@unbrained/pm-cli 2026.5.11 → 2026.5.14

package/packages/pm-calendar/extensions/calendar/runtime.js

@@ -0,0 +1,95 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+let calendarCore = null;
+let calendarCoreLoadPromise = null;
+
+async function ensureCalendarCoreModule() {
+  if (calendarCore) {
+    return calendarCore;
+  }
+  if (!calendarCoreLoadPromise) {
+    calendarCoreLoadPromise = loadCalendarCoreModule();
+  }
+  calendarCore = await calendarCoreLoadPromise;
+  return calendarCore;
+}
+
+async function loadCalendarCoreModule() {
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
+    throw new Error(
+      `builtin-calendar 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.runCalendar === "function" &&
+      typeof loaded.renderCalendarMarkdown === "function" &&
+      typeof loaded.resolveCalendarOutputFormat === "function"
+    ) {
+      return loaded;
+    }
+  } catch {
+    // Fall through to deterministic failure message below.
+  }
+  throw new Error(
+    `builtin-calendar failed to load calendar SDK runtime exports from ${modulePath}.`,
+  );
+}
+
+function isCalendarResult(value) {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    value.output_default === "markdown" &&
+    Array.isArray(value.events) &&
+    Array.isArray(value.days)
+  );
+}
+
+function isCalendarCommand(command) {
+  return command === "calendar" || command === "cal";
+}
+
+function readPayloadFormat(payload) {
+  if (typeof payload === "object" && payload !== null) {
+    const format = payload.format;
+    if (format === "json") {
+      return "json";
+    }
+  }
+  return "toon";
+}
+
+function readPayloadResult(payload) {
+  if (typeof payload === "object" && payload !== null && "result" in payload) {
+    return payload.result;
+  }
+  return payload;
+}
+
+export async function runCalendarPackage(options, global) {
+  const loaded = await ensureCalendarCoreModule();
+  return loaded.runCalendar(options, global);
+}
+
+export function renderCalendarPackageOutput(context) {
+  const result = readPayloadResult(context.payload);
+  if (!calendarCore || !isCalendarCommand(context.command) || !isCalendarResult(result)) {
+    return null;
+  }
+  const options = context.options ?? {};
+  const global = context.global ?? {};
+  const outputFormat = calendarCore.resolveCalendarOutputFormat(options, global);
+  if (outputFormat === "markdown") {
+    return `${calendarCore.renderCalendarMarkdown(result)}\n`;
+  }
+  if (outputFormat === "json" || readPayloadFormat(context.payload) === "json") {
+    return `${JSON.stringify(result, null, 2)}\n`;
+  }
+  return null;
+}

package/packages/pm-calendar/extensions/calendar/runtime.ts

@@ -0,0 +1,104 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { CalendarOptions, CalendarResult } from "../../../../src/sdk/runtime.js";
+import type { GlobalOptions, ServiceOverrideContext } from "../../../../src/sdk/index.js";
+
+const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+
+interface CalendarCoreModule {
+  runCalendar: (options: CalendarOptions, global: GlobalOptions) => Promise<CalendarResult>;
+  renderCalendarMarkdown: (result: CalendarResult) => string;
+  resolveCalendarOutputFormat: (options: CalendarOptions, global: GlobalOptions) => "markdown" | "toon" | "json";
+}
+
+let calendarCore: CalendarCoreModule | null = null;
+let calendarCoreLoadPromise: Promise<CalendarCoreModule> | null = null;
+
+async function ensureCalendarCoreModule(): Promise<CalendarCoreModule> {
+  if (calendarCore) {
+    return calendarCore;
+  }
+  if (!calendarCoreLoadPromise) {
+    calendarCoreLoadPromise = loadCalendarCoreModule();
+  }
+  calendarCore = await calendarCoreLoadPromise;
+  return calendarCore;
+}
+
+async function loadCalendarCoreModule(): Promise<CalendarCoreModule> {
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
+    throw new Error(
+      `builtin-calendar 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<CalendarCoreModule>;
+    if (
+      typeof loaded.runCalendar === "function" &&
+      typeof loaded.renderCalendarMarkdown === "function" &&
+      typeof loaded.resolveCalendarOutputFormat === "function"
+    ) {
+      return loaded as CalendarCoreModule;
+    }
+  } catch {
+    // Fall through to deterministic failure message below.
+  }
+  throw new Error(
+    `builtin-calendar failed to load calendar SDK runtime exports from ${modulePath}.`,
+  );
+}
+
+function isCalendarResult(value: unknown): value is CalendarResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { output_default?: unknown }).output_default === "markdown" &&
+    Array.isArray((value as { events?: unknown }).events) &&
+    Array.isArray((value as { days?: unknown }).days)
+  );
+}
+
+function isCalendarCommand(command: unknown): boolean {
+  return command === "calendar" || command === "cal";
+}
+
+function readPayloadFormat(payload: unknown): "toon" | "json" {
+  if (typeof payload === "object" && payload !== null) {
+    const format = (payload as { format?: unknown }).format;
+    if (format === "json") {
+      return "json";
+    }
+  }
+  return "toon";
+}
+
+function readPayloadResult(payload: unknown): unknown {
+  if (typeof payload === "object" && payload !== null && "result" in payload) {
+    return (payload as { result?: unknown }).result;
+  }
+  return payload;
+}
+
+export async function runCalendarPackage(options: CalendarOptions, global: GlobalOptions): Promise<CalendarResult> {
+  const loaded = await ensureCalendarCoreModule();
+  return loaded.runCalendar(options, global);
+}
+
+export function renderCalendarPackageOutput(context: ServiceOverrideContext): string | null {
+  const result = readPayloadResult(context.payload);
+  if (!calendarCore || !isCalendarCommand(context.command) || !isCalendarResult(result)) {
+    return null;
+  }
+  const options = (context.options ?? {}) as CalendarOptions;
+  const global = (context.global ?? {}) as GlobalOptions;
+  const outputFormat = calendarCore.resolveCalendarOutputFormat(options, global);
+  if (outputFormat === "markdown") {
+    return `${calendarCore.renderCalendarMarkdown(result)}\n`;
+  }
+  if (outputFormat === "json" || readPayloadFormat(context.payload) === "json") {
+    return `${JSON.stringify(result, null, 2)}\n`;
+  }
+  return null;
+}

package/packages/pm-calendar/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@unbrained/pm-package-calendar",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "First-party pm package for calendar and agenda views.",
+  "homepage": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-calendar#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unbraind/pm-cli.git",
+    "directory": "packages/pm-calendar"
+  },
+  "bugs": {
+    "url": "https://github.com/unbraind/pm-cli/issues"
+  },
+  "keywords": [
+    "pm-package",
+    "project-management",
+    "calendar",
+    "agenda"
+  ],
+  "pm": {
+    "aliases": [
+      "calendar"
+    ],
+    "extensions": [
+      "extensions/calendar"
+    ],
+    "catalog": {
+      "display_name": "Calendar Views",
+      "category": "workflow",
+      "summary": "Show agenda, day, week, and month views for deadlines, reminders, and scheduled events.",
+      "tags": [
+        "calendar",
+        "agenda",
+        "workflow"
+      ],
+      "links": {
+        "docs": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-calendar#readme",
+        "repository": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-calendar",
+        "report": "https://github.com/unbraind/pm-cli/issues"
+      }
+    },
+    "docs": [
+      "README.md"
+    ],
+    "examples": [
+      "README.md"
+    ]
+  }
+}

package/packages/pm-governance-audit/README.md

@@ -0,0 +1,23 @@
+# pm-governance-audit
+
+First-party package that restores optional governance audit surfaces in bare-core `pm`.
+
+## Commands
+
+- `pm dedupe-audit`
+- `pm comments-audit`
+- `pm normalize`
+
+## Install
+
+```bash
+pm install governance-audit --project
+```
+
+## Verify
+
+```bash
+pm dedupe-audit --mode parent_scope --limit 20 --json
+pm comments-audit --latest 3 --limit-items 20 --json
+pm normalize --dry-run --json
+```

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

@@ -0,0 +1,117 @@
+import {
+  runCommentsAuditPackage,
+  runDedupeAuditPackage,
+  runNormalizePackage,
+} from "./runtime.js";
+
+export const manifest = {
+  name: "builtin-governance-audit",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands", "schema"],
+};
+
+const dedupeAuditFlags = [
+  { long: "--mode", value_name: "value", value_type: "string", description: "Audit mode: title_exact|title_fuzzy|parent_scope." },
+  { long: "--status", value_name: "value", value_type: "string", description: "Filter by status." },
+  { long: "--type", value_name: "value", value_type: "string", description: "Filter by item type." },
+  { long: "--tag", value_name: "value", value_type: "string", description: "Filter by tag." },
+  { long: "--priority", value_name: "value", value_type: "string", description: "Filter by priority." },
+  { long: "--deadline-before", value_name: "value", value_type: "string", description: "Filter by deadline upper bound." },
+  { long: "--deadline-after", value_name: "value", value_type: "string", description: "Filter by deadline lower bound." },
+  { long: "--assignee", value_name: "value", value_type: "string", description: "Filter by assignee." },
+  { long: "--assignee-filter", value_name: "value", value_type: "string", description: "Filter assignee presence." },
+  { long: "--parent", value_name: "value", value_type: "string", description: "Filter by parent item ID." },
+  { long: "--sprint", value_name: "value", value_type: "string", description: "Filter by sprint." },
+  { long: "--release", value_name: "value", value_type: "string", description: "Filter by release." },
+  { long: "--limit", value_name: "n", value_type: "string", description: "Limit analyzed items." },
+  { long: "--threshold", value_name: "value", value_type: "string", description: "Similarity threshold for fuzzy modes." },
+];
+
+const commentsAuditFlags = [
+  { long: "--status", value_name: "value", value_type: "string", description: "Filter by status." },
+  { long: "--type", value_name: "value", value_type: "string", description: "Filter by item type." },
+  { long: "--tag", value_name: "value", value_type: "string", description: "Filter by tag." },
+  { long: "--priority", value_name: "value", value_type: "string", description: "Filter by priority." },
+  { long: "--parent", value_name: "value", value_type: "string", description: "Filter by parent item ID." },
+  { long: "--sprint", value_name: "value", value_type: "string", description: "Filter by sprint." },
+  { long: "--release", value_name: "value", value_type: "string", description: "Filter by release." },
+  { long: "--assignee", value_name: "value", value_type: "string", description: "Filter by assignee." },
+  { long: "--assignee-filter", value_name: "value", value_type: "string", description: "Filter assignee presence." },
+  { long: "--limit", value_name: "n", value_type: "string", description: "Limit output rows." },
+  { long: "--limit-items", value_name: "n", value_type: "string", description: "Limit scanned items before comment expansion." },
+  { long: "--latest", value_name: "n", value_type: "string", description: "Include latest n comments per item." },
+  { long: "--full-history", value_type: "boolean", description: "Emit full comment history rows." },
+];
+
+const normalizeFlags = [
+  { long: "--filter-status", value_name: "value", value_type: "string", description: "Status filter applied before normalize planning." },
+  { long: "--filter_status", value_name: "value", value_type: "string", description: "Alias for --filter-status." },
+  { long: "--type", value_name: "value", value_type: "string", description: "Filter by item type." },
+  { long: "--tag", value_name: "value", value_type: "string", description: "Filter by tag." },
+  { long: "--priority", value_name: "value", value_type: "string", description: "Filter by priority." },
+  { long: "--deadline-before", value_name: "value", value_type: "string", description: "Filter by deadline upper bound." },
+  { long: "--deadline-after", value_name: "value", value_type: "string", description: "Filter by deadline lower bound." },
+  { long: "--assignee", value_name: "value", value_type: "string", description: "Filter by assignee." },
+  { long: "--assignee-filter", value_name: "value", value_type: "string", description: "Filter assignee presence." },
+  { long: "--parent", value_name: "value", value_type: "string", description: "Filter by parent item ID." },
+  { long: "--sprint", value_name: "value", value_type: "string", description: "Filter by sprint." },
+  { long: "--release", value_name: "value", value_type: "string", description: "Filter by release." },
+  { long: "--limit", value_name: "n", value_type: "string", description: "Limit listed items." },
+  { long: "--offset", value_name: "n", value_type: "string", description: "Skip first n listed items." },
+  { long: "--include-body", value_type: "boolean", description: "Include body while listing candidate items." },
+  { long: "--include_body", value_type: "boolean", description: "Alias for --include-body." },
+  { long: "--compact", value_type: "boolean", description: "Request compact list projection." },
+  { long: "--fields", value_name: "value", value_type: "string", description: "Comma-separated list projection fields." },
+  { long: "--sort", value_name: "value", value_type: "string", description: "Sort field." },
+  { long: "--order", value_name: "value", value_type: "string", description: "Sort order." },
+  { long: "--dry-run", value_type: "boolean", description: "Preview normalize mutations without applying." },
+  { long: "--apply", value_type: "boolean", description: "Apply normalize mutations." },
+  { long: "--author", value_name: "value", value_type: "string", description: "Author used for apply-mode updates." },
+  { long: "--message", value_name: "value", value_type: "string", description: "History message used for apply-mode updates." },
+  { long: "--force", value_type: "boolean", description: "Force apply-mode updates." },
+  { long: "--allow-audit-update", value_type: "boolean", description: "Allow append-only audit updates across owners." },
+  { long: "--allow_audit_update", value_type: "boolean", description: "Alias for --allow-audit-update." },
+];
+
+function dedupeAuditCommand() {
+  return {
+    name: "dedupe-audit",
+    action: "dedupe-audit",
+    description: "Audit likely duplicate items by title and parent scope heuristics.",
+    flags: [...dedupeAuditFlags],
+    run: async (context) => runDedupeAuditPackage(context.options, context.global),
+  };
+}
+
+function commentsAuditCommand() {
+  return {
+    name: "comments-audit",
+    action: "comments-audit",
+    description: "Audit item comment coverage and export comment history rows.",
+    flags: [...commentsAuditFlags],
+    run: async (context) => runCommentsAuditPackage(context.options, context.global),
+  };
+}
+
+function normalizeCommand() {
+  return {
+    name: "normalize",
+    action: "normalize",
+    description: "Plan/apply lifecycle metadata normalization sweeps.",
+    flags: [...normalizeFlags],
+    run: async (context) => runNormalizePackage(context.options, context.global),
+  };
+}
+
+export function activate(api) {
+  api.registerCommand(dedupeAuditCommand());
+  api.registerCommand(commentsAuditCommand());
+  api.registerCommand(normalizeCommand());
+}
+
+export default {
+  manifest,
+  activate,
+};

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

@@ -0,0 +1,118 @@
+import type { CommandDefinition, ExtensionApi } from "../../../../src/sdk/index.js";
+import {
+  runCommentsAuditPackage,
+  runDedupeAuditPackage,
+  runNormalizePackage,
+} from "./runtime.js";
+
+export const manifest = {
+  name: "builtin-governance-audit",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands", "schema"],
+};
+
+const dedupeAuditFlags = [
+  { long: "--mode", value_name: "value", value_type: "string", description: "Audit mode: title_exact|title_fuzzy|parent_scope." },
+  { long: "--status", value_name: "value", value_type: "string", description: "Filter by status." },
+  { long: "--type", value_name: "value", value_type: "string", description: "Filter by item type." },
+  { long: "--tag", value_name: "value", value_type: "string", description: "Filter by tag." },
+  { long: "--priority", value_name: "value", value_type: "string", description: "Filter by priority." },
+  { long: "--deadline-before", value_name: "value", value_type: "string", description: "Filter by deadline upper bound." },
+  { long: "--deadline-after", value_name: "value", value_type: "string", description: "Filter by deadline lower bound." },
+  { long: "--assignee", value_name: "value", value_type: "string", description: "Filter by assignee." },
+  { long: "--assignee-filter", value_name: "value", value_type: "string", description: "Filter assignee presence." },
+  { long: "--parent", value_name: "value", value_type: "string", description: "Filter by parent item ID." },
+  { long: "--sprint", value_name: "value", value_type: "string", description: "Filter by sprint." },
+  { long: "--release", value_name: "value", value_type: "string", description: "Filter by release." },
+  { long: "--limit", value_name: "n", value_type: "string", description: "Limit analyzed items." },
+  { long: "--threshold", value_name: "value", value_type: "string", description: "Similarity threshold for fuzzy modes." },
+] as const;
+
+const commentsAuditFlags = [
+  { long: "--status", value_name: "value", value_type: "string", description: "Filter by status." },
+  { long: "--type", value_name: "value", value_type: "string", description: "Filter by item type." },
+  { long: "--tag", value_name: "value", value_type: "string", description: "Filter by tag." },
+  { long: "--priority", value_name: "value", value_type: "string", description: "Filter by priority." },
+  { long: "--parent", value_name: "value", value_type: "string", description: "Filter by parent item ID." },
+  { long: "--sprint", value_name: "value", value_type: "string", description: "Filter by sprint." },
+  { long: "--release", value_name: "value", value_type: "string", description: "Filter by release." },
+  { long: "--assignee", value_name: "value", value_type: "string", description: "Filter by assignee." },
+  { long: "--assignee-filter", value_name: "value", value_type: "string", description: "Filter assignee presence." },
+  { long: "--limit", value_name: "n", value_type: "string", description: "Limit output rows." },
+  { long: "--limit-items", value_name: "n", value_type: "string", description: "Limit scanned items before comment expansion." },
+  { long: "--latest", value_name: "n", value_type: "string", description: "Include latest n comments per item." },
+  { long: "--full-history", value_type: "boolean", description: "Emit full comment history rows." },
+] as const;
+
+const normalizeFlags = [
+  { long: "--filter-status", value_name: "value", value_type: "string", description: "Status filter applied before normalize planning." },
+  { long: "--filter_status", value_name: "value", value_type: "string", description: "Alias for --filter-status." },
+  { long: "--type", value_name: "value", value_type: "string", description: "Filter by item type." },
+  { long: "--tag", value_name: "value", value_type: "string", description: "Filter by tag." },
+  { long: "--priority", value_name: "value", value_type: "string", description: "Filter by priority." },
+  { long: "--deadline-before", value_name: "value", value_type: "string", description: "Filter by deadline upper bound." },
+  { long: "--deadline-after", value_name: "value", value_type: "string", description: "Filter by deadline lower bound." },
+  { long: "--assignee", value_name: "value", value_type: "string", description: "Filter by assignee." },
+  { long: "--assignee-filter", value_name: "value", value_type: "string", description: "Filter assignee presence." },
+  { long: "--parent", value_name: "value", value_type: "string", description: "Filter by parent item ID." },
+  { long: "--sprint", value_name: "value", value_type: "string", description: "Filter by sprint." },
+  { long: "--release", value_name: "value", value_type: "string", description: "Filter by release." },
+  { long: "--limit", value_name: "n", value_type: "string", description: "Limit listed items." },
+  { long: "--offset", value_name: "n", value_type: "string", description: "Skip first n listed items." },
+  { long: "--include-body", value_type: "boolean", description: "Include body while listing candidate items." },
+  { long: "--include_body", value_type: "boolean", description: "Alias for --include-body." },
+  { long: "--compact", value_type: "boolean", description: "Request compact list projection." },
+  { long: "--fields", value_name: "value", value_type: "string", description: "Comma-separated list projection fields." },
+  { long: "--sort", value_name: "value", value_type: "string", description: "Sort field." },
+  { long: "--order", value_name: "value", value_type: "string", description: "Sort order." },
+  { long: "--dry-run", value_type: "boolean", description: "Preview normalize mutations without applying." },
+  { long: "--apply", value_type: "boolean", description: "Apply normalize mutations." },
+  { long: "--author", value_name: "value", value_type: "string", description: "Author used for apply-mode updates." },
+  { long: "--message", value_name: "value", value_type: "string", description: "History message used for apply-mode updates." },
+  { long: "--force", value_type: "boolean", description: "Force apply-mode updates." },
+  { long: "--allow-audit-update", value_type: "boolean", description: "Allow append-only audit updates across owners." },
+  { long: "--allow_audit_update", value_type: "boolean", description: "Alias for --allow-audit-update." },
+] as const;
+
+function dedupeAuditCommand(): CommandDefinition {
+  return {
+    name: "dedupe-audit",
+    action: "dedupe-audit",
+    description: "Audit likely duplicate items by title and parent scope heuristics.",
+    flags: [...dedupeAuditFlags],
+    run: async (context) => runDedupeAuditPackage(context.options, context.global),
+  };
+}
+
+function commentsAuditCommand(): CommandDefinition {
+  return {
+    name: "comments-audit",
+    action: "comments-audit",
+    description: "Audit item comment coverage and export comment history rows.",
+    flags: [...commentsAuditFlags],
+    run: async (context) => runCommentsAuditPackage(context.options, context.global),
+  };
+}
+
+function normalizeCommand(): CommandDefinition {
+  return {
+    name: "normalize",
+    action: "normalize",
+    description: "Plan/apply lifecycle metadata normalization sweeps.",
+    flags: [...normalizeFlags],
+    run: async (context) => runNormalizePackage(context.options, context.global),
+  };
+}
+
+export function activate(api: ExtensionApi): void {
+  api.registerCommand(dedupeAuditCommand());
+  api.registerCommand(commentsAuditCommand());
+  api.registerCommand(normalizeCommand());
+}
+
+export default {
+  manifest,
+  activate,
+};

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

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