@principles/pd-cli 1.73.0

package/src/commands/runtime-features.ts

@@ -0,0 +1,103 @@
+import * as path from 'path';
+import { loadEffectiveFeatureFlags } from '../services/feature-flag-loader.js';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+export interface FeatureFlagsStatusOutput {
+  status: 'ok' | 'degraded';
+  source: string;
+  configPath: string;
+  flags: {
+    id: string;
+    category: string;
+    enabled: boolean;
+    since: string;
+    description?: string;
+  }[];
+  warnings: string[];
+  totalFlags: number;
+  enabledCount: number;
+  disabledCount: number;
+  reason?: string;
+  nextAction?: string;
+}
+
+interface FeaturesOptions {
+  workspace?: string;
+  json?: boolean;
+}
+
+export function buildFeatureFlagsStatus(workspaceDir: string): FeatureFlagsStatusOutput {
+  const effective = loadEffectiveFeatureFlags(workspaceDir);
+  const flags = Object.values(effective.flags);
+  const enabledCount = flags.filter(f => f.enabled).length;
+  const hasWarnings = effective.warnings.length > 0;
+
+  return {
+    status: hasWarnings ? 'degraded' : 'ok',
+    source: effective.source,
+    configPath: effective.configPath,
+    flags: flags.map(f => ({
+      id: f.id,
+      category: f.category,
+      enabled: f.enabled,
+      since: f.since,
+      ...(f.description ? { description: f.description } : {}),
+    })),
+    warnings: effective.warnings,
+    totalFlags: flags.length,
+    enabledCount,
+    disabledCount: flags.length - enabledCount,
+    ...(hasWarnings ? {
+      reason: `Config warnings: ${effective.warnings.join('; ')}`,
+      nextAction: 'Review feature-flags.yaml for malformed overrides or unknown flags',
+    } : {}),
+  };
+}
+
+function formatTextOutput(output: FeatureFlagsStatusOutput): string {
+  const lines: string[] = [];
+
+  lines.push('PD Feature Flags Status');
+  lines.push(`source: ${output.source}`);
+  lines.push(`config: ${output.configPath}`);
+  lines.push('');
+
+  const categoryOrder = ['core', 'quiet', 'gone', 'legacy_retire'] as const;
+  for (const category of categoryOrder) {
+    const categoryFlags = output.flags.filter(f => f.category === category);
+    if (categoryFlags.length === 0) continue;
+
+    lines.push(`  ${category.toUpperCase()} (${categoryFlags.length})`);
+    for (const flag of categoryFlags) {
+      const icon = flag.enabled ? '+' : '-';
+      lines.push(`    [${icon}] ${flag.id} (since ${flag.since})${flag.description ? ` — ${flag.description}` : ''}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(`Total: ${output.totalFlags} flags, ${output.enabledCount} enabled, ${output.disabledCount} disabled`);
+
+  if (output.warnings.length > 0) {
+    lines.push('');
+    lines.push('Warnings:');
+    for (const warning of output.warnings) {
+      lines.push(`  [!] ${warning}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export async function handleRuntimeFeaturesStatus(opts: FeaturesOptions): Promise<void> {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const output = buildFeatureFlagsStatus(workspaceDir);
+
+  if (opts.json) {
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    console.log(formatTextOutput(output));
+  }
+}

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

@@ -0,0 +1,135 @@
+/**
+ * pd runtime gfi snapshot command — GFI workspace snapshot for Runtime V2.
+ *
+ * Usage:
+ *   pd runtime gfi snapshot --workspace <path> --json
+ *   pd runtime health gfi --workspace <path> --json  (alias)
+ *
+ * Shows active vs stale session breakdown for GFI visibility.
+ * Stale sessions (>2h inactive) do NOT influence the active snapshot.
+ *
+ * PRI-78/PRI-82: GFI Observability
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { buildGfiWorkspaceSnapshot } from '@principles/core/runtime-v2';
+import type { GfiWorkspaceSnapshot } from '@principles/core/runtime-v2';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface GfiSnapshotOptions {
+  workspace?: string;
+  json?: boolean;
+}
+
+function formatTextOutput(snapshot: GfiWorkspaceSnapshot): string {
+  const lines: string[] = [];
+
+  lines.push('GFI Workspace Snapshot');
+  lines.push(`generatedAt: ${snapshot.generatedAt}`);
+  lines.push('');
+
+  if (snapshot.active) {
+    const a = snapshot.active;
+    lines.push('ACTIVE SESSION');
+    lines.push(`  currentGfi: ${a.currentGfi}  stage: ${a.stage}`);
+    lines.push(`  dominantSource: ${a.dominantSource ?? '(none)'}`);
+    lines.push(`  consecutiveErrors: ${a.consecutiveErrors}`);
+    lines.push(`  dailyGfiPeak: ${a.dailyGfiPeak ?? '(none)'}`);
+    lines.push(`  attitudeMode: ${a.consumers.attitudeMode}`);
+    lines.push(`  painDiagnosticReason: ${a.consumers.painDiagnosticReason}`);
+  } else {
+    lines.push('ACTIVE SESSION: (none)');
+  }
+
+  lines.push('');
+
+  if (snapshot.staleSessionCount > 0 && snapshot.staleGfiRange) {
+    lines.push(`STALE SESSIONS: ${snapshot.staleSessionCount} session(s)` +
+      ` (GFI range: ${snapshot.staleGfiRange.min}-${snapshot.staleGfiRange.max})`);
+  } else {
+    lines.push('STALE SESSIONS: 0');
+  }
+
+  lines.push('');
+  lines.push(`TOTAL: ${snapshot.totalSessionCount} session(s) (${snapshot.activeSessionCount} active)`);
+
+  return lines.join('\n');
+}
+
+function readPersistedSessions(workspaceDir: string): {
+  sessionId: string;
+  currentGfi: number;
+  gfiBySource?: Record<string, number>;
+  lastErrorSource?: string;
+  consecutiveErrors: number;
+  lastGfiDecayAt?: number;
+  dailyGfiPeak?: number;
+  lastActivityAt: number;
+}[] {
+  const sessionDir = path.join(workspaceDir, '.state', 'sessions');
+
+  if (!fs.existsSync(sessionDir)) {
+    return [];
+  }
+
+  const sessions: {
+    sessionId: string;
+    currentGfi: number;
+    gfiBySource?: Record<string, number>;
+    lastErrorSource?: string;
+    consecutiveErrors: number;
+    lastGfiDecayAt?: number;
+    dailyGfiPeak?: number;
+    lastActivityAt: number;
+  }[] = [];
+  let skippedCount = 0;
+
+  for (const file of fs.readdirSync(sessionDir)) {
+    if (!file.endsWith('.json')) continue;
+    try {
+      const raw = fs.readFileSync(path.join(sessionDir, file), 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed?.sessionId) {
+        sessions.push({
+          sessionId: parsed.sessionId ?? file.replace('.json', ''),
+          currentGfi: parsed.currentGfi ?? 0,
+          gfiBySource: parsed.gfiBySource,
+          lastErrorSource: parsed.lastErrorSource,
+          consecutiveErrors: parsed.consecutiveErrors ?? 0,
+          lastGfiDecayAt: parsed.lastGfiDecayAt,
+          dailyGfiPeak: parsed.dailyGfiPeak,
+          lastActivityAt: parsed.lastActivityAt ?? parsed.lastControlActivityAt ?? 0,
+        });
+      } else {
+        skippedCount++;
+      }
+    } catch {
+      skippedCount++;
+    }
+  }
+
+  if (skippedCount > 0) {
+    console.warn(`[runtime-gfi-snapshot] Skipped ${skippedCount} malformed session file(s)`);
+  }
+
+  return sessions;
+}
+
+export async function handleRuntimeGfiSnapshot(opts: GfiSnapshotOptions): Promise<void> {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const sessions = readPersistedSessions(workspaceDir);
+
+  const snapshot = buildGfiWorkspaceSnapshot({
+    sessions,
+    nowMs: Date.now(),
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(snapshot, null, 2));
+  } else {
+    console.log(formatTextOutput(snapshot));
+  }
+}

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

@@ -0,0 +1,106 @@
+/**
+ * pd runtime health snapshot command — Operator health snapshot for Runtime V2.
+ *
+ * Usage:
+ *   pd runtime health snapshot --workspace <path> --json
+ *
+ * Aggregates chain reliability, candidate/ledger consistency, and pruning
+ * lifecycle signals into a single operator-facing read-only snapshot.
+ *
+ * PRI-28: Operator health snapshot.
+ */
+import * as path from 'path';
+import { OperatorHealthReadModel } from '@principles/core/runtime-v2';
+import type { OperatorHealthSnapshot } from '@principles/core/runtime-v2';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface HealthSnapshotOptions {
+  workspace?: string;
+  json?: boolean;
+}
+
+function formatTextOutput(snapshot: OperatorHealthSnapshot): string {
+  const lines: string[] = [];
+  const statusIcon = snapshot.overallStatus === 'healthy' ? '✓' : '✗';
+
+  lines.push(`Operator Health Snapshot`);
+  lines.push(`generatedAt: ${snapshot.generatedAt}`);
+  lines.push(`workspace:   ${snapshot.workspace}`);
+  lines.push('');
+  lines.push(`OVERALL: ${statusIcon} ${snapshot.overallStatus.toUpperCase()}`);
+  lines.push('');
+
+  // Pain chain
+  lines.push('painChain:');
+  if (snapshot.painChain.lastSuccessfulChain) {
+    const c = snapshot.painChain.lastSuccessfulChain;
+    lines.push(`  lastChain: ${c.painId} → ${c.taskId} → ${c.runId ?? '-'} → ${c.artifactId ?? '-'}`);
+    lines.push(`  candidates: ${c.candidateIds.length}, ledgerEntries: ${c.ledgerEntryIds.length}`);
+  } else {
+    lines.push('  lastChain: (none)');
+  }
+  lines.push('');
+
+  // Candidate/ledger
+  lines.push('candidateLedger:');
+  lines.push(`  status: ${snapshot.candidateLedger.auditStatus}`);
+  if (snapshot.candidateLedger.missingLedgerCount > 0) {
+    lines.push(`  missingLedger: ${snapshot.candidateLedger.missingLedgerCount}`);
+  }
+  lines.push('');
+
+  // Pruning
+  lines.push('pruning:');
+  lines.push(`  watchCount: ${snapshot.pruning.watchCount}, reviewCount: ${snapshot.pruning.reviewCount}`);
+  if (snapshot.pruning.orphanDerivedCandidateCount > 0) {
+    lines.push(`  orphanDerivedCandidates: ${snapshot.pruning.orphanDerivedCandidateCount}`);
+  }
+  lines.push('');
+
+  // GFI
+  if (snapshot.gfi.active) {
+    const g = snapshot.gfi.active;
+    lines.push(`gfi: stage=${g.stage} currentGfi=${g.currentGfi} dominantSource=${g.dominantSource ?? '-'} sessions=${snapshot.gfi.activeSessionCount}active/${snapshot.gfi.staleSessionCount}stale`);
+  } else {
+    lines.push('gfi: (no active sessions)');
+  }
+  lines.push('');
+
+  // Actions
+  if (snapshot.recommendedActions.length === 0) {
+    lines.push('No actions recommended.');
+  } else {
+    lines.push('Recommended actions:');
+    for (const action of snapshot.recommendedActions) {
+      lines.push(`  [!] ${action}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export async function handleRuntimeHealthSnapshot(opts: HealthSnapshotOptions): Promise<void> {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const model = new OperatorHealthReadModel({ workspaceDir });
+
+  try {
+    const snapshot = await model.getSnapshot();
+
+    if (opts.json) {
+      console.log(JSON.stringify(snapshot, null, 2));
+    } else {
+      console.log(formatTextOutput(snapshot));
+    }
+
+    if (snapshot.overallStatus !== 'healthy') {
+      console.error('');
+      console.error(`FAIL: overallStatus=${snapshot.overallStatus}`);
+      process.exitCode = 1;
+    }
+  } finally {
+    await model.close();
+  }
+}