@unbrained/pm-cli 2026.5.14 → 2026.5.24

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

@@ -15,6 +15,16 @@ const searchAdvancedFlags = [
     value_type: "string",
     description: "Search mode override: keyword|semantic|hybrid.",
   },
+  {
+    long: "--semantic",
+    value_type: "boolean",
+    description: "Alias for --mode semantic.",
+  },
+  {
+    long: "--hybrid",
+    value_type: "boolean",
+    description: "Alias for --mode hybrid.",
+  },
   {
     long: "--include-linked",
     value_type: "boolean",
@@ -45,6 +55,70 @@ const searchAdvancedFlags = [
     value_type: "boolean",
     description: "Alias for --phrase-exact.",
   },
+  {
+    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: "date",
+    value_type: "string",
+    description: "Filter to items with deadlines before a date.",
+  },
+  {
+    long: "--deadline_before",
+    value_name: "date",
+    value_type: "string",
+    description: "Alias for --deadline-before.",
+  },
+  {
+    long: "--deadline-after",
+    value_name: "date",
+    value_type: "string",
+    description: "Filter to items with deadlines after a date.",
+  },
+  {
+    long: "--deadline_after",
+    value_name: "date",
+    value_type: "string",
+    description: "Alias for --deadline-after.",
+  },
+  {
+    long: "--limit",
+    value_name: "count",
+    value_type: "string",
+    description: "Limit the number of search results.",
+  },
+  {
+    long: "--fields",
+    value_name: "list",
+    value_type: "string",
+    description: "Return only selected result fields.",
+  },
+  {
+    long: "--compact",
+    value_type: "boolean",
+    description: "Return compact token-efficient search results.",
+  },
+  {
+    long: "--full",
+    value_type: "boolean",
+    description: "Return full search results.",
+  },
 ];
 
 const reindexFlags = [

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

@@ -6,7 +6,7 @@ export const manifest = {
   version: "0.1.0",
   entry: "./index.js",
   priority: 0,
-  capabilities: ["commands"],
+  capabilities: ["commands", "schema"],
 };
 
 const searchAdvancedFlags = [
@@ -16,6 +16,16 @@ const searchAdvancedFlags = [
     value_type: "string",
     description: "Search mode override: keyword|semantic|hybrid.",
   },
+  {
+    long: "--semantic",
+    value_type: "boolean",
+    description: "Alias for --mode semantic.",
+  },
+  {
+    long: "--hybrid",
+    value_type: "boolean",
+    description: "Alias for --mode hybrid.",
+  },
   {
     long: "--include-linked",
     value_type: "boolean",
@@ -46,6 +56,70 @@ const searchAdvancedFlags = [
     value_type: "boolean",
     description: "Alias for --phrase-exact.",
   },
+  {
+    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: "date",
+    value_type: "string",
+    description: "Filter to items with deadlines before a date.",
+  },
+  {
+    long: "--deadline_before",
+    value_name: "date",
+    value_type: "string",
+    description: "Alias for --deadline-before.",
+  },
+  {
+    long: "--deadline-after",
+    value_name: "date",
+    value_type: "string",
+    description: "Filter to items with deadlines after a date.",
+  },
+  {
+    long: "--deadline_after",
+    value_name: "date",
+    value_type: "string",
+    description: "Alias for --deadline-after.",
+  },
+  {
+    long: "--limit",
+    value_name: "count",
+    value_type: "string",
+    description: "Limit the number of search results.",
+  },
+  {
+    long: "--fields",
+    value_name: "list",
+    value_type: "string",
+    description: "Return only selected result fields.",
+  },
+  {
+    long: "--compact",
+    value_type: "boolean",
+    description: "Return compact token-efficient search results.",
+  },
+  {
+    long: "--full",
+    value_type: "boolean",
+    description: "Return full search results.",
+  },
 ] as const;
 
 const reindexFlags = [

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

@@ -48,6 +48,9 @@ function readStringOption(options, key, aliases = []) {
   return undefined;
 }
 
+const BOOLEAN_TRUE_VALUES = new Set(["true", "1", "yes", "on"]);
+const BOOLEAN_FALSE_VALUES = new Set(["false", "0", "no", "off"]);
+
 function readBooleanOption(options, key, aliases = []) {
   const keys = [key, ...aliases];
   for (const candidate of keys) {
@@ -60,10 +63,10 @@ function readBooleanOption(options, key, aliases = []) {
     }
     if (typeof value === "string") {
       const normalized = value.trim().toLowerCase();
-      if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on") {
+      if (BOOLEAN_TRUE_VALUES.has(normalized)) {
         return true;
       }
-      if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "off") {
+      if (BOOLEAN_FALSE_VALUES.has(normalized)) {
         return false;
       }
     }
@@ -71,24 +74,79 @@ function readBooleanOption(options, key, aliases = []) {
   return undefined;
 }
 
+const SEARCH_VALUE_FLAGS = new Set([
+  "--mode",
+  "--type",
+  "--tag",
+  "--priority",
+  "--deadline-before",
+  "--deadline_before",
+  "--deadline-after",
+  "--deadline_after",
+  "--limit",
+  "--fields",
+]);
+
+const SEARCH_BOOLEAN_FLAGS = new Set([
+  "--semantic",
+  "--hybrid",
+  "--include-linked",
+  "--include_linked",
+  "--title-exact",
+  "--title_exact",
+  "--phrase-exact",
+  "--phrase_exact",
+  "--compact",
+  "--full",
+  "--json",
+]);
+
+function stripSearchOptionTokens(args) {
+  const queryTokens = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index]?.trim() ?? "";
+    const equalsIndex = token.indexOf("=");
+    const flagName = equalsIndex > 0 ? token.slice(0, equalsIndex) : token;
+    if (SEARCH_VALUE_FLAGS.has(flagName)) {
+      if (equalsIndex < 0) {
+        index += 1;
+      }
+      continue;
+    }
+    if (SEARCH_BOOLEAN_FLAGS.has(flagName)) {
+      continue;
+    }
+    if (token.length > 0) {
+      queryTokens.push(token);
+    }
+  }
+  return queryTokens;
+}
+
 function resolveSearchQuery(args) {
-  const query = args
-    .map((value) => value.trim())
-    .filter((value) => value.length > 0)
-    .join(" ");
+  const query = stripSearchOptionTokens(args).join(" ");
   if (query.length === 0) {
     throw new PmCliError("Search query must not be empty", EXIT_CODE.USAGE);
   }
   return query;
 }
 
-function normalizeAdvancedSearchOptions(rawOptions) {
+function normalizeAdvancedSearchOptions(rawOptions, args) {
   const fields = readStringOption(rawOptions, "fields");
   const compactRequested = readBooleanOption(rawOptions, "compact") === true;
   const fullRequested = readBooleanOption(rawOptions, "full") === true;
   const defaultCompact = !compactRequested && !fullRequested && fields === undefined;
+  const explicitMode = readStringOption(rawOptions, "mode");
+  const argFlags = new Set(args.map((value) => value?.trim() ?? ""));
+  const mode =
+    explicitMode ??
+    (readBooleanOption(rawOptions, "semantic") === true || argFlags.has("--semantic")
+      ? "semantic"
+      : readBooleanOption(rawOptions, "hybrid") === true || argFlags.has("--hybrid")
+        ? "hybrid"
+        : "keyword");
   return {
-    mode: readStringOption(rawOptions, "mode"),
+    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,
@@ -112,7 +170,7 @@ function normalizeReindexOptions(rawOptions) {
 }
 
 export async function runAdvancedSearchPackage(args, rawOptions, global) {
-  return runSearch(resolveSearchQuery(args), normalizeAdvancedSearchOptions(rawOptions), global);
+  return runSearch(resolveSearchQuery(args), normalizeAdvancedSearchOptions(rawOptions, args), global);
 }
 
 export async function runAdvancedReindexPackage(rawOptions, global) {

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

@@ -65,6 +65,9 @@ function readStringOption(options: Record<string, unknown>, key: string, aliases
   return undefined;
 }
 
+const BOOLEAN_TRUE_VALUES = new Set(["true", "1", "yes", "on"]);
+const BOOLEAN_FALSE_VALUES = new Set(["false", "0", "no", "off"]);
+
 function readBooleanOption(options: Record<string, unknown>, key: string, aliases: string[] = []): boolean | undefined {
   const keys = [key, ...aliases];
   for (const candidate of keys) {
@@ -77,10 +80,10 @@ function readBooleanOption(options: Record<string, unknown>, key: string, aliase
     }
     if (typeof value === "string") {
       const normalized = value.trim().toLowerCase();
-      if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on") {
+      if (BOOLEAN_TRUE_VALUES.has(normalized)) {
         return true;
       }
-      if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "off") {
+      if (BOOLEAN_FALSE_VALUES.has(normalized)) {
         return false;
       }
     }
@@ -88,24 +91,79 @@ function readBooleanOption(options: Record<string, unknown>, key: string, aliase
   return undefined;
 }
 
+const SEARCH_VALUE_FLAGS = new Set([
+  "--mode",
+  "--type",
+  "--tag",
+  "--priority",
+  "--deadline-before",
+  "--deadline_before",
+  "--deadline-after",
+  "--deadline_after",
+  "--limit",
+  "--fields",
+]);
+
+const SEARCH_BOOLEAN_FLAGS = new Set([
+  "--semantic",
+  "--hybrid",
+  "--include-linked",
+  "--include_linked",
+  "--title-exact",
+  "--title_exact",
+  "--phrase-exact",
+  "--phrase_exact",
+  "--compact",
+  "--full",
+  "--json",
+]);
+
+function stripSearchOptionTokens(args: string[]): string[] {
+  const queryTokens: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index]?.trim() ?? "";
+    const equalsIndex = token.indexOf("=");
+    const flagName = equalsIndex > 0 ? token.slice(0, equalsIndex) : token;
+    if (SEARCH_VALUE_FLAGS.has(flagName)) {
+      if (equalsIndex < 0) {
+        index += 1;
+      }
+      continue;
+    }
+    if (SEARCH_BOOLEAN_FLAGS.has(flagName)) {
+      continue;
+    }
+    if (token.length > 0) {
+      queryTokens.push(token);
+    }
+  }
+  return queryTokens;
+}
+
 function resolveSearchQuery(args: string[]): string {
-  const query = args
-    .map((value) => value.trim())
-    .filter((value) => value.length > 0)
-    .join(" ");
+  const query = stripSearchOptionTokens(args).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 {
+function normalizeAdvancedSearchOptions(rawOptions: Record<string, unknown>, args: string[]): SearchOptions {
   const fields = readStringOption(rawOptions, "fields");
   const compactRequested = readBooleanOption(rawOptions, "compact") === true;
   const fullRequested = readBooleanOption(rawOptions, "full") === true;
   const defaultCompact = !compactRequested && !fullRequested && fields === undefined;
+  const explicitMode = readStringOption(rawOptions, "mode");
+  const argFlags = new Set(args.map((value) => value?.trim() ?? ""));
+  const mode =
+    explicitMode ??
+    (readBooleanOption(rawOptions, "semantic") === true || argFlags.has("--semantic")
+      ? "semantic"
+      : readBooleanOption(rawOptions, "hybrid") === true || argFlags.has("--hybrid")
+        ? "hybrid"
+        : "keyword");
   return {
-    mode: readStringOption(rawOptions, "mode"),
+    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,
@@ -133,7 +191,7 @@ export async function runAdvancedSearchPackage(
   rawOptions: Record<string, unknown>,
   global: GlobalOptions,
 ): Promise<SearchResult> {
-  return runSearch(resolveSearchQuery(args), normalizeAdvancedSearchOptions(rawOptions), global);
+  return runSearch(resolveSearchQuery(args), normalizeAdvancedSearchOptions(rawOptions, args), global);
 }
 
 export async function runAdvancedReindexPackage(

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

@@ -1,5 +1,5 @@
 {
-  "name": "@unbrained/pm-package-search-advanced",
+  "name": "@unbrained/pm-search-advanced",
   "version": "0.1.0",
   "private": true,
   "type": "module",

package/packages/pm-templates/README.md

@@ -1,6 +1,6 @@
 # pm Templates Package
 
-`@unbrained/pm-package-templates` provides reusable `pm create` templates as an installable pm package.
+`@unbrained/pm-templates` provides reusable `pm create` templates as an installable pm package.
 
 Install it with:
 

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

@@ -1,226 +1,35 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 const sdk = await loadTemplatesSdkModule();
-const {
-  CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS,
-  EXIT_CODE,
-  PmCliError,
-  getSettingsPath,
-  nowIso,
-  pathExists,
-  readFileIfExists,
-  resolvePmRoot,
-  writeFileAtomic,
-} = sdk;
-
 async function loadTemplatesSdkModule() {
   const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
   if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
-    throw new Error(
-      `builtin-templates requires ${PM_PACKAGE_ROOT_ENV} to locate core SDK runtime exports.`,
-    );
+    throw new Error(`builtin-templates requires ${PM_PACKAGE_ROOT_ENV} to locate core SDK runtime exports.`);
   }
   const modulePath = path.join(path.resolve(envRoot.trim()), "dist", "sdk", "index.js");
   try {
     const loaded = await import(pathToFileURL(modulePath).href);
-    if (
-      typeof loaded.resolvePmRoot === "function" &&
-      typeof loaded.pathExists === "function" &&
-      typeof loaded.PmCliError === "function" &&
-      Array.isArray(loaded.CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS)
-    ) {
+    if (typeof loaded.loadCreateTemplateOptions === "function" &&
+      typeof loaded.runTemplatesList === "function" &&
+      typeof loaded.runTemplatesSave === "function" &&
+      typeof loaded.runTemplatesShow === "function") {
       return loaded;
     }
   } catch {
     // Fall through to deterministic failure message below.
   }
-  throw new Error(
-    `builtin-templates failed to load SDK runtime exports from ${modulePath}.`,
-  );
+  throw new Error(`builtin-templates failed to load template runtime exports from ${modulePath}.`);
 }
-
-const TEMPLATE_DIRECTORY_NAME = "templates";
-const TEMPLATE_FILE_EXTENSION = ".json";
-const TEMPLATE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
-const TEMPLATE_OPTION_REPEATABLE_KEY_SET = new Set(CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS.map((entry) => entry.target));
-
-function normalizeTemplateName(rawName) {
-  const name = rawName.trim();
-  if (!TEMPLATE_NAME_PATTERN.test(name)) {
-    throw new PmCliError(
-      `Invalid template name "${rawName}". Expected 1-64 characters matching [A-Za-z0-9][A-Za-z0-9._-]*.`,
-      EXIT_CODE.USAGE,
-    );
-  }
-  return name;
-}
-
-function templatesDirectory(pmRoot) {
-  return path.join(pmRoot, TEMPLATE_DIRECTORY_NAME);
-}
-
-function templatePath(pmRoot, normalizedName) {
-  return path.join(templatesDirectory(pmRoot), `${normalizedName}${TEMPLATE_FILE_EXTENSION}`);
-}
-
-async function ensureTrackerInitialized(pmRoot) {
-  if (!(await pathExists(getSettingsPath(pmRoot)))) {
-    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-  }
-}
-
-function sortTemplateOptions(options) {
-  return Object.fromEntries(Object.entries(options).sort(([left], [right]) => left.localeCompare(right)));
-}
-
-function extractTemplateOptions(rawOptions) {
-  const next = {};
-  for (const [key, value] of Object.entries(rawOptions)) {
-    if (value === undefined) {
-      continue;
-    }
-    if (TEMPLATE_OPTION_REPEATABLE_KEY_SET.has(key)) {
-      if (typeof value === "string") {
-        next[key] = [value];
-        continue;
-      }
-      if (!Array.isArray(value)) {
-        continue;
-      }
-      const values = value.filter((entry) => typeof entry === "string");
-      if (values.length > 0) {
-        next[key] = values;
-      }
-      continue;
-    }
-    if (typeof value === "string") {
-      next[key] = value;
-      continue;
-    }
-    if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
-      next[key] = [...value];
-    }
-  }
-  return sortTemplateOptions(next);
-}
-
-function parseStoredTemplateOptions(rawOptions, templateName) {
-  if (typeof rawOptions !== "object" || rawOptions === null || Array.isArray(rawOptions)) {
-    throw new PmCliError(`Template "${templateName}" has invalid options payload.`, EXIT_CODE.GENERIC_FAILURE);
-  }
-  const normalized = {};
-  for (const [key, value] of Object.entries(rawOptions)) {
-    const normalizedKey = key.trim();
-    if (normalizedKey.length === 0) {
-      throw new PmCliError(`Template "${templateName}" contains an empty option key.`, EXIT_CODE.GENERIC_FAILURE);
-    }
-    if (typeof value === "string") {
-      normalized[normalizedKey] = value;
-      continue;
-    }
-    if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
-      normalized[normalizedKey] = [...value];
-      continue;
-    }
-    throw new PmCliError(`Template "${templateName}" contains invalid value for option "${normalizedKey}".`, EXIT_CODE.GENERIC_FAILURE);
-  }
-  return sortTemplateOptions(normalized);
-}
-
-function parseStoredTemplateDocument(raw, normalizedName) {
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    throw new PmCliError(`Template "${normalizedName}" contains invalid JSON.`, EXIT_CODE.GENERIC_FAILURE);
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new PmCliError(`Template "${normalizedName}" has invalid document shape.`, EXIT_CODE.GENERIC_FAILURE);
-  }
-  const options = parseStoredTemplateOptions(parsed.options, normalizedName);
-  const now = nowIso();
-  return {
-    name: typeof parsed.name === "string" && parsed.name.trim().length > 0 ? parsed.name.trim() : normalizedName,
-    created_at: typeof parsed.created_at === "string" ? parsed.created_at : now,
-    updated_at: typeof parsed.updated_at === "string" ? parsed.updated_at : now,
-    options,
-  };
-}
-
-async function readStoredTemplateDocument(pmRoot, normalizedName) {
-  const raw = await readFileIfExists(templatePath(pmRoot, normalizedName));
-  if (raw === null) {
-    throw new PmCliError(`Template "${normalizedName}" not found`, EXIT_CODE.NOT_FOUND);
-  }
-  return parseStoredTemplateDocument(raw, normalizedName);
+export async function loadCreateTemplateOptions(pmRoot, rawTemplateName) {
+  return sdk.loadCreateTemplateOptions(pmRoot, rawTemplateName);
 }
-
 export async function runTemplatesSave(rawTemplateName, options, global) {
-  const pmRoot = resolvePmRoot(process.cwd(), global.path);
-  await ensureTrackerInitialized(pmRoot);
-  const normalizedName = normalizeTemplateName(rawTemplateName);
-  const nextOptions = extractTemplateOptions(options);
-  if (Object.keys(nextOptions).length === 0) {
-    throw new PmCliError("templates save requires at least one create option flag", EXIT_CODE.USAGE);
-  }
-
-  const now = nowIso();
-  const storedPath = templatePath(pmRoot, normalizedName);
-  let createdAt = now;
-  if (await pathExists(storedPath)) {
-    const existing = await readStoredTemplateDocument(pmRoot, normalizedName);
-    createdAt = existing.created_at;
-  }
-
-  const document = {
-    name: normalizedName,
-    created_at: createdAt,
-    updated_at: now,
-    options: nextOptions,
-  };
-  await fs.mkdir(templatesDirectory(pmRoot), { recursive: true });
-  await writeFileAtomic(storedPath, `${JSON.stringify(document, null, 2)}\n`);
-  return {
-    name: document.name,
-    created_at: document.created_at,
-    updated_at: document.updated_at,
-    path: storedPath,
-    options: document.options,
-  };
+  return sdk.runTemplatesSave(rawTemplateName, options, global);
 }
-
 export async function runTemplatesList(global) {
-  const pmRoot = resolvePmRoot(process.cwd(), global.path);
-  await ensureTrackerInitialized(pmRoot);
-  const dirPath = templatesDirectory(pmRoot);
-  if (!(await pathExists(dirPath))) {
-    return { templates: [], count: 0 };
-  }
-  const entries = await fs.readdir(dirPath);
-  const templates = entries
-    .filter((entry) => entry.toLowerCase().endsWith(TEMPLATE_FILE_EXTENSION))
-    .map((entry) => entry.slice(0, -TEMPLATE_FILE_EXTENSION.length))
-    .filter((entry) => TEMPLATE_NAME_PATTERN.test(entry))
-    .sort((left, right) => left.localeCompare(right));
-  return {
-    templates,
-    count: templates.length,
-  };
+  return sdk.runTemplatesList(global);
 }
-
 export async function runTemplatesShow(rawTemplateName, global) {
-  const pmRoot = resolvePmRoot(process.cwd(), global.path);
-  await ensureTrackerInitialized(pmRoot);
-  const normalizedName = normalizeTemplateName(rawTemplateName);
-  const stored = await readStoredTemplateDocument(pmRoot, normalizedName);
-  return {
-    name: stored.name,
-    created_at: stored.created_at,
-    updated_at: stored.updated_at,
-    path: templatePath(pmRoot, normalizedName),
-    options: stored.options,
-  };
+  return sdk.runTemplatesShow(rawTemplateName, global);
 }