@unbrained/pm-cli 2026.10.13 → 2026.10.15

package/dist/sdk/governance/health.d.ts

@@ -5,7 +5,7 @@ import { resolveVectorStores } from "../../core/search/vector-stores.js";
 import type { GlobalOptions } from "../../core/shared/command-types.js";
 import { type HistoryAuthorAttributionScan } from "../author-attribution.js";
 import type { PmSettings } from "../../types/index.js";
-import { buildCapabilityContractMetadata, collectUnknownCapabilityGuidance } from "../extension/doctor.js";
+import { buildCapabilityContractMetadata,collectUnknownCapabilityGuidance } from "../extension/doctor.js";
 import { type StaleInProgressScan } from "./stale-work.js";
 import { type HierarchyIntegrityAnalysis } from "../graph/hierarchy-integrity.js";
 type HealthStatus = "ok" | "warn";
@@ -13,254 +13,254 @@ type MigrationRuntimeStatus = "pending" | "failed" | "applied";
 /** Documents the health check payload exchanged by command, SDK, and package integrations. */
 export interface HealthCheck {
 /** Value that configures or reports name for this contract. */
-name: "settings" | "directories" | "settings_values" | "telemetry" | "extensions" | "storage" | "locks" | "integrity" | "history_drift" | "vectorization";
+name:"settings" | "directories" | "settings_values" | "telemetry" | "extensions" | "storage" | "locks" | "integrity" | "history_drift" | "vectorization";
 /** Lifecycle state reported for status. */
-status: HealthStatus;
+status:HealthStatus;
 /** True when this check has no gate-failing findings; advisory warnings retain warn status. */
-ok: boolean;
+ok:boolean;
 /** Value that configures or reports details for this contract. */
-details: Record<string, unknown>;
+details:Record<string,unknown>;
 }
 /** One warning indexed to the check, severity, and safe next action that decide health. */
 export interface HealthFinding {
 /** Original stable warning token. */
-warning: string;
+warning:string;
 /** Stable colon-delimited warning code. */
-code: string;
+code:string;
 /** Health check that owns the finding. */
-check: HealthCheck["name"];
+check:HealthCheck["name"];
 /** Whether the finding blocks the top-level health verdict. */
-severity: "advisory" | "gate_failing";
+severity:"advisory" | "gate_failing";
 /** Executable remediation when one is safe and fully specified. */
-remediation?: string;
+remediation?:string;
 /** Explicit refusal when automatic remediation would require operator choices. */
-disposition?: "no_safe_automatic_remediation";
+disposition?:"no_safe_automatic_remediation";
 }
 /** Documents the health result payload exchanged by command, SDK, and package integrations. */
 export interface HealthResult {
 /** Whether the operation completed without a blocking failure. */
-ok: boolean;
+ok:boolean;
 /** Invocation policy and process outcome; `ok` is the authoritative health predicate. */
-verdict?: {
+verdict?:{
 /** Field consumers must branch on to decide project health. */
-authority: "ok";
+authority:"ok";
 /** Present when a failed verdict sets a nonzero process exit; omitted means false. */
-strict_exit?: true;
+strict_exit?:true;
 /** Present when missing merge drivers block this invocation; omitted means false. */
-require_merge_drivers?: true;
+require_merge_drivers?:true;
 /** Process exit code for this invocation, independent of diagnostic severity. */
-exit_code: number;
+exit_code:number;
 };
 /** Value that configures or reports checks for this contract. */
-checks: HealthCheck[];
+checks:HealthCheck[];
 /** Number of warning entries represented by this result. */
-warning_count?: number;
+warning_count?:number;
 /** Maximum warning rows retained in every projection. */
-warning_limit?: number;
+warning_limit?:number;
 /** Whether warning rows were omitted after the declared limit. */
-warnings_truncated?: boolean;
+warnings_truncated?:boolean;
 /** Value that configures or reports warnings for this contract. */
-warnings: string[];
+warnings:string[];
 /** Every retained warning indexed to its owning check and severity. */
-findings: HealthFinding[];
+findings:HealthFinding[];
 /** Exact gate-failing warning tokens that make `ok` false. */
-failed_because: string[];
+failed_because:string[];
 /** Value that configures or reports projection for this contract. */
-projection?: {
-mode: "brief" | "summary" | "full";
-warning_count: number;
-warnings_truncated: boolean;
-detail_limit: number;
-omitted_checks?: HealthCheck["name"][];
+projection?:{
+mode:"brief" | "summary" | "full";
+warning_count:number;
+warnings_truncated:boolean;
+detail_limit:number;
+omitted_checks?:HealthCheck["name"][];
 };
 /** ISO 8601 timestamp recording when generated occurred. */
-generated_at: string;
+generated_at:string;
 }
 /** Documents the run health options payload exchanged by command, SDK, and package integrations. */
 export interface RunHealthOptions {
 /** Match CLI strict-exit policy: require merge drivers and exit nonzero on blocking findings. */
-strictExit?: boolean;
+strictExit?:boolean;
 /** Compatibility alias for strictExit across SDK and MCP invocations. */
-failOnWarn?: boolean;
+failOnWarn?:boolean;
 /** Value that configures or reports strict directories for this contract. */
-strictDirectories?: boolean;
+strictDirectories?:boolean;
 /** Treat absent clone-local merge drivers as a required health failure instead of an advisory. */
-requireMergeDrivers?: boolean;
+requireMergeDrivers?:boolean;
 /** Preserve the legacy compact check projection while keeping diagnostics read-only. */
-checkOnly?: boolean;
+checkOnly?:boolean;
 /** Value that configures or reports check telemetry for this contract. */
-checkTelemetry?: boolean;
+checkTelemetry?:boolean;
 /** Explicitly document that vector refresh is disabled. */
-noRefresh?: boolean;
+noRefresh?:boolean;
 /** Opt in to the only mutating health operation: refreshing stale vectors. */
-refreshVectors?: boolean;
+refreshVectors?:boolean;
 /** Value that configures or reports verbose stale items for this contract. */
-verboseStaleItems?: boolean;
+verboseStaleItems?:boolean;
 /** Include the complete actionable unknown-author coordinate list. */
-verboseAuthorEvents?: boolean;
+verboseAuthorEvents?:boolean;
 /** Value that configures or reports skip vectors for this contract. */
-skipVectors?: boolean;
+skipVectors?:boolean;
 /** Skip optional integrity work; full output and required merge-driver enforcement still run it. */
-skipIntegrity?: boolean;
+skipIntegrity?:boolean;
 /** Value that configures or reports skip drift for this contract. */
-skipDrift?: boolean;
+skipDrift?:boolean;
 /** Value that configures or reports full for this contract. */
-full?: boolean;
+full?:boolean;
 /** Value that configures or reports brief for this contract. */
-brief?: boolean;
+brief?:boolean;
 /** Value that configures or reports summary for this contract. */
-summary?: boolean;
+summary?:boolean;
 }
 interface VectorRefreshPolicy {
-enabled: boolean;
-checkOnly: boolean;
-noRefresh: boolean;
-refreshVectors: boolean;
+enabled:boolean;
+checkOnly:boolean;
+noRefresh:boolean;
+refreshVectors:boolean;
 }
 interface MigrationStatusEntry {
-layer: "global" | "project";
-name: string;
-id: string;
-status: MigrationRuntimeStatus;
-reason?: string;
+layer:"global" | "project";
+name:string;
+id:string;
+status:MigrationRuntimeStatus;
+reason?:string;
 }
 interface MigrationStatusSummary {
-applied: MigrationStatusEntry[];
-pending: MigrationStatusEntry[];
-failed: MigrationStatusEntry[];
-applied_count: number;
-pending_count: number;
-failed_count: number;
+applied:MigrationStatusEntry[];
+pending:MigrationStatusEntry[];
+failed:MigrationStatusEntry[];
+applied_count:number;
+pending_count:number;
+failed_count:number;
 }
 interface ExtensionHealthTriageSummary {
-status: "ok" | "warn";
-warning_count: number;
-warning_codes: string[];
-load_failure_count: number;
-activation_failure_count: number;
-migration_failed_count: number;
-migration_pending_count: number;
-managed_state_warning_count: number;
-managed_extension_entries_count: number;
-unmanaged_loaded_extension_count: number;
-unmanaged_loaded_extensions: string[];
-unmanaged_expected_extension_count: number;
-unmanaged_expected_extensions: string[];
-unmanaged_action_required_extension_count: number;
-unmanaged_action_required_extensions: string[];
-update_health_coverage: "full" | "partial";
-update_health_partial: boolean;
-unknown_capability_count: number;
-top_warnings: string[];
-remediation: string[];
+status:"ok" | "warn";
+warning_count:number;
+warning_codes:string[];
+load_failure_count:number;
+activation_failure_count:number;
+migration_failed_count:number;
+migration_pending_count:number;
+managed_state_warning_count:number;
+managed_extension_entries_count:number;
+unmanaged_loaded_extension_count:number;
+unmanaged_loaded_extensions:string[];
+unmanaged_expected_extension_count:number;
+unmanaged_expected_extensions:string[];
+unmanaged_action_required_extension_count:number;
+unmanaged_action_required_extensions:string[];
+update_health_coverage:"full" | "partial";
+update_health_partial:boolean;
+unknown_capability_count:number;
+top_warnings:string[];
+remediation:string[];
 }
 /** Advisory warnings are surfaced for visibility but never flip overall health to not-ok. Telemetry is opt-out, non-critical observability: a queued/unreachable telemetry endpoint or corrupt local telemetry state is not a project-health failure and must not block agents that gate on `pm health` `ok`. History over-compaction-threshold warnings are likewise advisory maintenance hints — a deep stream is healthy, just a candidate for `pm history-compact`. Invalid legacy provenance remains advisory until an operator explicitly applies the privacy-safe history normalizer. */
-declare function isAdvisoryHealthWarning(warning: string, requireMergeDrivers?: boolean): boolean;
-declare function warningCode(value: string): string;
-declare function normalizeExtensionNameForMatch(value: string): string;
-declare function isExpectedUnmanagedExtension(name: string, directory: string): boolean;
-declare function isDirectory(targetPath: string): Promise<boolean>;
-declare function listItemDocumentPaths(pmRoot: string, typeToFolder: Record<string, string>): Promise<string[]>;
-declare function buildHierarchyIntegrityWarnings(analysis: HierarchyIntegrityAnalysis): string[];
-declare function buildExtensionHealthTriageSummary(warnings: string[], loadFailureCount: number, activationFailureCount: number, migrationStatus: MigrationStatusSummary, managedStateWarningCount: number, managedExtensionEntriesCount: number, unmanagedLoadedExtensions: string[], unmanagedExpectedExtensions: string[], unmanagedActionRequiredExtensions: string[]): ExtensionHealthTriageSummary;
-declare function summarizeRecordList(value: unknown, limit: number): {
-count: number;
-sample: unknown[];
-truncated: boolean;
+declare function isAdvisoryHealthWarning(warning:string,requireMergeDrivers?:boolean):boolean;
+declare function warningCode(value:string):string;
+declare function normalizeExtensionNameForMatch(value:string):string;
+declare function isExpectedUnmanagedExtension(name:string,directory:string):boolean;
+declare function isDirectory(targetPath:string):Promise<boolean>;
+declare function listItemDocumentPaths(pmRoot:string,typeToFolder:Record<string,string>):Promise<string[]>;
+declare function buildHierarchyIntegrityWarnings(analysis:HierarchyIntegrityAnalysis):string[];
+declare function buildExtensionHealthTriageSummary(warnings:string[],loadFailureCount:number,activationFailureCount:number,migrationStatus:MigrationStatusSummary,managedStateWarningCount:number,managedExtensionEntriesCount:number,unmanagedLoadedExtensions:string[],unmanagedExpectedExtensions:string[],unmanagedActionRequiredExtensions:string[]):ExtensionHealthTriageSummary;
+declare function summarizeRecordList(value:unknown,limit:number):{
+count:number;
+sample:unknown[];
+truncated:boolean;
 };
-declare function summarizeExtensionList(value: unknown, limit: number): {
-count: number;
-sample: unknown[];
-truncated: boolean;
+declare function summarizeExtensionList(value:unknown,limit:number):{
+count:number;
+sample:unknown[];
+truncated:boolean;
 };
-declare function summarizeStringList(value: unknown, limit: number): {
-count: number;
-sample: string[];
-truncated: boolean;
+declare function summarizeStringList(value:unknown,limit:number):{
+count:number;
+sample:string[];
+truncated:boolean;
 };
-declare function summarizeHealthCheckDetails(check: HealthCheck, limit: number): Record<string, unknown>;
-declare function selectStaleItemDetail(values: string[], verboseStaleItems: boolean): {
-values: string[];
-truncated: boolean;
-total: number;
+declare function summarizeHealthCheckDetails(check:HealthCheck,limit:number):Record<string,unknown>;
+declare function selectStaleItemDetail(values:string[],verboseStaleItems:boolean):{
+values:string[];
+truncated:boolean;
+total:number;
 };
 type VectorizationRuntimeDefaults = ReturnType<typeof resolveSettingsWithSemanticRuntimeDefaults>;
 type VectorizationProviderResolution = ReturnType<typeof resolveEmbeddingProviders>;
 type VectorizationStoreResolution = ReturnType<typeof resolveVectorStores>;
 interface VectorizationRuntimeSnapshot {
-runtimeDefaults: VectorizationRuntimeDefaults;
-providerResolution: VectorizationProviderResolution;
-vectorStoreResolution: VectorizationStoreResolution;
-runtimeEmbeddingIdentity: ReturnType<typeof buildVectorizationEmbeddingIdentity> | null;
-semanticRuntimeAvailable: boolean;
+runtimeDefaults:VectorizationRuntimeDefaults;
+providerResolution:VectorizationProviderResolution;
+vectorStoreResolution:VectorizationStoreResolution;
+runtimeEmbeddingIdentity:ReturnType<typeof buildVectorizationEmbeddingIdentity> | null;
+semanticRuntimeAvailable:boolean;
 }
-declare function telemetryEnvFlagEnabled(envKey: "PM_TELEMETRY_DISABLED" | "PM_TELEMETRY_OTEL_DISABLED" | "PM_NO_TELEMETRY" | "PM_TELEMETRY_INLINE_FLUSH"): boolean;
-declare function normalizeEndpointForDisplay(rawEndpoint: string): string;
-declare function parseTelemetryQueue(raw: string): {
-validEntries: number;
-invalidRows: number;
-totalRows: number;
-highRetryEntries: number;
-maxAttempts: number;
+declare function telemetryEnvFlagEnabled(envKey:"PM_TELEMETRY_DISABLED" | "PM_TELEMETRY_OTEL_DISABLED" | "PM_NO_TELEMETRY" | "PM_TELEMETRY_INLINE_FLUSH"):boolean;
+declare function normalizeEndpointForDisplay(rawEndpoint:string):string;
+declare function parseTelemetryQueue(raw:string):{
+validEntries:number;
+invalidRows:number;
+totalRows:number;
+highRetryEntries:number;
+maxAttempts:number;
 };
-declare function probeTelemetryEndpointHealth(endpoint: string): Promise<{
-probe_url: string;
-ok: boolean;
-status?: number;
-max_schema_version?: string;
-error?: string;
+declare function probeTelemetryEndpointHealth(endpoint:string):Promise<{
+probe_url:string;
+ok:boolean;
+status?:number;
+max_schema_version?:string;
+error?:string;
 }>;
-declare function buildVectorizationProviderDetails(settings: PmSettings, snapshot: VectorizationRuntimeSnapshot): Record<string, unknown>;
-declare function resolveVectorRefreshPolicy(options: RunHealthOptions): VectorRefreshPolicy;
+declare function buildVectorizationProviderDetails(settings:PmSettings,snapshot:VectorizationRuntimeSnapshot):Record<string,unknown>;
+declare function resolveVectorRefreshPolicy(options:RunHealthOptions):VectorRefreshPolicy;
 interface HealthSkipPolicy {
-summaryMode: boolean;
-skipIntegrity: boolean;
-skipDrift: boolean;
-skipVectors: boolean;
+summaryMode:boolean;
+skipIntegrity:boolean;
+skipDrift:boolean;
+skipVectors:boolean;
 }
-declare function resolveHealthSkipPolicy(options: RunHealthOptions): HealthSkipPolicy;
-declare function buildStaleInProgressHealthSummary(scan: StaleInProgressScan): {
-scan: StaleInProgressScan;
-warnings: string[];
+declare function resolveHealthSkipPolicy(options:RunHealthOptions):HealthSkipPolicy;
+declare function buildStaleInProgressHealthSummary(scan:StaleInProgressScan):{
+scan:StaleInProgressScan;
+warnings:string[];
 };
 /** Index every warning to exactly one health check, severity, and safe next action. */
-declare function buildHealthFindings(params: {
-warnings: string[];
-checks: HealthCheck[];
-remediationSources: Record<HealthCheck["name"], string[]>;
-requireMergeDrivers: boolean;
-}): HealthFinding[];
-declare function projectHealthResult(result: HealthResult, options: RunHealthOptions, summaryMode: boolean): HealthResult;
+declare function buildHealthFindings(params:{
+warnings:string[];
+checks:HealthCheck[];
+remediationSources:Record<HealthCheck["name"],string[]>;
+requireMergeDrivers:boolean;
+}):HealthFinding[];
+declare function projectHealthResult(result:HealthResult,options:RunHealthOptions,summaryMode:boolean):HealthResult;
 /** Inspect tracker integrity and runtime configuration, keeping optional guidance and telemetry failures diagnostic. */
-export declare function runHealth(global: GlobalOptions, options?: RunHealthOptions): Promise<HealthResult>;
+export declare function runHealth(global:GlobalOptions,options?:RunHealthOptions):Promise<HealthResult>;
 /** Public contract for test only health command, shared by SDK and presentation-layer consumers. */
-export declare const _testOnlyHealthCommand: {
-buildHierarchyIntegrityWarnings: typeof buildHierarchyIntegrityWarnings;
-buildExtensionHealthTriageSummary: typeof buildExtensionHealthTriageSummary;
-buildHealthFindings: typeof buildHealthFindings;
-buildCapabilityContractMetadata: typeof buildCapabilityContractMetadata;
-buildStaleInProgressHealthSummary: typeof buildStaleInProgressHealthSummary;
-buildVectorizationProviderDetails: typeof buildVectorizationProviderDetails;
-collectUnknownCapabilityGuidance: typeof collectUnknownCapabilityGuidance;
-isAdvisoryHealthWarning: typeof isAdvisoryHealthWarning;
-isDirectory: typeof isDirectory;
-isExpectedUnmanagedExtension: typeof isExpectedUnmanagedExtension;
-listItemDocumentPaths: typeof listItemDocumentPaths;
-normalizeEndpointForDisplay: typeof normalizeEndpointForDisplay;
-normalizeExtensionNameForMatch: typeof normalizeExtensionNameForMatch;
-parseTelemetryQueue: typeof parseTelemetryQueue;
-probeTelemetryEndpointHealth: typeof probeTelemetryEndpointHealth;
-projectHealthResult: typeof projectHealthResult;
-resolveActionableUnknownAuthorEventCount: (authorAttribution: HistoryAuthorAttributionScan) => number;
-resolveHealthSkipPolicy: typeof resolveHealthSkipPolicy;
-resolveUnknownAuthorEventCount: (authorAttribution: HistoryAuthorAttributionScan) => number;
-resolveVectorRefreshPolicy: typeof resolveVectorRefreshPolicy;
-selectStaleItemDetail: typeof selectStaleItemDetail;
-summarizeHealthCheckDetails: typeof summarizeHealthCheckDetails;
-summarizeExtensionList: typeof summarizeExtensionList;
-summarizeRecordList: typeof summarizeRecordList;
-summarizeStringList: typeof summarizeStringList;
-telemetryEnvFlagEnabled: typeof telemetryEnvFlagEnabled;
-warningCode: typeof warningCode;
+export declare const _testOnlyHealthCommand:{
+buildHierarchyIntegrityWarnings:typeof buildHierarchyIntegrityWarnings;
+buildExtensionHealthTriageSummary:typeof buildExtensionHealthTriageSummary;
+buildHealthFindings:typeof buildHealthFindings;
+buildCapabilityContractMetadata:typeof buildCapabilityContractMetadata;
+buildStaleInProgressHealthSummary:typeof buildStaleInProgressHealthSummary;
+buildVectorizationProviderDetails:typeof buildVectorizationProviderDetails;
+collectUnknownCapabilityGuidance:typeof collectUnknownCapabilityGuidance;
+isAdvisoryHealthWarning:typeof isAdvisoryHealthWarning;
+isDirectory:typeof isDirectory;
+isExpectedUnmanagedExtension:typeof isExpectedUnmanagedExtension;
+listItemDocumentPaths:typeof listItemDocumentPaths;
+normalizeEndpointForDisplay:typeof normalizeEndpointForDisplay;
+normalizeExtensionNameForMatch:typeof normalizeExtensionNameForMatch;
+parseTelemetryQueue:typeof parseTelemetryQueue;
+probeTelemetryEndpointHealth:typeof probeTelemetryEndpointHealth;
+projectHealthResult:typeof projectHealthResult;
+resolveActionableUnknownAuthorEventCount:(authorAttribution:HistoryAuthorAttributionScan) => number;
+resolveHealthSkipPolicy:typeof resolveHealthSkipPolicy;
+resolveUnknownAuthorEventCount:(authorAttribution:HistoryAuthorAttributionScan) => number;
+resolveVectorRefreshPolicy:typeof resolveVectorRefreshPolicy;
+selectStaleItemDetail:typeof selectStaleItemDetail;
+summarizeHealthCheckDetails:typeof summarizeHealthCheckDetails;
+summarizeExtensionList:typeof summarizeExtensionList;
+summarizeRecordList:typeof summarizeRecordList;
+summarizeStringList:typeof summarizeStringList;
+telemetryEnvFlagEnabled:typeof telemetryEnvFlagEnabled;
+warningCode:typeof warningCode;
 };
 export {};