@owlmeans/viable-sdk 0.1.18-rc.1

package/build/executor/boot-check.d.ts

@@ -0,0 +1,73 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { TargetHealthReading } from './health.js';
+/**
+ * Boot the generated backend for real, in isolation, and report what happened.
+ *
+ * `tsc` cannot see a foreign key that names a resource nothing registers: the reference is a
+ * string in an AJV schema, and it is resolved while the OwlMeans context initializes. So a story
+ * can type-check, be stamped complete, and leave a backend that dies at boot — which is exactly
+ * what happened, because the only real boot in the pipeline ran AFTER the story was accepted.
+ *
+ * It runs the real thing, but never the live one: a second process, on its own port, against a
+ * scratch schema, killed on every exit path.
+ */
+/** How far the boot got. `ready` is the only success. */
+export type BootCheckPhase = 'build' | 'schema' | 'boot' | 'ready';
+export interface BootCheckReport {
+    ok: boolean;
+    phase: BootCheckPhase;
+    /** The classifier's reason plus the captured startup log, or null when the boot succeeded. */
+    error: string | null;
+    dbOk?: boolean;
+}
+export interface BootCheckDeps {
+    port: number;
+    /** Argv marker that tells this instance apart from the live one for process matching. */
+    marker: string;
+    cwd: string;
+    env: Record<string, string>;
+    bootId: string;
+    /** Omitted to reuse the artifacts already on disk. */
+    build?: () => Promise<string | null>;
+    readHealth?: (port: number, bootId: string, timeoutMs: number) => Promise<TargetHealthReading>;
+    spawn?: typeof nodeSpawn;
+    ddlWindowMs?: number;
+    readyWindowMs?: number;
+    readyPollMs?: number;
+    /** Whole-run cap, so a wedged boot cannot outlive the caller's deadline. */
+    timeoutMs?: number;
+}
+/**
+ * DELIBERATE DIFFERENCE from the publisher: no `resetSchema` step, and therefore no `schema`
+ * failure of its own.
+ *
+ * A slot's check drops and recreates its scratch schema as the application role, which owns it. On
+ * a developer's machine the database is the DEVELOPER'S — the connector was handed a `DATABASE_URL`
+ * and nothing above it, it has no credential that may drop anything, and a platform that silently
+ * dropped a schema in a database it does not own would be destroying work it cannot restore. The
+ * check still runs under `DATABASE_SCHEMA=bootcheck`, so it never touches the app's namespace; it
+ * simply leaves what it created behind, and the next run reconciles into it.
+ */
+export declare const runBootCheck: (deps: BootCheckDeps) => Promise<BootCheckReport>;
+export interface BootCheckStatus {
+    running: boolean;
+    startedAt: number | null;
+    report: BootCheckReport | null;
+}
+export interface BootCheckJob {
+    /** Start a check, or join the one already running. `true` when this call started it. */
+    start: (run: () => Promise<BootCheckReport>) => boolean;
+    status: () => BootCheckStatus;
+    /** The running check, for the legacy blocking caller. */
+    pending: () => Promise<BootCheckReport> | null;
+}
+/**
+ * The job behind `BootCheck` / `BootCheckStatus`.
+ *
+ * The command STARTS a check and returns; the verdict is read separately. A boot is minutes of
+ * build and startup, and holding one request open for it made a fault indistinguishable from a
+ * hung agent for the whole of the caller's timeout. A second start joins the running check rather
+ * than spawning another instance onto the same port.
+ */
+export declare const createBootCheckJob: (watchdogMs?: number) => BootCheckJob;
+//# sourceMappingURL=boot-check.d.ts.map

package/build/executor/boot-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-check.d.ts","sourceRoot":"","sources":["../../src/executor/boot-check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAIvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAGtD;;;;;;;;;;GAUG;AAEH,yDAAyD;AACzD,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAA;AAElE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAA;IACX,KAAK,EAAE,cAAc,CAAA;IACrB,8FAA8F;IAC9F,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACpC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAA;IAC9F,KAAK,CAAC,EAAE,OAAO,SAAS,CAAA;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAID;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,SAAgB,aAAa,KAAG,OAAO,CAAC,eAAe,CA6F/E,CAAA;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,MAAM,EAAE,eAAe,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,wFAAwF;IACxF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,KAAK,OAAO,CAAA;IACvD,MAAM,EAAE,MAAM,eAAe,CAAA;IAC7B,yDAAyD;IACzD,OAAO,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAAA;CAC/C;AAWD;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,2BAA+B,YA2C7D,CAAA"}

package/build/executor/boot-check.js

@@ -0,0 +1,155 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { readTargetHealth } from './health.js';
+import { delay, killGroupAndWait, reclaimPort, waitForPortFree } from './spawn.js';
+const STARTUP_LOG_CAP = 16_384;
+/**
+ * DELIBERATE DIFFERENCE from the publisher: no `resetSchema` step, and therefore no `schema`
+ * failure of its own.
+ *
+ * A slot's check drops and recreates its scratch schema as the application role, which owns it. On
+ * a developer's machine the database is the DEVELOPER'S — the connector was handed a `DATABASE_URL`
+ * and nothing above it, it has no credential that may drop anything, and a platform that silently
+ * dropped a schema in a database it does not own would be destroying work it cannot restore. The
+ * check still runs under `DATABASE_SCHEMA=bootcheck`, so it never touches the app's namespace; it
+ * simply leaves what it created behind, and the next run reconciles into it.
+ */
+export const runBootCheck = async (deps) => {
+    const { port, marker, cwd, env, bootId, build, readHealth = readTargetHealth, spawn = nodeSpawn, ddlWindowMs = 10_000, readyWindowMs = 90_000, readyPollMs = 2_000, timeoutMs = 480_000, } = deps;
+    const deadline = Date.now() + timeoutMs;
+    let child = null;
+    let log = '';
+    const record = (chunk) => {
+        log = (log + chunk).slice(-STARTUP_LOG_CAP);
+    };
+    try {
+        if (build != null) {
+            const buildError = await build();
+            if (buildError != null)
+                return { ok: false, phase: 'build', error: buildError };
+        }
+        // Before the spawn, not only after it. The leftover this reclaims belongs to a run that never
+        // finished, so it is already holding the port by the time anything asks for a fresh check —
+        // and the target refuses to start on a taken port rather than stealing it, correctly.
+        if (!await waitForPortFree(port, 2_000))
+            await reclaimPort(port, marker);
+        child = spawn('bun', ['dist/index.js', marker], {
+            cwd,
+            detached: true,
+            shell: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, ...env, BACKEND_BOOT_ID: bootId },
+        });
+        child.stdout?.on('data', chunk => record(chunk.toString()));
+        child.stderr?.on('data', chunk => record(chunk.toString()));
+        let exited = false;
+        child.on('exit', () => { exited = true; });
+        child.on('error', error => record(`\n${String(error)}`));
+        // A structure or reference error takes the target down during init; that is what this window
+        // is for. A target that survives it may still be degraded, which is what the poll asks about.
+        const ddlDeadline = Date.now() + ddlWindowMs;
+        while (Date.now() < ddlDeadline && !exited) {
+            await delay(200);
+        }
+        if (exited) {
+            return { ok: false, phase: 'boot', error: `The target backend exited while initializing:\n${log}` };
+        }
+        const readyDeadline = Math.min(Date.now() + readyWindowMs, deadline);
+        let reason = 'The target backend did not become ready';
+        while (Date.now() < readyDeadline) {
+            if (exited) {
+                return { ok: false, phase: 'boot', error: `The target backend exited while initializing:\n${log}` };
+            }
+            const health = await readHealth(port, bootId, 2_000);
+            if (health.ready)
+                return { ok: true, phase: 'ready', error: null, dbOk: health.dbOk };
+            reason = health.reason;
+            // A self-reported failure is terminal — no point waiting out the window for a target that
+            // has already said it will not come up.
+            if (health.terminal) {
+                return { ok: false, phase: 'boot', error: `${reason}\n${log}`.trim(), dbOk: health.dbOk };
+            }
+            await delay(readyPollMs);
+        }
+        return { ok: false, phase: 'boot', error: `${reason}\n${log}`.trim() };
+    }
+    catch (e) {
+        return { ok: false, phase: 'boot', error: `Boot check failed to run: ${String(e)}\n${log}`.trim() };
+    }
+    finally {
+        // Unconditional: a validation instance left holding its port would fail every later check,
+        // and one left holding the database would be indistinguishable from the live backend.
+        if (child != null) {
+            try {
+                await killGroupAndWait(child);
+            }
+            catch {
+                // Already gone.
+            }
+        }
+        try {
+            // Reclaimed by MARKER when waiting is not enough: a connector killed mid-check leaves its
+            // detached child alive, and every later check then fails with the target's own "the api port
+            // is already in use" — which reads as a defect in the generated app rather than as a stray
+            // process from a run that never finished.
+            if (!await waitForPortFree(port))
+                await reclaimPort(port, marker);
+        }
+        catch {
+            // Nothing else to do — the next check reclaims by marker anyway.
+        }
+    }
+};
+/**
+ * Outer bound on one boot-check job.
+ *
+ * `runBootCheck` caps its own ready poll but not the build in front of it, so this is the only
+ * thing that guarantees a poller eventually reads `running: false` — a check that outlives it is
+ * abandoned, not awaited.
+ */
+const WATCHDOG_MS = 600_000;
+/**
+ * The job behind `BootCheck` / `BootCheckStatus`.
+ *
+ * The command STARTS a check and returns; the verdict is read separately. A boot is minutes of
+ * build and startup, and holding one request open for it made a fault indistinguishable from a
+ * hung agent for the whole of the caller's timeout. A second start joins the running check rather
+ * than spawning another instance onto the same port.
+ */
+export const createBootCheckJob = (watchdogMs = WATCHDOG_MS) => {
+    let promise = null;
+    let startedAt = null;
+    let last = null;
+    return {
+        start: run => {
+            if (promise != null)
+                return false;
+            startedAt = Date.now();
+            const job = run();
+            promise = job;
+            // The job owns its own completion: the starting request is already gone by then, so the
+            // report has to be parked where a status read can find it. A throw is a report too — a
+            // poller that never sees `running: false` waits out its whole deadline for nothing.
+            void job.then(report => { last = report; }, e => {
+                last = { ok: false, phase: 'boot', error: `Boot check failed to run: ${String(e)}` };
+            }).finally(() => {
+                if (promise === job)
+                    promise = null;
+            });
+            const watchdog = setTimeout(() => {
+                if (promise !== job)
+                    return;
+                promise = null;
+                last = {
+                    ok: false, phase: 'boot',
+                    error: `Boot check exceeded ${watchdogMs}ms and was abandoned`,
+                };
+            }, watchdogMs);
+            watchdog.unref?.();
+            void job.finally(() => clearTimeout(watchdog));
+            return true;
+        },
+        status: () => ({ running: promise != null, startedAt, report: last }),
+        pending: () => promise,
+    };
+};
+//# sourceMappingURL=boot-check.js.map

package/build/executor/boot-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-check.js","sourceRoot":"","sources":["../../src/executor/boot-check.ts"],"names":[],"mappings":"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"}

package/build/executor/env.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Runtime environment for the target's api and worker processes.
+ *
+ * Read at runtime, never baked into the bundle — the api resolves `DATABASE_URL`, `VALKEY_URL`
+ * and the OIDC triple when it boots, which is why a configure push that lands after a build still
+ * reaches it with nothing more than a restart.
+ */
+export declare const backendEnv: (dir: string) => Promise<Record<string, string>>;
+/**
+ * Build-time environment for the target's browser bundle.
+ *
+ * DELIBERATE DIFFERENCE from the publisher: `BACKEND_PORT` names the WEB port, not the api's.
+ * A slot serves the app and its `/api` from one hostname behind one TLS front door, so the
+ * publisher can leave the port blank and let the scheme imply it. A local run has two processes
+ * on two loopback ports, and the local server proxies `/api` precisely so the browser stays
+ * same-origin — pointing the bundle at 3000 instead would make every call cross-origin and put
+ * the target's CORS configuration in the path of a developer's first page load.
+ *
+ * Composed from the WEB package's own `.env` and never from the root one. The publisher has the
+ * same boundary as an allow-list (`frontendEnvVars` / `frontendSecrets`); here it is the file
+ * split, and it is what keeps `DATABASE_URL` and `OIDC_SECRET` out of a bundle every visitor
+ * downloads.
+ */
+export declare const frontendEnv: (dir: string) => Promise<Record<string, string>>;
+//# sourceMappingURL=env.d.ts.map

package/build/executor/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/executor/env.ts"],"names":[],"mappings":"AA0BA;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAAe,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiB5E,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,QAAe,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmB7E,CAAA"}

package/build/executor/env.js

@@ -0,0 +1,77 @@
+import { TARGET_API_BASE, TARGET_API_PORT, TARGET_WEB_PORT, TARGET_WORKER_PORT } from '@owlmeans/viable-common';
+import { readEnvFile, ROOT_ENV_FILE, webEnvFile } from '../project/env.js';
+/**
+ * The environment a locally-run target sees.
+ *
+ * Same tables the publisher composes for a pod, with two differences that follow from where this
+ * runs. The hosts are `localhost` — a loopback address, not a claimed preview hostname — and the
+ * VALUES come from the target's own `.env` files rather than from slot metadata, because on a
+ * developer's machine the platform provisions nothing: the database URL, the queue URL and the
+ * OIDC identity are lines in a file the developer and the configure push both write.
+ *
+ * The defaults are laid down first and the `.env` is overlaid on top, so a user who set a value
+ * gets the value they set. Callers that own a port — the boot check, the worker — spread their
+ * override over the result, exactly as the publisher does.
+ */
+/** Keys the frontend build injects on its own, so they are never announced as extras. */
+const FRONTEND_STANDARD_KEYS = new Set([
+    'FRONTEND_PORT', 'FRONTEND_HOST', 'BACKEND_HOST', 'BACKEND_PORT', 'BACKEND_BASE_URL',
+    'BASE_URL', 'FRONTEND_ENV_KEYS', 'SOURCEMAP',
+]);
+/**
+ * Runtime environment for the target's api and worker processes.
+ *
+ * Read at runtime, never baked into the bundle — the api resolves `DATABASE_URL`, `VALKEY_URL`
+ * and the OIDC triple when it boots, which is why a configure push that lands after a build still
+ * reaches it with nothing more than a restart.
+ */
+export const backendEnv = async (dir) => {
+    // The ROOT `.env` alone. The web package's file is compiled into a bundle anybody can read, so
+    // the two are never merged in either direction.
+    const values = await readEnvFile(dir, ROOT_ENV_FILE);
+    return {
+        BACKEND_PORT: `${TARGET_API_PORT}`,
+        BACKEND_HOST: 'localhost',
+        BACKEND_BASE_URL: TARGET_API_BASE,
+        FRONTEND_HOST: 'localhost',
+        FRONTEND_PORT: `${TARGET_WEB_PORT}`,
+        BASE_URL: '',
+        WORKER_PORT: `${TARGET_WORKER_PORT}`,
+        // The target's own values last: everything above is a default this machine can state without
+        // asking, and everything the user or a configure push wrote outranks it.
+        ...values,
+    };
+};
+/**
+ * Build-time environment for the target's browser bundle.
+ *
+ * DELIBERATE DIFFERENCE from the publisher: `BACKEND_PORT` names the WEB port, not the api's.
+ * A slot serves the app and its `/api` from one hostname behind one TLS front door, so the
+ * publisher can leave the port blank and let the scheme imply it. A local run has two processes
+ * on two loopback ports, and the local server proxies `/api` precisely so the browser stays
+ * same-origin — pointing the bundle at 3000 instead would make every call cross-origin and put
+ * the target's CORS configuration in the path of a developer's first page load.
+ *
+ * Composed from the WEB package's own `.env` and never from the root one. The publisher has the
+ * same boundary as an allow-list (`frontendEnvVars` / `frontendSecrets`); here it is the file
+ * split, and it is what keeps `DATABASE_URL` and `OIDC_SECRET` out of a bundle every visitor
+ * downloads.
+ */
+export const frontendEnv = async (dir) => {
+    const values = await readEnvFile(dir, webEnvFile(dir));
+    const env = {
+        FRONTEND_PORT: `${TARGET_WEB_PORT}`,
+        BACKEND_HOST: 'localhost',
+        BACKEND_PORT: `${TARGET_WEB_PORT}`,
+        BACKEND_BASE_URL: TARGET_API_BASE,
+        BASE_URL: '/',
+        ...values,
+    };
+    // What the target's bundler substitutes. A key absent from this list is not replaced at build
+    // time and reaches the browser as `process.env.X` against an object that does not exist there.
+    env.FRONTEND_ENV_KEYS = Object.keys(env)
+        .filter(key => !FRONTEND_STANDARD_KEYS.has(key))
+        .join(',');
+    return env;
+};
+//# sourceMappingURL=env.js.map

package/build/executor/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/executor/env.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,kBAAkB,EACtE,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE1E;;;;;;;;;;;;GAYG;AAEH,yFAAyF;AACzF,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC;IACrC,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB;IACpF,UAAU,EAAE,mBAAmB,EAAE,WAAW;CAC7C,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAAE,GAAW,EAAmC,EAAE;IAC/E,+FAA+F;IAC/F,gDAAgD;IAChD,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,aAAa,CAAC,CAAA;IAEpD,OAAO;QACL,YAAY,EAAE,GAAG,eAAe,EAAE;QAClC,YAAY,EAAE,WAAW;QACzB,gBAAgB,EAAE,eAAe;QACjC,aAAa,EAAE,WAAW;QAC1B,aAAa,EAAE,GAAG,eAAe,EAAE;QACnC,QAAQ,EAAE,EAAE;QACZ,WAAW,EAAE,GAAG,kBAAkB,EAAE;QACpC,6FAA6F;QAC7F,yEAAyE;QACzE,GAAG,MAAM;KACV,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,GAAW,EAAmC,EAAE;IAChF,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;IAEtD,MAAM,GAAG,GAA2B;QAClC,aAAa,EAAE,GAAG,eAAe,EAAE;QACnC,YAAY,EAAE,WAAW;QACzB,YAAY,EAAE,GAAG,eAAe,EAAE;QAClC,gBAAgB,EAAE,eAAe;QACjC,QAAQ,EAAE,GAAG;QACb,GAAG,MAAM;KACV,CAAA;IAED,8FAA8F;IAC9F,+FAA+F;IAC/F,GAAG,CAAC,iBAAiB,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;SACrC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,sBAAsB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;SAC/C,IAAI,CAAC,GAAG,CAAC,CAAA;IAEZ,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA"}

package/build/executor/errors.d.ts

@@ -0,0 +1,69 @@
+import type { TargetIntegrityReport } from '@owlmeans/viable-common';
+/**
+ * What the local executor throws, and why so little of it does.
+ *
+ * The publisher answers an ordinary command failure with a VALUE — error text in
+ * `SlotShellResult.result`, a report in the git answer — because the platform's remote helpers
+ * parse those shapes and a throw arrives as a transport failure with the diagnostics lost. The
+ * connector executes the same commands and is read by the same helpers, so it keeps that rule:
+ * everything here is for a condition the publisher ALSO throws on.
+ *
+ * Plain `Error` subclasses rather than `ResilientError` ones, for the same reason: these travel
+ * as an operation result the session marshals, and the publisher's equivalents are plain errors
+ * too — a class the platform has never seen would only widen what its catch has to know.
+ */
+/**
+ * A path that resolved outside the project directory.
+ *
+ * Never a user's fault — always a caller's bug. On a developer's machine the blast radius is
+ * their whole home directory rather than a pod's volume, which is the one thing about this guard
+ * that is stricter here than in the publisher.
+ */
+export declare class SandboxPathError extends Error {
+    readonly name = "SandboxPathError";
+    constructor(file: string);
+}
+/**
+ * A file command was asked for something it must refuse whatever the caller intended.
+ *
+ * Two conditions today, and both are about not destroying what is already there: a relocation into
+ * a directory that already holds files (the move would interleave two trees, and nothing
+ * afterwards could tell them apart), and a removal of the project root (which is `deleteProject`,
+ * a command with its own name and its own keep list).
+ *
+ * Thrown rather than answered, unlike the git refusals: those are policies a caller can plan
+ * around, and these two mean the caller's own arguments were wrong.
+ */
+export declare class FileCommandRefused extends Error {
+    readonly name = "FileCommandRefused";
+    constructor(message: string);
+}
+/**
+ * A revert was asked for on a tree with uncommitted work in it.
+ *
+ * Thrown rather than answered, exactly as the platform's git service does: `RevertTo` answers a
+ * commit, so there is no field in its shape that could carry a refusal, and silently reverting
+ * over a person's uncommitted edits is the one outcome this operation must never have.
+ */
+export declare class GitDirtyTree extends Error {
+    readonly name = "GitDirtyTree";
+    constructor(dir: string);
+}
+/** A git command failed in a way no answer shape can carry — an unresolvable hash, say. */
+export declare class LocalGitError extends Error {
+    readonly name = "LocalGitError";
+    constructor(message: string);
+}
+/**
+ * The tree is not the generated application.
+ *
+ * Raised only where a caller asked for a verdict it cannot express as text; every build and shell
+ * path returns {@link integrityRefusal} instead, because that is the channel a failed build
+ * already travels on.
+ */
+export declare class TargetIntegrityError extends Error {
+    readonly report: TargetIntegrityReport;
+    readonly name = "TargetIntegrityError";
+    constructor(report: TargetIntegrityReport);
+}
+//# sourceMappingURL=errors.d.ts.map

package/build/executor/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/executor/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAA;AAGpE;;;;;;;;;;;;GAYG;AAEH;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAyB,IAAI,sBAAqB;IAElD,YAAY,IAAI,EAAE,MAAM,EAEvB;CACF;AAED;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAyB,IAAI,wBAAuB;IAEpD,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAED;;;;;;GAMG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAyB,IAAI,kBAAiB;IAE9C,YAAY,GAAG,EAAE,MAAM,EAEtB;CACF;AAED,2FAA2F;AAC3F,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAyB,IAAI,mBAAkB;IAE/C,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAGjB,MAAM,EAAE,qBAAqB;IAFzD,SAAyB,IAAI,0BAAyB;IAEtD,YAA4B,MAAM,EAAE,qBAAqB,EAExD;CACF"}

package/build/executor/errors.js

@@ -0,0 +1,80 @@
+import { formatIntegrityReport } from '@owlmeans/viable-common';
+/**
+ * What the local executor throws, and why so little of it does.
+ *
+ * The publisher answers an ordinary command failure with a VALUE — error text in
+ * `SlotShellResult.result`, a report in the git answer — because the platform's remote helpers
+ * parse those shapes and a throw arrives as a transport failure with the diagnostics lost. The
+ * connector executes the same commands and is read by the same helpers, so it keeps that rule:
+ * everything here is for a condition the publisher ALSO throws on.
+ *
+ * Plain `Error` subclasses rather than `ResilientError` ones, for the same reason: these travel
+ * as an operation result the session marshals, and the publisher's equivalents are plain errors
+ * too — a class the platform has never seen would only widen what its catch has to know.
+ */
+/**
+ * A path that resolved outside the project directory.
+ *
+ * Never a user's fault — always a caller's bug. On a developer's machine the blast radius is
+ * their whole home directory rather than a pod's volume, which is the one thing about this guard
+ * that is stricter here than in the publisher.
+ */
+export class SandboxPathError extends Error {
+    name = 'SandboxPathError';
+    constructor(file) {
+        super(`Path escapes the sandbox: ${file}`);
+    }
+}
+/**
+ * A file command was asked for something it must refuse whatever the caller intended.
+ *
+ * Two conditions today, and both are about not destroying what is already there: a relocation into
+ * a directory that already holds files (the move would interleave two trees, and nothing
+ * afterwards could tell them apart), and a removal of the project root (which is `deleteProject`,
+ * a command with its own name and its own keep list).
+ *
+ * Thrown rather than answered, unlike the git refusals: those are policies a caller can plan
+ * around, and these two mean the caller's own arguments were wrong.
+ */
+export class FileCommandRefused extends Error {
+    name = 'FileCommandRefused';
+    constructor(message) {
+        super(message);
+    }
+}
+/**
+ * A revert was asked for on a tree with uncommitted work in it.
+ *
+ * Thrown rather than answered, exactly as the platform's git service does: `RevertTo` answers a
+ * commit, so there is no field in its shape that could carry a refusal, and silently reverting
+ * over a person's uncommitted edits is the one outcome this operation must never have.
+ */
+export class GitDirtyTree extends Error {
+    name = 'GitDirtyTree';
+    constructor(dir) {
+        super(`Working tree has uncommitted changes: ${dir}`);
+    }
+}
+/** A git command failed in a way no answer shape can carry — an unresolvable hash, say. */
+export class LocalGitError extends Error {
+    name = 'LocalGitError';
+    constructor(message) {
+        super(message);
+    }
+}
+/**
+ * The tree is not the generated application.
+ *
+ * Raised only where a caller asked for a verdict it cannot express as text; every build and shell
+ * path returns {@link integrityRefusal} instead, because that is the channel a failed build
+ * already travels on.
+ */
+export class TargetIntegrityError extends Error {
+    report;
+    name = 'TargetIntegrityError';
+    constructor(report) {
+        super(`The project in this directory is not a Viable application:\n${formatIntegrityReport(report)}`);
+        this.report = report;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/build/executor/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/executor/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAA;AAE/D;;;;;;;;;;;;GAYG;AAEH;;;;;;GAMG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChB,IAAI,GAAG,kBAAkB,CAAA;IAElD,YAAY,IAAY;QACtB,KAAK,CAAC,6BAA6B,IAAI,EAAE,CAAC,CAAA;IAC5C,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClB,IAAI,GAAG,oBAAoB,CAAA;IAEpD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;IAChB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACZ,IAAI,GAAG,cAAc,CAAA;IAE9C,YAAY,GAAW;QACrB,KAAK,CAAC,yCAAyC,GAAG,EAAE,CAAC,CAAA;IACvD,CAAC;CACF;AAED,2FAA2F;AAC3F,MAAM,OAAO,aAAc,SAAQ,KAAK;IACb,IAAI,GAAG,eAAe,CAAA;IAE/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;IAChB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAGjB,MAAM;IAFT,IAAI,GAAG,sBAAsB,CAAA;IAEtD,YAA4B,MAA6B;QACvD,KAAK,CAAC,+DAA+D,qBAAqB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;sBAD3E,MAAM;IAElC,CAAC;CACF"}

package/build/executor/files.d.ts

@@ -0,0 +1,124 @@
+import { SubProject } from '@owlmeans/viable-common';
+import type { StatTreeResult } from '@owlmeans/viable-common';
+/** What `readSource` and friends answer with — the shape the platform's file helpers parse. */
+export interface LocalSourceFile {
+    path: string;
+    code?: string;
+}
+export interface SourceListOptions {
+    skipUIElements?: boolean;
+    excludes?: string[];
+}
+/**
+ * The target's files, as the platform asks for them.
+ *
+ * Shaped exactly like the publisher's `createFileHelper`, because the caller is the same code:
+ * the agent's remote helper sends a `SlotFileCommand` and parses one of these answers, and it has
+ * no way to know whether a pod or a laptop produced it.
+ */
+export declare const createLocalFileHelper: (projectPath: string) => {
+    /**
+     * Wipe the project, keeping what the caller names and what is never ours to delete.
+     *
+     * The kept paths are project-relative and may be NESTED — `.agents/memory/history.md` is one
+     * the reinit pipeline passes, and `sources/web/.env` is one this helper adds itself. Matching
+     * them against top-level `readdir` names alone is what deleted the first: `.agents` matched
+     * nothing in the ignore set, so the whole harness tree went along with the one file the
+     * caller had explicitly asked to preserve — and nothing failed.
+     *
+     * So a directory is removed whole only when nothing kept lives under it; otherwise it is
+     * walked and pruned entry by entry.
+     */
+    emptyProject: (ignore?: string[]) => Promise<void>;
+    deleteProject: () => Promise<void>;
+    /**
+     * Finish an installed template: make sure the root manifest declares its workspaces.
+     *
+     * The agent pushes every template file itself, so this is only the finalizer. The workspace
+     * list is written only when the manifest does not already declare one — the template ships
+     * `["sources/*"]`, and injecting the explicit list beside it produced a manifest carrying the
+     * key TWICE, valid only because JSON keeps the last one.
+     */
+    initializeProject: () => Promise<void>;
+    getSourceList: (pattern?: string, options?: SourceListOptions) => Promise<string[]>;
+    getStructuredList: (patterns: string[]) => Promise<string[]>;
+    readFile: (path: string, notThrow?: boolean) => Promise<string>;
+    readSource: (filePath: string) => Promise<LocalSourceFile>;
+    readPossibleSource: (filePath: string) => Promise<LocalSourceFile>;
+    readSources: (files: string | string[]) => Promise<LocalSourceFile[]>;
+    writeFile: (filePath: string, content: string) => Promise<void>;
+    writeSource: (file: {
+        path: string;
+        code: string;
+    }) => Promise<void>;
+    deleteFile: (filePath: string, noThrow?: boolean) => Promise<void>;
+    /**
+     * The tree, one line per file, bounded.
+     *
+     * One command rather than a listing plus a read per entry: the caller is a census over a
+     * repository somebody else wrote, which may hold a hundred thousand files, and one round trip
+     * each — over a connector, on somebody's laptop — is not a slower walk but a walk that never
+     * finishes.
+     *
+     * `total` counts what the walk SAW and `entries` what it returned. They differ once the limit
+     * is reached, and that difference is the only thing that tells a caller its picture of the
+     * tree is partial: a listing that reported only its own length would be indistinguishable
+     * from a small repository.
+     *
+     * Every entry's `path` is relative to the directory ASKED FOR, not to the project root. That
+     * is the contract the in-process helper and the publisher answer, and one executor answering
+     * a different relativity is worse than either choice: the caller is a census that follows a
+     * listing with a `readHead` of what it listed, and nothing downstream knows which of the
+     * three produced the path it is holding.
+     */
+    statTree: (dir?: string, limit?: number) => Promise<StatTreeResult>;
+    /**
+     * The first bytes of one file, decoded as text.
+     *
+     * A classification reads a head; reading whole files to do it would hold a megabyte export in
+     * memory to look at its first line. Whatever the decoding produces for a binary head is the
+     * answer — that IS the signal an entropy classification wants, and cleaning it up would hide
+     * the one thing the caller is asking about.
+     */
+    readHead: (filePath: string, bytes: number) => Promise<string>;
+    /**
+     * Move everything in the project root under one directory, leaving a named few where they are.
+     *
+     * What makes a converted project possible: the origin's own tree goes below, a Viable target
+     * is grown above it, and the two never share a path. It is the same walk `emptyProject` does —
+     * kept paths may be nested, a directory holding one is walked rather than moved, and a
+     * directory left empty by that walk does not survive as a shell.
+     *
+     * The always-keep set applies here too and for the same reason: `.git` is the developer's
+     * history and moving it under the origin would take the project's whole history with it,
+     * `.viable` is how a later session recognizes the project, and the two `.env` files hold what
+     * the platform cannot re-derive.
+     *
+     * Refuses a destination that already holds something. A relocation into an occupied directory
+     * interleaves two trees, and nothing afterwards can tell which files came from where.
+     */
+    relocate: (dir: string, keep?: string[]) => Promise<{
+        moved: number;
+        kept: string[];
+    }>;
+    /**
+     * Delete a directory and everything under it — the purge of a relocated origin.
+     *
+     * Refuses the project root: emptying the project is `emptyProject`, which has a keep list this
+     * does not, and a purge that resolved to `.` would take the developer's `.git` and `.env` with
+     * the origin it was asked to remove.
+     */
+    removeTree: (dir: string) => Promise<void>;
+    getRootPath: (subproject?: SubProject) => string;
+    findFilesWithEnvVars: (frontend?: boolean) => Promise<string[]>;
+};
+export type LocalFileHelper = ReturnType<typeof createLocalFileHelper>;
+/**
+ * The same confinement, for callers outside this helper.
+ *
+ * Exported because the configure push writes `.env` files by name and a path is a path: a guard
+ * that only the file commands apply is a guard on the file commands, and the connector holds the
+ * developer's home directory rather than a pod's volume.
+ */
+export declare const confineToProject: (dir: string, file: string) => string;
+//# sourceMappingURL=files.d.ts.map

package/build/executor/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/executor/files.ts"],"names":[],"mappings":"AAKA,OAAO,EAE4E,UAAU,EAC5F,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAY,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAKvE,+FAA+F;AAC/F,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AA4CD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,gBAAiB,MAAM;IAsDrD;;;;;;;;;;;OAWG;4BAC2B,MAAM,EAAE;;IAsCtC;;;;;;;OAOG;;gDA6BQ,iBAAiB,KACzB,OAAO,CAAC,MAAM,EAAE,CAAC;kCA6CgB,MAAM,EAAE,KAAG,OAAO,CAAC,MAAM,EAAE,CAAC;qBASzC,MAAM,yBAAqB,OAAO,CAAC,MAAM,CAAC;2BAWpC,MAAM,KAAG,OAAO,CAAC,eAAe,CAAC;mCAOzB,MAAM,KAAG,OAAO,CAAC,eAAe,CAAC;yBAQ3C,MAAM,GAAG,MAAM,EAAE,KAAG,OAAO,CAAC,eAAe,EAAE,CAAC;0BAY7C,MAAM,WAAW,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;wBAMzC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAG,OAAO,CAAC,IAAI,CAAC;2BAM3C,MAAM,wBAAmB,OAAO,CAAC,IAAI,CAAC;IAWnE;;;;;;;;;;;;;;;;;;OAkBG;qBACoB,MAAM,UAAU,MAAM,KAAG,OAAO,CAAC,cAAc,CAAC;IAyCvE;;;;;;;OAOG;yBACwB,MAAM,SAAS,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;IA2BlE;;;;;;;;;;;;;;;OAeG;oBACmB,MAAM,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IA6D1F;;;;;;OAMG;sBACqB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;+BAQnB,UAAU,KAAG,MAAM;sCAIN,OAAO,KAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CA+BtE,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAoCtE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,QAAS,MAAM,QAAQ,MAAM,KAAG,MACU,CAAA"}