@unbrained/pm-cli 2026.5.18 → 2026.5.27

package/dist/cli/commands/health.js

@@ -1,13 +1,13 @@
 
-!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]="877f600b-5e09-5d62-bf4e-7bf9f9e38289")}catch(e){}}();
+!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]="43221c16-6351-5238-a4d1-d94619239fb2")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
 import { pathExists, readFileIfExists } from "../../core/fs/fs-utils.js";
 import { activateExtensions, getActiveExtensionRegistrations, loadExtensions, runActiveOnReadHooks } from "../../core/extensions/index.js";
 import { EXTENSION_CAPABILITY_CONTRACT, KNOWN_EXTENSION_CAPABILITIES, parseLegacyExtensionCapabilityAliasWarning, parseUnknownExtensionCapabilityWarning, } from "../../core/extensions/loader.js";
-import { hashDocument } from "../../core/history/history.js";
 import { enforceHistoryStreamPolicyForItems } from "../../core/history/history-stream-policy.js";
+import { scanHistoryDrift } from "../../core/history/drift-scan.js";
 import { readVectorizationStatusLedger, refreshSemanticEmbeddingsForMutatedItems, } from "../../core/search/cache.js";
 import { resolveEmbeddingProviders } from "../../core/search/providers.js";
 import { resolveSettingsWithSemanticRuntimeDefaults } from "../../core/search/semantic-defaults.js";
@@ -18,16 +18,25 @@ import { PmCliError } from "../../core/shared/errors.js";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
 import { nowIso } from "../../core/shared/time.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
-import { listAllFrontMatterWithBody } from "../../core/store/item-store.js";
-import { getHistoryPath, getItemFormatFromPath, getSettingsPath, ITEM_FILE_EXTENSIONS, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
+import { listAllFrontMatter, listAllFrontMatterWithBody } from "../../core/store/item-store.js";
+import { getItemFormatFromPath, getSettingsPath, ITEM_FILE_EXTENSIONS, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
 import { readSettingsWithMetadata } from "../../core/store/settings.js";
 import { readManagedExtensionState } from "./extension.js";
-import { verifyHistoryChain } from "./history.js";
 const STALE_VECTORIZATION_SUMMARY_LIMIT = 25;
+const BRIEF_HEALTH_DETAIL_LIMIT = 8;
 const TELEMETRY_QUEUE_RELATIVE_PATH = path.join("runtime", "telemetry", "events.jsonl");
 const TELEMETRY_STATE_RELATIVE_PATH = path.join("runtime", "telemetry", "state.json");
 const TELEMETRY_ENDPOINT_PROBE_TIMEOUT_MS = 2_500;
 const TELEMETRY_QUEUE_HIGH_WATER_MARK = 500;
+/**
+ * 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`.
+ */
+function isAdvisoryHealthWarning(warning) {
+    return warning.startsWith("telemetry_");
+}
 function warningCode(value) {
     const normalized = value.trim();
     const separator = normalized.indexOf(":");
@@ -550,6 +559,227 @@ function summarizeList(values, limit) {
         truncated: true,
     };
 }
+function summarizeRecordList(value, limit) {
+    if (!Array.isArray(value)) {
+        return {
+            count: 0,
+            sample: [],
+            truncated: false,
+        };
+    }
+    return {
+        count: value.length,
+        sample: value.slice(0, limit),
+        truncated: value.length > limit,
+    };
+}
+function summarizeExtensionRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {};
+    }
+    const record = value;
+    return {
+        layer: record.layer,
+        directory: record.directory,
+        name: record.name,
+        version: record.version,
+        enabled: record.enabled,
+        status: record.status,
+        has_activate: record.has_activate,
+        capabilities: record.capabilities,
+    };
+}
+function summarizeExtensionList(value, limit) {
+    const summary = summarizeRecordList(value, limit);
+    return {
+        ...summary,
+        sample: summary.sample.map((entry) => summarizeExtensionRecord(entry)),
+    };
+}
+function summarizeStringList(value, limit) {
+    if (!Array.isArray(value)) {
+        return {
+            count: 0,
+            sample: [],
+            truncated: false,
+        };
+    }
+    const strings = value.filter((entry) => typeof entry === "string");
+    return {
+        count: strings.length,
+        sample: strings.slice(0, limit),
+        truncated: strings.length > limit,
+    };
+}
+function summarizeHealthCheckDetails(check, limit) {
+    const details = check.details;
+    if (check.name === "settings") {
+        return {
+            version: details.version,
+            id_prefix: details.id_prefix,
+            locks_ttl_seconds: details.locks_ttl_seconds,
+            warnings: summarizeStringList(details.warnings, limit),
+        };
+    }
+    if (check.name === "directories") {
+        return {
+            required_count: Array.isArray(details.required) ? details.required.length : 0,
+            optional_count: Array.isArray(details.optional) ? details.optional.length : 0,
+            missing_required: summarizeStringList(details.missing_required, limit),
+            missing_optional: summarizeStringList(details.missing_optional, limit),
+            missing: summarizeStringList(details.missing, limit),
+            strict_directories: details.strict_directories,
+        };
+    }
+    if (check.name === "settings_values") {
+        return {
+            warnings: summarizeStringList(details.warnings, limit),
+        };
+    }
+    if (check.name === "telemetry") {
+        return {
+            enabled: details.enabled,
+            capture_level: details.capture_level,
+            endpoint: details.endpoint,
+            queue_exists: details.queue_exists,
+            queue_entries: details.queue_entries,
+            queue_draining: details.queue_draining,
+            queue_invalid_rows: details.queue_invalid_rows,
+            queue_rows_total: details.queue_rows_total,
+            last_successful_flush_at: details.last_successful_flush_at,
+            last_failed_flush_at: details.last_failed_flush_at,
+            endpoint_probe: details.endpoint_probe,
+            env_overrides: details.env_overrides,
+        };
+    }
+    if (check.name === "extensions") {
+        const activation = typeof details.activation === "object" && details.activation !== null ? details.activation : {};
+        return {
+            disabled_by_flag: details.disabled_by_flag,
+            discovered: summarizeExtensionList(details.discovered, limit),
+            effective: summarizeExtensionList(details.effective, limit),
+            loaded: summarizeExtensionList(details.loaded, limit),
+            failed: summarizeRecordList(details.failed, limit),
+            warnings: summarizeStringList(details.warnings, limit),
+            activation: {
+                failed: summarizeRecordList(activation.failed, limit),
+                warnings: summarizeStringList(activation.warnings, limit),
+                hook_counts: activation.hook_counts,
+                command_handler_count: activation.command_handler_count,
+                service_override_count: activation.service_override_count,
+                renderer_override_count: activation.renderer_override_count,
+                registration_counts: activation.registration_counts,
+                migration_status: typeof activation.migration_status === "object" && activation.migration_status !== null
+                    ? {
+                        applied_count: activation.migration_status.applied_count,
+                        pending_count: activation.migration_status.pending_count,
+                        failed_count: activation.migration_status.failed_count,
+                    }
+                    : null,
+            },
+            triage: details.triage,
+            capability_contract: details.capability_contract,
+            capability_guidance: summarizeRecordList(details.capability_guidance, limit),
+        };
+    }
+    if (check.name === "storage") {
+        return details;
+    }
+    if (check.name === "integrity") {
+        return {
+            checked_item_files: details.checked_item_files,
+            checked_history_streams: details.checked_history_streams,
+            counts: details.counts,
+            item_unreadable: summarizeStringList(details.item_unreadable, limit),
+            item_conflict_markers: summarizeRecordList(details.item_conflict_markers, limit),
+            item_parse_failures: summarizeStringList(details.item_parse_failures, limit),
+            history_unreadable: summarizeStringList(details.history_unreadable, limit),
+            history_conflict_markers: summarizeRecordList(details.history_conflict_markers, limit),
+            history_invalid_json: summarizeRecordList(details.history_invalid_json, limit),
+            skipped: details.skipped,
+        };
+    }
+    if (check.name === "history_drift") {
+        return {
+            checked_items: details.checked_items,
+            counts: details.counts,
+            drifted_items: summarizeStringList(details.drifted_items, limit),
+            missing_streams: summarizeStringList(details.missing_streams, limit),
+            unreadable_streams: summarizeStringList(details.unreadable_streams, limit),
+            hash_mismatches: summarizeStringList(details.hash_mismatches, limit),
+            chain_mismatches: summarizeStringList(details.chain_mismatches, limit),
+            skipped: details.skipped,
+        };
+    }
+    if (check.name === "vectorization") {
+        return {
+            semantic_runtime_available: details.semantic_runtime_available,
+            compatibility_mode_auto_defaults: details.compatibility_mode_auto_defaults,
+            auto_ollama_defaults_applied: details.auto_ollama_defaults_applied,
+            refresh_policy: details.refresh_policy,
+            provider_active: details.provider_active,
+            vector_store_active: details.vector_store_active,
+            items: details.items,
+            ledger_entries_before: details.ledger_entries_before,
+            stale_items_before_total: details.stale_items_before_total,
+            stale_items_before: summarizeStringList(details.stale_items_before, limit),
+            refresh_attempted: details.refresh_attempted,
+            refresh_skipped_reason: details.refresh_skipped_reason,
+            refresh_result: details.refresh_result,
+            ledger_entries_after: details.ledger_entries_after,
+            stale_items_after_total: details.stale_items_after_total,
+            stale_items_after: summarizeStringList(details.stale_items_after, limit),
+            skipped: details.skipped,
+        };
+    }
+    return details;
+}
+function applyBriefHealthProjection(result) {
+    const warningsSummary = summarizeStringList(result.warnings, BRIEF_HEALTH_DETAIL_LIMIT);
+    return {
+        ok: result.ok,
+        checks: result.checks.map((check) => ({
+            name: check.name,
+            status: check.status,
+            details: summarizeHealthCheckDetails(check, BRIEF_HEALTH_DETAIL_LIMIT),
+        })),
+        warnings: warningsSummary.sample,
+        projection: {
+            mode: "brief",
+            warning_count: warningsSummary.count,
+            warnings_truncated: warningsSummary.truncated,
+            detail_limit: BRIEF_HEALTH_DETAIL_LIMIT,
+        },
+        generated_at: result.generated_at,
+    };
+}
+function isSkippedHealthCheck(check) {
+    return check.details.skipped === true;
+}
+function applySummaryHealthProjection(result) {
+    const warningsSummary = summarizeStringList(result.warnings, BRIEF_HEALTH_DETAIL_LIMIT);
+    const omittedChecks = result.checks.filter(isSkippedHealthCheck).map((check) => check.name);
+    return {
+        ok: result.ok,
+        checks: result.checks
+            .filter((check) => !isSkippedHealthCheck(check))
+            .map((check) => ({
+            name: check.name,
+            status: check.status,
+            details: {},
+        })),
+        warning_count: warningsSummary.count,
+        warnings: warningsSummary.sample,
+        projection: {
+            mode: "summary",
+            warning_count: warningsSummary.count,
+            warnings_truncated: warningsSummary.truncated,
+            detail_limit: BRIEF_HEALTH_DETAIL_LIMIT,
+            omitted_checks: omittedChecks,
+        },
+        generated_at: result.generated_at,
+    };
+}
 function selectStaleItemDetail(values, verboseStaleItems) {
     if (verboseStaleItems) {
         return {
@@ -732,7 +962,8 @@ async function buildTelemetryCheck(settings, options) {
                     attempted: false,
                 },
                 env_overrides: {
-                    telemetry_disabled: telemetryEnvFlagEnabled("PM_TELEMETRY_DISABLED"),
+                    telemetry_disabled: telemetryEnvFlagEnabled("PM_TELEMETRY_DISABLED") || telemetryEnvFlagEnabled("PM_NO_TELEMETRY"),
+                    pm_no_telemetry: telemetryEnvFlagEnabled("PM_NO_TELEMETRY"),
                     telemetry_otel_disabled: telemetryEnvFlagEnabled("PM_TELEMETRY_OTEL_DISABLED"),
                 },
             },
@@ -741,61 +972,7 @@ async function buildTelemetryCheck(settings, options) {
     };
 }
 async function buildHistoryDriftCheck(pmRoot, items) {
-    const missingStreams = [];
-    const unreadableStreams = [];
-    const hashMismatches = [];
-    const chainMismatches = [];
-    for (const item of items) {
-        const historyPath = getHistoryPath(pmRoot, item.id);
-        let latestAfterHash = null;
-        try {
-            const raw = await fs.readFile(historyPath, "utf8");
-            if (raw.trim().length === 0) {
-                missingStreams.push(item.id);
-                continue;
-            }
-            const lines = raw.split(/\r?\n/);
-            const entries = [];
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (trimmed.length === 0) {
-                    continue;
-                }
-                const parsed = JSON.parse(trimmed);
-                if (typeof parsed.after_hash !== "string" || parsed.after_hash.trim().length === 0) {
-                    throw new Error("missing after_hash");
-                }
-                entries.push(parsed);
-                latestAfterHash = parsed.after_hash;
-            }
-            const chainVerification = verifyHistoryChain(entries);
-            if (!chainVerification.ok) {
-                chainMismatches.push(item.id);
-            }
-        }
-        catch (error) {
-            if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
-                missingStreams.push(item.id);
-            }
-            else {
-                unreadableStreams.push(item.id);
-            }
-            continue;
-        }
-        if (!latestAfterHash) {
-            missingStreams.push(item.id);
-            continue;
-        }
-        const { body, ...frontMatter } = item;
-        const currentHash = hashDocument({
-            metadata: frontMatter,
-            body,
-        });
-        if (latestAfterHash !== currentHash) {
-            hashMismatches.push(item.id);
-        }
-    }
-    const driftedItems = [...new Set([...missingStreams, ...unreadableStreams, ...hashMismatches, ...chainMismatches])].sort((a, b) => a.localeCompare(b));
+    const { missingStreams, unreadableStreams, hashMismatches, chainMismatches, driftedItems } = await scanHistoryDrift(pmRoot, items);
     const warnings = [
         ...missingStreams.map((id) => `history_drift_missing_stream:${id}`),
         ...unreadableStreams.map((id) => `history_drift_unreadable_stream:${id}`),
@@ -973,28 +1150,35 @@ export async function runHealth(global, options = {}) {
         checkTelemetry: options.checkTelemetry === true,
     });
     const extensionCheck = await buildExtensionCheck(pmRoot, settings, Boolean(global.noExtensions));
+    const summaryMode = options.summary === true && options.full !== true;
+    const fastProjectionCheckOnly = options.checkOnly === true && (options.brief === true || options.summary === true) && options.full !== true;
+    const skipIntegrity = (options.skipIntegrity === true || fastProjectionCheckOnly) && options.full !== true;
+    const skipDrift = (options.skipDrift === true || fastProjectionCheckOnly) && options.full !== true;
+    const skipVectors = (options.skipVectors === true || fastProjectionCheckOnly) && options.full !== true;
     const itemReadWarnings = [];
-    const items = await listAllFrontMatterWithBody(pmRoot, settings.item_format, typeRegistry.type_to_folder, itemReadWarnings, settings.schema);
+    const items = skipDrift && skipVectors
+        ? await listAllFrontMatter(pmRoot, settings.item_format, typeRegistry.type_to_folder, itemReadWarnings, settings.schema)
+        : await listAllFrontMatterWithBody(pmRoot, settings.item_format, typeRegistry.type_to_folder, itemReadWarnings, settings.schema);
+    const itemsWithBody = items;
     const normalizedItemReadWarnings = [...new Set(itemReadWarnings)];
-    const historyPolicy = await enforceHistoryStreamPolicyForItems({
-        pmRoot,
-        settings,
-        itemIds: items.map((item) => item.id),
-        commandLabel: "health",
-    });
+    const historyPolicy = skipDrift
+        ? { warnings: [] }
+        : await enforceHistoryStreamPolicyForItems({
+            pmRoot,
+            settings,
+            itemIds: items.map((item) => item.id),
+            commandLabel: "health",
+        });
     const historySummary = await countHistoryStreams(pmRoot);
-    const skipIntegrity = options.skipIntegrity === true && options.full !== true;
-    const skipDrift = options.skipDrift === true && options.full !== true;
-    const skipVectors = options.skipVectors === true && options.full !== true;
     const integrityCheck = skipIntegrity
         ? { check: { name: "integrity", status: "ok", details: { skipped: true } }, warnings: [] }
         : await buildIntegrityCheck(pmRoot, typeRegistry.type_to_folder, settings.schema);
     const historyDriftCheck = skipDrift
         ? { check: { name: "history_drift", status: "ok", details: { skipped: true } }, warnings: [] }
-        : await buildHistoryDriftCheck(pmRoot, items);
+        : await buildHistoryDriftCheck(pmRoot, itemsWithBody);
     const vectorizationCheck = skipVectors
         ? { check: { name: "vectorization", status: "ok", details: { skipped: true } }, warnings: [] }
-        : await buildVectorizationCheck(pmRoot, settings, items, refreshPolicy, options.verboseStaleItems === true);
+        : await buildVectorizationCheck(pmRoot, settings, itemsWithBody, refreshPolicy, options.verboseStaleItems === true);
     const checks = [
         {
             name: "settings",
@@ -1055,12 +1239,21 @@ export async function runHealth(global, options = {}) {
         ...hookWarnings,
     ];
     const normalizedWarnings = [...new Set(warnings)];
-    return {
-        ok: normalizedWarnings.length === 0,
+    // Telemetry is an opt-out, non-critical observability feature. Its operational
+    // state (queue backlog, unreachable endpoint, corrupt local state) is advisory:
+    // it must never flip overall project health to not-ok. Such warnings are still
+    // surfaced in `warnings` and the telemetry check's own `warn` status.
+    const blockingWarnings = normalizedWarnings.filter((warning) => !isAdvisoryHealthWarning(warning));
+    const result = {
+        ok: blockingWarnings.length === 0,
         checks,
         warnings: normalizedWarnings,
         generated_at: nowIso(),
     };
+    if (summaryMode) {
+        return applySummaryHealthProjection(result);
+    }
+    return options.brief === true ? applyBriefHealthProjection(result) : result;
 }
 //# sourceMappingURL=health.js.map
-//# debugId=877f600b-5e09-5d62-bf4e-7bf9f9e38289
+//# debugId=43221c16-6351-5238-a4d1-d94619239fb2