agentplane 0.3.5 → 0.3.7

package/dist/commands/task/migrate-doc.js

@@ -1,13 +1,14 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { atomicWriteFile, ensureDocSections, extractTaskDoc, loadConfig, mergeTaskDoc, normalizeTaskDoc, parseTaskReadme, renderTaskReadme, resolveProject, setMarkdownSection, } from "@agentplaneorg/core";
+import { atomicWriteFile, ensureDocSections, extractTaskDoc, loadConfig, mergeTaskDoc, normalizeTaskDoc, parseTaskReadme, renderTaskDocFromSections, renderTaskReadme, resolveProject, setMarkdownSection, taskDocToSectionMap, } from "@agentplaneorg/core";
 import { mapCoreError } from "../../cli/error-map.js";
 import { exitCodeForError } from "../../cli/exit-codes.js";
 import { fileExists, getPathKind } from "../../cli/fs-utils.js";
 import { successMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
-import { exportTaskProjectionSnapshot, loadCommandContext } from "../shared/task-backend.js";
-import { extractDocSection, extractTaskObservationSection, normalizeTaskDocVersion, normalizeVerificationSectionLayout, } from "./shared/docs.js";
+import { execFileAsync, gitEnv } from "../shared/git.js";
+import { exportTaskProjectionSnapshot, loadCommandContext, } from "../shared/task-backend.js";
+import { extractDocSection, extractTaskObservationSection, decodeEscapedTaskTextNewlines, normalizeTaskDocVersion, normalizeVerificationSectionLayout, } from "./shared/docs.js";
 import { defaultTaskDocV3 } from "./doc-template.js";
 const V3_CANONICAL_ORDER = [
     "Summary",
@@ -22,6 +23,21 @@ const HUMAN_TEXT_SECTIONS = new Set(["summary", "context", "scope", "plan", "fin
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function normalizeRevision(value) {
+    return Number.isInteger(value) && typeof value === "number" && value > 0 ? value : null;
+}
+function normalizeCanonicalSections(value) {
+    if (!isRecord(value))
+        return null;
+    const out = {};
+    for (const [title, text] of Object.entries(value)) {
+        const normalizedTitle = title.trim();
+        if (!normalizedTitle || typeof text !== "string")
+            continue;
+        out[normalizedTitle] = text.replaceAll("\r\n", "\n").trimEnd();
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
 function normalizeSectionKey(section) {
     return section.trim().replaceAll(/\s+/g, " ").toLowerCase();
 }
@@ -61,13 +77,7 @@ function renderMarkdownSections(sections) {
 function normalizeLiteralNewlinesInHumanSection(title, text) {
     if (!HUMAN_TEXT_SECTIONS.has(normalizeSectionKey(title)))
         return text.trimEnd();
-    let next = text.replaceAll("\r\n", "\n");
-    const escapedDoubleNewline = next.includes(String.raw `\n\n`) || next.includes(String.raw `\r\n\r\n`);
-    const escapedNewlineMatches = next.match(/\\n/g) ?? [];
-    if (escapedDoubleNewline || escapedNewlineMatches.length >= 2) {
-        next = next.replaceAll(String.raw `\r\n`, "\n").replaceAll(String.raw `\n`, "\n");
-    }
-    return next.trimEnd();
+    return decodeEscapedTaskTextNewlines(text).trimEnd();
 }
 function firstSectionText(sections, title) {
     const target = normalizeSectionKey(title);
@@ -183,9 +193,12 @@ async function migrateTaskReadmeDoc(opts) {
     ensurePlanApprovalFrontmatter(frontmatter);
     ensureVerificationFrontmatter(frontmatter);
     normalizeFrontmatterNoteTimestamps(frontmatter);
+    const canonicalSections = normalizeCanonicalSections(frontmatter.sections);
     const required = opts.config.tasks.doc.required_sections;
     const extracted = extractTaskDoc(parsed.body);
-    const baseDoc = extracted || parsed.body;
+    const baseDoc = canonicalSections === null
+        ? extracted || parsed.body
+        : renderTaskDocFromSections(canonicalSections);
     let nextDoc = normalizeTaskDoc(ensureDocSections(baseDoc, required));
     const docVersion = normalizeTaskDocVersion(frontmatter.doc_version);
     if (docVersion === 2) {
@@ -208,6 +221,8 @@ async function migrateTaskReadmeDoc(opts) {
         }
     }
     const nextBody = extracted ? mergeTaskDoc(parsed.body, nextDoc) : nextDoc;
+    frontmatter.sections = taskDocToSectionMap(nextDoc);
+    frontmatter.revision = normalizeRevision(frontmatter.revision) ?? 1;
     const rendered = renderTaskReadme(frontmatter, nextBody);
     const next = rendered.endsWith("\n") ? rendered : `${rendered}\n`;
     if (next === original)
@@ -232,48 +247,118 @@ async function resolveReadmePaths(opts) {
     }
     return out;
 }
-export async function cmdTaskMigrateDoc(opts) {
-    const params = { all: opts.all, quiet: opts.quiet, taskIds: opts.taskIds };
+async function exportProjectionSnapshotIfChanged(opts) {
+    if (!(opts.ctx.taskBackend.exportProjectionSnapshot || opts.ctx.taskBackend.exportTasksJson)) {
+        return [];
+    }
+    const relOutputPath = opts.tasksPath.replaceAll("\\", "/");
+    const outputPath = path.join(opts.resolvedGitRoot, relOutputPath);
+    let before = null;
+    try {
+        before = await readFile(outputPath, "utf8");
+    }
+    catch {
+        before = null;
+    }
+    await exportTaskProjectionSnapshot({ ctx: opts.ctx, outputPath });
+    let after = null;
+    try {
+        after = await readFile(outputPath, "utf8");
+    }
+    catch {
+        after = null;
+    }
+    if (before === after)
+        return [];
+    return (await canStageGitPath(opts.resolvedGitRoot, relOutputPath)) ? [relOutputPath] : [];
+}
+async function canStageGitPath(gitRoot, relPath) {
     try {
-        const resolved = await resolveProject({
+        await execFileAsync("git", ["ls-files", "--error-unmatch", "--", relPath], {
+            cwd: gitRoot,
+            env: gitEnv(),
+        });
+        return true;
+    }
+    catch {
+        // Continue below: untracked paths may still be stageable when they are not ignored.
+    }
+    try {
+        await execFileAsync("git", ["check-ignore", "--quiet", "--", relPath], {
+            cwd: gitRoot,
+            env: gitEnv(),
+        });
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+export async function migrateTaskDocsInWorkspace(opts) {
+    const resolved = opts.resolvedProject ??
+        (await resolveProject({
             cwd: opts.cwd,
             rootOverride: opts.rootOverride ?? null,
-        });
-        const loaded = await loadConfig(resolved.agentplaneDir);
-        const ctx = await loadCommandContext({
+        }));
+    let config = opts.config;
+    if (!config) {
+        const loadedConfig = await loadConfig(resolved.agentplaneDir);
+        config = loadedConfig.config;
+    }
+    const ctx = opts.ctx ??
+        (await loadCommandContext({
             cwd: opts.cwd,
             rootOverride: opts.rootOverride ?? null,
             resolvedProject: resolved,
-            config: loaded.config,
-        });
-        const tasksDir = path.join(resolved.gitRoot, loaded.config.paths.workflow_dir);
-        const readmePaths = await resolveReadmePaths({ tasksDir, params });
-        if (!params.all) {
-            for (const readmePath of readmePaths) {
-                if (!(await fileExists(readmePath))) {
-                    const taskId = path.basename(path.dirname(readmePath));
-                    throw new CliError({
-                        exitCode: exitCodeForError("E_IO"),
-                        code: "E_IO",
-                        message: `Task README not found: ${taskId}`,
-                    });
-                }
-            }
-        }
-        let changed = 0;
+            config,
+        }));
+    const params = { all: opts.all, quiet: false, taskIds: opts.taskIds };
+    const tasksDir = path.join(resolved.gitRoot, config.paths.workflow_dir);
+    const readmePaths = await resolveReadmePaths({ tasksDir, params });
+    if (!opts.all) {
         for (const readmePath of readmePaths) {
-            const res = await migrateTaskReadmeDoc({ readmePath, config: loaded.config });
-            if (res.changed)
-                changed += 1;
+            if (!(await fileExists(readmePath))) {
+                const taskId = path.basename(path.dirname(readmePath));
+                throw new CliError({
+                    exitCode: exitCodeForError("E_IO"),
+                    code: "E_IO",
+                    message: `Task README not found: ${taskId}`,
+                });
+            }
         }
-        // Refresh the local export snapshot so doctor and other snapshot-based checks
-        // immediately observe the migrated README contract without a separate task export.
-        if (ctx.taskBackend.exportProjectionSnapshot || ctx.taskBackend.exportTasksJson) {
-            const outPath = path.join(resolved.gitRoot, loaded.config.paths.tasks_path);
-            await exportTaskProjectionSnapshot({ ctx, outputPath: outPath });
+    }
+    let changed = 0;
+    const changedPaths = [];
+    for (const readmePath of readmePaths) {
+        const res = await migrateTaskReadmeDoc({ readmePath, config });
+        if (!res.changed)
+            continue;
+        changed += 1;
+        const relReadmePath = path.relative(resolved.gitRoot, readmePath).replaceAll("\\", "/");
+        if (await canStageGitPath(resolved.gitRoot, relReadmePath)) {
+            changedPaths.push(relReadmePath);
         }
+    }
+    if (changed > 0) {
+        changedPaths.push(...(await exportProjectionSnapshotIfChanged({
+            ctx,
+            resolvedGitRoot: resolved.gitRoot,
+            tasksPath: config.paths.tasks_path,
+        })));
+    }
+    return { changed, changedPaths: [...new Set(changedPaths)] };
+}
+export async function cmdTaskMigrateDoc(opts) {
+    const params = { all: opts.all, quiet: opts.quiet, taskIds: opts.taskIds };
+    try {
+        const result = await migrateTaskDocsInWorkspace({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+            all: params.all,
+            taskIds: params.taskIds,
+        });
         if (!params.quiet) {
-            process.stdout.write(`${successMessage("migrated task docs", undefined, `changed=${changed}`)}\n`);
+            process.stdout.write(`${successMessage("migrated task docs", undefined, `changed=${result.changed}`)}\n`);
         }
         return 0;
     }

package/dist/commands/task/new.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../../src/commands/task/new.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAcpF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAmDF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,aAAa,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgFlB"}
+{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../../src/commands/task/new.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAcpF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAmDF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,aAAa,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmFlB"}

package/dist/commands/task/new.js

@@ -1,4 +1,4 @@
-import { setMarkdownSection } from "@agentplaneorg/core";
+import { setMarkdownSection, taskDocToSectionMap } from "@agentplaneorg/core";
 import { mapBackendError } from "../../cli/error-map.js";
 import { backendNotSupportedMessage, warnMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
@@ -73,6 +73,7 @@ export async function runTaskNewParsed(opts) {
             status: "TODO",
             priority: p.priority,
             owner: p.owner,
+            revision: 1,
             tags: p.tags,
             depends_on: p.dependsOn,
             verify: p.verify,
@@ -107,6 +108,7 @@ export async function runTaskNewParsed(opts) {
         if (hasSpike && hasImplementationTags) {
             process.stderr.write(`${warnMessage("spike is combined with a primary tag that requires verify steps; consider splitting spike vs implementation tasks")}\n`);
         }
+        task.sections = taskDocToSectionMap(task.doc ?? "");
         await ctx.taskBackend.writeTask(task);
         process.stdout.write(`${taskId}\n`);
         return 0;

package/dist/commands/task/plan-set.command.js

@@ -10,7 +10,7 @@ export const taskPlanSetSpec = {
             kind: "string",
             name: "text",
             valueHint: "<text>",
-            description: "Plan text to write into the task README Plan section.",
+            description: String.raw `Plan text to write into the task README Plan section. Literal escaped newlines (\n) are normalized for inline text.`,
         },
         {
             kind: "string",

package/dist/commands/task/plan.command.d.ts

@@ -0,0 +1,8 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+type TaskPlanGroupParsed = {
+    cmd: string[];
+};
+export declare const taskPlanSpec: CommandSpec<TaskPlanGroupParsed>;
+export declare const runTaskPlan: CommandHandler<TaskPlanGroupParsed>;
+export {};
+//# sourceMappingURL=plan.command.d.ts.map

package/dist/commands/task/plan.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/plan.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAItF,KAAK,mBAAmB,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAI7C,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,mBAAmB,CAqBzD,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,cAAc,CAAC,mBAAmB,CAW3D,CAAC"}

package/dist/commands/task/plan.command.js

@@ -0,0 +1,37 @@
+import { usageError } from "../../cli/spec/errors.js";
+import { suggestOne } from "../../cli/spec/suggest.js";
+const TASK_PLAN_SUBCOMMANDS = ["set", "approve", "reject"];
+export const taskPlanSpec = {
+    id: ["task", "plan"],
+    group: "Task",
+    summary: "Task plan commands (set/approve/reject).",
+    synopsis: ["agentplane task plan <set|approve|reject> [args] [options]"],
+    args: [{ name: "cmd", required: false, variadic: true, valueHint: "<subcommand>" }],
+    examples: [
+        {
+            cmd: 'agentplane task plan set <task-id> --text "..." --updated-by ORCHESTRATOR',
+            why: "Write or replace the task plan.",
+        },
+        {
+            cmd: "agentplane task plan approve <task-id> --by ORCHESTRATOR",
+            why: "Approve the current task plan.",
+        },
+        {
+            cmd: 'agentplane task plan reject <task-id> --by ORCHESTRATOR --note "..."',
+            why: "Reject the current task plan with a note.",
+        },
+    ],
+    parse: (raw) => ({ cmd: (raw.args.cmd ?? []) }),
+};
+export const runTaskPlan = (_ctx, p) => {
+    const input = p.cmd.join(" ");
+    const suggestion = suggestOne(input, [...TASK_PLAN_SUBCOMMANDS]);
+    const suffix = suggestion ? ` Did you mean: ${suggestion}?` : "";
+    const message = p.cmd.length === 0 ? "Missing subcommand." : `Unknown subcommand: ${p.cmd[0]}.`;
+    throw usageError({
+        spec: taskPlanSpec,
+        command: "task plan",
+        message: `${message}${suffix}`,
+        context: { command: "task plan" },
+    });
+};

package/dist/commands/task/plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/commands/task/plan.ts"],"names":[],"mappings":"AASA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAuDnC,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6ElB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CA4FlB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CAuDlB"}
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/commands/task/plan.ts"],"names":[],"mappings":"AASA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAkJnC,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8HlB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CA2DlB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CAkElB"}