@unbrained/pm-cli 2026.9.7 → 2026.9.8

package/dist/sdk/templates.js

@@ -1,293 +1,3 @@
-/**
- * @module sdk/templates
- *
- * Implements the pm templates command surface and its agent-facing runtime behavior.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5c70da27-21f6-5d31-b506-96e1818996d6")}catch(e){}}();
-import { assertInitializedTracker } from "./environment/tracker-preflight.js";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { pathExists, readFileIfExists, } from "../core/fs/fs-utils.js";
-import { writeWorkspaceJsonWithHistory } from "../core/history/workspace-history.js";
-import { resolveAuthor } from "../core/shared/author.js";
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-import { nowIso } from "../core/shared/time.js";
-import { resolvePmRoot } from "../core/store/paths.js";
-import { readSettings } from "../core/store/settings.js";
-import { CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS } from "./cli-contracts.js";
-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).filter((target) => target !== "acceptanceCriteria");
-const TEMPLATE_OPTION_REPEATABLE_KEY_SET = new Set(TEMPLATE_OPTION_REPEATABLE_KEYS);
-const BUILTIN_TEMPLATE_TIMESTAMP = "1970-01-01T00:00:00.000Z";
-const BUILTIN_TEMPLATES = {
-    bug: {
-        type: "Issue",
-        priority: "1",
-        tags: "bug",
-        acceptanceCriteria: "Bug no longer reproduces with the steps below and a regression test guards it.",
-        expectedResult: "Describe the correct behavior.",
-        actualResult: "Describe the observed (buggy) behavior.",
-        body: "## Repro steps\n1. \n2. \n3. \n\n## Expected\n\n## Actual\n",
-    },
-    feature: {
-        type: "Feature",
-        priority: "2",
-        tags: "feature",
-        acceptanceCriteria: "Feature is shipped behind agreed scope with tests and docs updated.",
-        whyNow: "Explain why this is worth doing now (impact / urgency).",
-        body: "## Goal\n\n## Why now\n\n## Out of scope\n",
-    },
-    spike: {
-        type: "Task",
-        priority: "2",
-        tags: "spike",
-        estimatedMinutes: "120",
-        acceptanceCriteria: "Timeboxed investigation complete; findings and a recommendation are recorded.",
-        body: "## Question to answer\n\n## Timebox\n2h\n\n## Findings\n\n## Recommendation\n",
-    },
-    chore: {
-        type: "Chore",
-        priority: "3",
-        tags: "chore",
-        acceptanceCriteria: "Maintenance task done with no behavior change and green checks.",
-        body: "## What\n\n## Why\n",
-    },
-};
-/** Public contract for test only, shared by SDK and presentation-layer consumers. */
-export const _testOnly = {
-    normalizeTemplateName,
-    extractTemplateOptions,
-    parseStoredTemplateDocument,
-    builtinTemplateDocument,
-    readStoredTemplateDocument,
-};
-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) {
-    await assertInitializedTracker(pmRoot);
-}
-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 optionsRecord = rawOptions;
-    const normalized = {};
-    for (const [key, value] of Object.entries(optionsRecord)) {
-        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 record = parsed;
-    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,
-    };
-}
-function builtinTemplateDocument(normalizedName) {
-    const options = BUILTIN_TEMPLATES[normalizedName];
-    if (!options) {
-        return null;
-    }
-    return {
-        name: normalizedName,
-        created_at: BUILTIN_TEMPLATE_TIMESTAMP,
-        updated_at: BUILTIN_TEMPLATE_TIMESTAMP,
-        options: sortTemplateOptions({ ...options }),
-    };
-}
-async function resolveTemplateDocument(pmRoot, normalizedName) {
-    const raw = await readFileIfExists(templatePath(pmRoot, normalizedName));
-    if (raw !== null) {
-        return {
-            document: parseStoredTemplateDocument(raw, normalizedName),
-            source: "user",
-        };
-    }
-    const builtin = builtinTemplateDocument(normalizedName);
-    if (builtin) {
-        return { document: builtin, source: "builtin" };
-    }
-    throw new PmCliError(`Template "${normalizedName}" not found`, EXIT_CODE.NOT_FOUND);
-}
-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);
-}
-/** Implements load create template options for the public runtime surface of this module. */
-export async function loadCreateTemplateOptions(pmRoot, rawTemplateName) {
-    const normalizedName = normalizeTemplateName(rawTemplateName);
-    const { document } = await resolveTemplateDocument(pmRoot, normalizedName);
-    return document.options;
-}
-/** Implements run templates save for the public runtime surface of this module. */
-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,
-    };
-    const settings = await readSettings(pmRoot);
-    await fs.mkdir(templatesDirectory(pmRoot), { recursive: true });
-    await writeWorkspaceJsonWithHistory({
-        pmRoot,
-        filePath: storedPath,
-        raw: `${JSON.stringify(document, null, 2)}\n`,
-        op: "templates:save",
-        author: resolveAuthor(undefined, settings.author_default),
-        lockTtlSeconds: settings.locks.ttl_seconds,
-        lockWaitMs: settings.locks.wait_ms,
-    });
-    return {
-        name: document.name,
-        created_at: document.created_at,
-        updated_at: document.updated_at,
-        path: storedPath,
-        options: document.options,
-    };
-}
-async function readUserTemplateNames(pmRoot) {
-    const dirPath = templatesDirectory(pmRoot);
-    if (!(await pathExists(dirPath))) {
-        return [];
-    }
-    const entries = await fs.readdir(dirPath);
-    return 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));
-}
-/** Implements run templates list for the public runtime surface of this module. */
-export async function runTemplatesList(global) {
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    await ensureTrackerInitialized(pmRoot);
-    const userTemplates = await readUserTemplateNames(pmRoot);
-    const userTemplateSet = new Set(userTemplates);
-    const builtinTemplates = Object.keys(BUILTIN_TEMPLATES).filter((name) => !userTemplateSet.has(name));
-    const sortedUser = [...userTemplates].sort((left, right) => left.localeCompare(right));
-    const sortedBuiltin = [...builtinTemplates].sort((left, right) => left.localeCompare(right));
-    const templates = [...new Set([...sortedUser, ...sortedBuiltin])].sort((left, right) => left.localeCompare(right));
-    return {
-        templates,
-        count: templates.length,
-        builtin_templates: sortedBuiltin,
-        user_templates: sortedUser,
-    };
-}
-/** Implements run templates show for the public runtime surface of this module. */
-export async function runTemplatesShow(rawTemplateName, global) {
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    await ensureTrackerInitialized(pmRoot);
-    const normalizedName = normalizeTemplateName(rawTemplateName);
-    const { document, source } = await resolveTemplateDocument(pmRoot, normalizedName);
-    return {
-        name: document.name,
-        source,
-        created_at: document.created_at,
-        updated_at: document.updated_at,
-        path: source === "builtin"
-            ? `builtin:${normalizedName}`
-            : templatePath(pmRoot, normalizedName),
-        options: document.options,
-    };
-}
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ff76c0f3-d8cf-51de-a7e6-acb0a4942268")}catch(e2){}})();import{assertInitializedTracker}from"./environment/tracker-preflight.js";import fs from"node:fs/promises";import path from"node:path";import{pathExists,readFileIfExists}from"../core/fs/fs-utils.js";import{writeWorkspaceJsonWithHistory}from"../core/history/workspace-history.js";import{resolveAuthor}from"../core/shared/author.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{nowIso}from"../core/shared/time.js";import{resolvePmRoot}from"../core/store/paths.js";import{readSettings}from"../core/store/settings.js";import{CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS}from"./cli-contracts.js";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).filter(target=>target!=="acceptanceCriteria");const TEMPLATE_OPTION_REPEATABLE_KEY_SET=new Set(TEMPLATE_OPTION_REPEATABLE_KEYS);const BUILTIN_TEMPLATE_TIMESTAMP="1970-01-01T00:00:00.000Z";const BUILTIN_TEMPLATES={bug:{type:"Issue",priority:"1",tags:"bug",acceptanceCriteria:"Bug no longer reproduces with the steps below and a regression test guards it.",expectedResult:"Describe the correct behavior.",actualResult:"Describe the observed (buggy) behavior.",body:"## Repro steps\n1. \n2. \n3. \n\n## Expected\n\n## Actual\n"},feature:{type:"Feature",priority:"2",tags:"feature",acceptanceCriteria:"Feature is shipped behind agreed scope with tests and docs updated.",whyNow:"Explain why this is worth doing now (impact / urgency).",body:"## Goal\n\n## Why now\n\n## Out of scope\n"},spike:{type:"Task",priority:"2",tags:"spike",estimatedMinutes:"120",acceptanceCriteria:"Timeboxed investigation complete; findings and a recommendation are recorded.",body:"## Question to answer\n\n## Timebox\n2h\n\n## Findings\n\n## Recommendation\n"},chore:{type:"Chore",priority:"3",tags:"chore",acceptanceCriteria:"Maintenance task done with no behavior change and green checks.",body:"## What\n\n## Why\n"}};const _testOnly={normalizeTemplateName,extractTemplateOptions,parseStoredTemplateDocument,builtinTemplateDocument,readStoredTemplateDocument};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){await assertInitializedTracker(pmRoot)}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===void 0){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 optionsRecord=rawOptions;const normalized={};for(const[key,value]of Object.entries(optionsRecord)){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 record=parsed;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}}function builtinTemplateDocument(normalizedName){const options=BUILTIN_TEMPLATES[normalizedName];if(!options){return null}return{name:normalizedName,created_at:BUILTIN_TEMPLATE_TIMESTAMP,updated_at:BUILTIN_TEMPLATE_TIMESTAMP,options:sortTemplateOptions({...options})}}async function resolveTemplateDocument(pmRoot,normalizedName){const raw=await readFileIfExists(templatePath(pmRoot,normalizedName));if(raw!==null){return{document:parseStoredTemplateDocument(raw,normalizedName),source:"user"}}const builtin=builtinTemplateDocument(normalizedName);if(builtin){return{document:builtin,source:"builtin"}}throw new PmCliError(`Template "${normalizedName}" not found`,EXIT_CODE.NOT_FOUND)}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)}async function loadCreateTemplateOptions(pmRoot,rawTemplateName){const normalizedName=normalizeTemplateName(rawTemplateName);const{document}=await resolveTemplateDocument(pmRoot,normalizedName);return document.options}async function runTemplatesSave(rawTemplateName,options,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.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};const settings=await readSettings(pmRoot);await fs.mkdir(templatesDirectory(pmRoot),{recursive:true});await writeWorkspaceJsonWithHistory({pmRoot,filePath:storedPath,raw:`${JSON.stringify(document,null,2)}
+`,op:"templates:save",author:resolveAuthor(void 0,settings.author_default),lockTtlSeconds:settings.locks.ttl_seconds,lockWaitMs:settings.locks.wait_ms});return{name:document.name,created_at:document.created_at,updated_at:document.updated_at,path:storedPath,options:document.options}}async function readUserTemplateNames(pmRoot){const dirPath=templatesDirectory(pmRoot);if(!await pathExists(dirPath)){return[]}const entries=await fs.readdir(dirPath);return 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))}async function runTemplatesList(global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await ensureTrackerInitialized(pmRoot);const userTemplates=await readUserTemplateNames(pmRoot);const userTemplateSet=new Set(userTemplates);const builtinTemplates=Object.keys(BUILTIN_TEMPLATES).filter(name=>!userTemplateSet.has(name));const sortedUser=[...userTemplates].sort((left,right)=>left.localeCompare(right));const sortedBuiltin=[...builtinTemplates].sort((left,right)=>left.localeCompare(right));const templates=[...new Set([...sortedUser,...sortedBuiltin])].sort((left,right)=>left.localeCompare(right));return{templates,count:templates.length,builtin_templates:sortedBuiltin,user_templates:sortedUser}}async function runTemplatesShow(rawTemplateName,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await ensureTrackerInitialized(pmRoot);const normalizedName=normalizeTemplateName(rawTemplateName);const{document,source}=await resolveTemplateDocument(pmRoot,normalizedName);return{name:document.name,source,created_at:document.created_at,updated_at:document.updated_at,path:source==="builtin"?`builtin:${normalizedName}`:templatePath(pmRoot,normalizedName),options:document.options}}export{_testOnly,loadCreateTemplateOptions,runTemplatesList,runTemplatesSave,runTemplatesShow};
 //# sourceMappingURL=templates.js.map
-//# debugId=5c70da27-21f6-5d31-b506-96e1818996d6