omkit 0.8.20 → 0.8.22

package/README.md

@@ -220,19 +220,20 @@ The wrapper is not `===` to the original object, so code that compares it agains
 
 The action `exec` receives an `ActionContext`; the om body receives an `OmContext`.
 
-| Member                        | `ActionContext` | `OmContext` | Purpose                                                                                                                                                          |
-| ----------------------------- | :-------------: | :---------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `signal`                      |        ✓        |      ✓      | `AbortSignal` that fires on cancel or teardown. Honor it to stop early.                                                                                          |
-| `logs`                        |        ✓        |      ✓      | The run's combined log, read-only: `logs.subscribe({ replay? })` is an async iterable of entries.                                                                |
-| `tag(name)`                   |        ✓        |      ✓      | Tag this node.                                                                                                                                                   |
-| `assert(cond, message)`       |        ✓        |      ✓      | Record a pass or fail in the run's verdict. Never throws.                                                                                                        |
-| `snapshot(name, value)`       |        ✓        |      ✓      | Write `value` as JSON into the run folder; resolves the file's path.                                                                                             |
-| `artifact(name, file, opts?)` |        ✓        |      ✓      | Label a file you wrote (optional `description`, MIME inferred). It appears in `result.json` and the report.                                                      |
-| `artifactsFolder`             |        ✓        |      ✓      | Absolute path of the run's output folder. Write artifacts here.                                                                                                  |
-| `emit(event, payload)`        |        ✓        |             | Emit one of the action's declared events.                                                                                                                        |
-| `attach(handle)`              |        ✓        |             | Publish the action's handle and resolve its `.ref`. The first call wins.                                                                                         |
-| `proc(name, opts?)`           |        ✓        |             | Spawn a child process: ``proc("tsc")`tsc -b` `` ([zx](https://github.com/google/zx) syntax). Its output goes to this action's log, and it is killed on teardown. |
-| `cancel()`                    |                 |      ✓      | Tear the whole run down.                                                                                                                                         |
+| Member                        | `ActionContext` | `OmContext` | Purpose                                                                                                                                                                                                    |
+| ----------------------------- | :-------------: | :---------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `signal`                      |        ✓        |      ✓      | `AbortSignal` that fires on cancel or teardown. Honor it to stop early.                                                                                                                                    |
+| `untilAborted()`              |        ✓        |      ✓      | Resolves when `signal` fires: `await ctx.untilAborted(); cleanup()`. Code after the await stays attributed to this node, unlike an `"abort"` listener. Also exported standalone as `untilAborted(signal)`. |
+| `logs`                        |        ✓        |      ✓      | The run's combined log, read-only: `logs.subscribe({ replay? })` is an async iterable of entries.                                                                                                          |
+| `tag(name)`                   |        ✓        |      ✓      | Tag this node.                                                                                                                                                                                             |
+| `assert(cond, message)`       |        ✓        |      ✓      | Record a pass or fail in the run's verdict. Never throws.                                                                                                                                                  |
+| `snapshot(name, value)`       |        ✓        |      ✓      | Write `value` as JSON into the run folder; resolves the file's path.                                                                                                                                       |
+| `artifact(name, file, opts?)` |        ✓        |      ✓      | Label a file you wrote (optional `description`, MIME inferred). It appears in `result.json` and the report.                                                                                                |
+| `artifactsFolder`             |        ✓        |      ✓      | Absolute path of the run's output folder. Write artifacts here.                                                                                                                                            |
+| `emit(event, payload)`        |        ✓        |             | Emit one of the action's declared events.                                                                                                                                                                  |
+| `attach(handle)`              |        ✓        |             | Publish the action's handle and resolve its `.ref`. The first call wins.                                                                                                                                   |
+| `proc(name, opts?)`           |        ✓        |             | Spawn a child process: ``proc("tsc")`tsc -b` `` ([zx](https://github.com/google/zx) syntax). Its output goes to this action's log, and it is killed on teardown.                                           |
+| `cancel()`                    |                 |      ✓      | Tear the whole run down.                                                                                                                                                                                   |
 
 `console.*` inside an action or the om body is captured and attributed to that node's log.
 
@@ -316,8 +317,9 @@ Ready-made actions built on the same engine. For anything else, write your own w
 | `command(cmd, { args?, cwd?, env? })`                                             | Runs a shell command, or an executable when `args` is given, as an action named after it. Output goes to its log; killed on teardown.          | —                                                | Rejects on a non-zero exit.                  |
 | `healthcheck({ url \| host+port+path, status?, body?, intervalMs?, timeoutMs? })` | Polls until the endpoint answers with a matching status (and body).                                                                            | `healthy`                                        | Result `{ url, status, attempts }`.          |
 | `portFree(port, { host?, intervalMs?, timeoutMs? })`                              | Polls until nothing listens on the port, so a restart can rebind.                                                                              | `free`                                           | Result `{ port, host, attempts }`.           |
+| `pollUntil(description, predicate, { intervalMs?, timeoutMs? })`                  | Calls `predicate(signal)` until it returns something other than `false`, `null` or `undefined`. The node is named after `description`.         | —                                                | Result: the predicate's value.               |
 | `untilLog(matcher, { timeoutMs?, replay? })`                                      | Waits for the first run-log entry matching `matcher(entry)`.                                                                                   | `match`                                          | The matching entry.                          |
-| `tailLog(file, { fromStart?, encoding? })`                                        | Tails a file another process writes and folds its lines into the run log.                                                                      | —                                                | —                                            |
+| `tailLog(file, { fromStart?, encoding?, debounceMs?, pollMs?, diagnostics? })`    | Tails a file another process writes and folds its lines into the run log.                                                                      | —                                                | —                                            |
 | `watch(file, { onCreate?, onUpdate?, onDelete?, onMissing? })`                    | Watches one file and survives it being deleted and recreated.                                                                                  | —                                                | —                                            |
 | `watchDir(dir, { debounceMs? })`                                                  | Watches a directory tree and survives it being wiped and recreated.                                                                            | `ready`, `create`, `update`, `delete`, `removed` | —                                            |
 | `prompt({ kind?, message, choices?, default?, timeoutMs?, until? })`              | Asks in the terminal (or the picker, or the MCP client). `kind` is `"input"`, `"choice"` or `"multiline"`. Falls back to `default` on timeout. | —                                                | Result: the answer.                          |

package/dist/actions/index.d.ts

@@ -6,6 +6,8 @@ export { command } from "./command.ts";
 export type { CommandOptions } from "./command.ts";
 export { untilLog } from "./until-log.ts";
 export type { LogMatcher, UntilLogOptions, UntilLogEvents } from "./until-log.ts";
+export { pollUntil } from "./poll-until.ts";
+export type { PollUntilOptions, PollValue } from "./poll-until.ts";
 export { healthcheck } from "./healthcheck.ts";
 export type { HealthcheckOptions, HealthcheckResult, HealthcheckEvents, StatusMatcher, BodyMatcher, } from "./healthcheck.ts";
 export { portFree } from "./port-free.ts";

package/dist/actions/index.js

@@ -4,6 +4,7 @@
  */
 export { command } from "./command.js";
 export { untilLog } from "./until-log.js";
+export { pollUntil } from "./poll-until.js";
 export { healthcheck } from "./healthcheck.js";
 export { portFree } from "./port-free.js";
 export { watch } from "./watch.js";

package/dist/actions/poll-until.d.ts

@@ -0,0 +1,16 @@
+/** What a {@link pollUntil} predicate returns: `false`, `null` or `undefined` mean "not yet". */
+export type PollValue<T> = T | false | null | undefined;
+export interface PollUntilOptions {
+    /** Delay between checks. Default 200ms. */
+    intervalMs?: number;
+    /** Reject after this long overall. Default 30000ms; pass `Infinity` to wait until teardown. */
+    timeoutMs?: number;
+}
+/**
+ * Gate: calls `predicate` every `intervalMs` until it returns something other than `false`,
+ * `null` or `undefined`, and resolves with that value — so it can find a thing as well as wait
+ * for one. The node is named after `description` (like `command`), which also heads the
+ * timeout error. The predicate gets this node's abort signal to cancel its own work (a
+ * `fetch`, say); a predicate that throws fails the gate rather than being retried.
+ */
+export declare function pollUntil<T>(description: string, predicate: (signal: AbortSignal) => PollValue<T> | Promise<PollValue<T>>, options?: PollUntilOptions): import("../index.ts").Activity<T, import("../core/types.ts").NoEvents, void>;

package/dist/actions/poll-until.js

@@ -0,0 +1,30 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { action } from "../core/action.js";
+/**
+ * Gate: calls `predicate` every `intervalMs` until it returns something other than `false`,
+ * `null` or `undefined`, and resolves with that value — so it can find a thing as well as wait
+ * for one. The node is named after `description` (like `command`), which also heads the
+ * timeout error. The predicate gets this node's abort signal to cancel its own work (a
+ * `fetch`, say); a predicate that throws fails the gate rather than being retried.
+ */
+export function pollUntil(description, predicate, options = {}) {
+    const { intervalMs = 200, timeoutMs = 30_000 } = options;
+    return action(description).run(async ({ signal }) => {
+        const deadline = Date.now() + timeoutMs;
+        let attempts = 0;
+        for (;;) {
+            signal.throwIfAborted();
+            attempts++;
+            const value = await predicate(signal);
+            if (value !== false && value !== null && value !== undefined) {
+                console.log(`met after ${attempts} ${attempts === 1 ? "check" : "checks"}`);
+                return value;
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                throw new Error(`${description}: not met within ${timeoutMs}ms (${attempts} checks)`);
+            }
+            await sleep(Math.min(intervalMs, remaining), undefined, { signal });
+        }
+    })();
+}

package/dist/actions/tail-log.d.ts

@@ -5,6 +5,18 @@ export interface TailLogOptions {
     encoding?: BufferEncoding;
     /** Coalesce rapid writes within this window. Default 50ms. */
     debounceMs?: number;
+    /**
+     * Also re-check the file's size this often (ms), independent of watch events; 0 disables.
+     * Needed on Windows, where appends through a handle another process keeps open often raise
+     * no directory notification until that handle closes. Default 500ms.
+     */
+    pollMs?: number;
+    /**
+     * Log `[diag]` lines (watch events, filter decisions, pump/read activity, sizes and
+     * offsets — never file contents) into this action's log. Default: on when
+     * `OMKIT_DEBUG` is set.
+     */
+    diagnostics?: boolean;
 }
 /**
  * Tails a (possibly not-yet-existing) text file and streams each appended line

package/dist/actions/tail-log.js

@@ -1,3 +1,4 @@
+import { AsyncResource } from "node:async_hooks";
 import { watch as fsWatch } from "node:fs";
 import { open, stat } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
@@ -14,7 +15,8 @@ export const tailLog = action("tailLog").run(async ({ signal }, target, opts = {
     const file = resolve(target);
     const dir = dirname(file);
     const name = basename(file);
-    const { fromStart = false, encoding = "utf8", debounceMs = 50 } = opts;
+    const { fromStart = false, encoding = "utf8", debounceMs = 50, pollMs = 500, diagnostics = Boolean(process.env.OMKIT_DEBUG), } = opts;
+    const diag = diagnostics ? (msg) => console.log(`[diag] ${msg}`) : undefined;
     let pos = 0; // bytes consumed so far
     let pending = ""; // partial trailing line, buffered until its newline
     let decoder = new StringDecoder(encoding);
@@ -33,11 +35,15 @@ export const tailLog = action("tailLog").run(async ({ signal }, target, opts = {
         try {
             size = (await stat(file)).size;
         }
-        catch {
+        catch (err) {
+            diag?.(`stat failed: ${err.code ?? err}`);
             return; // missing/unreadable — wait for the next event
         }
+        if (size !== pos)
+            diag?.(`read size=${size} pos=${pos}`); // quiet on idle poll ticks
         if (size < pos) {
             // Truncation/rotation: restart from the top, drop stale buffers.
+            diag?.(`truncated ${pos} -> ${size}, restarting from 0`);
             pos = 0;
             pending = "";
             decoder = new StringDecoder(encoding);
@@ -54,6 +60,7 @@ export const tailLog = action("tailLog").run(async ({ signal }, target, opts = {
                 if (bytesRead === 0)
                     break;
                 pos += bytesRead;
+                diag?.(`read bytes=${bytesRead} pos=${pos}`);
                 feed(decoder.write(buffer.subarray(0, bytesRead)));
             }
         }
@@ -64,9 +71,13 @@ export const tailLog = action("tailLog").run(async ({ signal }, target, opts = {
     // Serialize reads; coalesce extra triggers into a single follow-up pass.
     let reading = false;
     let again = false;
+    let stopped = false;
     const pump = () => {
+        if (stopped)
+            return;
         if (reading) {
             again = true;
+            diag?.("pump: read in flight, queued follow-up");
             return;
         }
         reading = true;
@@ -77,6 +88,10 @@ export const tailLog = action("tailLog").run(async ({ signal }, target, opts = {
                     await readDelta();
                 } while (again);
             }
+            catch (err) {
+                diag?.(`read failed: ${err.code ?? err}`);
+                throw err;
+            }
             finally {
                 reading = false;
             }
@@ -86,7 +101,11 @@ export const tailLog = action("tailLog").run(async ({ signal }, target, opts = {
     const schedule = () => {
         if (timer)
             clearTimeout(timer);
-        timer = setTimeout(pump, debounceMs);
+        diag?.(`schedule pump in ${debounceMs}ms${timer ? " (reset pending timer)" : ""}`);
+        timer = setTimeout(() => {
+            timer = undefined;
+            pump();
+        }, debounceMs);
     };
     try {
         pos = fromStart ? 0 : (await stat(file)).size;
@@ -95,22 +114,42 @@ export const tailLog = action("tailLog").run(async ({ signal }, target, opts = {
         pos = 0;
     }
     console.log(`tailing ${file}${fromStart ? " (from start)" : ""}`);
+    diag?.(`watching dir=${dir} name=${name} startPos=${pos}`);
     if (fromStart)
         pump();
-    const watcher = fsWatch(dir, (_event, filename) => {
-        if (filename === null || filename === name)
+    // Fallback for missed notifications. Goes through the serialized pump and reads are
+    // offset-based, so a tick racing a watch-triggered read can't overlap or duplicate it.
+    const poll = pollMs > 0 ? setInterval(pump, pollMs) : undefined;
+    const watcher = fsWatch(dir, (event, filename) => {
+        const accepted = filename === null || filename === name;
+        diag?.(`watch ${event} filename=${filename} ${accepted ? "accepted" : "ignored"}`);
+        if (accepted)
             schedule();
     });
+    if (diag) {
+        // Observe only: rethrow so a watcher error stays as loud as it is without a listener.
+        watcher.on("error", (err) => {
+            diag(`watcher error: ${err.message}`);
+            throw err;
+        });
+    }
     return new Promise((resolveRun) => {
-        const stop = () => {
+        // Bound to this action's async context: the abort listener otherwise runs in the
+        // canceller's, and the flushed partial line would be attributed to that node instead.
+        const stop = AsyncResource.bind(() => {
+            diag?.(`stop: aborted, pos=${pos} pendingChars=${pending.length}`);
+            stopped = true;
             if (timer)
                 clearTimeout(timer);
+            if (poll)
+                clearInterval(poll);
             watcher.close();
             const tail = pending.replace(/\r$/, "");
+            pending = "";
             if (tail)
                 console.log(tail);
             resolveRun();
-        };
+        });
         if (signal.aborted)
             stop();
         else

package/dist/core/ActionRun.js

@@ -1,6 +1,7 @@
 import { defer } from "../foundation/Deferred.js";
 import { events } from "../foundation/events.js";
 import { CancelledError } from "../foundation/CancelledError.js";
+import { untilAborted } from "../foundation/untilAborted.js";
 import { renderValue } from "../foundation/format.js";
 import { callerSite } from "../foundation/callsite.js";
 import { currentNode } from "./context.js";
@@ -279,6 +280,7 @@ export class ActionRun {
     context() {
         return {
             signal: this.signal,
+            untilAborted: () => untilAborted(this.signal),
             logs: this.store,
             emit: ((key, payload) => {
                 this.emitter.emit(key, payload);

package/dist/core/om.js

@@ -42,6 +42,7 @@ function launch(name, site, description, exposure, body, schema) {
         tree.root.meta = { describeArgs: () => describeSchema(schema) };
     const rootBody = (ctx) => body({
         signal: ctx.signal,
+        untilAborted: ctx.untilAborted,
         logs: ctx.logs,
         tag: ctx.tag,
         cancel: () => tree.cancel(),

package/dist/core/types.d.ts

@@ -28,6 +28,11 @@ export type InstanceEvents<Events extends object, Result> = Events & SystemEvent
 export interface ActionContext<Events extends object = NoEvents, Handle = void> {
     /** This node's abort signal — honor it to stop early. */
     readonly signal: AbortSignal;
+    /**
+     * Resolves once `signal` aborts — the daemon idiom `await ctx.untilAborted(); cleanup()`.
+     * Code after the await stays attributed to this node (an `"abort"` listener would not).
+     */
+    readonly untilAborted: () => Promise<void>;
     /** The combined run log, read-only (subscribe/observe; never append). */
     readonly logs: ReadableLog;
     /** Emit one of this action's declared events (also logged onto the timeline). */
@@ -121,6 +126,11 @@ export interface OmBuilderArgs<S extends ZodTypeLike> {
 export interface OmContext {
     /** The run's (root) abort signal. */
     readonly signal: AbortSignal;
+    /**
+     * Resolves once `signal` aborts — the daemon idiom `await ctx.untilAborted(); cleanup()`.
+     * Code after the await stays attributed to this node (an `"abort"` listener would not).
+     */
+    readonly untilAborted: () => Promise<void>;
     /** Tag the root run. */
     readonly tag: (name: string) => void;
     /** Tear the whole run down. */

package/dist/foundation/untilAborted.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolves once `signal` aborts (immediately if it already has). Never rejects. Unlike a raw
+ * `"abort"` listener, code after `await untilAborted(signal)` resumes in the *awaiting* async
+ * context, so its `console.*` output stays attributed to the node that waited — a listener
+ * runs in the canceller's context instead.
+ */
+export declare function untilAborted(signal: AbortSignal): Promise<void>;

package/dist/foundation/untilAborted.js

@@ -0,0 +1,14 @@
+/**
+ * Resolves once `signal` aborts (immediately if it already has). Never rejects. Unlike a raw
+ * `"abort"` listener, code after `await untilAborted(signal)` resumes in the *awaiting* async
+ * context, so its `console.*` output stays attributed to the node that waited — a listener
+ * runs in the canceller's context instead.
+ */
+export function untilAborted(signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            resolve();
+        else
+            signal.addEventListener("abort", () => resolve(), { once: true });
+    });
+}

package/dist/index.d.ts

@@ -11,4 +11,5 @@ export { om } from "./core/om.ts";
 export { action } from "./core/action.ts";
 export { step } from "./core/step.ts";
 export { CancelledError, isCancelled } from "./foundation/CancelledError.ts";
+export { untilAborted } from "./foundation/untilAborted.ts";
 export type { Action, Activity, ActionContext, OmBuilder, OmBuilderArgs, OmContext, OmDescription, } from "./core/types.ts";

package/dist/index.js

@@ -11,3 +11,4 @@ export { om } from "./core/om.js";
 export { action } from "./core/action.js";
 export { step } from "./core/step.js";
 export { CancelledError, isCancelled } from "./foundation/CancelledError.js";
+export { untilAborted } from "./foundation/untilAborted.js";