@esneiderbravo/speclaw 0.3.5 → 0.3.7

package/README.md

@@ -5,6 +5,8 @@
 <br/>
 
 <a href="https://www.npmjs.com/package/@esneiderbravo/speclaw"><img src="https://img.shields.io/npm/v/@esneiderbravo/speclaw?color=0E8E8E&labelColor=0B0F10&style=flat-square&label=npm" alt="npm"></a>
+&nbsp;<a href="https://github.com/esneiderbravo/speclaw/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/esneiderbravo/speclaw/ci.yml?branch=main&label=CI&labelColor=0B0F10&style=flat-square&color=0E8E8E" alt="CI"></a>
+&nbsp;<a href="https://www.npmjs.com/package/@esneiderbravo/speclaw?activeTab=versions"><img src="https://img.shields.io/badge/provenance-SLSA-0E8E8E?labelColor=0B0F10&style=flat-square" alt="npm provenance"></a>
 &nbsp;<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0E8E8E?labelColor=0B0F10&style=flat-square" alt="MIT"></a>
 &nbsp;<img src="https://img.shields.io/badge/node-%E2%89%A522-0E8E8E?labelColor=0B0F10&style=flat-square" alt="Node >= 22">
 
@@ -29,32 +31,40 @@ One command. No cloud, no LLM, no API keys — <b>everything runs on your machin
 <br/>
 
 > [!TIP]
-> **Install once, then one command sets everything up.** Install speclaw globally, run
-> `speclaw init`, pick the agents you use, and speclaw scaffolds the project, indexes
-> your code, and hands your agent a ready-to-paste prompt to finish the setup.
+> **One command. Detects your agents and wires only those.** Paste
+> `npx @esneiderbravo/speclaw@latest init` — speclaw detects Claude Code, Cursor,
+> Codex, Windsurf, and generic `AGENTS.md` surfaces, scaffolds the constitution +
+> lawbook, indexes your code, and registers the local MCP server — only for the
+> agents you pick. This one-liner is a **stable contract** (see
+> [CONTRIBUTING.md](CONTRIBUTING.md)); do not invent alternate install commands in
+> directories or newsletters.
 
 <br/>
 
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Quick start
 
-Install speclaw globally (once), then run `init` in your project root:
-
 ```bash
-npm i -g @esneiderbravo/speclaw
-speclaw init
+npx @esneiderbravo/speclaw@latest init
 ```
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-quickstart.png" width="800" alt="speclaw init">
 </p>
 
-The `speclaw` command is now available everywhere — run `speclaw index`,
-`speclaw visualize`, or `speclaw lawbook …` directly in any project.
+Prefer a global install for repeated CLI use?
+
+```bash
+npm i -g @esneiderbravo/speclaw
+speclaw init
+```
+
+The `speclaw` command is then available everywhere — run `speclaw index`,
+`speclaw doctor`, `speclaw visualize`, or `speclaw lawbook …` directly.
 
 `init` will:
 
-1. **Ask which agents you use** (Claude Code, Cursor, Codex, …) — and configure
-   only those. Add more later; nothing is forced on you.
+1. **Ask which agents you use** (Claude Code, Cursor, Codex, Windsurf, …) — and
+   configure only those. Add more later; nothing is forced on you.
 2. Write the **foundation** (constitution + standards) and the **lawbook workflow**,
    and compile your blocking laws into **agent hooks** for the agents that support them.
 3. **Index your code** with a live progress bar and a summary of what it found.
@@ -62,9 +72,23 @@ The `speclaw` command is now available everywhere — run `speclaw index`,
 5. Print a prompt to paste into your agent so it fills the constitution with your
    project's real architecture and conventions.
 
-Prefer not to install globally? A one-off `npx @esneiderbravo/speclaw init` works
-too (also `pnpm dlx` / `yarn dlx`) — but installing globally means you can run the
-`speclaw` commands directly afterwards.
+When something breaks, run `speclaw doctor --json` and paste it into an issue
+(required on bug reports). Output is redacted by default.
+
+<br/>
+
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Verify a release (provenance)
+
+Every npm publish is signed via **Trusted Publishing (OIDC)** and carries a
+SLSA provenance attestation tied to this repository and workflow. That proves
+*where* the tarball was built — not that its contents are benign. Pair it with
+your own review and (later) law-integrity pinning.
+
+```bash
+npm audit signatures
+# After downloading the tarball from the registry:
+gh attestation verify <tarball> --owner esneiderbravo
+```
 
 <br/>
 
@@ -202,7 +226,10 @@ you** — commit your own skills and commands there if you want to.
 
 **Enforcement artifacts.** For agents that support hooks, speclaw merges its law
 hooks into that agent's settings (e.g. `.claude/settings.json`) **by identity** —
-it never touches hooks you added yourself. The compiled law manifest lives in
+it never touches hooks you added yourself. Each speclaw `mcp_tool` hook includes
+an `input` map Claude Code substitutes from the hook event (`${cwd}`,
+`${hook_event_name}`, `${tool_input.file_path}`, …) so `speclaw_check` receives
+`projectPath` / `event` / `payload`. The compiled law manifest lives in
 `.speclaw/laws-manifest.json` (gitignored, regenerated on `init`/`update`), and a
 context-coverage log in `.speclaw/context-log.jsonl` feeds `speclaw doctor`.
 

package/dist/cli/commands/doctor.js

@@ -1,31 +1,63 @@
 import { doctor } from "../../modules/foundation/doctor.js";
-import { measureInstallBudget } from "../../modules/foundation/context-budget.js";
 import { ui } from "../lib/ui.js";
-/** Verify the installation, printing each check and exiting non-zero on failure. */
-export async function runDoctor(_flags) {
-    const cwd = process.cwd();
-    const checks = doctor(cwd);
+const STATUS_MARK = {
+    ok: "ok",
+    warn: "warn",
+    error: "error",
+    skip: "skip",
+};
+function printHuman(report) {
     ui.heading("speclaw doctor");
-    for (const c of checks) {
-        if (c.ok)
-            ui.ok(`${c.name} — ${c.detail}`);
-        else
-            ui.err(`${c.name} — ${c.detail}`);
-    }
-    try {
-        const m = measureInstallBudget(cwd);
-        ui.ok(`context budget — profile ${m.profile} · ${m.toolCount} tools · ~${m.total} always-on tokens ` +
-            `(A ${m.tools} · B ${m.skillsAndCommands} · C ${m.alwaysOnInstructions}; D path-scoped ${m.pathScoped} not in total)`);
-    }
-    catch (err) {
-        ui.warn(`context budget — could not measure: ${err.message}`);
+    for (const section of report.sections) {
+        ui.plain();
+        ui.ok(`${section.id}  [${STATUS_MARK[section.status]}]`);
+        for (const c of section.checks) {
+            const line = `${c.title.padEnd(24)} ${c.detail ?? c.status}`;
+            if (c.status === "ok" || c.status === "skip")
+                ui.ok(`  ${line}`);
+            else if (c.status === "warn") {
+                ui.warn(`  ${line}`);
+                if (c.remedy)
+                    ui.plain(`      → ${c.remedy}`);
+            }
+            else {
+                ui.err(`  ${line}`);
+                if (c.remedy)
+                    ui.plain(`      → ${c.remedy}`);
+            }
+        }
     }
-    const failed = checks.filter((c) => !c.ok).length;
     ui.plain();
-    if (failed === 0)
+    const warns = report.sections.flatMap((s) => s.checks).filter((c) => c.status === "warn").length;
+    const errs = report.sections.flatMap((s) => s.checks).filter((c) => c.status === "error").length;
+    if (errs === 0 && warns === 0)
         ui.ok("Everything is within the law.");
+    else if (errs === 0) {
+        ui.warn(`${warns} warning(s). Run \`speclaw doctor --json\` and paste it into an issue.`);
+    }
+    else {
+        ui.err(`${errs} error(s), ${warns} warning(s).`);
+    }
+}
+/**
+ * Verify the installation. Supports `--json`, `--offline`, `--strict`,
+ * `--redact` (default) / `--no-redact`.
+ */
+export async function runDoctor(flags) {
+    const cwd = process.cwd();
+    const redact = flags["no-redact"] ? false : true;
+    const report = await doctor(cwd, {
+        offline: Boolean(flags.offline),
+        redact,
+    });
+    if (flags.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
     else {
-        ui.warn(`${failed} check(s) failed.`);
+        printHuman(report);
+    }
+    const strict = Boolean(flags.strict);
+    if (report.status === "error" || (strict && report.status === "warn")) {
         process.exit(1);
     }
 }

package/dist/cli/commands/telemetry.js

@@ -0,0 +1,16 @@
+import { ui } from "../lib/ui.js";
+/**
+ * Telemetry posture command. speclaw ships **no** telemetry code — `status`
+ * says so; enable/disable/log are rejected.
+ */
+export async function runTelemetry(flags) {
+    const sub = flags._[0] ?? "status";
+    if (sub === "status") {
+        ui.ok("speclaw includes no telemetry — nothing is collected or transmitted.");
+        ui.plain("Policy: 100% local. There is no enable path and no analytics endpoint.");
+        return;
+    }
+    ui.err(`telemetry ${sub} is unavailable: speclaw does not include telemetry. ` +
+        "Run `speclaw telemetry status`.");
+    process.exit(1);
+}

package/dist/cli/commands/update.js

@@ -79,6 +79,19 @@ const MIGRATIONS = [
             "(no server-side defer_loading).\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "0.3.6",
+        describe: "Doctor JSON diagnostics and stable install one-liner",
+        agentPrompt: "- Mention that `speclaw doctor --json` is the support report (redacted by default) " +
+            "and that the stable install command is `npx @esneiderbravo/speclaw@latest init`.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
+    {
+        version: "0.3.7",
+        describe: "Claude Code mcp_tool hooks pass speclaw_check input via ${…} templates",
+        // scaffold → installHooks already rewrites .claude/settings.json when the
+        // compiled hook shape changes; no extra run() step.
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:

package/dist/cli/index.js

@@ -35,8 +35,9 @@ Lawbook (spec-driven workflow)
   lawbook archive <c>      Finalize and archive a change
 
 Other
-  doctor                   Verify the installation
+  doctor                   Verify the installation (--json, --offline, --strict)
   budget                   Measure always-on context cost (tools, skills, instructions)
+  telemetry status         Confirm speclaw ships no telemetry
   check                    Evaluate an action against the laws (hooks call this; --dry-run to preview)
   laws verify              Verify the deterministic dependency/graph laws against the index
   verify                   Verify laws for CI: exit codes, --sarif, --json, --strict-engines
@@ -59,6 +60,7 @@ const HEADER_COMMANDS = new Set([
     "agent",
     "doctor",
     "budget",
+    "telemetry",
     "index",
     "watch",
     "lawbook",
@@ -68,7 +70,8 @@ const HEADER_COMMANDS = new Set([
  * header-eligible command AND stdout is an interactive terminal (so pipes,
  * redirection, and CI stay clean — mirroring the color gate in `ui.ts`). A
  * forced-color signal counts as interactive so the header is exercisable in a
- * child process. `budget --json` is machine-consumed and suppresses the header.
+ * child process. `budget --json` and `doctor --json` are machine-consumed and
+ * suppress the header.
  */
 function maybeHeader(cmd, flags) {
     if (!process.stdout.isTTY && process.env.FORCE_COLOR !== "1")
@@ -77,6 +80,8 @@ function maybeHeader(cmd, flags) {
         return;
     if (cmd === "budget" && flags.json)
         return;
+    if (cmd === "doctor" && flags.json)
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -121,6 +126,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/doctor.js")).runDoctor(flags);
         case "budget":
             return (await import("./commands/budget.js")).runBudget(flags);
+        case "telemetry":
+            return (await import("./commands/telemetry.js")).runTelemetry(flags);
         case "check":
             return (await import("./commands/check.js")).runCheck(flags);
         case "laws":

package/dist/modules/compass/indexer.js

@@ -165,6 +165,7 @@ export async function buildIndex(projectPath, onProgress) {
       )
       WHERE kind = 'call' AND dst_node_id IS NULL
     `);
+        db.prepare("INSERT INTO meta(key, value) VALUES ('indexed_at', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(new Date().toISOString());
         db.exec("COMMIT");
     }
     catch (err) {

package/dist/modules/foundation/context-budget.js

@@ -1,12 +1,22 @@
+import { z } from "zod";
 import { registerCompass } from "../compass/register.js";
 import { registerSpec } from "../lawbook/register.js";
 import { registerTools } from "../tools/register.js";
-import { registerFoundation } from "./register.js";
+import { registerFoundationCore } from "./register-core.js";
 import { measureBudget } from "../../shared/budget.js";
-import { isMinimalMode, packageRoot } from "../../shared/exposure.js";
+import { isMinimalMode, packageRoot, shouldExpose } from "../../shared/exposure.js";
+/** Mirrors the `doctor` tool surface without importing `doctor.ts` (avoids a cycle). */
+const DOCTOR_TOOL_FOR_BUDGET = {
+    name: "doctor",
+    description: "Verify the speclaw install; returns a versioned DoctorReport (schemaVersion 1).",
+    inputSchema: { projectPath: z.string() },
+};
 /**
  * Collect tool definitions as the MCP server would register them for a profile.
  *
+ * Uses `registerFoundationCore` plus a static `doctor` stub so budget/doctor
+ * measurement never imports the live `doctor` implementation (module cycle).
+ *
  * @param minimal - Exposure profile.
  */
 export function collectRegisteredTools(minimal) {
@@ -22,7 +32,10 @@ export function collectRegisteredTools(minimal) {
     };
     const opts = { minimal };
     const stub = server;
-    registerFoundation(stub, opts);
+    registerFoundationCore(stub, opts);
+    if (shouldExpose("doctor", minimal)) {
+        tools.push(DOCTOR_TOOL_FOR_BUDGET);
+    }
     registerSpec(stub, opts);
     registerCompass(stub, opts);
     registerTools(stub, opts);