@pikku/cli 0.12.114 → 0.12.116

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

@@ -4,15 +4,30 @@ import { resolveApiContext } from '../lib/config.js';
 import { getFabricRPC } from '../lib/http.js';
 import { assertNamedBranchDeploySafety, resolveRef } from '../lib/git.js';
 import { promptConfirm } from '../lib/prompt.js';
-import { added, changed, dim } from '../lib/output.js';
+import { added, changed, removed, dim, table } from '../lib/output.js';
+import { blockedReason, blockedSummary, changesAreEmpty, classifyStatus, describeDeployment, destructiveMigrations, isApprovable, readDeploymentStatus, readWorkers, stateLabel, waitForDeployment, } from '../lib/deployment.js';
+const DEFAULT_TIMEOUT_SECONDS = 900;
 export const FabricDeployInput = z.object({
     branch: z.string().optional(),
     production: z.boolean().optional(),
     ref: z.string().optional(),
-    message: z.string().optional(),
-    autoApply: z.boolean().optional(),
+    deploymentId: z.string().optional(),
+    sync: z.boolean().optional(),
+    autoApprove: z.boolean().optional(),
+    allowDestructive: z.boolean().optional(),
+    timeout: z.number().optional(),
+    json: z.boolean().optional(),
 });
 export const FabricDeployValidatedInput = FabricDeployInput.superRefine((value, ctx) => {
+    if (value.deploymentId) {
+        if (value.branch || value.production) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: '--deployment-id already names its target — drop --branch/--production.',
+            });
+        }
+        return;
+    }
     if (!!value.branch === !!value.production) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
@@ -20,28 +35,58 @@ export const FabricDeployValidatedInput = FabricDeployInput.superRefine((value,
         });
     }
 });
-// `plan` resolves the target ref and reports what a deploy would do — nothing
-// is queued, so there is no deploymentId/stageId/runId yet. `apply` carries
-// those once the deploy is queued. The two intentionally have distinct shapes
-// rather than one shape padded with empty-string sentinels.
-export const FabricDeployPlanOutput = z.object({
-    projectId: z.string(),
-    branch: z.string(),
-    ref: z.string(),
-    requestedRef: z.string().optional(),
+const MissingConfig = z.object({
+    name: z.string(),
+    displayName: z.string().nullable(),
+    description: z.string().nullable(),
+    docsUrl: z.string().nullable(),
+});
+const Changes = z.object({
+    unitsAdded: z.array(z.string()),
+    unitsRemoved: z.array(z.string()),
+    handlersAdded: z.array(z.string()),
+    handlersRemoved: z.array(z.string()),
+    workflowsAdded: z.array(z.string()),
+    workflowsRemoved: z.array(z.string()),
+    workflowsChanged: z.array(z.string()),
+    functionsAdded: z.array(z.string()),
+    functionsRemoved: z.array(z.string()),
+    secretsChanged: z.array(z.string()),
+    variablesChanged: z.array(z.string()),
+    pendingMigrations: z.array(z.string()),
+    migrationRisks: z.array(z.object({
+        name: z.string(),
+        level: z.enum(['destructive', 'safe']),
+        reasons: z.array(z.string()),
+    })),
 });
 export const FabricDeployApplyOutput = z.object({
+    event: z.literal('result'),
+    outcome: z.enum(['queued', 'succeeded', 'failed', 'blocked', 'timeout']),
     projectId: z.string(),
-    branch: z.string(),
-    ref: z.string(),
     deploymentId: z.string(),
-    stageId: z.string(),
-    runId: z.string(),
+    branch: z.string().optional(),
+    ref: z.string().optional(),
+    status: z.string().optional(),
+    statusReason: z.string().nullable().optional(),
+    stageId: z.string().optional(),
+    runId: z.string().optional(),
+    blockedReason: z
+        .enum(['awaiting_approval', 'needs_config', 'needs_attention', 'unknown'])
+        .optional(),
+    missingSecrets: z.array(MissingConfig).optional(),
+    missingVariables: z.array(MissingConfig).optional(),
+    approvalWithheld: z.literal('destructive_migrations').optional(),
+    changes: Changes.optional(),
+    workers: z
+        .array(z.object({ name: z.string(), role: z.string(), status: z.string() }))
+        .optional(),
+    url: z.string().nullable().optional(),
+    approved: z.boolean().optional(),
+    elapsedMs: z.number().optional(),
+    timeoutSeconds: z.number().optional(),
 });
 /**
- * Shared prep for `deploy plan` and `deploy apply`: authenticate, resolve the
- * target branch, and resolve the ref to a concrete sha. Returns everything both
- * subcommands need; neither prints — human output lives in the renders.
  */
 async function prepDeploy({ branch, production, ref }) {
     const ctx = await resolveApiContext();
@@ -60,69 +105,271 @@ async function prepDeploy({ branch, production, ref }) {
     const targetBranch = production ? 'main' : branch;
     const safety = await assertNamedBranchDeploySafety(targetBranch);
     const resolved = ref ? ((await resolveRef(ref)) ?? ref) : safety.headSha;
-    const requestedRef = ref && resolved !== safety.headSha ? ref : undefined;
-    return {
-        ctx,
-        projectId: ctx.projectId,
-        targetBranch,
-        resolved,
-        requestedRef,
-        safety,
-    };
+    return { ctx, projectId: ctx.projectId, targetBranch, resolved, safety };
 }
-export const FabricDeployPlan = pikkuSessionlessFunc({
-    description: 'Resolve the target ref and report what a deploy would do.',
-    input: FabricDeployValidatedInput,
-    output: FabricDeployPlanOutput,
-    func: async (_services, input) => {
-        const { projectId, targetBranch, resolved, requestedRef } = await prepDeploy(input);
-        return { projectId, branch: targetBranch, ref: resolved, requestedRef };
-    },
-});
+async function prepAttach() {
+    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.');
+    }
+    return { ctx, projectId: ctx.projectId };
+}
+const EXIT_BY_OUTCOME = {
+    queued: 0,
+    succeeded: 0,
+    failed: 2,
+    blocked: 3,
+    timeout: 4,
+};
 export const FabricDeployApply = pikkuSessionlessFunc({
-    description: 'Build + deploy a named branch or production (main).',
+    description: 'Build + deploy a named branch or production (main), or attach to an existing deployment.',
     input: FabricDeployValidatedInput,
     output: FabricDeployApplyOutput,
     func: async (_services, input) => {
-        const { ctx, projectId, targetBranch, resolved, safety } = await prepDeploy(input);
-        // Classic yes/no guard. `--auto-apply` skips it; a non-interactive session
-        // has no human to answer, so we refuse rather than hang.
-        if (!input.autoApply) {
-            const target = `${targetBranch} @ ${resolved.slice(0, 8)}`;
-            if (!process.stdin.isTTY) {
-                throw new Error(`Refusing to deploy ${target} without confirmation — re-run with --auto-apply to deploy non-interactively.`);
-            }
-            const ok = await promptConfirm(`Deploy ${target}?`);
-            if (!ok) {
-                throw new Error('Deploy aborted.');
+        const emit = input.json
+            ? (event) => console.log(JSON.stringify(event))
+            : () => { };
+        const timeoutSeconds = input.timeout ?? DEFAULT_TIMEOUT_SECONDS;
+        if (timeoutSeconds <= 0) {
+            throw new Error('--timeout must be a positive number of seconds.');
+        }
+        if (input.deploymentId && (input.branch || input.production)) {
+            throw new Error('--deployment-id already names its target — drop --branch/--production.');
+        }
+        const attaching = Boolean(input.deploymentId);
+        let projectId;
+        let deploymentId;
+        let branch;
+        let ref;
+        let stageId;
+        let runId;
+        let rpc;
+        if (attaching) {
+            const { ctx, projectId: id } = await prepAttach();
+            projectId = id;
+            rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
+            deploymentId = input.deploymentId;
+            const current = await readDeploymentStatus(rpc, deploymentId);
+            stageId = current.stageId;
+            branch = (await describeDeployment(rpc, projectId, deploymentId))?.branch;
+            emit({ event: 'attached', deploymentId, status: current.status });
+        }
+        else {
+            const { ctx, projectId: id, targetBranch, resolved, safety, } = await prepDeploy(input);
+            projectId = id;
+            branch = targetBranch;
+            ref = resolved;
+            rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
+            if (!input.autoApprove) {
+                const target = `${branch} @ ${resolved.slice(0, 8)}`;
+                if (!process.stdin.isTTY) {
+                    throw new Error(`Refusing to deploy ${target} without confirmation — re-run with --auto-approve to deploy non-interactively.`);
+                }
+                if (!(await promptConfirm(`Deploy ${target}?`))) {
+                    throw new Error('Deploy aborted.');
+                }
             }
+            const created = await rpc.invoke('deployByStageKind', {
+                projectId,
+                branch,
+                ref: resolved,
+                expectedHeadSha: safety.headSha,
+            });
+            deploymentId = created.deploymentId;
+            stageId = created.stageId;
+            runId = created.runId;
+            emit({ event: 'created', deploymentId, branch, ref: resolved });
         }
-        const rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
-        const result = await rpc.invoke('deployByStageKind', {
+        const base = {
+            event: 'result',
             projectId,
-            branch: targetBranch,
-            ref: resolved,
-            expectedHeadSha: safety.headSha,
+            deploymentId,
+            branch,
+            ...(ref ? { ref } : {}),
+            ...(stageId ? { stageId } : {}),
+            ...(runId ? { runId } : {}),
+        };
+        if (!input.sync && !attaching) {
+            return { ...base, outcome: 'queued' };
+        }
+        let approvalWithheld;
+        const approveGate = async (status) => {
+            const described = await describeDeployment(rpc, projectId, deploymentId);
+            const destructive = destructiveMigrations(described?.changes);
+            if (destructive.length > 0 && !input.allowDestructive) {
+                if (input.autoApprove || input.json || !process.stdin.isTTY) {
+                    approvalWithheld = 'destructive_migrations';
+                    return false;
+                }
+            }
+            else if (input.autoApprove) {
+                return true;
+            }
+            if (input.json || !process.stdin.isTTY)
+                return false;
+            const warning = destructive.length > 0
+                ? `\n${destructiveLines(destructive).join('\n')}\n`
+                : '';
+            return promptConfirm(`Plan for ${branch ?? deploymentId} is ready to publish (${stateLabel(status.status, status.statusReason)}).${warning} Approve?`);
+        };
+        if (!input.sync) {
+            const status = await readDeploymentStatus(rpc, deploymentId);
+            const klass = classifyStatus(status.status);
+            const outcome = klass === 'in_flight' ? 'queued' : klass;
+            const finished = await finalise(rpc, projectId, deploymentId, status.stageId, outcome);
+            process.exitCode = EXIT_BY_OUTCOME[outcome];
+            return {
+                ...base,
+                outcome,
+                status: status.status,
+                statusReason: status.statusReason,
+                url: status.hostname ? `https://${status.hostname}` : null,
+                ...(outcome === 'blocked'
+                    ? {
+                        blockedReason: blockedReason(status.statusReason),
+                        missingSecrets: status.missingSecrets,
+                        missingVariables: status.missingVariables,
+                    }
+                    : {}),
+                ...finished,
+            };
+        }
+        const waited = await waitForDeployment({
+            rpc,
+            deploymentId,
+            timeoutMs: timeoutSeconds * 1000,
+            approve: approveGate,
+            onEvent: emit,
         });
+        const finished = await finalise(rpc, projectId, deploymentId, waited.stageId, waited.outcome);
+        process.exitCode = EXIT_BY_OUTCOME[waited.outcome];
         return {
-            projectId,
-            branch: targetBranch,
-            ref: resolved,
-            deploymentId: result.deploymentId,
-            stageId: result.stageId,
-            runId: result.runId,
+            ...base,
+            outcome: waited.outcome,
+            status: waited.status,
+            statusReason: waited.statusReason,
+            approved: waited.approved,
+            elapsedMs: waited.elapsedMs,
+            url: waited.hostname ? `https://${waited.hostname}` : null,
+            ...(waited.outcome === 'timeout' ? { timeoutSeconds } : {}),
+            ...(waited.outcome === 'blocked'
+                ? {
+                    blockedReason: waited.reason ?? 'unknown',
+                    missingSecrets: waited.missingSecrets,
+                    missingVariables: waited.missingVariables,
+                    ...(approvalWithheld ? { approvalWithheld } : {}),
+                }
+                : {}),
+            ...finished,
         };
     },
 });
-export const renderDeployPlan = (_s, { projectId, branch, ref, requestedRef, }) => {
-    if (requestedRef) {
-        console.log(dim(`retargeted ${requestedRef} → ${ref.slice(0, 8)}`));
+async function finalise(rpc, projectId, deploymentId, stageId, outcome) {
+    const out = {};
+    if (outcome === 'queued')
+        return out;
+    const described = await describeDeployment(rpc, projectId, deploymentId);
+    if (described?.changes)
+        out.changes = described.changes;
+    if (outcome === 'succeeded') {
+        out.workers = await readWorkers(rpc, stageId);
     }
-    console.log(`${changed('plan')} ${dim('would deploy')} ${branch} ${dim('@')} ${ref.slice(0, 8)} ${dim(`(${projectId})`)}`);
-    // The coloured added/changed/removed manifest diff lands here once `plan`
-    // returns it from the preview workflow.
-    console.log(dim('Run `pikku fabric deploy apply` to execute.'));
+    return out;
+}
+const shortList = (names, limit = 8) => names.length <= limit
+    ? names.join(', ')
+    : `${names.slice(0, limit).join(', ')} +${names.length - limit} more`;
+const destructiveLines = (risks) => risks.map((r) => `  ${removed('! destructive')} ${r.name}${r.reasons.length > 0 ? dim(` (${r.reasons.join(', ')})`) : ''}`);
+const changeLines = (changes) => {
+    if (!changes || changesAreEmpty(changes))
+        return [];
+    const lines = [];
+    const add = (label, names, colour) => {
+        if (names.length > 0)
+            lines.push(`  ${colour(label)} ${shortList(names)}`);
+    };
+    add('+ units', changes.unitsAdded, added);
+    add('- units', changes.unitsRemoved, removed);
+    add('+ handlers', changes.handlersAdded, added);
+    add('- handlers', changes.handlersRemoved, removed);
+    add('+ functions', changes.functionsAdded, added);
+    add('- functions', changes.functionsRemoved, removed);
+    add('+ workflows', changes.workflowsAdded, added);
+    add('- workflows', changes.workflowsRemoved, removed);
+    add('~ workflows', changes.workflowsChanged, changed);
+    add('~ secrets', changes.secretsChanged, changed);
+    add('~ variables', changes.variablesChanged, changed);
+    add('~ migrations', changes.pendingMigrations, changed);
+    lines.push(...destructiveLines(destructiveMigrations(changes)));
+    return lines;
+};
+const missingLines = (label, entries) => {
+    if (!entries || entries.length === 0)
+        return [];
+    return [
+        `  ${removed(label)}`,
+        ...entries.map((e) => `    ${e.name}${e.displayName ? dim(` (${e.displayName})`) : ''}${e.docsUrl ? dim(` — ${e.docsUrl}`) : ''}`),
+    ];
 };
-export const renderDeployApply = (_s, { branch, ref, deploymentId }) => {
-    console.log(`${added('queued')} deploy ${branch} ${dim('@')} ${ref.slice(0, 8)} ${dim('·')} ${deploymentId}`);
+const reattachHint = (deploymentId) => dim(`Re-attach with \`pikku fabric deploy apply --deployment-id ${deploymentId} --sync\`.`);
+export const renderDeployApply = (_s, result) => {
+    const { outcome, branch, ref, deploymentId, status, statusReason, changes, workers, url, elapsedMs, timeoutSeconds, approved, } = result;
+    const where = branch ?? 'deployment';
+    const at = ref ? ` ${dim('@')} ${ref.slice(0, 8)}` : '';
+    const took = elapsedMs === undefined ? '' : dim(` in ${Math.round(elapsedMs / 1000)}s`);
+    if (outcome === 'queued') {
+        console.log(`${added('queued')} deploy ${where}${at} ${dim('·')} ${deploymentId}`);
+        if (status) {
+            console.log(dim(`status ${stateLabel(status, statusReason ?? null)}`));
+        }
+        console.log(reattachHint(deploymentId));
+        return;
+    }
+    if (outcome === 'succeeded') {
+        console.log(`${added('deployed')} ${where}${at} ${dim('·')} ${deploymentId}${took}`);
+        for (const line of changeLines(changes))
+            console.log(line);
+        if (workers && workers.length > 0) {
+            console.log(table(['WORKER', 'ROLE', 'STATUS'], workers.map((w) => [w.name, w.role, w.status])));
+        }
+        if (url)
+            console.log(dim(url));
+        return;
+    }
+    if (outcome === 'blocked') {
+        const reason = result.blockedReason ?? 'unknown';
+        console.log(`${changed(stateLabel(status ?? 'suspended', statusReason ?? null))} ${where}${at} ${dim('·')} ${deploymentId}`);
+        console.log(dim(blockedSummary(reason)));
+        for (const line of missingLines('missing secrets', result.missingSecrets)) {
+            console.log(line);
+        }
+        for (const line of missingLines('missing variables', result.missingVariables)) {
+            console.log(line);
+        }
+        for (const line of changeLines(changes))
+            console.log(line);
+        if (result.approvalWithheld === 'destructive_migrations') {
+            console.log(dim('The plan drops or rewrites data. Nothing was published — review the migrations above, then re-run with `--allow-destructive` to accept them.'));
+            console.log(dim(`\`pikku fabric deploy apply --deployment-id ${deploymentId} --sync --auto-approve --allow-destructive\``));
+        }
+        else if (isApprovable(reason) && !approved) {
+            console.log(dim(`Approve it with \`pikku fabric deploy apply --deployment-id ${deploymentId} --sync --auto-approve\`.`));
+        }
+        else if (reason === 'needs_config') {
+            console.log(dim('Set the values with `pikku fabric secrets set <name>`.'));
+        }
+        return;
+    }
+    if (outcome === 'timeout') {
+        console.log(`${changed('timed out')} after ${timeoutSeconds}s ${dim('·')} ${deploymentId} ${dim(`(still ${status ?? 'in flight'})`)}`);
+        console.log(reattachHint(deploymentId));
+        console.log(dim('Raise the ceiling with `--timeout <seconds>`.'));
+        return;
+    }
+    console.log(`${removed('failed')} ${where}${at} ${dim('·')} ${deploymentId}${took} ${dim(`(${stateLabel(status ?? 'failed', statusReason ?? null)})`)}`);
+    if (branch)
+        console.log(dim(`Logs: \`pikku fabric logs --branch ${branch}\``));
 };

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

@@ -38,6 +38,7 @@ export const FabricInit = pikkuSessionlessFunc({
             repoUrl: repo,
             name,
             defaultBranch: branch,
+            productionBranch: 'main',
         });
         const path = await writeProjectConfig(process.cwd(), {
             projectId: result.projectId,

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

@@ -57,7 +57,10 @@ export const FabricLink = pikkuSessionlessFunc({
                 }
             }
         }
-        const project = await rpc.invoke('importProject', { repoUrl: remoteUrl });
+        const project = await rpc.invoke('importProject', {
+            repoUrl: remoteUrl,
+            productionBranch: 'main',
+        });
         await writeProjectConfig(process.cwd(), {
             projectId: project.projectId,
             ...(apiUrlOverride ? { apiUrl: apiUrlOverride } : {}),

package/dist/src/fabric/functions/secrets-rotate.function.d.ts

@@ -4,21 +4,21 @@ export declare const FabricSecretsRotateInput: z.ZodObject<{
     force: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const FabricSecretsRotateOutput: z.ZodObject<{
-    retiredKeyId: z.ZodString;
+    retiredKeyId: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export declare const FabricSecretsRotate: import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionConfig<{
     branch: string;
     force?: boolean | undefined;
 }, {
-    retiredKeyId: string;
+    retiredKeyId: string | null;
 }, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionSessionless<{
     branch: string;
     force?: boolean | undefined;
 }, {
-    retiredKeyId: string;
+    retiredKeyId: string | null;
 }, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices, unknown> | import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunction<{
     branch: string;
     force?: boolean | undefined;
 }, {
-    retiredKeyId: string;
+    retiredKeyId: string | null;
 }, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices>, undefined, undefined>;

package/dist/src/fabric/functions/secrets-rotate.function.js

@@ -8,7 +8,7 @@ export const FabricSecretsRotateInput = z.object({
     force: z.boolean().optional(),
 });
 export const FabricSecretsRotateOutput = z.object({
-    retiredKeyId: z.string(),
+    retiredKeyId: z.string().nullable(),
 });
 export const FabricSecretsRotate = pikkuSessionlessFunc({
     description: "Retire a stage's sealing key so the next deploy issues a new one. Secrets sealed to the old key must be set again.",
@@ -31,6 +31,6 @@ export const FabricSecretsRotate = pikkuSessionlessFunc({
         const result = await rpc.invoke('rotateStageSealingKey', { stageId });
         console.log(`[fabric] retired sealing key ${result.retiredKeyId} on ${branch}`);
         console.log('[fabric] deploy the stage to issue a new key, then set its secrets again');
-        return result;
+        return { retiredKeyId: result.retiredKeyId };
     },
 });

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

@@ -811,6 +811,71 @@ export async function runValidate(startDir = process.cwd(), opts = {}) {
             declaredFrontends.push({ slug, cwd: rel, dir, deploy: deploy !== false });
         }
     }
+    const LOCALHOST_URL_RE = /['"`](?:https?|wss?):\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0)(?::\d+)?[^'"`]*['"`]/;
+    const ENV_FALLBACK_RE = /(?:import\.meta\.env|process\.env)\s*(?:\.\w+|\[\s*['"][^'"]+['"]\s*\])\s*(?:\?\?|\|\|)\s*['"`](?:https?|wss?):\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0)/;
+    const API_ENV_READ_RE = /(?:import\.meta\.env|process\.env)\s*(?:\.(\w*(?:API|BACKEND|SERVER)\w*)|\[\s*['"](\w*(?:API|BACKEND|SERVER)\w*)['"]\s*\])/g;
+    for (const fe of declaredFrontends) {
+        if (!fe.deploy)
+            continue;
+        const files = [
+            ...(await listSourceFiles(join(fe.dir, 'src'))),
+            ...(await listSourceFiles(join(fe.dir, 'app'))),
+            ...(await listSourceFiles(join(fe.dir, 'pages'))),
+        ];
+        const envFallbackHits = [];
+        const bareHits = [];
+        const apiEnvHits = [];
+        const apiEnvNames = new Set();
+        let derivesOrigin = false;
+        for (const file of files) {
+            const rel = file.slice(fe.dir.length + 1).replace(/\\/g, '/');
+            if (/\.(test|spec)\.[jt]sx?$/.test(rel) ||
+                rel.endsWith('.d.ts') ||
+                /(?:^|\/)(?:__tests__|__mocks__)\//.test(rel)) {
+                continue;
+            }
+            const text = await readTextSafe(file);
+            if (!text)
+                continue;
+            if (/\blocation\s*\.\s*origin\b/.test(text))
+                derivesOrigin = true;
+            for (const raw of text.split('\n')) {
+                const line = raw.trim();
+                if (line.startsWith('//') ||
+                    line.startsWith('*') ||
+                    line.startsWith('/*')) {
+                    continue;
+                }
+                API_ENV_READ_RE.lastIndex = 0;
+                let m;
+                while ((m = API_ENV_READ_RE.exec(line)) !== null) {
+                    apiEnvNames.add((m[1] ?? m[2]));
+                    if (!apiEnvHits.includes(rel))
+                        apiEnvHits.push(rel);
+                }
+                if (ENV_FALLBACK_RE.test(line)) {
+                    if (!envFallbackHits.includes(rel))
+                        envFallbackHits.push(rel);
+                }
+                else if (LOCALHOST_URL_RE.test(line)) {
+                    if (!bareHits.includes(rel))
+                        bareHits.push(rel);
+                }
+            }
+        }
+        const sample = (hits) => hits.slice(0, 5).join(', ') +
+            (hits.length > 5 ? `, +${hits.length - 5} more` : '');
+        const originFix = lines('Derive the base from the page instead of from a variable nobody sets:', '', '  const configured = import.meta.env.VITE_API_URL', '  const remote = !/^(localhost|127\\.0\\.0\\.1)$/.test(window.location.hostname)', '  // a localhost base served from a real origin is a stray dev value', '  if (configured && !(remote && /\\/\\/(localhost|127\\.0\\.0\\.1)(:|\\/)/.test(configured))) {', '    return configured', '  }', "  return window.location.origin + '/api'", '', 'Fabric serves the app and the API on one hostname and routes /api/* to', 'the API units, so the derived value is correct on every stage, preview', 'and custom domain. Guard the `window` read for SSR.');
+        if (envFallbackHits.length > 0) {
+            e(`frontend-env-fallback-localhost-${fe.slug}`, `frontend "${fe.slug}" defaults a build-time env read to a localhost URL (${sample(envFallbackHits)}) — the deploy sets no VITE_*/NEXT_PUBLIC_* variable at build time, so that fallback is what the production bundle ships and every call from a browser will time out`, fe.dir, originFix);
+        }
+        else if (apiEnvHits.length > 0 && !derivesOrigin) {
+            e(`frontend-api-base-not-derived-${fe.slug}`, `frontend "${fe.slug}" takes its API base from ${[...apiEnvNames].sort().join(', ')} (${sample(apiEnvHits)}) and never derives it from the page origin — fabric binds VITE_API_URL on the deployed Worker at runtime, so the build inlines nothing and whatever follows the read is what ships`, fe.dir, originFix);
+        }
+        if (bareHits.length > 0 && !derivesOrigin) {
+            e(`frontend-localhost-url-${fe.slug}`, `frontend "${fe.slug}" hardcodes a localhost URL (${sample(bareHits)}) — unreachable from any deployed page`, fe.dir, originFix);
+        }
+    }
     // ── apps/ vs fabric.config.json frontends ─────────────────────────────
     const appsDir = join(root, 'apps');
     if (existsSync(appsDir)) {
@@ -1061,6 +1126,64 @@ export async function runValidate(startDir = process.cwd(), opts = {}) {
             }
         }
     }
+    // ── scenario steps must locate by i18n key, not rendered copy ──────────
+    // A browser step that says getByLabel('Full Name') passes only while the app
+    // happens to render the base locale, and a copy edit breaks it as a timeout
+    // on a selector — the failure points at the wizard rather than at the rename
+    // that caused it. Any literal in a step file that is verbatim a value in the
+    // base catalogue is that mistake: the catalogue already holds the string
+    // under a key the test can read. Comments are stripped first, because the
+    // prose around a step quotes the copy it is explaining.
+    {
+        const relFile = (p) => p.slice(root.length + 1).replace(/\\/g, '/');
+        const keysByValue = new Map();
+        const appsRoot = join(root, 'apps');
+        if (existsSync(appsRoot)) {
+            for (const ent of await readdir(appsRoot, { withFileTypes: true })) {
+                if (!ent.isDirectory())
+                    continue;
+                const appPath = join(appsRoot, ent.name);
+                const settings = await readJsonSafe(join(appPath, 'project.inlang', 'settings.json'));
+                if (!settings)
+                    continue;
+                const catalogue = await readJsonSafe(join(appPath, 'messages', `${settings.baseLocale ?? 'en'}.json`));
+                if (!catalogue)
+                    continue;
+                for (const [key, value] of Object.entries(catalogue)) {
+                    if (typeof value !== 'string' || value.trim().length < 2)
+                        continue;
+                    const owners = keysByValue.get(value) ?? [];
+                    owners.push(key);
+                    keysByValue.set(value, owners);
+                }
+            }
+        }
+        if (keysByValue.size > 0) {
+            const STRING_LITERAL = /(?<![A-Za-z0-9_$])(['"])((?:[^\\\n]|\\.){2,200}?)\1/g;
+            for (const file of await walkSourceFiles(root)) {
+                if (!/\.(steps|scenario)\.tsx?$/.test(file))
+                    continue;
+                const text = await readTextSafe(file);
+                if (!text)
+                    continue;
+                const code = text
+                    .replace(/\/\*[\s\S]*?\*\//g, '')
+                    .replace(/(^|[^:'"`\\])\/\/[^\n]*/g, '$1');
+                const hits = [];
+                for (const match of code.matchAll(STRING_LITERAL)) {
+                    const literal = match[2];
+                    if (!literal)
+                        continue;
+                    const keys = keysByValue.get(literal);
+                    if (keys)
+                        hits.push(`"${literal}" → ${keys.join(' | ')}`);
+                }
+                if (hits.length === 0)
+                    continue;
+                e(`scenario-hardcoded-copy-${relFile(file).replace(/[^a-z0-9]/gi, '-')}`, `${relFile(file)} hardcodes ${hits.length} string(s) the message catalogue already owns — the step passes only while the app renders the base locale, and a copy edit breaks it as an unexplained selector timeout`, file, lines('Read each string from the catalogue instead of repeating it:', ...hits.slice(0, 10).map((h) => `  - ${h}`), ...(hits.length > 10 ? [`  …and ${hits.length - 10} more`] : []), 'Type the lookup off the catalogue so a renamed key is a compile error:', "  import type messages from '<app>/messages/<baseLocale>.json'", '  export type MessageKey = keyof typeof messages'));
+            }
+        }
+    }
     // ── packages/theme + packages/components ──────────────────────────────
     const designDocUrl = 'https://pikkufabric.dev/docs/design';
     const designSeverity = hasMantineFrontend ? w : info;