@claudexor/artifact-store 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joi-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @claudexor/artifact-store
+
+Internal package of [Claudexor](https://github.com/razzant/claudexor) — Files-first canonical artifact store (repo-local .claudexor/runs layout).
+
+Published as part of the Claudexor toolchain; it follows the monorepo's
+lockstep version and has no separate semver contract. Use the `claudexor`
+CLI (or `@claudexor/cli`) as the supported entry point.

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+export interface RunPaths {
+    runId: string;
+    root: string;
+    contextDir: string;
+    attemptsDir: string;
+    reviewsDir: string;
+    findingsDir: string;
+    arbitrationDir: string;
+    finalDir: string;
+    eventsPath: string;
+}
+/**
+ * Files-first artifact store. Canonical artifacts live under
+ * `<repo>/.claudexor/`. Nothing here is a database; an optional SQLite index can
+ * be rebuilt from these files later.
+ */
+export declare class ArtifactStore {
+    readonly repoRoot: string;
+    readonly claudexorDir: string;
+    constructor(repoRoot: string, options?: {
+        claudexorDir?: string;
+    });
+    runsDir(): string;
+    workspacesDir(): string;
+    runPaths(runId: string): RunPaths;
+    /** Create the on-disk layout for a new run and return its paths. */
+    createRun(runId: string): RunPaths;
+    writeYaml(path: string, value: unknown): void;
+    writeJson(path: string, value: unknown): void;
+    writeText(path: string, text: string): void;
+    readYaml<T = unknown>(path: string): T | null;
+    /** List existing run ids (most-recent ordering is the caller's concern). */
+    listRuns(): string[];
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,aAAa;aAGI,QAAQ,EAAE,MAAM;IAF5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAEF,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO;IAIrF,OAAO,IAAI,MAAM;IAIjB,aAAa,IAAI,MAAM;IAIvB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ;IAuBjC,oEAAoE;IACpE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ;IAgBlC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAI7C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAI7C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI3C,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAU7C,4EAA4E;IAC5E,QAAQ,IAAI,MAAM,EAAE;CAGrB"}

package/dist/index.js

@@ -0,0 +1,85 @@
+import { join } from "node:path";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import { ensureDir, listDir, readTextSafe, writeJson, writeText } from "@claudexor/util";
+/**
+ * Files-first artifact store. Canonical artifacts live under
+ * `<repo>/.claudexor/`. Nothing here is a database; an optional SQLite index can
+ * be rebuilt from these files later.
+ */
+export class ArtifactStore {
+    repoRoot;
+    claudexorDir;
+    constructor(repoRoot, options = {}) {
+        this.repoRoot = repoRoot;
+        this.claudexorDir = options.claudexorDir ?? join(repoRoot, ".claudexor");
+    }
+    runsDir() {
+        return join(this.claudexorDir, "runs");
+    }
+    workspacesDir() {
+        return join(this.claudexorDir, "workspaces");
+    }
+    runPaths(runId) {
+        // Id-shape fence at the single owner of run-dir layout: a runId is one
+        // path SEGMENT, never a path. This blocks `../`-style ids from escaping
+        // `.claudexor/runs` for every caller (HTTP surfaces already resolve ids
+        // via registry lookup — this is the defense-in-depth floor beneath them,
+        // the same reasoning as the envelope-id validation in dispose()).
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId)) {
+            throw new Error(`invalid run id '${runId}': a run id is a single path segment ([A-Za-z0-9._-], no separators)`);
+        }
+        const root = join(this.runsDir(), runId);
+        return {
+            runId,
+            root,
+            contextDir: join(root, "context"),
+            attemptsDir: join(root, "attempts"),
+            reviewsDir: join(root, "reviews"),
+            findingsDir: join(root, "findings"),
+            arbitrationDir: join(root, "arbitration"),
+            finalDir: join(root, "final"),
+            eventsPath: join(root, "events.jsonl"),
+        };
+    }
+    /** Create the on-disk layout for a new run and return its paths. */
+    createRun(runId) {
+        const paths = this.runPaths(runId);
+        for (const dir of [
+            paths.root,
+            paths.contextDir,
+            paths.attemptsDir,
+            paths.reviewsDir,
+            paths.findingsDir,
+            paths.arbitrationDir,
+            paths.finalDir,
+        ]) {
+            ensureDir(dir);
+        }
+        return paths;
+    }
+    writeYaml(path, value) {
+        writeText(path, yamlStringify(value));
+    }
+    writeJson(path, value) {
+        writeJson(path, value);
+    }
+    writeText(path, text) {
+        writeText(path, text);
+    }
+    readYaml(path) {
+        const text = readTextSafe(path);
+        if (text === null)
+            return null;
+        try {
+            return yamlParse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** List existing run ids (most-recent ordering is the caller's concern). */
+    listRuns() {
+        return listDir(this.runsDir());
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@claudexor/artifact-store",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Files-first canonical artifact store (repo-local .claudexor/runs layout).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "yaml": "^2.6.1",
+    "@claudexor/util": "1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/razzant/claudexor.git",
+    "directory": "packages/artifact-store"
+  },
+  "homepage": "https://github.com/razzant/claudexor#readme",
+  "bugs": {
+    "url": "https://github.com/razzant/claudexor/issues"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}