omkit 0.0.1

package/dist/actions/prompt.js

@@ -0,0 +1,99 @@
+import { createInterface } from "node:readline/promises";
+import { action } from "../core/action.js";
+/** Normalize choices to `{ label, value }`. */
+const asChoices = (choices) => choices.map((c) => (typeof c === "string" ? { label: c, value: c } : c));
+/**
+ * Asks the terminal a question — free-text **input** or a **choice** from a list —
+ * and resolves with the answer, which it also publishes as the action's handle
+ * (so `prompt(...).ref` feeds straight into another action). Everything is
+ * defaulted: a bare `prompt()` is a free-text input with no default and a 30s
+ * timeout.
+ *
+ * A configurable timeout (default 30s; non-finite/≤0 waits forever) falls back to
+ * the default value, so an unattended run never blocks. The run's abort signal
+ * also unblocks a pending prompt on teardown. Emits `prompt` when shown and
+ * `answer` when settled (carrying whether it came from input, the default, or a
+ * timeout).
+ */
+export const prompt = action("Prompt")
+    .emits()
+    .ref()
+    .run(async ({ logs, signal, emit, attach }, opts = {}) => {
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    const finite = Number.isFinite(timeoutMs) && timeoutMs > 0;
+    // Build the question, the fallback value, and a resolver from raw input.
+    let message;
+    let query;
+    let defaultValue;
+    let resolveRaw;
+    if (opts.kind === "choice") {
+        const choices = asChoices(opts.choices);
+        const { default: def } = opts;
+        const picked = typeof def === "number"
+            ? choices[def - 1]
+            : def !== undefined
+                ? choices.find((c) => c.value === def)
+                : undefined;
+        defaultValue = (picked ?? choices[0])?.value ?? "";
+        message = opts.message ?? "Choose:";
+        const list = choices
+            .map((c, i) => `  ${i + 1}) ${c.label}${c.value === defaultValue ? " (default)" : ""}`)
+            .join("\n");
+        query = `${message}\n${list}\n> `;
+        // Accept a 1-based index, an exact value, or an exact label.
+        resolveRaw = (raw) => {
+            const n = Number(raw);
+            if (Number.isInteger(n) && n >= 1 && n <= choices.length)
+                return choices[n - 1].value;
+            return choices.find((c) => c.value === raw || c.label === raw)?.value;
+        };
+    }
+    else {
+        defaultValue = opts.default ?? "";
+        message = opts.message ?? "Input:";
+        query = defaultValue ? `${message} (${defaultValue}) ` : `${message} `;
+        resolveRaw = (raw) => raw; // any non-empty input is the value
+    }
+    emit("prompt", message);
+    // A dedicated controller for the timeout, so it's distinguishable from a
+    // teardown abort; either one cancels the pending question.
+    const onTimeout = new AbortController();
+    const timer = finite ? setTimeout(() => onTimeout.abort(), timeoutMs) : undefined;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let value = defaultValue;
+    let via = "default";
+    try {
+        const raw = (await rl.question(query, { signal: AbortSignal.any([signal, onTimeout.signal]) })).trim();
+        if (raw === "") {
+            via = "default";
+        }
+        else {
+            const resolved = resolveRaw(raw);
+            if (resolved !== undefined) {
+                value = resolved;
+                via = "input";
+            }
+            else {
+                logs.append({ source: "Prompt", level: "info", message: `invalid answer "${raw}", using default` });
+                via = "default";
+            }
+        }
+    }
+    catch {
+        // Aborted before an answer: the timeout (use default + note it) or teardown.
+        via = onTimeout.signal.aborted ? "timeout" : "default";
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        rl.close();
+    }
+    logs.append({
+        source: "Prompt",
+        level: "info",
+        message: via === "timeout" ? `timed out → ${value}` : `${value} (${via})`,
+    });
+    attach(value); // resolves instance.ref → the answer
+    emit("answer", { value, via });
+    return value;
+});

package/dist/actions/tail-log.d.ts

@@ -0,0 +1,30 @@
+export interface TailLogOptions {
+    /** Label the lines are logged under. Default: the file's basename. */
+    source?: string;
+    /** Level for appended lines. Default "info". */
+    level?: string;
+    /**
+     * Replay the file's existing content first. Default false — start at the
+     * current end and only stream what's appended from now on (like `tail -f`).
+     */
+    fromStart?: boolean;
+    /** Text encoding of the file. Default "utf8". */
+    encoding?: BufferEncoding;
+    /** Coalesce rapid writes within this window. Default 50ms. */
+    debounceMs?: number;
+}
+/**
+ * Tails a (possibly not-yet-existing) text/log file and streams each appended
+ * line into the run's combined log — the way `proc` streams a child's stdout, but
+ * for a file some *other* process writes. Useful for folding an external tool's
+ * own log file into the one timeline.
+ *
+ * It tracks a byte offset and reads only the delta on each change, buffering a
+ * partial trailing line until its newline arrives (so a line split across two
+ * writes is logged once, whole). A shrink in size is treated as truncation or
+ * rotation — the offset resets to 0 and reading resumes from the top. Since
+ * `fs.watch` can't watch a missing path, it watches the parent directory and
+ * filters by name, like {@link import("./watch.ts").watch}. Runs until the run's
+ * signal aborts, then closes the watcher (flushing any trailing partial line).
+ */
+export declare const tailLog: import("../core/action.ts").Action<[target: string, opts?: TailLogOptions | undefined], void, import("../core/action.ts").NoEvents, void>;

package/dist/actions/tail-log.js

@@ -0,0 +1,124 @@
+import { watch as fsWatch } from "node:fs";
+import { open, stat } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { action } from "../core/action.js";
+/**
+ * Tails a (possibly not-yet-existing) text/log file and streams each appended
+ * line into the run's combined log — the way `proc` streams a child's stdout, but
+ * for a file some *other* process writes. Useful for folding an external tool's
+ * own log file into the one timeline.
+ *
+ * It tracks a byte offset and reads only the delta on each change, buffering a
+ * partial trailing line until its newline arrives (so a line split across two
+ * writes is logged once, whole). A shrink in size is treated as truncation or
+ * rotation — the offset resets to 0 and reading resumes from the top. Since
+ * `fs.watch` can't watch a missing path, it watches the parent directory and
+ * filters by name, like {@link import("./watch.ts").watch}. Runs until the run's
+ * signal aborts, then closes the watcher (flushing any trailing partial line).
+ */
+export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, opts = {}) => {
+    const file = resolve(target);
+    const dir = dirname(file);
+    const name = basename(file);
+    const { source = name, level = "info", fromStart = false, encoding = "utf8", debounceMs = 50 } = opts;
+    let pos = 0; // bytes consumed so far
+    let pending = ""; // partial trailing line, buffered until its newline
+    // Append every complete line in `text`, keeping any remainder for next time.
+    const feed = (text) => {
+        pending += text;
+        let newline;
+        while ((newline = pending.indexOf("\n")) !== -1) {
+            const line = pending.slice(0, newline).replace(/\r$/, "");
+            pending = pending.slice(newline + 1);
+            if (line)
+                logs.append({ source, level, message: line });
+        }
+    };
+    // Read [pos, size) and feed it. Catches the file being absent (rotated away)
+    // and resets on a shrink (truncation/rotation), so reading self-heals.
+    const readDelta = async () => {
+        let size;
+        try {
+            size = (await stat(file)).size;
+        }
+        catch {
+            return; // missing/unreadable — wait for the next event
+        }
+        if (size < pos) {
+            pos = 0;
+            pending = "";
+        }
+        if (size <= pos)
+            return;
+        const handle = await open(file, "r");
+        try {
+            const length = size - pos;
+            const buffer = Buffer.alloc(length);
+            await handle.read(buffer, 0, length, pos);
+            pos = size;
+            feed(buffer.toString(encoding));
+        }
+        finally {
+            await handle.close();
+        }
+    };
+    // Serialize reads so a burst of events can't overlap; coalesce extra triggers
+    // into a single follow-up pass.
+    let reading = false;
+    let again = false;
+    const pump = () => {
+        if (reading) {
+            again = true;
+            return;
+        }
+        reading = true;
+        void (async () => {
+            try {
+                do {
+                    again = false;
+                    await readDelta();
+                } while (again);
+            }
+            finally {
+                reading = false;
+            }
+        })();
+    };
+    let timer;
+    const schedule = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(pump, debounceMs);
+    };
+    // Seed the offset: from the top when replaying, otherwise from the current end
+    // so existing content is skipped. A missing file starts at 0 — its content
+    // counts as "appended" once it appears.
+    try {
+        pos = fromStart ? 0 : (await stat(file)).size;
+    }
+    catch {
+        pos = 0;
+    }
+    if (fromStart)
+        pump();
+    const watcher = fsWatch(dir, (_event, filename) => {
+        if (filename === null || filename === name)
+            schedule();
+    });
+    // Daemon: stay alive until torn down, then stop and flush any partial line.
+    return new Promise((resolveRun) => {
+        const stop = () => {
+            if (timer)
+                clearTimeout(timer);
+            watcher.close();
+            const tail = pending.replace(/\r$/, "");
+            if (tail)
+                logs.append({ source, level, message: tail });
+            resolveRun();
+        };
+        if (signal.aborted)
+            stop();
+        else
+            signal.addEventListener("abort", stop, { once: true });
+    });
+});

package/dist/actions/until-log.d.ts

@@ -0,0 +1,24 @@
+import type { LogEntry } from "../core/log-collector/LogsCollector.ts";
+/** Predicate over a log entry — return `true` for the entry to wait for. */
+export type LogMatcher = (entry: LogEntry) => boolean;
+export interface UntilLogOptions {
+    /**
+     * Reject if no entry matches within this many milliseconds. Omit to wait
+     * indefinitely (the caller is then responsible for guaranteeing a match).
+     */
+    timeoutMs?: number;
+    /** Replay the buffered history before live entries (catch already-logged matches). */
+    replay?: boolean;
+}
+/** Events emitted by {@link untilLog}. */
+export interface UntilLogEvents {
+    /** Fired with the matching entry the moment it's found, just before resolving. */
+    match: LogEntry;
+}
+/**
+ * Gate: resolves with the first log entry the `matcher` accepts (and emits
+ * `match`). Subscribes to the injected collector and races each read against the
+ * run's abort signal (and an optional timeout), so teardown unblocks a pending
+ * wait instead of hanging.
+ */
+export declare const untilLog: import("../core/action.ts").Action<[matcher: LogMatcher, (UntilLogOptions | undefined)?], LogEntry, UntilLogEvents, void>;

package/dist/actions/until-log.js

@@ -0,0 +1,49 @@
+import { action } from "../core/action.js";
+/**
+ * Gate: resolves with the first log entry the `matcher` accepts (and emits
+ * `match`). Subscribes to the injected collector and races each read against the
+ * run's abort signal (and an optional timeout), so teardown unblocks a pending
+ * wait instead of hanging.
+ */
+export const untilLog = action("Until Log")
+    .emits()
+    .run(({ logs, signal, emit }, matcher, { timeoutMs, replay = false } = {}) => {
+    const iterator = logs.subscribe({ replay })[Symbol.asyncIterator]();
+    let timer;
+    const deadline = timeoutMs === undefined
+        ? undefined
+        : new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`untilLog: no match within ${timeoutMs}ms`)), timeoutMs);
+        });
+    let onAbort;
+    const aborted = new Promise((_, reject) => {
+        if (signal.aborted)
+            return reject(new Error("untilLog: aborted"));
+        onAbort = () => reject(new Error("untilLog: aborted"));
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    const scan = async () => {
+        try {
+            for (;;) {
+                const racers = [iterator.next(), aborted];
+                if (deadline)
+                    racers.push(deadline);
+                const result = await Promise.race(racers);
+                if (result.done)
+                    throw new Error("untilLog: stream ended before a match");
+                if (matcher(result.value)) {
+                    emit("match", result.value);
+                    return result.value;
+                }
+            }
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            if (onAbort)
+                signal.removeEventListener("abort", onAbort);
+            await iterator.return?.();
+        }
+    };
+    return scan();
+});

package/dist/actions/watch-dir.d.ts

@@ -0,0 +1,35 @@
+export interface WatchDirOptions {
+    /** Coalesce rapid events within this window. Default 50ms. */
+    debounceMs?: number;
+}
+/**
+ * Events emitted by {@link watchDir}. Each payload is the absolute path of the
+ * entry — a file for create/update/delete, the folder itself for ready/removed.
+ */
+export interface WatchDirEvents {
+    /** A file appeared during the run. */
+    create: string;
+    /** A file's contents changed (its mtime moved). */
+    update: string;
+    /** A file was removed. */
+    delete: string;
+    /** The folder appeared (or existed at startup); fires again on recreation. */
+    ready: string;
+    /** The folder was removed (paired with `ready` when it's replaced). */
+    removed: string;
+}
+/**
+ * Watches a directory and emits per-file events on changes, surviving the folder
+ * being deleted and recreated (e.g. a build that `rm -rf`s it first).
+ *
+ * It watches the existing ancestor chain (target recursively, ancestors
+ * non-recursively) so a stable ancestor keeps firing when the target reappears.
+ * Per-file changes are derived by re-`stat`ing and diffing mtimes.
+ *
+ * The folder's own removal/recreation can't be seen by stat: a wipe+recreate is
+ * atomic (never observed absent), and on NTFS the recreated dir even keeps the
+ * old `ino`/`birthtime` (tunneling). So that's detected from the raw `rename`
+ * event the *parent* fires for the target's name — when it does and the target
+ * still exists, it was replaced (`removed` + `ready`).
+ */
+export declare const watchDir: import("../core/action.ts").Action<[target: string, opts?: WatchDirOptions | undefined], void, WatchDirEvents, void>;

package/dist/actions/watch-dir.js

@@ -0,0 +1,159 @@
+import { existsSync, watch as fsWatch } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { action } from "../core/action.js";
+/**
+ * Watches a directory and emits per-file events on changes, surviving the folder
+ * being deleted and recreated (e.g. a build that `rm -rf`s it first).
+ *
+ * It watches the existing ancestor chain (target recursively, ancestors
+ * non-recursively) so a stable ancestor keeps firing when the target reappears.
+ * Per-file changes are derived by re-`stat`ing and diffing mtimes.
+ *
+ * The folder's own removal/recreation can't be seen by stat: a wipe+recreate is
+ * atomic (never observed absent), and on NTFS the recreated dir even keeps the
+ * old `ino`/`birthtime` (tunneling). So that's detected from the raw `rename`
+ * event the *parent* fires for the target's name — when it does and the target
+ * still exists, it was replaced (`removed` + `ready`).
+ */
+export const watchDir = action("Watch Dir")
+    .emits()
+    .run(({ signal, emit }, target, opts = {}) => {
+    const { debounceMs = 50 } = opts;
+    const root = resolve(target);
+    const targetName = basename(root);
+    const targetParent = dirname(root);
+    let seen = new Map(); // abs path -> mtimeMs
+    let rootPresent = false; // believed existence of the folder itself
+    let churned = false; // the parent reported a rename for the target since last tick
+    const scan = async () => {
+        const next = new Map();
+        let entries;
+        try {
+            entries = await readdir(root, { recursive: true });
+        }
+        catch {
+            return next; // target missing/unreadable -> empty snapshot
+        }
+        for (const rel of entries) {
+            const abs = join(root, rel);
+            try {
+                const stats = await stat(abs);
+                if (stats.isFile())
+                    next.set(abs, stats.mtimeMs);
+            }
+            catch {
+                // entry vanished between readdir and stat — skip
+            }
+        }
+        return next;
+    };
+    const recheck = async (isInitial) => {
+        const next = await scan();
+        // Startup seeds the snapshot silently — so onCreate means "created during
+        // this run", not "already there when we started" (last run's leftovers).
+        if (!isInitial) {
+            for (const [path, mtime] of next) {
+                const prev = seen.get(path);
+                if (prev === undefined)
+                    emit("create", path);
+                else if (prev !== mtime)
+                    emit("update", path);
+            }
+            for (const path of seen.keys()) {
+                if (!next.has(path))
+                    emit("delete", path);
+            }
+        }
+        seen = next;
+    };
+    // Derive the folder's own create/remove/recreate from existence + the churn
+    // signal (a parent `rename` for the target's name).
+    const detectDir = (isInitial, didChurn) => {
+        const present = existsSync(root);
+        if (isInitial) {
+            rootPresent = present;
+            if (present)
+                emit("ready", root);
+            return;
+        }
+        if (didChurn) {
+            if (rootPresent)
+                emit("removed", root); // replaced or removed
+            if (present)
+                emit("ready", root); // created or recreated
+        }
+        else if (present !== rootPresent) {
+            emit(present ? "ready" : "removed", root);
+        }
+        rootPresent = present;
+    };
+    const existingChain = () => {
+        const chain = [];
+        for (let dir = root;; dir = dirname(dir)) {
+            if (existsSync(dir))
+                chain.push(dir);
+            if (dirname(dir) === dir)
+                break;
+        }
+        return chain;
+    };
+    const watchers = [];
+    let armed = [];
+    const onEvent = (dir) => (eventType, filename) => {
+        // A rename of the target's own name, seen from its parent = the folder
+        // was created / removed / replaced.
+        if (dir === targetParent && filename === targetName && eventType === "rename") {
+            churned = true;
+        }
+        schedule();
+    };
+    const arm = (force) => {
+        const chain = existingChain();
+        const same = chain.length === armed.length && chain.every((d, i) => d === armed[i]);
+        if (same && !force)
+            return; // re-arm only when structure changed (or forced after a churn)
+        for (const w of watchers)
+            w.close();
+        watchers.length = 0;
+        for (const dir of chain) {
+            try {
+                watchers.push(fsWatch(dir, { recursive: dir === root }, onEvent(dir)));
+            }
+            catch {
+                // some ancestors may be unwatchable — ignore
+            }
+        }
+        armed = chain;
+    };
+    let timer;
+    const schedule = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => void tick(false), debounceMs);
+    };
+    const tick = async (isInitial) => {
+        const didChurn = churned;
+        churned = false;
+        arm(didChurn); // re-arm (force after a churn — the old target handle is dead)
+        detectDir(isInitial, didChurn);
+        await recheck(isInitial);
+    };
+    void tick(true); // initial state + arm the chain
+    // Daemon: stay alive until torn down, then flush once more and close.
+    return new Promise((resolveRun) => {
+        const stop = async () => {
+            if (timer)
+                clearTimeout(timer);
+            await tick(false); // final flush — capture changes right before teardown
+            for (const w of watchers)
+                w.close();
+            watchers.length = 0;
+            resolveRun();
+        };
+        if (signal.aborted)
+            void stop();
+        else
+            signal.addEventListener("abort", () => void stop(), { once: true });
+    });
+});

package/dist/actions/watch.d.ts

@@ -0,0 +1,33 @@
+import { type Stats } from "node:fs";
+export interface FileEvent {
+    /** Absolute path of the watched file. */
+    path: string;
+    /** True for the state reported at startup; false for a live transition. */
+    isInitial: boolean;
+    /** Stats when the file exists (create/update); absent for delete/missing. */
+    stats?: Stats;
+}
+export type FileListener = (event: FileEvent) => void;
+export interface WatchOptions {
+    /** The file is absent when watching starts. */
+    onMissing?: FileListener;
+    /** The file appeared (or already existed at startup — `isInitial`). */
+    onCreate?: FileListener;
+    /** The file's contents changed (its mtime moved). */
+    onUpdate?: FileListener;
+    /** The file was removed. */
+    onDelete?: FileListener;
+    /** Coalesce rapid events (e.g. an editor's atomic save) within this window. Default 50ms. */
+    debounceMs?: number;
+}
+/**
+ * Watches a single file that may not exist yet, firing callbacks on its
+ * transitions. Since `fs.watch` can't watch a missing path, it watches the
+ * parent directory and filters by name; on each event it re-`stat`s and diffs
+ * against the last known state rather than trusting the raw event type. Runs
+ * until the run's signal aborts, then closes the watcher.
+ *
+ * Assumes the parent directory exists; watching when an ancestor is missing is
+ * a later case.
+ */
+export declare const watch: import("../core/action.ts").Action<[target: string, opts?: WatchOptions | undefined], void, import("../core/action.ts").NoEvents, void>;

package/dist/actions/watch.js

@@ -0,0 +1,80 @@
+import { watch as fsWatch } from "node:fs";
+import { stat } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { action } from "../core/action.js";
+/**
+ * Watches a single file that may not exist yet, firing callbacks on its
+ * transitions. Since `fs.watch` can't watch a missing path, it watches the
+ * parent directory and filters by name; on each event it re-`stat`s and diffs
+ * against the last known state rather than trusting the raw event type. Runs
+ * until the run's signal aborts, then closes the watcher.
+ *
+ * Assumes the parent directory exists; watching when an ancestor is missing is
+ * a later case.
+ */
+export const watch = action("Watch").run(({ logs, signal }, target, opts = {}) => {
+    const { onMissing, onCreate, onUpdate, onDelete, debounceMs = 50 } = opts;
+    const file = resolve(target);
+    const dir = dirname(file);
+    const name = basename(file);
+    let present = false;
+    let mtimeMs = 0;
+    const recheck = async (isInitial) => {
+        let stats;
+        try {
+            stats = await stat(file);
+        }
+        catch {
+            stats = undefined; // ENOENT (or unreadable) → treat as absent
+        }
+        if (stats?.isFile()) {
+            if (!present) {
+                present = true;
+                mtimeMs = stats.mtimeMs;
+                logs.append({ source: name, level: "info", message: `created ${file}` });
+                onCreate?.({ path: file, isInitial, stats });
+            }
+            else if (stats.mtimeMs !== mtimeMs) {
+                mtimeMs = stats.mtimeMs;
+                logs.append({ source: name, level: "info", message: `updated ${file}` });
+                onUpdate?.({ path: file, isInitial, stats });
+            }
+        }
+        else if (present) {
+            present = false;
+            mtimeMs = 0;
+            logs.append({ source: name, level: "info", message: `deleted ${file}` });
+            onDelete?.({ path: file, isInitial });
+        }
+        else if (isInitial) {
+            logs.append({ source: name, level: "info", message: `missing ${file}` });
+            onMissing?.({ path: file, isInitial });
+        }
+    };
+    let timer;
+    const schedule = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => void recheck(false), debounceMs);
+    };
+    // Watch the parent dir (the file may not exist yet) and filter by name.
+    // Some platforms pass a null filename — recheck anyway, it's a cheap stat.
+    const watcher = fsWatch(dir, (_event, filename) => {
+        if (filename === null || filename === name)
+            schedule();
+    });
+    void recheck(true); // report the initial state
+    // Daemon: stay alive until torn down, then close the watcher.
+    return new Promise((resolveRun) => {
+        const stop = () => {
+            if (timer)
+                clearTimeout(timer);
+            watcher.close();
+            resolveRun();
+        };
+        if (signal.aborted)
+            stop();
+        else
+            signal.addEventListener("abort", stop, { once: true });
+    });
+});