@principles/pd-cli 1.73.0

package/src/commands/health.ts

@@ -0,0 +1,189 @@
+/**
+ * pd health command implementation — Runtime V2 edition.
+ *
+ * Usage: pd health [--workspace <path>] [--json]
+ *
+ * Reads workspace/.pd/state.db and workspace/.state/principle_training_state.json
+ * to provide Runtime V2 health diagnostics.
+ * Uses read models from @principles/core/runtime-v2 (no direct ledger access).
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import Database from 'better-sqlite3';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { PruningReadModel, PainChainReadModel, auditCandidateLedgerConsistency, getLedgerFilePathPublic } from '@principles/core/runtime-v2';
+import type { PainChainTrace } from '@principles/core/runtime-v2';
+
+interface LastSuccessfulChain {
+  painId?: string;
+  taskId: string;
+  runId: string;
+  artifactId: string;
+  candidateIds: string[];
+  ledgerEntryIds: string[];
+  latencyMs?: { totalMs?: number };
+  failureCategory: string | null;
+  checkedAt: string;
+}
+
+interface WorkspaceHealth {
+  generatedAt: string;
+  workspace: string;
+  partialHealth?: boolean;
+  pdStateDb: { path: string; exists: boolean };
+  ledger: { path: string; exists: boolean; totalPrinciples: number; byStatus: Record<string, number> };
+  candidates: { total: number; consumed: number; pending: number };
+  tasks: { total: number; byStatus: Record<string, number> };
+  candidateLedgerConsistency: { status: 'ok' | 'degraded'; missing: number };
+  lastSuccessfulChain?: LastSuccessfulChain;
+}
+
+interface HealthOptions {
+  workspace?: string;
+  json?: boolean;
+}
+
+function painChainTraceToLastSuccessfulChain(trace: PainChainTrace): LastSuccessfulChain {
+  const totalMs = (trace.latencyMs.painToTask ?? 0)
+    + (trace.latencyMs.taskToRun ?? 0)
+    + (trace.latencyMs.runToArtifact ?? 0);
+
+  return {
+    painId: trace.painId,
+    taskId: trace.taskId,
+    runId: trace.runId ?? '',
+    artifactId: trace.artifactId ?? '',
+    candidateIds: trace.candidateIds,
+    ledgerEntryIds: trace.ledgerEntryIds,
+    latencyMs: { totalMs: totalMs > 0 ? totalMs : undefined },
+    failureCategory: trace.failureCategory,
+    checkedAt: trace.checkedAt,
+  };
+}
+
+export async function handleHealth(opts: HealthOptions = {}): Promise<void> {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const generatedAt = new Date().toISOString();
+  const pdDbPath = path.join(workspaceDir, '.pd', 'state.db');
+  const ledgerStateDir = path.join(workspaceDir, '.state');
+  const ledgerPath = getLedgerFilePathPublic(ledgerStateDir);
+
+  const pruningModel = new PruningReadModel({ workspaceDir });
+  const healthSummary = pruningModel.getHealthSummary();
+  const ledgerByStatus = healthSummary.byStatus;
+
+  const { missingLedgerCount } = await auditCandidateLedgerConsistency(workspaceDir);
+
+  let candidatesTotal = 0, candidatesConsumed = 0, candidatesPending = 0;
+  let tasksTotal = 0;
+  const tasksByStatus: Record<string, number> = {};
+  let pdDbExists = false;
+  let lastSuccessfulChain: LastSuccessfulChain | undefined = undefined;
+  let partialHealth = false;
+
+  function buildHealth(): WorkspaceHealth {
+    return {
+      generatedAt,
+      workspace: workspaceDir,
+      partialHealth,
+      pdStateDb: { path: pdDbPath, exists: pdDbExists },
+      ledger: {
+        path: ledgerPath,
+        exists: fs.existsSync(ledgerPath),
+        totalPrinciples: healthSummary.totalPrinciples,
+        byStatus: ledgerByStatus,
+      },
+      candidates: { total: candidatesTotal, consumed: candidatesConsumed, pending: candidatesPending },
+      tasks: { total: tasksTotal, byStatus: tasksByStatus },
+      candidateLedgerConsistency: {
+        status: missingLedgerCount === 0 ? 'ok' : 'degraded',
+        missing: missingLedgerCount,
+      },
+      lastSuccessfulChain,
+    };
+  }
+
+  function writeHealth(): void {
+    const health = buildHealth();
+
+    if (opts.json) {
+      console.log(JSON.stringify(health, null, 2));
+      if (health.candidateLedgerConsistency.status === 'degraded') process.exit(1);
+      return;
+    }
+
+    console.log(`generatedAt: ${health.generatedAt}`);
+    console.log(`workspace: ${health.workspace}`);
+    console.log(`pdStateDb.exists: ${health.pdStateDb.exists}`);
+    console.log(`pdStateDb.path: ${health.pdStateDb.path}`);
+    console.log(`ledger.exists: ${health.ledger.exists}`);
+    console.log(`ledger.path: ${health.ledger.path}`);
+    console.log(`ledger.totalPrinciples: ${health.ledger.totalPrinciples}`);
+    console.log(`ledger.byStatus: ${JSON.stringify(health.ledger.byStatus)}`);
+    console.log(`candidates.total: ${health.candidates.total}`);
+    console.log(`candidates.consumed: ${health.candidates.consumed}`);
+    console.log(`candidates.pending: ${health.candidates.pending}`);
+    console.log(`tasks.total: ${health.tasks.total}`);
+    console.log(`tasks.byStatus: ${JSON.stringify(health.tasks.byStatus)}`);
+    console.log(`candidateLedgerConsistency.status: ${health.candidateLedgerConsistency.status}`);
+    console.log(`candidateLedgerConsistency.missing: ${health.candidateLedgerConsistency.missing}`);
+    if (health.lastSuccessfulChain) {
+      console.log('lastSuccessfulChain:');
+      console.log(`  taskId:       ${health.lastSuccessfulChain.taskId}`);
+      console.log(`  runId:        ${health.lastSuccessfulChain.runId}`);
+      console.log(`  artifactId:   ${health.lastSuccessfulChain.artifactId}`);
+      console.log(`  candidateIds: ${health.lastSuccessfulChain.candidateIds.join(', ')}`);
+      console.log(`  ledgerEntries: ${health.lastSuccessfulChain.ledgerEntryIds.join(', ')}`);
+    }
+    console.log('');
+
+    if (health.candidateLedgerConsistency.status === 'degraded') {
+      console.warn('⚠️  Candidate/ledger consistency is DEGRADED. Run: pd candidate audit --workspace "' + workspaceDir + '" --json');
+      console.warn('   To repair missing entries: pd candidate repair --candidate-id <id> --workspace "' + workspaceDir + '" --json');
+      process.exit(1);
+    }
+  }
+
+  if (fs.existsSync(pdDbPath)) {
+    pdDbExists = true;
+    const db = Database(pdDbPath, { readonly: true });
+    try {
+      const cRow = db.prepare('SELECT COUNT(*) as total, status FROM principle_candidates GROUP BY status').all() as { total: number; status: string }[];
+      for (const r of cRow) {
+        candidatesTotal += r.total;
+        if (r.status === 'consumed') candidatesConsumed = r.total;
+        if (r.status === 'pending') candidatesPending = r.total;
+      }
+
+      const tRows = db.prepare('SELECT COUNT(*) as total, status FROM tasks GROUP BY status').all() as { total: number; status: string }[];
+      for (const r of tRows) {
+        tasksTotal += r.total;
+        tasksByStatus[r.status] = r.total;
+      }
+
+      const painChainModel = new PainChainReadModel({ workspaceDir });
+      try {
+        const chain = await painChainModel.getLastSuccessfulChain();
+        if (chain) {
+          lastSuccessfulChain = painChainTraceToLastSuccessfulChain(chain);
+        }
+      } catch {
+        partialHealth = true;
+      } finally {
+        await painChainModel.close();
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`Warning: could not read full state.db metrics — partial health data: ${msg}`);
+      partialHealth = true;
+    } finally {
+      db.close();
+    }
+  }
+
+  writeHealth();
+}

package/src/commands/history.ts

@@ -0,0 +1,63 @@
+/**
+ * pd history query — Query run history for a task with pagination.
+ *
+ * Usage:
+ *   pd history query <taskId> [--limit N] [--cursor <cursor>]
+ *   pd history query <taskId> --from <date> --to <date>
+ */
+import { SqliteConnection, SqliteHistoryQuery } from '@principles/core';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface HistoryQueryOptions {
+  limit?: number;
+  cursor?: string;
+  from?: string;
+  to?: string;
+  json?: boolean;
+  workspace?: string;
+}
+
+export async function handleHistoryQuery(taskId: string, opts: HistoryQueryOptions): Promise<void> {
+  const workspaceDir = resolveWorkspaceDir(opts.workspace);
+  const connection = new SqliteConnection(workspaceDir);
+
+  try {
+    const historyQuery = new SqliteHistoryQuery(connection);
+
+    const queryOpts = opts.limit || opts.from || opts.to
+      ? {
+          limit: opts.limit,
+          timeWindowStart: opts.from,
+          timeWindowEnd: opts.to,
+        }
+      : undefined;
+    const result = await historyQuery.query(taskId, opts.cursor, queryOpts);
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    if (result.entries.length === 0) {
+      console.log('No history entries found.');
+      return;
+    }
+
+    console.log(`\nHistory for ${taskId} (${result.entries.length} entries${result.truncated ? ', truncated' : ''}):\n`);
+    for (const entry of result.entries) {
+      const text = entry.text ? (entry.text.length > 60 ? entry.text.substring(0, 57) + '...' : entry.text) : '<empty>';
+      console.log('  [%s] %-8s %s', entry.ts.substring(11, 19), entry.role, text);
+    }
+
+    if (result.nextCursor) {
+      console.log(`\n  nextCursor: ${result.nextCursor}`);
+    }
+    console.log('');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  } finally {
+    connection.close();
+  }
+}

package/src/commands/legacy-cleanup.ts

@@ -0,0 +1,206 @@
+/**
+ * pd legacy cleanup
+ *
+ * Cleans legacy artifacts from workspaces:
+ * - .state/pd_tasks.json  (removes empathy-optimizer entries)
+ * - .state/sessions/*.json (archives sessions with cron:pd-empathy-optimizer)
+ * - .state/diagnostician_tasks.json (archives)
+ * - .state/.evolution_complete_* (archives)
+ * - .state/.diagnostician_report_* (archives)
+ * - ~/.openclaw/cron/jobs.json (removes pd-empathy-optimizer cron jobs)
+ *
+ * Usage:
+ *   pd legacy cleanup --workspace <path> --dry-run
+ *   pd legacy cleanup --workspace <path> --apply
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+interface CleanupTarget {
+  path: string;
+  action: 'remove' | 'archive';
+  reason: string;
+  archivePath?: string;
+}
+
+interface CronJobRecord {
+  id?: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+interface _CronStore {
+  jobs: CronJobRecord[];
+}
+
+interface TaskRecord {
+  id?: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+function glob(pattern: string): string[] {
+  const results: string[] = [];
+  const baseDir = path.dirname(pattern);
+  const filePattern = path.basename(pattern).replace(/\*/g, '');
+
+  if (!fs.existsSync(baseDir)) return [];
+
+  for (const file of fs.readdirSync(baseDir)) {
+    if (file.startsWith(filePattern) || filePattern === '') {
+      const fullPath = path.join(baseDir, file);
+      const stat = fs.statSync(fullPath);
+      if (stat.isFile()) results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+function findLegacyTargets(workspacePath: string): CleanupTarget[] {
+  const targets: CleanupTarget[] = [];
+  const stateDir = path.join(workspacePath, '.state');
+  const archiveTimestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const archiveDir = path.join(stateDir, 'legacy-archive', archiveTimestamp);
+
+  // 1. pd_tasks.json — remove empathy-optimizer entries
+  const pdTasksPath = path.join(stateDir, 'pd_tasks.json');
+  if (fs.existsSync(pdTasksPath)) {
+    try {
+      const content = fs.readFileSync(pdTasksPath, 'utf-8');
+      const tasks = JSON.parse(content);
+      const filtered = tasks.filter((t: TaskRecord) =>
+        !t.id?.includes('empathy-optimizer') && !t.name?.includes('Empathy Optimizer')
+      );
+      if (filtered.length !== tasks.length) {
+        targets.push({
+          path: pdTasksPath,
+          action: 'archive',
+          reason: 'Removed empathy-optimizer entries from pd_tasks.json',
+          archivePath: path.join(archiveDir, 'pd_tasks.json.backup'),
+        });
+      }
+    } catch { /* skip invalid JSON */ }
+  }
+
+  // 2. sessions/*.json — archive empathy cron sessions
+  const sessionsDir = path.join(stateDir, 'sessions');
+  if (fs.existsSync(sessionsDir)) {
+    for (const file of fs.readdirSync(sessionsDir)) {
+      if (!file.endsWith('.json')) continue;
+      const filePath = path.join(sessionsDir, file);
+      try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const session = JSON.parse(content);
+        if (session.sessionKey?.includes('cron:pd-empathy-optimizer') ||
+            session.sessionKey?.includes('cron:empathy-optimizer')) {
+          targets.push({
+            path: filePath,
+            action: 'archive',
+            reason: `Legacy empathy cron session: ${session.sessionKey}`,
+            archivePath: path.join(archiveDir, 'sessions', file),
+          });
+        }
+      } catch { /* skip */ }
+    }
+  }
+
+  // 3. diagnostician_tasks.json
+  const diagPath = path.join(stateDir, 'diagnostician_tasks.json');
+  if (fs.existsSync(diagPath)) {
+    targets.push({
+      path: diagPath,
+      action: 'archive',
+      reason: 'Legacy diagnostician task store',
+      archivePath: path.join(archiveDir, 'diagnostician_tasks.json'),
+    });
+  }
+
+  // 4. .evolution_complete_* markers
+  for (const marker of glob(path.join(stateDir, '.evolution_complete_*'))) {
+    targets.push({
+      path: marker,
+      action: 'archive',
+      reason: 'Legacy evolution marker',
+      archivePath: path.join(archiveDir, path.basename(marker)),
+    });
+  }
+
+  // 5. .diagnostician_report_* markers
+  for (const marker of glob(path.join(stateDir, '.diagnostician_report_*'))) {
+    targets.push({
+      path: marker,
+      action: 'archive',
+      reason: 'Legacy diagnostician report marker',
+      archivePath: path.join(archiveDir, path.basename(marker)),
+    });
+  }
+
+  // 6. OpenClaw cron jobs.json
+  const cronPath = path.join(os.homedir(), '.openclaw', 'cron', 'jobs.json');
+  if (fs.existsSync(cronPath)) {
+    try {
+      const content = fs.readFileSync(cronPath, 'utf-8');
+      const store = JSON.parse(content) as _CronStore;
+      const filtered = store.jobs.filter((j: CronJobRecord) =>
+        !j.id?.includes('pd-empathy-optimizer') && !j.name?.includes('Empathy Optimizer')
+      );
+      if (filtered.length !== store.jobs.length) {
+        targets.push({
+          path: cronPath,
+          action: 'archive',
+          reason: 'Removed pd-empathy-optimizer cron jobs',
+          archivePath: path.join(os.homedir(), '.openclaw', 'cron', `jobs.json.backup-${archiveTimestamp}`),
+        });
+      }
+    } catch { /* skip */ }
+  }
+
+  return targets;
+}
+
+export async function handleLegacyCleanup(
+  workspacePath: string,
+  dryRun: boolean
+): Promise<{ targets: CleanupTarget[]; applied: number }> {
+  const targets = findLegacyTargets(workspacePath);
+  let applied = 0;
+
+  if (dryRun) {
+    console.log(`\n=== DRY RUN: Would process ${targets.length} target(s) ===`);
+    for (const t of targets) {
+      console.log(`  ${t.action}: ${t.path}`);
+      console.log(`         Reason: ${t.reason}`);
+      if (t.archivePath) {
+        console.log(`         Archive: ${t.archivePath}`);
+      }
+    }
+    if (targets.length === 0) {
+      console.log('  No legacy artifacts found.');
+    }
+  } else {
+    console.log(`\n=== Applying ${targets.length} cleanup(s) ===`);
+    for (const t of targets) {
+      try {
+        if (t.action === 'archive' && t.archivePath) {
+          const archiveDir = path.dirname(t.archivePath);
+          if (!fs.existsSync(archiveDir)) {
+            fs.mkdirSync(archiveDir, { recursive: true });
+          }
+          fs.copyFileSync(t.path, t.archivePath);
+          fs.unlinkSync(t.path);
+          console.log(`  Archived: ${t.path} -> ${t.archivePath}`);
+        } else {
+          fs.unlinkSync(t.path);
+          console.log(`  Removed: ${t.path}`);
+        }
+        applied++;
+      } catch (err) {
+        console.error(`  ERROR processing ${t.path}: ${String(err)}`);
+      }
+    }
+  }
+
+  return { targets, applied };
+}

package/src/commands/legacy-import.ts

@@ -0,0 +1,104 @@
+/**
+ * pd legacy import openclaw — Import OpenClaw legacy data into PD runtime-v2 store.
+ *
+ * Usage:
+ *   pd legacy import openclaw --workspace <path>
+ *
+ * This command is the formal operator path for migrating OpenClaw workspace data
+ * into PD runtime-v2 SQLite. It must be run before trajectory/history/context commands
+ * can return results on a workspace that only has OpenClaw legacy data.
+ *
+ * Two import stages:
+ *   1. Task/Run metadata from .state/diagnostician_tasks.json
+ *   2. Session history from .state/trajectory.db (assistant_turns, user_turns, tool_calls)
+ */
+import { SqliteConnection } from '@principles/core';
+import { syncOpenClawWorkspace } from '../legacy/legacy-import.js';
+import { importSessionHistory } from '../legacy/session-history-import.js';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface LegacyImportOptions {
+  workspace?: string;
+  json?: boolean;
+}
+
+export async function handleLegacyImportOpenClaw(opts: LegacyImportOptions): Promise<void> {
+  const workspaceDir = resolveWorkspaceDir(opts.workspace);
+  const connection = new SqliteConnection(workspaceDir);
+
+  try {
+    const openclawWorkspace = workspaceDir; // same workspace for now
+
+    // Stage 1: Task/Run metadata import
+    if (opts.json) {
+      console.log(JSON.stringify({ stage: 1, source: '.state/diagnostician_tasks.json' }));
+    } else {
+      console.log('Stage 1: Importing diagnostician tasks and runs...');
+    }
+    const syncResult = await syncOpenClawWorkspace(workspaceDir, connection);
+
+    if (opts.json) {
+      console.log(
+        JSON.stringify({
+          stage: 1,
+          tasksImported: syncResult.tasksSynced,
+          runsImported: syncResult.runsSynced,
+        }),
+      );
+    } else {
+      console.log(`  → ${syncResult.tasksSynced} tasks, ${syncResult.runsSynced} runs synced`);
+    }
+
+    // Stage 2: Session history import (if better-sqlite3 is available)
+    try {
+      if (opts.json) {
+        console.log(JSON.stringify({ stage: 2, source: '.state/trajectory.db' }));
+      } else {
+        console.log('Stage 2: Importing session history from trajectory.db...');
+      }
+
+       
+      const historyResult = await importSessionHistory(
+        openclawWorkspace,
+        workspaceDir,
+        () => connection.getDb(),
+      );
+
+      if (opts.json) {
+        console.log(
+          JSON.stringify({
+            stage: 2,
+            sessionsProcessed: historyResult.sessionsProcessed,
+            entriesImported: historyResult.entriesImported,
+          }),
+        );
+      } else {
+        console.log(
+          `  → ${historyResult.sessionsProcessed} sessions, ${historyResult.entriesImported} entries imported`,
+        );
+      }
+    } catch (historyError) {
+      const msg = historyError instanceof Error ? historyError.message : String(historyError);
+      if (opts.json) {
+        console.log(
+          JSON.stringify({
+            stage: 2,
+            skipped: true,
+            reason: `better-sqlite3 not available: ${msg}`,
+          }),
+        );
+      } else {
+        console.log(`  → Stage 2 skipped (better-sqlite3 not available: ${msg})`);
+      }
+    }
+
+    if (!opts.json) {
+      console.log('\nImport complete. You can now run:');
+      console.log('  pd trajectory locate --task <id> --workspace <path>');
+      console.log('  pd history query <id> --workspace <path>');
+      console.log('  pd context build <id> --workspace <path>');
+    }
+  } finally {
+    connection.close();
+  }
+}