@agentplaneorg/core 0.1.1 → 0.1.3

package/README.md

@@ -1,5 +1,68 @@
 # @agentplaneorg/core
 
-Internal core library used by the `agentplane` CLI.
+[![npm](https://img.shields.io/npm/v/@agentplaneorg/core.svg)](https://www.npmjs.com/package/@agentplaneorg/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/basilisk-labs/agentplane/blob/main/LICENSE)
+[![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-3c873a.svg)](https://github.com/basilisk-labs/agentplane/blob/main/docs/user/prerequisites.mdx)
 
-This package is intended to be published alongside `agentplane` to satisfy runtime dependencies.
+Core utilities and models used by the `agentplane` CLI. This package exposes the reusable building blocks
+for project discovery, config handling, task readme parsing, and task export/linting.
+
+If you are an end-user, install the CLI instead: https://www.npmjs.com/package/agentplane
+
+## Install
+
+```bash
+npm install @agentplaneorg/core
+```
+
+## Requirements
+
+- Node.js >= 20
+- ESM-only (`type: module`)
+
+## Usage
+
+```ts
+import {
+  resolveProject,
+  loadConfig,
+  listTasks,
+  readTask,
+  buildTasksExportSnapshot,
+} from "@agentplaneorg/core";
+
+const project = await resolveProject(process.cwd());
+const config = await loadConfig(project.root);
+const tasks = await listTasks(project.root);
+const task = await readTask(project.root, tasks[0]?.id ?? "");
+const snapshot = await buildTasksExportSnapshot(project.root);
+
+console.log(config.data.workflow_mode, task?.id, snapshot.meta.version);
+```
+
+## Exported Modules
+
+| Area              | Highlights                                                     |
+| ----------------- | -------------------------------------------------------------- |
+| Project discovery | `resolveProject`, `findGitRoot`                                |
+| Config            | `loadConfig`, `saveConfig`, `setByDottedKey`, `validateConfig` |
+| Task README       | `parseTaskReadme`, `renderTaskReadme`                          |
+| Task store        | `createTask`, `listTasks`, `readTask`, `setTaskDocSection`     |
+| Exports           | `buildTasksExportSnapshot`, `writeTasksExport`, checksums      |
+| Linting           | `lintTasksFile`, `lintTasksSnapshot`                           |
+| Git               | `getStagedFiles`, `getUnstagedFiles`, base branch helpers      |
+| Commit policy     | `validateCommitSubject`, `extractTaskSuffix`                   |
+
+## Stability
+
+This package is versioned alongside the CLI and is primarily used by `agentplane`. The API is stable for
+current use cases, but expect changes as the CLI evolves.
+
+## Docs
+
+- Repository: https://github.com/basilisk-labs/agentplane
+- Developer docs: https://github.com/basilisk-labs/agentplane/tree/main/docs
+
+## License
+
+MIT

package/dist/task-readme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-readme.d.ts","sourceRoot":"","sources":["../src/task-readme.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAQF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAYlE;AAiED,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CA8BlF;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3F"}
+{"version":3,"file":"task-readme.d.ts","sourceRoot":"","sources":["../src/task-readme.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAqBF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAYlE;AAiED,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CA8BlF;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3F"}

package/dist/task-readme.js

@@ -2,11 +2,25 @@ import { parse as parseYaml } from "yaml";
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
+function stripLeadingFrontmatterBlocks(body) {
+    let next = body.replaceAll("\r\n", "\n");
+    while (true) {
+        const trimmed = next.replace(/^\n+/, "");
+        if (!trimmed.startsWith("---\n"))
+            break;
+        const end = trimmed.indexOf("\n---\n", 4);
+        if (end === -1)
+            break;
+        next = trimmed.slice(end + 5);
+    }
+    return next;
+}
 function splitFrontmatter(markdown) {
     const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(markdown);
     if (!match)
         return { frontmatterText: null, body: markdown };
-    return { frontmatterText: match[1] ?? null, body: markdown.slice(match[0].length) };
+    const body = stripLeadingFrontmatterBlocks(markdown.slice(match[0].length));
+    return { frontmatterText: match[1] ?? null, body };
 }
 export function parseTaskReadme(markdown) {
     const { frontmatterText, body } = splitFrontmatter(markdown);

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

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

package/dist/task-store.js

@@ -6,6 +6,9 @@ import { parseTaskReadme, renderTaskReadme } from "./task-readme.js";
 function nowIso() {
     return new Date().toISOString();
 }
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
 export function validateTaskDocMetadata(frontmatter) {
     const errors = [];
     if (frontmatter.doc_version !== 2)
@@ -107,6 +110,146 @@ function setMarkdownSection(body, section, text) {
     const out = [...lines.slice(0, start + 1), ...replacement, ...lines.slice(nextHeading)];
     return `${out.join("\n")}\n`;
 }
+function normalizeDocSectionName(section) {
+    return section.trim().replaceAll(/\s+/g, " ").toLowerCase();
+}
+function getLastCommentAuthor(frontmatter) {
+    const comments = frontmatter.comments;
+    if (!Array.isArray(comments))
+        return null;
+    const entries = comments;
+    for (let i = entries.length - 1; i >= 0; i -= 1) {
+        const entry = entries[i];
+        if (!isRecord(entry))
+            continue;
+        const author = entry.author;
+        if (typeof author === "string") {
+            const trimmed = author.trim();
+            if (trimmed)
+                return trimmed;
+        }
+    }
+    return null;
+}
+function resolveDocUpdatedBy(frontmatter, updatedBy) {
+    if (updatedBy != null) {
+        const explicit = updatedBy.trim();
+        if (explicit.length === 0) {
+            throw new Error("doc_updated_by must be a non-empty string");
+        }
+        return explicit;
+    }
+    const lastAuthor = getLastCommentAuthor(frontmatter);
+    if (lastAuthor)
+        return lastAuthor;
+    const existing = frontmatter.doc_updated_by;
+    if (typeof existing === "string") {
+        const trimmed = existing.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return "agentplane";
+}
+function splitCombinedHeadingLines(doc) {
+    const lines = doc.replaceAll("\r\n", "\n").split("\n");
+    const out = [];
+    let inFence = false;
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("```")) {
+            inFence = !inFence;
+            out.push(line);
+            continue;
+        }
+        if (!inFence && line.includes("## ")) {
+            const matches = [...line.matchAll(/##\s+/g)];
+            if (matches.length > 1 && matches[0]?.index === 0) {
+                let start = 0;
+                for (let i = 1; i < matches.length; i += 1) {
+                    const idx = matches[i]?.index ?? 0;
+                    const chunk = line.slice(start, idx).trimEnd();
+                    if (chunk)
+                        out.push(chunk);
+                    start = idx;
+                }
+                const last = line.slice(start).trimEnd();
+                if (last)
+                    out.push(last);
+                continue;
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
+function normalizeDocSections(doc, required) {
+    const lines = splitCombinedHeadingLines(doc);
+    const sections = new Map();
+    const order = [];
+    const pendingSeparator = new Set();
+    let currentKey = null;
+    for (const line of lines) {
+        const match = /^##\s+(.*)$/.exec(line.trim());
+        if (match) {
+            const title = match[1]?.trim() ?? "";
+            const key = normalizeDocSectionName(title);
+            if (key) {
+                const existing = sections.get(key);
+                if (existing) {
+                    if (existing.lines.some((entry) => entry.trim() !== "")) {
+                        pendingSeparator.add(key);
+                    }
+                }
+                else {
+                    sections.set(key, { title, lines: [] });
+                    order.push(key);
+                }
+                currentKey = key;
+                continue;
+            }
+        }
+        if (currentKey) {
+            const entry = sections.get(currentKey);
+            if (!entry)
+                continue;
+            if (pendingSeparator.has(currentKey) && line.trim() !== "") {
+                entry.lines.push("");
+                pendingSeparator.delete(currentKey);
+            }
+            entry.lines.push(line);
+        }
+    }
+    const out = [];
+    const seen = new Set(order);
+    for (const key of order) {
+        const section = sections.get(key);
+        if (!section)
+            continue;
+        out.push(`## ${section.title}`);
+        if (section.lines.length > 0) {
+            out.push(...section.lines);
+        }
+        else {
+            out.push("");
+        }
+        out.push("");
+    }
+    for (const requiredSection of required) {
+        const requiredKey = normalizeDocSectionName(requiredSection);
+        if (seen.has(requiredKey))
+            continue;
+        out.push(`## ${requiredSection}`, "", "");
+    }
+    return `${out.join("\n").trimEnd()}\n`;
+}
+function ensureDocSections(doc, required) {
+    const trimmed = doc.trim();
+    if (!trimmed) {
+        const blocks = required.map((section) => `## ${section}\n`);
+        return `${blocks.join("\n").trimEnd()}\n`;
+    }
+    return normalizeDocSections(doc, required);
+}
 export async function createTask(opts) {
     const { tasksDir, idSuffixLengthDefault } = await getTasksDir({
         cwd: opts.cwd,
@@ -154,16 +297,15 @@ export async function setTaskDocSection(opts) {
     const readmePath = taskReadmePath(tasksDir, opts.taskId);
     const original = await readFile(readmePath, "utf8");
     const parsed = parseTaskReadme(original);
-    const updatedBy = (opts.updatedBy ?? "agentplane").trim();
-    if (updatedBy.length === 0)
-        throw new Error("doc_updated_by must be a non-empty string");
+    const updatedBy = resolveDocUpdatedBy(parsed.frontmatter, opts.updatedBy);
     const nextFrontmatter = {
         ...parsed.frontmatter,
         doc_version: 2,
         doc_updated_at: nowIso(),
         doc_updated_by: updatedBy,
     };
-    const nextBody = setMarkdownSection(parsed.body, opts.section, opts.text);
+    const baseDoc = ensureDocSections(parsed.body, loaded.config.tasks.doc.required_sections);
+    const nextBody = ensureDocSections(setMarkdownSection(baseDoc, opts.section, opts.text), loaded.config.tasks.doc.required_sections);
     const nextText = renderTaskReadme(nextFrontmatter, nextBody);
     await writeFile(readmePath, nextText, "utf8");
     return { readmePath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentplaneorg/core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Core utilities and models for the Agent Plane CLI.",
   "keywords": [
     "agentplane",