@unbrained/pm-cli 2026.5.12 → 2026.5.18

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

@@ -0,0 +1,327 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { GlobalOptions, ServiceOverrideContext } from "../../../../src/sdk/index.js";
+
+const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+
+interface RuntimeSdkModule {
+  runGuide: (options: Record<string, unknown>, global: GlobalOptions) => Promise<unknown>;
+  resolveGuideOutputFormat: (options: Record<string, unknown>, global: GlobalOptions) => "markdown" | "toon" | "json";
+  renderGuideMarkdown: (result: unknown) => string;
+  runCompletion: (
+    shell: string,
+    itemTypes?: string[],
+    tags?: string[],
+    eagerTagExpansion?: boolean,
+    runtime?: {
+      statuses?: string[];
+      command_flags?: Partial<Record<"list" | "create" | "update" | "update-many" | "search" | "calendar" | "context", string[]>>;
+    },
+  ) => {
+    shell: string;
+    script: string;
+    setup_hint: string;
+  };
+  pathExists: (targetPath: string) => Promise<boolean>;
+  getSettingsPath: (pmRoot: string) => string;
+  resolvePmRoot: (cwd: string, overridePath?: string) => string;
+  readSettings: (pmRoot: string) => Promise<Record<string, unknown>>;
+  resolveItemTypeRegistry: (settings: unknown, registrations: unknown) => { definitions: Array<{ name: string; folder: string }> };
+  resolveRuntimeStatusRegistry: (schema: unknown) => { definitions: Array<{ id: string }> };
+  resolveRuntimeFieldRegistry: (schema: unknown) => {
+    command_to_fields: Map<string, Array<{ cli_flag: string }>>;
+  };
+  listAllFrontMatter: (
+    pmRoot: string,
+    itemFormat: "toon" | "json_markdown",
+    typeToFolder: Record<string, string>,
+    status?: unknown,
+    schema?: unknown,
+  ) => Promise<Array<{ metadata: { tags?: string[] } }>>;
+  getActiveExtensionRegistrations: () => unknown;
+}
+
+interface RuntimeBundle {
+  sdk: RuntimeSdkModule;
+}
+
+let runtimeBundle: RuntimeBundle | null = null;
+let runtimeBundlePromise: Promise<RuntimeBundle> | null = null;
+
+async function ensureRuntimeBundle(): Promise<RuntimeBundle> {
+  if (runtimeBundle) {
+    return runtimeBundle;
+  }
+  if (!runtimeBundlePromise) {
+    runtimeBundlePromise = loadRuntimeBundle();
+  }
+  runtimeBundle = await runtimeBundlePromise;
+  return runtimeBundle;
+}
+
+async function loadRuntimeBundle(): Promise<RuntimeBundle> {
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
+    throw new Error(
+      `builtin-guide-shell 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 sdkLoaded = (await import(pathToFileURL(modulePath).href)) as Partial<RuntimeSdkModule>;
+    if (
+      typeof sdkLoaded.runGuide === "function" &&
+      typeof sdkLoaded.resolveGuideOutputFormat === "function" &&
+      typeof sdkLoaded.renderGuideMarkdown === "function" &&
+      typeof sdkLoaded.runCompletion === "function" &&
+      typeof sdkLoaded.pathExists === "function" &&
+      typeof sdkLoaded.getSettingsPath === "function" &&
+      typeof sdkLoaded.resolvePmRoot === "function" &&
+      typeof sdkLoaded.readSettings === "function" &&
+      typeof sdkLoaded.resolveItemTypeRegistry === "function" &&
+      typeof sdkLoaded.resolveRuntimeStatusRegistry === "function" &&
+      typeof sdkLoaded.resolveRuntimeFieldRegistry === "function" &&
+      typeof sdkLoaded.listAllFrontMatter === "function" &&
+      typeof sdkLoaded.getActiveExtensionRegistrations === "function"
+    ) {
+      return {
+        sdk: sdkLoaded as RuntimeSdkModule,
+      };
+    }
+  } catch {
+    // Fall through to deterministic failure message below.
+  }
+  throw new Error(
+    `builtin-guide-shell failed to load guide/completion 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 readCsvListOption(options: Record<string, unknown>, key: string, aliases: string[] = []): string[] {
+  const value = readStringOption(options, key, aliases);
+  if (!value) {
+    return [];
+  }
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+function normalizeGuideOptions(args: string[], options: Record<string, unknown>): Record<string, unknown> {
+  const topicFromArgs = args[0];
+  return {
+    topic: readStringOption(options, "topic") ?? (typeof topicFromArgs === "string" && topicFromArgs.trim().length > 0 ? topicFromArgs : undefined),
+    list: readBooleanOption(options, "list") === true ? true : undefined,
+    format: readStringOption(options, "format"),
+    depth: readStringOption(options, "depth"),
+  };
+}
+
+function normalizeCompletionOptions(args: string[], options: Record<string, unknown>): {
+  shell: string;
+  itemTypes: string[];
+  tags: string[];
+  eagerTags: boolean;
+} {
+  const shellFromOptions = readStringOption(options, "shell");
+  const shellFromArgs = typeof args[0] === "string" && args[0].trim().length > 0 ? args[0].trim() : undefined;
+  return {
+    shell: shellFromOptions ?? shellFromArgs ?? "bash",
+    itemTypes: readCsvListOption(options, "itemTypes", ["item_types"]),
+    tags: readCsvListOption(options, "tags"),
+    eagerTags: readBooleanOption(options, "eagerTags", ["eager_tags"]) === true,
+  };
+}
+
+async function buildCompletionRuntimeConfig(
+  bundle: RuntimeBundle,
+  global: GlobalOptions,
+): Promise<{
+  statuses?: string[];
+  command_flags?: Partial<Record<"list" | "create" | "update" | "update-many" | "search" | "calendar" | "context", string[]>>;
+}> {
+  const pmRoot = bundle.sdk.resolvePmRoot(process.cwd(), global.path);
+  if (!(await bundle.sdk.pathExists(bundle.sdk.getSettingsPath(pmRoot)))) {
+    return {};
+  }
+  const settings = await bundle.sdk.readSettings(pmRoot);
+  const schema = (settings as { schema?: unknown }).schema;
+  const statuses = bundle.sdk.resolveRuntimeStatusRegistry(schema).definitions
+    .map((definition) => definition.id)
+    .filter((status) => typeof status === "string" && status.trim().length > 0)
+    .sort((left, right) => left.localeCompare(right));
+  const fieldRegistry = bundle.sdk.resolveRuntimeFieldRegistry(schema);
+  const runtimeCommands = ["list", "create", "update", "update-many", "search", "calendar", "context"] as const;
+  const commandFlags: Partial<Record<(typeof runtimeCommands)[number], string[]>> = {};
+  for (const command of runtimeCommands) {
+    const definitions = fieldRegistry.command_to_fields.get(command) ?? [];
+    const flags = [
+      ...new Set(
+        definitions
+          .map((definition) => definition.cli_flag)
+          .filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+          .map((value) => `--${value.trim().replaceAll("_", "-")}`),
+      ),
+    ].sort((left, right) => left.localeCompare(right));
+    if (flags.length > 0) {
+      commandFlags[command] = flags;
+    }
+  }
+  return {
+    statuses: statuses.length > 0 ? statuses : undefined,
+    command_flags: Object.keys(commandFlags).length > 0 ? commandFlags : undefined,
+  };
+}
+
+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;
+}
+
+function collectTagsFromItems(items: Array<{ metadata: { tags?: string[] } }>): string[] {
+  const tagSet = new Set<string>();
+  for (const item of items) {
+    const tags = Array.isArray(item.metadata.tags) ? item.metadata.tags : [];
+    for (const tag of tags) {
+      if (typeof tag === "string" && tag.trim().length > 0) {
+        tagSet.add(tag.trim());
+      }
+    }
+  }
+  return [...tagSet].sort((left, right) => left.localeCompare(right));
+}
+
+export async function runGuidePackage(
+  args: string[],
+  options: Record<string, unknown>,
+  global: GlobalOptions,
+): Promise<unknown> {
+  const bundle = await ensureRuntimeBundle();
+  return bundle.sdk.runGuide(normalizeGuideOptions(args, options), global);
+}
+
+export async function runCompletionPackage(
+  args: string[],
+  options: Record<string, unknown>,
+  global: GlobalOptions,
+): Promise<unknown> {
+  const bundle = await ensureRuntimeBundle();
+  const normalized = normalizeCompletionOptions(args, options);
+  const runtimeConfig = await buildCompletionRuntimeConfig(bundle, global);
+  return bundle.sdk.runCompletion(
+    normalized.shell,
+    normalized.itemTypes,
+    normalized.tags,
+    normalized.eagerTags,
+    runtimeConfig,
+  );
+}
+
+export async function runCompletionTagsPackage(global: GlobalOptions): Promise<{ tags: string[]; count: number }> {
+  const bundle = await ensureRuntimeBundle();
+  const pmRoot = bundle.sdk.resolvePmRoot(process.cwd(), global.path);
+  if (!(await bundle.sdk.pathExists(bundle.sdk.getSettingsPath(pmRoot)))) {
+    return { tags: [], count: 0 };
+  }
+  const settings = await bundle.sdk.readSettings(pmRoot);
+  const registrations = bundle.sdk.getActiveExtensionRegistrations();
+  const typeRegistry = bundle.sdk.resolveItemTypeRegistry(settings, registrations);
+  const typeToFolder = Object.fromEntries(
+    typeRegistry.definitions.map((definition) => [definition.name, definition.folder]),
+  );
+  const schema = (settings as { schema?: unknown }).schema;
+  const itemFormat = ((settings as { item_format?: unknown }).item_format === "json_markdown" ? "json_markdown" : "toon") as
+    | "toon"
+    | "json_markdown";
+  const items = await bundle.sdk.listAllFrontMatter(pmRoot, itemFormat, typeToFolder, undefined, schema);
+  const tags = collectTagsFromItems(items);
+  return {
+    tags,
+    count: tags.length,
+  };
+}
+
+export function renderGuideShellPackageOutput(context: ServiceOverrideContext): string | null {
+  if (!runtimeBundle) {
+    return null;
+  }
+  const result = readPayloadResult(context.payload);
+  if (context.command === "guide") {
+    const options = (context.options ?? {}) as Record<string, unknown>;
+    const global = (context.global ?? {}) as GlobalOptions;
+    const outputFormat = runtimeBundle.sdk.resolveGuideOutputFormat(options, global);
+    if (outputFormat === "markdown") {
+      return `${runtimeBundle.sdk.renderGuideMarkdown(result)}\n`;
+    }
+    if (outputFormat === "json" || readPayloadFormat(context.payload) === "json") {
+      return `${JSON.stringify(result, null, 2)}\n`;
+    }
+    return null;
+  }
+  if (context.command === "completion") {
+    if (readPayloadFormat(context.payload) === "json") {
+      return `${JSON.stringify(result, null, 2)}\n`;
+    }
+    if (typeof result === "object" && result !== null && typeof (result as { script?: unknown }).script === "string") {
+      const script = (result as { script: string }).script;
+      return script.endsWith("\n") ? script : `${script}\n`;
+    }
+    return null;
+  }
+  if (context.command === "completion-tags") {
+    if (readPayloadFormat(context.payload) === "json") {
+      return `${JSON.stringify(result, null, 2)}\n`;
+    }
+    const tags = typeof result === "object" && result !== null && Array.isArray((result as { tags?: unknown }).tags)
+      ? ((result as { tags: unknown[] }).tags.filter((entry): entry is string => typeof entry === "string"))
+      : [];
+    return `${tags.join(" ")}\n`;
+  }
+  return null;
+}

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

@@ -0,0 +1,52 @@
+{
+  "name": "@unbrained/pm-guide-shell",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "First-party pm package for guide and shell completion workflows.",
+  "homepage": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-guide-shell#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unbraind/pm-cli.git",
+    "directory": "packages/pm-guide-shell"
+  },
+  "bugs": {
+    "url": "https://github.com/unbraind/pm-cli/issues"
+  },
+  "keywords": [
+    "pm-package",
+    "project-management",
+    "guide",
+    "completion",
+    "shell"
+  ],
+  "pm": {
+    "aliases": [
+      "guide-shell"
+    ],
+    "extensions": [
+      "extensions/guide-shell"
+    ],
+    "catalog": {
+      "display_name": "Guide + Shell UX",
+      "category": "workflow",
+      "summary": "Restore guide documentation and shell completion commands as package-owned UX surfaces.",
+      "tags": [
+        "guide",
+        "completion",
+        "shell"
+      ],
+      "links": {
+        "docs": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-guide-shell#readme",
+        "repository": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-guide-shell",
+        "report": "https://github.com/unbraind/pm-cli/issues"
+      }
+    },
+    "docs": [
+      "README.md"
+    ],
+    "examples": [
+      "README.md"
+    ]
+  }
+}

package/packages/pm-linked-test-adapters/README.md

@@ -0,0 +1,24 @@
+# pm-linked-test-adapters
+
+First-party package that restores optional linked-test background run management surfaces in bare-core `pm`.
+
+## Commands
+
+- `pm test-runs`
+- `pm test-runs list`
+- `pm test-runs status <runId>`
+- `pm test-runs logs <runId>`
+- `pm test-runs stop <runId>`
+- `pm test-runs resume <runId>`
+
+## Install
+
+```bash
+pm install linked-test-adapters --project
+```
+
+## Verify
+
+```bash
+pm test-runs list --json
+```

package/packages/pm-linked-test-adapters/extensions/linked-test-adapters/index.js

@@ -0,0 +1,101 @@
+import {
+  runTestRunsListPackage,
+  runTestRunsLogsPackage,
+  runTestRunsResumePackage,
+  runTestRunsStatusPackage,
+  runTestRunsStopPackage,
+} from "./runtime.js";
+
+export const manifest = {
+  name: "builtin-linked-test-adapters",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands", "schema"],
+};
+
+function testRunsCommand() {
+  return {
+    name: "test-runs",
+    action: "test-runs-list",
+    description: "List background linked-test runs.",
+    flags: [
+      { long: "--status", value_name: "value", value_type: "string", description: "Filter by background run status." },
+      { long: "--limit", value_name: "n", value_type: "string", description: "Limit number of runs returned." },
+    ],
+    run: async (context) => runTestRunsListPackage(context.options, context.global),
+  };
+}
+
+function testRunsListCommand() {
+  return {
+    name: "test-runs list",
+    action: "test-runs-list",
+    description: "List background linked-test runs.",
+    flags: [
+      { long: "--status", value_name: "value", value_type: "string", description: "Filter by background run status." },
+      { long: "--limit", value_name: "n", value_type: "string", description: "Limit number of runs returned." },
+    ],
+    run: async (context) => runTestRunsListPackage(context.options, context.global),
+  };
+}
+
+function testRunsStatusCommand() {
+  return {
+    name: "test-runs status",
+    action: "test-runs-status",
+    description: "Show status and health snapshot for a background linked-test run.",
+    arguments: [{ name: "runId", required: true, description: "Background run id." }],
+    run: async (context) => runTestRunsStatusPackage(context.args, context.global),
+  };
+}
+
+function testRunsLogsCommand() {
+  return {
+    name: "test-runs logs",
+    action: "test-runs-logs",
+    description: "Show tailed logs for a background linked-test run.",
+    arguments: [{ name: "runId", required: true, description: "Background run id." }],
+    flags: [
+      { long: "--stream", value_name: "value", value_type: "string", description: "Log stream selector: stdout|stderr|both." },
+      { long: "--tail", value_name: "n", value_type: "string", description: "Tail number of lines per selected stream." },
+    ],
+    run: async (context) => runTestRunsLogsPackage(context.args, context.options, context.global),
+  };
+}
+
+function testRunsStopCommand() {
+  return {
+    name: "test-runs stop",
+    action: "test-runs-stop",
+    description: "Stop a running background linked-test run.",
+    arguments: [{ name: "runId", required: true, description: "Background run id." }],
+    flags: [{ long: "--force", value_type: "boolean", description: "Force-stop via SIGKILL." }],
+    run: async (context) => runTestRunsStopPackage(context.args, context.options, context.global),
+  };
+}
+
+function testRunsResumeCommand() {
+  return {
+    name: "test-runs resume",
+    action: "test-runs-resume",
+    description: "Resume a terminal background linked-test run by starting a new attempt.",
+    arguments: [{ name: "runId", required: true, description: "Background run id." }],
+    flags: [{ long: "--author", value_name: "value", value_type: "string", description: "Resume author override." }],
+    run: async (context) => runTestRunsResumePackage(context.args, context.options, context.global),
+  };
+}
+
+export function activate(api) {
+  api.registerCommand(testRunsCommand());
+  api.registerCommand(testRunsListCommand());
+  api.registerCommand(testRunsStatusCommand());
+  api.registerCommand(testRunsLogsCommand());
+  api.registerCommand(testRunsStopCommand());
+  api.registerCommand(testRunsResumeCommand());
+}
+
+export default {
+  manifest,
+  activate,
+};

package/packages/pm-linked-test-adapters/extensions/linked-test-adapters/index.ts

@@ -0,0 +1,102 @@
+import type { CommandDefinition, ExtensionApi } from "../../../../src/sdk/index.js";
+import {
+  runTestRunsListPackage,
+  runTestRunsLogsPackage,
+  runTestRunsResumePackage,
+  runTestRunsStatusPackage,
+  runTestRunsStopPackage,
+} from "./runtime.js";
+
+export const manifest = {
+  name: "builtin-linked-test-adapters",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands", "schema"],
+};
+
+function testRunsCommand(): CommandDefinition {
+  return {
+    name: "test-runs",
+    action: "test-runs-list",
+    description: "List background linked-test runs.",
+    flags: [
+      { long: "--status", value_name: "value", value_type: "string", description: "Filter by background run status." },
+      { long: "--limit", value_name: "n", value_type: "string", description: "Limit number of runs returned." },
+    ],
+    run: async (context) => runTestRunsListPackage(context.options, context.global),
+  };
+}
+
+function testRunsListCommand(): CommandDefinition {
+  return {
+    name: "test-runs list",
+    action: "test-runs-list",
+    description: "List background linked-test runs.",
+    flags: [
+      { long: "--status", value_name: "value", value_type: "string", description: "Filter by background run status." },
+      { long: "--limit", value_name: "n", value_type: "string", description: "Limit number of runs returned." },
+    ],
+    run: async (context) => runTestRunsListPackage(context.options, context.global),
+  };
+}
+
+function testRunsStatusCommand(): CommandDefinition {
+  return {
+    name: "test-runs status",
+    action: "test-runs-status",
+    description: "Show status and health snapshot for a background linked-test run.",
+    arguments: [{ name: "runId", required: true, description: "Background run id." }],
+    run: async (context) => runTestRunsStatusPackage(context.args, context.global),
+  };
+}
+
+function testRunsLogsCommand(): CommandDefinition {
+  return {
+    name: "test-runs logs",
+    action: "test-runs-logs",
+    description: "Show tailed logs for a background linked-test run.",
+    arguments: [{ name: "runId", required: true, description: "Background run id." }],
+    flags: [
+      { long: "--stream", value_name: "value", value_type: "string", description: "Log stream selector: stdout|stderr|both." },
+      { long: "--tail", value_name: "n", value_type: "string", description: "Tail number of lines per selected stream." },
+    ],
+    run: async (context) => runTestRunsLogsPackage(context.args, context.options, context.global),
+  };
+}
+
+function testRunsStopCommand(): CommandDefinition {
+  return {
+    name: "test-runs stop",
+    action: "test-runs-stop",
+    description: "Stop a running background linked-test run.",
+    arguments: [{ name: "runId", required: true, description: "Background run id." }],
+    flags: [{ long: "--force", value_type: "boolean", description: "Force-stop via SIGKILL." }],
+    run: async (context) => runTestRunsStopPackage(context.args, context.options, context.global),
+  };
+}
+
+function testRunsResumeCommand(): CommandDefinition {
+  return {
+    name: "test-runs resume",
+    action: "test-runs-resume",
+    description: "Resume a terminal background linked-test run by starting a new attempt.",
+    arguments: [{ name: "runId", required: true, description: "Background run id." }],
+    flags: [{ long: "--author", value_name: "value", value_type: "string", description: "Resume author override." }],
+    run: async (context) => runTestRunsResumePackage(context.args, context.options, context.global),
+  };
+}
+
+export function activate(api: ExtensionApi): void {
+  api.registerCommand(testRunsCommand());
+  api.registerCommand(testRunsListCommand());
+  api.registerCommand(testRunsStatusCommand());
+  api.registerCommand(testRunsLogsCommand());
+  api.registerCommand(testRunsStopCommand());
+  api.registerCommand(testRunsResumeCommand());
+}
+
+export default {
+  manifest,
+  activate,
+};

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

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