@unbrained/pm-cli 2026.7.14 → 2026.7.15

package/dist/sdk/governance/gc.js

@@ -0,0 +1,276 @@
+/**
+ * @module sdk/governance/gc
+ *
+ * Implements the pm gc 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]="68767a06-5737-53dc-91a4-aa9ef5c8c6a7")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runCheckpointGc } from "../../core/checkpoint/checkpoint-gc.js";
+import { runActiveOnIndexHooks, runActiveOnReadHooks, runActiveOnWriteHooks, } from "../../core/extensions/index.js";
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { runLockGc } from "../../core/lock/lock-gc.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { nowIso } from "../../core/shared/time.js";
+import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+const GC_SCOPE_VALUES = [
+    "index",
+    "embeddings",
+    "runtime",
+    "locks",
+    "checkpoints",
+];
+const GC_TARGETS = [
+    {
+        scope: "index",
+        relativePath: "index/manifest.json",
+        kind: "file",
+    },
+    {
+        scope: "embeddings",
+        relativePath: "search/embeddings.jsonl",
+        kind: "file",
+    },
+    {
+        scope: "embeddings",
+        relativePath: "search/vectorization-status.json",
+        kind: "file",
+    },
+    {
+        scope: "embeddings",
+        relativePath: "search/lancedb",
+        kind: "directory",
+    },
+    {
+        // Removing embeddings invalidates the whole semantic index, so the queued
+        // background-refresh work is also meaningless: a worker draining a stale
+        // queue against an empty ledger would rebuild a partial, inconsistent index
+        // (only the queued items vectorized). Clear the queue and its gate so the
+        // next mutation re-seeds from a clean slate. See core/search/background-refresh.ts.
+        scope: "embeddings",
+        relativePath: "search/pending-refresh.json",
+        kind: "file",
+    },
+    {
+        scope: "embeddings",
+        relativePath: "search/pending-refresh.gate.lock",
+        kind: "directory",
+    },
+    {
+        scope: "runtime",
+        relativePath: "runtime/test-runs",
+        kind: "directory",
+    },
+    {
+        scope: "runtime",
+        relativePath: "runtime/history-drift-cache.json",
+        kind: "file",
+    },
+];
+function isErrno(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+async function removeCacheFile(pmRoot, target, dryRun) {
+    const relativePath = target.relativePath;
+    const absolutePath = path.join(pmRoot, relativePath);
+    const warnings = await runActiveOnReadHooks({
+        path: absolutePath,
+        scope: "project",
+    });
+    try {
+        const stats = await fs.stat(absolutePath);
+        if (target.kind === "file" && !stats.isFile()) {
+            return {
+                removed: false,
+                warnings: [...warnings, `not_a_file:${relativePath}`],
+            };
+        }
+        if (target.kind === "directory" && !stats.isDirectory()) {
+            return {
+                removed: false,
+                warnings: [...warnings, `not_a_directory:${relativePath}`],
+            };
+        }
+        if (dryRun) {
+            return {
+                removed: true,
+                warnings,
+            };
+        }
+        if (target.kind === "file") {
+            await fs.unlink(absolutePath);
+        }
+        else {
+            await fs.rm(absolutePath, { recursive: true, force: true });
+        }
+        const writeWarnings = await runActiveOnWriteHooks({
+            path: absolutePath,
+            scope: "project",
+            op: "gc:remove",
+        });
+        return {
+            removed: true,
+            warnings: [...warnings, ...writeWarnings],
+        };
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            return {
+                removed: false,
+                warnings,
+            };
+        }
+        throw error;
+    }
+}
+function parseScopes(raw) {
+    if (!raw || raw.length === 0) {
+        return [...GC_SCOPE_VALUES];
+    }
+    const tokens = raw
+        .flatMap((entry) => entry.split(","))
+        .map((entry) => entry.trim().toLowerCase())
+        .filter((entry) => entry.length > 0);
+    if (tokens.length === 0) {
+        throw new PmCliError(`--scope requires at least one value (${GC_SCOPE_VALUES.join(",")})`, EXIT_CODE.USAGE);
+    }
+    const resolved = new Set();
+    for (const token of tokens) {
+        if (!GC_SCOPE_VALUES.includes(token)) {
+            throw new PmCliError(`Invalid --scope value "${token}". Expected one or more of: ${GC_SCOPE_VALUES.join(", ")}`, EXIT_CODE.USAGE);
+        }
+        resolved.add(token);
+    }
+    return GC_SCOPE_VALUES.filter((scope) => resolved.has(scope));
+}
+function buildGcGuidance(params) {
+    const guidance = [];
+    if (params.dryRun) {
+        guidance.push("Dry-run preview only: no cache artifacts were deleted.");
+    }
+    const searchScopeSelected = params.scopes.includes("index") || params.scopes.includes("embeddings");
+    const searchArtifactsAffected = params.removed.some((entry) => entry === "index/manifest.json" ||
+        entry === "search/embeddings.jsonl" ||
+        entry === "search/vectorization-status.json" ||
+        entry === "search/lancedb" ||
+        entry === "search/pending-refresh.json" ||
+        entry === "search/pending-refresh.gate.lock");
+    if (searchScopeSelected && searchArtifactsAffected) {
+        guidance.push('Search artifacts were removed; the semantic index (including any queued background refresh) is invalidated. Run "pm install search-advanced --project" if reindex is unavailable, then "pm reindex --mode keyword" (and "--mode semantic" when semantic search is enabled) before search-heavy workflows.');
+    }
+    if (params.removed.includes("runtime/history-drift-cache.json")) {
+        guidance.push('History drift cache was removed; the next "pm health" run performs a full history-drift re-scan.');
+    }
+    if (!params.dryRun &&
+        params.removed.some((entry) => entry.startsWith("checkpoints/"))) {
+        guidance.push('Aged rollback checkpoints were removed; their "pm update-many"/"pm close-many --rollback" windows are no longer recoverable.');
+    }
+    return guidance;
+}
+/** Implements run gc for the public runtime surface of this module. */
+export async function runGc(global, options = {}) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const settings = await readSettings(pmRoot);
+    const dryRun = options.dryRun === true;
+    const scopes = parseScopes(options.scope);
+    const selectedTargets = GC_TARGETS.filter((target) => scopes.includes(target.scope));
+    const removed = [];
+    const retained = [];
+    const warnings = [];
+    for (const target of selectedTargets) {
+        const result = await removeCacheFile(pmRoot, target, dryRun);
+        if (result.removed) {
+            removed.push(target.relativePath);
+        }
+        else {
+            retained.push(target.relativePath);
+        }
+        warnings.push(...result.warnings);
+    }
+    // The locks scope is not a path-based GC_TARGET: it sweeps the locks/ directory
+    // and removes only locks whose own embedded ttl has expired (crashed-process
+    // debris), retaining active and unparseable locks. See core/lock/lock-gc.ts.
+    let locksSummary;
+    if (scopes.includes("locks")) {
+        const lockResult = await runLockGc(pmRoot, {
+            dryRun,
+            hooks: {
+                onRead: (lockPath) => runActiveOnReadHooks({ path: lockPath, scope: "project" }),
+                onWrite: (lockPath) => runActiveOnWriteHooks({
+                    path: lockPath,
+                    scope: "project",
+                    op: "gc:lock_remove",
+                }),
+            },
+        });
+        removed.push(...lockResult.removed);
+        retained.push(...lockResult.retained);
+        warnings.push(...lockResult.warnings);
+        locksSummary = {
+            scanned: lockResult.scanned,
+            removed: lockResult.removed.length,
+            retained: lockResult.retained.length,
+        };
+    }
+    // The checkpoints scope is also not a path-based GC_TARGET: it sweeps
+    // checkpoints/ and removes only rollback checkpoints older than the configured
+    // checkpoints.retention_days, retaining active and unparseable files. See
+    // core/checkpoint/checkpoint-gc.ts.
+    let checkpointsSummary;
+    if (scopes.includes("checkpoints")) {
+        const retentionDays = settings.checkpoints.retention_days;
+        const checkpointResult = await runCheckpointGc(pmRoot, {
+            dryRun,
+            retentionDays,
+            hooks: {
+                onRead: (checkpointPath) => runActiveOnReadHooks({ path: checkpointPath, scope: "project" }),
+                onWrite: (checkpointPath) => runActiveOnWriteHooks({
+                    path: checkpointPath,
+                    scope: "project",
+                    op: "gc:checkpoint_remove",
+                }),
+            },
+        });
+        removed.push(...checkpointResult.removed);
+        retained.push(...checkpointResult.retained);
+        warnings.push(...checkpointResult.warnings);
+        checkpointsSummary = {
+            scanned: checkpointResult.scanned,
+            removed: checkpointResult.removed.length,
+            retained: checkpointResult.retained.length,
+            retention_days: retentionDays,
+        };
+    }
+    warnings.push(...(await runActiveOnIndexHooks({
+        mode: dryRun ? "gc:dry-run" : "gc",
+        total_items: selectedTargets.length,
+    })));
+    const guidance = buildGcGuidance({
+        dryRun,
+        scopes,
+        removed,
+    });
+    return {
+        ok: warnings.length === 0,
+        dry_run: dryRun,
+        scope: scopes,
+        removed,
+        retained,
+        warnings,
+        ...(locksSummary ? { locks: locksSummary } : {}),
+        ...(checkpointsSummary ? { checkpoints: checkpointsSummary } : {}),
+        guidance,
+        generated_at: nowIso(),
+    };
+}
+//# sourceMappingURL=gc.js.map
+//# debugId=68767a06-5737-53dc-91a4-aa9ef5c8c6a7

package/dist/sdk/governance/gc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gc.js","sources":["sdk/governance/gc.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/governance/gc\n *\n * Implements the pm gc command surface and its agent-facing runtime behavior.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { runCheckpointGc } from \"../../core/checkpoint/checkpoint-gc.js\";\nimport {\n  runActiveOnIndexHooks,\n  runActiveOnReadHooks,\n  runActiveOnWriteHooks,\n} from \"../../core/extensions/index.js\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { runLockGc } from \"../../core/lock/lock-gc.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 { nowIso } from \"../../core/shared/time.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\n\nconst GC_SCOPE_VALUES = [\n  \"index\",\n  \"embeddings\",\n  \"runtime\",\n  \"locks\",\n  \"checkpoints\",\n] as const;\ntype GcScope = (typeof GC_SCOPE_VALUES)[number];\n\ninterface GcTarget {\n  scope: GcScope;\n  relativePath: string;\n  kind: \"file\" | \"directory\";\n}\n\nconst GC_TARGETS: readonly GcTarget[] = [\n  {\n    scope: \"index\",\n    relativePath: \"index/manifest.json\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/embeddings.jsonl\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/vectorization-status.json\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/lancedb\",\n    kind: \"directory\",\n  },\n  {\n    // Removing embeddings invalidates the whole semantic index, so the queued\n    // background-refresh work is also meaningless: a worker draining a stale\n    // queue against an empty ledger would rebuild a partial, inconsistent index\n    // (only the queued items vectorized). Clear the queue and its gate so the\n    // next mutation re-seeds from a clean slate. See core/search/background-refresh.ts.\n    scope: \"embeddings\",\n    relativePath: \"search/pending-refresh.json\",\n    kind: \"file\",\n  },\n  {\n    scope: \"embeddings\",\n    relativePath: \"search/pending-refresh.gate.lock\",\n    kind: \"directory\",\n  },\n  {\n    scope: \"runtime\",\n    relativePath: \"runtime/test-runs\",\n    kind: \"directory\",\n  },\n  {\n    scope: \"runtime\",\n    relativePath: \"runtime/history-drift-cache.json\",\n    kind: \"file\",\n  },\n] as const;\n\n/** Documents the gc command options payload exchanged by command, SDK, and package integrations. */\nexport interface GcCommandOptions {\n  /** Value that configures or reports dry run for this contract. */\n  dryRun?: boolean;\n  /** Value that configures or reports scope for this contract. */\n  scope?: string[];\n}\n\n/** Documents the gc locks summary payload exchanged by command, SDK, and package integrations. */\nexport interface GcLocksSummary {\n  /** Value that configures or reports scanned for this contract. */\n  scanned: number;\n  /** Value that configures or reports removed for this contract. */\n  removed: number;\n  /** Value that configures or reports retained for this contract. */\n  retained: number;\n}\n\n/** Documents the gc checkpoints summary payload exchanged by command, SDK, and package integrations. */\nexport interface GcCheckpointsSummary {\n  /** Value that configures or reports scanned for this contract. */\n  scanned: number;\n  /** Value that configures or reports removed for this contract. */\n  removed: number;\n  /** Value that configures or reports retained for this contract. */\n  retained: number;\n  /** Value that configures or reports retention days for this contract. */\n  retention_days: number;\n}\n\n/** Documents the gc result payload exchanged by command, SDK, and package integrations. */\nexport interface GcResult {\n  /** Whether the operation completed without a blocking failure. */\n  ok: boolean;\n  /** Value that configures or reports dry run for this contract. */\n  dry_run: boolean;\n  /** Value that configures or reports scope for this contract. */\n  scope: GcScope[];\n  /** Value that configures or reports removed for this contract. */\n  removed: string[];\n  /** Value that configures or reports retained for this contract. */\n  retained: string[];\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Value that configures or reports guidance for this contract. */\n  guidance: string[];\n  /** Present only when the locks scope was selected. Summarizes the stale-lock sweep. */\n  locks?: GcLocksSummary;\n  /** Present only when the checkpoints scope was selected. Summarizes the rollback-checkpoint sweep. */\n  checkpoints?: GcCheckpointsSummary;\n  /** ISO 8601 timestamp recording when generated occurred. */\n  generated_at: string;\n}\n\nfunction isErrno(error: unknown, code: string): boolean {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"code\" in error &&\n    (error as { code?: string }).code === code\n  );\n}\n\nasync function removeCacheFile(\n  pmRoot: string,\n  target: GcTarget,\n  dryRun: boolean,\n): Promise<{ removed: boolean; warnings: string[] }> {\n  const relativePath = target.relativePath;\n  const absolutePath = path.join(pmRoot, relativePath);\n  const warnings = await runActiveOnReadHooks({\n    path: absolutePath,\n    scope: \"project\",\n  });\n  try {\n    const stats = await fs.stat(absolutePath);\n    if (target.kind === \"file\" && !stats.isFile()) {\n      return {\n        removed: false,\n        warnings: [...warnings, `not_a_file:${relativePath}`],\n      };\n    }\n    if (target.kind === \"directory\" && !stats.isDirectory()) {\n      return {\n        removed: false,\n        warnings: [...warnings, `not_a_directory:${relativePath}`],\n      };\n    }\n    if (dryRun) {\n      return {\n        removed: true,\n        warnings,\n      };\n    }\n    if (target.kind === \"file\") {\n      await fs.unlink(absolutePath);\n    } else {\n      await fs.rm(absolutePath, { recursive: true, force: true });\n    }\n    const writeWarnings = await runActiveOnWriteHooks({\n      path: absolutePath,\n      scope: \"project\",\n      op: \"gc:remove\",\n    });\n    return {\n      removed: true,\n      warnings: [...warnings, ...writeWarnings],\n    };\n  } catch (error: unknown) {\n    if (isErrno(error, \"ENOENT\")) {\n      return {\n        removed: false,\n        warnings,\n      };\n    }\n    throw error;\n  }\n}\n\nfunction parseScopes(raw: string[] | undefined): GcScope[] {\n  if (!raw || raw.length === 0) {\n    return [...GC_SCOPE_VALUES];\n  }\n  const tokens = raw\n    .flatMap((entry) => entry.split(\",\"))\n    .map((entry) => entry.trim().toLowerCase())\n    .filter((entry) => entry.length > 0);\n  if (tokens.length === 0) {\n    throw new PmCliError(\n      `--scope requires at least one value (${GC_SCOPE_VALUES.join(\",\")})`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  const resolved = new Set<GcScope>();\n  for (const token of tokens) {\n    if (!(GC_SCOPE_VALUES as readonly string[]).includes(token)) {\n      throw new PmCliError(\n        `Invalid --scope value \"${token}\". Expected one or more of: ${GC_SCOPE_VALUES.join(\", \")}`,\n        EXIT_CODE.USAGE,\n      );\n    }\n    resolved.add(token as GcScope);\n  }\n  return GC_SCOPE_VALUES.filter((scope) => resolved.has(scope));\n}\n\nfunction buildGcGuidance(params: {\n  dryRun: boolean;\n  scopes: GcScope[];\n  removed: string[];\n}): string[] {\n  const guidance: string[] = [];\n  if (params.dryRun) {\n    guidance.push(\"Dry-run preview only: no cache artifacts were deleted.\");\n  }\n  const searchScopeSelected =\n    params.scopes.includes(\"index\") || params.scopes.includes(\"embeddings\");\n  const searchArtifactsAffected = params.removed.some(\n    (entry) =>\n      entry === \"index/manifest.json\" ||\n      entry === \"search/embeddings.jsonl\" ||\n      entry === \"search/vectorization-status.json\" ||\n      entry === \"search/lancedb\" ||\n      entry === \"search/pending-refresh.json\" ||\n      entry === \"search/pending-refresh.gate.lock\",\n  );\n  if (searchScopeSelected && searchArtifactsAffected) {\n    guidance.push(\n      'Search artifacts were removed; the semantic index (including any queued background refresh) is invalidated. Run \"pm install search-advanced --project\" if reindex is unavailable, then \"pm reindex --mode keyword\" (and \"--mode semantic\" when semantic search is enabled) before search-heavy workflows.',\n    );\n  }\n  if (params.removed.includes(\"runtime/history-drift-cache.json\")) {\n    guidance.push(\n      'History drift cache was removed; the next \"pm health\" run performs a full history-drift re-scan.',\n    );\n  }\n  if (\n    !params.dryRun &&\n    params.removed.some((entry) => entry.startsWith(\"checkpoints/\"))\n  ) {\n    guidance.push(\n      'Aged rollback checkpoints were removed; their \"pm update-many\"/\"pm close-many --rollback\" windows are no longer recoverable.',\n    );\n  }\n  return guidance;\n}\n\n/** Implements run gc for the public runtime surface of this module. */\nexport async function runGc(\n  global: GlobalOptions,\n  options: GcCommandOptions = {},\n): Promise<GcResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\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  const settings = await readSettings(pmRoot);\n  const dryRun = options.dryRun === true;\n  const scopes = parseScopes(options.scope);\n  const selectedTargets = GC_TARGETS.filter((target) =>\n    scopes.includes(target.scope),\n  );\n\n  const removed: string[] = [];\n  const retained: string[] = [];\n  const warnings: string[] = [];\n\n  for (const target of selectedTargets) {\n    const result = await removeCacheFile(pmRoot, target, dryRun);\n    if (result.removed) {\n      removed.push(target.relativePath);\n    } else {\n      retained.push(target.relativePath);\n    }\n    warnings.push(...result.warnings);\n  }\n\n  // The locks scope is not a path-based GC_TARGET: it sweeps the locks/ directory\n  // and removes only locks whose own embedded ttl has expired (crashed-process\n  // debris), retaining active and unparseable locks. See core/lock/lock-gc.ts.\n  let locksSummary: GcLocksSummary | undefined;\n  if (scopes.includes(\"locks\")) {\n    const lockResult = await runLockGc(pmRoot, {\n      dryRun,\n      hooks: {\n        onRead: (lockPath) =>\n          runActiveOnReadHooks({ path: lockPath, scope: \"project\" }),\n        onWrite: (lockPath) =>\n          runActiveOnWriteHooks({\n            path: lockPath,\n            scope: \"project\",\n            op: \"gc:lock_remove\",\n          }),\n      },\n    });\n    removed.push(...lockResult.removed);\n    retained.push(...lockResult.retained);\n    warnings.push(...lockResult.warnings);\n    locksSummary = {\n      scanned: lockResult.scanned,\n      removed: lockResult.removed.length,\n      retained: lockResult.retained.length,\n    };\n  }\n\n  // The checkpoints scope is also not a path-based GC_TARGET: it sweeps\n  // checkpoints/ and removes only rollback checkpoints older than the configured\n  // checkpoints.retention_days, retaining active and unparseable files. See\n  // core/checkpoint/checkpoint-gc.ts.\n  let checkpointsSummary: GcCheckpointsSummary | undefined;\n  if (scopes.includes(\"checkpoints\")) {\n    const retentionDays = settings.checkpoints.retention_days;\n    const checkpointResult = await runCheckpointGc(pmRoot, {\n      dryRun,\n      retentionDays,\n      hooks: {\n        onRead: (checkpointPath) =>\n          runActiveOnReadHooks({ path: checkpointPath, scope: \"project\" }),\n        onWrite: (checkpointPath) =>\n          runActiveOnWriteHooks({\n            path: checkpointPath,\n            scope: \"project\",\n            op: \"gc:checkpoint_remove\",\n          }),\n      },\n    });\n    removed.push(...checkpointResult.removed);\n    retained.push(...checkpointResult.retained);\n    warnings.push(...checkpointResult.warnings);\n    checkpointsSummary = {\n      scanned: checkpointResult.scanned,\n      removed: checkpointResult.removed.length,\n      retained: checkpointResult.retained.length,\n      retention_days: retentionDays,\n    };\n  }\n\n  warnings.push(\n    ...(await runActiveOnIndexHooks({\n      mode: dryRun ? \"gc:dry-run\" : \"gc\",\n      total_items: selectedTargets.length,\n    })),\n  );\n  const guidance = buildGcGuidance({\n    dryRun,\n    scopes,\n    removed,\n  });\n\n  return {\n    ok: warnings.length === 0,\n    dry_run: dryRun,\n    scope: scopes,\n    removed,\n    retained,\n    warnings,\n    ...(locksSummary ? { locks: locksSummary } : {}),\n    ...(checkpointsSummary ? { checkpoints: checkpointsSummary } : {}),\n    guidance,\n    generated_at: nowIso(),\n  };\n}\n"],"names":[],"mappings":"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","debugId":"68767a06-5737-53dc-91a4-aa9ef5c8c6a7"}

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

@@ -0,0 +1,187 @@
+import { resolveEmbeddingProviders } from "../../core/search/providers.js";
+import { resolveSettingsWithSemanticRuntimeDefaults } from "../../core/search/semantic-defaults.js";
+import { buildVectorizationEmbeddingIdentity } from "../../core/search/vectorization-metadata.js";
+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";
+type HealthStatus = "ok" | "warn";
+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";
+    /** Lifecycle state reported for status. */
+    status: HealthStatus;
+    /** Value that configures or reports details for this contract. */
+    details: Record<string, unknown>;
+}
+/** 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;
+    /** Value that configures or reports checks for this contract. */
+    checks: HealthCheck[];
+    /** Number of warning entries represented by this result. */
+    warning_count?: number;
+    /** Value that configures or reports warnings for this contract. */
+    warnings: 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"][];
+    };
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the run health options payload exchanged by command, SDK, and package integrations. */
+export interface RunHealthOptions {
+    /** Value that configures or reports strict directories for this contract. */
+    strictDirectories?: boolean;
+    /** Value that configures or reports check only for this contract. */
+    checkOnly?: boolean;
+    /** Value that configures or reports check telemetry for this contract. */
+    checkTelemetry?: boolean;
+    /** Value that configures or reports no refresh for this contract. */
+    noRefresh?: boolean;
+    /** Value that configures or reports refresh vectors for this contract. */
+    refreshVectors?: boolean;
+    /** Value that configures or reports verbose stale items for this contract. */
+    verboseStaleItems?: boolean;
+    /** Value that configures or reports skip vectors for this contract. */
+    skipVectors?: boolean;
+    /** Value that configures or reports skip integrity for this contract. */
+    skipIntegrity?: boolean;
+    /** Value that configures or reports skip drift for this contract. */
+    skipDrift?: boolean;
+    /** Value that configures or reports full for this contract. */
+    full?: boolean;
+    /** Value that configures or reports brief for this contract. */
+    brief?: boolean;
+    /** Value that configures or reports summary for this contract. */
+    summary?: boolean;
+}
+interface MigrationStatusEntry {
+    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;
+}
+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[];
+}
+/** 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`. */
+declare function isAdvisoryHealthWarning(warning: string): 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 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 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;
+};
+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;
+}
+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 buildVectorizationProviderDetails(settings: PmSettings, snapshot: VectorizationRuntimeSnapshot): Record<string, unknown>;
+/** Implements run health for the public runtime surface of this module. */
+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: {
+    buildExtensionHealthTriageSummary: typeof buildExtensionHealthTriageSummary;
+    buildCapabilityContractMetadata: typeof buildCapabilityContractMetadata;
+    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;
+    resolveActionableUnknownAuthorEventCount: (authorAttribution: HistoryAuthorAttributionScan) => number;
+    resolveUnknownAuthorEventCount: (authorAttribution: HistoryAuthorAttributionScan) => number;
+    selectStaleItemDetail: typeof selectStaleItemDetail;
+    summarizeHealthCheckDetails: typeof summarizeHealthCheckDetails;
+    summarizeExtensionList: typeof summarizeExtensionList;
+    summarizeRecordList: typeof summarizeRecordList;
+    summarizeStringList: typeof summarizeStringList;
+    telemetryEnvFlagEnabled: typeof telemetryEnvFlagEnabled;
+    warningCode: typeof warningCode;
+};
+export {};