@unbrained/pm-cli 2026.3.9 → 2026.5.1

package/.agents/pm/extensions/.managed-extensions.json

@@ -0,0 +1,42 @@
+{
+  "version": 1,
+  "updated_at": "2026-04-25T17:01:49.273Z",
+  "entries": [
+    {
+      "name": "builtin-beads-import",
+      "directory": "beads",
+      "scope": "project",
+      "manifest_version": "0.1.0",
+      "manifest_entry": "./index.js",
+      "capabilities": [
+        "commands",
+        "schema"
+      ],
+      "installed_at": "2026-04-25T17:01:49.268Z",
+      "updated_at": "2026-04-25T17:01:49.268Z",
+      "source": {
+        "kind": "local",
+        "input": "builtin-beads-import",
+        "location": "/home/steve/GITHUB_RELEASE/pm-cli/.agents/pm/extensions/beads"
+      }
+    },
+    {
+      "name": "builtin-todos-import-export",
+      "directory": "todos",
+      "scope": "project",
+      "manifest_version": "0.1.0",
+      "manifest_entry": "./index.js",
+      "capabilities": [
+        "commands",
+        "schema"
+      ],
+      "installed_at": "2026-04-25T17:01:49.268Z",
+      "updated_at": "2026-04-25T17:01:49.268Z",
+      "source": {
+        "kind": "local",
+        "input": "builtin-todos-import-export",
+        "location": "/home/steve/GITHUB_RELEASE/pm-cli/.agents/pm/extensions/todos"
+      }
+    }
+  ]
+}

package/.agents/pm/extensions/beads/index.js

@@ -0,0 +1,109 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+
+export const manifest = {
+  name: "builtin-beads-import",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands", "schema"],
+};
+
+function asOptionalString(value) {
+  return typeof value === "string" ? value : undefined;
+}
+
+function asBoolean(value) {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function toBeadsImportOptions(options) {
+  return {
+    file: asOptionalString(options.file),
+    author: asOptionalString(options.author),
+    message: asOptionalString(options.message),
+    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 modulePath = path.join(packageRoot, ".agents", "pm", "extensions", "beads", "runtime.js");
+    attempted.push(modulePath);
+    try {
+      return await import(pathToFileURL(modulePath).href);
+    } catch {
+      // Try the next package-root candidate.
+    }
+  }
+  throw new Error(
+    "Unable to resolve bundled beads extension runtime module. " +
+      `Tried: ${attempted.join(", ")}. Ensure PM_CLI_PACKAGE_ROOT points to an installed pm package root.`,
+  );
+}
+
+async function runBeadsImportFromRuntime(options, global) {
+  const runtime = await loadRuntimeModule();
+  if (typeof runtime.runBeadsImport !== "function") {
+    throw new Error('Bundled beads runtime module is missing runBeadsImport().');
+  }
+  return runtime.runBeadsImport(options, global);
+}
+
+export function activate(api) {
+  api.registerCommand({
+    name: "beads import",
+    description: "Import Beads JSONL records into pm items.",
+    flags: [
+      {
+        long: "--file",
+        value_name: "path",
+        value_type: "string",
+        description: "Path to the Beads JSONL source file.",
+      },
+      {
+        long: "--author",
+        value_name: "author",
+        value_type: "string",
+        description: "Override import mutation author.",
+      },
+      {
+        long: "--message",
+        value_name: "text",
+        value_type: "string",
+        description: "Override import history message.",
+      },
+      {
+        long: "--preserve-source-ids",
+        value_type: "boolean",
+        description: "Preserve source IDs from Beads payload records when possible.",
+      },
+    ],
+    run: async (context) => runBeadsImportFromRuntime(toBeadsImportOptions(context.options), context.global),
+  });
+}
+
+export default {
+  manifest,
+  activate,
+};

package/.agents/pm/extensions/beads/manifest.json

@@ -0,0 +1,7 @@
+{
+  "name": "builtin-beads-import",
+  "version": "0.1.0",
+  "entry": "./index.js",
+  "priority": 0,
+  "capabilities": ["commands", "schema"]
+}

package/{dist/cli/commands/beads.js → .agents/pm/extensions/beads/runtime.js}

@@ -1,19 +1,29 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { pathExists, removeFileIfExists, writeFileAtomic } from "../../core/fs/fs-utils.js";
-import { runActiveOnReadHooks, runActiveOnWriteHooks } from "../../core/extensions/index.js";
-import { appendHistoryEntry, createHistoryEntry } from "../../core/history/history.js";
-import { generateItemId, normalizeItemId } from "../../core/item/id.js";
-import { canonicalDocument, normalizeFrontMatter, serializeItemDocument } from "../../core/item/item-format.js";
-import { parseTags } from "../../core/item/parse.js";
-import { acquireLock } from "../../core/lock/lock.js";
-import { EXIT_CODE } from "../../core/shared/constants.js";
-import { PmCliError } from "../../core/shared/errors.js";
-import { nowIso } from "../../core/shared/time.js";
-import { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
-import { readSettings } from "../../core/store/settings.js";
-import { DEPENDENCY_KIND_VALUES, STATUS_VALUES } from "../../types/index.js";
-const DEFAULT_BEADS_FILE = ".beads/issues.jsonl";
+import { pathExists, removeFileIfExists, writeFileAtomic } from "../../../../dist/core/fs/fs-utils.js";
+import { getActiveExtensionRegistrations, runActiveOnReadHooks, runActiveOnWriteHooks } from "../../../../dist/core/extensions/index.js";
+import { appendHistoryEntry, createHistoryEntry } from "../../../../dist/core/history/history.js";
+import { generateItemId, normalizeItemId, normalizeRawItemId } from "../../../../dist/core/item/id.js";
+import { canonicalDocument, normalizeFrontMatter, serializeItemDocument } from "../../../../dist/core/item/item-format.js";
+import { normalizeStatusInput } from "../../../../dist/core/item/status.js";
+import { resolveItemTypeRegistry } from "../../../../dist/core/item/type-registry.js";
+import { parseTags } from "../../../../dist/core/item/parse.js";
+import { acquireLock } from "../../../../dist/core/lock/lock.js";
+import { EXIT_CODE } from "../../../../dist/core/shared/constants.js";
+import { PmCliError } from "../../../../dist/core/shared/errors.js";
+import { isTimestampLiteral, nowIso } from "../../../../dist/core/shared/time.js";
+import { locateItem } from "../../../../dist/core/store/item-store.js";
+import { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from "../../../../dist/core/store/paths.js";
+import { readSettings } from "../../../../dist/core/store/settings.js";
+import { DEPENDENCY_KIND_VALUES } from "../../../../dist/types/index.js";
+const PRIMARY_AUTO_DISCOVERY_FILES = [
+    ".beads/issues.jsonl",
+    "issues.jsonl",
+];
+const UNSAFE_AUTO_DISCOVERY_FILES = [
+    ".beads/sync_base.jsonl",
+    "sync_base.jsonl",
+];
 function toNonEmptyString(value) {
     if (typeof value !== "string") {
         return undefined;
@@ -26,11 +36,10 @@ function toIsoString(value) {
     if (!raw) {
         return undefined;
     }
-    const timestamp = Date.parse(raw);
-    if (!Number.isFinite(timestamp)) {
+    if (!isTimestampLiteral(raw)) {
         return undefined;
     }
-    return new Date(timestamp).toISOString();
+    return raw;
 }
 function toEstimatedMinutes(value) {
     if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
@@ -71,37 +80,75 @@ function toTags(value) {
     return [];
 }
 function toItemType(value) {
-    const normalized = toNonEmptyString(value)?.toLowerCase();
+    const raw = toNonEmptyString(value);
+    const normalized = raw?.toLowerCase();
     switch (normalized) {
         case "epic":
-            return "Epic";
+            return { type: "Epic" };
         case "feature":
-            return "Feature";
+            return { type: "Feature" };
         case "task":
-            return "Task";
+            return { type: "Task" };
         case "chore":
-            return "Chore";
+            return { type: "Chore" };
         case "issue":
-            return "Issue";
+            return { type: "Issue" };
+        case "bug":
+            return { type: "Issue", sourceType: raw };
+        case "event":
+            return { type: "Task", sourceType: raw };
         default:
-            return "Task";
+            return { type: "Task", sourceType: raw };
     }
 }
 function toStatus(value) {
-    const normalized = toNonEmptyString(value)?.toLowerCase();
-    if (normalized && STATUS_VALUES.includes(normalized)) {
-        return normalized;
+    const normalized = toNonEmptyString(value);
+    if (normalized) {
+        const canonical = normalizeStatusInput(normalized);
+        if (canonical) {
+            return canonical;
+        }
     }
     return "open";
 }
 function toDependencyKind(value) {
-    const normalized = toNonEmptyString(value)?.toLowerCase();
-    if (normalized && DEPENDENCY_KIND_VALUES.includes(normalized)) {
-        return normalized;
+    const raw = toNonEmptyString(value);
+    const normalized = raw?.toLowerCase();
+    if (!normalized) {
+        return { kind: "related" };
+    }
+    const preserveIfChanged = (kind) => ({
+        kind,
+        sourceKind: normalized === kind ? undefined : raw,
+    });
+    if (DEPENDENCY_KIND_VALUES.includes(normalized)) {
+        return preserveIfChanged(normalized);
+    }
+    switch (normalized) {
+        case "parent-child":
+            return preserveIfChanged("parent_child");
+        case "child-of":
+            return preserveIfChanged("child_of");
+        case "related-to":
+        case "relates-to":
+            return preserveIfChanged("related_to");
+        case "discovered-from":
+            return preserveIfChanged("discovered_from");
+        case "blocked-by":
+            return preserveIfChanged("blocked_by");
+        case "incident-from":
+            return preserveIfChanged("incident_from");
+        default:
+            return {
+                kind: "related",
+                sourceKind: raw,
+            };
     }
-    return "related";
 }
-function toDependencies(value, fallbackCreatedAt, prefix) {
+function normalizeImportedId(id, prefix, preserveSourceIds) {
+    return preserveSourceIds ? normalizeRawItemId(id) : normalizeItemId(id, prefix);
+}
+function toDependencies(value, fallbackCreatedAt, prefix, preserveSourceIds) {
     if (!Array.isArray(value)) {
         return undefined;
     }
@@ -113,7 +160,7 @@ function toDependencies(value, fallbackCreatedAt, prefix) {
                 continue;
             }
             dependencies.push({
-                id: normalizeItemId(id, prefix),
+                id: normalizeImportedId(id, prefix, preserveSourceIds),
                 kind: "related",
                 created_at: fallbackCreatedAt,
             });
@@ -127,11 +174,13 @@ function toDependencies(value, fallbackCreatedAt, prefix) {
         if (!id) {
             continue;
         }
+        const dependencyKind = toDependencyKind(candidate.type ?? candidate.kind);
         dependencies.push({
-            id: normalizeItemId(id, prefix),
-            kind: toDependencyKind(candidate.kind),
+            id: normalizeImportedId(id, prefix, preserveSourceIds),
+            kind: dependencyKind.kind,
             created_at: toIsoString(candidate.created_at) ?? fallbackCreatedAt,
-            author: toNonEmptyString(candidate.author),
+            author: toNonEmptyString(candidate.author) ?? toNonEmptyString(candidate.created_by),
+            source_kind: dependencyKind.sourceKind,
         });
     }
     return dependencies.length > 0 ? dependencies : undefined;
@@ -319,22 +368,76 @@ function emptyDocument() {
 function resolveInputPath(rawPath) {
     return path.isAbsolute(rawPath) ? rawPath : path.resolve(process.cwd(), rawPath);
 }
+async function readStdin() {
+    if (process.stdin.isTTY === true) {
+        throw new PmCliError('--file value "-" requires piped stdin input. Pipe JSONL content into the command, or end manual stdin with Ctrl+D (Unix/macOS) or Ctrl+Z then Enter (Windows).', EXIT_CODE.USAGE);
+    }
+    return await new Promise((resolve, reject) => {
+        let raw = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            raw += chunk;
+        });
+        process.stdin.on("end", () => resolve(raw));
+        process.stdin.on("error", reject);
+    });
+}
+async function resolveBeadsSource(rawPath) {
+    const explicitSource = toNonEmptyString(rawPath);
+    if (explicitSource) {
+        if (explicitSource === "-") {
+            return {
+                source: "-",
+                raw: await readStdin(),
+                warnings: [],
+            };
+        }
+        const explicitPath = resolveInputPath(explicitSource);
+        if (!(await pathExists(explicitPath))) {
+            throw new PmCliError(`Beads source file not found at ${explicitPath}`, EXIT_CODE.NOT_FOUND);
+        }
+        return {
+            source: explicitSource,
+            sourcePath: explicitPath,
+            raw: await fs.readFile(explicitPath, "utf8"),
+            warnings: [],
+        };
+    }
+    for (const candidate of PRIMARY_AUTO_DISCOVERY_FILES) {
+        const candidatePath = resolveInputPath(candidate);
+        if (await pathExists(candidatePath)) {
+            return {
+                source: candidate,
+                sourcePath: candidatePath,
+                raw: await fs.readFile(candidatePath, "utf8"),
+                warnings: candidate === PRIMARY_AUTO_DISCOVERY_FILES[0] ? [] : [`beads_import_source_autodiscovered:${candidate}`],
+            };
+        }
+    }
+    for (const candidate of UNSAFE_AUTO_DISCOVERY_FILES) {
+        const candidatePath = resolveInputPath(candidate);
+        if (await pathExists(candidatePath)) {
+            throw new PmCliError(`Beads auto-discovery found ${candidatePath}, but sync_base snapshots may be partial. Export a full Beads JSONL file and pass --file <path> (or --file - for stdin).`, EXIT_CODE.NOT_FOUND);
+        }
+    }
+    throw new PmCliError(`Beads source file not found. Checked ${PRIMARY_AUTO_DISCOVERY_FILES.join(", ")}. Use --file <path> or --file - for stdin.`, EXIT_CODE.NOT_FOUND);
+}
 export async function runBeadsImport(options, global) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
     await ensureInitHasRun(pmRoot);
     const settings = await readSettings(pmRoot);
-    const source = toNonEmptyString(options.file) ?? DEFAULT_BEADS_FILE;
-    const sourcePath = resolveInputPath(source);
-    if (!(await pathExists(sourcePath))) {
-        throw new PmCliError(`Beads source file not found at ${sourcePath}`, EXIT_CODE.NOT_FOUND);
-    }
-    const raw = await fs.readFile(sourcePath, "utf8");
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    const preserveSourceIds = options.preserveSourceIds === true;
+    const { source, sourcePath, raw, warnings: sourceWarnings } = await resolveBeadsSource(options.file);
     const warnings = [
-        ...(await runActiveOnReadHooks({
+        ...sourceWarnings,
+    ];
+    if (sourcePath) {
+        warnings.push(...(await runActiveOnReadHooks({
             path: sourcePath,
             scope: "project",
-        })),
-    ];
+        })));
+    }
     const lines = raw.split(/\r?\n/);
     const author = selectAuthor(toNonEmptyString(options.author), settings.author_default);
     const message = toNonEmptyString(options.message) ?? "Import from Beads JSONL";
@@ -371,26 +474,34 @@ export async function runBeadsImport(options, global) {
         const createdAt = toIsoString(record.created_at) ?? nowIso();
         const updatedAt = toIsoString(record.updated_at) ?? createdAt;
         const id = toNonEmptyString(record.id)
-            ? normalizeItemId(toNonEmptyString(record.id), settings.id_prefix)
+            ? normalizeImportedId(toNonEmptyString(record.id), settings.id_prefix, preserveSourceIds)
             : await generateItemId(pmRoot, settings.id_prefix);
-        const type = toItemType(record.issue_type ?? record.type);
+        const typeMapping = toItemType(record.issue_type ?? record.type);
+        const type = typeMapping.type;
+        const closedAt = toIsoString(record.closed_at);
+        const assignee = toNonEmptyString(record.assignee) ?? toNonEmptyString(record.owner);
         const frontMatter = normalizeFrontMatter({
             id,
             title,
             description: toNonEmptyString(record.description) ?? "",
             type,
+            source_type: typeMapping.sourceType,
             status: toStatus(record.status),
             priority: toPriority(record.priority),
             tags: toTags(record.tags ?? record.labels),
             created_at: createdAt,
             updated_at: updatedAt,
-            deadline: toIsoString(record.deadline),
-            assignee: toNonEmptyString(record.assignee),
+            deadline: toIsoString(record.due_at ?? record.deadline),
+            closed_at: closedAt,
+            assignee,
+            source_owner: toNonEmptyString(record.owner),
             author: toNonEmptyString(record.author) ?? toNonEmptyString(record.created_by) ?? author,
             estimated_minutes: toEstimatedMinutes(record.estimated_minutes),
             acceptance_criteria: toNonEmptyString(record.acceptance_criteria),
-            close_reason: toNonEmptyString(record.close_reason) ?? (toIsoString(record.closed_at) ? `Closed at ${toIsoString(record.closed_at)}` : undefined),
-            dependencies: toDependencies(record.dependencies, createdAt, settings.id_prefix),
+            design: toNonEmptyString(record.design),
+            external_ref: toNonEmptyString(record.external_ref),
+            close_reason: toNonEmptyString(record.close_reason),
+            dependencies: toDependencies(record.dependencies, createdAt, settings.id_prefix, preserveSourceIds),
             comments: toLogEntries(record.comments, createdAt, author),
             notes: toLogEntries(record.notes, createdAt, author),
             learnings: toLogEntries(record.learnings, createdAt, author),
@@ -412,17 +523,18 @@ export async function runBeadsImport(options, global) {
             front_matter: frontMatter,
             body: finalBody,
         });
-        const itemPath = getItemPath(pmRoot, type, id);
-        if (await pathExists(itemPath)) {
+        const existing = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
+        if (existing) {
             warnings.push(`beads_import_item_exists:${id}`);
             skipped += 1;
             continue;
         }
+        const itemPath = getItemPath(pmRoot, type, id, settings.item_format, 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));
+                await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: settings.item_format }));
                 try {
                     const entry = createHistoryEntry({
                         nowIso: nowIso(),
@@ -471,5 +583,4 @@ export async function runBeadsImport(options, global) {
         ids,
         warnings,
     };
-}
-//# sourceMappingURL=beads.js.map
+}