opensquid 0.5.395

package/dist/codex/parse.js

@@ -0,0 +1,309 @@
+/**
+ * Codex YAML parsing + runtime validation.
+ *
+ * Authoritative parse for codex.yaml files. Used by `opensquid codex
+ * install <path>` to validate before storing locally. Foreign-format
+ * imports (superpowers SKILL.md, ECC, etc.) come pre-converted to
+ * native codex YAML via LLM at install time — this parser sees the
+ * native shape only.
+ */
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+// ---------------------------------------------------------------------
+// Primitive schemas
+// ---------------------------------------------------------------------
+const CodexToolSchema = z.object({
+    name: z.string().min(1),
+    semver: z.string().optional(),
+});
+const CodexFoundationSchema = z.object({
+    tools: z.array(CodexToolSchema).optional(),
+    domains: z.array(z.string()).optional(),
+    methodologies: z.array(z.string()).optional(),
+});
+const ActivationScopeSchema = z.enum([
+    "project",
+    "user",
+    "hybrid",
+    "team",
+    "global",
+]);
+const BankStrategySchema = z.enum([
+    "full",
+    "trigger_only",
+    "summary",
+    "none",
+]);
+// Detection — recursive type, defined via z.lazy()
+const DetectionSchema = z.lazy(() => z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("file_exists"), path: z.string().min(1) }),
+    z.object({ kind: z.literal("dir_exists"), path: z.string().min(1) }),
+    z.object({
+        kind: z.literal("file_match"),
+        path: z.string().min(1),
+        matches: z.record(z.string(), z.unknown()),
+    }),
+    z.object({
+        kind: z.literal("file_glob"),
+        pattern: z.string().min(1),
+        min_count: z.number().int().nonnegative().optional(),
+    }),
+    z.object({
+        kind: z.literal("memory_match"),
+        memory_kind: z.string().min(1),
+        value: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal("conversation_signal"),
+        contains: z.array(z.string()).min(1),
+    }),
+    z.object({ kind: z.literal("user_pinned") }),
+    z.object({
+        kind: z.literal("all_of"),
+        conditions: z.array(DetectionSchema).min(1),
+    }),
+    z.object({
+        kind: z.literal("any_of"),
+        conditions: z.array(DetectionSchema).min(1),
+    }),
+]));
+const TriggerSchema = z.union([
+    z.string().min(1),
+    z.object({
+        intent: z.string().min(1),
+        prescriptive_form: z.string().optional(),
+    }),
+]);
+const SeedLessonSchema = z.object({
+    id: z.string().min(1),
+    trigger: TriggerSchema,
+    priority: z.enum(["high", "medium", "low"]).optional(),
+    bank_strategy: BankStrategySchema.optional(),
+    body_path: z.string().min(1),
+    citations: z.array(z.string()).optional(),
+});
+const VerifyGateSchema = z.object({
+    id: z.string().min(1),
+    before: z.object({
+        tool_call: z.string().optional(),
+        file_pattern: z.string().optional(),
+        intent: z.string().optional(),
+    }),
+    require: z.array(z.record(z.string(), z.unknown())).min(1),
+});
+const MemoryTemplateSchema = z.object({
+    scan: z.string().min(1),
+    extract: z.array(z.string()).min(1),
+    memorize_as: z
+        .object({
+        kind: z.string().min(1),
+        scope: z.string().optional(),
+    })
+        .optional(),
+});
+const DocFetchSchema = z.object({
+    trigger: z.string().min(1),
+    url: z.string().url(),
+    ttl_days: z.number().int().positive().optional(),
+});
+const ReferenceDocSchema = z.object({
+    path: z.string().min(1),
+    bank_strategy: BankStrategySchema.optional(),
+});
+// v0.6d: import provenance (set by the SKILL.md converter; absent on
+// natively-authored codexes).
+const SourceSchema = z.object({
+    kind: z.enum(["skill_md", "native"]),
+    original_variant: z.enum(["anthropic", "superpowers", "ecc", "hermes", "unknown"]).optional(),
+    original_name: z.string().optional(),
+    original_path: z.string().optional(),
+    imported_at: z.string().optional(),
+});
+const HeaderSchema = z.object({
+    id: z.string().min(1),
+    version: z.string().min(1),
+    author: z
+        .object({
+        name: z.string().optional(),
+        contact: z.string().optional(),
+    })
+        .optional(),
+    license: z.string().optional(),
+    description: z.string().optional(),
+    // v0.6d: optional import provenance + extensibility bucket. Both
+    // additive; pre-v0.6d codex.yaml files parse unchanged.
+    source: SourceSchema.optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+// ---------------------------------------------------------------------
+// Composite vs focused — discriminated by `kind` field
+// ---------------------------------------------------------------------
+const CompositeCodexSchema = HeaderSchema.extend({
+    kind: z.literal("composite"),
+    includes: z
+        .array(z.object({
+        id: z.string().min(1),
+        semver: z.string().min(1),
+    }))
+        .min(1),
+});
+// ---------------------------------------------------------------------
+// Drift-as-codex section schemas (0.7.3+, additive)
+// ---------------------------------------------------------------------
+const DriftSeveritySchema = z.enum(["block", "warn"]);
+const DriftToolMatchSchema = z.enum(["Bash", "Edit", "Write", "*"]);
+const DriftTriggerSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("bash_contains"),
+        needle: z.string().min(1),
+        strip_quotes: z.boolean().optional(),
+    }),
+    z.object({
+        kind: z.literal("bash_regex"),
+        pattern: z.string().min(1),
+        strip_quotes: z.boolean().optional(),
+    }),
+    z.object({
+        kind: z.literal("text_regex"),
+        pattern: z.string().min(1),
+        field: z.string().min(1),
+    }),
+]);
+const DriftEntrySchema = z.object({
+    id: z.string().min(1),
+    tool: DriftToolMatchSchema,
+    trigger: DriftTriggerSchema,
+    lesson: z.string().min(1),
+    message: z.string().min(1),
+    severity: DriftSeveritySchema,
+});
+const WorkflowPhaseSchema = z.object({
+    name: z.string().min(1),
+    required: z.boolean(),
+    description: z.string().optional(),
+});
+const WorkflowEntrySchema = z.object({
+    id: z.string().min(1),
+    phases: z.array(WorkflowPhaseSchema).min(1),
+    enforce_on: z.array(z.string().min(1)).min(1),
+    description: z.string().optional(),
+});
+const ClaimEvidenceSchema = z.lazy(() => z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("tool_call"), tool: z.string().min(1) }),
+    z.object({ kind: z.literal("bash_contains"), needle: z.string().min(1) }),
+    z.object({ kind: z.literal("bash_regex"), pattern: z.string().min(1) }),
+    z.object({
+        kind: z.literal("input_contains"),
+        tool: z.string().min(1),
+        field: z.string().min(1),
+        needle: z.string().min(1),
+    }),
+    z.object({ kind: z.literal("any_of"), options: z.array(ClaimEvidenceSchema).min(1) }),
+    // 0.7.17 (chunk 3b): "any_tool" fulfills the claim if any tool
+    // was called this turn. Used by claim patterns like "audit-done"
+    // / "starting-now" where the proof of action is just doing work.
+    z.object({ kind: z.literal("any_tool") }),
+]));
+const ClaimEntrySchema = z.object({
+    id: z.string().min(1),
+    claim_pattern: z.string().min(1),
+    evidence: ClaimEvidenceSchema,
+    unfulfilled_message: z.string().min(1),
+    severity: DriftSeveritySchema,
+});
+const VersioningPolicySchema = z.object({
+    per_commit_required: z.boolean(),
+    allowed_slots: z.array(z.enum(["patch", "minor", "major"])).min(1),
+    slot_for: z
+        .object({
+        bug_fix: z.enum(["patch", "minor", "major"]).optional(),
+        feature: z.enum(["patch", "minor", "major"]).optional(),
+        breaking: z.enum(["patch", "minor", "major"]).optional(),
+    })
+        .optional(),
+});
+const PhaseLoggedPolicySchema = z.object({
+    workflow_id: z.string().min(1),
+    enforce_on: z.array(z.string().min(1)).min(1),
+});
+const PolicyEntrySchema = z.discriminatedUnion("kind", [
+    z.object({
+        id: z.string().min(1),
+        kind: z.literal("versioning"),
+        params: VersioningPolicySchema,
+    }),
+    z.object({
+        id: z.string().min(1),
+        kind: z.literal("phase_logged"),
+        params: PhaseLoggedPolicySchema,
+    }),
+]);
+const FocusedCodexSchema = HeaderSchema.extend({
+    kind: z.literal("focused").optional(),
+    foundation: CodexFoundationSchema.optional(),
+    activation_scope: ActivationScopeSchema.optional(),
+    detected_by: z.array(DetectionSchema).optional(),
+    seed_lessons: z.array(SeedLessonSchema).optional(),
+    verify_gates: z.array(VerifyGateSchema).optional(),
+    memory_templates: z.array(MemoryTemplateSchema).optional(),
+    doc_fetch: z.array(DocFetchSchema).optional(),
+    reference_docs: z.array(ReferenceDocSchema).optional(),
+    drifts: z.array(DriftEntrySchema).optional(),
+    workflows: z.array(WorkflowEntrySchema).optional(),
+    default_workflow_id: z.string().min(1).optional(),
+    claims: z.array(ClaimEntrySchema).optional(),
+    policies: z.array(PolicyEntrySchema).optional(),
+    evolves: z.boolean().optional(),
+});
+const CodexSchema = z.union([CompositeCodexSchema, FocusedCodexSchema]);
+// ---------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------
+export class CodexParseError extends Error {
+    issues;
+    constructor(message, issues) {
+        super(message);
+        this.issues = issues;
+        this.name = "CodexParseError";
+    }
+}
+// ---------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------
+/**
+ * Parse + validate a codex from a raw object (already-parsed YAML/JSON).
+ *
+ * Throws `CodexParseError` on schema violations with detailed issues.
+ */
+export function parseCodex(raw) {
+    const result = CodexSchema.safeParse(raw);
+    if (!result.success) {
+        throw new CodexParseError(`codex validation failed: ${result.error.issues
+            .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
+            .join("; ")}`, result.error.issues);
+    }
+    // safeParse with z.union returns one of the union branches — narrow.
+    const parsed = result.data;
+    if (parsed.kind === "composite") {
+        return parsed;
+    }
+    return parsed;
+}
+/**
+ * Parse a codex from a YAML string.
+ *
+ * Throws `CodexParseError` on YAML syntax error or schema violation.
+ */
+export function parseCodexYaml(source) {
+    let raw;
+    try {
+        raw = parseYaml(source);
+    }
+    catch (err) {
+        throw new CodexParseError(`codex YAML syntax error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (raw === null || typeof raw !== "object") {
+        throw new CodexParseError(`codex YAML must be a top-level object, got ${raw === null ? "null" : typeof raw}`);
+    }
+    return parseCodex(raw);
+}

package/dist/codex/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src.legacy/codex/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoBxB,wEAAwE;AACxE,oBAAoB;AACpB,wEAAwE;AAExE,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAEH,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,QAAQ,EAAE;IAC1C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACvC,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC9C,CAAC,CAAC;AAEH,MAAM,qBAAqB,GAAoC,CAAC,CAAC,IAAI,CAAC;IACpE,SAAS;IACT,MAAM;IACN,QAAQ;IACR,MAAM;IACN,QAAQ;CACT,CAAC,CAAC;AAEH,MAAM,kBAAkB,GAAiC,CAAC,CAAC,IAAI,CAAC;IAC9D,MAAM;IACN,cAAc;IACd,SAAS;IACT,MAAM;CACP,CAAC,CAAC;AAEH,mDAAmD;AACnD,MAAM,eAAe,GAA8B,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAC7D,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAC3B,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACrE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACpE,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;QAC7B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;KAC3C,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;QAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;KACrD,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC;QAC/B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;KACzB,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC;QACtC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;KACrC,CAAC;IACF,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;IAC5C,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;QACzB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;KAC5C,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;QACzB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;KAC5C,CAAC;CACH,CAAC,CACH,CAAC;AAEF,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC;IAC5B,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjB,CAAC,CAAC,MAAM,CAAC;QACP,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACzB,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACzC,CAAC;CACH,CAAC,CAAC;AAEH,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,OAAO,EAAE,aAAa;IACtB,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE;IACtD,aAAa,EAAE,kBAAkB,CAAC,QAAQ,EAAE;IAC5C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC;AAEH,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAChC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QACnC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC9B,CAAC;IACF,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAC3D,CAAC,CAAC;AAEH,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,WAAW,EAAE,CAAC;SACX,MAAM,CAAC;QACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC7B,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AAEH,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACjD,CAAC,CAAC;AAEH,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,aAAa,EAAE,kBAAkB,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAC;AAEH,qEAAqE;AACrE,8BAA8B;AAC9B,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACpC,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC7F,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,MAAM,EAAE,CAAC;SACN,MAAM,CAAC;QACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC3B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC/B,CAAC;SACD,QAAQ,EAAE;IACb,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,iEAAiE;IACjE,wDAAwD;IACxD,MAAM,EAAE,YAAY,CAAC,QAAQ,EAAE;IAC/B,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvD,CAAC,CAAC;AAEH,wEAAwE;AACxE,uDAAuD;AACvD,wEAAwE;AAExE,MAAM,oBAAoB,GAAG,YAAY,CAAC,MAAM,CAAC;IAC/C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IAC5B,QAAQ,EAAE,CAAC;SACR,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACrB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;KAC1B,CAAC,CACH;SACA,GAAG,CAAC,CAAC,CAAC;CACV,CAAC,CAAC;AAEH,wEAAwE;AACxE,oDAAoD;AACpD,wEAAwE;AAExE,MAAM,mBAAmB,GAAkC,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAErF,MAAM,oBAAoB,GAAmC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;AAEpG,MAAM,kBAAkB,GAAiC,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACpF,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC;QAChC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACzB,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;KACrC,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;QAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1B,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;KACrC,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;QAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;KACzB,CAAC;CACH,CAAC,CAAC;AAEH,MAAM,gBAAgB,GAA+B,CAAC,CAAC,MAAM,CAAC;IAC5D,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,IAAI,EAAE,oBAAoB;IAC1B,OAAO,EAAE,kBAAkB;IAC3B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,QAAQ,EAAE,mBAAmB;CAC9B,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAkC,CAAC,CAAC,MAAM,CAAC;IAClE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;IACrB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAkC,CAAC,CAAC,MAAM,CAAC;IAClE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAkC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CACrE,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAC3B,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACnE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACzE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC;QACjC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACxB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;KAC1B,CAAC;IACF,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACrF,+DAA+D;IAC/D,iEAAiE;IACjE,iEAAiE;IACjE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;CAC1C,CAAC,CACH,CAAC;AAEF,MAAM,gBAAgB,GAA+B,CAAC,CAAC,MAAM,CAAC;IAC5D,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,QAAQ,EAAE,mBAAmB;IAC7B,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtC,QAAQ,EAAE,mBAAmB;CAC9B,CAAC,CAAC;AAEH,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,mBAAmB,EAAE,CAAC,CAAC,OAAO,EAAE;IAChC,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,QAAQ,EAAE,CAAC;SACR,MAAM,CAAC;QACN,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE;QACvD,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE;QACvD,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE;KACzD,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AAEH,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAC9C,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAgC,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAClF,CAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACrB,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;QAC7B,MAAM,EAAE,sBAAsB;KAC/B,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACrB,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC;QAC/B,MAAM,EAAE,uBAAuB;KAChC,CAAC;CACH,CAAC,CAAC;AAEH,MAAM,kBAAkB,GAAG,YAAY,CAAC,MAAM,CAAC;IAC7C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE;IACrC,UAAU,EAAE,qBAAqB,CAAC,QAAQ,EAAE;IAC5C,gBAAgB,EAAE,qBAAqB,CAAC,QAAQ,EAAE;IAClD,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,QAAQ,EAAE;IAChD,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,QAAQ,EAAE;IAClD,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,QAAQ,EAAE;IAClD,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,QAAQ,EAAE;IAC1D,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE;IAC7C,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,QAAQ,EAAE;IACtD,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,QAAQ,EAAE;IAC5C,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,QAAQ,EAAE;IAClD,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACjD,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,QAAQ,EAAE;IAC5C,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,QAAQ,EAAE;IAC/C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAEH,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAExE,wEAAwE;AACxE,SAAS;AACT,wEAAwE;AAExE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAGtB;IAFlB,YACE,OAAe,EACC,MAAqB;QAErC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,WAAM,GAAN,MAAM,CAAe;QAGrC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,wEAAwE;AACxE,aAAa;AACb,wEAAwE;AAExE;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,eAAe,CACvB,4BAA4B,MAAM,CAAC,KAAK,CAAC,MAAM;aAC5C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aAC3D,IAAI,CAAC,IAAI,CAAC,EAAE,EACf,MAAM,CAAC,KAAK,CAAC,MAAM,CACpB,CAAC;IACJ,CAAC;IACD,qEAAqE;IACrE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC;IAC3B,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,OAAO,MAAwB,CAAC;IAClC,CAAC;IACD,OAAO,MAAsB,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,eAAe,CACvB,4BAA4B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC/E,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,MAAM,IAAI,eAAe,CACvB,8CAA8C,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,GAAG,EAAE,CACnF,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC"}

package/dist/codex/parse.test.js

@@ -0,0 +1,241 @@
+import { describe, expect, it } from "vitest";
+import { CodexParseError, parseCodex, parseCodexYaml } from "./parse.js";
+import { isCompositeCodex, isFocusedCodex } from "./types.js";
+describe("parseCodex — focused codex", () => {
+    it("accepts a minimal focused codex (id + version only)", () => {
+        const c = parseCodex({ id: "minimal", version: "1.0.0" });
+        expect(c.id).toBe("minimal");
+        expect(isFocusedCodex(c)).toBe(true);
+        expect(isCompositeCodex(c)).toBe(false);
+    });
+    it("accepts a fully-featured developer codex", () => {
+        const c = parseCodex({
+            id: "react-19",
+            version: "1.0.0",
+            author: { name: "anon", contact: "x@y.z" },
+            license: "MIT",
+            foundation: {
+                tools: [{ name: "react", semver: ">=19,<20" }],
+                domains: ["software-engineering", "frontend"],
+            },
+            activation_scope: "project",
+            detected_by: [
+                {
+                    kind: "file_match",
+                    path: "package.json",
+                    matches: { "dependencies.react": ">=19" },
+                },
+            ],
+            seed_lessons: [
+                {
+                    id: "atomic-search",
+                    trigger: "before creating a new React component",
+                    priority: "high",
+                    bank_strategy: "full",
+                    body_path: "lessons/atomic-search/lesson.md",
+                },
+            ],
+            verify_gates: [
+                {
+                    id: "atomic-boundary",
+                    before: { tool_call: "Write", file_pattern: "src/components/**/*.tsx" },
+                    require: [{ search_completed: "atoms/" }],
+                },
+            ],
+            doc_fetch: [
+                {
+                    trigger: "React hooks",
+                    url: "https://react.dev/reference/react/hooks",
+                    ttl_days: 30,
+                },
+            ],
+            evolves: true,
+        });
+        expect(c.id).toBe("react-19");
+        expect(isFocusedCodex(c)).toBe(true);
+        if (isFocusedCodex(c)) {
+            expect(c.foundation?.tools?.[0]?.name).toBe("react");
+            expect(c.seed_lessons).toHaveLength(1);
+            expect(c.evolves).toBe(true);
+        }
+    });
+    it("accepts a methodology-only codex (no tools, no domain)", () => {
+        const c = parseCodex({
+            id: "tdd",
+            version: "1.0.0",
+            foundation: { methodologies: ["tdd"] },
+            detected_by: [{ kind: "dir_exists", path: "tests/" }],
+        });
+        expect(isFocusedCodex(c)).toBe(true);
+    });
+    it("accepts a user-pinned codex (no filesystem signals)", () => {
+        const c = parseCodex({
+            id: "positive-discipline",
+            version: "1.0.0",
+            foundation: { domains: ["parenting"] },
+            activation_scope: "user",
+            detected_by: [{ kind: "user_pinned" }],
+        });
+        expect(isFocusedCodex(c)).toBe(true);
+        if (isFocusedCodex(c)) {
+            expect(c.activation_scope).toBe("user");
+        }
+    });
+    it("accepts structured trigger objects", () => {
+        const c = parseCodex({
+            id: "x",
+            version: "1.0.0",
+            seed_lessons: [
+                {
+                    id: "l1",
+                    trigger: {
+                        intent: "before doing X",
+                        prescriptive_form: "You MUST do X first",
+                    },
+                    body_path: "lessons/l1/lesson.md",
+                },
+            ],
+        });
+        expect(isFocusedCodex(c)).toBe(true);
+    });
+    it("accepts nested all_of / any_of detection", () => {
+        const c = parseCodex({
+            id: "x",
+            version: "1.0.0",
+            detected_by: [
+                {
+                    kind: "all_of",
+                    conditions: [
+                        { kind: "file_exists", path: "a" },
+                        {
+                            kind: "any_of",
+                            conditions: [
+                                { kind: "dir_exists", path: "b" },
+                                { kind: "dir_exists", path: "c" },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        });
+        expect(isFocusedCodex(c)).toBe(true);
+    });
+});
+describe("parseCodex — composite codex", () => {
+    it("accepts a composite codex (pure aggregator)", () => {
+        const c = parseCodex({
+            id: "fullstack-react-atomic",
+            kind: "composite",
+            version: "1.0.0",
+            includes: [
+                { id: "react", semver: ">=18,<20" },
+                { id: "tailwindcss", semver: ">=4" },
+                { id: "atomic-design", semver: ">=1" },
+            ],
+        });
+        expect(isCompositeCodex(c)).toBe(true);
+        if (isCompositeCodex(c)) {
+            expect(c.includes).toHaveLength(3);
+        }
+    });
+    it("rejects composite without includes", () => {
+        expect(() => parseCodex({ id: "x", kind: "composite", version: "1.0.0" })).toThrow(CodexParseError);
+    });
+    it("rejects composite with empty includes array", () => {
+        expect(() => parseCodex({ id: "x", kind: "composite", version: "1.0.0", includes: [] })).toThrow(CodexParseError);
+    });
+});
+describe("parseCodex — validation errors", () => {
+    it("rejects missing id", () => {
+        expect(() => parseCodex({ version: "1.0.0" })).toThrow(CodexParseError);
+    });
+    it("rejects missing version", () => {
+        expect(() => parseCodex({ id: "x" })).toThrow(CodexParseError);
+    });
+    it("rejects invalid activation_scope", () => {
+        expect(() => parseCodex({ id: "x", version: "1.0.0", activation_scope: "bogus" })).toThrow(CodexParseError);
+    });
+    it("rejects invalid bank_strategy", () => {
+        expect(() => parseCodex({
+            id: "x",
+            version: "1.0.0",
+            seed_lessons: [
+                {
+                    id: "l1",
+                    trigger: "t",
+                    body_path: "p",
+                    bank_strategy: "weird",
+                },
+            ],
+        })).toThrow(CodexParseError);
+    });
+    it("rejects unknown detection kind", () => {
+        expect(() => parseCodex({
+            id: "x",
+            version: "1.0.0",
+            detected_by: [{ kind: "bogus_kind", path: "x" }],
+        })).toThrow(CodexParseError);
+    });
+    it("rejects non-https URL in doc_fetch", () => {
+        expect(() => parseCodex({
+            id: "x",
+            version: "1.0.0",
+            doc_fetch: [{ trigger: "t", url: "not-a-url" }],
+        })).toThrow(CodexParseError);
+    });
+    it("includes structured zod issues in error", () => {
+        try {
+            parseCodex({ version: "1.0.0" });
+            expect.fail("expected throw");
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(CodexParseError);
+            const e = err;
+            expect(e.issues).toBeDefined();
+            expect(e.issues?.length).toBeGreaterThan(0);
+        }
+    });
+});
+describe("parseCodexYaml", () => {
+    it("parses minimal YAML", () => {
+        const yaml = `
+id: minimal
+version: 1.0.0
+`;
+        const c = parseCodexYaml(yaml);
+        expect(c.id).toBe("minimal");
+    });
+    it("parses fully-featured YAML round-trip", () => {
+        const yaml = `
+id: react-19
+version: 1.0.0
+foundation:
+  tools:
+    - { name: react, semver: ">=19,<20" }
+  domains: [software-engineering, frontend]
+activation_scope: project
+detected_by:
+  - kind: dir_exists
+    path: "src/components/atoms"
+seed_lessons:
+  - id: atomic-search
+    trigger: "before creating a component"
+    priority: high
+    bank_strategy: full
+    body_path: "lessons/atomic-search/lesson.md"
+evolves: true
+`;
+        const c = parseCodexYaml(yaml);
+        expect(isFocusedCodex(c)).toBe(true);
+        if (isFocusedCodex(c)) {
+            expect(c.foundation?.tools?.[0]?.name).toBe("react");
+            expect(c.detected_by?.[0]?.kind).toBe("dir_exists");
+        }
+    });
+    it("throws CodexParseError on YAML syntax error", () => {
+        expect(() => parseCodexYaml("id: x\n  bad: indentation: here")).toThrow(CodexParseError);
+    });
+    it("throws CodexParseError on non-object root", () => {
+        expect(() => parseCodexYaml("just a string")).toThrow(CodexParseError);
+    });
+});

package/dist/codex/store.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 type { Codex } from "./types.js";
+export type CodexStoreErrorCode = "NOT_FOUND" | "ALREADY_INSTALLED" | "INVALID_ID" | "READ_FAILED" | "WRITE_FAILED" | "PARSE_FAILED";
+export declare class CodexStoreError extends Error {
+    readonly code: CodexStoreErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(code: CodexStoreErrorCode, message: string, cause?: unknown | undefined);
+}
+/**
+ * Resolve the opensquid data root.
+ *
+ * Order: explicit rootDir → OPENSQUID_HOME → LOOP_HOME → ~/.opensquid
+ */
+export declare function resolveDataRoot(rootDir?: string): string;
+/** Directory holding all installed codexes. */
+export declare function codexesDir(rootDir?: string): string;
+/** Directory for a specific codex by id. */
+export declare function codexDir(id: string, rootDir?: string): string;
+/**
+ * Validate a codex id: lowercase alphanumeric + `._-`, max 128 chars,
+ * cannot start with `._-`. Prevents path traversal and ambiguous names.
+ */
+export declare function validateCodexId(id: string): void;
+/**
+ * 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 declare function installCodex(codex: Codex, options?: {
+    rootDir?: string;
+    force?: boolean;
+}): Promise<{
+    id: string;
+    path: string;
+}>;
+/**
+ * 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 declare function getCodex(id: string, options?: {
+    rootDir?: string;
+}): Promise<Codex>;
+/**
+ * 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 declare function listCodexes(options?: {
+    rootDir?: string;
+}): Promise<string[]>;
+/**
+ * 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 declare function removeCodex(id: string, options?: {
+    rootDir?: string;
+}): Promise<boolean>;
+/**
+ * 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 declare function codexContentPath(id: string, relativePath: string, options?: {
+    rootDir?: string;
+}): string;
+//# sourceMappingURL=store.d.ts.map

package/dist/codex/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src.legacy/codex/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAQxC,MAAM,MAAM,mBAAmB,GAC3B,WAAW,GACX,mBAAmB,GACnB,YAAY,GACZ,aAAa,GACb,cAAc,GACd,cAAc,CAAC;AAEnB,qBAAa,eAAgB,SAAQ,KAAK;aAEtB,IAAI,EAAE,mBAAmB;aAEzB,KAAK,CAAC,EAAE,OAAO;gBAFf,IAAI,EAAE,mBAAmB,EACzC,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,OAAO,YAAA;CAKlC;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED,+CAA+C;AAC/C,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,4CAA4C;AAC5C,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7D;AAQD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAOhD;AAgCD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAClD,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAqBvC;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAY7F;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoBvF;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,MAAM,EACV,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC,MAAM,CASR"}