@esneiderbravo/speclaw 0.3.4 → 0.3.5

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/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.5",
   "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"