@principles/pd-cli 1.106.0 → 1.108.0

package/src/commands/mvp-smoke.ts

@@ -0,0 +1,160 @@
+/**
+ * pd mvp smoke — MVP mainline readiness check (PRI-397 / C5).
+ *
+ * Assembles a MainlineSnapshot from the shared reader, judges it via the
+ * pure assertMainlineContract, and outputs a single JSON verdict.
+ *
+ * Rules (EP-04, EP-02):
+ *   - Read-only by default. NEVER mutates workspace state.
+ *   - Uses the shared mainline-snapshot-assembler (no new chain logic).
+ *   - --json mode: stdout = exactly one parseable JSON object — even on failure.
+ *     Every degraded/refused path emits a structured `{ok, reason, nextAction}`
+ *     JSON so CI/script consumers can branch on outcome (EP-04 Rule 6).
+ *   - Human mode: formatted output to stdout.
+ *   - Exit code: 0 on overall === 'ok', 1 on overall === 'violation' or failure.
+ */
+
+import type { Command } from 'commander';
+import {
+  assembleMainlineSnapshot,
+  assertMainlineContract,
+} from '../services/mainline-snapshot-assembler.js';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { withWorkspaceAndJson } from './command-helpers.js';
+
+export interface MvpSmokeOptions {
+  workspace?: string;
+  json?: boolean;
+}
+
+/**
+ * Classify a thrown error so the failure JSON can name a real next action.
+ * EP-03: never silently swallow; emit a structured reason + actionable next step.
+ */
+function classifySmokeError(err: unknown): { reason: string; nextAction: string } {
+  if (err instanceof Error) {
+    const msg = err.message;
+    const lower = msg.toLowerCase();
+    // No .pd/state.db on disk (fresh / reset workspace) is the post-PRI-398
+    // expected first failure — name the recovery path explicitly.
+    if (
+      msg.includes('SQLITE_CANTOPEN') ||
+      lower.includes('no such file') ||
+      lower.includes('no such table') ||
+      lower.includes('cannot open database') ||
+      lower.includes('directory does not exist')
+    ) {
+      return {
+        reason: `Workspace database is missing or unreadable: ${msg}`,
+        nextAction: 'Run "pd runtime internalization integrity-repair --confirm" or restore the workspace; this command requires a bootstrapped .pd/state.db.',
+      };
+    }
+    if (lower.includes('workspace') && lower.includes('not configured')) {
+      return {
+        reason: msg,
+        nextAction: 'Set --workspace <path>, PD_WORKSPACE_DIR, or add workspace.default to .pd/config.yaml.',
+      };
+    }
+    return {
+      reason: msg,
+      nextAction: 'Inspect the workspace state and retry. Run "pd config doctor --json" to validate the workspace.',
+    };
+  }
+  return {
+    reason: `Unknown failure: ${String(err)}`,
+    nextAction: 'Inspect the workspace state and retry. Run "pd config doctor --json" to validate the workspace.',
+  };
+}
+
+export async function handleMvpSmoke(opts: MvpSmokeOptions): Promise<void> {
+  // Pass through resolveWorkspaceDir to honor the consistency warning for
+  // --workspace flags that disagree with the config default. The resolver
+  // returns an absolute, normalized path either way.
+  const workspaceDir = resolveWorkspaceDir(opts.workspace);
+
+  let result;
+  try {
+    result = await assembleMainlineSnapshot({ workspaceDir });
+  } catch (err: unknown) {
+    const { reason, nextAction } = classifySmokeError(err);
+    if (opts.json) {
+      // EP-04 Rule 1 + 6: stdout = exactly one parseable JSON object carrying
+      // a structured reason and nextAction, even on the failure path.
+      console.log(JSON.stringify({
+        ok: false,
+        reason,
+        nextAction,
+        workspace: workspaceDir,
+      }, null, 2));
+    } else {
+      console.error(`MVP smoke failed: ${reason}`);
+      console.error(`nextAction: ${nextAction}`);
+    }
+    process.exit(1);
+    return;
+  }
+
+  const verdict = assertMainlineContract(result.snapshot);
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      ok: verdict.overall === 'ok',
+      verdict,
+      warnings: result.warnings,
+      resolvedPainId: result.resolvedPainId,
+    }, null, 2));
+  } else {
+    console.log(`\nMVP Smoke — ${workspaceDir}\n`);
+    console.log(`  Overall:      ${verdict.overall}`);
+    console.log(`  Pain ID:      ${verdict.painId ?? '(none)'}`);
+    console.log(`  Generated At: ${verdict.generatedAt}\n`);
+
+    console.log('  Stages:');
+    for (const s of verdict.stages) {
+      const icon = s.status === 'ok' ? '  OK' : s.status === 'violation' ? ' VIOLATION' : ' SKIP';
+      console.log(`    [${icon}] ${s.stage}`);
+      console.log(`           ${s.reason}`);
+      if (s.nextAction) {
+        console.log(`           nextAction: ${s.nextAction}`);
+      }
+      console.log('');
+    }
+
+    if (result.warnings.length > 0) {
+      console.log('  Warnings:');
+      for (const w of result.warnings) {
+        console.log(`    - ${w}`);
+      }
+      console.log('');
+    }
+  }
+
+  if (verdict.overall === 'violation') {
+    process.exit(1);
+    return;
+  }
+}
+
+/**
+ * Register the `pd mvp` parent command and its `smoke` subcommand.
+ *
+ * Single source of truth for both production (`index.ts`) and parser tests
+ * (`mvp-smoke.test.ts`). If a test passes against this function, the same
+ * registration runs in production — flag typos surface at parseAsync time.
+ */
+export function registerMvpCommands(program: Command): Command {
+  const mvpCmd = program
+    .command('mvp')
+    .description('MVP readiness commands');
+
+  withWorkspaceAndJson(
+    mvpCmd
+      .command('smoke')
+      .description('Check MVP mainline readiness: assemble snapshot → assert contract → structured verdict')
+      .action(async (opts: { workspace?: string; json?: boolean }) => {
+        await handleMvpSmoke({ workspace: opts.workspace, json: opts.json });
+      }),
+  );
+
+  return mvpCmd;
+}

package/src/commands/task.ts

@@ -6,29 +6,55 @@
  *   pd task show <taskId>
  */
 import * as path from 'path';
+import type { Command } from 'commander';
 import { RuntimeStateManager, MalformedRunError, type RunRecord } from '@principles/core';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { withWorkspaceAndJson } from './command-helpers.js';
 
 interface TaskListOptions {
   status?: string;
   kind?: string;
   limit?: number;
+  workspace?: string;
+  json?: boolean;
 }
 
 export async function handleTaskList(opts: TaskListOptions): Promise<void> {
-  const workspaceDir = resolveWorkspaceDir();
+  // Pass through resolveWorkspaceDir to honor its consistency warning when
+  // --workspace disagrees with workspace.default in .pd/config.yaml.
+  const workspaceDir = resolveWorkspaceDir(opts.workspace);
   const stateManager = new RuntimeStateManager({ workspaceDir });
-  await stateManager.initialize();
 
   try {
+    await stateManager.initialize();
+
     const filter: Record<string, string | number> = {};
     if (opts.status) filter.status = opts.status;
     if (opts.kind) filter.taskKind = opts.kind;
     if (opts.limit) filter.limit = opts.limit;
 
-     
     const tasks = await stateManager.listTasks(Object.keys(filter).length > 0 ? filter : undefined);
 
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ok: true,
+        count: tasks.length,
+        workspace: workspaceDir,
+        tasks: tasks.map((t) => ({
+          taskId: t.taskId,
+          taskKind: t.taskKind,
+          status: t.status,
+          attemptCount: t.attemptCount,
+          maxAttempts: t.maxAttempts,
+          leaseOwner: t.leaseOwner ?? null,
+          leaseExpiresAt: t.leaseExpiresAt ?? null,
+          createdAt: t.createdAt,
+          updatedAt: t.updatedAt,
+        })),
+      }, null, 2));
+      return;
+    }
+
     if (tasks.length === 0) {
       console.log('No tasks found.');
       return;
@@ -57,6 +83,23 @@ export async function handleTaskList(opts: TaskListOptions): Promise<void> {
       );
     }
     console.log('');
+  } catch (err: unknown) {
+    // EP-04: failure paths emit a single parseable JSON object with
+    // structured reason + nextAction (mirror handleTaskShow).
+    if (opts.json) {
+      const reason = err instanceof Error ? err.message : String(err);
+      console.log(JSON.stringify({
+        ok: false,
+        count: 0,
+        workspace: workspaceDir,
+        reason,
+        nextAction: 'Check workspace path and database accessibility. The workspace may need bootstrap (run "pd runtime internalization integrity-repair --confirm") or the workspace dir may be wrong.',
+      }, null, 2));
+    } else {
+      console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    process.exit(1);
+    return;
   } finally {
     await stateManager.close();
   }
@@ -204,3 +247,25 @@ export async function handleTaskShow(opts: TaskShowOptions): Promise<void> {
     await stateManager.close();
   }
 }
+
+/**
+ * Register the `pd task list` subcommand.
+ *
+ * Single source of truth for both production (`index.ts`) and parser tests
+ * (mvp-smoke.test.ts). Reuses the `withWorkspaceAndJson` helper so adding a
+ * new --workspace/--json pair elsewhere is one line, not five.
+ */
+export function registerTaskListCommand(taskCmd: Command): Command {
+  const listCmd = taskCmd
+    .command('list')
+    .description('List runtime tasks')
+    .option('-s, --status <status>', 'Filter by status (pending, leased, retry_wait, succeeded, failed)')
+    .option('-k, --kind <kind>', 'Filter by task kind')
+    .option('-l, --limit <number>', 'Limit number of results', parseInt, 50)
+    .action(async (opts: { status?: string; kind?: string; limit?: number; workspace?: string; json?: boolean }) => {
+      await handleTaskList({ status: opts.status, kind: opts.kind, limit: opts.limit, workspace: opts.workspace, json: opts.json });
+    });
+
+  withWorkspaceAndJson(listCmd);
+  return listCmd;
+}

package/src/index.ts

@@ -16,7 +16,7 @@ import { handleEvolutionTasksList } from './commands/evolution-tasks-list.js';
 import { handleEvolutionTasksShow } from './commands/evolution-tasks-show.js';
 import { handleHealth } from './commands/health.js';
 import { handleCentralSync } from './commands/central-sync.js';
-import { handleTaskList, handleTaskShow } from './commands/task.js';
+import { handleTaskShow, registerTaskListCommand } from './commands/task.js';
 import { handleRunList, handleRunShow } from './commands/run.js';
 import { handleTrajectoryLocate } from './commands/trajectory.js';
 import { handleHistoryQuery } from './commands/history.js';
@@ -50,6 +50,7 @@ import { handleProvenChannelBaseline } from './commands/proven-channel-baseline.
 import { handleDemoStoryA } from './commands/demo-story-a.js';
 import { handleRuntimeFeaturesStatus } from './commands/runtime-features.js';
 import { handleConfigDoctor } from './commands/config-doctor.js';
+import { registerMvpCommands } from './commands/mvp-smoke.js';
 
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
@@ -191,15 +192,7 @@ const rtTaskCmd = program
   .command('task')
   .description('Runtime v2 task inspection');
 
-rtTaskCmd
-  .command('list')
-  .description('List runtime tasks')
-  .option('-s, --status <status>', 'Filter by status (pending, leased, retry_wait, succeeded, failed)')
-  .option('-k, --kind <kind>', 'Filter by task kind')
-  .option('-l, --limit <number>', 'Limit number of results', parseInt, 50)
-  .action(async (opts) => {
-    await handleTaskList(opts);
-  });
+registerTaskListCommand(rtTaskCmd);
 
 rtTaskCmd
   .command('show <taskId>')
@@ -885,6 +878,10 @@ const _legacyCleanupCmd = legacyCmd
     await handleLegacyCleanup(opts.workspace, apply);
   });
 
+// ─── MVP Smoke (PRI-397) ────────────────────────────────────────────────────
+
+registerMvpCommands(program);
+
 const consoleCmd = program
   .command('console')
   .description('Start the pd-console web UI for principle review (default: legacy launcher)')

package/tests/commands/pri-393-runtime-config-unification.test.ts

@@ -281,4 +281,157 @@ funnels:
       expect(typeof parsed).toBe('object');
     });
   });
+
+  // ── Boundary Condition Tests ────────────────────────────────────────────────
+
+  describe('resolveRuntimeWithOverrides', () => {
+    it('CLI overrides take precedence over config values', async () => {
+      writeConfigYaml(tmpDir, makeValidConfigYaml({ provider: 'lmstudio', model: 'local-model' }));
+
+      const { resolveRuntimeWithOverrides } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const resolved = resolveRuntimeWithOverrides(tmpDir, {
+        provider: 'override-provider',
+        model: 'override-model',
+      }, () => 'test-key');
+
+      expect(resolved.mergedConfig).not.toBeNull();
+      if (resolved.mergedConfig) {
+        expect(resolved.mergedConfig.provider).toBe('override-provider');
+        expect(resolved.mergedConfig.model).toBe('override-model');
+      }
+    });
+
+    it('returns mergedConfig=null when base config is malformed', async () => {
+      const pdDir = path.join(tmpDir, '.pd');
+      fs.mkdirSync(pdDir, { recursive: true });
+      fs.writeFileSync(path.join(pdDir, 'config.yaml'), 'version: [invalid', 'utf8');
+
+      const { resolveRuntimeWithOverrides } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const resolved = resolveRuntimeWithOverrides(tmpDir, {
+        provider: 'override',
+      }, () => 'test-key');
+
+      expect(resolved.mergedConfig).toBeNull();
+    });
+
+    it('preserves config values when overrides are undefined', async () => {
+      writeConfigYaml(tmpDir, makeValidConfigYaml({ provider: 'lmstudio', model: 'local-model' }));
+
+      const { resolveRuntimeWithOverrides } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const resolved = resolveRuntimeWithOverrides(tmpDir, {
+        provider: undefined,
+        model: undefined,
+      }, () => 'test-key');
+
+      expect(resolved.mergedConfig).not.toBeNull();
+      if (resolved.mergedConfig) {
+        expect(resolved.mergedConfig.provider).toBe('lmstudio');
+        expect(resolved.mergedConfig.model).toBe('local-model');
+      }
+    });
+
+    it('merges numeric overrides correctly', async () => {
+      writeConfigYaml(tmpDir, makeValidConfigYaml());
+
+      const { resolveRuntimeWithOverrides } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const resolved = resolveRuntimeWithOverrides(tmpDir, {
+        maxRetries: 5,
+        timeoutMs: 60000,
+      }, () => 'test-key');
+
+      expect(resolved.mergedConfig).not.toBeNull();
+      if (resolved.mergedConfig) {
+        expect(resolved.mergedConfig.maxRetries).toBe(5);
+        expect(resolved.mergedConfig.timeoutMs).toBe(60000);
+      }
+    });
+  });
+
+  describe('edge cases and error handling', () => {
+    it('handles empty workspace directory gracefully', async () => {
+      // No .pd directory at all
+      const { resolveRuntimeFromPdConfig } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const resolved = resolveRuntimeFromPdConfig(tmpDir, () => 'test-key');
+
+      // Missing config should return defaults (ok=true with source='defaults')
+      expect(resolved.configLoadResult.ok).toBe(true);
+      expect(resolved.configSource).toBe('.pd/config.yaml');
+    });
+
+    it('handles config with missing runtimeProfiles section', async () => {
+      writeConfigYaml(tmpDir, {
+        version: 1,
+        features: {},
+        // Missing runtimeProfiles
+      });
+
+      const { resolveRuntimeFromPdConfig } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const { isRuntimeConfigError } = await import('@principles/core/runtime-v2');
+      const resolved = resolveRuntimeFromPdConfig(tmpDir, () => 'test-key');
+
+      // Missing runtimeProfiles should either load with defaults or produce
+      // a RuntimeConfigError — never silently succeed with wrong config.
+      if (isRuntimeConfigError(resolved.result)) {
+        expect(resolved.result.reason).toBeTruthy();
+        expect(resolved.result.nextAction).toBeTruthy();
+      } else {
+        // If defaults were returned, configLoadResult.ok should be true
+        expect(resolved.configLoadResult.ok).toBe(true);
+      }
+    });
+
+    it('handles config with invalid runtime profile type', async () => {
+      writeConfigYaml(tmpDir, {
+        version: 1,
+        runtimeProfiles: {
+          'bad-profile': {
+            type: 'invalid-type', // Invalid type
+          },
+        },
+        internalAgents: {
+          defaultRuntime: 'bad-profile',
+          agents: { diagnostician: { enabled: true, runtimeProfile: 'bad-profile' } },
+        },
+      });
+
+      const { resolveRuntimeFromPdConfig } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const { isRuntimeConfigError } = await import('@principles/core/runtime-v2');
+      const resolved = resolveRuntimeFromPdConfig(tmpDir, () => 'test-key');
+
+      // Invalid type should be caught — verify external contract, not internal state
+      expect(isRuntimeConfigError(resolved.result)).toBe(true);
+      if (isRuntimeConfigError(resolved.result)) {
+        expect(resolved.result.reason).toBeTruthy();
+        expect(resolved.result.nextAction).toBeTruthy();
+      }
+    });
+
+    it('handles env var returning undefined for apiKeyEnv', async () => {
+      writeConfigYaml(tmpDir, makeValidConfigYaml());
+
+      const { resolveRuntimeFromPdConfig } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const resolved = resolveRuntimeFromPdConfig(tmpDir, () => undefined);
+
+      // Should handle undefined env var gracefully
+      expect(resolved.result).toBeDefined();
+    });
+
+    it('handles multiple legacy files detected', async () => {
+      writeConfigYaml(tmpDir, makeValidConfigYaml());
+
+      // Create multiple legacy files
+      const stateDir = path.join(tmpDir, '.state');
+      fs.mkdirSync(stateDir, { recursive: true });
+      fs.writeFileSync(path.join(stateDir, 'workflows.yaml'), 'version: 1', 'utf8');
+
+      const ffDir = path.join(tmpDir, '.pd');
+      fs.writeFileSync(path.join(ffDir, 'feature-flags.yaml'), 'flags: []', 'utf8');
+
+      const { resolveRuntimeFromPdConfig } = await import('../../src/services/resolve-runtime-from-pd-config.js');
+      const resolved = resolveRuntimeFromPdConfig(tmpDir, () => 'test-key');
+
+      expect(resolved.legacyWarnings.length).toBeGreaterThan(0);
+      expect(resolved.configLoadResult.legacyFilesDetected.length).toBeGreaterThanOrEqual(2);
+    });
+  });
 });