omkit 0.0.15 → 0.1.0

package/dist/actions/healthcheck.js

@@ -1,19 +1,14 @@
-import { action } from "../orchestration/action/action.js";
+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
+ * optionally, body), then resolves with that probe and emits `healthy`. Refusals
+ * and slow probes during startup are retried; each request is bounded by
+ * `requestTimeoutMs` and the whole wait by the run's abort signal and optional
  * `timeoutMs`, so teardown unblocks a pending probe instead of hanging.
  */
-export const healthcheck = action("Healthcheck")
+export const healthcheck = action("healthcheck")
     .emits()
-    .run(async ({ logs, signal, emit }, opts = {}) => {
+    .run(async ({ 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)
@@ -46,7 +41,7 @@ export const healthcheck = action("Healthcheck")
             signal.addEventListener("abort", onAbort, { once: true });
     });
     const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
-    logs.append({ source: "Healthcheck", level: "info", message: `probing ${url}` });
+    console.log(`probing ${url}`);
     let attempts = 0;
     for (;;) {
         if (signal.aborted)
@@ -55,23 +50,16 @@ export const healthcheck = action("Healthcheck")
         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})`,
-                    });
+                    console.log(`healthy ${url} → ${res.status} (${probes})`);
                     emit("healthy", result);
                     return result;
                 }
@@ -81,8 +69,6 @@ export const healthcheck = action("Healthcheck")
             }
         }
         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");
         }

package/dist/actions/index.d.ts

@@ -1,22 +1,20 @@
 /**
- * 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`.
+ * omkit/actions — reusable actions built on the core engine. For anything beyond
+ * these, drop down to `action(...).run(...)`.
  */
 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 { healthcheck } from "./healthcheck.ts";
+export type { HealthcheckOptions, HealthcheckResult, HealthcheckEvents, StatusMatcher, BodyMatcher, } from "./healthcheck.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

@@ -1,14 +1,12 @@
 /**
- * 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`.
+ * omkit/actions — reusable actions built on the core engine. For anything beyond
+ * these, drop down to `action(...).run(...)`.
  */
 export { command } from "./command.js";
+export { untilLog } from "./until-log.js";
+export { healthcheck } from "./healthcheck.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

@@ -6,11 +6,7 @@ export type PromptChoice = 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.
-     */
+    /** Use the default and stop waiting after this many ms (≤0/non-finite = forever). Default 30000. */
     timeoutMs?: number;
 }
 export interface InputPromptOptions extends PromptCommon {
@@ -20,7 +16,6 @@ export interface InputPromptOptions extends PromptCommon {
 }
 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;
@@ -29,26 +24,17 @@ 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).
+ * 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.
  */
 export declare const prompt: import("../index.ts").Action<[opts?: PromptOptions | undefined], string, PromptEvents, string>;
 export {};

package/dist/actions/prompt.js

@@ -1,27 +1,18 @@
 import { createInterface } from "node:readline/promises";
-import { action } from "../orchestration/action/action.js";
-/** Normalize choices to `{ label, value }`. */
+import { action } from "../core/action.js";
 const asChoices = (choices) => choices.map((c) => (typeof c === "string" ? { label: c, value: c } : c));
 /**
- * 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).
+ * 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.
  */
-export const prompt = action("Prompt")
+export const prompt = action("prompt")
     .emits()
     .ref()
-    .run(async ({ logs, signal, emit, attach }, opts = {}) => {
+    .run(async ({ signal, emit, attach }, opts = {}) => {
     const timeoutMs = opts.timeoutMs ?? 30_000;
     const finite = Number.isFinite(timeoutMs) && timeoutMs > 0;
-    // Build the question, the fallback value, and a resolver from raw input.
     let message;
     let query;
     let defaultValue;
@@ -40,7 +31,6 @@ export const prompt = action("Prompt")
             .map((c, i) => `  ${i + 1}) ${c.label}${c.value === defaultValue ? " (default)" : ""}`)
             .join("\n");
         query = `${message}\n${list}\n> `;
-        // Accept a 1-based index, an exact value, or an exact label.
         resolveRaw = (raw) => {
             const n = Number(raw);
             if (Number.isInteger(n) && n >= 1 && n <= choices.length)
@@ -52,11 +42,9 @@ export const prompt = action("Prompt")
         defaultValue = opts.default ?? "";
         message = opts.message ?? "Input:";
         query = defaultValue ? `${message} (${defaultValue}) ` : `${message} `;
-        resolveRaw = (raw) => raw; // any non-empty input is the value
+        resolveRaw = (raw) => raw;
     }
     emit("prompt", message);
-    // A dedicated controller for the timeout, so it's distinguishable from a
-    // teardown abort; either one cancels the pending question.
     const onTimeout = new AbortController();
     const timer = finite ? setTimeout(() => onTimeout.abort(), timeoutMs) : undefined;
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -74,17 +62,12 @@ export const prompt = action("Prompt")
                 via = "input";
             }
             else {
-                logs.append({
-                    source: "Prompt",
-                    level: "info",
-                    message: `invalid answer "${raw}", using default`,
-                });
+                console.log(`invalid answer "${raw}", using default`);
                 via = "default";
             }
         }
     }
     catch {
-        // Aborted before an answer: the timeout (use default + note it) or teardown.
         via = onTimeout.signal.aborted ? "timeout" : "default";
     }
     finally {
@@ -92,11 +75,7 @@ export const prompt = action("Prompt")
             clearTimeout(timer);
         rl.close();
     }
-    logs.append({
-        source: "Prompt",
-        level: "info",
-        message: via === "timeout" ? `timed out → ${value}` : `${value} (${via})`,
-    });
+    console.log(via === "timeout" ? `timed out → ${value}` : `${value} (${via})`);
     attach(value); // resolves instance.ref → the answer
     emit("answer", { value, via });
     return value;

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

@@ -1,12 +1,5 @@
 export interface TailLogOptions {
-    /** Label the lines are logged under. Default: the file's basename. */
-    source?: string;
-    /** Level for appended lines. Default "info". */
-    level?: string;
-    /**
-     * Replay the file's existing content first. Default false — start at the
-     * current end and only stream what's appended from now on (like `tail -f`).
-     */
+    /** Replay the file's existing content first. Default false (start at the end). */
     fromStart?: boolean;
     /** Text encoding of the file. Default "utf8". */
     encoding?: BufferEncoding;
@@ -14,17 +7,10 @@ export interface TailLogOptions {
     debounceMs?: number;
 }
 /**
- * Tails a (possibly not-yet-existing) text/log file and streams each appended
- * line into the run's combined log — the way `proc` streams a child's stdout, but
- * for a file some *other* process writes. Useful for folding an external tool's
- * own log file into the one timeline.
- *
- * It tracks a byte offset and reads only the delta on each change, buffering a
- * partial trailing line until its newline arrives (so a line split across two
- * writes is logged once, whole). A shrink in size is treated as truncation or
- * rotation — the offset resets to 0 and reading resumes from the top. Since
- * `fs.watch` can't watch a missing path, it watches the parent directory and
- * filters by name, like {@link import("./watch.ts").watch}. Runs until the run's
- * signal aborts, then closes the watcher (flushing any trailing partial line).
+ * Tails a (possibly not-yet-existing) text file and streams each appended line
+ * into the run's log — like `proc` streams a child's stdout, but for a file some
+ * *other* process writes. Tracks a byte offset and reads only the delta, buffering
+ * a partial trailing line until its newline; a shrink is treated as truncation
+ * (offset resets). Daemon: runs until torn down, then flushes any partial line.
  */
-export declare const tailLog: import("../index.ts").Action<[target: string, opts?: TailLogOptions | undefined], void, import("../index.ts").NoEvents, void>;
+export declare const tailLog: import("../index.ts").Action<[target: string, opts?: TailLogOptions | undefined], void, import("../core/types.ts").NoEvents, void>;

package/dist/actions/tail-log.js

@@ -2,33 +2,22 @@ import { watch as fsWatch } from "node:fs";
 import { open, stat } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
 import { StringDecoder } from "node:string_decoder";
-import { action } from "../orchestration/action/action.js";
+import { action } from "../core/action.js";
 /**
- * Tails a (possibly not-yet-existing) text/log file and streams each appended
- * line into the run's combined log — the way `proc` streams a child's stdout, but
- * for a file some *other* process writes. Useful for folding an external tool's
- * own log file into the one timeline.
- *
- * It tracks a byte offset and reads only the delta on each change, buffering a
- * partial trailing line until its newline arrives (so a line split across two
- * writes is logged once, whole). A shrink in size is treated as truncation or
- * rotation — the offset resets to 0 and reading resumes from the top. Since
- * `fs.watch` can't watch a missing path, it watches the parent directory and
- * filters by name, like {@link import("./watch.ts").watch}. Runs until the run's
- * signal aborts, then closes the watcher (flushing any trailing partial line).
+ * Tails a (possibly not-yet-existing) text file and streams each appended line
+ * into the run's log — like `proc` streams a child's stdout, but for a file some
+ * *other* process writes. Tracks a byte offset and reads only the delta, buffering
+ * a partial trailing line until its newline; a shrink is treated as truncation
+ * (offset resets). Daemon: runs until torn down, then flushes any partial line.
  */
-export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, opts = {}) => {
+export const tailLog = action("tailLog").run(async ({ signal }, target, opts = {}) => {
     const file = resolve(target);
     const dir = dirname(file);
     const name = basename(file);
-    const { source = name, level = "info", fromStart = false, encoding = "utf8", debounceMs = 50, } = opts;
+    const { fromStart = false, encoding = "utf8", debounceMs = 50 } = opts;
     let pos = 0; // bytes consumed so far
     let pending = ""; // partial trailing line, buffered until its newline
-    // Decodes bytes to text across reads. It holds back an incomplete trailing
-    // multi-byte char (split across a chunk or read boundary) until its remaining
-    // bytes arrive, so a character straddling a boundary never decodes to `�`.
     let decoder = new StringDecoder(encoding);
-    // Append every complete line in `text`, keeping any remainder for next time.
     const feed = (text) => {
         pending += text;
         let newline;
@@ -36,7 +25,7 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
             const line = pending.slice(0, newline).replace(/\r$/, "");
             pending = pending.slice(newline + 1);
             if (line)
-                logs.append({ source, level, message: line });
+                console.log(line);
         }
     };
     const readDelta = async () => {
@@ -48,8 +37,7 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
             return; // missing/unreadable — wait for the next event
         }
         if (size < pos) {
-            // Truncation/rotation: restart from the top and drop any buffered partial
-            // line and half-decoded char — they belong to the old file's bytes.
+            // Truncation/rotation: restart from the top, drop stale buffers.
             pos = 0;
             pending = "";
             decoder = new StringDecoder(encoding);
@@ -66,8 +54,6 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
                 if (bytesRead === 0)
                     break;
                 pos += bytesRead;
-                // decoder.write returns only fully-decoded chars, buffering any partial
-                // trailing multi-byte char for the next chunk/read.
                 feed(decoder.write(buffer.subarray(0, bytesRead)));
             }
         }
@@ -75,8 +61,7 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
             await handle.close();
         }
     };
-    // Serialize reads so a burst of events can't overlap; coalesce extra triggers
-    // into a single follow-up pass.
+    // Serialize reads; coalesce extra triggers into a single follow-up pass.
     let reading = false;
     let again = false;
     const pump = () => {
@@ -103,25 +88,19 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
             clearTimeout(timer);
         timer = setTimeout(pump, debounceMs);
     };
-    // Seed the offset: from the top when replaying, otherwise from the current end
-    // so existing content is skipped. A missing file starts at 0 — its content
-    // counts as "appended" once it appears.
     try {
         pos = fromStart ? 0 : (await stat(file)).size;
     }
     catch {
         pos = 0;
     }
-    // Announce the target up front so the combined log shows which file these
-    // lines come from — the resolved absolute path, plus whether we're replaying.
-    logs.append({ source, level, message: `tailing ${file}${fromStart ? " (from start)" : ""}` });
+    console.log(`tailing ${file}${fromStart ? " (from start)" : ""}`);
     if (fromStart)
         pump();
     const watcher = fsWatch(dir, (_event, filename) => {
         if (filename === null || filename === name)
             schedule();
     });
-    // Daemon: stay alive until torn down, then stop and flush any partial line.
     return new Promise((resolveRun) => {
         const stop = () => {
             if (timer)
@@ -129,7 +108,7 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
             watcher.close();
             const tail = pending.replace(/\r$/, "");
             if (tail)
-                logs.append({ source, level, message: tail });
+                console.log(tail);
             resolveRun();
         };
         if (signal.aborted)

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

@@ -1,13 +1,10 @@
-import type { LogEntry } from "../output/log/LogsCollector.ts";
+import type { LogEntry } from "../foundation/LogEntry.ts";
 /** Predicate over a log entry — return `true` for the entry to wait for. */
 export type LogMatcher = (entry: LogEntry) => boolean;
 export interface UntilLogOptions {
-    /**
-     * Reject if no entry matches within this many milliseconds. Omit to wait
-     * indefinitely (the caller is then responsible for guaranteeing a match).
-     */
+    /** Reject if no entry matches within this many ms. Omit to wait indefinitely. */
     timeoutMs?: number;
-    /** Replay the buffered history before live entries (catch already-logged matches). */
+    /** Replay buffered history before live entries (catch already-logged matches). */
     replay?: boolean;
 }
 /** Events emitted by {@link untilLog}. */
@@ -17,7 +14,7 @@ export interface UntilLogEvents {
 }
 /**
  * Gate: resolves with the first log entry the `matcher` accepts (and emits
- * `match`). Subscribes to the injected collector and races each read against the
+ * `match`). Subscribes to the readable run log and races each read against the
  * run's abort signal (and an optional timeout), so teardown unblocks a pending
  * wait instead of hanging.
  */

package/dist/actions/until-log.js

@@ -1,11 +1,11 @@
-import { action } from "../orchestration/action/action.js";
+import { action } from "../core/action.js";
 /**
  * Gate: resolves with the first log entry the `matcher` accepts (and emits
- * `match`). Subscribes to the injected collector and races each read against the
+ * `match`). Subscribes to the readable run log and races each read against the
  * run's abort signal (and an optional timeout), so teardown unblocks a pending
  * wait instead of hanging.
  */
-export const untilLog = action("Until Log")
+export const untilLog = action("untilLog")
     .emits()
     .run(({ logs, signal, emit }, matcher, { timeoutMs, replay = false } = {}) => {
     const iterator = logs.subscribe({ replay })[Symbol.asyncIterator]();

package/dist/actions/watch-dir.d.ts

@@ -2,16 +2,10 @@ export interface WatchDirOptions {
     /** Coalesce rapid events within this window. Default 50ms. */
     debounceMs?: number;
 }
-/**
- * Events emitted by {@link watchDir}. Each payload is the absolute path of the
- * entry — a file for create/update/delete, the folder itself for ready/removed.
- */
+/** Events emitted by {@link watchDir}. Each payload is the absolute path of the entry. */
 export interface WatchDirEvents {
-    /** A file appeared during the run. */
     create: string;
-    /** A file's contents changed (its mtime moved). */
     update: string;
-    /** A file was removed. */
     delete: string;
     /** The folder appeared (or existed at startup); fires again on recreation. */
     ready: string;
@@ -19,17 +13,9 @@ export interface WatchDirEvents {
     removed: string;
 }
 /**
- * Watches a directory and emits per-file events on changes, surviving the folder
- * being deleted and recreated (e.g. a build that `rm -rf`s it first).
- *
- * It watches the existing ancestor chain (target recursively, ancestors
- * non-recursively) so a stable ancestor keeps firing when the target reappears.
- * Per-file changes are derived by re-`stat`ing and diffing mtimes.
- *
- * The folder's own removal/recreation can't be seen by stat: a wipe+recreate is
- * atomic (never observed absent), and on NTFS the recreated dir even keeps the
- * old `ino`/`birthtime` (tunneling). So that's detected from the raw `rename`
- * event the *parent* fires for the target's name — when it does and the target
- * still exists, it was replaced (`removed` + `ready`).
+ * Watches a directory and emits per-file events, surviving the folder being
+ * deleted and recreated (e.g. a build that `rm -rf`s it first). Watches the
+ * existing ancestor chain so a stable ancestor keeps firing when the target
+ * reappears; per-file changes are derived by re-`stat`ing and diffing mtimes.
  */
 export declare const watchDir: import("../index.ts").Action<[target: string, opts?: WatchDirOptions | undefined], void, WatchDirEvents, void>;

package/dist/actions/watch-dir.js

@@ -1,22 +1,14 @@
 import { existsSync, watch as fsWatch } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
-import { action } from "../orchestration/action/action.js";
+import { action } from "../core/action.js";
 /**
- * Watches a directory and emits per-file events on changes, surviving the folder
- * being deleted and recreated (e.g. a build that `rm -rf`s it first).
- *
- * It watches the existing ancestor chain (target recursively, ancestors
- * non-recursively) so a stable ancestor keeps firing when the target reappears.
- * Per-file changes are derived by re-`stat`ing and diffing mtimes.
- *
- * The folder's own removal/recreation can't be seen by stat: a wipe+recreate is
- * atomic (never observed absent), and on NTFS the recreated dir even keeps the
- * old `ino`/`birthtime` (tunneling). So that's detected from the raw `rename`
- * event the *parent* fires for the target's name — when it does and the target
- * still exists, it was replaced (`removed` + `ready`).
+ * Watches a directory and emits per-file events, surviving the folder being
+ * deleted and recreated (e.g. a build that `rm -rf`s it first). Watches the
+ * existing ancestor chain so a stable ancestor keeps firing when the target
+ * reappears; per-file changes are derived by re-`stat`ing and diffing mtimes.
  */
-export const watchDir = action("Watch Dir")
+export const watchDir = action("watchDir")
     .emits()
     .run(({ signal, emit }, target, opts = {}) => {
     const { debounceMs = 50 } = opts;
@@ -24,8 +16,8 @@ export const watchDir = action("Watch Dir")
     const targetName = basename(root);
     const targetParent = dirname(root);
     let seen = new Map(); // abs path -> mtimeMs
-    let rootPresent = false; // believed existence of the folder itself
-    let churned = false; // the parent reported a rename for the target since last tick
+    let rootPresent = false;
+    let churned = false;
     const scan = async () => {
         const next = new Map();
         let entries;
@@ -50,8 +42,6 @@ export const watchDir = action("Watch Dir")
     };
     const recheck = async (isInitial) => {
         const next = await scan();
-        // Startup seeds the snapshot silently — so onCreate means "created during
-        // this run", not "already there when we started" (last run's leftovers).
         if (!isInitial) {
             for (const [path, mtime] of next) {
                 const prev = seen.get(path);
@@ -67,8 +57,6 @@ export const watchDir = action("Watch Dir")
         }
         seen = next;
     };
-    // Derive the folder's own create/remove/recreate from existence + the churn
-    // signal (a parent `rename` for the target's name).
     const detectDir = (isInitial, didChurn) => {
         const present = existsSync(root);
         if (isInitial) {
@@ -79,9 +67,9 @@ export const watchDir = action("Watch Dir")
         }
         if (didChurn) {
             if (rootPresent)
-                emit("removed", root); // replaced or removed
+                emit("removed", root);
             if (present)
-                emit("ready", root); // created or recreated
+                emit("ready", root);
         }
         else if (present !== rootPresent) {
             emit(present ? "ready" : "removed", root);
@@ -101,8 +89,6 @@ export const watchDir = action("Watch Dir")
     const watchers = [];
     let armed = [];
     const onEvent = (dir) => (eventType, filename) => {
-        // A rename of the target's own name, seen from its parent = the folder
-        // was created / removed / replaced.
         if (dir === targetParent && filename === targetName && eventType === "rename") {
             churned = true;
         }
@@ -112,7 +98,7 @@ export const watchDir = action("Watch Dir")
         const chain = existingChain();
         const same = chain.length === armed.length && chain.every((d, i) => d === armed[i]);
         if (same && !force)
-            return; // re-arm only when structure changed (or forced after a churn)
+            return;
         for (const w of watchers)
             w.close();
         watchers.length = 0;
@@ -135,17 +121,16 @@ export const watchDir = action("Watch Dir")
     const tick = async (isInitial) => {
         const didChurn = churned;
         churned = false;
-        arm(didChurn); // re-arm (force after a churn — the old target handle is dead)
+        arm(didChurn);
         detectDir(isInitial, didChurn);
         await recheck(isInitial);
     };
     void tick(true); // initial state + arm the chain
-    // Daemon: stay alive until torn down, then flush once more and close.
     return new Promise((resolveRun) => {
         const stop = async () => {
             if (timer)
                 clearTimeout(timer);
-            await tick(false); // final flush — capture changes right before teardown
+            await tick(false); // final flush before teardown
             for (const w of watchers)
                 w.close();
             watchers.length = 0;

package/dist/actions/watch.d.ts

@@ -9,25 +9,17 @@ export interface FileEvent {
 }
 export type FileListener = (event: FileEvent) => void;
 export interface WatchOptions {
-    /** The file is absent when watching starts. */
     onMissing?: FileListener;
-    /** The file appeared (or already existed at startup — `isInitial`). */
     onCreate?: FileListener;
-    /** The file's contents changed (its mtime moved). */
     onUpdate?: FileListener;
-    /** The file was removed. */
     onDelete?: FileListener;
     /** Coalesce rapid events (e.g. an editor's atomic save) within this window. Default 50ms. */
     debounceMs?: number;
 }
 /**
  * Watches a single file that may not exist yet, firing callbacks on its
- * transitions. Since `fs.watch` can't watch a missing path, it watches the
- * parent directory and filters by name; on each event it re-`stat`s and diffs
- * against the last known state rather than trusting the raw event type. Runs
- * until the run's signal aborts, then closes the watcher.
- *
- * Assumes the parent directory exists; watching when an ancestor is missing is
- * a later case.
+ * transitions. Watches the parent directory and filters by name (so a missing
+ * file can be awaited), re-`stat`ing on each event to diff against last state.
+ * Daemon: runs until the run's signal aborts, then closes the watcher.
  */
-export declare const watch: import("../index.ts").Action<[target: string, opts?: WatchOptions | undefined], void, import("../index.ts").NoEvents, void>;
+export declare const watch: import("../index.ts").Action<[target: string, opts?: WatchOptions | undefined], void, import("../core/types.ts").NoEvents, void>;