omkit 0.0.2 → 0.0.5

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 {
     /**
@@ -7,20 +8,43 @@ export interface CommandOptions {
     cwd?: string;
     /** Label the child's output is logged under. Defaults to the action's name. */
     label?: string;
+    /**
+     * Environment for the child. Pass the full set you want (e.g.
+     * `{ ...process.env, NODE_ENV: "development" }`) — it's handed to the child
+     * as-is, not merged. Omit to inherit the parent's `process.env`.
+     */
+    env?: NodeJS.ProcessEnv;
 }
 /**
- * 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).
+ *
+ * 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 })
  *
- *   run(
- *     command("TSKB:dev", "npm run dev:explorer", { cwd: pkg }),
- *     command("TSKB:test", "npm test", { cwd: repo }),
- *   );
+ *   `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,74 @@ 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, ...(options.env ? { env: options.env } : {}) })(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.
+    // env omitted -> spawn inherits the parent's process.env (Node's default).
+    const child = spawn(file, args, { cwd, windowsHide: true, env: options.env });
+    // 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/tail-log.js

@@ -25,7 +25,13 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
     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;
+        // Strip NUL bytes first. Log rotators (log4js/streamroller) can pre-allocate
+        // or leave a rotated file padded with \0, and a NUL run contains no newline —
+        // so without this the whole padded region buffers and flushes as one huge
+        // bogus line (the tell-tale "line of blanks/spaces"). NUL is never valid in
+        // a text log, so dropping it is safe; a NUL-only stretch collapses to "" and
+        // is skipped by the empty-line guard below.
+        pending += text.replace(/\0/g, "");
         let newline;
         while ((newline = pending.indexOf("\n")) !== -1) {
             const line = pending.slice(0, newline).replace(/\r$/, "");

package/dist/core/action.d.ts

@@ -63,18 +63,22 @@ export interface ActionInstance<Result = unknown, Events extends object = NoEven
      */
     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.
+     * Gate this action on its **inputs** — the files/folders it *reads* (its
+     * sources), **not** what it produces. `paths` (each a file or a folder) are
+     * fingerprinted by mtime+size; the returned instance skips running when those
+     * inputs are unchanged since the last successful run, and otherwise runs this
+     * action and records the fingerprint. Pass inputs, not build outputs: caching
+     * on an output would skip the very run that produces it.
+     *
      * 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` *before* handing the instance in — passing the source dir:
+     * `nod(command("build", "npm run build").withCache(srcAbs))`.
      */
-    withCache(...folders: string[]): AnyActionInstance;
+    withCache(...paths: string[]): AnyActionInstance;
 }
 /**
  * Any constructed instance, whatever its result, events, or handle. The launch

package/dist/core/action.js

@@ -1,6 +1,6 @@
 import { events } from "./events.js";
 import { createProc } from "./process.js";
-import { fingerprint, read, write, resolveFolders } from "./folder-cache.js";
+import { fingerprint, read, write, resolvePaths } from "./folder-cache.js";
 /** A promise paired with its settlers, for the set-once handle. */
 const deferred = () => {
     let resolve;
@@ -105,23 +105,23 @@ const build = (name, exec) => {
                 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
+            // emitter/ref/on/once) that fingerprints `paths` 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) {
+            withCache(...paths) {
                 // 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);
+                const targets = resolvePaths(paths);
                 return action(name).run(async (ctx) => {
-                    const fp = await fingerprint(dirs);
-                    if ((await read(dirs)) === fp) {
+                    const fp = await fingerprint(targets);
+                    if ((await read(targets)) === 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
+                    await write(targets, fp); // only on success — a throw above skips this
                     return result;
                 })();
             },

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

@@ -1,36 +1,39 @@
 /**
- * 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.
+ * An input-fingerprint cache: hash the mtime+size of one or more **input**
+ * targets (the files/folders an action reads — *not* what it produces), so an
+ * expensive action can be skipped when its inputs are unchanged 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.
+ * one JSON file per set of inputs, 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.
+ * Require every path to be **absolute** (a relative path is a developer error —
+ * throws, naming it) and return them canonicalized with `resolve`, so different
+ * spellings of the same target (`.`/`..`/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. Each target may be a file or a
+ * folder (see {@link fingerprint}).
  */
-export declare const resolveFolders: (folders: string[]) => string[];
+export declare const resolvePaths: (paths: 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.
+ * Fingerprints one or more **input** targets by mtime+size. Each target may be
+ * a **file** (fingerprinted directly) or a **folder** (walked recursively, its
+ * files fingerprinted). Every path must be absolute (throws otherwise). A
+ * missing target contributes nothing — so an input that doesn't exist 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>;
+export declare const fingerprint: (paths: string[]) => Promise<string>;
 /**
- * Reads the fingerprint stored for these folders, or `undefined` when there's
+ * Reads the fingerprint stored for these targets, 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>;
+export declare const read: (paths: string[]) => Promise<string | undefined>;
 /**
- * Records the fingerprint for these folders after a successful run. Writes
+ * Records the fingerprint for these targets 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>;
+export declare const write: (paths: string[], fp: string) => Promise<void>;

package/dist/core/folder-cache.js

@@ -2,52 +2,71 @@ 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.
+ * An input-fingerprint cache: hash the mtime+size of one or more **input**
+ * targets (the files/folders an action reads — *not* what it produces), so an
+ * expensive action can be skipped when its inputs are unchanged 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.
+ * one JSON file per set of inputs, 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.
+ * Require every path to be **absolute** (a relative path is a developer error —
+ * throws, naming it) and return them canonicalized with `resolve`, so different
+ * spellings of the same target (`.`/`..`/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. Each target may be a file or a
+ * folder (see {@link fingerprint}).
  */
-export const resolveFolders = (folders) => folders.map((folder) => {
-    if (!isAbsolute(folder)) {
-        throw new Error(`withCache: folder path must be absolute, got "${folder}"`);
+export const resolvePaths = (paths) => paths.map((p) => {
+    if (!isAbsolute(p)) {
+        throw new Error(`withCache: path must be absolute, got "${p}"`);
     }
-    return resolve(folder);
+    return resolve(p);
 });
 /**
- * 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.
+ * Fingerprints one or more **input** targets by mtime+size. Each target may be
+ * a **file** (fingerprinted directly) or a **folder** (walked recursively, its
+ * files fingerprinted). Every path must be absolute (throws otherwise). A
+ * missing target contributes nothing — so an input that doesn't exist 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);
+export const fingerprint = async (paths) => {
+    const targets = resolvePaths(paths);
     const entries = [];
-    for (const folder of dirs) {
+    const record = (target, rel, mtimeMs, size) => {
+        entries.push(`${target}\0${rel}\0${mtimeMs}\0${size}`);
+    };
+    for (const target of targets) {
+        let root;
+        try {
+            root = await stat(target);
+        }
+        catch {
+            continue; // missing/unreadable — contributes no entries
+        }
+        // A file target fingerprints itself (empty rel — there's no walk).
+        if (root.isFile()) {
+            record(target, "", root.mtimeMs, root.size);
+            continue;
+        }
+        // A folder target: walk it and fingerprint every file inside.
         let rels;
         try {
-            rels = await readdir(folder, { recursive: true });
+            rels = await readdir(target, { recursive: true });
         }
         catch {
-            continue; // folder missing/unreadable — contributes no entries
+            continue;
         }
         for (const rel of rels) {
-            const abs = join(folder, rel);
+            const abs = join(target, rel);
             try {
                 const stats = await stat(abs);
                 if (stats.isFile())
-                    entries.push(`${folder}\0${rel}\0${stats.mtimeMs}\0${stats.size}`);
+                    record(target, rel, stats.mtimeMs, stats.size);
             }
             catch {
                 // entry vanished between readdir and stat — skip
@@ -57,18 +76,18 @@ export const fingerprint = async (folders) => {
     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");
+/** The on-disk filename for a set of targets — a hash of their absolute paths. */
+const entryPath = (paths) => {
+    const key = createHash("sha1").update(resolvePaths(paths).sort().join("\0")).digest("hex");
     return join(cacheDir, `${key}.json`);
 };
 /**
- * Reads the fingerprint stored for these folders, or `undefined` when there's
+ * Reads the fingerprint stored for these targets, or `undefined` when there's
  * no cache (absent, unreadable, or malformed — all treated as a miss).
  */
-export const read = async (folders) => {
+export const read = async (paths) => {
     try {
-        const raw = await readFile(entryPath(folders), "utf8");
+        const raw = await readFile(entryPath(paths), "utf8");
         const entry = JSON.parse(raw);
         return typeof entry.fingerprint === "string" ? entry.fingerprint : undefined;
     }
@@ -77,13 +96,13 @@ export const read = async (folders) => {
     }
 };
 /**
- * Records the fingerprint for these folders after a successful run. Writes
+ * Records the fingerprint for these targets after a successful run. Writes
  * atomically (temp file + rename) so a concurrent read never sees a half-file.
  */
-export const write = async (folders, fp) => {
+export const write = async (paths, fp) => {
     await mkdir(cacheDir, { recursive: true });
-    const target = entryPath(folders);
-    const entry = { folders, fingerprint: fp, ts: Date.now() };
+    const target = entryPath(paths);
+    const entry = { folders: paths, 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.js

@@ -24,6 +24,7 @@ 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.
+// Backs the `.withCache(...inputs)` method on instances (fingerprints an
+// action's input files/folders, not its outputs); 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.2",
+  "version": "0.0.5",
   "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",