@clemrig/flow 0.0.0-stage → 0.2.0

package/dist/system/store.js

@@ -0,0 +1,157 @@
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, readdir, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { join, resolve } from "node:path";
+const isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+function isRetryCounts(value) {
+    return (isRecord(value) &&
+        Object.values(value).every((count) => Number.isSafeInteger(count) && count >= 1));
+}
+const finiteNonnegative = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+const isUsage = (value) => isRecord(value) &&
+    ["input", "output", "cacheRead", "cacheWrite", "costUsd"].every((key) => finiteNonnegative(value[key]));
+function isRunMetrics(value) {
+    if (!isRecord(value) || !isUsage(value.usage))
+        return false;
+    const counts = value.usage;
+    return (["responses", "missing"].every((key) => Number.isSafeInteger(counts[key]) && finiteNonnegative(counts[key])) &&
+        (value.sessions === undefined ||
+            (isRecord(value.sessions) &&
+                Object.values(value.sessions).every(isUsage))));
+}
+/** Each runtime's version and connection, as text. */
+const isRuntimes = (value) => isRecord(value) &&
+    Object.values(value).every((detail) => typeof detail === "string");
+/** No run has this ID, or none can: unlike a read error, asking again will not find it. */
+export class UnknownRunError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnknownRunError";
+    }
+}
+/** Whether `path` is a directory; `undefined` when nothing is there. */
+export async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/** `.flow/runs/` of `dir`: where runs are kept unless the caller chooses another directory. */
+export function defaultRunsDir(dir) {
+    return resolve(dir, ".flow", "runs");
+}
+/** Creates `.flow/` in `dir`, with a `.gitignore` that keeps its private runs out of Git; an existing `.flow/` is left as it is. */
+export async function createFlowDirectory(dir) {
+    const flowDir = join(dir, ".flow");
+    try {
+        await mkdir(flowDir);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        if (!(await isDirectory(flowDir)))
+            throw new Error(`.flow is not a directory: ${flowDir}`);
+        return;
+    }
+    await writeFile(join(flowDir, ".gitignore"), "*\n");
+}
+/** A new run ID: its creation time, then a random suffix, so that IDs sort in creation order. */
+export function newRunId() {
+    return `${Date.now()}-${randomUUID().slice(0, 8)}`;
+}
+/** One run's directory: `state.json` and its `events.jsonl` journal. */
+export class FileRunStore {
+    directory;
+    runId;
+    constructor(runsDir, runId) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(runId))
+            throw new UnknownRunError("Invalid run ID");
+        this.runId = runId;
+        // Absolute: runtimes get it while they work in another directory.
+        this.directory = resolve(runsDir, runId);
+    }
+    /** Run IDs in order: they start with their creation time. */
+    static async list(runsDir) {
+        try {
+            return (await readdir(runsDir, { withFileTypes: true }))
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => entry.name)
+                .sort();
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+    }
+    async save(state) {
+        if (state.id !== this.runId)
+            throw new Error("Run state ID does not match store");
+        await mkdir(this.directory, { recursive: true });
+        const temporary = join(this.directory, `state-${randomUUID()}.tmp`);
+        try {
+            await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, {
+                mode: 0o600,
+            });
+            await rename(temporary, join(this.directory, "state.json"));
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    async load() {
+        let text;
+        try {
+            text = await readFile(join(this.directory, "state.json"), "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                throw new UnknownRunError(`Unknown run ${this.runId}`);
+            throw error;
+        }
+        const state = JSON.parse(text);
+        if (state?.version !== 4 ||
+            state.id !== this.runId ||
+            typeof state.workflow !== "string" ||
+            !state.workflow.trim() ||
+            !["running", "completed", "failed"].includes(state.status) ||
+            typeof state.stage !== "string" ||
+            typeof state.createdAt !== "string" ||
+            typeof state.updatedAt !== "string" ||
+            !isRecord(state.input) ||
+            !isRecord(state.data) ||
+            (state.retries !== undefined && !isRetryCounts(state.retries)) ||
+            (state.metrics !== undefined && !isRunMetrics(state.metrics)) ||
+            (state.runtimes !== undefined && !isRuntimes(state.runtimes)))
+            throw new Error("Unsupported or mismatched persisted run; runs created by earlier flow versions are not readable");
+        return state;
+    }
+    async event(event) {
+        if (event.runId !== this.runId)
+            throw new Error("Event run ID does not match store");
+        await mkdir(this.directory, { recursive: true });
+        await appendFile(join(this.directory, "events.jsonl"), `${JSON.stringify(event)}\n`, { mode: 0o600 });
+    }
+    /** Recorded events; a last line still being written is ignored. */
+    async events() {
+        let text;
+        try {
+            text = await readFile(join(this.directory, "events.jsonl"), "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+        const lines = text.split("\n");
+        // Only lines ended by a newline are complete.
+        lines.pop();
+        return lines
+            .filter((line) => line.trim())
+            .map((line) => JSON.parse(line));
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/system/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/system/store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@clemrig/flow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Write agent workflows in TypeScript and run them with Claude Code or Pi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clementchesneau/clemrig-factory-v2.git",
+    "directory": "packages/flow"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "zod": "4.6.5"
+  }
+}