npm - @agentplaneorg/core - Versions diffs - 0.1.2 → 0.1.4 - Mend

@agentplaneorg/core 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,5 +1,81 @@
 # @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
+## 5-minute start (CLI)
+```bash
+npm install -g agentplane
+agentplane init
+agentplane quickstart
+agentplane task new --title "First task" --description "Describe the change" --priority med --owner ORCHESTRATOR --tag docs
+agentplane verify <task-id>
+agentplane finish <task-id>
+```
+## For library usage
+### 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-store.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"task-store.d.ts","sourceRoot":"","sources":["../src/task-store.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAC/D,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AAE7D,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7C,WAAW,EAAE,CAAC,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,eAAe,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;~~AAMF~~,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAgBtF;AA8BD,wBAAsB,WAAW,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC;IAC9F,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB,EAAE,MAAM,CAAC;CAC/B,CAAC,CASD;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvE;~~AAwDD~~,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAuC9C;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,GAAG,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,~~CA4BlC~~;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,UAAU,CAAC,CActB;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CA0BxB"}
1	+ {"version":3,"file":"task-store.d.ts","sourceRoot":"","sources":["../src/task-store.ts"],"names":[],"mappings":"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"}

package/dist/task-store.js CHANGED Viewed

@@ -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,152 @@ 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 && trimmed.toLowerCase() !== "agentplane")
+            return trimmed;
+    }
+    const owner = frontmatter.owner;
+    if (typeof owner === "string") {
+        const trimmed = owner.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,
@@ -132,7 +281,7 @@ export async function createTask(opts) {
             comments: [],
             doc_version: 2,
             doc_updated_at: nowIso(),
-            doc_updated_by: "agentplane",
+            doc_updated_by: opts.owner,
             description: opts.description,
         };
         const body = defaultTaskBody();
@@ -154,16 +303,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 CHANGED Viewed

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