omkit 0.0.15 → 0.1.1

package/README.md

@@ -2,136 +2,147 @@
 
 **The operational-model kit.** _Typed actions. One run. One log._
 
-A runtime for the workflows around your code — build, watch, spawn, probe, drive
-a browser, inspect state, tear it all down together. `omkit` is the running,
-typed model of your system in motion. Where
-[tskb](https://www.npmjs.com/package/tskb) is the _knowledge_ layer, `omkit` is
-the _operational_ one.
+A tiny runtime for the workflows _around_ your code — build, watch, spawn, probe, drive a browser, read state back, and tear it all down together. Where [tskb](https://www.npmjs.com/package/tskb) is the _knowledge_ layer, `omkit` is the _operational_ one: the running, typed model of your system in motion.
 
 ## The problem
 
-Real developer workflows aren't linear. They start processes, wait for health
-checks, connect a browser, read state back, watch files, react to events — and
-shut everything down as one. Most teams glue this together with shell scripts,
-npm scripts, and ad-hoc Node.
+Real developer workflows aren't linear. They start processes, wait for health checks, connect a browser, read state back, watch files, react to events — and shut everything down as one. Most teams glue this together with shell scripts, npm scripts, and ad-hoc Node, and get back a pile of opaque process output.
 
-`omkit` models the workflow instead. Each step is a typed **action** running
-inside one runtime, and actions don't share globals — they hand each other typed
-runtime **capabilities** (a port, a client, a live browser page) and emit typed
-**events**. So a running system exposes structured handoffs and observations
-rather than a pile of opaque process output — which makes the whole thing
-observable, reproducible, and scriptable.
+`omkit` models the workflow instead. Each step is a typed **action** running inside one runtime. Actions don't share globals — they hand each other typed runtime **capabilities** (a port, a client, a live browser page) and emit typed **events**, all onto one log. So a running system exposes structured handoffs and observations, which makes it observable, reproducible, and scriptable.
 
 ```ts
-import { spin } from "omkit";
-import { command, healthcheck, chromedriver, chromePage } from "omkit/actions";
+import { om } from "omkit";
+import { command, healthcheck, chromePage } from "omkit/actions";
 
-spin(async ({ nod }) => {
-  nod(command("api", "npm run dev:api")); // start a daemon…
-  await nod(healthcheck({ port: 3000 })).once("healthy"); // …gate on it…
+om(async () => {
+  command("api", "npm run dev:api").exec().tag("api:daemon"); // start a daemon…
 
-  const chrome = nod(chromedriver({ url: "http://localhost:3000" }));
-  nod(chromePage(chrome.ref)); // …then hand the live page downstream
+  const ready = await healthcheck({ port: 3000 }).exec().result; // …gate on it…
+  if (!ready.ok) return;
+
+  // …then hand the live page downstream — typed, not scraped from a log.
+  const page = chromePage("app", "localhost:9222", { url: "http://localhost:3000" }).exec();
+  await inspect(page.ref); // whatever drives the app receives the live Page
+
+  console.log("up — press Ctrl+C to stop");
 });
 ```
 
-That last line is the point. `chrome.ref` isn't a URL scraped from a log — it's a
-typed capability the next action receives and drives. Few workflow tools pass
-anything but strings between steps.
+`page.ref` isn't a URL scraped from stdout — it's a typed capability the next step receives and drives. Few workflow tools pass anything but strings between steps.
 
 ```
-                    spin()
-                      │
-        ┌─────────────┼─────────────┐
-        ▼             ▼             ▼
-     command      healthcheck   chromedriver
-                                     │ .ref
-                                     ▼
-                                 chromePage
-                                     │ .ref
+                      om()
+                       │
+        ┌──────────────┼──────────────┐
+        ▼              ▼              ▼
+     command       healthcheck    chromePage
+    (daemon)         (gate)          │ .ref
                                      ▼
-                                inspectPage
+                                 your driver
 ```
 
-## Five concepts
-
-- **Action** — a named, typed unit of work; optionally declares events and an
-  imperative handle. Calling it constructs an instance (deferred — the run
-  executes it).
-
-  ```ts
-  const build = action("Build").run(({ proc }) => proc("tsc")`tsc -b`);
-  ```
-
-- **Spin** — hosts an async orchestration _inside_ the runtime. You write normal
-  `await` / `if` / loops / variables, while the actions you launch keep running
-  in parallel. omkit runs your function as one in-flight action and hands it
-  `nod`; because that host stays in-flight while you `await`, the run never idles
-  shut between steps. `nod(instance)` launches an action and returns it, so you
-  can `await` its `.once(...)` or its `.ref`:
-
-  ```ts
-  spin({ failFast: false }, async ({ nod }) => {
-    if ((await nod(prompt({ … })).once("done")) === "yes") await nod(test).once("done");
-    nod(devServer); // daemon: keeps the run alive
-    const chrome = nod(chromedriver({ … }));
-    nod(chromePage(chrome.ref));
-  });
-  ```
+## Core concepts
+
+### Actions & Activities
 
-- **Handle — a typed capability** — an action can `attach` a value (a port, a
-  client, a page) that others `await` via `instance.ref`. Not a file descriptor:
-  a typed runtime handoff, so actions chain without globals or string-scraping:
+An **Action** is an immutable description of work — named, typed, optionally declaring events and an imperative handle. An **Activity** is a live execution of one, created synchronously by `.exec()`. Everything _before_ `exec()` configures the Action; everything _after_ configures or observes the Activity.
+
+```ts
+import { action } from "omkit";
+
+const Build = action("Build").run(({ proc }) => proc("tsc")`tsc -b`);
+
+const activity = Build().exec(); // launch; returns the live Activity
+```
 
-  ```ts
-  const Server = action("Server")
-    .ref<number>()
-    .run(async ({ attach, signal }) => {
-      attach(await listen()); // publish the capability…
-      await until(signal); // …and stay alive
-    });
+`om(async (ctx) => …)` hosts a linear orchestration as the root of a run. You write normal `await` / `if` / loops / variables; the Activities you launch keep running in parallel. Because the body stays in-flight while you `await`, the run never idles shut between steps. For a one-off inline step, `step(name, fn)` runs `fn` as its own node without a reusable definition.
 
-  const Probe = action("Probe").run((_ctx, port: Promise<number>) => drive(port));
+### Typed capabilities
 
-  spin(async ({ nod }) => {
-    const server = nod(Server());
-    nod(Probe(server.ref)); // Probe receives Server's port, typed
+An action can `attach` a value — a port, a client, a page — that downstream actions receive by awaiting `activity.ref`. Not a file descriptor: a typed runtime handoff, so actions chain without globals or string-scraping.
+
+```ts
+const Server = action("Server")
+  .ref<number>()
+  .run(async ({ attach, signal }) => {
+    attach(await listen()); // publish the capability…
+    await until(signal); // …and stay alive until teardown
   });
-  ```
 
-- **Log** — every action's output, events, and lifecycle land on one timeline. It
-  streams live and is written to disk. (A spin auto-drains; pass `drain: false`
-  to start the stream yourself — e.g. after a `prompt` so it doesn't write over
-  the question.)
+const Probe = action("Probe").run((_ctx, port: Promise<number>) => drive(port));
+
+om(async () => {
+  const server = Server().exec();
+  Probe(server.ref).exec(); // Probe receives Server's port, typed
+});
+```
 
-- **Run** — the runtime a spin sits on: actions in parallel under one abort
-  controller and the process-wide log, one run per process. `spin` is the usual
-  entry point; drop to `run(...)` directly when you just want to launch a fixed
-  set and `await r.done`. Ctrl-C, a failure, or natural completion tears it all
-  down.
+### Outcomes — a result that doesn't throw
+
+Every Activity settles to a typed **`Outcome`**, read via `activity.result` — which **never throws**:
+
+```ts
+type Outcome<T> = { ok: true; value: T } | { ok: false; error: unknown };
+
+const r = await runTests().exec().result;
+if (!r.ok) {
+  // an expected, operational failure — inspect it and carry on
+}
+```
+
+Awaiting `.result` also _observes_ the Activity (see teardown, below). A cancelled Activity resolves `{ ok: false, error: CancelledError }`.
+
+### Failure & teardown
+
+omkit uses **structured supervision**: a failure that **nobody is watching** tears the whole run down and marks it failed. An Activity is "watched" if — before it fails — you awaited its `.result` (or `.ref`), attached an `on("error")` listener, or attached `.handleFailure`.
+
+- **Await it** (`await x.exec().result`) → the failure is yours to inspect as `{ ok: false }`; the run stays green.
+- **Fire-and-forget it** (`x.exec()`, never awaited) → an unobserved failure tears the run down. This is the guardrail for daemons: a crashed daemon fails the run instead of leaving it wedged.
+- **`.handleFailure(fn)`** → own a fire-and-forget Activity's failure: `fn(error)` runs instead of tearing down.
+
+```ts
+watchDir(".build").exec().tag("watch:daemon"); // crash here → run tears down
+someFlakyDaemon()
+  .exec()
+  .handleFailure((e) => log(e)); // …unless you own it
+```
+
+**Ctrl+C** and **`ctx.cancel()`** tear everything down gracefully — the log is always written. And **success is keep-alive**: when your `om` body returns, daemons it launched keep running until Ctrl+C or `cancel()`, so a body that finishes wiring things up doesn't kill the servers it started.
+
+### One log, on disk
+
+Every action's output, events, asserts, snapshots, and lifecycle land on **one timeline**. It streams live to the terminal (curated milestones) and is written to a per-run folder:
+
+- `result.json` — the run's tree, per-node status, and verdict.
+- `raw.jsonl` — every entry, machine-readable.
+- `main.log` + one `.log` per node — the human-readable timelines.
+- `events.log` / `asserts.log` / `snapshots.log` — cross-cutting rollups.
+
+`ctx` also gives each action `assert(...)` (tallies into the verdict) and `snapshot(name, value)` (captures JSON state to the run folder) — so a run is an inspectable artifact, not just exit codes.
 
 ## Events
 
-An instance exposes its declared events plus the lifecycle ones (`done`,
-`error`, `attached`):
+An Activity exposes its declared events plus the lifecycle ones (`done`, `error`, `attached`):
 
-- **`instance.on(event, handler)`** — subscribe with a handler for every emit.
-- **`instance.once(event)`** — a **promise** for the next emit: resolves with the
-  payload, or rejects if the action settles first (so an `await` never hangs).
-  `await instance.once("done")` is the action's result; a retained snapshot (like
-  `healthy`) resolves immediately even if you subscribe late.
+- **`activity.on(event, handler)`** — subscribe to every emit.
+- **`activity.once(event)`** — a **promise** for the next emit; resolves `undefined` if the Activity settles first, so an `await` never hangs. A retained snapshot (like `healthy`) is replayed immediately even if you subscribe late.
+
+```ts
+const probe = healthcheck({ port: 3000 }).exec();
+probe.on("healthy", (r) => console.log(`up after ${r.attempts} tries`));
+```
 
 ## Batteries — `omkit/actions`
 
-- **`command`** — wrap a shell command (output streams to the log, killed on teardown).
+Reusable actions built on the core engine. For anything beyond these, drop down to `action(...).run(...)`.
+
+- **`command`** — run a shell command; output streams to the log, killed on teardown.
 - **`watch`** / **`watchDir`** — watch a file or directory for changes (survives wipe + recreate).
 - **`untilLog`** — gate on the first log entry matching a predicate.
-- **`tailLog`** — tail a file another process writes, streaming its lines into the combined log.
-- **`healthcheck`** — poll a URL/port until status (and optionally body) matches.
+- **`tailLog`** — tail a file another process writes, folding its lines into the combined log.
+- **`healthcheck`** — poll a URL/port until the status (and optionally body) matches.
 - **`prompt`** — ask the terminal for input or a choice, with a timeout that falls back to a default; the answer is its handle.
-- **`chromePage`** — attach to Chrome over CDP — or to an existing Playwright
-  `Page`/`Browser`/`Context` (including Electron windows) — and expose the live
-  `Page` as a handle.
+- **`chromePage`** — attach to Chrome over CDP — or to an existing Playwright `Page`/`Browser`/`Context`, including Electron windows — and expose the live `Page` as a handle.
 
 ## Install
 
@@ -139,6 +150,8 @@ An instance exposes its declared events plus the lifecycle ones (`done`,
 npm install omkit
 ```
 
+Requires Node ≥ 20.11. ESM only.
+
 ## License
 
 MIT

package/dist/actions/chrome-page.d.ts

@@ -1,48 +1,31 @@
 import { type Browser, type BrowserContext, type Page } from "playwright-core";
 export type { Page, Browser, BrowserContext } from "playwright-core";
 /**
- * Where {@link chromePage} gets its page from:
- * - a **CDP endpoint** (`host:port` or `http://host:port`) — it connects, and
- *   owns (closes) that connection on teardown;
- * - an existing **`Page`** — e.g. an Electron `BrowserWindow`, used as-is;
+ * Where {@link chromePage} gets its page:
+ * - a **CDP endpoint** (`host:port` or `http://host:port`) — connected and owned
+ *   (closed on teardown);
+ * - an existing **`Page`** (e.g. an Electron window) — used as-is;
  * - a **`BrowserContext`** or **`Browser`** — a page is taken (or opened) from it.
  *
- * Handle sources aren't owned: teardown never closes a browser/window the action
- * didn't open, leaving its lifecycle to whoever launched it.
+ * Handles aren't owned: teardown never closes a browser/window the action didn't open.
  */
 export type ChromePageSource = string | Page | BrowserContext | Browser;
-/** Events {@link chromePage} pushes to the global log (and exposes via `.on`). */
+/** Events {@link chromePage} emits. */
 export interface ChromePageEvents {
-    /** A `console.*` call in the page; payload is the rendered text. */
     console: string;
-    /** An uncaught error in the page; payload is its message. */
     pageerror: string;
-    /** A top-level navigation settled; payload is the new URL. */
     navigated: string;
 }
 export interface ChromePageOptions {
-    /**
-     * Navigate the attached page here once acquired. Omit to drive the page as-is
-     * (the existing window, or the first page of a connected/handed-in browser).
-     */
+    /** Navigate the attached page here once acquired. Omit to drive it as-is. */
     url?: string;
 }
 /**
  * Publishes a Chrome/Chromium {@link Page} as this action's handle, so downstream
- * actions can await `instance.ref` and drive the same live page. The page comes
- * from whatever {@link ChromePageSource} is given — a CDP endpoint to connect to,
- * or an already-owned Playwright handle (an Electron `BrowserWindow` page, a
- * `BrowserContext`, or a `Browser`). The source may be a promise, so it wires
- * straight from another action's `.ref` (e.g. `chromePage("Explorer",
- * chromedriver.ref)` or `chromePage("App", electronApp.ref)`).
- *
- * Daemon-shaped like the watch actions: acquire the page, attach it, then stay
- * alive on a promise that only resolves when the run's `signal` aborts. On
- * teardown it closes the CDP connection *only* when it opened one — a handed-in
- * browser or window is left untouched for its owner to close.
- *
- * `label` names this page in the log (its `source`), so several `chromePage`
- * instances in one run stay distinguishable — e.g. `chromePage("Explorer",
- * chrome.ref)` logs its lines under `Explorer` rather than a shared default.
+ * actions can await `instance.ref` and drive the same live page. The source may be
+ * a promise, so it wires straight from another action's `.ref` (e.g.
+ * `chromePage("Explorer", chromedriver.ref)`). `label` tags this run so several
+ * pages in one run stay distinguishable. Daemon: acquire + attach, stay alive
+ * until teardown, then close the CDP connection only when it opened one.
  */
 export declare const chromePage: import("../index.ts").Action<[label: string, source: ChromePageSource | Promise<ChromePageSource>, opts?: ChromePageOptions | undefined], void, ChromePageEvents, Page>;

package/dist/actions/chrome-page.js

@@ -1,38 +1,26 @@
 import { chromium } from "playwright-core";
-import { action } from "../orchestration/action/action.js";
-// Playwright's classes are structurally distinct by these methods; only Browser
-// has `contexts()`, only Page has `mainFrame()`, and a BrowserContext has
-// `newPage()` without either — enough to tell a handed-in handle apart.
+import { action } from "../core/action.js";
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
 const isPage = (x) => typeof x.mainFrame === "function";
 const isBrowser = (x) => typeof x.contexts === "function";
 /** Take the first existing page of a context, or open one. */
 const pageOf = (context, fresh) => fresh ? context.newPage() : (context.pages()[0] ?? context.newPage());
 /**
  * Publishes a Chrome/Chromium {@link Page} as this action's handle, so downstream
- * actions can await `instance.ref` and drive the same live page. The page comes
- * from whatever {@link ChromePageSource} is given — a CDP endpoint to connect to,
- * or an already-owned Playwright handle (an Electron `BrowserWindow` page, a
- * `BrowserContext`, or a `Browser`). The source may be a promise, so it wires
- * straight from another action's `.ref` (e.g. `chromePage("Explorer",
- * chromedriver.ref)` or `chromePage("App", electronApp.ref)`).
- *
- * Daemon-shaped like the watch actions: acquire the page, attach it, then stay
- * alive on a promise that only resolves when the run's `signal` aborts. On
- * teardown it closes the CDP connection *only* when it opened one — a handed-in
- * browser or window is left untouched for its owner to close.
- *
- * `label` names this page in the log (its `source`), so several `chromePage`
- * instances in one run stay distinguishable — e.g. `chromePage("Explorer",
- * chrome.ref)` logs its lines under `Explorer` rather than a shared default.
+ * actions can await `instance.ref` and drive the same live page. The source may be
+ * a promise, so it wires straight from another action's `.ref` (e.g.
+ * `chromePage("Explorer", chromedriver.ref)`). `label` tags this run so several
+ * pages in one run stay distinguishable. Daemon: acquire + attach, stay alive
+ * until teardown, then close the CDP connection only when it opened one.
  */
-export const chromePage = action("Chrome Page")
+export const chromePage = action("chromePage")
     .emits()
     .ref()
-    .run(async ({ logs, signal, emit, attach }, label, source, opts = {}) => {
+    .run(async ({ signal, emit, attach, tag }, label, source, opts = {}) => {
+    tag(label);
     const { url } = opts;
     const resolved = await source;
-    // Resolve the source to a Page, recording what (if anything) we own. Only a
-    // CDP connection we open here is ours to close; handles belong to callers.
+    // Only a CDP connection we open here is ours to close; handles belong to callers.
     let owned;
     let page;
     let from;
@@ -40,8 +28,6 @@ export const chromePage = action("Chrome Page")
         const cdpUrl = resolved.includes("://") ? resolved : `http://${resolved}`;
         from = cdpUrl;
         try {
-            // connectOverCDP resolves the ws endpoint from /json/version under the
-            // hood, so the plain http URL is what to hand it.
             owned = await chromium.connectOverCDP(cdpUrl);
         }
         catch (cause) {
@@ -64,11 +50,11 @@ export const chromePage = action("Chrome Page")
         page = await pageOf(resolved, url !== undefined);
     }
     page.on("console", (msg) => {
-        logs.append({ source: label, level: "info", message: `console: ${msg.text()}` });
+        console.log(`console: ${msg.text()}`);
         emit("console", `from: ${label}:  ${msg.text()}`);
     });
     page.on("pageerror", (err) => {
-        logs.append({ source: label, level: "error", message: err.message });
+        console.error(err.message);
         emit("pageerror", `from: ${label}:  ${err.message}`);
     });
     page.on("framenavigated", (frame) => {
@@ -77,16 +63,17 @@ export const chromePage = action("Chrome Page")
     });
     if (url) {
         await page.goto(url);
-        logs.append({ source: label, level: "info", message: `navigated ${url}` });
+        console.log(`navigated ${url}`);
     }
     attach(page); // resolves instance.ref for every downstream action
-    logs.append({ source: label, level: "info", message: `attached ${from}` });
-    // Daemon: hold the page open until teardown, then drop the CDP session if it
-    // was ours; never close a handed-in browser/window.
+    console.log(`attached ${from}`);
+    // Daemon: hold the page open until teardown, then drop the CDP session if ours.
     return new Promise((resolveRun) => {
         const stop = () => {
+            // Bound the close: on a broken CDP connection `close()` can hang, which
+            // would wedge teardown — settle after a short race regardless.
             if (owned)
-                void owned.close().finally(resolveRun);
+                void Promise.race([owned.close(), delay(2000)]).finally(resolveRun);
             else
                 resolveRun();
         };

package/dist/actions/command.d.ts

@@ -1,48 +1,27 @@
-import type { AnyActionInstance } from "../orchestration/action/types.ts";
 /** Tunes an action built with {@link command}. */
 export interface CommandOptions {
-    /**
-     * Directory to run the command in. Relative paths resolve against the directory
-     * node was executed from (process.cwd()). Default ".".
-     */
+    /** Directory to run in; relative paths resolve against `process.cwd()`. Default ".". */
     cwd?: 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`.
-     */
+    /** Full environment for the child (handed as-is, not merged). Omit to inherit. */
     env?: NodeJS.ProcessEnv;
+    /** Let this command inherit the orchestrator's debugger (default false). */
+    inheritDebugger?: boolean;
 }
+declare function build(name: string, cmdOrFile: string, argsOrOptions: readonly string[] | CommandOptions, maybeOptions: CommandOptions): import("../index.ts").ActionInstance<import("zx").ProcessOutput, import("../core/types.ts").NoEvents, void>;
 /**
- * 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).
+ * Runs a shell command as an action instance. Two forms:
  *
- * Two forms:
+ * - `command(name, cmd, options?)` — a full command **string**, run verbatim through the
+ *   shell, so pipes, globs and `&&` work (quote anything yourself).
+ * - `command(name, file, args, options?)` — an executable **plus an args array**; each arg
+ *   is quoted individually, so spaces and `=`/paths in args are safe without hand-quoting.
  *
- * - **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.
+ * Output streams into the run's log under `name`; a non-zero exit fails the action;
+ * teardown kills the child tree. For interpolated events or a daemon loop, drop to
+ * `action(...).run(...)`.
  */
-export declare function command(name: string, cmd: string, options?: CommandOptions): AnyActionInstance;
-export declare function command(name: string, file: string, args: string[], options?: CommandOptions): AnyActionInstance;
+export declare const command: {
+    (name: string, cmd: string, options?: CommandOptions): ReturnType<typeof build>;
+    (name: string, file: string, args: readonly string[], options?: CommandOptions): ReturnType<typeof build>;
+};
+export {};

package/dist/actions/command.js

@@ -1,90 +1,38 @@
-import { spawn } from "node:child_process";
 import path from "node:path";
-import { action } from "../orchestration/action/action.js";
-import { killTree } from "../system/process/process.js";
+import { action } from "../core/action.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` —
- * so placing the whole command in `pieces` is identical to writing it inline as
- * `` proc`cmd` ``. The command is developer-supplied (not user input), so
- * verbatim is exactly what we want.
+ * Build a zx tagged template that runs `cmd` verbatim — zx only quotes interpolated
+ * args, not the template's `pieces`, so the whole (developer-supplied) command in
+ * `pieces` runs exactly as written (pipes, globs, `&&`).
  */
 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.output.snapshots, 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.
+function build(name, cmdOrFile, argsOrOptions, maybeOptions) {
+    const hasArgs = Array.isArray(argsOrOptions);
+    const args = hasArgs ? argsOrOptions : undefined;
+    const options = (hasArgs ? maybeOptions : argsOrOptions) ?? {};
+    return action(name).run((ctx) => {
         const cwd = path.resolve(options.cwd ?? ".");
-        // proc sources the LogsCollector from async context and streams output into it.
-        return proc(name, {
+        const proc = ctx.proc(name, {
             cwd,
             ...(options.env ? { env: options.env } : {}),
-        })(verbatim(cmdOrFile));
-    })(); // construct the instance here, so callers get one in a single call
+            ...(options.inheritDebugger ? { inheritDebugger: true } : {}),
+        });
+        // `file, args` form: zx quotes the file and every arg individually (arrays spread), so
+        // paths/values with spaces are safe and nothing is re-parsed by the shell. String form:
+        // run the whole command verbatim.
+        return args ? proc `${cmdOrFile} ${args}` : proc(verbatim(cmdOrFile));
+    })();
 }
 /**
- * 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).
+ * Runs a shell command as an action instance. Two forms:
+ *
+ * - `command(name, cmd, options?)` — a full command **string**, run verbatim through the
+ *   shell, so pipes, globs and `&&` work (quote anything yourself).
+ * - `command(name, file, args, options?)` — an executable **plus an args array**; each arg
+ *   is quoted individually, so spaces and `=`/paths in args are safe without hand-quoting.
+ *
+ * Output streams into the run's log under `name`; a non-zero exit fails the action;
+ * teardown kills the child tree. For interpolated events or a daemon loop, drop to
+ * `action(...).run(...)`.
  */
-const spawnDirect = (snapshots, logs, signal, name, file, args, options) => {
-    const cwd = path.resolve(options.cwd ?? ".");
-    const source = 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 = snapshots.captureJson(`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)
-                return resolve();
-            // Non-zero exit: reject with an error carrying `exitCode`, so the framework
-            // surfaces it on the action's Outcome (`{ ok: false, exitCode }`).
-            const error = Object.assign(new Error(`${name} exited with ${code ?? sig}`), {
-                exitCode: code ?? undefined,
-            });
-            reject(error);
-        });
-    });
-};
+export const command = (name, cmdOrFile, argsOrOptions = {}, maybeOptions = {}) => build(name, cmdOrFile, argsOrOptions, maybeOptions);

package/dist/actions/healthcheck.d.ts

@@ -28,11 +28,8 @@ export interface HealthcheckOptions {
 }
 /** The passing probe — also this action's result and `healthy` event payload. */
 export interface HealthcheckResult {
-    /** The URL that was probed. */
     url: string;
-    /** Status of the passing probe. */
     status: number;
-    /** Probes made, counting the passing one. */
     attempts: number;
 }
 /** Events emitted by {@link healthcheck}. */
@@ -42,14 +39,9 @@ export interface HealthcheckEvents {
 }
 /**
  * Gate: polls an HTTP endpoint until it answers in a healthy way (status and,
- * optionally, body), then resolves with that probe and emits `healthy`. The
- * counterpart to {@link import("./until-log.ts").untilLog} for "wait until a
- * service is up" — robust where log-scraping is brittle (no output format to
- * track, no ANSI to strip).
- *
- * Connection refusals and slow probes during startup are expected and simply
- * retried; each request is bounded by `requestTimeoutMs` (so a hung socket can't
- * stall the loop) and the whole wait by the run's abort signal and an optional
+ * optionally, body), then resolves with that probe and emits `healthy`. Refusals
+ * and slow probes during startup are retried; each request is bounded by
+ * `requestTimeoutMs` and the whole wait by the run's abort signal and optional
  * `timeoutMs`, so teardown unblocks a pending probe instead of hanging.
  */
 export declare const healthcheck: import("../index.ts").Action<[opts?: HealthcheckOptions | undefined], HealthcheckResult, HealthcheckEvents, void>;