@principles/pd-cli 1.136.0 → 1.138.0

package/src/commands/runtime-init.ts

@@ -18,12 +18,38 @@
  */
 
 import * as path from 'path';
-import { SqliteConnection } from '@principles/core/runtime-v2';
-import { SchemaConformanceReadModel } from '@principles/core/runtime-v2';
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+import { SqliteConnection, SchemaConformanceReadModel } from '@principles/core/runtime-v2';
+import { getDefaultPdConfig, validatePdConfig } from '@principles/core/runtime-v2';
 import { initTrajectorySchema, initWorkflowSchema } from 'principles-disciple';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { emitResult, emitFlagConflict, emitError } from '../services/cli-output.js';
 
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const CONFIG_DIR = '.pd';
+const CONFIG_FILENAME = 'config.yaml';
+const CONFIG_HEADER =
+  `# PD Runtime Configuration — single source of truth (.pd/config.yaml, ADR-0016)\n` +
+  `# Auto-generated by 'pd runtime init'. Existing config files are never overwritten.\n` +
+  `# Edit to configure feature flags, runtime profiles, internal agents, and UI.\n`;
+
+/**
+ * Type guard for Node.js errno errors (rc-2: no `as` on caught unknown).
+ * Mirrors principle-tree-ledger.ts — uses Object.hasOwn, not `in`.
+ * Structural type (not NodeJS.ErrnoException) to avoid the NodeJS global,
+ * which is not defined in this package's eslint config.
+ * Needed to detect EEXIST from the atomic exclusive write below.
+ */
+interface ErrnoExceptionLike {
+  code?: string;
+}
+
+function isErrnoException(value: unknown): value is ErrnoExceptionLike {
+  return typeof value === 'object' && value !== null && Object.hasOwn(value, 'code');
+}
+
 // ── Output types ─────────────────────────────────────────────────────────────
 
 export interface DatabaseInitResult {
@@ -34,11 +60,18 @@ export interface DatabaseInitResult {
   warnings: string[];
 }
 
+export interface ConfigInitResult {
+  path: string;
+  status: 'initialized' | 'skipped' | 'failed' | 'verified';
+  warnings: string[];
+}
+
 export interface RuntimeInitOutput {
   ok: boolean;
   mode: 'dry-run' | 'confirm';
   workspace: string;
   databases: DatabaseInitResult[];
+  config?: ConfigInitResult;
   warnings: string[];
   reason?: string;
   nextAction?: string;
@@ -52,6 +85,100 @@ const DB_NAMES = {
   workflow: 'subagent_workflows.db',
 } as const;
 
+// ── Config file generation ─────────────────────────────────────────────────────
+
+/**
+ * Build a clean YAML representation of the default PD config, injecting the
+ * workspace.default path so that discoverWorkspaceDefault() can find it.
+ *
+ * Returns the YAML string (with header comment) for writing to disk.
+ */
+function buildConfigYaml(workspaceDir: string): string {
+  const config = getDefaultPdConfig();
+  const yamlObj: Record<string, unknown> = {
+    version: config.version,
+    workspace: {
+      default: workspaceDir,
+    },
+    features: config.features,
+    runtimeProfiles: config.runtimeProfiles,
+    internalAgents: config.internalAgents,
+    ui: config.ui,
+  };
+  return CONFIG_HEADER + yaml.dump(yamlObj, {
+    indent: 2,
+    lineWidth: 120,
+    noRefs: true,
+    sortKeys: false,
+    quotingType: '"',
+    forceQuotes: false,
+  });
+}
+
+/**
+ * Generate and write .pd/config.yaml if it does not already exist.
+ * Validates the generated file with a round-trip parse+validate check.
+ */
+function buildConfigInitResult(workspaceDir: string, confirm: boolean): ConfigInitResult {
+  const configPath = path.join(workspaceDir, CONFIG_DIR, CONFIG_FILENAME);
+  const warnings: string[] = [];
+
+  if (!confirm) {
+    return { path: configPath, status: 'skipped', warnings: [] };
+  }
+
+  // Ensure .pd directory exists
+  const configDir = path.dirname(configPath);
+  try {
+    fs.mkdirSync(configDir, { recursive: true });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return { path: configPath, status: 'failed', warnings: [`Failed to create ${configDir}: ${reason}`] };
+  }
+
+  // Build and write YAML
+  let yamlContent: string;
+  try {
+    yamlContent = buildConfigYaml(workspaceDir);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return { path: configPath, status: 'failed', warnings: [`Failed to build config YAML: ${reason}`] };
+  }
+
+  try {
+    // Atomic exclusive create ('wx'): the write itself is the authoritative
+    // existence check — fails with EEXIST if the file already exists (from a
+    // previous run or a concurrent process). No existsSync pre-check, so there
+    // is no TOCTOU window and the "never overwrite existing config" contract
+    // is race-free (CodeQL js/race-condition).
+    fs.writeFileSync(configPath, yamlContent, { encoding: 'utf8', flag: 'wx' });
+  } catch (err) {
+    if (isErrnoException(err) && err.code === 'EEXIST') {
+      return { path: configPath, status: 'skipped', warnings: ['config.yaml already exists, skipped'] };
+    }
+    const reason = err instanceof Error ? err.message : String(err);
+    return { path: configPath, status: 'failed', warnings: [`Failed to write ${configPath}: ${reason}`] };
+  }
+
+  // Round-trip validation: read back, parse, validate
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const parsed: unknown = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+    const validationResult = validatePdConfig(parsed);
+    if (!validationResult.ok) {
+      warnings.push(`config.yaml round-trip validation produced ${validationResult.errors.length} warnings`);
+      for (const ve of validationResult.errors) {
+        warnings.push(`  [${ve.path}] ${ve.reason} — ${ve.nextAction}`);
+      }
+    }
+  } catch (err) {
+    // Non-fatal: proceed even if round-trip check fails
+    warnings.push(`config.yaml round-trip check skipped: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  return { path: configPath, status: 'initialized', warnings };
+}
+
 export function buildRuntimeInitOutput(workspaceDir: string, confirm: boolean): RuntimeInitOutput {
   const resolvedWorkspace = path.resolve(workspaceDir);
   const warnings: string[] = [];
@@ -213,11 +340,27 @@ export function buildRuntimeInitOutput(workspaceDir: string, confirm: boolean):
     }
   }
 
+  // 4. config.yaml — scaffold the single source of truth (P0: runtime discovery)
+  const config = buildConfigInitResult(resolvedWorkspace, confirm);
+  if (config.status === 'failed') {
+    return {
+      ok: false,
+      mode: 'confirm',
+      workspace: resolvedWorkspace,
+      databases,
+      config,
+      warnings,
+      reason: config.warnings[0] ?? 'config.yaml initialization failed',
+      nextAction: 'Check .pd directory permissions and disk space, then re-run `pd runtime init --confirm`.',
+    };
+  }
+
   return {
     ok: true,
     mode: confirm ? 'confirm' : 'dry-run',
     workspace: resolvedWorkspace,
     databases,
+    config,
     warnings,
   };
 }
@@ -246,6 +389,17 @@ function formatTextOutput(output: RuntimeInitOutput): string {
     }
   }
 
+  if (output.config) {
+    const icon = output.config.status === 'initialized' ? '[+]' :
+                 output.config.status === 'verified' ? '[v]' :
+                 output.config.status === 'skipped' ? '[ ]' : '[x]';
+    lines.push(`${icon} config.yaml (${output.config.status})`);
+    lines.push(`    path: ${output.config.path}`);
+    for (const w of output.config.warnings) {
+      lines.push(`    warning: ${w}`);
+    }
+  }
+
   if (output.warnings.length > 0) {
     lines.push('');
     lines.push('Warnings:');

package/src/commands/runtime-internalization-run-once.ts

@@ -20,6 +20,8 @@ import {
 import type { WakeOnceResult, DreamerRunnerResult, PhilosopherRunnerResult, ScribeRunnerResult, ArtificerRunnerResult, EvaluatorRunnerResult, RolloutReviewerRunnerResult, PDRuntimeAdapter, PeerRunnerKind, OutputLanguage } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { readOutputLanguageFromWorkspace } from '../config-reader.js';
+import { loadPdConfig } from '../services/pd-config-loader.js';
+import type { EffectivePdConfig } from '@principles/core/runtime-v2';
 import {
   resolveRuntimeAdapterFromConfig,
   ConfigResolutionError,
@@ -447,6 +449,11 @@ export async function handleRuntimeInternalizationRunOnce(opts: RunOnceOptions):
   const stateManager = new RuntimeStateManager({ workspaceDir });
   await stateManager.initialize();
 
+  // Issue 2: resolve effective config for feature-flag-aware runners
+  // (e.g. `artificer_output_retry`). Mirrors rulehost-pipeline-runner.
+  const configLoad = loadPdConfig(workspaceDir);
+  const effectiveConfig: EffectivePdConfig | undefined = configLoad.ok ? configLoad.effective : configLoad.defaults;
+
   try {
     const orchestrator = new InternalizationOrchestrator(
       { stateManager },
@@ -515,7 +522,7 @@ export async function handleRuntimeInternalizationRunOnce(opts: RunOnceOptions):
           const validator = new DefaultArtificerValidator();
           const runner = new ArtificerRunner(
             { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore, contentHashFn },
-            { owner: OWNER, runtimeKind: runtimeAdapter.kind(), pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
+            { owner: OWNER, runtimeKind: runtimeAdapter.kind(), pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs, effectiveConfig },
           );
           runnerResult = await runner.run(wakeResult.taskId);
         } else if (runnerKind === 'evaluator') {

package/src/services/rulehost-pipeline-runner.ts

@@ -272,6 +272,11 @@ export async function runRuleHostPipeline(opts: RuleHostPipelineOptions): Promis
   try {
     const artifactStore = stateManager.piArtifactStore;
     const eventEmitter = new StoreEventEmitter();
+    // Issue 2: load effective config once so every stage runner can resolve
+    // feature flags (e.g. `artificer_output_retry`). Mirrors
+    // createEvaluatorRunnerDeps (rc-9: malformed config → fallback defaults).
+    const configLoad = loadPdConfig(opts.workspaceDir);
+    const effectiveConfig = configLoad.ok ? configLoad.effective : configLoad.defaults;
     // Allow the caller's adapter to resolve real artifactIds (needed by
     // test-double adapters whose scripted outputs must match store-assigned IDs).
     opts.onStoreReady?.(artifactStore);
@@ -282,7 +287,7 @@ export async function runRuleHostPipeline(opts: RuleHostPipelineOptions): Promis
       scribe: opts.runtimeAdapter,
       evaluator: opts.runtimeAdapter,
     };
-    const runnerOptsFor = (adapter: PDRuntimeAdapter) => ({ owner, runtimeKind: adapter.kind(), pollIntervalMs, timeoutMs });
+    const runnerOptsFor = (adapter: PDRuntimeAdapter) => ({ owner, runtimeKind: adapter.kind(), pollIntervalMs, timeoutMs, effectiveConfig });
 
     // ── Stage: pain lookup ──
     // Find a dreamer task already seeded for this pain (the pain→dreamer bridge

package/tests/commands/runtime-activation.test.ts

@@ -655,7 +655,8 @@ describe('handleRuntimeActivationList', () => {
     expect(rec.evidenceRefs).toEqual(['ex-1', 'ex-2']);
     expect(rec.evidenceSummary).toContain('2 evidence ref(s)');
     expect(rec.nextAction).toContain('Enable rulecode_context_v2 flag');
-    expect(rec.nextAction).toContain('pd activation deactivate --activation-id act-v2-shadow --confirm');
+    expect(rec.nextAction).toContain('pd activation deactivate --activation-id act-v2-shadow');
+    expect(rec.nextAction).not.toContain('--confirm');
 
     // Restore the mock for subsequent tests.
     mockFeatureFlags.flags.rulecode_context_v2.enabled = true;
@@ -761,7 +762,8 @@ describe('handleRuntimeActivationList', () => {
     expect(rec.status).toBe('active');
     expect(rec.mode).toBe('live');
     expect(rec.promotedAt).toBe('2026-06-19T00:00:00.000Z');
-    expect(rec.nextAction).toBe('pd activation deactivate --activation-id act-v1-live --confirm');
+    expect(rec.nextAction).toBe('pd activation deactivate --activation-id act-v1-live');
+    expect(rec.nextAction).not.toContain('--confirm');
   });
 
   it('PRI-491: text output shows promotedAt timestamp when present', async () => {
@@ -790,7 +792,8 @@ describe('handleRuntimeActivationList', () => {
     const text = consoleLogSpy.mock.calls.map(c => c[0]).join('\n');
     expect(text).toContain('(live)');
     expect(text).toContain('promotedAt: 2026-06-19T00:00:00.000Z');
-    expect(text).toContain('nextAction: pd activation deactivate --activation-id act-v1-live --confirm');
+    expect(text).toContain('nextAction: pd activation deactivate --activation-id act-v1-live');
+    expect(text).not.toContain('--confirm');
   });
 
   it('PRI-491: deactivated activation shows [DEACTIVATED <ts>] regardless of contextVersion (precedence)', async () => {

package/tests/commands/runtime-init-empty-workspace.test.ts

@@ -18,7 +18,9 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import * as yaml from 'js-yaml';
 import Database from 'better-sqlite3';
+import { validatePdConfig } from '@principles/core/runtime-v2';
 import { buildRuntimeInitOutput } from '../../src/commands/runtime-init.js';
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
@@ -190,6 +192,26 @@ describe('pd runtime init — empty workspace integration', () => {
         db.close();
       }
     });
+
+    // ── P0: config.yaml scaffolding (Issue 1b) ────────────────────────────────
+
+    it('creates .pd/config.yaml with version 1 and workspace.default set', () => {
+      buildRuntimeInitOutput(tmpDir, true);
+      const configPath = path.join(tmpDir, '.pd', 'config.yaml');
+      expect(fs.existsSync(configPath)).toBe(true);
+      const parsed = yaml.load(fs.readFileSync(configPath, 'utf8'), { schema: yaml.JSON_SCHEMA });
+      const obj = parsed as { version?: unknown; workspace?: { default?: unknown } };
+      expect(obj.version).toBe(1);
+      expect(obj.workspace?.default).toBe(path.resolve(tmpDir));
+    });
+
+    it('generated config.yaml passes validatePdConfig (round-trip)', () => {
+      buildRuntimeInitOutput(tmpDir, true);
+      const configPath = path.join(tmpDir, '.pd', 'config.yaml');
+      const parsed: unknown = yaml.load(fs.readFileSync(configPath, 'utf8'), { schema: yaml.JSON_SCHEMA });
+      const result = validatePdConfig(parsed);
+      expect(result.ok).toBe(true);
+    });
   });
 
   // ── EMPTY-02: idempotency ──────────────────────────────────────────────────
@@ -215,6 +237,12 @@ describe('pd runtime init — empty workspace integration', () => {
       // Table set should be unchanged
       const tables2 = getTableNames(trajDbPath);
       expect(tables2).toEqual(tables1);
+
+      // config.yaml is preserved: second run reports skipped, content unchanged
+      expect(output2.config?.status).toBe('skipped');
+      const configPath = path.join(tmpDir, '.pd', 'config.yaml');
+      const config1 = fs.readFileSync(configPath, 'utf8');
+      expect(fs.readFileSync(configPath, 'utf8')).toBe(config1);
     });
 
     it('dry-run after confirm does not modify existing DBs', () => {

package/tests/commands/runtime-init.test.ts

@@ -40,10 +40,14 @@ vi.mock('principles-disciple', () => ({
   initWorkflowSchema: mockState.initWorkflowSchema,
 }));
 
-vi.mock('@principles/core/runtime-v2', () => ({
-  SqliteConnection: mockState.sqliteConnectionCtor,
-  SchemaConformanceReadModel: mockState.schemaConformanceCtor,
-}));
+vi.mock('@principles/core/runtime-v2', async () => {
+  const actual = await vi.importActual<typeof import('@principles/core/runtime-v2')>('@principles/core/runtime-v2');
+  return {
+    ...actual,
+    SqliteConnection: mockState.sqliteConnectionCtor,
+    SchemaConformanceReadModel: mockState.schemaConformanceCtor,
+  };
+});
 
 vi.mock('../../src/resolve-workspace.js', () => ({
   resolveWorkspaceDir: mockState.resolveWorkspaceDir,
@@ -343,4 +347,67 @@ describe('pd runtime init', () => {
       } finally { rmTmpDir(tmp); }
     });
   });
+
+  // ── INIT-07: config.yaml scaffolding (P0: runtime discovery) ───────────────
+
+  describe('INIT-07: config.yaml scaffolding', () => {
+    it('dry-run reports config.yaml as skipped without writing the file', () => {
+      const tmp = mkTmpDir();
+      try {
+        const output = buildRuntimeInitOutput(tmp, false);
+        expect(output.config).toBeDefined();
+        expect(output.config?.status).toBe('skipped');
+        expect(fs.existsSync(path.join(tmp, '.pd', 'config.yaml'))).toBe(false);
+      } finally { rmTmpDir(tmp); }
+    });
+
+    it('--confirm writes a valid config.yaml with version and workspace.default', async () => {
+      const tmp = mkTmpDir();
+      try {
+        const output = buildRuntimeInitOutput(tmp, true);
+        expect(output.config?.status).toBe('initialized');
+        const configPath = path.join(tmp, '.pd', 'config.yaml');
+        expect(fs.existsSync(configPath)).toBe(true);
+        const yaml = (await import('js-yaml')).default;
+        const raw = fs.readFileSync(configPath, 'utf8');
+        const parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+        expect(typeof parsed).toBe('object');
+        const obj = parsed as { version?: unknown; workspace?: { default?: unknown }; features?: unknown };
+        expect(obj.version).toBe(1);
+        expect(obj.workspace?.default).toBe(path.resolve(tmp));
+        expect(obj.features).toBeDefined();
+        expect(Object.keys(obj.features as Record<string, unknown>).length).toBeGreaterThan(0);
+      } finally { rmTmpDir(tmp); }
+    });
+
+    it('round-trip: generated config passes validatePdConfig', async () => {
+      const tmp = mkTmpDir();
+      try {
+        buildRuntimeInitOutput(tmp, true);
+        const configPath = path.join(tmp, '.pd', 'config.yaml');
+        const yaml = (await import('js-yaml')).default;
+        const { validatePdConfig } = await import('@principles/core/runtime-v2');
+        const parsed: unknown = yaml.load(fs.readFileSync(configPath, 'utf8'), { schema: yaml.JSON_SCHEMA });
+        const result = validatePdConfig(parsed);
+        expect(result.ok).toBe(true);
+      } finally { rmTmpDir(tmp); }
+    });
+
+    it('--confirm skips when config.yaml already exists (preserves user file)', () => {
+      const tmp = mkTmpDir();
+      try {
+        // Pre-create a user-modified config.yaml
+        const configDir = path.join(tmp, '.pd');
+        fs.mkdirSync(configDir, { recursive: true });
+        const userConfig = '# user config\nversion: 1\n';
+        fs.writeFileSync(path.join(configDir, 'config.yaml'), userConfig, 'utf8');
+
+        const output = buildRuntimeInitOutput(tmp, true);
+        expect(output.config?.status).toBe('skipped');
+        expect(output.config?.warnings.some(w => w.includes('already exists'))).toBe(true);
+        // Content must be preserved
+        expect(fs.readFileSync(path.join(configDir, 'config.yaml'), 'utf8')).toBe(userConfig);
+      } finally { rmTmpDir(tmp); }
+    });
+  });
 });