omkit 0.0.1

package/dist/core/run.js

@@ -0,0 +1,212 @@
+import { relative } from "node:path";
+import { log as logs } from "./log-collector/global.js";
+import { createRenderer } from "./log-collector/render.js";
+import { streamLog, writeLog } from "./output.js";
+import { marker } from "./markers.js";
+/** One run per process — a single world over the one global log. See {@link run}. */
+let started = false;
+/** Narrate a run-lifecycle milestone into the global log (renders as a `[run]` line). */
+const narrate = (message) => logs.append({ source: "run", level: "run", message });
+/** The entry script, relative to where node was invoked (so the log says what produced it). */
+const scriptPath = () => {
+    const entry = process.argv[1];
+    return entry ? relative(process.cwd(), entry) : "(unknown)";
+};
+/** A constructed instance is an object carrying a `start` function. */
+const isActionInstance = (value) => typeof value === "object" &&
+    value !== null &&
+    typeof value.start === "function";
+/** An *uncalled* action: the callable `action(name).run(…)` returns before it's invoked. */
+const isUncalledAction = (value) => typeof value === "function" && typeof value.actionName === "string";
+/**
+ * Guard each launch argument: an action *instance* is required, not the action
+ * itself. Forgetting the trailing `()` is an easy slip (the callable has no
+ * `.start`), and silently treating it as something else would report a false
+ * green — so fail loudly with the fix.
+ */
+function assertInstance(value) {
+    if (isActionInstance(value))
+        return;
+    const hint = isUncalledAction(value)
+        ? ` — that looks like an action that wasn't invoked; construct an instance by calling it: action("…").run(…)()`
+        : "";
+    throw new Error(`run() expects action instances; received ${typeof value}${hint}`);
+}
+export function run(...args) {
+    if (started) {
+        throw new Error("run() may only be called once per process — attach more actions to the existing run with its .run(…) method.");
+    }
+    // Peel an optional leading options bag off the variadic actions, keeping the
+    // bare `run(...actions)` call form working unchanged. Options are a plain
+    // object (no `.start`); a *function* first arg is never options — it's an
+    // uncalled action, which `assertInstance` below reports clearly.
+    const first = args[0];
+    const hasOptions = first !== undefined && !isActionInstance(first) && typeof first !== "function";
+    const options = hasOptions ? first : {};
+    const actions = (hasOptions ? args.slice(1) : args);
+    const failFast = options.failFast ?? true;
+    // Validate eagerly, before the one-run latch flips, so a bad argument throws
+    // cleanly and leaves the process's single run slot still usable.
+    for (const instance of actions)
+        assertInstance(instance);
+    started = true;
+    const controller = new AbortController();
+    // The log closes when the run tears down, so every `logs.subscribe(…)` ends on
+    // its own — no subscriber has to watch the signal.
+    logs.endOn(controller.signal);
+    // ── Lifecycle state ──────────────────────────────────────────────────────
+    // The single source of truth for "where in its life is this run". Only
+    // `beginClosing` and the finalize step below mutate it, and only forward.
+    let state = "open";
+    // Genuine failures (not teardown cascade). Frozen into the verdict at close.
+    const failures = [];
+    // Every launched action's promise lives here until it settles; the drain loop
+    // empties this set. Daemons keep it non-empty until the controller aborts.
+    const inFlight = new Set();
+    /**
+     * 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.
+     */
+    const beginClosing = (reason) => {
+        if (state !== "open")
+            return;
+        state = "closing";
+        narrate(`tearing down · ${reason}`);
+        controller.abort();
+    };
+    /** Record a genuine fault and, under fail-fast, kick off teardown. */
+    const recordFailure = (action, error) => {
+        failures.push({ action, error });
+        if (failFast)
+            beginClosing(`failed: ${action}`);
+    };
+    // Ctrl-C tears the run down gracefully through the lifecycle, like cancel().
+    const onSigint = () => beginClosing("interrupted (SIGINT)");
+    process.once("SIGINT", onSigint);
+    // 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.
+    const onFatal = (kind) => (error) => {
+        logs.append({
+            source: kind,
+            level: "error",
+            message: error instanceof Error ? (error.stack ?? error.message) : String(error),
+        });
+        // Genuine fault vs. teardown fallout: only one that surfaces *before* the
+        // signal aborts is the run's own (mirrors `launch`'s cascade rule); a throw
+        // during unwind is logged but doesn't pollute the verdict. Either way tear
+        // down — an uncaught fault leaves the process state undefined, so we always
+        // finish and flush, even under `failFast: false`.
+        if (!controller.signal.aborted)
+            failures.push({ action: kind, error });
+        beginClosing(kind);
+    };
+    const onUncaught = onFatal("uncaughtException");
+    const onUnhandled = onFatal("unhandledRejection");
+    process.on("uncaughtException", onUncaught);
+    process.on("unhandledRejection", onUnhandled);
+    narrate(`run started · ${scriptPath()}`);
+    // Start streaming log entries to disk immediately — incremental writes survive
+    // hard kills where the final writeLog never runs.
+    void streamLog(logs).catch(() => { });
+    const launch = (instance) => {
+        narrate(`launch ${instance.name}`);
+        // The action logs into the one shared store (entries carry their `source`;
+        // grouping is applied at render time) and gets the run's signal directly; the
+        // framework injects a `proc` bound to both, so there's no ambient context.
+        const promise = instance.start({ logs, signal: controller.signal }).catch((error) => {
+            // Always record the fault in the action's own log, under its name.
+            logs.append({
+                source: instance.name,
+                level: "error",
+                message: error instanceof Error ? (error.stack ?? error.message) : String(error),
+            });
+            // Genuine failure vs. teardown fallout: if the signal was already aborted
+            // when this surfaced, the rejection is almost certainly the abort killing
+            // the action (a cascade), not its own fault — so it must not pollute the
+            // verdict. The *first* real error is caught here before `recordFailure`
+            // triggers the abort, so `signal.aborted` is still false for it.
+            if (!controller.signal.aborted)
+                recordFailure(instance.name, error);
+        });
+        inFlight.add(promise);
+        void promise.finally(() => inFlight.delete(promise));
+    };
+    for (const instance of actions)
+        launch(instance);
+    // 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.
+    const done = (async () => {
+        for (;;) {
+            if (inFlight.size === 0) {
+                // Nothing left to run. If still open, every action finished on its own —
+                // natural completion; tear down so daemons/listeners unwind uniformly.
+                // If already closing, teardown is simply complete.
+                if (state === "open")
+                    beginClosing("completed");
+                break;
+            }
+            await Promise.allSettled([...inFlight]);
+        }
+        // ── Finalize (reached exactly once) ──────────────────────────────────────
+        state = "closed";
+        process.off("SIGINT", onSigint);
+        process.off("uncaughtException", onUncaught);
+        process.off("unhandledRejection", onUnhandled);
+        narrate("finished");
+        const file = await writeLog(logs);
+        // Direct to the terminal — the file's already written, so this line isn't in it.
+        console.log(marker("run", `log → ${file}`));
+        const result = { ok: failures.length === 0, failures };
+        // One process = one run = one verdict; reflect pass/fail in the exit code so
+        // shells and CI see it without parsing the log. Only set it on failure, so a
+        // code a failing action's own handler may have set isn't clobbered to 0.
+        if (!result.ok)
+            process.exitCode = 1;
+        return result;
+    })();
+    // `done` resolves with the verdict and never rejects; guard anyway so a stray
+    // finalize error can't surface as an unhandled rejection.
+    done.catch(() => { });
+    const drain = (write = (message) => console.log(message)) => {
+        void (async () => {
+            // A renderer 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.
+            const render = createRenderer();
+            for await (const entry of logs.subscribe({ replay: true }))
+                write(render(entry));
+        })().catch(() => { });
+        return self;
+    };
+    const self = {
+        logs,
+        get state() {
+            return state;
+        },
+        done,
+        signal: controller.signal,
+        run(...more) {
+            if (state !== "open") {
+                throw new Error(`run.run(…) rejected: the run is "${state}", not "open". Launch actions before ` +
+                    `teardown, or from a lifecycle event of an action that is still running.`);
+            }
+            for (const instance of more)
+                launch(instance);
+            return self;
+        },
+        cancel: () => beginClosing("cancelled"),
+        drain,
+    };
+    return self;
+}

package/dist/core/spin.d.ts

@@ -0,0 +1,58 @@
+import { type AnyActionInstance } from "./action.ts";
+import { type Run, type RunOptions } from "./run.ts";
+/**
+ * Launch an action into the spin's run and get the same instance back, so you
+ * can `await` its `.done` / `.ref` or subscribe with `.on` / `.once`. A nod is
+ * how the body waves an action in.
+ */
+export type Nod = <I extends AnyActionInstance>(instance: I) => I;
+/** Tunes a {@link spin} — the run's options plus how it drains. */
+export interface SpinOptions extends RunOptions {
+    /**
+     * Stream the log to the console automatically from the start. Default `true`.
+     * Set `false` when you need to drain later via {@link SpinContext.drain} —
+     * e.g. after an interactive `prompt`, so the stream doesn't write over it.
+     */
+    drain?: boolean;
+}
+/** What a {@link spin} body receives. */
+export interface SpinContext {
+    /** Launch an action into the run; returns the instance for awaiting/chaining. */
+    readonly nod: Nod;
+    /**
+     * Start streaming the run's log to the console now. Only needed when the spin
+     * was created with `drain: false`; idempotent, so it's safe to call regardless.
+     */
+    readonly drain: Run["drain"];
+    /**
+     * Tear the run down (abort the signal, stopping daemons). Use it to end a run
+     * whose work is finished but which is held open by a daemon — e.g. once a
+     * one-shot build completes while a watcher is still running.
+     */
+    readonly cancel: Run["cancel"];
+    /** The run's abort signal — honor it to stop early. */
+    readonly signal: AbortSignal;
+}
+/** The body of a {@link spin}: any (async) function — it isn't named or wrapped by you. */
+export type SpinBody = (ctx: SpinContext) => void | Promise<void>;
+/**
+ * Runs a linear orchestration. You pass a plain (async) function; tswm hosts it
+ * in a single in-flight action and hands it a {@link Nod}. Because that host
+ * stays in-flight while your body `await`s, the run never idles shut between
+ * steps — so you write `await` / `if` control flow instead of nested `done`
+ * callbacks. When the body returns, the daemons it nodded in keep the run alive
+ * until teardown.
+ *
+ *   spin({ failFast: false }, async ({ nod }) => {
+ *     if ((await nod(prompt({ … })).done) === "yes") await nod(test).done;
+ *     nod(devServer);                                 // fire-and-forget daemon
+ *     const chrome = nod(chromedriver({ … }));
+ *     nod(chromePage(chrome.ref));                    // data deps via .ref
+ *   });
+ *
+ * Auto-drains by default; pass `drain: false` and call `ctx.drain()` yourself to
+ * stream the log only from a chosen point (e.g. after a `prompt`). Returns the
+ * {@link Run}, so `.done` is available on it too.
+ */
+export declare function spin(body: SpinBody): Run;
+export declare function spin(options: SpinOptions, body: SpinBody): Run;

package/dist/core/spin.js

@@ -0,0 +1,29 @@
+import { action } from "./action.js";
+import { run } from "./run.js";
+export function spin(a, b) {
+    const [options, body] = typeof a === "function" ? [{}, a] : [a, b];
+    const { drain: autoDrain = true, ...runOptions } = options;
+    // `run(...)` below assigns `host` synchronously, before the action's async body
+    // ever runs — so the closures here capture the run safely.
+    let host;
+    // One-shot drain: auto-drain and a manual ctx.drain() can't double-subscribe.
+    let drained = false;
+    const startDrain = (write) => {
+        if (!drained) {
+            drained = true;
+            host.drain(write);
+        }
+        return host;
+    };
+    const hosted = action("Spin").run(async ({ signal }) => {
+        const nod = (instance) => {
+            host.run(instance);
+            return instance;
+        };
+        await body({ nod, drain: startDrain, cancel: () => host.cancel(), signal });
+    });
+    host = run(runOptions, hosted());
+    if (autoDrain)
+        startDrain();
+    return host;
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * tswm — the operational/runtime layer to tskb's knowledge layer.
+ *
+ * The core engine: define typed {@link action}s, launch them under one
+ * {@link run}, and share a single append-only log. Reusable actions built on
+ * this engine live at the `tswm/actions` entry point.
+ *
+ * This is a curated public surface — internal helpers (the async queue, the log
+ * renderer, marker prefixing) are intentionally not exported.
+ */
+export { action } from "./core/action.ts";
+export type { Action, ActionBuilder, ActionInstance, AnyActionInstance, ActionContext, SystemGlobal, SystemEvents, InstanceEvents, NoEvents, Awaitable, } from "./core/action.ts";
+export { run } from "./core/run.ts";
+export type { Run, RunResult, RunOptions, RunState, ActionFailure } from "./core/run.ts";
+export { spin } from "./core/spin.ts";
+export type { Nod, SpinOptions, SpinContext, SpinBody } from "./core/spin.ts";
+export { events } from "./core/events.ts";
+export type { Emitter, EventHandler, EventMeta } from "./core/events.ts";
+export { createProc } from "./core/process.ts";
+export type { Proc } from "./core/process.ts";
+export { LogsCollector } from "./core/log-collector/LogsCollector.ts";
+export type { Logger, LogEntry, LogInput, SubscribeOptions, } from "./core/log-collector/LogsCollector.ts";
+export { log } from "./core/log-collector/global.ts";
+export { snapshot, captureSnapshot } from "./core/output.ts";
+export type { SnapshotRef } from "./core/output.ts";

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * tswm — the operational/runtime layer to tskb's knowledge layer.
+ *
+ * The core engine: define typed {@link action}s, launch them under one
+ * {@link run}, and share a single append-only log. Reusable actions built on
+ * this engine live at the `tswm/actions` entry point.
+ *
+ * This is a curated public surface — internal helpers (the async queue, the log
+ * renderer, marker prefixing) are intentionally not exported.
+ */
+// ── Actions ────────────────────────────────────────────────────────────────
+export { action } from "./core/action.js";
+// ── Runs ───────────────────────────────────────────────────────────────────
+export { run } from "./core/run.js";
+// ── Spin (linear orchestration) ──────────────────────────────────────────────
+export { spin } from "./core/spin.js";
+// ── Events ─────────────────────────────────────────────────────────────────
+export { events } from "./core/events.js";
+// ── Child processes ────────────────────────────────────────────────────────
+export { createProc } from "./core/process.js";
+// ── The log ────────────────────────────────────────────────────────────────
+export { LogsCollector } from "./core/log-collector/LogsCollector.js";
+export { log } from "./core/log-collector/global.js";
+// ── Snapshots ──────────────────────────────────────────────────────────────
+export { snapshot, captureSnapshot } from "./core/output.js";

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "omkit",
+  "version": "0.0.1",
+  "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",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./actions": {
+      "types": "./dist/actions/index.d.ts",
+      "import": "./dist/actions/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "author": "Dimitar Mihaylov",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mitk0936/tskb.git",
+    "directory": "packages/omkit"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "keywords": [
+    "typescript",
+    "orchestration",
+    "actions",
+    "simulation",
+    "pipeline",
+    "process",
+    "watch",
+    "logging",
+    "developer-tools"
+  ],
+  "dependencies": {
+    "playwright-core": "^1.49.0",
+    "zx": "^8.8.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.3"
+  }
+}