octwin-cli 0.8.16 → 0.9.0

package/dist/lib/base.js

@@ -0,0 +1,85 @@
+/**
+ * `.octwin-base.json` — what this pack folder was made from: the pack, version and content hash of its
+ * last `octwin pull` or successful `octwin deploy`, plus one hash per file.
+ *
+ * Two writers publish the same pack: this CLI and Tavi (Build with AI) in the console. Until 0.8.17 a
+ * deploy said nothing about the copy it was made from, so an old copy on disk silently replaced what Tavi
+ * had just published. Now `deploy` sends the base and the platform refuses (`live_moved`) when the live
+ * content is not the base's — the platform's half is `deployVerdict` (`provisioning/deploy-base.ts`).
+ *
+ * The per-file hashes are for `pull`: a file that still matches the base is the old version and safe to
+ * replace; a file that does not is the author's own edit, and `pull` stops rather than lose it
+ * (`planPull`). Tracked in git like the rest of the pack — a fresh clone keeps its base. Never deployed:
+ * a dot-file is not pack content (`classifyPackPath`).
+ *
+ * Pure apart from `readBase` / `writeBase`, so every rule is tested without a network.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const BASE_FILE = '.octwin-base.json';
+/**
+ * The hash of one file. Text is hashed with CRLF read as LF: git on Windows rewrites line endings on
+ * checkout, and a base that called every file "edited" after a clone would make `pull` useless there.
+ */
+export function fileHash(kind, body) {
+    const bytes = kind === 'text' ? Buffer.from(body.replace(/\r\n/g, '\n'), 'utf8') : Buffer.from(body, 'base64');
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/** One hash per file of a bundle — text files as UTF-8, blobs as base64 (the shape deploy and pull carry). */
+export function hashBundle(files, blobs) {
+    const out = {};
+    for (const [rel, body] of Object.entries(files))
+        out[rel] = fileHash('text', body);
+    for (const [rel, b64] of Object.entries(blobs))
+        out[rel] = fileHash('blob', b64);
+    return out;
+}
+/** The folder's base, or null when it has none — or one this CLI cannot read, which says nothing either. */
+export function readBase(dir) {
+    const p = join(dir, BASE_FILE);
+    if (!existsSync(p))
+        return null;
+    try {
+        const b = JSON.parse(readFileSync(p, 'utf8'));
+        if (typeof b.pack_id !== 'string' || typeof b.version !== 'string' || typeof b.content_sha !== 'string')
+            return null;
+        const files = b.files && typeof b.files === 'object' && !Array.isArray(b.files) ? b.files : {};
+        return { pack_id: b.pack_id, version: b.version, content_sha: b.content_sha, files };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeBase(dir, base) {
+    const files = Object.fromEntries(Object.entries(base.files).sort(([a], [b]) => a.localeCompare(b)));
+    writeFileSync(join(dir, BASE_FILE), JSON.stringify({ ...base, files }, null, 2) + '\n', 'utf8');
+}
+/** What a deploy sends as `base` — the three facts the platform compares, never the file list. */
+export function deployBaseOf(base) {
+    return base ? { pack_id: base.pack_id, version: base.version, content_sha: base.content_sha } : null;
+}
+/**
+ * What a pull into a folder would do. `local` and `incoming` are path → `fileHash`.
+ *
+ *   • `atRisk` — files the pull would overwrite or delete that hold work the base does not: changed or
+ *     added since the last pull/deploy. With no base nothing can be told apart, so every local file that
+ *     differs from the incoming one is at risk. A file already equal to the incoming one never is.
+ *   • `remove` — local files the incoming version no longer has (the live version deleted them).
+ *
+ * The caller refuses when `atRisk` is not empty, unless `--force`.
+ */
+export function planPull(args) {
+    const { local, incoming, base } = args;
+    const atRisk = [];
+    const remove = [];
+    for (const [rel, hash] of Object.entries(local)) {
+        if (incoming[rel] === hash)
+            continue;
+        if (!(base && base.files[rel] === hash))
+            atRisk.push(rel);
+        if (!(rel in incoming))
+            remove.push(rel);
+    }
+    return { atRisk: atRisk.sort(), remove: remove.sort() };
+}

package/dist/lib/init-id.js

@@ -0,0 +1,13 @@
+/**
+ * The pack id `octwin init <dir>` derives when no `--id` is given.
+ *
+ * It is the target directory's OWN name — its last path segment — lowercased, every run of
+ * characters outside `[a-z0-9-]` one hyphen, edges trimmed. Until 2026-10-11 it stripped the slashes
+ * out of the WHOLE path instead, so `./clinic` became `-clinic` (refused) and `packs/clinic` became
+ * `packsclinic`. The result still passes `describePackNameProblem` in `cmdInit`, which names the fix
+ * (`--id`) when a directory's name cannot be a pack id.
+ */
+import { basename, resolve } from 'node:path';
+export function packIdFromDir(target) {
+    return basename(resolve(target)).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+}

package/dist/lib/journey-check.js

@@ -0,0 +1,119 @@
+/**
+ * Offline journey-id check — every LITERAL id a flow names in `track:` or `do: track_event` must be
+ * declared by one of the pack's own `journeys/*.journey.yaml`.
+ *
+ * WHY it matters: a journey id resolves at RUNTIME, against the pack's journey indexes. A `track:`
+ * naming one nothing declares throws mid-conversation (the customer gets the flow's generic failure
+ * copy, the real reason is only in `octwin logs`), and `do: track_event` takes its `failed` port on
+ * every run, so the funnel silently records nothing. A September field report shipped four dead
+ * `track:` call sites across three flows in a pack with no `journeys/` at all, and the offline check
+ * passed it — the platform's `undeclared-journey-reference` rule caught it only on `--remote`.
+ *
+ * The ids are the pack's own, so this check needs NO pulled KB and always runs: the declared set is
+ * read from the same bundle, the way the platform reads it (`journeys/<id>.journey.yaml`, top level
+ * of the folder only). Stage and goal ids are `id:`, event ids `name:`; `key:` is the accepted
+ * synonym for either. A pack with no `journeys/` declares an EMPTY set, so every literal id it names
+ * is reported — that is the case this check exists for.
+ *
+ * Each key resolves against its OWN index, as on the platform: `event` against events,
+ * `stage_enter` against stages, `goal_reached` against goals. A stage id does not satisfy `event:`.
+ *
+ * WHAT IT DOES NOT CHECK — stated because a check that hides its edges gets trusted past them:
+ *   • An EXPRESSION id (`'$state.x'`, `'{$…}'`) — it names nothing this check could look up. On a
+ *     `track:` node that is a defect of its own (the node reads the id as written), which the
+ *     platform's `track-id-not-literal` reports; on `track_event` it is legal.
+ *   • Anything inside a `use:` template body — the platform expands those; `--remote` covers it.
+ *   • Whether a journey file is itself valid — the declaration check and `--remote` own that.
+ */
+/** `journeys/<id>.journey.yaml`, top level of the folder only — the platform loader's own rule. */
+const JOURNEY_FILE = /^journeys\/[^/]+\.journey\.yaml$/;
+/** Flow files — everything the platform loads as a flow lives under `flows/`. */
+const FLOW_FILE = /^flows\/.+\.ya?ml$/i;
+const norm = (p) => p.replace(/\\/g, '/');
+export const isJourneyFile = (p) => JOURNEY_FILE.test(norm(p));
+export const isFlowFile = (p) => FLOW_FILE.test(norm(p));
+const isBag = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/** A runtime-resolved value; nothing static to check. Same predicate as the platform rule. */
+const isExpr = (v) => v.trimStart().startsWith('$') || v.includes('{$');
+/** Collect every declared id from the pack's parsed files (non-journey files are ignored). */
+export function collectJourneyIds(docs) {
+    const ids = { events: new Set(), stages: new Set(), goals: new Set(), any: false };
+    const idOf = (row, field) => {
+        if (!isBag(row))
+            return null;
+        const v = row[field] ?? row['key'];
+        return typeof v === 'string' && v !== '' ? v : null;
+    };
+    for (const [file, doc] of docs) {
+        if (!isJourneyFile(file))
+            continue;
+        ids.any = true;
+        if (!isBag(doc))
+            continue;
+        const list = (k) => (Array.isArray(doc[k]) ? doc[k] : []);
+        for (const s of list('stages')) {
+            const id = idOf(s, 'id');
+            if (id)
+                ids.stages.add(id);
+        }
+        for (const g of list('goals')) {
+            const id = idOf(g, 'id');
+            if (id)
+                ids.goals.add(id);
+        }
+        for (const e of list('events')) {
+            const id = idOf(e, 'name');
+            if (id)
+                ids.events.add(id);
+        }
+    }
+    return ids;
+}
+/** Walk one parsed flow file and report every literal journey id the pack does not declare. */
+export function findJourneyViolations(doc, file, ids) {
+    const findings = [];
+    const KEYS = [
+        ['event', ids.events],
+        ['stage_enter', ids.stages],
+        ['goal_reached', ids.goals],
+    ];
+    const check = (bag, at, via) => {
+        for (const [key, declared] of KEYS) {
+            const id = bag[key];
+            if (typeof id !== 'string' || id === '' || isExpr(id) || declared.has(id))
+                continue;
+            findings.push({
+                file, path: [...at, key], via, key, id,
+                declared: [...declared].sort(), noJourneys: !ids.any,
+            });
+        }
+    };
+    const walk = (node, path) => {
+        if (Array.isArray(node)) {
+            node.forEach((v, i) => walk(v, [...path, i]));
+            return;
+        }
+        if (!isBag(node))
+            return;
+        if (isBag(node['track']))
+            check(node['track'], [...path, 'track'], 'track');
+        if (node['do'] === 'track_event' && isBag(node['args']))
+            check(node['args'], [...path, 'args'], 'track_event');
+        for (const [k, v] of Object.entries(node))
+            walk(v, [...path, k]);
+    };
+    walk(doc, []);
+    return findings;
+}
+const WHAT = { event: 'event', stage_enter: 'stage', goal_reached: 'goal' };
+/** One-line human message per finding — the platform rule's wording, with the file and line. */
+export function describeJourneyFinding(f) {
+    const at = f.line != null ? `:${f.line}` : (f.path.length ? ` (${f.path.join('.')})` : '');
+    const label = f.via === 'track' ? `track.${f.key}` : `track_event args.${f.key}`;
+    const tail = f.noJourneys
+        ? ` — this pack ships no journeys/, so ${f.via === 'track' ? 'every track: in it fails at runtime' : 'this call takes its `failed` port on every run'}`
+        : f.declared.length
+            ? ` (declared: ${f.declared.join(', ')})`
+            : ` (no journey declares any ${WHAT[f.key]})`;
+    return `${f.file}${at}: ${label}: ${WHAT[f.key]} '${f.id}' is declared in no journey${tail}`;
+}

package/dist/lib/kb-index.js

@@ -5,7 +5,8 @@
  * the pack being authored, so the pull ships navigation instead:
  *
  *   INDEX.md    — the corpus: which docs exist, which FAMILY each belongs to,
- *                 how big it is, and the order to read the first six.
+ *                 how big it is, the order to read the first few, which guide
+ *                 to add per capability, the recipes, and every symptom row.
  *   SYMBOLS.md  — a NAME → the file that defines it (see `kb-symbols.ts`).
  *   OUTLINE.md  — every doc's headings WITH line numbers, so a heavy doc is read
  *                 from the right offset instead of end to end.
@@ -55,27 +56,129 @@ export function kbOneLiner(text, max = 160) {
     const line = end >= 40 ? flat.slice(0, end) : flat;
     return line.length > max ? line.slice(0, max - 1).trimEnd() + '…' : line;
 }
+/**
+ * The size at which a doc is "heavy — search it" in INDEX.md. Also the line a CRAFT guide may not
+ * cross without a named reason (`content/kb/validate.ts` §2c) — one number, so the label an author
+ * reads and the gate the KB is held to cannot disagree.
+ */
+export const HEAVY_BYTES = 30 * 1024;
 /**
  * What one doc costs to open.
  *
  * DERIVED from the published byte count, never declared. `craft-capabilities`
  * used to carry this as a hand-typed table of four doc names, which is a fact
- * stated twice — and the corpus is lopsided enough (3.7 KB to 71 KB) that
- * getting it wrong costs an agent a five-figure token read on a hunch.
+ * stated twice — and the corpus is lopsided enough that getting it wrong costs
+ * an agent a five-figure token read on a hunch.
  */
 export function kbWeight(bytes) {
     if (!bytes)
         return { label: '', kb: '' };
     const kb = `${Math.round(bytes / 1024)} KB`;
-    if (bytes >= 30 * 1024)
+    if (bytes >= HEAVY_BYTES)
         return { label: 'heavy — search it', kb };
     if (bytes >= 12 * 1024)
         return { label: 'a sitting', kb };
     return { label: 'one read', kb };
 }
+/** A table cell holds no raw `|`, and no line break. */
+export const kbEscapePipes = (s) => s.replace(/(?<!\\)\|/g, '\\|');
+const cellText = (s) => kbEscapePipes(s.replace(/\s+/g, ' ').trim());
+/**
+ * The words that name one section of a doc: `§3` for a numbered heading (`## 3. …`, `## §3 …`,
+ * `## 3b. …`, `## 2.5 …`), the heading itself otherwise. An anchor the outline does not carry prints
+ * as itself — `content:check` refuses one, so that only happens against a hand-built index.
+ */
+export function kbSectionLabel(doc, anchor) {
+    const s = doc.sections?.find(x => x.anchor === anchor);
+    if (!s)
+        return `#${anchor}`;
+    const n = /^§?\s?(\d+(?:\.\d+)?[a-z]?)[.:]?\s/.exec(s.title);
+    return n ? `§${n[1]}` : s.title;
+}
+/**
+ * A section's heading WITHOUT its number — `4. Many — what the customer sees` → `Many — what the customer
+ * sees`. For a committed page that check:kb-examples scans: a `§4` printed right after a symptom that
+ * says "button label" reads, to its cap rule, as a 4-character button cap.
+ */
+export function kbSectionTitle(doc, anchor) {
+    const s = doc.sections?.find(x => x.anchor === anchor);
+    return s ? s.title.replace(/^§?\s?\d+(?:\.\d+)?[a-z]?[.:]?\s+/, '') : `#${anchor}`;
+}
+/** `§3` follows the guide's name directly; a heading title is set off with `›`. */
+export const kbSectionSuffix = (doc, anchor) => {
+    if (!anchor)
+        return '';
+    const label = kbSectionLabel(doc, anchor);
+    return label.startsWith('§') ? ` ${label}` : ` › ${label}`;
+};
+/** The reading route every author takes first, in `read_order`. */
+export function renderReadingRoute(docs, cell, opts = {}) {
+    return docs
+        .filter(d => d.read_order != null)
+        .sort((a, b) => a.read_order - b.read_order)
+        .map(d => {
+        const w = kbWeight(d.bytes);
+        return `${d.read_order}. ${cell(d)}${opts.sizes && w.kb ? ` *(${w.kb})*` : ''} — ${kbOneLiner(d.summary, 150)}`;
+    });
+}
+/** "The business… → also read", one row per declared route, in index order. Empty when no doc declares one. */
+export function renderCapabilityRoutes(docs, cell) {
+    const rows = docs.flatMap(d => (d.routes ?? []).map(r => ({ d, r })));
+    if (!rows.length)
+        return [];
+    return [
+        '| The business… | Also read |',
+        '|---|---|',
+        ...rows.map(({ d, r }) => `| ${cellText(r.when)} | ${cell(d, r.anchor, r.note ? cellText(r.note) : undefined)} |`),
+    ];
+}
+/** Every module recipe with its id. Empty when no doc carries one. */
+export function renderRecipes(docs, cell) {
+    const rows = docs.flatMap(d => (d.recipes ?? []).map(r => ({ d, r })));
+    if (!rows.length)
+        return [];
+    return [
+        '| Capability | Recipe | Id |',
+        '|---|---|---|',
+        ...rows.map(({ d, r }) => `| ${cellText(r.module)} | ${cell(d, r.anchor)} | \`guide:${d.key}#${r.anchor}\` |`),
+    ];
+}
+/** Every guide's symptom rows, gathered: what you see → the guide, the section, and why. */
+export function renderSymptoms(docs, cell) {
+    const rows = docs.flatMap(d => (d.symptoms ?? []).map(s => ({ d, s })));
+    if (!rows.length)
+        return [];
+    return [
+        '| What you\'re seeing | Read |',
+        '|---|---|',
+        ...rows.map(({ d, s }) => `| ${cellText(s.text)} | ${cell(d, s.anchor, s.why ? cellText(s.why) : undefined)} |`),
+    ];
+}
+/** INDEX.md's cell: the pulled file, for a section the line to read it from, then the note. */
+const indexCell = (d, anchor, note) => {
+    const line = anchor ? d.sections?.find(s => s.anchor === anchor)?.line : undefined;
+    return `\`${d.key}.md\`${kbEscapePipes(kbSectionSuffix(d, anchor))}${line ? ` (line ${line})` : ''}${note ? ` — ${note}` : ''}`;
+};
+/**
+ * One row per doc: its title, its one-line summary, and the view's cell for the file — plus its size
+ * and class when `sizes` is set. Sizes are INDEX.md's alone: a committed page that printed them would
+ * be rewritten by every edit to any other doc.
+ */
+export function renderKbDocTable(rows, cell, opts = {}) {
+    return [
+        opts.sizes ? '| Doc | Read it for | File | Size |' : '| Doc | Read it for | File |',
+        opts.sizes ? '|---|---|---|---|' : '|---|---|---|',
+        ...rows.map(d => {
+            const w = kbWeight(d.bytes);
+            const size = opts.sizes ? ` ${w.kb ? `${w.kb} · ${w.label}` : ''} |` : '';
+            return `| ${d.title ?? d.key} | ${kbOneLiner(d.summary).replace(/\|/g, '\\|')} | ${cell(d)} |${size}`;
+        }),
+    ];
+}
 /** Display order of the doc families: the authoring on-ramp first, grammar last. */
 const GROUP_ORDER = ['craft', 'module-guide', 'reference'];
-const GROUP_HEADING = {
+/** Each family's heading and one-paragraph blurb — INDEX.md's, and `craft-capabilities`' generated doc list. */
+export const KB_GROUP_HEADING = {
     craft: {
         title: 'Craft guides — how to build WELL',
         blurb: 'Author altitude, opinionated, and where the traps are. Each is small enough to read whole. '
@@ -118,28 +221,49 @@ export function buildKbIndexMarkdown(bundle, catalogEntryCounts) {
     L.push('| a heavy doc and one subject inside it | **`OUTLINE.md`** — every heading with its line number; read from there |');
     L.push('');
     // The reading route, straight from the index — no second hand-maintained copy.
-    const route = docs.filter(d => d.read_order != null).sort((a, b) => a.read_order - b.read_order);
+    const route = renderReadingRoute(docs, indexCell, { sizes: true });
     if (route.length) {
         L.push('## Read in this order');
         L.push('');
         L.push('Before authoring anything. Everything else is reached on demand.');
         L.push('');
-        for (const d of route) {
-            const w = kbWeight(d.bytes);
-            L.push(`${d.read_order}. \`${d.key}.md\`${w.kb ? ` *(${w.kb})*` : ''} — ${kbOneLiner(d.summary, 150)}`);
-        }
+        L.push(...route);
+        L.push('');
+    }
+    // The three routing tables — each printed only when the platform publishes its field, so an older
+    // platform's index prints none of them rather than an empty table.
+    const perCapability = renderCapabilityRoutes(docs, indexCell);
+    if (perCapability.length) {
+        L.push('## Add per capability');
+        L.push('');
+        L.push('Then add only the guides for what the business actually does — a section, where one is named:');
+        L.push('');
+        L.push(...perCapability);
+        L.push('');
+    }
+    const recipes = renderRecipes(docs, indexCell);
+    if (recipes.length) {
+        L.push('## Start from a recipe');
+        L.push('');
+        L.push('A recipe is a section of its guide that builds one capability end to end: its ingredients, a');
+        L.push('starter to copy, the rules, and the scenarios to test it with. Where one exists, start there.');
+        L.push('');
+        L.push(...recipes);
+        L.push('');
+    }
+    const symptoms = renderSymptoms(docs, indexCell);
+    if (symptoms.length) {
+        L.push('## When something is already wrong');
+        L.push('');
+        L.push('Every guide\'s `## Symptoms` rows, gathered. Find what you are seeing, then read that section.');
+        L.push('');
+        L.push(...symptoms);
         L.push('');
     }
     L.push('## Guides & reference docs');
     L.push('');
     const renderDocTable = (rows) => {
-        L.push('| Doc | Read it for | File | Size |');
-        L.push('|---|---|---|---|');
-        for (const d of rows) {
-            const w = kbWeight(d.bytes);
-            const size = w.kb ? `${w.kb} · ${w.label}` : '';
-            L.push(`| ${d.title ?? d.key} | ${kbOneLiner(d.summary).replace(/\|/g, '\\|')} | \`${d.key}.md\` | ${size} |`);
-        }
+        L.push(...renderKbDocTable(rows, indexCell, { sizes: true }));
         L.push('');
     };
     if (grouped) {
@@ -147,7 +271,7 @@ export function buildKbIndexMarkdown(bundle, catalogEntryCounts) {
             const rows = docs.filter(d => d.group === g);
             if (!rows.length)
                 continue;
-            const h = GROUP_HEADING[g];
+            const h = KB_GROUP_HEADING[g];
             L.push(`### ${h.title}`);
             L.push('');
             L.push(h.blurb);

package/dist/lib/recipe.js

@@ -0,0 +1,190 @@
+/**
+ * `octwin recipe <module>` — write a KB recipe's starter files into a pack, from the pulled KB.
+ *
+ * A recipe is a `## <Module> recipe` section of a craft guide whose `### <Module> starter` carries
+ * whole files, each a ```yaml fence whose first line is `# starter: <kind> — <path>` (the same
+ * contract the platform's `content/kb/recipes.test.ts` holds every starter to, as one pack on the
+ * `octwin init` starter). Reading them from the PULLED guide is the point: there is no second copy of
+ * a recipe to drift — hand-kept `--template` folders would have been one per recipe.
+ *
+ * Nothing is overwritten. A flow, a flow's locale file or a declaration the pack does not have yet is
+ * written; one it already has is left alone — a declaration's part is printed for the author to merge
+ * (an `xrm.yaml` already holds their entities), and a file the recipe would replace is named. A
+ * `manifest` starter is printed as the lines to add, and so are the new flows for `flows:` and the
+ * agent's `tools:`.
+ *
+ * Platform-free like every file here: the parse is a fence regex, not the platform's outline reader.
+ *
+ * A recipe can NEED another: the booking starter's "no free slot" button opens `reception`, which the
+ * handoff recipe ships, whose own buttons open casework's `ticket`. `recipeNeeds` derives that from the
+ * recipe's files — never a hand-kept list — so `octwin recipe` can say it before the author meets the
+ * chain one validate error at a time (2026-10-12: an author adding only `booking` hit three in a row).
+ */
+import { parse as parseYaml } from 'yaml';
+import { collectJourneyIds, findJourneyViolations, isJourneyFile } from './journey-check.js';
+/** Every recipe the pulled index names, module → the guide that carries it. */
+export function recipeModules(index) {
+    const out = new Map();
+    for (const e of index)
+        for (const r of e.recipes ?? [])
+            if (!out.has(r.module))
+                out.set(r.module, e.key);
+    return out;
+}
+const STARTER_FENCE = /```yaml\n# starter: (\S+)(?: — ([^\n]+))?\n([\s\S]*?)```/g;
+/**
+ * The starters under `## <Module> recipe` in a guide (up to the next H2), or `null` when the guide
+ * has no such section. `module` is the recipe's module word (`booking`, `reschedule`), matched without
+ * regard to case.
+ */
+export function recipeStarters(markdown, module) {
+    const text = markdown.replace(/\r\n/g, '\n');
+    const heading = new RegExp(`^## ${module.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')} recipe\\s*$`, 'im');
+    const m = heading.exec(text);
+    if (!m)
+        return null;
+    const from = m.index + m[0].length;
+    const next = text.slice(from).search(/^## /m);
+    const section = next < 0 ? text.slice(from) : text.slice(from, from + next);
+    const out = [];
+    for (const f of section.matchAll(STARTER_FENCE)) {
+        const rest = (f[2] ?? '').trim();
+        const paren = rest.indexOf(' (');
+        out.push({
+            kind: f[1],
+            path: (paren < 0 ? rest : rest.slice(0, paren)).trim(),
+            note: paren < 0 ? null : rest.slice(paren + 2).replace(/\)\s*$/, '').trim() || null,
+            body: f[3],
+        });
+    }
+    return out;
+}
+/** A flow's id from its path — `flows/tools/book.flow.yaml` → `book`. */
+const flowIdOf = (path) => path.split('/').pop().replace(/\.flow\.yaml$/, '');
+/**
+ * Decide what each starter does to the pack at `exists`'s answers. A pack-level locale file carries
+ * the PACK's id as its `pack_id` — the recipe's own (`homefix`) would namespace its labels under a
+ * pack that is not this one, and `$enum_label` would find none of them.
+ */
+export function planRecipe(starters, exists, packId) {
+    const actions = [];
+    const flows = [];
+    for (const s of starters) {
+        if (s.kind === 'manifest') {
+            actions.push({ act: 'manifest', body: s.body });
+            continue;
+        }
+        const body = s.kind === 'pack-locale' ? s.body.replace(/^pack_id:.*$/m, `pack_id: ${packId}`) : s.body;
+        if (s.kind === 'flow')
+            flows.push(flowIdOf(s.path));
+        if (!exists(s.path))
+            actions.push({ act: 'write', path: s.path, body });
+        else if (s.kind === 'flow' || s.kind === 'locale')
+            actions.push({ act: 'exists', path: s.path });
+        else
+            actions.push({ act: 'merge', path: s.path, note: s.note, body });
+    }
+    return { actions, flows };
+}
+const isExprId = (v) => v.startsWith('$') || v.includes('{$');
+/**
+ * A tap target the PLATFORM answers, not a pack flow — `_platform.handoff_cancel` today. The prefix is
+ * reserved (no pack flow id can carry it), so it opens nothing a recipe could ship. The platform's
+ * constant is `HANDOFF_CANCEL_TAP_TARGET`; `content/kb/recipes.test.ts` holds it to this prefix.
+ */
+export const PLATFORM_TARGET_PREFIX = '_platform.';
+function parseOrNull(body) {
+    try {
+        return parseYaml(body);
+    }
+    catch {
+        return null;
+    }
+}
+/** Every literal flow id an `invoke:` / `resume:` names in `node`, into `out` — `$self` opens nothing new. */
+function collectOpens(node, out) {
+    if (Array.isArray(node)) {
+        for (const v of node)
+            collectOpens(v, out);
+        return;
+    }
+    if (node === null || typeof node !== 'object')
+        return;
+    for (const [k, v] of Object.entries(node)) {
+        if ((k === 'invoke' || k === 'resume') && typeof v === 'string') {
+            if (v !== '$self' && !isExprId(v) && !v.startsWith(PLATFORM_TARGET_PREFIX))
+                out.add(v);
+        }
+        else
+            collectOpens(v, out);
+    }
+}
+function factsOf(starters) {
+    const facts = { ships: new Set(), opens: new Set(), journeys: [], tracking: [] };
+    for (const s of starters) {
+        if (s.kind === 'manifest' || s.kind === 'locale' || s.kind === 'pack-locale')
+            continue;
+        const doc = parseOrNull(s.body);
+        if (isJourneyFile(s.path)) {
+            facts.journeys.push([s.path, doc]);
+            continue;
+        }
+        if (s.kind === 'flow') {
+            facts.ships.add(flowIdOf(s.path));
+            collectOpens(doc, facts.opens);
+        }
+        facts.tracking.push([s.path, doc]); // a declaration's `on:` hook carries `track:` too
+    }
+    return facts;
+}
+const INDEX_OF = { event: 'events', stage_enter: 'stages', goal_reached: 'goals' };
+/**
+ * The other recipes `module` needs on top of what the pack `has`: a recipe that ships each flow its
+ * taps open, and one whose journey declares each literal id its `track:` names — then theirs, until
+ * nothing is missing. Read from the recipes' own files, the same parse the platform's cookbook test
+ * holds every recipe to, so a starter that gains a button gains the need with it.
+ */
+export function recipeNeeds(module, recipes, has) {
+    const memo = new Map();
+    const facts = (m) => {
+        let f = memo.get(m);
+        if (!f)
+            memo.set(m, f = factsOf(recipes.get(m) ?? []));
+        return f;
+    };
+    const chosen = [module];
+    const direct = [];
+    const unresolved = [];
+    const take = (provider, from) => {
+        if (chosen.includes(provider))
+            return;
+        chosen.push(provider);
+        if (from === module)
+            direct.push(provider);
+    };
+    for (let i = 0; i < chosen.length; i++) {
+        const m = chosen[i];
+        const shipped = new Set([...has.flows, ...chosen.flatMap(c => [...facts(c).ships])]);
+        for (const flow of facts(m).opens) {
+            if (shipped.has(flow))
+                continue;
+            const provider = [...recipes.keys()].find(r => facts(r).ships.has(flow));
+            if (provider)
+                take(provider, m);
+            else
+                unresolved.push(`${m}: a button opens '${flow}', which neither the pack nor any recipe ships`);
+        }
+        const declared = collectJourneyIds([...has.journeys, ...chosen.flatMap(c => facts(c).journeys)]);
+        for (const [path, doc] of facts(m).tracking) {
+            for (const v of findJourneyViolations(doc, path, declared)) {
+                const index = INDEX_OF[v.key];
+                const provider = [...recipes.keys()].find(r => collectJourneyIds(facts(r).journeys)[index].has(v.id));
+                if (provider)
+                    take(provider, m);
+                else
+                    unresolved.push(`${m}: ${path} tracks ${v.key} '${v.id}', which no journey declares`);
+            }
+        }
+    }
+    return { needs: chosen.slice(1), direct, unresolved: [...new Set(unresolved)] };
+}