omkit 0.0.3 → 0.0.5

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

@@ -63,18 +63,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,6 @@
 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";
 /** A promise paired with its settlers, for the set-once handle. */
 const deferred = () => {
     let resolve;
@@ -105,23 +105,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/index.js

@@ -24,6 +24,7 @@ export { log } from "./core/log-collector/global.js";
 // ── Snapshots ──────────────────────────────────────────────────────────────
 export { snapshot, captureSnapshot } 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.5",
   "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",