omkit 0.0.14 → 0.1.0

package/dist/orchestration/action/types.d.ts

@@ -1,182 +0,0 @@
-import type { Logger } from "../../output/log/LogsCollector.ts";
-import type { Output } from "../../output/Output.ts";
-import type { Emitter, EventHandler } from "../events/events.ts";
-import type { Proc } from "../../system/process/process.ts";
-import type { Assert } from "../assert.ts";
-/** An action that declares no events. */
-export type NoEvents = Record<never, never>;
-/** A value an action's `exec` may return: a result, or a promise of one. */
-export type Awaitable<T> = T | Promise<T>;
-/**
- * How an action settles. An action **never throws into the spin body** — its
- * failure is data, not control flow: it completes with `{ ok: false, error }`
- * instead of rejecting. On success it carries the exec's `value`. `exitCode` is
- * present when the failure came from a process (see {@link import("../../../actions/command.ts").command}).
- * Await it via `instance.done` or `once("done")`; both resolve, never reject.
- */
-export type Outcome<T> = {
-    readonly ok: true;
-    readonly value: T;
-} | {
-    readonly ok: false;
-    readonly error: unknown;
-    readonly exitCode?: number;
-};
-/**
- * Lifecycle events the framework emits for every action — on top of whatever it
- * declares via `.emits<…>()`. They make key moments first-class signals (no
- * log-scraping) and give a uniform sequencing hook.
- */
-export interface SystemEvents<Result> {
-    /** The action published its imperative handle via `ctx.attach` (fires once). */
-    attached: void;
-    /** The action settled; payload is its {@link Outcome} (success or failure). Fires once, always. */
-    done: Outcome<Result>;
-    /** The action failed; payload is the thrown error. Fires only on failure (alongside `done`). */
-    error: unknown;
-}
-/** The full event map a constructed instance exposes: the declared events plus the system ones. */
-export type InstanceEvents<Events extends object, Result> = Events & SystemEvents<Result>;
-/**
- * Launch an action into the spin and get the same instance back, so you can
- * `await` its `.done` (its {@link Outcome} — resolves with `{ ok, value } |
- * { ok, error }`, **never throws**), its `.ref` (the attached handle; rejects on
- * failure, so it's for data deps consumed inside other actions), or subscribe with
- * `.on` / `.once`. The spin body waves an action in with a nod; an action nods
- * **child** actions the same way, and their log output is prefixed with the
- * parent's path (see `SpinHost`).
- */
-export type Nod = <I extends AnyActionInstance>(instance: I) => I;
-/** System services the pipeline injects into every action when it runs. */
-export interface SystemGlobal {
-    /** A logger bound to this action — feeds it directly or via `proc`. */
-    readonly logs: Logger;
-    /** The run's abort signal — aborted on teardown/cancel; honor it to stop early. */
-    readonly signal: AbortSignal;
-    /**
-     * Launch a **child** action into the same spin (returns it for awaiting/chaining).
-     * The child's log output is prefixed with this action's path (`parent › child`),
-     * and the child lives in the spin — it keeps the run alive until it settles,
-     * independent of when this action finishes. `await ctx.nod(x).done` to wait on it.
-     */
-    readonly nod: Nod;
-    /**
-     * This run's output subsystem — the folder, snapshot store, and run-log writer,
-     * owned by the {@link SpinHost} and threaded to every action (rather than reached
-     * as a module singleton). The framework uses it to place `ctx.artifactsFolder`
-     * and to snapshot event/proc payloads; actions can reach `output.snapshots` to
-     * capture their own artifacts.
-     */
-    readonly output: Output;
-    /**
-     * Assert a boolean invariant for this action. Logs a `⊨` line every call; a
-     * mismatch is recorded into the run's verdict (never throws, never stops the
-     * run). Bound to this action's path for attribution.
-     */
-    readonly assert: Assert;
-}
-/** What an action's implementation receives: the system bag, plus `emit`, `attach`, and `proc`. */
-export interface ActionContext<Events extends object, Handle = void> extends SystemGlobal {
-    /** Emit one of this action's declared events (also logged onto the timeline under this action's path). */
-    readonly emit: Emitter<Events>["emit"];
-    /** Publish this action's imperative handle, resolving its instance's `.ref`. */
-    readonly attach: (handle: Handle) => void;
-    /**
-     * Spawn child processes bound to this action: their output streams into this
-     * action's log and they're killed on teardown. The built-in source; a custom
-     * one (e.g. CDP) follows the same pattern over `logs`/`signal`.
-     */
-    readonly proc: Proc;
-    /**
-     * Absolute path to this run's output folder (`logs/<name>/<date>/<time>/`) —
-     * created and shared across the run. Write action artifacts here so they land
-     * beside `run.log`; the same folder is on the `spin` context.
-     */
-    readonly artifactsFolder: string;
-    /**
-     * Capture a JSON snapshot into this run's output folder and drop a `[snapshot]`
-     * line on the timeline (under this action's path). The ergonomic shortcut for
-     * `ctx.output.snapshots.snapshot(…)`; the same convenience is on the `spin`
-     * context. Resolves with the snapshot's relative path.
-     */
-    readonly snapshot: (name: string, value: unknown) => Promise<string>;
-}
-/** A constructed-but-not-yet-run action: what calling an `Action` produces. */
-export interface ActionInstance<Result = unknown, Events extends object = NoEvents, Handle = void> {
-    readonly name: string;
-    readonly args: readonly unknown[];
-    /**
-     * Runs the action with the captured args and the injected system services.
-     * **Resolves with the {@link Outcome}, never rejects** — a failing action is
-     * reported as `{ ok: false, error }`, not a thrown promise, so it can't tear a
-     * caller down. The run reads this to build its verdict.
-     */
-    readonly start: (system: SystemGlobal) => Promise<Outcome<Result>>;
-    /**
-     * The action's {@link Outcome}, as a memoized promise that **never rejects** —
-     * the ergonomic way to await completion in a spin body:
-     * `const r = await nod(x).done; if (!r.ok) …`. Same value as `once("done")`.
-     */
-    readonly done: Promise<Outcome<Result>>;
-    /**
-     * Resolves with the handle the action attached via `ctx.attach` (set once).
-     * Used to thread a handle into another action (`chromePage("Explorer", driver.ref)`). If
-     * the action settles *without* attaching, this resolves (`undefined` for the
-     * default `void` handle) on success and **rejects on failure** — so, unlike
-     * `done`, awaiting `ref` in a body can throw. It's meant to be consumed as a
-     * constructor arg *inside* another action, where that rejection becomes that
-     * action's failure Outcome. For control flow, await `done`.
-     */
-    readonly ref: Promise<Handle>;
-    /** Subscribe to a declared or system event (`done`/`error`) with a handler. */
-    on<K extends keyof InstanceEvents<Events, Result>>(key: K, handler: EventHandler<InstanceEvents<Events, Result>[K]>): void;
-    /**
-     * A promise for the next occurrence of an event. It **never rejects**: it
-     * resolves with the event's payload, or with `undefined` if the action settles
-     * (`done`) before the event ever fires — so awaiting it in a spin body can't
-     * throw and can't hang. `once("done")` yields the {@link Outcome}. Use {@link on}
-     * for ongoing/handler subscriptions; `once` is the awaitable, one-value form.
-     */
-    once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K] | undefined>;
-    /**
-     * Gate this action on its **inputs** — the files/folders it *reads* (its
-     * sources), **not** what it produces. `paths` (each a file or a folder) are
-     * fingerprinted by mtime+size; the returned instance skips running when those
-     * inputs are unchanged since the last successful run, and otherwise runs this
-     * action and records the fingerprint. Pass inputs, not build outputs: caching
-     * on an output would skip the very run that produces it.
-     *
-     * Every path must be **absolute** (throws otherwise). A cache hit resolves
-     * immediately as success (result `undefined`) and logs a `cached, skipping`
-     * line; a failure of the inner action records nothing, so it re-runs next time.
-     *
-     * Because `nod`/`run` launch an instance the moment they receive it, chain
-     * `.withCache` *before* handing the instance in — passing the source dir:
-     * `nod(command("build", "npm run build").withCache(srcAbs))`.
-     */
-    withCache(...paths: string[]): AnyActionInstance;
-}
-/**
- * Any constructed instance, whatever its result, events, or handle. The launch
- * surface ({@link ActionInstance}-takers like `run` and `Spin.run`) accepts this
- * so handle-bearing actions — those declaring `.ref<H>()` — can be launched: the
- * bare `ActionInstance` pins the handle to `void`, so an instance whose `ref` is
- * a `Promise<Page>` (not `Promise<void>`) would otherwise be rejected. `unknown`
- * for result/handle and `object` for events admit every concrete instance while
- * still excluding non-instances.
- */
-export type AnyActionInstance = ActionInstance<unknown, object, unknown>;
-/** A callable produced by `action`: invoking it builds an {@link ActionInstance}. */
-export interface Action<Args extends unknown[], Result, Events extends object = NoEvents, Handle = void> {
-    (...args: Args): ActionInstance<Result, Events, Handle>;
-    readonly actionName: string;
-}
-/** Intermediate step from `action(name)`: declare events/handle, then provide the impl. */
-export interface ActionBuilder<Events extends object, Handle = void> {
-    /** Declare the typed event map this action emits. */
-    emits<E extends object>(): ActionBuilder<E, Handle>;
-    /** Declare the imperative handle this action exposes (resolved via `instance.ref`). */
-    ref<H>(): ActionBuilder<Events, H>;
-    /** Provide the implementation. `ctx` carries `logs`, `signal`, `emit`, and `attach`. */
-    run<Args extends unknown[], Result>(exec: (ctx: ActionContext<Events, Handle>, ...args: Args) => Awaitable<Result>): Action<Args, Result, Events, Handle>;
-}

package/dist/orchestration/assert.d.ts

@@ -1,22 +0,0 @@
-import type { Logger } from "../output/log/LogsCollector.ts";
-/**
- * An inline check injected into every action's `ctx` and the `spin` body. Passes
- * when `value` is `true`. Every call is logged; a failure is recorded into the
- * run's verdict — as data, not a throw — so the run keeps going and later
- * assertions still fire. Returns the pass boolean so a body can branch on it.
- *
- *   assert(page.isVisible(), "page loaded")
- */
-export type Assert = (value: boolean, what: string) => boolean;
-/** Marks a failed assertion in the spin's verdict, distinct from an action's own error. */
-export declare class AssertionError extends Error {
-    constructor(message: string);
-}
-/**
- * Build an {@link Assert} bound to one action (or the spin body): `name` is its
- * launch path (used for attribution in the log line and the error), `logs` is the
- * logger to append to, and `onFail` records a genuine failure into the verdict. The
- * factory is file-agnostic — it only appends `level: "assert"` entries; the
- * dedicated `assertions.log` is a downstream projection of that stream.
- */
-export declare function createAssert(name: string, logs: Logger, onFail: (error: AssertionError) => void): Assert;

package/dist/orchestration/assert.js

@@ -1,26 +0,0 @@
-/** Marks a failed assertion in the spin's verdict, distinct from an action's own error. */
-export class AssertionError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "AssertionError";
-    }
-}
-/**
- * Build an {@link Assert} bound to one action (or the spin body): `name` is its
- * launch path (used for attribution in the log line and the error), `logs` is the
- * logger to append to, and `onFail` records a genuine failure into the verdict. The
- * factory is file-agnostic — it only appends `level: "assert"` entries; the
- * dedicated `assertions.log` is a downstream projection of that stream.
- */
-export function createAssert(name, logs, onFail) {
-    return (value, what) => {
-        const pass = value;
-        const glyph = pass ? "✓" : "✗";
-        const message = `${name} · ${glyph} ${what}`;
-        logs.append({ source: "assert", level: "assert", message });
-        if (!pass) {
-            onFail(new AssertionError(`${name}: ${what}`));
-        }
-        return pass;
-    };
-}

package/dist/orchestration/spin/SpinHost.d.ts

@@ -1,109 +0,0 @@
-import type { AnyActionInstance } from "../action/types.ts";
-import { LogsCollector } from "../../output/log/LogsCollector.ts";
-import { Output } from "../../output/Output.ts";
-import type { SpinResult, SpinState } from "./types.ts";
-/**
- * A live spin over its own append-only log: constructing one launches the given
- * actions in parallel under a single abort controller and drives them to a terminal
- * {@link SpinResult}. Stop it with `.cancel()`, `await` its `.done` for the verdict.
- *
- * **A spin owns its world.** Each construction creates its *own* {@link LogsCollector}
- * and {@link Output} — the run's log, folder, and snapshots — rather than sharing a
- * process global, so runs don't bleed into each other and a fresh run can be created
- * in a living process (sequential re-runs, in-process tests). Attach further actions
- * to a running spin — including event-driven ones — via its `.run(…)` method.
- *
- * Each action runs against its own child logger (which headers and indents its
- * lines into this run's log) and the spin's shared abort signal — both injected
- * into its context, where the framework also binds a `proc` and the run's `output`
- * so child processes stream into the right log and die on teardown. A **failing
- * action never tears the spin down** — its `{ ok: false }` outcome is recorded in
- * the verdict (and sets exit code 1) and the spin keeps running. Teardown to
- * `closed` happens only on Ctrl-C, `.cancel()`, natural completion, or an uncaught
- * fatal. The process-level hooks (SIGINT/uncaught handlers, `exitCode`) are owned by
- * the run and cleaned at finalize, so they don't outlive it.
- */
-export declare class SpinHost {
-    /** This run's append-only log — its own store, not a process global. */
-    readonly logs: LogsCollector;
-    /** This run's output subsystem (folder + snapshots + run-log writer), wired to {@link logs}. */
-    readonly output: Output;
-    /** The spin's abort signal — for consumers that want to observe teardown. */
-    readonly signal: AbortSignal;
-    /** Settles once the spin reaches `closed`, carrying the terminal verdict. Never rejects. */
-    readonly done: Promise<SpinResult>;
-    /** The original `console.log`, captured before patching — the run's terminal writer. */
-    private readonly term;
-    /** Reinstalls the pre-run console methods; called once at finalize. */
-    private readonly restoreConsole;
-    private readonly controller;
-    private phase;
-    /** The current lifecycle state — see {@link SpinState}. */
-    get state(): SpinState;
-    private readonly failures;
-    private readonly inFlight;
-    private readonly launched;
-    private readonly streaming;
-    private readonly onSigint;
-    private readonly onUncaught;
-    private readonly onUnhandled;
-    constructor(...actions: AnyActionInstance[]);
-    /**
-     * Launch more actions into this same spin — same controller, same log. Chainable.
-     *
-     * Throws if the spin is no longer `open`.
-     */
-    run(...more: AnyActionInstance[]): this;
-    /**
-     * Launch `instance` into the spin under an optional `parentPath` (the nodding
-     * action's path, or `undefined` for a top-level nod). The single guarded entry to
-     * launching — `run` (top-level) and an action's own scoped `nod` both route here,
-     * so the "spin is open" check lives in one place.
-     */
-    private nodInto;
-    /** Begin teardown: abort the signal (killing procs, unblocking waits, stopping daemons). */
-    cancel(): void;
-    /**
-     * Live-render the log to the console. Started automatically from the constructor
-     * — every spin drains, with no flag to disable and nothing for the caller to
-     * invoke (for now). A single {@link LogRenderer} applies grouping/indentation as
-     * entries stream by; its state spans the replayed history and live entries as one
-     * continuous stream. The subscription ends itself when the run tears down (the
-     * collector closes it), so this loop simply runs to completion.
-     */
-    private drain;
-    /** Narrate a run-lifecycle milestone into this run's log (renders as a `[run]` line). */
-    private narrate;
-    /**
-     * Move `open → closing`: abort the signal (unwinding procs, waits, and
-     * daemons), narrate the cause once, and stop accepting new actions. Idempotent
-     * — only the first caller transitions; later triggers (a second failure, a
-     * `cancel()` during teardown) are no-ops. This is the *only* path to abort, so
-     * every teardown reason flows through one place.
-     */
-    private beginClosing;
-    /**
-     * Record a genuine fault in the verdict. It does **not** tear the spin down — a
-     * failing action is data, and the spin keeps running (only Ctrl-C / cancel /
-     * completion / an uncaught fatal close it).
-     */
-    private recordFailure;
-    /**
-     * A throw or rejection that escaped every action's own handling. Without a
-     * handler Node prints it and exits *immediately* — before the run can flush its
-     * log, which leaves a silent, empty log directory and no verdict. So catch it,
-     * log it, fold it into the verdict, and drive teardown so the log still flushes
-     * and the exit code reflects the fault — degrading a stray throw to a recorded
-     * failure instead of a hard crash. Removed at finalize, so it only governs
-     * while this run owns the process.
-     */
-    private onFatal;
-    private launch;
-    /**
-     * Drives the run to `closed`. The loop re-checks `inFlight` because actions can
-     * be added (or daemons can settle on abort) while we await. A synchronous
-     * `.run(…)` from a settling action's lifecycle event lands before that action's
-     * `finally` removes it, so `inFlight` never spuriously hits 0 mid-handoff.
-     */
-    private drive;
-}