omkit 0.0.2 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.0.2",
+  "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",