@theford/runly 0.0.0-stage → 0.20.0

package/dist/core/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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';
+/** Every lease is a session lease (decision 0032); a `run` row from a pre-0.13 journal is read as one. */
+export type LeaseKind = 'session';
+/** The field an agent branches on mechanically (decision 0010). */
+export type ErrorClass = 'work-error' | 'env-error' | 'infra-error';
+/**
+ * A recorded service process. `startTime` (kernel clock ticks since boot,
+ * Linux only) pins the pid to one process *life*, so a later daemon can tell
+ * "still my service" from "the OS reused that pid" before signalling it.
+ */
+export interface ServicePid {
+    pid: number;
+    startTime?: number;
+    pgid?: number;
+    pgids?: number[];
+}

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/units.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The two units a manifest and the policy knobs speak: durations (`90s`,
+ * `10m`, `2h`) and sizes (`600M`, `2G`). Parsing lives in one place so the
+ * schema, the engine and `runly plan` can never disagree about what `2G` is.
+ */
+/**
+ * A duration in milliseconds. Strings take a unit (`ms`, `s`, `m`, `h`, `d`);
+ * a bare number is SECONDS (the manifest convention, like `timeout:`).
+ * `never`/`off` is Infinity. Returns undefined for anything unreadable.
+ */
+export declare function parseDuration(v: unknown): number | undefined;
+/**
+ * A size in bytes. Numbers are bytes; strings take K/M/G/T (binary multiples,
+ * with or without `i`/`B`): `600M`, `2G`, `1.5GiB`. Undefined when unreadable.
+ */
+export declare function parseSize(v: unknown): number | undefined;
+/** `2.0G`, `600M`, `12K` — for humans, one decimal at most. */
+export declare function formatSize(bytes: number): string;
+/** `45s`, `10m`, `1.5h`. */
+export declare function formatDuration(ms: number): string;

package/dist/core/units.js

@@ -0,0 +1,69 @@
+/**
+ * The two units a manifest and the policy knobs speak: durations (`90s`,
+ * `10m`, `2h`) and sizes (`600M`, `2G`). Parsing lives in one place so the
+ * schema, the engine and `runly plan` can never disagree about what `2G` is.
+ */
+/**
+ * A duration in milliseconds. Strings take a unit (`ms`, `s`, `m`, `h`, `d`);
+ * a bare number is SECONDS (the manifest convention, like `timeout:`).
+ * `never`/`off` is Infinity. Returns undefined for anything unreadable.
+ */
+export function parseDuration(v) {
+    if (typeof v === 'number')
+        return Number.isFinite(v) && v >= 0 ? v * 1000 : undefined;
+    if (typeof v !== 'string')
+        return undefined;
+    const s = v.trim().toLowerCase();
+    if (s === 'never' || s === 'off')
+        return Infinity;
+    const m = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?$/.exec(s);
+    if (!m)
+        return undefined;
+    const n = Number(m[1]);
+    const unit = m[2] ?? 's';
+    const mult = unit === 'ms' ? 1 : unit === 's' ? 1000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000;
+    return n * mult;
+}
+/**
+ * A size in bytes. Numbers are bytes; strings take K/M/G/T (binary multiples,
+ * with or without `i`/`B`): `600M`, `2G`, `1.5GiB`. Undefined when unreadable.
+ */
+export function parseSize(v) {
+    if (typeof v === 'number')
+        return Number.isFinite(v) && v >= 0 ? v : undefined;
+    if (typeof v !== 'string')
+        return undefined;
+    const m = /^(\d+(?:\.\d+)?)\s*([kmgt])?(i?b)?$/i.exec(v.trim());
+    if (!m)
+        return undefined;
+    const n = Number(m[1]);
+    const unit = (m[2] ?? '').toLowerCase();
+    const exp = unit === 'k' ? 1 : unit === 'm' ? 2 : unit === 'g' ? 3 : unit === 't' ? 4 : 0;
+    return Math.round(n * 1024 ** exp);
+}
+/** `2.0G`, `600M`, `12K` — for humans, one decimal at most. */
+export function formatSize(bytes) {
+    if (!Number.isFinite(bytes))
+        return '∞';
+    const units = ['B', 'K', 'M', 'G', 'T'];
+    let v = Math.max(0, bytes);
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v >= 10 || i === 0 ? Math.round(v) : v.toFixed(1)}${units[i]}`;
+}
+/** `45s`, `10m`, `1.5h`. */
+export function formatDuration(ms) {
+    if (!Number.isFinite(ms))
+        return 'never';
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    if (ms < 60_000)
+        return `${Math.round(ms / 1000)}s`;
+    if (ms < 3_600_000)
+        return `${Math.round(ms / 60_000)}m`;
+    return `${(ms / 3_600_000).toFixed(1)}h`;
+}
+//# sourceMappingURL=units.js.map

package/dist/core/units.js.map

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

package/dist/core/upkeep.d.ts

@@ -0,0 +1,90 @@
+import { type Manifest } from './manifest.js';
+export interface UpkeepStep {
+    /** 1-based position in the manifest's upkeep list — progress never names the command. */
+    index: number;
+    when: string;
+    /** `ran` executed now; `fresh` matched the ledger; `skipped` was not this caller's to run. */
+    status: 'ran' | 'fresh' | 'skipped';
+    durationMs: number;
+    reason?: string;
+}
+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[];
+    steps: UpkeepStep[];
+}
+export interface UpkeepOptions {
+    /**
+     * Evaluate `@` built-ins (default true). They act on an environment's data
+     * (`@rebake-template`), so `runly warm` — which has no environment — skips
+     * them and reports why.
+     */
+    builtins?: boolean;
+    /**
+     * Persist the ledger as it moves. Called with the rule's key REMOVED before
+     * its command runs, and with the new hash after it succeeds: a rule that fails
+     * half-way has left the worktree in neither state, and a ledger still naming
+     * the old trigger would let a later revert to that trigger skip the repair.
+     */
+    commit?: (fingerprints: Record<string, string>) => void;
+    /** Receives each command rule's output as it runs (`upkeep.build.log`, decision 0038). */
+    onOutput?: {
+        begin: (label: string) => void;
+        data: (stream: 'out' | 'err', chunk: string) => void;
+        end: (stream: 'out' | 'err') => void;
+    };
+}
+export declare const ruleKey: (rule: {
+    when: string;
+    run: string;
+}) => string;
+/**
+ * The worktree files any upkeep rule's `when:` glob matches — the only files a
+ * bind reads to decide what upkeep is due. Empty, without asking git, when the
+ * manifest declares no rules.
+ */
+export declare function triggerFiles(root: string, manifest: Manifest): Promise<string[]>;
+/**
+ * The trigger files with their content hashes, read once per bind.
+ *
+ * Trigger globs can match large files — a consumer's database backups are
+ * 160 MB, named by several @rebake-template rules each — so hashing them per
+ * rule on every bind would re-read the same bytes several times on the
+ * daemon's thread. Each file is hashed once per bind, and only when its
+ * (size, mtime) moved since the cache under `cacheDir` recorded it. The cache
+ * holds the trigger files and nothing else, and lives in the state root.
+ *
+ * Filesystem mtimes are coarse, so a same-size rewrite inside one timestamp
+ * tick of the recorded stat is indistinguishable from the file already hashed.
+ * git's "racily clean" rule applies: an entry whose mtime is not strictly older
+ * than the cache write (minus a window) is re-hashed.
+ */
+export interface TriggerSet {
+    files: string[];
+    hashOf: (rel: string) => string | null;
+}
+export declare function triggerSet(root: string, manifest: Manifest, cacheDir?: string): Promise<TriggerSet>;
+/** The fingerprint of one `when:` glob: the content of exactly the files it matches. */
+export declare function triggerHash(root: string, files: string[] | TriggerSet, when: string): string;
+/**
+ * Content-derived bake key per datastore (vetbill-1i49).
+ *
+ * The baked-template identity used to hash only the static `create:` command
+ * string — identical for every branch — so two environments of the same stack
+ * whose trees carry *different* migrations/seeds could silently share one
+ * template with the wrong schema. The @rebake-template rules already declare
+ * exactly which files define a datastore's baked content; hashing those
+ * files' current contents into the template name makes divergent content
+ * yield disjoint templates by construction (rebake becomes cleanup, not the
+ * only line of defense).
+ *
+ * Datastores with no @rebake-template rule get no key (undefined) and keep
+ * their historical template names — existing bakes stay valid.
+ */
+export declare function templateBakeKeys(manifest: Manifest, root: string, files: string[] | TriggerSet): Record<string, string>;
+export declare function runUpkeep(root: string, files: string[] | TriggerSet, manifest: Manifest, previous: Record<string, string>, onProgress?: (phase: string) => void, opts?: UpkeepOptions): Promise<UpkeepOutcome>;

package/dist/core/upkeep.js

@@ -0,0 +1,176 @@
+/**
+ * The fingerprint ledger (decision 0008): a closed list of (trigger -> action)
+ * rules, evaluated at bind (and `runly warm`) time, direction-agnostic. Actions
+ * are repo commands, or engine built-ins prefixed with @.
+ *
+ * A rule's fingerprint is the content of the files its `when:` glob matches —
+ * those files and nothing else (decision 0032). runly keeps no identity of the
+ * rest of the worktree and no record of builds.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cmdTimeoutS, runBounded } from './exec.js';
+import { existsSync } from 'node:fs';
+import { globToRegex, sha256, fileHash, BrokerError, commandFailure, safeJoin } from './util.js';
+import { enumerateSource, enumerateSourceStats } from './worktree.js';
+import { upkeepOutputs } from './manifest.js';
+export const ruleKey = (rule) => `${rule.when} -> ${rule.run}`;
+/**
+ * The worktree files any upkeep rule's `when:` glob matches — the only files a
+ * bind reads to decide what upkeep is due. Empty, without asking git, when the
+ * manifest declares no rules.
+ */
+export async function triggerFiles(root, manifest) {
+    const whens = (manifest.upkeep ?? []).map((rule) => rule.when);
+    return whens.length === 0 ? [] : enumerateSource(root, manifest, whens);
+}
+const RACY_WINDOW_MS = 2000;
+export async function triggerSet(root, manifest, cacheDir) {
+    // The listing's own stat is the cache's check: one stat per trigger file.
+    const whens = (manifest.upkeep ?? []).map((rule) => rule.when);
+    const listed = whens.length === 0 ? [] : await enumerateSourceStats(root, manifest, whens);
+    const files = listed.map((f) => f.path);
+    const statOfListed = new Map(listed.map((f) => [f.path, f]));
+    let cache = { entries: {} };
+    if (cacheDir) {
+        try {
+            const raw = JSON.parse(readFileSync(join(cacheDir, 'triggers.json'), 'utf8'));
+            if (raw && typeof raw === 'object' && raw.entries && typeof raw.entries === 'object')
+                cache = raw;
+        }
+        catch {
+            /* absent or torn: hash everything once */
+        }
+    }
+    const racyFrom = cache.writtenAt === undefined ? -Infinity : cache.writtenAt - RACY_WINDOW_MS;
+    const next = {};
+    const hashes = new Map();
+    for (const rel of files) {
+        const abs = join(root, rel);
+        const st = statOfListed.get(rel);
+        if (!st) {
+            hashes.set(rel, null);
+            continue;
+        }
+        const cached = cache.entries[rel];
+        const trust = cached !== undefined && cached.size === st.size && cached.mtime === st.mtimeMs && cached.mtime < racyFrom;
+        const hash = trust ? cached.hash : fileHash(abs);
+        hashes.set(rel, hash);
+        if (hash !== null)
+            next[rel] = { hash, size: st.size, mtime: st.mtimeMs };
+    }
+    if (cacheDir) {
+        mkdirSync(cacheDir, { recursive: true });
+        const tmp = join(cacheDir, `triggers.json.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`);
+        writeFileSync(tmp, JSON.stringify({ root, writtenAt: Date.now(), entries: next }));
+        renameSync(tmp, join(cacheDir, 'triggers.json'));
+    }
+    return { files, hashOf: (rel) => (hashes.has(rel) ? (hashes.get(rel) ?? null) : fileHash(join(root, rel))) };
+}
+/** The fingerprint of one `when:` glob: the content of exactly the files it matches. */
+export function triggerHash(root, files, when) {
+    const re = globToRegex(when);
+    const list = Array.isArray(files) ? files : files.files;
+    const hashOf = Array.isArray(files) ? (rel) => fileHash(join(root, rel)) : files.hashOf;
+    const matching = list.filter((f) => re.test(f)).sort();
+    return sha256(matching.map((f) => `${f}:${hashOf(f) ?? 'gone'}`).join('\n'));
+}
+/**
+ * Content-derived bake key per datastore (vetbill-1i49).
+ *
+ * The baked-template identity used to hash only the static `create:` command
+ * string — identical for every branch — so two environments of the same stack
+ * whose trees carry *different* migrations/seeds could silently share one
+ * template with the wrong schema. The @rebake-template rules already declare
+ * exactly which files define a datastore's baked content; hashing those
+ * files' current contents into the template name makes divergent content
+ * yield disjoint templates by construction (rebake becomes cleanup, not the
+ * only line of defense).
+ *
+ * Datastores with no @rebake-template rule get no key (undefined) and keep
+ * their historical template names — existing bakes stay valid.
+ */
+export function templateBakeKeys(manifest, root, files) {
+    const perDs = {};
+    for (const rule of manifest.upkeep ?? []) {
+        if (!rule.run.startsWith('@rebake-template'))
+            continue;
+        const target = rule.run.slice('@rebake-template'.length).trim() || 'main';
+        (perDs[target] ??= []).push(triggerHash(root, files, rule.when));
+    }
+    return Object.fromEntries(Object.entries(perDs).map(([ds, hashes]) => [ds, sha256(hashes.sort().join('\n')).slice(0, 12)]));
+}
+export async function runUpkeep(root, files, manifest, previous, onProgress, opts = {}) {
+    const outcome = { ran: [], fingerprints: { ...previous }, rebakeTemplates: [], steps: [] };
+    const builtins = opts.builtins ?? true;
+    for (const [index, rule] of (manifest.upkeep ?? []).entries()) {
+        const key = ruleKey(rule);
+        const position = index + 1;
+        if (rule.run.startsWith('@') && !builtins) {
+            outcome.steps.push({ index: position, when: rule.when, status: 'skipped', durationMs: 0, reason: 'acts on an environment\'s data; the next bind applies it' });
+            continue;
+        }
+        const hash = triggerHash(root, files, rule.when);
+        // Its trigger is unchanged — but a rule that declares what it leaves
+        // behind is due again when that is gone (a pool's `git clean -fdx`).
+        const missing = rule.run.startsWith('@') ? undefined : upkeepOutputs(rule).find((o) => !existsSync(safeJoin(root, o, 'upkeep outputs')));
+        if (previous[key] === hash && missing === undefined) {
+            outcome.steps.push({ index: position, when: rule.when, status: 'fresh', durationMs: 0 });
+            continue;
+        }
+        if (previous[key] === hash)
+            onProgress?.(`upkeep rule ${position}: its output ${missing} is missing — running it again`);
+        const started = Date.now();
+        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 {
+            // Bounded like every other repo-declared command: an install blocking on
+            // a half-up registry used to hold the env's busy bit until the daemon
+            // was killed.
+            const timeoutS = cmdTimeoutS(rule.timeout);
+            // Commands and their output may contain credentials. Progress names only
+            // the manifest rule's position, never its command or captured output.
+            const label = `upkeep rule ${position}`;
+            onProgress?.(`${label}: starting (timeout ${timeoutS}s)`);
+            delete outcome.fingerprints[key];
+            opts.commit?.(outcome.fingerprints);
+            const heartbeat = onProgress && setInterval(() => {
+                onProgress(`${label}: running (${Math.floor((Date.now() - started) / 1000)}s elapsed)`);
+            }, 5000);
+            heartbeat?.unref();
+            let r;
+            try {
+                opts.onOutput?.begin(`${label} (when: ${rule.when})`);
+                r = await runBounded(rule.run, root, timeoutS, undefined, opts.onOutput);
+            }
+            finally {
+                if (heartbeat)
+                    clearInterval(heartbeat);
+            }
+            if (r.timedOut) {
+                onProgress?.(`${label}: timed out after ${timeoutS}s`);
+                throw new BrokerError('work-error', `upkeep rule timed out after ${timeoutS}s (process group killed): ${rule.run}`, rule.when, r.output.slice(-800));
+            }
+            if (r.code !== 0) {
+                onProgress?.(`${label}: failed (${Math.floor((Date.now() - started) / 1000)}s elapsed)`);
+                // Triggered by the binding's own change -> work-error by default (decision 0008).
+                throw commandFailure(`upkeep rule failed: ${rule.run}`, rule.when, r.output);
+            }
+            onProgress?.(`${label}: finished (${Math.floor((Date.now() - started) / 1000)}s elapsed)`);
+        }
+        outcome.ran.push({ when: rule.when, run: rule.run });
+        outcome.fingerprints[key] = hash;
+        if (!rule.run.startsWith('@'))
+            opts.commit?.(outcome.fingerprints);
+        outcome.steps.push({ index: position, when: rule.when, status: 'ran', durationMs: Date.now() - started });
+    }
+    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,46 @@
+export declare const sha256: (data: string | Buffer) => string;
+/**
+ * Run a shell command, swallowing failures (best-effort cleanup paths).
+ * Bounded: these run inside awaited sweeps, and a hung `drop` against an
+ * unreachable appliance used to stall retention forever while each later
+ * sweep piled another wedged `sh` onto the same marker.
+ */
+export declare const runQuiet: (cmd: string, cwd: string) => Promise<void>;
+export declare const fileHash: (path: string) => string | null;
+/** One stat, no throw: what a listing of tens of thousands of files can afford per file. */
+export declare const statOf: (p: string) => import("node:fs").Stats | undefined;
+export declare const isFile: (p: string) => boolean;
+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" | "env-error" | "infra-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 runly'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;
+/** A hint naming the daemon's environment when `output` looks like one, else undefined. */
+export declare function environmentHint(output: string): string | undefined;
+/**
+ * A failed repo command as an error: env-error with the hint when it reads as
+ * a missing tool or runtime, else `klass` (work-error: the code's fault).
+ */
+export declare function commandFailure(message: string, source: string | undefined, output: string, klass?: 'work-error' | 'env-error'): BrokerError;
+export declare const now: () => number;
+export declare const shortId: () => string;

package/dist/core/util.js

@@ -0,0 +1,168 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import * as pathMod from 'node:path';
+import { cmdTimeoutS, runBounded } from './exec.js';
+export const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+/**
+ * Run a shell command, swallowing failures (best-effort cleanup paths).
+ * Bounded: these run inside awaited sweeps, and a hung `drop` against an
+ * unreachable appliance used to stall retention forever while each later
+ * sweep piled another wedged `sh` onto the same marker.
+ */
+export const runQuiet = (cmd, cwd) => runBounded(cmd, cwd, cmdTimeoutS()).then(() => undefined);
+export const fileHash = (path) => {
+    try {
+        return sha256(readFileSync(path));
+    }
+    catch {
+        return null;
+    }
+};
+/** One stat, no throw: what a listing of tens of thousands of files can afford per file. */
+export const statOf = (p) => statSync(p, { throwIfNoEntry: false });
+export const isFile = (p) => statOf(p)?.isFile() ?? false;
+/**
+ * Minimal glob matcher for manifest patterns (caches, sync.include, outputs,
+ * upkeep and build `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 /**).
+ *
+ * `**` is anchored at path segments: a leading or inner `**\/` stands for zero
+ * or more WHOLE directories, so `**\/bin` matches `bin` and `src/bin` but never
+ * `src/Cabin` (it used to compile to `^.*bin`, which made a .NET
+ * `caches: [**\/bin]` swallow every source directory whose name ends in "bin").
+ * `*` and `?` stay inside one segment. Dotfiles are not special.
+ *
+ * Compiled patterns are cached: the same few manifest globs are matched
+ * against every file of a worktree listing, and compiling them per file cost
+ * seconds per `up` on a large tree.
+ */
+const globCache = new Map();
+const GLOB_CACHE_MAX = 4096;
+export function globToRegex(pattern) {
+    const hit = globCache.get(pattern);
+    if (hit)
+        return hit;
+    const re = compileGlob(pattern);
+    if (globCache.size >= GLOB_CACHE_MAX)
+        globCache.clear();
+    globCache.set(pattern, re);
+    return re;
+}
+function compileGlob(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] === '*') {
+                const segmentStart = i === 0 || p[i - 1] === '/';
+                if (segmentStart && p[i + 2] === '/') {
+                    // `**/`: zero or more whole directories.
+                    re += '(?:.*/)?';
+                    i += 2;
+                }
+                else {
+                    // A trailing `**` (everything below), or `**` inside a segment.
+                    re += '.*';
+                    i++;
+                }
+            }
+            else
+                re += '[^/]*';
+        }
+        else if (c === '?')
+            re += '[^/]';
+        else
+            re += c.replace(/[.+^${}()|\\[\]]/g, '\\$&');
+    }
+    return new RegExp(`^${re}(/.*)?$`);
+}
+export const matchesAny = (path, patterns) => {
+    for (const p of patterns)
+        if (globToRegex(p).test(path))
+            return true;
+    return false;
+};
+/** 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 runly's own dirs even
+ * on an honest `../shared/.env` typo, not only a malicious manifest.
+ */
+export function safeJoin(base, rel, what) {
+    const { 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;
+}
+/**
+ * The output of a failed command that reads as a missing tool or runtime — the
+ * DAEMON's environment, not the repo's code. Under a unit it is the
+ * environment `runly daemon install` captured; a missing DOTNET_ROOT once made
+ * every template bake fail there, reported as the code's fault.
+ */
+const ENVIRONMENTAL = /command not found|: not found\b|You must install or update \.NET|\.NET location: Not found|DOTNET_ROOT|spawn \S+ ENOENT|exec format error|cannot execute binary|env: '?[^\s']+'?: No such file or directory/i;
+/** A hint naming the daemon's environment when `output` looks like one, else undefined. */
+export function environmentHint(output) {
+    if (!ENVIRONMENTAL.test(output))
+        return undefined;
+    const sup = process.env.RUNLY_SUPERVISOR;
+    return sup === 'systemd' || sup === 'launchd'
+        ? ` — this looks like the daemon's environment, not the code: a tool or runtime was not found. The daemon runs under its ${sup} unit with the environment 'runly daemon install' captured (it prints it); re-run the install from a shell that has the tool, or add a variable with --env NAME, then 'runly daemon stop' — the next verb starts it again`
+        : ` — this looks like the daemon's environment, not the code: a tool or runtime was not found. The daemon kept the environment of the shell that started it; 'runly daemon stop', and the next verb starts it from yours`;
+}
+/**
+ * A failed repo command as an error: env-error with the hint when it reads as
+ * a missing tool or runtime, else `klass` (work-error: the code's fault).
+ */
+export function commandFailure(message, source, output, klass = 'work-error') {
+    const hint = environmentHint(output);
+    return new BrokerError(hint ? 'env-error' : klass, `${message}${hint ?? ''}`, source, output.slice(-800));
+}
+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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"}