@theford/runly 0.0.0-stage → 0.20.0

package/dist/cli/watchdog.js

@@ -0,0 +1,81 @@
+/**
+ * `runly db with`'s watchdog (0.19): it runs the command, and takes it down
+ * when the CLI that started it dies.
+ *
+ * The CLI drops the database copy after the command exits. If the CLI itself
+ * is killed (SIGKILL, OOM, a `kill` of its process group that missed a command
+ * in a group of its own — `setsid runly db with …`), the daemon drops the copy
+ * once it notices, and the command used to keep working against a database
+ * that no longer exists. Node cannot set PR_SET_PDEATHSIG, so the tie is a
+ * pipe: the CLI holds the write end of fd 3, the kernel closes it when the CLI
+ * dies however it dies, and this process sees EOF.
+ *
+ * argv: <shell|argv> <group|nogroup> <command…>. `group`: this process leads
+ * the command's process group (no terminal), and the whole group goes. At a
+ * terminal the command stays in the caller's job and only it is signalled.
+ *
+ * The command's exit code (or the signal that ended it) is this process's, so
+ * the CLI passes it through unchanged.
+ */
+import { spawn } from 'node:child_process';
+import { Socket } from 'node:net';
+const [mode, grouping, ...parts] = process.argv.slice(2);
+const group = grouping === 'group';
+const command = parts[0];
+if (command === undefined) {
+    console.error('runly db with: watchdog started without a command');
+    process.exit(64);
+}
+const child = mode === 'shell'
+    ? spawn(command, { stdio: 'inherit', shell: true })
+    : spawn(command, parts.slice(1), { stdio: 'inherit' });
+const signalCommand = (sig) => {
+    try {
+        if (group)
+            process.kill(-process.pid, sig);
+        else
+            child.kill(sig);
+    }
+    catch {
+        /* already gone */
+    }
+};
+// A signal the CLI passes on: in a group of our own the whole group (the
+// command included) already received it; at a terminal only this process did.
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(sig, () => {
+        if (!group)
+            child.kill(sig);
+    });
+}
+let cliGone = false;
+const onCliGone = () => {
+    if (cliGone)
+        return;
+    cliGone = true;
+    signalCommand('SIGTERM');
+    // A command that ignores SIGTERM goes anyway: nothing may go on working
+    // against a copy that is about to be dropped.
+    setTimeout(() => signalCommand('SIGKILL'), 3000).unref();
+};
+// A stream handle, not an fs read: a blocking read on fd 3 would sit in the
+// threadpool and keep process.exit() from returning.
+const pipe = new Socket({ fd: 3, readable: true, writable: false });
+pipe.on('data', () => undefined);
+pipe.on('end', onCliGone);
+pipe.on('close', onCliGone);
+pipe.on('error', onCliGone);
+child.on('error', (err) => {
+    console.error(`runly db with: could not start '${command}': ${err.message}`);
+    process.exit(127);
+});
+child.on('exit', (code, signal) => {
+    if (signal) {
+        // Die of the same signal, so the CLI reports 128+n like a shell would.
+        process.removeAllListeners(signal);
+        process.kill(process.pid, signal);
+        return;
+    }
+    process.exit(code ?? 1);
+});
+//# sourceMappingURL=watchdog.js.map

package/dist/cli/watchdog.js.map

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

package/dist/core/builds.d.ts

@@ -0,0 +1,20 @@
+import type { Manifest } from './manifest.js';
+/**
+ * The key a build is recorded under: its (templated) command plus path, size
+ * and mtime of every file its `when:` globs match.
+ */
+export declare function buildInputsKey(root: string, manifest: Manifest, cmd: string, when: string[]): Promise<string>;
+/**
+ * Was this service last built SUCCESSFULLY from exactly these inputs, and are
+ * its outputs still what that build left? `outputs` is the current stat
+ * snapshot of the declared outputs (undefined when none are declared).
+ */
+export declare function buildIsCurrent(stackId: string, service: string, key: string, outputs?: string): boolean;
+/** Forget a service's build before running it again (a failure must not vouch for anything). */
+export declare function forgetBuild(stackId: string, root: string, service: string): void;
+/** Record a successful build, with the stat snapshot of its outputs when it declares any. */
+export declare function recordBuild(stackId: string, root: string, service: string, key: string, outputs?: string): void;
+/** Has this service ever been built successfully in this worktree (any inputs)? */
+export declare function everBuilt(stackId: string, service: string): boolean;
+/** `--pristine`: nothing is trusted, so every build runs again. */
+export declare function clearBuilds(stackId: string): void;

package/dist/core/builds.js

@@ -0,0 +1,93 @@
+/**
+ * Build skip (decision 0038): a service whose `build:` declares `when:` globs
+ * is not rebuilt while the files they match are unchanged since its last
+ * SUCCESSFUL build in this worktree.
+ *
+ * The inputs are listed the way upkeep triggers are (decision 0032): git's
+ * file list filtered by the globs before anything is stat'ed, minus declared
+ * `caches:` — so a `frontend/**` glob never walks node_modules. A file's
+ * identity is path + size + mtime; the build line itself is part of the key,
+ * so editing the command rebuilds. The ledger lives in the state root
+ * (`worktrees/<stack>/builds.json`), never in the worktree, and is the
+ * worktree's: `runly warm` writes it as well as `up`.
+ *
+ * An entry is dropped BEFORE its build runs and written only after it
+ * succeeds, so a build that fails half-way is never vouched for.
+ *
+ * When the service declares `outputs:`, the entry also records a stat
+ * snapshot of them taken right after the build. A skip needs that snapshot
+ * to still hold: outputs that were deleted or overwritten since (a `git
+ * clean`, a manual `rm -rf dist`, another tool) would otherwise leave the
+ * service with nothing, or the wrong thing, to run.
+ */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sha256 } from './util.js';
+import { enumerateSourceStats } from './worktree.js';
+import { worktreeStateDir } from './tree-ledger.js';
+const ledgerPath = (stackId) => join(worktreeStateDir(stackId), 'builds.json');
+function read(stackId) {
+    try {
+        const raw = JSON.parse(readFileSync(ledgerPath(stackId), 'utf8'));
+        return raw.builds && typeof raw.builds === 'object' ? { ...raw.builds } : {};
+    }
+    catch {
+        return {};
+    }
+}
+function write(stackId, root, builds) {
+    const dir = worktreeStateDir(stackId);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `builds.json.${process.pid}.tmp`);
+    writeFileSync(tmp, JSON.stringify({ root, builds }));
+    renameSync(tmp, ledgerPath(stackId));
+}
+/**
+ * The key a build is recorded under: its (templated) command plus path, size
+ * and mtime of every file its `when:` globs match.
+ */
+export async function buildInputsKey(root, manifest, cmd, when) {
+    // The listing stats every file once, and this key is made of those stats.
+    const files = await enumerateSourceStats(root, manifest, when);
+    return sha256(`${cmd}\n${files.map((f) => `${f.path}:${f.size}:${f.mtimeMs}`).join('\n')}`);
+}
+/**
+ * Was this service last built SUCCESSFULLY from exactly these inputs, and are
+ * its outputs still what that build left? `outputs` is the current stat
+ * snapshot of the declared outputs (undefined when none are declared).
+ */
+export function buildIsCurrent(stackId, service, key, outputs) {
+    const entry = read(stackId)[service];
+    if (entry?.key !== key)
+        return false;
+    if (outputs === undefined)
+        return true;
+    // An entry written before outputs were recorded vouches for its inputs only;
+    // the caller has already checked that outputs exist at all.
+    if (entry.outputs === undefined)
+        return true;
+    return entry.outputs === outputs;
+}
+/** Forget a service's build before running it again (a failure must not vouch for anything). */
+export function forgetBuild(stackId, root, service) {
+    const builds = read(stackId);
+    if (!(service in builds))
+        return;
+    delete builds[service];
+    write(stackId, root, builds);
+}
+/** Record a successful build, with the stat snapshot of its outputs when it declares any. */
+export function recordBuild(stackId, root, service, key, outputs) {
+    const builds = read(stackId);
+    builds[service] = outputs === undefined ? { key, at: Date.now() } : { key, at: Date.now(), outputs };
+    write(stackId, root, builds);
+}
+/** Has this service ever been built successfully in this worktree (any inputs)? */
+export function everBuilt(stackId, service) {
+    return read(stackId)[service] !== undefined;
+}
+/** `--pristine`: nothing is trusted, so every build runs again. */
+export function clearBuilds(stackId) {
+    rmSync(ledgerPath(stackId), { force: true });
+}
+//# sourceMappingURL=builds.js.map

package/dist/core/builds.js.map

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

package/dist/core/caller-env.d.ts

@@ -0,0 +1,17 @@
+/** Caller environment transport is allowlisted by service, never journaled. */
+import type { Manifest, ServiceSpec } from './manifest.js';
+export declare function collectCallerEnv(cwd: string, source?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function selectCallerEnv(manifest: Manifest, source: NodeJS.ProcessEnv): Record<string, string>;
+/** Validate the socket payload without echoing values into error messages. */
+export declare function validateCallerEnv(manifest: Manifest, input: unknown): Record<string, string>;
+export declare function requireCallerEnv(manifest: Manifest, active: Iterable<string>, values: Record<string, string>): void;
+/**
+ * A supplied value wins; an omitted one keeps the service's explicit `env`
+ * default, and undefined deliberately masks a same-named inherited daemon
+ * value when there is no such default.
+ */
+export declare function serviceCallerEnv(spec: ServiceSpec, values: Record<string, string>): NodeJS.ProcessEnv;
+/** Declaration identity only: safe to compare without hashing secret values. */
+export declare function callerEnvSpec(manifest: Manifest): string;
+/** Preserve chunk boundaries without ever writing a prefix of a secret first. */
+export declare function redactStream(values: string[]): (chunk: string, final?: boolean) => string;

package/dist/core/caller-env.js

@@ -0,0 +1,77 @@
+import { loadStack } from './manifest.js';
+import { BrokerError } from './util.js';
+export function collectCallerEnv(cwd, source = process.env) {
+    return selectCallerEnv(loadStack(cwd).manifest, source);
+}
+export function selectCallerEnv(manifest, source) {
+    return Object.fromEntries(Object.values(manifest.services).flatMap((spec) => Object.keys(spec.env_from ?? {}).flatMap((name) => source[name] === undefined ? [] : [[name, source[name]]])));
+}
+/** Validate the socket payload without echoing values into error messages. */
+export function validateCallerEnv(manifest, input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        throw new BrokerError('work-error', 'callerEnv must be an object containing only declared environment inputs', 'env_from');
+    }
+    const allowed = new Set(Object.values(manifest.services).flatMap((s) => Object.keys(s.env_from ?? {})));
+    const values = Object.create(null);
+    for (const [name, value] of Object.entries(input)) {
+        if (!allowed.has(name) || typeof value !== 'string' || value.includes('\0')) {
+            throw new BrokerError('work-error', 'callerEnv contains an undeclared name or invalid value; only manifest env_from inputs are accepted', 'env_from');
+        }
+        values[name] = value;
+    }
+    return values;
+}
+export function requireCallerEnv(manifest, active, values) {
+    for (const service of active) {
+        for (const [name, mode] of Object.entries(manifest.services[service].env_from ?? {})) {
+            if (mode === 'required' && values[name] === undefined) {
+                throw new BrokerError('work-error', `service '${service}' requires caller environment '${name}'; export it and run 'runly up' again (inputs are not retained across daemon restarts)`, 'env_from');
+            }
+        }
+    }
+}
+/**
+ * A supplied value wins; an omitted one keeps the service's explicit `env`
+ * default, and undefined deliberately masks a same-named inherited daemon
+ * value when there is no such default.
+ */
+export function serviceCallerEnv(spec, values) {
+    return Object.fromEntries(Object.keys(spec.env_from ?? {}).flatMap((name) => values[name] !== undefined ? [[name, values[name]]] : name in (spec.env ?? {}) ? [] : [[name, undefined]]));
+}
+/** Declaration identity only: safe to compare without hashing secret values. */
+export function callerEnvSpec(manifest) {
+    return JSON.stringify(Object.entries(manifest.services)
+        .filter(([, spec]) => Object.keys(spec.env_from ?? {}).length > 0)
+        .map(([name, spec]) => [name, Object.entries(spec.env_from).sort(([a], [b]) => a.localeCompare(b))])
+        .sort(([a], [b]) => String(a).localeCompare(String(b))));
+}
+/** Preserve chunk boundaries without ever writing a prefix of a secret first. */
+export function redactStream(values) {
+    const secrets = [...new Set(values.filter(Boolean))].sort((a, b) => b.length - a.length);
+    if (secrets.length === 0)
+        return (chunk) => chunk;
+    let pending = '';
+    return (chunk, final = false) => {
+        const input = pending + chunk;
+        pending = '';
+        let output = '';
+        for (let i = 0; i < input.length;) {
+            const remaining = input.slice(i);
+            if (!final && secrets.some((secret) => remaining.length < secret.length && secret.startsWith(remaining))) {
+                pending = remaining;
+                break;
+            }
+            const match = secrets.find((secret) => input.startsWith(secret, i));
+            if (match) {
+                output += '[redacted]';
+                i += match.length;
+            }
+            else {
+                output += input[i];
+                i++;
+            }
+        }
+        return output;
+    };
+}
+//# sourceMappingURL=caller-env.js.map

package/dist/core/caller-env.js.map

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

package/dist/core/diagnostics.d.ts

@@ -0,0 +1,68 @@
+/** Request-local bind explanations. Never persist commands or environment values. */
+export interface BindDiagnostics {
+    durationMs: number;
+    /** Wall time per phase. On a full bind `data` and `build` overlap (decision 0039), so they may add up to more than `durationMs`. */
+    phasesMs: Record<BindPhase, number>;
+    /**
+     * `reused`: no running service was stopped — every build ran and none
+     * changed a service's declared outputs (services in `started` were added
+     * next to them); `restarted`: the services kept running except `restarted`;
+     * `rebound`: the full stop/data/build/start path, for the `reasons` given.
+     */
+    reuse: 'reused' | 'restarted' | 'rebound';
+    /**
+     * The running services an `up` restarted: their build output changed, or
+     * they use a datastore this operation reloaded (decision 0034); on a full
+     * rebind, every one that was running (0.19).
+     */
+    restarted: string[];
+    /** Services this `up` added to the ones already running (decision 0034: `up` is additive); on a full rebind, the ones not running before it (0.19). */
+    started: string[];
+    /** Datastores reloaded from their template because the caller named a preset for them (decision 0034). */
+    reloaded: string[];
+    /**
+     * Why the full path ran (empty when it did not): `new-environment` (its
+     * first bind), `upkeep-required`, `environment-not-running`,
+     * `service-process-unhealthy`, `environment-inputs-changed`,
+     * `manifest-changed`, `hygiene-<reset-data|pristine>`, `public-port-moved`.
+     * The plain `up` summary prints them in words (0.19).
+     */
+    reasons: string[];
+    upkeep: {
+        ran: number;
+        skipped: number;
+    };
+    /**
+     * Every `build:` that ran in this operation — all of them, every `up`
+     * (decision 0032: runly keeps no build cache; the build tool decides what is
+     * current) — and whether its service was restarted, with why:
+     * `outputs-changed`, `outputs-unchanged`, `no-outputs-declared` (always
+     * restarted), `not-running` (a service this `up` adds), `full-rebind`,
+     * `not-named` (`up <service>` left this running one alone, 0.19), or
+     * `when-unchanged` (decision 0038: a `build: { when: }` whose inputs did
+     * not change since its last successful build — skipped, durationMs 0).
+     */
+    builds: Array<{
+        service: string;
+        durationMs: number;
+        restart: boolean;
+        reason: 'outputs-changed' | 'outputs-unchanged' | 'no-outputs-declared' | 'not-running' | 'full-rebind' | 'not-named' | 'when-unchanged';
+    }>;
+}
+type BindPhase = 'queue' | 'prepare' | 'appliances' | 'upkeep' | 'stop' | 'data' | 'build' | 'ready' | 'finalize';
+export declare class BindTrace {
+    readonly result: BindDiagnostics;
+    private started;
+    private marked;
+    private current;
+    phase(next: BindPhase): void;
+    /**
+     * Phases that ran side by side (data and build on a full bind, decision
+     * 0039): each gets its own wall time, and the span they shared is not
+     * counted again for the phase that was current. `durationMs` is then less
+     * than the sum of the phases.
+     */
+    overlapped(ms: Partial<Record<BindPhase, number>>): void;
+    finish(): BindDiagnostics;
+}
+export {};

package/dist/core/diagnostics.js

@@ -0,0 +1,34 @@
+export class BindTrace {
+    result = {
+        durationMs: 0,
+        phasesMs: { queue: 0, prepare: 0, appliances: 0, upkeep: 0, stop: 0, data: 0, build: 0, ready: 0, finalize: 0 },
+        reuse: 'rebound', restarted: [], started: [], reloaded: [], reasons: [],
+        upkeep: { ran: 0, skipped: 0 }, builds: [],
+    };
+    started = performance.now();
+    marked = this.started;
+    current = 'prepare';
+    phase(next) {
+        const at = performance.now();
+        this.result.phasesMs[this.current] += at - this.marked;
+        this.marked = at;
+        this.current = next;
+    }
+    /**
+     * Phases that ran side by side (data and build on a full bind, decision
+     * 0039): each gets its own wall time, and the span they shared is not
+     * counted again for the phase that was current. `durationMs` is then less
+     * than the sum of the phases.
+     */
+    overlapped(ms) {
+        for (const [phase, v] of Object.entries(ms))
+            this.result.phasesMs[phase] += v;
+        this.marked = performance.now();
+    }
+    finish() {
+        this.phase('finalize');
+        this.result.durationMs = performance.now() - this.started;
+        return this.result;
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/core/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/core/diagnostics.ts"],"names":[],"mappings":"AA8CA,MAAM,OAAO,SAAS;IACX,MAAM,GAAoB;QACjC,UAAU,EAAE,CAAC;QACb,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE;QAC/G,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE;QACvE,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE;KAC3C,CAAC;IACM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAC5B,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC;IACtB,OAAO,GAAc,SAAS,CAAC;IAEvC,KAAK,CAAC,IAAe;QACnB,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACvD,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,EAAsC;QAC/C,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAA+B;YAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5G,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAClC,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAC1D,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}

package/dist/core/env-vars.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The RUNLY_* variables that describe an environment (decision 0032): what
+ * `runly ctx --env` prints and what `runly exec` exports, one set of names.
+ *
+ *   RUNLY_ENV_ID, RUNLY_PORT_<PORT>, RUNLY_URL_<SERVICE>,
+ *   RUNLY_DATASTORE_<NAME>_URL, RUNLY_DATASTORE_<NAME>_PRESET (decision 0034),
+ *   RUNLY_LOGIN_USER, RUNLY_LOGIN_PASSWORD
+ *
+ * Names are uppercased, any other character becomes `_`.
+ */
+export interface EnvVarSource {
+    envId: string;
+    ports?: Record<string, number>;
+    urls?: Record<string, string>;
+    datastores?: Record<string, {
+        url: string;
+        preset?: string | null;
+    }>;
+    logins?: {
+        user: string;
+        password: string;
+    } | null;
+}
+/** `web-audit` -> `WEB_AUDIT`: a valid, stable shell variable suffix. */
+export declare const envName: (s: string) => string;
+/** The variables, in a stable order. */
+export declare function runlyEnvVars(c: EnvVarSource): Record<string, string>;
+/** Quoted only when it has to be, so plain values stay plain. */
+export declare const shellValue: (v: string) => string;
+/**
+ * `export KEY=value` lines. `export` is what makes them reach a child:
+ * `eval "$(runly ctx --env)" && npm test` with bare `KEY=value` lines set
+ * shell variables that `npm test` never saw.
+ */
+export declare function exportLines(c: EnvVarSource): string[];

package/dist/core/env-vars.js

@@ -0,0 +1,32 @@
+/** `web-audit` -> `WEB_AUDIT`: a valid, stable shell variable suffix. */
+export const envName = (s) => s.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+/** The variables, in a stable order. */
+export function runlyEnvVars(c) {
+    const out = { RUNLY_ENV_ID: c.envId };
+    for (const [k, v] of Object.entries(c.ports ?? {}).sort())
+        out[`RUNLY_PORT_${envName(k)}`] = String(v);
+    for (const [k, v] of Object.entries(c.urls ?? {}).sort())
+        out[`RUNLY_URL_${envName(k)}`] = v;
+    for (const [k, v] of Object.entries(c.datastores ?? {}).sort()) {
+        out[`RUNLY_DATASTORE_${envName(k)}_URL`] = v.url;
+        // What the datastore holds right now (decision 0034); absent before its first restore.
+        if (v.preset)
+            out[`RUNLY_DATASTORE_${envName(k)}_PRESET`] = v.preset;
+    }
+    if (c.logins) {
+        out.RUNLY_LOGIN_USER = c.logins.user;
+        out.RUNLY_LOGIN_PASSWORD = c.logins.password;
+    }
+    return out;
+}
+/** Quoted only when it has to be, so plain values stay plain. */
+export const shellValue = (v) => (/^[A-Za-z0-9_./:@%+,=-]*$/.test(v) ? v : `'${v.replace(/'/g, `'\\''`)}'`);
+/**
+ * `export KEY=value` lines. `export` is what makes them reach a child:
+ * `eval "$(runly ctx --env)" && npm test` with bare `KEY=value` lines set
+ * shell variables that `npm test` never saw.
+ */
+export function exportLines(c) {
+    return Object.entries(runlyEnvVars(c)).map(([k, v]) => `export ${k}=${shellValue(v)}`);
+}
+//# sourceMappingURL=env-vars.js.map

package/dist/core/env-vars.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-vars.js","sourceRoot":"","sources":["../../src/core/env-vars.ts"],"names":[],"mappings":"AAkBA,yEAAyE;AACzE,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;AAEzF,wCAAwC;AACxC,MAAM,UAAU,YAAY,CAAC,CAAe;IAC1C,MAAM,GAAG,GAA2B,EAAE,YAAY,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;IAC9D,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,cAAc,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACvG,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,aAAa,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAC7F,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/D,GAAG,CAAC,mBAAmB,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;QACjD,uFAAuF;QACvF,IAAI,CAAC,CAAC,MAAM;YAAE,GAAG,CAAC,mBAAmB,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IACvE,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;QACb,GAAG,CAAC,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;QACrC,GAAG,CAAC,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC/C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iEAAiE;AACjE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;AAE5H;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,CAAe;IACzC,OAAO,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACzF,CAAC"}

package/dist/core/events.d.ts

@@ -0,0 +1,10 @@
+export type EventLevel = 'info' | 'warn' | 'error';
+export interface DaemonEvent {
+    at: number;
+    level: EventLevel;
+    kind: string;
+    envId?: string;
+    detail?: string;
+}
+export declare function logEvent(e: Omit<DaemonEvent, 'at'>): void;
+export declare function recentEvents(limit?: number): DaemonEvent[];

package/dist/core/events.js

@@ -0,0 +1,42 @@
+/**
+ * Structured daemon event log (task: observability). Failures used to vanish
+ * into swallowed catches; this makes them visible. Append-only JSONL under the
+ * state dir, size-capped in place, read back by `status`/`doctor`.
+ */
+import { appendFileSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateRoot } from './paths.js';
+const logPath = () => join(stateRoot(), 'events.jsonl');
+const CAP = 512 * 1024;
+export function logEvent(e) {
+    const line = JSON.stringify({ at: Date.now(), ...e }) + '\n';
+    try {
+        const p = logPath();
+        try {
+            if (statSync(p).size > CAP) {
+                const kept = readFileSync(p, 'utf8').split('\n').slice(-500).join('\n');
+                writeFileSync(p, kept);
+            }
+        }
+        catch {
+            /* no file yet */
+        }
+        appendFileSync(p, line);
+    }
+    catch {
+        /* logging must never throw into a caller */
+    }
+}
+export function recentEvents(limit = 30) {
+    try {
+        return readFileSync(logPath(), 'utf8')
+            .split('\n')
+            .filter(Boolean)
+            .slice(-limit)
+            .map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/core/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/core/events.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAChF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAWvC,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,cAAc,CAAC,CAAC;AACxD,MAAM,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC;AAEvB,MAAM,UAAU,QAAQ,CAAC,CAA0B;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,OAAO,EAAE,CAAC;QACpB,IAAI,CAAC;YACH,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,EAAE,CAAC;gBAC3B,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACxE,aAAa,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,iBAAiB;QACnB,CAAC;QACD,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,4CAA4C;IAC9C,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAK,GAAG,EAAE;IACrC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC;aACnC,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,OAAO,CAAC;aACf,KAAK,CAAC,CAAC,KAAK,CAAC;aACb,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAgB,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/core/exec.d.ts

@@ -0,0 +1,22 @@
+/** Repo-declared commands are IO-bound setup steps, not builds. */
+export declare const DEFAULT_CMD_TIMEOUT_S = 300;
+/** Build/exec/check-grade work gets a longer leash than setup steps. */
+export declare const LONG_CMD_TIMEOUT_S = 600;
+/**
+ * The deadline for a repo-declared command. Callers pass the default that fits
+ * their site's class (setup steps 300s, or an upkeep rule's own `timeout`;
+ * build/exec-grade work 600s); BACKLOT_CMD_TIMEOUT_S overrides ALL of them —
+ * the escape hatch for a repo whose legitimate commands outrun the class default.
+ */
+export declare function cmdTimeoutS(fallback?: number): number;
+export interface CmdResult {
+    code: number;
+    output: string;
+    timedOut: boolean;
+}
+export declare function runBounded(cmd: string, cwd: string, timeoutS?: number, env?: NodeJS.ProcessEnv, 
+/** Sees every chunk as it arrives (a build log, decision 0038); `end` once per stream. */
+onOutput?: {
+    data: (stream: 'out' | 'err', chunk: string) => void;
+    end: (stream: 'out' | 'err') => void;
+}): Promise<CmdResult>;