001 update cst types

.envrc

@@ -0,0 +1 @@
+export CODEX_HOME=$PWD/.codex

.github/workflows/ci.yml

@@ -33,5 +33,5 @@ jobs:
       - run: git branch --track main origin/main
         if: ${{ github.event_name == 'pull_request' }}
 
-      - run: npx nx-cloud record -- nx format:check
+      # - run: npx nx-cloud record -- nx format:check
       - run: npx nx affected -t lint test build

.gitignore

@@ -39,3 +39,13 @@ testem.log
 Thumbs.db
 
 .nx/cache
+.nx/workspace-data
+
+vite.config.*.timestamp*
+vitest.config.*.timestamp*
+
+migrations.json
+
+.codex/
+.cursor/rules/nx-rules.mdc
+.github/instructions/nx.instructions.md

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "tree-sitter-gram"]
+	path = tree-sitter-gram
+	url = git@github.com:gram-data/tree-sitter-gram.git
+	ignore = dirty

.prettierignore

@@ -1,4 +1,5 @@
 # Add files here to ignore them from prettier formatting
 /dist
 /coverage
-/.nx/cache
+/.nx/cache
+/.nx/workspace-data

.specify/memory/constitution.md

@@ -0,0 +1,72 @@
+<!--
+Sync Impact Report
+Version: Unversioned → 1.0.0
+Modified Principles:
+- Introduced I. Design for Composable Grammar
+- Introduced II. Code Quality: Typed and Traceable Modules
+- Introduced III. Testing Standards: Contract-Driven Verification
+- Introduced IV. Developer Experience: Empower Gram Producers
+Added Sections:
+- Engineering Guardrails
+- Delivery Workflow
+Removed Sections:
+- Placeholder Principle V block
+Templates requiring updates:
+- .specify/templates/plan-template.md ✅ updated
+- .specify/templates/spec-template.md ✅ updated
+- .specify/templates/tasks-template.md ✅ updated
+- .specify/templates/checklist-template.md ✅ updated
+Follow-up TODOs:
+- None
+-->
+# gram-ts Constitution
+
+## Core Principles
+
+### I. Design for Composable Grammar
+- Every new capability MUST state the target grammar pattern(s) and constraints in the spec before implementation begins.
+- Libraries under `packages/*` MUST remain composable and expose entry points via `src/index.ts`; internal state stays private to its package unless a deliberate API contract is documented.
+- Cross-package dependencies MUST be declared through Nx tags and reviewed for domain fit; ad-hoc imports are forbidden.
+**Rationale**: Gram delivers value when grammar pieces compose predictably; disciplined design keeps the domain model coherent.
+
+### II. Code Quality: Typed and Traceable Modules
+- TypeScript strictness MUST stay enabled across all projects; suppressing compiler or ESLint rules requires a documented justification in the PR.
+- Modules MUST publish minimal, named exports with docstrings for public APIs; avoid default exports except at package entrypoints.
+- Shared utilities MUST include lightweight examples or inline usage notes so maintainers can trace data flow quickly.
+**Rationale**: Strong typing and traceable APIs prevent regressions across the Nx workspace and accelerate maintainer reviews.
+
+### III. Testing Standards: Contract-Driven Verification
+- Feature work MUST add or update Vitest suites that fail before implementation and cover both parser contracts and CLI flows.
+- Property-based tests with `fast-check` MUST guard new or modified grammar transformations; integration gaps require an explicit risk noted in the plan.
+- Before merge, contributors MUST run `npx nx run-many -t test -p <touched-projects>` and attach the command output or summary in the PR.
+**Rationale**: Contract-first testing preserves correctness of the grammar toolchain and exposes regressions before release.
+
+### IV. Developer Experience: Empower Gram Producers
+- Any change affecting CLI usage, API signatures, or file formats MUST update `README.md`, relevant package docs, or embedded `--help` output before completion.
+- Samples under `samples/` and quickstart guides MUST either reflect new behavior or state why no change is needed; omissions require issue tracking.
+- Error messages and logs MUST describe actionable remediation steps and reference supporting documentation when possible.
+**Rationale**: Gram succeeds when downstream developers adopt updates confidently; clear guidance keeps the ecosystem usable.
+
+## Engineering Guardrails
+
+- House all shipped code in publishable Nx targets under `packages/*`; link shared logic via libraries instead of relative imports across packages.
+- Maintain alignment with repository standards: Prettier formatting (`npx nx format:check`), ESLint module boundaries, and consistent configuration in `tsconfig.base.json`.
+- Build artifacts MUST live under `dist/packages/<project>`; scripts or tooling that need other locations require an explicit exemption.
+- Capture changes to parser grammar schemas or CLI commands in versioned docs within `docs/` or package-level READMEs alongside changelog entries.
+
+## Delivery Workflow
+
+1. Start with `/specs/<feature>/spec.md`, documenting grammar patterns, affected developers, and success metrics that map to the core principles.
+2. Generate `/specs/<feature>/plan.md` via `/speckit.plan` and complete the Constitution Check by providing evidence for each principle before Phase 0 completes.
+3. Break work into `/speckit.tasks` outputs that include testing, docs, and grammar validation tasks; keep stories independently shippable.
+4. Prior to merge, run lint, format, build, and test targets for all touched projects (`npx nx lint`, `npx nx format:check`, `npx nx build`, `npx nx run-many -t test`) and record results in the PR summary.
+
+## Governance
+
+- This constitution supersedes prior informal practices; reviewers MUST block PRs that violate the principles until resolved.
+- Amendments require a proposal summarizing motivation, expected impact, and updated Sync Impact Report entries; at least two maintainers must approve.
+- Versioning follows semantic rules: MAJOR for redefining or removing principles, MINOR for adding new principles or sections, PATCH for wording clarifications.
+- Upon adoption, update `LAST_AMENDED_DATE` and ensure dependent templates reflect the new guidance before closing the PR.
+- Compliance reviews happen at the start of each milestone and before tagged releases; unresolved breaches are logged as backlog items with owners.
+
+**Version**: 1.0.0 | **Ratified**: 2025-10-26 | **Last Amended**: 2025-10-26

.specify/scripts/bash/check-prerequisites.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-tasks     Require tasks.md to exist (for implementation phase)
+#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.sh --json
+
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.sh --json --require-tasks --include-tasks
+
+  # Get feature paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths and validate branch
+eval $(get_feature_paths)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+if $PATHS_ONLY; then
+    if $JSON_MODE; then
+        # Minimal JSON paths payload (no validation performed)
+        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "BRANCH: $CURRENT_BRANCH"
+        echo "FEATURE_DIR: $FEATURE_DIR"
+        echo "FEATURE_SPEC: $FEATURE_SPEC"
+        echo "IMPL_PLAN: $IMPL_PLAN"
+        echo "TASKS: $TASKS"
+    fi
+    exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d "$FEATURE_DIR" ]]; then
+    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+    echo "Run /speckit.specify first to create the feature structure." >&2
+    exit 1
+fi
+
+if [[ ! -f "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.plan first to create the implementation plan." >&2
+    exit 1
+fi
+
+# Check for tasks.md if required
+if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
+    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.tasks first to create the task list." >&2
+    exit 1
+fi
+
+# Build list of available documents
+docs=()
+
+# Always check these optional docs
+[[ -f "$RESEARCH" ]] && docs+=("research.md")
+[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
+
+# Check contracts directory (only if it exists and has files)
+if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+    docs+=("contracts/")
+fi
+
+[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
+
+# Include tasks.md if requested and it exists
+if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
+    docs+=("tasks.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+    # Build JSON array of documents
+    if [[ ${#docs[@]} -eq 0 ]]; then
+        json_docs="[]"
+    else
+        json_docs=$(printf '"%s",' "${docs[@]}")
+        json_docs="[${json_docs%,}]"
+    fi
+
+    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
+else
+    # Text output
+    echo "FEATURE_DIR:$FEATURE_DIR"
+    echo "AVAILABLE_DOCS:"
+
+    # Show status of each potential document
+    check_file "$RESEARCH" "research.md"
+    check_file "$DATA_MODEL" "data-model.md"
+    check_dir "$CONTRACTS_DIR" "contracts/"
+    check_file "$QUICKSTART" "quickstart.md"
+
+    if $INCLUDE_TASKS; then
+        check_file "$TASKS" "tasks.md"
+    fi
+fi