@principles/pd-cli 1.152.12 → 1.152.13

package/src/commands/trace.ts

@@ -1,174 +0,0 @@
-/**
- * pd runtime trace show command — full pain-to-ledger chain trace.
- *
- * Usage: pd runtime trace show --pain-id <id> [--workspace <path>] [--json]
- *
- * Traces the complete pain→task→run→artifact→candidate→ledger chain
- * and reports consistency, latency, and failure classification.
- *
- * PRI-129: Migrated from direct store/ledger usage
- * to PainChainReadModel (ADR-0001 boundary compliance).
- */
-
-import * as path from 'path';
-import { resolveWorkspaceDir } from '../resolve-workspace.js';
-import { PainChainReadModel } from '@principles/core/runtime-v2';
-import type { PainChainTrace, PainChainTraceLatencyMs } from '@principles/core/runtime-v2';
-
-interface TraceResult {
-  painId: string;
-  taskId: string;
-  runId?: string;
-  artifactId?: string;
-  candidateIds: string[];
-  ledgerEntryIds: string[];
-  status: string;
-  latencyMs: PainChainTraceLatencyMs;
-  failureCategory: string | null;
-  checkedAt: string;
-  missingLinks: string[];
-}
-
-interface TraceOptions {
-  painId: string;
-  workspace?: string;
-  json?: boolean;
-}
-
-function formatNoTaskResult(opts: TraceOptions, workspaceDir: string, checkedAt: string) {
-  const taskId = `diagnosis_${opts.painId}`;
-  return {
-    painId: opts.painId,
-    taskId,
-    status: 'not_found' as const,
-    failureCategory: 'runtime_unavailable' as const,
-    message: `No task found for painId: ${opts.painId}`,
-    workspace: workspaceDir,
-    checkedAt,
-    missingLinks: ['task' as const],
-  };
-}
-
-function outputResult(result: TraceResult, opts: TraceOptions): void {
-  if (opts.json) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-
-  console.log(`Pain ID:       ${result.painId}`);
-  console.log(`Task ID:       ${result.taskId}`);
-  console.log(`Status:        ${result.status}`);
-  if (result.runId) console.log(`Run ID:        ${result.runId}`);
-  if (result.artifactId) console.log(`Artifact ID:   ${result.artifactId}`);
-  if (result.candidateIds.length > 0) console.log(`Candidate IDs:  ${result.candidateIds.join(', ')}`);
-  if (result.ledgerEntryIds.length > 0) console.log(`Ledger Entries: ${result.ledgerEntryIds.join(', ')}`);
-  if (result.failureCategory) console.log(`Failure:       ${result.failureCategory}`);
-  console.log(`Checked at:    ${result.checkedAt}`);
-
-  if (Object.keys(result.latencyMs).length > 0) {
-    console.log('\nLatency:');
-    if (result.latencyMs.painToTask) console.log(`  pain→task:          ${result.latencyMs.painToTask}ms`);
-    if (result.latencyMs.taskToRun) console.log(`  task→run:           ${result.latencyMs.taskToRun}ms`);
-    if (result.latencyMs.runToArtifact) console.log(`  run→artifact:       ${result.latencyMs.runToArtifact}ms`);
-    if (result.latencyMs.artifactToCandidate) console.log(`  artifact→candidate: ${result.latencyMs.artifactToCandidate}ms`);
-    if (result.latencyMs.candidateToLedger) console.log(`  candidate→ledger:   ${result.latencyMs.candidateToLedger}ms`);
-  }
-
-  if (result.missingLinks.length > 0) {
-    console.log(`\nMissing links (${result.missingLinks.length}):`);
-    for (const link of result.missingLinks) {
-      console.log(`  - ${link}`);
-    }
-  }
-}
-
-export async function handleTraceShow(opts: TraceOptions): Promise<void> {
-  if (!opts.painId) {
-    console.error('Error: --pain-id <id> is required');
-    process.exitCode = 1;
-    return;
-  }
-
-  const workspaceDir = opts.workspace
-    ? path.resolve(opts.workspace)
-    : resolveWorkspaceDir();
-
-  const readModel = new PainChainReadModel({ workspaceDir });
-
-  try {
-    const trace: PainChainTrace = await readModel.traceByPainId(opts.painId);
-
-    if (trace.status === 'not_found') {
-      const noTaskResult = formatNoTaskResult(opts, workspaceDir, trace.checkedAt);
-      if (opts.json) {
-        console.log(JSON.stringify(noTaskResult, null, 2));
-      } else {
-        console.error(`Error: No task found for painId: ${opts.painId}`);
-        console.error(`  Derived taskId: ${noTaskResult.taskId}`);
-        console.error(`  Workspace: ${workspaceDir}`);
-      }
-      process.exitCode = 1;
-      return;
-    }
-
-    if (trace.status === 'error') {
-      const isConfigError = trace.failureCategory === 'config_missing';
-      if (opts.json) {
-        console.log(JSON.stringify({
-          painId: trace.painId,
-          taskId: trace.taskId,
-          status: 'error',
-          failureCategory: trace.failureCategory,
-          message: isConfigError
-            ? 'Failed to initialize state manager'
-            : 'Internal error during trace',
-          checkedAt: trace.checkedAt,
-          missingLinks: trace.missingLinks,
-        }, null, 2));
-      } else {
-        console.error(`Error: ${isConfigError ? 'Failed to open workspace' : 'Internal error during trace'}`);
-        console.error(`  Workspace: ${workspaceDir}`);
-      }
-      process.exitCode = 1;
-      return;
-    }
-
-    const result: TraceResult = {
-      painId: trace.painId,
-      taskId: trace.taskId,
-      runId: trace.runId,
-      artifactId: trace.artifactId,
-      candidateIds: trace.candidateIds,
-      ledgerEntryIds: trace.ledgerEntryIds,
-      status: trace.status,
-      latencyMs: trace.latencyMs,
-      failureCategory: trace.failureCategory,
-      checkedAt: trace.checkedAt,
-      missingLinks: trace.missingLinks,
-    };
-
-    outputResult(result, opts);
-
-    if (result.status === 'error' || result.status === 'failed' || result.status === 'degraded') {
-      process.exitCode = 1;
-    }
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (opts.json) {
-      console.log(JSON.stringify({
-        painId: opts.painId,
-        taskId: `diagnosis_${opts.painId}`,
-        status: 'error',
-        failureCategory: 'runtime_unavailable',
-        message: msg,
-        checkedAt: new Date().toISOString(),
-        missingLinks: ['internal_error'],
-      }, null, 2));
-    } else {
-      console.error(`Error: ${msg}`);
-    }
-    process.exitCode = 1;
-  } finally {
-    await readModel.close();
-  }
-}

package/src/commands/trajectory-db-unavailable.ts

@@ -1,19 +0,0 @@
-/**
- * Shared operator-facing failure for an unavailable trajectory database (PRI-753).
- *
- * The four trajectory-reading commands (`pd samples list/review`,
- * `pd evolution tasks list/show`) surface the same structured failure:
- * the error message carries path + reason, the second line is the next
- * action (cli-6), and the process exits before any further mutation (cli-5).
- */
-
-import type { TrajectoryDbUnavailableError } from '@principles/core/trajectory-store';
-
-const NEXT_ACTION =
-  "Trajectory data lives in the workspace database written by the PD plugin. Initialize this workspace with 'pd runtime init --confirm' or run PD here first.";
-
-export function exitWithTrajectoryDbUnavailable(err: TrajectoryDbUnavailableError): never {
-  console.error(`Error: ${err.message}`);
-  console.error(NEXT_ACTION);
-  process.exit(1);
-}

package/src/commands/trajectory.ts

@@ -1,64 +0,0 @@
-/**
- * pd trajectory locate — Locate a trajectory by task ID, run ID, or time range.
- *
- * Usage:
- *   pd trajectory locate --task <taskId> --workspace <path>
- *   pd trajectory locate --run <runId> --workspace <path>
- *   pd trajectory locate --from <date> --to <date> --workspace <path>
- */
-import { SqliteConnection, SqliteTrajectoryLocator } from '@principles/core';
-import { resolveWorkspaceDir } from '../resolve-workspace.js';
-
-interface TrajectoryLocateOptions {
-  task?: string;
-  run?: string;
-  from?: string;
-  to?: string;
-  json?: boolean;
-  workspace?: string;
-}
-
-export async function handleTrajectoryLocate(opts: TrajectoryLocateOptions): Promise<void> {
-  const workspaceDir = resolveWorkspaceDir(opts.workspace);
-  const connection = new SqliteConnection(workspaceDir);
-
-  try {
-    const locator = new SqliteTrajectoryLocator(connection);
-
-    let query: Record<string, unknown> = {};
-
-    if (opts.task) query = { taskId: opts.task };
-    else if (opts.run) query = { runId: opts.run };
-    else if (opts.from || opts.to) query = { timeRange: { start: opts.from ?? '', end: opts.to ?? '' } };
-    else {
-      console.error('Error: specify at least one search criterion (--task, --run, --from/--to)');
-      process.exit(1);
-    }
-
-    const result = await locator.locate(query);
-
-    if (result.candidates.length === 0) {
-      console.log('No trajectories found.');
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-      return;
-    }
-
-    console.log(`\nTrajectories (${result.candidates.length}):\n`);
-    for (const candidate of result.candidates) {
-      const reasonsCount = candidate.reasons.length;
-      console.log(
-        '  %s  confidence=%s  reasons=%d',
-        candidate.trajectoryRef.substring(0, 36),
-        candidate.confidence.toFixed(1),
-        reasonsCount,
-      );
-    }
-    console.log('');
-  } finally {
-    connection.close();
-  }
-}

package/src/commands/version.ts

@@ -1,49 +0,0 @@
-/**
- * pd version command (SPEC §12).
- *
- * Human output prints the short stable version text; `--json` emits exactly
- * one parseable JSON object with the full canonical report (productVersion,
- * releaseId, components, bootstrapVersion, channel, source, generation,
- * health, lastTransaction).
- */
-
-import type { Command } from 'commander';
-import { buildVersionReport, formatShortVersion, VersionReportError } from '../services/version-report.js';
-
-async function runVersion(json: boolean): Promise<void> {
-  try {
-    const report = buildVersionReport();
-    if (json) {
-      console.log(JSON.stringify(report, null, 2));
-      return;
-    }
-    console.log(formatShortVersion(report));
-  } catch (error) {
-    if (error instanceof VersionReportError) {
-      if (json) {
-        console.log(JSON.stringify({
-          ok: false,
-          reason: error.reason,
-          message: error.message,
-          nextAction: error.nextAction,
-        }, null, 2));
-      } else {
-        console.error(error.message);
-        console.error(`Next: ${error.nextAction}`);
-      }
-      process.exitCode = 1;
-      return;
-    }
-    throw error;
-  }
-}
-
-export function registerVersionCommand(program: Command): void {
-  program
-    .command('version')
-    .description('Show the canonical PD product version and installation state')
-    .option('--json', 'Emit the full canonical version report as one JSON object', false)
-    .action(async (opts: Record<string, unknown>) => {
-      await runVersion(opts.json === true);
-    });
-}

package/src/config-reader.ts

@@ -1,122 +0,0 @@
-/**
- * Config reader for pd-cli — reads outputLanguage from .pd/config.yaml.
- *
- * This is an I/O boundary module (pd-cli is the I/O layer).
- * Uses core's `resolveOutputLanguage` for validation and degradation.
- *
- * ERR entries:
- * - ERR-001: No `as` bypasses on untrusted parsed YAML — use isRecord type guard
- * - ERR-002: Graceful degradation includes reason + nextAction
- * - ERR-009: Malformed values fail loud with structured warning
- * - ERR-013: Object.hasOwn() for untrusted keys
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import * as yaml from 'js-yaml';
-import { resolveOutputLanguage, DEFAULT_OUTPUT_LANGUAGE } from '@principles/core/runtime-v2';
-import type { ResolvedOutputLanguage } from '@principles/core/runtime-v2';
-
-/**
- * Type guard: checks that a value is a non-null plain object (Record<string, unknown>).
- * Per ERR-001: use type guards instead of `as` casts at trust boundaries.
- */
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-/**
- * Build a structured degradation warning for config read errors.
- * Per ERR-002/ERR-009: every degraded path must include reason + nextAction.
- */
-function configDegradationWarning(
-  reason: 'read_error' | 'yaml_parse_error' | 'invalid_config_root' | 'invalid_principles_structure',
-  detail: string,
-): string {
-  const reasons: Record<typeof reason, { msg: string; action: string }> = {
-    read_error: {
-      msg: `Failed to read .pd/config.yaml: ${detail}`,
-      action: 'Check file permissions and ensure .pd/config.yaml is readable',
-    },
-    yaml_parse_error: {
-      msg: `Failed to parse .pd/config.yaml: ${detail}`,
-      action: 'Fix YAML syntax errors in .pd/config.yaml',
-    },
-    invalid_config_root: {
-      msg: `.pd/config.yaml root is not an object: ${detail}`,
-      action: 'Ensure .pd/config.yaml has a valid YAML mapping at the top level',
-    },
-    invalid_principles_structure: {
-      msg: `.pd/config.yaml principles field is not an object: ${detail}`,
-      action: 'Ensure principles field in .pd/config.yaml is a YAML mapping (e.g. principles: { outputLanguage: zh-CN })',
-    },
-  };
-  const entry = reasons[reason];
-  return `${entry.msg}. Falling back to default: ${DEFAULT_OUTPUT_LANGUAGE}. nextAction: ${entry.action}`;
-}
-
-/**
- * Read principles.outputLanguage from workspace .pd/config.yaml.
- *
- * Returns ResolvedOutputLanguage with:
- * - outputLanguage: the effective language to use
- * - degradationWarning: present if config was malformed or unreadable (ERR-002/ERR-009)
- *
- * Distinguishes between "not configured" (legitimate default, no warning)
- * and "config broken" (degraded with reason + nextAction).
- */
-export function readOutputLanguageFromWorkspace(workspaceDir: string): ResolvedOutputLanguage {
-  const configPath = path.join(workspaceDir, '.pd', 'config.yaml');
-
-  if (!fs.existsSync(configPath)) {
-    // No config file → legitimate default, no warning
-    return resolveOutputLanguage(undefined);
-  }
-
-  let raw: string;
-  try {
-    raw = fs.readFileSync(configPath, 'utf8');
-  } catch (err) {
-    return {
-      outputLanguage: DEFAULT_OUTPUT_LANGUAGE,
-      degradationWarning: configDegradationWarning('read_error', String(err)),
-    };
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
-  } catch (err) {
-    return {
-      outputLanguage: DEFAULT_OUTPUT_LANGUAGE,
-      degradationWarning: configDegradationWarning('yaml_parse_error', String(err)),
-    };
-  }
-
-  if (!isRecord(parsed)) {
-    return {
-      outputLanguage: DEFAULT_OUTPUT_LANGUAGE,
-      degradationWarning: configDegradationWarning('invalid_config_root', typeof parsed),
-    };
-  }
-
-  if (!Object.hasOwn(parsed, 'principles')) {
-    // No principles section → legitimate default, no warning
-    return resolveOutputLanguage(undefined);
-  }
-
-  const principlesRaw = parsed.principles;
-  if (!isRecord(principlesRaw)) {
-    return {
-      outputLanguage: DEFAULT_OUTPUT_LANGUAGE,
-      degradationWarning: configDegradationWarning('invalid_principles_structure', typeof principlesRaw),
-    };
-  }
-
-  if (!Object.hasOwn(principlesRaw, 'outputLanguage')) {
-    // No outputLanguage key → legitimate default, no warning
-    return resolveOutputLanguage(undefined);
-  }
-
-  return resolveOutputLanguage(principlesRaw.outputLanguage);
-}