@unbrained/pm-cli 2026.10.11 → 2026.10.13

package/dist/core/lock/lock-gc.d.ts

@@ -10,75 +10,75 @@
  */
 /** Documents the stale lock scan entry payload exchanged by command, SDK, and package integrations. */
 export interface StaleLockScanEntry {
-    /** e.g. "pm-abc1.lock" */
-    file: string;
-    /** parsed id, or null if unparseable */
-    id: string | null;
-    /** Value that configures or reports owner for this contract. */
-    owner: string | null;
-    /** ISO 8601 timestamp recording when created occurred. */
-    created_at: string | null;
-    /** Value that configures or reports ttl seconds for this contract. */
-    ttl_seconds: number | null;
-    /** floor((now - created_at)/1000), null if unparseable */
-    age_seconds: number | null;
-    /** true only when classified expired */
-    stale: boolean;
-    /** Value that configures or reports reason for this contract. */
-    reason: "expired" | "active" | "unparseable";
+/** e.g. "pm-abc1.lock" */
+file: string;
+/** parsed id, or null if unparseable */
+id: string | null;
+/** Value that configures or reports owner for this contract. */
+owner: string | null;
+/** ISO 8601 timestamp recording when created occurred. */
+created_at: string | null;
+/** Value that configures or reports ttl seconds for this contract. */
+ttl_seconds: number | null;
+/** floor((now - created_at)/1000), null if unparseable */
+age_seconds: number | null;
+/** true only when classified expired */
+stale: boolean;
+/** Value that configures or reports reason for this contract. */
+reason: "expired" | "active" | "unparseable";
 }
 /** Documents the lock gc hooks payload exchanged by command, SDK, and package integrations. */
 export interface LockGcHooks {
-    /** Value that configures or reports on read for this contract. */
-    onRead?: (lockPath: string) => Promise<string[]> | string[];
-    /** Value that configures or reports on write for this contract. */
-    onWrite?: (lockPath: string) => Promise<string[]> | string[];
+/** Value that configures or reports on read for this contract. */
+onRead?: (lockPath: string) => Promise<string[]> | string[];
+/** Value that configures or reports on write for this contract. */
+onWrite?: (lockPath: string) => Promise<string[]> | string[];
 }
 /** Documents the lock gc options payload exchanged by command, SDK, and package integrations. */
 export interface LockGcOptions {
-    /** Value that configures or reports dry run for this contract. */
-    dryRun: boolean;
-    /** epoch ms; defaults to Date.now() — injectable for deterministic tests */
-    now?: number;
-    /** Value that configures or reports hooks for this contract. */
-    hooks?: LockGcHooks;
+/** Value that configures or reports dry run for this contract. */
+dryRun: boolean;
+/** epoch ms; defaults to Date.now() — injectable for deterministic tests */
+now?: number;
+/** Value that configures or reports hooks for this contract. */
+hooks?: LockGcHooks;
 }
 /** Documents the lock gc result payload exchanged by command, SDK, and package integrations. */
 export interface LockGcResult {
-    /** number of *.lock files examined */
-    scanned: number;
-    /** relative paths like "locks/pm-abc1.lock" (removed, or would-remove under dryRun) */
-    removed: string[];
-    /** relative paths retained (active OR unparseable — never delete what we can't reason about) */
-    retained: string[];
-    /** Value that configures or reports warnings for this contract. */
-    warnings: string[];
-    /** one per scanned *.lock file, sorted by file name asc */
-    entries: StaleLockScanEntry[];
+/** number of *.lock files examined */
+scanned: number;
+/** relative paths like "locks/pm-abc1.lock" (removed, or would-remove under dryRun) */
+removed: string[];
+/** relative paths retained (active OR unparseable — never delete what we can't reason about) */
+retained: string[];
+/** Value that configures or reports warnings for this contract. */
+warnings: string[];
+/** one per scanned *.lock file, sorted by file name asc */
+entries: StaleLockScanEntry[];
 }
 /** Fine-grained classification outcome for one readable lock file's content. `unparseable_json` and `invalid_timestamp` both surface as the coarse `reason: "unparseable"` on the scan entry (gc retains both), but stay distinct here so callers can emit precise warnings. */
 export type LockClassificationDetail = "active" | "expired" | "unparseable_json" | "invalid_timestamp";
 /** Documents the lock content classification payload exchanged by command, SDK, and package integrations. */
 export interface LockContentClassification {
-    /** Value that configures or reports detail for this contract. */
-    detail: LockClassificationDetail;
-    /** Value that configures or reports entry for this contract. */
-    entry: StaleLockScanEntry;
+/** Value that configures or reports detail for this contract. */
+detail: LockClassificationDetail;
+/** Value that configures or reports entry for this contract. */
+entry: StaleLockScanEntry;
 }
 /** Pure classification of one lock file's raw content against `nowMs`. This is the single staleness/parse policy shared by `pm gc --scope locks` (which acts on it) and the `pm health` locks check (which only reports it). */
 export declare function classifyLockContent(file: string, raw: string, nowMs: number): LockContentClassification;
 /** Documents the lock health scan payload exchanged by command, SDK, and package integrations. */
 export interface LockHealthScan {
-    /** number of *.lock files examined (ghost files that vanish mid-scan are skipped) */
-    scanned: number;
-    /** Number of active lock entries represented by this result. */
-    active_lock_count: number;
-    /** Number of stale lock entries represented by this result. */
-    stale_lock_count: number;
-    /** Number of unreadable lock entries represented by this result. */
-    unreadable_lock_count: number;
-    /** invalid JSON, wrong shape, or an unparseable created_at timestamp */
-    unparseable_lock_count: number;
+/** number of *.lock files examined (ghost files that vanish mid-scan are skipped) */
+scanned: number;
+/** Number of active lock entries represented by this result. */
+active_lock_count: number;
+/** Number of stale lock entries represented by this result. */
+stale_lock_count: number;
+/** Number of unreadable lock entries represented by this result. */
+unreadable_lock_count: number;
+/** invalid JSON, wrong shape, or an unparseable created_at timestamp */
+unparseable_lock_count: number;
 }
 /** Read-only locks scan for `pm health`: classifies every lock file with the same policy `pm gc --scope locks` uses but never removes anything. */
 export declare function scanLockHealth(pmRoot: string, now?: number): Promise<LockHealthScan>;

package/dist/core/lock/lock.d.ts

@@ -1,26 +1,26 @@
 interface LockInfo {
-    id: string;
-    pid: number;
-    owner: string;
-    token?: string;
-    created_at: string;
-    ttl_seconds: number;
+id: string;
+pid: number;
+owner: string;
+token?: string;
+created_at: string;
+ttl_seconds: number;
 }
 interface LockReadResult {
-    info: LockInfo | null;
-    warnings: string[];
+info: LockInfo | null;
+warnings: string[];
 }
 interface StaleLockRemovalResult {
-    lockInfo: LockReadResult;
-    shouldRetryCreate: boolean;
-    staleRemovalCounted: boolean;
+lockInfo: LockReadResult;
+shouldRetryCreate: boolean;
+staleRemovalCounted: boolean;
 }
 /** Stable operating-system identity for a process when the host exposes one. */
 export interface ProcessIdentity {
-    /** Operating-system process identifier captured with the owner record. */
-    pid: number;
-    /** Host process-start coordinate that distinguishes reuse of the same PID. */
-    process_start_identity?: string;
+/** Operating-system process identifier captured with the owner record. */
+pid: number;
+/** Host process-start coordinate that distinguishes reuse of the same PID. */
+process_start_identity?: string;
 }
 declare function parseLockInfo(raw: string): LockReadResult;
 declare function readLockInfo(lockPath: string, emitReadHook?: boolean): Promise<LockReadResult>;
@@ -51,30 +51,30 @@ export declare function captureProcessIdentity(pid?: number): Promise<ProcessIde
 export declare function isProcessIdentityAlive(identity: ProcessIdentity, unverifiedAgeMs: number, maxUnverifiedAgeMs: number): Promise<boolean>;
 declare function acquireStaleCleanupGate(lockPath: string, _id: string): Promise<(() => Promise<void>) | null>;
 declare function removeConfirmedStaleLock(params: {
-    lockPath: string;
-    id: string;
-    ttlSeconds: number;
-    force: boolean;
-    forceRequiredForStaleLock: boolean;
-    staleRemovals: number;
-    waitBudgetMs: number;
-    startedAtMs: number;
-    fallbackLockInfo: LockReadResult;
+lockPath: string;
+id: string;
+ttlSeconds: number;
+force: boolean;
+forceRequiredForStaleLock: boolean;
+staleRemovals: number;
+waitBudgetMs: number;
+startedAtMs: number;
+fallbackLockInfo: LockReadResult;
 }): Promise<StaleLockRemovalResult>;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export declare const _testOnly: {
-    parseLockInfo: typeof parseLockInfo;
-    readLockInfo: typeof readLockInfo;
-    isErrno: typeof isErrno;
-    isLockCreateContention: typeof isLockCreateContention;
-    buildLockPayload: typeof buildLockPayload;
-    isStaleLock: typeof isStaleLock;
-    lockOwnerSuffix: typeof lockOwnerSuffix;
-    resolveLockWaitMs: typeof resolveLockWaitMs;
-    parseLinuxProcessStartIdentity: typeof parseLinuxProcessStartIdentity;
-    readProcessStartIdentity: typeof readProcessStartIdentity;
-    acquireStaleCleanupGate: typeof acquireStaleCleanupGate;
-    removeConfirmedStaleLock: typeof removeConfirmedStaleLock;
+parseLockInfo: typeof parseLockInfo;
+readLockInfo: typeof readLockInfo;
+isErrno: typeof isErrno;
+isLockCreateContention: typeof isLockCreateContention;
+buildLockPayload: typeof buildLockPayload;
+isStaleLock: typeof isStaleLock;
+lockOwnerSuffix: typeof lockOwnerSuffix;
+resolveLockWaitMs: typeof resolveLockWaitMs;
+parseLinuxProcessStartIdentity: typeof parseLinuxProcessStartIdentity;
+readProcessStartIdentity: typeof readProcessStartIdentity;
+acquireStaleCleanupGate: typeof acquireStaleCleanupGate;
+removeConfirmedStaleLock: typeof removeConfirmedStaleLock;
 };
 /**
  * Acquire a token-owned tracker lock with bounded contention waiting and
@@ -83,6 +83,6 @@ export declare const _testOnly: {
  * storage. Extension overrides retain responsibility for their own lifecycle.
  */
 export declare function acquireLock(pmRoot: string, id: string, ttlSeconds: number, owner: string, force?: boolean, forceRequiredForStaleLock?: boolean, waitMs?: number, options?: {
-    createParentDirectories?: boolean;
+createParentDirectories?: boolean;
 }): Promise<() => Promise<void>>;
 export {};

package/dist/core/output/mutation-projection.d.ts

@@ -23,12 +23,12 @@
 export type ChangedFieldsMode = "full" | "compact";
 /** Documents the mutation projection options payload exchanged by command, SDK, and package integrations. */
 export interface MutationProjectionOptions {
-    /** Defaults to "full" (unchanged output). "compact" drops the array, keeping a count. */
-    changedFields?: ChangedFieldsMode;
-    /** Return the default agent envelope: id, status, changed-field count, and close reason. */
-    compactEnvelope?: boolean;
-    /** Return only id/status for single-item mutation envelopes. */
-    idOnly?: boolean;
+/** Defaults to "full" (unchanged output). "compact" drops the array, keeping a count. */
+changedFields?: ChangedFieldsMode;
+/** Return the default agent envelope: id, status, changed-field count, and close reason. */
+compactEnvelope?: boolean;
+/** Return only id/status for single-item mutation envelopes. */
+idOnly?: boolean;
 }
 /** Returns a copy of a mutation result with the envelope `changed_fields` arrays replaced by `changed_field_count` when compact mode is requested. Inputs that are not a mutation envelope (or full mode) are returned unchanged (same reference). */
 export declare function projectMutationResult(result: unknown, options?: MutationProjectionOptions): unknown;

package/dist/core/output/output-control.d.ts

@@ -7,10 +7,10 @@
 export declare const SUPPRESS_HOST_OUTPUT_MARKER = "@unbrained/pm-cli:suppress-host-output:v1";
 /** A handled result that tells a pm host not to render or write another payload. */
 export interface SuppressedHostOutput<TResult = unknown> {
-    /** Explicit protocol marker consumed by CLI and SDK-built presentation hosts. */
-    readonly __pm_suppress_host_output: typeof SUPPRESS_HOST_OUTPUT_MARKER;
-    /** Optional structured result retained for hooks, telemetry, and embedding hosts. */
-    readonly result?: TResult;
+/** Explicit protocol marker consumed by CLI and SDK-built presentation hosts. */
+readonly __pm_suppress_host_output: typeof SUPPRESS_HOST_OUTPUT_MARKER;
+/** Optional structured result retained for hooks, telemetry, and embedding hosts. */
+readonly result?: TResult;
 }
 /** Return from a command/exporter after it has written its own streaming, binary, or pre-rendered output. */
 export declare function suppressHostOutput<TResult = undefined>(result?: TResult): SuppressedHostOutput<TResult>;

package/dist/core/output/output.d.ts

@@ -1,43 +1,43 @@
 /** Host output controls shared by command execution and extension rendering. */
 export interface OutputOptions {
-    /** Select JSON explicitly; otherwise use the host default format. */
-    json?: boolean;
-    /** Suppress process output while retaining the active command result. */
-    quiet?: boolean;
-    /** When true, mutation results drop the verbose changed_fields array (keeps changed_field_count). */
-    noChangedFields?: boolean;
-    /** When true, preserve the legacy full mutation envelope and changed-fields array. */
-    fullChangedFields?: boolean;
-    /** When true, single-item mutation results print only id and status. */
-    idOnly?: boolean;
-    /** When true, JSON output omits null, undefined, and empty containers recursively. */
-    lean?: boolean;
-    /** Attach a bounded receipt for the emitted output before the receipt itself. */
-    tokenAccounting?: boolean;
-    /** Canonical comma-separated fields or sections retained in read output. */
-    outputInclude?: string;
-    /** Canonical maximum row count retained in read output. */
-    outputLimit?: string;
-    /** Canonical estimated-token ceiling for read output. */
-    outputBudget?: string;
-    /** Canonical renderer encoding for read output. */
-    outputFormat?: "toon" | "json";
-    /** Caller-carried cross-call budget and served-item state. */
-    outputSession?: string;
-    /** Opaque budget-compaction continuation cursor. */
-    outputCursor?: string;
-    /** Include machine-readable row location and row-encoding metadata. */
-    outputRowContract?: boolean;
-    /** Fallback output format used when callers do not provide an override. */
-    defaultOutputFormat?: "toon" | "json";
-    /** Command identity used to resolve read contracts and extension overrides. */
-    command?: string;
-    /** Positional arguments passed to the output service override. */
-    commandArgs?: string[];
-    /** Command options merged with active invocation options for output contracts. */
-    commandOptions?: Record<string, unknown>;
-    /** Tracker root supplied to the output service override. */
-    pmRoot?: string;
+/** Select JSON explicitly; otherwise use the host default format. */
+json?: boolean;
+/** Suppress process output while retaining the active command result. */
+quiet?: boolean;
+/** When true, mutation results drop the verbose changed_fields array (keeps changed_field_count). */
+noChangedFields?: boolean;
+/** When true, preserve the legacy full mutation envelope and changed-fields array. */
+fullChangedFields?: boolean;
+/** When true, single-item mutation results print only id and status. */
+idOnly?: boolean;
+/** When true, JSON output omits null, undefined, and empty containers recursively. */
+lean?: boolean;
+/** Attach a bounded receipt for the emitted output before the receipt itself. */
+tokenAccounting?: boolean;
+/** Canonical comma-separated fields or sections retained in read output. */
+outputInclude?: string;
+/** Canonical maximum row count retained in read output. */
+outputLimit?: string;
+/** Canonical estimated-token ceiling for read output. */
+outputBudget?: string;
+/** Canonical renderer encoding for read output. */
+outputFormat?: "toon" | "json";
+/** Caller-carried cross-call budget and served-item state. */
+outputSession?: string;
+/** Opaque budget-compaction continuation cursor. */
+outputCursor?: string;
+/** Include machine-readable row location and row-encoding metadata. */
+outputRowContract?: boolean;
+/** Fallback output format used when callers do not provide an override. */
+defaultOutputFormat?: "toon" | "json";
+/** Command identity used to resolve read contracts and extension overrides. */
+command?: string;
+/** Positional arguments passed to the output service override. */
+commandArgs?: string[];
+/** Command options merged with active invocation options for output contracts. */
+commandOptions?: Record<string, unknown>;
+/** Tracker root supplied to the output service override. */
+pmRoot?: string;
 }
 /** Write stdout and return false when its consumer has closed the pipe. */
 export declare function writeStdout(text: string): boolean;
@@ -61,7 +61,7 @@ export declare function printResult(result: unknown, options: OutputOptions): vo
 export declare function printError(message: string): void;
 /** Internal rendering seams retained for deterministic presentation regression tests. */
 export declare const outputTestOnly: {
-    compactToonValue: typeof compactToonValue;
-    renderToonValue: typeof renderToonValue;
+compactToonValue: typeof compactToonValue;
+renderToonValue: typeof renderToonValue;
 };
 export {};

package/dist/core/output/query-summary.d.ts

@@ -9,10 +9,10 @@
  */
 /** Compact echo of filters and projection mode applied to list/search responses. */
 export interface QuerySummary {
-    /** Value that configures or reports filters for this contract. */
-    filters: Record<string, unknown>;
-    /** Value that configures or reports projection for this contract. */
-    projection: string;
+/** Value that configures or reports filters for this contract. */
+filters: Record<string, unknown>;
+/** Value that configures or reports projection for this contract. */
+projection: string;
 }
 /** Resolve the projection label implied by list/search projection options. Used when the result payload itself carries no projection metadata (the compact summary paths omit it for token efficiency). */
 export declare function resolveQueryProjectionLabel(options: Record<string, unknown>): string;
@@ -26,5 +26,5 @@ export declare function resolveQueryProjectionLabel(options: Record<string, unkn
  * paths that omit projection metadata.
  */
 export declare function withQuerySummary<T extends Record<string, unknown>>(result: T, options: Record<string, unknown>): T & {
-    query_summary: QuerySummary;
+query_summary: QuerySummary;
 };

package/dist/core/packages/manifest.d.ts

@@ -6,65 +6,65 @@ export type PmPackageResourceKind = (typeof PM_PACKAGE_RESOURCE_KINDS)[number];
 export type PmPackageResourceMap = Partial<Record<PmPackageResourceKind, string[]>>;
 /** Documents the pm package catalog link map payload exchanged by command, SDK, and package integrations. */
 export interface PmPackageCatalogLinkMap {
-    /** Value that configures or reports docs for this contract. */
-    docs?: string;
-    /** Value that configures or reports npm for this contract. */
-    npm?: string;
-    /** Value that configures or reports repository for this contract. */
-    repository?: string;
-    /** Value that configures or reports report for this contract. */
-    report?: string;
+/** Value that configures or reports docs for this contract. */
+docs?: string;
+/** Value that configures or reports npm for this contract. */
+npm?: string;
+/** Value that configures or reports repository for this contract. */
+repository?: string;
+/** Value that configures or reports report for this contract. */
+report?: string;
 }
 /** Documents the pm package catalog media map payload exchanged by command, SDK, and package integrations. */
 export interface PmPackageCatalogMediaMap {
-    /** Value that configures or reports image for this contract. */
-    image?: string;
-    /** Value that configures or reports video for this contract. */
-    video?: string;
+/** Value that configures or reports image for this contract. */
+image?: string;
+/** Value that configures or reports video for this contract. */
+video?: string;
 }
 /** Documents the pm package catalog metadata payload exchanged by command, SDK, and package integrations. */
 export interface PmPackageCatalogMetadata {
-    /** Value that configures or reports display name for this contract. */
-    display_name?: string;
-    /** Value that configures or reports category for this contract. */
-    category?: string;
-    /** Value that configures or reports summary for this contract. */
-    summary?: string;
-    /** Value that configures or reports links for this contract. */
-    links?: PmPackageCatalogLinkMap;
-    /** Value that configures or reports media for this contract. */
-    media?: PmPackageCatalogMediaMap;
-    /** Value that configures or reports tags for this contract. */
-    tags?: string[];
+/** Value that configures or reports display name for this contract. */
+display_name?: string;
+/** Value that configures or reports category for this contract. */
+category?: string;
+/** Value that configures or reports summary for this contract. */
+summary?: string;
+/** Value that configures or reports links for this contract. */
+links?: PmPackageCatalogLinkMap;
+/** Value that configures or reports media for this contract. */
+media?: PmPackageCatalogMediaMap;
+/** Value that configures or reports tags for this contract. */
+tags?: string[];
 }
 /** Documents the pm package manifest payload exchanged by command, SDK, and package integrations. */
 export interface PmPackageManifest {
-    /** Value that configures or reports source for this contract. */
-    source: "pm" | "convention";
-    /** Filesystem path used for package json resolution. */
-    package_json_path?: string;
-    /** Value that configures or reports package name for this contract. */
-    package_name?: string;
-    /** Value that configures or reports package version for this contract. */
-    package_version?: string;
-    /** Value that configures or reports package private for this contract. */
-    package_private?: boolean;
-    /** Value that configures or reports package description for this contract. */
-    package_description?: string;
-    /** Value that configures or reports package keywords for this contract. */
-    package_keywords?: string[];
-    /** Value that configures or reports package homepage for this contract. */
-    package_homepage?: string;
-    /** Value that configures or reports package repository url for this contract. */
-    package_repository_url?: string;
-    /** Value that configures or reports package bugs url for this contract. */
-    package_bugs_url?: string;
-    /** Value that configures or reports aliases for this contract. */
-    aliases?: string[];
-    /** Value that configures or reports resources for this contract. */
-    resources: PmPackageResourceMap;
-    /** Value that configures or reports catalog for this contract. */
-    catalog?: PmPackageCatalogMetadata;
+/** Value that configures or reports source for this contract. */
+source: "pm" | "convention";
+/** Filesystem path used for package json resolution. */
+package_json_path?: string;
+/** Value that configures or reports package name for this contract. */
+package_name?: string;
+/** Value that configures or reports package version for this contract. */
+package_version?: string;
+/** Value that configures or reports package private for this contract. */
+package_private?: boolean;
+/** Value that configures or reports package description for this contract. */
+package_description?: string;
+/** Value that configures or reports package keywords for this contract. */
+package_keywords?: string[];
+/** Value that configures or reports package homepage for this contract. */
+package_homepage?: string;
+/** Value that configures or reports package repository url for this contract. */
+package_repository_url?: string;
+/** Value that configures or reports package bugs url for this contract. */
+package_bugs_url?: string;
+/** Value that configures or reports aliases for this contract. */
+aliases?: string[];
+/** Value that configures or reports resources for this contract. */
+resources: PmPackageResourceMap;
+/** Value that configures or reports catalog for this contract. */
+catalog?: PmPackageCatalogMetadata;
 }
 /** Public contract for pm package conventional resource roots, shared by SDK and presentation-layer consumers. */
 export declare const PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS: Readonly<Record<PmPackageResourceKind, readonly string[]>>;