@unbrained/pm-cli 2026.5.12 → 2026.5.18

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-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"
+    ]
+  }
+}