@unbrained/pm-cli 2026.7.5 → 2026.7.7

package/dist/sdk/runtime.d.ts

@@ -1,5 +1,17 @@
 import { type ExtensionRegistrationRegistry } from "../core/extensions/index.js";
+import type { GlobalOptions } from "../core/shared/command-types.js";
+import type { PmToolAction } from "./cli-contracts/enum-contracts.js";
+export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";
+import { type AggregateOptions, type AggregateResult } from "../cli/commands/index.js";
+import type { ContextOptions, ContextResult } from "../cli/commands/context.js";
+import type { GetOptions, GetResult } from "../cli/commands/get.js";
+import type { CloseManyCommandOptions } from "../cli/commands/close-many.js";
 import { type ContractsCommandOptions, type ContractsResult } from "../cli/commands/contracts.js";
+import type { ListOptions, ListResult } from "../cli/commands/list.js";
+import type { NextOptions, NextResult } from "../cli/commands/next.js";
+import type { SearchOptions, SearchResult } from "../cli/commands/search.js";
+import type { StatsCommandOptions, StatsResult } from "../cli/commands/stats.js";
+import type { UpdateManyCommandOptions } from "../cli/commands/update-many.js";
 export { getActiveExtensionRegistrations, runActiveOnReadHooks, runActiveOnWriteHooks, } from "../core/extensions/index.js";
 export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic } from "../core/fs/fs-utils.js";
 export { appendHistoryEntry, createHistoryEntry } from "../core/history/history.js";
@@ -20,6 +32,13 @@ export { isTimestampLiteral, nowIso } from "../core/shared/time.js";
 export { listAllFrontMatter, locateItem, readLocatedItem } from "../core/store/item-store.js";
 export { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 export { readSettings } from "../core/store/settings.js";
+export { runAggregate, type AggregateOptions, type AggregateResult, type AggregateRow, } from "../cli/commands/aggregate.js";
+export { CONTEXT_OUTPUT_VALUES, runContext, type BlockerEntry, type ContextFocusItem, type ContextOptions, type ContextOutputFormat, type ContextResult, type HierarchyChild, type HierarchyNode, type HotFile, type ProgressEntry, type RecentContextItem, type StaleEntry, type TestHealthSummary, type WorkloadEntry, } from "../cli/commands/context.js";
+export { runGet, type GetOptions, type GetResult, } from "../cli/commands/get.js";
+export { runList, type ListCompactResult, type ListedItem, type ListOptions, type ListResult, type ListSortField, type ListSortOrder, type ListVerboseResult, } from "../cli/commands/list.js";
+export { NEXT_OUTPUT_VALUES, runNext, type NextActionableItem, type NextBlockerRef, type NextOptions, type NextOutputFormat, type NextRecommendation, type NextResult, } from "../cli/commands/next.js";
+export { runSearch, type SearchCompactResult, type SearchHit, type SearchHitHighlight, type SearchMatchMode, type SearchOptions, type SearchResult, type SearchResultItem, type SearchVerboseResult, } from "../cli/commands/search.js";
+export { runStats, type StatsCommandOptions, type StatsResult, } from "../cli/commands/stats.js";
 export { renderCalendarMarkdown, renderCalendarToon, resolveCalendarOutputFormat, runCalendar, type CalendarOptions, type CalendarResult, } from "../cli/commands/calendar.js";
 export { renderGuideMarkdown, resolveGuideOutputFormat, runGuide, type GuideDepth, type GuideOptions, type GuideOutputFormat, type GuideResult, } from "../cli/commands/guide.js";
 export { runCompletion, type CompletionResult, type CompletionShell } from "../cli/commands/completion.js";
@@ -28,7 +47,6 @@ export { runDedupeAudit, type DedupeAuditCandidate, type DedupeAuditCluster, typ
 export { runDedupeMerge, type DedupeMergeChildReparent, type DedupeMergeCloseAction, type DedupeMergeDuplicateOutcome, type DedupeMergeOptions, type DedupeMergeResult, } from "../cli/commands/dedupe-merge.js";
 export { runNormalize, type NormalizeCommandOptions, type NormalizeResult } from "../cli/commands/normalize.js";
 export { runReindex, type ReindexOptions, type ReindexResult } from "../cli/commands/reindex.js";
-export { runSearch, type SearchOptions, type SearchResult } from "../cli/commands/search.js";
 export { loadCreateTemplateOptions, runTemplatesList, runTemplatesSave, runTemplatesShow, type CreateTemplateOptions, type TemplatesListResult, type TemplatesSaveResult, type TemplatesShowResult, } from "../cli/commands/templates.js";
 export { runTestRunsList, runTestRunsLogs, runTestRunsResume, runTestRunsStatus, runTestRunsStop, type TestRunsListCommandOptions, type TestRunsLogsCommandOptions, type TestRunsResumeCommandOptions, type TestRunsStopCommandOptions, } from "../cli/commands/test-runs.js";
 export { CONFIDENCE_TEXT_VALUES, DEPENDENCY_KIND_VALUES, BUILTIN_ITEM_TYPE_VALUES, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, RISK_VALUES, STATUS_VALUES, } from "../types/index.js";
@@ -63,11 +81,243 @@ export interface WorkspaceContracts {
     canceledStatus: string;
 }
 /**
- * Drop all memoized workspace extension registrations so the next
- * `getWorkspaceContracts` call re-loads and re-activates extensions from disk.
- * Long-lived hosts should call this after any extension or settings mutation.
+ * Names a native pm action or an extension-contributed action accepted by {@link runAction}.
  */
-export declare function clearWorkspaceContractsCache(): void;
+export type PmActionName = PmToolAction | (string & {});
+/**
+ * Plain object option bag forwarded to the same command runners used by MCP.
+ */
+export type PmActionOptions = Record<string, unknown>;
+/**
+ * Complete high-level action request for {@link runAction}.
+ */
+export type PmActionInput = PmActionOptions & {
+    /** Native or extension-contributed action name to dispatch. */
+    action: PmActionName;
+    /** Command-runner options forwarded after MCP-compatible normalization. */
+    options?: PmActionOptions;
+};
+/**
+ * Per-call arguments accepted by {@link PmClient.run}. The action name is passed
+ * as the first parameter, so an `action` property inside the args bag is rejected
+ * at compile time.
+ */
+export type PmClientRunArgs = Omit<PmActionInput, "action"> & {
+    /**
+     * Return full `changed_fields` arrays for mutation actions instead of the
+     * default compact `changed_field_count` projection.
+     */
+    fullChangedFields?: boolean;
+    /** Return only mutation item ids when supported by the action. */
+    idOnly?: boolean;
+    action?: never;
+};
+/**
+ * Command options accepted by PmClient mutation convenience methods.
+ */
+export type PmClientMutationOptions = PmActionOptions & {
+    /**
+     * Return full `changed_fields` arrays for this mutation instead of the compact
+     * SDK default.
+     */
+    fullChangedFields?: boolean;
+    /** Return only mutation item ids when supported by the action. */
+    idOnly?: boolean;
+};
+/**
+ * Stable defaults applied by {@link PmClient} to every action it runs.
+ */
+export interface PmClientOptions {
+    /** Tracker root to pass as the SDK equivalent of `--path`. */
+    pmRoot?: string;
+    /** Working directory used for workspace and extension resolution. */
+    cwd?: string;
+    /** Default mutation author forwarded to action options when absent. */
+    author?: string;
+    /** Disable extension loading for every action this client runs. */
+    noExtensions?: boolean;
+}
+/**
+ * Programmatic pm client for custom tools, CI jobs, bots, and embedded runtimes.
+ *
+ * Action execution shares the same process-wide extension activation queue used
+ * by MCP. Concurrent calls from one process are serialized across extension
+ * load, activation, dispatch, cleanup, and deactivate so active registries cannot
+ * interleave.
+ *
+ * Convenience methods accept command options only. Use {@link PmClient.run} for
+ * per-call runtime overrides such as `cwd`, `path`, or `noExtensions`.
+ */
+export declare class PmClient {
+    private readonly defaults;
+    /**
+     * Create a client with workspace, author, and extension-loading defaults.
+     */
+    constructor(options?: PmClientOptions);
+    /**
+     * Run any native or extension-contributed action through the SDK dispatcher.
+     */
+    run(action: PmActionName, args?: PmClientRunArgs): Promise<unknown>;
+    private runTyped;
+    /**
+     * Return the same context snapshot produced by `pm context`.
+     */
+    context(options?: ContextOptions): Promise<ContextResult>;
+    /**
+     * List items with the MCP/agent compact defaults.
+     */
+    list(options?: ListOptions): Promise<ListResult>;
+    /**
+     * Search items with the MCP/agent compact defaults.
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Read one item by id.
+     */
+    get(id: string, options?: GetOptions): Promise<GetResult>;
+    /**
+     * Return the ranked next-work recommendation produced by `pm next`.
+     */
+    next(options?: NextOptions): Promise<NextResult>;
+    /**
+     * Group matching items with the same semantics as `pm aggregate`.
+     */
+    aggregate(options?: AggregateOptions): Promise<AggregateResult>;
+    /**
+     * Return project tracker statistics with the same sections as `pm stats`.
+     */
+    stats(options?: StatsCommandOptions): Promise<StatsResult>;
+    /**
+     * Create an item using the same mutation path as `pm create`.
+     */
+    create(options?: PmClientMutationOptions): Promise<unknown>;
+    /**
+     * Update an item using the same mutation path as `pm update`.
+     */
+    update(id: string, options?: PmClientMutationOptions): Promise<unknown>;
+    /**
+     * Close an item using the same mutation path as `pm close`.
+     */
+    close(id: string, reason: string, options?: PmClientMutationOptions): Promise<unknown>;
+    /**
+     * Claim an item using the same mutation path as `pm claim`.
+     */
+    claim(id: string, options?: PmClientMutationOptions): Promise<unknown>;
+    /**
+     * Release an item's active claim using the same mutation path as `pm release`.
+     */
+    release(id: string, options?: PmClientMutationOptions): Promise<unknown>;
+    /**
+     * Copy an item using the same mutation path as `pm copy`.
+     */
+    copy(id: string, options?: PmClientMutationOptions): Promise<unknown>;
+    /**
+     * Delete an item using the same mutation path as `pm delete`.
+     */
+    delete(id: string, options?: PmClientMutationOptions): Promise<unknown>;
+    /**
+     * Restore an item to a history version or timestamp using `pm restore`.
+     */
+    restore(id: string, target: string, options?: PmClientMutationOptions): Promise<unknown>;
+    /**
+     * Set, clear, or read workspace focus using the same path as `pm focus`.
+     */
+    focus(id?: string, options?: PmClientMutationOptions): Promise<unknown>;
+    /**
+     * Claim an item and transition it to the workspace in-progress status.
+     */
+    startTask(id: string, options?: PmClientMutationOptions): Promise<unknown>;
+    /**
+     * Move an item back to the workspace open status and release the claim.
+     */
+    pauseTask(id: string, options?: PmClientMutationOptions): Promise<unknown>;
+    /**
+     * Close an item and release its active assignment.
+     */
+    closeTask(id: string, reason: string, options?: PmClientMutationOptions): Promise<unknown>;
+}
+/**
+ * Return the same context snapshot produced by `pm context` without constructing
+ * a reusable client.
+ */
+export declare function context(options?: ContextOptions, clientOptions?: PmClientOptions): Promise<ContextResult>;
+/**
+ * List items with the MCP/agent compact defaults without constructing a
+ * reusable client.
+ */
+export declare function list(options?: ListOptions, clientOptions?: PmClientOptions): Promise<ListResult>;
+/**
+ * Search items with the MCP/agent compact defaults without constructing a
+ * reusable client.
+ */
+export declare function search(query: string, options?: SearchOptions, clientOptions?: PmClientOptions): Promise<SearchResult>;
+/**
+ * Read one item by id without constructing a reusable client.
+ */
+export declare function get(id: string, options?: GetOptions, clientOptions?: PmClientOptions): Promise<GetResult>;
+/**
+ * Return the ranked next-work recommendation produced by `pm next` without
+ * constructing a reusable client.
+ */
+export declare function next(options?: NextOptions, clientOptions?: PmClientOptions): Promise<NextResult>;
+/**
+ * Group matching items with the same semantics as `pm aggregate` without
+ * constructing a reusable client.
+ */
+export declare function aggregate(options?: AggregateOptions, clientOptions?: PmClientOptions): Promise<AggregateResult>;
+/**
+ * Return project tracker statistics with the same sections as `pm stats`
+ * without constructing a reusable client.
+ */
+export declare function stats(options?: StatsCommandOptions, clientOptions?: PmClientOptions): Promise<StatsResult>;
+/**
+ * Create an item without constructing a reusable client.
+ */
+export declare function create(options?: PmClientMutationOptions, clientOptions?: PmClientOptions): Promise<unknown>;
+/**
+ * Update an item without constructing a reusable client.
+ */
+export declare function update(id: string, options?: PmClientMutationOptions, clientOptions?: PmClientOptions): Promise<unknown>;
+/**
+ * Close an item without constructing a reusable client.
+ */
+export declare function close(id: string, reason: string, options?: PmClientMutationOptions, clientOptions?: PmClientOptions): Promise<unknown>;
+/**
+ * Claim an item without constructing a reusable client.
+ */
+export declare function claim(id: string, options?: PmClientMutationOptions, clientOptions?: PmClientOptions): Promise<unknown>;
+/**
+ * Release an item's active claim without constructing a reusable client.
+ */
+export declare function release(id: string, options?: PmClientMutationOptions, clientOptions?: PmClientOptions): Promise<unknown>;
+/**
+ * Copy an item without constructing a reusable client.
+ */
+export declare function copy(id: string, options?: PmClientMutationOptions, clientOptions?: PmClientOptions): Promise<unknown>;
+/**
+ * Delete an item without constructing a reusable client.
+ */
+export declare function deleteItem(id: string, options?: PmClientMutationOptions, clientOptions?: PmClientOptions): Promise<unknown>;
+/**
+ * Restore an item without constructing a reusable client.
+ */
+export declare function restore(id: string, target: string, options?: PmClientMutationOptions, clientOptions?: PmClientOptions): Promise<unknown>;
+/**
+ * Set, clear, or read workspace focus without constructing a reusable client.
+ */
+export declare function focus(id?: string, options?: PmClientMutationOptions, clientOptions?: PmClientOptions): Promise<unknown>;
+/**
+ * Claim an item and transition it to in-progress without constructing a client.
+ */
+export declare function startTask(id: string, options?: PmClientMutationOptions, clientOptions?: PmClientOptions): Promise<unknown>;
+/**
+ * Move an item to open and release it without constructing a client.
+ */
+export declare function pauseTask(id: string, options?: PmClientMutationOptions, clientOptions?: PmClientOptions): Promise<unknown>;
+/**
+ * Close an item and release its active assignment without constructing a client.
+ */
+export declare function closeTask(id: string, reason: string, options?: PmClientMutationOptions, clientOptions?: PmClientOptions): Promise<unknown>;
 /**
  * Implements get workspace contracts for the public runtime surface of this module.
  */
@@ -76,4 +326,61 @@ export declare function getWorkspaceContracts(pmRoot: string, options?: Workspac
  * Implements get contracts for the public runtime surface of this module.
  */
 export declare function getContracts(pmRootOrOptions?: string | GetContractsOptions, options?: GetContractsOptions): Promise<ContractsResult>;
+declare function readScalarString(args: Record<string, unknown>, key: string): string | undefined;
+declare function readScalarStringAllowBlank(args: Record<string, unknown>, key: string): string | undefined;
+/**
+ * Read a required non-empty string from an action argument bag.
+ */
+export declare function readRequiredString(args: Record<string, unknown>, key: string): string;
+declare function globalOptions(args: Record<string, unknown>): GlobalOptions;
+declare function normalizeMcpOptionsArrays(options: Record<string, unknown>, action?: string): Record<string, unknown>;
+declare function optionsWithAuthor(args: Record<string, unknown>, action?: string): Record<string, unknown>;
+declare function withAddNoteOption(options: Record<string, unknown>): Record<string, unknown>;
+declare function withFilesDiscoveryOptions(options: Record<string, unknown>): Record<string, unknown>;
+declare function normalizeActionName(value: string): string;
+declare function normalizeCommandPath(value: string): string;
+declare function readStringArray(value: unknown): string[];
+declare function extensionOptionsFromArgs(args: Record<string, unknown>, options: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Mutation tools (create/update/close/append/update-many) return a verbose
+ * `changed_fields` array. On the agent path we drop it to a `changed_field_count`
+ * by default for token efficiency, restoring the full array only when the caller
+ * explicitly passes the MCP-level fullChangedFields=true control. Mutation options
+ * are forwarded unchanged so runtime fields named `full` remain valid user data.
+ */
+declare function withMutationCompaction(args: Record<string, unknown>, options?: Record<string, unknown> | null): {
+    changedFields: "full" | "compact";
+    idOnly: boolean;
+    runnerOptions: Record<string, unknown>;
+};
+declare function mutationListOptions(options: Record<string, unknown>): ListOptions;
+declare function closeManyOptionsFromFlat(options: Record<string, unknown>): CloseManyCommandOptions;
+declare function normalizeMcpUpdateOptions(options: Record<string, unknown>): Record<string, unknown>;
+declare function updateManyOptionsFromFlat(options: Record<string, unknown>): UpdateManyCommandOptions;
+/**
+ * Execute one native or extension-contributed pm action in-process.
+ */
+export declare function runAction(args: PmActionInput): Promise<unknown>;
+declare const actionRunnerTestHooks: {
+    closeManyOptionsFromFlat: typeof closeManyOptionsFromFlat;
+    extensionOptionsFromArgs: typeof extensionOptionsFromArgs;
+    globalOptions: typeof globalOptions;
+    mutationListOptions: typeof mutationListOptions;
+    normalizeActionName: typeof normalizeActionName;
+    normalizeCommandPath: typeof normalizeCommandPath;
+    normalizeMcpUpdateOptions: typeof normalizeMcpUpdateOptions;
+    normalizeMcpOptionsArrays: typeof normalizeMcpOptionsArrays;
+    optionsWithAuthor: typeof optionsWithAuthor;
+    readRequiredString: typeof readRequiredString;
+    readScalarString: typeof readScalarString;
+    readScalarStringAllowBlank: typeof readScalarStringAllowBlank;
+    readStringArray: typeof readStringArray;
+    updateManyOptionsFromFlat: typeof updateManyOptionsFromFlat;
+    withAddNoteOption: typeof withAddNoteOption;
+    withFilesDiscoveryOptions: typeof withFilesDiscoveryOptions;
+    withMutationCompaction: typeof withMutationCompaction;
+};
+declare global {
+    var __pmCliActionRunnerTestHooks: typeof actionRunnerTestHooks | undefined;
+}
 export type { ContractsCommandOptions, ContractsResult };