@pikku/cli 0.12.125 → 0.12.126

package/dist/src/fabric/functions/validate.function.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { createRequire } from 'node:module';
 import { pikkuSessionlessFunc } from '../../../.pikku/function/index.js';
 import { added, changed, removed, dim } from '../lib/output.js';
@@ -10,6 +10,8 @@ import { readJsonSafe, readTextSafe, runSharedProjectChecks, } from '../../funct
 import { runTypeIdentityChecks } from '../../functions/validate/type-identity-checks.js';
 import { migrationCreatesTable } from '../../functions/validate/shared-checks.js';
 import { isGitRepo, isTracked } from '../lib/git.js';
+import { blankComments, lineOfOffset } from '../lib/blank-comments.js';
+import { blankScenarioMeta } from '../lib/blank-scenario-meta.js';
 const FindingSchema = z.object({
     id: z.string(),
     severity: z.enum(['error', 'warn', 'info']),
@@ -66,15 +68,6 @@ async function listSourceFiles(dir) {
         return [];
     }
 }
-/**
- * Blanks comment bodies so a raw-text scan cannot read prose as code. Prose in a
- * scenario description ("Converted from the Gherkin scenario...") otherwise
- * matches the import scanner's `from "..."` and reports a package that is really
- * a sentence.
- */
-const stripCommentText = (text) => text
-    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
-    .replace(/(^|[^:'"`\\])\/\/[^\n]*/g, (_m, p1) => p1);
 // Heavy/generated dirs pruned during a source walk.
 const SKIP_WALK_DIRS = new Set([
     'node_modules',
@@ -489,17 +482,20 @@ export async function runValidate(startDir = process.cwd(), opts = {}) {
             // tsconfig `paths` keys (e.g. "@/*") are internal aliases, not packages.
             const tsconfig = await readJsonSafe(join(dir, 'tsconfig.json'));
             const aliasPrefixes = Object.keys(tsconfig?.compilerOptions?.paths ?? {}).map((k) => k.replace(/\*$/, ''));
+            // name → "<relative file>:<line>" of the first import that used it.
             const used = new Map();
             for (const file of await listSourceFiles(join(dir, 'src'))) {
                 if (/\.gen\.(ts|tsx)$/.test(file))
                     continue;
-                const txt = await readTextSafe(file);
-                if (!txt)
+                const raw = await readTextSafe(file);
+                if (!raw)
                     continue;
-                const src = stripCommentText(txt);
+                // Comments first, or prose becomes a dependency: `from "is fine"` in a
+                // sentence is indistinguishable from an import to this regex.
+                const txt = blankComments(raw);
                 const re = /(?:from|import|require)\s*\(?\s*['"]([^'".#][^'"]*)['"]/g;
                 let m;
-                while ((m = re.exec(src))) {
+                while ((m = re.exec(txt))) {
                     const spec = m[1];
                     if (/\s/.test(spec) ||
                         spec.startsWith('node:') ||
@@ -516,13 +512,15 @@ export async function runValidate(startDir = process.cwd(), opts = {}) {
                     const name = pkgNameOf(spec);
                     if (NODE_BUILTINS.has(name) || name === pkg.name || wsNames.has(name))
                         continue;
-                    if (!used.has(name))
-                        used.set(name, file);
+                    if (!used.has(name)) {
+                        const where = `${relative(root, file).replace(/\\/g, '/')}:${lineOfOffset(raw, m.index)}`;
+                        used.set(name, where);
+                    }
                 }
             }
             const missing = [...used.keys()].filter((n) => !declared.has(n)).sort();
             if (missing.length) {
-                e(`undeclared-deps-${(pkg.name ?? dir).replace(/[@/]/g, '-')}`, `${pkg.name ?? dir} imports undeclared package(s): ${missing.join(', ')} — the deploy bundle cannot resolve them`, join(dir, 'package.json'), lines(`Add the missing package(s) to ${pkg.name ?? 'this package'}'s dependencies, e.g.:`, ...missing.map((n) => `  "${n}": "<version>"`), 'then reinstall. They import-resolve locally via tsconfig paths / root', 'hoisting, but esbuild/Bun.build resolves each package independently.'));
+                e(`undeclared-deps-${(pkg.name ?? dir).replace(/[@/]/g, '-')}`, `${pkg.name ?? dir} imports undeclared package(s): ${missing.join(', ')} — the deploy bundle cannot resolve them`, join(dir, 'package.json'), lines(`Add the missing package(s) to ${pkg.name ?? 'this package'}'s dependencies, e.g.:`, ...missing.map((n) => `  "${n}": "<version>"   (first used at ${used.get(n)})`), 'then reinstall. They import-resolve locally via tsconfig paths / root', 'hoisting, but esbuild/Bun.build resolves each package independently.'));
             }
             // @pikku/browser pins `puppeteer-core` to the exact version that
             // @cloudflare/puppeteer forks, so headless rendering behaves identically
@@ -762,13 +760,37 @@ export async function runValidate(startDir = process.cwd(), opts = {}) {
                 // readdir failure — skip
             }
         }
+        // ── the coercion map has to reach a Kysely instance ──────────────────
+        // `pikku db migrate` generates a CoercionMap from the `kind` entries in
+        // db/annotations.ts, and nothing wires it up on the project's behalf. An
+        // unwired map is invisible locally and fatal deployed: the dev sqlite
+        // driver hydrates a TEXT date into a Date by itself, libsql on a stage
+        // returns the raw string, and the generated schema types the column
+        // `Date` either way — so tsc flags nothing and there is no failing local
+        // test to write. It surfaces as `TypeError: e.getFullYear is not a
+        // function` on the first deployed request. Booleans diverge more quietly
+        // still: `1` from a stage where local gives `true`.
+        const outDirRel = typeof pikkuConfig?.outDir === 'string' ? pikkuConfig.outDir : '.pikku';
+        const coercionPath = join(root, outDirRel, 'db', 'coercion.gen.ts');
+        const coercionText = await readTextSafe(coercionPath);
+        // `{}` means no column declared a `kind`, so there is nothing to wire.
+        if (coercionText && /:\s*"(date|boolean|json)"/.test(coercionText)) {
+            const wired = (await Promise.all((await walkSourceFiles(root)).map((f) => readTextSafe(f)))).some((text) => text?.includes('createCoercionPlugin'));
+            if (!wired) {
+                e('coercion-map-not-wired', `${join(outDirRel, 'db', 'coercion.gen.ts')} declares coercions that no Kysely instance applies`, coercionPath, lines('Attach the plugin where the kysely singleton is created, in', 'createSingletonServices:', '', "  import { createCoercionPlugin } from '@pikku/kysely'", "  import { coercionMap } from '#pikku/db/coercion.gen.js'", '', '  kysely: existingServices.kysely.withPlugin(', '    createCoercionPlugin({ map: coercionMap }),', '  )', '', 'Without it a deployed stage returns raw strings and integers where', 'the generated schema promises Date and boolean. The dev driver', 'hydrates them for you, so this cannot fail locally.'));
+            }
+        }
         const devSeedPath = join(root, 'db', dbEngine === 'postgres' ? 'postgres-dev-seed.sql' : 'sqlite-dev-seed.sql');
+        // Info, not an error. The dev seed is replayed by `pikku db reset` and
+        // never by a deploy, so a project whose data has correctly moved into a
+        // migration — where anything a deployed stage needs has to live — no
+        // longer needs this file, and was being failed for not carrying it.
         if (!existsSync(devSeedPath)) {
-            e('dev-seed-sql-missing', dbEngine === 'postgres'
-                ? 'db/postgres-dev-seed.sql not found'
-                : 'db/sqlite-dev-seed.sql not found', devSeedPath, dbEngine === 'postgres'
-                ? lines('Create `db/postgres-dev-seed.sql`.', 'Use idempotent INSERT statements suitable for local/dev/test setup.', 'Keep it safe to re-run.')
-                : lines('Create `db/sqlite-dev-seed.sql`.', 'Use idempotent `INSERT OR IGNORE` statements for local/dev/test data.', 'Keep it safe to re-run.'));
+            const seedFile = dbEngine === 'postgres'
+                ? 'db/postgres-dev-seed.sql'
+                : 'db/sqlite-dev-seed.sql';
+            const migrationsRel = dbEngine === 'postgres' ? 'db/postgres/' : 'db/sqlite/';
+            info('dev-seed-sql-missing', `${seedFile} not found — no dev seed will be applied by \`pikku db reset\``, devSeedPath, lines(`Optional. Add \`${seedFile}\` for rows you want locally and nowhere else;`, 'it is replayed by `pikku db reset` against a freshly wiped database and', 'is never applied to a deployed stage.', `Data a deployed stage needs is migration data — put it in ${migrationsRel}`, 'rather than here, whatever it looks like.'));
         }
         // audit table — info if not present (optional feature)
         if (existsSync(migrationsDir)) {
@@ -1038,7 +1060,7 @@ export async function runValidate(startDir = process.cwd(), opts = {}) {
                     }
                 }
                 if (loginFiles.length > 0 && !hasQuickLogin) {
-                    e(`app-missing-actor-quick-login-${name}`, `apps/${name} has a login screen (${loginFiles[0]}) but no one-click actor sign-in — nobody can view the app as a scenario persona without a password`, join(appPath, loginFiles[0]), lines('Render the dev-only "Sign in as …" switcher from the login screen.', `In ${loginFiles[0]}:`, "  import { DevActorSwitcher } from '@pikku/mantine/dev'", '  <DevActorSwitcher', '    actors={import.meta.env.DEV ? import.meta.env.VITE_DEV_ACTORS : undefined}', '    secret={import.meta.env.DEV ? import.meta.env.VITE_SCENARIO_ACTOR_SECRET : undefined}', '    apiUrl={apiUrl()}', "    onSignedIn={() => navigate({ to: '/' })}", '  />', 'The sandbox dev server bakes both env vars from your declared personas;', 'neither is set in production, so the control renders null there.', 'Gate the reads on import.meta.env.DEV as above so the secret never', 'reaches a production bundle. Next.js apps read the NEXT_PUBLIC_* pair.', 'For custom UI, build on useDevActors() from @pikku/react instead.'));
+                    e(`app-missing-actor-quick-login-${name}`, `apps/${name} has a login screen (${loginFiles[0]}) but no one-click actor sign-in — nobody can view the app as a scenario persona without a password`, join(appPath, loginFiles[0]), lines('Render the dev-only "Sign in as …" switcher from the login screen.', `In ${loginFiles[0]}:`, "  import { DevActorSwitcher } from '@pikku/mantine/dev'", '  <DevActorSwitcher', '    actors={import.meta.env.DEV ? import.meta.env.VITE_DEV_ACTORS : undefined}', '    secrets={import.meta.env.DEV ? import.meta.env.VITE_DEV_ACTOR_SECRETS : undefined}', '    apiUrl={apiUrl()}', "    onSignedIn={() => navigate({ to: '/' })}", '  />', 'The sandbox dev server bakes both env vars from your declared personas;', 'neither is set in production, so the control renders null there.', 'VITE_DEV_ACTOR_SECRETS is one credential per persona, each accepted for', 'that persona only. Gate the reads on import.meta.env.DEV as above so no', 'credential reaches a production bundle. Next.js reads the NEXT_PUBLIC_* pair.', 'For custom UI, build on useDevActors() from @pikku/react instead.'));
                 }
             }
         }
@@ -1241,7 +1263,10 @@ export async function runValidate(startDir = process.cwd(), opts = {}) {
                 const text = await readTextSafe(file);
                 if (!text)
                     continue;
-                const code = stripCommentText(text);
+                // Comments carry the copy they explain; a feature's own name and
+                // description are Console meta authored in the project's locale, not
+                // app copy. Neither reaches the DOM, so neither is a selector.
+                const code = blankScenarioMeta(blankComments(text));
                 const hits = [];
                 for (const match of code.matchAll(STRING_LITERAL)) {
                     const literal = match[2];

package/dist/src/fabric/functions/variables-get.function.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 export declare const FabricVariablesGetInput: z.ZodObject<{
     name: z.ZodString;
-    branch: z.ZodString;
+    branch: z.ZodOptional<z.ZodString>;
     json: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const FabricVariablesGetOutput: z.ZodObject<{
@@ -11,7 +11,7 @@ export declare const FabricVariablesGetOutput: z.ZodObject<{
 }, z.core.$strip>;
 export declare const FabricVariablesGet: import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionConfig<{
     name: string;
-    branch: string;
+    branch?: string | undefined;
     json?: boolean | undefined;
 }, {
     name: string;
@@ -19,7 +19,7 @@ export declare const FabricVariablesGet: import("../../../.pikku/function/pikku-
     value: unknown;
 }, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionSessionless<{
     name: string;
-    branch: string;
+    branch?: string | undefined;
     json?: boolean | undefined;
 }, {
     name: string;
@@ -27,7 +27,7 @@ export declare const FabricVariablesGet: import("../../../.pikku/function/pikku-
     value: unknown;
 }, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices, unknown> | import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunction<{
     name: string;
-    branch: string;
+    branch?: string | undefined;
     json?: boolean | undefined;
 }, {
     name: string;

package/dist/src/fabric/functions/variables-get.function.js

@@ -2,10 +2,10 @@ import { z } from 'zod';
 import { pikkuSessionlessFunc } from '../../../.pikku/function/index.js';
 import { resolveApiContext } from '../lib/config.js';
 import { getFabricRPC } from '../lib/http.js';
-import { resolveStageId } from '../lib/stage.js';
+import { resolveStage } from '../lib/stage.js';
 export const FabricVariablesGetInput = z.object({
     name: z.string(),
-    branch: z.string(),
+    branch: z.string().optional(),
     json: z.boolean().optional(),
 });
 export const FabricVariablesGetOutput = z.object({
@@ -17,14 +17,14 @@ export const FabricVariablesGet = pikkuSessionlessFunc({
     description: 'Read a stage-scoped variable back, so you can see the shape it was stored in rather than the shape you meant.',
     input: FabricVariablesGetInput,
     output: FabricVariablesGetOutput,
-    func: async (_services, { name, branch, json }) => {
+    func: async (_services, { name, branch: requested, json }) => {
         const ctx = await resolveApiContext();
         if (!ctx.token)
             throw new Error('Not logged in. Run `pikku fabric login` first.');
         if (!ctx.projectId)
             throw new Error('No fabric project linked. Run `pikku fabric link` first.');
         const rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
-        const stageId = await resolveStageId(rpc, ctx.projectId, branch);
+        const { stageId, branch } = await resolveStage(rpc, ctx.projectId, requested);
         const { exists, value } = await rpc.invoke('getStageConsoleVariable', {
             stageId,
             variableId: name,

package/dist/src/fabric/functions/variables-set.function.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 export declare const FabricVariablesSetInput: z.ZodObject<{
     name: z.ZodString;
-    branch: z.ZodString;
+    branch: z.ZodOptional<z.ZodString>;
     value: z.ZodString;
 }, z.core.$strip>;
 export declare const FabricVariablesSetOutput: z.ZodObject<{
@@ -10,22 +10,22 @@ export declare const FabricVariablesSetOutput: z.ZodObject<{
 }, z.core.$strip>;
 export declare const FabricVariablesSet: import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionConfig<{
     name: string;
-    branch: string;
     value: string;
+    branch?: string | undefined;
 }, {
     name: string;
     success: boolean;
 }, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionSessionless<{
     name: string;
-    branch: string;
     value: string;
+    branch?: string | undefined;
 }, {
     name: string;
     success: boolean;
 }, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices, unknown> | import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunction<{
     name: string;
-    branch: string;
     value: string;
+    branch?: string | undefined;
 }, {
     name: string;
     success: boolean;

package/dist/src/fabric/functions/variables-set.function.js

@@ -2,11 +2,11 @@ import { z } from 'zod';
 import { pikkuSessionlessFunc } from '../../../.pikku/function/index.js';
 import { resolveApiContext } from '../lib/config.js';
 import { getFabricRPC } from '../lib/http.js';
-import { resolveStageId } from '../lib/stage.js';
+import { resolveStage } from '../lib/stage.js';
 import { parseVariableValue } from '../lib/variable-value.js';
 export const FabricVariablesSetInput = z.object({
     name: z.string(),
-    branch: z.string(),
+    branch: z.string().optional(),
     value: z.string(),
 });
 export const FabricVariablesSetOutput = z.object({
@@ -17,14 +17,14 @@ export const FabricVariablesSet = pikkuSessionlessFunc({
     description: 'Set a stage-scoped variable — the deployed counterpart of a line in .env. Not a secret: the value is stored in plain form and is readable back.',
     input: FabricVariablesSetInput,
     output: FabricVariablesSetOutput,
-    func: async (_services, { name, branch, value }) => {
+    func: async (_services, { name, branch: requested, value }) => {
         const ctx = await resolveApiContext();
         if (!ctx.token)
             throw new Error('Not logged in. Run `pikku fabric login` first.');
         if (!ctx.projectId)
             throw new Error('No fabric project linked. Run `pikku fabric link` first.');
         const rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
-        const stageId = await resolveStageId(rpc, ctx.projectId, branch);
+        const { stageId, branch } = await resolveStage(rpc, ctx.projectId, requested);
         // Deliberately not sealed, and deliberately not prompted for. A variable is
         // configuration — a port, a URL, a feature switch — and treating it like a
         // secret would mean it could not be read back, which is most of the value of

package/dist/src/fabric/lib/blank-comments.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Replace every comment in a TypeScript/JavaScript source with spaces, keeping
+ * the string exactly as long and every newline where it was, so offsets and
+ * line numbers computed against the result still point at the real file.
+ *
+ * The checks that scan source text with a regex have to run over this first.
+ * Scanning raw text made prose executable: a sentence reading
+ *
+ *   // what separates "needs you" from "is fine" at a glance
+ *
+ * matched an import-specifier pattern and reported `is fine` as an undeclared
+ * dependency. Quotes are tracked rather than blanked, because the specifier a
+ * caller is looking for lives inside them.
+ *
+ * A regex literal holding `//` or an unpaired quote is not modelled — telling
+ * `/` as division from `/` as a regex needs the parser this deliberately is
+ * not. The failure mode is a blanked region, never a comment left readable.
+ */
+export declare function blankComments(source: string): string;
+/** 1-based line number of a character offset. */
+export declare function lineOfOffset(source: string, offset: number): number;

package/dist/src/fabric/lib/blank-comments.js

@@ -0,0 +1,71 @@
+/**
+ * Replace every comment in a TypeScript/JavaScript source with spaces, keeping
+ * the string exactly as long and every newline where it was, so offsets and
+ * line numbers computed against the result still point at the real file.
+ *
+ * The checks that scan source text with a regex have to run over this first.
+ * Scanning raw text made prose executable: a sentence reading
+ *
+ *   // what separates "needs you" from "is fine" at a glance
+ *
+ * matched an import-specifier pattern and reported `is fine` as an undeclared
+ * dependency. Quotes are tracked rather than blanked, because the specifier a
+ * caller is looking for lives inside them.
+ *
+ * A regex literal holding `//` or an unpaired quote is not modelled — telling
+ * `/` as division from `/` as a regex needs the parser this deliberately is
+ * not. The failure mode is a blanked region, never a comment left readable.
+ */
+export function blankComments(source) {
+    const out = source.split('');
+    const blank = (start, end) => {
+        for (let i = start; i < end && i < out.length; i++) {
+            if (out[i] !== '\n' && out[i] !== '\r')
+                out[i] = ' ';
+        }
+    };
+    let i = 0;
+    while (i < source.length) {
+        const ch = source[i];
+        const next = source[i + 1];
+        if (ch === '/' && next === '/') {
+            const end = source.indexOf('\n', i);
+            blank(i, end === -1 ? source.length : end);
+            i = end === -1 ? source.length : end;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            const close = source.indexOf('*/', i + 2);
+            const end = close === -1 ? source.length : close + 2;
+            blank(i, end);
+            i = end;
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === '`') {
+            i++;
+            while (i < source.length) {
+                if (source[i] === '\\') {
+                    i += 2;
+                    continue;
+                }
+                if (source[i] === ch) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        i++;
+    }
+    return out.join('');
+}
+/** 1-based line number of a character offset. */
+export function lineOfOffset(source, offset) {
+    let line = 1;
+    for (let i = 0; i < offset && i < source.length; i++) {
+        if (source[i] === '\n')
+            line++;
+    }
+    return line;
+}

package/dist/src/fabric/lib/blank-scenario-meta.d.ts

@@ -0,0 +1 @@
+export declare function blankScenarioMeta(source: string): string;

package/dist/src/fabric/lib/blank-scenario-meta.js

@@ -0,0 +1,110 @@
+/**
+ * Blank the `name`, `description` and `template` values declared directly on a
+ * `pikkuFeature` / `pikkuScenario` / `pikkuScenarioStep` object, keeping the
+ * source the same length so a later scan still reports real positions.
+ *
+ * Those three fields are Console meta — authored in the project's `locale`,
+ * describing the test to whoever reads the run — and are deliberately not the
+ * app's UI copy. The hardcoded-copy check flagged them anyway whenever a
+ * feature happened to be named after the screen it covers:
+ *
+ *   export const downloadsFeature = pikkuFeature({
+ *     name: 'Downloads',   → ✗ "Downloads" → nav__downloads | downloads__title
+ *
+ * and its advice — read the string from the app catalogue — would tie the
+ * Console's language to the product's, which is the opposite of what should
+ * happen. Complying with the rule that puts features in `*.scenario.ts` was
+ * what surfaced them, so the two rules disagreed: satisfying one created
+ * violations of the other.
+ *
+ * Only the top level of the object is blanked. `getByRole('button', { name:
+ * 'Speichern' })` nested inside a step is a selector built out of UI copy —
+ * exactly what the check exists to catch — and stays visible.
+ */
+const DECLARATIONS = [
+    'pikkuFeature',
+    'pikkuScenario',
+    'pikkuScenarioStep',
+    'pikkuPlatformScenarioStep',
+    'pikkuAddonScenarioStep',
+];
+const META_FIELDS = /^(name|description|template)$/;
+const QUOTES = new Set(["'", '"', '`']);
+/** Index just past the string literal opening at `start`, or -1. */
+function endOfString(src, start) {
+    const quote = src[start];
+    let i = start + 1;
+    while (i < src.length) {
+        if (src[i] === '\\') {
+            i += 2;
+            continue;
+        }
+        if (src[i] === quote)
+            return i + 1;
+        i++;
+    }
+    return -1;
+}
+export function blankScenarioMeta(source) {
+    const out = source.split('');
+    for (const decl of DECLARATIONS) {
+        const call = new RegExp(`\\b${decl}\\s*\\(`, 'g');
+        let m;
+        while ((m = call.exec(source))) {
+            let i = m.index + m[0].length;
+            while (i < source.length && /\s/.test(source[i]))
+                i++;
+            if (source[i] !== '{')
+                continue;
+            let depth = 0;
+            while (i < source.length) {
+                const ch = source[i];
+                if (QUOTES.has(ch)) {
+                    const end = endOfString(source, i);
+                    if (end === -1)
+                        break;
+                    i = end;
+                    continue;
+                }
+                if (ch === '{') {
+                    depth++;
+                    i++;
+                    continue;
+                }
+                if (ch === '}') {
+                    depth--;
+                    if (depth === 0)
+                        break;
+                    i++;
+                    continue;
+                }
+                if (depth === 1 && /[A-Za-z_$]/.test(ch)) {
+                    const key = /^[A-Za-z0-9_$]+/.exec(source.slice(i))[0];
+                    let j = i + key.length;
+                    while (j < source.length && /\s/.test(source[j]))
+                        j++;
+                    if (source[j] === ':' && META_FIELDS.test(key)) {
+                        j++;
+                        while (j < source.length && /\s/.test(source[j]))
+                            j++;
+                        if (QUOTES.has(source[j])) {
+                            const end = endOfString(source, j);
+                            if (end !== -1) {
+                                for (let k = j + 1; k < end - 1; k++) {
+                                    if (out[k] !== '\n' && out[k] !== '\r')
+                                        out[k] = ' ';
+                                }
+                                i = end;
+                                continue;
+                            }
+                        }
+                    }
+                    i += key.length;
+                    continue;
+                }
+                i++;
+            }
+        }
+    }
+    return out.join('');
+}

package/dist/src/fabric/lib/deployment.d.ts

@@ -118,4 +118,30 @@ export interface WaitOptions {
     now?: () => number;
 }
 export declare function waitForDeployment({ rpc, deploymentId, timeoutMs, approve, onEvent, sleep, now, }: WaitOptions): Promise<WaitResult>;
+/**
+ * The sha a deployment actually holds, or an error naming the disagreement.
+ *
+ * `deployByStageKind` does not always cut a new deployment: with one already
+ * parked at `suspended` for the branch, it attaches to that plan — pinned to
+ * whatever commit it was created at — and returns its id. The CLI then
+ * reported the sha it had been *asked* for, so `apply` printed
+ *
+ *   status: suspended   sha: 599439e6
+ *
+ * for a deployment `deploy list` showed pinned to `5bfe84c`, five commits
+ * above it. Passing `--ref` explicitly changed nothing; the argument was
+ * echoed back. Nothing shipped only because that plan timed out.
+ *
+ * The blast radius is bounded — a second command still publishes, and only a
+ * commit already on the branch can go out — but the failure mode is a rollback
+ * that silently does not roll back, and a rollback is reached for precisely
+ * when production is already wrong. So whatever `apply` reports as the ref is
+ * read from the deployment, and a disagreement is an error rather than a line
+ * of output nobody can tell from the truth.
+ */
+export declare function reconcileDeployedRef({ requested, actual, deploymentId, }: {
+    requested: string;
+    actual: string | null;
+    deploymentId: string;
+}): string;
 export {};

package/dist/src/fabric/lib/deployment.js

@@ -286,3 +286,38 @@ export async function waitForDeployment({ rpc, deploymentId, timeoutMs, approve,
         latest = await readDeploymentStatus(rpc, deploymentId);
     }
 }
+/**
+ * The sha a deployment actually holds, or an error naming the disagreement.
+ *
+ * `deployByStageKind` does not always cut a new deployment: with one already
+ * parked at `suspended` for the branch, it attaches to that plan — pinned to
+ * whatever commit it was created at — and returns its id. The CLI then
+ * reported the sha it had been *asked* for, so `apply` printed
+ *
+ *   status: suspended   sha: 599439e6
+ *
+ * for a deployment `deploy list` showed pinned to `5bfe84c`, five commits
+ * above it. Passing `--ref` explicitly changed nothing; the argument was
+ * echoed back. Nothing shipped only because that plan timed out.
+ *
+ * The blast radius is bounded — a second command still publishes, and only a
+ * commit already on the branch can go out — but the failure mode is a rollback
+ * that silently does not roll back, and a rollback is reached for precisely
+ * when production is already wrong. So whatever `apply` reports as the ref is
+ * read from the deployment, and a disagreement is an error rather than a line
+ * of output nobody can tell from the truth.
+ */
+export function reconcileDeployedRef({ requested, actual, deploymentId, }) {
+    if (!actual)
+        return requested;
+    if (actual === requested)
+        return actual;
+    const short = (sha) => sha.slice(0, 8);
+    throw new Error([
+        `Refusing to continue: deployment ${deploymentId} is pinned to ${short(actual)}, not the ${short(requested)} you asked for.`,
+        'A deployment already parked for this branch was attached to rather than a new one being cut,',
+        'so continuing would deploy a different commit than the one named.',
+        `Inspect it with \`pikku fabric deploy list --json\`, then either publish it deliberately with`,
+        `\`pikku fabric deploy apply --deployment-id ${deploymentId} --sync\` or dismiss it and re-run.`,
+    ].join('\n'));
+}

package/dist/src/fabric/lib/stage.d.ts

@@ -1,7 +1,23 @@
 import type { PikkuRPC } from '../sdk/pikku-rpc.gen.js';
+export interface ResolvedStage {
+    stageId: string;
+    branch: string;
+}
 /**
- * Resolve a stage UUID from (projectId, branch) via the `listStages` RPC.
- * The stageId-based read RPCs (listDeployments, listDeploymentWorkers,
+ * Resolve a stage from (projectId, branch) via the `listStages` RPC. The
+ * stageId-based read RPCs (listDeployments, listDeploymentWorkers,
  * getStageDatabaseSchema) need a UUID, but the CLI only knows the branch.
+ *
+ * `branch` is optional because it is optional in practice: nothing upstream
+ * guarantees the flag was passed, and interpolating what arrived produced
+ * `No stage for branch "undefined"` — an error naming the missing argument's
+ * value rather than saying the argument is missing, directly above a line
+ * listing the one stage it could have used. With exactly one stage there is
+ * nothing to disambiguate, so that stage is the answer.
+ *
+ * The branch comes back with the id so callers can name the stage they acted
+ * on rather than echoing the argument, which is `undefined` in exactly the
+ * case this function exists to handle.
  */
-export declare function resolveStageId(rpc: PikkuRPC, projectId: string, branch: string): Promise<string>;
+export declare function resolveStage(rpc: PikkuRPC, projectId: string, branch: string | undefined): Promise<ResolvedStage>;
+export declare function resolveStageId(rpc: PikkuRPC, projectId: string, branch: string | undefined): Promise<string>;

package/dist/src/fabric/lib/stage.js

@@ -1,14 +1,37 @@
 /**
- * Resolve a stage UUID from (projectId, branch) via the `listStages` RPC.
- * The stageId-based read RPCs (listDeployments, listDeploymentWorkers,
+ * Resolve a stage from (projectId, branch) via the `listStages` RPC. The
+ * stageId-based read RPCs (listDeployments, listDeploymentWorkers,
  * getStageDatabaseSchema) need a UUID, but the CLI only knows the branch.
+ *
+ * `branch` is optional because it is optional in practice: nothing upstream
+ * guarantees the flag was passed, and interpolating what arrived produced
+ * `No stage for branch "undefined"` — an error naming the missing argument's
+ * value rather than saying the argument is missing, directly above a line
+ * listing the one stage it could have used. With exactly one stage there is
+ * nothing to disambiguate, so that stage is the answer.
+ *
+ * The branch comes back with the id so callers can name the stage they acted
+ * on rather than echoing the argument, which is `undefined` in exactly the
+ * case this function exists to handle.
  */
-export async function resolveStageId(rpc, projectId, branch) {
+export async function resolveStage(rpc, projectId, branch) {
     const { stages } = await rpc.invoke('listStages', { projectId });
+    const known = stages.map((s) => s.branch);
+    if (!branch) {
+        const only = stages[0];
+        if (stages.length === 1 && only) {
+            return { stageId: only.stageId, branch: only.branch };
+        }
+        throw new Error(stages.length === 0
+            ? 'No stages deployed for this project yet — run `pikku fabric deploy apply --branch <branch>` first.'
+            : `--branch is required — this project has ${stages.length} stages: ${known.join(', ')}`);
+    }
     const stage = stages.find((s) => s.branch === branch);
     if (!stage) {
-        const known = stages.map((s) => s.branch).join(', ');
-        throw new Error(`No stage for branch "${branch}".${known ? ` Existing: ${known}` : ''}`);
+        throw new Error(`No stage for branch "${branch}".${known.length ? ` Existing: ${known.join(', ')}` : ''}`);
     }
-    return stage.stageId;
+    return { stageId: stage.stageId, branch: stage.branch };
+}
+export async function resolveStageId(rpc, projectId, branch) {
+    return (await resolveStage(rpc, projectId, branch)).stageId;
 }