@aletheia-works/vivarium-mcp 0.0.1

package/dist/tools/match_error.js

@@ -0,0 +1,282 @@
+// Phase 6 X.2 → Phase 7 A5 — match_error tool, v2.
+//
+// Server-side mirror of the docs-site error → recipe matcher
+// (Phase 6 S.2, ADR-0025). The scoring weights are bit-identical
+// with the docs-site `ErrorRecipeMatcher.tsx`:
+//   symptom segment match → +5
+//   tag segment match     → +3
+//   project / slug match  → +2
+// Recipes with score 0 are dropped. Ties broken by (layer asc, slug asc).
+//
+// Phase 7 A5 (ADR-0028) extends v1 with three accuracy improvements,
+// none of which change the weights above:
+//   1. Adjacent-pair token expansion — "data type" also tries `datatype`,
+//      so multi-word user input can hit single-word catalogue terms.
+//   2. Synonym groups — variants of the same concept (e.g. `dtype` ⇄
+//      `datatype`) all expand to the whole group.
+//   3. Bounded fuzzy match — tokens of length ≥ 6 within Levenshtein
+//      distance 1 score the same as exact, so "missmatch" still hits
+//      `mismatch`.
+//   4. Multi-language stopwords — German, Spanish, French, Chinese,
+//      Korean noise tokens drop alongside the existing English+Japanese.
+//
+// **CRITICAL: keep in sync with `docs/components/ErrorRecipeMatcher.tsx`.**
+// ADR-0025 §Neutral made the docs surface the canonical implementation;
+// X.2 lifted it server-side bit-identical, and A5 keeps both copies
+// updated atomically. Diverging the scoring between MCP and the docs
+// matcher would surface as agent-vs-UI disagreement on identical input.
+//
+// The matcher remains mechanical — no LLM, no semantic embeddings.
+// AGENTS.md §3.3's mechanical-over-judgement rule carries through.
+import { getCatalogue } from '../catalogue.js';
+const MAX_INPUT_BYTES = 16 * 1024;
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 50;
+// Multi-language stopword set (Phase 7 A5). The goal isn't full
+// lexical coverage of any single language — it's dropping the
+// frequent noise tokens that would never sit in a recipe overlay.
+// Anything that sneaks through scores 0 against the catalogue
+// anyway; the worst case is wasted comparison cycles, not wrong
+// matches.
+const STOPWORDS = new Set([
+    // English
+    'the', 'and', 'for', 'with', 'from', 'that', 'this', 'have',
+    'has', 'are', 'was', 'were', 'will', 'not', 'but', 'all',
+    'error', 'errors', 'exception', 'failed', 'failure', 'trace',
+    'traceback', 'stack', 'line', 'file', 'most', 'recent', 'call',
+    // Japanese
+    'です', 'ます', 'した', 'する', 'これ', 'それ', 'その', 'この',
+    'エラー', '例外', '失敗', 'スタック',
+    // German
+    'der', 'die', 'das', 'und', 'mit', 'von', 'für', 'fehler',
+    'ausnahme', 'aufgetreten',
+    // Spanish
+    'que', 'por', 'una', 'los', 'las', 'del', 'con',
+    'excepción', 'fallo',
+    // French
+    'pour', 'avec', 'sur', 'dans', 'erreur',
+    'échec',
+    // Chinese (Simplified + Traditional, common particles + error words)
+    '错误', '异常', '失败', '堆栈', '錯誤', '異常', '失敗', '堆疊',
+    // Korean (common particles + error words)
+    '오류', '예외', '실패', '스택',
+]);
+// Synonym groups (Phase 7 A5). Within a group, any token in the
+// user's input expands the input set to include all members.
+// Variants are stored hyphen-stripped (lowercase, alphanumeric)
+// to match the kebab-segmented catalogue tokens.
+//
+// Conservative on purpose — false-positive pressure rises with
+// table size. Add a group only when there's an unambiguous mapping
+// between a user-input shape and a catalogue overlay token.
+const SYNONYM_GROUPS = [
+    ['dtype', 'datatype'],
+    ['nullptr', 'nullpointer', 'nilptr', 'nullpointerexception'],
+    ['segfault', 'sigsegv', 'segmentation'],
+    ['flock', 'filelock'],
+    ['deadlock', 'deadblock'],
+    ['datarace', 'racecondition'],
+    ['exitcode', 'exitstatus', 'returncode'],
+    ['oom', 'outofmemory'],
+    ['encoding', 'utf'],
+    ['mismatch', 'mismatched'],
+];
+const SYNONYM_MAP = (() => {
+    const m = new Map();
+    for (const group of SYNONYM_GROUPS) {
+        for (const member of group) {
+            m.set(member, group.filter((g) => g !== member));
+        }
+    }
+    return m;
+})();
+// Phase 7 A5: bounded fuzzy match. Only fires for tokens of length
+// ≥ FUZZY_MIN_LEN; only Levenshtein distance ≤ 1 is accepted (single
+// insert / delete / substitute). Same weight as exact, but the
+// MatchedToken records `via: 'fuzzy'` for client-side rendering.
+const FUZZY_MIN_LEN = 6;
+function withinDistance1(a, b) {
+    if (a === b)
+        return true;
+    const lenA = a.length;
+    const lenB = b.length;
+    if (Math.abs(lenA - lenB) > 1)
+        return false;
+    if (lenA === lenB) {
+        let diffs = 0;
+        for (let i = 0; i < lenA; i++) {
+            if (a[i] !== b[i]) {
+                diffs++;
+                if (diffs > 1)
+                    return false;
+            }
+        }
+        return diffs === 1;
+    }
+    const shorter = lenA < lenB ? a : b;
+    const longer = lenA < lenB ? b : a;
+    let i = 0;
+    let j = 0;
+    let diffs = 0;
+    while (i < shorter.length && j < longer.length) {
+        if (shorter[i] !== longer[j]) {
+            diffs++;
+            if (diffs > 1)
+                return false;
+            j++;
+        }
+        else {
+            i++;
+            j++;
+        }
+    }
+    return true;
+}
+function tokenise(input) {
+    let trimmed = input;
+    if (trimmed.length > MAX_INPUT_BYTES) {
+        trimmed = trimmed.slice(trimmed.length - MAX_INPUT_BYTES);
+    }
+    const lower = trimmed.toLowerCase();
+    const raw = lower.split(/[^a-z0-9_]+/);
+    // Stage 1: filter raw tokens (length ≥ 3, not stopword, dedup).
+    const ordered = [];
+    const seenRaw = new Set();
+    for (const t of raw) {
+        if (t.length < 3)
+            continue;
+        if (STOPWORDS.has(t))
+            continue;
+        if (seenRaw.has(t))
+            continue;
+        seenRaw.add(t);
+        ordered.push(t);
+    }
+    // Stage 2: adjacent-pair expansion. Lets multi-word user input
+    // (e.g. "data type") match single-word catalogue terms (`dtype`)
+    // via the synonym table.
+    const direct = new Set(ordered);
+    for (let i = 0; i < ordered.length - 1; i++) {
+        direct.add(ordered[i] + ordered[i + 1]);
+    }
+    // Stage 3: synonym expansion. For each direct token, if it has a
+    // synonym group, add the other members and remember which input
+    // token brought them in.
+    const synonyms = new Map();
+    for (const t of direct) {
+        const partners = SYNONYM_MAP.get(t);
+        if (!partners)
+            continue;
+        for (const p of partners) {
+            if (direct.has(p) || synonyms.has(p))
+                continue;
+            synonyms.set(p, t);
+        }
+    }
+    // Stage 4: fuzzy candidate set — direct tokens (not synonym
+    // additions) of sufficient length.
+    const fuzzyCandidates = [];
+    for (const t of direct) {
+        if (t.length >= FUZZY_MIN_LEN)
+            fuzzyCandidates.push(t);
+    }
+    return { direct, synonyms, fuzzyCandidates };
+}
+function kebabSegments(value) {
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 3 && !STOPWORDS.has(t));
+}
+function matchSegment(seg, tokens) {
+    if (tokens.direct.has(seg))
+        return { matched: true };
+    const synonymInput = tokens.synonyms.get(seg);
+    if (synonymInput !== undefined) {
+        return { matched: true, via: 'synonym', input: synonymInput };
+    }
+    if (seg.length >= FUZZY_MIN_LEN) {
+        for (const candidate of tokens.fuzzyCandidates) {
+            if (withinDistance1(seg, candidate)) {
+                return { matched: true, via: 'fuzzy', input: candidate };
+            }
+        }
+    }
+    return { matched: false };
+}
+function scoreRecipe(recipe, tokens) {
+    const matched = [];
+    let score = 0;
+    const apply = (source, weight, seg) => {
+        const m = matchSegment(seg, tokens);
+        if (!m.matched)
+            return;
+        score += weight;
+        const entry = { source, token: seg };
+        if (m.via)
+            entry.via = m.via;
+        if (m.input !== undefined)
+            entry.input = m.input;
+        matched.push(entry);
+    };
+    if (recipe.symptom) {
+        for (const seg of kebabSegments(recipe.symptom))
+            apply('symptom', 5, seg);
+    }
+    for (const tag of recipe.tags ?? []) {
+        for (const seg of kebabSegments(tag))
+            apply('tags', 3, seg);
+    }
+    for (const seg of kebabSegments(recipe.project))
+        apply('project', 2, seg);
+    for (const seg of kebabSegments(recipe.slug))
+        apply('slug', 2, seg);
+    return { recipe, score, matched };
+}
+export async function matchError(args) {
+    const text = (args.text ?? '').trim();
+    if (!text) {
+        return { ok: false, error: 'missing required argument: text' };
+    }
+    const limit = Math.min(Math.max(1, args.limit ?? DEFAULT_LIMIT), MAX_LIMIT);
+    const tokens = tokenise(text);
+    const { recipes } = await getCatalogue();
+    const scored = recipes
+        .map((r) => scoreRecipe(r, tokens))
+        .filter((s) => s.score > 0);
+    scored.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        if (a.recipe.layer !== b.recipe.layer)
+            return a.recipe.layer - b.recipe.layer;
+        return a.recipe.slug.localeCompare(b.recipe.slug);
+    });
+    return {
+        ok: true,
+        query_token_count: tokens.direct.size,
+        total_recipes: recipes.length,
+        matches: scored.slice(0, limit),
+    };
+}
+export const MATCH_ERROR_TOOL = {
+    name: 'match_error',
+    description: "Find Vivarium recipes that match a pasted error message or stack trace by mechanical token overlap (no LLM). The text is tokenised, lowercase-compared against each recipe's symptom (weight 5 per segment), tags (3), project (2), and slug (2). v2 (Phase 7 A5) adds adjacent-pair tokens (so 'data type' can hit `dtype`), a small synonym table (e.g. dtype⇄datatype, segfault⇄sigsegv), and bounded Levenshtein-1 fuzzy matching for tokens of length ≥ 6. Stopword set covers English, Japanese, German, Spanish, French, Chinese, and Korean noise tokens. Recipes with score > 0 are returned in descending score order; ties broken by (layer asc, slug asc). Each matched token reports its `via` (`synonym` or `fuzzy` when non-exact) and the original `input` that triggered it, so agents can render the provenance. Pair with `get_recipe` to drill into a specific result, or `list_recipes` for unfiltered browsing.",
+    inputSchema: {
+        type: 'object',
+        properties: {
+            text: {
+                type: 'string',
+                description: 'Error message, stack trace, or any free-text fragment to match against the catalogue. Tokenised on non-alphanumeric runs after lowercasing; tokens shorter than 3 chars and a multi-language stopword list are dropped. Input longer than 16 KB is truncated from the front.',
+            },
+            limit: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 50,
+                default: 10,
+                description: 'Maximum number of matches to return. Defaults to 10; capped at 50.',
+            },
+        },
+        required: ['text'],
+    },
+};
+//# sourceMappingURL=match_error.js.map

package/dist/tools/match_error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match_error.js","sourceRoot":"","sources":["../../src/tools/match_error.ts"],"names":[],"mappings":"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"}

package/dist/tools/prepare_new_recipe.d.ts

@@ -0,0 +1,92 @@
+import type { Layer } from '../types.js';
+export interface PrepareNewRecipeArgs {
+    project?: string;
+    issue?: number;
+    title?: string;
+    base_image?: string;
+    repo_owner?: string;
+    layer?: Layer;
+}
+interface RecipeFacetsRow {
+    key: string;
+    value: {
+        language: string;
+        symptom: string;
+        severity: string;
+        tags: string[];
+    };
+}
+interface ProjectsRow {
+    key: string;
+    value: {
+        display_name: string;
+        tagline: string;
+        description: string;
+        homepage: string;
+        github: string;
+    };
+    note: string;
+}
+interface PrepareNewRecipeOk {
+    ok: true;
+    slug: string;
+    layer: Layer;
+    upstream_issue_url: string;
+    scaffold_command: string;
+    verify_command: string;
+    recipe_facets_row: RecipeFacetsRow;
+    projects_row: ProjectsRow;
+    commit_subject: string;
+    next_steps: string[];
+    references: {
+        rules: string;
+        layer_readme: string;
+        selection_policy: string;
+    };
+}
+interface PrepareNewRecipeError {
+    ok: false;
+    error: string;
+}
+export type PrepareNewRecipeResult = PrepareNewRecipeOk | PrepareNewRecipeError;
+export declare function prepareNewRecipe(args: PrepareNewRecipeArgs): Promise<PrepareNewRecipeResult>;
+export declare const PREPARE_NEW_RECIPE_TOOL: {
+    readonly name: "prepare_new_recipe";
+    readonly description: "Prepare everything an AI agent needs to author a new Vivarium recipe for a given upstream project + issue. SCAFFOLDING HELPER, not an execution engine — returns the exact `mise run recipes:new` and `mise run recipes:verify` commands the agent should run, plus placeholder rows for docs/data/recipe-facets.json and (if the project is new) docs/data/projects.json, plus a commit-subject template and a sequenced next-steps checklist. Validates the slug at call time against the same regex `docs/scripts/generate-recipes-index.ts` uses, so unparseable slugs are rejected before any work begins. Use this immediately after picking an issue from `gh search`; pair with `match_error` / `list_recipes` if you need to confirm no existing recipe already covers the bug.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly project: {
+                readonly type: "string";
+                readonly pattern: "^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$";
+                readonly description: "Upstream project name in kebab-case (e.g. 'node', 'cpython', 'typescript'). Must not contain trailing digits — those would confuse the slug parser.";
+            };
+            readonly issue: {
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly description: "Upstream issue number (positive integer, e.g. 63041 for nodejs/node#63041).";
+            };
+            readonly title: {
+                readonly type: "string";
+                readonly description: "One-line bug title (e.g. \"Intl.DateTimeFormat drops month with calendar:'iso8601'\"). Used in the scaffold command and as the recipe README's H1.";
+            };
+            readonly base_image: {
+                readonly type: "string";
+                readonly description: "Optional Docker base image for Layer 2 recipes (e.g. 'node:26-slim'). Forwarded to `mise run recipes:new -- ... --base <image>`. Layer 1 / 3 ignore this.";
+            };
+            readonly repo_owner: {
+                readonly type: "string";
+                readonly description: "Optional upstream owner/repo override (e.g. 'microsoft/TypeScript'). Defaults to a heuristic per project name: 'node' → 'nodejs/node', 'cpython' → 'python/cpython', etc. Only forward to the scaffold command when it differs from the heuristic.";
+            };
+            readonly layer: {
+                readonly type: "integer";
+                readonly enum: readonly [1, 2, 3];
+                readonly default: 2;
+                readonly description: "Vivarium layer: 1=WASM (in-browser), 2=Docker (default), 3=record-replay (rr). The commit scope, scaffold command, and next-steps tailor to the layer.";
+            };
+        };
+        readonly required: readonly ["project", "issue", "title"];
+    };
+};
+export {};
+//# sourceMappingURL=prepare_new_recipe.d.ts.map

package/dist/tools/prepare_new_recipe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare_new_recipe.d.ts","sourceRoot":"","sources":["../../src/tools/prepare_new_recipe.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,UAAU,eAAe;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE;QACL,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,CAAC;CACH;AAED,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,kBAAkB;IAC1B,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,eAAe,CAAC;IACnC,YAAY,EAAE,WAAW,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAED,UAAU,qBAAqB;IAC7B,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,sBAAsB,GAC9B,kBAAkB,GAClB,qBAAqB,CAAC;AAuC1B,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,sBAAsB,CAAC,CAoHjC;AAED,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4C1B,CAAC"}

package/dist/tools/prepare_new_recipe.js

@@ -0,0 +1,193 @@
+// prepare_new_recipe — given an upstream project + issue + title,
+// returns everything an AI agent (or human) needs to author a new
+// Vivarium recipe in a single step:
+//
+//   - validated slug (rejects values that the recipes-index parser
+//     in docs/scripts/generate-recipes-index.ts would not resolve)
+//   - the exact `mise run recipes:new -- ...` and
+//     `mise run recipes:verify -- ...` commands the agent should run
+//   - placeholder rows for docs/data/recipe-facets.json (always) and
+//     docs/data/projects.json (only when the project is new), with
+//     TODO markers for the human to fill in
+//   - a commit-subject template matching the `feat(layer<N>):` /
+//     `feat(wasm):` historical scope conventions
+//   - a sequenced next-steps checklist
+//
+// SCAFFOLDING HELPER, NOT an execution engine — same pattern as
+// verify_branch_fix. The MCP server returns the commands and
+// metadata; the agent's shell tool actually invokes mise.
+// Same regex as parseSlug() in docs/scripts/generate-recipes-index.ts.
+// Single-sourced as a literal here because the MCP package is published
+// independently and cannot import from docs/.
+const SLUG_REGEX = /^([a-z][a-z0-9]*(?:-[a-z][a-z0-9]*)*?)-(\d+)$/;
+// Default upstream owner/repo for common projects, mirroring the lookup
+// in docs/scripts/new-recipe.ts. Override via repo_owner.
+const DEFAULT_REPO = {
+    node: 'nodejs/node',
+    cpython: 'python/cpython',
+    typescript: 'microsoft/TypeScript',
+    rust: 'rust-lang/rust',
+    pandas: 'pandas-dev/pandas',
+    numpy: 'numpy/numpy',
+    php: 'php/php-src',
+    ruby: 'ruby/ruby',
+    regex: 'rust-lang/regex',
+};
+// Layer scope conventions: feat(wasm) for Layer 1, feat(layer2) for
+// Layer 2, feat(layer3) for Layer 3 — established by PRs #92/#94/#98/
+// #194 (Layer 2), #180/#189/#192 (Layer 1 = wasm), #106 (Layer 3).
+function commitScopeFor(layer) {
+    switch (layer) {
+        case 1:
+            return 'wasm';
+        case 2:
+            return 'layer2';
+        case 3:
+            return 'layer3';
+    }
+}
+function defaultRepoFor(project) {
+    return DEFAULT_REPO[project] ?? `${project}/${project}`;
+}
+export async function prepareNewRecipe(args) {
+    const project = (args.project ?? '').trim();
+    const issueNum = args.issue;
+    const title = (args.title ?? '').trim();
+    const layer = args.layer ?? 2;
+    if (!project)
+        return { ok: false, error: 'project is required' };
+    if (issueNum === undefined || issueNum === null)
+        return { ok: false, error: 'issue is required' };
+    if (!Number.isInteger(issueNum) || issueNum <= 0)
+        return { ok: false, error: `issue must be a positive integer (got ${issueNum})` };
+    if (!title)
+        return { ok: false, error: 'title is required' };
+    if (![1, 2, 3].includes(layer))
+        return { ok: false, error: `layer must be 1, 2, or 3 (got ${layer})` };
+    const slug = `${project}-${issueNum}`;
+    if (!SLUG_REGEX.test(slug)) {
+        return {
+            ok: false,
+            error: `generated slug "${slug}" is not parseable by ` +
+                `docs/scripts/generate-recipes-index.ts. project must be ` +
+                `kebab-case ([a-z][a-z0-9]*(-[a-z][a-z0-9]*)*) and contain no ` +
+                `trailing digits.`,
+        };
+    }
+    const ownerRepo = (args.repo_owner ?? defaultRepoFor(project)).trim();
+    const upstreamIssueUrl = `https://github.com/${ownerRepo}/issues/${issueNum}`;
+    // Layer 2 has the canonical scaffolder today (mise run recipes:new).
+    // Layer 1 / 3 scaffolders do not yet exist — for those, the agent
+    // copies from an existing recipe; we still return scaffolding intent.
+    const baseFlag = args.base_image
+        ? ` --base "${args.base_image}"`
+        : '';
+    const repoFlag = args.repo_owner && args.repo_owner !== defaultRepoFor(project)
+        ? ` --repo ${args.repo_owner}`
+        : '';
+    const scaffoldCommand = layer === 2
+        ? `mise run recipes:new -- ${project} ${issueNum} "${title}"${baseFlag}${repoFlag}`
+        : `# No scaffolder for Layer ${layer} yet — copy from an existing src/layer${layer}_*/ recipe and adapt.`;
+    const verifyCommand = layer === 2
+        ? `mise run recipes:verify -- ${slug}`
+        : `# No verifier for Layer ${layer} yet — see src/layer${layer}_*/README.md for per-layer validation.`;
+    const recipeFacetsRow = {
+        key: slug,
+        value: {
+            language: 'TODO-fill-in',
+            symptom: 'TODO-fill-in',
+            severity: 'TODO-fill-in',
+            tags: [],
+        },
+    };
+    const projectsRow = {
+        key: project,
+        value: {
+            display_name: project,
+            tagline: 'TODO-fill-in',
+            description: 'TODO-fill-in',
+            homepage: '',
+            github: `https://github.com/${ownerRepo}`,
+        },
+        note: `Only add this row to docs/data/projects.json if "${project}" is a new project (i.e. no existing recipe under src/layer*_*/${project}-*/).`,
+    };
+    const commitSubject = `feat(${commitScopeFor(layer)}): ${slug} reproduction (...)`;
+    const nextSteps = layer === 2
+        ? [
+            `Run: ${scaffoldCommand}`,
+            `Edit src/layer2_docker/${slug}/Dockerfile — set the real base image.`,
+            `Edit src/layer2_docker/${slug}/repro.sh — replace the TODO stub with the real probe.`,
+            `Edit src/layer2_docker/${slug}/README.md — fill in bug description, verdict contract, references.`,
+            `Edit src/layer2_docker/${slug}/index.html — fill in the lede.`,
+            `Add the recipe_facets_row to docs/data/recipe-facets.json with real values.`,
+            `If "${project}" is a new project, add the projects_row to docs/data/projects.json.`,
+            `Run: ${verifyCommand}  (this regenerates indices, runs lint, runs the docker build/run, and the rspress build).`,
+            `Commit with subject: ${commitSubject}`,
+            `Submit the PR.`,
+        ]
+        : [
+            `Copy from an existing recipe under src/layer${layer}_*/ — the canonical authoring reference.`,
+            `Add the recipe_facets_row to docs/data/recipe-facets.json with real values.`,
+            `If "${project}" is a new project, add the projects_row to docs/data/projects.json.`,
+            `Run: cd docs && mise exec -- bun run generate-index && mise exec -- bun run generate-project-pages`,
+            `Validate locally per the layer's README + the .claude/rules/recipe-authoring.md checklist.`,
+            `Commit with subject: ${commitSubject}`,
+            `Submit the PR.`,
+        ];
+    return {
+        ok: true,
+        slug,
+        layer,
+        upstream_issue_url: upstreamIssueUrl,
+        scaffold_command: scaffoldCommand,
+        verify_command: verifyCommand,
+        recipe_facets_row: recipeFacetsRow,
+        projects_row: projectsRow,
+        commit_subject: commitSubject,
+        next_steps: nextSteps,
+        references: {
+            rules: 'https://github.com/aletheia-works/vivarium/blob/main/.claude/rules/recipe-authoring.md',
+            layer_readme: `https://github.com/aletheia-works/vivarium/blob/main/src/layer${layer}_${layer === 1 ? 'wasm' : layer === 2 ? 'docker' : 'thirdway'}/README.md`,
+            selection_policy: 'https://github.com/aletheia-works/vivarium (issue selection policy is in _context/strategy/issue_selection_policy.md, gitignored)',
+        },
+    };
+}
+export const PREPARE_NEW_RECIPE_TOOL = {
+    name: 'prepare_new_recipe',
+    description: "Prepare everything an AI agent needs to author a new Vivarium recipe for a given upstream project + issue. SCAFFOLDING HELPER, not an execution engine — returns the exact `mise run recipes:new` and `mise run recipes:verify` commands the agent should run, plus placeholder rows for docs/data/recipe-facets.json and (if the project is new) docs/data/projects.json, plus a commit-subject template and a sequenced next-steps checklist. Validates the slug at call time against the same regex `docs/scripts/generate-recipes-index.ts` uses, so unparseable slugs are rejected before any work begins. Use this immediately after picking an issue from `gh search`; pair with `match_error` / `list_recipes` if you need to confirm no existing recipe already covers the bug.",
+    inputSchema: {
+        type: 'object',
+        properties: {
+            project: {
+                type: 'string',
+                pattern: '^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$',
+                description: "Upstream project name in kebab-case (e.g. 'node', 'cpython', 'typescript'). Must not contain trailing digits — those would confuse the slug parser.",
+            },
+            issue: {
+                type: 'integer',
+                minimum: 1,
+                description: 'Upstream issue number (positive integer, e.g. 63041 for nodejs/node#63041).',
+            },
+            title: {
+                type: 'string',
+                description: "One-line bug title (e.g. \"Intl.DateTimeFormat drops month with calendar:'iso8601'\"). Used in the scaffold command and as the recipe README's H1.",
+            },
+            base_image: {
+                type: 'string',
+                description: "Optional Docker base image for Layer 2 recipes (e.g. 'node:26-slim'). Forwarded to `mise run recipes:new -- ... --base <image>`. Layer 1 / 3 ignore this.",
+            },
+            repo_owner: {
+                type: 'string',
+                description: "Optional upstream owner/repo override (e.g. 'microsoft/TypeScript'). Defaults to a heuristic per project name: 'node' → 'nodejs/node', 'cpython' → 'python/cpython', etc. Only forward to the scaffold command when it differs from the heuristic.",
+            },
+            layer: {
+                type: 'integer',
+                enum: [1, 2, 3],
+                default: 2,
+                description: 'Vivarium layer: 1=WASM (in-browser), 2=Docker (default), 3=record-replay (rr). The commit scope, scaffold command, and next-steps tailor to the layer.',
+            },
+        },
+        required: ['project', 'issue', 'title'],
+    },
+};
+//# sourceMappingURL=prepare_new_recipe.js.map

package/dist/tools/prepare_new_recipe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare_new_recipe.js","sourceRoot":"","sources":["../../src/tools/prepare_new_recipe.ts"],"names":[],"mappings":"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"}

package/dist/tools/verify_branch_fix.d.ts

@@ -0,0 +1,49 @@
+import type { Layer } from '../types.js';
+export interface VerifyBranchFixArgs {
+    slug: string;
+    fix_url?: string;
+    fix_source?: string;
+}
+interface VerifyBranchFixOk {
+    ok: true;
+    slug: string;
+    layer: Layer;
+    path: 'A' | 'B';
+    page_url: string;
+    compare_url: string;
+    gh_command?: string;
+    instructions: string;
+    notes: string[];
+}
+interface VerifyBranchFixError {
+    ok: false;
+    error: string;
+}
+export type VerifyBranchFixResult = VerifyBranchFixOk | VerifyBranchFixError;
+export declare function verifyBranchFix(args: VerifyBranchFixArgs): Promise<VerifyBranchFixResult>;
+export declare const VERIFY_BRANCH_FIX_TOOL: {
+    readonly name: "verify_branch_fix";
+    readonly description: "Generate a deep-link URL and instructions for verifying a candidate branch-fix against a Vivarium recipe. SCAFFOLDING HELPER, not an execution engine — actual reproduction runs in the visitor's browser (Layer 1) or in GitHub Actions (Layer 2/3). Layer dispatch is automatic from the recipe's catalogue layer. Layer 1 returns Path A: a recipe-page URL with the fix pre-loaded via `?fix_url=` or `?fix=<base64url>`. Layer 2/3 returns Path B: a `/repro/compare` URL plus the `gh workflow run branch-fix-verdict.yml` command the contributor runs to capture a verdict against their pushed Docker image. Use after `match_error` or `list_recipes` has narrowed to a specific slug. Pair with the D-5 walkthrough page (https://aletheia-works.github.io/vivarium/guide/compare-branch-fix) for the full AI-slop verification loop.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly slug: {
+                readonly type: "string";
+                readonly pattern: "^[a-z0-9]+(-[a-z0-9]+)*$";
+                readonly description: "Kebab-case recipe slug (e.g. 'php-12167', 'bash-local-shadows-exit'). Same convention as Manifest v1's `slug`.";
+            };
+            readonly fix_url: {
+                readonly type: "string";
+                readonly description: "Public URL of the candidate fix source (raw.githubusercontent.com / gist.githubusercontent.com). Layer 1 only — embedded in the returned compare_url as `?fix_url=`. Mutually exclusive with fix_source.";
+            };
+            readonly fix_source: {
+                readonly type: "string";
+                readonly maxLength: number;
+                readonly description: "Inline candidate fix source (max 4096 bytes). Layer 1 only — embedded in the returned compare_url as `?fix=<base64url>`. Mutually exclusive with fix_url. Long fixes should use fix_url instead.";
+            };
+        };
+        readonly required: readonly ["slug"];
+    };
+};
+export {};
+//# sourceMappingURL=verify_branch_fix.d.ts.map

package/dist/tools/verify_branch_fix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_branch_fix.d.ts","sourceRoot":"","sources":["../../src/tools/verify_branch_fix.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,KAAK,EAAe,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,iBAAiB;IACzB,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,GAAG,GAAG,GAAG,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,UAAU,oBAAoB;IAC5B,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;AA6H7E,wBAAsB,eAAe,CACnC,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,qBAAqB,CAAC,CAyFhC;AAED,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;CA2BzB,CAAC"}