opensquid 0.5.395

package/dist/codex/store.js

@@ -0,0 +1,205 @@
+/**
+ * Codex local storage — filesystem layer for installed codexes.
+ *
+ * Stores codex YAML + lesson markdown files at <root>/codexes/<id>/.
+ * Engine sees none of this; it only stores the resulting lessons that
+ * opensquid seeds via `lesson.create` with `authored_by: Pack(<id>)`.
+ *
+ * Resolution order for the data root:
+ *   1. `rootDir` parameter (explicit override; used by tests)
+ *   2. `OPENSQUID_HOME` env var
+ *   3. `LOOP_HOME` env var (engine-shared)
+ *   4. `~/.opensquid/` default
+ */
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parseCodexYaml } from "./parse.js";
+import { stringify as stringifyYaml } from "yaml";
+export class CodexStoreError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = "CodexStoreError";
+    }
+}
+// ---------------------------------------------------------------------
+// Data root resolution
+// ---------------------------------------------------------------------
+/**
+ * Resolve the opensquid data root.
+ *
+ * Order: explicit rootDir → OPENSQUID_HOME → LOOP_HOME → ~/.opensquid
+ */
+export function resolveDataRoot(rootDir) {
+    if (rootDir)
+        return rootDir;
+    if (process.env.OPENSQUID_HOME)
+        return process.env.OPENSQUID_HOME;
+    if (process.env.LOOP_HOME)
+        return process.env.LOOP_HOME;
+    return path.join(os.homedir(), ".opensquid");
+}
+/** Directory holding all installed codexes. */
+export function codexesDir(rootDir) {
+    return path.join(resolveDataRoot(rootDir), "codexes");
+}
+/** Directory for a specific codex by id. */
+export function codexDir(id, rootDir) {
+    return path.join(codexesDir(rootDir), id);
+}
+// ---------------------------------------------------------------------
+// Id validation
+// ---------------------------------------------------------------------
+const CODEX_ID_RE = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+/**
+ * Validate a codex id: lowercase alphanumeric + `._-`, max 128 chars,
+ * cannot start with `._-`. Prevents path traversal and ambiguous names.
+ */
+export function validateCodexId(id) {
+    if (!CODEX_ID_RE.test(id)) {
+        throw new CodexStoreError("INVALID_ID", `codex id "${id}" is invalid (must match /^[a-z0-9][a-z0-9._-]{0,127}$/)`);
+    }
+}
+// ---------------------------------------------------------------------
+// Filesystem helpers
+// ---------------------------------------------------------------------
+async function ensureDir(dir) {
+    await fs.mkdir(dir, { recursive: true });
+}
+async function readIfExists(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw new CodexStoreError("READ_FAILED", `read failed: ${filePath}`, err);
+    }
+}
+async function pathExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------
+/**
+ * Install a codex into local storage.
+ *
+ * Writes `codex.yaml` at the canonical path. If `force=false` and a
+ * codex with this id is already installed, throws ALREADY_INSTALLED.
+ */
+export async function installCodex(codex, options = {}) {
+    validateCodexId(codex.id);
+    const dir = codexDir(codex.id, options.rootDir);
+    const manifestPath = path.join(dir, "codex.yaml");
+    if (!options.force && (await pathExists(manifestPath))) {
+        throw new CodexStoreError("ALREADY_INSTALLED", `codex "${codex.id}" is already installed at ${dir} (use force to overwrite)`);
+    }
+    try {
+        await ensureDir(dir);
+        const yaml = stringifyYaml(codex);
+        await fs.writeFile(manifestPath, yaml, "utf8");
+    }
+    catch (err) {
+        throw new CodexStoreError("WRITE_FAILED", `failed to write codex "${codex.id}"`, err);
+    }
+    return { id: codex.id, path: dir };
+}
+/**
+ * Load an installed codex by id.
+ *
+ * Reads + parses `codex.yaml`. Throws NOT_FOUND if not installed, or
+ * PARSE_FAILED if the manifest is malformed.
+ */
+export async function getCodex(id, options = {}) {
+    validateCodexId(id);
+    const manifestPath = path.join(codexDir(id, options.rootDir), "codex.yaml");
+    const content = await readIfExists(manifestPath);
+    if (content === null) {
+        throw new CodexStoreError("NOT_FOUND", `codex "${id}" not installed at ${manifestPath}`);
+    }
+    try {
+        return parseCodexYaml(content);
+    }
+    catch (err) {
+        throw new CodexStoreError("PARSE_FAILED", `codex "${id}" manifest is malformed`, err);
+    }
+}
+/**
+ * List all installed codex ids.
+ *
+ * Scans `<root>/codexes/` for directories that contain a `codex.yaml`.
+ * Directories without a manifest are skipped (partial installs, etc.).
+ * Returns ids in sorted order.
+ */
+export async function listCodexes(options = {}) {
+    const dir = codexesDir(options.rootDir);
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw new CodexStoreError("READ_FAILED", `failed to list codexes at ${dir}`, err);
+    }
+    const ids = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (!CODEX_ID_RE.test(entry.name))
+            continue;
+        const manifest = path.join(dir, entry.name, "codex.yaml");
+        if (await pathExists(manifest)) {
+            ids.push(entry.name);
+        }
+    }
+    ids.sort();
+    return ids;
+}
+/**
+ * Remove an installed codex.
+ *
+ * Deletes the entire `<root>/codexes/<id>/` directory. Returns true if
+ * the codex existed and was removed; false if it wasn't installed.
+ * Does NOT touch the engine's lesson store — the caller is responsible
+ * for retiring the codex's seeded lessons via the engine RPC first.
+ */
+export async function removeCodex(id, options = {}) {
+    validateCodexId(id);
+    const dir = codexDir(id, options.rootDir);
+    if (!(await pathExists(dir)))
+        return false;
+    try {
+        await fs.rm(dir, { recursive: true, force: true });
+        return true;
+    }
+    catch (err) {
+        throw new CodexStoreError("WRITE_FAILED", `failed to remove codex "${id}"`, err);
+    }
+}
+/**
+ * Resolve the path to a content file (lesson body, reference doc) inside
+ * a codex. Used by the orchestrator when bank_strategy requires lazy
+ * fetching the full body. Does NOT read the file — just returns the path.
+ */
+export function codexContentPath(id, relativePath, options = {}) {
+    validateCodexId(id);
+    // Refuse paths that try to escape the codex dir.
+    const dir = codexDir(id, options.rootDir);
+    const resolved = path.resolve(dir, relativePath);
+    if (!resolved.startsWith(dir + path.sep) && resolved !== dir) {
+        throw new CodexStoreError("INVALID_ID", `relative path "${relativePath}" escapes codex root`);
+    }
+    return resolved;
+}

package/dist/codex/store.js.map

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

package/dist/codex/store.test.js

@@ -0,0 +1,242 @@
+import * as crypto from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { CodexStoreError, codexContentPath, codexDir, codexesDir, getCodex, installCodex, listCodexes, removeCodex, resolveDataRoot, validateCodexId, } from "./store.js";
+// ---------------------------------------------------------------------
+// Per-test temp directory isolation
+// ---------------------------------------------------------------------
+let tmpRoot;
+beforeEach(async () => {
+    tmpRoot = path.join(os.tmpdir(), `opensquid-codex-test-${crypto.randomUUID()}`);
+    await fs.mkdir(tmpRoot, { recursive: true });
+});
+afterEach(async () => {
+    await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+// Test fixtures
+function focused(id) {
+    return {
+        id,
+        version: "1.0.0",
+        foundation: { methodologies: ["tdd"] },
+        detected_by: [{ kind: "user_pinned" }],
+        activation_scope: "user",
+    };
+}
+// ---------------------------------------------------------------------
+// resolveDataRoot
+// ---------------------------------------------------------------------
+describe("resolveDataRoot", () => {
+    const origOpenSquid = process.env.OPENSQUID_HOME;
+    const origLoop = process.env.LOOP_HOME;
+    afterEach(() => {
+        if (origOpenSquid === undefined)
+            delete process.env.OPENSQUID_HOME;
+        else
+            process.env.OPENSQUID_HOME = origOpenSquid;
+        if (origLoop === undefined)
+            delete process.env.LOOP_HOME;
+        else
+            process.env.LOOP_HOME = origLoop;
+    });
+    it("prefers explicit rootDir over everything else", () => {
+        process.env.OPENSQUID_HOME = "/from-env";
+        expect(resolveDataRoot("/explicit")).toBe("/explicit");
+    });
+    it("uses OPENSQUID_HOME when no explicit rootDir", () => {
+        process.env.OPENSQUID_HOME = "/from-os-home";
+        process.env.LOOP_HOME = "/from-loop-home";
+        expect(resolveDataRoot()).toBe("/from-os-home");
+    });
+    it("falls back to LOOP_HOME", () => {
+        delete process.env.OPENSQUID_HOME;
+        process.env.LOOP_HOME = "/from-loop-home";
+        expect(resolveDataRoot()).toBe("/from-loop-home");
+    });
+    it("defaults to ~/.opensquid when no env set", () => {
+        delete process.env.OPENSQUID_HOME;
+        delete process.env.LOOP_HOME;
+        expect(resolveDataRoot()).toBe(path.join(os.homedir(), ".opensquid"));
+    });
+});
+// ---------------------------------------------------------------------
+// validateCodexId
+// ---------------------------------------------------------------------
+describe("validateCodexId", () => {
+    it("accepts standard ids", () => {
+        expect(() => validateCodexId("react-19")).not.toThrow();
+        expect(() => validateCodexId("fullstack-react-atomic")).not.toThrow();
+        expect(() => validateCodexId("scanpy.v1")).not.toThrow();
+        expect(() => validateCodexId("a")).not.toThrow();
+        expect(() => validateCodexId("123tools")).not.toThrow();
+    });
+    it("rejects path traversal attempts", () => {
+        expect(() => validateCodexId("../escape")).toThrow(CodexStoreError);
+        expect(() => validateCodexId("a/b")).toThrow(CodexStoreError);
+        expect(() => validateCodexId("a\\b")).toThrow(CodexStoreError);
+    });
+    it("rejects uppercase", () => {
+        expect(() => validateCodexId("React-19")).toThrow(CodexStoreError);
+    });
+    it("rejects empty + dot/dash leading", () => {
+        expect(() => validateCodexId("")).toThrow(CodexStoreError);
+        expect(() => validateCodexId(".hidden")).toThrow(CodexStoreError);
+        expect(() => validateCodexId("-leading")).toThrow(CodexStoreError);
+    });
+    it("rejects >128 chars", () => {
+        expect(() => validateCodexId("a".repeat(129))).toThrow(CodexStoreError);
+    });
+});
+// ---------------------------------------------------------------------
+// installCodex / getCodex round-trip
+// ---------------------------------------------------------------------
+describe("installCodex + getCodex round-trip", () => {
+    it("installs and retrieves a focused codex", async () => {
+        const c = focused("react-19");
+        const res = await installCodex(c, { rootDir: tmpRoot });
+        expect(res.id).toBe("react-19");
+        expect(res.path).toBe(codexDir("react-19", tmpRoot));
+        const loaded = await getCodex("react-19", { rootDir: tmpRoot });
+        expect(loaded.id).toBe("react-19");
+        expect(loaded.version).toBe("1.0.0");
+    });
+    it("creates the codex directory + codex.yaml manifest", async () => {
+        await installCodex(focused("x"), { rootDir: tmpRoot });
+        const manifest = path.join(codexDir("x", tmpRoot), "codex.yaml");
+        const stat = await fs.stat(manifest);
+        expect(stat.isFile()).toBe(true);
+    });
+    it("throws ALREADY_INSTALLED on re-install without force", async () => {
+        await installCodex(focused("x"), { rootDir: tmpRoot });
+        await expect(installCodex(focused("x"), { rootDir: tmpRoot })).rejects.toMatchObject({
+            code: "ALREADY_INSTALLED",
+        });
+    });
+    it("overwrites with force=true", async () => {
+        const v1 = focused("x");
+        v1.version = "1.0.0";
+        await installCodex(v1, { rootDir: tmpRoot });
+        const v2 = focused("x");
+        v2.version = "2.0.0";
+        await installCodex(v2, { rootDir: tmpRoot, force: true });
+        const loaded = await getCodex("x", { rootDir: tmpRoot });
+        expect(loaded.version).toBe("2.0.0");
+    });
+    it("installs composite codex", async () => {
+        const composite = {
+            id: "fullstack",
+            kind: "composite",
+            version: "1.0.0",
+            includes: [
+                { id: "react", semver: ">=18" },
+                { id: "tdd", semver: ">=1" },
+            ],
+        };
+        await installCodex(composite, { rootDir: tmpRoot });
+        const loaded = await getCodex("fullstack", { rootDir: tmpRoot });
+        expect(loaded.kind).toBe("composite");
+    });
+    it("rejects invalid codex id at install", async () => {
+        const bad = focused("Bad-Id");
+        await expect(installCodex(bad, { rootDir: tmpRoot })).rejects.toMatchObject({
+            code: "INVALID_ID",
+        });
+    });
+});
+// ---------------------------------------------------------------------
+// getCodex error paths
+// ---------------------------------------------------------------------
+describe("getCodex error paths", () => {
+    it("throws NOT_FOUND when codex is not installed", async () => {
+        await expect(getCodex("ghost", { rootDir: tmpRoot })).rejects.toMatchObject({
+            code: "NOT_FOUND",
+        });
+    });
+    it("throws PARSE_FAILED on malformed manifest", async () => {
+        const dir = codexDir("malformed", tmpRoot);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, "codex.yaml"), "id: x\n  bad: indentation: here", "utf8");
+        await expect(getCodex("malformed", { rootDir: tmpRoot })).rejects.toMatchObject({
+            code: "PARSE_FAILED",
+        });
+    });
+    it("throws INVALID_ID for path-escaping ids", async () => {
+        await expect(getCodex("../escape", { rootDir: tmpRoot })).rejects.toMatchObject({
+            code: "INVALID_ID",
+        });
+    });
+});
+// ---------------------------------------------------------------------
+// listCodexes
+// ---------------------------------------------------------------------
+describe("listCodexes", () => {
+    it("returns [] when codexes/ dir doesn't exist", async () => {
+        expect(await listCodexes({ rootDir: tmpRoot })).toEqual([]);
+    });
+    it("returns sorted list of installed ids", async () => {
+        await installCodex(focused("zebra"), { rootDir: tmpRoot });
+        await installCodex(focused("apple"), { rootDir: tmpRoot });
+        await installCodex(focused("mango"), { rootDir: tmpRoot });
+        expect(await listCodexes({ rootDir: tmpRoot })).toEqual(["apple", "mango", "zebra"]);
+    });
+    it("skips directories without codex.yaml (partial installs)", async () => {
+        await installCodex(focused("complete"), { rootDir: tmpRoot });
+        // Create a stray directory without a manifest.
+        await fs.mkdir(path.join(codexesDir(tmpRoot), "partial"), {
+            recursive: true,
+        });
+        expect(await listCodexes({ rootDir: tmpRoot })).toEqual(["complete"]);
+    });
+    it("skips directories with invalid id syntax", async () => {
+        await installCodex(focused("valid"), { rootDir: tmpRoot });
+        await fs.mkdir(path.join(codexesDir(tmpRoot), "Bad-Id"), {
+            recursive: true,
+        });
+        await fs.writeFile(path.join(codexesDir(tmpRoot), "Bad-Id", "codex.yaml"), "id: Bad-Id\nversion: 1.0.0\n", "utf8");
+        expect(await listCodexes({ rootDir: tmpRoot })).toEqual(["valid"]);
+    });
+});
+// ---------------------------------------------------------------------
+// removeCodex
+// ---------------------------------------------------------------------
+describe("removeCodex", () => {
+    it("removes an installed codex, returns true", async () => {
+        await installCodex(focused("doomed"), { rootDir: tmpRoot });
+        expect(await removeCodex("doomed", { rootDir: tmpRoot })).toBe(true);
+        await expect(getCodex("doomed", { rootDir: tmpRoot })).rejects.toMatchObject({
+            code: "NOT_FOUND",
+        });
+    });
+    it("returns false when codex is not installed (idempotent)", async () => {
+        expect(await removeCodex("ghost", { rootDir: tmpRoot })).toBe(false);
+    });
+    it("recursively removes lesson bodies + companion files", async () => {
+        await installCodex(focused("with-content"), { rootDir: tmpRoot });
+        const lessonDir = path.join(codexDir("with-content", tmpRoot), "lessons", "l1");
+        await fs.mkdir(lessonDir, { recursive: true });
+        await fs.writeFile(path.join(lessonDir, "lesson.md"), "# lesson", "utf8");
+        await removeCodex("with-content", { rootDir: tmpRoot });
+        await expect(fs.access(lessonDir)).rejects.toThrow();
+    });
+});
+// ---------------------------------------------------------------------
+// codexContentPath
+// ---------------------------------------------------------------------
+describe("codexContentPath", () => {
+    it("resolves a content path inside the codex", () => {
+        const p = codexContentPath("react-19", "lessons/x/lesson.md", {
+            rootDir: tmpRoot,
+        });
+        expect(p).toBe(path.join(codexDir("react-19", tmpRoot), "lessons", "x", "lesson.md"));
+    });
+    it("rejects path traversal in the relative path", () => {
+        expect(() => codexContentPath("react-19", "../../../etc/passwd", {
+            rootDir: tmpRoot,
+        })).toThrow(CodexStoreError);
+    });
+    it("rejects invalid codex id", () => {
+        expect(() => codexContentPath("../escape", "lesson.md", { rootDir: tmpRoot })).toThrow(CodexStoreError);
+    });
+});