@principles/pd-cli 1.133.0 → 1.134.0

package/src/commands/runtime-canary.ts

@@ -1,4 +1,5 @@
 import * as path from 'path';
+import { createRequire } from 'module';
 import { OperatorHealthReadModel, SchemaConformanceReadModel, PruningReadModel, createInternalizationQueueReadModel, auditCandidateLedgerConsistency, buildGfiWorkspaceSnapshot, classifyGfiWorkspaceHealth } from '@principles/core/runtime-v2';
 import type { OperatorHealthSnapshot, SchemaConformanceResult, OrphanDetectionResult, InternalizationQueueSnapshot, GfiWorkspaceSnapshot, CandidateAuditResult } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
@@ -20,6 +21,17 @@ export interface CanaryOutput {
   internalizationQueueSummary?: InternalizationQueueSummary;
 }
 
+const require = createRequire(import.meta.url);
+
+function readCliVersion(): string {
+  const packageMetadata: unknown = require('../../package.json');
+  if (typeof packageMetadata === 'object' && packageMetadata !== null && Object.hasOwn(packageMetadata, 'version')) {
+    const version: unknown = Reflect.get(packageMetadata, 'version');
+    if (typeof version === 'string') return version;
+  }
+  return 'unknown';
+}
+
 export interface InternalizationQueueSummary {
   readyCount: number;
   retryWaitCount: number;
@@ -244,11 +256,23 @@ export async function runCanaryChecks(workspaceDir: string): Promise<CanaryOutpu
         const model = new OperatorHealthReadModel({ workspaceDir });
         try {
           const snapshot: OperatorHealthSnapshot = await model.getSnapshot();
-          const status = snapshot.overallStatus === 'healthy' ? 'healthy' : snapshot.overallStatus === 'degraded' ? 'degraded' : 'error';
+          // Priority: real errors (e.g. DB missing) must surface as 'error' and not be
+          // masked by the cold-start `totalTaskCount === 0` branch, which is only a
+          // 'degraded' signal. Check overallStatus==='error' first, then unexercised,
+          // then healthy/degraded.
+          const status = snapshot.overallStatus === 'error'
+            ? 'error'
+            : snapshot.totalTaskCount === 0
+            ? 'degraded'
+            : snapshot.overallStatus === 'healthy' ? 'healthy' : 'degraded';
           return {
             name: 'runtime_health',
             status,
-            summary: status === 'healthy'
+            summary: snapshot.overallStatus === 'error'
+              ? `Runtime health: ${snapshot.overallStatus}. Actions: ${snapshot.recommendedActions.join('; ')}`
+              : snapshot.totalTaskCount === 0
+              ? 'Runtime pipeline has not been exercised yet.'
+              : status === 'healthy'
               ? 'Runtime health OK.'
               : `Runtime health: ${snapshot.overallStatus}. Actions: ${snapshot.recommendedActions.join('; ')}`,
             details: snapshot,
@@ -272,7 +296,7 @@ export async function runCanaryChecks(workspaceDir: string): Promise<CanaryOutpu
           summary: status === 'healthy'
             ? `PD CLI accessible at ${cliPath}`
             : 'PD CLI entrypoint not found — verify installation.',
-          details: { cliPath, exists: cliExists, version: '0.1.0' },
+          details: { cliPath, exists: cliExists, version: readCliVersion() },
         };
       } catch (err) {
         return { name: 'pd_shim_info', status: 'error', summary: 'PD shim check failed.', error: String(err) };
@@ -362,8 +386,10 @@ export async function handleRuntimeCanary(opts: CanaryOptions): Promise<void> {
   }
 
   if (output.overallStatus !== 'healthy') {
-    console.error('');
-    console.error(`FAIL: overallStatus=${output.overallStatus}`);
+    if (!opts.json) {
+      console.error('');
+      console.error(`FAIL: overallStatus=${output.overallStatus}`);
+    }
     process.exitCode = 1;
   }
 }

package/src/commands/runtime-health-snapshot.ts

@@ -96,8 +96,10 @@ export async function handleRuntimeHealthSnapshot(opts: HealthSnapshotOptions):
     }
 
     if (snapshot.overallStatus !== 'healthy') {
-      console.error('');
-      console.error(`FAIL: overallStatus=${snapshot.overallStatus}`);
+      if (!opts.json) {
+        console.error('');
+        console.error(`FAIL: overallStatus=${snapshot.overallStatus}`);
+      }
       process.exitCode = 1;
     }
   } finally {

package/src/commands/runtime-init.ts

@@ -0,0 +1,305 @@
+/**
+ * pd runtime init — Initialize all PD SQLite databases for a workspace.
+ *
+ * Creates state.db, trajectory.db, and subagent_workflows.db with full schema
+ * (tables + indexes + views + migrations). Idempotent: safe to run on existing
+ * workspaces (all CREATE statements use IF NOT EXISTS).
+ *
+ * Output contract (cli-1 strict-json, cli-4 dry-run/confirm mutex, cli-6 nextAction):
+ * - Default mode is --dry-run (no writes); use --confirm to actually initialize.
+ * - --json emits a single parseable JSON object on stdout.
+ * - Failures emit { ok: false, reason, nextAction } with exit code 1.
+ *
+ * ERR refs:
+ * - ERR-001/ERR-005: no `as` casts; DB rows typed via type guards
+ * - ERR-002: degraded paths include reason + nextAction
+ * - ERR-009/ERR-010: missing required fields fail loud
+ * - ERR-014: safe JSON.stringify on known output shapes
+ */
+
+import * as path from 'path';
+import { SqliteConnection } from '@principles/core/runtime-v2';
+import { SchemaConformanceReadModel } from '@principles/core/runtime-v2';
+import { initTrajectorySchema, initWorkflowSchema } from 'principles-disciple';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { emitResult, emitFlagConflict, emitError } from '../services/cli-output.js';
+
+// ── Output types ─────────────────────────────────────────────────────────────
+
+export interface DatabaseInitResult {
+  name: string;
+  path: string;
+  tables: string[];
+  status: 'initialized' | 'verified' | 'skipped' | 'failed';
+  warnings: string[];
+}
+
+export interface RuntimeInitOutput {
+  ok: boolean;
+  mode: 'dry-run' | 'confirm';
+  workspace: string;
+  databases: DatabaseInitResult[];
+  warnings: string[];
+  reason?: string;
+  nextAction?: string;
+}
+
+// ── Build output ─────────────────────────────────────────────────────────────
+
+const DB_NAMES = {
+  state: 'state.db',
+  trajectory: 'trajectory.db',
+  workflow: 'subagent_workflows.db',
+} as const;
+
+export function buildRuntimeInitOutput(workspaceDir: string, confirm: boolean): RuntimeInitOutput {
+  const resolvedWorkspace = path.resolve(workspaceDir);
+  const warnings: string[] = [];
+  const databases: DatabaseInitResult[] = [];
+
+  // 1. state.db (via SqliteConnection, which triggers initSchema + migrateSchema)
+  const stateDbPath = path.join(resolvedWorkspace, '.pd', 'state.db');
+  if (!confirm) {
+    // dry-run: report what would be initialized without touching disk
+    databases.push({
+      name: DB_NAMES.state,
+      path: stateDbPath,
+      tables: ['tasks', 'runs', 'artifacts', 'commits', 'principle_candidates',
+        'pi_artifacts', 'approvals', 'activations', 'intent_decisions', 'schema_version'],
+      status: 'skipped',
+      warnings: [],
+    });
+  } else {
+    try {
+      const conn = new SqliteConnection({ workspaceDir: resolvedWorkspace, readonly: false });
+      try {
+        conn.getDb(); // triggers initSchema + migrateSchema
+        const connWarnings = conn.getSchemaInitWarnings();
+        if (connWarnings.length > 0) {
+          warnings.push(...connWarnings.map(w => `${DB_NAMES.state}: ${w}`));
+        }
+        databases.push({
+          name: DB_NAMES.state,
+          path: stateDbPath,
+          tables: ['tasks', 'runs', 'artifacts', 'commits', 'principle_candidates',
+            'pi_artifacts', 'approvals', 'activations', 'intent_decisions', 'schema_version'],
+          status: 'initialized',
+          warnings: connWarnings,
+        });
+      } finally {
+        conn.close();
+      }
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      databases.push({
+        name: DB_NAMES.state,
+        path: stateDbPath,
+        tables: [],
+        status: 'failed',
+        warnings: [reason],
+      });
+      return {
+        ok: false,
+        mode: 'confirm',
+        workspace: resolvedWorkspace,
+        databases,
+        warnings,
+        reason: `state.db initialization failed: ${reason}`,
+        nextAction: 'Check workspace directory permissions and disk space, then retry.',
+      };
+    }
+  }
+
+  // 2. trajectory.db (via initTrajectorySchema)
+  if (!confirm) {
+    databases.push({
+      name: DB_NAMES.trajectory,
+      path: path.join(resolvedWorkspace, '.state', 'trajectory.db'),
+      tables: ['schema_version', 'ingest_checkpoint', 'sessions', 'assistant_turns',
+        'user_turns', 'tool_calls', 'pain_events', 'gate_blocks', 'trust_changes',
+        'principle_events', 'task_outcomes', 'correction_samples', 'sample_reviews',
+        'exports_audit', 'evolution_tasks', 'evolution_events'],
+      status: 'skipped',
+      warnings: [],
+    });
+  } else {
+    try {
+      const result = initTrajectorySchema(resolvedWorkspace);
+      if (result.warnings.length > 0) {
+        warnings.push(...result.warnings.map((w: string) => `${DB_NAMES.trajectory}: ${w}`));
+      }
+      databases.push({
+        name: DB_NAMES.trajectory,
+        path: path.join(resolvedWorkspace, '.state', 'trajectory.db'),
+        tables: result.tables,
+        status: 'initialized',
+        warnings: result.warnings,
+      });
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      databases.push({
+        name: DB_NAMES.trajectory,
+        path: path.join(resolvedWorkspace, '.state', 'trajectory.db'),
+        tables: [],
+        status: 'failed',
+        warnings: [reason],
+      });
+      return {
+        ok: false,
+        mode: 'confirm',
+        workspace: resolvedWorkspace,
+        databases,
+        warnings,
+        reason: `trajectory.db initialization failed: ${reason}`,
+        nextAction: 'Check workspace directory permissions and disk space, then retry.',
+      };
+    }
+  }
+
+  // 3. subagent_workflows.db (via initWorkflowSchema)
+  if (!confirm) {
+    databases.push({
+      name: DB_NAMES.workflow,
+      path: path.join(resolvedWorkspace, '.state', 'subagent_workflows.db'),
+      tables: ['schema_version', 'subagent_workflows', 'subagent_workflow_events'],
+      status: 'skipped',
+      warnings: [],
+    });
+  } else {
+    try {
+      const result = initWorkflowSchema(resolvedWorkspace);
+      if (result.warnings.length > 0) {
+        warnings.push(...result.warnings.map((w: string) => `${DB_NAMES.workflow}: ${w}`));
+      }
+      databases.push({
+        name: DB_NAMES.workflow,
+        path: path.join(resolvedWorkspace, '.state', 'subagent_workflows.db'),
+        tables: result.tables,
+        status: 'initialized',
+        warnings: result.warnings,
+      });
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      databases.push({
+        name: DB_NAMES.workflow,
+        path: path.join(resolvedWorkspace, '.state', 'subagent_workflows.db'),
+        tables: [],
+        status: 'failed',
+        warnings: [reason],
+      });
+      return {
+        ok: false,
+        mode: 'confirm',
+        workspace: resolvedWorkspace,
+        databases,
+        warnings,
+        reason: `subagent_workflows.db initialization failed: ${reason}`,
+        nextAction: 'Check workspace directory permissions and disk space, then retry.',
+      };
+    }
+  }
+
+  // Verify state.db schema conformance after initialization (confirm mode only)
+  if (confirm) {
+    try {
+      const conformance = new SchemaConformanceReadModel({ workspaceDir: resolvedWorkspace });
+      const result = conformance.check();
+      if (result.overallStatus === 'error') {
+        warnings.push(`state.db schema conformance check returned 'error' — some tables or indexes may be missing`);
+      }
+    } catch (err) {
+      // Non-fatal: schema conformance check is a post-verification step
+      warnings.push(`schema conformance verification skipped: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return {
+    ok: true,
+    mode: confirm ? 'confirm' : 'dry-run',
+    workspace: resolvedWorkspace,
+    databases,
+    warnings,
+  };
+}
+
+// ── Text formatting ──────────────────────────────────────────────────────────
+
+function formatTextOutput(output: RuntimeInitOutput): string {
+  const lines: string[] = [];
+
+  lines.push('PD Runtime Init');
+  lines.push(`mode: ${output.mode}`);
+  lines.push(`workspace: ${output.workspace}`);
+  lines.push('');
+
+  for (const db of output.databases) {
+    const icon = db.status === 'initialized' ? '[+]' :
+                 db.status === 'verified' ? '[v]' :
+                 db.status === 'skipped' ? '[ ]' : '[x]';
+    lines.push(`${icon} ${db.name} (${db.status})`);
+    lines.push(`    path: ${db.path}`);
+    if (db.tables.length > 0) {
+      lines.push(`    tables: ${db.tables.length} (${db.tables.slice(0, 5).join(', ')}${db.tables.length > 5 ? ', ...' : ''})`);
+    }
+    for (const w of db.warnings) {
+      lines.push(`    warning: ${w}`);
+    }
+  }
+
+  if (output.warnings.length > 0) {
+    lines.push('');
+    lines.push('Warnings:');
+    for (const w of output.warnings) {
+      lines.push(`  [!] ${w}`);
+    }
+  }
+
+  if (!output.ok && output.reason) {
+    lines.push('');
+    lines.push(`Error: ${output.reason}`);
+    if (output.nextAction) {
+      lines.push(`→ ${output.nextAction}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ── CLI handler ──────────────────────────────────────────────────────────────
+
+export interface RuntimeInitOptions {
+  workspace?: string;
+  dryRun?: boolean;
+  confirm?: boolean;
+  json?: boolean;
+}
+
+export async function handleRuntimeInit(opts: RuntimeInitOptions): Promise<void> {
+  // cli-4: --dry-run and --confirm are mutually exclusive
+  if (opts.dryRun && opts.confirm) {
+    process.exitCode = emitFlagConflict({ json: opts.json ?? false });
+    return;
+  }
+
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  // Default is dry-run; --confirm opts in to actual initialization
+  const confirm = opts.confirm === true;
+
+  try {
+    const output = buildRuntimeInitOutput(workspaceDir, confirm);
+    emitResult(output, { json: opts.json ?? false, formatText: formatTextOutput });
+
+    if (!output.ok) {
+      process.exitCode = 1; // cli-2: set exit code, no process.exit()
+    }
+  } catch (err) {
+    process.exitCode = emitError(err, {
+      json: opts.json ?? false,
+      nextAction: 'Check workspace directory and permissions, then retry.',
+    });
+  }
+}
+