@unbrained/pm-cli 2026.5.11 → 2026.5.14

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

@@ -0,0 +1,109 @@
+import type { CommandDefinition, ExtensionApi, GlobalOptions } from "../../../../src/sdk/index.js";
+import {
+  runTemplatesList as runTemplatesListPackage,
+  runTemplatesSave as runTemplatesSavePackage,
+  runTemplatesShow as runTemplatesShowPackage,
+  type TemplatesListResult,
+  type TemplatesSaveResult,
+  type TemplatesShowResult,
+} from "./runtime.js";
+
+export const manifest = {
+  name: "builtin-templates",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands", "schema"],
+};
+
+function firstArg(args: string[], commandName: string): string {
+  const value = args[0];
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value;
+  }
+  throw new Error(`${commandName} requires a template name argument.`);
+}
+
+async function runTemplatesListFromRuntime(global: GlobalOptions): Promise<TemplatesListResult> {
+  return runTemplatesListPackage(global);
+}
+
+async function runTemplatesSaveFromRuntime(
+  args: string[],
+  options: Record<string, unknown>,
+  global: GlobalOptions,
+): Promise<TemplatesSaveResult> {
+  return runTemplatesSavePackage(firstArg(args, "templates save"), options, global);
+}
+
+async function runTemplatesShowFromRuntime(args: string[], global: GlobalOptions): Promise<TemplatesShowResult> {
+  return runTemplatesShowPackage(firstArg(args, "templates show"), global);
+}
+
+const createOptionFlags = [
+  { long: "--title", short: "-t", value_name: "value", value_type: "string", description: "Template default item title." },
+  { long: "--description", short: "-d", value_name: "value", value_type: "string", description: "Template default item description." },
+  { long: "--type", value_name: "value", value_type: "string", description: "Template default item type." },
+  { long: "--status", short: "-s", value_name: "value", value_type: "string", description: "Template default item status." },
+  { long: "--priority", short: "-p", value_name: "value", value_type: "string", description: "Template default priority 0..4." },
+  { long: "--tags", value_name: "value", value_type: "string", description: "Template default comma-separated tags." },
+  { long: "--body", short: "-b", value_name: "value", value_type: "string", description: "Template default item markdown body." },
+  { long: "--deadline", value_name: "value", value_type: "string", description: "Template default deadline." },
+  { long: "--estimate", value_name: "value", value_type: "string", description: "Template default estimated minutes." },
+  { long: "--estimated-minutes", value_name: "value", value_type: "string", description: "Template default estimated minutes." },
+  { long: "--acceptance-criteria", value_name: "value", value_type: "string", description: "Template default acceptance criteria." },
+  { long: "--ac", value_name: "value", value_type: "string", description: "Alias for --acceptance-criteria." },
+  { long: "--author", value_name: "value", value_type: "string", description: "Template default mutation author." },
+  { long: "--message", value_name: "value", value_type: "string", description: "Template default history message." },
+  { long: "--assignee", value_name: "value", value_type: "string", description: "Template default assignee." },
+  { long: "--parent", value_name: "value", value_type: "string", description: "Template default parent item ID." },
+  { long: "--reviewer", value_name: "value", value_type: "string", description: "Template default reviewer." },
+  { long: "--risk", value_name: "value", value_type: "string", description: "Template default risk level." },
+  { long: "--confidence", value_name: "value", value_type: "string", description: "Template default confidence." },
+  { long: "--sprint", value_name: "value", value_type: "string", description: "Template default sprint identifier." },
+  { long: "--release", value_name: "value", value_type: "string", description: "Template default release identifier." },
+  { long: "--dep", value_name: "value", value_type: "string", description: "Template default dependency seed.", repeatable: true },
+  { long: "--comment", value_name: "value", value_type: "string", description: "Template default comment seed.", repeatable: true },
+  { long: "--note", value_name: "value", value_type: "string", description: "Template default note seed.", repeatable: true },
+  { long: "--learning", value_name: "value", value_type: "string", description: "Template default learning seed.", repeatable: true },
+  { long: "--file", value_name: "value", value_type: "string", description: "Template default linked file seed.", repeatable: true },
+  { long: "--test", value_name: "value", value_type: "string", description: "Template default linked test seed.", repeatable: true },
+  { long: "--doc", value_name: "value", value_type: "string", description: "Template default linked doc seed.", repeatable: true },
+  { long: "--reminder", value_name: "value", value_type: "string", description: "Template default reminder seed.", repeatable: true },
+  { long: "--event", value_name: "value", value_type: "string", description: "Template default event seed.", repeatable: true },
+] as const;
+
+export function activate(api: ExtensionApi): void {
+  api.registerCommand({
+    name: "templates",
+    action: "templates-list",
+    description: "List saved create templates.",
+    run: async (context) => runTemplatesListFromRuntime(context.global),
+  } satisfies CommandDefinition);
+  api.registerCommand({
+    name: "templates list",
+    action: "templates-list",
+    description: "List saved create templates.",
+    run: async (context) => runTemplatesListFromRuntime(context.global),
+  } satisfies CommandDefinition);
+  api.registerCommand({
+    name: "templates save",
+    action: "templates-save",
+    description: "Save reusable create template defaults.",
+    arguments: [{ name: "name", required: true, description: "Template name." }],
+    flags: [...createOptionFlags],
+    run: async (context) => runTemplatesSaveFromRuntime(context.args, context.options, context.global),
+  } satisfies CommandDefinition);
+  api.registerCommand({
+    name: "templates show",
+    action: "templates-show",
+    description: "Show a saved create template.",
+    arguments: [{ name: "name", required: true, description: "Template name." }],
+    run: async (context) => runTemplatesShowFromRuntime(context.args, context.global),
+  } satisfies CommandDefinition);
+}
+
+export default {
+  manifest,
+  activate,
+};

package/packages/pm-templates/extensions/templates/manifest.json

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

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

@@ -0,0 +1,226 @@
+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.`,
+    );
+  }
+  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)
+    ) {
+      return loaded;
+    }
+  } 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_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 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,
+  };
+}
+
+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,
+  };
+}
+
+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,
+  };
+}

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

@@ -0,0 +1,283 @@
+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;
+  updated_at: string;
+  path: string;
+  options: CreateTemplateOptions;
+}
+
+export interface TemplatesListResult {
+  templates: string[];
+  count: number;
+}
+
+export interface TemplatesShowResult {
+  name: string;
+  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;
+}
+
+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);
+}
+
+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);
+  }
+  return sortTemplateOptions(normalized);
+}
+
+function parseStoredTemplateDocument(raw: string, normalizedName: string): StoredCreateTemplateDocument {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } 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 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,
+  };
+}
+
+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 runTemplatesSave(
+  rawTemplateName: string,
+  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,
+  };
+}
+
+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,
+  };
+}
+
+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,
+  };
+}

package/packages/pm-templates/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@unbrained/pm-package-templates",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "First-party pm package for reusable create templates.",
+  "homepage": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-templates#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unbraind/pm-cli.git",
+    "directory": "packages/pm-templates"
+  },
+  "bugs": {
+    "url": "https://github.com/unbraind/pm-cli/issues"
+  },
+  "keywords": [
+    "pm-package",
+    "project-management",
+    "templates"
+  ],
+  "pm": {
+    "aliases": [
+      "templates"
+    ],
+    "extensions": [
+      "extensions/templates"
+    ],
+    "catalog": {
+      "display_name": "Create Templates",
+      "category": "workflow",
+      "summary": "Save, list, show, and apply reusable pm create option templates.",
+      "tags": [
+        "templates",
+        "create",
+        "workflow"
+      ],
+      "links": {
+        "docs": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-templates#readme",
+        "repository": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-templates",
+        "report": "https://github.com/unbraind/pm-cli/issues"
+      }
+    },
+    "docs": [
+      "README.md"
+    ],
+    "examples": [
+      "README.md"
+    ]
+  }
+}

package/packages/pm-todos/README.md

@@ -0,0 +1,11 @@
+# pm Todos Package
+
+First-party pm package for Todo markdown import and export.
+
+```bash
+pm install ./packages/pm-todos --project
+pm todos import --folder .pm/todos
+pm todos export --folder .pm/todos
+```
+
+The package exposes the `todos import` and `todos export` extension commands through the `pm.extensions` package manifest. Runtime sources are authored in TypeScript and shipped with JavaScript entry artifacts for Node extension loading.