omkit 0.4.7 → 0.4.8

package/README.md

@@ -33,7 +33,7 @@ om("dev", async () => {
 
   // …then launch a real browser and hand its live page downstream — typed, not scraped.
   const chrome = browser({ headless: false }); // a visible Chromium, closed on teardown
-  const page = chromePage("app", chrome.ref, { url: "http://localhost:3000" });
+  const page = chromePage("app", await chrome.ref, { url: "http://localhost:3000" });
   console.log(`opened ${(await page.ref).url()}`);
 
   console.log("stack is up — press Ctrl+C to stop");
@@ -223,6 +223,7 @@ Reusable actions built on the core engine. For anything beyond these, drop down
 - **`untilLog`** — gate on the first log entry matching a predicate.
 - **`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.
+- **`portFree`** — the mirror of `healthcheck`: poll a TCP port until nothing is listening, so a restart can rebind without racing the old process.
 - **`prompt`** — ask the terminal for input or a choice, with a timeout that falls back to a default; the answer is its handle.
 - **`browser`** — launch a Chromium browser with Playwright and expose the live `Browser` as a handle (defaults to the installed Chrome); closed on teardown. Feed its `.ref` to `chromePage`.
 - **`chromePage`** — attach to Chrome over CDP, or to an existing Playwright `Page`/`Browser`/`Context` (including a `browser` handle or an Electron window), and expose the live `Page` as a handle.

package/dist/actions/browser.d.ts

@@ -17,7 +17,7 @@ export interface BrowserOptions {
 }
 /**
  * Launches a Chromium browser with Playwright and publishes the live {@link Browser}
- * as this action's handle, so a driver — e.g. `chromePage("Explorer", browser.ref,
+ * as this action's handle, so a driver — e.g. `chromePage("Explorer", await browser.ref,
  * { url })` — can await `instance.ref` and open pages in it. This owns the browser it
  * launches (unlike a CDP endpoint handed to `chromePage`, which belongs to its opener),
  * so teardown closes it. Replaces the external chromedriver/WebDriver dance.

package/dist/actions/browser.js

@@ -3,7 +3,7 @@ import { action } from "../core/action.js";
 const delay = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * Launches a Chromium browser with Playwright and publishes the live {@link Browser}
- * as this action's handle, so a driver — e.g. `chromePage("Explorer", browser.ref,
+ * as this action's handle, so a driver — e.g. `chromePage("Explorer", await browser.ref,
  * { url })` — can await `instance.ref` and open pages in it. This owns the browser it
  * launches (unlike a CDP endpoint handed to `chromePage`, which belongs to its opener),
  * so teardown closes it. Replaces the external chromedriver/WebDriver dance.

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

@@ -22,10 +22,11 @@ export interface ChromePageOptions {
 }
 /**
  * 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.
  */
-export declare const chromePage: import("../index.ts").Action<[label: string, source: ChromePageSource | Promise<ChromePageSource>, opts?: ChromePageOptions | undefined], void, ChromePageEvents, Page>;
+export declare const chromePage: import("../index.ts").Action<[label: string, source: ChromePageSource, opts?: ChromePageOptions | undefined], void, ChromePageEvents, Page>;

package/dist/actions/chrome-page.js

@@ -7,9 +7,10 @@ const isBrowser = (x) => typeof x.contexts === "function";
 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 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,13 +20,12 @@ 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}`;
+    if (typeof source === "string") {
+        const cdpUrl = source.includes("://") ? source : `http://${source}`;
         from = cdpUrl;
         try {
             owned = await chromium.connectOverCDP(cdpUrl);
@@ -36,18 +36,18 @@ export const chromePage = action("chromePage")
         const context = owned.contexts()[0] ?? (await owned.newContext());
         page = await pageOf(context, url !== undefined);
     }
-    else if (isPage(resolved)) {
+    else if (isPage(source)) {
         from = "page handle";
-        page = resolved;
+        page = source;
     }
-    else if (isBrowser(resolved)) {
+    else if (isBrowser(source)) {
         from = "browser handle";
-        const context = resolved.contexts()[0] ?? (await resolved.newContext());
+        const context = source.contexts()[0] ?? (await source.newContext());
         page = await pageOf(context, url !== undefined);
     }
     else {
         from = "context handle";
-        page = await pageOf(resolved, url !== undefined);
+        page = await pageOf(source, url !== undefined);
     }
     page.on("console", (msg) => {
         console.log(`console: ${msg.text()}`);

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";

package/dist/actions/index.js

@@ -5,6 +5,7 @@
 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";

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

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",