@unbrained/pm-cli 2026.5.18 → 2026.5.27

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

@@ -1,81 +1,12 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import type { GlobalOptions } from "../../../../src/sdk/index.js";
 
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 
-interface TemplatesSdkModule {
-  CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS: Array<{ target: string }>;
-  EXIT_CODE: {
-    USAGE: number;
-    NOT_FOUND: number;
-    GENERIC_FAILURE: number;
-  };
-  PmCliError: new (message: string, exitCode?: number) => Error;
-  getSettingsPath: (pmRoot: string) => string;
-  nowIso: () => string;
-  pathExists: (targetPath: string) => Promise<boolean>;
-  readFileIfExists: (targetPath: string) => Promise<string | null>;
-  resolvePmRoot: (cwd: string, overridePath?: string) => string;
-  writeFileAtomic: (targetPath: string, contents: string) => Promise<void>;
-}
-
-const sdk = await loadTemplatesSdkModule();
-const {
-  CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS,
-  EXIT_CODE,
-  PmCliError,
-  getSettingsPath,
-  nowIso,
-  pathExists,
-  readFileIfExists,
-  resolvePmRoot,
-  writeFileAtomic,
-} = sdk;
-
-async function loadTemplatesSdkModule(): Promise<TemplatesSdkModule> {
-  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
-  if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
-    throw new Error(
-      `builtin-templates requires ${PM_PACKAGE_ROOT_ENV} to locate core SDK runtime exports.`,
-    );
-  }
-  const modulePath = path.join(path.resolve(envRoot.trim()), "dist", "sdk", "index.js");
-  try {
-    const loaded = (await import(pathToFileURL(modulePath).href)) as Partial<TemplatesSdkModule>;
-    if (
-      typeof loaded.resolvePmRoot === "function" &&
-      typeof loaded.pathExists === "function" &&
-      typeof loaded.PmCliError === "function" &&
-      Array.isArray(loaded.CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS)
-    ) {
-      return loaded as TemplatesSdkModule;
-    }
-  } catch {
-    // Fall through to deterministic failure message below.
-  }
-  throw new Error(
-    `builtin-templates failed to load SDK runtime exports from ${modulePath}.`,
-  );
-}
-
-const TEMPLATE_DIRECTORY_NAME = "templates";
-const TEMPLATE_FILE_EXTENSION = ".json";
-const TEMPLATE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
-const TEMPLATE_OPTION_REPEATABLE_KEYS = CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS.map((entry) => entry.target);
-const TEMPLATE_OPTION_REPEATABLE_KEY_SET = new Set<string>(TEMPLATE_OPTION_REPEATABLE_KEYS);
-
 type TemplateOptionValue = string | string[];
 export type CreateTemplateOptions = Record<string, TemplateOptionValue>;
 
-interface StoredCreateTemplateDocument {
-  name: string;
-  created_at: string;
-  updated_at: string;
-  options: CreateTemplateOptions;
-}
-
 export interface TemplatesSaveResult {
   name: string;
   created_at: string;
@@ -87,128 +18,60 @@ export interface TemplatesSaveResult {
 export interface TemplatesListResult {
   templates: string[];
   count: number;
+  builtin_templates: string[];
+  user_templates: string[];
 }
 
 export interface TemplatesShowResult {
   name: string;
+  source: "builtin" | "user";
   created_at: string;
   updated_at: string;
   path: string;
   options: CreateTemplateOptions;
 }
 
-function normalizeTemplateName(rawName: string): string {
-  const name = rawName.trim();
-  if (!TEMPLATE_NAME_PATTERN.test(name)) {
-    throw new PmCliError(
-      `Invalid template name "${rawName}". Expected 1-64 characters matching [A-Za-z0-9][A-Za-z0-9._-]*.`,
-      EXIT_CODE.USAGE,
-    );
-  }
-  return name;
-}
-
-function templatesDirectory(pmRoot: string): string {
-  return path.join(pmRoot, TEMPLATE_DIRECTORY_NAME);
-}
-
-function templatePath(pmRoot: string, normalizedName: string): string {
-  return path.join(templatesDirectory(pmRoot), `${normalizedName}${TEMPLATE_FILE_EXTENSION}`);
-}
-
-async function ensureTrackerInitialized(pmRoot: string): Promise<void> {
-  if (!(await pathExists(getSettingsPath(pmRoot)))) {
-    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-  }
-}
-
-function sortTemplateOptions(options: CreateTemplateOptions): CreateTemplateOptions {
-  return Object.fromEntries(
-    Object.entries(options).sort(([left], [right]) => left.localeCompare(right)),
-  ) as CreateTemplateOptions;
+interface TemplatesSdkModule {
+  loadCreateTemplateOptions: (pmRoot: string, rawTemplateName: string) => Promise<CreateTemplateOptions>;
+  runTemplatesList: (global: GlobalOptions) => Promise<TemplatesListResult>;
+  runTemplatesSave: (
+    rawTemplateName: string,
+    options: Record<string, unknown>,
+    global: GlobalOptions,
+  ) => Promise<TemplatesSaveResult>;
+  runTemplatesShow: (rawTemplateName: string, global: GlobalOptions) => Promise<TemplatesShowResult>;
 }
 
-function extractTemplateOptions(rawOptions: Record<string, unknown>): CreateTemplateOptions {
-  const next: CreateTemplateOptions = {};
-  for (const [key, value] of Object.entries(rawOptions)) {
-    if (value === undefined) {
-      continue;
-    }
-    if (TEMPLATE_OPTION_REPEATABLE_KEY_SET.has(key)) {
-      if (typeof value === "string") {
-        next[key] = [value];
-        continue;
-      }
-      if (!Array.isArray(value)) {
-        continue;
-      }
-      const values = value.filter((entry): entry is string => typeof entry === "string");
-      if (values.length > 0) {
-        next[key] = values;
-      }
-      continue;
-    }
-    if (typeof value === "string") {
-      next[key] = value;
-      continue;
-    }
-    if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
-      next[key] = [...value];
-    }
-  }
-  return sortTemplateOptions(next);
-}
+const sdk = await loadTemplatesSdkModule();
 
-function parseStoredTemplateOptions(rawOptions: unknown, templateName: string): CreateTemplateOptions {
-  if (typeof rawOptions !== "object" || rawOptions === null || Array.isArray(rawOptions)) {
-    throw new PmCliError(`Template "${templateName}" has invalid options payload.`, EXIT_CODE.GENERIC_FAILURE);
-  }
-  const normalized: CreateTemplateOptions = {};
-  for (const [key, value] of Object.entries(rawOptions as Record<string, unknown>)) {
-    const normalizedKey = key.trim();
-    if (normalizedKey.length === 0) {
-      throw new PmCliError(`Template "${templateName}" contains an empty option key.`, EXIT_CODE.GENERIC_FAILURE);
-    }
-    if (typeof value === "string") {
-      normalized[normalizedKey] = value;
-      continue;
-    }
-    if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
-      normalized[normalizedKey] = [...value];
-      continue;
-    }
-    throw new PmCliError(`Template "${templateName}" contains invalid value for option "${normalizedKey}".`, EXIT_CODE.GENERIC_FAILURE);
+async function loadTemplatesSdkModule(): Promise<TemplatesSdkModule> {
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
+    throw new Error(
+      `builtin-templates requires ${PM_PACKAGE_ROOT_ENV} to locate core SDK runtime exports.`,
+    );
   }
-  return sortTemplateOptions(normalized);
-}
-
-function parseStoredTemplateDocument(raw: string, normalizedName: string): StoredCreateTemplateDocument {
-  let parsed: unknown;
+  const modulePath = path.join(path.resolve(envRoot.trim()), "dist", "sdk", "index.js");
   try {
-    parsed = JSON.parse(raw) as unknown;
+    const loaded = (await import(pathToFileURL(modulePath).href)) as Partial<TemplatesSdkModule>;
+    if (
+      typeof loaded.loadCreateTemplateOptions === "function" &&
+      typeof loaded.runTemplatesList === "function" &&
+      typeof loaded.runTemplatesSave === "function" &&
+      typeof loaded.runTemplatesShow === "function"
+    ) {
+      return loaded as TemplatesSdkModule;
+    }
   } catch {
-    throw new PmCliError(`Template "${normalizedName}" contains invalid JSON.`, EXIT_CODE.GENERIC_FAILURE);
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new PmCliError(`Template "${normalizedName}" has invalid document shape.`, EXIT_CODE.GENERIC_FAILURE);
+    // Fall through to deterministic failure message below.
   }
-  const record = parsed as Record<string, unknown>;
-  const options = parseStoredTemplateOptions(record.options, normalizedName);
-  const now = nowIso();
-  return {
-    name: typeof record.name === "string" && record.name.trim().length > 0 ? record.name.trim() : normalizedName,
-    created_at: typeof record.created_at === "string" ? record.created_at : now,
-    updated_at: typeof record.updated_at === "string" ? record.updated_at : now,
-    options,
-  };
+  throw new Error(
+    `builtin-templates failed to load template runtime exports from ${modulePath}.`,
+  );
 }
 
-async function readStoredTemplateDocument(pmRoot: string, normalizedName: string): Promise<StoredCreateTemplateDocument> {
-  const raw = await readFileIfExists(templatePath(pmRoot, normalizedName));
-  if (raw === null) {
-    throw new PmCliError(`Template "${normalizedName}" not found`, EXIT_CODE.NOT_FOUND);
-  }
-  return parseStoredTemplateDocument(raw, normalizedName);
+export async function loadCreateTemplateOptions(pmRoot: string, rawTemplateName: string): Promise<CreateTemplateOptions> {
+  return sdk.loadCreateTemplateOptions(pmRoot, rawTemplateName);
 }
 
 export async function runTemplatesSave(
@@ -216,68 +79,13 @@ export async function runTemplatesSave(
   options: Record<string, unknown>,
   global: GlobalOptions,
 ): Promise<TemplatesSaveResult> {
-  const pmRoot = resolvePmRoot(process.cwd(), global.path);
-  await ensureTrackerInitialized(pmRoot);
-  const normalizedName = normalizeTemplateName(rawTemplateName);
-  const nextOptions = extractTemplateOptions(options);
-  if (Object.keys(nextOptions).length === 0) {
-    throw new PmCliError("templates save requires at least one create option flag", EXIT_CODE.USAGE);
-  }
-
-  const now = nowIso();
-  const storedPath = templatePath(pmRoot, normalizedName);
-  let createdAt = now;
-  if (await pathExists(storedPath)) {
-    const existing = await readStoredTemplateDocument(pmRoot, normalizedName);
-    createdAt = existing.created_at;
-  }
-
-  const document: StoredCreateTemplateDocument = {
-    name: normalizedName,
-    created_at: createdAt,
-    updated_at: now,
-    options: nextOptions,
-  };
-  await fs.mkdir(templatesDirectory(pmRoot), { recursive: true });
-  await writeFileAtomic(storedPath, `${JSON.stringify(document, null, 2)}\n`);
-  return {
-    name: document.name,
-    created_at: document.created_at,
-    updated_at: document.updated_at,
-    path: storedPath,
-    options: document.options,
-  };
+  return sdk.runTemplatesSave(rawTemplateName, options, global);
 }
 
 export async function runTemplatesList(global: GlobalOptions): Promise<TemplatesListResult> {
-  const pmRoot = resolvePmRoot(process.cwd(), global.path);
-  await ensureTrackerInitialized(pmRoot);
-  const dirPath = templatesDirectory(pmRoot);
-  if (!(await pathExists(dirPath))) {
-    return { templates: [], count: 0 };
-  }
-  const entries = await fs.readdir(dirPath);
-  const templates = entries
-    .filter((entry) => entry.toLowerCase().endsWith(TEMPLATE_FILE_EXTENSION))
-    .map((entry) => entry.slice(0, -TEMPLATE_FILE_EXTENSION.length))
-    .filter((entry) => TEMPLATE_NAME_PATTERN.test(entry))
-    .sort((left, right) => left.localeCompare(right));
-  return {
-    templates,
-    count: templates.length,
-  };
+  return sdk.runTemplatesList(global);
 }
 
 export async function runTemplatesShow(rawTemplateName: string, global: GlobalOptions): Promise<TemplatesShowResult> {
-  const pmRoot = resolvePmRoot(process.cwd(), global.path);
-  await ensureTrackerInitialized(pmRoot);
-  const normalizedName = normalizeTemplateName(rawTemplateName);
-  const stored = await readStoredTemplateDocument(pmRoot, normalizedName);
-  return {
-    name: stored.name,
-    created_at: stored.created_at,
-    updated_at: stored.updated_at,
-    path: templatePath(pmRoot, normalizedName),
-    options: stored.options,
-  };
+  return sdk.runTemplatesShow(rawTemplateName, global);
 }

package/packages/pm-todos/extensions/todos/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-todos-import-export",
     version: "0.1.0",
@@ -24,59 +21,15 @@ function toExportOptions(options) {
         folder: asOptionalString(options.folder),
     };
 }
-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", "todos", "runtime.js"),
-            path.join(packageRoot, "packages", "pm-todos", "extensions", "todos", "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 todos 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 runTodosImportFromRuntime(options, global) {
-    const runtime = await loadRuntimeModule();
+    const runtime = await loadPackageRuntimeModule();
     if (typeof runtime.runTodosImport !== "function") {
         throw new Error("Bundled todos runtime module is missing runTodosImport().");
     }
     return runtime.runTodosImport(options, global);
 }
 async function runTodosExportFromRuntime(options, global) {
-    const runtime = await loadRuntimeModule();
+    const runtime = await loadPackageRuntimeModule();
     if (typeof runtime.runTodosExport !== "function") {
         throw new Error("Bundled todos runtime module is missing runTodosExport().");
     }

package/packages/pm-todos/extensions/todos/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 { TodosExportOptions, TodosExportResult, TodosImportOptions, TodosImportResult } 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-todos-import-export",
@@ -37,56 +33,8 @@ function toExportOptions(options: Record<string, unknown>): TodosExportOptions {
   };
 }
 
-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", "todos", "runtime.js"),
-      path.join(packageRoot, "packages", "pm-todos", "extensions", "todos", "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 todos 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 runTodosImportFromRuntime(options: TodosImportOptions, global: GlobalOptions): Promise<TodosImportResult> {
-  const runtime = await loadRuntimeModule();
+  const runtime = await loadPackageRuntimeModule() as RuntimeModule;
   if (typeof runtime.runTodosImport !== "function") {
     throw new Error("Bundled todos runtime module is missing runTodosImport().");
   }
@@ -94,7 +42,7 @@ async function runTodosImportFromRuntime(options: TodosImportOptions, global: Gl
 }
 
 async function runTodosExportFromRuntime(options: TodosExportOptions, global: GlobalOptions): Promise<TodosExportResult> {
-  const runtime = await loadRuntimeModule();
+  const runtime = await loadPackageRuntimeModule() as RuntimeModule;
   if (typeof runtime.runTodosExport !== "function") {
     throw new Error("Bundled todos runtime module is missing runTodosExport().");
   }

package/packages/pm-todos/extensions/todos/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 = "todos";
+const PACKAGE_NAME = "pm-todos";
+const DIAGNOSTIC_NAME = "todos";
+
+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-todos/extensions/todos/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 = "todos";
+const PACKAGE_NAME = "pm-todos";
+const DIAGNOSTIC_NAME = "todos";
+
+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.`,
+  );
+}