agentplane 0.3.23 → 0.3.24

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

@@ -1,239 +1,16 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { loadConfig } from "@agentplaneorg/core/config";
+import { gitEnv } from "@agentplaneorg/core/git";
+import { execFileAsync } from "@agentplaneorg/core/process";
 import { resolveProject } from "@agentplaneorg/core/project";
-import { atomicWriteFile } from "@agentplaneorg/core/fs";
-import { ensureDocSections, extractTaskDoc, mergeTaskDoc, normalizeTaskDoc, parseTaskReadme, renderTaskDocFromSections, renderTaskReadme, setMarkdownSection, taskDocToSectionMap, } from "@agentplaneorg/core/tasks";
 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 { execFileAsync } from "@agentplaneorg/core/process";
-import { gitEnv } from "@agentplaneorg/core/git";
 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",
-    "Scope",
-    "Plan",
-    "Verify Steps",
-    "Verification",
-    "Rollback Plan",
-    "Findings",
-];
-const HUMAN_TEXT_SECTIONS = new Set(["summary", "context", "scope", "plan", "findings", "notes"]);
-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();
-}
-function parseMarkdownSections(doc) {
-    const lines = doc.replaceAll("\r\n", "\n").split("\n");
-    const sections = [];
-    let current = null;
-    for (const line of lines) {
-        const match = /^##\s+(.*)$/.exec(line.trim());
-        if (match) {
-            if (current) {
-                current.text = current.text.trimEnd();
-                sections.push(current);
-            }
-            current = { title: (match[1] ?? "").trim(), text: "" };
-            continue;
-        }
-        if (current) {
-            current.text = current.text.length > 0 ? `${current.text}\n${line}` : line;
-        }
-    }
-    if (current) {
-        current.text = current.text.trimEnd();
-        sections.push(current);
-    }
-    return sections;
-}
-function renderMarkdownSections(sections) {
-    return sections
-        .map((section) => {
-        const text = section.text.trimEnd();
-        return text ? `## ${section.title}\n\n${text}` : `## ${section.title}\n`;
-    })
-        .join("\n\n")
-        .trimEnd();
-}
-function normalizeLiteralNewlinesInHumanSection(title, text) {
-    if (!HUMAN_TEXT_SECTIONS.has(normalizeSectionKey(title)))
-        return text.trimEnd();
-    return decodeEscapedTaskTextNewlines(text).trimEnd();
-}
-function firstSectionText(sections, title) {
-    const target = normalizeSectionKey(title);
-    return sections.find((section) => normalizeSectionKey(section.title) === target)?.text ?? null;
-}
-function mergeObservationText(doc, version) {
-    const preferred = extractTaskObservationSection(doc, version)?.trim() ?? "";
-    const notes = extractDocSection(doc, "Notes")?.trim() ?? "";
-    const findings = extractDocSection(doc, "Findings")?.trim() ?? "";
-    const out = [];
-    for (const candidate of [preferred, findings, notes]) {
-        if (!candidate)
-            continue;
-        if (out.includes(candidate))
-            continue;
-        out.push(candidate);
-    }
-    return out.join("\n\n").trim();
-}
-function migrateDocToV3(opts) {
-    const currentSections = parseMarkdownSections(opts.doc);
-    const defaultSections = parseMarkdownSections(defaultTaskDocV3({ title: opts.title, description: opts.description }));
-    const emitted = new Set();
-    const nextSections = [];
-    const observationText = mergeObservationText(opts.doc, 2);
-    for (const title of V3_CANONICAL_ORDER) {
-        const key = normalizeSectionKey(title);
-        const currentText = firstSectionText(currentSections, title);
-        const defaultText = firstSectionText(defaultSections, title) ?? "";
-        let nextText = currentText ?? defaultText;
-        if (title === "Verification") {
-            nextText = normalizeVerificationSectionLayout(currentText ?? defaultText, 3);
-        }
-        if (title === "Findings") {
-            nextText = observationText || defaultText;
-        }
-        if (nextText === null)
-            continue;
-        nextText = normalizeLiteralNewlinesInHumanSection(title, nextText);
-        nextSections.push({ title, text: nextText.trimEnd() });
-        emitted.add(key);
-        if (title === "Findings")
-            emitted.add("notes");
-    }
-    for (const section of currentSections) {
-        const key = normalizeSectionKey(section.title);
-        if (emitted.has(key))
-            continue;
-        nextSections.push({ title: section.title, text: section.text.trimEnd() });
-        emitted.add(key);
-    }
-    return renderMarkdownSections(nextSections);
-}
-function ensurePlanApprovalFrontmatter(frontmatter) {
-    const raw = frontmatter.plan_approval;
-    if (isRecord(raw) && typeof raw.state === "string")
-        return;
-    frontmatter.plan_approval = {
-        state: "pending",
-        updated_at: null,
-        updated_by: null,
-        note: null,
-    };
-}
-function ensureVerificationFrontmatter(frontmatter) {
-    const raw = frontmatter.verification;
-    if (isRecord(raw) && typeof raw.state === "string")
-        return;
-    frontmatter.verification = {
-        state: "pending",
-        updated_at: null,
-        updated_by: null,
-        note: null,
-    };
-}
-const DATE_ONLY_ON_RE = /\bon (\d{4}-\d{2}-\d{2})(?!T)\b/g;
-function isIsoTimestamp(value) {
-    if (!value.includes("T") || !value.endsWith("Z"))
-        return false;
-    const ms = Date.parse(value);
-    return Number.isFinite(ms);
-}
-function normalizeNoteTimestamp(opts) {
-    if (!isIsoTimestamp(opts.updatedAt))
-        return opts.note;
-    const updatedDate = opts.updatedAt.slice(0, 10);
-    return opts.note.replaceAll(DATE_ONLY_ON_RE, (match, date) => {
-        if (date !== updatedDate)
-            return match;
-        return `on ${opts.updatedAt}`;
-    });
-}
-function normalizeFrontmatterNoteTimestamps(frontmatter) {
-    const plan = frontmatter.plan_approval;
-    if (isRecord(plan) && typeof plan.note === "string" && typeof plan.updated_at === "string") {
-        plan.note = normalizeNoteTimestamp({ note: plan.note, updatedAt: plan.updated_at });
-    }
-    const verification = frontmatter.verification;
-    if (isRecord(verification) &&
-        typeof verification.note === "string" &&
-        typeof verification.updated_at === "string") {
-        verification.note = normalizeNoteTimestamp({
-            note: verification.note,
-            updatedAt: verification.updated_at,
-        });
-    }
-}
-async function migrateTaskReadmeDoc(opts) {
-    const originalRaw = await readFile(opts.readmePath, "utf8");
-    const original = originalRaw.endsWith("\n") ? originalRaw : `${originalRaw}\n`;
-    const parsed = parseTaskReadme(original);
-    const frontmatter = { ...parsed.frontmatter };
-    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 = canonicalSections === null
-        ? extracted || parsed.body
-        : renderTaskDocFromSections(canonicalSections);
-    let nextDoc = normalizeTaskDoc(ensureDocSections(baseDoc, required));
-    const docVersion = normalizeTaskDocVersion(frontmatter.doc_version);
-    if (docVersion === 2) {
-        frontmatter.doc_version = 3;
-        nextDoc = migrateDocToV3({
-            title: typeof frontmatter.title === "string" ? frontmatter.title : "",
-            description: typeof frontmatter.description === "string" ? frontmatter.description : "",
-            doc: nextDoc,
-        });
-    }
-    else {
-        const verificationSection = extractDocSection(nextDoc, "Verification");
-        const normalizedVerification = normalizeVerificationSectionLayout(verificationSection, docVersion);
-        nextDoc = setMarkdownSection(nextDoc, "Verification", normalizedVerification);
-        for (const sectionTitle of ["Summary", "Context", "Scope", "Plan", "Findings", "Notes"]) {
-            const sectionText = extractDocSection(nextDoc, sectionTitle);
-            if (sectionText == null)
-                continue;
-            nextDoc = setMarkdownSection(nextDoc, sectionTitle, normalizeLiteralNewlinesInHumanSection(sectionTitle, sectionText));
-        }
-    }
-    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)
-        return { changed: false };
-    await atomicWriteFile(opts.readmePath, next, "utf8");
-    return { changed: true };
-}
+import { migrateTaskReadmeDoc } from "./migrate-doc.readme.js";
 async function resolveReadmePaths(opts) {
     if (!opts.params.all) {
         return opts.params.taskIds.map((taskId) => path.join(opts.tasksDir, taskId, "README.md"));
@@ -251,6 +28,28 @@ async function resolveReadmePaths(opts) {
     }
     return out;
 }
+async function canStageGitPath(gitRoot, relPath) {
+    try {
+        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;
+    }
+}
 async function exportProjectionSnapshotIfChanged(opts) {
     if (!(opts.ctx.taskBackend.exportProjectionSnapshot || opts.ctx.taskBackend.exportTasksJson)) {
         return [];
@@ -276,28 +75,6 @@ async function exportProjectionSnapshotIfChanged(opts) {
         return [];
     return (await canStageGitPath(opts.resolvedGitRoot, relOutputPath)) ? [relOutputPath] : [];
 }
-async function canStageGitPath(gitRoot, relPath) {
-    try {
-        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({

package/dist/commands/task/migrate-doc.readme.d.ts

@@ -0,0 +1,8 @@
+import type { AgentplaneConfig } from "@agentplaneorg/core/config";
+export declare function migrateTaskReadmeDoc(opts: {
+    readmePath: string;
+    config: AgentplaneConfig;
+}): Promise<{
+    changed: boolean;
+}>;
+//# sourceMappingURL=migrate-doc.readme.d.ts.map

package/dist/commands/task/migrate-doc.readme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-doc.readme.d.ts","sourceRoot":"","sources":["../../../src/commands/task/migrate-doc.readme.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AA4NnE,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;CAC1B,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAuDhC"}

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

@@ -0,0 +1,225 @@
+import { readFile } from "node:fs/promises";
+import { atomicWriteFile } from "@agentplaneorg/core/fs";
+import { ensureDocSections, extractTaskDoc, mergeTaskDoc, normalizeTaskDoc, parseTaskReadme, renderTaskDocFromSections, renderTaskReadme, setMarkdownSection, taskDocToSectionMap, } from "@agentplaneorg/core/tasks";
+import { decodeEscapedTaskTextNewlines, extractDocSection, extractTaskObservationSection, normalizeTaskDocVersion, normalizeVerificationSectionLayout, } from "./shared/docs.js";
+import { defaultTaskDocV3 } from "./doc-template.js";
+const V3_CANONICAL_ORDER = [
+    "Summary",
+    "Scope",
+    "Plan",
+    "Verify Steps",
+    "Verification",
+    "Rollback Plan",
+    "Findings",
+];
+const HUMAN_TEXT_SECTIONS = new Set(["summary", "context", "scope", "plan", "findings", "notes"]);
+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();
+}
+function parseMarkdownSections(doc) {
+    const lines = doc.replaceAll("\r\n", "\n").split("\n");
+    const sections = [];
+    let current = null;
+    for (const line of lines) {
+        const match = /^##\s+(.*)$/.exec(line.trim());
+        if (match) {
+            if (current) {
+                current.text = current.text.trimEnd();
+                sections.push(current);
+            }
+            current = { title: (match[1] ?? "").trim(), text: "" };
+            continue;
+        }
+        if (current) {
+            current.text = current.text.length > 0 ? `${current.text}\n${line}` : line;
+        }
+    }
+    if (current) {
+        current.text = current.text.trimEnd();
+        sections.push(current);
+    }
+    return sections;
+}
+function renderMarkdownSections(sections) {
+    return sections
+        .map((section) => {
+        const text = section.text.trimEnd();
+        return text ? `## ${section.title}\n\n${text}` : `## ${section.title}\n`;
+    })
+        .join("\n\n")
+        .trimEnd();
+}
+function normalizeLiteralNewlinesInHumanSection(title, text) {
+    if (!HUMAN_TEXT_SECTIONS.has(normalizeSectionKey(title)))
+        return text.trimEnd();
+    return decodeEscapedTaskTextNewlines(text).trimEnd();
+}
+function firstSectionText(sections, title) {
+    const target = normalizeSectionKey(title);
+    return sections.find((section) => normalizeSectionKey(section.title) === target)?.text ?? null;
+}
+function mergeObservationText(doc, version) {
+    const preferred = extractTaskObservationSection(doc, version)?.trim() ?? "";
+    const notes = extractDocSection(doc, "Notes")?.trim() ?? "";
+    const findings = extractDocSection(doc, "Findings")?.trim() ?? "";
+    const out = [];
+    for (const candidate of [preferred, findings, notes]) {
+        if (!candidate)
+            continue;
+        if (out.includes(candidate))
+            continue;
+        out.push(candidate);
+    }
+    return out.join("\n\n").trim();
+}
+function migrateDocToV3(opts) {
+    const currentSections = parseMarkdownSections(opts.doc);
+    const defaultSections = parseMarkdownSections(defaultTaskDocV3({ title: opts.title, description: opts.description }));
+    const emitted = new Set();
+    const nextSections = [];
+    const observationText = mergeObservationText(opts.doc, 2);
+    for (const title of V3_CANONICAL_ORDER) {
+        const key = normalizeSectionKey(title);
+        const currentText = firstSectionText(currentSections, title);
+        const defaultText = firstSectionText(defaultSections, title) ?? "";
+        let nextText = currentText ?? defaultText;
+        if (title === "Verification") {
+            nextText = normalizeVerificationSectionLayout(currentText ?? defaultText, 3);
+        }
+        if (title === "Findings") {
+            nextText = observationText || defaultText;
+        }
+        if (nextText === null)
+            continue;
+        nextText = normalizeLiteralNewlinesInHumanSection(title, nextText);
+        nextSections.push({ title, text: nextText.trimEnd() });
+        emitted.add(key);
+        if (title === "Findings")
+            emitted.add("notes");
+    }
+    for (const section of currentSections) {
+        const key = normalizeSectionKey(section.title);
+        if (emitted.has(key))
+            continue;
+        nextSections.push({ title: section.title, text: section.text.trimEnd() });
+        emitted.add(key);
+    }
+    return renderMarkdownSections(nextSections);
+}
+function ensurePlanApprovalFrontmatter(frontmatter) {
+    const raw = frontmatter.plan_approval;
+    if (isRecord(raw) && typeof raw.state === "string")
+        return;
+    frontmatter.plan_approval = {
+        state: "pending",
+        updated_at: null,
+        updated_by: null,
+        note: null,
+    };
+}
+function ensureVerificationFrontmatter(frontmatter) {
+    const raw = frontmatter.verification;
+    if (isRecord(raw) && typeof raw.state === "string")
+        return;
+    frontmatter.verification = {
+        state: "pending",
+        updated_at: null,
+        updated_by: null,
+        note: null,
+    };
+}
+const DATE_ONLY_ON_RE = /\bon (\d{4}-\d{2}-\d{2})(?!T)\b/g;
+function isIsoTimestamp(value) {
+    if (!value.includes("T") || !value.endsWith("Z"))
+        return false;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms);
+}
+function normalizeNoteTimestamp(opts) {
+    if (!isIsoTimestamp(opts.updatedAt))
+        return opts.note;
+    const updatedDate = opts.updatedAt.slice(0, 10);
+    return opts.note.replaceAll(DATE_ONLY_ON_RE, (match, date) => {
+        if (date !== updatedDate)
+            return match;
+        return `on ${opts.updatedAt}`;
+    });
+}
+function normalizeFrontmatterNoteTimestamps(frontmatter) {
+    const plan = frontmatter.plan_approval;
+    if (isRecord(plan) && typeof plan.note === "string" && typeof plan.updated_at === "string") {
+        plan.note = normalizeNoteTimestamp({ note: plan.note, updatedAt: plan.updated_at });
+    }
+    const verification = frontmatter.verification;
+    if (isRecord(verification) &&
+        typeof verification.note === "string" &&
+        typeof verification.updated_at === "string") {
+        verification.note = normalizeNoteTimestamp({
+            note: verification.note,
+            updatedAt: verification.updated_at,
+        });
+    }
+}
+export async function migrateTaskReadmeDoc(opts) {
+    const originalRaw = await readFile(opts.readmePath, "utf8");
+    const original = originalRaw.endsWith("\n") ? originalRaw : `${originalRaw}\n`;
+    const parsed = parseTaskReadme(original);
+    const frontmatter = { ...parsed.frontmatter };
+    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 = canonicalSections === null
+        ? extracted || parsed.body
+        : renderTaskDocFromSections(canonicalSections);
+    let nextDoc = normalizeTaskDoc(ensureDocSections(baseDoc, required));
+    const docVersion = normalizeTaskDocVersion(frontmatter.doc_version);
+    if (docVersion === 2) {
+        frontmatter.doc_version = 3;
+        nextDoc = migrateDocToV3({
+            title: typeof frontmatter.title === "string" ? frontmatter.title : "",
+            description: typeof frontmatter.description === "string" ? frontmatter.description : "",
+            doc: nextDoc,
+        });
+    }
+    else {
+        const verificationSection = extractDocSection(nextDoc, "Verification");
+        const normalizedVerification = normalizeVerificationSectionLayout(verificationSection, docVersion);
+        nextDoc = setMarkdownSection(nextDoc, "Verification", normalizedVerification);
+        for (const sectionTitle of ["Summary", "Context", "Scope", "Plan", "Findings", "Notes"]) {
+            const sectionText = extractDocSection(nextDoc, sectionTitle);
+            if (sectionText == null)
+                continue;
+            nextDoc = setMarkdownSection(nextDoc, sectionTitle, normalizeLiteralNewlinesInHumanSection(sectionTitle, sectionText));
+        }
+    }
+    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)
+        return { changed: false };
+    await atomicWriteFile(opts.readmePath, next, "utf8");
+    return { changed: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentplane",
-  "version": "0.3.23",
+  "version": "0.3.24",
   "description": "Agent Plane CLI for task workflows, recipes, and project automation.",
   "keywords": [
     "agentplane",
@@ -56,8 +56,8 @@
     "prepublishOnly": "node ../../scripts/enforce-github-publish.mjs && npm run prepack"
   },
   "dependencies": {
-    "@agentplaneorg/core": "0.3.23",
-    "@agentplaneorg/recipes": "0.3.23",
+    "@agentplaneorg/core": "0.3.24",
+    "@agentplaneorg/recipes": "0.3.24",
     "@clack/prompts": "^1.2.0",
     "yauzl": "^2.10.0",
     "zod": "^3",