@unbrained/pm-cli 2026.5.31 → 2026.6.6

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 {

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

@@ -1,4 +1,11 @@
-import type { CommandDefinition, ExtensionApi } from "../../../../src/sdk/index.js";
+import type {
+  CommandDefinition,
+  ExtensionApi,
+  ItemDocument,
+  SearchProviderDefinition,
+  SearchProviderHit,
+  SearchProviderQueryContext,
+} from "../../../../src/sdk/index.js";
 import { runAdvancedReindexPackage, runAdvancedSearchPackage } from "./runtime.js";
 
 export const manifest = {
@@ -6,9 +13,90 @@ export const manifest = {
   version: "0.1.0",
   entry: "./index.js",
   priority: 0,
-  capabilities: ["commands", "schema"],
+  capabilities: ["commands", "schema", "search"],
 };
 
+/**
+ * Provider name selected via `pm config set search.provider search-advanced-local`.
+ * Core search invokes the registered `query` when this name is configured.
+ */
+export const SEARCH_ADVANCED_LOCAL_PROVIDER = "search-advanced-local";
+
+const SEARCH_FIELD_WEIGHTS = { title: 3, tags: 2, description: 1 } as const;
+
+function tokenizeSearchText(value: string): string[] {
+  // 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: readonly string[],
+  document: ItemDocument,
+): { score: number; matched_fields: string[] } {
+  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: Array<{ field: keyof typeof SEARCH_FIELD_WEIGHTS; tokens: string[] }> = [
+    { 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: string[] = [];
+  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 };
+}
+
+/**
+ * First-party exemplar SearchProvider: a deterministic, dependency-free local
+ * lexical ranker over the in-memory document corpus. Core search calls `query`
+ * when `settings.search.provider === "search-advanced-local"`. Authors building
+ * embedding-backed providers (for example Ollama or a hosted model) implement
+ * `embed`/`embedBatch` on this same SearchProviderDefinition shape instead.
+ */
+export function searchAdvancedLocalProvider(): SearchProviderDefinition {
+  return {
+    name: SEARCH_ADVANCED_LOCAL_PROVIDER,
+    query(context: SearchProviderQueryContext): SearchProviderHit[] {
+      const queryTokens = tokenizeSearchText(context.query);
+      if (queryTokens.length === 0) {
+        return [];
+      }
+      const hits: SearchProviderHit[] = [];
+      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",
@@ -160,6 +248,7 @@ export function activate(api: ExtensionApi): void {
   api.registerFlags("search-advanced", [...searchAdvancedFlags]);
   api.registerCommand(searchAdvancedCommand());
   api.registerCommand(reindexCommand());
+  api.registerSearchProvider(searchAdvancedLocalProvider());
 }
 
 export default {

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

@@ -3,5 +3,17 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
-  "capabilities": ["commands", "schema"]
+  "capabilities": [
+    "commands",
+    "schema",
+    "search"
+  ],
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0",
+  "activation": {
+    "commands": [
+      "reindex",
+      "search-advanced"
+    ]
+  }
 }

package/packages/pm-templates/extensions/templates/manifest.json

@@ -3,5 +3,10 @@
   "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": ["templates", "templates list", "templates save", "templates show"]
+  }
 }

package/packages/pm-todos/extensions/todos/index.js

@@ -4,7 +4,7 @@ export const manifest = {
     version: "0.1.0",
     entry: "./index.js",
     priority: 0,
-    capabilities: ["commands", "schema"],
+    capabilities: ["commands", "schema", "importers"],
 };
 function asOptionalString(value) {
     return typeof value === "string" ? value : undefined;
@@ -36,8 +36,7 @@ async function runTodosExportFromRuntime(options, global) {
     return runtime.runTodosExport(options, global);
 }
 export function activate(api) {
-    api.registerCommand({
-        name: "todos import",
+    api.registerImporter("todos", async (context) => runTodosImportFromRuntime(toImportOptions(context.options), context.global), {
         action: "todos-import",
         description: "Import Todo markdown files into pm items.",
         flags: [
@@ -60,10 +59,8 @@ export function activate(api) {
                 description: "Override import history message.",
             },
         ],
-        run: async (context) => runTodosImportFromRuntime(toImportOptions(context.options), context.global),
     });
-    api.registerCommand({
-        name: "todos export",
+    api.registerExporter("todos", async (context) => runTodosExportFromRuntime(toExportOptions(context.options), context.global), {
         action: "todos-export",
         description: "Export pm items into Todo markdown files.",
         flags: [
@@ -74,7 +71,6 @@ export function activate(api) {
                 description: "Destination folder for exported Todo markdown files.",
             },
         ],
-        run: async (context) => runTodosExportFromRuntime(toExportOptions(context.options), context.global),
     });
 }
 export default {