@unbrained/pm-cli 2026.6.13 → 2026.6.16

package/dist/cli/commands/guide.js.map

@@ -1 +1 @@
-{"version":3,"file":"guide.js","sources":["cli/commands/guide.ts"],"sourceRoot":"/","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { resolveConfiguredPmPackageRoot } from \"../../core/packages/root.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 {\n  listGuideTopicIds,\n  listGuideTopics,\n  resolveGuideTopic,\n  type GuideTopicDefinition,\n} from \"../guide-topics.js\";\n\nexport const GUIDE_OUTPUT_VALUES = [\"markdown\", \"toon\", \"json\"] as const;\nexport type GuideOutputFormat = (typeof GUIDE_OUTPUT_VALUES)[number];\n\nexport const GUIDE_DEPTH_VALUES = [\"brief\", \"standard\", \"deep\"] as const;\nexport type GuideDepth = (typeof GUIDE_DEPTH_VALUES)[number];\n\nexport interface GuideOptions {\n  topic?: string;\n  list?: boolean;\n  format?: string;\n  depth?: string;\n  [key: string]: unknown;\n}\n\nexport interface GuideDocRender {\n  path: string;\n  purpose: string;\n  optional: boolean;\n  exists: boolean;\n  line_count: number | null;\n  content_mode: \"none\" | \"excerpt\" | \"full\";\n  content: string | null;\n  truncated: boolean;\n}\n\nexport interface GuideIndexResult {\n  output_default: \"toon\";\n  mode: \"index\";\n  depth: GuideDepth;\n  topics: Array<{\n    id: string;\n    aliases: string[];\n    title: string;\n    summary: string;\n    intent: string;\n    quick_commands: string[];\n    docs: Array<{ path: string; purpose: string }>;\n    related: string[];\n  }>;\n  suggested_next_steps: string[];\n}\n\nexport interface GuideTopicResult {\n  output_default: \"toon\";\n  mode: \"topic\";\n  depth: GuideDepth;\n  requested_topic: string;\n  topic: GuideTopicDefinition;\n  docs: GuideDocRender[];\n  warnings: string[];\n}\n\nexport type GuideResult = GuideIndexResult | GuideTopicResult;\n\nfunction parseGuideOutputFormat(raw: string | undefined): GuideOutputFormat | undefined {\n  if (!raw) {\n    return undefined;\n  }\n  const normalized = raw.trim().toLowerCase();\n  if (!GUIDE_OUTPUT_VALUES.includes(normalized as GuideOutputFormat)) {\n    throw new PmCliError(\"Guide format must be one of markdown|toon|json\", EXIT_CODE.USAGE);\n  }\n  return normalized as GuideOutputFormat;\n}\n\nexport function resolveGuideOutputFormat(options: GuideOptions, global: GlobalOptions): GuideOutputFormat {\n  const commandFormat = parseGuideOutputFormat(options.format);\n  if (global.json && commandFormat && commandFormat !== \"json\") {\n    throw new PmCliError(\"Cannot combine --json with --format markdown|toon\", EXIT_CODE.USAGE);\n  }\n  if (global.json) {\n    return \"json\";\n  }\n  return commandFormat ?? \"toon\";\n}\n\nfunction parseGuideDepth(raw: string | undefined): GuideDepth {\n  if (!raw) {\n    return \"brief\";\n  }\n  const normalized = raw.trim().toLowerCase();\n  if (!GUIDE_DEPTH_VALUES.includes(normalized as GuideDepth)) {\n    throw new PmCliError(\"Guide depth must be one of brief|standard|deep\", EXIT_CODE.USAGE);\n  }\n  return normalized as GuideDepth;\n}\n\nfunction resolvePackageRoot(): string {\n  return resolveConfiguredPmPackageRoot(process.env, \"PM_CLI_PACKAGE_ROOT\", import.meta.url, [\"..\", \"..\", \"..\"]);\n}\n\nfunction normalizeLineEndings(value: string): string {\n  return value.replaceAll(\"\\r\\n\", \"\\n\");\n}\n\nfunction toExcerpt(content: string, maxLines: number, maxCharacters: number): { excerpt: string; truncated: boolean; lineCount: number } {\n  const normalized = normalizeLineEndings(content);\n  const lines = normalized.split(\"\\n\");\n  const lineSlice = lines.slice(0, maxLines);\n  let excerpt = lineSlice.join(\"\\n\");\n  let truncated = lines.length > maxLines;\n  if (excerpt.length > maxCharacters) {\n    excerpt = excerpt.slice(0, maxCharacters);\n    truncated = true;\n  }\n  return {\n    excerpt: excerpt.trimEnd(),\n    truncated,\n    lineCount: lines.length,\n  };\n}\n\nasync function renderGuideDocs(topic: GuideTopicDefinition, depth: GuideDepth, packageRoot: string): Promise<GuideDocRender[]> {\n  const includeContent = depth !== \"brief\";\n  const contentMode: GuideDocRender[\"content_mode\"] = includeContent ? (depth === \"deep\" ? \"full\" : \"excerpt\") : \"none\";\n  const docs: GuideDocRender[] = [];\n  for (const doc of topic.docs) {\n    const absolutePath = path.resolve(packageRoot, doc.path);\n    if (!includeContent) {\n      docs.push({\n        path: doc.path,\n        purpose: doc.purpose,\n        optional: doc.optional === true,\n        exists: true,\n        line_count: null,\n        content_mode: \"none\",\n        content: null,\n        truncated: false,\n      });\n      continue;\n    }\n    try {\n      const rawContent = await readFile(absolutePath, \"utf8\");\n      if (depth === \"deep\") {\n        const normalized = normalizeLineEndings(rawContent).trimEnd();\n        docs.push({\n          path: doc.path,\n          purpose: doc.purpose,\n          optional: doc.optional === true,\n          exists: true,\n          line_count: normalized.length === 0 ? 0 : normalized.split(\"\\n\").length,\n          content_mode: \"full\",\n          content: normalized,\n          truncated: false,\n        });\n      } else {\n        const excerpt = toExcerpt(rawContent, 120, 12_000);\n        docs.push({\n          path: doc.path,\n          purpose: doc.purpose,\n          optional: doc.optional === true,\n          exists: true,\n          line_count: excerpt.lineCount,\n          content_mode: contentMode,\n          content: excerpt.excerpt,\n          truncated: excerpt.truncated,\n        });\n      }\n    } catch (error) {\n      const code = (error as { code?: string } | null)?.code;\n      const missing = code === \"ENOENT\";\n      docs.push({\n        path: doc.path,\n        purpose: doc.purpose,\n        optional: doc.optional === true,\n        exists: false,\n        line_count: null,\n        content_mode: \"none\",\n        content: null,\n        truncated: false,\n      });\n      if (!missing) {\n        throw new PmCliError(`Failed to read guide document \"${doc.path}\".`, EXIT_CODE.GENERIC_FAILURE);\n      }\n    }\n  }\n  return docs;\n}\n\nfunction buildGuideIndex(depth: GuideDepth): GuideIndexResult {\n  const topics = listGuideTopics().map((topic) => ({\n    id: topic.id,\n    aliases: topic.aliases,\n    title: topic.title,\n    summary: topic.summary,\n    intent: topic.intent,\n    quick_commands: depth === \"brief\" ? topic.commands.slice(0, 3) : topic.commands.slice(0, 6),\n    docs: topic.docs.map((doc) => ({ path: doc.path, purpose: doc.purpose })),\n    related: topic.related,\n  }));\n  return {\n    output_default: \"toon\",\n    mode: \"index\",\n    depth,\n    topics,\n    suggested_next_steps: [\n      \"pm guide <topic>\",\n      \"pm guide <topic> --depth standard\",\n      \"pm guide <topic> --depth deep --format markdown\",\n      \"pm guide <topic> --json\",\n    ],\n  };\n}\n\nfunction ensureGuideTopic(topic: string | undefined): GuideTopicDefinition {\n  const resolved = resolveGuideTopic(topic);\n  if (resolved) {\n    return resolved;\n  }\n  const available = listGuideTopicIds().join(\", \");\n  throw new PmCliError(\n    `Unknown guide topic \"${topic ?? \"\"}\". Available topics: ${available}. Use \"pm guide --list\" to browse.`,\n    EXIT_CODE.USAGE,\n  );\n}\n\nexport async function runGuide(options: GuideOptions, global: GlobalOptions): Promise<GuideResult> {\n  const depth = parseGuideDepth(typeof options.depth === \"string\" ? options.depth : undefined);\n  const listRequested = options.list === true;\n  const topicRaw = typeof options.topic === \"string\" ? options.topic : undefined;\n  if (listRequested || !topicRaw) {\n    return buildGuideIndex(depth);\n  }\n\n  const topic = ensureGuideTopic(topicRaw);\n  const packageRoot = resolvePackageRoot();\n  const docs = await renderGuideDocs(topic, depth, packageRoot);\n  const warnings = docs\n    .filter((doc) => !doc.exists && !doc.optional)\n    .map((doc) => `Missing required guide document: ${doc.path}`);\n\n  return {\n    output_default: \"toon\",\n    mode: \"topic\",\n    depth,\n    requested_topic: topicRaw,\n    topic,\n    docs,\n    warnings,\n  };\n}\n\nfunction markdownCodeFence(content: string): string {\n  return content.replaceAll(\"```\", \"``\\\\`\");\n}\n\nexport function renderGuideMarkdown(result: GuideResult): string {\n  if (result.mode === \"index\") {\n    const lines: string[] = [\n      \"# pm guide\",\n      \"\",\n      \"Token-efficient local documentation index for agent and maintainer workflows.\",\n      \"\",\n      \"## Topics\",\n    ];\n    for (const topic of result.topics) {\n      lines.push(`- \\`${topic.id}\\` - ${topic.summary}`);\n      if (result.depth !== \"brief\") {\n        lines.push(`  - intent: ${topic.intent}`);\n        lines.push(`  - docs: ${topic.docs.map((doc) => `\\`${doc.path}\\``).join(\", \")}`);\n      }\n    }\n    lines.push(\"\", \"## Next steps\");\n    for (const step of result.suggested_next_steps) {\n      lines.push(`- \\`${step}\\``);\n    }\n    return lines.join(\"\\n\");\n  }\n\n  const lines: string[] = [\n    `# pm guide ${result.topic.id}`,\n    \"\",\n    result.topic.summary,\n    \"\",\n    \"## Intent\",\n    result.topic.intent,\n    \"\",\n    \"## Key commands\",\n    ...result.topic.commands.map((command) => `- \\`${command}\\``),\n    \"\",\n    \"## Workflow prompts\",\n  ];\n  for (const workflow of result.topic.workflows) {\n    lines.push(`### ${workflow.name}`);\n    lines.push(`goal: ${workflow.goal}`);\n    lines.push(`prompt: ${workflow.prompt}`);\n    lines.push(\"commands:\");\n    lines.push(...workflow.commands.map((command) => `- \\`${command}\\``));\n    lines.push(\"\");\n  }\n  lines.push(\"## Documents\");\n  for (const doc of result.docs) {\n    const status = doc.exists ? \"available\" : doc.optional ? \"missing (optional)\" : \"missing (required)\";\n    lines.push(`- \\`${doc.path}\\` - ${doc.purpose} (${status})`);\n    if (doc.exists && doc.content_mode !== \"none\" && doc.content) {\n      lines.push(\"\");\n      lines.push(`### Excerpt: \\`${doc.path}\\``);\n      if (doc.truncated) {\n        lines.push(\"_truncated for context efficiency_\");\n      }\n      lines.push(\"```markdown\");\n      lines.push(markdownCodeFence(doc.content));\n      lines.push(\"```\");\n    }\n  }\n  if (result.topic.related.length > 0) {\n    lines.push(\"\", \"## Related topics\");\n    lines.push(...result.topic.related.map((topic) => `- \\`${topic}\\``));\n  }\n  if (result.warnings.length > 0) {\n    lines.push(\"\", \"## Warnings\");\n    lines.push(...result.warnings.map((warning) => `- ${warning}`));\n  }\n  return lines.join(\"\\n\");\n}\n"],"names":[],"mappings":"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","debugId":"8d06806e-bba1-5626-9ff4-b7fda8387582"}
+{"version":3,"file":"guide.js","sources":["cli/commands/guide.ts"],"sourceRoot":"/","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { resolveConfiguredPmPackageRoot } from \"../../core/packages/root.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 {\n  listGuideTopicIds,\n  listGuideTopics,\n  resolveGuideTopic,\n  type GuideTopicDefinition,\n} from \"../guide-topics.js\";\n\nexport const GUIDE_OUTPUT_VALUES = [\"markdown\", \"toon\", \"json\"] as const;\nexport type GuideOutputFormat = (typeof GUIDE_OUTPUT_VALUES)[number];\n\nexport const GUIDE_DEPTH_VALUES = [\"brief\", \"standard\", \"deep\"] as const;\nexport type GuideDepth = (typeof GUIDE_DEPTH_VALUES)[number];\n\nexport interface GuideOptions {\n  topic?: string;\n  list?: boolean;\n  format?: string;\n  depth?: string;\n  [key: string]: unknown;\n}\n\nexport interface GuideDocRender {\n  path: string;\n  purpose: string;\n  optional: boolean;\n  exists: boolean;\n  line_count: number | null;\n  content_mode: \"none\" | \"excerpt\" | \"full\";\n  content: string | null;\n  truncated: boolean;\n}\n\nexport interface GuideIndexResult {\n  output_default: \"toon\";\n  mode: \"index\";\n  depth: GuideDepth;\n  topics: Array<{\n    id: string;\n    aliases: string[];\n    title: string;\n    summary: string;\n    intent: string;\n    quick_commands: string[];\n    docs: Array<{ path: string; purpose: string }>;\n    related: string[];\n  }>;\n  suggested_next_steps: string[];\n}\n\nexport interface GuideTopicResult {\n  output_default: \"toon\";\n  mode: \"topic\";\n  depth: GuideDepth;\n  requested_topic: string;\n  topic: GuideTopicDefinition;\n  docs: GuideDocRender[];\n  warnings: string[];\n}\n\nexport type GuideResult = GuideIndexResult | GuideTopicResult;\n\nfunction parseGuideOutputFormat(raw: string | undefined): GuideOutputFormat | undefined {\n  if (!raw) {\n    return undefined;\n  }\n  const normalized = raw.trim().toLowerCase();\n  if (!GUIDE_OUTPUT_VALUES.includes(normalized as GuideOutputFormat)) {\n    throw new PmCliError(\"Guide format must be one of markdown|toon|json\", EXIT_CODE.USAGE);\n  }\n  return normalized as GuideOutputFormat;\n}\n\nexport function resolveGuideOutputFormat(options: GuideOptions, global: GlobalOptions): GuideOutputFormat {\n  const commandFormat = parseGuideOutputFormat(options.format);\n  if (global.json && commandFormat && commandFormat !== \"json\") {\n    throw new PmCliError(\"Cannot combine --json with --format markdown|toon\", EXIT_CODE.USAGE);\n  }\n  if (global.json) {\n    return \"json\";\n  }\n  return commandFormat ?? \"toon\";\n}\n\nfunction parseGuideDepth(raw: string | undefined): GuideDepth {\n  if (!raw) {\n    return \"brief\";\n  }\n  const normalized = raw.trim().toLowerCase();\n  if (!GUIDE_DEPTH_VALUES.includes(normalized as GuideDepth)) {\n    throw new PmCliError(\"Guide depth must be one of brief|standard|deep\", EXIT_CODE.USAGE);\n  }\n  return normalized as GuideDepth;\n}\n\nfunction resolvePackageRoot(): string {\n  return resolveConfiguredPmPackageRoot(process.env, \"PM_CLI_PACKAGE_ROOT\", import.meta.url, [\"..\", \"..\", \"..\"]);\n}\n\nfunction normalizeLineEndings(value: string): string {\n  return value.replaceAll(\"\\r\\n\", \"\\n\");\n}\n\nfunction toExcerpt(content: string, maxLines: number, maxCharacters: number): { excerpt: string; truncated: boolean; lineCount: number } {\n  const normalized = normalizeLineEndings(content);\n  const lines = normalized.split(\"\\n\");\n  const lineSlice = lines.slice(0, maxLines);\n  let excerpt = lineSlice.join(\"\\n\");\n  let truncated = lines.length > maxLines;\n  if (excerpt.length > maxCharacters) {\n    excerpt = excerpt.slice(0, maxCharacters);\n    truncated = true;\n  }\n  return {\n    excerpt: excerpt.trimEnd(),\n    truncated,\n    lineCount: lines.length,\n  };\n}\n\nasync function renderGuideDocs(topic: GuideTopicDefinition, depth: GuideDepth, packageRoot: string): Promise<GuideDocRender[]> {\n  const includeContent = depth !== \"brief\";\n  const contentMode: GuideDocRender[\"content_mode\"] = includeContent ? (depth === \"deep\" ? \"full\" : \"excerpt\") : \"none\";\n  const docs: GuideDocRender[] = [];\n  for (const doc of topic.docs) {\n    const absolutePath = path.resolve(packageRoot, doc.path);\n    if (!includeContent) {\n      docs.push({\n        path: doc.path,\n        purpose: doc.purpose,\n        optional: doc.optional === true,\n        exists: true,\n        line_count: null,\n        content_mode: \"none\",\n        content: null,\n        truncated: false,\n      });\n      continue;\n    }\n    try {\n      const rawContent = await readFile(absolutePath, \"utf8\");\n      if (depth === \"deep\") {\n        const normalized = normalizeLineEndings(rawContent).trimEnd();\n        docs.push({\n          path: doc.path,\n          purpose: doc.purpose,\n          optional: doc.optional === true,\n          exists: true,\n          line_count: normalized.length === 0 ? 0 : normalized.split(\"\\n\").length,\n          content_mode: \"full\",\n          content: normalized,\n          truncated: false,\n        });\n      } else {\n        const excerpt = toExcerpt(rawContent, 120, 12_000);\n        docs.push({\n          path: doc.path,\n          purpose: doc.purpose,\n          optional: doc.optional === true,\n          exists: true,\n          line_count: excerpt.lineCount,\n          content_mode: contentMode,\n          content: excerpt.excerpt,\n          truncated: excerpt.truncated,\n        });\n      }\n    } catch (error) {\n      const code = (error as { code?: string } | null)?.code;\n      const missing = code === \"ENOENT\";\n      docs.push({\n        path: doc.path,\n        purpose: doc.purpose,\n        optional: doc.optional === true,\n        exists: false,\n        line_count: null,\n        content_mode: \"none\",\n        content: null,\n        truncated: false,\n      });\n      if (!missing) {\n        throw new PmCliError(`Failed to read guide document \"${doc.path}\".`, EXIT_CODE.GENERIC_FAILURE);\n      }\n    }\n  }\n  return docs;\n}\n\nfunction buildGuideIndex(depth: GuideDepth): GuideIndexResult {\n  const topics = listGuideTopics().map((topic) => ({\n    id: topic.id,\n    aliases: topic.aliases,\n    title: topic.title,\n    summary: topic.summary,\n    intent: topic.intent,\n    quick_commands: depth === \"brief\" ? topic.commands.slice(0, 3) : topic.commands.slice(0, 6),\n    docs: topic.docs.map((doc) => ({ path: doc.path, purpose: doc.purpose })),\n    related: topic.related,\n  }));\n  return {\n    output_default: \"toon\",\n    mode: \"index\",\n    depth,\n    topics,\n    suggested_next_steps: [\n      \"pm guide <topic>\",\n      \"pm guide <topic> --depth standard\",\n      \"pm guide <topic> --depth deep --format markdown\",\n      \"pm guide <topic> --json\",\n    ],\n  };\n}\n\nfunction ensureGuideTopic(topic: string): GuideTopicDefinition {\n  const resolved = resolveGuideTopic(topic);\n  if (resolved) {\n    return resolved;\n  }\n  const available = listGuideTopicIds().join(\", \");\n  throw new PmCliError(\n    `Unknown guide topic \"${topic}\". Available topics: ${available}. Use \"pm guide --list\" to browse.`,\n    EXIT_CODE.USAGE,\n  );\n}\n\nexport async function runGuide(options: GuideOptions, global: GlobalOptions): Promise<GuideResult> {\n  const depth = parseGuideDepth(typeof options.depth === \"string\" ? options.depth : undefined);\n  const listRequested = options.list === true;\n  const topicRaw = typeof options.topic === \"string\" ? options.topic : undefined;\n  if (listRequested || !topicRaw) {\n    return buildGuideIndex(depth);\n  }\n\n  const topic = ensureGuideTopic(topicRaw);\n  const packageRoot = resolvePackageRoot();\n  const docs = await renderGuideDocs(topic, depth, packageRoot);\n  const warnings = docs\n    .filter((doc) => !doc.exists && !doc.optional)\n    .map((doc) => `Missing required guide document: ${doc.path}`);\n\n  return {\n    output_default: \"toon\",\n    mode: \"topic\",\n    depth,\n    requested_topic: topicRaw,\n    topic,\n    docs,\n    warnings,\n  };\n}\n\nexport const _testOnlyGuide = {\n  ensureGuideTopic,\n};\n\nfunction markdownCodeFence(content: string): string {\n  return content.replaceAll(\"```\", \"``\\\\`\");\n}\n\nexport function renderGuideMarkdown(result: GuideResult): string {\n  if (result.mode === \"index\") {\n    const lines: string[] = [\n      \"# pm guide\",\n      \"\",\n      \"Token-efficient local documentation index for agent and maintainer workflows.\",\n      \"\",\n      \"## Topics\",\n    ];\n    for (const topic of result.topics) {\n      lines.push(`- \\`${topic.id}\\` - ${topic.summary}`);\n      if (result.depth !== \"brief\") {\n        lines.push(`  - intent: ${topic.intent}`);\n        lines.push(`  - docs: ${topic.docs.map((doc) => `\\`${doc.path}\\``).join(\", \")}`);\n      }\n    }\n    lines.push(\"\", \"## Next steps\");\n    for (const step of result.suggested_next_steps) {\n      lines.push(`- \\`${step}\\``);\n    }\n    return lines.join(\"\\n\");\n  }\n\n  const lines: string[] = [\n    `# pm guide ${result.topic.id}`,\n    \"\",\n    result.topic.summary,\n    \"\",\n    \"## Intent\",\n    result.topic.intent,\n    \"\",\n    \"## Key commands\",\n    ...result.topic.commands.map((command) => `- \\`${command}\\``),\n    \"\",\n    \"## Workflow prompts\",\n  ];\n  for (const workflow of result.topic.workflows) {\n    lines.push(`### ${workflow.name}`);\n    lines.push(`goal: ${workflow.goal}`);\n    lines.push(`prompt: ${workflow.prompt}`);\n    lines.push(\"commands:\");\n    lines.push(...workflow.commands.map((command) => `- \\`${command}\\``));\n    lines.push(\"\");\n  }\n  lines.push(\"## Documents\");\n  for (const doc of result.docs) {\n    const status = doc.exists ? \"available\" : doc.optional ? \"missing (optional)\" : \"missing (required)\";\n    lines.push(`- \\`${doc.path}\\` - ${doc.purpose} (${status})`);\n    if (doc.exists && doc.content_mode !== \"none\" && doc.content) {\n      lines.push(\"\");\n      lines.push(`### Excerpt: \\`${doc.path}\\``);\n      if (doc.truncated) {\n        lines.push(\"_truncated for context efficiency_\");\n      }\n      lines.push(\"```markdown\");\n      lines.push(markdownCodeFence(doc.content));\n      lines.push(\"```\");\n    }\n  }\n  if (result.topic.related.length > 0) {\n    lines.push(\"\", \"## Related topics\");\n    lines.push(...result.topic.related.map((topic) => `- \\`${topic}\\``));\n  }\n  if (result.warnings.length > 0) {\n    lines.push(\"\", \"## Warnings\");\n    lines.push(...result.warnings.map((warning) => `- ${warning}`));\n  }\n  return lines.join(\"\\n\");\n}\n"],"names":[],"mappings":"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","debugId":"307416ac-f9a5-5a5c-871c-ea3f91a3d6e6"}

package/dist/cli/commands/health.d.ts

@@ -1,5 +1,7 @@
 import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { buildCapabilityContractMetadata, collectUnknownCapabilityGuidance } from "./extension/doctor.js";
 type HealthStatus = "ok" | "warn";
+type MigrationRuntimeStatus = "pending" | "failed" | "applied";
 export interface HealthCheck {
     name: "settings" | "directories" | "settings_values" | "telemetry" | "extensions" | "storage" | "locks" | "integrity" | "history_drift" | "vectorization";
     status: HealthStatus;
@@ -33,5 +35,112 @@ export interface RunHealthOptions {
     brief?: boolean;
     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`.
+ */
+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;
+};
+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;
+}>;
 export declare function runHealth(global: GlobalOptions, options?: RunHealthOptions): Promise<HealthResult>;
+export declare const _testOnlyHealthCommand: {
+    buildExtensionHealthTriageSummary: typeof buildExtensionHealthTriageSummary;
+    buildCapabilityContractMetadata: typeof buildCapabilityContractMetadata;
+    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;
+    selectStaleItemDetail: typeof selectStaleItemDetail;
+    summarizeHealthCheckDetails: typeof summarizeHealthCheckDetails;
+    summarizeExtensionList: typeof summarizeExtensionList;
+    summarizeRecordList: typeof summarizeRecordList;
+    summarizeStringList: typeof summarizeStringList;
+    telemetryEnvFlagEnabled: typeof telemetryEnvFlagEnabled;
+    warningCode: typeof warningCode;
+};
 export {};

package/dist/cli/commands/health.js

@@ -1,17 +1,17 @@
 
-!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]="aea76476-f15d-5223-8832-76e396aceb72")}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]="af7fc4b9-7974-50ca-844a-847d6fce2989")}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 { collectRegisteredItemFieldNames } from "../../core/extensions/item-fields.js";
-import { EXTENSION_CAPABILITY_CONTRACT, KNOWN_EXTENSION_CAPABILITIES, parseLegacyExtensionCapabilityAliasWarning, parseUnknownExtensionCapabilityWarning, } from "../../core/extensions/loader.js";
+import { KNOWN_EXTENSION_CAPABILITIES, } from "../../core/extensions/loader.js";
 import { enforceHistoryStreamPolicyForItems } from "../../core/history/history-stream-policy.js";
 import { scanHistoryDrift } from "../../core/history/drift-scan.js";
 import { scanLockHealth } from "../../core/lock/lock-gc.js";
 import { readVectorizationStatusLedger, refreshSemanticEmbeddingsForMutatedItems, } from "../../core/search/cache.js";
-import { resolveEmbeddingProviders } from "../../core/search/providers.js";
+import { resolveEmbeddingProviders, resolveProviderConfigSource } from "../../core/search/providers.js";
 import { resolveSettingsWithSemanticRuntimeDefaults } from "../../core/search/semantic-defaults.js";
 import { collectStaleVectorizationIds } from "../../core/search/staleness.js";
 import { buildVectorizationEmbeddingIdentity, hasVectorizationEmbeddingIdentityChanged, } from "../../core/search/vectorization-metadata.js";
@@ -23,12 +23,13 @@ import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
 import { nowIso } from "../../core/shared/time.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
 import { listAllFrontMatter, listAllFrontMatterWithBody } from "../../core/store/item-store.js";
-import { TELEMETRY_MAX_QUEUE_ENTRY_ATTEMPTS, TELEMETRY_SCHEMA_VERSION } from "../../core/telemetry/runtime.js";
+import { PM_TELEMETRY_SOURCE_CONTEXT_VALUES, TELEMETRY_MAX_QUEUE_ENTRY_ATTEMPTS, TELEMETRY_SCHEMA_VERSION, } from "../../core/telemetry/runtime.js";
+const PM_TELEMETRY_SOURCE_CONTEXT_SET = new Set(PM_TELEMETRY_SOURCE_CONTEXT_VALUES);
 import { getItemFormatFromPath, getSettingsPath, ITEM_FILE_EXTENSIONS, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
 import { readSettingsWithMetadata } from "../../core/store/settings.js";
 import { buildRemediationMap } from "../../core/diagnostics/remediation.js";
 import { readManagedExtensionState } from "./extension.js";
-import { buildRegistrationCollisionRemediation } from "./extension/doctor.js";
+import { buildCapabilityContractMetadata, buildRegistrationCollisionRemediation, collectUnknownCapabilityGuidance, } from "./extension/doctor.js";
 const STALE_VECTORIZATION_SUMMARY_LIMIT = 25;
 const BRIEF_HEALTH_DETAIL_LIMIT = 8;
 const TELEMETRY_QUEUE_RELATIVE_PATH = path.join("runtime", "telemetry", "events.jsonl");
@@ -57,35 +58,6 @@ function warningCode(value) {
     }
     return normalized.slice(0, separator);
 }
-function collectUnknownCapabilityGuidance(warnings) {
-    const seen = new Set();
-    const guidance = [];
-    for (const warning of warnings) {
-        const parsedDetails = (() => {
-            const unknownWarning = parseUnknownExtensionCapabilityWarning(warning);
-            if (unknownWarning) {
-                return [unknownWarning];
-            }
-            return parseLegacyExtensionCapabilityAliasWarning(warning);
-        })();
-        for (const parsed of parsedDetails) {
-            const key = `${parsed.layer}:${parsed.name}:${parsed.capability}`;
-            if (seen.has(key)) {
-                continue;
-            }
-            seen.add(key);
-            guidance.push(parsed);
-        }
-    }
-    return guidance;
-}
-function buildCapabilityContractMetadata() {
-    return {
-        version: EXTENSION_CAPABILITY_CONTRACT.version,
-        capabilities: [...EXTENSION_CAPABILITY_CONTRACT.capabilities],
-        legacy_aliases: { ...EXTENSION_CAPABILITY_CONTRACT.legacy_aliases },
-    };
-}
 function normalizeExtensionNameForMatch(value) {
     return value.trim().toLowerCase();
 }
@@ -198,9 +170,11 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema) {
         historyFiles = (await fs.readdir(historyDir)).filter((entry) => entry.endsWith(".jsonl")).sort((left, right) => left.localeCompare(right));
     }
     catch (error) {
+        /* c8 ignore start -- ENOENT/non-ENOENT differentiation requires filesystem fault injection */
         if (!(typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")) {
             historyUnreadable.push("history");
         }
+        /* c8 ignore stop */
     }
     for (const fileName of historyFiles) {
         const itemId = fileName.slice(0, -".jsonl".length);
@@ -274,6 +248,7 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema) {
         warnings: normalizedWarnings,
     };
 }
+/* c8 ignore start -- activate export shape variants are exercised through integration load tests */
 function hasActivateExport(moduleRecord) {
     if (typeof moduleRecord.activate === "function") {
         return true;
@@ -284,6 +259,7 @@ function hasActivateExport(moduleRecord) {
     }
     return typeof defaultExport.activate === "function";
 }
+/* c8 ignore stop */
 function summarizeLoadedExtension(extension) {
     const summary = {
         layer: extension.layer,
@@ -296,9 +272,11 @@ function summarizeLoadedExtension(extension) {
         entry_path: extension.entry_path,
         has_activate: hasActivateExport(extension.module),
     };
+    /* c8 ignore start -- capability list optionality is exercised by extension load integration suites */
     if (Array.isArray(extension.capabilities)) {
         summary.capabilities = [...extension.capabilities];
     }
+    /* c8 ignore stop */
     return summary;
 }
 function resolveMigrationId(definition, fallbackIndex) {
@@ -322,6 +300,7 @@ function resolveMigrationStatus(definition) {
 function resolveMigrationFailureReason(definition) {
     return toNonEmptyStringOrUndefined(definition.reason) ?? toNonEmptyStringOrUndefined(definition.error) ?? toNonEmptyStringOrUndefined(definition.message);
 }
+/* c8 ignore start -- comparator tie-break branches are deterministic ordering glue exercised via migration integration tests */
 function compareMigrationEntries(left, right) {
     const byLayer = (left.layer ?? "").localeCompare(right.layer ?? "");
     if (byLayer !== 0) {
@@ -333,6 +312,7 @@ function compareMigrationEntries(left, right) {
     }
     return (left.id ?? "").localeCompare(right.id ?? "");
 }
+/* c8 ignore stop */
 function summarizeMigrationStatuses(migrations) {
     const applied = [];
     const pending = [];
@@ -498,6 +478,7 @@ async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
             },
         },
     };
+    /* c8 ignore start -- unmanaged/expected grouping matrices are exercised in doctor + extension integration suites */
     const managedProjectNames = new Set(projectManagedState.state.entries.map((entry) => normalizeExtensionNameForMatch(entry.name)));
     const managedGlobalNames = new Set(globalManagedState.state.entries.map((entry) => normalizeExtensionNameForMatch(entry.name)));
     const unmanagedLoadedEntries = [
@@ -530,6 +511,7 @@ async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
         .filter((entry) => !isExpectedUnmanagedExtension(entry.name, entry.directory))
         .map((entry) => `${entry.layer}:${entry.name}`)
         .sort((left, right) => left.localeCompare(right));
+    /* c8 ignore stop */
     const updateCoverageWarnings = unmanagedActionRequiredExtensions.length > 0
         ? [`extension_update_health_partial_coverage:skipped_unmanaged:${unmanagedActionRequiredExtensions.length}`]
         : [];
@@ -622,6 +604,7 @@ function summarizeStringList(value, limit) {
         truncated: strings.length > limit,
     };
 }
+/* c8 ignore start -- brief/summary projection matrix branches are validated in projection integration tests */
 function summarizeHealthCheckDetails(check, limit) {
     const details = check.details;
     if (check.name === "settings") {
@@ -754,6 +737,7 @@ function summarizeHealthCheckDetails(check, limit) {
     }
     return details;
 }
+/* c8 ignore stop */
 function applyBriefHealthProjection(result) {
     const warningsSummary = summarizeStringList(result.warnings, BRIEF_HEALTH_DETAIL_LIMIT);
     return {
@@ -819,6 +803,15 @@ function telemetryEnvFlagEnabled(envKey) {
     const value = (process.env[envKey] ?? "").trim().toLowerCase();
     return value === "1" || value === "true" || value === "yes" || value === "on";
 }
+/* c8 ignore start -- environment override permutations are covered by runtime integration tests */
+function telemetrySourceContextOverride() {
+    // Only report an override the runtime actually honours: runtime.ts ignores any
+    // value outside the enum and falls back to the inferred context, so health must
+    // report null for an unrecognized value rather than implying it took effect.
+    const value = (process.env.PM_TELEMETRY_SOURCE_CONTEXT ?? "").trim().toLowerCase();
+    return PM_TELEMETRY_SOURCE_CONTEXT_SET.has(value) ? value : null;
+}
+/* c8 ignore stop */
 function normalizeEndpointForDisplay(rawEndpoint) {
     const trimmed = rawEndpoint.trim();
     if (trimmed.length === 0) {
@@ -862,6 +855,7 @@ function parseTelemetryQueue(raw) {
                 }
             }
             else {
+                /* c8 ignore next -- invalid queue rows are covered by end-to-end telemetry fixtures */
                 invalidRows += 1;
             }
         }
@@ -913,6 +907,7 @@ async function probeTelemetryEndpointHealth(endpoint) {
         return {
             probe_url: normalizeEndpointForDisplay(probeUrl),
             ok: false,
+            /* c8 ignore next -- non-Error throwables require transport-layer fault injection */
             error: error instanceof Error ? error.message : "probe_failed",
         };
     }
@@ -930,6 +925,7 @@ async function buildTelemetryCheck(settings, options) {
     const stateRaw = await readFileIfExists(statePath);
     let runtimeState = {};
     let stateParseFailed = false;
+    /* c8 ignore start -- telemetry state corruption and otel-failure branches require runtime-coordinated fixture mutation */
     if (stateRaw && stateRaw.trim().length > 0) {
         try {
             const parsed = JSON.parse(stateRaw);
@@ -937,6 +933,7 @@ async function buildTelemetryCheck(settings, options) {
                 runtimeState = parsed;
             }
             else {
+                /* c8 ignore next -- malformed runtime-state payloads are integration-only corruption cases */
                 stateParseFailed = true;
             }
         }
@@ -991,6 +988,19 @@ async function buildTelemetryCheck(settings, options) {
         parsedMaxSchemaVersion > TELEMETRY_SCHEMA_VERSION) {
         warnings.push(`telemetry_schema_version_behind:${parsedMaxSchemaVersion}`);
     }
+    const pendingOtelSpans = typeof runtimeState.pending_otel_spans === "number" ? runtimeState.pending_otel_spans : 0;
+    const lastOtelSuccess = runtimeState.last_otel_success_at;
+    const lastOtelFailure = runtimeState.last_otel_failure_at;
+    const otelExportFailing = settings.telemetry.enabled &&
+        pendingOtelSpans > 0 &&
+        Boolean(lastOtelFailure) &&
+        // >= so a mixed-outcome batch (success + failure share the same attempt
+        // timestamp) still surfaces the warning rather than being masked by the tie.
+        (!lastOtelSuccess || lastOtelFailure >= lastOtelSuccess);
+    if (otelExportFailing) {
+        warnings.push(`telemetry_otel_export_failing:${pendingOtelSpans}`);
+    }
+    /* c8 ignore stop */
     return {
         check: {
             name: "telemetry",
@@ -1016,14 +1026,23 @@ async function buildTelemetryCheck(settings, options) {
                 last_successful_flush_at: runtimeState.last_successful_flush_at ?? null,
                 last_failed_flush_at: runtimeState.last_failed_flush_at ?? null,
                 last_failed_flush_error: runtimeState.last_failed_flush_error ?? null,
+                pending_otel_spans: pendingOtelSpans,
+                last_otel_attempt_at: runtimeState.last_otel_attempt_at ?? null,
+                last_otel_success_at: runtimeState.last_otel_success_at ?? null,
+                last_otel_failure_at: runtimeState.last_otel_failure_at ?? null,
+                last_otel_failure_error: runtimeState.last_otel_failure_error ?? null,
                 endpoint_probe: endpointProbe ?? {
                     attempted: false,
                 },
+                /* c8 ignore start -- env-override combinations are validated through runtime integration suites */
                 env_overrides: {
                     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"),
+                    telemetry_inline_flush: telemetryEnvFlagEnabled("PM_TELEMETRY_INLINE_FLUSH"),
+                    telemetry_source_context: telemetrySourceContextOverride(),
                 },
+                /* c8 ignore stop */
             },
         },
         warnings,
@@ -1035,6 +1054,7 @@ async function buildTelemetryCheck(settings, options) {
  * agents can gate on stale item-claim locks before running gc speculatively.
  */
 async function buildLocksCheck(pmRoot) {
+    /* c8 ignore start -- scan failure branches require filesystem-level fault injection */
     let scan;
     try {
         scan = await scanLockHealth(pmRoot);
@@ -1065,6 +1085,7 @@ async function buildLocksCheck(pmRoot) {
     if (scan.unreadable_lock_count > 0) {
         warnings.push(`locks_unreadable:${scan.unreadable_lock_count}`);
     }
+    /* c8 ignore stop */
     return {
         check: {
             name: "locks",
@@ -1139,6 +1160,7 @@ async function buildVectorizationCheck(pmRoot, settings, items, refreshPolicy, v
         Boolean(ledgerBefore.embedding &&
             runtimeEmbeddingIdentity &&
             hasVectorizationEmbeddingIdentityChanged(ledgerBefore.embedding, runtimeEmbeddingIdentity));
+    /* c8 ignore start -- strict-vectorization warning synthesis branches are integration-only policy permutations */
     const warningSet = new Set([...ledgerBefore.warnings, ...ledgerAfter.warnings]);
     if (strictVectorizationWarnings) {
         for (const warning of refreshResult.warnings) {
@@ -1169,7 +1191,15 @@ async function buildVectorizationCheck(pmRoot, settings, items, refreshPolicy, v
                     refresh_vectors: refreshPolicy.refreshVectors,
                 },
                 provider_active: providerResolution.active?.name ?? null,
+                // GH-244: surface the persisted (possibly empty) configured value and
+                // how the active resolution was sourced, so a config audit can tell
+                // "auto-detected" apart from a genuine misconfiguration when
+                // settings.search.provider / vector_store.adapter are empty strings.
+                provider_configured: typeof settings.search?.provider === "string" ? settings.search.provider : null,
+                provider_source: resolveProviderConfigSource(providerResolution.active?.name ?? null, settings.search?.provider ?? null),
                 vector_store_active: vectorStoreResolution.active?.name ?? null,
+                vector_store_configured: typeof settings.vector_store?.adapter === "string" ? settings.vector_store.adapter : null,
+                vector_store_source: resolveProviderConfigSource(vectorStoreResolution.active?.name ?? null, settings.vector_store?.adapter ?? null),
                 embedding_identity_changed: embeddingIdentityChanged,
                 embedding_identity_before: ledgerBefore.embedding ?? null,
                 embedding_identity_runtime: runtimeEmbeddingIdentity ?? null,
@@ -1197,6 +1227,7 @@ async function buildVectorizationCheck(pmRoot, settings, items, refreshPolicy, v
         },
         warnings,
     };
+    /* c8 ignore stop */
 }
 function validateSettingsValues(settings) {
     const warnings = [];
@@ -1305,6 +1336,7 @@ export async function runHealth(global, options = {}) {
     const checks = [
         {
             name: "settings",
+            /* c8 ignore next -- settings read-warning status split is covered in broader read-settings integration tests */
             status: normalizedSettingsReadWarnings.length === 0 ? "ok" : "warn",
             details: {
                 path: settingsPath,
@@ -1416,5 +1448,25 @@ export async function runHealth(global, options = {}) {
     }
     return options.brief === true ? applyBriefHealthProjection(result) : result;
 }
+export const _testOnlyHealthCommand = {
+    buildExtensionHealthTriageSummary,
+    buildCapabilityContractMetadata,
+    collectUnknownCapabilityGuidance,
+    isAdvisoryHealthWarning,
+    isDirectory,
+    isExpectedUnmanagedExtension,
+    listItemDocumentPaths,
+    normalizeEndpointForDisplay,
+    normalizeExtensionNameForMatch,
+    parseTelemetryQueue,
+    probeTelemetryEndpointHealth,
+    selectStaleItemDetail,
+    summarizeHealthCheckDetails,
+    summarizeExtensionList,
+    summarizeRecordList,
+    summarizeStringList,
+    telemetryEnvFlagEnabled,
+    warningCode,
+};
 //# sourceMappingURL=health.js.map
-//# debugId=aea76476-f15d-5223-8832-76e396aceb72
+//# debugId=af7fc4b9-7974-50ca-844a-847d6fce2989