@theford/runly 0.0.0-stage → 0.20.0

package/dist/core/logs.js

@@ -0,0 +1,259 @@
+/**
+ * Service logs on disk (decision 0038).
+ *
+ * Every line a service writes is stored with the time it arrived —
+ * `<ISO-8601> <line>` — so `runly logs` can interleave several services in
+ * order and answer `--since`. Each process start writes a marker line, which
+ * is what `--since up` (this process's output only) finds. A file is capped
+ * (BACKLOT_LOG_CAP_BYTES, default 20 MB) and rotated once: past the cap it
+ * becomes `<name>.log.1`, replacing the previous rotation. Logs live in the
+ * environment's private directory, so they survive idle stops and daemon
+ * restarts and go with the environment.
+ *
+ * Build and upkeep output of the last `up` are kept apart, in
+ * `<service>.build.log` and `upkeep.build.log`, replaced by each new build.
+ */
+import { appendFileSync, closeSync, existsSync, openSync, readSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { policy } from './policy.js';
+export const START_MARKER = '-- runly:';
+const STAMP = /^(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z) (.*)$/;
+/** A stamped start marker line, as it is on disk. */
+const MARKER_LINE = /^\S+Z -- runly:/;
+export const logFileOf = (dir, service) => join(dir, `${service}.log`);
+export const buildLogOf = (dir, service) => join(dir, `${service}.build.log`);
+export const UPKEEP_LOG = 'upkeep';
+/** The marker written when a service process starts; `--since up` reads from the last one. */
+export function startMarker(service, pid, reason) {
+    return `${START_MARKER} ${service} started${pid ? ` (pid ${pid})` : ''}${reason ? ` — ${reason}` : ''} --`;
+}
+/**
+ * Appends time-stamped lines to one service's log. Output arrives in chunks
+ * from two streams; each stream keeps its own partial line, so a line is
+ * stamped once, when it completes, and stdout and stderr never splice into
+ * one line.
+ */
+export class LogWriter {
+    file;
+    cap;
+    size = -1;
+    partial = new Map();
+    constructor(file, cap = policy().logCapBytes) {
+        this.file = file;
+        this.cap = cap;
+    }
+    /** A whole line from runly itself (a start marker). */
+    line(text) {
+        this.flushAll();
+        this.append(`${new Date().toISOString()} ${text}\n`);
+    }
+    /** A chunk of output from `stream` ('out'/'err'). */
+    write(stream, chunk) {
+        if (!chunk)
+            return;
+        const text = (this.partial.get(stream) ?? '') + chunk;
+        const nl = text.lastIndexOf('\n');
+        if (nl < 0) {
+            // Bounded: a process that never prints a newline must not grow memory.
+            if (text.length > 64_000) {
+                this.partial.delete(stream);
+                this.append(`${new Date().toISOString()} ${text}\n`);
+            }
+            else
+                this.partial.set(stream, text);
+            return;
+        }
+        this.partial.set(stream, text.slice(nl + 1));
+        const stamp = new Date().toISOString();
+        const lines = text.slice(0, nl).split('\n');
+        this.append(lines.map((l) => `${stamp} ${l}\n`).join(''));
+    }
+    /** The stream ended: whatever is left of its last line is written. */
+    end(stream) {
+        const rest = this.partial.get(stream);
+        this.partial.delete(stream);
+        if (rest)
+            this.append(`${new Date().toISOString()} ${rest}\n`);
+    }
+    flushAll() {
+        for (const s of [...this.partial.keys()])
+            this.end(s);
+    }
+    append(data) {
+        try {
+            if (this.size < 0)
+                this.size = existsSync(this.file) ? statSync(this.file).size : 0;
+            if (this.size + data.length > this.cap && this.size > 0) {
+                renameSync(this.file, `${this.file}.1`);
+                this.size = 0;
+            }
+            appendFileSync(this.file, data);
+            this.size += Buffer.byteLength(data);
+        }
+        catch {
+            /* log dir gone mid-teardown */
+        }
+    }
+}
+/** Rotate a log past the cap (the retention sweep's backstop for a writer that never rotated). */
+export function rotateIfOver(file, cap) {
+    try {
+        if (statSync(file).size <= cap)
+            return false;
+        renameSync(file, `${file}.1`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the tail of a file (bounded), so a 20 MB log is never one string
+ * twice. `end` stops at that offset (what a follower will read from), so a
+ * line appended meanwhile is read once, by the follower.
+ */
+function readTail(file, maxBytes, end) {
+    try {
+        const size = Math.min(statSync(file).size, end ?? Infinity);
+        const len = Math.min(size, maxBytes);
+        const fd = openSync(file, 'r');
+        try {
+            const buf = Buffer.alloc(len);
+            readSync(fd, buf, 0, len, size - len);
+            const text = buf.toString('utf8');
+            // A cut-off first line is dropped rather than shown half.
+            return len < size ? text.slice(text.indexOf('\n') + 1) : text;
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return '';
+    }
+}
+function parseInto(out, text, service, last) {
+    for (const raw of text.split('\n')) {
+        if (raw === '')
+            continue;
+        const m = STAMP.exec(raw);
+        if (m) {
+            last = Date.parse(m[1]);
+            out.push({ service, at: last, text: m[2], marker: m[2].startsWith(START_MARKER) });
+        }
+        else {
+            out.push({ service, at: last, text: raw, marker: false });
+        }
+    }
+    return last;
+}
+/** Parse one log (its rotation first, then the live file up to `end`) into lines. */
+export function readLog(file, service, maxBytes = 64 * 1024 * 1024, end) {
+    const out = [];
+    let last = NaN;
+    for (const f of [`${file}.1`, file]) {
+        const text = readTail(f, maxBytes, f === file ? end : undefined);
+        if (text)
+            last = parseInto(out, text, service, last);
+    }
+    return out;
+}
+/**
+ * The last lines of one log — at least `want` that are not start markers, or
+ * all there are — read BACKWARDS from `end` in growing chunks, into the
+ * rotation only when the live file runs out. `logs --lines 40` on a 20 MB log
+ * used to parse both whole files to print 40 lines.
+ */
+export function readLastLines(file, service, want, end) {
+    const content = (text) => text.split('\n').filter((l) => l !== '' && !MARKER_LINE.test(l)).length;
+    const chunks = [];
+    let have = 0;
+    for (const f of [file, `${file}.1`]) {
+        if (have >= want)
+            break;
+        let fd;
+        let size;
+        try {
+            size = Math.min(statSync(f).size, f === file ? (end ?? Infinity) : Infinity);
+            fd = openSync(f, 'r');
+        }
+        catch {
+            continue;
+        }
+        try {
+            let pos = size;
+            let held = Buffer.alloc(0);
+            let step = 64 * 1024;
+            let text = '';
+            while (pos > 0) {
+                const len = Math.min(step, pos);
+                pos -= len;
+                const buf = Buffer.alloc(len);
+                readSync(fd, buf, 0, len, pos);
+                held = Buffer.concat([buf, held]);
+                step *= 2;
+                if (pos === 0) {
+                    text = held.toString('utf8');
+                    break;
+                }
+                // Whole lines only: what follows the first newline of what is held.
+                const nl = held.indexOf(0x0a);
+                if (nl < 0)
+                    continue;
+                const whole = held.subarray(nl + 1).toString('utf8');
+                if (have + content(whole) >= want) {
+                    text = whole;
+                    break;
+                }
+            }
+            have += content(text);
+            chunks.unshift(text);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    const out = [];
+    let last = NaN;
+    for (const text of chunks)
+        last = parseInto(out, text, service, last);
+    return out;
+}
+/** Mark every line before the last start marker as `prior` (an earlier process's). */
+export function markPrior(lines) {
+    let lastMarker = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (lines[i].marker) {
+            lastMarker = i;
+            break;
+        }
+    }
+    return lines.map((l, i) => (i < lastMarker ? { ...l, prior: true } : l));
+}
+/** Only the lines of the CURRENT process: from the last start marker on. */
+export function sinceLastStart(lines) {
+    for (let i = lines.length - 1; i >= 0; i--)
+        if (lines[i].marker)
+            return lines.slice(i);
+    return lines;
+}
+/** Interleave several services' lines by time (stable within one service). */
+export function interleave(groups) {
+    const all = groups.flatMap((g, gi) => g.map((l, i) => ({ l, gi, i })));
+    all.sort((a, b) => {
+        const ta = Number.isNaN(a.l.at) ? -Infinity : a.l.at;
+        const tb = Number.isNaN(b.l.at) ? -Infinity : b.l.at;
+        return ta - tb || (a.gi === b.gi ? a.i - b.i : a.gi - b.gi);
+    });
+    return all.map((x) => x.l);
+}
+/** Start a build log afresh for this build. */
+export function beginBuildLog(file, header) {
+    try {
+        writeFileSync(file, `${new Date().toISOString()} ${START_MARKER} ${header} --\n`);
+    }
+    catch {
+        /* no log dir (warm without an environment) */
+    }
+}
+//# sourceMappingURL=logs.js.map

package/dist/core/logs.js.map

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

package/dist/core/manifest.d.ts

@@ -0,0 +1,292 @@
+export interface ReadySpec {
+    http?: string;
+    log?: string;
+    cmd?: string;
+    timeout?: number;
+}
+/**
+ * What a service (or an appliance) costs the box, for the server-wide load
+ * budget (decision 0036). `memory` is a size (`600M`, `2G`, or bytes), `cpu`
+ * a number of cores. `build` is what its build costs while it runs. Anything
+ * left out is a conservative default, and `runly plan` says so.
+ */
+export interface ResourceSpec {
+    memory?: string | number;
+    cpu?: number;
+    build?: {
+        memory?: string | number;
+        cpu?: number;
+    };
+}
+/**
+ * A build step. The string form runs on every `up` that starts or keeps the
+ * service. The object form adds `when:` — globs of the files the build reads;
+ * when none of the matched files changed (path, size, mtime) since the last
+ * SUCCESSFUL build of this service in this worktree, the build is skipped
+ * (decision 0038).
+ */
+export type BuildSpec = string | {
+    run: string;
+    when?: string[];
+    serial?: boolean;
+};
+/**
+ * What a build produces. String/array form: globs compared by path, size and
+ * mtime. Object form: `compare: content` hashes the files instead, so a build
+ * that rewrites identical files does not restart the service (decision 0038).
+ */
+export type OutputsSpec = string | string[] | {
+    paths: string[];
+    compare?: 'stat' | 'content';
+};
+/** The build line and its `when:` globs, whichever form the manifest used. */
+export declare function buildOf(spec: {
+    build?: BuildSpec;
+}): {
+    run: string;
+    when?: string[];
+    serial?: boolean;
+} | undefined;
+/** The output globs and how they are compared, whichever form the manifest used. */
+export declare function outputsOf(spec: {
+    outputs?: OutputsSpec;
+}): {
+    paths: string[];
+    compare: 'stat' | 'content';
+};
+export interface ServiceSpec {
+    run: string;
+    build?: BuildSpec;
+    /**
+     * How long this service may sit with no client bytes through its public
+     * port and no runly verb on its environment before it is stopped (decision
+     * 0035). A duration (`90s`, `10m`, `2h`), seconds as a number, or `never`.
+     * Default: BACKLOT_SERVICE_IDLE_MS (10 minutes).
+     */
+    idle?: string | number;
+    resources?: ResourceSpec;
+    /** Accepted and ignored since decision 0032 (`--watch` was removed). */
+    watch_run?: string;
+    /** Accepted and ignored since decision 0032: a service without `build:` keeps running on `up` anyway. */
+    hot_reload?: boolean;
+    /**
+     * Globs (relative to the stack root) of what this service's `build:`
+     * produces. Snapshotted (path, size, mtime) around the build on every `up`;
+     * the service is restarted only when they changed. Without it, a service
+     * with a build is restarted after every build (decision 0032).
+     */
+    outputs?: OutputsSpec;
+    cwd?: string;
+    port?: string;
+    env?: Record<string, string>;
+    /** Allowlisted inputs supplied by the caller, retained only in lease memory. */
+    env_from?: Record<string, 'required' | 'optional'>;
+    ready?: ReadySpec;
+    fatal_logs?: string;
+    depends_on?: string[];
+}
+export interface DatastoreSpec {
+    driver: 'sqlite' | 'postgres' | 'mssql' | 'mysql' | 'redis';
+    server?: 'external';
+    probe?: string;
+    url?: string;
+    create?: string;
+    drop?: string;
+    template_restore?: string;
+    presets?: string[];
+    /** One preset name; the pre-0.13 `{run, session}` split is accepted and read as one value (session, then run). */
+    default_preset?: string | {
+        run?: string;
+        session?: string;
+    };
+    template?: boolean;
+    ephemeral?: boolean;
+    /**
+     * Never provisioned for an environment (decision 0039): it exists only as
+     * the source of `runly db new|with` copies. Its template is baked on the
+     * first copy and reused by the next. No service may template it, `ctx`
+     * does not list it, and `up --preset` / `reset-data` cannot name it.
+     */
+    copies_only?: boolean;
+    /**
+     * Share this datastore's templates with every worktree of the same manifest
+     * name on this daemon (decision 0044). Default true; it applies only to a
+     * content-keyed template (an `@rebake-template` rule names the datastore).
+     * Set false when the baked content depends on the worktree beyond its
+     * trigger files (an absolute path written into the data, say).
+     */
+    share_templates?: boolean;
+    /**
+     * Repo command printing the namespaces ({{ns}} values) of this datastore
+     * that exist on its server, one per line. Only `runly pool doctor` reads it:
+     * a listed name that matches runly's naming and no journal row references is
+     * an orphan, and `--fix` drops it with `drop:` (decision 0037).
+     */
+    list?: string;
+}
+export interface ApplianceSpec {
+    /** host:port whose reachability IS the appliance's identity. */
+    probe: string;
+    /** Daemonizing command run once (machine-wide) when the probe fails. */
+    start?: string;
+    /** Command for the explicit stop verb; never run automatically. */
+    stop?: string;
+    /** Optional readiness gate polled after TCP accepts (exit 0 = ready). */
+    ready?: string;
+    /** Seconds to wait after start for probe+ready. Default 60. */
+    timeout?: number;
+    /** What it costs while running, counted against the load budget when runly would start it (decision 0036). */
+    resources?: ResourceSpec;
+}
+export interface UpkeepRule {
+    when: string;
+    run: string;
+    /** Hard process-group deadline in seconds; default 300, global override wins. */
+    timeout?: number;
+    /**
+     * Paths (relative to the stack root) the rule's command leaves behind — an
+     * install's `node_modules/.modules.yaml`, a generated client's directory. A
+     * rule whose trigger is unchanged runs again when any of them is missing
+     * (a `git clean -fdx` removed it). A rule without `outputs:` is forgotten by
+     * `runly destroy` instead, so the next `up` after a pool reset runs it.
+     */
+    outputs?: string | string[];
+}
+/** A rule's declared `outputs:` as a list (empty when it declares none). */
+export declare const upkeepOutputs: (rule: {
+    outputs?: string | string[];
+}) => string[];
+/**
+ * A seeded, dev-grade login the stack advertises to consumers. `role` names the
+ * `{{role}}` an `auth.token` hook would take; `description` says what the login is
+ * FOR, so a consumer picks the right one without reading the seed.
+ */
+export interface Login {
+    user: string;
+    password: string;
+    role?: string;
+    description?: string;
+}
+/**
+ * `auth.logins` accepts a single login (the original form) or a list. The list's
+ * FIRST entry is the primary one — see `normalizeLogins`.
+ */
+export type LoginsSpec = Login | Login[];
+/**
+ * One shape for consumers regardless of which form the manifest used: `[]` when no
+ * login is declared, otherwise every declared login in order. A single-object
+ * manifest yields exactly one entry, so callers never branch on the manifest form.
+ */
+export declare function normalizeLogins(spec: LoginsSpec | undefined): Login[];
+export interface PreviewSpec {
+    /**
+     * When true, `runly preview` is refused (work-error). Stacks with fixed dev
+     * credentials or a known signing key must set this.
+     */
+    forbidden?: boolean;
+    /**
+     * Named preview publisher adapter (default: cloudflare-quick). Known:
+     * `cloudflare-quick`, `cloudflare-named`, `tailscale` (tailnet-only HTTPS via
+     * `tailscale serve`, decision 0031).
+     */
+    publisher?: string;
+    /**
+     * Zone a naming publisher publishes under, e.g. `example.dev`. Required by
+     * `cloudflare-named`; meaningless to `cloudflare-quick`, which is handed its
+     * hostname by Cloudflare.
+     */
+    domain?: string;
+    /**
+     * What makes a hostname this environment's own.
+     *
+     * A naming publisher derives `<service>-<prefix>.<domain>`, so two
+     * environments sharing a prefix want the same name — and the second one takes
+     * it from the first. The manifest is the wrong place to make that unique: a
+     * pooled stack has several environments and one manifest. Left unset, the
+     * environment id supplies the prefix, which is unique by construction. Set it
+     * only to pin a name a human has to remember, and only where one environment
+     * of this stack runs at a time.
+     */
+    prefix?: string;
+    /**
+     * The HTTPS port on this machine's tailnet name that the `tailscale` publisher
+     * serves on (`https://<machine>.<tailnet>.ts.net:<port>`). Unset means a port
+     * derived from the environment id and service, stable for the environment's
+     * lifetime and moved past any port this machine already serves. Pin it only
+     * for an address a human has to remember, and only where one environment of
+     * this stack publishes at a time — a second publish of a pinned port is
+     * refused rather than taken over. Ignored by the Cloudflare publishers.
+     */
+    https_port?: number;
+}
+export interface Manifest {
+    name: string;
+    services: Record<string, ServiceSpec>;
+    preview?: PreviewSpec;
+    appliances?: Record<string, ApplianceSpec>;
+    datastores?: Record<string, DatastoreSpec>;
+    /**
+     * How one `up` runs its builds: `parallel` (default) in depends_on waves,
+     * the builds of one wave at once; `serial` one at a time in manifest order.
+     */
+    builds?: 'parallel' | 'serial';
+    /** Build/install output in the worktree: never an upkeep trigger (decision 0032). */
+    caches?: string[];
+    /** `include`: git-ignored files an upkeep `when:` glob may still match. `keep` is accepted and ignored (decision 0032). */
+    sync?: {
+        keep?: string[];
+        include?: string[];
+    };
+    /** Accepted and ignored since decision 0032 (it served `runly run`). */
+    outputs?: string[];
+    upkeep?: UpkeepRule[];
+    auth?: {
+        logins?: LoginsSpec;
+        token?: string;
+    };
+    /**
+     * Accepted and ignored since decision 0032: `runly run` was removed. Repo
+     * scripts read `runly ctx --env` instead. A manifest that still declares it
+     * loads, with a one-line deprecation warning (`manifestDeprecations`).
+     */
+    checks?: Record<string, unknown>;
+}
+/**
+ * One-line warnings for manifest sections runly accepts but no longer acts on.
+ * The CLI prints them to stderr; the manifest still loads.
+ */
+export declare function manifestDeprecations(manifest: Manifest, file?: string): string[];
+export interface Stack {
+    manifest: Manifest;
+    /** Directory containing the manifest — the worktree environments run in (decision 0032). */
+    root: string;
+    /** Stable identity: pools are keyed by this. */
+    id: string;
+    /** The manifest's file name as found (runly.yml, backlot.yml or stack.yaml), for messages. */
+    file?: string;
+}
+/** The manifest's file name for a message: the one actually loaded. */
+export declare const manifestFileOf: (stack?: {
+    file?: string;
+}) => string;
+/** Walk upward from cwd to the nearest manifest. */
+/** runly.yml is canonical; backlot.yml and stack.yaml stay accepted so
+ * existing consumers survive the upgrade. When several exist, runly.yml wins —
+ * a rename, not a coin toss. */
+export declare const MANIFEST_NAMES: readonly ["runly.yml", "backlot.yml", "stack.yaml"];
+export declare function canonicalDirectory(from: string): string;
+export declare function stackIdentity(name: string, root: string): string;
+export declare function findStackRoot(from: string): string;
+/**
+ * Find, read and validate the manifest from `from` upward. `validate: false`
+ * skips the schema check — only for a CLI-side read whose result the daemon
+ * re-reads and validates before acting on it (the deprecation warnings).
+ */
+export declare function loadStack(from: string, opts?: {
+    validate?: boolean;
+}): Stack;
+/** The datastores an environment provisions: every declared one except `copies_only` (decision 0039). */
+export declare function envDatastoreNames(manifest: Manifest): string[];
+/** The declared default preset, if any — one value, whichever form the manifest used. */
+export declare function declaredDefaultPreset(ds: DatastoreSpec): string | undefined;
+export declare function defaultPreset(ds: DatastoreSpec): string;