heyspex 0.1.0

package/docs/mcp-client-config.md

@@ -0,0 +1,200 @@
+# Connecting an MCP client to HeySpex
+
+There are two ways to get the `hs` / `heyspex` / `heyspex-mcp` commands onto a
+machine, and they are **not** interchangeable:
+
+| You are… | Use |
+|---|---|
+| a customer, no clone | [§1a — install the package](#1a-install-the-package-customers) |
+| working from a clone of the HeySpex source repo | [§1b — clone + `npm link`](#1b-clone--npm-link-working-from-source) |
+
+Either way, this replaces the repo-only wiring in this repository's `.mcp.json`, which
+points at `node ${CLAUDE_PROJECT_DIR}/vendor/heyspex-mcp/cli.mjs` — a path that **only
+exists inside a clone of the HeySpex source repository** and is therefore useless to
+anyone who installed the package.
+
+## 1a. Install the package (customers)
+
+```sh
+npm install -g heyspex
+```
+
+The package installs three executables: `hs`, `heyspex` (an alias of `hs`), and
+`heyspex-mcp` (the MCP server itself).
+
+> **Not published yet.** `heyspex` is not on the public npm registry today, so this
+> command 404s. Until it ships, §1b is the only path that works.
+
+> Do **not** run `npx hs`. `hs` is an unrelated package on the public registry and
+> `npx hs` will install *that* instead — it does not error, it just silently runs
+> somebody else's tool. Use `heyspex` or `heyspex-mcp`, which are ours.
+
+To avoid a global install entirely, run the server through `npx` with the **package**
+name, which is unambiguous:
+
+```sh
+npx --yes --package heyspex heyspex-mcp
+```
+
+## 1b. Clone + `npm link` (working from source)
+
+`npm install` in a clone does **not** put `hs` on your PATH. Nothing does, except
+`npm link` — run once per machine, from the repo root:
+
+```sh
+git clone https://github.com/pwhermanson/workflow-protocol.git
+cd workflow-protocol
+npm install
+npm link          # the step that actually creates hs / heyspex / heyspex-mcp
+npm run doctor    # confirms `hs` resolves to THIS checkout
+```
+
+`npm link` writes the three shims into npm's global bin directory (`npm prefix -g`)
+and points them at this clone. It is machine-global: linking a second clone repoints
+`hs` at that one instead. `npm run doctor`'s **`hs` on PATH → this checkout** check
+is what catches all of that — a missing link, an unrelated `hs`, or an `hs` that is
+live but aimed at a different clone.
+
+If `hs` still does not resolve after linking, npm's global bin directory is not on
+your PATH — add the directory `npm prefix -g` prints (the shims sit in it directly)
+and reopen your terminal.
+
+Until you have linked, every command in this document works as
+`node bin/hs.mjs <args>` from the repo root. That form always works and is the right
+fallback — `npx hs` is not.
+
+## 2. Point your MCP client at it
+
+### Claude Code
+
+Project scope — `.mcp.json` in the root of the repository you want HeySpex to track:
+
+```json
+{
+  "mcpServers": {
+    "heyspex": {
+      "type": "stdio",
+      "command": "heyspex-mcp",
+      "args": [],
+      "env": {
+        "HEYSPEX_VAULT_ROOT": "."
+      }
+    }
+  }
+}
+```
+
+If you did not install globally, use the no-install form instead:
+
+```json
+{
+  "mcpServers": {
+    "heyspex": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["--yes", "--package", "heyspex", "heyspex-mcp"],
+      "env": {
+        "HEYSPEX_VAULT_ROOT": "."
+      }
+    }
+  }
+}
+```
+
+User scope, from any directory:
+
+```sh
+claude mcp add --scope user heyspex heyspex-mcp
+```
+
+### Cursor
+
+`~/.cursor/mcp.json` (user scope) or `.cursor/mcp.json` (project scope) takes the
+same object:
+
+```json
+{
+  "mcpServers": {
+    "heyspex": {
+      "command": "heyspex-mcp",
+      "args": [],
+      "env": {
+        "HEYSPEX_VAULT_ROOT": "."
+      }
+    }
+  }
+}
+```
+
+### Any other MCP client
+
+The server speaks JSON-RPC over stdin/stdout. Anything that can launch a command and
+talk MCP to it works — launch `heyspex-mcp` with no arguments.
+
+**After adding the server, restart the client.** MCP servers are read once at client
+startup; a mid-session install will not surface the tools.
+
+## 3. Sign in
+
+```sh
+heyspex login          # or `hs login`, or `node bin/hs.mjs login` from a clone
+```
+
+That opens the console, mints a pairing code, and writes a lasting token to
+`~/.heyspex/credentials.yaml`. On a machine with no browser — or when the code was
+minted elsewhere — redeem it directly:
+
+```sh
+heyspex mcp pair <code>
+```
+
+> If `credentials.yaml` never appears, the command you ran was probably not ours.
+> `npx hs login` runs the unrelated registry package and writes nothing; an unlinked
+> clone has no `hs` at all. Run `npm run doctor` — its **`hs` on PATH → this
+> checkout** check names the cause.
+
+## Which vault the server reads
+
+Resolution order, highest first:
+
+| # | Source | Notes |
+|---|---|---|
+| 1 | An explicit vault id | `hs vault use <id>` |
+| 2 | `active_vault_id` in `~/.heyspex/registry.json` | the offline active-vault pointer |
+| 3 | `HEYSPEX_VAULT_ROOT` | the repository root; what the config above sets |
+| 4 | `HEYSPEX_VAULT_DIR` | the `specs/` directory itself |
+| 5 | The working directory | used when it contains a `specs/` directory |
+
+## Which console the server calls
+
+Resolution order, highest first:
+
+| # | Source | Written by |
+|---|---|---|
+| 1 | `HEYSPEX_CONSOLE_URL` | you, in the client config or your shell |
+| 2 | `console_url:` in `~/.heyspex/credentials.yaml` | `heyspex login` / `heyspex mcp pair` |
+| 3 | `.heyspex/console-url` in the vault | a local development server |
+| 4 | `http://localhost:3000` | the fallback |
+
+A customer install normally uses row 2 and needs no environment variable at all. Set
+`HEYSPEX_CONSOLE_URL` only to override a paired console for one session.
+
+## Verifying it works
+
+From a clone, one command covers every install surface, including whether `hs`
+resolves to this checkout:
+
+```sh
+npm run doctor
+```
+
+Otherwise:
+
+```sh
+heyspex-mcp --version 2>/dev/null || echo "server starts"
+```
+
+The real check is in the client: after restarting it, the `heyspex_*` tools should be
+listed. If they are not, the client did not restart, or the command is not on your
+`PATH` — from a clone run `npm link` (§1b); from an install, try the
+`npx --package heyspex heyspex-mcp` form.

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "heyspex",
+  "version": "0.1.0",
+  "description": "HeySpex CLI + MCP server — connect Claude Code, Cursor, and any MCP client to your HeySpex spec vault",
+  "keywords": [
+    "heyspex",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "cursor",
+    "spec-driven-development",
+    "agents"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pwhermanson/workflow-protocol.git"
+  },
+  "engines": {
+    "node": ">=20.0.0 <25.0.0"
+  },
+  "workspaces": [
+    "spex-console",
+    "pm-control-center",
+    "companion/extension"
+  ],
+  "bin": {
+    "hs": "bin/hs.mjs",
+    "heyspex": "bin/hs.mjs",
+    "heyspex-mcp": "vendor/heyspex-mcp/cli.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    "./console-url-resolver": "./scripts/lib/console-url-resolver.mjs"
+  },
+  "files": [
+    "bin/hs.mjs",
+    "bin/postinstall.mjs",
+    "vendor/heyspex-mcp/**/*.mjs",
+    "!vendor/heyspex-mcp/**/*.test.mjs",
+    "scripts/check-mcp-freshness.mjs",
+    "scripts/gateway-skills-lib.mjs",
+    "scripts/vault-id-lib.mjs",
+    "scripts/lib/console-url-resolver.mjs",
+    "scripts/lib/hs-link.mjs",
+    "scripts/lib/dev-mode.mjs",
+    "scripts/dev-server-status.mjs",
+    "scripts/lib/hs-source-*.mjs",
+    "!scripts/lib/hs-source-*.test.mjs",
+    "scripts/lib/standalone-doctor.mjs",
+    "dev-factory/lib/fleet-readiness.mjs",
+    "dev-factory/lib/fleet-state.mjs",
+    "dev-factory/lib/sufficiency-score.mjs",
+    "docs/mcp-client-config.md",
+    "dist/cli/*.mjs",
+    "dist/cli-templates/**",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "js-yaml": ">=3.13.0 <5.0.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.2"
+  },
+  "scripts": {
+    "prepack": "node scripts/build-cli-bundle.mjs",
+    "build:cli": "node scripts/build-cli-bundle.mjs",
+    "postinstall": "node bin/postinstall.mjs",
+    "setup": "node scripts/heyspex-doctor.mjs --fix",
+    "doctor": "node scripts/heyspex-doctor.mjs",
+    "heyspex:on": "node scripts/hs-mode.mjs on",
+    "heyspex:off": "node scripts/hs-mode.mjs off",
+    "heyspex:status": "node scripts/hs-mode.mjs status",
+    "commandcode:install": "node scripts/install-commandcode.mjs",
+    "commandcode:check": "node scripts/install-commandcode.mjs --check",
+    "commandcode:uninstall": "node scripts/install-commandcode.mjs --uninstall",
+    "seats:sync": "node scripts/sync-seat-context.mjs",
+    "seats:check": "node scripts/sync-seat-context.mjs --check",
+    "skills:sync": "node scripts/sync-skills.mjs",
+    "skills:check": "node scripts/sync-skills.mjs --check",
+    "pm:dashboard": "node bin/cli.mjs dashboard",
+    "pm:control-center": "node bin/cli.mjs control-center",
+    "pm:parallel-check": "node bin/cli.mjs parallel-check",
+    "validate:vault-ids": "node scripts/validate-vault-ids.mjs",
+    "validate:vault-naming": "node scripts/validate-vault-naming.mjs",
+    "validate:vault-blockers": "node scripts/validate-vault-blockers.mjs",
+    "validate:vault-frontmatter": "node scripts/validate-vault-frontmatter.mjs",
+    "validate:vault-encoding": "node scripts/fix-mojibake.mjs --check",
+    "fix:vault-encoding": "node scripts/fix-mojibake.mjs --apply",
+    "validate:review-backlinks": "node scripts/validate-review-backlinks.mjs",
+    "build:procedure-catalog": "node scripts/build-procedure-catalog.mjs",
+    "validate:procedure-catalog": "node scripts/build-procedure-catalog.mjs --check",
+    "build:guardrails": "node scripts/build-guardrails.mjs",
+    "validate:guardrails": "node scripts/build-guardrails.mjs --check",
+    "compile:agents": "node scripts/compile-agents.mjs",
+    "validate:agents": "node scripts/compile-agents.mjs --check",
+    "build:vault-index": "node scripts/build-vault-index.mjs",
+    "validate:vault-index": "node scripts/build-vault-index.mjs --check",
+    "check:no-cockpit": "node scripts/check-no-cockpit.mjs",
+    "commit": "node scripts/human-commit.mjs",
+    "commit:owner": "node scripts/owner-commit.mjs",
+    "hooks:install": "node scripts/install-git-hooks.mjs",
+    "hooks:install-claude": "node scripts/install-claude-code-hooks.mjs",
+    "hooks:check-claude": "node scripts/install-claude-code-hooks.mjs --check",
+    "hooks:install-cursor": "node scripts/install-cursor-hooks.mjs",
+    "hooks:check-cursor": "node scripts/install-cursor-hooks.mjs --check",
+    "hooks:smoke-cursor": "node scripts/cursor-hooks/_run.smoke.mjs",
+    "companion": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action start",
+    "companion:stop": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action stop",
+    "companion:status": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action status",
+    "spexcompanion": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action start",
+    "spexcompanion:stop": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action stop",
+    "spexcompanion:status": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action status",
+    "console": "npm run dev -w spex-console",
+    "console:log": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/run-console-devlog.ps1",
+    "console:log:lan": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/run-console-devlog.ps1 -Lan",
+    "console:stop": "node scripts/dev-server-stop.mjs",
+    "console:status": "node scripts/dev-server-status.mjs",
+    "test:mcp": "node --test vendor/heyspex-mcp/*.test.mjs scripts/lib/*.test.mjs",
+    "verify:package": "node scripts/verify-mcp-package.mjs"
+  },
+  "//files": "PUBLISHED SURFACE - every entry is verified by `node scripts/verify-mcp-package.mjs`. It must cover the STATIC import closure of vendor/heyspex-mcp/cli.mjs and nothing else. SpexFleet internals (dev-factory/router.mjs, cloud-clients.mjs, cost-tracker.mjs, dream-research/) are deliberately absent - research-tools.mjs reaches them through the lazy dev-factory-bridge.mjs. Do not add a path here without re-running the verifier; npm publish is a one-way door ([[HS-ZJSP-0JNK-TASK-ship-the-heyspex-mcp-server-as-an]] / [[HS-8DET-0JNK-TASK-confirm-the-open-core-boundary-and]]). `dist/cli/*.mjs` + `dist/cli-templates/**` are a SEPARATE published surface (`hs init` / `hs install` bundled by `scripts/build-cli-bundle.mjs`, regenerated fresh every `prepack` - `dist/` itself stays git-ignored) - see that script's doc comment for the entry scope decision and [[HS-JOQX-0JNK-TASK-published-package-runs-hs-init-and-hs]]."
+}