omkit 0.0.1 → 0.0.3

package/dist/actions/command.d.ts

@@ -1,3 +1,4 @@
+import { type AnyActionInstance } from "../core/action.ts";
 /** Tunes an action built with {@link command}. */
 export interface CommandOptions {
     /**
@@ -9,18 +10,35 @@ export interface CommandOptions {
     label?: string;
 }
 /**
- * Runs a fixed shell command via `proc` as an action **instance** — built in a
- * single call, the same shape as every other bundled action (`healthcheck`,
- * `prompt`, …), rather than a factory you instantiate separately. `name`
- * identifies it across the run (the `launch <name>` line and the proc's log
- * source); `cmd` runs verbatim in the resolved `cwd`.
+ * Runs a fixed command as an action **instance** — built in a single call, the
+ * same shape as every other bundled action (`healthcheck`, `prompt`, …), rather
+ * than a factory you instantiate separately. `name` identifies it across the run
+ * (the `launch <name>` line and the child's log source).
  *
- *   run(
- *     command("TSKB:dev", "npm run dev:explorer", { cwd: pkg }),
- *     command("TSKB:test", "npm test", { cwd: repo }),
- *   );
+ * Two forms:
+ *
+ * - **Shell form** — `command(name, cmd, opts)`. The string runs verbatim
+ *   through a shell (PowerShell on Windows), so pipes, globs, and `&&` work:
+ *
+ *     command("TSKB:dev", "npm run dev:explorer", { cwd: pkg })
+ *
+ *   The direct child is the *shell*, and the real program is a grandchild. On
+ *   Windows teardown reaps the tree only while that shell is alive — so a GUI
+ *   app that ignores console Ctrl-C (Electron) can be **orphaned and survive**.
+ *
+ * - **Direct form** — `command(name, file, args, opts)`. Spawns `file` with
+ *   `args` **without a shell**, so the action's direct child *is* the program.
+ *   On teardown it's force-reaped by its own PID (`taskkill /F /T`), so it dies
+ *   even when a shell would have orphaned it. Use this for long-lived apps you
+ *   launch and must be able to kill on Ctrl-C:
+ *
+ *     command("platform", electronExe, [".", "--inspect"], { cwd: app })
+ *
+ *   `file` must be a real executable (an actual `electron.exe`), not a `.cmd`
+ *   shim — shims need a shell to run.
  *
  * For anything beyond a static command — interpolated args, emitted events, a
  * daemon loop — drop down to `action(...).run(...)` directly.
  */
-export declare const command: (name: string, cmd: string, options?: CommandOptions) => import("../core/action.ts").ActionInstance<import("zx").ProcessOutput, import("../core/action.ts").NoEvents, void>;
+export declare function command(name: string, cmd: string, options?: CommandOptions): AnyActionInstance;
+export declare function command(name: string, file: string, args: string[], options?: CommandOptions): AnyActionInstance;

package/dist/actions/command.js

@@ -1,5 +1,8 @@
+import { spawn } from "node:child_process";
 import path from "node:path";
 import { action } from "../core/action.js";
+import { killTree } from "../core/process.js";
+import { captureSnapshot } from "../core/output.js";
 /**
  * Build the literal part of a zx tagged template from a command string, so it
  * runs verbatim. zx only quotes interpolated args, not the template's `pieces` —
@@ -8,25 +11,73 @@ import { action } from "../core/action.js";
  * verbatim is exactly what we want.
  */
 const verbatim = (cmd) => Object.assign([cmd], { raw: [cmd] });
+export function command(name, cmdOrFile, argsOrOptions, maybeOptions) {
+    const direct = Array.isArray(argsOrOptions);
+    const options = (direct ? maybeOptions : argsOrOptions) ?? {};
+    if (direct) {
+        return action(name).run((ctx) => spawnDirect(ctx.logs, ctx.signal, name, cmdOrFile, argsOrOptions, options))();
+    }
+    return action(name).run(({ proc }) => {
+        // path.resolve keeps an absolute cwd as-is and resolves a relative one
+        // against process.cwd() — exactly the "absolute from where node runs" rule.
+        const cwd = path.resolve(options.cwd ?? ".");
+        // proc sources the LogsCollector from async context and streams output into it.
+        return proc(options.label ?? name, { cwd })(verbatim(cmdOrFile));
+    })(); // construct the instance here, so callers get one in a single call
+}
 /**
- * Runs a fixed shell command via `proc` as an action **instance** — built in a
- * single call, the same shape as every other bundled action (`healthcheck`,
- * `prompt`, …), rather than a factory you instantiate separately. `name`
- * identifies it across the run (the `launch <name>` line and the proc's log
- * source); `cmd` runs verbatim in the resolved `cwd`.
- *
- *   run(
- *     command("TSKB:dev", "npm run dev:explorer", { cwd: pkg }),
- *     command("TSKB:test", "npm test", { cwd: repo }),
- *   );
- *
- * For anything beyond a static command — interpolated args, emitted events, a
- * daemon loop — drop down to `action(...).run(...)` directly.
+ * The direct (shell-less) launcher behind {@link command}'s four-arg form.
+ * Spawns `file`/`args` with no shell — so the returned child *is* the program,
+ * killable by its own PID on teardown — streams its stdout/stderr into the run's
+ * log, and resolves when it exits (0 = ok; a non-zero exit is a genuine failure,
+ * unless the run is tearing down, where the abort-kill is the reason).
  */
-export const command = (name, cmd, options = {}) => action(name).run(({ proc }) => {
-    // path.resolve keeps an absolute cwd as-is and resolves a relative one
-    // against process.cwd() — exactly the "absolute from where node runs" rule.
+const spawnDirect = (logs, signal, name, file, args, options) => {
     const cwd = path.resolve(options.cwd ?? ".");
-    // proc sources the LogsCollector from async context and streams output into it.
-    return proc(options.label ?? name, { cwd })(verbatim(cmd));
-})(); // construct the instance here, so callers get one in a single call
+    const source = options.label ?? name;
+    // windowsHide keeps a stray console window from flashing for the child.
+    const child = spawn(file, args, { cwd, windowsHide: true });
+    // Mirror proc's launch line: a filterable milestone on the timeline, with the
+    // structured args snapshotted and linked (see process.ts for the rationale).
+    const snap = captureSnapshot(`proc-${name}-start`, { cmd: file, args, cwd });
+    logs.append({
+        source: name,
+        level: "event",
+        message: `${name} · start · ${file} ${args.join(" ")} · in ${cwd} · → ${snap.rel}`,
+    });
+    if (child.stdout)
+        logs.attach(child.stdout, source, "info");
+    if (child.stderr)
+        logs.attach(child.stderr, source, "error");
+    // Force-reap the child's tree on teardown, by its own PID. Guarded so a child
+    // that has already exited isn't re-killed (its PID may have been reused).
+    let finished = false;
+    const onAbort = () => {
+        if (finished || child.pid == null)
+            return;
+        killTree(child.pid);
+    };
+    const done = () => {
+        finished = true;
+        signal.removeEventListener("abort", onAbort);
+    };
+    if (signal.aborted)
+        killTree(child.pid ?? -1);
+    else
+        signal.addEventListener("abort", onAbort, { once: true });
+    return new Promise((resolve, reject) => {
+        child.on("error", (error) => {
+            done();
+            reject(error);
+        });
+        child.on("exit", (code, sig) => {
+            done();
+            // During teardown the abort-kill is why it exited — a clean shutdown, not a
+            // fault; let it settle successfully so it isn't recorded as a failure.
+            if (signal.aborted || code === 0)
+                resolve();
+            else
+                reject(new Error(`${name} exited with ${code ?? sig}`));
+        });
+    });
+};

package/dist/actions/prompt.js

@@ -74,7 +74,11 @@ export const prompt = action("Prompt")
                 via = "input";
             }
             else {
-                logs.append({ source: "Prompt", level: "info", message: `invalid answer "${raw}", using default` });
+                logs.append({
+                    source: "Prompt",
+                    level: "info",
+                    message: `invalid answer "${raw}", using default`,
+                });
                 via = "default";
             }
         }

package/dist/actions/tail-log.js

@@ -20,7 +20,7 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
     const file = resolve(target);
     const dir = dirname(file);
     const name = basename(file);
-    const { source = name, level = "info", fromStart = false, encoding = "utf8", debounceMs = 50 } = opts;
+    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.
@@ -99,6 +99,9 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
     catch {
         pos = 0;
     }
+    // Announce the target up front so the combined log shows which file these
+    // lines come from — the resolved absolute path, plus whether we're replaying.
+    logs.append({ source, level, message: `tailing ${file}${fromStart ? " (from start)" : ""}` });
     if (fromStart)
         pump();
     const watcher = fsWatch(dir, (_event, filename) => {

package/dist/core/action.d.ts

@@ -62,6 +62,19 @@ export interface ActionInstance<Result = unknown, Events extends object = NoEven
      * subscriptions; `once` is the awaitable, one-value form.
      */
     once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K]>;
+    /**
+     * Gate this action on a folder fingerprint: returns a new instance that skips
+     * running when the mtime+size of every file under `folders` matches the last
+     * successful run, and otherwise runs this action and records the fingerprint.
+     * Every path must be **absolute** (throws otherwise). A cache hit resolves
+     * immediately as success (result `undefined`) and logs a `cached, skipping`
+     * line; a failure of the inner action records nothing, so it re-runs next time.
+     *
+     * Because `nod`/`run` launch an instance the moment they receive it, chain
+     * `.withCache` *before* handing the instance in:
+     * `nod(command("build", "…").withCache(distAbs))`.
+     */
+    withCache(...folders: string[]): AnyActionInstance;
 }
 /**
  * Any constructed instance, whatever its result, events, or handle. The launch

package/dist/core/action.js

@@ -1,5 +1,6 @@
 import { events } from "./events.js";
 import { createProc } from "./process.js";
+import { fingerprint, read, write, resolveFolders } from "./folder-cache.js";
 /** A promise paired with its settlers, for the set-once handle. */
 const deferred = () => {
     let resolve;
@@ -103,6 +104,27 @@ const build = (name, exec) => {
             once(key) {
                 return awaitEvent(emitter, name, key);
             },
+            // Wrap this instance in a fresh one (reusing the engine for its own
+            // emitter/ref/on/once) that fingerprints `folders` and either skips or
+            // runs+records. The wrapper keeps this action's `name`, so log lines and
+            // the `launch <name>` line are unchanged. It forwards its injected
+            // logs/signal straight into the inner action's `start`.
+            withCache(...folders) {
+                // Validate + canonicalize eagerly here (at the call site), not lazily
+                // inside the run — a relative path fails fast where it's written, and
+                // the resolved paths give a stable cache key regardless of spelling.
+                const dirs = resolveFolders(folders);
+                return action(name).run(async (ctx) => {
+                    const fp = await fingerprint(dirs);
+                    if ((await read(dirs)) === fp) {
+                        ctx.logs.append({ source: name, level: "info", message: "cached, skipping" });
+                        return undefined;
+                    }
+                    const result = await instance.start({ logs: ctx.logs, signal: ctx.signal });
+                    await write(dirs, fp); // only on success — a throw above skips this
+                    return result;
+                })();
+            },
         };
         return instance;
     };

package/dist/core/folder-cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A folder-fingerprint cache: hash the mtime+size of every file under one or
+ * more folders, so an expensive action can be skipped when nothing it depends
+ * on has changed since its last successful run. Backs the `.withCache(...)`
+ * method on action instances.
+ *
+ * Entries live under `node_modules/.cache/omkit/` (conventional, gitignored) —
+ * one JSON file per set of folders, named by a hash of their absolute paths.
+ */
+/** Where cache entries are written — `node_modules/.cache/omkit/` under the cwd. */
+export declare const cacheDir: string;
+/**
+ * Require every path to be **absolute** (a relative folder is a developer error
+ * — throws, naming it) and return them canonicalized with `resolve`, so
+ * different spellings of the same folder (`.`/`..`/trailing slash) collapse to
+ * one stable fingerprint prefix and cache key. `resolve` on an already-absolute
+ * path only normalizes — it never falls back to the cwd.
+ */
+export declare const resolveFolders: (folders: string[]) => string[];
+/**
+ * Fingerprints one or more folders by their files' mtime+size. Every path must
+ * be absolute (throws otherwise). A missing folder contributes nothing (so an
+ * output folder that hasn't been built yet is naturally a miss, not an error).
+ * The entry list is sorted for determinism before hashing.
+ */
+export declare const fingerprint: (folders: string[]) => Promise<string>;
+/**
+ * Reads the fingerprint stored for these folders, or `undefined` when there's
+ * no cache (absent, unreadable, or malformed — all treated as a miss).
+ */
+export declare const read: (folders: string[]) => Promise<string | undefined>;
+/**
+ * Records the fingerprint for these folders after a successful run. Writes
+ * atomically (temp file + rename) so a concurrent read never sees a half-file.
+ */
+export declare const write: (folders: string[], fp: string) => Promise<void>;

package/dist/core/folder-cache.js

@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+/**
+ * A folder-fingerprint cache: hash the mtime+size of every file under one or
+ * more folders, so an expensive action can be skipped when nothing it depends
+ * on has changed since its last successful run. Backs the `.withCache(...)`
+ * method on action instances.
+ *
+ * Entries live under `node_modules/.cache/omkit/` (conventional, gitignored) —
+ * one JSON file per set of folders, named by a hash of their absolute paths.
+ */
+/** Where cache entries are written — `node_modules/.cache/omkit/` under the cwd. */
+export const cacheDir = join(process.cwd(), "node_modules", ".cache", "omkit");
+/**
+ * Require every path to be **absolute** (a relative folder is a developer error
+ * — throws, naming it) and return them canonicalized with `resolve`, so
+ * different spellings of the same folder (`.`/`..`/trailing slash) collapse to
+ * one stable fingerprint prefix and cache key. `resolve` on an already-absolute
+ * path only normalizes — it never falls back to the cwd.
+ */
+export const resolveFolders = (folders) => folders.map((folder) => {
+    if (!isAbsolute(folder)) {
+        throw new Error(`withCache: folder path must be absolute, got "${folder}"`);
+    }
+    return resolve(folder);
+});
+/**
+ * Fingerprints one or more folders by their files' mtime+size. Every path must
+ * be absolute (throws otherwise). A missing folder contributes nothing (so an
+ * output folder that hasn't been built yet is naturally a miss, not an error).
+ * The entry list is sorted for determinism before hashing.
+ */
+export const fingerprint = async (folders) => {
+    const dirs = resolveFolders(folders);
+    const entries = [];
+    for (const folder of dirs) {
+        let rels;
+        try {
+            rels = await readdir(folder, { recursive: true });
+        }
+        catch {
+            continue; // folder missing/unreadable — contributes no entries
+        }
+        for (const rel of rels) {
+            const abs = join(folder, rel);
+            try {
+                const stats = await stat(abs);
+                if (stats.isFile())
+                    entries.push(`${folder}\0${rel}\0${stats.mtimeMs}\0${stats.size}`);
+            }
+            catch {
+                // entry vanished between readdir and stat — skip
+            }
+        }
+    }
+    entries.sort();
+    return createHash("sha1").update(entries.join("\n")).digest("hex");
+};
+/** The on-disk filename for a set of folders — a hash of their absolute paths. */
+const entryPath = (folders) => {
+    const key = createHash("sha1").update(resolveFolders(folders).sort().join("\0")).digest("hex");
+    return join(cacheDir, `${key}.json`);
+};
+/**
+ * Reads the fingerprint stored for these folders, or `undefined` when there's
+ * no cache (absent, unreadable, or malformed — all treated as a miss).
+ */
+export const read = async (folders) => {
+    try {
+        const raw = await readFile(entryPath(folders), "utf8");
+        const entry = JSON.parse(raw);
+        return typeof entry.fingerprint === "string" ? entry.fingerprint : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Records the fingerprint for these folders after a successful run. Writes
+ * atomically (temp file + rename) so a concurrent read never sees a half-file.
+ */
+export const write = async (folders, fp) => {
+    await mkdir(cacheDir, { recursive: true });
+    const target = entryPath(folders);
+    const entry = { folders, fingerprint: fp, ts: Date.now() };
+    const tmp = `${target}.${process.pid}.tmp`;
+    await writeFile(tmp, JSON.stringify(entry, null, 2));
+    await rename(tmp, target);
+};

package/dist/core/process.d.ts

@@ -1,5 +1,18 @@
 import { type Options, type ProcessPromise } from "zx";
 import type { Logger } from "./log-collector/LogsCollector.ts";
+/**
+ * Force-kill a process **and its whole tree, synchronously**.
+ *
+ * Windows has no process groups: a child outlives its parent, and a Ctrl-C sent
+ * to the console group can make an intermediate shell exit and *orphan* the real
+ * app (e.g. electron.exe), which then survives teardown. So the tree must be
+ * reaped explicitly by PID — `taskkill /F /T` does it, and running it
+ * **synchronously** guarantees it completes before the run's own process exits
+ * (a fire-and-forget kill can lose that race). On POSIX, zx's `kill` already
+ * does a process-group tree kill. Best-effort: an already-dead/missing PID is
+ * ignored.
+ */
+export declare const killTree: (pid: number) => void;
 /**
  * Spawns a command (tagged-template, exactly like zx's `$`) and streams the
  * child's stdout/stderr into a log (stdout as `info`, stderr as `error`) under

package/dist/core/process.js

@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import os from "node:os";
 import { $, kill, usePowerShell } from "zx";
 import { captureSnapshot } from "./output.js";
@@ -5,6 +6,31 @@ import { captureSnapshot } from "./output.js";
 // Use Windows PowerShell there so zx spawns and quotes for the right shell.
 if (os.platform() === "win32")
     usePowerShell();
+/**
+ * Force-kill a process **and its whole tree, synchronously**.
+ *
+ * Windows has no process groups: a child outlives its parent, and a Ctrl-C sent
+ * to the console group can make an intermediate shell exit and *orphan* the real
+ * app (e.g. electron.exe), which then survives teardown. So the tree must be
+ * reaped explicitly by PID — `taskkill /F /T` does it, and running it
+ * **synchronously** guarantees it completes before the run's own process exits
+ * (a fire-and-forget kill can lose that race). On POSIX, zx's `kill` already
+ * does a process-group tree kill. Best-effort: an already-dead/missing PID is
+ * ignored.
+ */
+export const killTree = (pid) => {
+    if (process.platform === "win32") {
+        try {
+            execFileSync("taskkill", ["/F", "/T", "/PID", String(pid)], { stdio: "ignore" });
+        }
+        catch {
+            // already gone, access denied, or taskkill missing — nothing more to do
+        }
+    }
+    else {
+        void kill(pid).catch(() => { });
+    }
+};
 /**
  * Builds a {@link Proc} bound to a specific log sink and abort signal. The action
  * pipeline injects one per action as `ctx.proc`, wired to that action's logger
@@ -46,19 +72,21 @@ export const createProc = (logs, signal) => (name, opts) => {
         });
         logs.attach(child.stdout, name, "info");
         logs.attach(child.stderr, name, "error");
-        // Kill the child's entire process tree on teardown. `child.kill()` (zx's
-        // ProcessPromise method) throws "Too late to kill" when the direct child
-        // has already settled — but grandchildren (vite, tsc, npm scripts) may
-        // still be alive. Using zx's standalone `kill(pid)` bypasses that guard
-        // and does a cross-platform tree kill (taskkill /T /F on Windows,
-        // ps.tree + process-group kill on Unix).
+        // Kill the child's entire process tree on teardown via {@link killTree} —
+        // a synchronous, force tree kill by PID (taskkill /F /T on Windows,
+        // process-group kill on Unix). Synchronous so it finishes before the run's
+        // process exits. NOTE: with zx the direct child is a *shell wrapper*
+        // (PowerShell on Windows), so this only reaps grandchildren while that
+        // wrapper is still alive; a GUI app that must survive its shell being
+        // Ctrl-C'd should be launched shell-less via `command(name, file, args)`,
+        // whose direct child is the app itself.
         let finished = false;
         const onAbort = () => {
             if (finished)
                 return;
             const pid = child.pid;
             if (pid != null)
-                void kill(pid).catch(() => { });
+                killTree(pid);
         };
         const markFinished = () => {
             finished = true;

package/dist/index.d.ts

@@ -23,3 +23,4 @@ export type { Logger, LogEntry, LogInput, SubscribeOptions, } from "./core/log-c
 export { log } from "./core/log-collector/global.ts";
 export { snapshot, captureSnapshot } from "./core/output.ts";
 export type { SnapshotRef } from "./core/output.ts";
+export { fingerprint, cacheDir } from "./core/folder-cache.ts";

package/dist/index.js

@@ -23,3 +23,7 @@ export { LogsCollector } from "./core/log-collector/LogsCollector.js";
 export { log } from "./core/log-collector/global.js";
 // ── Snapshots ──────────────────────────────────────────────────────────────
 export { snapshot, captureSnapshot } from "./core/output.js";
+// ── Folder cache ─────────────────────────────────────────────────────────────
+// Backs the `.withCache(...folders)` method on instances; exported for scripts
+// that want to inspect or manually invalidate the cache.
+export { fingerprint, cacheDir } from "./core/folder-cache.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",