@unbrained/pm-cli 2026.5.11 → 2026.5.14

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

@@ -0,0 +1,93 @@
+import { runAdvancedReindexPackage, runAdvancedSearchPackage } from "./runtime.js";
+
+export const manifest = {
+  name: "builtin-search-advanced",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands"],
+};
+
+const searchAdvancedFlags = [
+  {
+    long: "--mode",
+    value_name: "value",
+    value_type: "string",
+    description: "Search mode override: keyword|semantic|hybrid.",
+  },
+  {
+    long: "--include-linked",
+    value_type: "boolean",
+    description: "Include linked docs/files/tests corpus in lexical scoring.",
+  },
+  {
+    long: "--include_linked",
+    value_type: "boolean",
+    description: "Alias for --include-linked.",
+  },
+  {
+    long: "--title-exact",
+    value_type: "boolean",
+    description: "Require exact title phrase matching before scoring.",
+  },
+  {
+    long: "--title_exact",
+    value_type: "boolean",
+    description: "Alias for --title-exact.",
+  },
+  {
+    long: "--phrase-exact",
+    value_type: "boolean",
+    description: "Require exact phrase match across searchable document fields.",
+  },
+  {
+    long: "--phrase_exact",
+    value_type: "boolean",
+    description: "Alias for --phrase-exact.",
+  },
+];
+
+const reindexFlags = [
+  {
+    long: "--mode",
+    value_name: "value",
+    value_type: "string",
+    description: "Reindex mode: keyword|semantic|hybrid.",
+  },
+  {
+    long: "--progress",
+    value_type: "boolean",
+    description: "Emit non-interactive progress lines to stderr.",
+  },
+];
+
+function searchAdvancedCommand() {
+  return {
+    name: "search-advanced",
+    action: "search-advanced",
+    description: "Enable optional semantic and hybrid search modes via package runtime.",
+    arguments: [{ name: "keywords", required: true, variadic: true, description: "Query tokens." }],
+    run: async (context) => runAdvancedSearchPackage(context.args, context.options, context.global),
+  };
+}
+
+function reindexCommand() {
+  return {
+    name: "reindex",
+    action: "reindex",
+    description: "Rebuild search artifacts for keyword, semantic, and hybrid modes.",
+    flags: [...reindexFlags],
+    run: async (context) => runAdvancedReindexPackage(context.options, context.global),
+  };
+}
+
+export function activate(api) {
+  api.registerFlags("search-advanced", [...searchAdvancedFlags]);
+  api.registerCommand(searchAdvancedCommand());
+  api.registerCommand(reindexCommand());
+}
+
+export default {
+  manifest,
+  activate,
+};

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

@@ -0,0 +1,94 @@
+import type { CommandDefinition, ExtensionApi } from "../../../../src/sdk/index.js";
+import { runAdvancedReindexPackage, runAdvancedSearchPackage } from "./runtime.js";
+
+export const manifest = {
+  name: "builtin-search-advanced",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands"],
+};
+
+const searchAdvancedFlags = [
+  {
+    long: "--mode",
+    value_name: "value",
+    value_type: "string",
+    description: "Search mode override: keyword|semantic|hybrid.",
+  },
+  {
+    long: "--include-linked",
+    value_type: "boolean",
+    description: "Include linked docs/files/tests corpus in lexical scoring.",
+  },
+  {
+    long: "--include_linked",
+    value_type: "boolean",
+    description: "Alias for --include-linked.",
+  },
+  {
+    long: "--title-exact",
+    value_type: "boolean",
+    description: "Require exact title phrase matching before scoring.",
+  },
+  {
+    long: "--title_exact",
+    value_type: "boolean",
+    description: "Alias for --title-exact.",
+  },
+  {
+    long: "--phrase-exact",
+    value_type: "boolean",
+    description: "Require exact phrase match across searchable document fields.",
+  },
+  {
+    long: "--phrase_exact",
+    value_type: "boolean",
+    description: "Alias for --phrase-exact.",
+  },
+] as const;
+
+const reindexFlags = [
+  {
+    long: "--mode",
+    value_name: "value",
+    value_type: "string",
+    description: "Reindex mode: keyword|semantic|hybrid.",
+  },
+  {
+    long: "--progress",
+    value_type: "boolean",
+    description: "Emit non-interactive progress lines to stderr.",
+  },
+] as const;
+
+function searchAdvancedCommand(): CommandDefinition {
+  return {
+    name: "search-advanced",
+    action: "search-advanced",
+    description: "Enable optional semantic and hybrid search modes via package runtime.",
+    arguments: [{ name: "keywords", required: true, variadic: true, description: "Query tokens." }],
+    run: async (context) => runAdvancedSearchPackage(context.args, context.options, context.global),
+  };
+}
+
+function reindexCommand(): CommandDefinition {
+  return {
+    name: "reindex",
+    action: "reindex",
+    description: "Rebuild search artifacts for keyword, semantic, and hybrid modes.",
+    flags: [...reindexFlags],
+    run: async (context) => runAdvancedReindexPackage(context.options, context.global),
+  };
+}
+
+export function activate(api: ExtensionApi): void {
+  api.registerFlags("search-advanced", [...searchAdvancedFlags]);
+  api.registerCommand(searchAdvancedCommand());
+  api.registerCommand(reindexCommand());
+}
+
+export default {
+  manifest,
+  activate,
+};

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

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

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

@@ -0,0 +1,120 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+const sdk = await loadSearchSdkModule();
+const {
+  EXIT_CODE,
+  PmCliError,
+  runSearch,
+  runReindex,
+} = sdk;
+
+async function loadSearchSdkModule() {
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
+    throw new Error(
+      `builtin-search-advanced 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.runSearch === "function" &&
+      typeof loaded.runReindex === "function" &&
+      typeof loaded.PmCliError === "function" &&
+      typeof loaded.EXIT_CODE === "object" &&
+      loaded.EXIT_CODE !== null
+    ) {
+      return loaded;
+    }
+  } catch {
+    // Fall through to deterministic failure message below.
+  }
+  throw new Error(
+    `builtin-search-advanced failed to load 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 resolveSearchQuery(args) {
+  const query = args
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0)
+    .join(" ");
+  if (query.length === 0) {
+    throw new PmCliError("Search query must not be empty", EXIT_CODE.USAGE);
+  }
+  return query;
+}
+
+function normalizeAdvancedSearchOptions(rawOptions) {
+  const fields = readStringOption(rawOptions, "fields");
+  const compactRequested = readBooleanOption(rawOptions, "compact") === true;
+  const fullRequested = readBooleanOption(rawOptions, "full") === true;
+  const defaultCompact = !compactRequested && !fullRequested && fields === undefined;
+  return {
+    mode: readStringOption(rawOptions, "mode"),
+    includeLinked: readBooleanOption(rawOptions, "includeLinked", ["include_linked"]) === true ? true : undefined,
+    titleExact: readBooleanOption(rawOptions, "titleExact", ["title_exact"]) === true ? true : undefined,
+    phraseExact: readBooleanOption(rawOptions, "phraseExact", ["phrase_exact"]) === true ? true : undefined,
+    type: readStringOption(rawOptions, "type"),
+    tag: readStringOption(rawOptions, "tag"),
+    priority: readStringOption(rawOptions, "priority"),
+    deadlineBefore: readStringOption(rawOptions, "deadlineBefore", ["deadline_before"]),
+    deadlineAfter: readStringOption(rawOptions, "deadlineAfter", ["deadline_after"]),
+    limit: readStringOption(rawOptions, "limit"),
+    fields,
+    compact: compactRequested || defaultCompact ? true : undefined,
+    full: fullRequested ? true : undefined,
+  };
+}
+
+function normalizeReindexOptions(rawOptions) {
+  return {
+    mode: readStringOption(rawOptions, "mode"),
+    progress: readBooleanOption(rawOptions, "progress") === true ? true : undefined,
+  };
+}
+
+export async function runAdvancedSearchPackage(args, rawOptions, global) {
+  return runSearch(resolveSearchQuery(args), normalizeAdvancedSearchOptions(rawOptions), global);
+}
+
+export async function runAdvancedReindexPackage(rawOptions, global) {
+  return runReindex(normalizeReindexOptions(rawOptions), global);
+}

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

@@ -0,0 +1,144 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type {
+  GlobalOptions,
+  ReindexOptions,
+  ReindexResult,
+  SearchOptions,
+  SearchResult,
+} from "../../../../src/sdk/runtime.js";
+
+const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+
+interface SearchRuntimeSdkModule {
+  EXIT_CODE: {
+    USAGE: number;
+  };
+  PmCliError: new (message: string, exitCode?: number) => Error;
+  runSearch: (query: string, options: SearchOptions, global: GlobalOptions) => Promise<SearchResult>;
+  runReindex: (options: ReindexOptions, global: GlobalOptions) => Promise<ReindexResult>;
+}
+
+const sdk = await loadSearchSdkModule();
+const {
+  EXIT_CODE,
+  PmCliError,
+  runSearch,
+  runReindex,
+} = sdk;
+
+async function loadSearchSdkModule(): Promise<SearchRuntimeSdkModule> {
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
+    throw new Error(
+      `builtin-search-advanced 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<SearchRuntimeSdkModule>;
+    if (
+      typeof loaded.runSearch === "function" &&
+      typeof loaded.runReindex === "function" &&
+      typeof loaded.PmCliError === "function" &&
+      typeof loaded.EXIT_CODE === "object" &&
+      loaded.EXIT_CODE !== null
+    ) {
+      return loaded as SearchRuntimeSdkModule;
+    }
+  } catch {
+    // Fall through to deterministic failure message below.
+  }
+  throw new Error(
+    `builtin-search-advanced failed to load 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 resolveSearchQuery(args: string[]): string {
+  const query = args
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0)
+    .join(" ");
+  if (query.length === 0) {
+    throw new PmCliError("Search query must not be empty", EXIT_CODE.USAGE);
+  }
+  return query;
+}
+
+function normalizeAdvancedSearchOptions(rawOptions: Record<string, unknown>): SearchOptions {
+  const fields = readStringOption(rawOptions, "fields");
+  const compactRequested = readBooleanOption(rawOptions, "compact") === true;
+  const fullRequested = readBooleanOption(rawOptions, "full") === true;
+  const defaultCompact = !compactRequested && !fullRequested && fields === undefined;
+  return {
+    mode: readStringOption(rawOptions, "mode"),
+    includeLinked: readBooleanOption(rawOptions, "includeLinked", ["include_linked"]) === true ? true : undefined,
+    titleExact: readBooleanOption(rawOptions, "titleExact", ["title_exact"]) === true ? true : undefined,
+    phraseExact: readBooleanOption(rawOptions, "phraseExact", ["phrase_exact"]) === true ? true : undefined,
+    type: readStringOption(rawOptions, "type"),
+    tag: readStringOption(rawOptions, "tag"),
+    priority: readStringOption(rawOptions, "priority"),
+    deadlineBefore: readStringOption(rawOptions, "deadlineBefore", ["deadline_before"]),
+    deadlineAfter: readStringOption(rawOptions, "deadlineAfter", ["deadline_after"]),
+    limit: readStringOption(rawOptions, "limit"),
+    fields,
+    compact: compactRequested || defaultCompact ? true : undefined,
+    full: fullRequested ? true : undefined,
+  };
+}
+
+function normalizeReindexOptions(rawOptions: Record<string, unknown>): ReindexOptions {
+  return {
+    mode: readStringOption(rawOptions, "mode"),
+    progress: readBooleanOption(rawOptions, "progress") === true ? true : undefined,
+  };
+}
+
+export async function runAdvancedSearchPackage(
+  args: string[],
+  rawOptions: Record<string, unknown>,
+  global: GlobalOptions,
+): Promise<SearchResult> {
+  return runSearch(resolveSearchQuery(args), normalizeAdvancedSearchOptions(rawOptions), global);
+}
+
+export async function runAdvancedReindexPackage(
+  rawOptions: Record<string, unknown>,
+  global: GlobalOptions,
+): Promise<ReindexResult> {
+  return runReindex(normalizeReindexOptions(rawOptions), global);
+}

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

@@ -0,0 +1,54 @@
+{
+  "name": "@unbrained/pm-package-search-advanced",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",
+  "homepage": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-search-advanced#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unbraind/pm-cli.git",
+    "directory": "packages/pm-search-advanced"
+  },
+  "bugs": {
+    "url": "https://github.com/unbraind/pm-cli/issues"
+  },
+  "keywords": [
+    "pm-package",
+    "project-management",
+    "search",
+    "reindex",
+    "semantic",
+    "hybrid"
+  ],
+  "pm": {
+    "aliases": [
+      "search-advanced"
+    ],
+    "extensions": [
+      "extensions/search-advanced"
+    ],
+    "catalog": {
+      "display_name": "Advanced Search",
+      "category": "search",
+      "summary": "Enable semantic/hybrid search modes and reindex workflows.",
+      "tags": [
+        "search",
+        "semantic",
+        "hybrid",
+        "reindex"
+      ],
+      "links": {
+        "docs": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-search-advanced#readme",
+        "repository": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-search-advanced",
+        "report": "https://github.com/unbraind/pm-cli/issues"
+      }
+    },
+    "docs": [
+      "README.md"
+    ],
+    "examples": [
+      "README.md"
+    ]
+  }
+}

package/packages/pm-templates/README.md

@@ -0,0 +1,20 @@
+# pm Templates Package
+
+`@unbrained/pm-package-templates` provides reusable `pm create` templates as an installable pm package.
+
+Install it with:
+
+```bash
+pm install templates
+```
+
+Commands:
+
+```bash
+pm templates
+pm templates list
+pm templates save release-defaults --type Task --priority 1 --tags release
+pm templates show release-defaults
+```
+
+The package stores template documents in the active pm project root and uses only the public `@unbrained/pm-cli/sdk` runtime surface.

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

@@ -0,0 +1,101 @@
+import {
+  runTemplatesList as runTemplatesListPackage,
+  runTemplatesSave as runTemplatesSavePackage,
+  runTemplatesShow as runTemplatesShowPackage,
+} from "./runtime.js";
+
+export const manifest = {
+  name: "builtin-templates",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands", "schema"],
+};
+
+function firstArg(args, commandName) {
+  const value = args[0];
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value;
+  }
+  throw new Error(`${commandName} requires a template name argument.`);
+}
+
+async function runTemplatesListFromRuntime(global) {
+  return runTemplatesListPackage(global);
+}
+
+async function runTemplatesSaveFromRuntime(args, options, global) {
+  return runTemplatesSavePackage(firstArg(args, "templates save"), options, global);
+}
+
+async function runTemplatesShowFromRuntime(args, global) {
+  return runTemplatesShowPackage(firstArg(args, "templates show"), global);
+}
+
+const createOptionFlags = [
+  { long: "--title", short: "-t", value_name: "value", value_type: "string", description: "Template default item title." },
+  { long: "--description", short: "-d", value_name: "value", value_type: "string", description: "Template default item description." },
+  { long: "--type", value_name: "value", value_type: "string", description: "Template default item type." },
+  { long: "--status", short: "-s", value_name: "value", value_type: "string", description: "Template default item status." },
+  { long: "--priority", short: "-p", value_name: "value", value_type: "string", description: "Template default priority 0..4." },
+  { long: "--tags", value_name: "value", value_type: "string", description: "Template default comma-separated tags." },
+  { long: "--body", short: "-b", value_name: "value", value_type: "string", description: "Template default item markdown body." },
+  { long: "--deadline", value_name: "value", value_type: "string", description: "Template default deadline." },
+  { long: "--estimate", value_name: "value", value_type: "string", description: "Template default estimated minutes." },
+  { long: "--estimated-minutes", value_name: "value", value_type: "string", description: "Template default estimated minutes." },
+  { long: "--acceptance-criteria", value_name: "value", value_type: "string", description: "Template default acceptance criteria." },
+  { long: "--ac", value_name: "value", value_type: "string", description: "Alias for --acceptance-criteria." },
+  { long: "--author", value_name: "value", value_type: "string", description: "Template default mutation author." },
+  { long: "--message", value_name: "value", value_type: "string", description: "Template default history message." },
+  { long: "--assignee", value_name: "value", value_type: "string", description: "Template default assignee." },
+  { long: "--parent", value_name: "value", value_type: "string", description: "Template default parent item ID." },
+  { long: "--reviewer", value_name: "value", value_type: "string", description: "Template default reviewer." },
+  { long: "--risk", value_name: "value", value_type: "string", description: "Template default risk level." },
+  { long: "--confidence", value_name: "value", value_type: "string", description: "Template default confidence." },
+  { long: "--sprint", value_name: "value", value_type: "string", description: "Template default sprint identifier." },
+  { long: "--release", value_name: "value", value_type: "string", description: "Template default release identifier." },
+  { long: "--dep", value_name: "value", value_type: "string", description: "Template default dependency seed.", repeatable: true },
+  { long: "--comment", value_name: "value", value_type: "string", description: "Template default comment seed.", repeatable: true },
+  { long: "--note", value_name: "value", value_type: "string", description: "Template default note seed.", repeatable: true },
+  { long: "--learning", value_name: "value", value_type: "string", description: "Template default learning seed.", repeatable: true },
+  { long: "--file", value_name: "value", value_type: "string", description: "Template default linked file seed.", repeatable: true },
+  { long: "--test", value_name: "value", value_type: "string", description: "Template default linked test seed.", repeatable: true },
+  { long: "--doc", value_name: "value", value_type: "string", description: "Template default linked doc seed.", repeatable: true },
+  { long: "--reminder", value_name: "value", value_type: "string", description: "Template default reminder seed.", repeatable: true },
+  { long: "--event", value_name: "value", value_type: "string", description: "Template default event seed.", repeatable: true },
+];
+
+export function activate(api) {
+  api.registerCommand({
+    name: "templates",
+    action: "templates-list",
+    description: "List saved create templates.",
+    run: async (context) => runTemplatesListFromRuntime(context.global),
+  });
+  api.registerCommand({
+    name: "templates list",
+    action: "templates-list",
+    description: "List saved create templates.",
+    run: async (context) => runTemplatesListFromRuntime(context.global),
+  });
+  api.registerCommand({
+    name: "templates save",
+    action: "templates-save",
+    description: "Save reusable create template defaults.",
+    arguments: [{ name: "name", required: true, description: "Template name." }],
+    flags: [...createOptionFlags],
+    run: async (context) => runTemplatesSaveFromRuntime(context.args, context.options, context.global),
+  });
+  api.registerCommand({
+    name: "templates show",
+    action: "templates-show",
+    description: "Show a saved create template.",
+    arguments: [{ name: "name", required: true, description: "Template name." }],
+    run: async (context) => runTemplatesShowFromRuntime(context.args, context.global),
+  });
+}
+
+export default {
+  manifest,
+  activate,
+};