@principles/pd-cli 1.141.0 → 1.142.0

package/src/commands/runtime-internalization-retry.ts

@@ -22,8 +22,7 @@
  */
 
 import * as path from 'path';
-import { RuntimeStateManager } from '@principles/core/runtime-v2';
-import { hydratePITaskRecord, createPITaskDiagnosticJson, mergePITaskMetadata } from '@principles/core/runtime-v2';
+import { RuntimeStateManager, ownerRetryNeedsHumanReviewTask } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 
 export interface InternalizationRetryOptions {
@@ -111,15 +110,41 @@ export async function handleRuntimeInternalizationRetry(opts: InternalizationRet
     // Owner retry = authority reset: runnerDecision 与 completionIntent 同时
     // 清空 (保留 revisionCount / revisionCauseId / rolloutRevisionPayload /
     // repairPayload / lineage — revision budget 证据不动)。
-    const piTask = hydratePITaskRecord(task);
-    if (!piTask) {
+    // 落库序列提取在 core ownerRetryNeedsHumanReviewTask (Governance Recovery
+    // Actions v1): Console 恢复端点与 CLI 走同一段逻辑,禁止复制。
+    const outcome = await ownerRetryNeedsHumanReviewTask(stateManager, opts.taskId);
+
+    if (outcome.status === 'not_found') {
+      const out: InternalizationRetryOutput = {
+        status: 'failed',
+        taskId: opts.taskId,
+        reason: 'task_not_found',
+        nextAction: 'Verify the task id and workspace',
+      };
+      emit(out, opts.json);
+      process.exitCode = 1;
+      return;
+    }
+    if (outcome.status === 'skipped') {
+      const out: InternalizationRetryOutput = {
+        status: 'skipped',
+        taskId: opts.taskId,
+        taskKind: outcome.taskKind,
+        previousStatus: outcome.previousStatus,
+        reason: 'only_needs_human_review_tasks_are_retryable',
+        nextAction: 'This task is not in the owner attention queue; use run-once / enqueue-successors instead',
+      };
+      emit(out, opts.json);
+      return;
+    }
+    if (outcome.status === 'metadata_invalid') {
       // fail closed: 只改 status 会把(可能损坏的)旧 authority 记录原样留在
       // metadata 里,下一次 run 由它接管 —— 产生 partial retry。
       const out: InternalizationRetryOutput = {
         status: 'failed',
         taskId: opts.taskId,
-        taskKind: task.taskKind,
-        previousStatus: task.status,
+        taskKind: outcome.taskKind,
+        previousStatus: 'needs_human_review',
         reason: 'metadata_invalid',
         nextAction: 'Task metadata failed PI hydration; a retry now would risk a partial authority reset. Inspect: pd runtime internalization integrity --json',
       };
@@ -127,23 +152,12 @@ export async function handleRuntimeInternalizationRetry(opts: InternalizationRet
       process.exitCode = 1;
       return;
     }
-    // 原子单写: 同一 patch 同时落 status=pending / attemptCount=0 / 清空后的
-    // diagnosticJson。updateTask 抛错时 DB 行保持原样(单条 UPDATE),无 partial reset。
-    const merged = mergePITaskMetadata(piTask, {
-      runnerDecision: undefined,
-      completionIntent: undefined,
-    });
-    await stateManager.updateTask(opts.taskId, {
-      status: 'pending',
-      attemptCount: 0,
-      diagnosticJson: createPITaskDiagnosticJson(merged),
-    });
 
     const out: InternalizationRetryOutput = {
       status: 'requeued',
       taskId: opts.taskId,
-      taskKind: task.taskKind,
-      previousStatus: task.status,
+      taskKind: outcome.taskKind,
+      previousStatus: outcome.previousStatus,
       nextAction: 'Task requeued; it will be picked up by the auto-consumer cycle, or advance manually: pd runtime internalization run-once',
     };
     emit(out, opts.json);

package/src/index.ts

@@ -67,6 +67,7 @@ import { registerMvpCommands } from './commands/mvp-smoke.js';
 import { registerRulecodeCommand } from './commands/rulecode.js';
 import { registerIntentCommand } from './commands/intent.js';
 import { registerErrorsListCommand } from './commands/errors-list.js';
+import { registerPrinciplesCommand } from './commands/principles-stats.js';
 
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
@@ -1006,6 +1007,12 @@ registerIntentCommand(program);
 
 registerErrorsListCommand(program);
 
+// ─── Principles Stats (PRI-562 Phase 0) ─────────────────────────────────────
+// Owner-facing observability: principle injection volume/cost/duplicates/
+// application evidence. Read-only aggregation over event logs + receipt ledger.
+
+registerPrinciplesCommand(program);
+
 const consoleCmd = program
   .command('console')
   .description('Start the pd-console web UI for principle review (default: fallback launcher)')

package/tests/bdd/principles-stats.steps.ts

@@ -0,0 +1,211 @@
+/**
+ * BDD step definitions for `pd principles stats` (PRI-562 Phase 0,
+ * cli-1/cli-5/cli-6 contract).
+ *
+ * Approach: in-process handler invocation against real temp-workspace
+ * fixtures (same pattern as tests/commands/principles-stats.test.ts —
+ * real event JSONL + real SqliteConnection-bootstrap schema, no heavy mocks).
+ *
+ * @see docs/specs/features/cli/principles-stats.feature
+ */
+import { vi, expect } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import Database from 'better-sqlite3';
+import { SqliteConnection } from '@principles/core';
+import { readFileSync } from 'node:fs';
+import { createStepRegistry, defineFeature } from './support/vitest-bdd.js';
+import { resolveFeaturePath } from './support/repo-root.js';
+import { handlePrinciplesStats } from '../../src/commands/principles-stats.js';
+
+const registry = createStepRegistry();
+
+interface WsState {
+  ws?: string;
+  dbBytesBefore?: Buffer;
+  ledgerRowsBefore?: number;
+}
+
+const state: WsState = {};
+
+function localDateString(d: Date): string {
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+let stdoutText = '';
+let stderrText = '';
+let lastExitCode: number | undefined;
+
+function makeFixtureWorkspace(): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-principles-bdd-'));
+  const today = localDateString(new Date());
+  const logsDir = path.join(root, '.state', 'logs');
+  fs.mkdirSync(logsDir, { recursive: true });
+  const event = JSON.stringify({
+    ts: Date.now(),
+    date: today,
+    type: 'runtime_v2_prompt_activations_injected',
+    category: 'injected',
+    sessionId: 'bdd-s1',
+    data: {
+      sessionId: 'bdd-s1',
+      principleIds: ['p1', 'p2'],
+      injectedCount: 2,
+      skippedWarnings: [],
+      injectedCharCount: 420,
+      budget: 2000,
+      legacySelectedCount: 1,
+      legacyTotalChars: 300,
+      legacyTruncated: false,
+      v2Truncated: false,
+      crossBlockDuplicateIds: ['p2'],
+    },
+  });
+  fs.writeFileSync(path.join(logsDir, `events_${today}.jsonl`), [event, ''].join('\n'), 'utf8');
+
+  fs.mkdirSync(path.join(root, '.pd'), { recursive: true });
+  const connection = new SqliteConnection({ workspaceDir: root });
+  const db = connection.getDb();
+  const insert = db.prepare(
+    `INSERT INTO principle_applications (principle_id, channel, level, kind, session_id, created_at)
+     VALUES (?, 'prompt', ?, ?, ?, ?)`,
+  );
+  insert.run('p1', 'presence', 'prompt_injected', 'bdd-s1', new Date().toISOString());
+  insert.run('p2', 'presence', 'prompt_injected', 'bdd-s1', new Date().toISOString());
+  insert.run('p2', 'effect', 'self_reported', 'bdd-s1', new Date().toISOString());
+  connection.close();
+  return root;
+}
+
+// ── Given ────────────────────────────────────────────────────────────────────
+
+registry.given('一个可用的 pd-cli 可执行文件', () => {
+  state.ws = undefined;
+});
+
+registry.given('一个包含已知注入事件与回执账本的临时工作区', () => {
+  state.ws = makeFixtureWorkspace();
+  const dbPath = path.join(state.ws, '.pd', 'state.db');
+  state.dbBytesBefore = readFileSync(dbPath);
+  const db = new Database(dbPath, { readonly: true });
+  state.ledgerRowsBefore =
+    (db.prepare('SELECT COUNT(*) AS n FROM principle_applications').get() as { n: number }).n;
+  db.close();
+});
+
+registry.given('一个空的临时工作区', () => {
+  state.ws = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-principles-bdd-empty-'));
+});
+
+// ── When ─────────────────────────────────────────────────────────────────────
+
+registry.when(/operator 执行 "pd principles stats( --json)?"/, async (_ctx, jsonFlag) => {
+  const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  const errSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+  const originalExitCode = process.exitCode;
+  process.exitCode = undefined;
+  try {
+    await handlePrinciplesStats({ workspace: state.ws, json: !!jsonFlag });
+  } finally {
+    stdoutText = logSpy.mock.calls.map((c) => String(c[0])).join('');
+    stderrText = errSpy.mock.calls.map((c) => String(c[0])).join('');
+    logSpy.mockRestore();
+    errSpy.mockRestore();
+    lastExitCode = process.exitCode;
+    process.exitCode = originalExitCode;
+  }
+});
+
+// ── Then ─────────────────────────────────────────────────────────────────────
+
+registry.then('stdout 是严格的单一 JSON 对象', () => {
+  expect(lastExitCode).toBeUndefined();
+  expect(stderrText).toBe('');
+  expect(stdoutText.trim().startsWith('{')).toBe(true);
+  expect(stdoutText.trim().endsWith('}')).toBe(true);
+});
+
+registry.then('该 JSON 对象可以被 JSON.parse 解析', () => {
+  expect(() => JSON.parse(stdoutText)).not.toThrow();
+});
+
+registry.then('stdout 不包含任何 banner 或 heading', () => {
+  const text = stdoutText.replace(/^\s*\{[\s\S]*\}\s*$/, '');
+  expect(text).toBe('');
+});
+
+function getParsed(): Record<string, unknown> {
+  // rc-1/rc-2: narrow from unknown via runtime guards before touching fields.
+  const parsed: unknown = JSON.parse(stdoutText);
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`Expected JSON object in stdout but got: ${typeof parsed}`);
+  }
+  // runtime-contract-exempt: ERR-001 narrowed from unknown via typeof + Array.isArray check above (test-only helper on trusted stdout JSON)
+  return parsed as Record<string, unknown>;
+}
+
+registry.then('该 JSON 对象的 ok 字段为 true', () => {
+  expect(getParsed().ok).toBe(true);
+});
+
+registry.then('该 JSON 对象包含 injections 指标组', () => {
+  expect(typeof getParsed().injections).toBe('object');
+});
+
+registry.then('该 JSON 对象包含 chars 指标组', () => {
+  expect(typeof getParsed().chars).toBe('object');
+});
+
+registry.then('该 JSON 对象包含 duplicates 指标组', () => {
+  expect(typeof getParsed().duplicates).toBe('object');
+});
+
+registry.then('该 JSON 对象包含 applicationCorrelation 指标组', () => {
+  expect(typeof getParsed().applicationCorrelation).toBe('object');
+});
+
+registry.then('数据库未被修改', () => {
+  const dbPath = path.join(state.ws as string, '.pd', 'state.db');
+  expect(readFileSync(dbPath).equals(state.dbBytesBefore)).toBe(true);
+});
+
+registry.then('ledger 未被修改', () => {
+  const db = new Database(path.join(state.ws as string, '.pd', 'state.db'), { readonly: true });
+  const n = (db.prepare('SELECT COUNT(*) AS n FROM principle_applications').get() as { n: number }).n;
+  db.close();
+  expect(n).toBe(state.ledgerRowsBefore);
+});
+
+registry.then('未入队新任务', () => {
+  // Read-only command: no queue writes anywhere. Guarded by the DB-bytes
+  // comparison above; nothing further to assert without a tasks table.
+  expect(state.dbBytesBefore).toBeDefined();
+});
+
+registry.then('未创建后继任务', () => {
+  expect(state.dbBytesBefore).toBeDefined();
+});
+
+registry.then('该 JSON 对象的 status 字段为 "degraded"', () => {
+  expect(getParsed().status).toBe('degraded');
+});
+
+registry.then('该 JSON 对象包含 nextAction 字段', () => {
+  expect(typeof getParsed().nextAction).toBe('string');
+  expect((getParsed().nextAction as string).length).toBeGreaterThan(0);
+});
+
+registry.then('nextAction 说明如何启用 receipt flag 或先产生注入数据', () => {
+  const nextAction = getParsed().nextAction as string;
+  expect(nextAction.includes('.pd/config.yaml') || nextAction.includes('Run PD')).toBe(true);
+});
+
+// ── Define Feature ───────────────────────────────────────────────────────────
+
+const featurePath = resolveFeaturePath('docs/specs/features/cli/principles-stats.feature');
+const featureText = readFileSync(featurePath, 'utf8');
+defineFeature(featureText, registry);

package/tests/commands/principles-stats-wiring.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Parser-level tests for `pd principles stats` flags (CLI gate rule 7).
+ *
+ * Mirrors `runtime-activation-list-flag-wiring.test.ts`. Exercises the real
+ * `registerPrinciplesCommand` helper (single source of truth shared with
+ * index.ts). Flag typos in the production surface fail here at parseAsync
+ * time, not at handler dispatch.
+ *
+ * Covers:
+ *   - --json is registered; --no-json is NOT (no accidental negation)
+ *   - --workspace / -w shorthand is registered
+ *   - --days is registered with parseInt coercer
+ *   - --dry-run / --confirm are NOT registered (read-only command, cli-4 N/A)
+ *
+ * Handler-level behavior (aggregation, JSON output shape) is covered by
+ * principles-stats.test.ts.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+
+import { registerPrinciplesCommand } from '../../src/commands/principles-stats.js';
+
+type ActionOptions = Record<string, unknown>;
+
+interface CapturedAction {
+  opts: ActionOptions | null;
+}
+
+function freshProgram(): Command {
+  const program = new Command();
+  program.name('pd').exitOverride();
+  return program;
+}
+
+function registerWithCapture(program: Command, state: CapturedAction): Command {
+  const principles = registerPrinciplesCommand(program);
+  const statsCmd = principles.commands.find((c) => c.name() === 'stats');
+  if (!statsCmd) throw new Error('stats subcommand not registered');
+  statsCmd.action(function captureAction(...args: unknown[]): void {
+    let optsArg: unknown = null;
+    for (let i = args.length - 1; i >= 0; i--) {
+      const arg: unknown = args[i];
+      if (arg !== null && typeof arg === 'object' && !(arg instanceof Command)) {
+        optsArg = arg;
+        break;
+      }
+    }
+    state.opts = optsArg !== null && typeof optsArg === 'object' ? (optsArg as ActionOptions) : {};
+  });
+  return statsCmd;
+}
+
+describe('pd principles stats — flag wiring (CLI gate rule 7)', () => {
+  it('registers --json flag on the stats subcommand', () => {
+    const program = freshProgram();
+    const statsCmd = registerPrinciplesCommand(program).commands.find((c) => c.name() === 'stats');
+    expect(statsCmd).toBeDefined();
+    const opt = statsCmd?.options.find((o) => o.long === '--json');
+    expect(opt).toBeDefined();
+  });
+
+  it('registers -w shorthand for --workspace', () => {
+    const program = freshProgram();
+    const statsCmd = registerPrinciplesCommand(program).commands.find((c) => c.name() === 'stats');
+    const opt = statsCmd?.options.find((o) => o.short === '-w');
+    expect(opt).toBeDefined();
+    expect(opt?.long).toBe('--workspace');
+  });
+
+  it('registers --days', () => {
+    const program = freshProgram();
+    const statsCmd = registerPrinciplesCommand(program).commands.find((c) => c.name() === 'stats');
+    const opt = statsCmd?.options.find((o) => o.long === '--days');
+    expect(opt).toBeDefined();
+  });
+
+  it('does NOT register --dry-run or --confirm (read-only command)', () => {
+    const program = freshProgram();
+    const statsCmd = registerPrinciplesCommand(program).commands.find((c) => c.name() === 'stats');
+    expect(statsCmd?.options.find((o) => o.long === '--dry-run')).toBeUndefined();
+    expect(statsCmd?.options.find((o) => o.long === '--confirm')).toBeUndefined();
+  });
+
+  it('does NOT register --no-json (no accidental negation)', () => {
+    const program = freshProgram();
+    const statsCmd = registerPrinciplesCommand(program).commands.find((c) => c.name() === 'stats');
+    expect(statsCmd?.options.find((o) => o.long === '--no-json')).toBeUndefined();
+  });
+
+  // ── Parser-level tests (program.parseAsync) ───────────────────────────────
+
+  it('parses --json as true through the full command path', async () => {
+    const program = freshProgram();
+    const captured: CapturedAction = { opts: null };
+    registerWithCapture(program, captured);
+
+    await program.parseAsync(['node', 'pd', 'principles', 'stats', '--json']);
+
+    expect(captured.opts).not.toBeNull();
+    expect(captured.opts?.json).toBe(true);
+  });
+
+  it('parses -w shorthand for --workspace', async () => {
+    const program = freshProgram();
+    const captured: CapturedAction = { opts: null };
+    registerWithCapture(program, captured);
+
+    await program.parseAsync(['node', 'pd', 'principles', 'stats', '-w', '/tmp/ws']);
+
+    expect(captured.opts?.workspace).toBe('/tmp/ws');
+  });
+
+  it('parses --days as a number via the parseInt coercer', async () => {
+    const program = freshProgram();
+    const captured: CapturedAction = { opts: null };
+    registerWithCapture(program, captured);
+
+    await program.parseAsync(['node', 'pd', 'principles', 'stats', '--days', '30']);
+
+    expect(captured.opts?.days).toBe(30);
+  });
+
+  it('defaults all options to undefined when none passed', async () => {
+    const program = freshProgram();
+    const captured: CapturedAction = { opts: null };
+    registerWithCapture(program, captured);
+
+    await program.parseAsync(['node', 'pd', 'principles', 'stats']);
+
+    expect(captured.opts?.json).toBeUndefined();
+    expect(captured.opts?.workspace).toBeUndefined();
+    expect(captured.opts?.days).toBeUndefined();
+  });
+});