agentplane 0.3.6 → 0.3.8

package/dist/commands/shared/task-backend.js

@@ -1,7 +1,10 @@
 import path from "node:path";
+import { resolveTaskDocUpdatedBy, parseTaskReadme, taskDocToSectionMap, validateTaskReadmeFrontmatter, withTaskReadmeFrontmatterDefaults, } from "@agentplaneorg/core";
 import { CliError } from "../../shared/errors.js";
-import { loadTaskBackend } from "../../backends/task-backend.js";
+import { loadTaskBackend, taskRecordToData, toTaskSummary, } from "../../backends/task-backend.js";
+import { gitShowFile, toGitPath } from "./git-diff.js";
 import { GitContext } from "./git-context.js";
+import { gitListTaskBranches, parseTaskIdFromBranch } from "./git-worktree.js";
 function normalizeDocUpdatedBy(value) {
     const trimmed = value?.trim() ?? "";
     if (!trimmed)
@@ -11,19 +14,23 @@ function normalizeDocUpdatedBy(value) {
     return trimmed;
 }
 export function resolveDocUpdatedBy(task, author) {
-    const fromAuthor = normalizeDocUpdatedBy(author);
-    if (fromAuthor)
-        return fromAuthor;
-    const fromTask = normalizeDocUpdatedBy(typeof task.doc_updated_by === "string" ? task.doc_updated_by : undefined);
-    if (fromTask)
-        return fromTask;
-    return normalizeDocUpdatedBy(typeof task.owner === "string" ? task.owner : undefined);
+    return normalizeDocUpdatedBy(resolveTaskDocUpdatedBy({
+        comments: task.comments ?? null,
+        doc_updated_by: task.doc_updated_by,
+        owner: task.owner,
+    }, author));
 }
 export function taskDataToFrontmatter(task) {
     const planApproval = task.plan_approval ??
         { state: "pending", updated_at: null, updated_by: null, note: null };
     const verification = task.verification ??
         { state: "pending", updated_at: null, updated_by: null, note: null };
+    const revision = Number.isInteger(task.revision) && Number(task.revision) > 0 ? Number(task.revision) : 1;
+    const sections = task.doc === undefined
+        ? task.sections && Object.keys(task.sections).length > 0
+            ? task.sections
+            : undefined
+        : taskDocToSectionMap(task.doc);
     return {
         id: task.id,
         title: task.title,
@@ -33,11 +40,14 @@ export function taskDataToFrontmatter(task) {
         status: task.status,
         priority: task.priority,
         owner: task.owner,
+        revision,
+        origin: task.origin ?? undefined,
         depends_on: task.depends_on ?? [],
         tags: task.tags ?? [],
         verify: task.verify ?? [],
         plan_approval: planApproval,
         verification,
+        runner: task.runner ?? undefined,
         commit: task.commit ?? null,
         comments: task.comments ?? [],
         events: task.events ?? [],
@@ -45,6 +55,7 @@ export function taskDataToFrontmatter(task) {
         doc_updated_at: task.doc_updated_at,
         doc_updated_by: task.doc_updated_by,
         description: task.description ?? "",
+        sections,
         id_source: task.id_source,
         dirty: task.dirty,
     };
@@ -65,22 +76,70 @@ export async function loadCommandContext(opts) {
         backendConfigPath,
         git: new GitContext({ gitRoot: resolved.gitRoot }),
         memo: {},
-        resolved,
-        backend,
     };
 }
 export async function loadTaskFromContext(opts) {
     const task = await opts.ctx.taskBackend.getTask(opts.taskId);
-    if (!task) {
-        const tasksDir = path.join(opts.ctx.resolvedProject.gitRoot, opts.ctx.config.paths.workflow_dir);
-        const readmePath = path.join(tasksDir, opts.taskId, "README.md");
+    if (task)
+        return task;
+    const tasksDir = path.join(opts.ctx.resolvedProject.gitRoot, opts.ctx.config.paths.workflow_dir);
+    const readmePath = path.join(tasksDir, opts.taskId, "README.md");
+    const branchFallback = await loadTaskFromBranchSnapshot({
+        ctx: opts.ctx,
+        taskId: opts.taskId,
+        readmePath,
+    });
+    if (branchFallback)
+        return branchFallback;
+    throw new CliError({
+        exitCode: 4,
+        code: "E_IO",
+        message: `ENOENT: no such file or directory, open '${readmePath}'`,
+    });
+}
+export async function loadTaskFromBranchSnapshot(opts) {
+    if (opts.ctx.backendId !== "local") {
+        return null;
+    }
+    const branch = await resolveSingleTaskBranch(opts.ctx, opts.taskId);
+    if (!branch)
+        return null;
+    const relReadmePath = toGitPath(path.relative(opts.ctx.resolvedProject.gitRoot, opts.readmePath));
+    let text = "";
+    try {
+        text = await gitShowFile(opts.ctx.resolvedProject.gitRoot, branch, relReadmePath);
+    }
+    catch {
+        return null;
+    }
+    const parsed = parseTaskReadme(text);
+    const frontmatter = validateTaskReadmeFrontmatter(withTaskReadmeFrontmatterDefaults({
+        ...parsed.frontmatter,
+        id: typeof parsed.frontmatter.id === "string" && parsed.frontmatter.id.trim().length > 0
+            ? parsed.frontmatter.id
+            : opts.taskId,
+    }));
+    return taskRecordToData({
+        id: opts.taskId,
+        frontmatter: frontmatter,
+        body: parsed.body,
+        readmePath: opts.readmePath,
+    });
+}
+async function resolveSingleTaskBranch(ctx, taskId) {
+    const prefix = ctx.config.branch.task_prefix;
+    const branches = await gitListTaskBranches(ctx.resolvedProject.gitRoot, prefix);
+    const matches = branches.filter((branch) => parseTaskIdFromBranch(prefix, branch) === taskId);
+    if (matches.length === 1)
+        return matches[0] ?? null;
+    if (matches.length > 1) {
         throw new CliError({
-            exitCode: 4,
-            code: "E_IO",
-            message: `ENOENT: no such file or directory, open '${readmePath}'`,
+            exitCode: 3,
+            code: "E_VALIDATION",
+            message: `Multiple task branches match ${taskId}: ${matches.join(", ")}`,
         });
     }
-    return task;
+    return null;
 }
 export async function loadBackendTask(opts) {
     const ctx = opts.ctx ??
@@ -95,16 +154,40 @@ export async function loadBackendTask(opts) {
         task,
     };
 }
-export async function listTasksMemo(ctx) {
-    ctx.memo.taskList ??= ctx.taskBackend.listTasks();
-    return await ctx.memo.taskList;
+export async function writeTasksOrFallback(backend, tasks) {
+    if (tasks.length === 0)
+        return;
+    if (backend.writeTasks) {
+        await backend.writeTasks([...tasks]);
+        return;
+    }
+    for (const task of tasks) {
+        await backend.writeTask(task);
+    }
+}
+export async function listTaskSummariesMemo(ctx) {
+    ctx.memo.taskProjection ??= (async () => {
+        if (ctx.taskBackend.capabilities?.projection_read_mode === "native") {
+            if (!ctx.taskBackend.listProjectionTasks) {
+                throw new CliError({
+                    exitCode: 1,
+                    code: "E_INTERNAL",
+                    message: `Backend ${ctx.taskBackend.id} advertises native projection reads but does not implement listProjectionTasks()`,
+                });
+            }
+            return await ctx.taskBackend.listProjectionTasks();
+        }
+        const tasks = await ctx.taskBackend.listTasks();
+        return tasks.map((task) => toTaskSummary(task));
+    })();
+    return await ctx.memo.taskProjection;
 }
 export async function listTaskProjection(ctx) {
-    if (ctx.taskBackend.listProjectionTasks) {
-        return await ctx.taskBackend.listProjectionTasks();
+    if (ctx.taskBackend.capabilities?.projection_read_mode === "native") {
+        return await listTaskSummariesMemo(ctx);
     }
-    if (ctx.taskBackend.capabilities.reads_from_projection_by_default) {
-        return await listTasksMemo(ctx);
+    if (ctx.taskBackend.capabilities?.reads_from_projection_by_default) {
+        return await listTaskSummariesMemo(ctx);
     }
     return null;
 }

package/dist/commands/shared/task-handoff.d.ts

@@ -0,0 +1,64 @@
+import { type TaskHandoff, type TaskHandoffRunnerNextAction, type TaskHandoffRunnerState } from "@agentplaneorg/core";
+import type { CommandContext } from "./task-backend.js";
+export type TaskHandoffArtifact = TaskHandoff;
+export type TaskHandoffRunnerHint = TaskHandoffRunnerState;
+export type TaskHandoffPaths = {
+    handoff_dir: string;
+    latest_path: string;
+    history_path: string;
+};
+export declare function resolveTaskHandoffPaths(opts: {
+    git_root: string;
+    workflow_dir: string;
+    task_id: string;
+}): TaskHandoffPaths;
+export declare function readTaskHandoffLatest(paths: TaskHandoffPaths): Promise<TaskHandoffArtifact | null>;
+export declare function readTaskHandoffLatestRequired(opts: {
+    task_id: string;
+    paths: TaskHandoffPaths;
+}): Promise<TaskHandoffArtifact>;
+export declare function writeTaskHandoff(opts: {
+    paths: TaskHandoffPaths;
+    handoff: TaskHandoffArtifact;
+}): Promise<void>;
+export declare function currentGitBranch(gitRoot: string): Promise<string | null>;
+export declare function readTaskPrBranch(opts: {
+    ctx: CommandContext;
+    task_id: string;
+}): Promise<string | null>;
+export declare function readTaskPrMetaSummary(opts: {
+    ctx: CommandContext;
+    task_id: string;
+}): Promise<{
+    branch: string | null;
+    base: string | null;
+}>;
+export declare function buildTaskHandoffArtifact(opts: {
+    task_id: string;
+    created_at: string;
+    from_role: string;
+    to_role?: string | null;
+    reason: string;
+    note?: string;
+    branch?: string | null;
+    base_branch?: string | null;
+    head_sha?: string | null;
+    workspace_root?: string | null;
+    pr_branch?: string | null;
+    runner?: TaskHandoffRunnerHint | undefined;
+    next_actions?: string[] | undefined;
+    risks?: string[] | undefined;
+    open_questions?: string[] | undefined;
+    evidence_paths?: string[] | undefined;
+}): TaskHandoffArtifact;
+export declare function buildRunnerHintCommands(opts: {
+    task_id: string;
+    run_id: string | null;
+    status: string | null;
+}): {
+    next_action: TaskHandoffRunnerNextAction;
+    next_command: string | null;
+    resume_command: string | null;
+    retry_command: string | null;
+};
+//# sourceMappingURL=task-handoff.d.ts.map

package/dist/commands/shared/task-handoff.d.ts.map

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

package/dist/commands/shared/task-handoff.js

@@ -0,0 +1,151 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { validateTaskHandoff, } from "@agentplaneorg/core";
+import { CliError } from "../../shared/errors.js";
+import { execFileAsync, gitEnv } from "./git.js";
+import { writeJsonStableIfChanged } from "../../shared/write-if-changed.js";
+function trimOrNull(value) {
+    const trimmed = value?.trim() ?? "";
+    return trimmed.length > 0 ? trimmed : null;
+}
+function normalizeStringList(values) {
+    if (!values?.length)
+        return undefined;
+    const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0);
+    return normalized.length > 0 ? normalized : undefined;
+}
+export function resolveTaskHandoffPaths(opts) {
+    const handoff_dir = path.join(opts.git_root, opts.workflow_dir, opts.task_id, "handoff");
+    return {
+        handoff_dir,
+        latest_path: path.join(handoff_dir, "latest.json"),
+        history_path: path.join(handoff_dir, "history.jsonl"),
+    };
+}
+export async function readTaskHandoffLatest(paths) {
+    try {
+        const raw = await readFile(paths.latest_path, "utf8");
+        return validateTaskHandoff(JSON.parse(raw));
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+export async function readTaskHandoffLatestRequired(opts) {
+    const handoff = await readTaskHandoffLatest(opts.paths);
+    if (handoff)
+        return handoff;
+    throw new CliError({
+        exitCode: 4,
+        code: "E_IO",
+        message: `Task handoff artifact not found for ${opts.task_id} (${opts.paths.latest_path})`,
+    });
+}
+export async function writeTaskHandoff(opts) {
+    await mkdir(opts.paths.handoff_dir, { recursive: true });
+    await writeJsonStableIfChanged(opts.paths.latest_path, opts.handoff);
+    await appendFile(opts.paths.history_path, `${JSON.stringify(opts.handoff)}\n`, "utf8");
+}
+export async function currentGitBranch(gitRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["branch", "--show-current"], {
+            cwd: gitRoot,
+            env: gitEnv(),
+        });
+        return trimOrNull(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readTaskPrBranch(opts) {
+    const summary = await readTaskPrMetaSummary(opts);
+    return summary.branch;
+}
+export async function readTaskPrMetaSummary(opts) {
+    const prMetaPath = path.join(opts.ctx.resolvedProject.gitRoot, opts.ctx.config.paths.workflow_dir, opts.task_id, "pr", "meta.json");
+    try {
+        const raw = JSON.parse(await readFile(prMetaPath, "utf8"));
+        return {
+            branch: trimOrNull(raw.branch),
+            base: trimOrNull(raw.base),
+        };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return { branch: null, base: null };
+        throw err;
+    }
+}
+export function buildTaskHandoffArtifact(opts) {
+    return validateTaskHandoff({
+        schema_version: 1,
+        task_id: opts.task_id,
+        created_at: opts.created_at,
+        from_role: opts.from_role.trim(),
+        to_role: trimOrNull(opts.to_role),
+        reason: opts.reason.trim(),
+        note: trimOrNull(opts.note) ?? undefined,
+        branch: trimOrNull(opts.branch),
+        base_branch: trimOrNull(opts.base_branch),
+        head_sha: trimOrNull(opts.head_sha),
+        workspace_root: trimOrNull(opts.workspace_root),
+        pr_branch: trimOrNull(opts.pr_branch),
+        runner: opts.runner,
+        next_actions: normalizeStringList(opts.next_actions),
+        risks: normalizeStringList(opts.risks),
+        open_questions: normalizeStringList(opts.open_questions),
+        evidence_paths: normalizeStringList(opts.evidence_paths),
+    });
+}
+export function buildRunnerHintCommands(opts) {
+    const taskRunCommand = `agentplane task run ${opts.task_id}`;
+    const resumeCommand = opts.run_id
+        ? `agentplane task run resume ${opts.task_id} ${opts.run_id}`
+        : null;
+    const retryCommand = opts.run_id
+        ? `agentplane task run retry ${opts.task_id} ${opts.run_id}`
+        : null;
+    if (!opts.run_id || !opts.status) {
+        return {
+            next_action: "run",
+            next_command: taskRunCommand,
+            resume_command: null,
+            retry_command: null,
+        };
+    }
+    if (opts.status === "prepared") {
+        return {
+            next_action: "resume",
+            next_command: resumeCommand,
+            resume_command: resumeCommand,
+            retry_command: retryCommand,
+        };
+    }
+    if (opts.status === "failed" || opts.status === "cancelled") {
+        return {
+            next_action: "retry",
+            next_command: retryCommand,
+            resume_command: resumeCommand,
+            retry_command: retryCommand,
+        };
+    }
+    if (opts.status === "success") {
+        return {
+            next_action: "none",
+            next_command: null,
+            resume_command: resumeCommand,
+            retry_command: retryCommand,
+        };
+    }
+    return {
+        next_action: "wait",
+        next_command: null,
+        resume_command: resumeCommand,
+        retry_command: retryCommand,
+    };
+}

package/dist/commands/shared/task-mutation.d.ts

@@ -0,0 +1,36 @@
+import type { TaskData, TaskWriteOptions } from "../../backends/task-backend.js";
+import { type CommandContext } from "./task-backend.js";
+import { getTaskStore, type TaskStoreIntentResult } from "./task-store.js";
+export type TaskMutationPlan = {
+    intents?: TaskStoreIntentResult;
+    nextTask?: TaskData;
+    forceWrite?: boolean;
+    writeOptions?: TaskWriteOptions;
+};
+export type TaskCollectionMutationPlan<TResult> = {
+    tasksToWrite?: readonly TaskData[];
+    result: TResult;
+};
+export declare function withTaskMutationStorage<TResult>(opts: {
+    ctx: CommandContext;
+    local: (store: ReturnType<typeof getTaskStore>) => Promise<TResult> | TResult;
+    remote: (backend: CommandContext["taskBackend"]) => Promise<TResult> | TResult;
+}): Promise<TResult>;
+export declare function applyTaskMutation(opts: {
+    ctx: CommandContext;
+    taskId: string;
+    build: (current: TaskData) => Promise<TaskMutationPlan | null | undefined> | TaskMutationPlan | null | undefined;
+    writeOptions?: TaskWriteOptions;
+}): Promise<{
+    changed: boolean;
+    task: TaskData;
+    mode: "local-store" | "backend";
+}>;
+export declare function applyTaskCollectionMutation<TResult>(opts: {
+    ctx: CommandContext;
+    build: (current: TaskData[]) => Promise<TaskCollectionMutationPlan<TResult>> | TaskCollectionMutationPlan<TResult>;
+}): Promise<{
+    result: TResult;
+    tasksToWrite: TaskData[];
+}>;
+//# sourceMappingURL=task-mutation.d.ts.map

package/dist/commands/shared/task-mutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-mutation.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/task-mutation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACjF,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnG,OAAO,EAGL,YAAY,EACZ,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,OAAO,IAAI;IAChD,YAAY,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,IAAI,EAAE;IAC3D,GAAG,EAAE,cAAc,CAAC;IACpB,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC9E,MAAM,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC,aAAa,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAChF,GAAG,OAAO,CAAC,OAAO,CAAC,CAKnB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,CACL,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,gBAAgB,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,gBAAgB,GAAG,IAAI,GAAG,SAAS,CAAC;IACxF,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,aAAa,GAAG,SAAS,CAAA;CAAE,CAAC,CAuDjF;AAED,wBAAsB,2BAA2B,CAAC,OAAO,EAAE,IAAI,EAAE;IAC/D,GAAG,EAAE,cAAc,CAAC;IACpB,KAAK,EAAE,CACL,OAAO,EAAE,QAAQ,EAAE,KAChB,OAAO,CAAC,0BAA0B,CAAC,OAAO,CAAC,CAAC,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;CACzF,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,QAAQ,EAAE,CAAA;CAAE,CAAC,CAQzD"}

package/dist/commands/shared/task-mutation.js

@@ -0,0 +1,67 @@
+import { loadTaskFromContext, writeTasksOrFallback } from "./task-backend.js";
+import { applyTaskStoreIntentsToTask, backendIsLocalFileBackend, getTaskStore, } from "./task-store.js";
+export async function withTaskMutationStorage(opts) {
+    if (backendIsLocalFileBackend(opts.ctx)) {
+        return await opts.local(getTaskStore(opts.ctx));
+    }
+    return await opts.remote(opts.ctx.taskBackend);
+}
+export async function applyTaskMutation(opts) {
+    if (backendIsLocalFileBackend(opts.ctx)) {
+        const store = getTaskStore(opts.ctx);
+        const result = await store.update(opts.taskId, async (current) => {
+            const plan = await opts.build({ ...current });
+            if (!plan)
+                return current;
+            if (plan.nextTask !== undefined)
+                return plan.nextTask;
+            if (plan.intents !== undefined) {
+                return applyTaskStoreIntentsToTask(current, plan.intents);
+            }
+            return current;
+        }, {
+            expectedRevision: opts.writeOptions?.expectedRevision,
+        });
+        return { ...result, mode: "local-store" };
+    }
+    const current = await loadTaskFromContext({ ctx: opts.ctx, taskId: opts.taskId });
+    let materializedCurrent = current;
+    if (opts.ctx.taskBackend.getTaskDoc) {
+        const currentDoc = typeof current.doc === "string" && current.doc.length > 0
+            ? current.doc
+            : ((await opts.ctx.taskBackend.getTaskDoc(opts.taskId)) ?? "");
+        if (currentDoc !== current.doc) {
+            materializedCurrent = { ...current, doc: currentDoc };
+        }
+    }
+    const plan = await opts.build({ ...materializedCurrent });
+    if (!plan)
+        return { changed: false, task: current, mode: "backend" };
+    const nextTask = plan.nextTask ??
+        (plan.intents === undefined
+            ? undefined
+            : applyTaskStoreIntentsToTask(materializedCurrent, plan.intents));
+    if (nextTask === undefined) {
+        return { changed: false, task: current, mode: "backend" };
+    }
+    const changed = JSON.stringify(materializedCurrent) !== JSON.stringify(nextTask);
+    if (!changed && plan.forceWrite !== true) {
+        return { changed: false, task: nextTask, mode: "backend" };
+    }
+    const mergedWriteOptions = {};
+    if (opts.writeOptions)
+        Object.assign(mergedWriteOptions, opts.writeOptions);
+    if (plan.writeOptions)
+        Object.assign(mergedWriteOptions, plan.writeOptions);
+    await opts.ctx.taskBackend.writeTask(nextTask, mergedWriteOptions);
+    return { changed, task: nextTask, mode: "backend" };
+}
+export async function applyTaskCollectionMutation(opts) {
+    const current = await opts.ctx.taskBackend.listTasks();
+    const plan = await opts.build(current.map((task) => ({ ...task })));
+    const tasksToWrite = [...(plan.tasksToWrite ?? [])];
+    if (tasksToWrite.length > 0) {
+        await writeTasksOrFallback(opts.ctx.taskBackend, tasksToWrite);
+    }
+    return { result: plan.result, tasksToWrite };
+}

package/dist/commands/shared/task-store.d.ts

@@ -24,17 +24,80 @@ export type TaskStorePatch = {
         version?: 2 | 3;
     };
 };
+export type TaskStoreIntent = {
+    kind: "set-task-fields";
+    task: TaskStoreTaskPatch;
+} | {
+    kind: "append-comments";
+    comments: TaskComment[];
+} | {
+    kind: "append-events";
+    events: TaskEvent[];
+} | {
+    kind: "replace-doc";
+    doc: string;
+    expectedCurrentDoc?: string | null;
+} | {
+    kind: "set-section";
+    section: string;
+    text: string;
+    requiredSections: string[];
+    expectedCurrentText?: string | null;
+} | {
+    kind: "touch-doc-meta";
+    updatedBy?: string;
+    version?: 2 | 3;
+};
+export type TaskStoreIntentResult = TaskStoreIntent | readonly TaskStoreIntent[] | null | undefined;
+export type TaskStoreMutationOptions = {
+    expectedRevision?: number;
+};
+export type TaskStoreLike = Pick<TaskStore, "patch"> & {
+    mutate?: TaskStore["mutate"];
+};
+export declare function setTaskFieldsIntent(task: TaskStoreTaskPatch): TaskStoreIntent;
+export declare function appendTaskCommentsIntent(comments: TaskComment[]): TaskStoreIntent;
+export declare function appendTaskCommentIntent(comment: TaskComment): TaskStoreIntent;
+export declare function appendTaskEventsIntent(events: TaskEvent[]): TaskStoreIntent;
+export declare function appendTaskEventIntent(event: TaskEvent): TaskStoreIntent;
+export declare function replaceTaskDocIntent(opts: {
+    doc: string;
+    expectedCurrentDoc?: string | null;
+}): TaskStoreIntent;
+export declare function setTaskSectionIntent(opts: {
+    section: string;
+    text: string;
+    requiredSections: string[];
+    expectedCurrentText?: string | null;
+}): TaskStoreIntent;
+export declare function touchTaskDocMetaIntent(opts?: {
+    updatedBy?: string;
+    version?: 2 | 3;
+}): TaskStoreIntent;
+export declare function taskStorePatchFromIntents(intents: TaskStoreIntentResult): TaskStorePatch | null | undefined;
+export declare function mutateTaskStore(store: TaskStoreLike, taskId: string, builder: (current: TaskData) => Promise<TaskStoreIntentResult> | TaskStoreIntentResult, opts?: TaskStoreMutationOptions): Promise<{
+    changed: boolean;
+    task: TaskData;
+}>;
+export declare function applyTaskStoreIntentsToTask(task: TaskData, intents: TaskStoreIntentResult, opts?: {
+    currentDocVersion?: 2 | 3;
+    docUpdatedAt?: string;
+}): TaskData;
 export declare class TaskStore {
     private ctx;
     private cache;
     constructor(ctx: CommandContext);
     get(taskId: string): Promise<TaskData>;
     private getCached;
-    update(taskId: string, updater: (current: TaskData) => Promise<TaskData> | TaskData): Promise<{
+    update(taskId: string, updater: (current: TaskData) => Promise<TaskData> | TaskData, opts?: TaskStoreMutationOptions): Promise<{
+        changed: boolean;
+        task: TaskData;
+    }>;
+    patch(taskId: string, builder: (current: TaskData) => Promise<TaskStorePatch | null | undefined> | TaskStorePatch | null | undefined, opts?: TaskStoreMutationOptions): Promise<{
         changed: boolean;
         task: TaskData;
     }>;
-    patch(taskId: string, builder: (current: TaskData) => Promise<TaskStorePatch | null | undefined> | TaskStorePatch | null | undefined): Promise<{
+    mutate(taskId: string, builder: (current: TaskData) => Promise<TaskStoreIntentResult> | TaskStoreIntentResult, opts?: TaskStoreMutationOptions): Promise<{
         changed: boolean;
         task: TaskData;
     }>;

package/dist/commands/shared/task-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-store.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/task-store.ts"],"names":[],"mappings":"AAcA,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEf,MAAM,gCAAgC,CAAC;AAIxC,OAAO,EAA8C,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AASpG,KAAK,WAAW,GAAG,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,IAAI,CACF,QAAQ,EACR,KAAK,GAAG,UAAU,GAAG,QAAQ,GAAG,aAAa,GAAG,gBAAgB,GAAG,gBAAgB,CACpF,CACF,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC,GACD;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,CAAC;AAEN,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,cAAc,CAAC,EAAE,WAAW,EAAE,CAAC;IAC/B,YAAY,CAAC,EAAE,SAAS,EAAE,CAAC;IAC3B,GAAG,CAAC,EAAE,iBAAiB,CAAC;IACxB,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;KACjB,CAAC;CACH,CAAC;AA2KF,qBAAa,SAAS;IACpB,OAAO,CAAC,GAAG,CAAiB;IAC5B,OAAO,CAAC,KAAK,CAA0C;gBAE3C,GAAG,EAAE,cAAc;IAIzB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;YAK9B,SAAS;IAsBjB,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,GAC3D,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC;IAM1C,KAAK,CACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CACP,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,cAAc,GAAG,IAAI,GAAG,SAAS,GAClF,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC;YAqClC,YAAY;YAyBZ,aAAa;CAyD5B;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS,CAI3D;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAEtE"}
+{"version":3,"file":"task-store.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/task-store.ts"],"names":[],"mappings":"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"}