omkit 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dimitar Mihaylov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# omkit
+
+**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.
+
+## 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.
+
+`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.
+
+```ts
+import { spin } from "omkit";
+import { command, healthcheck, chromedriver, 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…
+
+  const chrome = nod(chromedriver({ url: "http://localhost:3000" }));
+  nod(chromePage(chrome.ref)); // …then hand the live page downstream
+});
+```
+
+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.
+
+```
+                    spin()
+                      │
+        ┌─────────────┼─────────────┐
+        ▼             ▼             ▼
+     command      healthcheck   chromedriver
+                                     │ .ref
+                                     ▼
+                                 chromePage
+                                     │ .ref
+                                     ▼
+                                inspectPage
+```
+
+## 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));
+  });
+  ```
+
+- **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:
+
+  ```ts
+  const Server = action("Server")
+    .ref<number>()
+    .run(async ({ attach, signal }) => {
+      attach(await listen()); // publish the capability…
+      await until(signal); // …and stay alive
+    });
+
+  const Probe = action("Probe").run((_ctx, port: Promise<number>) => drive(port));
+
+  spin(async ({ nod }) => {
+    const server = nod(Server());
+    nod(Probe(server.ref)); // Probe receives Server's port, typed
+  });
+  ```
+
+- **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.)
+
+- **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.
+
+## Events
+
+An instance 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.
+
+## Batteries — `omkit/actions`
+
+- **`command`** — wrap 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.
+- **`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.
+
+## Install
+
+```sh
+npm install omkit
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,44 @@
+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;
+ * - 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.
+ */
+export type ChromePageSource = string | Page | BrowserContext | Browser;
+/** Events {@link chromePage} pushes to the global log (and exposes via `.on`). */
+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).
+     */
+    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(chromedriver.ref)` or
+ * `chromePage(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.
+ */
+export declare const chromePage: import("../core/action.ts").Action<[source: ChromePageSource | Promise<ChromePageSource>, opts?: ChromePageOptions | undefined], void, ChromePageEvents, Page>;

package/dist/actions/chrome-page.js

@@ -0,0 +1,94 @@
+import { chromium } from "playwright-core";
+import { action } from "../core/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.
+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(chromedriver.ref)` or
+ * `chromePage(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.
+ */
+export const chromePage = action("Chrome Page")
+    .emits()
+    .ref()
+    .run(async ({ logs, signal, emit, attach }, source, opts = {}) => {
+    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.
+    let owned;
+    let page;
+    let from;
+    if (typeof resolved === "string") {
+        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) {
+            throw new Error(`could not connect to Chrome over CDP at ${cdpUrl}`, { cause });
+        }
+        const context = owned.contexts()[0] ?? (await owned.newContext());
+        page = await pageOf(context, url !== undefined);
+    }
+    else if (isPage(resolved)) {
+        from = "page handle";
+        page = resolved;
+    }
+    else if (isBrowser(resolved)) {
+        from = "browser handle";
+        const context = resolved.contexts()[0] ?? (await resolved.newContext());
+        page = await pageOf(context, url !== undefined);
+    }
+    else {
+        from = "context handle";
+        page = await pageOf(resolved, url !== undefined);
+    }
+    page.on("console", (msg) => {
+        logs.append({ source: "Chrome Page", level: "info", message: `console: ${msg.text()}` });
+        emit("console", msg.text());
+    });
+    page.on("pageerror", (err) => {
+        logs.append({ source: "Chrome Page", level: "error", message: err.message });
+        emit("pageerror", err.message);
+    });
+    page.on("framenavigated", (frame) => {
+        if (frame === page.mainFrame())
+            emit("navigated", frame.url());
+    });
+    if (url) {
+        await page.goto(url);
+        logs.append({ source: "Chrome Page", level: "info", message: `navigated ${url}` });
+    }
+    attach(page); // resolves instance.ref for every downstream action
+    logs.append({ source: "Chrome Page", 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.
+    return new Promise((resolveRun) => {
+        const stop = () => {
+            if (owned)
+                void owned.close().finally(resolveRun);
+            else
+                resolveRun();
+        };
+        if (signal.aborted)
+            stop();
+        else
+            signal.addEventListener("abort", stop, { once: true });
+    });
+});

package/dist/actions/command.d.ts

@@ -0,0 +1,26 @@
+/** 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 ".".
+     */
+    cwd?: string;
+    /** Label the child's output is logged under. Defaults to the action's name. */
+    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`.
+ *
+ *   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.
+ */
+export declare const command: (name: string, cmd: string, options?: CommandOptions) => import("../core/action.ts").ActionInstance<import("zx").ProcessOutput, import("../core/action.ts").NoEvents, void>;

package/dist/actions/command.js

@@ -0,0 +1,32 @@
+import path from "node:path";
+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.
+ */
+const verbatim = (cmd) => Object.assign([cmd], { raw: [cmd] });
+/**
+ * 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.
+ */
+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 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

package/dist/actions/healthcheck.d.ts

@@ -0,0 +1,55 @@
+/** How a probe's HTTP status is judged healthy: an exact code, a set, or a predicate. */
+export type StatusMatcher = number | number[] | ((status: number) => boolean);
+/** How a probe's response body is judged healthy: a substring, a regex, or a predicate. */
+export type BodyMatcher = string | RegExp | ((body: string) => boolean);
+export interface HealthcheckOptions {
+    /** Full URL to probe. Overrides host/port/path/protocol when set. */
+    url?: string;
+    /** Host to probe when building from parts. Default "localhost". */
+    host?: string;
+    /** Port to probe when building from parts. */
+    port?: number;
+    /** Path appended after host:port when building from parts. Default "/". */
+    path?: string;
+    /** Scheme when building from parts. Default "http". */
+    protocol?: "http" | "https";
+    /** Acceptable status. Default: any 2xx. */
+    status?: StatusMatcher;
+    /** Optional body match against the response text. Omit to ignore the body. */
+    body?: BodyMatcher;
+    /** Delay between probes. Default 250ms. */
+    intervalMs?: number;
+    /** Abort a single probe that hasn't responded within this long. Default 5000ms. */
+    requestTimeoutMs?: number;
+    /** Reject after this long overall. Omit to probe until healthy or teardown. */
+    timeoutMs?: number;
+    /** Per-request overrides (method, headers, …). Default a plain GET. */
+    request?: RequestInit;
+}
+/** 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}. */
+export interface HealthcheckEvents {
+    /** The target passed every matcher; payload is the passing probe. */
+    healthy: HealthcheckResult;
+}
+/**
+ * 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
+ * `timeoutMs`, so teardown unblocks a pending probe instead of hanging.
+ */
+export declare const healthcheck: import("../core/action.ts").Action<[opts?: HealthcheckOptions | undefined], HealthcheckResult, HealthcheckEvents, void>;

package/dist/actions/healthcheck.js

@@ -0,0 +1,94 @@
+import { action } from "../core/action.js";
+/**
+ * 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
+ * `timeoutMs`, so teardown unblocks a pending probe instead of hanging.
+ */
+export const healthcheck = action("Healthcheck")
+    .emits()
+    .run(async ({ logs, signal, emit }, opts = {}) => {
+    const { url: rawUrl, host = "localhost", port, path = "/", protocol = "http", status = (s) => s >= 200 && s < 300, body, intervalMs = 250, requestTimeoutMs = 5000, timeoutMs, request, } = opts;
+    const url = rawUrl ?? (port !== undefined ? `${protocol}://${host}:${port}${path}` : undefined);
+    if (!url)
+        throw new Error("healthcheck: provide a `url` or a `port`");
+    const statusOk = (s) => typeof status === "function"
+        ? status(s)
+        : Array.isArray(status)
+            ? status.includes(s)
+            : status === s;
+    const bodyOk = (text) => body === undefined
+        ? true
+        : typeof body === "function"
+            ? body(text)
+            : body instanceof RegExp
+                ? body.test(text)
+                : text.includes(body);
+    // Abortable inter-probe delay: resolves after `ms`, or rejects on teardown.
+    const sleep = (ms) => new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error("healthcheck: aborted"));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+    });
+    const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
+    logs.append({ source: "Healthcheck", level: "info", message: `probing ${url}` });
+    let attempts = 0;
+    for (;;) {
+        if (signal.aborted)
+            throw new Error("healthcheck: aborted");
+        attempts++;
+        try {
+            const res = await fetch(url, {
+                ...request,
+                // Per-probe timeout combined with teardown — either aborts the request.
+                signal: AbortSignal.any([signal, AbortSignal.timeout(requestTimeoutMs)]),
+            });
+            if (statusOk(res.status)) {
+                // Read the body only when a matcher needs it; otherwise drain it so the
+                // connection is released rather than left dangling.
+                const text = body === undefined ? "" : await res.text();
+                if (body === undefined)
+                    await res.body?.cancel().catch(() => { });
+                if (bodyOk(text)) {
+                    const result = { url, status: res.status, attempts };
+                    const probes = `${attempts} ${attempts === 1 ? "probe" : "probes"}`;
+                    logs.append({
+                        source: "Healthcheck",
+                        level: "info",
+                        message: `healthy ${url} → ${res.status} (${probes})`,
+                    });
+                    emit("healthy", result);
+                    return result;
+                }
+            }
+            else {
+                await res.body?.cancel().catch(() => { });
+            }
+        }
+        catch {
+            // Teardown surfaces here too — stop cleanly. Otherwise it's a refusal or
+            // probe timeout while the service starts up: expected, so keep polling.
+            if (signal.aborted)
+                throw new Error("healthcheck: aborted");
+        }
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new Error(`healthcheck: ${url} not healthy within ${timeoutMs}ms (${attempts} probes)`);
+        }
+        await sleep(intervalMs);
+    }
+});

package/dist/actions/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * tswm/actions — reusable actions built on the core engine.
+ *
+ * Each is a ready-made {@link action} for a common orchestration need; for
+ * anything beyond these, drop down to `action(...).run(...)` from `tswm`.
+ */
+export { command } from "./command.ts";
+export type { CommandOptions } from "./command.ts";
+export { watch } from "./watch.ts";
+export type { FileEvent, FileListener, WatchOptions } from "./watch.ts";
+export { watchDir } from "./watch-dir.ts";
+export type { WatchDirOptions, WatchDirEvents } from "./watch-dir.ts";
+export { untilLog } from "./until-log.ts";
+export type { LogMatcher, UntilLogOptions, UntilLogEvents } from "./until-log.ts";
+export { tailLog } from "./tail-log.ts";
+export type { TailLogOptions } from "./tail-log.ts";
+export { prompt } from "./prompt.ts";
+export type { PromptOptions, InputPromptOptions, ChoicePromptOptions, PromptChoice, PromptVia, PromptEvents, } from "./prompt.ts";
+export { healthcheck } from "./healthcheck.ts";
+export type { HealthcheckOptions, HealthcheckResult, HealthcheckEvents, StatusMatcher, BodyMatcher, } from "./healthcheck.ts";
+export { chromePage } from "./chrome-page.ts";
+export type { ChromePageOptions, ChromePageEvents, ChromePageSource, Page, Browser, BrowserContext, } from "./chrome-page.ts";

package/dist/actions/index.js

@@ -0,0 +1,14 @@
+/**
+ * tswm/actions — reusable actions built on the core engine.
+ *
+ * Each is a ready-made {@link action} for a common orchestration need; for
+ * anything beyond these, drop down to `action(...).run(...)` from `tswm`.
+ */
+export { command } from "./command.js";
+export { watch } from "./watch.js";
+export { watchDir } from "./watch-dir.js";
+export { untilLog } from "./until-log.js";
+export { tailLog } from "./tail-log.js";
+export { prompt } from "./prompt.js";
+export { healthcheck } from "./healthcheck.js";
+export { chromePage } from "./chrome-page.js";

package/dist/actions/prompt.d.ts

@@ -0,0 +1,54 @@
+/** A selectable option: a bare string (its own value), or a labelled value. */
+export type PromptChoice = string | {
+    label: string;
+    value: string;
+};
+interface PromptCommon {
+    /** Question shown to the user. Defaults per kind ("Input:" / "Choose:"). */
+    message?: string;
+    /**
+     * Use the default and stop waiting after this many ms. A non-finite or
+     * non-positive value waits indefinitely (until answered or teardown).
+     * Default 30000.
+     */
+    timeoutMs?: number;
+}
+export interface InputPromptOptions extends PromptCommon {
+    kind?: "input";
+    /** Value used on an empty answer or timeout. Default "". */
+    default?: string;
+}
+export interface ChoicePromptOptions extends PromptCommon {
+    kind: "choice";
+    /** The options to choose from (entered by number, value, or label). */
+    choices: PromptChoice[];
+    /** Default selection — a choice value or a 1-based index. Default: the first choice. */
+    default?: string | number;
+}
+export type PromptOptions = InputPromptOptions | ChoicePromptOptions;
+/** How a prompt's answer was decided. */
+export type PromptVia = "input" | "default" | "timeout";
+export interface PromptEvents {
+    /** The prompt was shown; payload is the question message. */
+    prompt: string;
+    /** An answer settled; payload is the value and how it was decided. */
+    answer: {
+        value: string;
+        via: PromptVia;
+    };
+}
+/**
+ * Asks the terminal a question — free-text **input** or a **choice** from a list —
+ * and resolves with the answer, which it also publishes as the action's handle
+ * (so `prompt(...).ref` feeds straight into another action). Everything is
+ * defaulted: a bare `prompt()` is a free-text input with no default and a 30s
+ * timeout.
+ *
+ * A configurable timeout (default 30s; non-finite/≤0 waits forever) falls back to
+ * the default value, so an unattended run never blocks. The run's abort signal
+ * also unblocks a pending prompt on teardown. Emits `prompt` when shown and
+ * `answer` when settled (carrying whether it came from input, the default, or a
+ * timeout).
+ */
+export declare const prompt: import("../core/action.ts").Action<[opts?: PromptOptions | undefined], string, PromptEvents, string>;
+export {};