@pikku/cli 0.12.152 → 0.12.153

package/dist/src/fabric/functions/validate.function.d.ts

@@ -1,4 +1,16 @@
 import { z } from 'zod';
+declare const FindingSchema: z.ZodObject<{
+    id: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+    }>;
+    message: z.ZodString;
+    path: z.ZodString;
+    fixHint: z.ZodString;
+}, z.core.$strip>;
+type Finding = z.infer<typeof FindingSchema>;
 export declare const FabricValidateInput: z.ZodObject<{
     skipTypecheck: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
@@ -17,6 +29,27 @@ export declare const FabricValidateOutput: z.ZodObject<{
         fixHint: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/** One stage's record of what it has applied, as the control plane holds it. */
+export interface StageLedger {
+    stageId: string;
+    branch: string;
+    migrations: Array<{
+        name: string;
+        hash: string | null;
+        appliedAt: string;
+    }>;
+}
+/** Same digest the stage migrator records: sha256 of the file's bytes as UTF-8. */
+export declare function hashMigration(sql: string): string;
+/**
+ * Compares what each stage applied against the files in the repo now. Split
+ * out from the RPC call so the comparison is testable without a session.
+ *
+ * A row whose `hash` is null was applied before the stage migrator recorded
+ * hashes; the file it named is unrecoverable, so it is reported as unverified
+ * rather than as clean.
+ */
+export declare function migrationDriftFindings(migrationsDir: string, local: Map<string, string>, stages: StageLedger[]): Finding[];
 export declare function runValidate(startDir?: string, opts?: {
     skipTypecheck?: boolean;
 }): Promise<z.infer<typeof FabricValidateOutput>>;
@@ -58,3 +91,4 @@ export declare const FabricValidate: import("../../../.pikku/function/pikku-func
     }[];
 }, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices, unknown>, undefined, undefined>;
 export declare const renderValidate: (_s: unknown, { ok, root, findings }: z.infer<typeof FabricValidateOutput>) => void;
+export {};

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { readFile, readdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { createRequire } from 'node:module';
@@ -10,6 +11,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 { resolveApiContext } from '../lib/config.js';
+import { getFabricRPC } from '../lib/http.js';
 import { blankComments, lineOfOffset } from '../lib/blank-comments.js';
 import { blankScenarioMeta } from '../lib/blank-scenario-meta.js';
 const FindingSchema = z.object({
@@ -202,6 +205,105 @@ const POSTGRES_SQL_PATTERNS = [
     { re: /\bTSVECTOR\b/i, label: 'TSVECTOR' },
     { re: /\bARRAY\s*\[/i, label: 'ARRAY[…]' },
 ];
+/** Same digest the stage migrator records: sha256 of the file's bytes as UTF-8. */
+export function hashMigration(sql) {
+    return createHash('sha256').update(sql, 'utf-8').digest('hex');
+}
+const slug = (s) => s.replace(/[^a-z0-9]/gi, '-');
+/**
+ * Compares what each stage applied against the files in the repo now. Split
+ * out from the RPC call so the comparison is testable without a session.
+ *
+ * A row whose `hash` is null was applied before the stage migrator recorded
+ * hashes; the file it named is unrecoverable, so it is reported as unverified
+ * rather than as clean.
+ */
+export function migrationDriftFindings(migrationsDir, local, stages) {
+    const findings = [];
+    let unverifiable = 0;
+    for (const stage of stages) {
+        for (const applied of stage.migrations) {
+            const localHash = local.get(applied.name);
+            if (localHash === undefined) {
+                findings.push({
+                    id: `migration-applied-file-missing-${slug(stage.branch)}-${slug(applied.name)}`,
+                    severity: 'error',
+                    message: `${applied.name} was applied to the "${stage.branch}" stage but no longer exists locally`,
+                    path: join(migrationsDir, applied.name),
+                    fixHint: 'Restore the file under its original name. Deleting or renaming an applied migration does not undo it — the stage keeps the schema that file produced, and a fresh database will never reach that shape.',
+                });
+                continue;
+            }
+            if (applied.hash === null) {
+                unverifiable++;
+                continue;
+            }
+            if (applied.hash !== localHash) {
+                findings.push({
+                    id: `migration-drift-${slug(stage.branch)}-${slug(applied.name)}`,
+                    severity: 'error',
+                    message: `${applied.name} differs from the copy applied to the "${stage.branch}" stage (applied ${applied.hash.slice(0, 12)}, local ${localHash.slice(0, 12)})`,
+                    path: join(migrationsDir, applied.name),
+                    fixHint: [
+                        'Revert the file to what was applied and put the change in a NEW',
+                        'numbered migration. A migration is recorded by filename and never',
+                        're-runs, so this edit will never reach that stage — the next',
+                        'migration that depends on it fails there instead.',
+                    ].join('\n'),
+                });
+            }
+        }
+    }
+    if (unverifiable > 0) {
+        findings.push({
+            id: 'migration-drift-partially-unverifiable',
+            severity: 'info',
+            message: `${unverifiable} applied migration${unverifiable === 1 ? '' : 's'} predate hash recording and cannot be compared`,
+            path: migrationsDir,
+            fixHint: 'Nothing to do — rows written before the stage migrator recorded hashes carry none. Each deploy records hashes for what it applies.',
+        });
+    }
+    return findings;
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Silent when the project is unlinked or logged out — both already have their
+ * own findings — and degrades to an info when the API cannot be reached, so an
+ * offline developer still gets the rest of validate.
+ */
+async function checkMigrationDrift(root, migrationsDir) {
+    if (!existsSync(migrationsDir))
+        return [];
+    const ctx = await resolveApiContext({ startDir: root }).catch(() => null);
+    if (!ctx?.token || !ctx.projectId || !UUID.test(ctx.projectId))
+        return [];
+    let stages;
+    try {
+        const rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
+        const res = await rpc.invoke('listStageMigrationLedger', {
+            projectId: ctx.projectId,
+        });
+        stages = res.stages;
+    }
+    catch (err) {
+        return [
+            {
+                id: 'migration-drift-unchecked',
+                severity: 'info',
+                message: `could not read the deployed migration ledger (${err instanceof Error ? err.message : String(err)}) — local migrations were not compared against any stage`,
+                path: migrationsDir,
+                fixHint: 'Run `pikku fabric login` if the session expired. Offline this check is skipped, and the deploy plan catches drift instead.',
+            },
+        ];
+    }
+    const local = new Map();
+    for (const file of (await readdir(migrationsDir)).filter((f) => f.endsWith('.sql'))) {
+        const sql = await readTextSafe(join(migrationsDir, file));
+        if (sql !== null)
+            local.set(file, hashMigration(sql));
+    }
+    return migrationDriftFindings(migrationsDir, local, stages);
+}
 export async function runValidate(startDir = process.cwd(), opts = {}) {
     const root = await findProjectRoot(startDir);
     const findings = [];
@@ -760,6 +862,22 @@ export async function runValidate(startDir = process.cwd(), opts = {}) {
                 // readdir failure — skip
             }
         }
+        // ── migrations already applied to a stage must not be edited ─────────
+        // A stage records a migration by filename and never runs it again, so an
+        // edit to an applied file silently never reaches that schema: the stage
+        // keeps the shape the original file produced while the repo, local dev
+        // and CI all agree on the new one. CI cannot catch it — it migrates a
+        // throwaway empty database, where every file is pending — and the deploy
+        // risk gate only reads the SQL text, never the stage. It surfaces as the
+        // NEXT migration failing on a column that exists everywhere but there.
+        //
+        // The comparison is against the control plane's record of what each stage
+        // applied (hash included since @pikkufabric 2026-09), not against the
+        // stage database, which may be asleep and cannot be woken just to answer
+        // a local lint. Every stage of the project is checked, not just the one
+        // you are about to push: the case this is for is merging a branch that
+        // edited a migration another stage already ran.
+        findings.push(...(await checkMigrationDrift(root, migrationsDir)));
         // ── 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

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

@@ -79,4 +79,5 @@ export interface ResolvedApiContext {
  */
 export declare function resolveApiContext(opts?: {
     apiUrlOverride?: string;
+    startDir?: string;
 }): Promise<ResolvedApiContext>;

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

@@ -98,7 +98,7 @@ export async function writeAuthFile(file) {
  * Token comes from ~/.fabric/auth.json keyed by the resolved api-url.
  */
 export async function resolveApiContext(opts = {}) {
-    const projectFile = await findProjectConfig();
+    const projectFile = await findProjectConfig(opts.startDir);
     const apiUrl = opts.apiUrlOverride ??
         projectFile?.config.apiUrl ??
         process.env.FABRIC_API_URL ??

package/dist/src/functions/commands/dev-address.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Where a running `pikku dev` says it ended up.
+ *
+ * The port a dev server announces is not the port it was asked for: `--port 0`
+ * asks the OS for one, and a busy 3000 is the ordinary case on a machine that is
+ * already running something. Everything downstream — a scenario run, a frontend
+ * proxy, a person reading their own terminal — then targets the configured port
+ * and gets a connection refused that looks like a broken app.
+ *
+ * It lives in the runtime directory rather than the generated one because it is
+ * state about a process, not an artifact of codegen, and it is meaningless the
+ * moment that process is gone.
+ */
+export interface DevAddress {
+    apiUrl: string;
+    pid: number;
+    startedAt: string;
+}
+export declare const writeDevAddress: (runtimeDir: string, apiUrl: string) => void;
+export declare const clearDevAddress: (runtimeDir: string) => void;
+/**
+ * The address only if the process that wrote it is still alive — a dev server
+ * killed with SIGKILL, or one whose machine rebooted, never got to clear it, and
+ * a stale address is worse than none. Signal 0 checks liveness without sending
+ * anything; EPERM means a process owns that id, so it counts as alive.
+ */
+export declare const readDevAddress: (runtimeDir: string) => DevAddress | null;

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

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+const addressPath = (runtimeDir) => join(runtimeDir, 'dev-address.json');
+export const writeDevAddress = (runtimeDir, apiUrl) => {
+    const path = addressPath(runtimeDir);
+    mkdirSync(dirname(path), { recursive: true });
+    const address = {
+        apiUrl,
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    };
+    writeFileSync(path, `${JSON.stringify(address, null, 2)}\n`, 'utf8');
+};
+export const clearDevAddress = (runtimeDir) => {
+    rmSync(addressPath(runtimeDir), { force: true });
+};
+/**
+ * The address only if the process that wrote it is still alive — a dev server
+ * killed with SIGKILL, or one whose machine rebooted, never got to clear it, and
+ * a stale address is worse than none. Signal 0 checks liveness without sending
+ * anything; EPERM means a process owns that id, so it counts as alive.
+ */
+export const readDevAddress = (runtimeDir) => {
+    const path = addressPath(runtimeDir);
+    if (!existsSync(path))
+        return null;
+    let address;
+    try {
+        address = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof address?.apiUrl !== 'string' || typeof address?.pid !== 'number') {
+        return null;
+    }
+    try {
+        process.kill(address.pid, 0);
+    }
+    catch (error) {
+        if (error.code !== 'EPERM')
+            return null;
+    }
+    return address;
+};

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

@@ -25,6 +25,7 @@ import { resolveDevEnvironmentName } from './environment.js';
 import { createDevAgentRunner } from './dev-agent-runner.js';
 import { resolveConsoleMount } from './serve-console.js';
 import { serverReadyLine } from '../../server/server-ready.js';
+import { clearDevAddress, writeDevAddress } from './dev-address.js';
 import { createEphemeralContentSigningJWT } from '../../server/content-signing-jwt.js';
 import { enableDevActorSignIn } from '../../server/actor-sign-in.js';
 import { resolvePersonas } from '../../utils/resolve-personas.js';
@@ -364,6 +365,10 @@ export const dev = pikkuSessionlessFunc({
             logger.info(`Frontend not served in dev — run your frontend dev server and proxy its API calls to http://${hostname}:${boundPort}`);
         }
         logger.info(serverReadyLine(hostname, boundPort));
+        // Written from the bound port, so anything that has to find this server later
+        // reads where it actually is rather than where it was asked to be.
+        writeDevAddress(resolvedRuntimeDir, `http://${hostname}:${boundPort}`);
+        process.once('exit', () => clearDevAddress(resolvedRuntimeDir));
         let watcher;
         process.once('SIGINT', async () => {
             logger.info('Stopping dev server...');
@@ -375,6 +380,7 @@ export const dev = pikkuSessionlessFunc({
                 await lifecycle?.afterStop?.(resolvedServices);
             }
             finally {
+                clearDevAddress(resolvedRuntimeDir);
                 process.exit(0);
             }
         });

package/dist/src/functions/commands/environment.d.ts

@@ -44,6 +44,14 @@ export interface ResolveEnvironmentOptions {
     /** `--spawn`, which is only coherent against a local `apiUrl`. */
     spawn?: boolean;
 }
+/**
+ * Whether a resolved URL names a server on this machine.
+ *
+ * The gate for anything the runner does to a target directly rather than
+ * through its API — reaching into its database, for one. A remote host is
+ * somebody else's data whatever the config asked for.
+ */
+export declare const isLocalUrl: (value: string) => boolean;
 /**
  * Applied once, so actors, step env, the browser driver and the spawned server
  * all see the same target. The environment is still looked up by name: the

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

@@ -14,6 +14,21 @@ const LOCAL_HOSTNAMES = new Set([
     '::1',
     '[::1]',
 ]);
+/**
+ * Whether a resolved URL names a server on this machine.
+ *
+ * The gate for anything the runner does to a target directly rather than
+ * through its API — reaching into its database, for one. A remote host is
+ * somebody else's data whatever the config asked for.
+ */
+export const isLocalUrl = (value) => {
+    try {
+        return LOCAL_HOSTNAMES.has(new URL(value).hostname);
+    }
+    catch {
+        return false;
+    }
+};
 /**
  * Absolute URLs only: the value is concatenated with paths (`${apiUrl}/rpc`)
  * and parsed by the spawn path, so a relative one fails far from its cause.

package/dist/src/functions/commands/examples.d.ts

@@ -0,0 +1,170 @@
+import { renderExamplesAdd, renderExamplesList, renderExamplesShow } from '../examples/render.js';
+export declare const examplesList: import("#pikku/function").PikkuFunctionConfig<{
+    group?: string | undefined;
+}, {
+    examples: {
+        name: string;
+        title: string;
+        when: string;
+        lang: string;
+        entity: string;
+        deferUntil: string;
+    }[];
+}, "rpc" | "session", import("#pikku/function").PikkuFunction<{
+    group?: string | undefined;
+}, {
+    examples: {
+        name: string;
+        title: string;
+        when: string;
+        lang: string;
+        entity: string;
+        deferUntil: string;
+    }[];
+}, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<{
+    group?: string | undefined;
+}, {
+    examples: {
+        name: string;
+        title: string;
+        when: string;
+        lang: string;
+        entity: string;
+        deferUntil: string;
+    }[];
+}, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;
+export declare const examplesShow: import("#pikku/function").PikkuFunctionConfig<{
+    name: string;
+    entity?: string | undefined;
+}, {
+    found: boolean;
+    name: string;
+    title: string;
+    when: string;
+    source: string;
+    steps: string;
+    code: string;
+    notes: {
+        anchor: string | null;
+        lines: string[];
+    }[];
+    available: string[];
+}, "rpc" | "session", import("#pikku/function").PikkuFunction<{
+    name: string;
+    entity?: string | undefined;
+}, {
+    found: boolean;
+    name: string;
+    title: string;
+    when: string;
+    source: string;
+    steps: string;
+    code: string;
+    notes: {
+        anchor: string | null;
+        lines: string[];
+    }[];
+    available: string[];
+}, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<{
+    name: string;
+    entity?: string | undefined;
+}, {
+    found: boolean;
+    name: string;
+    title: string;
+    when: string;
+    source: string;
+    steps: string;
+    code: string;
+    notes: {
+        anchor: string | null;
+        lines: string[];
+    }[];
+    available: string[];
+}, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;
+export declare const examplesAdd: import("#pikku/function").PikkuFunctionConfig<{
+    name: string;
+    entity?: string | undefined;
+    app?: string | undefined;
+}, {
+    ok: boolean;
+    name: string;
+    entity: string;
+    refusal: string;
+    written: string[];
+    kept: string[];
+    failed: string[];
+    deferred: {
+        path: string;
+        tables: string[];
+    }[];
+    manual: string[];
+    api: {
+        path: string;
+        exports: string[];
+        declarations: string[];
+    }[];
+    when: string;
+    steps: string;
+    notes: {
+        anchor: string | null;
+        lines: string[];
+    }[];
+}, "rpc" | "session", import("#pikku/function").PikkuFunction<{
+    name: string;
+    entity?: string | undefined;
+    app?: string | undefined;
+}, {
+    ok: boolean;
+    name: string;
+    entity: string;
+    refusal: string;
+    written: string[];
+    kept: string[];
+    failed: string[];
+    deferred: {
+        path: string;
+        tables: string[];
+    }[];
+    manual: string[];
+    api: {
+        path: string;
+        exports: string[];
+        declarations: string[];
+    }[];
+    when: string;
+    steps: string;
+    notes: {
+        anchor: string | null;
+        lines: string[];
+    }[];
+}, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<{
+    name: string;
+    entity?: string | undefined;
+    app?: string | undefined;
+}, {
+    ok: boolean;
+    name: string;
+    entity: string;
+    refusal: string;
+    written: string[];
+    kept: string[];
+    failed: string[];
+    deferred: {
+        path: string;
+        tables: string[];
+    }[];
+    manual: string[];
+    api: {
+        path: string;
+        exports: string[];
+        declarations: string[];
+    }[];
+    when: string;
+    steps: string;
+    notes: {
+        anchor: string | null;
+        lines: string[];
+    }[];
+}, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;
+export { renderExamplesAdd, renderExamplesList, renderExamplesShow };

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

@@ -0,0 +1,28 @@
+import { pikkuSessionlessFunc } from '#pikku/function';
+import { ExamplesAddInputSchema, ExamplesAddOutputSchema, ExamplesListInputSchema, ExamplesListOutputSchema, ExamplesShowInputSchema, ExamplesShowOutputSchema, } from '../examples/command-schemas.js';
+import { runExamplesAdd, runExamplesList, runExamplesShow, } from '../examples/run.js';
+import { renderExamplesAdd, renderExamplesList, renderExamplesShow, } from '../examples/render.js';
+const projectOf = (config) => ({
+    rootDir: config.rootDir,
+    outDir: config.outDir,
+    srcDirectories: config.srcDirectories,
+});
+export const examplesList = pikkuSessionlessFunc({
+    description: 'List the worked examples this CLI ships — one per thing that is easy to get wrong and hard to discover',
+    input: ExamplesListInputSchema,
+    output: ExamplesListOutputSchema,
+    func: async (_services, input) => runExamplesList(input?.group),
+});
+export const examplesShow = pikkuSessionlessFunc({
+    description: 'Print one example, renamed onto your own entity, with everything the recipe says about itself',
+    input: ExamplesShowInputSchema,
+    output: ExamplesShowOutputSchema,
+    func: async ({ config }, input) => runExamplesShow(projectOf(config), input.name, input.entity),
+});
+export const examplesAdd = pikkuSessionlessFunc({
+    description: 'Write one example into this project, already named for your entity, or say what is in the way and write nothing',
+    input: ExamplesAddInputSchema,
+    output: ExamplesAddOutputSchema,
+    func: async ({ config }, input) => runExamplesAdd(projectOf(config), input.name, input.entity, input.app),
+});
+export { renderExamplesAdd, renderExamplesList, renderExamplesShow };