@unbrained/pm-cli 2026.5.18 → 2026.5.24

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

@@ -1,226 +1,35 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 const sdk = await loadTemplatesSdkModule();
-const {
-  CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS,
-  EXIT_CODE,
-  PmCliError,
-  getSettingsPath,
-  nowIso,
-  pathExists,
-  readFileIfExists,
-  resolvePmRoot,
-  writeFileAtomic,
-} = sdk;
-
 async function loadTemplatesSdkModule() {
   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.`,
-    );
+    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);
-    if (
-      typeof loaded.resolvePmRoot === "function" &&
-      typeof loaded.pathExists === "function" &&
-      typeof loaded.PmCliError === "function" &&
-      Array.isArray(loaded.CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS)
-    ) {
+    if (typeof loaded.loadCreateTemplateOptions === "function" &&
+      typeof loaded.runTemplatesList === "function" &&
+      typeof loaded.runTemplatesSave === "function" &&
+      typeof loaded.runTemplatesShow === "function") {
       return loaded;
     }
   } catch {
     // Fall through to deterministic failure message below.
   }
-  throw new Error(
-    `builtin-templates failed to load SDK runtime exports from ${modulePath}.`,
-  );
+  throw new Error(`builtin-templates failed to load template 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_KEY_SET = new Set(CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS.map((entry) => entry.target));
-
-function normalizeTemplateName(rawName) {
-  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) {
-  return path.join(pmRoot, TEMPLATE_DIRECTORY_NAME);
-}
-
-function templatePath(pmRoot, normalizedName) {
-  return path.join(templatesDirectory(pmRoot), `${normalizedName}${TEMPLATE_FILE_EXTENSION}`);
-}
-
-async function ensureTrackerInitialized(pmRoot) {
-  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) {
-  return Object.fromEntries(Object.entries(options).sort(([left], [right]) => left.localeCompare(right)));
-}
-
-function extractTemplateOptions(rawOptions) {
-  const next = {};
-  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) => 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);
-}
-
-function parseStoredTemplateOptions(rawOptions, templateName) {
-  if (typeof rawOptions !== "object" || rawOptions === null || Array.isArray(rawOptions)) {
-    throw new PmCliError(`Template "${templateName}" has invalid options payload.`, EXIT_CODE.GENERIC_FAILURE);
-  }
-  const normalized = {};
-  for (const [key, value] of Object.entries(rawOptions)) {
-    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);
-  }
-  return sortTemplateOptions(normalized);
-}
-
-function parseStoredTemplateDocument(raw, normalizedName) {
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } 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);
-  }
-  const options = parseStoredTemplateOptions(parsed.options, normalizedName);
-  const now = nowIso();
-  return {
-    name: typeof parsed.name === "string" && parsed.name.trim().length > 0 ? parsed.name.trim() : normalizedName,
-    created_at: typeof parsed.created_at === "string" ? parsed.created_at : now,
-    updated_at: typeof parsed.updated_at === "string" ? parsed.updated_at : now,
-    options,
-  };
-}
-
-async function readStoredTemplateDocument(pmRoot, normalizedName) {
-  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, rawTemplateName) {
+  return sdk.loadCreateTemplateOptions(pmRoot, rawTemplateName);
 }
-
 export async function runTemplatesSave(rawTemplateName, options, global) {
-  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 = {
-    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) {
-  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, global) {
-  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-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/dist/core/output/command-aware.d.ts

@@ -1 +0,0 @@
-export declare function buildCommandAwareEnvelope(command: string, result: unknown): Record<string, unknown>;