omkit 0.0.3 → 0.0.6

package/dist/actions/command.d.ts

@@ -8,6 +8,12 @@ export interface CommandOptions {
     cwd?: string;
     /** Label the child's output is logged under. Defaults to the action's name. */
     label?: string;
+    /**
+     * Environment for the child. Pass the full set you want (e.g.
+     * `{ ...process.env, NODE_ENV: "development" }`) — it's handed to the child
+     * as-is, not merged. Omit to inherit the parent's `process.env`.
+     */
+    env?: NodeJS.ProcessEnv;
 }
 /**
  * Runs a fixed command as an action **instance** — built in a single call, the

package/dist/actions/command.js

@@ -22,7 +22,7 @@ export function command(name, cmdOrFile, argsOrOptions, maybeOptions) {
         // against process.cwd() — exactly the "absolute from where node runs" rule.
         const cwd = path.resolve(options.cwd ?? ".");
         // proc sources the LogsCollector from async context and streams output into it.
-        return proc(options.label ?? name, { cwd })(verbatim(cmdOrFile));
+        return proc(options.label ?? name, { cwd, ...(options.env ? { env: options.env } : {}) })(verbatim(cmdOrFile));
     })(); // construct the instance here, so callers get one in a single call
 }
 /**
@@ -36,7 +36,8 @@ const spawnDirect = (logs, signal, name, file, args, options) => {
     const cwd = path.resolve(options.cwd ?? ".");
     const source = options.label ?? name;
     // windowsHide keeps a stray console window from flashing for the child.
-    const child = spawn(file, args, { cwd, windowsHide: true });
+    // env omitted -> spawn inherits the parent's process.env (Node's default).
+    const child = spawn(file, args, { cwd, windowsHide: true, env: options.env });
     // Mirror proc's launch line: a filterable milestone on the timeline, with the
     // structured args snapshotted and linked (see process.ts for the rationale).
     const snap = captureSnapshot(`proc-${name}-start`, { cmd: file, args, cwd });

package/dist/actions/tail-log.js

@@ -25,7 +25,13 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
     let pending = ""; // partial trailing line, buffered until its newline
     // Append every complete line in `text`, keeping any remainder for next time.
     const feed = (text) => {
-        pending += text;
+        // Strip NUL bytes first. Log rotators (log4js/streamroller) can pre-allocate
+        // or leave a rotated file padded with \0, and a NUL run contains no newline —
+        // so without this the whole padded region buffers and flushes as one huge
+        // bogus line (the tell-tale "line of blanks/spaces"). NUL is never valid in
+        // a text log, so dropping it is safe; a NUL-only stretch collapses to "" and
+        // is skipped by the empty-line guard below.
+        pending += text.replace(/\0/g, "");
         let newline;
         while ((newline = pending.indexOf("\n")) !== -1) {
             const line = pending.slice(0, newline).replace(/\r$/, "");

package/dist/core/action.d.ts

@@ -39,6 +39,12 @@ export interface ActionContext<Events extends object, Handle = void> extends Sys
      * 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;
 }
 /** A constructed-but-not-yet-run action: what calling an `Action` produces. */
 export interface ActionInstance<Result = unknown, Events extends object = NoEvents, Handle = void> {
@@ -63,18 +69,22 @@ export interface ActionInstance<Result = unknown, Events extends object = NoEven
      */
     once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K]>;
     /**
-     * Gate this action on a folder fingerprint: returns a new instance that skips
-     * running when the mtime+size of every file under `folders` matches the last
-     * successful run, and otherwise runs this action and records the fingerprint.
+     * 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:
-     * `nod(command("build", "…").withCache(distAbs))`.
+     * `.withCache` *before* handing the instance in — passing the source dir:
+     * `nod(command("build", "npm run build").withCache(srcAbs))`.
      */
-    withCache(...folders: string[]): AnyActionInstance;
+    withCache(...paths: string[]): AnyActionInstance;
 }
 /**
  * Any constructed instance, whatever its result, events, or handle. The launch

package/dist/core/action.js

@@ -1,6 +1,7 @@
 import { events } from "./events.js";
 import { createProc } from "./process.js";
-import { fingerprint, read, write, resolveFolders } from "./folder-cache.js";
+import { fingerprint, read, write, resolvePaths } from "./folder-cache.js";
+import { artifactsFolder } from "./output.js";
 /** A promise paired with its settlers, for the set-once handle. */
 const deferred = () => {
     let resolve;
@@ -82,7 +83,13 @@ const build = (name, exec) => {
             // `Promise.resolve().then` normalizes a sync result and routes a sync
             // throw to the `error` path, so exec may be sync or async.
             Promise.resolve()
-                .then(() => exec({ ...system, emit, attach, proc: createProc(system.logs, system.signal) }, ...args))
+                .then(() => exec({
+                ...system,
+                emit,
+                attach,
+                proc: createProc(system.logs, system.signal),
+                artifactsFolder: artifactsFolder(),
+            }, ...args))
                 .then((result) => {
                 systemEmit("done", result);
                 // Settle `ref` if the action finished without attaching, so awaiters
@@ -105,23 +112,23 @@ const build = (name, exec) => {
                 return awaitEvent(emitter, name, key);
             },
             // Wrap this instance in a fresh one (reusing the engine for its own
-            // emitter/ref/on/once) that fingerprints `folders` and either skips or
+            // emitter/ref/on/once) that fingerprints `paths` and either skips or
             // runs+records. The wrapper keeps this action's `name`, so log lines and
             // the `launch <name>` line are unchanged. It forwards its injected
             // logs/signal straight into the inner action's `start`.
-            withCache(...folders) {
+            withCache(...paths) {
                 // Validate + canonicalize eagerly here (at the call site), not lazily
                 // inside the run — a relative path fails fast where it's written, and
                 // the resolved paths give a stable cache key regardless of spelling.
-                const dirs = resolveFolders(folders);
+                const targets = resolvePaths(paths);
                 return action(name).run(async (ctx) => {
-                    const fp = await fingerprint(dirs);
-                    if ((await read(dirs)) === fp) {
+                    const fp = await fingerprint(targets);
+                    if ((await read(targets)) === fp) {
                         ctx.logs.append({ source: name, level: "info", message: "cached, skipping" });
                         return undefined;
                     }
                     const result = await instance.start({ logs: ctx.logs, signal: ctx.signal });
-                    await write(dirs, fp); // only on success — a throw above skips this
+                    await write(targets, fp); // only on success — a throw above skips this
                     return result;
                 })();
             },

package/dist/core/folder-cache.d.ts

@@ -1,36 +1,39 @@
 /**
- * A folder-fingerprint cache: hash the mtime+size of every file under one or
- * more folders, so an expensive action can be skipped when nothing it depends
- * on has changed since its last successful run. Backs the `.withCache(...)`
- * method on action instances.
+ * An input-fingerprint cache: hash the mtime+size of one or more **input**
+ * targets (the files/folders an action reads — *not* what it produces), so an
+ * expensive action can be skipped when its inputs are unchanged since its last
+ * successful run. Backs the `.withCache(...)` method on action instances.
  *
  * Entries live under `node_modules/.cache/omkit/` (conventional, gitignored) —
- * one JSON file per set of folders, named by a hash of their absolute paths.
+ * one JSON file per set of inputs, named by a hash of their absolute paths.
  */
 /** Where cache entries are written — `node_modules/.cache/omkit/` under the cwd. */
 export declare const cacheDir: string;
 /**
- * Require every path to be **absolute** (a relative folder is a developer error
- * — throws, naming it) and return them canonicalized with `resolve`, so
- * different spellings of the same folder (`.`/`..`/trailing slash) collapse to
- * one stable fingerprint prefix and cache key. `resolve` on an already-absolute
- * path only normalizes — it never falls back to the cwd.
+ * Require every path to be **absolute** (a relative path is a developer error —
+ * throws, naming it) and return them canonicalized with `resolve`, so different
+ * spellings of the same target (`.`/`..`/trailing slash) collapse to one stable
+ * fingerprint prefix and cache key. `resolve` on an already-absolute path only
+ * normalizes — it never falls back to the cwd. Each target may be a file or a
+ * folder (see {@link fingerprint}).
  */
-export declare const resolveFolders: (folders: string[]) => string[];
+export declare const resolvePaths: (paths: string[]) => string[];
 /**
- * Fingerprints one or more folders by their files' mtime+size. Every path must
- * be absolute (throws otherwise). A missing folder contributes nothing (so an
- * output folder that hasn't been built yet is naturally a miss, not an error).
- * The entry list is sorted for determinism before hashing.
+ * Fingerprints one or more **input** targets by mtime+size. Each target may be
+ * a **file** (fingerprinted directly) or a **folder** (walked recursively, its
+ * files fingerprinted). Every path must be absolute (throws otherwise). A
+ * missing target contributes nothing — so an input that doesn't exist yet is
+ * naturally a miss, not an error. The entry list is sorted for determinism
+ * before hashing.
  */
-export declare const fingerprint: (folders: string[]) => Promise<string>;
+export declare const fingerprint: (paths: string[]) => Promise<string>;
 /**
- * Reads the fingerprint stored for these folders, or `undefined` when there's
+ * Reads the fingerprint stored for these targets, or `undefined` when there's
  * no cache (absent, unreadable, or malformed — all treated as a miss).
  */
-export declare const read: (folders: string[]) => Promise<string | undefined>;
+export declare const read: (paths: string[]) => Promise<string | undefined>;
 /**
- * Records the fingerprint for these folders after a successful run. Writes
+ * Records the fingerprint for these targets after a successful run. Writes
  * atomically (temp file + rename) so a concurrent read never sees a half-file.
  */
-export declare const write: (folders: string[], fp: string) => Promise<void>;
+export declare const write: (paths: string[], fp: string) => Promise<void>;

package/dist/core/folder-cache.js

@@ -2,52 +2,71 @@ import { createHash } from "node:crypto";
 import { mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
 /**
- * A folder-fingerprint cache: hash the mtime+size of every file under one or
- * more folders, so an expensive action can be skipped when nothing it depends
- * on has changed since its last successful run. Backs the `.withCache(...)`
- * method on action instances.
+ * An input-fingerprint cache: hash the mtime+size of one or more **input**
+ * targets (the files/folders an action reads — *not* what it produces), so an
+ * expensive action can be skipped when its inputs are unchanged since its last
+ * successful run. Backs the `.withCache(...)` method on action instances.
  *
  * Entries live under `node_modules/.cache/omkit/` (conventional, gitignored) —
- * one JSON file per set of folders, named by a hash of their absolute paths.
+ * one JSON file per set of inputs, named by a hash of their absolute paths.
  */
 /** Where cache entries are written — `node_modules/.cache/omkit/` under the cwd. */
 export const cacheDir = join(process.cwd(), "node_modules", ".cache", "omkit");
 /**
- * Require every path to be **absolute** (a relative folder is a developer error
- * — throws, naming it) and return them canonicalized with `resolve`, so
- * different spellings of the same folder (`.`/`..`/trailing slash) collapse to
- * one stable fingerprint prefix and cache key. `resolve` on an already-absolute
- * path only normalizes — it never falls back to the cwd.
+ * Require every path to be **absolute** (a relative path is a developer error —
+ * throws, naming it) and return them canonicalized with `resolve`, so different
+ * spellings of the same target (`.`/`..`/trailing slash) collapse to one stable
+ * fingerprint prefix and cache key. `resolve` on an already-absolute path only
+ * normalizes — it never falls back to the cwd. Each target may be a file or a
+ * folder (see {@link fingerprint}).
  */
-export const resolveFolders = (folders) => folders.map((folder) => {
-    if (!isAbsolute(folder)) {
-        throw new Error(`withCache: folder path must be absolute, got "${folder}"`);
+export const resolvePaths = (paths) => paths.map((p) => {
+    if (!isAbsolute(p)) {
+        throw new Error(`withCache: path must be absolute, got "${p}"`);
     }
-    return resolve(folder);
+    return resolve(p);
 });
 /**
- * Fingerprints one or more folders by their files' mtime+size. Every path must
- * be absolute (throws otherwise). A missing folder contributes nothing (so an
- * output folder that hasn't been built yet is naturally a miss, not an error).
- * The entry list is sorted for determinism before hashing.
+ * Fingerprints one or more **input** targets by mtime+size. Each target may be
+ * a **file** (fingerprinted directly) or a **folder** (walked recursively, its
+ * files fingerprinted). Every path must be absolute (throws otherwise). A
+ * missing target contributes nothing — so an input that doesn't exist yet is
+ * naturally a miss, not an error. The entry list is sorted for determinism
+ * before hashing.
  */
-export const fingerprint = async (folders) => {
-    const dirs = resolveFolders(folders);
+export const fingerprint = async (paths) => {
+    const targets = resolvePaths(paths);
     const entries = [];
-    for (const folder of dirs) {
+    const record = (target, rel, mtimeMs, size) => {
+        entries.push(`${target}\0${rel}\0${mtimeMs}\0${size}`);
+    };
+    for (const target of targets) {
+        let root;
+        try {
+            root = await stat(target);
+        }
+        catch {
+            continue; // missing/unreadable — contributes no entries
+        }
+        // A file target fingerprints itself (empty rel — there's no walk).
+        if (root.isFile()) {
+            record(target, "", root.mtimeMs, root.size);
+            continue;
+        }
+        // A folder target: walk it and fingerprint every file inside.
         let rels;
         try {
-            rels = await readdir(folder, { recursive: true });
+            rels = await readdir(target, { recursive: true });
         }
         catch {
-            continue; // folder missing/unreadable — contributes no entries
+            continue;
         }
         for (const rel of rels) {
-            const abs = join(folder, rel);
+            const abs = join(target, rel);
             try {
                 const stats = await stat(abs);
                 if (stats.isFile())
-                    entries.push(`${folder}\0${rel}\0${stats.mtimeMs}\0${stats.size}`);
+                    record(target, rel, stats.mtimeMs, stats.size);
             }
             catch {
                 // entry vanished between readdir and stat — skip
@@ -57,18 +76,18 @@ export const fingerprint = async (folders) => {
     entries.sort();
     return createHash("sha1").update(entries.join("\n")).digest("hex");
 };
-/** The on-disk filename for a set of folders — a hash of their absolute paths. */
-const entryPath = (folders) => {
-    const key = createHash("sha1").update(resolveFolders(folders).sort().join("\0")).digest("hex");
+/** The on-disk filename for a set of targets — a hash of their absolute paths. */
+const entryPath = (paths) => {
+    const key = createHash("sha1").update(resolvePaths(paths).sort().join("\0")).digest("hex");
     return join(cacheDir, `${key}.json`);
 };
 /**
- * Reads the fingerprint stored for these folders, or `undefined` when there's
+ * Reads the fingerprint stored for these targets, or `undefined` when there's
  * no cache (absent, unreadable, or malformed — all treated as a miss).
  */
-export const read = async (folders) => {
+export const read = async (paths) => {
     try {
-        const raw = await readFile(entryPath(folders), "utf8");
+        const raw = await readFile(entryPath(paths), "utf8");
         const entry = JSON.parse(raw);
         return typeof entry.fingerprint === "string" ? entry.fingerprint : undefined;
     }
@@ -77,13 +96,13 @@ export const read = async (folders) => {
     }
 };
 /**
- * Records the fingerprint for these folders after a successful run. Writes
+ * Records the fingerprint for these targets after a successful run. Writes
  * atomically (temp file + rename) so a concurrent read never sees a half-file.
  */
-export const write = async (folders, fp) => {
+export const write = async (paths, fp) => {
     await mkdir(cacheDir, { recursive: true });
-    const target = entryPath(folders);
-    const entry = { folders, fingerprint: fp, ts: Date.now() };
+    const target = entryPath(paths);
+    const entry = { folders: paths, fingerprint: fp, ts: Date.now() };
     const tmp = `${target}.${process.pid}.tmp`;
     await writeFile(tmp, JSON.stringify(entry, null, 2));
     await rename(tmp, target);

package/dist/core/output.d.ts

@@ -1,4 +1,13 @@
 import type { LogsCollector } from "./log-collector/LogsCollector.ts";
+/**
+ * Absolute path to this run's output folder — `logs/<name>/<date>/<time>/`, where
+ * `run.log`, `run.jsonl`, and snapshots live. Exposed so actions can drop their
+ * own **artifacts** into the same per-run folder (one folder per run; one run per
+ * process). The folder is created on first access — synchronously, so a caller
+ * can write into it in the same tick — and the path is absolute so it's safe to
+ * hand to a child process with a different cwd.
+ */
+export declare const artifactsFolder: () => string;
 /**
  * Drains the collected log to two files in the run's output folder (the common
  * `logs/<name>/<date>/<time>/` convention, local time):

package/dist/core/output.js

@@ -1,4 +1,4 @@
-import { createWriteStream } from "node:fs";
+import { createWriteStream, mkdirSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { log } from "./log-collector/global.js";
@@ -24,6 +24,23 @@ const runDir = () => {
 };
 let made;
 const ensureDir = () => (made ??= mkdir(runDir(), { recursive: true }).then(() => { }));
+let ensuredSync = false;
+/**
+ * Absolute path to this run's output folder — `logs/<name>/<date>/<time>/`, where
+ * `run.log`, `run.jsonl`, and snapshots live. Exposed so actions can drop their
+ * own **artifacts** into the same per-run folder (one folder per run; one run per
+ * process). The folder is created on first access — synchronously, so a caller
+ * can write into it in the same tick — and the path is absolute so it's safe to
+ * hand to a child process with a different cwd.
+ */
+export const artifactsFolder = () => {
+    const abs = path.resolve(runDir());
+    if (!ensuredSync) {
+        mkdirSync(abs, { recursive: true });
+        ensuredSync = true;
+    }
+    return abs;
+};
 /** A compact header block for the top of run.log — legend + run identity. */
 const logHeader = () => {
     const now = new Date();

package/dist/core/spin.d.ts

@@ -32,6 +32,12 @@ export interface SpinContext {
     readonly cancel: Run["cancel"];
     /** The run's abort signal — honor it to stop early. */
     readonly signal: AbortSignal;
+    /**
+     * Absolute path to this run's output folder (`logs/<name>/<date>/<time>/`),
+     * created up front. Hand it to actions (or use `ctx.artifactsFolder` inside
+     * one) to write artifacts beside `run.log`.
+     */
+    readonly artifactsFolder: string;
 }
 /** 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>;

package/dist/core/spin.js

@@ -1,5 +1,6 @@
 import { action } from "./action.js";
 import { run } from "./run.js";
+import { artifactsFolder } from "./output.js";
 export function spin(a, b) {
     const [options, body] = typeof a === "function" ? [{}, a] : [a, b];
     const { drain: autoDrain = true, ...runOptions } = options;
@@ -20,7 +21,13 @@ export function spin(a, b) {
             host.run(instance);
             return instance;
         };
-        await body({ nod, drain: startDrain, cancel: () => host.cancel(), signal });
+        await body({
+            nod,
+            drain: startDrain,
+            cancel: () => host.cancel(),
+            signal,
+            artifactsFolder: artifactsFolder(),
+        });
     });
     host = run(runOptions, hosted());
     if (autoDrain)

package/dist/index.d.ts

@@ -23,4 +23,5 @@ export type { Logger, LogEntry, LogInput, SubscribeOptions, } from "./core/log-c
 export { log } from "./core/log-collector/global.ts";
 export { snapshot, captureSnapshot } from "./core/output.ts";
 export type { SnapshotRef } from "./core/output.ts";
+export { artifactsFolder } from "./core/output.ts";
 export { fingerprint, cacheDir } from "./core/folder-cache.ts";

package/dist/index.js

@@ -23,7 +23,12 @@ export { LogsCollector } from "./core/log-collector/LogsCollector.js";
 export { log } from "./core/log-collector/global.js";
 // ── Snapshots ──────────────────────────────────────────────────────────────
 export { snapshot, captureSnapshot } from "./core/output.js";
+// ── Artifacts ────────────────────────────────────────────────────────────────
+// This run's output folder (absolute) — also on the `spin`/action `ctx`. Import
+// it directly for artifact-writing helpers that aren't inside an action.
+export { artifactsFolder } from "./core/output.js";
 // ── Folder cache ─────────────────────────────────────────────────────────────
-// Backs the `.withCache(...folders)` method on instances; exported for scripts
-// that want to inspect or manually invalidate the cache.
+// Backs the `.withCache(...inputs)` method on instances (fingerprints an
+// action's input files/folders, not its outputs); exported for scripts that
+// want to inspect or manually invalidate the cache.
 export { fingerprint, cacheDir } from "./core/folder-cache.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "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",