@unbrained/pm-cli 2026.7.3 → 2026.7.4

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

@@ -5,16 +5,12 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 /**
  * This file is auto-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> {
@@ -42,15 +38,11 @@ function isMissingRuntimeModuleError(error: unknown, modulePath: string): boolea
 }
 
 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 candidates = typeof envRoot === "string" && envRoot.trim().length > 0 ? [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);
+    const entryDir = path.dirname(path.resolve(argvEntry));
     candidates.push(path.resolve(entryDir, ".."));
     candidates.push(path.resolve(entryDir, "../.."));
     candidates.push(path.resolve(entryDir, "../../.."));
@@ -58,41 +50,36 @@ function resolvePackageRootCandidates(): string[] {
   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.ts"),
-      path.join(packageRoot, "packages", PACKAGE_NAME, "extensions", EXTENSION_NAME, "runtime.ts"),
-    ];
-    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;
-      }
+function runtimePaths(packageRoot: string): string[] {
+  return [
+    path.join(packageRoot, ".agents", "pm", "extensions", EXTENSION_NAME, "runtime.ts"),
+    path.join(packageRoot, "packages", PACKAGE_NAME, "extensions", EXTENSION_NAME, "runtime.ts"),
+  ];
+}
+
+async function tryRuntime(modulePath: string, attempted: string[]): Promise<PackageRuntimeModule | undefined> {
+  attempted.push(modulePath);
+  if (!existsSync(modulePath)) {
+    return undefined;
+  }
+  try {
+    return await import(pathToFileURL(modulePath).href) as PackageRuntimeModule;
+  } catch (error: unknown) {
+    if (isMissingRuntimeModuleError(error, modulePath)) {
+      return undefined;
     }
+    throw error;
   }
+}
 
-  const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.ts");
-  attempted.push(localRuntimePath);
-  if (existsSync(localRuntimePath)) {
-    try {
-      return await import(pathToFileURL(localRuntimePath).href) as PackageRuntimeModule;
-    } catch (error: unknown) {
-      if (!isMissingRuntimeModuleError(error, localRuntimePath)) {
-        throw error;
-      }
+export async function loadPackageRuntimeModule(): Promise<PackageRuntimeModule> {
+  const attempted: string[] = [];
+  for (const modulePath of [...resolvePackageRootCandidates().flatMap(runtimePaths), path.join(CURRENT_EXTENSION_ROOT, "runtime.ts")]) {
+    const loaded = await tryRuntime(modulePath, attempted);
+    if (loaded) {
+      return loaded;
     }
   }
-
   throw new Error(
     `Unable to resolve packaged ${DIAGNOSTIC_NAME} extension runtime module. ` +
       `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.ts or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`,

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

@@ -10,11 +10,10 @@ import type {
   ItemMetadata,
   ItemStatus,
   ItemType,
-  LinkedDoc,
-  LinkedFile,
-  LinkedTest,
-  LogNote,
   PmSettings,
+  ToImportLinkedArtifactsOptions,
+  ToImportLinkedTestsOptions,
+  ToImportLogEntriesOptions,
 } from "@unbrained/pm-cli/sdk";
 
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
@@ -142,6 +141,10 @@ interface BeadsSdkModule {
   runActiveOnReadHooks: (context: { path: string; scope: "project" | "global" }) => Promise<string[]>;
   selectImportAuthor: (explicitAuthor: string | undefined, settingsAuthor: string) => string;
   toEstimatedMinutesValue: (value: unknown) => number | undefined;
+  toImportLinkedDocs: (value: unknown, options?: ToImportLinkedArtifactsOptions) => ItemMetadata["docs"];
+  toImportLinkedFiles: (value: unknown, options?: ToImportLinkedArtifactsOptions) => ItemMetadata["files"];
+  toImportLinkedTests: (value: unknown, options?: ToImportLinkedTestsOptions) => ItemMetadata["tests"];
+  toImportLogEntries: (value: unknown, options: ToImportLogEntriesOptions) => ItemMetadata["comments"];
   toImportPriority: (value: unknown) => 0 | 1 | 2 | 3 | 4;
   toImportStatus: (value: unknown) => ItemStatus;
   toImportTags: (value: unknown) => string[];
@@ -173,6 +176,10 @@ const BEADS_SDK_FUNCTION_EXPORTS = [
   "runActiveOnReadHooks",
   "selectImportAuthor",
   "toEstimatedMinutesValue",
+  "toImportLinkedDocs",
+  "toImportLinkedFiles",
+  "toImportLinkedTests",
+  "toImportLogEntries",
   "toImportPriority",
   "toImportStatus",
   "toImportTags",
@@ -241,6 +248,10 @@ const {
   runActiveOnReadHooks,
   selectImportAuthor,
   toEstimatedMinutesValue,
+  toImportLinkedDocs,
+  toImportLinkedFiles,
+  toImportLinkedTests,
+  toImportLogEntries,
   toImportPriority,
   toImportStatus,
   toImportTags,
@@ -255,6 +266,41 @@ const toEstimatedMinutes = toEstimatedMinutesValue;
 const toPriority = toImportPriority;
 const toTags = toImportTags;
 
+const BEADS_DEPENDENCY_KIND_ALIASES = new Map<string, Dependency["kind"]>([
+  ["parent-child", "parent_child"],
+  ["child-of", "child_of"],
+  ["related-to", "related_to"],
+  ["relates-to", "related_to"],
+  ["discovered-from", "discovered_from"],
+  ["blocked-by", "blocked_by"],
+  ["incident-from", "incident_from"],
+]);
+
+const BEADS_LOG_ENTRY_OPTIONS = {
+  allowScalar: true,
+  textKeys: ["text", "comment", "note", "learning"],
+  toIsoString,
+} satisfies Partial<ToImportLogEntriesOptions>;
+
+const BEADS_FILE_OPTIONS = {
+  allowScalar: true,
+  pathKeys: ["path", "file"],
+} satisfies ToImportLinkedArtifactsOptions;
+
+const BEADS_DOC_OPTIONS = {
+  allowScalar: true,
+  pathKeys: ["path", "doc"],
+} satisfies ToImportLinkedArtifactsOptions;
+
+const BEADS_TEST_OPTIONS = {
+  allowScalar: true,
+  commandKeys: ["command", "test"],
+  requireCommand: true,
+  integerTimeout: true,
+  timeoutMinimum: 0,
+  timeoutExclusiveMinimum: true,
+} satisfies ToImportLinkedTestsOptions;
+
 function toIsoString(value: unknown): string | undefined {
   const raw = toNonEmptyString(value);
   if (!raw) {
@@ -307,26 +353,15 @@ function toDependencyKind(value: unknown): { kind: Dependency["kind"]; sourceKin
     return preserveIfChanged(normalized as Dependency["kind"]);
   }
 
-  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,
-      };
+  const aliasKind = BEADS_DEPENDENCY_KIND_ALIASES.get(normalized);
+  if (aliasKind) {
+    return preserveIfChanged(aliasKind);
   }
+
+  return {
+    kind: "related",
+    sourceKind: raw,
+  };
 }
 
 function normalizeImportedId(id: string, prefix: string, preserveSourceIds: boolean): string {
@@ -345,219 +380,55 @@ function toDependencies(
 
   const dependencies: Dependency[] = [];
   for (const entry of value) {
-    if (typeof entry === "string") {
-      const id = toNonEmptyString(entry);
-      if (!id) {
-        continue;
-      }
-      dependencies.push({
-        id: normalizeImportedId(id, prefix, preserveSourceIds),
-        kind: "related",
-        created_at: fallbackCreatedAt,
-      });
-      continue;
-    }
-    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-      continue;
-    }
-    const candidate = entry as Record<string, unknown>;
-    const id = toNonEmptyString(candidate.id) ?? toNonEmptyString(candidate.item_id) ?? toNonEmptyString(candidate.depends_on_id);
-    if (!id) {
-      continue;
-    }
-    const dependencyKind = toDependencyKind(candidate.type ?? candidate.kind);
-    dependencies.push({
-      id: normalizeImportedId(id, prefix, preserveSourceIds),
-      kind: dependencyKind.kind,
-      created_at: toIsoString(candidate.created_at) ?? fallbackCreatedAt,
-      author: toNonEmptyString(candidate.author) ?? toNonEmptyString(candidate.created_by),
-      source_kind: dependencyKind.sourceKind,
-    });
+    const dependency = toDependency(entry, fallbackCreatedAt, prefix, preserveSourceIds);
+    if (dependency) dependencies.push(dependency);
   }
 
   return dependencies.length > 0 ? dependencies : undefined;
 }
 
-function toLogEntries(value: unknown, fallbackCreatedAt: string, fallbackAuthor: string): LogNote[] | undefined {
-  if (typeof value === "string") {
-    const text = toNonEmptyString(value);
-    if (!text) {
-      return undefined;
-    }
-    return [
-      {
-        created_at: fallbackCreatedAt,
-        author: fallbackAuthor,
-        text,
-      },
-    ];
-  }
-  if (!Array.isArray(value)) {
-    return undefined;
-  }
-
-  const entries: LogNote[] = [];
-  for (const entry of value) {
-    if (typeof entry === "string") {
-      const text = toNonEmptyString(entry);
-      if (!text) {
-        continue;
-      }
-      entries.push({
-        created_at: fallbackCreatedAt,
-        author: fallbackAuthor,
-        text,
-      });
-      continue;
-    }
-    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-      continue;
-    }
-    const candidate = entry as Record<string, unknown>;
-    const text =
-      toNonEmptyString(candidate.text) ??
-      toNonEmptyString(candidate.comment) ??
-      toNonEmptyString(candidate.note) ??
-      toNonEmptyString(candidate.learning);
-    if (!text) {
-      continue;
-    }
-    entries.push({
-      created_at: toIsoString(candidate.created_at) ?? fallbackCreatedAt,
-      author: toNonEmptyString(candidate.author) ?? fallbackAuthor,
-      text,
-    });
-  }
-
-  return entries.length > 0 ? entries : undefined;
-}
-
-function toLinkedFiles(value: unknown): LinkedFile[] | undefined {
-  if (typeof value === "string") {
-    const p = toNonEmptyString(value);
-    if (!p) return undefined;
-    return [{ path: p, scope: "project" }];
-  }
-  if (!Array.isArray(value)) {
-    return undefined;
-  }
-
-  const files: LinkedFile[] = [];
-  for (const entry of value) {
-    if (typeof entry === "string") {
-      const p = toNonEmptyString(entry);
-      if (p) files.push({ path: p, scope: "project" });
-      continue;
-    }
-    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-      continue;
-    }
-    const candidate = entry as Record<string, unknown>;
-    const p = toNonEmptyString(candidate.path) ?? toNonEmptyString(candidate.file);
-    if (!p) continue;
-    
-    files.push({
-      path: p,
-      scope: toNonEmptyString(candidate.scope) === "global" ? "global" : "project",
-      note: toNonEmptyString(candidate.note),
-    });
-  }
-
-  return files.length > 0 ? files : undefined;
-}
-
-function toLinkedTests(value: unknown): LinkedTest[] | undefined {
+function toDependency(
+  value: unknown,
+  fallbackCreatedAt: string,
+  prefix: string,
+  preserveSourceIds: boolean,
+): Dependency | undefined {
   if (typeof value === "string") {
-    const c = toNonEmptyString(value);
-    if (!c) return undefined;
-    return [{ command: c, scope: "project" }];
-  }
-  if (!Array.isArray(value)) {
-    return undefined;
+    return toDependencyFromString(value, fallbackCreatedAt, prefix, preserveSourceIds);
   }
-
-  const tests: LinkedTest[] = [];
-  for (const entry of value) {
-    if (typeof entry === "string") {
-      const c = toNonEmptyString(entry);
-      if (c) tests.push({ command: c, scope: "project" });
-      continue;
-    }
-    const linkedTest = toLinkedTestFromRecord(entry);
-    if (linkedTest) {
-      tests.push(linkedTest);
-    }
-  }
-
-  return tests.length > 0 ? tests : undefined;
-}
-
-function toLinkedTestTimeout(value: unknown): number | undefined {
-  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
-    return value;
-  }
-  if (typeof value !== "string") {
-    return undefined;
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    return undefined;
-  }
-  const parsed = Number(trimmed);
-  return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
-}
-
-function toLinkedTestFromRecord(value: unknown): LinkedTest | undefined {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return undefined;
   }
   const candidate = value as Record<string, unknown>;
-  const command = toNonEmptyString(candidate.command) ?? toNonEmptyString(candidate.test);
-  const p = toNonEmptyString(candidate.path);
-  if (!command && !p) {
+  const id = toNonEmptyString(candidate.id) ?? toNonEmptyString(candidate.item_id) ?? toNonEmptyString(candidate.depends_on_id);
+  if (!id) {
     return undefined;
   }
+  const dependencyKind = toDependencyKind(candidate.type ?? candidate.kind);
   return {
-    command,
-    path: p,
-    scope: toNonEmptyString(candidate.scope) === "global" ? "global" : "project",
-    timeout_seconds: toLinkedTestTimeout(candidate.timeout_seconds),
-    note: toNonEmptyString(candidate.note),
+    id: normalizeImportedId(id, prefix, preserveSourceIds),
+    kind: dependencyKind.kind,
+    created_at: toIsoString(candidate.created_at) ?? fallbackCreatedAt,
+    author: toNonEmptyString(candidate.author) ?? toNonEmptyString(candidate.created_by),
+    source_kind: dependencyKind.sourceKind,
   };
 }
 
-function toLinkedDocs(value: unknown): LinkedDoc[] | undefined {
-  if (typeof value === "string") {
-    const p = toNonEmptyString(value);
-    if (!p) return undefined;
-    return [{ path: p, scope: "project" }];
-  }
-  if (!Array.isArray(value)) {
+function toDependencyFromString(
+  value: string,
+  fallbackCreatedAt: string,
+  prefix: string,
+  preserveSourceIds: boolean,
+): Dependency | undefined {
+  const id = toNonEmptyString(value);
+  if (!id) {
     return undefined;
   }
-
-  const docs: LinkedDoc[] = [];
-  for (const entry of value) {
-    if (typeof entry === "string") {
-      const p = toNonEmptyString(entry);
-      if (p) docs.push({ path: p, scope: "project" });
-      continue;
-    }
-    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-      continue;
-    }
-    const candidate = entry as Record<string, unknown>;
-    const p = toNonEmptyString(candidate.path) ?? toNonEmptyString(candidate.doc);
-    if (!p) continue;
-    
-    docs.push({
-      path: p,
-      scope: toNonEmptyString(candidate.scope) === "global" ? "global" : "project",
-      note: toNonEmptyString(candidate.note),
-    });
-  }
-
-  return docs.length > 0 ? docs : undefined;
+  return {
+    id: normalizeImportedId(id, prefix, preserveSourceIds),
+    kind: "related",
+    created_at: fallbackCreatedAt,
+  };
 }
 
 const selectAuthor = selectImportAuthor;
@@ -714,12 +585,24 @@ async function importBeadsRecord(record: BeadsRecord, lineNumber: number, runtim
     external_ref: toNonEmptyString(record.external_ref),
     close_reason: toNonEmptyString(record.close_reason),
     dependencies: toDependencies(record.dependencies, createdAt, runtime.settings.id_prefix, runtime.preserveSourceIds),
-    comments: toLogEntries(record.comments, createdAt, runtime.author),
-    notes: toLogEntries(record.notes, createdAt, runtime.author),
-    learnings: toLogEntries(record.learnings, createdAt, runtime.author),
-    files: toLinkedFiles(record.files),
-    tests: toLinkedTests(record.tests),
-    docs: toLinkedDocs(record.docs),
+    comments: toImportLogEntries(record.comments, {
+      ...BEADS_LOG_ENTRY_OPTIONS,
+      fallbackCreatedAt: createdAt,
+      fallbackAuthor: runtime.author,
+    }),
+    notes: toImportLogEntries(record.notes, {
+      ...BEADS_LOG_ENTRY_OPTIONS,
+      fallbackCreatedAt: createdAt,
+      fallbackAuthor: runtime.author,
+    }),
+    learnings: toImportLogEntries(record.learnings, {
+      ...BEADS_LOG_ENTRY_OPTIONS,
+      fallbackCreatedAt: createdAt,
+      fallbackAuthor: runtime.author,
+    }),
+    files: toImportLinkedFiles(record.files, BEADS_FILE_OPTIONS),
+    tests: toImportLinkedTests(record.tests, BEADS_TEST_OPTIONS),
+    docs: toImportLinkedDocs(record.docs, BEADS_DOC_OPTIONS),
   });
   const afterDocument = runtime.sdk.canonicalDocument({
     metadata: frontMatter,

package/packages/pm-calendar/extensions/calendar/runtime.ts

@@ -62,39 +62,41 @@ function isCalendarResult(value: unknown): value is CalendarResult {
   );
 }
 
+function readObjectPayload(payload: unknown): Record<string, unknown> | null {
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    return null;
+  }
+  return payload as Record<string, unknown>;
+}
+
 function readPayloadFormat(payload: unknown): "toon" | "json" {
-  if (typeof payload === "object" && payload !== null) {
-    const format = (payload as { format?: unknown }).format;
-    if (format === "json") {
-      return "json";
-    }
+  const record = readObjectPayload(payload);
+  if (record?.format === "json") {
+    return "json";
   }
   return "toon";
 }
 
 function readPayloadResult(payload: unknown): unknown {
-  if (typeof payload === "object" && payload !== null && "result" in payload) {
-    return (payload as { result?: unknown }).result;
+  const record = readObjectPayload(payload);
+  if (!record || !Object.hasOwn(record, "result")) {
+    return payload;
   }
-  return payload;
+  return record.result;
 }
 
 function readPayloadCommandOptions(payload: unknown): CalendarOptions {
-  if (typeof payload === "object" && payload !== null) {
-    const commandOptions = (payload as { command_options?: unknown }).command_options;
-    if (typeof commandOptions === "object" && commandOptions !== null) {
-      return commandOptions as CalendarOptions;
-    }
+  const commandOptions = readObjectPayload(payload)?.command_options;
+  if (typeof commandOptions === "object" && commandOptions !== null && !Array.isArray(commandOptions)) {
+    return commandOptions as CalendarOptions;
   }
   return {};
 }
 
 function readPayloadGlobalOptions(payload: unknown): GlobalOptions {
-  if (typeof payload === "object" && payload !== null) {
-    const global = (payload as { global?: unknown }).global;
-    if (typeof global === "object" && global !== null) {
-      return global as GlobalOptions;
-    }
+  const global = readObjectPayload(payload)?.global;
+  if (typeof global === "object" && global !== null && !Array.isArray(global)) {
+    return global as GlobalOptions;
   }
   return {};
 }
@@ -137,6 +139,7 @@ export function renderCalendarPackageOutput(context: ServiceOverrideContext): st
  */
 export const _testOnly = {
   readPayloadFormat,
+  readPayloadResult,
   readPayloadCommandOptions,
   readPayloadGlobalOptions,
 };

package/packages/pm-guide-shell/extensions/guide-shell/runtime.ts

@@ -211,21 +211,19 @@ async function buildCompletionRuntimeConfig(
   };
 }
 
+function payloadRecord(payload: unknown): Record<string, unknown> | undefined {
+  return typeof payload === "object" && payload !== null && !Array.isArray(payload)
+    ? (payload as Record<string, unknown>)
+    : undefined;
+}
+
 function readPayloadFormat(payload: unknown): "toon" | "json" {
-  if (typeof payload === "object" && payload !== null) {
-    const format = (payload as { format?: unknown }).format;
-    if (format === "json") {
-      return "json";
-    }
-  }
-  return "toon";
+  return payloadRecord(payload)?.format === "json" ? "json" : "toon";
 }
 
 function readPayloadResult(payload: unknown): unknown {
-  if (typeof payload === "object" && payload !== null && "result" in payload) {
-    return (payload as { result?: unknown }).result;
-  }
-  return payload;
+  const record = payloadRecord(payload);
+  return record && Object.hasOwn(record, "result") ? record.result : payload;
 }
 
 function collectTagsFromItems(items: Array<{ metadata: { tags?: string[] } }>): string[] {