@unbrained/pm-cli 2026.7.15 → 2026.7.17

package/dist/sdk/test/runs.d.ts

@@ -0,0 +1,92 @@
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { type BackgroundLogStream, type BackgroundTestRunKind, type BackgroundTestRunStatus } from "../../core/test/background-runs.js";
+/** Documents the start background run command options payload exchanged by command, SDK, and package integrations. */
+export interface StartBackgroundRunCommandOptions {
+    /** Value that configures or reports kind for this contract. */
+    kind: BackgroundTestRunKind;
+    /** Value that configures or reports command args for this contract. */
+    commandArgs: string[];
+    /** Value that configures or reports target id for this contract. */
+    targetId?: string;
+    /** Value that configures or reports status filter for this contract. */
+    statusFilter?: string;
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports no extensions for this contract. */
+    noExtensions?: boolean;
+}
+/** Documents the start background run result payload exchanged by command, SDK, and package integrations. */
+export interface StartBackgroundRunResult {
+    /** Value that configures or reports started for this contract. */
+    started: boolean;
+    /** Value that configures or reports duplicate of for this contract. */
+    duplicate_of?: string;
+    /** Value that configures or reports run for this contract. */
+    run: unknown;
+}
+/** Implements run start background run for the public runtime surface of this module. */
+export declare function runStartBackgroundRun(options: StartBackgroundRunCommandOptions, global: GlobalOptions): Promise<StartBackgroundRunResult>;
+/** Documents the test runs list command options payload exchanged by command, SDK, and package integrations. */
+export interface TestRunsListCommandOptions {
+    /** Lifecycle state reported for status. */
+    status?: string;
+    /** Value that configures or reports limit for this contract. */
+    limit?: string;
+}
+/** Implements run test runs list for the public runtime surface of this module. */
+export declare function runTestRunsList(options: TestRunsListCommandOptions, global: GlobalOptions): Promise<{
+    runs: unknown[];
+    count: number;
+    filters: {
+        status?: BackgroundTestRunStatus;
+        limit?: number;
+    };
+}>;
+/** Implements run test runs status for the public runtime surface of this module. */
+export declare function runTestRunsStatus(runId: string, global: GlobalOptions): Promise<{
+    run: unknown;
+    health: unknown;
+}>;
+/** Documents the test runs logs command options payload exchanged by command, SDK, and package integrations. */
+export interface TestRunsLogsCommandOptions {
+    /** Value that configures or reports stream for this contract. */
+    stream?: string;
+    /** Value that configures or reports tail for this contract. */
+    tail?: string;
+}
+/** Implements run test runs logs for the public runtime surface of this module. */
+export declare function runTestRunsLogs(runId: string, options: TestRunsLogsCommandOptions, global: GlobalOptions): Promise<{
+    run: unknown;
+    stream: BackgroundLogStream;
+    tail: number;
+    stdout: string[];
+    stderr: string[];
+}>;
+/** Documents the test runs stop command options payload exchanged by command, SDK, and package integrations. */
+export interface TestRunsStopCommandOptions {
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Implements run test runs stop for the public runtime surface of this module. */
+export declare function runTestRunsStop(runId: string, options: TestRunsStopCommandOptions, global: GlobalOptions): Promise<{
+    run: unknown;
+    signal_sent: "SIGTERM" | "SIGKILL" | "none";
+}>;
+/** Documents the test runs resume command options payload exchanged by command, SDK, and package integrations. */
+export interface TestRunsResumeCommandOptions {
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports no extensions for this contract. */
+    noExtensions?: boolean;
+}
+/** Implements run test runs resume for the public runtime surface of this module. */
+export declare function runTestRunsResume(runId: string, options: TestRunsResumeCommandOptions, global: GlobalOptions): Promise<{
+    resumed_from: string;
+    run: unknown;
+}>;
+/** Implements run test runs worker for the public runtime surface of this module. */
+export declare function runTestRunsWorker(runId: string, global: GlobalOptions): Promise<{
+    id: string;
+    status: BackgroundTestRunStatus;
+    exit_code?: number;
+}>;

package/dist/sdk/test/runs.js

@@ -0,0 +1,195 @@
+/**
+ * @module sdk/test/runs
+ *
+ * Implements the pm test runs command surface and its agent-facing runtime behavior.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2c42bfb9-c598-5a6e-bfff-0c073bb44205")}catch(e){}}();
+import os from "node:os";
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { getBackgroundTestRunStatus, listBackgroundTestRuns, readBackgroundTestRunLogs, resumeBackgroundTestRun, runBackgroundTestRunWorker, spawnBackgroundTestRunWorker, startBackgroundTestRun, stopBackgroundTestRun, } from "../../core/test/background-runs.js";
+import { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+import { parseLimit } from "../../core/shared/numeric-parsers.js";
+const BACKGROUND_STATUS_VALUES = [
+    "queued",
+    "running",
+    "passed",
+    "failed",
+    "stopped",
+    "canceled",
+];
+const BACKGROUND_STREAM_VALUES = [
+    "stdout",
+    "stderr",
+    "both",
+];
+function normalizeStatus(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (BACKGROUND_STATUS_VALUES.includes(normalized)) {
+        return normalized;
+    }
+    throw new PmCliError(`Invalid --status value "${value}"`, EXIT_CODE.USAGE);
+}
+function normalizeStream(value) {
+    if (value === undefined || value.trim().length === 0) {
+        return "stderr";
+    }
+    const normalized = value.trim().toLowerCase();
+    if (BACKGROUND_STREAM_VALUES.includes(normalized)) {
+        return normalized;
+    }
+    throw new PmCliError(`Invalid --stream value "${value}"`, EXIT_CODE.USAGE);
+}
+function resolveWhoamiFallback() {
+    try {
+        const username = os.userInfo().username.trim();
+        if (username.length > 0) {
+            return username;
+        }
+    }
+    catch {
+        // Fall back to environment-derived attribution.
+    }
+    return undefined;
+}
+function resolveRequestedBy(author, fallback) {
+    const candidates = [
+        author,
+        process.env.PM_AUTHOR,
+        fallback,
+        process.env.USER,
+        process.env.LOGNAME,
+        process.env.USERNAME,
+        resolveWhoamiFallback(),
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate !== "string") {
+            continue;
+        }
+        const trimmed = candidate.trim();
+        if (trimmed.length > 0) {
+            return trimmed;
+        }
+    }
+    return "unknown";
+}
+async function ensureInitialized(pmRoot) {
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+}
+/** Implements run start background run for the public runtime surface of this module. */
+export async function runStartBackgroundRun(options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    const globalPmRoot = resolveGlobalPmRoot(process.cwd());
+    await ensureInitialized(pmRoot);
+    const settings = await readSettings(pmRoot);
+    const requestedBy = resolveRequestedBy(options.author, settings.author_default);
+    const started = await startBackgroundTestRun({
+        pmRoot,
+        globalPmRoot,
+        kind: options.kind,
+        commandArgs: options.commandArgs,
+        requestedBy,
+        targetId: options.targetId,
+        statusFilter: options.statusFilter,
+    });
+    if (!started.started) {
+        return {
+            started: false,
+            duplicate_of: started.duplicate_of,
+            run: started.run,
+        };
+    }
+    const spawned = await spawnBackgroundTestRunWorker({
+        pmRoot,
+        runId: started.run.id,
+        noExtensions: options.noExtensions === true,
+    });
+    return {
+        started: true,
+        run: spawned,
+    };
+}
+/** Implements run test runs list for the public runtime surface of this module. */
+export async function runTestRunsList(options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await ensureInitialized(pmRoot);
+    const status = normalizeStatus(options.status);
+    const limit = parseLimit(options.limit, "limit");
+    const runs = await listBackgroundTestRuns(pmRoot, { status, limit });
+    return {
+        runs,
+        count: runs.length,
+        filters: {
+            status,
+            limit,
+        },
+    };
+}
+/** Implements run test runs status for the public runtime surface of this module. */
+export async function runTestRunsStatus(runId, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await ensureInitialized(pmRoot);
+    const status = await getBackgroundTestRunStatus(pmRoot, runId);
+    return {
+        run: status.run,
+        health: status.health,
+    };
+}
+/** Implements run test runs logs for the public runtime surface of this module. */
+export async function runTestRunsLogs(runId, options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await ensureInitialized(pmRoot);
+    const stream = normalizeStream(options.stream);
+    const tail = parseLimit(options.tail, "tail");
+    const logs = await readBackgroundTestRunLogs(pmRoot, runId, stream, tail);
+    return {
+        run: logs.run,
+        stream: logs.stream,
+        tail: logs.tail,
+        stdout: logs.stdout,
+        stderr: logs.stderr,
+    };
+}
+/** Implements run test runs stop for the public runtime surface of this module. */
+export async function runTestRunsStop(runId, options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await ensureInitialized(pmRoot);
+    const stopped = await stopBackgroundTestRun(pmRoot, runId, options.force === true);
+    return {
+        run: stopped.run,
+        signal_sent: stopped.signal_sent,
+    };
+}
+/** Implements run test runs resume for the public runtime surface of this module. */
+export async function runTestRunsResume(runId, options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await ensureInitialized(pmRoot);
+    const settings = await readSettings(pmRoot);
+    const requestedBy = resolveRequestedBy(options.author, settings.author_default);
+    const resumed = await resumeBackgroundTestRun(pmRoot, runId, requestedBy, options.noExtensions === true);
+    return {
+        resumed_from: runId,
+        run: resumed,
+    };
+}
+/** Implements run test runs worker for the public runtime surface of this module. */
+export async function runTestRunsWorker(runId, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await ensureInitialized(pmRoot);
+    const finished = await runBackgroundTestRunWorker(pmRoot, runId, global.noExtensions === true);
+    return {
+        id: finished.id,
+        status: finished.status,
+        exit_code: finished.exit_code,
+    };
+}
+//# sourceMappingURL=runs.js.map
+//# debugId=2c42bfb9-c598-5a6e-bfff-0c073bb44205

package/dist/sdk/test/runs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.js","sources":["sdk/test/runs.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/test/runs\n *\n * Implements the pm test runs command surface and its agent-facing runtime behavior.\n */\nimport os from \"node:os\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport {\n  type BackgroundLogStream,\n  type BackgroundTestRunKind,\n  type BackgroundTestRunStatus,\n  getBackgroundTestRunStatus,\n  listBackgroundTestRuns,\n  readBackgroundTestRunLogs,\n  resumeBackgroundTestRun,\n  runBackgroundTestRunWorker,\n  spawnBackgroundTestRunWorker,\n  startBackgroundTestRun,\n  stopBackgroundTestRun,\n} from \"../../core/test/background-runs.js\";\nimport {\n  getSettingsPath,\n  resolveGlobalPmRoot,\n  resolvePmRoot,\n} from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { parseLimit } from \"../../core/shared/numeric-parsers.js\";\n\nconst BACKGROUND_STATUS_VALUES: readonly BackgroundTestRunStatus[] = [\n  \"queued\",\n  \"running\",\n  \"passed\",\n  \"failed\",\n  \"stopped\",\n  \"canceled\",\n];\nconst BACKGROUND_STREAM_VALUES: readonly BackgroundLogStream[] = [\n  \"stdout\",\n  \"stderr\",\n  \"both\",\n];\n\nfunction normalizeStatus(\n  value: string | undefined,\n): BackgroundTestRunStatus | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n  const normalized = value.trim().toLowerCase();\n  if ((BACKGROUND_STATUS_VALUES as readonly string[]).includes(normalized)) {\n    return normalized as BackgroundTestRunStatus;\n  }\n  throw new PmCliError(`Invalid --status value \"${value}\"`, EXIT_CODE.USAGE);\n}\n\nfunction normalizeStream(value: string | undefined): BackgroundLogStream {\n  if (value === undefined || value.trim().length === 0) {\n    return \"stderr\";\n  }\n  const normalized = value.trim().toLowerCase();\n  if ((BACKGROUND_STREAM_VALUES as readonly string[]).includes(normalized)) {\n    return normalized as BackgroundLogStream;\n  }\n  throw new PmCliError(`Invalid --stream value \"${value}\"`, EXIT_CODE.USAGE);\n}\n\nfunction resolveWhoamiFallback(): string | undefined {\n  try {\n    const username = os.userInfo().username.trim();\n    if (username.length > 0) {\n      return username;\n    }\n  } catch {\n    // Fall back to environment-derived attribution.\n  }\n  return undefined;\n}\n\nfunction resolveRequestedBy(\n  author: string | undefined,\n  fallback: string,\n): string {\n  const candidates = [\n    author,\n    process.env.PM_AUTHOR,\n    fallback,\n    process.env.USER,\n    process.env.LOGNAME,\n    process.env.USERNAME,\n    resolveWhoamiFallback(),\n  ];\n  for (const candidate of candidates) {\n    if (typeof candidate !== \"string\") {\n      continue;\n    }\n    const trimmed = candidate.trim();\n    if (trimmed.length > 0) {\n      return trimmed;\n    }\n  }\n  return \"unknown\";\n}\n\nasync function ensureInitialized(pmRoot: string): Promise<void> {\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(\n      `Tracker is not initialized at ${pmRoot}. Run pm init first.`,\n      EXIT_CODE.NOT_FOUND,\n    );\n  }\n}\n\n/** Documents the start background run command options payload exchanged by command, SDK, and package integrations. */\nexport interface StartBackgroundRunCommandOptions {\n  /** Value that configures or reports kind for this contract. */\n  kind: BackgroundTestRunKind;\n  /** Value that configures or reports command args for this contract. */\n  commandArgs: string[];\n  /** Value that configures or reports target id for this contract. */\n  targetId?: string;\n  /** Value that configures or reports status filter for this contract. */\n  statusFilter?: string;\n  /** Value that configures or reports author for this contract. */\n  author?: string;\n  /** Value that configures or reports no extensions for this contract. */\n  noExtensions?: boolean;\n}\n\n/** Documents the start background run result payload exchanged by command, SDK, and package integrations. */\nexport interface StartBackgroundRunResult {\n  /** Value that configures or reports started for this contract. */\n  started: boolean;\n  /** Value that configures or reports duplicate of for this contract. */\n  duplicate_of?: string;\n  /** Value that configures or reports run for this contract. */\n  run: unknown;\n}\n\n/** Implements run start background run for the public runtime surface of this module. */\nexport async function runStartBackgroundRun(\n  options: StartBackgroundRunCommandOptions,\n  global: GlobalOptions,\n): Promise<StartBackgroundRunResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  const globalPmRoot = resolveGlobalPmRoot(process.cwd());\n  await ensureInitialized(pmRoot);\n  const settings = await readSettings(pmRoot);\n  const requestedBy = resolveRequestedBy(\n    options.author,\n    settings.author_default,\n  );\n  const started = await startBackgroundTestRun({\n    pmRoot,\n    globalPmRoot,\n    kind: options.kind,\n    commandArgs: options.commandArgs,\n    requestedBy,\n    targetId: options.targetId,\n    statusFilter: options.statusFilter,\n  });\n  if (!started.started) {\n    return {\n      started: false,\n      duplicate_of: started.duplicate_of,\n      run: started.run,\n    };\n  }\n  const spawned = await spawnBackgroundTestRunWorker({\n    pmRoot,\n    runId: started.run.id,\n    noExtensions: options.noExtensions === true,\n  });\n  return {\n    started: true,\n    run: spawned,\n  };\n}\n\n/** Documents the test runs list command options payload exchanged by command, SDK, and package integrations. */\nexport interface TestRunsListCommandOptions {\n  /** Lifecycle state reported for status. */\n  status?: string;\n  /** Value that configures or reports limit for this contract. */\n  limit?: string;\n}\n\n/** Implements run test runs list for the public runtime surface of this module. */\nexport async function runTestRunsList(\n  options: TestRunsListCommandOptions,\n  global: GlobalOptions,\n): Promise<{\n  runs: unknown[];\n  count: number;\n  filters: {\n    status?: BackgroundTestRunStatus;\n    limit?: number;\n  };\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const status = normalizeStatus(options.status);\n  const limit = parseLimit(options.limit, \"limit\");\n  const runs = await listBackgroundTestRuns(pmRoot, { status, limit });\n  return {\n    runs,\n    count: runs.length,\n    filters: {\n      status,\n      limit,\n    },\n  };\n}\n\n/** Implements run test runs status for the public runtime surface of this module. */\nexport async function runTestRunsStatus(\n  runId: string,\n  global: GlobalOptions,\n): Promise<{\n  run: unknown;\n  health: unknown;\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const status = await getBackgroundTestRunStatus(pmRoot, runId);\n  return {\n    run: status.run,\n    health: status.health,\n  };\n}\n\n/** Documents the test runs logs command options payload exchanged by command, SDK, and package integrations. */\nexport interface TestRunsLogsCommandOptions {\n  /** Value that configures or reports stream for this contract. */\n  stream?: string;\n  /** Value that configures or reports tail for this contract. */\n  tail?: string;\n}\n\n/** Implements run test runs logs for the public runtime surface of this module. */\nexport async function runTestRunsLogs(\n  runId: string,\n  options: TestRunsLogsCommandOptions,\n  global: GlobalOptions,\n): Promise<{\n  run: unknown;\n  stream: BackgroundLogStream;\n  tail: number;\n  stdout: string[];\n  stderr: string[];\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const stream = normalizeStream(options.stream);\n  const tail = parseLimit(options.tail, \"tail\");\n  const logs = await readBackgroundTestRunLogs(pmRoot, runId, stream, tail);\n  return {\n    run: logs.run,\n    stream: logs.stream,\n    tail: logs.tail,\n    stdout: logs.stdout,\n    stderr: logs.stderr,\n  };\n}\n\n/** Documents the test runs stop command options payload exchanged by command, SDK, and package integrations. */\nexport interface TestRunsStopCommandOptions {\n  /** Value that configures or reports force for this contract. */\n  force?: boolean;\n}\n\n/** Implements run test runs stop for the public runtime surface of this module. */\nexport async function runTestRunsStop(\n  runId: string,\n  options: TestRunsStopCommandOptions,\n  global: GlobalOptions,\n): Promise<{\n  run: unknown;\n  signal_sent: \"SIGTERM\" | \"SIGKILL\" | \"none\";\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const stopped = await stopBackgroundTestRun(\n    pmRoot,\n    runId,\n    options.force === true,\n  );\n  return {\n    run: stopped.run,\n    signal_sent: stopped.signal_sent,\n  };\n}\n\n/** Documents the test runs resume command options payload exchanged by command, SDK, and package integrations. */\nexport interface TestRunsResumeCommandOptions {\n  /** Value that configures or reports author for this contract. */\n  author?: string;\n  /** Value that configures or reports no extensions for this contract. */\n  noExtensions?: boolean;\n}\n\n/** Implements run test runs resume for the public runtime surface of this module. */\nexport async function runTestRunsResume(\n  runId: string,\n  options: TestRunsResumeCommandOptions,\n  global: GlobalOptions,\n): Promise<{\n  resumed_from: string;\n  run: unknown;\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const settings = await readSettings(pmRoot);\n  const requestedBy = resolveRequestedBy(\n    options.author,\n    settings.author_default,\n  );\n  const resumed = await resumeBackgroundTestRun(\n    pmRoot,\n    runId,\n    requestedBy,\n    options.noExtensions === true,\n  );\n  return {\n    resumed_from: runId,\n    run: resumed,\n  };\n}\n\n/** Implements run test runs worker for the public runtime surface of this module. */\nexport async function runTestRunsWorker(\n  runId: string,\n  global: GlobalOptions,\n): Promise<{\n  id: string;\n  status: BackgroundTestRunStatus;\n  exit_code?: number;\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const finished = await runBackgroundTestRunWorker(\n    pmRoot,\n    runId,\n    global.noExtensions === true,\n  );\n  return {\n    id: finished.id,\n    status: finished.status,\n    exit_code: finished.exit_code,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"2c42bfb9-c598-5a6e-bfff-0c073bb44205"}

package/docs/SDK.md

@@ -45,7 +45,21 @@ Source of truth:
 - [`src/sdk/governance/validate.ts`](../src/sdk/governance/validate.ts)
 - [`src/sdk/governance/health.ts`](../src/sdk/governance/health.ts)
 - [`src/sdk/governance/gc.ts`](../src/sdk/governance/gc.ts)
+- [`src/sdk/query/list.ts`](../src/sdk/query/list.ts)
+- [`src/sdk/query/search.ts`](../src/sdk/query/search.ts)
+- [`src/sdk/query/search-pagination.ts`](../src/sdk/query/search-pagination.ts)
+- [`src/sdk/query/search-rendering.ts`](../src/sdk/query/search-rendering.ts)
+- [`src/sdk/query/item-filter-options.ts`](../src/sdk/query/item-filter-options.ts)
+- [`src/sdk/query/parsers.ts`](../src/sdk/query/parsers.ts)
+- [`src/sdk/test/execution.ts`](../src/sdk/test/execution.ts)
+- [`src/sdk/test/batch.ts`](../src/sdk/test/batch.ts)
+- [`src/sdk/test/runs.ts`](../src/sdk/test/runs.ts)
+- [`src/sdk/test/parsers.ts`](../src/sdk/test/parsers.ts)
+- [`src/sdk/eval.ts`](../src/sdk/eval.ts)
+- [`src/sdk/telemetry.ts`](../src/sdk/telemetry.ts)
+- [`src/sdk/stats.ts`](../src/sdk/stats.ts)
 - [`src/sdk/cli-contracts.ts`](../src/sdk/cli-contracts.ts)
+- [`src/sdk/cli-bootstrap.ts`](../src/sdk/cli-bootstrap.ts)
 - [`src/sdk/cli-contracts/commander-types.ts`](../src/sdk/cli-contracts/commander-types.ts)
 - [`src/sdk/cli-contracts/commander-mutation-options.ts`](../src/sdk/cli-contracts/commander-mutation-options.ts)
 
@@ -137,6 +151,9 @@ Command/action contract exports:
 - Typed governance and maintenance primitives on `PmClient`: `validate`, `health`, `gc`, `historyRedact`, `historyRepair`, `historyRepairAll`, `historyCompact`, and `historyCompactBulk`
 - Governance and maintenance option/result contracts: `ValidateCommandOptions` / `ValidateResult`, `RunHealthOptions` / `HealthResult`, `GcCommandOptions` / `GcResult`, `HistoryRedactCommandOptions` / `HistoryRedactResult`, `HistoryRepairCommandOptions` / `HistoryRepairResult` / `HistoryRepairAllResult`, and `HistoryCompactCommandOptions` / `HistoryCompactResult` / `HistoryCompactBulkCommandOptions` / `HistoryCompactBulkResult`
 - Direct governance engines: `runValidate`, `runHealth`, and `runGc` are public SDK exports used by the CLI compatibility adapters and by custom policy engines that already own `GlobalOptions`. Their structured results are identical to CLI JSON output; no shell process or private core import is required.
+- Execution and diagnostics engines: `runTest`, `runLinkedTests`, `runTestAll`, `runStartBackgroundRun`, `runTestRunsList`, `runTestRunsStatus`, `runTestRunsLogs`, `runTestRunsStop`, `runTestRunsResume`, `runTestRunsWorker`, `runEval`, `runTelemetry`, and `runStats`. Their CLI modules are compatibility re-exports of SDK-owned implementations.
+- Execution and diagnostics contracts: `TestCommandOptions` / `TestResult` / `TestRunResult`, `TestAllCommandOptions` / `TestAllResult`, `StartBackgroundRunCommandOptions` / `StartBackgroundRunResult`, `TestRuns*CommandOptions`, `EvalOptions` / `EvalResult`, `TelemetryCommandOptions` / `TelemetrySubcommand`, and `StatsCommandOptions` / `StatsResult`.
+- Linked-test authoring primitives: `parseLinkedTestJsonEntries`, the `parseLinkedTest*` field parsers, `LINKED_TEST_PM_CONTEXT_MODE_VALUES`, `LINKED_TEST_PROTECTED_ENV_KEYS`, `classifyLinkedTestFailure`, `countFailureCategories`, and `summarizeContextPreflight` let custom hosts validate, execute, classify, and report linked tests without duplicating CLI policy.
 - Typed plan workflow primitives on `PmClient`: `plan`, `planCreate`, `planShow`, `planAddStep`, `planUpdateStep`, `planCompleteStep`, `planBlockStep`, `planReorderStep`, `planRemoveStep`, `planLink`, `planUnlink`, `planDecision`, `planDiscovery`, `planValidation`, `planResume`, `planApprove`, and `planMaterialize`
 - Plan contracts: `PlanSubcommand`, `PlanCommandOptions`, `PlanCommandResult`, `PlanResultPlan`, `PlanStepSummary`, `PlanShowDepth`, and `PlanTemplateName`
 - Typed package and extension lifecycle primitives on `PmClient`: `extension`, `extensionList`, `extensionActivate`, `extensionDeactivate`, `package`, `packageList`, `packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`, `packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`, `packageDeactivate`, and `upgrade`
@@ -147,6 +164,29 @@ Command/action contract exports:
 - `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`
 - `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
 
+### Build an entire custom project tool
+
+The [SDK-only custom-tool exemplar](examples/sdk-custom-tool/README.md)
+is the acceptance reference for applications that use pm as a universal
+context engine rather than as an extension host. It imports only
+`@unbrained/pm-cli/sdk` and composes schema customization, custom workflow
+statuses, lifecycle mutations, annotations, linked resources, dependency
+graphs, bounded context, search, health, and validation into a standalone
+domain CLI.
+
+Copy its reusable client pattern when building a company workflow,
+domain-specific tracker, VCS-like system, or other application whose durable
+state and business rules fit pm's public primitives. Keep the executable layer
+thin: domain logic belongs in a reusable SDK client, while argv parsing and
+rendering stay at the edge.
+
+Embedded hosts can also import the SDK-owned bootstrap normalization primitives
+(`normalizeBootstrapInvocation`, `parseBootstrapGlobalOptions`, and related
+contracts) when they intentionally expose pm-compatible argv. Every
+`runPmCli()` call constructs a fresh Commander graph, so extension commands,
+extension flags, and runtime schema options from one workspace cannot leak into
+the next in-process invocation.
+
 ### Plan workflows
 
 Custom tools can manage durable plans without shelling out or importing CLI internals. The typed façade uses the same engine and result envelopes as `pm plan` and MCP `pm_plan`:
@@ -785,6 +825,87 @@ the same bounded maintenance engine as the CLI. Prefer these typed calls over
 shelling out when building CI, editor integrations, or long-running agent
 runtimes.
 
+### Query execution
+
+Tracked by [pm-rjqr](../.agents/pm/features/pm-rjqr.toon) and the SDK boundary
+capstone [pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon).
+
+`runList` and `runSearch` are SDK-owned query engines, including filtering,
+projection, pagination, keyword and semantic ranking, extension-provider
+dispatch, and token-efficient response metadata. Their historical CLI module
+paths are identity-preserving compatibility exports, while `runEval` consumes
+the SDK search engine directly. Package authors can import these functions and
+their typed result contracts from `@unbrained/pm-cli/sdk` without importing CLI
+implementation modules.
+
+List result rows are modeled by projection: `ListFullResult` contains complete
+`ListedItem` records, tree ordering may enrich them with `ListTreeMetadata`, and
+compact or `fields` projections return `ListProjectedItem` dictionaries. Use
+`full: true` when an integration requires complete item metadata; the overload
+then returns `ListFullResult` without an assertion or cast.
+
+### Execution and diagnostics
+
+Tracked by [pm-oslr](../.agents/pm/features/pm-oslr.toon) and the SDK boundary
+capstone [pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon).
+
+Test execution, background-run supervision, search evaluation, telemetry
+inspection, and tracker statistics are SDK-owned primitives. A custom CI host or
+project-specific tool can compose the same sandboxing, context-preflight,
+deduplication, failure classification, progress, consent, and structured-result
+behavior as the CLI without spawning `pm` or importing `src/core` modules:
+
+```ts
+import {
+  runEval,
+  runTelemetry,
+  runTest,
+  runTestAll,
+  runTestRunsStatus,
+  type GlobalOptions,
+} from "@unbrained/pm-cli/sdk";
+
+const pmRoot = "/path/to/project/.agents/pm";
+const itemId = "pm-example";
+const runId = "test-run-example";
+const global: GlobalOptions = { path: pmRoot };
+
+const itemRun = await runTest(
+  itemId,
+  {
+    run: true,
+    autoPmContext: true,
+    checkContext: true,
+    failOnEmptyTestRun: true,
+  },
+  global,
+);
+
+const workspaceRun = await runTestAll(
+  { status: "open", autoPmContext: true, failOnSkipped: true },
+  global,
+);
+const background = await runTestRunsStatus(runId, global);
+const relevance = await runEval({ mode: "keyword", k: 10 }, global);
+const telemetry = await runTelemetry(
+  { subcommand: "stats", limit: 20 },
+  global,
+);
+```
+
+`runTest` and `runTestAll` always execute linked commands in isolated project and
+global tracker roots. `pm_context_mode`, run-level overrides, automatic tracker
+context, assertion requirements, empty-run detection, and failure categories are
+part of the SDK result contract rather than presentation-layer behavior.
+Background-run helpers return durable records and health/log projections; the
+host remains responsible for its own rendering and exit-code policy.
+
+`runTelemetry` retains consent and storage ownership inside the primitive:
+`status` and `stats` are observational, `flush` uses the consent-aware queue
+runtime, and `clear` disables telemetry and removes runtime artifacts. `runEval`
+uses the same live search path and unrounded gate decision as `pm eval`, returning
+compact rounded report metrics for stable machine output.
+
 ### Context relevance and evaluation
 
 Tracked by [pm-4k6b](../.agents/pm/features/pm-4k6b.toon),
@@ -2226,6 +2347,7 @@ search degrades gracefully and emits warning codes instead of hard-failing.
 
 Runnable examples:
 
+- [SDK-only custom project tool](examples/sdk-custom-tool/README.md)
 - [SDK contract consumer](examples/sdk-contract-consumer/README.md)
 - [SDK app embedding](examples/sdk-app-embedding/README.md)
 - [CI examples](examples/ci/)

package/docs/SDK_PRIMITIVE_INVENTORY.md

@@ -1,6 +1,6 @@
 # SDK Primitive Inventory
 
-Tracked work: [pm-lodl](../.agents/pm/tasks/pm-lodl.toon), [pm-8778](../.agents/pm/tasks/pm-8778.toon), parent [pm-usfg](../.agents/pm/epics/pm-usfg.toon).
+Tracked work: [pm-lodl](../.agents/pm/tasks/pm-lodl.toon), [pm-8778](../.agents/pm/tasks/pm-8778.toon), [pm-rjqr](../.agents/pm/features/pm-rjqr.toon), [pm-oslr](../.agents/pm/features/pm-oslr.toon), capstone [pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon), parent [pm-usfg](../.agents/pm/epics/pm-usfg.toon).
 
 This inventory is the current SDK-first migration map for the principle `project management = context management`.
 The exact per-source CLI/MCP module inventory is checked in at [`scripts/release/sdk-import-boundary-baseline.json`](../scripts/release/sdk-import-boundary-baseline.json): each `allowed_private_core_imports[]` entry names one command, helper, or MCP source file and the private `src/core` modules it currently imports. The static quality gate reads that file and fails when `src/cli` or `src/mcp` adds a new private `src/core` import, uses a computed dynamic `import()` that cannot be ratcheted, or leaves a stale baseline entry after an import has been removed.
@@ -9,6 +9,7 @@ The exact per-source CLI/MCP module inventory is checked in at [`scripts/release
 
 - Boundary scope: `src/cli.ts`, `src/cli/**`, `src/mcp.ts`, and `src/mcp/**`.
 - Current scan size and private-edge counts are derived from [`scripts/release/sdk-import-boundary-baseline.json`](../scripts/release/sdk-import-boundary-baseline.json) and the `pnpm quality:static` ratchet output.
+- Current enforced baseline after the query/execution bundle: 51 CLI/MCP source modules and 412 private-core import edges, down from 62 sources and 538 edges at the start of the bundle.
 - Type-only imports and re-exports are intentionally counted because they still expose presentation layers to private core contracts.
 - Baseline owner: [pm-8778](../.agents/pm/tasks/pm-8778.toon).
 - Ratchet rule: SDK promotion PRs must shrink the baseline when they move a primitive behind `src/sdk`; no PR may grow it.
@@ -36,12 +37,13 @@ Use [`scripts/release/sdk-import-boundary-baseline.json`](../scripts/release/sdk
 | --- | --- | --- |
 | `create`, `update`, `update-many`, `copy`, `delete`, `restore` | [pm-98cz](../.agents/pm/features/pm-98cz.toon) | Item CRUD and replay paths should become typed lifecycle SDK calls. |
 | `claim`, `release`, `focus`, lifecycle shortcut helpers | [pm-98cz](../.agents/pm/features/pm-98cz.toon) | Ownership and actionable-state changes belong beside lifecycle primitives. |
-| `list`, `get`, `search`, `context`, `next`, `aggregate`, `stats` | [pm-rjqr](../.agents/pm/features/pm-rjqr.toon) | Read models should be reusable by CLI, MCP, and custom agents without shelling out. |
+| `list`, `get`, `search`, `context`, `next`, `aggregate`, `stats` | [pm-rjqr](../.agents/pm/features/pm-rjqr.toon) | `list` and `search` implementations now live under `src/sdk/query/**`; remaining read models should follow the same SDK-owned pattern. |
 | `comments`, `notes`, `learnings`, `files`, `docs`, `deps`, `append` | [pm-zwpp](../.agents/pm/features/pm-zwpp.toon) | Annotation/link mutation semantics must be stable SDK primitives. |
 | `schema`, `config`, `profile`, `init`, `init-agent-guidance` | [pm-3mna](../.agents/pm/features/pm-3mna.toon) | Universal customization requires programmatic schema, profile, and config APIs. |
 | `history`, `activity`, `history-redact`, `history-repair`, `history-compact` | [pm-4a7m](../.agents/pm/features/pm-4a7m.toon) | Audited history read, activity, rewrite, and checkpoint operations need explicit public contracts. |
 | `plan` | [pm-je50](../.agents/pm/features/pm-je50.toon) | Plan harness operations should be usable by external orchestrators through SDK calls. |
-| `test`, `test-all`, `test-runs`, `eval`, `telemetry`, `reindex` | [pm-oslr](../.agents/pm/features/pm-oslr.toon) | Execution helpers should return typed run state and diagnostics instead of CLI-only text. |
+| `test`, `test-all`, `test-runs`, `eval`, `telemetry`, `stats` | [pm-oslr](../.agents/pm/features/pm-oslr.toon) | Implementations live under `src/sdk/test/**`, `src/sdk/eval.ts`, `src/sdk/telemetry.ts`, and `src/sdk/stats.ts`; CLI paths are compatibility exports with typed structured results. |
+| `reindex` | [pm-rjqr](../.agents/pm/features/pm-rjqr.toon) / [pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon) | Search-index refresh remains part of the query/read ownership and terminal boundary burn-down. |
 | `extension`, `upgrade`, package lifecycle helpers | [pm-ugqx](../.agents/pm/epics/pm-ugqx.toon) | Existing package-author SDK surfaces stay public; package lifecycle can move behind SDK runtime helpers. |
 | `src/mcp/**` | [pm-usfg](../.agents/pm/epics/pm-usfg.toon) | MCP tools should call SDK primitives directly once each family is promoted. |
 

package/docs/examples/sdk-custom-tool/README.md

@@ -0,0 +1,27 @@
+# SDK-only custom project tool
+
+Tracked by [pm-cbwg](../../../.agents/pm/features/pm-cbwg.toon) and
+[pm-w89s](../../../.agents/pm/stories/pm-w89s.toon).
+
+This package is the end-to-end acceptance proof for pm's universal-tool goal.
+It is a standalone domain CLI, not an extension: its implementation imports
+only `@unbrained/pm-cli/sdk` and composes customization, lifecycle, query,
+context, annotation, linked-resource, relationship, and governance primitives.
+
+Run the acceptance suite, including the executable adapter contract, against
+fresh temporary workspaces:
+
+```bash
+node scripts/run-tests.mjs test -- tests/unit/sdk/sdk-universal-tool-exemplar.spec.ts
+```
+
+The `pm-custom` flow registers a `Deliverable` type and `reviewing` status,
+creates a related parent/child graph, records comments/notes/learnings, links
+workspace evidence, reads list/search/context/dependency projections, closes
+the work with resolution evidence, and returns health/history verification as
+structured JSON. It never imports `src/core`, `src/cli`, or spawns `pm`.
+
+Use [src/index.ts](src/index.ts) as the copyable library pattern and
+[src/cli.ts](src/cli.ts) as the process-independent executable adapter. The
+package maps `pm-custom` to [src/entry.ts](src/entry.ts), which wires that
+adapter to Node.js arguments, author identity, output streams, and exit status.

package/docs/examples/sdk-custom-tool/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@unbrained/pm-sdk-custom-tool",
+  "version": "2026.7.16",
+  "private": true,
+  "type": "module",
+  "description": "SDK-only exemplar for building a complete custom project-management tool on pm primitives.",
+  "bin": {
+    "pm-custom": "src/entry.ts"
+  },
+  "peerDependencies": {
+    "@unbrained/pm-cli": ">=2026.7.16"
+  }
+}

package/docs/examples/sdk-custom-tool/src/cli.ts

@@ -0,0 +1,36 @@
+/**
+ * @module docs/examples/sdk-custom-tool/cli
+ *
+ * Runs the SDK-only exemplar as a small domain CLI.
+ */
+import {
+  runUniversalToolScenario,
+  type UniversalToolScenarioOptions,
+  type UniversalToolScenarioResult,
+} from "./index.ts";
+
+/** Scenario boundary accepted by the executable adapter. */
+export type UniversalToolScenarioRunner = (
+  options: UniversalToolScenarioOptions,
+) => Promise<UniversalToolScenarioResult>;
+
+/** Run the exemplar CLI against process-independent argument and I/O ports. */
+export async function runUniversalToolCli(
+  args: string[],
+  author: string | undefined,
+  writeOutput: (value: string) => void,
+  writeError: (value: string) => void,
+  runScenario: UniversalToolScenarioRunner = runUniversalToolScenario,
+): Promise<number> {
+  const workspace = args[0];
+  if (!workspace) {
+    writeError("Usage: pm-custom <workspace>\n");
+    return 2;
+  }
+  const result = await runScenario({
+    workspace,
+    author: author ?? "pm-sdk-custom-tool",
+  });
+  writeOutput(`${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}

package/docs/examples/sdk-custom-tool/src/entry.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * @module docs/examples/sdk-custom-tool/entry
+ *
+ * Connects the process-independent SDK exemplar adapter to Node.js process
+ * arguments, author identity, output streams, and exit status.
+ */
+import { runUniversalToolCli } from "./cli.ts";
+
+process.exitCode = await runUniversalToolCli(
+  process.argv.slice(2),
+  process.env.PM_AUTHOR,
+  (value) => process.stdout.write(value),
+  (value) => process.stderr.write(value),
+);