@pikku/cli 0.12.156 → 0.12.160

package/dist/src/functions/commands/deploy-apply.js

@@ -5,17 +5,18 @@ import { readFile } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { pikkuSessionlessFunc } from '#pikku/function';
 import { runBuildPipeline, describeBuildFailure, PikkuDeployBuildFailedError, } from '../../deploy/build-pipeline.js';
+// A bundler reads anything not starting with `./` or `../` as a bare package
+// specifier, and a path into a dot-directory (`.pikku/...`) starts with a dot
+// without being relative — so testing for `.` alone silently emits an import
+// no bundler can resolve.
 function toRelativeImport(fromDir, toFile) {
     let rel = relative(fromDir, toFile).replace(/\\/g, '/');
-    if (!rel.startsWith('.'))
+    if (!rel.startsWith('./') && !rel.startsWith('../'))
         rel = `./${rel}`;
     return rel.replace(/\.ts$/, '.js');
 }
 export function getEntryContext(unitDir, pikkuDir, unit, inspectorState) {
-    const bootstrapRelative = relative(unitDir, join(pikkuDir, 'pikku-bootstrap.gen.js'));
-    const bootstrapPath = bootstrapRelative.startsWith('./') || bootstrapRelative.startsWith('../')
-        ? bootstrapRelative
-        : `./${bootstrapRelative}`;
+    const bootstrapPath = toRelativeImport(unitDir, join(pikkuDir, 'pikku-bootstrap.gen.js'));
     const { pikkuConfigFactory, singletonServicesFactory, singletonServicesType, } = inspectorState.filesAndMethods;
     if (!pikkuConfigFactory || !singletonServicesFactory) {
         throw new Error('Cannot generate deploy entries: createConfig and createSingletonServices must be defined in your project');
@@ -28,14 +29,22 @@ export function getEntryContext(unitDir, pikkuDir, unit, inspectorState) {
     const servicesType = singletonServicesType
         ? `Partial<${singletonServicesType.type}>`
         : 'Record<string, unknown>';
-    // MCP: when the unit's .pikku has a non-empty mcp.gen.json, import it and pass
-    // it to the generated server so PikkuNodeHTTPServer mounts /mcp. Without this
-    // the deployed bundle never serves MCP even though the dev server does.
+    // MCP: when the unit's surface manifest is non-empty, import it and pass it
+    // to the generated server so it mounts the surface. Without this the deployed
+    // bundle never serves MCP even though the dev server does.
+    //
+    // An `mcp` unit serves exactly the one surface it was emitted for — its name
+    // carries that surface's slug, which is also the manifest's filename. Any
+    // other unit (a monolith, say) serves the default surface, as before.
     let mcpImport = '';
     let mcpServerOption = '';
-    const mcpJsonAbs = join(pikkuDir, 'mcp', 'mcp.gen.json');
+    const mcpSlug = unit.role === 'mcp' && unit.name !== 'mcp-server'
+        ? unit.name.replace(/^mcp-/, '')
+        : undefined;
+    const mcpJsonAbs = join(pikkuDir, 'mcp', mcpSlug ? `mcp.${mcpSlug}.gen.json` : 'mcp.gen.json');
     if (existsSync(mcpJsonAbs)) {
         let hasMcp = false;
+        let mcpPath = '/mcp';
         try {
             const parsed = JSON.parse(readFileSync(mcpJsonAbs, 'utf-8'));
             hasMcp =
@@ -43,15 +52,18 @@ export function getEntryContext(unitDir, pikkuDir, unit, inspectorState) {
                     (parsed.resources?.length ?? 0) +
                     (parsed.prompts?.length ?? 0) >
                     0;
+            mcpPath = parsed.mcpPath ?? mcpPath;
         }
         catch (err) {
             console.warn(`[pikku] could not parse ${mcpJsonAbs} — skipping MCP mount: ${err instanceof Error ? err.message : String(err)}`);
         }
         if (hasMcp) {
-            const rel = relative(unitDir, mcpJsonAbs).replace(/\\/g, '/');
-            const relImport = rel.startsWith('.') ? rel : `./${rel}`;
+            const relImport = toRelativeImport(unitDir, mcpJsonAbs);
             mcpImport = `import mcpJson from '${relImport}' with { type: 'json' }`;
-            mcpServerOption = 'mcpJson, ';
+            mcpServerOption =
+                mcpPath === '/mcp'
+                    ? 'mcpJson, '
+                    : `mcpJson, mcpPath: ${JSON.stringify(mcpPath)}, `;
         }
     }
     return {
@@ -103,7 +115,105 @@ async function resolveProjectId(projectDir) {
  * configured provider may also be a URL, and a runtime whose `require.resolve`
  * hands a bare specifier straight back for its own built-ins has resolved
  * nothing. Both of those import as written.
+ *
+ * `require.resolve` applies the `require` condition, so an ESM-only provider —
+ * one whose exports map offers `types` and `import` and nothing else, which is
+ * a perfectly ordinary way to publish — does not resolve there even though it
+ * is installed and importable. Falling through to the bare import does not
+ * rescue it, because that resolves from the CLI rather than the project, so
+ * `resolveEsmOnlyEntry` reads the package's own entry instead. It has to walk
+ * the resolution paths by hand: the exports map that blocked the package also
+ * blocks `<name>/package.json`.
+ *
+ * Which is why it runs on any resolution failure rather than on one code. Node
+ * reports this as ERR_PACKAGE_PATH_NOT_EXPORTED and bun as a plain
+ * MODULE_NOT_FOUND, indistinguishable from a package that is genuinely absent.
+ * Telling them apart is what the filesystem is for: a package that is not there
+ * yields no entry and the bare import still runs, unchanged.
+ */
+/**
+ * The conditions that are true for the `import()` this resolution ends in.
+ * `default` matches unconditionally and is handled by the resolver rather than
+ * listed here, because node treats it as the fallthrough rather than as a name.
+ */
+const ACTIVE_EXPORT_CONDITIONS = new Set(['node', 'import']);
+/**
+ * Picks an export target the way node does: a conditions object is walked in
+ * DECLARATION order and the first key that is active wins, nesting included.
+ *
+ * The order is the package author's, not ours. `{ "import": { "node": "./n.js",
+ * "default": "./browser.js" } }` resolves to `./n.js`, because `node` is listed
+ * first and is true here — preferring a fixed list of condition names instead
+ * would hand back the browser build and load a different provider than the one
+ * node would have.
+ *
+ * An array is a list of fallbacks, and `null` is a deliberate block, so both
+ * carry on to the next candidate rather than ending the walk.
  */
+const resolveExportTarget = (target) => {
+    if (typeof target === 'string')
+        return target;
+    if (target === null || target === undefined)
+        return undefined;
+    if (Array.isArray(target)) {
+        for (const candidate of target) {
+            const resolved = resolveExportTarget(candidate);
+            if (resolved !== undefined)
+                return resolved;
+        }
+        return undefined;
+    }
+    if (typeof target !== 'object')
+        return undefined;
+    for (const [condition, value] of Object.entries(target)) {
+        if (condition !== 'default' && !ACTIVE_EXPORT_CONDITIONS.has(condition)) {
+            continue;
+        }
+        const resolved = resolveExportTarget(value);
+        if (resolved !== undefined)
+            return resolved;
+    }
+    return undefined;
+};
+/**
+ * The entry an exports map offers to `import`, or, for a package with no
+ * exports map at all, its legacy main. A map that deliberately omits a root
+ * entry offers nothing: falling back to `main` there would reach past the
+ * encapsulation the package asked for, so this reports no entry and the caller
+ * treats the provider as missing.
+ */
+const esmEntryFromManifest = (manifest) => {
+    const exportsField = manifest.exports;
+    if (exportsField === undefined || exportsField === null) {
+        const legacy = manifest.module ?? manifest.main;
+        return typeof legacy === 'string' ? legacy : undefined;
+    }
+    const isSubpathMap = typeof exportsField === 'object' &&
+        !Array.isArray(exportsField) &&
+        Object.keys(exportsField).some((key) => key.startsWith('.'));
+    const root = isSubpathMap ? exportsField['.'] : exportsField;
+    return resolveExportTarget(root);
+};
+const resolveEsmOnlyEntry = (require, packageName) => {
+    const searchPaths = require.resolve.paths(packageName) ?? [];
+    for (const searchPath of searchPaths) {
+        const packageJsonPath = join(searchPath, packageName, 'package.json');
+        if (!existsSync(packageJsonPath))
+            continue;
+        let manifest;
+        try {
+            manifest = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+        }
+        catch {
+            return undefined;
+        }
+        const entry = esmEntryFromManifest(manifest);
+        if (!entry)
+            return undefined;
+        return join(searchPath, packageName, entry);
+    }
+    return undefined;
+};
 const importProviderPackage = async (packageName, projectDir) => {
     const require = createRequire(join(projectDir ?? process.cwd(), 'package.json'));
     try {
@@ -115,9 +225,14 @@ const importProviderPackage = async (packageName, projectDir) => {
     catch (e) {
         const err = e;
         if (err?.code !== 'ERR_MODULE_NOT_FOUND' &&
-            err?.code !== 'MODULE_NOT_FOUND') {
+            err?.code !== 'MODULE_NOT_FOUND' &&
+            err?.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
             throw e;
         }
+        const entry = resolveEsmOnlyEntry(require, packageName);
+        if (entry && existsSync(entry)) {
+            return await import(pathToFileURL(entry).href);
+        }
     }
     return await import(packageName);
 };
@@ -250,6 +365,7 @@ export const deployApply = pikkuSessionlessFunc({
             serverlessIncompatible: config.deploy?.serverlessIncompatible,
             defaultTarget: config.deploy?.defaultTarget,
             grouping: config.deploy?.grouping,
+            mangleIdentifiers: config.deploy?.mangleIdentifiers,
             globalHTTPPrefix: config.globalHTTPPrefix,
             getEntryContext,
             frontend: config.frontend,

package/dist/src/functions/commands/deploy-plan.js

@@ -59,6 +59,7 @@ export const deployPlan = pikkuSessionlessFunc({
             serverlessIncompatible: config.deploy?.serverlessIncompatible,
             defaultTarget: config.deploy?.defaultTarget,
             grouping: config.deploy?.grouping,
+            mangleIdentifiers: config.deploy?.mangleIdentifiers,
             globalHTTPPrefix: config.globalHTTPPrefix,
             getEntryContext,
             frontend: config.frontend,

package/dist/src/functions/commands/dev-mcp-manifests.d.ts

@@ -0,0 +1,27 @@
+export type McpManifest = {
+    mcpPath?: string;
+    tools?: unknown[];
+    resources?: unknown[];
+    prompts?: unknown[];
+};
+export type McpSurfaceMount = {
+    mcpJson: McpManifest;
+    mcpPath: string;
+};
+/**
+ * Every MCP endpoint the generated tree describes: the default one, plus one
+ * per surface for a project that serves several connectors.
+ *
+ * Dev mounts all of them so a connector can be pointed at `pikku dev` and tried
+ * before it is deployed. Without the surfaces, a project that moved its tools
+ * onto their own endpoints would serve nothing locally at all — the default
+ * manifest it does read is empty precisely because they moved.
+ *
+ * A surface manifest without an `mcpPath` is skipped rather than guessed at: the
+ * path is what the deployed unit is routed on, and a mount at a different path
+ * would make dev disagree with production.
+ */
+export declare const readMcpManifests: (pikkuDir: string, onWarning: (message: string) => void) => {
+    mcpJson?: McpManifest;
+    mcpSurfaces: McpSurfaceMount[];
+};

package/dist/src/functions/commands/dev-mcp-manifests.js

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'path';
+/**
+ * A manifest with nothing in it reads as "no MCP here": the transports mount
+ * only when there is something to serve, so an empty one would announce an
+ * endpoint that answers every call with a missing tool.
+ *
+ * Absent or unparseable is not an error either — an app with no MCP wirings
+ * has no manifest, and that is the common case.
+ */
+const readMcpManifest = (file, onWarning) => {
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        const count = (parsed.tools?.length ?? 0) +
+            (parsed.resources?.length ?? 0) +
+            (parsed.prompts?.length ?? 0);
+        return count > 0 ? parsed : undefined;
+    }
+    catch (err) {
+        onWarning(`[pikku] could not parse ${file} — MCP will not be served: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+};
+/**
+ * Every MCP endpoint the generated tree describes: the default one, plus one
+ * per surface for a project that serves several connectors.
+ *
+ * Dev mounts all of them so a connector can be pointed at `pikku dev` and tried
+ * before it is deployed. Without the surfaces, a project that moved its tools
+ * onto their own endpoints would serve nothing locally at all — the default
+ * manifest it does read is empty precisely because they moved.
+ *
+ * A surface manifest without an `mcpPath` is skipped rather than guessed at: the
+ * path is what the deployed unit is routed on, and a mount at a different path
+ * would make dev disagree with production.
+ */
+export const readMcpManifests = (pikkuDir, onWarning) => {
+    const mcpDir = join(pikkuDir, 'mcp');
+    const mcpJson = readMcpManifest(join(mcpDir, 'mcp.gen.json'), onWarning);
+    const mcpSurfaces = (existsSync(mcpDir) ? readdirSync(mcpDir) : [])
+        .filter((name) => /^mcp\..+\.gen\.json$/.test(name))
+        .sort()
+        .flatMap((name) => {
+        const parsed = readMcpManifest(join(mcpDir, name), onWarning);
+        if (!parsed?.mcpPath)
+            return [];
+        return [{ mcpJson: parsed, mcpPath: parsed.mcpPath }];
+    });
+    return { mcpJson, mcpSurfaces };
+};

package/dist/src/functions/commands/dev.js

@@ -1,5 +1,5 @@
 import { join, resolve } from 'path';
-import { existsSync, readFileSync } from 'node:fs';
+import { readMcpManifests } from './dev-mcp-manifests.js';
 import { pikkuSessionlessFunc } from '#pikku/function';
 import chokidar from 'chokidar';
 import { pikkuDevReloader, reloadGeneratedMeta, reconcileAddonRegistry, } from '@pikku/core/dev';
@@ -308,45 +308,25 @@ export const dev = pikkuSessionlessFunc({
             ...(consoleMount ? [consoleMount] : []),
         ];
         /**
-         * Hand the server the generated MCP manifest so it actually serves MCP.
+         * Hand the server the generated MCP manifests so it actually serves MCP.
          *
          * Codegen reports "N MCP endpoints" and both transports mount them at
-         * `mcpPath` — but only when given `mcpJson`, and dev never passed it.
+         * `mcpPath` — but only when given the manifest, and dev never passed it.
          *
-         * It goes in the runner *options*, not in the config: the transport reads it
-         * off its third argument, and the runners forward a hand-picked list of
-         * fields. Putting it in `config` type-checks and is discarded in silence.
-         * So every pikku app announced an MCP surface at startup and served a 404,
-         * and the only way to exercise a tool was to deploy. `deploy-apply` even
-         * carries a comment saying the deployed bundle should match "the dev server"
-         * — which had never served it either.
-         *
-         * Absent or unparseable is not an error: an app with no MCP wirings has no
-         * manifest, and that is the common case.
+         * They go in the runner *options*, not in the config: the transport reads
+         * them off its third argument, and the runners forward a hand-picked list
+         * of fields. Putting them in `config` type-checks and is discarded in
+         * silence. So every pikku app announced an MCP surface at startup and
+         * served a 404, and the only way to exercise a tool was to deploy.
          */
-        const mcpJson = await (async () => {
-            const file = join(pikkuDir, 'mcp', 'mcp.gen.json');
-            if (!existsSync(file))
-                return undefined;
-            try {
-                const parsed = JSON.parse(readFileSync(file, 'utf-8'));
-                const count = (parsed.tools?.length ?? 0) +
-                    (parsed.resources?.length ?? 0) +
-                    (parsed.prompts?.length ?? 0);
-                return count > 0 ? parsed : undefined;
-            }
-            catch (err) {
-                logger.warn(`[pikku] could not parse ${file} — MCP will not be served: ${err instanceof Error ? err.message : String(err)}`);
-                return undefined;
-            }
-        })();
+        const { mcpJson, mcpSurfaces } = readMcpManifests(pikkuDir, (message) => logger.warn(message));
         const pikkuServer = devServerRunner.createServer({
             ...userConfig,
             hostname: bindHostname,
             port: resolvedPort,
             content: localContentConfig,
             ...(staticMounts.length > 0 ? { staticMounts } : {}),
-        }, logger, { contentSigningJWT, mcpJson });
+        }, logger, { contentSigningJWT, mcpJson, mcpSurfaces });
         const lifecycle = await loadLifecycle();
         await pikkuServer.init();
         await lifecycle?.beforeStart?.(resolvedServices);

package/dist/src/functions/commands/knowledge-reconcile.d.ts

@@ -1,5 +1,7 @@
 import { renderKnowledgeReconcile } from '../knowledge/render.js';
-export declare const knowledgeReconcile: import("#pikku/function").PikkuFunctionConfig<Record<string, never>, {
+export declare const knowledgeReconcile: import("#pikku/function").PikkuFunctionConfig<{
+    require?: string | undefined;
+}, {
     kind: "ask-user" | "dispatch" | "hold" | "idle" | "repair-note" | "write-plan";
     reason: string;
     note?: string | undefined;
@@ -13,7 +15,11 @@ export declare const knowledgeReconcile: import("#pikku/function").PikkuFunction
             description?: string | undefined;
         }[];
     } | undefined;
-}, "rpc" | "session", import("#pikku/function").PikkuFunction<Record<string, never>, {
+    satisfied?: boolean | undefined;
+    required?: string[] | undefined;
+}, "rpc" | "session", import("#pikku/function").PikkuFunction<{
+    require?: string | undefined;
+}, {
     kind: "ask-user" | "dispatch" | "hold" | "idle" | "repair-note" | "write-plan";
     reason: string;
     note?: string | undefined;
@@ -27,7 +33,11 @@ export declare const knowledgeReconcile: import("#pikku/function").PikkuFunction
             description?: string | undefined;
         }[];
     } | undefined;
-}, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<Record<string, never>, {
+    satisfied?: boolean | undefined;
+    required?: string[] | undefined;
+}, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<{
+    require?: string | undefined;
+}, {
     kind: "ask-user" | "dispatch" | "hold" | "idle" | "repair-note" | "write-plan";
     reason: string;
     note?: string | undefined;
@@ -41,5 +51,7 @@ export declare const knowledgeReconcile: import("#pikku/function").PikkuFunction
             description?: string | undefined;
         }[];
     } | undefined;
+    satisfied?: boolean | undefined;
+    required?: string[] | undefined;
 }, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;
 export { renderKnowledgeReconcile };

package/dist/src/functions/commands/knowledge-reconcile.js

@@ -6,6 +6,6 @@ export const knowledgeReconcile = pikkuSessionlessFunc({
     description: 'Say the one thing to do next with the knowledge base — repair a note, write a plan, ask the user, dispatch a build, or nothing — derived from what is on disk rather than from what a previous step remembered to announce.',
     input: KnowledgeReconcileInputSchema,
     output: KnowledgeReconcileOutputSchema,
-    func: async ({ config }) => runKnowledgeReconcile(config.rootDir),
+    func: async ({ config }, input) => runKnowledgeReconcile(config.rootDir, input),
 });
 export { renderKnowledgeReconcile };

package/dist/src/functions/commands/scenario-guide.d.ts

@@ -0,0 +1,184 @@
+/** One step of a scenario, as the run recorded it. */
+export interface GuideStep {
+    /** The gherkin keyword the sentence was recorded under: Given, When, Then, And. */
+    phase?: string;
+    /** The sentence itself, without the keyword. */
+    sentence: string;
+}
+/** One screenshot a scenario filed, ready to reference. */
+export interface GuideScreenshot {
+    /** The artifact's stable id, when the run recorded one. */
+    id?: string;
+    /** The caption the scenario author took the shot under; the alt text. */
+    name?: string;
+    /**
+     * The artifact's content key, relative to the run's artifact root and always
+     * forward-slashed — what the record stores, not a path on this machine. A
+     * page turns it into a link by prefixing the base it was rendered with.
+     */
+    path: string;
+}
+/**
+ * The recording a scenario filed, when the run kept one.
+ *
+ * A browser run keeps a video per scenario and per actor, so a two-actor
+ * scenario files two. Same shape as a screenshot because a consumer treats it
+ * the same way — a key under the run's artifact root that a base is prefixed
+ * onto.
+ */
+export interface GuideVideo {
+    id?: string;
+    /** Whose window it was, when the run recorded more than one. */
+    actor?: string;
+    path: string;
+}
+export interface GuideScenario {
+    /** The scenario registration this ran. */
+    name: string;
+    /** What the run labelled it — the registration name, plus its feature and data. */
+    title: string;
+    description?: string;
+    /**
+     * The recorded ladder. Never rendered — a reader wants prose, not a
+     * Given/When/Then list — but it is the seed the prose is written from and the
+     * input {@link featureEvidence} watches.
+     */
+    steps: GuideStep[];
+    screenshots: GuideScreenshot[];
+    /**
+     * Optional so that a record predating video, and every fixture written
+     * against one, still describes a scenario.
+     */
+    videos?: GuideVideo[];
+}
+export interface GuideFeature {
+    id: string;
+    name: string;
+    description?: string;
+    /** `document !== false` on the registered feature. */
+    document: boolean;
+    scenarios: GuideScenario[];
+}
+/** One checked-in editorial source, parsed. */
+export interface GuidePage {
+    /** Path relative to the docs source root, e.g. `deployments/promoting.md`. */
+    path: string;
+    title?: string;
+    description?: string;
+    /**
+     * The features this page cites, in the order their markers appear. Read off
+     * the body rather than declared in frontmatter: see {@link parseGuidePage}.
+     */
+    features: string[];
+    /**
+     * The frontmatter as it was written, every key of it. Carried whole rather
+     * than picked apart because a docs site reads its own keys off it — `slug`,
+     * `draft`, `sidebar_position` — and a compiler that rebuilt the block from
+     * the fields it happens to know about would drop them on the first rebuild.
+     */
+    frontmatter: Record<string, unknown>;
+    /** Everything after the frontmatter, generated regions included. */
+    body: string;
+}
+/**
+ * Read one editorial source.
+ *
+ * A page cites a feature by leaving the marker pair where the block belongs —
+ * an author writing `<!-- pikku:guide feature=x -->` followed by
+ * `<!-- /pikku:guide -->` and nothing between them. That one line is both
+ * halves of the job: it says *where* the block goes, which a frontmatter list
+ * cannot express, and it is what the coverage gate counts to decide *whether* a
+ * feature is documented at all. The mapping stays many-to-many and falls out of
+ * the union of every marker in the tree, so a feature written about in three
+ * places needs no index to say so.
+ */
+export declare const parseGuidePage: (path: string, content: string) => GuidePage;
+/**
+ * The hash a page's prose is written against.
+ *
+ * The input is the feature's **step sentences and artifact ids**, and
+ * deliberately not the image bytes and not the prose: restyling a UI changes
+ * every screenshot and no sentence, while inserting, reordering or renaming a
+ * step changes the sentence list — and that is what actually invalidates a
+ * paragraph describing the flow. It watches something the reader never sees.
+ *
+ * Canonically, the hashed value is the JSON of
+ * `[[scenarioName, [sentence, …], [artifactId, …]], …]` where:
+ *
+ * - scenarios are sorted by name then title, because a run's order is a
+ *   property of how the suite was selected that day, not of the feature;
+ * - sentences keep their ladder order, keyword included, because that order is
+ *   the flow being described — the one thing a step change must move;
+ * - each sentence is whitespace-collapsed, so the reporter's column padding is
+ *   not part of the promise;
+ * - artifact ids are sorted, because artifacts are filed as they are finalised
+ *   rather than as they were taken.
+ *
+ * Seven hex characters, like a short commit hash: it is read by a human
+ * comparing two lines, not by a collision-resistant protocol.
+ */
+export declare const featureEvidence: (feature: GuideFeature) => string;
+/**
+ * What each documented feature's evidence was the last time the guide was
+ * built, keyed by feature id.
+ *
+ * This is the one piece of machine state the pipeline keeps, and it is kept out
+ * of both the marker and the page frontmatter so that no hash is ever typed or
+ * merged by hand. It is generated, and it is checked in: a build that cannot
+ * read the previous hashes cannot tell stale prose from fresh, so a guide tree
+ * whose lock is untracked reports every page as current forever.
+ */
+export type GuideLock = Record<string, string>;
+export declare const parseGuideLock: (content: string) => GuideLock;
+export declare const renderGuideLock: (features: GuideFeature[], cited: Iterable<string>) => string;
+/** Which features are documented, which pages cite something that is not. */
+export interface GuideCoverage {
+    /** Registered, documented, and cited by at least one page. */
+    cited: string[];
+    /** Registered, documented, and cited by no page. */
+    missing: string[];
+    /** Cited by a page and not registered at all. */
+    unknown: Array<{
+        path: string;
+        featureId: string;
+    }>;
+    /** Cited by a page and registered with `document: false`. */
+    optedOut: Array<{
+        path: string;
+        featureId: string;
+    }>;
+    /** Cited, but the run filed no figure for it — a citation that shows nothing. */
+    figureless: Array<{
+        path: string;
+        featureId: string;
+    }>;
+    /** Pages whose locked evidence is not the feature's current evidence. */
+    stale: Array<{
+        path: string;
+        featureId: string;
+        locked: string;
+        current: string;
+    }>;
+}
+export declare const checkGuideCoverage: (features: GuideFeature[], pages: GuidePage[], lock?: GuideLock) => GuideCoverage;
+/**
+ * Merge one editorial source with the blocks its features generate.
+ *
+ * Hand-written prose and generated blocks stay separable, so a rebuild never
+ * clobbers writing: the body is the author's file, and only the regions between
+ * the markers are replaced. A block whose feature the page has stopped citing is
+ * dropped, since nothing would ever rewrite it again.
+ *
+ * `artifactBase` is prefixed onto every artifact key: the relative path from
+ * this page to the run's artifact root, which is all this module knows about
+ * where anything lives.
+ */
+export declare const renderGuidePage: (page: GuidePage, features: Map<string, GuideFeature>, artifactBase: string) => string;
+/**
+ * A recorded step sentence, split into its gherkin keyword and the rest.
+ *
+ * The run stores the composed sentence — `Given    yasser signs in`, padded to
+ * the reporter's keyword column — so the phase is already in it and is read
+ * back off the record rather than re-derived from today's source.
+ */
+export declare const guideStep: (sentence: string) => GuideStep;