@rryando/arcs 3.0.0

package/dist/utils/json-schemas.js

@@ -0,0 +1,147 @@
+/**
+ * Zod schemas for JSON file shapes used at file-read boundaries.
+ * Kept separate from schemas.ts (which holds tool-input schemas).
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// package.json (only fields ARCS reads)
+// ---------------------------------------------------------------------------
+export const packageJsonSchema = z.object({
+    name: z.string().optional(),
+    version: z.string(),
+});
+// ---------------------------------------------------------------------------
+// ~/.arcs/config.json
+// ---------------------------------------------------------------------------
+export const cliConfigSchema = z.object({
+    version: z.literal("1"),
+    ides: z.array(z.string()),
+});
+// ---------------------------------------------------------------------------
+// DAG root meta.json
+// ---------------------------------------------------------------------------
+export const dagNodeSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    status: z.string(),
+    dependsOn: z.array(z.string()),
+});
+export const rootMetaSchema = z.object({
+    version: z.string(),
+    projects: z.array(dagNodeSchema),
+});
+// ---------------------------------------------------------------------------
+// Per-project meta.json
+// ---------------------------------------------------------------------------
+export const syncStatsSchema = z.object({
+    docsUpdated: z.number().int().min(0),
+    knowledgeEntriesCreated: z.number().int().min(0),
+    knowledgeEntriesUpdated: z.number().int().min(0),
+    tasksTransitioned: z.number().int().min(0),
+    plansUpdated: z.number().int().min(0),
+    diagramsDrifted: z.number().int().min(0),
+});
+export const projectMetaSchema = z
+    .object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string(),
+    status: z.string().optional(),
+    repoUrl: z.string().optional(),
+    createdAt: z.string(),
+    workspacePaths: z.array(z.string()).optional().default([]),
+    lastSyncedAt: z.string().datetime().optional(),
+    lastSyncGitCommit: z.string().optional(),
+    lastSyncStats: syncStatsSchema.optional(),
+})
+    .passthrough();
+// ---------------------------------------------------------------------------
+// plans/index.json, knowledge/index.json, tasks/index.json
+// ---------------------------------------------------------------------------
+const fileRefSchemaLocal = z.object({
+    path: z.string(),
+    anchor: z.string().optional(),
+});
+export const planMetaSchema = z.object({
+    id: z.string(),
+    normalizedId: z.string(),
+    title: z.string(),
+    status: z.string(),
+    keywords: z.array(z.string()),
+    summary: z.string(),
+    sourceFiles: z.array(fileRefSchemaLocal).optional(),
+    file: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const planIndexSchema = z.object({
+    plans: z.array(planMetaSchema),
+});
+export const knowledgeMetaSchema = z.object({
+    id: z.string(),
+    normalizedId: z.string(),
+    title: z.string(),
+    kind: z.string(),
+    audience: z.string().optional(),
+    keywords: z.array(z.string()),
+    summary: z.string(),
+    sourceFiles: z.array(fileRefSchemaLocal).optional(),
+    file: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const knowledgeIndexSchema = z.object({
+    entries: z.array(knowledgeMetaSchema),
+});
+export const taskMetaSchema = z.object({
+    id: z.string(),
+    normalizedId: z.string(),
+    title: z.string(),
+    status: z.string(),
+    priority: z.string(),
+    sourceFiles: z.array(fileRefSchemaLocal).optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const taskIndexSchema = z.object({
+    tasks: z.array(taskMetaSchema),
+});
+// ---------------------------------------------------------------------------
+// OpenCode ARCS bundle manifest (source bundle)
+// ---------------------------------------------------------------------------
+const configMergeSchema = z.object({
+    path: z.array(z.string()),
+    value: z.unknown().transform((v) => v),
+});
+export const opencodeSourceManifestSchema = z.object({
+    bundleId: z.string(),
+    installMode: z.string(),
+    bundleVersionSource: z.string(),
+    sourceRoot: z.string(),
+    skills: z.object({
+        source: z.string(),
+        destination: z.string(),
+    }),
+    agents: z.array(z.object({
+        source: z.string(),
+        destination: z.string(),
+    })),
+    ownedPaths: z.array(z.string()),
+    plugin: z.object({
+        required: z.boolean(),
+        source: z.string(),
+        destination: z.string(),
+    }),
+    config: z.object({
+        requiredMerges: z.array(configMergeSchema),
+    }),
+});
+export const opencodeInstalledManifestSchema = z.object({
+    bundleId: z.string(),
+    installMode: z.string(),
+    sourceBundleVersion: z.string(),
+    sourceBundleHash: z.string(),
+    installedAt: z.string(),
+    ownedPaths: z.array(z.string()),
+});
+//# sourceMappingURL=json-schemas.js.map

package/dist/utils/json-schemas.js.map

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

package/dist/utils/json.d.ts

@@ -0,0 +1,15 @@
+import type { ZodType } from "zod";
+/**
+ * Async: read & parse a JSON file. Returns undefined on missing/parse-error.
+ */
+export declare function readJsonSafe<T>(filePath: string): Promise<T | undefined>;
+/**
+ * Sync: read & parse a JSON file. Returns undefined on missing/parse-error.
+ */
+export declare function readJsonSafeSync<T>(filePath: string): T | undefined;
+/**
+ * Validate a parsed value against a Zod schema.
+ * Returns the typed value on success; throws with file path context on failure.
+ */
+export declare function validateJson<T>(data: unknown, schema: ZodType<T>, filePath: string): T;
+//# sourceMappingURL=json.d.ts.map

package/dist/utils/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/utils/json.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAM9E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAMnE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAStF"}

package/dist/utils/json.js

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+/**
+ * Async: read & parse a JSON file. Returns undefined on missing/parse-error.
+ */
+export async function readJsonSafe(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Sync: read & parse a JSON file. Returns undefined on missing/parse-error.
+ */
+export function readJsonSafeSync(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Validate a parsed value against a Zod schema.
+ * Returns the typed value on success; throws with file path context on failure.
+ */
+export function validateJson(data, schema, filePath) {
+    const result = schema.safeParse(data);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  - ${i.path.join(".")}: ${i.message}`)
+            .join("\n");
+        throw new Error(`Invalid JSON in ${filePath}:\n${issues}`);
+    }
+    return result.data;
+}
+//# sourceMappingURL=json.js.map

package/dist/utils/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/utils/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,QAAgB;IACpD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAM,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAI,QAAgB;IAClD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAM,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAI,IAAa,EAAE,MAAkB,EAAE,QAAgB;IACjF,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACnD,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,MAAM,MAAM,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/utils/knowledge-store.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Knowledge entry CRUD storage for ARCS projects.
+ *
+ * Provides create, update, delete, and index-read operations for knowledge
+ * entries, with automatic index maintenance and rebuild-on-read resilience.
+ */
+export type { FileRef, KnowledgeAudience, KnowledgeKind } from "./storage-utils.js";
+export { KNOWLEDGE_AUDIENCES, KNOWLEDGE_KINDS } from "./storage-utils.js";
+export interface KnowledgeMeta {
+    id: string;
+    normalizedId: string;
+    title: string;
+    kind: import("./storage-utils.js").KnowledgeKind;
+    audience?: import("./storage-utils.js").KnowledgeAudience;
+    keywords: string[];
+    summary: string;
+    sourceFiles?: import("./storage-utils.js").FileRef[];
+    file: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateKnowledgeInput {
+    id: string;
+    title: string;
+    kind: import("./storage-utils.js").KnowledgeKind;
+    audience?: import("./storage-utils.js").KnowledgeAudience;
+    keywords: string[];
+    summary?: string;
+    content?: string;
+    sourceFiles?: import("./storage-utils.js").FileRef[];
+    now?: string;
+}
+export interface UpdateKnowledgeInput {
+    id: string;
+    title?: string;
+    kind?: import("./storage-utils.js").KnowledgeKind;
+    audience?: import("./storage-utils.js").KnowledgeAudience;
+    summary?: string;
+    keywords?: string[];
+    sourceFiles?: import("./storage-utils.js").FileRef[];
+    now?: string;
+}
+export declare function createKnowledgeEntry(projectDir: string, input: CreateKnowledgeInput): Promise<KnowledgeMeta>;
+export declare function updateKnowledgeEntry(projectDir: string, input: UpdateKnowledgeInput): Promise<KnowledgeMeta>;
+export declare function deleteKnowledgeEntry(projectDir: string, id: string): Promise<void>;
+export declare function readKnowledgeIndex(projectDir: string): Promise<{
+    entries: KnowledgeMeta[];
+}>;
+//# sourceMappingURL=knowledge-store.d.ts.map

package/dist/utils/knowledge-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-store.d.ts","sourceRoot":"","sources":["../../src/utils/knowledge-store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA+BH,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAM1E,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,oBAAoB,EAAE,aAAa,CAAC;IACjD,QAAQ,CAAC,EAAE,OAAO,oBAAoB,EAAE,iBAAiB,CAAC;IAC1D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,oBAAoB,EAAE,OAAO,EAAE,CAAC;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,oBAAoB,EAAE,aAAa,CAAC;IACjD,QAAQ,CAAC,EAAE,OAAO,oBAAoB,EAAE,iBAAiB,CAAC;IAC1D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,oBAAoB,EAAE,OAAO,EAAE,CAAC;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,oBAAoB,EAAE,aAAa,CAAC;IAClD,QAAQ,CAAC,EAAE,OAAO,oBAAoB,EAAE,iBAAiB,CAAC;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,oBAAoB,EAAE,OAAO,EAAE,CAAC;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAsED,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,aAAa,CAAC,CA0CxB;AAED,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,aAAa,CAAC,CA+CxB;AAED,wBAAsB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBxF;AAED,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC,CAmBvC"}

package/dist/utils/knowledge-store.js

@@ -0,0 +1,191 @@
+/**
+ * Knowledge entry CRUD storage for ARCS projects.
+ *
+ * Provides create, update, delete, and index-read operations for knowledge
+ * entries, with automatic index maintenance and rebuild-on-read resilience.
+ */
+import { readdir, unlink, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { invalidateGraphCache } from "../retrieval/graph-invalidate.js";
+import { indexRebuildFailed, invalidFileFormat, itemNotFound, normalizedIdCollision, } from "./errors.js";
+import { withLock } from "./file-lock.js";
+import { readJsonSafe } from "./json.js";
+import { knowledgeMetaSchema } from "./json-schemas.js";
+import { normalizeIdentifier } from "./slug.js";
+import { buildBody, ensureDir, fileExists, nowISO, rewriteH1, sanitizeFileRefs, sanitizeKeywords, validateKnowledgeKind, writeJson, } from "./storage-utils.js";
+export { KNOWLEDGE_AUDIENCES, KNOWLEDGE_KINDS } from "./storage-utils.js";
+// ---------------------------------------------------------------------------
+// Index helpers
+// ---------------------------------------------------------------------------
+async function rebuildKnowledgeIndex(knowledgeDir) {
+    const files = (await readdir(knowledgeDir)).filter((f) => f.endsWith(".meta.json"));
+    const entries = [];
+    const errors = [];
+    for (const file of files) {
+        try {
+            const filePath = join(knowledgeDir, file);
+            const raw = await readJsonSafe(filePath);
+            if (raw === undefined) {
+                errors.push(file);
+                continue;
+            }
+            const result = knowledgeMetaSchema.safeParse(raw);
+            if (!result.success) {
+                throw invalidFileFormat(filePath, result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", "));
+            }
+            entries.push(result.data);
+        }
+        catch (e) {
+            if (e instanceof Error && e.name === "DagError")
+                throw e;
+            errors.push(file);
+        }
+    }
+    if (errors.length > 0) {
+        throw indexRebuildFailed("knowledge", `corrupt meta files: ${errors.join(", ")}`);
+    }
+    const index = { entries };
+    await writeJson(join(knowledgeDir, "index.json"), index);
+    return index;
+}
+async function isKnowledgeIndexStale(knowledgeDir, index) {
+    const metaFiles = (await readdir(knowledgeDir)).filter((f) => f.endsWith(".meta.json"));
+    if (metaFiles.length !== index.entries.length)
+        return true;
+    for (const entry of index.entries) {
+        const metaPath = join(knowledgeDir, `${entry.normalizedId}.meta.json`);
+        const diskMeta = await readJsonSafe(metaPath);
+        if (!diskMeta || diskMeta.updatedAt !== entry.updatedAt) {
+            return true;
+        }
+    }
+    return false;
+}
+async function writeKnowledgeIndex(knowledgeDir, index) {
+    const indexPath = join(knowledgeDir, "index.json");
+    await withLock(indexPath, async () => {
+        await writeJson(indexPath, index);
+    });
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export async function createKnowledgeEntry(projectDir, input) {
+    validateKnowledgeKind(input.kind);
+    const keywords = sanitizeKeywords(input.keywords);
+    const sourceFiles = input.sourceFiles ? sanitizeFileRefs(input.sourceFiles) : undefined;
+    const normalizedId = normalizeIdentifier(input.id);
+    const knowledgeDir = join(projectDir, "knowledge");
+    await ensureDir(knowledgeDir);
+    const metaPath = join(knowledgeDir, `${normalizedId}.meta.json`);
+    if (await fileExists(metaPath)) {
+        throw normalizedIdCollision("knowledge entry", input.id, normalizedId);
+    }
+    const ts = nowISO(input.now);
+    const bodyFile = join("knowledge", `${normalizedId}.md`);
+    const meta = {
+        id: normalizedId,
+        normalizedId,
+        title: input.title,
+        kind: input.kind,
+        ...(input.audience && { audience: input.audience }),
+        keywords,
+        summary: input.summary ?? "",
+        ...(sourceFiles && { sourceFiles }),
+        file: bodyFile,
+        createdAt: ts,
+        updatedAt: ts,
+    };
+    await writeJson(metaPath, meta);
+    await writeFile(join(projectDir, bodyFile), buildBody(input.title, input.content), "utf-8");
+    const index = (await readJsonSafe(join(knowledgeDir, "index.json"))) ?? {
+        entries: [],
+    };
+    index.entries.push(meta);
+    await writeKnowledgeIndex(knowledgeDir, index);
+    invalidateGraphCache(basename(projectDir));
+    return meta;
+}
+export async function updateKnowledgeEntry(projectDir, input) {
+    if (input.kind !== undefined) {
+        validateKnowledgeKind(input.kind);
+    }
+    const normalizedId = normalizeIdentifier(input.id);
+    const knowledgeDir = join(projectDir, "knowledge");
+    const metaPath = join(knowledgeDir, `${normalizedId}.meta.json`);
+    const meta = await readJsonSafe(metaPath);
+    if (!meta) {
+        throw itemNotFound("knowledge entry", input.id);
+    }
+    if (input.kind !== undefined)
+        meta.kind = input.kind;
+    if (input.audience !== undefined)
+        meta.audience = input.audience;
+    if (input.title !== undefined && input.title !== meta.title) {
+        const bodyPath = join(projectDir, meta.file);
+        await rewriteH1(bodyPath, input.title);
+        meta.title = input.title;
+    }
+    if (input.summary !== undefined)
+        meta.summary = input.summary;
+    if (input.keywords !== undefined)
+        meta.keywords = sanitizeKeywords(input.keywords);
+    if (input.sourceFiles !== undefined) {
+        if (input.sourceFiles.length === 0) {
+            delete meta.sourceFiles;
+        }
+        else {
+            meta.sourceFiles = sanitizeFileRefs(input.sourceFiles);
+        }
+    }
+    meta.updatedAt = nowISO(input.now);
+    await writeJson(metaPath, meta);
+    const index = (await readJsonSafe(join(knowledgeDir, "index.json"))) ?? {
+        entries: [],
+    };
+    const idx = index.entries.findIndex((e) => e.normalizedId === normalizedId);
+    if (idx >= 0) {
+        index.entries[idx] = meta;
+    }
+    else {
+        index.entries.push(meta);
+    }
+    await writeKnowledgeIndex(knowledgeDir, index);
+    invalidateGraphCache(basename(projectDir));
+    return meta;
+}
+export async function deleteKnowledgeEntry(projectDir, id) {
+    const normalizedId = normalizeIdentifier(id);
+    const knowledgeDir = join(projectDir, "knowledge");
+    const metaPath = join(knowledgeDir, `${normalizedId}.meta.json`);
+    const meta = await readJsonSafe(metaPath);
+    if (!meta) {
+        throw itemNotFound("knowledge entry", id);
+    }
+    const bodyPath = join(projectDir, meta.file);
+    await unlink(metaPath);
+    if (await fileExists(bodyPath)) {
+        await unlink(bodyPath);
+    }
+    const index = (await readJsonSafe(join(knowledgeDir, "index.json"))) ?? {
+        entries: [],
+    };
+    index.entries = index.entries.filter((e) => e.normalizedId !== normalizedId);
+    await writeKnowledgeIndex(knowledgeDir, index);
+}
+export async function readKnowledgeIndex(projectDir) {
+    const knowledgeDir = join(projectDir, "knowledge");
+    if (!(await fileExists(knowledgeDir))) {
+        return { entries: [] };
+    }
+    const indexPath = join(knowledgeDir, "index.json");
+    const index = await readJsonSafe(indexPath);
+    if (!index || !Array.isArray(index.entries)) {
+        return rebuildKnowledgeIndex(knowledgeDir);
+    }
+    if (await isKnowledgeIndexStale(knowledgeDir, index)) {
+        return rebuildKnowledgeIndex(knowledgeDir);
+    }
+    return index;
+}
+//# sourceMappingURL=knowledge-store.js.map

package/dist/utils/knowledge-store.js.map

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

package/dist/utils/loop-state.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Loop state management for ARCS projects.
+ *
+ * Stores active loop state as loop-state.json in each project directory.
+ * Used by CLI commands (start/cancel/get) and the OpenCode plugin hook
+ * (which reads state directly from disk to drive iteration).
+ */
+export interface LoopState {
+    active: boolean;
+    iteration: number;
+    maxIterations: number;
+    completionPromise: string;
+    startedAt: string;
+    prompt: string;
+    sessionId: string;
+    strategy: "continue" | "reset";
+    projectSlug: string;
+    messageCountAtStart?: number;
+}
+export interface StartLoopInput {
+    sessionId: string;
+    prompt: string;
+    maxIterations?: number;
+    completionPromise?: string;
+    strategy?: "continue" | "reset";
+    projectSlug: string;
+    messageCountAtStart?: number;
+}
+export declare const LOOP_STATE_FILE = "loop-state.json";
+export declare const DEFAULT_MAX_ITERATIONS = 100;
+export declare const DEFAULT_COMPLETION_PROMISE = "DONE";
+export declare const COMPLETION_TAG_PATTERN: RegExp;
+/** Read loop-state.json from a project directory. Returns null if missing or corrupt. */
+export declare function readLoopState(projectDir: string): Promise<LoopState | null>;
+/** Write loop-state.json to a project directory. */
+export declare function writeLoopState(projectDir: string, state: LoopState): Promise<void>;
+/** Delete loop-state.json from a project directory. Returns true if the file was removed. */
+export declare function clearLoopState(projectDir: string): Promise<boolean>;
+/** Read loop state, bump iteration count, write back, and return the updated state. */
+export declare function incrementLoopIteration(projectDir: string): Promise<LoopState | null>;
+/** Create initial loop state for a project. Throws if a loop is already active. */
+export declare function startLoop(projectDir: string, input: StartLoopInput): Promise<LoopState>;
+/** Cancel an active loop if the session ID matches. Returns true if cleared. */
+export declare function cancelLoop(projectDir: string, sessionId: string): Promise<boolean>;
+/** Scan all projects for an active loop-state.json. Returns the first match or null. */
+export declare function findActiveLoop(): Promise<{
+    slug: string;
+    projectDir: string;
+    state: LoopState;
+} | null>;
+//# sourceMappingURL=loop-state.d.ts.map

package/dist/utils/loop-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-state.d.ts","sourceRoot":"","sources":["../../src/utils/loop-state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD,eAAO,MAAM,eAAe,oBAAoB,CAAC;AACjD,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,0BAA0B,SAAS,CAAC;AACjD,eAAO,MAAM,sBAAsB,QAAgC,CAAC;AA+BpE,yFAAyF;AACzF,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAGjF;AAED,oDAAoD;AACpD,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxF;AAED,6FAA6F;AAC7F,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOzE;AAED,uFAAuF;AACvF,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAQ1F;AAED,mFAAmF;AACnF,wBAAsB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CA0B7F;AAED,gFAAgF;AAChF,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMxF;AAED,wFAAwF;AACxF,wBAAsB,cAAc,IAAI,OAAO,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;CAClB,GAAG,IAAI,CAAC,CAkBR"}

package/dist/utils/loop-state.js

@@ -0,0 +1,123 @@
+/**
+ * Loop state management for ARCS projects.
+ *
+ * Stores active loop state as loop-state.json in each project directory.
+ * Used by CLI commands (start/cancel/get) and the OpenCode plugin hook
+ * (which reads state directly from disk to drive iteration).
+ */
+import { constants } from "node:fs";
+import { access, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DagError } from "./errors.js";
+import { getDataDir } from "./paths.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const LOOP_STATE_FILE = "loop-state.json";
+export const DEFAULT_MAX_ITERATIONS = 100;
+export const DEFAULT_COMPLETION_PROMISE = "DONE";
+export const COMPLETION_TAG_PATTERN = /<promise>(.*?)<\/promise>/is;
+// ---------------------------------------------------------------------------
+// Filesystem helpers
+// ---------------------------------------------------------------------------
+async function fileExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readJsonSafe(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function writeJson(filePath, data) {
+    await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Read loop-state.json from a project directory. Returns null if missing or corrupt. */
+export async function readLoopState(projectDir) {
+    const filePath = join(projectDir, LOOP_STATE_FILE);
+    return readJsonSafe(filePath);
+}
+/** Write loop-state.json to a project directory. */
+export async function writeLoopState(projectDir, state) {
+    const filePath = join(projectDir, LOOP_STATE_FILE);
+    await writeJson(filePath, state);
+}
+/** Delete loop-state.json from a project directory. Returns true if the file was removed. */
+export async function clearLoopState(projectDir) {
+    const filePath = join(projectDir, LOOP_STATE_FILE);
+    if (!(await fileExists(filePath))) {
+        return false;
+    }
+    await unlink(filePath);
+    return true;
+}
+/** Read loop state, bump iteration count, write back, and return the updated state. */
+export async function incrementLoopIteration(projectDir) {
+    const state = await readLoopState(projectDir);
+    if (!state) {
+        return null;
+    }
+    state.iteration += 1;
+    await writeLoopState(projectDir, state);
+    return state;
+}
+/** Create initial loop state for a project. Throws if a loop is already active. */
+export async function startLoop(projectDir, input) {
+    const existing = await readLoopState(projectDir);
+    if (existing?.active) {
+        throw new DagError("LOOP_ALREADY_ACTIVE", `A loop is already active for project "${input.projectSlug}" (session ${existing.sessionId}).`);
+    }
+    const state = {
+        active: true,
+        iteration: 0,
+        maxIterations: input.maxIterations ?? DEFAULT_MAX_ITERATIONS,
+        completionPromise: input.completionPromise ?? DEFAULT_COMPLETION_PROMISE,
+        startedAt: new Date().toISOString(),
+        prompt: input.prompt,
+        sessionId: input.sessionId,
+        strategy: input.strategy ?? "continue",
+        projectSlug: input.projectSlug,
+        ...(input.messageCountAtStart !== undefined && {
+            messageCountAtStart: input.messageCountAtStart,
+        }),
+    };
+    await writeLoopState(projectDir, state);
+    return state;
+}
+/** Cancel an active loop if the session ID matches. Returns true if cleared. */
+export async function cancelLoop(projectDir, sessionId) {
+    const state = await readLoopState(projectDir);
+    if (!state?.active || state.sessionId !== sessionId) {
+        return false;
+    }
+    return clearLoopState(projectDir);
+}
+/** Scan all projects for an active loop-state.json. Returns the first match or null. */
+export async function findActiveLoop() {
+    const dataDir = getDataDir();
+    const metaPath = join(dataDir, "meta.json");
+    const rootMeta = await readJsonSafe(metaPath);
+    if (!rootMeta?.projects) {
+        return null;
+    }
+    for (const node of rootMeta.projects) {
+        const projectDir = join(dataDir, "projects", node.id);
+        const state = await readLoopState(projectDir);
+        if (state?.active) {
+            return { slug: node.id, projectDir, state };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=loop-state.js.map