omkit 0.4.7 → 0.8.0

package/dist/actions/chrome-page.js

@@ -5,11 +5,86 @@ 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());
+/** Every page open across every context — a reattached browser may have more than one. */
+export const pagesOf = (browser) => browser.contexts().flatMap((c) => c.pages());
+/**
+ * Find the one open page a {@link PageMatch} selects, or explain what was open instead.
+ *
+ * Listing the candidates matters more here than anywhere else in this action: the caller is
+ * attaching to a browser they did not launch, so "no match" is nearly always a stale URL or a
+ * predicate written against the wrong page — and both are obvious the moment you can see what
+ * was actually there.
+ *
+ * A predicate that throws (a chrome:// page, a document still loading, a cross-origin frame)
+ * counts as "did not match" rather than failing the search, but is reported, because a
+ * predicate that threw on every page is a very different problem from one that simply found
+ * nothing.
+ */
+export async function selectPage(pages, match) {
+    const describe = () => pages.length ? pages.map((p) => `  ${p.url()}`).join("\n") : "  (no pages are open)";
+    if (typeof match === "string" || match instanceof RegExp) {
+        const hit = pages.find((p) => typeof match === "string" ? p.url().includes(match) : match.test(p.url()));
+        if (hit)
+            return hit;
+        throw new Error(`no open page matched ${String(match)}. Open pages:\n${describe()}`);
+    }
+    // Sequential, not parallel: stopping at the first hit keeps the predicate off pages it
+    // never needed to touch, which matters because it is someone else's live browser.
+    const threw = [];
+    for (const page of pages) {
+        try {
+            if (await page.evaluate(match.js))
+                return page;
+        }
+        catch (e) {
+            threw.push(`  ${page.url()} — ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    const errors = threw.length ? `\nThe predicate threw on:\n${threw.join("\n")}` : "";
+    throw new Error(`no open page satisfied \`${match.js}\`. Open pages:\n${describe()}${errors}`);
+}
+/**
+ * Resolve a {@link ChromePageSource} down to one live page.
+ *
+ * With `match` the page must already exist and is searched for across **every** context: a
+ * reattached browser belongs to someone else, and nothing says the page you want lives in the
+ * context we would otherwise default to. Without `match` the old behaviour stands — take the
+ * first page, or open a fresh one when navigating.
+ */
+async function acquire(source, opts) {
+    const { url, match } = opts;
+    const fresh = url !== undefined;
+    if (typeof source === "string") {
+        const cdpUrl = source.includes("://") ? source : `http://${source}`;
+        let owned;
+        try {
+            owned = await chromium.connectOverCDP(cdpUrl);
+        }
+        catch (cause) {
+            throw new Error(`could not connect to Chrome over CDP at ${cdpUrl}`, { cause });
+        }
+        const page = match
+            ? await selectPage(pagesOf(owned), match)
+            : await pageOf(owned.contexts()[0] ?? (await owned.newContext()), fresh);
+        return { page, from: cdpUrl, owned };
+    }
+    if (isPage(source))
+        return { page: source, from: "page handle" };
+    if (isBrowser(source)) {
+        const page = match
+            ? await selectPage(pagesOf(source), match)
+            : await pageOf(source.contexts()[0] ?? (await source.newContext()), fresh);
+        return { page, from: "browser handle" };
+    }
+    const page = match ? await selectPage(source.pages(), match) : await pageOf(source, fresh);
+    return { page, from: "context handle" };
+}
 /**
  * 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 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
+ * actions can await `instance.ref` and drive the same live page. The source is a
+ * resolved handle, not a promise — chain it from another action by awaiting that
+ * action's `.ref` at the call site (e.g.
+ * `chromePage("Explorer", await 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.
  */
@@ -19,36 +94,9 @@ export const chromePage = action("chromePage")
     .run(async ({ signal, emit, attach, tag }, label, source, opts = {}) => {
     tag(label);
     const { url } = opts;
-    const resolved = await source;
-    // 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 {
-            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);
-    }
+    // With both `match` and `url`, acquire finds the existing page and this navigates it —
+    // "go to that tab, then send it here" rather than opening a second one.
+    const { page, from, owned } = await acquire(source, opts);
     page.on("console", (msg) => {
         console.log(`console: ${msg.text()}`);
         emit("console", `from: ${label}:  ${msg.text()}`);

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

@@ -0,0 +1,50 @@
+import { type ChromePageSource, type PageMatch } from "./chrome-page.ts";
+export interface DrivePageOptions {
+    /**
+     * Where the page is. Either a **CDP endpoint** (`host:port` or a URL) for a browser
+     * running in another process, or a **live handle** — a `Page`, `BrowserContext`, or
+     * `Browser` — published by an earlier action in this same run.
+     *
+     * Both matter, and for different reasons. The address form is plain data, so it can be
+     * described by a schema and called from outside the process; the handle form skips the
+     * network entirely when the browser is already yours, which is what an om driving its own
+     * stack wants. Defaults to the endpoint `browser` opens when given a debugging port.
+     */
+    target?: ChromePageSource;
+    /** Which open tab to drive. Omit to take the first page the browser has open. */
+    match?: PageMatch;
+    /** Navigate the chosen tab here first. Omit to drive it wherever it already is. */
+    url?: string;
+    /**
+     * The JS to run in the page, as an **expression** — `document.title`, not `return …`.
+     * Wrap several statements in an IIFE: `(() => { …; return x })()`. The result travels
+     * back through the run's log, so it has to be JSON-serialisable.
+     */
+    js: string;
+    /** Save a PNG of the page afterwards and register it as a run artifact. Default true. */
+    screenshot?: boolean;
+}
+/** What {@link drivePage} reports back. */
+export interface DrivePageResult {
+    /** Whatever the expression evaluated to. */
+    readonly value: unknown;
+    readonly title: string;
+    readonly url: string;
+    /** Absolute path of the screenshot, when one was taken. */
+    readonly screenshot?: string;
+}
+/**
+ * Evaluate an expression in a live page and report what came back.
+ *
+ * Reaches its page either way round, and that is the point. Given a **handle** it drives a
+ * page an earlier action in the same run already published — the cheap path, and the one an
+ * om driving its own stack should take. Given a **CDP address** it attaches to a browser in
+ * another process entirely, which is what lets this action be described by a schema and
+ * called by name from outside: `browser` and {@link chromePage} publish capability handles,
+ * and a handle is not something a caller across a process boundary can pass.
+ *
+ * Nothing here is owned. `chromePage` closes only a CDP connection it opened, and closing a
+ * CDP connection disconnects the client rather than stopping the browser — so this finishing,
+ * failing, or being cancelled never tears down the stack it attached to, in either mode.
+ */
+export declare const drivePage: import("../core/types.ts").Action<[opts: DrivePageOptions], DrivePageResult, import("../core/types.ts").NoEvents, void>;

package/dist/actions/drive-page.js

@@ -0,0 +1,68 @@
+import path from "node:path";
+import { action } from "../core/action.js";
+import { chromePage } from "./chrome-page.js";
+/**
+ * Evaluate an expression in a live page and report what came back.
+ *
+ * Reaches its page either way round, and that is the point. Given a **handle** it drives a
+ * page an earlier action in the same run already published — the cheap path, and the one an
+ * om driving its own stack should take. Given a **CDP address** it attaches to a browser in
+ * another process entirely, which is what lets this action be described by a schema and
+ * called by name from outside: `browser` and {@link chromePage} publish capability handles,
+ * and a handle is not something a caller across a process boundary can pass.
+ *
+ * Nothing here is owned. `chromePage` closes only a CDP connection it opened, and closing a
+ * CDP connection disconnects the client rather than stopping the browser — so this finishing,
+ * failing, or being cancelled never tears down the stack it attached to, in either mode.
+ */
+export const drivePage = action("drivePage")
+    .describe({
+    summary: "Evaluate JS in a live page — a handle from this run, or a tab of a browser reached over CDP — and report the result.",
+})
+    .run(async ({ snapshot, artifact, artifactsFolder }, opts) => {
+    const { target = "localhost:9222", match, url } = opts;
+    // `chromePage` is daemon-shaped: it stays alive until something stops it, so a run that
+    // only awaits its `.ref` never settles — the tree finishes while the process is still
+    // held open, and the caller waits out a timeout for a run that is already done. Keep the
+    // handle and release it, the same shape `tskb:build` uses for its watcher.
+    const attached = chromePage("target", target, {
+        ...(url === undefined ? {} : { url }),
+        ...(match === undefined ? {} : { match }),
+    }).tag("page:attach");
+    try {
+        const page = await attached.ref;
+        return await evaluateIn(page, opts, { snapshot, artifact, artifactsFolder });
+    }
+    finally {
+        // Releases the daemon whether the expression threw or not. Cancelling closes the CDP
+        // connection, which disconnects this client and leaves the browser to its owner.
+        attached.cancel();
+    }
+});
+/** The work itself, split out so the daemon handle above has one obvious release point. */
+async function evaluateIn(page, opts, { snapshot, artifact, artifactsFolder }) {
+    const { js, screenshot = true } = opts;
+    const title = await page.title();
+    void snapshot("page", { title, url: page.url() });
+    // Evaluated as an expression in page context. A string is sent verbatim, which is what
+    // keeps it clear of the esbuild `__name` rewriting that catches serialized *functions*
+    // under tsx — see the shim in chrome-page.ts.
+    let value;
+    try {
+        value = await page.evaluate(js);
+    }
+    catch (cause) {
+        // A page-side stack means little to a caller who only sent a string, so lead with the
+        // expression that failed and keep the original as the cause.
+        throw new Error(`the expression threw in the page: ${js}`, { cause });
+    }
+    void snapshot("result", { js, value });
+    console.log(`result: ${JSON.stringify(value) ?? "undefined"}`);
+    const result = { value, title, url: page.url() };
+    if (!screenshot)
+        return result;
+    const file = path.join(artifactsFolder, "page.png");
+    await page.screenshot({ path: file });
+    artifact("page.png", file, { description: `The page after evaluating: ${js}` });
+    return { ...result, screenshot: file };
+}

package/dist/actions/index.d.ts

@@ -8,6 +8,8 @@ export { untilLog } from "./until-log.ts";
 export type { LogMatcher, UntilLogOptions, UntilLogEvents } from "./until-log.ts";
 export { healthcheck } from "./healthcheck.ts";
 export type { HealthcheckOptions, HealthcheckResult, HealthcheckEvents, StatusMatcher, BodyMatcher, } from "./healthcheck.ts";
+export { portFree } from "./port-free.ts";
+export type { PortFreeOptions, PortFreeResult, PortFreeEvents } from "./port-free.ts";
 export { watch } from "./watch.ts";
 export type { FileEvent, FileListener, WatchOptions } from "./watch.ts";
 export { watchDir } from "./watch-dir.ts";
@@ -15,8 +17,10 @@ export type { WatchDirOptions, WatchDirEvents } from "./watch-dir.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 { chromePage } from "./chrome-page.ts";
-export type { ChromePageOptions, ChromePageEvents, ChromePageSource, Page, Browser, BrowserContext, } from "./chrome-page.ts";
+export type { PromptOptions, InputPromptOptions, ChoicePromptOptions, MultilinePromptOptions, MultilineUntil, PromptChoice, PromptVia, PromptEvents, } from "./prompt.ts";
+export { chromePage, selectPage, pagesOf } from "./chrome-page.ts";
+export type { ChromePageOptions, ChromePageEvents, ChromePageSource, PageMatch, Page, Browser, BrowserContext, } from "./chrome-page.ts";
 export { browser } from "./browser.ts";
 export type { BrowserOptions } from "./browser.ts";
+export { drivePage } from "./drive-page.ts";
+export type { DrivePageOptions, DrivePageResult } from "./drive-page.ts";

package/dist/actions/index.js

@@ -5,9 +5,11 @@
 export { command } from "./command.js";
 export { untilLog } from "./until-log.js";
 export { healthcheck } from "./healthcheck.js";
+export { portFree } from "./port-free.js";
 export { watch } from "./watch.js";
 export { watchDir } from "./watch-dir.js";
 export { tailLog } from "./tail-log.js";
 export { prompt } from "./prompt.js";
-export { chromePage } from "./chrome-page.js";
+export { chromePage, selectPage, pagesOf } from "./chrome-page.js";
 export { browser } from "./browser.js";
+export { drivePage } from "./drive-page.js";

package/dist/actions/port-free.d.ts

@@ -0,0 +1,29 @@
+export interface PortFreeOptions {
+    /** Host to probe. Default "127.0.0.1". */
+    host?: string;
+    /** Delay between probes. Default 500ms. */
+    intervalMs?: number;
+    /** Abort a single connect attempt that hasn't answered within this long. Default 1000ms. */
+    connectTimeoutMs?: number;
+    /** Reject after this long overall. Default 30000ms; pass `undefined` to wait until teardown. */
+    timeoutMs?: number;
+}
+/** The probe that found the port free — this action's result and `free` event payload. */
+export interface PortFreeResult {
+    port: number;
+    host: string;
+    attempts: number;
+}
+/** Events emitted by {@link portFree}. */
+export interface PortFreeEvents {
+    /** Nothing is listening any more; payload is the passing probe. */
+    free: PortFreeResult;
+}
+/**
+ * Gate: polls a TCP port until nothing is listening on it, then resolves with that
+ * probe and emits `free`. The mirror of `healthcheck` — where that one waits
+ * for a service to come up, this waits for one to let go, so a restart can rebind
+ * without racing the previous process's socket. Bounded by the run's abort signal
+ * and `timeoutMs`, so teardown unblocks a pending probe instead of hanging.
+ */
+export declare const portFree: import("../index.ts").Action<[port: number, opts?: PortFreeOptions | undefined], PortFreeResult, PortFreeEvents, void>;

package/dist/actions/port-free.js

@@ -0,0 +1,78 @@
+import net from "node:net";
+import { action } from "../core/action.js";
+/**
+ * One TCP connect attempt. A refusal is the only answer that proves nobody is
+ * listening: a successful connect means the port is taken, and a hang or any other
+ * error (filtered, unreachable) is inconclusive, so both count as still busy rather
+ * than letting a firewall read as "free".
+ */
+const probe = (port, host, connectTimeoutMs, signal) => new Promise((resolve) => {
+    const socket = new net.Socket();
+    let settled = false;
+    const finish = (free) => {
+        if (settled)
+            return;
+        settled = true;
+        signal.removeEventListener("abort", onAbort);
+        socket.destroy();
+        resolve(free);
+    };
+    // Teardown mid-connect: drop the socket and report "busy" — the loop's own abort
+    // check turns that into a clean stop on the next pass.
+    function onAbort() {
+        finish(false);
+    }
+    socket.setTimeout(connectTimeoutMs);
+    socket.once("connect", () => finish(false));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", (error) => finish(error.code === "ECONNREFUSED"));
+    signal.addEventListener("abort", onAbort, { once: true });
+    socket.connect(port, host);
+});
+/**
+ * Gate: polls a TCP port until nothing is listening on it, then resolves with that
+ * probe and emits `free`. The mirror of `healthcheck` — where that one waits
+ * for a service to come up, this waits for one to let go, so a restart can rebind
+ * without racing the previous process's socket. Bounded by the run's abort signal
+ * and `timeoutMs`, so teardown unblocks a pending probe instead of hanging.
+ */
+export const portFree = action("portFree")
+    .emits()
+    .run(async ({ signal, emit }, port, opts = {}) => {
+    const { host = "127.0.0.1", intervalMs = 500, connectTimeoutMs = 1000, timeoutMs = 30_000, } = opts;
+    // 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("portFree: 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;
+    const target = `${host}:${port}`;
+    console.log(`waiting for ${target} to free up`);
+    let attempts = 0;
+    for (;;) {
+        if (signal.aborted)
+            throw new Error("portFree: aborted");
+        attempts++;
+        if (await probe(port, host, connectTimeoutMs, signal)) {
+            const result = { port, host, attempts };
+            const probes = `${attempts} ${attempts === 1 ? "probe" : "probes"}`;
+            console.log(`free ${target} (${probes})`);
+            emit("free", result);
+            return result;
+        }
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new Error(`portFree: ${target} still in use after ${timeoutMs}ms (${attempts} probes)`);
+        }
+        await sleep(intervalMs);
+    }
+});

package/dist/actions/prompt.d.ts

@@ -20,7 +20,33 @@ export interface ChoicePromptOptions extends PromptCommon {
     /** Default selection — a choice value or a 1-based index. Default: the first choice. */
     default?: string | number;
 }
-export type PromptOptions = InputPromptOptions | ChoicePromptOptions;
+/** How a multiline prompt decides the user is done. */
+export type MultilineUntil = "json" | string | ((text: string) => boolean);
+export interface MultilinePromptOptions extends PromptCommon {
+    kind: "multiline";
+    /** A one-line type sketch printed under the message. */
+    hint?: string;
+    /** Default `"json"` — stop once the text parses as JSON. */
+    until?: MultilineUntil;
+    /** Value used on EOF with no input, or on timeout. Default "". */
+    default?: string;
+}
+export type PromptOptions = InputPromptOptions | ChoicePromptOptions | MultilinePromptOptions;
+/** Reads one line, or `undefined` at EOF. */
+export type LineReader = () => Promise<string | undefined>;
+/**
+ * Accumulate lines until `until` says stop, or EOF. Exported for testing: keeping the
+ * termination rule separate from the terminal means it can be driven by a scripted
+ * reader instead of a TTY.
+ *
+ * `"json"` is self-terminating — pasting a pretty-printed blob just works, with no
+ * sentinel to explain. A sentinel line is excluded from the result.
+ *
+ * Note there is deliberately no Ctrl-D/EOF-by-keystroke terminator: readline treats it as
+ * a close, and `prompt` builds and tears down an interface per call, so it risks leaving
+ * stdin unusable for later prompts in the same run.
+ */
+export declare function readUntil(read: LineReader, until: MultilineUntil): Promise<string>;
 /** How a prompt's answer was decided. */
 export type PromptVia = "input" | "default" | "timeout";
 export interface PromptEvents {
@@ -31,10 +57,11 @@ export interface PromptEvents {
     };
 }
 /**
- * Asks the terminal a question — free-text **input** or a **choice** — and resolves
- * with the answer, which it also attaches as the handle (`prompt(...).ref` feeds
- * another action). A timeout (default 30s) falls back to the default so an
- * unattended run never blocks; teardown also unblocks a pending prompt.
+ * Asks the terminal a question — free-text **input**, a **choice**, or a **multiline**
+ * block (see {@link readUntil} for how it ends) — and resolves with the answer, which it
+ * also attaches as the handle (`prompt(...).ref` feeds another action). A timeout
+ * (default 30s) falls back to the default so an unattended run never blocks; teardown
+ * also unblocks a pending prompt.
  */
 export declare const prompt: import("../index.ts").Action<[opts?: PromptOptions | undefined], string, PromptEvents, string>;
 export {};

package/dist/actions/prompt.js

@@ -1,15 +1,56 @@
 import { createInterface } from "node:readline/promises";
 import { action } from "../core/action.js";
 import { activeSupervisor } from "../core/interaction.js";
+/**
+ * Accumulate lines until `until` says stop, or EOF. Exported for testing: keeping the
+ * termination rule separate from the terminal means it can be driven by a scripted
+ * reader instead of a TTY.
+ *
+ * `"json"` is self-terminating — pasting a pretty-printed blob just works, with no
+ * sentinel to explain. A sentinel line is excluded from the result.
+ *
+ * Note there is deliberately no Ctrl-D/EOF-by-keystroke terminator: readline treats it as
+ * a close, and `prompt` builds and tears down an interface per call, so it risks leaving
+ * stdin unusable for later prompts in the same run.
+ */
+export async function readUntil(read, until) {
+    const lines = [];
+    for (;;) {
+        const line = await read();
+        if (line === undefined)
+            break; // EOF
+        if (typeof until === "string" && until !== "json" && line === until)
+            break;
+        lines.push(line);
+        const text = lines.join("\n");
+        if (until === "json" && parses(text))
+            break;
+        if (typeof until === "function" && until(text))
+            break;
+    }
+    return lines.join("\n");
+}
+function parses(text) {
+    if (text.trim() === "")
+        return false;
+    try {
+        JSON.parse(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 const asChoices = (choices) => choices.map((c) => (typeof c === "string" ? { label: c, value: c } : c));
 /** Route the request over the supervisor channel, resolving the raw answer against the choices. */
 async function askSupervisor(supervisor, ctx, waitSignal) {
     const { opts, message, defaultValue, resolveRaw } = ctx;
     const spec = {
-        kind: opts.kind === "choice" ? "choice" : "input",
+        kind: opts.kind === "choice" ? "choice" : opts.kind === "multiline" ? "multiline" : "input",
         message,
         default: defaultValue,
         ...(opts.kind === "choice" ? { choices: asChoices(opts.choices) } : {}),
+        ...(opts.kind === "multiline" && opts.hint ? { hint: opts.hint } : {}),
     };
     const answer = await supervisor.request(spec, waitSignal);
     const resolved = resolveRaw(answer.value);
@@ -18,9 +59,44 @@ async function askSupervisor(supervisor, ctx, waitSignal) {
     return { value: resolved, via: answer.via ?? "input" };
 }
 /** Read the answer straight from the terminal (the bare, unsupervised path). */
-async function askTerminal(query, resolveRaw, defaultValue, waitSignal) {
+async function askTerminal(query, resolveRaw, defaultValue, waitSignal, multiline) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
+        if (multiline) {
+            process.stdout.write(query);
+            // Iterate the interface instead of calling `rl.question` per line. A paste arrives as a
+            // single chunk and readline emits every line in it synchronously, so a one-shot `question`
+            // takes the first line and the rest are emitted with no listener and lost — which would
+            // break the one case this kind exists for. The async iterator queues lines and applies
+            // backpressure, so a pasted blob and a typed one read the same.
+            const it = rl[Symbol.asyncIterator]();
+            // Nothing can abort a pending `it.next()`, so an abort (prompt timeout or run teardown)
+            // closes the interface, which ends the iteration. `waitSignal` then tells that apart from
+            // a genuinely closed stream below.
+            const onAbort = () => void rl.close();
+            if (waitSignal.aborted)
+                onAbort();
+            else
+                waitSignal.addEventListener("abort", onAbort, { once: true });
+            try {
+                const read = async () => {
+                    const { value, done } = await it.next();
+                    return done ? undefined : value; // done → end of input
+                };
+                const text = await readUntil(read, multiline.until);
+                // Giving up is not end-of-input. Propagate so the action's outer catch labels the answer
+                // `timeout` and falls back to the default, the same as the `input` and `choice` kinds —
+                // half a JSON blob is not a useful answer, so the partial text is dropped here.
+                if (waitSignal.aborted)
+                    throw new Error("prompt aborted");
+                if (text.trim() === "")
+                    return { value: defaultValue, via: "default" };
+                return { value: text, via: "input" };
+            }
+            finally {
+                waitSignal.removeEventListener("abort", onAbort);
+            }
+        }
         const raw = (await rl.question(query, { signal: waitSignal })).trim();
         if (raw === "")
             return { value: defaultValue, via: "default" };
@@ -35,10 +111,11 @@ async function askTerminal(query, resolveRaw, defaultValue, waitSignal) {
     }
 }
 /**
- * Asks the terminal a question — free-text **input** or a **choice** — and resolves
- * with the answer, which it also attaches as the handle (`prompt(...).ref` feeds
- * another action). A timeout (default 30s) falls back to the default so an
- * unattended run never blocks; teardown also unblocks a pending prompt.
+ * Asks the terminal a question — free-text **input**, a **choice**, or a **multiline**
+ * block (see {@link readUntil} for how it ends) — and resolves with the answer, which it
+ * also attaches as the handle (`prompt(...).ref` feeds another action). A timeout
+ * (default 30s) falls back to the default so an unattended run never blocks; teardown
+ * also unblocks a pending prompt.
  */
 export const prompt = action("prompt")
     .emits()
@@ -50,7 +127,13 @@ export const prompt = action("prompt")
     let query;
     let defaultValue;
     let resolveRaw;
-    if (opts.kind === "choice") {
+    if (opts.kind === "multiline") {
+        defaultValue = opts.default ?? "";
+        message = opts.message ?? "Input:";
+        query = opts.hint ? `${message}\n  ${opts.hint}\n> ` : `${message}\n> `;
+        resolveRaw = (raw) => raw;
+    }
+    else if (opts.kind === "choice") {
         const choices = asChoices(opts.choices);
         const { default: def } = opts;
         const picked = typeof def === "number"
@@ -83,6 +166,7 @@ export const prompt = action("prompt")
     const waitSignal = AbortSignal.any([signal, onTimeout.signal]);
     let value = defaultValue;
     let via = "default";
+    const multiline = opts.kind === "multiline" ? { until: opts.until ?? "json" } : undefined;
     const supervisor = activeSupervisor();
     try {
         // Supervised: hand off to whoever owns the terminal (Ink app / MCP client). Bare: read
@@ -90,7 +174,7 @@ export const prompt = action("prompt")
         // silent supervisor (or nobody) can't wedge the run.
         const outcome = supervisor
             ? await askSupervisor(supervisor, { opts, message, defaultValue, resolveRaw }, waitSignal)
-            : await askTerminal(query, resolveRaw, defaultValue, waitSignal);
+            : await askTerminal(query, resolveRaw, defaultValue, waitSignal, multiline);
         value = outcome.value;
         via = outcome.via;
     }

package/dist/cli/commands/help.js

@@ -13,12 +13,18 @@ export function helpText() {
         "  run [om]     run an om — interactive picker if no om is given, else by name or file path",
         "  ls           list the discovered oms and actions",
         "  check        typecheck the project (tsc --noEmit)",
+        "  skill        generate .claude/skills/omkit-runs/SKILL.md from what this project exposes",
+        "  mcp          serve this project over MCP on stdio (for Claude and other assistants)",
         "  init         scaffold a starter project (tsconfig.omkit.json + sample oms/ and actions/)",
         "  help         show this help",
         "",
         "Flags:",
         "  --tsconfig <path>   project config to scan (default: tsconfig.omkit.json)",
         "  --json              machine-readable output (ls)",
+        "  --describe          import the oms to show their summaries (ls) — slower, runs no workflow",
+        "  --check             report drift and exit non-zero instead of writing (skill)",
+        "  --out <path>        write somewhere else (skill)",
+        "  --root <path>       the project the skill describes, if the tsconfig sits below it (skill)",
         "  --inspect[=port]    run the om in a forked child with the Node inspector open (default port 9229)",
         "  -h, --help          show this help",
         "",

package/dist/cli/commands/init.js

@@ -16,7 +16,7 @@ const TSCONFIG = `{
 const DEV_OM = `import { om } from "omkit";
 import { command, healthcheck } from "omkit/actions";
 
-om("dev", async () => {
+om("dev").run(async () => {
   command("npm run dev", { cwd: "api" }).tag("api");
   const up = await healthcheck({ url: "http://localhost:3000" }).result;
   if (!up.ok) return;

package/dist/cli/commands/ls.d.ts

@@ -1,5 +1,12 @@
-import type { Registry } from "../../client/registry.ts";
+import type { RegistrationSet, Registry } from "../../client/registry.ts";
+export interface FormatOptions {
+    readonly json?: boolean;
+    /**
+     * What the oms and actions declare, from the discovery fork. Present only under
+     * `--describe`: reading it costs an import of every candidate file, which is why plain
+     * `ls` stays AST-only and prints exactly what it always did.
+     */
+    readonly registrations?: RegistrationSet;
+}
 /** Render a {@link Registry} for the terminal (plain text) or as JSON. */
-export declare function formatRegistry(registry: Registry, opts?: {
-    json?: boolean;
-}): string;
+export declare function formatRegistry(registry: Registry, opts?: FormatOptions): string;