@unbrained/pm-cli 2026.5.18 → 2026.5.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.5.18",
+  "version": "2026.5.27",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -28,6 +28,11 @@
       "import": "./dist/sdk/index.js",
       "default": "./dist/sdk/index.js"
     },
+    "./sdk/runtime": {
+      "types": "./dist/sdk/runtime.d.ts",
+      "import": "./dist/sdk/runtime.js",
+      "default": "./dist/sdk/runtime.js"
+    },
     "./cli": {
       "types": "./dist/cli/main.d.ts",
       "import": "./dist/cli/main.js",
@@ -44,7 +49,6 @@
     "CODE_OF_CONDUCT.md",
     "LICENSE",
     "AGENTS.md",
-    "PRD.md",
     "docs/**",
     ".claude-plugin/**",
     "plugins/**",
@@ -69,8 +73,10 @@
     "smoke:claude-plugin": "node scripts/smoke-claude-plugin.mjs",
     "version:check": "node scripts/release-version.mjs check",
     "version:next": "node scripts/release-version.mjs next",
+    "changelog:pm:install": "node dist/cli.js install npm:pm-changelog --project",
+    "changelog:pm": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm",
+    "changelog:pm:check": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm --check",
     "release:notes": "node scripts/generate-release-notes.mjs",
-    "release:changelog": "node scripts/release/changelog-promote.mjs",
     "release:gates": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",
     "release:pipeline": "node scripts/release/run-release-pipeline.mjs",
     "release:pipeline:dry-run": "node scripts/release/run-release-pipeline.mjs --dry-run",
@@ -108,22 +114,20 @@
     }
   },
   "dependencies": {
-    "@sentry/node": "^10.51.0",
-    "@toon-format/toon": "^2.1.0",
+    "@sentry/node": "^10.54.0",
+    "@toon-format/toon": "^2.3.0",
     "commander": "^14.0.3",
     "fast-glob": "^3.3.3",
-    "fast-json-patch": "^3.1.1",
-    "undici": "^8.1.0",
-    "zod": "^4.3.6"
+    "fast-json-patch": "^3.1.1"
   },
   "devDependencies": {
-    "@sentry/cli": "^3.4.1",
-    "@types/node": "^25.6.0",
-    "@vitest/coverage-v8": "^4.1.5",
+    "@sentry/cli": "^3.4.3",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.7",
     "c8": "^11.0.0",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.7"
   },
   "pnpm": {
     "onlyBuiltDependencies": [
@@ -131,7 +135,7 @@
     ],
     "overrides": {
       "rollup": ">=4.59.0",
-      "brace-expansion": ">=5.0.5",
+      "brace-expansion": ">=5.0.6",
       "vite": "7.3.2"
     }
   }

package/packages/pm-beads/extensions/beads/index.js

@@ -1,7 +1,4 @@
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
-const CURRENT_EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
+import { loadPackageRuntimeModule } from "./runtime-loader.js";
 export const manifest = {
     name: "builtin-beads-import",
     version: "0.1.0",
@@ -23,52 +20,8 @@ function toBeadsImportOptions(options) {
         preserveSourceIds: asBoolean(options.preserveSourceIds),
     };
 }
-function resolvePackageRootCandidates() {
-    const candidates = [];
-    const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
-    if (typeof envRoot === "string" && envRoot.trim().length > 0) {
-        candidates.push(path.resolve(envRoot.trim()));
-    }
-    const argvEntry = typeof process.argv[1] === "string" ? process.argv[1].trim() : "";
-    if (argvEntry.length > 0) {
-        const resolvedEntry = path.resolve(argvEntry);
-        const entryDir = path.dirname(resolvedEntry);
-        candidates.push(path.resolve(entryDir, ".."));
-        candidates.push(path.resolve(entryDir, "../.."));
-        candidates.push(path.resolve(entryDir, "../../.."));
-    }
-    return [...new Set(candidates)];
-}
-async function loadRuntimeModule() {
-    const attempted = [];
-    for (const packageRoot of resolvePackageRootCandidates()) {
-        const modulePaths = [
-            path.join(packageRoot, ".agents", "pm", "extensions", "beads", "runtime.js"),
-            path.join(packageRoot, "packages", "pm-beads", "extensions", "beads", "runtime.js"),
-        ];
-        for (const modulePath of modulePaths) {
-            attempted.push(modulePath);
-            try {
-                return await import(pathToFileURL(modulePath).href);
-            }
-            catch {
-                // Try the next package-root candidate.
-            }
-        }
-    }
-    const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.js");
-    attempted.push(localRuntimePath);
-    try {
-        return await import(pathToFileURL(localRuntimePath).href);
-    }
-    catch {
-        // Fall through to the diagnostic below.
-    }
-    throw new Error("Unable to resolve packaged beads extension runtime module. " +
-        `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.js or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`);
-}
 async function runBeadsImportFromRuntime(options, global) {
-    const runtime = await loadRuntimeModule();
+    const runtime = await loadPackageRuntimeModule();
     if (typeof runtime.runBeadsImport !== "function") {
         throw new Error("Bundled beads runtime module is missing runBeadsImport().");
     }

package/packages/pm-beads/extensions/beads/index.ts

@@ -1,10 +1,6 @@
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
 import type { CommandDefinition, ExtensionApi, GlobalOptions } from "../../../../src/sdk/index.js";
 import type { BeadsImportOptions, BeadsImportResult } from "./runtime.js";
-
-const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
-const CURRENT_EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
+import { loadPackageRuntimeModule } from "./runtime-loader.js";
 
 export const manifest = {
   name: "builtin-beads-import",
@@ -35,56 +31,8 @@ function toBeadsImportOptions(options: Record<string, unknown>): BeadsImportOpti
   };
 }
 
-function resolvePackageRootCandidates(): string[] {
-  const candidates: string[] = [];
-  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
-  if (typeof envRoot === "string" && envRoot.trim().length > 0) {
-    candidates.push(path.resolve(envRoot.trim()));
-  }
-  const argvEntry = typeof process.argv[1] === "string" ? process.argv[1].trim() : "";
-  if (argvEntry.length > 0) {
-    const resolvedEntry = path.resolve(argvEntry);
-    const entryDir = path.dirname(resolvedEntry);
-    candidates.push(path.resolve(entryDir, ".."));
-    candidates.push(path.resolve(entryDir, "../.."));
-    candidates.push(path.resolve(entryDir, "../../.."));
-  }
-  return [...new Set(candidates)];
-}
-
-async function loadRuntimeModule(): Promise<RuntimeModule> {
-  const attempted: string[] = [];
-  for (const packageRoot of resolvePackageRootCandidates()) {
-    const modulePaths = [
-      path.join(packageRoot, ".agents", "pm", "extensions", "beads", "runtime.js"),
-      path.join(packageRoot, "packages", "pm-beads", "extensions", "beads", "runtime.js"),
-    ];
-    for (const modulePath of modulePaths) {
-      attempted.push(modulePath);
-      try {
-        return await import(pathToFileURL(modulePath).href) as RuntimeModule;
-      } catch {
-        // Try the next package-root candidate.
-      }
-    }
-  }
-
-  const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.js");
-  attempted.push(localRuntimePath);
-  try {
-    return await import(pathToFileURL(localRuntimePath).href) as RuntimeModule;
-  } catch {
-    // Fall through to the diagnostic below.
-  }
-
-  throw new Error(
-    "Unable to resolve packaged beads extension runtime module. " +
-      `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.js or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`,
-  );
-}
-
 async function runBeadsImportFromRuntime(options: BeadsImportOptions, global: GlobalOptions): Promise<BeadsImportResult> {
-  const runtime = await loadRuntimeModule();
+  const runtime = await loadPackageRuntimeModule() as RuntimeModule;
   if (typeof runtime.runBeadsImport !== "function") {
     throw new Error("Bundled beads runtime module is missing runBeadsImport().");
   }

package/packages/pm-beads/extensions/beads/runtime-loader.js

@@ -0,0 +1,86 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/**
+ * GENERATED by scripts/gen-package-runtime-loaders.mjs - do not edit directly.
+ * This file is shipped with the package extension and intentionally avoids
+ * static SDK imports so project-local installed extensions can load it.
+ */
+
+const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+const CURRENT_EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const EXTENSION_NAME = "beads";
+const PACKAGE_NAME = "pm-beads";
+const DIAGNOSTIC_NAME = "beads";
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+function isMissingRuntimeModuleError(error, modulePath) {
+  if (!isRecord(error) || error.code !== "ERR_MODULE_NOT_FOUND") {
+    return false;
+  }
+  const message = typeof error.message === "string" ? error.message : "";
+  const moduleUrl = pathToFileURL(modulePath).href;
+  return message.includes(modulePath) || message.includes(moduleUrl);
+}
+
+function resolvePackageRootCandidates() {
+  const candidates = [];
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot === "string" && envRoot.trim().length > 0) {
+    candidates.push(path.resolve(envRoot.trim()));
+  }
+  const argvEntry = typeof process.argv[1] === "string" ? process.argv[1].trim() : "";
+  if (argvEntry.length > 0) {
+    const resolvedEntry = path.resolve(argvEntry);
+    const entryDir = path.dirname(resolvedEntry);
+    candidates.push(path.resolve(entryDir, ".."));
+    candidates.push(path.resolve(entryDir, "../.."));
+    candidates.push(path.resolve(entryDir, "../../.."));
+  }
+  return [...new Set(candidates)];
+}
+
+export async function loadPackageRuntimeModule() {
+  const attempted = [];
+  for (const packageRoot of resolvePackageRootCandidates()) {
+    const modulePaths = [
+      path.join(packageRoot, ".agents", "pm", "extensions", EXTENSION_NAME, "runtime.js"),
+      path.join(packageRoot, "packages", PACKAGE_NAME, "extensions", EXTENSION_NAME, "runtime.js"),
+    ];
+    for (const modulePath of modulePaths) {
+      attempted.push(modulePath);
+      if (!existsSync(modulePath)) {
+        continue;
+      }
+      try {
+        return await import(pathToFileURL(modulePath).href);
+      } catch (error) {
+        if (isMissingRuntimeModuleError(error, modulePath)) {
+          continue;
+        }
+        throw error;
+      }
+    }
+  }
+
+  const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.js");
+  attempted.push(localRuntimePath);
+  if (existsSync(localRuntimePath)) {
+    try {
+      return await import(pathToFileURL(localRuntimePath).href);
+    } catch (error) {
+      if (!isMissingRuntimeModuleError(error, localRuntimePath)) {
+        throw error;
+      }
+    }
+  }
+
+  throw new Error(
+    `Unable to resolve packaged ${DIAGNOSTIC_NAME} extension runtime module. ` +
+      `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.js or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`,
+  );
+}

package/packages/pm-beads/extensions/beads/runtime-loader.ts

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/**
+ * GENERATED by scripts/gen-package-runtime-loaders.mjs - do not edit directly.
+ * This file is shipped with the package extension and intentionally avoids
+ * static SDK imports so project-local installed extensions can load it.
+ */
+
+const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+const CURRENT_EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const EXTENSION_NAME = "beads";
+const PACKAGE_NAME = "pm-beads";
+const DIAGNOSTIC_NAME = "beads";
+
+export type PackageRuntimeModule = Record<string, unknown>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isMissingRuntimeModuleError(error: unknown, modulePath: string): boolean {
+  if (!isRecord(error) || error.code !== "ERR_MODULE_NOT_FOUND") {
+    return false;
+  }
+  const message = typeof error.message === "string" ? error.message : "";
+  const moduleUrl = pathToFileURL(modulePath).href;
+  return message.includes(modulePath) || message.includes(moduleUrl);
+}
+
+function resolvePackageRootCandidates(): string[] {
+  const candidates: string[] = [];
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot === "string" && envRoot.trim().length > 0) {
+    candidates.push(path.resolve(envRoot.trim()));
+  }
+  const argvEntry = typeof process.argv[1] === "string" ? process.argv[1].trim() : "";
+  if (argvEntry.length > 0) {
+    const resolvedEntry = path.resolve(argvEntry);
+    const entryDir = path.dirname(resolvedEntry);
+    candidates.push(path.resolve(entryDir, ".."));
+    candidates.push(path.resolve(entryDir, "../.."));
+    candidates.push(path.resolve(entryDir, "../../.."));
+  }
+  return [...new Set(candidates)];
+}
+
+export async function loadPackageRuntimeModule(): Promise<PackageRuntimeModule> {
+  const attempted: string[] = [];
+  for (const packageRoot of resolvePackageRootCandidates()) {
+    const modulePaths = [
+      path.join(packageRoot, ".agents", "pm", "extensions", EXTENSION_NAME, "runtime.js"),
+      path.join(packageRoot, "packages", PACKAGE_NAME, "extensions", EXTENSION_NAME, "runtime.js"),
+    ];
+    for (const modulePath of modulePaths) {
+      attempted.push(modulePath);
+      if (!existsSync(modulePath)) {
+        continue;
+      }
+      try {
+        return await import(pathToFileURL(modulePath).href) as PackageRuntimeModule;
+      } catch (error: unknown) {
+        if (isMissingRuntimeModuleError(error, modulePath)) {
+          continue;
+        }
+        throw error;
+      }
+    }
+  }
+
+  const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.js");
+  attempted.push(localRuntimePath);
+  if (existsSync(localRuntimePath)) {
+    try {
+      return await import(pathToFileURL(localRuntimePath).href) as PackageRuntimeModule;
+    } catch (error: unknown) {
+      if (!isMissingRuntimeModuleError(error, localRuntimePath)) {
+        throw error;
+      }
+    }
+  }
+
+  throw new Error(
+    `Unable to resolve packaged ${DIAGNOSTIC_NAME} extension runtime module. ` +
+      `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.js or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`,
+  );
+}

package/packages/pm-beads/extensions/beads/runtime.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { DEPENDENCY_KIND_VALUES, EXIT_CODE, PmCliError, acquireLock, appendHistoryEntry, canonicalDocument, createHistoryEntry, generateItemId, getActiveExtensionRegistrations, getHistoryPath, getItemPath, getSettingsPath, isTimestampLiteral, locateItem, normalizeFrontMatter, normalizeItemId, normalizeRawItemId, normalizeStatusInput, nowIso, parseTags, pathExists, readSettings, removeFileIfExists, resolveItemTypeRegistry, resolvePmRoot, runActiveOnReadHooks, runActiveOnWriteHooks, serializeItemDocument, writeFileAtomic, } from "../../../../dist/sdk/index.js";
+import { DEPENDENCY_KIND_VALUES, EXIT_CODE, PmCliError, canonicalDocument, commitImportedItem, generateItemId, getActiveExtensionRegistrations, getItemPath, isTimestampLiteral, locateItem, normalizeFrontMatter, normalizeItemId, normalizeRawItemId, nowIso, pathExists, readSettings, resolveItemTypeRegistry, resolvePmRoot, runActiveOnReadHooks, ensureTrackerInitialized, selectImportAuthor, toEstimatedMinutesValue, toImportPriority, toImportStatus, toImportTags, toNonEmptyImportString, } from "../../../../dist/sdk/index.js";
 const PRIMARY_AUTO_DISCOVERY_FILES = [
     ".beads/issues.jsonl",
     "issues.jsonl",
@@ -9,13 +9,13 @@ const UNSAFE_AUTO_DISCOVERY_FILES = [
     ".beads/sync_base.jsonl",
     "sync_base.jsonl",
 ];
-function toNonEmptyString(value) {
-    if (typeof value !== "string") {
-        return undefined;
-    }
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
-}
+// Shared, behavior-identical value coercers are sourced from the SDK adapter
+// surface; package-specific mappings (timestamps, item types, dependencies,
+// linked artifacts) stay local below.
+const toNonEmptyString = toNonEmptyImportString;
+const toEstimatedMinutes = toEstimatedMinutesValue;
+const toPriority = toImportPriority;
+const toTags = toImportTags;
 function toIsoString(value) {
     const raw = toNonEmptyString(value);
     if (!raw) {
@@ -26,44 +26,6 @@ function toIsoString(value) {
     }
     return raw;
 }
-function toEstimatedMinutes(value) {
-    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
-        return value;
-    }
-    if (typeof value === "string" && value.trim().length > 0) {
-        const parsed = Number(value);
-        if (Number.isFinite(parsed) && parsed >= 0) {
-            return parsed;
-        }
-    }
-    return undefined;
-}
-function toPriority(value) {
-    const fallback = 2;
-    if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 4) {
-        return value;
-    }
-    if (typeof value === "string" && value.trim().length > 0) {
-        const parsed = Number(value);
-        if (Number.isInteger(parsed) && parsed >= 0 && parsed <= 4) {
-            return parsed;
-        }
-    }
-    return fallback;
-}
-function toTags(value) {
-    if (Array.isArray(value)) {
-        const tags = value
-            .filter((entry) => typeof entry === "string")
-            .map((entry) => entry.trim().toLowerCase())
-            .filter((entry) => entry.length > 0);
-        return Array.from(new Set(tags)).sort((left, right) => left.localeCompare(right));
-    }
-    if (typeof value === "string") {
-        return parseTags(value);
-    }
-    return [];
-}
 function toItemType(value) {
     const raw = toNonEmptyString(value);
     const normalized = raw?.toLowerCase();
@@ -86,16 +48,7 @@ function toItemType(value) {
             return { type: "Task", sourceType: raw };
     }
 }
-function toStatus(value) {
-    const normalized = toNonEmptyString(value);
-    if (normalized) {
-        const canonical = normalizeStatusInput(normalized);
-        if (canonical) {
-            return canonical;
-        }
-    }
-    return "open";
-}
+const toStatus = toImportStatus;
 function toDependencyKind(value) {
     const raw = toNonEmptyString(value);
     const normalized = raw?.toLowerCase();
@@ -332,24 +285,8 @@ function toLinkedDocs(value) {
     }
     return docs.length > 0 ? docs : undefined;
 }
-function selectAuthor(explicitAuthor, settingsAuthor) {
-    const candidate = explicitAuthor ?? process.env.PM_AUTHOR ?? settingsAuthor;
-    const trimmed = candidate.trim();
-    return trimmed.length > 0 ? trimmed : "unknown";
-}
-function ensureInitHasRun(pmRoot) {
-    return pathExists(getSettingsPath(pmRoot)).then((exists) => {
-        if (!exists) {
-            throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-        }
-    });
-}
-function emptyDocument() {
-    return {
-        metadata: {},
-        body: "",
-    };
-}
+const selectAuthor = selectImportAuthor;
+const ensureInitHasRun = ensureTrackerInitialized;
 function resolveInputPath(rawPath) {
     return path.isAbsolute(rawPath) ? rawPath : path.resolve(process.cwd(), rawPath);
 }
@@ -515,48 +452,22 @@ export async function runBeadsImport(options, global) {
             continue;
         }
         const itemPath = getItemPath(pmRoot, type, id, "toon", typeRegistry.type_to_folder);
-        const historyPath = getHistoryPath(pmRoot, id);
-        try {
-            const releaseLock = await acquireLock(pmRoot, id, settings.locks.ttl_seconds, author);
-            try {
-                await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: "toon" }));
-                try {
-                    const entry = createHistoryEntry({
-                        nowIso: nowIso(),
-                        author,
-                        op: "import",
-                        before: emptyDocument(),
-                        after: afterDocument,
-                        message,
-                    });
-                    await appendHistoryEntry(historyPath, entry);
-                    warnings.push(...(await runActiveOnWriteHooks({
-                        path: itemPath,
-                        scope: "project",
-                        op: "import",
-                    })), ...(await runActiveOnWriteHooks({
-                        path: historyPath,
-                        scope: "project",
-                        op: "import:history",
-                    })));
-                }
-                catch (error) {
-                    await removeFileIfExists(itemPath);
-                    throw error;
-                }
-            }
-            finally {
-                await releaseLock();
-            }
-        }
-        catch (error) {
-            if (error instanceof PmCliError && error.exitCode === EXIT_CODE.CONFLICT) {
-                warnings.push(`beads_import_lock_conflict:${id}`);
-                skipped += 1;
-                continue;
-            }
-            throw error;
+        const commit = await commitImportedItem({
+            pmRoot,
+            id,
+            itemPath,
+            document: afterDocument,
+            author,
+            message,
+            settings,
+            conflictWarningPrefix: "beads_import_lock_conflict",
+        });
+        if (!commit.committed) {
+            warnings.push(commit.conflictWarning);
+            skipped += 1;
+            continue;
         }
+        warnings.push(...commit.writeWarnings);
         ids.push(id);
         imported += 1;
     }