@unbrained/pm-cli 2026.5.31 → 2026.6.5

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

@@ -7,6 +7,8 @@ First-party package that restores optional guide and shell-completion UX in bare
 - `pm guide [topic]`
 - `pm completion [bash|zsh|fish]`
 - `pm completion-tags`
+- `pm completion-statuses`
+- `pm completion-types`
 
 ## Install
 
@@ -20,4 +22,6 @@ pm install guide-shell --project
 pm guide --list --json
 pm completion bash
 pm completion-tags
+pm completion-statuses
+pm completion-types
 ```

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

@@ -1,7 +1,9 @@
 import {
   renderGuideShellPackageOutput,
   runCompletionPackage,
+  runCompletionStatusesPackage,
   runCompletionTagsPackage,
+  runCompletionTypesPackage,
   runGuidePackage,
 } from "./runtime.js";
 
@@ -60,10 +62,30 @@ function completionTagsCommand() {
   };
 }
 
+function completionStatusesCommand() {
+  return {
+    name: "completion-statuses",
+    action: "completion-statuses",
+    description: "Print runtime status IDs for completion filters.",
+    run: async (context) => runCompletionStatusesPackage(context.global),
+  };
+}
+
+function completionTypesCommand() {
+  return {
+    name: "completion-types",
+    action: "completion-types",
+    description: "Print runtime item type IDs for completion filters.",
+    run: async (context) => runCompletionTypesPackage(context.global),
+  };
+}
+
 export function activate(api) {
   api.registerCommand(guideCommand());
   api.registerCommand(completionCommand());
   api.registerCommand(completionTagsCommand());
+  api.registerCommand(completionStatusesCommand());
+  api.registerCommand(completionTypesCommand());
   api.registerService("output_format", (context) => {
     const rendered = renderGuideShellPackageOutput(context);
     return rendered ?? null;

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

@@ -6,7 +6,9 @@ import type {
 import {
   renderGuideShellPackageOutput,
   runCompletionPackage,
+  runCompletionStatusesPackage,
   runCompletionTagsPackage,
+  runCompletionTypesPackage,
   runGuidePackage,
 } from "./runtime.js";
 
@@ -65,10 +67,30 @@ function completionTagsCommand(): CommandDefinition {
   };
 }
 
+function completionStatusesCommand(): CommandDefinition {
+  return {
+    name: "completion-statuses",
+    action: "completion-statuses",
+    description: "Print runtime status IDs for completion filters.",
+    run: async (context) => runCompletionStatusesPackage(context.global),
+  };
+}
+
+function completionTypesCommand(): CommandDefinition {
+  return {
+    name: "completion-types",
+    action: "completion-types",
+    description: "Print runtime item type IDs for completion filters.",
+    run: async (context) => runCompletionTypesPackage(context.global),
+  };
+}
+
 export function activate(api: ExtensionApi): void {
   api.registerCommand(guideCommand());
   api.registerCommand(completionCommand());
   api.registerCommand(completionTagsCommand());
+  api.registerCommand(completionStatusesCommand());
+  api.registerCommand(completionTypesCommand());
   api.registerService("output_format", (context) => {
     const rendered = renderGuideShellPackageOutput(context as ServiceOverrideContext);
     return rendered ?? null;

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

@@ -3,5 +3,10 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
-  "capabilities": ["commands", "schema", "services"]
+  "capabilities": ["commands", "schema", "services"],
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0",
+  "activation": {
+    "commands": ["completion", "completion-statuses", "completion-tags", "completion-types", "guide"]
+  }
 }

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

@@ -79,12 +79,38 @@ function normalizeCompletionOptions(bundle, args, options) {
   };
 }
 
+function collectTypeNames(typeRegistry) {
+  const candidates = Array.isArray(typeRegistry.types)
+    ? typeRegistry.types
+    : Array.isArray(typeRegistry.definitions)
+      ? typeRegistry.definitions
+          .filter((definition) => Boolean(definition))
+          .map((definition) => definition.name)
+      : [];
+  return [...new Set(candidates.filter((value) => typeof value === "string" && value.trim().length > 0))]
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function collectTypeToFolder(typeRegistry) {
+  if (typeof typeRegistry.type_to_folder === "object" && typeRegistry.type_to_folder !== null) {
+    return typeRegistry.type_to_folder;
+  }
+  return Object.fromEntries(
+    (typeRegistry.definitions ?? [])
+      .filter((definition) => Boolean(definition?.name && definition?.folder))
+      .map((definition) => [definition.name, definition.folder]),
+  );
+}
+
 async function buildCompletionRuntimeConfig(bundle, global) {
   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 registrations = bundle.sdk.getActiveExtensionRegistrations();
+  const typeRegistry = bundle.sdk.resolveItemTypeRegistry(settings, registrations);
+  const itemTypes = collectTypeNames(typeRegistry);
   const schema = settings.schema;
   const statuses = bundle.sdk.resolveRuntimeStatusRegistry(schema).definitions
     .map((definition) => definition.id)
@@ -108,6 +134,7 @@ async function buildCompletionRuntimeConfig(bundle, global) {
     }
   }
   return {
+    item_types: itemTypes.length > 0 ? itemTypes : undefined,
     statuses: statuses.length > 0 ? statuses : undefined,
     command_flags: Object.keys(commandFlags).length > 0 ? commandFlags : undefined,
   };
@@ -170,9 +197,7 @@ export async function runCompletionTagsPackage(global) {
   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 typeToFolder = collectTypeToFolder(typeRegistry);
   const schema = settings.schema;
   const itemFormat = settings.item_format === "json_markdown" ? "json_markdown" : "toon";
   const items = await bundle.sdk.listAllFrontMatter(pmRoot, itemFormat, typeToFolder, undefined, schema);
@@ -183,6 +208,34 @@ export async function runCompletionTagsPackage(global) {
   };
 }
 
+export async function runCompletionStatusesPackage(global) {
+  const bundle = await ensureRuntimeBundle();
+  const pmRoot = bundle.sdk.resolvePmRoot(process.cwd(), global.path);
+  const settings = await bundle.sdk.readSettings(pmRoot);
+  const schema = settings.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));
+  return {
+    statuses,
+    count: statuses.length,
+  };
+}
+
+export async function runCompletionTypesPackage(global) {
+  const bundle = await ensureRuntimeBundle();
+  const pmRoot = bundle.sdk.resolvePmRoot(process.cwd(), global.path);
+  const settings = await bundle.sdk.readSettings(pmRoot);
+  const registrations = bundle.sdk.getActiveExtensionRegistrations();
+  const typeRegistry = bundle.sdk.resolveItemTypeRegistry(settings, registrations);
+  const types = collectTypeNames(typeRegistry);
+  return {
+    types,
+    count: types.length,
+  };
+}
+
 export function renderGuideShellPackageOutput(context) {
   if (!runtimeBundle) {
     return null;
@@ -219,5 +272,23 @@ export function renderGuideShellPackageOutput(context) {
       : [];
     return `${tags.join(" ")}\n`;
   }
+  if (context.command === "completion-statuses") {
+    if (readPayloadFormat(context.payload) === "json") {
+      return `${JSON.stringify(result, null, 2)}\n`;
+    }
+    const statuses = typeof result === "object" && result !== null && Array.isArray(result.statuses)
+      ? result.statuses.filter((entry) => typeof entry === "string")
+      : [];
+    return `${statuses.join(" ")}\n`;
+  }
+  if (context.command === "completion-types") {
+    if (readPayloadFormat(context.payload) === "json") {
+      return `${JSON.stringify(result, null, 2)}\n`;
+    }
+    const types = typeof result === "object" && result !== null && Array.isArray(result.types)
+      ? result.types.filter((entry) => typeof entry === "string")
+      : [];
+    return `${types.join(" ")}\n`;
+  }
   return null;
 }

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

@@ -14,6 +14,7 @@ interface RuntimeSdkModule {
     tags?: string[],
     eagerTagExpansion?: boolean,
     runtime?: {
+      item_types?: string[];
       statuses?: string[];
       command_flags?: Partial<Record<"list" | "create" | "update" | "update-many" | "search" | "calendar" | "context", string[]>>;
     },
@@ -26,7 +27,14 @@ interface RuntimeSdkModule {
   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 }> };
+  resolveItemTypeRegistry: (
+    settings: unknown,
+    registrations: unknown,
+  ) => {
+    types?: string[];
+    definitions?: Array<{ name: string; folder: string }>;
+    type_to_folder?: Record<string, string>;
+  };
   resolveRuntimeStatusRegistry: (schema: unknown) => { definitions: Array<{ id: string }> };
   resolveRuntimeFieldRegistry: (schema: unknown) => {
     command_to_fields: Map<string, Array<{ cli_flag: string }>>;
@@ -134,10 +142,34 @@ function normalizeCompletionOptions(bundle: RuntimeBundle, args: string[], optio
   };
 }
 
+function collectTypeNames(typeRegistry: ReturnType<RuntimeSdkModule["resolveItemTypeRegistry"]>): string[] {
+  const candidates = Array.isArray(typeRegistry.types)
+    ? typeRegistry.types
+    : Array.isArray(typeRegistry.definitions)
+      ? typeRegistry.definitions
+          .filter((definition) => Boolean(definition))
+          .map((definition) => definition.name)
+      : [];
+  return [...new Set(candidates.filter((value): value is string => typeof value === "string" && value.trim().length > 0))]
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function collectTypeToFolder(typeRegistry: ReturnType<RuntimeSdkModule["resolveItemTypeRegistry"]>): Record<string, string> {
+  if (typeof typeRegistry.type_to_folder === "object" && typeRegistry.type_to_folder !== null) {
+    return typeRegistry.type_to_folder;
+  }
+  return Object.fromEntries(
+    (typeRegistry.definitions ?? [])
+      .filter((definition) => Boolean(definition?.name && definition?.folder))
+      .map((definition) => [definition.name, definition.folder]),
+  );
+}
+
 async function buildCompletionRuntimeConfig(
   bundle: RuntimeBundle,
   global: GlobalOptions,
 ): Promise<{
+  item_types?: string[];
   statuses?: string[];
   command_flags?: Partial<Record<"list" | "create" | "update" | "update-many" | "search" | "calendar" | "context", string[]>>;
 }> {
@@ -146,6 +178,9 @@ async function buildCompletionRuntimeConfig(
     return {};
   }
   const settings = await bundle.sdk.readSettings(pmRoot);
+  const registrations = bundle.sdk.getActiveExtensionRegistrations();
+  const typeRegistry = bundle.sdk.resolveItemTypeRegistry(settings, registrations);
+  const itemTypes = collectTypeNames(typeRegistry);
   const schema = (settings as { schema?: unknown }).schema;
   const statuses = bundle.sdk.resolveRuntimeStatusRegistry(schema).definitions
     .map((definition) => definition.id)
@@ -169,6 +204,7 @@ async function buildCompletionRuntimeConfig(
     }
   }
   return {
+    item_types: itemTypes.length > 0 ? itemTypes : undefined,
     statuses: statuses.length > 0 ? statuses : undefined,
     command_flags: Object.keys(commandFlags).length > 0 ? commandFlags : undefined,
   };
@@ -239,9 +275,7 @@ export async function runCompletionTagsPackage(global: GlobalOptions): Promise<{
   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 typeToFolder = collectTypeToFolder(typeRegistry);
   const schema = (settings as { schema?: unknown }).schema;
   const itemFormat = ((settings as { item_format?: unknown }).item_format === "json_markdown" ? "json_markdown" : "toon") as
     | "toon"
@@ -254,6 +288,34 @@ export async function runCompletionTagsPackage(global: GlobalOptions): Promise<{
   };
 }
 
+export async function runCompletionStatusesPackage(global: GlobalOptions): Promise<{ statuses: string[]; count: number }> {
+  const bundle = await ensureRuntimeBundle();
+  const pmRoot = bundle.sdk.resolvePmRoot(process.cwd(), global.path);
+  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));
+  return {
+    statuses,
+    count: statuses.length,
+  };
+}
+
+export async function runCompletionTypesPackage(global: GlobalOptions): Promise<{ types: string[]; count: number }> {
+  const bundle = await ensureRuntimeBundle();
+  const pmRoot = bundle.sdk.resolvePmRoot(process.cwd(), global.path);
+  const settings = await bundle.sdk.readSettings(pmRoot);
+  const registrations = bundle.sdk.getActiveExtensionRegistrations();
+  const typeRegistry = bundle.sdk.resolveItemTypeRegistry(settings, registrations);
+  const types = collectTypeNames(typeRegistry);
+  return {
+    types,
+    count: types.length,
+  };
+}
+
 export function renderGuideShellPackageOutput(context: ServiceOverrideContext): string | null {
   if (!runtimeBundle) {
     return null;
@@ -290,5 +352,23 @@ export function renderGuideShellPackageOutput(context: ServiceOverrideContext):
       : [];
     return `${tags.join(" ")}\n`;
   }
+  if (context.command === "completion-statuses") {
+    if (readPayloadFormat(context.payload) === "json") {
+      return `${JSON.stringify(result, null, 2)}\n`;
+    }
+    const statuses = typeof result === "object" && result !== null && Array.isArray((result as { statuses?: unknown }).statuses)
+      ? ((result as { statuses: unknown[] }).statuses.filter((entry): entry is string => typeof entry === "string"))
+      : [];
+    return `${statuses.join(" ")}\n`;
+  }
+  if (context.command === "completion-types") {
+    if (readPayloadFormat(context.payload) === "json") {
+      return `${JSON.stringify(result, null, 2)}\n`;
+    }
+    const types = typeof result === "object" && result !== null && Array.isArray((result as { types?: unknown }).types)
+      ? ((result as { types: unknown[] }).types.filter((entry): entry is string => typeof entry === "string"))
+      : [];
+    return `${types.join(" ")}\n`;
+  }
   return null;
 }

package/packages/pm-lifecycle-hooks/README.md

@@ -0,0 +1,29 @@
+# pm-lifecycle-hooks
+
+First-party package that demonstrates lifecycle hook registration through the
+public pm SDK.
+
+This package is intentionally default-inert. Its `afterCommand` hook returns
+without producing output, writing files, or changing command behavior. Package
+authors can copy this shape when they need low-risk observation hooks.
+
+Transition-aware packages can inspect `afterCommand`'s optional `affected`
+entries for item mutations. Each entry includes the item id, operation,
+previous/current status, changed fields, and compact front matter snapshots.
+
+## Capabilities
+
+- `hooks`
+
+## Install
+
+```bash
+pm install lifecycle-hooks --project
+```
+
+## Verify
+
+```bash
+pm package doctor --project --detail deep --json
+pm contracts --runtime-only --availability-only --json
+```

package/packages/pm-lifecycle-hooks/extensions/lifecycle-hooks/index.js

@@ -0,0 +1,18 @@
+export const manifest = {
+  name: "builtin-lifecycle-hooks",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["hooks"],
+};
+
+export function activate(api) {
+  // First-party hooks exemplar: default-inert lifecycle observation with no
+  // output, writes, or command-specific behavior.
+  api.hooks.afterCommand(() => undefined);
+}
+
+export default {
+  manifest,
+  activate,
+};

package/packages/pm-lifecycle-hooks/extensions/lifecycle-hooks/index.ts

@@ -0,0 +1,20 @@
+import type { ExtensionApi } from "../../../../src/sdk/index.js";
+
+export const manifest = {
+  name: "builtin-lifecycle-hooks",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["hooks"],
+};
+
+export function activate(api: ExtensionApi): void {
+  // First-party hooks exemplar: default-inert lifecycle observation with no
+  // output, writes, or command-specific behavior.
+  api.hooks.afterCommand(() => undefined);
+}
+
+export default {
+  manifest,
+  activate,
+};

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

@@ -0,0 +1,9 @@
+{
+  "name": "builtin-lifecycle-hooks",
+  "version": "0.1.0",
+  "entry": "./index.js",
+  "priority": 0,
+  "capabilities": ["hooks"],
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0"
+}

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

@@ -0,0 +1,52 @@
+{
+  "name": "@unbrained/pm-lifecycle-hooks",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "First-party pm package demonstrating safe lifecycle hook registration.",
+  "homepage": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-lifecycle-hooks#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unbraind/pm-cli.git",
+    "directory": "packages/pm-lifecycle-hooks"
+  },
+  "bugs": {
+    "url": "https://github.com/unbraind/pm-cli/issues"
+  },
+  "keywords": [
+    "pm-package",
+    "project-management",
+    "hooks",
+    "lifecycle",
+    "sdk"
+  ],
+  "pm": {
+    "aliases": [
+      "lifecycle-hooks"
+    ],
+    "extensions": [
+      "extensions/lifecycle-hooks"
+    ],
+    "catalog": {
+      "display_name": "Lifecycle Hooks",
+      "category": "sdk",
+      "summary": "Default-inert lifecycle hook exemplar for package authors.",
+      "tags": [
+        "hooks",
+        "lifecycle",
+        "sdk"
+      ],
+      "links": {
+        "docs": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-lifecycle-hooks#readme",
+        "repository": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-lifecycle-hooks",
+        "report": "https://github.com/unbraind/pm-cli/issues"
+      }
+    },
+    "docs": [
+      "README.md"
+    ],
+    "examples": [
+      "README.md"
+    ]
+  }
+}

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

@@ -3,5 +3,17 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
-  "capabilities": ["commands", "schema"]
+  "capabilities": ["commands", "schema"],
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0",
+  "activation": {
+    "commands": [
+      "test-runs",
+      "test-runs list",
+      "test-runs logs",
+      "test-runs resume",
+      "test-runs status",
+      "test-runs stop"
+    ]
+  }
 }

package/packages/pm-search-advanced/extensions/search-advanced/index.js

@@ -5,9 +5,76 @@ export const manifest = {
   version: "0.1.0",
   entry: "./index.js",
   priority: 0,
-  capabilities: ["commands", "schema"],
+  capabilities: ["commands", "schema", "search"],
 };
 
+export const SEARCH_ADVANCED_LOCAL_PROVIDER = "search-advanced-local";
+
+const SEARCH_FIELD_WEIGHTS = { title: 3, tags: 2, description: 1 };
+
+function tokenizeSearchText(value) {
+  // Unicode-aware: keep letters/numbers from any script (é, ü, CJK, Cyrillic, ...)
+  // so the provider works for non-English/multilingual corpora.
+  return value.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+}
+
+function scoreDocumentForQuery(queryTokens, document) {
+  const metadata = document?.metadata;
+  // A non-string id would crash hits.sort()'s localeCompare; treat as unscoreable.
+  if (!metadata || typeof metadata.id !== "string") {
+    return { score: 0, matched_fields: [] };
+  }
+  const fields = [
+    { field: "title", tokens: tokenizeSearchText(typeof metadata.title === "string" ? metadata.title : "") },
+    {
+      field: "tags",
+      tokens: Array.isArray(metadata.tags)
+        ? metadata.tags.flatMap((tag) => (tag == null ? [] : tokenizeSearchText(String(tag))))
+        : [],
+    },
+    {
+      field: "description",
+      tokens: tokenizeSearchText(typeof metadata.description === "string" ? metadata.description : ""),
+    },
+  ];
+  let score = 0;
+  const matched = [];
+  for (const { field, tokens } of fields) {
+    const available = new Set(tokens);
+    let fieldMatches = 0;
+    for (const queryToken of queryTokens) {
+      if (available.has(queryToken)) {
+        fieldMatches += 1;
+      }
+    }
+    if (fieldMatches > 0) {
+      score += fieldMatches * SEARCH_FIELD_WEIGHTS[field];
+      matched.push(field);
+    }
+  }
+  return { score, matched_fields: matched };
+}
+
+export function searchAdvancedLocalProvider() {
+  return {
+    name: SEARCH_ADVANCED_LOCAL_PROVIDER,
+    query(context) {
+      const queryTokens = tokenizeSearchText(context.query);
+      if (queryTokens.length === 0) {
+        return [];
+      }
+      const hits = [];
+      for (const document of context.documents) {
+        const { score, matched_fields } = scoreDocumentForQuery(queryTokens, document);
+        if (score > 0) {
+          hits.push({ id: document.metadata.id, score, matched_fields });
+        }
+      }
+      return hits.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id));
+    },
+  };
+}
+
 const searchAdvancedFlags = [
   {
     long: "--mode",
@@ -159,6 +226,7 @@ export function activate(api) {
   api.registerFlags("search-advanced", [...searchAdvancedFlags]);
   api.registerCommand(searchAdvancedCommand());
   api.registerCommand(reindexCommand());
+  api.registerSearchProvider(searchAdvancedLocalProvider());
 }
 
 export default {