@esneiderbravo/speclaw 0.3.4 → 0.3.7

package/dist/shared/budget.js

@@ -0,0 +1,159 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isMinimalMode, loadDeclaredBudget, packageRoot } from "./exposure.js";
+import { toolDefinitionTokens } from "./schema-tokens.js";
+import { estimateTokens } from "./tokens.js";
+/**
+ * Measure always-on context cost across the four surfaces.
+ *
+ * @param opts - Paths and optional pre-collected tool definitions.
+ * @returns Structured measurement; `total` excludes path-scoped surface D.
+ */
+export function measureBudget(opts = {}) {
+    const projectPath = opts.projectPath ?? process.cwd();
+    const packagePath = opts.packagePath ?? packageRoot();
+    const minimal = opts.minimal ?? isMinimalMode(projectPath);
+    const toolDefs = opts.tools ?? [];
+    const toolDetails = toolDefs.map((t) => ({
+        name: t.name,
+        tokens: toolDefinitionTokens(t),
+    }));
+    const tools = toolDetails.reduce((s, t) => s + t.tokens, 0);
+    const skillRoots = [
+        path.join(packagePath, "src/modules/lawbook/assets/skills"),
+        path.join(packagePath, "dist/modules/lawbook/assets/skills"),
+        path.join(projectPath, "ai-specs/skills"),
+    ];
+    const commandRoots = [
+        path.join(packagePath, "src/modules/lawbook/assets/commands"),
+        path.join(packagePath, "dist/modules/lawbook/assets/commands"),
+        path.join(projectPath, "ai-specs/commands"),
+    ];
+    const skillFiles = firstExistingFiles(skillRoots, (dir) => collectSkillBudgetFiles(dir));
+    const commandFiles = firstExistingFiles(commandRoots, (dir) => listFilesRecursive(dir).filter((f) => f.endsWith(".md")));
+    const scDetails = [...skillFiles, ...commandFiles].map((f) => ({
+        path: path.relative(packagePath, f) || path.relative(projectPath, f) || f,
+        tokens: estimateTokens(safeRead(f)),
+    }));
+    const skillsAndCommands = scDetails.reduce((s, x) => s + x.tokens, 0);
+    const alwaysOnPaths = ["CLAUDE.md", "AGENTS.md", "LAWS.md", "docs/compass.md"].map((rel) => path.join(projectPath, rel));
+    const alwaysOnDetails = alwaysOnPaths
+        .filter((p) => fs.existsSync(p))
+        .map((p) => ({
+        path: path.relative(projectPath, p),
+        tokens: estimateTokens(safeRead(p)),
+    }));
+    const alwaysOnInstructions = alwaysOnDetails.reduce((s, x) => s + x.tokens, 0);
+    const pathScopedDetails = collectPathScoped(projectPath);
+    const pathScoped = pathScopedDetails.reduce((s, x) => s + x.tokens, 0);
+    return {
+        tools,
+        skillsAndCommands,
+        alwaysOnInstructions,
+        pathScoped,
+        total: tools + skillsAndCommands + alwaysOnInstructions,
+        profile: minimal ? "minimal" : "full",
+        toolCount: toolDefs.length,
+        details: {
+            tools: toolDetails,
+            skillsAndCommands: scDetails,
+            alwaysOn: alwaysOnDetails,
+            pathScoped: pathScopedDetails,
+        },
+    };
+}
+/**
+ * Format a human-readable budget table.
+ *
+ * @param m - Measurement.
+ * @param declared - Optional declared ceilings for an ok/over column.
+ */
+export function formatBudgetTable(m, declared) {
+    const d = declared ?? loadDeclaredBudget();
+    const row = (label, tokens, cap) => {
+        const capStr = cap === null ? "—".padStart(8) : String(cap).padStart(8);
+        const status = cap === null ? "" : tokens <= cap ? "  ok" : "  OVER";
+        return `${label.padEnd(40)} ${String(tokens).padStart(8)} ${capStr}${status}`;
+    };
+    const lines = [
+        "Superficie                              tokens   presupuesto",
+        row(`A  tools MCP (${m.toolCount}, ${m.profile})`, m.tools, d.surfaces.tools),
+        row("B  skills + commands", m.skillsAndCommands, d.surfaces.skillsAndCommands),
+        row("C  always-on instructions", m.alwaysOnInstructions, d.surfaces.alwaysOnInstructions),
+        row("D  path-scoped rules", m.pathScoped, null),
+        `${"".padEnd(40)} ${"──────".padStart(8)} ${"──────".padStart(8)}`,
+        row("TOTAL always-on", m.total, m.profile === "minimal" ? d.minimal.total : d.total),
+    ];
+    return lines.join("\n");
+}
+function safeRead(file) {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function listFilesRecursive(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...listFilesRecursive(full));
+        else
+            out.push(full);
+    }
+    return out;
+}
+/** Skill budget: dispatcher SKILL.md + only that counts for B's "loaded at turn" description;
+ * for always-present skill index we count SKILL.md bodies (dispatchers) fully and step files
+ * are loaded on demand — still include step files in B per design (commands full; skills
+ * frontmatter+description each turn). For simplicity and honesty we count entire SKILL.md
+ * (dispatcher) and do NOT count steps/ toward always-on B (JIT). */
+function collectSkillBudgetFiles(skillsRoot) {
+    if (!fs.existsSync(skillsRoot))
+        return [];
+    const files = [];
+    for (const entry of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const skillMd = path.join(skillsRoot, entry.name, "SKILL.md");
+        if (fs.existsSync(skillMd))
+            files.push(skillMd);
+    }
+    return files;
+}
+function firstExistingFiles(roots, collect) {
+    for (const root of roots) {
+        if (!fs.existsSync(root))
+            continue;
+        const files = collect(root);
+        if (files.length)
+            return files;
+    }
+    return [];
+}
+function collectPathScoped(projectPath) {
+    const details = [];
+    const ruleDirs = [
+        path.join(projectPath, ".claude/rules"),
+        path.join(projectPath, "ai-specs/rules"),
+    ];
+    for (const dir of ruleDirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const f of listFilesRecursive(dir).filter((p) => p.endsWith(".md"))) {
+            const body = safeRead(f);
+            // Heuristic: frontmatter with paths: means path-scoped lazy load.
+            if (/^---[\s\S]*?^paths:\s*$/m.test(body) || /^---[\s\S]*?^paths:/m.test(body)) {
+                details.push({
+                    path: path.relative(projectPath, f),
+                    tokens: estimateTokens(body),
+                });
+            }
+        }
+    }
+    return details;
+}

package/dist/shared/exposure.js

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readManifest } from "./manifest.js";
+/**
+ * Tools omitted when the exposure profile is `minimal`. Kept tools are the
+ * discovery + law loop: compass_explore/search/recall, lawbook_validate/sync,
+ * law_verify, speclaw_check.
+ */
+export const MINIMAL_OMIT = new Set([
+    "compass_index",
+    "compass_watch",
+    "compass_impact",
+    "compass_trace",
+    "compass_visualize",
+    "lawbook_init",
+    "lawbook_archive",
+    "lawbook_list",
+    "init_project",
+    "scaffold",
+    "configure_agent",
+    "doctor",
+    "add_pack",
+    "list_packs",
+]);
+/**
+ * Whether minimal exposure is active for this process / project.
+ * `SPECLAW_MINIMAL=1` wins; otherwise the project manifest's `minimal` flag.
+ *
+ * @param cwd - Project root to read the manifest from (default `process.cwd()`).
+ */
+export function isMinimalMode(cwd = process.cwd()) {
+    if (process.env.SPECLAW_MINIMAL === "1")
+        return true;
+    return Boolean(readManifest(cwd)?.minimal);
+}
+/**
+ * Whether a tool name should be registered under the given profile.
+ *
+ * @param name - MCP tool name.
+ * @param minimal - Active exposure profile.
+ */
+export function shouldExpose(name, minimal) {
+    return !(minimal && MINIMAL_OMIT.has(name));
+}
+const DEFAULT_BUDGET = {
+    schemaVersion: 1,
+    estimator: "speclaw/estimate-v1",
+    surfaces: {
+        tools: 12000,
+        skillsAndCommands: 4000,
+        alwaysOnInstructions: 8000,
+    },
+    total: 24000,
+    perTool: 800,
+    maxDescriptionWords: 25,
+    dispatcher: 400,
+    map: 300,
+    minimal: { tools: 4500, total: 12000 },
+    note: "Placeholder ceilings — replaced after the first post-rewrite measurement.",
+};
+/**
+ * Resolve the directory that holds speclaw's package root (where
+ * `token-budget.json` lives when developing or when shipped next to package.json).
+ */
+export function packageRoot() {
+    // Walk up from this module: src/shared, dist/shared, or dist-test/src/shared.
+    // Prefer a directory that actually contains token-budget.json — dist-test also
+    // has package.json with this package's name, so name-matching alone is wrong.
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    let named = null;
+    for (let i = 0; i < 8; i++) {
+        if (fs.existsSync(path.join(dir, "token-budget.json")))
+            return dir;
+        const pkg = path.join(dir, "package.json");
+        if (!named && fs.existsSync(pkg)) {
+            try {
+                const name = JSON.parse(fs.readFileSync(pkg, "utf8")).name;
+                if (name === "@esneiderbravo/speclaw")
+                    named = dir;
+            }
+            catch {
+                /* continue */
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    if (named)
+        return named;
+    return process.cwd();
+}
+/**
+ * Load declared budget ceilings. Missing file → embedded defaults (tests may
+ * still override via the committed file once written).
+ *
+ * @param root - Directory containing `token-budget.json`.
+ */
+export function loadDeclaredBudget(root = packageRoot()) {
+    const p = path.join(root, "token-budget.json");
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+        return { ...DEFAULT_BUDGET, ...raw, surfaces: { ...DEFAULT_BUDGET.surfaces, ...raw.surfaces } };
+    }
+    catch {
+        return { ...DEFAULT_BUDGET };
+    }
+}

package/dist/shared/manifest.js

@@ -18,6 +18,7 @@ export function readManifest(projectPath) {
             baselines: m.baselines && typeof m.baselines === "object"
                 ? m.baselines
                 : {},
+            minimal: Boolean(m.minimal),
         };
     }
     catch {
@@ -32,12 +33,20 @@ export function readManifest(projectPath) {
  * @param version - The speclaw version doing the write.
  * @param packs - Pack names installed in this run.
  * @param baselines - Managed-file hashes to merge over the recorded ones.
+ * @param opts - Optional `minimal` flag; omitted keeps the prior value (default false).
  */
-export function writeManifest(projectPath, version, packs, baselines = {}) {
+export function writeManifest(projectPath, version, packs, baselines = {}, opts = {}) {
     const prev = readManifest(projectPath);
     const merged = Array.from(new Set([...(prev?.packs ?? []), ...packs]));
     const mergedBaselines = { ...(prev?.baselines ?? {}), ...baselines };
+    const minimal = opts.minimal !== undefined ? opts.minimal : (prev?.minimal ?? false);
     const p = manifestPath(projectPath);
     fs.mkdirSync(path.dirname(p), { recursive: true });
-    fs.writeFileSync(p, JSON.stringify({ version, packs: merged, baselines: mergedBaselines }, null, 2) + "\n");
+    const body = {
+        version,
+        packs: merged,
+        baselines: mergedBaselines,
+        ...(minimal ? { minimal: true } : {}),
+    };
+    fs.writeFileSync(p, JSON.stringify(body, null, 2) + "\n");
 }

package/dist/shared/mcp.js

@@ -1,3 +1,6 @@
+import { loadDeclaredBudget } from "./exposure.js";
+import { toolDefinitionTokens } from "./schema-tokens.js";
+import { countWords } from "./tokens.js";
 /**
  * Wrap a value as an MCP text tool-result.
  *
@@ -14,3 +17,33 @@ export function text(value) {
         ],
     };
 }
+/**
+ * Register one MCP tool after enforcing the context-budget caps (description
+ * word count and estimated definition tokens). Does **not** set
+ * `defer_loading` — that is not author-settable for MCP servers.
+ *
+ * @param server - MCP server to register on.
+ * @param spec - Tool name, description, schema, and handler.
+ * @throws If the description or definition cost exceeds the declared cap.
+ */
+export function defineTool(server, spec) {
+    const budget = loadDeclaredBudget();
+    const words = countWords(spec.description);
+    if (words > budget.maxDescriptionWords) {
+        throw new Error(`tool ${spec.name}: description is ${words} words (cap ${budget.maxDescriptionWords})`);
+    }
+    const cost = toolDefinitionTokens({
+        name: spec.name,
+        description: spec.description,
+        inputSchema: spec.inputSchema,
+    });
+    if (cost > budget.perTool) {
+        throw new Error(`tool ${spec.name}: ${cost} tokens exceeds the ${budget.perTool} per-tool cap`);
+    }
+    const inputSchema = (spec.inputSchema ?? {});
+    server.registerTool(spec.name, {
+        description: spec.description,
+        inputSchema,
+        ...(spec.annotations ? { annotations: spec.annotations } : {}),
+    }, spec.handler);
+}

package/dist/shared/redact.js

@@ -0,0 +1,90 @@
+import os from "node:os";
+import path from "node:path";
+/**
+ * Replace every occurrence of `from` that sits on a path boundary (not as a
+ * substring of a longer path). Prevents `/home/runner` from mangling
+ * `/opt/home/runner/...` into `/opt~/...` on GitHub Actions.
+ */
+function replacePathToken(text, from, to) {
+    if (!from || from.length < 2)
+        return text;
+    let out = text;
+    let idx = 0;
+    while ((idx = out.indexOf(from, idx)) !== -1) {
+        const before = idx === 0 ? "" : out[idx - 1];
+        const afterIdx = idx + from.length;
+        const after = afterIdx >= out.length ? "" : out[afterIdx];
+        // Preceding char must not continue a path segment (blocks /opt + /home/…).
+        const beforeOk = idx === 0 || !/[A-Za-z0-9._-]/.test(before);
+        // Following char must end the token or continue as a separator.
+        const afterOk = after === "" || after === "/" || after === "\\" || /[\s'",):]/.test(after);
+        if (beforeOk && afterOk) {
+            out = out.slice(0, idx) + to + out.slice(afterIdx);
+            idx += to.length;
+        }
+        else {
+            idx += 1;
+        }
+    }
+    return out;
+}
+/**
+ * Redact absolute paths and usernames so a doctor report is safe to paste into
+ * a public issue. Home becomes `~`, the project root becomes `<project>`, and
+ * OS usernames are scrubbed from path segments.
+ *
+ * @param text - Arbitrary detail / remedy text that may contain paths.
+ * @param projectPath - Absolute project root to replace with `<project>`.
+ * @returns Redacted text (POSIX and Windows separators handled).
+ */
+export function redactText(text, projectPath) {
+    let out = text;
+    const home = os.homedir();
+    const user = os.userInfo().username;
+    const replacements = [];
+    const queueReplacement = (from, to) => {
+        if (from && from.length > 1)
+            replacements.push([from, to]);
+    };
+    queueReplacement(path.resolve(projectPath), "<project>");
+    queueReplacement(projectPath.replace(/\//g, "\\"), "<project>");
+    queueReplacement(home, "~");
+    queueReplacement(home.replace(/\//g, "\\"), "~");
+    queueReplacement(`C:\\Users\\${user}`, "~");
+    queueReplacement(`c:\\Users\\${user}`, "~");
+    replacements.sort((a, b) => b[0].length - a[0].length);
+    for (const [from, to] of replacements) {
+        out = replacePathToken(out, from, to);
+        if (from.includes("\\"))
+            out = replacePathToken(out, from.replace(/\\/g, "/"), to);
+    }
+    if (user && user.length > 1) {
+        const seg = new RegExp(`(^|[/\\\\])${escapeRegExp(user)}(?=[/\\\\]|$)`, "gi");
+        out = out.replace(seg, `$1<user>`);
+    }
+    return out;
+}
+/**
+ * Deep-redact every string field in a JSON-compatible value.
+ *
+ * @param value - Report fragment.
+ * @param projectPath - Project root for `<project>` substitution.
+ */
+export function redactValue(value, projectPath) {
+    if (typeof value === "string")
+        return redactText(value, projectPath);
+    if (Array.isArray(value)) {
+        return value.map((v) => redactValue(v, projectPath));
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = redactValue(v, projectPath);
+        }
+        return out;
+    }
+    return value;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/shared/schema-tokens.js

@@ -0,0 +1,86 @@
+import { estimateTokens } from "./tokens.js";
+/**
+ * Best-effort JSON Schema for the Zod shapes speclaw registers as MCP
+ * `inputSchema` records. Stable and offline — used only for token budgeting,
+ * not for validation. Prefer structural fidelity over full Zod coverage.
+ *
+ * @param shape - Record of Zod fields as passed to `registerTool`.
+ * @returns A JSON-Schema-like plain object suitable for `JSON.stringify`.
+ */
+export function zodShapeToJsonSchema(shape) {
+    const properties = {};
+    const required = [];
+    for (const [key, schema] of Object.entries(shape ?? {})) {
+        const { json, optional } = zodTypeToJson(schema);
+        properties[key] = json;
+        if (!optional)
+            required.push(key);
+    }
+    return {
+        type: "object",
+        properties,
+        ...(required.length ? { required } : {}),
+    };
+}
+function zodTypeToJson(schema) {
+    const def = schema._def;
+    const typeName = def.typeName ?? "";
+    const description = def.description;
+    if (typeName === "ZodOptional" || typeName === "ZodDefault") {
+        const inner = zodTypeToJson(def.innerType);
+        return { json: withDesc(inner.json, description), optional: true };
+    }
+    if (typeName === "ZodString") {
+        return { json: withDesc({ type: "string" }, description), optional: false };
+    }
+    if (typeName === "ZodNumber") {
+        return { json: withDesc({ type: "number" }, description), optional: false };
+    }
+    if (typeName === "ZodBoolean") {
+        return { json: withDesc({ type: "boolean" }, description), optional: false };
+    }
+    if (typeName === "ZodEnum") {
+        return {
+            json: withDesc({ type: "string", enum: def.values ?? [] }, description),
+            optional: false,
+        };
+    }
+    if (typeName === "ZodArray") {
+        const item = zodTypeToJson(def.type);
+        return {
+            json: withDesc({ type: "array", items: item.json }, description),
+            optional: false,
+        };
+    }
+    if (typeName === "ZodObject") {
+        return {
+            json: withDesc(zodShapeToJsonSchema(def.shape?.() ?? {}), description),
+            optional: false,
+        };
+    }
+    if (typeName === "ZodRecord") {
+        const value = def.valueType ? zodTypeToJson(def.valueType).json : {};
+        return {
+            json: withDesc({ type: "object", additionalProperties: value }, description),
+            optional: false,
+        };
+    }
+    if (typeName === "ZodUnknown" || typeName === "ZodAny") {
+        return { json: withDesc({}, description), optional: false };
+    }
+    // Fallback: type name only — still deterministic for budgeting.
+    return { json: withDesc({ type: typeName || "unknown" }, description), optional: false };
+}
+function withDesc(json, description) {
+    return description ? { ...json, description } : json;
+}
+/**
+ * Estimate tokens for one tool definition (name + description + JSON Schema).
+ *
+ * @param tool - Registered tool fields.
+ * @returns Estimated definition cost.
+ */
+export function toolDefinitionTokens(tool) {
+    const schemaJson = JSON.stringify(zodShapeToJsonSchema(tool.inputSchema));
+    return estimateTokens(tool.name) + estimateTokens(tool.description) + estimateTokens(schemaJson);
+}

package/dist/shared/tokens.js

@@ -0,0 +1,41 @@
+/**
+ * Deterministic token estimator. NOT a tokenizer: intended accuracy about ±8%
+ * against Anthropic's tokenizer on speclaw's own asset corpus. Intentionally
+ * not exact — a real BPE vocab is a multi-megabyte dependency, and exact counts
+ * are model-dependent. The CI gate needs a number that is stable across versions.
+ *
+ * Contract: monotone (more text ⇒ more or equal tokens) and stable across runs
+ * and processes. Performs no network I/O.
+ *
+ * @param text - Input to estimate.
+ * @returns Estimated token count (non-negative integer).
+ */
+export function estimateTokens(text) {
+    if (text.length === 0)
+        return 0;
+    const chunks = text.match(/[A-Za-z]+|\d+|\s+|[^\sA-Za-z\d]/g) ?? [];
+    let total = 0;
+    for (const c of chunks) {
+        if (/^[A-Za-z]+$/.test(c))
+            total += Math.ceil(c.length / 4.1);
+        else if (/^\d+$/.test(c))
+            total += Math.ceil(c.length / 2.5);
+        else if (/^\s+$/.test(c))
+            total += c.includes("\n") ? 1 : 0;
+        else
+            total += 1;
+    }
+    return total;
+}
+/**
+ * Count whitespace-separated words in a description (for the ≤25-word cap).
+ *
+ * @param description - Tool description prose.
+ * @returns Word count.
+ */
+export function countWords(description) {
+    const trimmed = description.trim();
+    if (!trimmed)
+        return 0;
+    return trimmed.split(/\s+/).length;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.3.4",
+  "version": "0.3.7",
   "publishConfig": {
     "access": "public"
   },
@@ -41,6 +41,7 @@
     "lint": "eslint .",
     "format": "prettier --write .",
     "check": "prettier --check . && eslint .",
+    "budget:calibrate": "node scripts/budget-calibrate.mjs",
     "pretest": "tsc -p tsconfig.test.json && node scripts/prep-test-assets.mjs",
     "test": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=80 --test-coverage-exclude='dist-test/test/**' --test-coverage-exclude='dist/**' 'dist-test/test/**/*.test.js'",
     "prepublishOnly": "npm run build"