@principles/pd-cli 1.73.0

package/src/commands/pain-record.ts

@@ -0,0 +1,167 @@
+/**
+ * pd pain record command — Runtime v2 pain signal entry point.
+ *
+ * Uses PainToPrincipleService as the single write-side orchestration API.
+ *
+ * Usage:
+ *   pd pain record --reason <text> [--score N] [--source manual] [--workspace <path>] [--json]
+ */
+import {
+  PainToPrincipleService,
+  PrincipleTreeLedgerAdapter,
+  resolveRuntimeConfig,
+  isRuntimeConfigError,
+} from '@principles/core/runtime-v2';
+import type { KnownProvider } from '@mariozechner/pi-ai';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface RecordOptions {
+  reason?: string;
+  score?: number;
+  source?: string;
+  workspace?: string;
+  json?: boolean;
+}
+
+export async function handlePainRecord(opts: RecordOptions): Promise<void> {
+  if (!opts.reason) {
+    console.error('Error: --reason <text> is required');
+    console.error('Usage: pd pain record --reason <text> [--score N] [--source manual] [--workspace <path>] [--json]');
+    process.exit(1);
+  }
+
+  if (opts.score !== undefined && (isNaN(opts.score) || opts.score < 0 || opts.score > 100)) {
+    console.error('Error: --score must be a number between 0 and 100');
+    process.exit(1);
+  }
+
+  const workspaceDir = resolveWorkspaceDir(opts.workspace);
+  const stateDir = `${workspaceDir}/.state`;
+  const painId = `manual_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+
+  const ledgerAdapter = new PrincipleTreeLedgerAdapter({ stateDir });
+  const service = new PainToPrincipleService({
+    workspaceDir,
+    stateDir,
+    ledgerAdapter,
+    owner: 'pd-cli',
+    autoIntakeEnabled: true,
+  });
+
+  const result = await service.recordPain({
+    painId,
+    painType: 'user_frustration',
+    source: opts.source ?? 'manual',
+    reason: opts.reason,
+    score: opts.score ?? 80,
+    sessionId: 'cli',
+    agentId: 'pd-cli',
+    provenance: 'owner_reported_no_host_trace',
+    recordObservability: true,
+  });
+
+  // Show diagnostic info for config failures
+  if (result.failureCategory === 'config_missing') {
+    const configResult = resolveRuntimeConfig(stateDir);
+    if (isRuntimeConfigError(configResult)) {
+      if (opts.json) {
+        console.log(JSON.stringify({
+          status: 'failed',
+          painId: result.painId,
+          taskId: result.taskId,
+          failureCategory: result.failureCategory,
+          message: result.message,
+          configError: {
+            reason: configResult.reason,
+            message: configResult.message,
+            nextAction: configResult.nextAction,
+          },
+        }, null, 2));
+      } else {
+        console.error(`  Config resolution failed: ${configResult.reason}`);
+        console.error(`  ${configResult.message}`);
+        console.error(`  nextAction: ${configResult.nextAction}`);
+      }
+      process.exit(1);
+      return;
+    }
+    const config = configResult;
+    const missing: string[] = [];
+    if (!config.provider) missing.push('provider');
+    if (!config.model) missing.push('model');
+    if (!config.apiKeyEnv) missing.push('apiKeyEnv');
+    if (config.provider) {
+      try {
+        const { getProviders } = await import('@mariozechner/pi-ai');
+        const knownProviders = getProviders();
+        if (!knownProviders.includes(config.provider as KnownProvider) && !config.baseUrl) {
+          missing.push('baseUrl');
+        }
+      } catch {
+        // pi-ai may not be available
+      }
+    }
+
+    if (missing.length > 0 || config.provider || config.apiKeyEnv) {
+      console.error('Error: Pain signal failed\n');
+
+      if (missing.length > 0) {
+        console.error('  Missing configuration:');
+        for (const m of missing) {
+          console.error(`    - ${m}`);
+        }
+        console.error('');
+      }
+
+      if (config.provider || config.model || config.apiKeyEnv || config.baseUrl) {
+        console.error('  Current workflow policy (pd-runtime-v2-diagnosis):');
+        console.error(`    runtimeKind: ${config.runtimeKind}`);
+        if (config.provider) console.error(`    provider:    ${config.provider}`);
+        if (config.model) console.error(`    model:       ${config.model}`);
+        if (config.apiKeyEnv) console.error(`    apiKeyEnv:   ${config.apiKeyEnv}`);
+        if (config.baseUrl) console.error(`    baseUrl:     ${config.baseUrl}`);
+        console.error('');
+      }
+
+      console.error('  To diagnose and configure your runtime, run:');
+      console.error('    pd runtime probe --runtime pi-ai --provider <name> --model <id> --apiKeyEnv <name>');
+      console.error('');
+
+      if (result.message) console.error(`  Details: ${result.message}`);
+      process.exit(1);
+    }
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    if (result.status !== 'succeeded' && result.status !== 'skipped' && result.status !== 'retried') process.exit(1);
+  } else {
+    if (result.status === 'succeeded') {
+      console.log('[OK] Pain signal recorded via PainToPrincipleService');
+      console.log(`   Pain ID: ${result.painId}`);
+      console.log(`   Task ID: ${result.taskId}`);
+      if (result.runId) console.log(`   Run ID: ${result.runId}`);
+      if (result.artifactId) console.log(`   Artifact ID: ${result.artifactId}`);
+      if (result.candidateIds.length > 0) console.log(`   Candidate IDs: ${result.candidateIds.join(', ')}`);
+      if (result.ledgerEntryIds.length > 0) console.log(`   Ledger Entry IDs: ${result.ledgerEntryIds.join(', ')}`);
+      console.log(`   Reason: ${opts.reason}`);
+      console.log(`   Score: ${opts.score ?? 80}`);
+      console.log(`   Source: ${opts.source ?? 'manual'}`);
+      console.log(`   Workspace: ${workspaceDir}`);
+      if (result.latencyMs !== undefined) console.log(`   Latency: ${result.latencyMs}ms`);
+      console.log(`\nDiagnostician pipeline running. Check progress with:`);
+      console.log(`   pd task show ${result.taskId} --workspace "${workspaceDir}"`);
+    } else if (result.status === 'skipped') {
+      console.log(`[SKIP] Task already in progress: ${result.message ?? 'unknown'}`);
+      console.log(`   Pain ID: ${result.painId}`);
+      console.log(`   Task ID: ${result.taskId}`);
+    } else if (result.status === 'retried') {
+      console.log(`[RETRY] Task retried: ${result.message ?? 'unknown'}`);
+      console.log(`   Pain ID: ${result.painId}`);
+      console.log(`   Task ID: ${result.taskId}`);
+    } else {
+      console.error('[FAIL] Pain signal failed:', result.message);
+      process.exit(1);
+    }
+  }
+}

package/src/commands/proven-channel-baseline.ts

@@ -0,0 +1,113 @@
+import * as path from 'path';
+import * as os from 'os';
+import * as fs from 'fs';
+import { runProvenChannelBaseline } from '../services/proven-channel-baseline-runner.js';
+import { parseChannels, type ProvenChannelBaselineSummary, type MvpChannel } from '@principles/core/runtime-v2';
+
+interface ProvenChannelBaselineCliOptions {
+  workspace?: string;
+  json?: boolean;
+  channels?: string;
+}
+
+function formatChannelResult(ch: { channel: string; status: string; failureReason?: string; nextAction?: string; evidence: Record<string, unknown> }): string {
+  const icon = ch.status === 'passed' ? '✓' : ch.status === 'degraded' ? '⚠' : '✗';
+  const lines: string[] = [];
+  lines.push(`  ${icon} ${ch.channel}: ${ch.status}`);
+  if (ch.failureReason) {
+    lines.push(`    reason: ${ch.failureReason}`);
+  }
+  if (ch.nextAction) {
+    lines.push(`    nextAction: ${ch.nextAction}`);
+  }
+  return lines.join('\n');
+}
+
+function formatTextOutput(summary: ProvenChannelBaselineSummary): string {
+  const lines: string[] = [];
+  const icon = summary.status === 'passed' ? '✓' : summary.status === 'degraded' ? '⚠' : '✗';
+
+  lines.push('PD Proven Channel Baseline (PRI-240)');
+  lines.push(`generatedAt: ${summary.generatedAt}`);
+  lines.push(`workspaceMode: ${summary.workspaceMode}`);
+  lines.push(`OVERALL: ${icon} ${summary.status.toUpperCase()}`);
+  lines.push('');
+
+  if (summary.inputValidationFailure) {
+    const ivf = summary.inputValidationFailure;
+    lines.push('Input Validation Failure:');
+    lines.push(`  reason: ${ivf.reason}`);
+    lines.push(`  message: ${ivf.message}`);
+    lines.push(`  nextAction: ${ivf.nextAction}`);
+    lines.push('');
+  }
+
+  lines.push('Channel Results:');
+  for (const ch of summary.channels) {
+    lines.push(formatChannelResult(ch));
+  }
+
+  lines.push('');
+  lines.push('Continuity Matrix:');
+  for (const entry of summary.continuityMatrix) {
+    lines.push(`  ${entry.channel}:`);
+    lines.push(`    entryPoint: ${entry.entryPoint}`);
+    lines.push(`    expected: ${entry.expectedObservable}`);
+    lines.push(`    dependsOnPluginDiscovery: ${entry.dependsOnPluginDiscovery}`);
+  }
+
+  if (summary.recommendedNextIssue) {
+    lines.push('');
+    lines.push(`Recommended next issue: ${summary.recommendedNextIssue}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function cleanupTempWorkspace(workspaceDir: string, rmSyncImpl: (dir: string, opts: { recursive: boolean; force: boolean }) => void = fs.rmSync.bind(fs)): void {
+  try {
+    rmSyncImpl(workspaceDir, { recursive: true, force: true });
+  } catch (cleanupErr) {
+    const cleanupMsg = cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr);
+    console.error(`[pd-cli] cleanup warning: failed to remove temp workspace ${workspaceDir}: ${cleanupMsg}`);
+  }
+}
+
+export async function handleProvenChannelBaseline(opts: ProvenChannelBaselineCliOptions): Promise<void> {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : fs.mkdtempSync(path.join(os.tmpdir(), 'pd-proven-channel-'));
+  const workspaceMode: 'temp' | 'explicit_workspace' = opts.workspace ? 'explicit_workspace' : 'temp';
+
+  const parsed = opts.channels ? parseChannels(opts.channels) : null;
+  const userSpecifiedChannels = opts.channels !== undefined;
+  const channels: MvpChannel[] | undefined = parsed && parsed.channels.length > 0 ? parsed.channels : undefined;
+  const unknownChannels: string[] = parsed ? parsed.unknowns : [];
+  const emptyChannelInput = userSpecifiedChannels && channels === undefined && unknownChannels.length === 0;
+
+  try {
+    const summary = await runProvenChannelBaseline({
+      workspaceDir,
+      workspaceMode,
+      channels,
+      unknownChannels,
+      emptyChannelInput,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(summary, null, 2));
+    } else {
+      console.log(formatTextOutput(summary));
+    }
+
+    if (summary.status !== 'passed') {
+      console.error('');
+      console.error(`FAIL: status=${summary.status}`);
+      process.exitCode = 1;
+    }
+  } finally {
+    if (workspaceMode === 'temp') {
+      cleanupTempWorkspace(workspaceDir);
+    }
+  }
+}

package/src/commands/remediation-output.ts

@@ -0,0 +1,66 @@
+export type RemediationMode = 'dry_run' | 'confirm';
+export type RemediationStatus = 'would_change' | 'changed' | 'no_op' | 'refused' | 'error';
+
+export interface RemediationAction {
+  action: string;
+  targetId: string;
+  previousState?: string;
+  nextState?: string;
+  reason: string;
+  taskId?: string;
+  type?: string;
+  severity?: 'error' | 'warning';
+  previousStatus?: string;
+  newStatus?: string;
+  recommendedAction?: string;
+  successorTaskId?: string;
+}
+
+export interface RemediationResult {
+  mode: RemediationMode;
+  status: RemediationStatus;
+  safeToConfirm: boolean;
+  repairedCount: number;
+  skippedCount: number;
+  actions: RemediationAction[];
+  warnings: string[];
+  generatedAt?: string;
+  dryRun?: boolean;
+}
+
+export function createRemediationResult(input: {
+  mode: RemediationMode;
+  repairedCount?: number;
+  skippedCount?: number;
+  actions?: RemediationAction[];
+  warnings?: string[];
+  status?: RemediationStatus;
+  safeToConfirm?: boolean;
+  generatedAt?: string;
+  includeLegacyDryRun?: boolean;
+}): RemediationResult {
+  const actions = input.actions ?? [];
+  const warnings = input.warnings ?? [];
+  const repairedCount = input.repairedCount ?? 0;
+  const status = input.status ?? (input.mode === 'dry_run'
+    ? (actions.length > 0 ? 'would_change' : 'no_op')
+    : (repairedCount > 0 ? 'changed' : 'no_op'));
+
+  return {
+    mode: input.mode,
+    status,
+    safeToConfirm: input.safeToConfirm ?? (
+      input.mode === 'dry_run' && status === 'would_change' && warnings.length === 0
+    ),
+    repairedCount,
+    skippedCount: input.skippedCount ?? 0,
+    actions,
+    warnings,
+    ...(input.generatedAt ? { generatedAt: input.generatedAt } : {}),
+    ...(input.includeLegacyDryRun ? { dryRun: input.mode === 'dry_run' } : {}),
+  };
+}
+
+export function remediationAction(input: RemediationAction): RemediationAction {
+  return input;
+}

package/src/commands/run.ts

@@ -0,0 +1,89 @@
+/**
+ * pd run list/show commands — Runtime v2 run inspection.
+ *
+ * Usage:
+ *   pd run list <taskId>
+ *   pd run show <runId>
+ */
+import { RuntimeStateManager } from '@principles/core';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface RunListOptions {
+  taskId: string;
+}
+
+export async function handleRunList(opts: RunListOptions): Promise<void> {
+  const workspaceDir = resolveWorkspaceDir();
+  const stateManager = new RuntimeStateManager({ workspaceDir });
+  await stateManager.initialize();
+
+  try {
+    const runs = await stateManager.getRunsByTask(opts.taskId);
+
+    if (runs.length === 0) {
+      console.log(`No runs found for task: ${opts.taskId}`);
+      return;
+    }
+
+    console.log(`\nRuns for ${opts.taskId} (${runs.length}):\n`);
+    console.log('  %-22s %-12s %-20s %-6s %s', 'RUN_ID', 'STATUS', 'STARTED', 'ATT', 'ENDED');
+    console.log('  ' + '-'.repeat(80));
+
+    for (const run of runs) {
+      console.log(
+        '  %-22s %-12s %-20s %-6s %s',
+        run.runId.substring(0, 22),
+        run.executionStatus,
+        new Date(run.startedAt).toLocaleString(),
+        run.attemptNumber,
+        run.endedAt ? new Date(run.endedAt).toLocaleString() : '-',
+      );
+    }
+    console.log('');
+  } finally {
+    await stateManager.close();
+  }
+}
+
+interface RunShowOptions {
+  id: string;
+}
+
+export async function handleRunShow(opts: RunShowOptions): Promise<void> {
+  const workspaceDir = resolveWorkspaceDir();
+  const stateManager = new RuntimeStateManager({ workspaceDir });
+  await stateManager.initialize();
+
+  try {
+    const run = await stateManager.getRun(opts.id);
+
+    if (!run) {
+      console.error(`Run not found: ${opts.id}`);
+      process.exit(1);
+    }
+
+    console.log(`\nRun: ${run.runId}\n`);
+    console.log(`  Task ID:       ${run.taskId}`);
+    console.log(`  Runtime Kind:  ${run.runtimeKind}`);
+    console.log(`  Status:        ${run.executionStatus}`);
+    console.log(`  Attempt:       ${run.attemptNumber}`);
+    console.log(`  Started:       ${new Date(run.startedAt).toLocaleString()}`);
+    if (run.endedAt) {
+      console.log(`  Ended:         ${new Date(run.endedAt).toLocaleString()}`);
+      const duration = new Date(run.endedAt).getTime() - new Date(run.startedAt).getTime();
+      console.log(`  Duration:      ${(duration / 1000).toFixed(1)}s`);
+    }
+    if (run.reason) {
+      console.log(`  Reason:        ${run.reason}`);
+    }
+    if (run.errorCategory) {
+      console.log(`  Error Category:${run.errorCategory}`);
+    }
+    if (run.outputRef) {
+      console.log(`  Output Ref:    ${run.outputRef}`);
+    }
+    console.log('');
+  } finally {
+    await stateManager.close();
+  }
+}

package/src/commands/runtime-activation.ts

@@ -0,0 +1,176 @@
+import * as path from 'path';
+import {
+  RuntimeStateManager,
+  ActivationDispatcher,
+  PromptWriter,
+  DeferArchiveWriter,
+  SqliteActivationStateStore,
+  SqliteApprovalQueueStore,
+} from '@principles/core/runtime-v2';
+import type { ActivationDecision, PIArtifactSnapshot, RolloutActivationDecision } from '@principles/core/runtime-v2';
+import type { PIArtifactRecord } from '@principles/core/runtime-v2';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface ActivationDispatchOptions {
+  workspace?: string;
+  artifactId?: string;
+  channel?: string;
+  dryRun?: boolean;
+  confirm?: boolean;
+  json?: boolean;
+}
+
+function mapRolloutDecision(reviewDecision: string | undefined): RolloutActivationDecision {
+  if (!reviewDecision) return 'require_approval';
+  if (reviewDecision === 'approve_rollout') return 'auto_activate';
+  if (reviewDecision === 'needs_revision') return 'require_approval';
+  if (reviewDecision === 'reject') return 'reject';
+  return 'require_approval';
+}
+
+function extractRolloutDecisionFromArtifact(artifact: PIArtifactRecord): RolloutActivationDecision {
+  try {
+    const parsed = JSON.parse(artifact.contentJson) as Record<string, unknown>;
+    if (parsed && typeof parsed === 'object') {
+      const review = parsed.review as Record<string, unknown> | undefined;
+      if (review && typeof review.decision === 'string') {
+        return mapRolloutDecision(review.decision);
+      }
+      if (typeof parsed.rolloutDecision === 'string') {
+        return mapRolloutDecision(parsed.rolloutDecision);
+      }
+    }
+  } catch {
+    return 'require_approval';
+  }
+  return 'require_approval';
+}
+
+function toSnapshot(record: PIArtifactRecord): PIArtifactSnapshot {
+  return {
+    artifactId: record.artifactId,
+    artifactKind: record.artifactKind,
+    sourceTaskId: record.sourceTaskId,
+    sourcePrincipleId: record.sourcePrincipleId,
+    sourceRuleId: record.sourceRuleId,
+    lineageArtifactIds: record.lineageArtifactIds,
+    validationStatus: record.validationStatus,
+    contentJson: record.contentJson,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+  };
+}
+
+function formatTextOutput(result: ActivationDecision): string {
+  const lines: string[] = [];
+  switch (result.decision) {
+    case 'would_activate':
+      lines.push(`Activation: would_activate`);
+      lines.push(`  activationId: ${result.activationId}`);
+      lines.push(`  action: ${result.action}`);
+      lines.push(`  targetRef: ${result.targetRef}`);
+      break;
+    case 'activated':
+      lines.push(`Activation: activated`);
+      lines.push(`  activationId: ${result.activationId}`);
+      lines.push(`  action: ${result.action}`);
+      lines.push(`  targetRef: ${result.targetRef}`);
+      break;
+    case 'already_activated':
+      lines.push(`Activation: already_activated`);
+      lines.push(`  activationId: ${result.activationId}`);
+      lines.push(`  action: ${result.action}`);
+      lines.push(`  targetRef: ${result.targetRef}`);
+      break;
+    case 'refused':
+      lines.push(`Activation: refused`);
+      lines.push(`  reason: ${result.reason}`);
+      if (result.riskLevel) lines.push(`  riskLevel: ${result.riskLevel}`);
+      if (result.channel) lines.push(`  channel: ${result.channel}`);
+      break;
+    case 'invalid_artifact':
+      lines.push(`Activation: invalid_artifact`);
+      lines.push(`  reason: ${result.reason}`);
+      break;
+  }
+  return lines.join('\n');
+}
+
+function isNegativeDecision(decision: ActivationDecision['decision']): boolean {
+  return decision === 'refused' || decision === 'invalid_artifact';
+}
+
+export async function handleRuntimeActivationDispatch(opts: ActivationDispatchOptions): Promise<void> {
+  if (opts.dryRun && opts.confirm) {
+    console.error('Error: --dry-run and --confirm are mutually exclusive');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!opts.artifactId) {
+    console.error('Error: --artifact-id is required');
+    process.exitCode = 1;
+    return;
+  }
+
+  const confirm = opts.confirm === true;
+  const channel = (opts.channel ?? 'prompt') as 'prompt' | 'defer_archive' | 'skill' | 'code_tool_hook' | 'model_training';
+
+  const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
+  const stateManager = new RuntimeStateManager({ workspaceDir });
+
+  try {
+    await stateManager.initialize();
+    const artifactRecord = await stateManager.piArtifactStore.getArtifactById(opts.artifactId);
+    if (!artifactRecord) {
+      const result: ActivationDecision = { decision: 'invalid_artifact', reason: 'artifact_not_found' };
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(formatTextOutput(result));
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    const artifactSnapshot = toSnapshot(artifactRecord);
+    const rolloutDecision = extractRolloutDecisionFromArtifact(artifactRecord);
+
+    const artifactReadModel = {
+      getArtifactById: async (id: string): Promise<PIArtifactSnapshot | null> => {
+        if (id === opts.artifactId) return artifactSnapshot;
+        const rec = await stateManager.piArtifactStore.getArtifactById(id);
+        return rec ? toSnapshot(rec) : null;
+      },
+    };
+
+    const activationStateStore = new SqliteActivationStateStore(stateManager.connection);
+    const approvalQueueStore = new SqliteApprovalQueueStore(stateManager.connection);
+    const dispatcher = new ActivationDispatcher(
+      artifactReadModel,
+      activationStateStore,
+      { writers: [new PromptWriter(), new DeferArchiveWriter()], approvalQueueStore },
+    );
+
+    const result = await dispatcher.dispatch({
+      artifactId: opts.artifactId,
+      channel,
+      rolloutDecision,
+      actor: { kind: 'system', source: 'rollout_reviewer' },
+      now: new Date().toISOString(),
+      confirm,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatTextOutput(result));
+    }
+
+    if (isNegativeDecision(result.decision)) {
+      process.exitCode = 1;
+    }
+  } finally {
+    await stateManager.close();
+  }
+}