backlot 0.4.0

package/dist/core/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Core domain model (see docs/architecture.md §3).
+ * Persisted in the per-machine SQLite journal; the daemon's memory is a cache.
+ */
+export type EnvState = 'provisioning' | 'hot' | 'warm' | 'degraded' | 'recycling';
+export type Hygiene = 'reuse' | 'reset-data' | 'pristine';
+export type LeaseKind = 'session' | 'run';
+/** The field an agent branches on mechanically (decision 0010). */
+export type ErrorClass = 'work-error' | 'env-error' | 'infra-error';
+export interface Environment {
+    id: string;
+    stack: string;
+    substrate: string;
+    state: EnvState;
+    root: string;
+    /** Symbolic name -> allocated port. Stable for the environment's lifetime. */
+    ports: Record<string, number>;
+    datastoreNs: Record<string, string>;
+    /** Per-upkeep-rule trigger hash as last applied IN THIS ENV (decision 0008). */
+    fingerprints: Record<string, string>;
+    bindCount: number;
+    createdAt: number;
+    lastUsedAt: number;
+}
+/** An immutable snapshot of source + data state (decision 0005). */
+export interface Binding {
+    envId: string;
+    revision: number;
+    ref: string;
+    dirtyPatchHash: string | null;
+    preset: string;
+    hygiene: Hygiene;
+    syncedAt: number;
+}
+export interface Lease {
+    id: string;
+    envId: string;
+    kind: LeaseKind;
+    /** Refreshed by any CLI touch; expiry releases the env WARM (decision 0003). */
+    expiresAt: number;
+    holder: string;
+}
+export interface Failure {
+    class: ErrorClass;
+    message: string;
+    /** e.g. the upkeep rule or service that failed. */
+    source?: string;
+    logExcerpt?: string;
+}
+export interface Verdict {
+    check: string;
+    ok: boolean;
+    exitCode: number;
+    failure?: Failure;
+    artifactsDir?: string;
+    /** Declared outputs the env offers back; pulled only explicitly (decision 0011). */
+    outputsChanged: string[];
+    binding: Binding;
+    durationMs: number;
+}
+/** What `backlot ctx --json` returns — the consumer's entire interface. */
+export interface Context {
+    stack: string;
+    envId: string;
+    lease: Lease;
+    urls: Record<string, string>;
+    logins?: {
+        user: string;
+        password: string;
+    };
+    tokenCommand?: string;
+    datastores: Record<string, {
+        url: string;
+    }>;
+    artifactsDir: string;
+    hygiene: Hygiene;
+    events: Array<{
+        at: number;
+        service: string;
+        event: string;
+    }>;
+}

package/dist/core/types.js

@@ -0,0 +1,6 @@
+/**
+ * Core domain model (see docs/architecture.md §3).
+ * Persisted in the per-machine SQLite journal; the daemon's memory is a cache.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/core/upkeep.d.ts

@@ -0,0 +1,11 @@
+import type { Manifest } from './manifest.js';
+export interface UpkeepOutcome {
+    ran: Array<{
+        when: string;
+        run: string;
+    }>;
+    fingerprints: Record<string, string>;
+    /** Names of datastores whose templates must be rebaked (@rebake-template). */
+    rebakeTemplates: string[];
+}
+export declare function runUpkeep(envTree: string, syncedFiles: string[], manifest: Manifest, previous: Record<string, string>): Promise<UpkeepOutcome>;

package/dist/core/upkeep.js

@@ -0,0 +1,47 @@
+/**
+ * The fingerprint ledger (decision 0008): a closed list of (trigger -> action)
+ * rules, evaluated per environment at bind time, direction-agnostic. Actions
+ * are repo commands, or engine built-ins prefixed with @.
+ */
+import { execFile } from 'node:child_process';
+import { join } from 'node:path';
+import { globToRegex, sha256, fileHash, BrokerError } from './util.js';
+function triggerHash(envTree, files, when) {
+    const re = globToRegex(when);
+    const matching = files.filter((f) => re.test(f)).sort();
+    return sha256(matching.map((f) => `${f}:${fileHash(join(envTree, f)) ?? 'gone'}`).join('\n'));
+}
+export async function runUpkeep(envTree, syncedFiles, manifest, previous) {
+    const outcome = { ran: [], fingerprints: { ...previous }, rebakeTemplates: [] };
+    for (const rule of manifest.upkeep ?? []) {
+        const key = `${rule.when} -> ${rule.run}`;
+        const hash = triggerHash(envTree, syncedFiles, rule.when);
+        if (previous[key] === hash)
+            continue;
+        if (rule.run.startsWith('@')) {
+            const [builtin, ...args] = rule.run.slice(1).split(/\s+/);
+            if (builtin === 'rebake-template') {
+                outcome.rebakeTemplates.push(args[0] ?? 'main');
+            }
+            else {
+                throw new BrokerError('work-error', `unknown upkeep built-in '@${builtin}'`, 'upkeep');
+            }
+        }
+        else {
+            await new Promise((resolve, reject) => {
+                execFile('sh', ['-c', rule.run], { cwd: envTree, maxBuffer: 16 * 1024 * 1024 }, (err, _out, stderr) => {
+                    if (err) {
+                        // Triggered by the binding's own change -> work-error by default (decision 0008).
+                        reject(new BrokerError('work-error', `upkeep rule failed: ${rule.run}`, rule.when, String(stderr).slice(0, 800)));
+                    }
+                    else
+                        resolve();
+                });
+            });
+        }
+        outcome.ran.push({ when: rule.when, run: rule.run });
+        outcome.fingerprints[key] = hash;
+    }
+    return outcome;
+}
+//# sourceMappingURL=upkeep.js.map

package/dist/core/upkeep.js.map

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

package/dist/core/util.d.ts

@@ -0,0 +1,36 @@
+export declare const sha256: (data: string | Buffer) => string;
+export declare const fileHash: (path: string) => string | null;
+export declare const isFile: (p: string) => boolean;
+/**
+ * Minimal glob matcher for manifest patterns (caches, sync.keep, artifacts,
+ * upkeep when:). Supports **, *, ?. A bare name with no glob chars and no
+ * slash matches that path segment anywhere (node_modules). All patterns also
+ * protect their subtree (an implicit trailing /**).
+ */
+export declare function globToRegex(pattern: string): RegExp;
+export declare const matchesAny: (path: string, patterns: string[]) => boolean;
+/** Resolve {{...}} placeholders against a nested context object. */
+export declare function template(str: string, ctx: Record<string, unknown>): string;
+export declare const templateEnv: (env: Record<string, string> | undefined, ctx: Record<string, unknown>) => Record<string, string>;
+export declare class BrokerError extends Error {
+    readonly klass: 'work-error' | 'env-error' | 'infra-error';
+    readonly source?: string | undefined;
+    readonly logExcerpt?: string | undefined;
+    constructor(klass: 'work-error' | 'env-error' | 'infra-error', message: string, source?: string | undefined, logExcerpt?: string | undefined);
+    toJSON(): {
+        class: "work-error" | "infra-error" | "env-error";
+        message: string;
+        source: string | undefined;
+        logExcerpt: string | undefined;
+    };
+}
+/**
+ * A manifest-supplied relative path (sync.include, outputs, a datastore key)
+ * must stay INSIDE its base after resolution — never escape via `..` or an
+ * absolute path. Returns the safe joined absolute path, or throws work-error.
+ * This is the guard that keeps file ops from leaving backlot's own dirs even
+ * on an honest `../shared/.env` typo, not only a malicious manifest.
+ */
+export declare function safeJoin(base: string, rel: string, what: string): string;
+export declare const now: () => number;
+export declare const shortId: () => string;

package/dist/core/util.js

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import * as pathMod from 'node:path';
+export const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+export const fileHash = (path) => {
+    try {
+        return sha256(readFileSync(path));
+    }
+    catch {
+        return null;
+    }
+};
+export const isFile = (p) => existsSync(p) && statSync(p).isFile();
+/**
+ * Minimal glob matcher for manifest patterns (caches, sync.keep, artifacts,
+ * upkeep when:). Supports **, *, ?. A bare name with no glob chars and no
+ * slash matches that path segment anywhere (node_modules). All patterns also
+ * protect their subtree (an implicit trailing /**).
+ */
+export function globToRegex(pattern) {
+    const p = pattern.replace(/^glob\((.*)\)$/, '$1').replace(/^\.\//, '');
+    if (!/[*?[]/.test(p) && !p.includes('/')) {
+        return new RegExp(`(^|/)${p.replace(/[.+^${}()|\\]/g, '\\$&')}(/|$)`);
+    }
+    let re = '';
+    for (let i = 0; i < p.length; i++) {
+        const c = p[i];
+        if (c === '*') {
+            if (p[i + 1] === '*') {
+                re += '.*';
+                i++;
+                if (p[i + 1] === '/')
+                    i++;
+            }
+            else
+                re += '[^/]*';
+        }
+        else if (c === '?')
+            re += '[^/]';
+        else
+            re += c.replace(/[.+^${}()|\\[\]]/g, '\\$&');
+    }
+    return new RegExp(`^${re}(/.*)?$`);
+}
+export const matchesAny = (path, patterns) => patterns.some((p) => globToRegex(p).test(path));
+/** Resolve {{...}} placeholders against a nested context object. */
+export function template(str, ctx) {
+    return str.replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (_, expr) => {
+        const val = expr.split('.').reduce((acc, key) => {
+            if (acc && typeof acc === 'object' && key in acc) {
+                return acc[key];
+            }
+            return undefined;
+        }, ctx);
+        if (val === undefined || val === null)
+            throw new Error(`unresolved template variable {{${expr}}}`);
+        return String(val);
+    });
+}
+export const templateEnv = (env, ctx) => {
+    const out = {};
+    for (const [k, v] of Object.entries(env ?? {}))
+        out[k] = template(v, ctx);
+    return out;
+};
+export class BrokerError extends Error {
+    klass;
+    source;
+    logExcerpt;
+    constructor(klass, message, source, logExcerpt) {
+        super(message);
+        this.klass = klass;
+        this.source = source;
+        this.logExcerpt = logExcerpt;
+    }
+    toJSON() {
+        return { class: this.klass, message: this.message, source: this.source, logExcerpt: this.logExcerpt };
+    }
+}
+/**
+ * A manifest-supplied relative path (sync.include, outputs, a datastore key)
+ * must stay INSIDE its base after resolution — never escape via `..` or an
+ * absolute path. Returns the safe joined absolute path, or throws work-error.
+ * This is the guard that keeps file ops from leaving backlot's own dirs even
+ * on an honest `../shared/.env` typo, not only a malicious manifest.
+ */
+export function safeJoin(base, rel, what) {
+    const { join, resolve, isAbsolute } = pathMod;
+    if (isAbsolute(rel))
+        throw new BrokerError('work-error', `${what} must be a relative path, got absolute '${rel}'`, 'manifest');
+    const abs = resolve(base, rel);
+    const baseResolved = resolve(base);
+    if (abs !== baseResolved && !abs.startsWith(baseResolved + pathMod.sep)) {
+        throw new BrokerError('work-error', `${what} '${rel}' escapes its directory — path traversal is not allowed`, 'manifest');
+    }
+    return abs;
+}
+export const now = () => Date.now();
+export const shortId = () => Math.random().toString(36).slice(2, 8);
+//# sourceMappingURL=util.js.map

package/dist/core/util.js.map

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

package/dist/daemon/engine.d.ts

@@ -0,0 +1,284 @@
+import { Journal } from '../core/journal.js';
+import type { Hygiene, LeaseKind } from '../core/types.js';
+/** Streamed bind phases → human progress on stderr (never on the --json stdout). */
+export type Progress = (phase: string) => void;
+export interface UpOptions {
+    cwd: string;
+    holder?: string;
+    hygiene?: Hygiene;
+    kind?: LeaseKind;
+    watch?: boolean;
+    ttlMs?: number;
+    /** Bind from this directory instead of the worktree (bind --ref extraction). */
+    sourceRoot?: string;
+    /** Set by the daemon per-request; emits progress frames back to the client. */
+    onProgress?: Progress;
+}
+export declare class Engine {
+    readonly journal: Journal;
+    private supervisors;
+    private lastSweep;
+    private lastRetention;
+    private poolChain;
+    private envChains;
+    /** Envs with an operation in flight — the sweeper must not expire/quiesce these. */
+    readonly busy: Set<string>;
+    /** --watch: per-env worktree watchers ("verbs sync, watch streams", decision 0005). */
+    private watchers;
+    private poolLocked;
+    private envLocked;
+    /** Recovery (decision 0009): reap recorded PIDs from a previous daemon life; hot -> warm. */
+    recover(): void;
+    private envDirs;
+    private createEnv;
+    /** One atomic claim attempt — MUST run under the pool lock. */
+    private tryClaim;
+    /** Queue at capacity WITHOUT holding the pool lock while sleeping. */
+    private acquireEnv;
+    private templateCtx;
+    private supervisor;
+    private bindAndStart;
+    /**
+     * --watch: the daemon observes the CONSUMER's worktree (opt-in, per lease)
+     * and auto-syncs debounced. The environment's own dev servers then pick up
+     * the projected change — two-stage reload. Stopped on release/expiry/
+     * quiesce/recycle/shutdown.
+     */
+    private startWatch;
+    private stopWatch;
+    up(opts: UpOptions): Promise<{
+        stack: string;
+        envId: string;
+        state: import("../core/types.js").EnvState;
+        lease: {
+            id: string;
+            kind: LeaseKind;
+            hygiene: Hygiene;
+            expiresAt: number;
+        } | null;
+        urls: Record<string, string>;
+        logins: {
+            user: string;
+            password: string;
+        } | null;
+        tokenCommand: string | null;
+        datastores: {
+            [k: string]: {
+                url: string;
+                ns: string;
+            };
+        };
+        artifactsDir: string;
+        events: import("./supervisor.js").ServiceEvent[];
+    }>;
+    ctx(cwd: string, holder?: string, envId?: string): {
+        stack: string;
+        envId: string;
+        state: import("../core/types.js").EnvState;
+        lease: {
+            id: string;
+            kind: LeaseKind;
+            hygiene: Hygiene;
+            expiresAt: number;
+        } | null;
+        urls: Record<string, string>;
+        logins: {
+            user: string;
+            password: string;
+        } | null;
+        tokenCommand: string | null;
+        datastores: {
+            [k: string]: {
+                url: string;
+                ns: string;
+            };
+        };
+        artifactsDir: string;
+        events: import("./supervisor.js").ServiceEvent[];
+    };
+    run(opts: UpOptions & {
+        check: string;
+    }): Promise<{
+        check: string;
+        ok: boolean;
+        exitCode: number;
+        failure: {
+            class: string;
+            message: string;
+            logExcerpt: string;
+        } | null;
+        output: string;
+        artifactsDir: string | null;
+        outputsChanged: string[];
+        envId: string;
+        durationMs: number;
+    }>;
+    /**
+     * Detached submit-and-poll runs (decision 0015): the verdict outlives the
+     * client. Returns immediately with a jobId; the caller polls jobStatus.
+     * Execution is handed back to the daemon's serialized queue by the server.
+     */
+    createJob(cwd: string, check: string): string;
+    executeJob(id: string, opts: UpOptions & {
+        check: string;
+    }): Promise<void>;
+    jobStatus(id: string): {
+        id: string;
+        check: string;
+        state: string;
+        verdict: unknown;
+        createdAt: number;
+        finishedAt: number | null;
+    };
+    private collectArtifacts;
+    syncLease(cwd: string, holder?: string, onProgress?: Progress): Promise<{
+        stack: string;
+        envId: string;
+        state: import("../core/types.js").EnvState;
+        lease: {
+            id: string;
+            kind: LeaseKind;
+            hygiene: Hygiene;
+            expiresAt: number;
+        } | null;
+        urls: Record<string, string>;
+        logins: {
+            user: string;
+            password: string;
+        } | null;
+        tokenCommand: string | null;
+        datastores: {
+            [k: string]: {
+                url: string;
+                ns: string;
+            };
+        };
+        artifactsDir: string;
+        events: import("./supervisor.js").ServiceEvent[];
+    }>;
+    /** bind --ref: project a COMMITTED ref (not the worktree state) into the env. */
+    bindRef(cwd: string, ref: string, holder?: string): Promise<{
+        stack: string;
+        envId: string;
+        state: import("../core/types.js").EnvState;
+        lease: {
+            id: string;
+            kind: LeaseKind;
+            hygiene: Hygiene;
+            expiresAt: number;
+        } | null;
+        urls: Record<string, string>;
+        logins: {
+            user: string;
+            password: string;
+        } | null;
+        tokenCommand: string | null;
+        datastores: {
+            [k: string]: {
+                url: string;
+                ns: string;
+            };
+        };
+        artifactsDir: string;
+        events: import("./supervisor.js").ServiceEvent[];
+    }>;
+    jobList(): {
+        jobs: {
+            id: string;
+            check: string;
+            state: string;
+            ok: boolean | null;
+            createdAt: number;
+            finishedAt: number | null;
+        }[];
+    };
+    resetData(cwd: string, holder?: string, onProgress?: Progress): Promise<{
+        stack: string;
+        envId: string;
+        state: import("../core/types.js").EnvState;
+        lease: {
+            id: string;
+            kind: LeaseKind;
+            hygiene: Hygiene;
+            expiresAt: number;
+        } | null;
+        urls: Record<string, string>;
+        logins: {
+            user: string;
+            password: string;
+        } | null;
+        tokenCommand: string | null;
+        datastores: {
+            [k: string]: {
+                url: string;
+                ns: string;
+            };
+        };
+        artifactsDir: string;
+        events: import("./supervisor.js").ServiceEvent[];
+    }>;
+    exec(cwd: string, cmd: string, holder?: string): Promise<unknown>;
+    /** Resolve auth.token with {{role}} and run it in the env tree. */
+    token(cwd: string, role: string, holder?: string): Promise<unknown>;
+    logs(cwd: string, service: string, lines: number, holder?: string): {
+        service: string;
+        lines: string;
+    };
+    pull(cwd: string, holder?: string): {
+        pulled: string[];
+    };
+    release(cwd: string, holder?: string): Promise<{
+        released: boolean;
+        envId?: undefined;
+    } | {
+        released: boolean;
+        envId: string;
+    }>;
+    status(): {
+        pid: number;
+        envs: {
+            id: string;
+            stack: string;
+            state: import("../core/types.js").EnvState;
+            ports: Record<string, number>;
+            bindCount: number;
+            lease: import("../core/journal.js").LeaseRow | null;
+            idleMs: number;
+        }[];
+        poolMax: number;
+        events: import("../core/events.js").DaemonEvent[];
+    };
+    /**
+     * doctor: actively check for the failure shapes the review surfaced —
+     * orphaned ports, journal/reality pid divergence, envs stuck recycling.
+     */
+    doctor(): Promise<{
+        ok: boolean;
+        issues: {
+            level: string;
+            envId?: string;
+            issue: string;
+        }[];
+        events: import("../core/events.js").DaemonEvent[];
+    }>;
+    /**
+     * Atomically claim an env for teardown UNDER THE POOL LOCK: re-read it, and
+     * (unless force) refuse if it's leased or busy, then flip it to the
+     * 'recycling' guard state so tryClaim/sweep skip it. Returns the row to tear
+     * down, or null if it slipped away. The slow teardown then runs OUTSIDE the
+     * lock, but no claim can touch a 'recycling' env.
+     */
+    private claimForTeardown;
+    /** Slow teardown of an already-claimed ('recycling') env. */
+    private teardownClaimed;
+    private recycleOne;
+    poolRecycle(all: boolean): Promise<{
+        recycled: string[];
+    }>;
+    /** Reap the provably-dead (degraded) envs now, instead of waiting for the sweep. */
+    poolReconcile(): Promise<{
+        reaped: string[];
+    }>;
+    sweep(): Promise<void>;
+    shutdown(): Promise<void>;
+}