@unbrained/pm-cli 2026.9.20 → 2026.9.21

package/packages/pm-guide-shell/extensions/guide-shell/runtime.ts

@@ -1,5 +1,5 @@
 /**
- * Runtime contracts and behavior for packages/pm guide shell/extensions/guide shell/runtime.
+ * Adapt package commands to public SDK guide/completion operations and preserve their Markdown, script and word-list transports.
  *
  * @module packages/pm-guide-shell/extensions/guide-shell/runtime
  */
@@ -27,6 +27,7 @@ import {
   type ServiceOverrideContext,
 } from "@unbrained/pm-cli/sdk";
 
+/** Resolve the explicit topic before positional input and retain only SDK-supported guide options. */
 function normalizeGuideOptions(
   args: string[],
   options: Record<string, unknown>,
@@ -44,6 +45,7 @@ function normalizeGuideOptions(
   };
 }
 
+/** Choose the shell with a Bash default and normalize camel-case or snake-case choice options. */
 function normalizeCompletionOptions(
   args: string[],
   options: Record<string, unknown>,
@@ -66,6 +68,7 @@ function normalizeCompletionOptions(
   };
 }
 
+/** Return distinct nonblank runtime type names in stable locale order without inventing fallback types. */
 function collectTypeNames(
   typeRegistry: ReturnType<typeof resolveItemTypeRegistry>,
 ): string[] {
@@ -79,12 +82,7 @@ function collectTypeNames(
   ].sort((left, right) => left.localeCompare(right));
 }
 
-function collectTypeToFolder(
-  typeRegistry: ReturnType<typeof resolveItemTypeRegistry>,
-): Record<string, string> {
-  return typeRegistry.type_to_folder;
-}
-
+/** Extract nonblank workflow status identifiers in stable locale order for helper responses. */
 function collectStatusNames(
   statusRegistry: ReturnType<typeof resolveRuntimeStatusRegistry>,
 ): string[] {
@@ -156,6 +154,7 @@ async function buildCompletionRuntimeConfig(global: GlobalOptions): Promise<Comp
   };
 }
 
+/** Accept only non-array objects as output envelopes; primitive and array results remain unwrapped. */
 function payloadRecord(payload: unknown): Record<string, unknown> | undefined {
   return typeof payload === "object" &&
     payload !== null &&
@@ -164,15 +163,18 @@ function payloadRecord(payload: unknown): Record<string, unknown> | undefined {
     : undefined;
 }
 
+/** Honor an explicit JSON envelope format and otherwise select the default human-readable transport. */
 function readPayloadFormat(payload: unknown): "toon" | "json" {
   return payloadRecord(payload)?.format === "json" ? "json" : "toon";
 }
 
+/** Unwrap an own result property while preserving bare results and explicit undefined payload values. */
 function readPayloadResult(payload: unknown): unknown {
   const record = payloadRecord(payload);
   return record && Object.hasOwn(record, "result") ? record.result : payload;
 }
 
+/** Trim and deduplicate nonblank string tags across all items, then sort the helper word list. */
 function collectTagsFromItems(items: ItemMetadata[]): string[] {
   const tagSet = new Set<string>();
   for (const item of items) {
@@ -186,6 +188,7 @@ function collectTagsFromItems(items: ItemMetadata[]): string[] {
   return [...tagSet].sort((left, right) => left.localeCompare(right));
 }
 
+/** Read only string entries from the requested helper collection, returning no choices for malformed results. */
 function readStringArrayResult(
   result: unknown,
   key: "tags" | "statuses" | "types",
@@ -199,6 +202,7 @@ function readStringArrayResult(
     : [];
 }
 
+/** Serialize explicit JSON or the whitespace-delimited helper protocol, always terminating output with a newline. */
 function renderJsonOrWords(
   payload: unknown,
   result: unknown,
@@ -210,6 +214,7 @@ function renderJsonOrWords(
   return `${readStringArrayResult(result, key).join(" ")}\n`;
 }
 
+/** Render explicit JSON or a generated script with a trailing newline; defer unsupported result shapes. */
 function renderCompletionPackageOutput(
   payload: unknown,
   result: unknown,
@@ -228,6 +233,7 @@ function renderCompletionPackageOutput(
   return null;
 }
 
+/** Render guide Markdown or JSON according to SDK format precedence and defer generic TOON rendering. */
 function renderGuidePackageOutput(
   context: ServiceOverrideContext,
   result: unknown,
@@ -247,7 +253,7 @@ function renderGuidePackageOutput(
   return null;
 }
 
-/** Executes the guide package operation through the package runtime. */
+/** Normalize package arguments and delegate guide discovery to the public SDK using the caller workspace options. */
 export async function runGuidePackage(
   args: string[],
   options: Record<string, unknown>,
@@ -256,7 +262,7 @@ export async function runGuidePackage(
   return runGuide(normalizeGuideOptions(args, options), global);
 }
 
-/** Executes the completion package operation through the package runtime. */
+/** Render the requested shell using explicit choices plus the active workspace schema and package command paths. */
 export async function runCompletionPackage(
   args: string[],
   options: Record<string, unknown>,
@@ -273,7 +279,7 @@ export async function runCompletionPackage(
   );
 }
 
-/** Executes the completion tags package operation through the package runtime. */
+/** Collect tags across configured item folders and formats; return an empty counted collection before initialization. */
 export async function runCompletionTagsPackage(
   global: GlobalOptions,
 ): Promise<{ tags: string[]; count: number }> {
@@ -284,7 +290,7 @@ export async function runCompletionTagsPackage(
   const settings = await readSettings(pmRoot);
   const registrations = getActiveExtensionRegistrations();
   const typeRegistry = resolveItemTypeRegistry(settings, registrations);
-  const typeToFolder = collectTypeToFolder(typeRegistry);
+  const typeToFolder = typeRegistry.type_to_folder;
   const itemFormat = (
     settings.item_format === "json_markdown" ? "json_markdown" : "toon"
   ) as "toon" | "json_markdown";
@@ -302,7 +308,7 @@ export async function runCompletionTagsPackage(
   };
 }
 
-/** Executes the completion statuses package operation through the package runtime. */
+/** Expose configured workflow status IDs with an exact count, or an empty collection before initialization. */
 export async function runCompletionStatusesPackage(
   global: GlobalOptions,
 ): Promise<{ statuses: string[]; count: number }> {
@@ -320,7 +326,7 @@ export async function runCompletionStatusesPackage(
   };
 }
 
-/** Executes the completion types package operation through the package runtime. */
+/** Expose distinct configured and extension-provided type names with an exact count; tolerate an uninitialized workspace. */
 export async function runCompletionTypesPackage(
   global: GlobalOptions,
 ): Promise<{ types: string[]; count: number }> {
@@ -338,7 +344,7 @@ export async function runCompletionTypesPackage(
   };
 }
 
-/** Formats guide shell package output data for the selected output mode. */
+/** Preserve script and word-list wire formats for canonical commands and compatibility aliases, with explicit JSON output retained. */
 export function renderGuideShellPackageOutput(
   context: ServiceOverrideContext,
 ): string | null {
@@ -349,13 +355,13 @@ export function renderGuideShellPackageOutput(
   if (context.command === "completion") {
     return renderCompletionPackageOutput(context.payload, result);
   }
-  if (context.command === "completion-tags") {
+  if (context.command === "completion-tags" || context.command === "completion tags") {
     return renderJsonOrWords(context.payload, result, "tags");
   }
-  if (context.command === "completion-statuses") {
+  if (context.command === "completion-statuses" || context.command === "completion statuses") {
     return renderJsonOrWords(context.payload, result, "statuses");
   }
-  if (context.command === "completion-types") {
+  if (context.command === "completion-types" || context.command === "completion types") {
     return renderJsonOrWords(context.payload, result, "types");
   }
   return null;

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.9.20",
+  "version": "2026.9.21",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.9.20",
+  "version": "2026.9.21",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.9.20",
+  "version": "2026.9.21",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.9.20",
+  "version": "2026.9.21",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.9.20",
+  "version": "2026.9.21",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.9.20",
+  "version": "2026.9.21",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.9.20",
+  "version": "2026.9.21",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-vcs-sdk-exemplar",
-  "version": "2026.9.20",
+  "version": "2026.9.21",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",

package/plugins/pm-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pm-claude",
   "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
-  "version": "2026.9.20",
+  "version": "2026.9.21",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

package/plugins/pm-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-codex",
-  "version": "2026.9.20",
+  "version": "2026.9.21",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",