agentplane 0.3.6 → 0.3.8

package/dist/backends/task-backend/local-backend-write.js

@@ -0,0 +1,254 @@
+import { mkdir, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { applyTaskDocMutations, docChanged, parseTaskReadme, renderTaskReadme, taskDocToSectionMap, taskReadmePath, validateTaskReadmeFrontmatter, withTaskReadmeFrontmatterDefaults, } from "@agentplaneorg/core";
+import { isRecord } from "../../shared/guards.js";
+import { writeTextIfChanged } from "../../shared/write-if-changed.js";
+import { listLocalTasks } from "./local-backend-read.js";
+import { assertExpectedRevision, storedRevisionFromFrontmatter, taskDocStateFromTask, } from "./local-backend-state.js";
+import { DEFAULT_DOC_UPDATED_BY, defaultPlanApproval, defaultVerificationResult, extractTaskDoc, generateTaskId, invalidLengthMessage, mapLimit, mergeTaskDoc, missingTaskIdMessage, normalizeDocVersion, nowIso, resolveDocUpdatedByFromTask, taskRecordToData, validateTaskId, writeTasksExportFromTasks, } from "./shared.js";
+export async function generateLocalTaskId(context, opts) {
+    const length = opts.length;
+    if (length < 4)
+        throw new Error(invalidLengthMessage(length, 4));
+    const attempts = Math.max(1, opts.attempts);
+    return await generateTaskId({
+        length,
+        attempts,
+        isAvailable: async (taskId) => {
+            const readmePath = taskReadmePath(context.root, taskId);
+            try {
+                await readFile(readmePath, "utf8");
+                return false;
+            }
+            catch (err) {
+                const code = err?.code;
+                if (code === "ENOENT")
+                    return true;
+                throw err;
+            }
+        },
+    });
+}
+export async function writeLocalTask(context, task, opts) {
+    const taskId = task.id.trim();
+    if (!taskId)
+        throw new Error(missingTaskIdMessage());
+    validateTaskId(taskId);
+    const readmePath = taskReadmePath(context.root, taskId);
+    let body = "";
+    let existingDoc = "";
+    let existingFrontmatter = {};
+    try {
+        const text = await readFile(readmePath, "utf8");
+        const parsed = parseTaskReadme(text);
+        body = parsed.body;
+        existingDoc = extractTaskDoc(parsed.body);
+        existingFrontmatter = parsed.frontmatter;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== "ENOENT")
+            throw err;
+    }
+    assertExpectedRevision({
+        taskId,
+        expectedRevision: opts?.expectedRevision,
+        currentRevision: Object.keys(existingFrontmatter).length > 0
+            ? storedRevisionFromFrontmatter(existingFrontmatter, 1)
+            : 0,
+    });
+    const payload = { ...task };
+    delete payload.doc;
+    if (!Number.isInteger(payload.revision) ||
+        typeof payload.revision !== "number" ||
+        payload.revision <= 0) {
+        payload.revision =
+            Number.isInteger(existingFrontmatter.revision) &&
+                typeof existingFrontmatter.revision === "number" &&
+                existingFrontmatter.revision > 0
+                ? existingFrontmatter.revision
+                : 1;
+    }
+    for (const [key, value] of Object.entries(payload)) {
+        if (value === undefined)
+            delete payload[key];
+    }
+    for (const key of ["doc_version", "doc_updated_at", "doc_updated_by"]) {
+        if (payload[key] === undefined && existingFrontmatter[key] !== undefined) {
+            payload[key] = existingFrontmatter[key];
+        }
+    }
+    if (payload.plan_approval === undefined && existingFrontmatter.plan_approval !== undefined) {
+        payload.plan_approval = existingFrontmatter.plan_approval;
+    }
+    if (payload.plan_approval === undefined) {
+        payload.plan_approval = defaultPlanApproval();
+    }
+    if (payload.verification === undefined && existingFrontmatter.verification !== undefined) {
+        payload.verification = existingFrontmatter.verification;
+    }
+    if (payload.verification === undefined) {
+        payload.verification = defaultVerificationResult();
+    }
+    const existingDocVersion = normalizeDocVersion(existingFrontmatter.doc_version);
+    const requestedDocVersion = normalizeDocVersion(payload.doc_version, existingDocVersion);
+    const effectiveDoc = task.doc === undefined ? null : String(task.doc ?? "");
+    let nextSections = effectiveDoc === null
+        ? task.sections && Object.keys(task.sections).length > 0
+            ? task.sections
+            : existingDoc
+                ? taskDocToSectionMap(existingDoc)
+                : undefined
+        : taskDocToSectionMap(effectiveDoc);
+    if (task.doc !== undefined) {
+        const docText = String(task.doc ?? "");
+        body = mergeTaskDoc(body, docText);
+        if (docChanged(existingDoc, docText) || !payload.doc_updated_at) {
+            const applied = applyTaskDocMutations(taskDocStateFromTask({
+                comments: task.comments,
+                doc_updated_by: typeof payload.doc_updated_by === "string" ? payload.doc_updated_by : undefined,
+                doc_version: requestedDocVersion,
+                owner: task.owner,
+            }, existingDoc), [
+                { kind: "replace-doc", doc: docText },
+                {
+                    kind: "touch-doc-meta",
+                    updatedBy: resolveDocUpdatedByFromTask(task, context.updatedBy || DEFAULT_DOC_UPDATED_BY),
+                    version: requestedDocVersion,
+                },
+            ], { now: nowIso() });
+            payload.doc_version = applied.doc_version;
+            payload.doc_updated_at = applied.doc_updated_at;
+            payload.doc_updated_by = applied.doc_updated_by;
+            nextSections = applied.sections;
+        }
+    }
+    if (nextSections && Object.keys(nextSections).length > 0) {
+        payload.sections = nextSections;
+    }
+    payload.doc_version = normalizeDocVersion(payload.doc_version, requestedDocVersion);
+    if (payload.doc_updated_at === undefined || payload.doc_updated_at === "") {
+        payload.doc_updated_at = nowIso();
+    }
+    if (payload.doc_updated_by === undefined || payload.doc_updated_by === "") {
+        payload.doc_updated_by = resolveDocUpdatedByFromTask(task, context.updatedBy || DEFAULT_DOC_UPDATED_BY);
+    }
+    validateTaskReadmeFrontmatter(withTaskReadmeFrontmatterDefaults(payload));
+    await mkdir(path.dirname(readmePath), { recursive: true });
+    const text = renderTaskReadme(payload, body || "");
+    await writeTextIfChanged(readmePath, text.endsWith("\n") ? text : `${text}\n`);
+}
+export async function writeLocalTasks(context, tasks, opts) {
+    await mapLimit(tasks, 4, async (task) => {
+        await writeLocalTask(context, task, opts);
+        return null;
+    });
+}
+export async function normalizeLocalTasks(context) {
+    const entries = await readdir(context.root, { withFileTypes: true }).catch(() => []);
+    const dirs = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    const results = await mapLimit(dirs, 8, async (dirName) => {
+        const readmePath = path.join(context.root, dirName, "README.md");
+        let text = "";
+        try {
+            text = await readFile(readmePath, "utf8");
+        }
+        catch {
+            return { taskId: "", scanned: false, changed: false };
+        }
+        let parsed;
+        try {
+            parsed = parseTaskReadme(text);
+        }
+        catch {
+            return { taskId: "", scanned: false, changed: false };
+        }
+        const frontmatter = parsed.frontmatter;
+        if (!isRecord(frontmatter) || Object.keys(frontmatter).length === 0) {
+            return { taskId: "", scanned: false, changed: false };
+        }
+        const fallbackTaskId = (typeof frontmatter.id === "string" ? frontmatter.id : dirName).trim();
+        let validatedFrontmatter;
+        try {
+            validatedFrontmatter = validateTaskReadmeFrontmatter(withTaskReadmeFrontmatterDefaults({
+                ...frontmatter,
+                id: fallbackTaskId,
+            }));
+        }
+        catch {
+            return { taskId: "", scanned: false, changed: false };
+        }
+        const taskId = fallbackTaskId;
+        if (taskId)
+            validateTaskId(taskId);
+        const task = taskRecordToData({
+            id: taskId,
+            frontmatter: validatedFrontmatter,
+            body: parsed.body,
+            readmePath,
+        });
+        const payload = { ...task };
+        delete payload.doc;
+        if (!Number.isInteger(payload.revision) ||
+            typeof payload.revision !== "number" ||
+            payload.revision <= 0) {
+            payload.revision =
+                Number.isInteger(frontmatter.revision) &&
+                    typeof frontmatter.revision === "number" &&
+                    frontmatter.revision > 0
+                    ? frontmatter.revision
+                    : 1;
+        }
+        for (const [key, value] of Object.entries(payload)) {
+            if (value === undefined)
+                delete payload[key];
+        }
+        for (const key of ["doc_version", "doc_updated_at", "doc_updated_by"]) {
+            if (payload[key] === undefined && frontmatter[key] !== undefined) {
+                payload[key] = frontmatter[key];
+            }
+        }
+        if (payload.plan_approval === undefined && frontmatter.plan_approval !== undefined) {
+            payload.plan_approval = frontmatter.plan_approval;
+        }
+        if (payload.plan_approval === undefined)
+            payload.plan_approval = defaultPlanApproval();
+        if (payload.verification === undefined && frontmatter.verification !== undefined) {
+            payload.verification = frontmatter.verification;
+        }
+        if (payload.verification === undefined)
+            payload.verification = defaultVerificationResult();
+        payload.doc_version = normalizeDocVersion(payload.doc_version, normalizeDocVersion(frontmatter.doc_version));
+        if (payload.doc_updated_at === undefined || payload.doc_updated_at === "") {
+            payload.doc_updated_at = nowIso();
+        }
+        if (payload.doc_updated_by === undefined || payload.doc_updated_by === "") {
+            payload.doc_updated_by = resolveDocUpdatedByFromTask(task, context.updatedBy || DEFAULT_DOC_UPDATED_BY);
+        }
+        if (!payload.sections && task.doc) {
+            payload.sections = taskDocToSectionMap(task.doc);
+        }
+        validateTaskReadmeFrontmatter(withTaskReadmeFrontmatterDefaults(payload));
+        const next = renderTaskReadme(payload, parsed.body || "");
+        const didWrite = await writeTextIfChanged(readmePath, next.endsWith("\n") ? next : `${next}\n`);
+        return { taskId, scanned: true, changed: didWrite };
+    });
+    const seen = new Set();
+    for (const { taskId } of results) {
+        if (!taskId)
+            continue;
+        if (seen.has(taskId))
+            throw new Error(`Duplicate task id in local backend: ${taskId}`);
+        seen.add(taskId);
+    }
+    const scanned = results.reduce((acc, result) => acc + (result.scanned ? 1 : 0), 0);
+    const changed = results.reduce((acc, result) => acc + (result.changed ? 1 : 0), 0);
+    return { scanned, changed };
+}
+export async function exportLocalTasksJson(context, outputPath) {
+    const tasks = await listLocalTasks(context, "full");
+    await writeTasksExportFromTasks({ outputPath, tasks });
+}
+export async function exportLocalProjectionSnapshot(context, outputPath) {
+    await exportLocalTasksJson(context, outputPath);
+}

package/dist/backends/task-backend/local-backend.d.ts

@@ -1,11 +1,14 @@
-import { type TaskBackend, type TaskData } from "./shared.js";
+import { type TaskBackend, type TaskData, type TaskSummary, type TaskWriteOptions } from "./shared.js";
 export declare class LocalBackend implements TaskBackend {
     id: string;
     capabilities: {
         readonly canonical_source: "local";
         readonly projection: "canonical";
+        readonly projection_read_mode: "native";
         readonly reads_from_projection_by_default: true;
         readonly writes_task_readmes: true;
+        readonly supports_task_revisions: true;
+        readonly supports_revision_guarded_writes: true;
         readonly may_access_network_on_read: false;
         readonly may_access_network_on_write: false;
         readonly supports_projection_refresh: false;
@@ -23,16 +26,17 @@ export declare class LocalBackend implements TaskBackend {
         length: number;
         attempts: number;
     }): Promise<string>;
+    private backendContext;
     listTasks(): Promise<TaskData[]>;
-    listProjectionTasks(): Promise<TaskData[]>;
+    listProjectionTasks(): Promise<TaskSummary[]>;
     getLastListWarnings(): string[];
     getTask(taskId: string): Promise<TaskData | null>;
     getTasks(taskIds: string[]): Promise<(TaskData | null)[]>;
     getTaskDoc(taskId: string): Promise<string>;
-    writeTask(task: TaskData): Promise<void>;
-    setTaskDoc(taskId: string, doc: string, updatedBy?: string): Promise<void>;
-    touchTaskDocMetadata(taskId: string, updatedBy?: string): Promise<void>;
-    writeTasks(tasks: TaskData[]): Promise<void>;
+    writeTask(task: TaskData, opts?: TaskWriteOptions): Promise<void>;
+    setTaskDoc(taskId: string, doc: string, updatedBy?: string, opts?: TaskWriteOptions): Promise<void>;
+    touchTaskDocMetadata(taskId: string, updatedBy?: string, opts?: TaskWriteOptions): Promise<void>;
+    writeTasks(tasks: TaskData[], opts?: TaskWriteOptions): Promise<void>;
     normalizeTasks(): Promise<{
         scanned: number;
         changed: number;

package/dist/backends/task-backend/local-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-backend.d.ts","sourceRoot":"","sources":["../../../src/backends/task-backend/local-backend.ts"],"names":[],"mappings":"AAqBA,OAAO,EAiBL,KAAK,WAAW,EAChB,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AAErB,qBAAa,YAAa,YAAW,WAAW;IAC9C,EAAE,SAAW;IACb,YAAY;;;;;;;;;;MAUD;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,gBAAgB,CAAgB;gBAE5B,QAAQ,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;IAKrD,cAAc,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB3E,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAwHhC,mBAAmB,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIhD,mBAAmB,IAAI,MAAM,EAAE;IAIzB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAoBjD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC;IAKzD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO3C,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAyExC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB1E,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBvE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAuF/D,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlD,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGlE"}
+{"version":3,"file":"local-backend.d.ts","sourceRoot":"","sources":["../../../src/backends/task-backend/local-backend.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAC;AAiBrB,qBAAa,YAAa,YAAW,WAAW;IAC9C,EAAE,SAAW;IACb,YAAY;;;;;;;;;;;;;MAaD;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,gBAAgB,CAAgB;gBAE5B,QAAQ,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;IAKrD,cAAc,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjF,OAAO,CAAC,cAAc;IAUhB,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIhC,mBAAmB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAInD,mBAAmB,IAAI,MAAM,EAAE;IAIzB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAIjD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC;IAIzD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3C,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE,UAAU,CACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC;IAIV,oBAAoB,CACxB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC;IAIV,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrE,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAI/D,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGlE"}