@unbrained/pm-cli 2026.5.11 → 2026.5.14

package/packages/pm-governance-audit/extensions/governance-audit/runtime.js

@@ -0,0 +1,159 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+let governanceModule = null;
+let governanceModulePromise = null;
+
+async function ensureGovernanceModule() {
+  if (governanceModule) {
+    return governanceModule;
+  }
+  if (!governanceModulePromise) {
+    governanceModulePromise = loadGovernanceModule();
+  }
+  governanceModule = await governanceModulePromise;
+  return governanceModule;
+}
+
+async function loadGovernanceModule() {
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
+    throw new Error(
+      `builtin-governance-audit requires ${PM_PACKAGE_ROOT_ENV} to locate core SDK runtime exports.`,
+    );
+  }
+  const modulePath = path.join(path.resolve(envRoot.trim()), "dist", "sdk", "runtime.js");
+  try {
+    const loaded = await import(pathToFileURL(modulePath).href);
+    if (
+      typeof loaded.runDedupeAudit === "function" &&
+      typeof loaded.runCommentsAudit === "function" &&
+      typeof loaded.runNormalize === "function"
+    ) {
+      return loaded;
+    }
+  } catch {
+    // Fall through to deterministic failure message below.
+  }
+  throw new Error(
+    `builtin-governance-audit failed to load governance SDK runtime exports from ${modulePath}.`,
+  );
+}
+
+function readStringOption(options, key, aliases = []) {
+  const keys = [key, ...aliases];
+  for (const candidate of keys) {
+    const value = options[candidate];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+function readBooleanOption(options, key, aliases = []) {
+  const keys = [key, ...aliases];
+  for (const candidate of keys) {
+    const value = options[candidate];
+    if (value === undefined) {
+      continue;
+    }
+    if (typeof value === "boolean") {
+      return value;
+    }
+    if (typeof value === "string") {
+      const normalized = value.trim().toLowerCase();
+      if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on") {
+        return true;
+      }
+      if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "off") {
+        return false;
+      }
+    }
+  }
+  return undefined;
+}
+
+function normalizeDedupeAuditOptions(raw) {
+  return {
+    mode: readStringOption(raw, "mode"),
+    status: readStringOption(raw, "status"),
+    type: readStringOption(raw, "type"),
+    tag: readStringOption(raw, "tag"),
+    priority: readStringOption(raw, "priority"),
+    deadlineBefore: readStringOption(raw, "deadlineBefore", ["deadline_before"]),
+    deadlineAfter: readStringOption(raw, "deadlineAfter", ["deadline_after"]),
+    assignee: readStringOption(raw, "assignee"),
+    assigneeFilter: readStringOption(raw, "assigneeFilter", ["assignee_filter"]),
+    parent: readStringOption(raw, "parent"),
+    sprint: readStringOption(raw, "sprint"),
+    release: readStringOption(raw, "release"),
+    limit: readStringOption(raw, "limit"),
+    threshold: readStringOption(raw, "threshold"),
+  };
+}
+
+function normalizeCommentsAuditOptions(raw) {
+  return {
+    status: readStringOption(raw, "status"),
+    type: readStringOption(raw, "type"),
+    tag: readStringOption(raw, "tag"),
+    priority: readStringOption(raw, "priority"),
+    parent: readStringOption(raw, "parent"),
+    sprint: readStringOption(raw, "sprint"),
+    release: readStringOption(raw, "release"),
+    assignee: readStringOption(raw, "assignee"),
+    assigneeFilter: readStringOption(raw, "assigneeFilter", ["assignee_filter"]),
+    limit: readStringOption(raw, "limit"),
+    limitItems: readStringOption(raw, "limitItems", ["limit_items"]),
+    latest: readStringOption(raw, "latest"),
+    fullHistory: readBooleanOption(raw, "fullHistory", ["full_history"]) === true ? true : undefined,
+  };
+}
+
+function normalizeNormalizeOptions(raw) {
+  return {
+    status: readStringOption(raw, "filterStatus", ["filter_status", "status"]),
+    list: {
+      type: readStringOption(raw, "type"),
+      tag: readStringOption(raw, "tag"),
+      priority: readStringOption(raw, "priority"),
+      deadlineBefore: readStringOption(raw, "deadlineBefore", ["deadline_before"]),
+      deadlineAfter: readStringOption(raw, "deadlineAfter", ["deadline_after"]),
+      assignee: readStringOption(raw, "assignee"),
+      assigneeFilter: readStringOption(raw, "assigneeFilter", ["assignee_filter"]),
+      parent: readStringOption(raw, "parent"),
+      sprint: readStringOption(raw, "sprint"),
+      release: readStringOption(raw, "release"),
+      limit: readStringOption(raw, "limit"),
+      offset: readStringOption(raw, "offset"),
+      includeBody: readBooleanOption(raw, "includeBody", ["include_body"]) === true ? true : undefined,
+      compact: readBooleanOption(raw, "compact") === true ? true : undefined,
+      fields: readStringOption(raw, "fields"),
+      sort: readStringOption(raw, "sort"),
+      order: readStringOption(raw, "order"),
+    },
+    dryRun: readBooleanOption(raw, "dryRun", ["dry_run"]) === true ? true : undefined,
+    apply: readBooleanOption(raw, "apply") === true ? true : undefined,
+    author: readStringOption(raw, "author"),
+    message: readStringOption(raw, "message"),
+    force: readBooleanOption(raw, "force") === true ? true : undefined,
+    allowAuditUpdate: readBooleanOption(raw, "allowAuditUpdate", ["allow_audit_update"]) === true ? true : undefined,
+  };
+}
+
+export async function runDedupeAuditPackage(options, global) {
+  const module = await ensureGovernanceModule();
+  return module.runDedupeAudit(normalizeDedupeAuditOptions(options), global);
+}
+
+export async function runCommentsAuditPackage(options, global) {
+  const module = await ensureGovernanceModule();
+  return module.runCommentsAudit(normalizeCommentsAuditOptions(options), global);
+}
+
+export async function runNormalizePackage(options, global) {
+  const module = await ensureGovernanceModule();
+  return module.runNormalize(normalizeNormalizeOptions(options), global);
+}

package/packages/pm-governance-audit/extensions/governance-audit/runtime.ts

@@ -0,0 +1,176 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { GlobalOptions } from "../../../../src/sdk/runtime.js";
+
+const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+
+interface GovernanceRuntimeSdkModule {
+  runDedupeAudit: (options: Record<string, unknown>, global: GlobalOptions) => Promise<unknown>;
+  runCommentsAudit: (options: Record<string, unknown>, global: GlobalOptions) => Promise<unknown>;
+  runNormalize: (options: Record<string, unknown>, global: GlobalOptions) => Promise<unknown>;
+}
+
+let governanceModule: GovernanceRuntimeSdkModule | null = null;
+let governanceModulePromise: Promise<GovernanceRuntimeSdkModule> | null = null;
+
+async function ensureGovernanceModule(): Promise<GovernanceRuntimeSdkModule> {
+  if (governanceModule) {
+    return governanceModule;
+  }
+  if (!governanceModulePromise) {
+    governanceModulePromise = loadGovernanceModule();
+  }
+  governanceModule = await governanceModulePromise;
+  return governanceModule;
+}
+
+async function loadGovernanceModule(): Promise<GovernanceRuntimeSdkModule> {
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
+    throw new Error(
+      `builtin-governance-audit requires ${PM_PACKAGE_ROOT_ENV} to locate core SDK runtime exports.`,
+    );
+  }
+  const modulePath = path.join(path.resolve(envRoot.trim()), "dist", "sdk", "runtime.js");
+  try {
+    const loaded = (await import(pathToFileURL(modulePath).href)) as Partial<GovernanceRuntimeSdkModule>;
+    if (
+      typeof loaded.runDedupeAudit === "function" &&
+      typeof loaded.runCommentsAudit === "function" &&
+      typeof loaded.runNormalize === "function"
+    ) {
+      return loaded as GovernanceRuntimeSdkModule;
+    }
+  } catch {
+    // Fall through to deterministic failure message below.
+  }
+  throw new Error(
+    `builtin-governance-audit failed to load governance SDK runtime exports from ${modulePath}.`,
+  );
+}
+
+function readStringOption(options: Record<string, unknown>, key: string, aliases: string[] = []): string | undefined {
+  const keys = [key, ...aliases];
+  for (const candidate of keys) {
+    const value = options[candidate];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+function readBooleanOption(options: Record<string, unknown>, key: string, aliases: string[] = []): boolean | undefined {
+  const keys = [key, ...aliases];
+  for (const candidate of keys) {
+    const value = options[candidate];
+    if (value === undefined) {
+      continue;
+    }
+    if (typeof value === "boolean") {
+      return value;
+    }
+    if (typeof value === "string") {
+      const normalized = value.trim().toLowerCase();
+      if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on") {
+        return true;
+      }
+      if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "off") {
+        return false;
+      }
+    }
+  }
+  return undefined;
+}
+
+function normalizeDedupeAuditOptions(raw: Record<string, unknown>): Record<string, unknown> {
+  return {
+    mode: readStringOption(raw, "mode"),
+    status: readStringOption(raw, "status"),
+    type: readStringOption(raw, "type"),
+    tag: readStringOption(raw, "tag"),
+    priority: readStringOption(raw, "priority"),
+    deadlineBefore: readStringOption(raw, "deadlineBefore", ["deadline_before"]),
+    deadlineAfter: readStringOption(raw, "deadlineAfter", ["deadline_after"]),
+    assignee: readStringOption(raw, "assignee"),
+    assigneeFilter: readStringOption(raw, "assigneeFilter", ["assignee_filter"]),
+    parent: readStringOption(raw, "parent"),
+    sprint: readStringOption(raw, "sprint"),
+    release: readStringOption(raw, "release"),
+    limit: readStringOption(raw, "limit"),
+    threshold: readStringOption(raw, "threshold"),
+  };
+}
+
+function normalizeCommentsAuditOptions(raw: Record<string, unknown>): Record<string, unknown> {
+  return {
+    status: readStringOption(raw, "status"),
+    type: readStringOption(raw, "type"),
+    tag: readStringOption(raw, "tag"),
+    priority: readStringOption(raw, "priority"),
+    parent: readStringOption(raw, "parent"),
+    sprint: readStringOption(raw, "sprint"),
+    release: readStringOption(raw, "release"),
+    assignee: readStringOption(raw, "assignee"),
+    assigneeFilter: readStringOption(raw, "assigneeFilter", ["assignee_filter"]),
+    limit: readStringOption(raw, "limit"),
+    limitItems: readStringOption(raw, "limitItems", ["limit_items"]),
+    latest: readStringOption(raw, "latest"),
+    fullHistory: readBooleanOption(raw, "fullHistory", ["full_history"]) === true ? true : undefined,
+  };
+}
+
+function normalizeNormalizeOptions(raw: Record<string, unknown>): Record<string, unknown> {
+  return {
+    status: readStringOption(raw, "filterStatus", ["filter_status", "status"]),
+    list: {
+      type: readStringOption(raw, "type"),
+      tag: readStringOption(raw, "tag"),
+      priority: readStringOption(raw, "priority"),
+      deadlineBefore: readStringOption(raw, "deadlineBefore", ["deadline_before"]),
+      deadlineAfter: readStringOption(raw, "deadlineAfter", ["deadline_after"]),
+      assignee: readStringOption(raw, "assignee"),
+      assigneeFilter: readStringOption(raw, "assigneeFilter", ["assignee_filter"]),
+      parent: readStringOption(raw, "parent"),
+      sprint: readStringOption(raw, "sprint"),
+      release: readStringOption(raw, "release"),
+      limit: readStringOption(raw, "limit"),
+      offset: readStringOption(raw, "offset"),
+      includeBody: readBooleanOption(raw, "includeBody", ["include_body"]) === true ? true : undefined,
+      compact: readBooleanOption(raw, "compact") === true ? true : undefined,
+      fields: readStringOption(raw, "fields"),
+      sort: readStringOption(raw, "sort"),
+      order: readStringOption(raw, "order"),
+    },
+    dryRun: readBooleanOption(raw, "dryRun", ["dry_run"]) === true ? true : undefined,
+    apply: readBooleanOption(raw, "apply") === true ? true : undefined,
+    author: readStringOption(raw, "author"),
+    message: readStringOption(raw, "message"),
+    force: readBooleanOption(raw, "force") === true ? true : undefined,
+    allowAuditUpdate: readBooleanOption(raw, "allowAuditUpdate", ["allow_audit_update"]) === true ? true : undefined,
+  };
+}
+
+export async function runDedupeAuditPackage(
+  options: Record<string, unknown>,
+  global: GlobalOptions,
+): Promise<unknown> {
+  const module = await ensureGovernanceModule();
+  return module.runDedupeAudit(normalizeDedupeAuditOptions(options), global);
+}
+
+export async function runCommentsAuditPackage(
+  options: Record<string, unknown>,
+  global: GlobalOptions,
+): Promise<unknown> {
+  const module = await ensureGovernanceModule();
+  return module.runCommentsAudit(normalizeCommentsAuditOptions(options), global);
+}
+
+export async function runNormalizePackage(
+  options: Record<string, unknown>,
+  global: GlobalOptions,
+): Promise<unknown> {
+  const module = await ensureGovernanceModule();
+  return module.runNormalize(normalizeNormalizeOptions(options), global);
+}

package/packages/pm-governance-audit/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@unbrained/pm-package-governance-audit",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "First-party pm package for governance audit and normalization workflows.",
+  "homepage": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-governance-audit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unbraind/pm-cli.git",
+    "directory": "packages/pm-governance-audit"
+  },
+  "bugs": {
+    "url": "https://github.com/unbraind/pm-cli/issues"
+  },
+  "keywords": [
+    "pm-package",
+    "project-management",
+    "governance",
+    "audit",
+    "normalize"
+  ],
+  "pm": {
+    "aliases": [
+      "governance-audit"
+    ],
+    "extensions": [
+      "extensions/governance-audit"
+    ],
+    "catalog": {
+      "display_name": "Governance Audit",
+      "category": "governance",
+      "summary": "Run dedupe audits, comments audits, and normalize sweeps as package-owned workflows.",
+      "tags": [
+        "governance",
+        "audit",
+        "normalize"
+      ],
+      "links": {
+        "docs": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-governance-audit#readme",
+        "repository": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-governance-audit",
+        "report": "https://github.com/unbraind/pm-cli/issues"
+      }
+    },
+    "docs": [
+      "README.md"
+    ],
+    "examples": [
+      "README.md"
+    ]
+  }
+}

package/packages/pm-guide-shell/README.md

@@ -0,0 +1,23 @@
+# pm-guide-shell
+
+First-party package that restores optional guide and shell-completion UX in bare-core `pm`.
+
+## Commands
+
+- `pm guide [topic]`
+- `pm completion [bash|zsh|fish]`
+- `pm completion-tags`
+
+## Install
+
+```bash
+pm install guide-shell --project
+```
+
+## Verify
+
+```bash
+pm guide --list --json
+pm completion bash
+pm completion-tags
+```

package/packages/pm-guide-shell/extensions/guide-shell/index.js

@@ -0,0 +1,76 @@
+import {
+  renderGuideShellPackageOutput,
+  runCompletionPackage,
+  runCompletionTagsPackage,
+  runGuidePackage,
+} from "./runtime.js";
+
+export const manifest = {
+  name: "builtin-guide-shell",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands", "schema", "services"],
+};
+
+const guideFlags = [
+  { long: "--list", value_type: "boolean", description: "List available guide topics." },
+  { long: "--format", value_name: "value", value_type: "string", description: "Output format override: markdown|toon|json." },
+  { long: "--depth", value_name: "value", value_type: "string", description: "Guide detail depth." },
+  { long: "--topic", value_name: "value", value_type: "string", description: "Explicit guide topic override." },
+];
+
+const completionFlags = [
+  { long: "--shell", value_name: "value", value_type: "string", description: "Completion target shell: bash|zsh|fish." },
+  { long: "--item-types", value_name: "csv", value_type: "string", description: "Filter completion item types." },
+  { long: "--item_types", value_name: "csv", value_type: "string", description: "Alias for --item-types." },
+  { long: "--tags", value_name: "csv", value_type: "string", description: "Filter completion tags." },
+  { long: "--eager-tags", value_type: "boolean", description: "Expand all tag suggestions eagerly." },
+  { long: "--eager_tags", value_type: "boolean", description: "Alias for --eager-tags." },
+];
+
+function guideCommand() {
+  return {
+    name: "guide",
+    action: "guide",
+    description: "Show migration and usage guidance for pm command families.",
+    arguments: [{ name: "topic", required: false, description: "Optional guide topic." }],
+    flags: [...guideFlags],
+    run: async (context) => runGuidePackage(context.args, context.options, context.global),
+  };
+}
+
+function completionCommand() {
+  return {
+    name: "completion",
+    action: "completion",
+    description: "Generate shell completion scripts for bash, zsh, and fish.",
+    arguments: [{ name: "shell", required: false, description: "Target shell (bash|zsh|fish)." }],
+    flags: [...completionFlags],
+    run: async (context) => runCompletionPackage(context.args, context.options, context.global),
+  };
+}
+
+function completionTagsCommand() {
+  return {
+    name: "completion-tags",
+    action: "completion-tags",
+    description: "Print known tags for completion filters.",
+    run: async (context) => runCompletionTagsPackage(context.global),
+  };
+}
+
+export function activate(api) {
+  api.registerCommand(guideCommand());
+  api.registerCommand(completionCommand());
+  api.registerCommand(completionTagsCommand());
+  api.registerService("output_format", (context) => {
+    const rendered = renderGuideShellPackageOutput(context);
+    return rendered ?? context.payload;
+  });
+}
+
+export default {
+  manifest,
+  activate,
+};

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

@@ -0,0 +1,81 @@
+import type {
+  CommandDefinition,
+  ExtensionApi,
+  ServiceOverrideContext,
+} from "../../../../src/sdk/index.js";
+import {
+  renderGuideShellPackageOutput,
+  runCompletionPackage,
+  runCompletionTagsPackage,
+  runGuidePackage,
+} from "./runtime.js";
+
+export const manifest = {
+  name: "builtin-guide-shell",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands", "schema", "services"],
+};
+
+const guideFlags = [
+  { long: "--list", value_type: "boolean", description: "List available guide topics." },
+  { long: "--format", value_name: "value", value_type: "string", description: "Output format override: markdown|toon|json." },
+  { long: "--depth", value_name: "value", value_type: "string", description: "Guide detail depth." },
+  { long: "--topic", value_name: "value", value_type: "string", description: "Explicit guide topic override." },
+] as const;
+
+const completionFlags = [
+  { long: "--shell", value_name: "value", value_type: "string", description: "Completion target shell: bash|zsh|fish." },
+  { long: "--item-types", value_name: "csv", value_type: "string", description: "Filter completion item types." },
+  { long: "--item_types", value_name: "csv", value_type: "string", description: "Alias for --item-types." },
+  { long: "--tags", value_name: "csv", value_type: "string", description: "Filter completion tags." },
+  { long: "--eager-tags", value_type: "boolean", description: "Expand all tag suggestions eagerly." },
+  { long: "--eager_tags", value_type: "boolean", description: "Alias for --eager-tags." },
+] as const;
+
+function guideCommand(): CommandDefinition {
+  return {
+    name: "guide",
+    action: "guide",
+    description: "Show migration and usage guidance for pm command families.",
+    arguments: [{ name: "topic", required: false, description: "Optional guide topic." }],
+    flags: [...guideFlags],
+    run: async (context) => runGuidePackage(context.args, context.options, context.global),
+  };
+}
+
+function completionCommand(): CommandDefinition {
+  return {
+    name: "completion",
+    action: "completion",
+    description: "Generate shell completion scripts for bash, zsh, and fish.",
+    arguments: [{ name: "shell", required: false, description: "Target shell (bash|zsh|fish)." }],
+    flags: [...completionFlags],
+    run: async (context) => runCompletionPackage(context.args, context.options, context.global),
+  };
+}
+
+function completionTagsCommand(): CommandDefinition {
+  return {
+    name: "completion-tags",
+    action: "completion-tags",
+    description: "Print known tags for completion filters.",
+    run: async (context) => runCompletionTagsPackage(context.global),
+  };
+}
+
+export function activate(api: ExtensionApi): void {
+  api.registerCommand(guideCommand());
+  api.registerCommand(completionCommand());
+  api.registerCommand(completionTagsCommand());
+  api.registerService("output_format", (context) => {
+    const rendered = renderGuideShellPackageOutput(context as ServiceOverrideContext);
+    return rendered ?? context.payload;
+  });
+}
+
+export default {
+  manifest,
+  activate,
+};

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

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