@pikku/cli 0.12.151 → 0.12.153

package/dist/src/fabric/fabric-commands.d.ts

@@ -1130,6 +1130,43 @@ export declare const fabricCommands: {
                 thread: any;
                 stageUrl: string | null;
             }, "rpc" | "session", import("../../.pikku/function/pikku-function-types.gen.js").WiredServices, unknown>, undefined, undefined>, import("../../.pikku/middleware/pikku-middleware-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
+            file: import("@pikku/core/cli").CoreCLICommandConfig<import("../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionConfig<{
+                apiUrl?: string | undefined;
+                projectId?: string | undefined;
+                stageId?: string | undefined;
+                branch?: string | undefined;
+                title: string;
+                body?: string | undefined;
+                bodyFile?: string | undefined;
+                route?: string | undefined;
+                locale?: string | undefined;
+            }, {
+                change: any;
+            }, "rpc" | "session", import("../../.pikku/function/pikku-function-types.gen.js").PikkuFunction<{
+                apiUrl?: string | undefined;
+                projectId?: string | undefined;
+                stageId?: string | undefined;
+                branch?: string | undefined;
+                title: string;
+                body?: string | undefined;
+                bodyFile?: string | undefined;
+                route?: string | undefined;
+                locale?: string | undefined;
+            }, {
+                change: any;
+            }, "rpc" | "session", import("../../.pikku/function/pikku-function-types.gen.js").WiredServices> | import("../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionSessionless<{
+                apiUrl?: string | undefined;
+                projectId?: string | undefined;
+                stageId?: string | undefined;
+                branch?: string | undefined;
+                title: string;
+                body?: string | undefined;
+                bodyFile?: string | undefined;
+                route?: string | undefined;
+                locale?: string | undefined;
+            }, {
+                change: any;
+            }, "rpc" | "session", import("../../.pikku/function/pikku-function-types.gen.js").WiredServices, unknown>, undefined, undefined>, import("../../.pikku/middleware/pikku-middleware-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
             claim: import("@pikku/core/cli").CoreCLICommandConfig<import("../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionConfig<{
                 apiUrl?: string | undefined;
                 projectId?: string | undefined;

package/dist/src/fabric/fabric-commands.js

@@ -45,6 +45,7 @@ import { FabricDomainsRemove } from './functions/domains-remove.function.js';
 import { FabricLLMKey, renderLLMKey } from './functions/llm-key.function.js';
 import { FabricChangesList, renderChangesList, } from './functions/changes-list.function.js';
 import { FabricChangesShow, renderChangesShow, } from './functions/changes-show.function.js';
+import { FabricChangesFile, renderChangesFile, } from './functions/changes-file.function.js';
 import { FabricChangesClaim, renderChangesClaim, } from './functions/changes-claim.function.js';
 import { FabricChangesAsk, renderChangesAsk, } from './functions/changes-ask.function.js';
 import { FabricChangesShot, renderChangesShot, } from './functions/changes-shot.function.js';
@@ -482,7 +483,7 @@ export const fabricCommands = defineCLICommands({
         },
     },
     changes: {
-        description: 'The todo list filed from inside a deployed stage: read what is open, claim a batch, ask what you need to know, and tick items off',
+        description: 'The todo list filed from inside a deployed stage: read what is open, file what was decided elsewhere, claim a batch, ask what you need to know, and tick items off',
         subcommands: {
             list: pikkuCLICommand({
                 func: FabricChangesList,
@@ -524,6 +525,36 @@ export const fabricCommands = defineCLICommands({
                     apiUrl: { description: 'Override the fabric-api URL for this call' },
                 },
             }),
+            file: pikkuCLICommand({
+                func: FabricChangesFile,
+                render: renderChangesFile,
+                description: 'File an item from outside the panel — the words, without the screenshot the panel would have attached',
+                options: {
+                    projectId: {
+                        description: 'Project to file against (defaults to the linked checkout)',
+                        short: 'p',
+                    },
+                    stageId: {
+                        description: 'Stage to file against (defaults to the only stage)',
+                    },
+                    branch: {
+                        description: 'Resolve the stage from this branch instead',
+                    },
+                    title: {
+                        description: 'The requirement, in one line',
+                        short: 't',
+                    },
+                    body: { description: 'The detail, if a line is not enough' },
+                    bodyFile: {
+                        description: 'Read the body from a file — use this when it has newlines',
+                    },
+                    route: {
+                        description: 'The route it is about, e.g. /admin/rota',
+                    },
+                    locale: { description: 'Locale it was seen in, e.g. de' },
+                    apiUrl: { description: 'Override the fabric-api URL for this call' },
+                },
+            }),
             claim: pikkuCLICommand({
                 func: FabricChangesClaim,
                 render: renderChangesClaim,

package/dist/src/fabric/functions/changes-file.function.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import type { CreateChangeOutput } from '../sdk/rpc-map.gen.d.js';
+export declare const FabricChangesFileInput: z.ZodObject<{
+    apiUrl: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
+    stageId: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    bodyFile: z.ZodOptional<z.ZodString>;
+    route: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const FabricChangesFileOutput: z.ZodObject<{
+    change: z.ZodAny;
+}, z.core.$strip>;
+/**
+ * An item filed from a terminal carries no screenshot, no circled elements and
+ * no build — the panel supplies those and nothing here can invent them. What it
+ * does carry is the words, which the skill already treats as the requirement
+ * and every other address as evidence, so a written item is a thinner but not a
+ * malformed one.
+ *
+ * `--body-file` because a real item's body is a paragraph with newlines in it,
+ * and putting that through shell quoting is where it gets mangled.
+ */
+export declare const FabricChangesFile: import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionConfig<{
+    apiUrl?: string | undefined;
+    projectId?: string | undefined;
+    stageId?: string | undefined;
+    branch?: string | undefined;
+    title: string;
+    body?: string | undefined;
+    bodyFile?: string | undefined;
+    route?: string | undefined;
+    locale?: string | undefined;
+}, {
+    change: any;
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunction<{
+    apiUrl?: string | undefined;
+    projectId?: string | undefined;
+    stageId?: string | undefined;
+    branch?: string | undefined;
+    title: string;
+    body?: string | undefined;
+    bodyFile?: string | undefined;
+    route?: string | undefined;
+    locale?: string | undefined;
+}, {
+    change: any;
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices> | import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionSessionless<{
+    apiUrl?: string | undefined;
+    projectId?: string | undefined;
+    stageId?: string | undefined;
+    branch?: string | undefined;
+    title: string;
+    body?: string | undefined;
+    bodyFile?: string | undefined;
+    route?: string | undefined;
+    locale?: string | undefined;
+}, {
+    change: any;
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices, unknown>, undefined, undefined>;
+export declare const renderChangesFile: (_s: unknown, { change }: CreateChangeOutput) => void;

package/dist/src/fabric/functions/changes-file.function.js

@@ -0,0 +1,56 @@
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { pikkuSessionlessFunc } from '../../../.pikku/function/index.js';
+import { changesContext, requireProjectId } from '../lib/changes.js';
+import { resolveStageId } from '../lib/stage.js';
+import { dim, safe } from '../lib/output.js';
+export const FabricChangesFileInput = z.object({
+    apiUrl: z.string().optional(),
+    projectId: z.string().optional(),
+    stageId: z.string().optional(),
+    branch: z.string().optional(),
+    title: z.string().trim().min(1, 'Give the item a title.'),
+    body: z.string().optional(),
+    bodyFile: z.string().optional(),
+    route: z.string().optional(),
+    locale: z.string().optional(),
+});
+export const FabricChangesFileOutput = z.object({
+    change: z.any(),
+});
+/**
+ * An item filed from a terminal carries no screenshot, no circled elements and
+ * no build — the panel supplies those and nothing here can invent them. What it
+ * does carry is the words, which the skill already treats as the requirement
+ * and every other address as evidence, so a written item is a thinner but not a
+ * malformed one.
+ *
+ * `--body-file` because a real item's body is a paragraph with newlines in it,
+ * and putting that through shell quoting is where it gets mangled.
+ */
+export const FabricChangesFile = pikkuSessionlessFunc({
+    description: 'File a change against a stage from outside the panel.',
+    input: FabricChangesFileInput,
+    output: FabricChangesFileOutput,
+    func: async (_services, input) => {
+        if (input.body && input.bodyFile)
+            throw new Error('Pass --body or --body-file, not both.');
+        const { rpc, projectId } = await changesContext(input.apiUrl, input.projectId);
+        const stageId = input.stageId ??
+            (await resolveStageId(rpc, requireProjectId(projectId), input.branch));
+        const body = input.bodyFile
+            ? await readFile(input.bodyFile, 'utf8')
+            : input.body;
+        return await rpc.invoke('createChange', {
+            stageId,
+            title: input.title,
+            body: body?.trim() || undefined,
+            route: input.route,
+            locale: input.locale,
+        });
+    },
+});
+export const renderChangesFile = (_s, { change }) => {
+    console.log(`Filed #${safe(change.shortId)}  ${safe(change.title)}`);
+    console.log(dim(`  ${safe(change.changeId)}`));
+};

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.