peaks-loop 4.1.2 → 4.1.4

package/dist/services/mcp/tool-core.js

@@ -0,0 +1,137 @@
+// src/services/mcp/tool-core.ts
+//
+// What both tool handlers are made of: the result shape, the argument-to-argv
+// step, and the one place a CLI execution becomes an outcome. Split out of
+// `tools.ts` because that file had grown past the repo's 300-line cap, and the
+// cap is measured per file rather than per concept.
+//
+// ERRORS ARE NEVER FLATTENED HERE, either. A CLI failure becomes a `failure`
+// string on the outcome, never an absent value: a read tool that answers
+// "nothing there" when it actually failed is worse than one that errors, because
+// the reader believes the empty answer (spec §9 rule 3).
+import { executeCliArgv } from './cli-executor.js';
+/** How much of one memory note's description travels back. */
+export const MEMORY_EXCERPT_CHARS = 120;
+/** Hard ceiling on matches returned, independent of what the CLI was asked for. */
+export const MEMORY_MAX_RETURNED = 50;
+/**
+ * Hand-written parameter defaults — the one place this module can drift from the
+ * whitelist (spec §8.1 asks such places to be visible). `project` is a MANDATORY
+ * option of `peaks request show`, and a status caller should not have to repeat
+ * the directory the server already runs in. Nothing else is defaulted: every
+ * other placeholder is either required by the caller or defaulted in the data.
+ */
+function defaultFor(param, context) {
+    return param === 'project' ? (context.cwd ?? process.cwd()) : undefined;
+}
+/**
+ * A transported argument as the guard's input. The JSON transport carries
+ * numbers for integer parameters and the guard can only judge a string, so
+ * coercion happens here, at the boundary — and a wrong JSON type is NOT
+ * stringified into something that looks like data: it becomes the empty string,
+ * which the guard already refuses by name (`EMPTY`).
+ */
+function asGuardInput(supplied) {
+    if (typeof supplied === 'string')
+        return supplied;
+    if (typeof supplied === 'number')
+        return String(supplied);
+    return '';
+}
+/**
+ * The values to render one entry with, or `undefined` when the caller did not
+ * supply enough for this entry to run. A value the caller DID supply is always
+ * present — it is handed to the guard, which is what decides whether it is
+ * allowed, so nothing supplied can be silently skipped.
+ */
+export function valuesForEntry(entry, args, context) {
+    const values = {};
+    for (const [name, spec] of Object.entries(entry.params)) {
+        const supplied = args[name];
+        if (supplied !== undefined) {
+            values[name] = asGuardInput(supplied);
+            continue;
+        }
+        const fallback = spec.default === undefined ? defaultFor(name, context) : String(spec.default);
+        if (fallback === undefined)
+            return undefined;
+        values[name] = fallback;
+    }
+    return values;
+}
+/** True when the CLI process itself failed, or its stdout was not a JSON envelope. */
+function failureReasonOf(execution, envelope) {
+    const called = `peaks ${execution.argv.join(' ')}`;
+    if (execution.launchError !== undefined) {
+        return `The peaks CLI could not be started: ${execution.launchError}`;
+    }
+    if (execution.timedOut) {
+        return `The peaks CLI did not finish in time and was killed: ${called}`;
+    }
+    if (execution.exitCode !== 0) {
+        return `The peaks CLI exited with code ${String(execution.exitCode)}: ${called}`;
+    }
+    if (envelope === undefined) {
+        return `The peaks CLI printed no JSON on stdout: ${called}`;
+    }
+    if (isFailedEnvelope(envelope)) {
+        return `The peaks CLI reported failure: ${called}`;
+    }
+    return undefined;
+}
+function isFailedEnvelope(value) {
+    return typeof value === 'object' && value !== null && 'ok' in value && value.ok === false;
+}
+function parseStdout(stdout) {
+    try {
+        return { parsed: true, value: JSON.parse(stdout) };
+    }
+    catch {
+        return { parsed: false };
+    }
+}
+/** Render the outcomes as a tool result, failing the call when any argv failed. */
+export function resultOf(outcomes) {
+    const payload = {};
+    for (const outcome of outcomes) {
+        payload[outcome.key] =
+            outcome.envelope === undefined
+                ? { ok: false, message: outcome.failure ?? 'no output', argv: outcome.execution.argv }
+                : outcome.envelope;
+    }
+    const failures = outcomes.filter((outcome) => outcome.failure !== undefined);
+    if (failures.length === 0) {
+        return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    ...payload,
+                    failures: failures.map((outcome) => ({ key: outcome.key, reason: outcome.failure }))
+                })
+            }
+        ],
+        isError: true
+    };
+}
+/** A refused call: the parameter guard said no, before anything was executed. */
+export function rejectedResult(entry, reason) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ entry: entry.id, reason }) }],
+        isError: true
+    };
+}
+/** Execute one already-validated argv and keep its whole outcome. */
+export async function runArgv(key, argv, context) {
+    const execute = context.execute ??
+        ((args) => executeCliArgv(args, context.cwd === undefined ? {} : { cwd: context.cwd }));
+    const execution = await execute(argv);
+    const parsed = parseStdout(execution.stdout);
+    const envelope = parsed.parsed ? parsed.value : undefined;
+    const failure = failureReasonOf(execution, envelope);
+    return failure === undefined
+        ? { key, execution, envelope }
+        : { key, execution, envelope, failure };
+}

package/dist/services/mcp/tools.d.ts

@@ -0,0 +1,13 @@
+import type { McpToolDefinition } from './surface.js';
+import { type ToolCallContext, type ToolCallResult } from './tool-core.js';
+/**
+ * `peaks_status`: run every argv the caller supplied enough for, and return each
+ * CLI envelope verbatim under the id of the whitelist entry that produced it.
+ */
+export declare function callStatusTool(tool: McpToolDefinition, args: Readonly<Record<string, unknown>>, context: ToolCallContext): Promise<ToolCallResult>;
+type ToolHandler = (tool: McpToolDefinition, args: Readonly<Record<string, unknown>>, context: ToolCallContext) => Promise<ToolCallResult>;
+/** Tools the surface declares that no handler can serve. Non-empty = refuse to start. */
+export declare function missingHandlers(tools: readonly McpToolDefinition[]): readonly string[];
+/** Route a `tools/call` to its handler, or `undefined` for a tool nobody serves. */
+export declare function handlerFor(name: string): ToolHandler | undefined;
+export {};

package/dist/services/mcp/tools.js

@@ -0,0 +1,58 @@
+// src/services/mcp/tools.ts
+//
+// `peaks_status`, and the table that routes a `tools/call` to its handler. The
+// result shape, the argument-to-argv step and the outcome rendering live in
+// `tool-core.ts`; the bounded memory tool lives in `memory-tool.ts`.
+//
+// The composite is a pipe with a shape, never a judge (spec §3.2): "a composite
+// tool may arrange and reshape; it may not CONCLUDE." Each CLI envelope is
+// embedded VERBATIM under the whitelist entry id that produced it, so the whole
+// result is an identity transform of the calls it ran. A key is absent when its
+// argv did not run — exactly "subset"; no branch fabricates a value no argv
+// returned.
+import { buildArgv } from '../readonly-surface/argv-guard.js';
+import { callMemorySearchTool } from './memory-tool.js';
+import { rejectedResult, resultOf, runArgv, valuesForEntry } from './tool-core.js';
+/**
+ * `peaks_status`: run every argv the caller supplied enough for, and return each
+ * CLI envelope verbatim under the id of the whitelist entry that produced it.
+ */
+export async function callStatusTool(tool, args, context) {
+    // Every argv is BUILT before any is run. Executing as we go meant a refused
+    // placeholder left the earlier argv of the same call already executed — a
+    // caller's malformed input would have reached the CLI's read path anyway.
+    const plan = [];
+    for (const entry of tool.entries) {
+        const values = valuesForEntry(entry, args, context);
+        if (values === undefined)
+            continue;
+        const built = buildArgv(entry, values);
+        if (!built.ok) {
+            return rejectedResult(entry, `Parameter ${built.param} was refused: ${built.message}`);
+        }
+        plan.push({ id: entry.id, argv: built.argv });
+    }
+    const outcomes = [];
+    for (const step of plan) {
+        outcomes.push(await runArgv(step.id, step.argv, context));
+    }
+    return resultOf(outcomes);
+}
+/**
+ * Tool name -> handler, spelled out rather than derived. A tool the whitelist
+ * declares but this table does not name cannot be served, and `missingHandlers`
+ * below turns that into a refusal to start instead of a call that answers with
+ * whatever the fallback branch happened to do.
+ */
+const TOOL_HANDLERS = {
+    peaks_status: callStatusTool,
+    peaks_memory_search: callMemorySearchTool
+};
+/** Tools the surface declares that no handler can serve. Non-empty = refuse to start. */
+export function missingHandlers(tools) {
+    return tools.map((tool) => tool.name).filter((name) => !(name in TOOL_HANDLERS));
+}
+/** Route a `tools/call` to its handler, or `undefined` for a tool nobody serves. */
+export function handlerFor(name) {
+    return TOOL_HANDLERS[name];
+}

package/dist/services/readonly-surface/argv-guard.d.ts

@@ -0,0 +1,32 @@
+import type { PlaceholderSpec, ReadOnlyWhitelistEntry } from './readonly-whitelist.js';
+/** Upper bound on any single placeholder value, whatever its type. */
+export declare const READONLY_VALUE_MAX_LENGTH = 200;
+export type GuardRejection = {
+    readonly ok: false;
+    readonly param: string;
+    readonly code: GuardRejectionCode;
+    readonly message: string;
+};
+export type GuardRejectionCode = 'NOT_A_STRING' | 'EMPTY' | 'TOO_LONG' | 'FLAG_SHAPED' | 'CONTROL_CHARACTER' | 'WHITESPACE' | 'PATTERN_MISMATCH' | 'NOT_IN_ENUM' | 'NOT_AN_INTEGER' | 'OUT_OF_RANGE' | 'NOT_ABSOLUTE';
+export type GuardResult = {
+    readonly ok: true;
+    readonly value: string;
+} | GuardRejection;
+/** The process options that keep the array from being re-parsed by a shell. */
+export declare function readonlySpawnOptions(): {
+    readonly shell: false;
+};
+/** Validate one placeholder value against its spec. */
+export declare function validatePlaceholderValue(param: string, spec: PlaceholderSpec, raw: unknown): GuardResult;
+export type BuildArgvResult = {
+    readonly ok: true;
+    readonly argv: string[];
+} | GuardRejection;
+/**
+ * Render a whitelist entry into a concrete argv ARRAY.
+ *
+ * The output is never a string: literals and validated values are pushed as
+ * separate elements, so no value can contribute token boundaries. A parameter the
+ * entry does not declare is refused rather than appended.
+ */
+export declare function buildArgv(entry: ReadOnlyWhitelistEntry, values: Readonly<Record<string, string>>): BuildArgvResult;

package/dist/services/readonly-surface/argv-guard.js

@@ -0,0 +1,164 @@
+/**
+ * Parameter-injection guard for the read-only surface.
+ *
+ * THE ATTACK. An argv template has placeholder slots (`request show <rid>`). If a
+ * placeholder value is pasted into a command LINE, the value `--apply` stops being
+ * a request id and becomes a flag - the semantics of the call are inverted by its
+ * own data. Two independent defences, both required (spec §8.1):
+ *
+ *   1. TYPE WHITELIST - every placeholder declares a type, and the value must
+ *      satisfy it. No type admits a leading `-`, so a flag-shaped value is never a
+ *      legal value of any placeholder.
+ *   2. ARRAY PASSING - `buildArgv` returns `string[]`. The caller passes the array
+ *      to the process API with shell parsing disabled (`readonlySpawnOptions`), so
+ *      no value is ever re-tokenized by a shell.
+ *
+ * Defence 2 alone is not enough: `spawn(..., {shell:false})` still hands `--apply`
+ * to the CLI as a real flag. Defence 1 alone is not enough: a caller that joins
+ * the array into a string reintroduces the shell. Hence both.
+ */
+import { isAbsolute } from 'node:path';
+/** Fallback pattern for a `slug` placeholder that declares none. */
+const DEFAULT_SLUG_PATTERN = '^[a-z0-9][a-z0-9-]*$';
+/** Upper bound on any single placeholder value, whatever its type. */
+export const READONLY_VALUE_MAX_LENGTH = 200;
+/** The process options that keep the array from being re-parsed by a shell. */
+export function readonlySpawnOptions() {
+    return { shell: false };
+}
+function reject(param, code, message) {
+    return { ok: false, param, code, message };
+}
+/**
+ * Control characters, matched by Unicode category rather than by a literal range:
+ * a hand-written `\x00-\x1f` class is a lint error (`no-control-regex`) precisely
+ * because such a range in a pattern is usually a bug, and `\p{Cc}` says what is
+ * meant without spelling out code points.
+ */
+function hasControlCharacter(value) {
+    return /\p{Cc}/u.test(value);
+}
+/**
+ * The rules that hold for EVERY type, before any type-specific rule runs. A
+ * leading `-` is refused here, so no type can carry a flag into the argv.
+ */
+function precheckCommon(param, raw) {
+    if (typeof raw !== 'string') {
+        return reject(param, 'NOT_A_STRING', `Parameter ${param} must be a string.`);
+    }
+    if (raw.length === 0)
+        return reject(param, 'EMPTY', `Parameter ${param} must not be empty.`);
+    if (raw.length > READONLY_VALUE_MAX_LENGTH) {
+        return reject(param, 'TOO_LONG', `Parameter ${param} exceeds ${READONLY_VALUE_MAX_LENGTH} characters.`);
+    }
+    if (raw.startsWith('-')) {
+        return reject(param, 'FLAG_SHAPED', `Parameter ${param} must not look like a flag: ${raw}`);
+    }
+    if (hasControlCharacter(raw)) {
+        return reject(param, 'CONTROL_CHARACTER', `Parameter ${param} must not contain control characters.`);
+    }
+    return { ok: true, value: raw };
+}
+function checkToken(param, value) {
+    if (/\s/.test(value)) {
+        return reject(param, 'WHITESPACE', `Parameter ${param} must be a single token.`);
+    }
+    return { ok: true, value };
+}
+function checkSlug(param, value, spec) {
+    const asToken = checkToken(param, value);
+    if (!asToken.ok)
+        return asToken;
+    const pattern = new RegExp(spec.pattern ?? DEFAULT_SLUG_PATTERN);
+    if (!pattern.test(value)) {
+        return reject(param, 'PATTERN_MISMATCH', `Parameter ${param} must match ${pattern.source}: ${value}`);
+    }
+    return { ok: true, value };
+}
+function checkEnum(param, value, spec) {
+    if (spec.values === undefined || !spec.values.includes(value)) {
+        return reject(param, 'NOT_IN_ENUM', `Parameter ${param} must be one of: ${(spec.values ?? []).join(', ')}`);
+    }
+    return { ok: true, value };
+}
+function checkInteger(param, value, spec) {
+    if (!/^[0-9]+$/.test(value)) {
+        return reject(param, 'NOT_AN_INTEGER', `Parameter ${param} must be an integer: ${value}`);
+    }
+    const parsed = Number.parseInt(value, 10);
+    const min = spec.min ?? 0;
+    const max = spec.max ?? Number.MAX_SAFE_INTEGER;
+    if (parsed < min || parsed > max) {
+        return reject(param, 'OUT_OF_RANGE', `Parameter ${param} must be between ${min} and ${max}.`);
+    }
+    return { ok: true, value };
+}
+function checkPath(param, value) {
+    // Spaces are legal in a path and irrelevant under array passing; the absolute
+    // check is what keeps `--apply` and a bare word out.
+    if (!isAbsolute(value)) {
+        return reject(param, 'NOT_ABSOLUTE', `Parameter ${param} must be an absolute path.`);
+    }
+    return { ok: true, value };
+}
+const TYPE_CHECKS = {
+    token: (param, value) => checkToken(param, value),
+    slug: (param, value, spec) => checkSlug(param, value, spec),
+    enum: (param, value, spec) => checkEnum(param, value, spec),
+    integer: (param, value, spec) => checkInteger(param, value, spec),
+    path: (param, value) => checkPath(param, value)
+};
+/** Validate one placeholder value against its spec. */
+export function validatePlaceholderValue(param, spec, raw) {
+    const prechecked = precheckCommon(param, raw);
+    if (!prechecked.ok)
+        return prechecked;
+    return TYPE_CHECKS[spec.type](param, prechecked.value, spec);
+}
+function missingParam(param) {
+    return reject(param, 'EMPTY', `Parameter ${param} was not supplied.`);
+}
+/** A value is required for every placeholder present in the template. */
+function resolveParamValue(param, declared, values) {
+    if (declared === undefined)
+        return missingParam(param);
+    const supplied = values[param];
+    // Every placeholder in this surface is required (introspected), and a missing
+    // OPTIONAL value could only be honoured by also dropping the flag literal the
+    // loop has already pushed. Refusing is the honest answer.
+    if (supplied === undefined)
+        return missingParam(param);
+    return validatePlaceholderValue(param, declared, supplied);
+}
+function unknownParams(entry, values) {
+    for (const name of Object.keys(values)) {
+        if (!(name in entry.params)) {
+            return reject(name, 'NOT_A_STRING', `Entry ${entry.id} declares no parameter ${name}.`);
+        }
+    }
+    return undefined;
+}
+/**
+ * Render a whitelist entry into a concrete argv ARRAY.
+ *
+ * The output is never a string: literals and validated values are pushed as
+ * separate elements, so no value can contribute token boundaries. A parameter the
+ * entry does not declare is refused rather than appended.
+ */
+export function buildArgv(entry, values) {
+    const unexpected = unknownParams(entry, values);
+    if (unexpected !== undefined)
+        return unexpected;
+    const argv = [];
+    for (const segment of entry.argv) {
+        if (segment.kind === 'literal') {
+            argv.push(segment.value);
+            continue;
+        }
+        const resolved = resolveParamValue(segment.name, entry.params[segment.name], values);
+        if (!resolved.ok)
+            return resolved;
+        argv.push(resolved.value);
+    }
+    return { ok: true, argv };
+}

package/dist/services/readonly-surface/readonly-whitelist.d.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+/** Where the generator writes the artifact, relative to the package root. */
+export declare const READONLY_WHITELIST_RELATIVE_PATH = "contracts/readonly-argv-whitelist.json";
+declare const PlaceholderSpecSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        enum: "enum";
+        path: "path";
+        token: "token";
+        slug: "slug";
+        integer: "integer";
+    }>;
+    pattern: z.ZodOptional<z.ZodString>;
+    values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    default: z.ZodOptional<z.ZodNumber>;
+    binding: z.ZodObject<{
+        kind: z.ZodEnum<{
+            option: "option";
+            positional: "positional";
+        }>;
+        token: z.ZodString;
+        required: z.ZodBoolean;
+    }, z.core.$strip>;
+    constraintSource: z.ZodEnum<{
+        introspected: "introspected";
+        handwritten: "handwritten";
+    }>;
+}, z.core.$strip>;
+declare const EntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    tool: z.ZodString;
+    commandPath: z.ZodArray<z.ZodString>;
+    argv: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"literal">;
+        value: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"param">;
+        name: z.ZodString;
+    }, z.core.$strip>]>>;
+    params: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            enum: "enum";
+            path: "path";
+            token: "token";
+            slug: "slug";
+            integer: "integer";
+        }>;
+        pattern: z.ZodOptional<z.ZodString>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodNumber>;
+        binding: z.ZodObject<{
+            kind: z.ZodEnum<{
+                option: "option";
+                positional: "positional";
+            }>;
+            token: z.ZodString;
+            required: z.ZodBoolean;
+        }, z.core.$strip>;
+        constraintSource: z.ZodEnum<{
+            introspected: "introspected";
+            handwritten: "handwritten";
+        }>;
+    }, z.core.$strip>>;
+    introspection: z.ZodObject<{
+        optionTokens: z.ZodArray<z.ZodString>;
+        positionalCount: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+declare const WhitelistSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    source: z.ZodString;
+    readOnlyDefinition: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tool: z.ZodString;
+        commandPath: z.ZodArray<z.ZodString>;
+        argv: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"literal">;
+            value: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"param">;
+            name: z.ZodString;
+        }, z.core.$strip>]>>;
+        params: z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                enum: "enum";
+                path: "path";
+                token: "token";
+                slug: "slug";
+                integer: "integer";
+            }>;
+            pattern: z.ZodOptional<z.ZodString>;
+            values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            default: z.ZodOptional<z.ZodNumber>;
+            binding: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    option: "option";
+                    positional: "positional";
+                }>;
+                token: z.ZodString;
+                required: z.ZodBoolean;
+            }, z.core.$strip>;
+            constraintSource: z.ZodEnum<{
+                introspected: "introspected";
+                handwritten: "handwritten";
+            }>;
+        }, z.core.$strip>>;
+        introspection: z.ZodObject<{
+            optionTokens: z.ZodArray<z.ZodString>;
+            positionalCount: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PlaceholderSpec = z.infer<typeof PlaceholderSpecSchema>;
+export type ReadOnlyWhitelistEntry = z.infer<typeof EntrySchema>;
+export type ReadOnlyWhitelist = z.infer<typeof WhitelistSchema>;
+/** Absolute path of the generated artifact for a package root. */
+export declare function resolveReadOnlyWhitelistPath(root?: string): string;
+/** Parse + validate the artifact text. Throws a zod error when the shape drifts. */
+export declare function parseReadOnlyWhitelist(text: string): ReadOnlyWhitelist;
+/** Read + validate the artifact. The only supported way to obtain it. */
+export declare function loadReadOnlyWhitelist(root?: string): ReadOnlyWhitelist;
+/** The param names an entry expects, in argv order. */
+export declare function paramNamesOf(entry: ReadOnlyWhitelistEntry): string[];
+/**
+ * The tool names the surface declares, in first-appearance order.
+ *
+ * This is the pre-tool interceptor's view of "what may be called", and it is
+ * computed HERE rather than in the MCP module on purpose: the interceptor must
+ * keep working when `src/services/mcp/` is deleted (spec §1), so it cannot reach
+ * into it for the answer. Grouping the entries by their `tool` field is the whole
+ * computation, and both readers do it from the same DATA.
+ */
+export declare function toolIdsOf(whitelist: ReadOnlyWhitelist): string[];
+/**
+ * Match a CONCRETE argv against the entries. A param slot consumes exactly one
+ * token, so `--apply` in a param slot still MATCHES here - refusing it is the
+ * validator's job (`argv-guard.ts`), not the matcher's. Keeping the two separate
+ * is what stops a rejected value from silently re-routing to another entry.
+ */
+export declare function matchReadOnlyEntry(whitelist: ReadOnlyWhitelist, argv: readonly string[]): ReadOnlyWhitelistEntry | undefined;
+export {};

package/dist/services/readonly-surface/readonly-whitelist.js

@@ -0,0 +1,107 @@
+/**
+ * The read-only argv whitelist, as DATA.
+ *
+ * WHY THIS IS A LOADER AND NOT AN IMPORT. The generated whitelist is read by two
+ * consumers that must survive the removal of the MCP module (spec §1): the
+ * pre-tool interceptor and, later, the MCP server. If either `import`ed the
+ * generated artifact it would become a static edge between them, and deleting
+ * the MCP module would break the gate. So the artifact stays a `.json` file and
+ * every reader goes through the filesystem. `tests/unit/standards/no-mcp-source-import.test.ts`
+ * pins that no module may `import` it.
+ *
+ * The shape is `{ schemaVersion, source, readOnlyDefinition, entries[] }`. Each
+ * entry is a full argv template (flags included) plus typed placeholders - the
+ * key is the WHOLE argv, never the top-level verb, because each named command
+ * family mixes read and write subcommands.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { repoRoot } from 'peaks-loop-shared/paths';
+/** Where the generator writes the artifact, relative to the package root. */
+export const READONLY_WHITELIST_RELATIVE_PATH = 'contracts/readonly-argv-whitelist.json';
+const PlaceholderBindingSchema = z.object({
+    /** `option` when the value is the argument of a flag, `positional` otherwise. */
+    kind: z.enum(['option', 'positional']),
+    /** The flag token (`--role`) or the positional name (`request-id`). */
+    token: z.string().min(1),
+    required: z.boolean()
+});
+const PlaceholderSpecSchema = z.object({
+    type: z.enum(['slug', 'enum', 'token', 'integer', 'path']),
+    pattern: z.string().min(1).optional(),
+    values: z.array(z.string().min(1)).min(1).optional(),
+    min: z.number().int().optional(),
+    max: z.number().int().optional(),
+    default: z.number().int().optional(),
+    /**
+     * Where the placeholder lives and whether the REGISTRY makes it mandatory.
+     * A placeholder present in the template is always supplied a value; this
+     * field carries the introspected fact, not the template's demand.
+     */
+    binding: PlaceholderBindingSchema,
+    /** `introspected` when the registry supplied the constraint, else `handwritten`. */
+    constraintSource: z.enum(['introspected', 'handwritten'])
+});
+const ArgvSegmentSchema = z.union([
+    z.object({ kind: z.literal('literal'), value: z.string().min(1) }),
+    z.object({ kind: z.literal('param'), name: z.string().min(1) })
+]);
+const EntrySchema = z.object({
+    id: z.string().min(1),
+    tool: z.string().min(1),
+    commandPath: z.array(z.string().min(1)).min(1),
+    argv: z.array(ArgvSegmentSchema).min(1),
+    params: z.record(z.string(), PlaceholderSpecSchema),
+    introspection: z.object({
+        optionTokens: z.array(z.string().min(1)),
+        positionalCount: z.number().int().gte(0)
+    })
+});
+const WhitelistSchema = z.object({
+    schemaVersion: z.literal(1),
+    source: z.string().min(1),
+    readOnlyDefinition: z.string().min(1),
+    entries: z.array(EntrySchema).min(1)
+});
+/** Absolute path of the generated artifact for a package root. */
+export function resolveReadOnlyWhitelistPath(root = repoRoot) {
+    return join(root, READONLY_WHITELIST_RELATIVE_PATH);
+}
+/** Parse + validate the artifact text. Throws a zod error when the shape drifts. */
+export function parseReadOnlyWhitelist(text) {
+    return WhitelistSchema.parse(JSON.parse(text));
+}
+/** Read + validate the artifact. The only supported way to obtain it. */
+export function loadReadOnlyWhitelist(root = repoRoot) {
+    return parseReadOnlyWhitelist(readFileSync(resolveReadOnlyWhitelistPath(root), 'utf8'));
+}
+/** The param names an entry expects, in argv order. */
+export function paramNamesOf(entry) {
+    return entry.argv.flatMap((segment) => (segment.kind === 'param' ? [segment.name] : []));
+}
+/**
+ * The tool names the surface declares, in first-appearance order.
+ *
+ * This is the pre-tool interceptor's view of "what may be called", and it is
+ * computed HERE rather than in the MCP module on purpose: the interceptor must
+ * keep working when `src/services/mcp/` is deleted (spec §1), so it cannot reach
+ * into it for the answer. Grouping the entries by their `tool` field is the whole
+ * computation, and both readers do it from the same DATA.
+ */
+export function toolIdsOf(whitelist) {
+    return [...new Set(whitelist.entries.map((entry) => entry.tool))];
+}
+/**
+ * Match a CONCRETE argv against the entries. A param slot consumes exactly one
+ * token, so `--apply` in a param slot still MATCHES here - refusing it is the
+ * validator's job (`argv-guard.ts`), not the matcher's. Keeping the two separate
+ * is what stops a rejected value from silently re-routing to another entry.
+ */
+export function matchReadOnlyEntry(whitelist, argv) {
+    return whitelist.entries.find((entry) => {
+        if (entry.argv.length !== argv.length)
+            return false;
+        return entry.argv.every((segment, index) => segment.kind === 'literal' ? segment.value === argv[index] : true);
+    });
+}