@principles/pd-cli 1.132.0 → 1.134.0

package/src/commands/health.ts

@@ -11,10 +11,12 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import Database from 'better-sqlite3';
+import type { Command } from 'commander';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { PruningReadModel, PainChainReadModel, auditCandidateLedgerConsistency } from '@principles/core/runtime-v2';
 import type { PainChainTrace } from '@principles/core/runtime-v2';
 import { getLedgerFilePathPublic } from '@principles/core/principle-tree-ledger';
+import { handleHealthCodex } from './health-codex.js';
 
 interface LastSuccessfulChain {
   painId?: string;
@@ -188,3 +190,61 @@ export async function handleHealth(opts: HealthOptions = {}): Promise<void> {
 
   writeHealth();
 }
+
+/**
+ * Handlers backing the `pd health` command. Injected so the registration
+ * wiring test can exercise the real `registerHealthCommand` without executing
+ * real workspace/DB I/O; production uses the defaults.
+ */
+interface HealthCommandHandlers {
+  health?: typeof handleHealth;
+  healthCodex?: typeof handleHealthCodex;
+}
+
+/**
+ * Registers the `pd health` command on a Commander program.
+ *
+ * cli-7 test-wiring: this is the single registration used by both the CLI
+ * entrypoint and the wiring test, so a test exercising it covers the real
+ * production command (options + --host dispatch), not a copy.
+ *
+ * --host accepts only `openclaw` and `codex`; any other value is rejected with
+ * a structured reason/nextAction and a non-zero exit (cli-1/cli-2/cli-6). When
+ * `--json` is set, the rejection is emitted as exactly one parseable JSON
+ * object on stdout.
+ */
+export function registerHealthCommand(program: Command, handlers: HealthCommandHandlers = {}): void {
+  const healthHandler = handlers.health ?? handleHealth;
+  const codexHandler = handlers.healthCodex ?? handleHealthCodex;
+  program
+    .command('health')
+    .description('Show health diagnostics for all workspaces')
+    .option('-w, --workspace <path>', 'Workspace directory')
+    .option('--json', 'Output raw JSON')
+    .option('--host <host>', 'Host to inspect (openclaw|codex). Defaults to openclaw workspace health.')
+    .action(async (opts) => {
+      const host = opts.host ?? 'openclaw';
+      if (host !== 'codex' && host !== 'openclaw') {
+        // cli-2: exit-stops — return after setting exitCode.
+        if (opts.json) {
+          console.log(JSON.stringify({
+            ok: false,
+            reason: 'invalid_host',
+            host,
+            nextAction: `Use a supported host: openclaw or codex.`,
+          }));
+          process.exitCode = 1;
+          return;
+        }
+        console.error(`Invalid --host "${host}". Supported hosts: openclaw, codex.`);
+        console.error(`nextAction: run \`pd health --host openclaw\` or \`pd health --host codex\`.`);
+        process.exitCode = 1;
+        return;
+      }
+      if (host === 'codex') {
+        await codexHandler(opts);
+        return;
+      }
+      await healthHandler(opts);
+    });
+}

package/src/commands/intent.ts

@@ -2,14 +2,17 @@
  * pd intent — Owner-authored INTENT.md management (PRI-466).
  *
  * Subcommands:
- *   - init : create .principles/INTENT.md from the canonical template
- *   - show : display a read-only summary of INTENT.md (sections, hash, warnings)
+ *   - init : create .principles/INTENT.{lang}.md from the canonical template
+ *   - show : display a read-only summary of INTENT.{lang}.md (sections, hash, warnings)
  *
  * `init` is not gated by the intent_engineering flag — the Owner can
  * initialise the intent doc at any time. `show` IS gated: flag-off returns
  * a structured `flag_disabled` result without touching the filesystem,
  * matching the Console backend contract.
  *
+ * Bilingual: --lang zh-CN|en (default zh-CN) selects the intent doc language.
+ * File naming: INTENT.zh-CN.md / INTENT.en.md via getIntentFilename(lang).
+ *
  * JSON mode is strict: --json outputs exactly one parseable JSON object on
  * stdout (CLI Operator Gate rule 1). Failure paths include structured
  * reason + nextAction (rule 6).
@@ -27,13 +30,14 @@ import * as path from 'node:path';
 import type { Command } from 'commander';
 import {
   INTENT_MAX_BYTES,
-  INTENT_DOC_TEMPLATE,
+  getIntentFilename,
+  createIntentTemplate,
   parseIntentDocSections,
   computeIntentContentHash,
   validateIntentDocSections,
   isFeatureEnabled,
 } from '@principles/core/runtime-v2';
-import type { IntentDocSections, IntentDocWarning } from '@principles/core/runtime-v2';
+import type { IntentDocSections, IntentDocWarning, IntentLang } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { loadPdConfig, computeFlagsFromLoadResult } from '../services/pd-config-loader.js';
 import { emitResult } from '../services/cli-output.js';
@@ -41,7 +45,23 @@ import { emitResult } from '../services/cli-output.js';
 // ── Constants ────────────────────────────────────────────────────────────────
 
 const INTENT_DIR = '.principles';
-const INTENT_FILENAME = 'INTENT.md';
+
+/**
+ * Parse and validate the --lang option.
+ *
+ * Returns:
+ *   - 'zh-CN' | 'en' when value is undefined (default zh-CN) or a valid lang.
+ *   - null when value is a non-empty string that is neither 'zh-CN' nor 'en'.
+ *
+ * rc-9: invalid values MUST NOT silently fall back to zh-CN — that would
+ * let a typo like `--lang zh` quietly write to INTENT.zh-CN.md. Callers
+ * emit a structured `invalid_lang` error when null is returned.
+ */
+export function parseLang(value: string | undefined): IntentLang | null {
+  if (value === undefined) return 'zh-CN';
+  if (value === 'zh-CN' || value === 'en') return value;
+  return null;
+}
 
 // ── Output types ─────────────────────────────────────────────────────────────
 
@@ -54,7 +74,7 @@ export interface IntentInitOutput {
 }
 
 export interface IntentShowOutput {
-  status: 'ok' | 'flag_disabled' | 'not_found' | 'oversized' | 'read_error';
+  status: 'ok' | 'skipped' | 'flag_disabled' | 'not_found' | 'oversized' | 'read_error';
   flagEnabled: boolean;
   found: boolean;
   path?: string;
@@ -68,8 +88,8 @@ export interface IntentShowOutput {
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-function getIntentFilePath(workspaceDir: string): string {
-  return path.join(workspaceDir, INTENT_DIR, INTENT_FILENAME);
+function getIntentFilePath(workspaceDir: string, lang: IntentLang): string {
+  return path.join(workspaceDir, INTENT_DIR, getIntentFilename(lang));
 }
 
 function sectionsToRecord(sections: IntentDocSections): Record<string, string> {
@@ -82,9 +102,9 @@ function sectionsToRecord(sections: IntentDocSections): Record<string, string> {
   return record;
 }
 
-function formatIntentShowText(o: IntentShowOutput): string {
+function formatIntentShowText(o: IntentShowOutput, filename: string): string {
   const lines: string[] = [];
-  lines.push(`INTENT.md — ${o.path}`);
+  lines.push(`${filename} — ${o.path}`);
   lines.push(`Content hash: ${o.contentHash}`);
   lines.push(`Last edited:  ${o.lastEditedAt}`);
   lines.push('');
@@ -114,9 +134,29 @@ export interface IntentInitOptions {
   json?: boolean;
   dryRun?: boolean;
   confirm?: boolean;
+  lang?: string;
 }
 
 export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
+  const lang = parseLang(opts.lang);
+
+  // rc-9: invalid --lang must not silently fall back. Emit structured error.
+  if (lang === null) {
+    const output: IntentInitOutput = {
+      status: 'skipped',
+      path: '',
+      overwritten: false,
+      reason: 'invalid_lang',
+      nextAction: `--lang must be 'zh-CN' or 'en'. Received: ${opts.lang ?? ''}`,
+    };
+    emitResult(output, {
+      json: opts.json ?? false,
+      formatText: (o) => `Error: ${o.reason}\n→ ${o.nextAction}`,
+    });
+    process.exitCode = 1;
+    return;
+  }
+
   // CLI Gate rule 4: --dry-run and --confirm must be mutually exclusive.
   if (opts.dryRun && opts.confirm) {
     const output: IntentInitOutput = {
@@ -141,7 +181,7 @@ export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
   let dir: string;
   try {
     workspaceDir = resolveWorkspaceDir(opts.workspace);
-    filePath = getIntentFilePath(workspaceDir);
+    filePath = getIntentFilePath(workspaceDir, lang);
     dir = path.dirname(filePath);
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
@@ -160,6 +200,8 @@ export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
     return;
   }
 
+  const filename = getIntentFilename(lang);
+
   // CLI Gate rule 4: state-mutating command defaults to dry-run unless --confirm.
   const isDryRun = opts.dryRun === true || opts.confirm !== true;
 
@@ -170,11 +212,11 @@ export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
         path: filePath,
         overwritten: false,
         reason: 'file_exists',
-        nextAction: `Use --force to overwrite: pd intent init --force --confirm --workspace "${workspaceDir}"`,
+        nextAction: `Use --force to overwrite: pd intent init --force --confirm --lang ${lang} --workspace "${workspaceDir}"`,
       };
       emitResult(output, {
         json: opts.json ?? false,
-        formatText: (o) => `INTENT.md already exists at ${o.path}\n→ ${o.nextAction}`,
+        formatText: (o) => `${filename} already exists at ${o.path}\n→ ${o.nextAction}`,
       });
       process.exitCode = 1;
       return;
@@ -186,17 +228,17 @@ export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
         path: filePath,
         overwritten: opts.force === true,
         reason: 'dry_run',
-        nextAction: `Confirm write: pd intent init --confirm${opts.force ? ' --force' : ''} --workspace "${workspaceDir}"`,
+        nextAction: `Confirm write: pd intent init --confirm --lang ${lang}${opts.force ? ' --force' : ''} --workspace "${workspaceDir}"`,
       };
       emitResult(output, {
         json: opts.json ?? false,
-        formatText: (o) => `[dry-run] Would create INTENT.md at ${o.path}${o.overwritten ? ' (overwritten)' : ''}\n→ ${o.nextAction}`,
+        formatText: (o) => `[dry-run] Would create ${filename} at ${o.path}${o.overwritten ? ' (overwritten)' : ''}\n→ ${o.nextAction}`,
       });
       return;
     }
 
     fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(filePath, INTENT_DOC_TEMPLATE, 'utf8');
+    fs.writeFileSync(filePath, createIntentTemplate(lang), 'utf8');
 
     const output: IntentInitOutput = {
       status: 'ok',
@@ -205,7 +247,7 @@ export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
     };
     emitResult(output, {
       json: opts.json ?? false,
-      formatText: (o) => `Created INTENT.md at ${o.path}${o.overwritten ? ' (overwritten)' : ''}\nNext: edit the file to declare your project intent, then run "pd intent show".`,
+      formatText: (o) => `Created ${filename} at ${o.path}${o.overwritten ? ' (overwritten)' : ''}\nNext: edit the file to declare your project intent, then run "pd intent show --lang ${lang}".`,
     });
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
@@ -228,9 +270,30 @@ export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
 export interface IntentShowOptions {
   workspace?: string;
   json?: boolean;
+  lang?: string;
 }
 
 export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
+  const lang = parseLang(opts.lang);
+
+  // rc-9: invalid --lang must not silently fall back. Emit structured error.
+  if (lang === null) {
+    const output: IntentShowOutput = {
+      status: 'skipped',
+      flagEnabled: false,
+      found: false,
+      warnings: [],
+      reason: 'invalid_lang',
+      nextAction: `--lang must be 'zh-CN' or 'en'. Received: ${opts.lang ?? ''}`,
+    };
+    emitResult(output, {
+      json: opts.json ?? false,
+      formatText: (o) => `Error: ${o.reason}\n→ ${o.nextAction}`,
+    });
+    process.exitCode = 1;
+    return;
+  }
+
   // CLI Gate rule 6: workspace resolution inside try/catch for structured errors.
   let workspaceDir: string;
   try {
@@ -258,6 +321,8 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
   const flagsResult = computeFlagsFromLoadResult(configResult);
   const flagEnabled = isFeatureEnabled(flagsResult, 'intent_engineering');
 
+  const filename = getIntentFilename(lang);
+
   if (!flagEnabled) {
     const output: IntentShowOutput = {
       status: 'flag_disabled',
@@ -265,7 +330,7 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
       found: false,
       warnings: [],
       reason: 'flag_disabled',
-      nextAction: 'Enable the intent_engineering feature flag in .pd/config.yaml to read INTENT.md.',
+      nextAction: `Enable the intent_engineering feature flag in .pd/config.yaml to read ${filename}.`,
     };
     emitResult(output, {
       json: opts.json ?? false,
@@ -274,7 +339,7 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
     return;
   }
 
-  const filePath = getIntentFilePath(workspaceDir);
+  const filePath = getIntentFilePath(workspaceDir, lang);
 
   try {
     if (!fs.existsSync(filePath)) {
@@ -284,11 +349,11 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
         found: false,
         warnings: [],
         reason: 'not_found',
-        nextAction: `Create INTENT.md: pd intent init --workspace "${workspaceDir}"`,
+        nextAction: `Create ${filename}: pd intent init --confirm --lang ${lang} --workspace "${workspaceDir}"`,
       };
       emitResult(output, {
         json: opts.json ?? false,
-        formatText: (o) => `INTENT.md not found.\n→ ${o.nextAction}`,
+        formatText: (o) => `${filename} not found.\n→ ${o.nextAction}`,
       });
       return;
     }
@@ -301,11 +366,11 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
         found: true,
         warnings: [],
         reason: 'oversized',
-        nextAction: `INTENT.md exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content.`,
+        nextAction: `${filename} exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content.`,
       };
       emitResult(output, {
         json: opts.json ?? false,
-        formatText: (o) => `INTENT.md is too large.\n→ ${o.nextAction}`,
+        formatText: (o) => `${filename} is too large.\n→ ${o.nextAction}`,
       });
       return;
     }
@@ -327,7 +392,7 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
     };
     emitResult(output, {
       json: opts.json ?? false,
-      formatText: (o) => formatIntentShowText(o),
+      formatText: (o) => formatIntentShowText(o, filename),
     });
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
@@ -341,7 +406,7 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
     };
     emitResult(output, {
       json: opts.json ?? false,
-      formatText: (o) => `Error reading INTENT.md: ${o.reason}\n→ ${o.nextAction}`,
+      formatText: (o) => `Error reading ${filename}: ${o.reason}\n→ ${o.nextAction}`,
     });
     process.exitCode = 1;
   }
@@ -356,11 +421,12 @@ export function registerIntentCommand(parentCmd: Command): Command {
 
   intentCmd
     .command('init')
-    .description('Create .principles/INTENT.md from the canonical template')
+    .description('Create .principles/INTENT.{lang}.md from the canonical template')
     .option('-w, --workspace <path>', 'Workspace directory')
-    .option('--force', 'Overwrite existing INTENT.md')
+    .option('--force', 'Overwrite existing INTENT file')
     .option('--dry-run', 'Show what would happen without writing (default)')
-    .option('--confirm', 'Actually write the file (required to create INTENT.md)')
+    .option('--confirm', 'Actually write the file (required to create INTENT file)')
+    .option('--lang <lang>', 'Language: zh-CN or en (default: zh-CN)')
     .option('--json', 'Output raw JSON')
     .action(async (opts) => {
       await handleIntentInit({
@@ -369,18 +435,21 @@ export function registerIntentCommand(parentCmd: Command): Command {
         json: opts.json === true,
         dryRun: opts.dryRun === true,
         confirm: opts.confirm === true,
+        lang: opts.lang,
       });
     });
 
   intentCmd
     .command('show')
-    .description('Display a read-only summary of INTENT.md (sections, hash, warnings)')
+    .description('Display a read-only summary of INTENT.{lang}.md (sections, hash, warnings)')
     .option('-w, --workspace <path>', 'Workspace directory')
+    .option('--lang <lang>', 'Language: zh-CN or en (default: zh-CN)')
     .option('--json', 'Output raw JSON')
     .action(async (opts) => {
       await handleIntentShow({
         workspace: opts.workspace,
         json: opts.json === true,
+        lang: opts.lang,
       });
     });
 

package/src/commands/pain-evidence.ts

@@ -8,6 +8,12 @@
  *   pd pain evidence [--workspace <path>] [--limit N] [--json]
  *
  * Shows the most recent TRIGGER_DECISION log entries.
+ *
+ * Note: TRIGGER_DECISION entries are pain-signal admission gate decisions
+ * (Gate B / TriggerController). These are distinct from GFI (General
+ * Friction Index) friction events like GFI_SLICE_RESET, which track
+ * session-level tool-friction resets and are NOT pain signals. This command
+ * does not surface GFI events; use `pd runtime health gfi` for GFI state.
  */
 
 import * as fs from 'fs';

package/src/commands/pain-record.ts

@@ -32,6 +32,27 @@ export async function handlePainRecord(opts: RecordOptions): Promise<void> {
     console.error('Error: --reason <text> is required');
     console.error('Usage: pd pain record --reason <text> [--score N] [--source manual] [--workspace <path>] [--session <id>] [--json]');
     process.exit(1);
+    return;
+  }
+
+  // Bug-P fix: enforce reason length limit to prevent oversized data entering the pipeline.
+  // Consistent with pain-flood-simulation.ts (MAX_REASON_LENGTH = 500) and synthetic-baseline.ts.
+  // CodeRabbit review fix: emit JSON on --json and stop execution after exit (cli-1, cli-2, cli-5).
+  const MAX_REASON_LENGTH = 500;
+  if (opts.reason.length > MAX_REASON_LENGTH) {
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status: 'failed',
+        reason: 'reason_too_long',
+        message: `--reason must be at most ${MAX_REASON_LENGTH} characters (got ${opts.reason.length})`,
+        nextAction: 'Shorten the reason text or split it into multiple pain records.',
+      }, null, 2));
+    } else {
+      console.error(`Error: --reason must be at most ${MAX_REASON_LENGTH} characters (got ${opts.reason.length})`);
+      console.error('Next action: shorten the reason text or split into multiple pain records.');
+    }
+    process.exit(1);
+    return;
   }
 
   if (opts.score !== undefined && (isNaN(opts.score) || opts.score < 0 || opts.score > 100)) {