@selvakumaresra/specship 0.1.0

package/commands/cg-explore.md

@@ -0,0 +1,13 @@
+---
+description: Explore a region of the codebase by naming the symbols you care about. Use for "how does X work" or "what's in this area" questions.
+argument-hint: <symbol-bag>
+allowed-tools: mcp__specship__specship_explore, mcp__specship__specship_node
+---
+
+# SpecShip Explore: `$ARGUMENTS`
+
+Call `mcp__specship__specship_explore` with `$ARGUMENTS` as a bag of symbol names (include `Class.method` qualified forms when given). The tool returns the relevant symbols' source grouped by file, plus any flow it can synthesize between them.
+
+Treat the returned source as already Read — do NOT re-Read files. If the response truncates a god-file, run `specship_explore` again with a tighter symbol bag rather than reaching for Read.
+
+If a specific overload's full body is needed, call `mcp__specship__specship_node` on the symbol name — the response returns every overload in one call.

package/commands/cg-fix.md

@@ -0,0 +1,21 @@
+---
+description: Fix a drifted or broken spec link. Runs the spec-fix workflow (diagnose → approve → apply → verify) in an isolated git worktree.
+argument-hint: <SPEC_ID>
+allowed-tools: Bash
+---
+
+# SpecShip Fix: `$ARGUMENTS`
+
+Run the bundled `spec-fix` workflow.
+
+```bash
+specship workflow run spec-fix --input SPEC_ID=$ARGUMENTS
+```
+
+This:
+1. Creates a git worktree.
+2. Diagnoses why the link is drifted/broken (spec content_hash changed? code signature changed? test failing?).
+3. Pauses for you to approve the proposed fix.
+4. Applies the fix, runs tests, calls `specship_link_verify` to promote the link back to "verified".
+
+Use `/cg-relink` instead if the link is `orphaned` (target symbol no longer exists).

package/commands/cg-impact.md

@@ -0,0 +1,13 @@
+---
+description: Show what would break if you change a symbol. Use before editing a function/class/method to scope the blast radius.
+argument-hint: <symbol>
+allowed-tools: mcp__specship__specship_impact, mcp__specship__specship_callers
+---
+
+# SpecShip Impact: `$1`
+
+Call `mcp__specship__specship_impact` on `$1`. The response lists every transitive dependent — symbols that would need to change (or be re-verified) if `$1`'s contract changes.
+
+Group the output by file and lead with the count. Note any provenance: `heuristic` edges in the result — those came from a dynamic-dispatch synthesizer (callback, EventEmitter, React re-render, JSX child) and are higher-uncertainty than static-call edges.
+
+If the user wants direct callers only (not transitive), use `mcp__specship__specship_callers` instead.

package/commands/cg-implement.md

@@ -0,0 +1,23 @@
+---
+description: Implement a spec end-to-end. Runs the spec-implement workflow (plan → approve → implement → verify → link → final review) in an isolated git worktree.
+argument-hint: <SPEC_ID>
+allowed-tools: Bash
+---
+
+# SpecShip Implement: `$ARGUMENTS`
+
+Run the bundled `spec-implement` workflow against the spec.
+
+```bash
+specship workflow run spec-implement --input SPEC_ID=$ARGUMENTS
+```
+
+This:
+1. Creates a git worktree (`specship/wf-spec-implement-<runId>`) so changes don't touch your working tree.
+2. Drafts a plan from the spec body + adjacent code.
+3. PAUSES at an approval gate — you review the plan, then run `specship workflow approve <runId>` and `specship workflow resume <runId>`.
+4. Implements, runs tests, asserts spec→code links, pauses for a final review.
+
+If you just want to view the spec without implementing, use `/cg-spec` instead.
+
+After the workflow completes, the worktree is left for inspection — merge it into your branch when ready, or clean up with `specship workflow cancel <runId>`.

package/commands/cg-relink.md

@@ -0,0 +1,21 @@
+---
+description: Re-attach an orphaned spec link after a refactor moved or renamed the target symbol.
+argument-hint: <SPEC_ID>
+allowed-tools: Bash
+---
+
+# SpecShip Re-link: `$ARGUMENTS`
+
+Run the bundled `spec-relink` workflow.
+
+```bash
+specship workflow run spec-relink --input SPEC_ID=$ARGUMENTS
+```
+
+This:
+1. Presents the orphaned link's original target (file path + qualified name).
+2. Searches the current codebase for candidate symbols that match.
+3. Pauses for you to pick the right candidate (or reject all and abandon).
+4. Calls `specship_link_assert` at the new location.
+
+No code is edited — this only updates the spec→code link layer.

package/commands/cg-spec.md

@@ -0,0 +1,19 @@
+---
+description: Fetch a spec by ID — body, parent/siblings, and the code currently linked to it (with state). Call FIRST when the user mentions a spec ID.
+argument-hint: <SPEC_ID>
+allowed-tools: mcp__specship__specship_spec, mcp__specship__specship_node, mcp__specship__specship_explore
+---
+
+# SpecShip Spec: `$ARGUMENTS`
+
+Call `mcp__specship__specship_spec` with `spec_id: "$ARGUMENTS"`. The response includes:
+
+- The spec body, kind, owner, priority
+- Parent doc and sibling requirements (the surrounding context)
+- All code currently linked to this spec with state (verified / drifted / orphaned / broken) and provenance (agent-asserted / code-comment / spec-declaration)
+
+Use this BEFORE Read-ing the spec file — it returns more than the file alone.
+
+After reading the spec, jump into linked code via `mcp__specship__specship_node` (it surfaces every linked spec on a symbol too). If no linked code exists yet, walk the codebase with `mcp__specship__specship_explore` using terms drawn from the spec's title and acceptance criteria.
+
+When you edit code in response to this spec, call `mcp__specship__specship_link_assert` before reporting done.

package/commands/cg-sync.md

@@ -0,0 +1,8 @@
+---
+description: Refresh the SpecShip index for the current project. Use after external file changes (git pull, another editor) when the auto-sync hook isn't enough.
+allowed-tools: Bash(specship sync:*), Bash(specship status:*)
+---
+
+Run `specship sync` in the current project and report a one-line summary (files indexed, nodes added/removed, milliseconds). If sync reports the index is up to date, say so and stop.
+
+If sync fails (no `.specship/` directory, lock contention, etc.), surface the error verbatim and stop — don't try to recover automatically.

package/commands/cg-trace.md

@@ -0,0 +1,13 @@
+---
+description: Trace the call flow from one symbol to another using SpecShip. Use for "how does X reach Y" questions — much faster than grep + Read.
+argument-hint: <from-symbol> <to-symbol>
+allowed-tools: mcp__specship__specship_explore, mcp__specship__specship_node
+---
+
+# SpecShip Trace: `$1` → `$2`
+
+Call `mcp__specship__specship_explore` with a query that names BOTH `$1` and `$2` (include any qualified forms like `Class.method` if the user gave one). The Flow section in the response will show the path between them with inline source for every hop.
+
+If explore returns no Flow section, the two symbols don't connect statically — say so. Don't fall back to grep / Read; the absence is the answer.
+
+If you need to drill into a single symbol's full body afterwards, use `mcp__specship__specship_node` — never Read the file directly.

package/dist/bin/node-version-check.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Node.js version compatibility check.
+ *
+ * Node 25.x has a V8 turboshaft WASM JIT Zone allocator bug that
+ * reliably crashes SpecShip with `Fatal process out of memory: Zone`
+ * during tree-sitter grammar compilation. This module owns the
+ * user-facing banner shown before exit. Kept side-effect-free so it's
+ * safe to import from tests without triggering CLI bootstrap.
+ */
+/**
+ * Build the bordered banner shown when SpecShip detects an
+ * unsupported Node.js major version (currently 25+). Pinned via unit
+ * test so the recovery commands and override instructions can't be
+ * silently stripped by future edits.
+ *
+ * Uses ASCII glyphs to stay readable on Windows OEM-codepage consoles
+ * (see ../ui/glyphs.ts for the rationale).
+ */
+export declare function buildNode25BlockBanner(nodeVersion: string): string;
+/**
+ * Lowest supported Node.js major version. Matches the `engines` floor in
+ * package.json. Below this, SpecShip relies on language features / native APIs
+ * that aren't present, and the combination is untested. `engines` alone only
+ * *warns* on install (unless the user set `engine-strict`), so the CLI bootstrap
+ * also hard-blocks here to actually enforce the floor.
+ */
+export declare const MIN_NODE_MAJOR = 20;
+/**
+ * Build the bordered banner shown when SpecShip detects a Node.js major below
+ * {@link MIN_NODE_MAJOR}. Pinned via unit test so the recovery commands and the
+ * override env var can't be silently stripped by future edits.
+ *
+ * Uses ASCII glyphs to stay readable on Windows OEM-codepage consoles
+ * (see ../ui/glyphs.ts for the rationale).
+ */
+export declare function buildNodeTooOldBanner(nodeVersion: string): string;
+//# sourceMappingURL=node-version-check.d.ts.map

package/dist/bin/node-version-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-version-check.d.ts","sourceRoot":"","sources":["../../src/bin/node-version-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAmBlE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAkBjE"}

package/dist/bin/node-version-check.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Node.js version compatibility check.
+ *
+ * Node 25.x has a V8 turboshaft WASM JIT Zone allocator bug that
+ * reliably crashes SpecShip with `Fatal process out of memory: Zone`
+ * during tree-sitter grammar compilation. This module owns the
+ * user-facing banner shown before exit. Kept side-effect-free so it's
+ * safe to import from tests without triggering CLI bootstrap.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_NODE_MAJOR = void 0;
+exports.buildNode25BlockBanner = buildNode25BlockBanner;
+exports.buildNodeTooOldBanner = buildNodeTooOldBanner;
+/**
+ * Build the bordered banner shown when SpecShip detects an
+ * unsupported Node.js major version (currently 25+). Pinned via unit
+ * test so the recovery commands and override instructions can't be
+ * silently stripped by future edits.
+ *
+ * Uses ASCII glyphs to stay readable on Windows OEM-codepage consoles
+ * (see ../ui/glyphs.ts for the rationale).
+ */
+function buildNode25BlockBanner(nodeVersion) {
+    const sep = '-'.repeat(72);
+    return [
+        sep,
+        `[SpecShip] Unsupported Node.js version: ${nodeVersion}`,
+        sep,
+        'Node.js 25.x has a V8 WASM JIT (turboshaft) Zone allocator bug that',
+        'crashes with `Fatal process out of memory: Zone` when SpecShip',
+        'compiles tree-sitter grammars. SpecShip WILL crash on this Node',
+        'version mid-indexing. See https://github.com/selvakumarEsra/specship/issues/81',
+        '',
+        'Fix: install Node.js 22 LTS:',
+        '  nvm install 22 && nvm use 22                          # nvm',
+        '  brew install node@22 && brew link --overwrite --force node@22  # Homebrew',
+        '',
+        'To override (NOT recommended - you will likely OOM):',
+        '  SPECSHIP_ALLOW_UNSAFE_NODE=1 specship ...',
+        sep,
+    ].join('\n');
+}
+/**
+ * Lowest supported Node.js major version. Matches the `engines` floor in
+ * package.json. Below this, SpecShip relies on language features / native APIs
+ * that aren't present, and the combination is untested. `engines` alone only
+ * *warns* on install (unless the user set `engine-strict`), so the CLI bootstrap
+ * also hard-blocks here to actually enforce the floor.
+ */
+exports.MIN_NODE_MAJOR = 20;
+/**
+ * Build the bordered banner shown when SpecShip detects a Node.js major below
+ * {@link MIN_NODE_MAJOR}. Pinned via unit test so the recovery commands and the
+ * override env var can't be silently stripped by future edits.
+ *
+ * Uses ASCII glyphs to stay readable on Windows OEM-codepage consoles
+ * (see ../ui/glyphs.ts for the rationale).
+ */
+function buildNodeTooOldBanner(nodeVersion) {
+    const sep = '-'.repeat(72);
+    return [
+        sep,
+        `[SpecShip] Unsupported Node.js version: ${nodeVersion}`,
+        sep,
+        `SpecShip requires Node.js ${exports.MIN_NODE_MAJOR} or newer. Older versions lack`,
+        'language features and native APIs SpecShip depends on, and are not',
+        'tested or supported.',
+        '',
+        'Fix: install Node.js 22 LTS:',
+        '  nvm install 22 && nvm use 22                          # nvm',
+        '  brew install node@22 && brew link --overwrite --force node@22  # Homebrew',
+        '',
+        'To override (NOT recommended - unsupported):',
+        '  SPECSHIP_ALLOW_UNSAFE_NODE=1 specship ...',
+        sep,
+    ].join('\n');
+}
+//# sourceMappingURL=node-version-check.js.map

package/dist/bin/node-version-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-version-check.js","sourceRoot":"","sources":["../../src/bin/node-version-check.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAWH,wDAmBC;AAmBD,sDAkBC;AAjED;;;;;;;;GAQG;AACH,SAAgB,sBAAsB,CAAC,WAAmB;IACxD,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3B,OAAO;QACL,GAAG;QACH,2CAA2C,WAAW,EAAE;QACxD,GAAG;QACH,qEAAqE;QACrE,gEAAgE;QAChE,iEAAiE;QACjE,gFAAgF;QAChF,EAAE;QACF,8BAA8B;QAC9B,+DAA+D;QAC/D,6EAA6E;QAC7E,EAAE;QACF,sDAAsD;QACtD,6CAA6C;QAC7C,GAAG;KACJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACU,QAAA,cAAc,GAAG,EAAE,CAAC;AAEjC;;;;;;;GAOG;AACH,SAAgB,qBAAqB,CAAC,WAAmB;IACvD,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3B,OAAO;QACL,GAAG;QACH,2CAA2C,WAAW,EAAE;QACxD,GAAG;QACH,6BAA6B,sBAAc,gCAAgC;QAC3E,oEAAoE;QACpE,sBAAsB;QACtB,EAAE;QACF,8BAA8B;QAC9B,+DAA+D;QAC/D,6EAA6E;QAC7E,EAAE;QACF,8CAA8C;QAC9C,6CAA6C;QAC7C,GAAG;KACJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/bin/specship.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * SpecShip CLI
+ *
+ * Command-line interface for SpecShip code intelligence.
+ *
+ * Usage:
+ *   specship                    Run interactive installer (when no args)
+ *   specship install            Run interactive installer
+ *   specship uninstall          Remove SpecShip from your agents
+ *   specship init [path]        Initialize SpecShip in a project
+ *   specship uninit [path]      Remove SpecShip from a project
+ *   specship index [path]       Index all files in the project
+ *   specship sync [path]        Sync changes since last index
+ *   specship status [path]      Show index status
+ *   specship query <search>     Search for symbols
+ *   specship files [options]    Show project file structure
+ *   specship context <task>     Build context for a task
+ *   specship callers <symbol>   Find what calls a function/method
+ *   specship callees <symbol>   Find what a function/method calls
+ *   specship impact <symbol>    Analyze what code is affected by changing a symbol
+ *   specship affected [files]   Find test files affected by changes
+ */
+export {};
+//# sourceMappingURL=specship.d.ts.map

package/dist/bin/specship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specship.d.ts","sourceRoot":"","sources":["../../src/bin/specship.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;GAqBG"}