omkit 0.0.1 → 0.0.2

package/dist/actions/prompt.js

@@ -74,7 +74,11 @@ export const prompt = action("Prompt")
                 via = "input";
             }
             else {
-                logs.append({ source: "Prompt", level: "info", message: `invalid answer "${raw}", using default` });
+                logs.append({
+                    source: "Prompt",
+                    level: "info",
+                    message: `invalid answer "${raw}", using default`,
+                });
                 via = "default";
             }
         }

package/dist/actions/tail-log.js

@@ -20,7 +20,7 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
     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 { source = name, level = "info", fromStart = false, encoding = "utf8", debounceMs = 50, } = opts;
     let pos = 0; // bytes consumed so far
     let pending = ""; // partial trailing line, buffered until its newline
     // Append every complete line in `text`, keeping any remainder for next time.
@@ -99,6 +99,9 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
     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)" : ""}` });
     if (fromStart)
         pump();
     const watcher = fsWatch(dir, (_event, filename) => {

package/dist/core/action.d.ts

@@ -62,6 +62,19 @@ export interface ActionInstance<Result = unknown, Events extends object = NoEven
      * subscriptions; `once` is the awaitable, one-value form.
      */
     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.
+     * 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(...folders: string[]): AnyActionInstance;
 }
 /**
  * Any constructed instance, whatever its result, events, or handle. The launch

package/dist/core/action.js

@@ -1,5 +1,6 @@
 import { events } from "./events.js";
 import { createProc } from "./process.js";
+import { fingerprint, read, write, resolveFolders } from "./folder-cache.js";
 /** A promise paired with its settlers, for the set-once handle. */
 const deferred = () => {
     let resolve;
@@ -103,6 +104,27 @@ const build = (name, exec) => {
             once(key) {
                 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
+            // 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) {
+                // 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);
+                return action(name).run(async (ctx) => {
+                    const fp = await fingerprint(dirs);
+                    if ((await read(dirs)) === 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
+                    return result;
+                })();
+            },
         };
         return instance;
     };

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

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ *
+ * Entries live under `node_modules/.cache/omkit/` (conventional, gitignored) —
+ * one JSON file per set of folders, 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.
+ */
+export declare const resolveFolders: (folders: 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.
+ */
+export declare const fingerprint: (folders: string[]) => Promise<string>;
+/**
+ * Reads the fingerprint stored for these folders, 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>;
+/**
+ * Records the fingerprint for these folders 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>;

package/dist/core/folder-cache.js

@@ -0,0 +1,90 @@
+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.
+ *
+ * Entries live under `node_modules/.cache/omkit/` (conventional, gitignored) —
+ * one JSON file per set of folders, 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.
+ */
+export const resolveFolders = (folders) => folders.map((folder) => {
+    if (!isAbsolute(folder)) {
+        throw new Error(`withCache: folder path must be absolute, got "${folder}"`);
+    }
+    return resolve(folder);
+});
+/**
+ * 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.
+ */
+export const fingerprint = async (folders) => {
+    const dirs = resolveFolders(folders);
+    const entries = [];
+    for (const folder of dirs) {
+        let rels;
+        try {
+            rels = await readdir(folder, { recursive: true });
+        }
+        catch {
+            continue; // folder missing/unreadable — contributes no entries
+        }
+        for (const rel of rels) {
+            const abs = join(folder, rel);
+            try {
+                const stats = await stat(abs);
+                if (stats.isFile())
+                    entries.push(`${folder}\0${rel}\0${stats.mtimeMs}\0${stats.size}`);
+            }
+            catch {
+                // entry vanished between readdir and stat — skip
+            }
+        }
+    }
+    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");
+    return join(cacheDir, `${key}.json`);
+};
+/**
+ * Reads the fingerprint stored for these folders, or `undefined` when there's
+ * no cache (absent, unreadable, or malformed — all treated as a miss).
+ */
+export const read = async (folders) => {
+    try {
+        const raw = await readFile(entryPath(folders), "utf8");
+        const entry = JSON.parse(raw);
+        return typeof entry.fingerprint === "string" ? entry.fingerprint : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Records the fingerprint for these folders after a successful run. Writes
+ * atomically (temp file + rename) so a concurrent read never sees a half-file.
+ */
+export const write = async (folders, fp) => {
+    await mkdir(cacheDir, { recursive: true });
+    const target = entryPath(folders);
+    const entry = { folders, 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.d.ts

@@ -23,3 +23,4 @@ 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 { fingerprint, cacheDir } from "./core/folder-cache.ts";

package/dist/index.js

@@ -23,3 +23,7 @@ export { LogsCollector } from "./core/log-collector/LogsCollector.js";
 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.
+export { fingerprint, cacheDir } from "./core/folder-cache.js";

package/package.json

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