@pikku/cli 0.12.159 → 0.12.162

package/dist/.pikku/services/pikku-meta-service.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { LocalMetaService } from '@pikku/core/services/local-meta';
 export declare class PikkuMetaService extends LocalMetaService {

package/dist/.pikku/services/pikku-meta-service.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { LocalMetaService } from '@pikku/core/services/local-meta';
 export class PikkuMetaService extends LocalMetaService {

package/dist/.pikku/setup/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Subpath entry — `#pikku/setup` resolves here.

package/dist/.pikku/setup/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Subpath entry — `#pikku/setup` resolves here.

package/dist/.pikku/setup/pikku-setup-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Config and service factory definitions, declared once per application

package/dist/.pikku/setup/pikku-setup-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Config and service factory definitions, declared once per application

package/dist/.pikku/trigger/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Subpath entry — `#pikku/trigger` resolves here.

package/dist/.pikku/trigger/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Subpath entry — `#pikku/trigger` resolves here.

package/dist/.pikku/trigger/pikku-trigger-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Trigger-specific type definitions for tree-shaking optimization

package/dist/.pikku/trigger/pikku-trigger-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Trigger-specific type definitions for tree-shaking optimization

package/dist/.pikku/variables/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Subpath entry — `#pikku/variables` resolves here.

package/dist/.pikku/variables/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Subpath entry — `#pikku/variables` resolves here.

package/dist/.pikku/variables/pikku-variable-types.gen.d.ts

@@ -1,4 +1,4 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 export { defineVariable } from '@pikku/core/variable';

package/dist/.pikku/variables/pikku-variable-types.gen.js

@@ -1,4 +1,4 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 export { defineVariable } from '@pikku/core/variable';

package/dist/.pikku/variables/pikku-variables.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { TypedVariablesService as CoreTypedVariablesService } from '@pikku/core/services';
 import type { VariablesService } from '@pikku/core/services';

package/dist/.pikku/variables/pikku-variables.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { TypedVariablesService as CoreTypedVariablesService, } from '@pikku/core/services';
 /**

package/dist/.pikku/workflow/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Subpath entry — `#pikku/workflow` resolves here.

package/dist/.pikku/workflow/index.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 /**
  * Subpath entry — `#pikku/workflow` resolves here.

package/dist/.pikku/workflow/pikku-workflow-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import type { PikkuWorkflowGraphConfig, PikkuWorkflowGraphResult } from '@pikku/core/workflow';

package/dist/.pikku/workflow/pikku-workflow-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { pikkuWorkflowGraph as corePikkuWorkflowGraph } from '@pikku/core/workflow';

package/dist/.pikku/workflow/pikku-workflow-wirings-meta.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { pikkuState } from '@pikku/core/state';
 import allWorkflowMeta from './meta/allWorkflow.gen.json' with { type: 'json' };

package/dist/.pikku/workflow/pikku-workflow-wirings.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.159
+ * This file was generated by @pikku/cli@0.12.162
  */
 import { addWorkflow } from '@pikku/core/workflow';
 import './pikku-workflow-wirings-meta.gen.js';

package/dist/bin/pikku-bin.mjs

@@ -11,8 +11,8 @@ async function checkForUpdate() {
     })
     if (!res.ok) return
     const { version: latest } = await res.json()
-    if (latest !== '0.12.159') {
-      process.stderr.write(`\n  Update available  0.12.159 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
+    if (latest !== '0.12.162') {
+      process.stderr.write(`\n  Update available  0.12.162 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
     }
   } catch {}
 }

package/dist/src/cli.wiring.js

@@ -38,7 +38,7 @@ import { knowledgeValidate, renderKnowledgeValidate, } from './functions/command
 import { knowledgeIndex, renderKnowledgeIndex, } from './functions/commands/knowledge-index.js';
 import { knowledgeReconcile, renderKnowledgeReconcile, } from './functions/commands/knowledge-reconcile.js';
 import { knowledgePlanDefer, knowledgePlanProgress, knowledgePlanSchema, knowledgePlanSet, knowledgePlanShow, renderKnowledgePlanDefer, renderKnowledgePlanProgress, renderKnowledgePlanSchema, renderKnowledgePlanSet, renderKnowledgePlanShow, } from './functions/commands/knowledge-plan.js';
-import { scenarioRun, scenarioList } from './functions/commands/scenario.js';
+import { scenarioRun, scenarioList, scenarioGuide, } from './functions/commands/scenario.js';
 import { personaList, personaRun, personaSecret, } from './functions/commands/persona.js';
 import { personaSync } from './functions/commands/persona-sync.js';
 import { pikkuVersionsInit } from './functions/commands/versions-init.js';
@@ -708,6 +708,30 @@ wireCLI({
                     func: scenarioList,
                     description: 'List scenarios with names and descriptions',
                 }),
+                guide: pikkuCLICommand({
+                    func: scenarioGuide,
+                    description: "Write the user guide the suite already contains: each page's editorial prose merged with the steps and screenshots the latest run recorded. Markdown only — no HTML, no asset URLs, no model.",
+                    options: {
+                        docs: {
+                            description: 'Where the editorial sources live, relative to the project. A `<!-- pikku:guide feature=<id> -->` marker pair in a `<section>/<slug>.md` is both the citation and the place the block is written',
+                            default: 'docs',
+                        },
+                        output: {
+                            description: 'Where the merged markdown is written (default: <outDir>/guide)',
+                            short: 'o',
+                        },
+                        runId: {
+                            description: 'Build from this run rather than the most recent one',
+                        },
+                        allowUndocumented: {
+                            description: 'Report features no page documents instead of failing on them',
+                            default: false,
+                        },
+                        artifactBase: {
+                            description: "Prefix every figure with this instead of the path from the page to the run's artifacts — for a host that serves them at a fixed address. Route-relative (`/docs/_media/`) keeps the output portable; an origin pins it to one host",
+                        },
+                    },
+                }),
             },
         },
         persona: {

package/dist/src/deploy/analyzer/analyzer.js

@@ -303,7 +303,13 @@ export function analyzeDeployment(state, options) {
     // ── Step 1b: Addon units ───────────────────────────────────────────
     const addonUnitByRpcName = new Map();
     for (const [namespace, addonMeta] of entries(state.addonFunctions ?? {})) {
-        const exposed = entries(addonMeta).filter(([, meta]) => meta.expose);
+        // The wiring's `expose` decides when it is `false` or a list; otherwise
+        // the addon's own `expose: true` does — the same rule `rpc.exposed`
+        // applies at runtime, so the unit carries exactly what can be called.
+        const wiredExpose = state.rpc?.wireAddonDeclarations?.get(namespace)?.expose;
+        const exposed = entries(addonMeta).filter(([funcName, meta]) => Array.isArray(wiredExpose)
+            ? wiredExpose.includes(funcName)
+            : wiredExpose !== false && meta.expose);
         if (exposed.length === 0) {
             continue;
         }

package/dist/src/deploy/build-pipeline.d.ts

@@ -111,6 +111,8 @@ export declare function runBuildPipeline(options: {
     srcDirectories?: string[];
     /** Emit sourcemaps + per-unit `metafile.json` (debug-only). Default false. */
     debugArtifacts?: boolean;
+    /** Overrides the provider's own choice when set. See PikkuCLIConfig. */
+    mangleIdentifiers?: boolean;
     logger: BuildLogger;
     /** Runtime-specific bundler (esbuild for node, Bun.build for bun). */
     bundler: Bundler;

package/dist/src/deploy/build-pipeline.js

@@ -193,7 +193,7 @@ function resolveLifecycle(unitDir, state) {
     };
 }
 export async function runBuildPipeline(options) {
-    const { projectDir, projectId, provider, inspectorState, getEntryContext, debugArtifacts, logger, bundler, } = options;
+    const { projectDir, projectId, provider, inspectorState, getEntryContext, debugArtifacts, mangleIdentifiers, logger, bundler, } = options;
     const deployDir = options.deployDir ?? join(projectDir, '.deploy');
     const providerDir = join(deployDir, provider.deployDirName);
     // Step 1: Analyze
@@ -263,7 +263,7 @@ export async function runBuildPipeline(options) {
             define: provider.getDefine?.(),
             platform: provider.getPlatform?.(),
             format: provider.getFormat?.(),
-            mangleIdentifiers: provider.getMangleIdentifiers?.(),
+            mangleIdentifiers: mangleIdentifiers ?? provider.getMangleIdentifiers?.(),
             noRequireShim: provider.getNoRequireShim?.(),
             sourcemap: debugArtifacts,
             emitMetafile: debugArtifacts,
@@ -417,7 +417,7 @@ export async function runBuildPipeline(options) {
                 define: provider.getDefine?.(),
                 platform: provider.getPlatform?.(),
                 format: provider.getFormat?.(),
-                mangleIdentifiers: provider.getMangleIdentifiers?.(),
+                mangleIdentifiers: mangleIdentifiers ?? provider.getMangleIdentifiers?.(),
                 noRequireShim: provider.getNoRequireShim?.(),
                 sourcemap: debugArtifacts,
                 emitMetafile: debugArtifacts,
@@ -442,6 +442,7 @@ export async function runBuildPipeline(options) {
                 define: undefined,
                 platform: 'node',
                 format: 'esm',
+                mangleIdentifiers,
                 noRequireShim: false,
                 sourcemap: debugArtifacts,
                 emitMetafile: debugArtifacts,

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

@@ -365,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/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;