@selvakumaresra/specship 0.1.3 → 0.3.0

package/README.md

@@ -101,7 +101,7 @@ A YAML workflow engine (`specship workflow run <name>`) drives the agent through
 - `spec-verify` — run tests, promote `implemented` links to `verified`
 - `spec-relink` — re-attach an orphan after a refactor
 
-Customize by dropping your own `<project>/.specship/workflows/<name>.yaml` (project tier overrides bundled defaults). The matching slash commands `/cg-spec`, `/cg-implement`, `/cg-drifted`, `/cg-fix`, `/cg-relink` are installed into Claude Code by `specship install`.
+Customize by dropping your own `<project>/.specship/workflows/<name>.yaml` (project tier overrides bundled defaults). The matching slash commands `/ss-spec`, `/ss-implement`, `/ss-drifted`, `/ss-fix`, `/ss-relink` are installed into Claude Code by `specship install`.
 
 ---
 
@@ -156,7 +156,7 @@ The handful of cases where manual `specship sync` makes sense: the watcher is di
 
 `specship serve --ui` boots a single-process Fastify + Angular SPA on `http://127.0.0.1:4242/`. One port serves both the API and the desktop UI. No Electron, no auth — loopback only.
 
-![SpecShip Desktop dashboard — stat tiles, recent neighborhood mini-graph, tips, tool-call heatmap and recent-prompt rollup at a glance](assets/screenshots/dashboard.png?v=1)
+![SpecShip Desktop dashboard — stat tiles, recent neighborhood mini-graph, tips, tool-call heatmap and recent-prompt rollup at a glance](https://raw.githubusercontent.com/selvakumarEsra/specship/main/assets/screenshots/dashboard.png?v=1)
 
 The dashboard is designed to answer four questions in one glance — **what is the structural state of my codebase, what needs attention, what did my last session cost, and what should I do about it.** The zones, top-to-bottom:
 

package/commands/ss-design-implement.md

@@ -0,0 +1,79 @@
+---
+description: Import a Claude Design (or Figma) file, snapshot it for zero-loss reference, draft a SpecShip spec, and hand off to /ss-implement.
+argument-hint: <Claude-Design-URL> [SLUG]
+allowed-tools: Read, Write, Edit, Bash, mcp__specship__specship_explore, mcp__specship__specship_search, mcp__specship__specship_node, mcp__specship__specship_spec, mcp__specship__specship_files
+---
+
+# SpecShip Design → Spec → Implement: `$ARGUMENTS`
+
+Run the bundled `claude-design-implement` workflow against the Claude Design URL in `$ARGUMENTS`. The workflow:
+
+1. **Snapshots** the design source byte-for-byte into `specs/<slug>/snapshot.html` (zero-loss fidelity layer).
+2. **Records the import** in `specs/<slug>/source.md` (audit trail — URL, project ID, date, original prompt verbatim).
+3. **Extracts design tokens** into `specs/<slug>/tokens.css`, mapped onto your project's existing token system where possible.
+4. **Drafts a spec** at `specs/<slug>.md` covering behavioural contract, accessibility, responsive, interaction states, and data shape — **without** pixel values or hex colors (those stay in the snapshot + tokens).
+5. **Pauses at an approval gate** for you to walk the `[needs review]` markers and gap-fill questions.
+6. **Writes the spec** and `specship sync`s it into the graph.
+7. **Hands off** with the next command: `/ss-implement <first REQ ID>`.
+
+## How to invoke
+
+Parse `$ARGUMENTS`. The first token must be a Claude Design URL of the form:
+
+```
+https://claude.ai/design/p/<project-id>/?file=<File+Name>.html
+```
+
+Optional second token is the slug (kebab-case directory name). If omitted, derive from the `file=` query param (e.g. `Data+Flow.html` → `data-flow`).
+
+Then run:
+
+```bash
+specship workflow run claude-design-implement \
+  --input CONNECTOR_URL="<URL>" \
+  --input FILE_LABEL="<File Name>" \
+  --input SLUG="<slug>"
+```
+
+(Add `--input OWNER="<team>"` and `--input PRIORITY="high|medium|low"` if you want them populated in the spec frontmatter; otherwise they're marked `[needs review]` and surfaced in the gap-fill step.)
+
+## Why the four-file pattern
+
+The workflow produces four files in `specs/<slug>/` rather than a single spec. This is deliberate:
+
+| File | Role | Drift-tracked? |
+|---|---|---|
+| `snapshot.html` | Byte-for-byte design capture | No (frozen reference) |
+| `source.md` | Import audit record | No (metadata) |
+| `tokens.css` | Design tokens — CSS variables | No (reference data) |
+| `specs/<slug>.md` | Contract: REQs, acceptance criteria | **Yes — drift gate on this** |
+
+Specs that name pixel values flag drift on every theme tweak; specs that name token symbols (`MUST use --error`) survive token-value changes silently. The split keeps the drift queue meaningful.
+
+## After the workflow finishes
+
+You get a hand-off message listing the REQs. Run:
+
+```
+/ss-implement <REQ-XXX-001>
+```
+
+The implementation phase reads:
+- `specs/<slug>.md` for what to build
+- `specs/<slug>/snapshot.html` for how it should look
+- `specs/<slug>/tokens.css` for which design tokens to wire up
+
+This is what preserves visual fidelity — the snapshot is on disk and the implementer reads it directly. The spec layer enforces contract; the snapshot layer guarantees fidelity.
+
+## When the designer iterates
+
+Re-run `/ss-design-implement` with the same URL. The workflow re-snapshots, re-drafts, re-prompts for approval — keeping existing REQ IDs stable so any in-flight implementation work survives the iteration. `git diff` on the snapshot tells you exactly what changed visually; `git diff` on `specs/<slug>.md` tells you what changed contractually.
+
+## Anti-patterns
+
+- **Don't put hex codes in the spec.** Reference tokens by name. The values live in `tokens.css`.
+- **Don't delete the snapshot after implementation.** It's the durable reference if the Claude Design URL ever goes 404.
+- **Don't paraphrase the snapshot.** Save byte-for-byte. Summarising loses detail that the implementation step would otherwise have used.
+- **Don't skip the approval gate.** The workflow's value is the gap-fill questions surfaced there — answering them is what closes the "no details lost" gap on the things a static design can't show (failure modes, real-time updates, keyboard order).
+
+If `$ARGUMENTS` is empty or doesn't look like a Claude Design URL, ask the user for the URL before running the workflow.

package/commands/{cg-drifted.md → ss-drifted.md}

@@ -17,7 +17,7 @@ specship drifted $ARGUMENTS
 Add `--fail-on=broken,drifted,orphaned` to make it exit non-zero — useful as a pre-commit or CI gate.
 
 For each link returned:
-- **drifted (drift_axis=spec)**: spec body changed; the code may be stale. Run `/cg-fix <SPEC_ID>` to investigate.
+- **drifted (drift_axis=spec)**: spec body changed; the code may be stale. Run `/ss-fix <SPEC_ID>` to investigate.
 - **drifted (drift_axis=code)**: code's signature changed since the link was set. Re-verify with `mcp__specship__specship_link_verify` if behavior is still correct.
 - **broken**: verification failed. Open the spec, find the failing test, fix the code.
-- **orphaned**: target symbol no longer exists. Use `/cg-relink <SPEC_ID>` to re-attach.
+- **orphaned**: target symbol no longer exists. Use `/ss-relink <SPEC_ID>` to re-attach.

package/commands/{cg-fix.md → ss-fix.md}

@@ -18,4 +18,4 @@ This:
 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).
+Use `/ss-relink` instead if the link is `orphaned` (target symbol no longer exists).

package/commands/{cg-implement.md → ss-implement.md}

@@ -18,6 +18,6 @@ This:
 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.
+If you just want to view the spec without implementing, use `/ss-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/ss-spec-author.md

@@ -0,0 +1,43 @@
+---
+description: Draft a new SpecShip spec from a one-line feature description. Walks gap-filling questions, runs a quality review, writes the file.
+argument-hint: <one-line feature description>
+allowed-tools: Read, Write, Edit, Bash, mcp__specship__specship_explore, mcp__specship__specship_search, mcp__specship__specship_node, mcp__specship__specship_files, mcp__specship__specship_spec
+---
+
+# SpecShip Author Spec: `$ARGUMENTS`
+
+Author a new spec for the feature `$ARGUMENTS` using the `spec-author` skill loop. Read the skill first if you haven't already — it lives at `~/.claude/skills/spec-author/SKILL.md` with references for format, quality rubric, gap-filling questions, and the review checklist.
+
+Run the loop conversationally:
+
+1. **Scope check.** Confirm whether this is one requirement under an existing doc, a new document with N children, or a refinement of a draft the user already has. Refuse "spec the whole app" — pick a feature area.
+
+2. **Ground in code.** Call `mcp__specship__specship_explore` on terms drawn from `$ARGUMENTS` to find where similar features live, what conventions to mirror, and which files the implementation will likely touch. Skip for clearly-greenfield work.
+
+3. **Draft.** Produce a complete spec body in memory following `~/.claude/skills/spec-author/references/format.md`:
+   - YAML frontmatter (id, title, owner, priority)
+   - Embedded `<!-- id: -->` markers above every heading
+   - RFC 2119 keyword (MUST/SHOULD/MAY) in each requirement title
+   - One concern per requirement
+   - `## Acceptance` with `.A<N>`-ID'd bullets, happy + failure paths
+   - Optional `implementations:` block populated from grounding
+   - `[needs user confirmation]` markers wherever the description didn't tell you something
+
+4. **Gap-fill.** Walk `~/.claude/skills/spec-author/references/gap-questions.md` against the draft and ask the user the 3–5 most important unanswered questions. Mark the rest as `[needs review]`. Phrase questions so they can answer in one line each.
+
+5. **Review.** Run `~/.claude/skills/spec-author/references/review-checklist.md` and surface a numbered findings list. Be sharp.
+
+6. **Write.** Use the `Write` tool against `specs/<slug>.md` at the project root. Slug is kebab-case from the feature name, NO date prefix. If a file with that name exists, APPEND the new REQs to it rather than overwriting; tell the user.
+
+7. **Hand off.** Tell the user:
+   - The file path you wrote
+   - Run `specship sync` to index it
+   - Run `/ss-implement <REQ-ID>` when ready to build
+
+If the user wants the more disciplined path with formal approval gates and worktree isolation, point them at:
+
+```
+specship workflow run spec-author --input DESCRIPTION="$ARGUMENTS"
+```
+
+But the default for this slash command is the conversational loop above — lighter weight, no workflow overhead.

package/commands/ss-spec-review.md

@@ -0,0 +1,48 @@
+---
+description: Review an existing spec against the SpecShip quality rubric. Read-only — produces a numbered findings list without modifying the file.
+argument-hint: <SPEC_ID | path/to/spec.md>
+allowed-tools: Read, mcp__specship__specship_spec, mcp__specship__specship_explore, mcp__specship__specship_node, mcp__specship__specship_search
+---
+
+# SpecShip Review Spec: `$ARGUMENTS`
+
+Review the spec referred to by `$ARGUMENTS` (either a spec ID like `REQ-AUTH-005`, or a file path like `specs/auth.md`) against the rubric defined in the `spec-author` skill. **This is read-only — do NOT modify any files.**
+
+If you haven't loaded the skill yet, read `~/.claude/skills/spec-author/SKILL.md` and especially `~/.claude/skills/spec-author/references/review-checklist.md`.
+
+## How to do it
+
+1. **Resolve the target.** If `$ARGUMENTS` looks like a spec ID, call `mcp__specship__specship_spec` to fetch its source path. If it looks like a file path, read the file directly.
+
+2. **Verify code grounding** (when applicable). For each entry in the spec's `implementations:` block, confirm via `mcp__specship__specship_node` or `mcp__specship__specship_explore` that the referenced file + symbol actually exists. Greenfield specs (empty `implementations:`) skip this step.
+
+3. **Run the checklist.** Walk `references/review-checklist.md` in order:
+   - **STRUCTURAL** (S1–S5): embedded ID markers, no stranded IDs, unique IDs, well-formed frontmatter, valid `implementations:` syntax. These block the file from indexing — flag any breakage as critical.
+   - **QUALITY** (Q1–Q7): RFC 2119 keywords, no weasel words, no implementation leak, testable acceptance, one concern per REQ, failure-path coverage, grounded `implementations:` paths.
+   - **HYGIENE** (H1–H4): owner + priority set, no stale `[needs review]` markers, no TODO/FIXME, body conciseness.
+
+4. **Output as a numbered findings list**, grouped by category:
+
+   ```
+   STRUCTURAL — N findings:
+   1. Line N: ...
+
+   QUALITY — N findings:
+   1. Line N: ...
+
+   HYGIENE — N findings:
+   1. Line N: ...
+
+   Net: <summary>. Address structural items before re-indexing.
+   ```
+
+5. **End with a one-line verdict**: "Spec is ready to ship", "Needs the structural fixes before it can index", or "Has quality issues worth addressing before /ss-implement runs."
+
+## Anti-patterns to avoid
+
+- **Don't modify the file.** Even if the issues are obvious. The user runs `/ss-spec-author` for that flow.
+- **Don't paraphrase the checklist.** Reference specific items (S1, Q3, etc.) when you flag a finding so the user can cross-reference.
+- **Don't be polite about real problems.** Implementation leak ("MUST use bcrypt") and untestable bullets ("handles errors gracefully") are pickup-line-quality findings — say so directly.
+- **Don't review the wrong file.** If the path is ambiguous (e.g. multiple specs at similar paths), ask the user which one before reading.
+
+If `$ARGUMENTS` is empty, ask the user which spec to review (by ID or path).

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"}