@unbrained/pm-cli 2026.5.6 → 2026.5.10

package/dist/cli/commands/guide.js

@@ -0,0 +1,260 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { listGuideTopicIds, listGuideTopics, resolveGuideTopic, } from "../guide-topics.js";
+export const GUIDE_OUTPUT_VALUES = ["markdown", "toon", "json"];
+export const GUIDE_DEPTH_VALUES = ["brief", "standard", "deep"];
+const PACKAGE_ROOT_FROM_SOURCE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+function parseGuideOutputFormat(raw) {
+    if (!raw) {
+        return undefined;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (!GUIDE_OUTPUT_VALUES.includes(normalized)) {
+        throw new PmCliError("Guide format must be one of markdown|toon|json", EXIT_CODE.USAGE);
+    }
+    return normalized;
+}
+export function resolveGuideOutputFormat(options, global) {
+    const commandFormat = parseGuideOutputFormat(options.format);
+    if (global.json && commandFormat && commandFormat !== "json") {
+        throw new PmCliError("Cannot combine --json with --format markdown|toon", EXIT_CODE.USAGE);
+    }
+    if (global.json) {
+        return "json";
+    }
+    return commandFormat ?? "toon";
+}
+function parseGuideDepth(raw) {
+    if (!raw) {
+        return "brief";
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (!GUIDE_DEPTH_VALUES.includes(normalized)) {
+        throw new PmCliError("Guide depth must be one of brief|standard|deep", EXIT_CODE.USAGE);
+    }
+    return normalized;
+}
+function resolvePackageRoot() {
+    const envRoot = process.env.PM_CLI_PACKAGE_ROOT;
+    if (typeof envRoot === "string" && envRoot.trim().length > 0) {
+        return path.resolve(envRoot.trim());
+    }
+    return PACKAGE_ROOT_FROM_SOURCE;
+}
+function normalizeLineEndings(value) {
+    return value.replaceAll("\r\n", "\n");
+}
+function toExcerpt(content, maxLines, maxCharacters) {
+    const normalized = normalizeLineEndings(content);
+    const lines = normalized.split("\n");
+    const lineSlice = lines.slice(0, maxLines);
+    let excerpt = lineSlice.join("\n");
+    let truncated = lines.length > maxLines;
+    if (excerpt.length > maxCharacters) {
+        excerpt = excerpt.slice(0, maxCharacters);
+        truncated = true;
+    }
+    return {
+        excerpt: excerpt.trimEnd(),
+        truncated,
+        lineCount: lines.length,
+    };
+}
+async function renderGuideDocs(topic, depth, packageRoot) {
+    const includeContent = depth !== "brief";
+    const contentMode = includeContent ? (depth === "deep" ? "full" : "excerpt") : "none";
+    const docs = [];
+    for (const doc of topic.docs) {
+        const absolutePath = path.resolve(packageRoot, doc.path);
+        if (!includeContent) {
+            docs.push({
+                path: doc.path,
+                purpose: doc.purpose,
+                optional: doc.optional === true,
+                exists: true,
+                line_count: null,
+                content_mode: "none",
+                content: null,
+                truncated: false,
+            });
+            continue;
+        }
+        try {
+            const rawContent = await readFile(absolutePath, "utf8");
+            if (depth === "deep") {
+                const normalized = normalizeLineEndings(rawContent).trimEnd();
+                docs.push({
+                    path: doc.path,
+                    purpose: doc.purpose,
+                    optional: doc.optional === true,
+                    exists: true,
+                    line_count: normalized.length === 0 ? 0 : normalized.split("\n").length,
+                    content_mode: "full",
+                    content: normalized,
+                    truncated: false,
+                });
+            }
+            else {
+                const excerpt = toExcerpt(rawContent, 120, 12_000);
+                docs.push({
+                    path: doc.path,
+                    purpose: doc.purpose,
+                    optional: doc.optional === true,
+                    exists: true,
+                    line_count: excerpt.lineCount,
+                    content_mode: contentMode,
+                    content: excerpt.excerpt,
+                    truncated: excerpt.truncated,
+                });
+            }
+        }
+        catch (error) {
+            const code = error?.code;
+            const missing = code === "ENOENT";
+            docs.push({
+                path: doc.path,
+                purpose: doc.purpose,
+                optional: doc.optional === true,
+                exists: false,
+                line_count: null,
+                content_mode: "none",
+                content: null,
+                truncated: false,
+            });
+            if (!missing) {
+                throw new PmCliError(`Failed to read guide document "${doc.path}".`, EXIT_CODE.GENERIC_FAILURE);
+            }
+        }
+    }
+    return docs;
+}
+function buildGuideIndex(depth) {
+    const topics = listGuideTopics().map((topic) => ({
+        id: topic.id,
+        aliases: topic.aliases,
+        title: topic.title,
+        summary: topic.summary,
+        intent: topic.intent,
+        quick_commands: depth === "brief" ? topic.commands.slice(0, 3) : topic.commands.slice(0, 6),
+        docs: topic.docs.map((doc) => ({ path: doc.path, purpose: doc.purpose })),
+        related: topic.related,
+    }));
+    return {
+        output_default: "toon",
+        mode: "index",
+        depth,
+        topics,
+        suggested_next_steps: [
+            "pm guide <topic>",
+            "pm guide <topic> --depth standard",
+            "pm guide <topic> --depth deep --format markdown",
+            "pm guide <topic> --json",
+        ],
+    };
+}
+function ensureGuideTopic(topic) {
+    const resolved = resolveGuideTopic(topic);
+    if (resolved) {
+        return resolved;
+    }
+    const available = listGuideTopicIds().join(", ");
+    throw new PmCliError(`Unknown guide topic "${topic ?? ""}". Available topics: ${available}. Use "pm guide --list" to browse.`, EXIT_CODE.USAGE);
+}
+export async function runGuide(options, global) {
+    const depth = parseGuideDepth(typeof options.depth === "string" ? options.depth : undefined);
+    const listRequested = options.list === true;
+    const topicRaw = typeof options.topic === "string" ? options.topic : undefined;
+    if (listRequested || !topicRaw) {
+        return buildGuideIndex(depth);
+    }
+    const topic = ensureGuideTopic(topicRaw);
+    const packageRoot = resolvePackageRoot();
+    const docs = await renderGuideDocs(topic, depth, packageRoot);
+    const warnings = docs
+        .filter((doc) => !doc.exists && !doc.optional)
+        .map((doc) => `Missing required guide document: ${doc.path}`);
+    return {
+        output_default: "toon",
+        mode: "topic",
+        depth,
+        requested_topic: topicRaw,
+        topic,
+        docs,
+        warnings,
+    };
+}
+function markdownCodeFence(content) {
+    return content.replaceAll("```", "``\\`");
+}
+export function renderGuideMarkdown(result) {
+    if (result.mode === "index") {
+        const lines = [
+            "# pm guide",
+            "",
+            "Token-efficient local documentation index for agent and maintainer workflows.",
+            "",
+            "## Topics",
+        ];
+        for (const topic of result.topics) {
+            lines.push(`- \`${topic.id}\` - ${topic.summary}`);
+            if (result.depth !== "brief") {
+                lines.push(`  - intent: ${topic.intent}`);
+                lines.push(`  - docs: ${topic.docs.map((doc) => `\`${doc.path}\``).join(", ")}`);
+            }
+        }
+        lines.push("", "## Next steps");
+        for (const step of result.suggested_next_steps) {
+            lines.push(`- \`${step}\``);
+        }
+        return lines.join("\n");
+    }
+    const lines = [
+        `# pm guide ${result.topic.id}`,
+        "",
+        result.topic.summary,
+        "",
+        "## Intent",
+        result.topic.intent,
+        "",
+        "## Key commands",
+        ...result.topic.commands.map((command) => `- \`${command}\``),
+        "",
+        "## Workflow prompts",
+    ];
+    for (const workflow of result.topic.workflows) {
+        lines.push(`### ${workflow.name}`);
+        lines.push(`goal: ${workflow.goal}`);
+        lines.push(`prompt: ${workflow.prompt}`);
+        lines.push("commands:");
+        lines.push(...workflow.commands.map((command) => `- \`${command}\``));
+        lines.push("");
+    }
+    lines.push("## Documents");
+    for (const doc of result.docs) {
+        const status = doc.exists ? "available" : doc.optional ? "missing (optional)" : "missing (required)";
+        lines.push(`- \`${doc.path}\` - ${doc.purpose} (${status})`);
+        if (doc.exists && doc.content_mode !== "none" && doc.content) {
+            lines.push("");
+            lines.push(`### Excerpt: \`${doc.path}\``);
+            if (doc.truncated) {
+                lines.push("_truncated for context efficiency_");
+            }
+            lines.push("```markdown");
+            lines.push(markdownCodeFence(doc.content));
+            lines.push("```");
+        }
+    }
+    if (result.topic.related.length > 0) {
+        lines.push("", "## Related topics");
+        lines.push(...result.topic.related.map((topic) => `- \`${topic}\``));
+    }
+    if (result.warnings.length > 0) {
+        lines.push("", "## Warnings");
+        lines.push(...result.warnings.map((warning) => `- ${warning}`));
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=guide.js.map

package/dist/cli/commands/guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.js","sourceRoot":"/","sources":["cli/commands/guide.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport {\n  listGuideTopicIds,\n  listGuideTopics,\n  resolveGuideTopic,\n  type GuideTopicDefinition,\n} from \"../guide-topics.js\";\n\nexport const GUIDE_OUTPUT_VALUES = [\"markdown\", \"toon\", \"json\"] as const;\nexport type GuideOutputFormat = (typeof GUIDE_OUTPUT_VALUES)[number];\n\nexport const GUIDE_DEPTH_VALUES = [\"brief\", \"standard\", \"deep\"] as const;\nexport type GuideDepth = (typeof GUIDE_DEPTH_VALUES)[number];\n\nexport interface GuideOptions {\n  topic?: string;\n  list?: boolean;\n  format?: string;\n  depth?: string;\n  [key: string]: unknown;\n}\n\nexport interface GuideDocRender {\n  path: string;\n  purpose: string;\n  optional: boolean;\n  exists: boolean;\n  line_count: number | null;\n  content_mode: \"none\" | \"excerpt\" | \"full\";\n  content: string | null;\n  truncated: boolean;\n}\n\nexport interface GuideIndexResult {\n  output_default: \"toon\";\n  mode: \"index\";\n  depth: GuideDepth;\n  topics: Array<{\n    id: string;\n    aliases: string[];\n    title: string;\n    summary: string;\n    intent: string;\n    quick_commands: string[];\n    docs: Array<{ path: string; purpose: string }>;\n    related: string[];\n  }>;\n  suggested_next_steps: string[];\n}\n\nexport interface GuideTopicResult {\n  output_default: \"toon\";\n  mode: \"topic\";\n  depth: GuideDepth;\n  requested_topic: string;\n  topic: GuideTopicDefinition;\n  docs: GuideDocRender[];\n  warnings: string[];\n}\n\nexport type GuideResult = GuideIndexResult | GuideTopicResult;\n\nconst PACKAGE_ROOT_FROM_SOURCE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), \"..\", \"..\", \"..\");\n\nfunction parseGuideOutputFormat(raw: string | undefined): GuideOutputFormat | undefined {\n  if (!raw) {\n    return undefined;\n  }\n  const normalized = raw.trim().toLowerCase();\n  if (!GUIDE_OUTPUT_VALUES.includes(normalized as GuideOutputFormat)) {\n    throw new PmCliError(\"Guide format must be one of markdown|toon|json\", EXIT_CODE.USAGE);\n  }\n  return normalized as GuideOutputFormat;\n}\n\nexport function resolveGuideOutputFormat(options: GuideOptions, global: GlobalOptions): GuideOutputFormat {\n  const commandFormat = parseGuideOutputFormat(options.format);\n  if (global.json && commandFormat && commandFormat !== \"json\") {\n    throw new PmCliError(\"Cannot combine --json with --format markdown|toon\", EXIT_CODE.USAGE);\n  }\n  if (global.json) {\n    return \"json\";\n  }\n  return commandFormat ?? \"toon\";\n}\n\nfunction parseGuideDepth(raw: string | undefined): GuideDepth {\n  if (!raw) {\n    return \"brief\";\n  }\n  const normalized = raw.trim().toLowerCase();\n  if (!GUIDE_DEPTH_VALUES.includes(normalized as GuideDepth)) {\n    throw new PmCliError(\"Guide depth must be one of brief|standard|deep\", EXIT_CODE.USAGE);\n  }\n  return normalized as GuideDepth;\n}\n\nfunction resolvePackageRoot(): string {\n  const envRoot = process.env.PM_CLI_PACKAGE_ROOT;\n  if (typeof envRoot === \"string\" && envRoot.trim().length > 0) {\n    return path.resolve(envRoot.trim());\n  }\n  return PACKAGE_ROOT_FROM_SOURCE;\n}\n\nfunction normalizeLineEndings(value: string): string {\n  return value.replaceAll(\"\\r\\n\", \"\\n\");\n}\n\nfunction toExcerpt(content: string, maxLines: number, maxCharacters: number): { excerpt: string; truncated: boolean; lineCount: number } {\n  const normalized = normalizeLineEndings(content);\n  const lines = normalized.split(\"\\n\");\n  const lineSlice = lines.slice(0, maxLines);\n  let excerpt = lineSlice.join(\"\\n\");\n  let truncated = lines.length > maxLines;\n  if (excerpt.length > maxCharacters) {\n    excerpt = excerpt.slice(0, maxCharacters);\n    truncated = true;\n  }\n  return {\n    excerpt: excerpt.trimEnd(),\n    truncated,\n    lineCount: lines.length,\n  };\n}\n\nasync function renderGuideDocs(topic: GuideTopicDefinition, depth: GuideDepth, packageRoot: string): Promise<GuideDocRender[]> {\n  const includeContent = depth !== \"brief\";\n  const contentMode: GuideDocRender[\"content_mode\"] = includeContent ? (depth === \"deep\" ? \"full\" : \"excerpt\") : \"none\";\n  const docs: GuideDocRender[] = [];\n  for (const doc of topic.docs) {\n    const absolutePath = path.resolve(packageRoot, doc.path);\n    if (!includeContent) {\n      docs.push({\n        path: doc.path,\n        purpose: doc.purpose,\n        optional: doc.optional === true,\n        exists: true,\n        line_count: null,\n        content_mode: \"none\",\n        content: null,\n        truncated: false,\n      });\n      continue;\n    }\n    try {\n      const rawContent = await readFile(absolutePath, \"utf8\");\n      if (depth === \"deep\") {\n        const normalized = normalizeLineEndings(rawContent).trimEnd();\n        docs.push({\n          path: doc.path,\n          purpose: doc.purpose,\n          optional: doc.optional === true,\n          exists: true,\n          line_count: normalized.length === 0 ? 0 : normalized.split(\"\\n\").length,\n          content_mode: \"full\",\n          content: normalized,\n          truncated: false,\n        });\n      } else {\n        const excerpt = toExcerpt(rawContent, 120, 12_000);\n        docs.push({\n          path: doc.path,\n          purpose: doc.purpose,\n          optional: doc.optional === true,\n          exists: true,\n          line_count: excerpt.lineCount,\n          content_mode: contentMode,\n          content: excerpt.excerpt,\n          truncated: excerpt.truncated,\n        });\n      }\n    } catch (error) {\n      const code = (error as { code?: string } | null)?.code;\n      const missing = code === \"ENOENT\";\n      docs.push({\n        path: doc.path,\n        purpose: doc.purpose,\n        optional: doc.optional === true,\n        exists: false,\n        line_count: null,\n        content_mode: \"none\",\n        content: null,\n        truncated: false,\n      });\n      if (!missing) {\n        throw new PmCliError(`Failed to read guide document \"${doc.path}\".`, EXIT_CODE.GENERIC_FAILURE);\n      }\n    }\n  }\n  return docs;\n}\n\nfunction buildGuideIndex(depth: GuideDepth): GuideIndexResult {\n  const topics = listGuideTopics().map((topic) => ({\n    id: topic.id,\n    aliases: topic.aliases,\n    title: topic.title,\n    summary: topic.summary,\n    intent: topic.intent,\n    quick_commands: depth === \"brief\" ? topic.commands.slice(0, 3) : topic.commands.slice(0, 6),\n    docs: topic.docs.map((doc) => ({ path: doc.path, purpose: doc.purpose })),\n    related: topic.related,\n  }));\n  return {\n    output_default: \"toon\",\n    mode: \"index\",\n    depth,\n    topics,\n    suggested_next_steps: [\n      \"pm guide <topic>\",\n      \"pm guide <topic> --depth standard\",\n      \"pm guide <topic> --depth deep --format markdown\",\n      \"pm guide <topic> --json\",\n    ],\n  };\n}\n\nfunction ensureGuideTopic(topic: string | undefined): GuideTopicDefinition {\n  const resolved = resolveGuideTopic(topic);\n  if (resolved) {\n    return resolved;\n  }\n  const available = listGuideTopicIds().join(\", \");\n  throw new PmCliError(\n    `Unknown guide topic \"${topic ?? \"\"}\". Available topics: ${available}. Use \"pm guide --list\" to browse.`,\n    EXIT_CODE.USAGE,\n  );\n}\n\nexport async function runGuide(options: GuideOptions, global: GlobalOptions): Promise<GuideResult> {\n  const depth = parseGuideDepth(typeof options.depth === \"string\" ? options.depth : undefined);\n  const listRequested = options.list === true;\n  const topicRaw = typeof options.topic === \"string\" ? options.topic : undefined;\n  if (listRequested || !topicRaw) {\n    return buildGuideIndex(depth);\n  }\n\n  const topic = ensureGuideTopic(topicRaw);\n  const packageRoot = resolvePackageRoot();\n  const docs = await renderGuideDocs(topic, depth, packageRoot);\n  const warnings = docs\n    .filter((doc) => !doc.exists && !doc.optional)\n    .map((doc) => `Missing required guide document: ${doc.path}`);\n\n  return {\n    output_default: \"toon\",\n    mode: \"topic\",\n    depth,\n    requested_topic: topicRaw,\n    topic,\n    docs,\n    warnings,\n  };\n}\n\nfunction markdownCodeFence(content: string): string {\n  return content.replaceAll(\"```\", \"``\\\\`\");\n}\n\nexport function renderGuideMarkdown(result: GuideResult): string {\n  if (result.mode === \"index\") {\n    const lines: string[] = [\n      \"# pm guide\",\n      \"\",\n      \"Token-efficient local documentation index for agent and maintainer workflows.\",\n      \"\",\n      \"## Topics\",\n    ];\n    for (const topic of result.topics) {\n      lines.push(`- \\`${topic.id}\\` - ${topic.summary}`);\n      if (result.depth !== \"brief\") {\n        lines.push(`  - intent: ${topic.intent}`);\n        lines.push(`  - docs: ${topic.docs.map((doc) => `\\`${doc.path}\\``).join(\", \")}`);\n      }\n    }\n    lines.push(\"\", \"## Next steps\");\n    for (const step of result.suggested_next_steps) {\n      lines.push(`- \\`${step}\\``);\n    }\n    return lines.join(\"\\n\");\n  }\n\n  const lines: string[] = [\n    `# pm guide ${result.topic.id}`,\n    \"\",\n    result.topic.summary,\n    \"\",\n    \"## Intent\",\n    result.topic.intent,\n    \"\",\n    \"## Key commands\",\n    ...result.topic.commands.map((command) => `- \\`${command}\\``),\n    \"\",\n    \"## Workflow prompts\",\n  ];\n  for (const workflow of result.topic.workflows) {\n    lines.push(`### ${workflow.name}`);\n    lines.push(`goal: ${workflow.goal}`);\n    lines.push(`prompt: ${workflow.prompt}`);\n    lines.push(\"commands:\");\n    lines.push(...workflow.commands.map((command) => `- \\`${command}\\``));\n    lines.push(\"\");\n  }\n  lines.push(\"## Documents\");\n  for (const doc of result.docs) {\n    const status = doc.exists ? \"available\" : doc.optional ? \"missing (optional)\" : \"missing (required)\";\n    lines.push(`- \\`${doc.path}\\` - ${doc.purpose} (${status})`);\n    if (doc.exists && doc.content_mode !== \"none\" && doc.content) {\n      lines.push(\"\");\n      lines.push(`### Excerpt: \\`${doc.path}\\``);\n      if (doc.truncated) {\n        lines.push(\"_truncated for context efficiency_\");\n      }\n      lines.push(\"```markdown\");\n      lines.push(markdownCodeFence(doc.content));\n      lines.push(\"```\");\n    }\n  }\n  if (result.topic.related.length > 0) {\n    lines.push(\"\", \"## Related topics\");\n    lines.push(...result.topic.related.map((topic) => `- \\`${topic}\\``));\n  }\n  if (result.warnings.length > 0) {\n    lines.push(\"\", \"## Warnings\");\n    lines.push(...result.warnings.map((warning) => `- ${warning}`));\n  }\n  return lines.join(\"\\n\");\n}\n\n"]}

package/dist/cli/commands/health.js

@@ -778,7 +778,7 @@ async function buildHistoryDriftCheck(pmRoot, items) {
         }
         const { body, ...frontMatter } = item;
         const currentHash = hashDocument({
-            front_matter: frontMatter,
+            metadata: frontMatter,
             body,
         });
         if (latestAfterHash !== currentHash) {