@principles/pd-cli 1.73.2 → 1.74.0

package/src/commands/config-doctor.ts

@@ -0,0 +1,158 @@
+/**
+ * pd config doctor — Discover and explain PD / OpenClaw configuration state.
+ *
+ * PRI-299 MVP UX:
+ *   - Reports workspace + OpenClaw config paths and existence
+ *   - Lists effective feature flags and enabled MVP channels
+ *   - Classifies provider/model/auth connectivity (healthy, auth_missing, rate_limit, etc.)
+ *   - Emits `reason` + `nextActions` for failures
+ *   - NEVER leaks tokens, env var values, or raw config bytes
+ *
+ * Usage:
+ *   pd config doctor [--workspace <path>] [--json]
+ */
+
+import * as path from 'path';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { buildDoctorOutput, type DoctorOutput } from '../services/config-doctor.js';
+
+interface DoctorOptions {
+  workspace?: string;
+  json?: boolean;
+}
+
+function formatTextOutput(output: DoctorOutput): string {
+  const lines: string[] = [];
+  const statusIcon = output.status === 'ok' ? '✓' : output.status === 'degraded' ? '⚠' : '✗';
+
+  lines.push('PD Config Doctor');
+  lines.push(`status: ${statusIcon} ${output.status.toUpperCase()}`);
+  lines.push(`workspace: ${output.workspaceDir}`);
+  lines.push('');
+
+  lines.push('PD config paths:');
+  for (const [k, v] of Object.entries(output.pdConfigPaths)) {
+    const exists = v.exists ? '[exists]' : '[missing]';
+    lines.push(`  ${k.padEnd(16)} ${exists.padEnd(10)} ${v.path}`);
+  }
+  lines.push('');
+
+  lines.push('OpenClaw paths:');
+  for (const [k, v] of Object.entries(output.openclawConfigPaths)) {
+    const exists = v.exists ? '[exists]' : '[missing]';
+    lines.push(`  ${k.padEnd(16)} ${exists.padEnd(10)} ${v.path}`);
+  }
+  lines.push('');
+
+  lines.push(`Feature flags: source=${output.featureFlags.source}`);
+  lines.push(`  enabled MVP channels: ${output.featureFlags.enabledMvpChannels.length === 0 ? '(none)' : output.featureFlags.enabledMvpChannels.join(', ')}`);
+  if (output.featureFlags.disabledFlags.length > 0) {
+    lines.push(`  disabled: ${output.featureFlags.disabledFlags.join(', ')}`);
+  }
+  if (output.featureFlags.warnings.length > 0) {
+    lines.push(`  warnings: ${output.featureFlags.warnings.length}`);
+  }
+  lines.push('');
+
+  lines.push('Provider health:');
+  if (output.providerHealth.length === 0) {
+    lines.push('  (no providers discovered)');
+  } else {
+    for (const p of output.providerHealth) {
+      const cls = p.classification.toUpperCase();
+      const provider = p.provider ?? '(unset)';
+      const model = p.model ?? '(unset)';
+      const apiKeyEnv = p.apiKeyEnv ?? '(unset)';
+      const apiKeyState = p.apiKeyPresent ? 'present' : 'absent';
+      lines.push(`  [${cls}] ${provider} / ${model}`);
+      lines.push(`    apiKeyEnv:   ${apiKeyEnv} (${apiKeyState})`);
+      lines.push(`    source:      ${p.source}`);
+      lines.push(`    reason:      ${p.reason}`);
+      lines.push(`    nextAction:  ${p.nextAction}`);
+    }
+  }
+  lines.push('');
+
+  lines.push('Internal agents:');
+  if (output.internalAgents && output.internalAgents.correctionObserver) {
+    const co = output.internalAgents.correctionObserver;
+    const coStatus = co.status.toUpperCase();
+    const coProvider = co.provider ?? '(unset)';
+    const coModel = co.model ?? '(unset)';
+    const coApiKeyEnv = co.apiKeyEnv ?? '(unset)';
+    const coApiKeyState = co.apiKeyPresent ? 'present' : 'absent';
+    lines.push(`  correctionObserver: [${coStatus}]`);
+    lines.push(`    enabled:     ${co.enabled}`);
+    lines.push(`    flagSource:  ${co.flagSource}`);
+    lines.push(`    configSource:${co.configSource}`);
+    if (co.provider || co.model) {
+      lines.push(`    provider:    ${coProvider} / ${coModel}`);
+    }
+    lines.push(`    apiKeyEnv:   ${coApiKeyEnv} (${coApiKeyState})`);
+    lines.push(`    reason:      ${co.reason}`);
+    lines.push(`    nextAction:  ${co.nextAction}`);
+  } else {
+    lines.push('  (no internal agents diagnosed)');
+  }
+  lines.push('');
+
+  if (output.warnings.length > 0) {
+    lines.push('Warnings:');
+    for (const w of output.warnings) {
+      lines.push(`  [!] ${w}`);
+    }
+    lines.push('');
+  }
+
+  if (output.reason) {
+    lines.push(`Reason: ${output.reason}`);
+    lines.push('');
+  }
+
+  if (output.nextActions.length > 0) {
+    lines.push('Next actions:');
+    for (const a of output.nextActions) {
+      lines.push(`  → ${a}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export async function handleConfigDoctor(opts: DoctorOptions): Promise<void> {
+  let workspaceDir: string;
+  try {
+    workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const output = {
+      status: 'failed' as const,
+      reason: 'workspace_resolution_failed',
+      message,
+      nextActions: ['Pass --workspace <path> explicitly, or set PD_WORKSPACE_DIR environment variable'],
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(output, null, 2));
+    } else {
+      console.error(`error: ${message}`);
+    }
+    process.exit(1);
+    return;
+  }
+
+  const output = await buildDoctorOutput({ workspaceDir });
+
+  if (opts.json) {
+    // JSON mode: single parseable object on stdout.
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    console.log(formatTextOutput(output));
+  }
+
+  if (output.status === 'failed') {
+    process.exitCode = 1;
+  } else if (output.status === 'degraded') {
+    // degraded: do not exit 1, but emit a hint to stderr for the operator.
+    console.error(`\nNote: doctor status is degraded. Inspect warnings + nextActions.`);
+  }
+}

package/src/index.ts

@@ -1,6 +1,6 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
- * pd CLI — Principles Disciple command-line interface.
+ * pd CLI 鈥?Principles Disciple command-line interface.
  *
  * Usage:
  *   pd pain record --reason <text> [--score N] [--source manual]
@@ -55,7 +55,7 @@ const program = new Command();
 
 program
   .name('pd')
-  .description('PD CLI — Pain recording, sample management, and evolution tasks')
+  .description('PD CLI 鈥?Pain recording, sample management, and evolution tasks')
   .version(pkg.version);
 
 const painCmd = program
@@ -147,7 +147,7 @@ centralCmd
     await handleCentralSync();
   });
 
-// ── Runtime v2 task/run commands ──────────────────────────────────────────────
+// 鈹€鈹€ Runtime v2 task/run commands 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
 
 const rtTaskCmd = program
   .command('task')
@@ -190,7 +190,7 @@ rtRunCmd
     await handleRunShow({ id: runId });
   });
 
-// ── Runtime v2 trajectory/history/context commands ───────────────────────────
+// 鈹€鈹€ Runtime v2 trajectory/history/context commands 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
 
 const trajectoryCmd = program
   .command('trajectory')
@@ -239,7 +239,7 @@ contextCmd
     await handleContextBuild(taskId, opts);
   });
 
-// ── Legacy import command ───────────────────────────────────────────────────────
+// 鈹€鈹€ Legacy import command 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
 
 const legacyCmd = program
   .command('legacy')
@@ -258,7 +258,7 @@ importCmd
     await handleLegacyImportOpenClaw(opts);
   });
 
-// ── Diagnostician run/status commands ─────────────────────────────────────
+// 鈹€鈹€ Diagnostician run/status commands 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
 
 const diagnoseCmd = program
   .command('diagnose')
@@ -283,19 +283,19 @@ diagnoseCmd
   .option('--openclaw-local', 'Use local OpenClaw (mutually exclusive with --openclaw-gateway)')
   .option('--openclaw-gateway', 'Use gateway OpenClaw (mutually exclusive with --openclaw-local)')
   .option('-a, --agent <agentId>', 'Agent ID to invoke')
-  .option('--provider <name>', 'LLM provider (e.g., openrouter) — for pi-ai, falls back to policy')
-  .option('--model <id>', 'Model ID (e.g., anthropic/claude-sonnet-4) — for pi-ai, falls back to policy')
-  .option('--apiKeyEnv <name>', 'Env var name for API key — for pi-ai, falls back to policy')
-  .option('--baseUrl <url>', 'Custom base URL — for pi-ai, falls back to policy')
-  .option('--maxRetries <n>', 'Max retry attempts for LLM failures — for pi-ai, falls back to policy', parseInt)
-  .option('--timeoutMs <ms>', 'Timeout in milliseconds — for pi-ai, falls back to policy', parseInt)
+  .option('--provider <name>', 'LLM provider (e.g., openrouter) 鈥?for pi-ai, falls back to policy')
+  .option('--model <id>', 'Model ID (e.g., anthropic/claude-sonnet-4) 鈥?for pi-ai, falls back to policy')
+  .option('--apiKeyEnv <name>', 'Env var name for API key 鈥?for pi-ai, falls back to policy')
+  .option('--baseUrl <url>', 'Custom base URL 鈥?for pi-ai, falls back to policy')
+  .option('--maxRetries <n>', 'Max retry attempts for LLM failures 鈥?for pi-ai, falls back to policy', parseInt)
+  .option('--timeoutMs <ms>', 'Timeout in milliseconds 鈥?for pi-ai, falls back to policy', parseInt)
   .option('--no-intake', 'Skip candidate intake after successful diagnosis')
   .option('--json', 'Output raw JSON')
   .action(async (opts) => {
     await handleDiagnoseRun(opts);
   });
 
-// ── Runtime probe command (HG-01 HARD GATE) ─────────────────────────────────
+// 鈹€鈹€ Runtime probe command (HG-01 HARD GATE) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
 
 const runtimeCmd = program
   .command('runtime')
@@ -316,7 +316,7 @@ const synthCmd = runtimeCmd
 
 synthCmd
   .command('baseline')
-  .description('Run synthetic PD workload baseline (PRI-206) — deterministic, no LLM required')
+  .description('Run synthetic PD workload baseline (PRI-206) 鈥?deterministic, no LLM required')
   .option('-w, --workspace <path>', 'Workspace directory (default: temp workspace)')
   .option('--json', 'Output raw JSON')
   .action(async (opts) => {
@@ -325,7 +325,7 @@ synthCmd
 
 synthCmd
   .command('flood')
-  .description('Run pain flood simulation (PRI-208) — deterministic dedup/stress test, no LLM required')
+  .description('Run pain flood simulation (PRI-208) 鈥?deterministic dedup/stress test, no LLM required')
   .option('-w, --workspace <path>', 'Workspace directory (default: temp workspace)')
   .option('--json', 'Output raw JSON')
   .option('--identical-count <n>', 'Number of identical pain signals (default: 10)', parseInt)
@@ -343,7 +343,7 @@ synthCmd
 
 synthCmd
   .command('proven-channel')
-  .description('Run MVP activation continuity baseline (PRI-240) — deterministic, no LLM required')
+  .description('Run MVP activation continuity baseline (PRI-240) 鈥?deterministic, no LLM required')
   .option('-w, --workspace <path>', 'Workspace directory (default: temp workspace)')
   .option('--json', 'Output raw JSON')
   .option('--channels <channels>', 'Comma-separated channel list (prompt,code_tool_hook,defer_archive)')
@@ -373,7 +373,7 @@ const demoCmd = program
 
 demoCmd
   .command('story-a')
-  .description('Run Story A\' proven-channel demo (PRI-246) — full evidence→proposal→approval→activation→observation chain')
+  .description('Run Story A\' proven-channel demo (PRI-246) 鈥?full evidence鈫抪roposal鈫抋pproval鈫抋ctivation鈫抩bservation chain')
   .option('-w, --workspace <path>', 'Workspace directory (default: temp workspace)')
   .option('--json', 'Output raw JSON')
   .option('--channels <channels>', 'Comma-separated channel list (prompt,code_tool_hook,defer_archive)')
@@ -392,13 +392,13 @@ runtimeCmd
   .option('--openclaw-local', 'Use local OpenClaw (mutually exclusive with --openclaw-gateway)')
   .option('--openclaw-gateway', 'Use gateway OpenClaw (mutually exclusive with --openclaw-local)')
   .option('-a, --agent <agentId>', 'Agent ID to probe')
-  .option('--provider <name>', 'LLM provider (e.g., openrouter) — for pi-ai, falls back to --workspace workflows.yaml')
-  .option('--model <id>', 'Model ID (e.g., anthropic/claude-sonnet-4) — for pi-ai, falls back to --workspace workflows.yaml')
-  .option('--apiKeyEnv <name>', 'Env var name for API key (e.g., OPENROUTER_API_KEY) — for pi-ai, falls back to --workspace workflows.yaml')
-  .option('--baseUrl <url>', 'Custom base URL for OpenAI-compatible providers — for pi-ai, falls back to --workspace workflows.yaml')
+  .option('--provider <name>', 'LLM provider (e.g., openrouter) 鈥?for pi-ai, falls back to --workspace workflows.yaml')
+  .option('--model <id>', 'Model ID (e.g., anthropic/claude-sonnet-4) 鈥?for pi-ai, falls back to --workspace workflows.yaml')
+  .option('--apiKeyEnv <name>', 'Env var name for API key (e.g., OPENROUTER_API_KEY) 鈥?for pi-ai, falls back to --workspace workflows.yaml')
+  .option('--baseUrl <url>', 'Custom base URL for OpenAI-compatible providers 鈥?for pi-ai, falls back to --workspace workflows.yaml')
   .option('--maxRetries <n>', 'Max retry attempts for LLM failures', parseInt)
   .option('--timeoutMs <ms>', 'Timeout in milliseconds for probe', parseInt)
-  .option('-w, --workspace <path>', 'Workspace directory — loads pi-ai policy from .state/workflows.yaml')
+  .option('-w, --workspace <path>', 'Workspace directory 鈥?loads pi-ai policy from .state/workflows.yaml')
   .option('--json', 'Output raw JSON')
   .action(async (opts) => {
     await handleRuntimeProbe(opts);
@@ -462,17 +462,17 @@ runtimeHealthCmd
 
 runtimeHealthCmd
   .command('gfi')
-  .description('GFI workspace snapshot — active vs stale session breakdown')
+  .description('GFI workspace snapshot 鈥?active vs stale session breakdown')
   .option('-w, --workspace <path>', 'Workspace directory')
   .option('--json', 'Output raw JSON')
   .action(async (opts) => {
     await handleRuntimeGfiSnapshot({ workspace: opts.workspace, json: opts.json });
   });
 
-// PRI-82: pd runtime gfi snapshot — canonical operator command (alias of runtime health gfi)
+// PRI-82: pd runtime gfi snapshot 鈥?canonical operator command (alias of runtime health gfi)
 runtimeCmd
   .command('gfi')
-  .description('GFI workspace snapshot — active vs stale session breakdown')
+  .description('GFI workspace snapshot 鈥?active vs stale session breakdown')
   .command('snapshot')
   .description('GFI workspace snapshot for the operator (alias: pd runtime health gfi)')
   .option('-w, --workspace <path>', 'Workspace directory')
@@ -608,7 +608,7 @@ const pruningCmd = runtimeCmd
 
 pruningCmd
   .command('report')
-  .description('Show pruning health report — watch/review principle signals')
+  .description('Show pruning health report 鈥?watch/review principle signals')
   .option('-w, --workspace <path>', 'Workspace directory')
   .option('--json', 'Output raw JSON')
   .action((opts) => {
@@ -679,7 +679,7 @@ pruningCmd
     });
   });
 
-// ── Candidate inspection commands ───────────────────────────────────────────
+// 鈹€鈹€ Candidate inspection commands 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
 
 const candidateCmd = program
   .command('candidate')
@@ -783,7 +783,7 @@ candidateInternalizationCmd
     await handleCandidateInternalizationBackfill({ workspace: opts.workspace, dryRun: opts.dryRun, confirm: opts.confirm, includePending: opts.includePending, json: opts.json });
   });
 
-// ── Artifact inspection commands ────────────────────────────────────────────
+// 鈹€鈹€ Artifact inspection commands 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
 
 const artifactCmd = program
   .command('artifact')
@@ -830,4 +830,22 @@ program
     });
   });
 
+// PRI-299: PD Config Doctor 鈥?surface config paths, feature flags, and provider connectivity
+const configCmd = program
+  .command('config')
+  .description('PD config diagnostics');
+
+configCmd
+  .command('doctor')
+  .description('Inspect PD / OpenClaw config paths, feature flags, and provider connectivity (PRI-299)')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--json', 'Output a single parseable JSON object on stdout', false)
+  .action(async (opts) => {
+    const { handleConfigDoctor } = await import('./commands/config-doctor.js');
+    await handleConfigDoctor({
+      workspace: opts.workspace,
+      json: opts.json,
+    });
+  });
+
 program.parse();