@principles/pd-cli 1.73.0

package/src/commands/central-sync.ts

@@ -0,0 +1,44 @@
+/**
+ * pd central sync command implementation.
+ *
+ * Usage: pd central sync
+ *
+ * Triggers a sync cycle via CentralDatabase.syncAll() and reports
+ * per-workspace sync results with exit code 0 on success, non-zero on failure.
+ */
+
+async function loadCentralDatabase(): Promise<{ CentralDatabase: new () => {
+  syncAll(): Map<string, number>;
+  dispose(): void;
+} }> {
+  const importModule = Function('specifier', 'return import(specifier)') as (specifier: string) => Promise<{
+    CentralDatabase: new () => {
+      syncAll(): Map<string, number>;
+      dispose(): void;
+    };
+  }>;
+  return importModule('../../../openclaw-plugin/src/service/central-database.js');
+}
+
+export async function handleCentralSync(): Promise<void> {
+  try {
+    const { CentralDatabase } = await loadCentralDatabase();
+    const centralDb = new CentralDatabase();
+    const results = centralDb.syncAll();
+
+    const totalRecords = Array.from(results.values()).reduce((sum, count) => sum + count, 0);
+    const workspaceCount = results.size;
+
+    console.log(`Sync complete — ${totalRecords} records across ${workspaceCount} workspace(s).`);
+
+    for (const [workspaceName, count] of results.entries()) {
+      console.log(`  ${workspaceName}: ${count} records`);
+    }
+
+    centralDb.dispose();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: Sync failed — ${message}`);
+    process.exit(1);
+  }
+}

package/src/commands/console.ts

@@ -0,0 +1,121 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import { spawn } from 'child_process';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface ConsoleOptions {
+  workspace?: string;
+  port?: string;
+  noAuth?: boolean;
+  json?: boolean;
+}
+
+function getConsoleDir(): string | null {
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  if (!homeDir) return null;
+  const consoleDir = path.join(homeDir, '.openclaw', 'extensions', 'principles-disciple', 'console');
+  return fs.existsSync(consoleDir) ? consoleDir : null;
+}
+
+export async function handleConsole(opts: ConsoleOptions = {}): Promise<void> {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const consoleDir = getConsoleDir();
+  if (!consoleDir) {
+    const msg = 'pd-console is not installed. Run: npx create-principles-disciple to install.';
+    if (opts.json) {
+      console.log(JSON.stringify({ success: false, reason: msg, nextAction: 'npx create-principles-disciple' }));
+    } else {
+      console.error(msg);
+    }
+    process.exit(1);
+    return;
+  }
+
+  const serverEntry = path.join(consoleDir, 'dist', 'server.js');
+  if (!fs.existsSync(serverEntry)) {
+    const msg = `Console server entry not found at ${serverEntry}. Re-run installer.`;
+    if (opts.json) {
+      console.log(JSON.stringify({ success: false, reason: msg, nextAction: 'npx create-principles-disciple' }));
+    } else {
+      console.error(msg);
+    }
+    process.exit(1);
+    return;
+  }
+
+  const port = opts.port || '3100';
+  const host = '127.0.0.1';
+  const args = [serverEntry, '--workspace', workspaceDir, '--port', port, '--host', host];
+  if (opts.noAuth) args.push('--no-auth');
+
+  const child = spawn(process.execPath, args, {
+    stdio: opts.json ? 'pipe' : 'inherit',
+    env: { ...process.env },
+  });
+
+  let startupConfirmed = false;
+
+  child.on('error', (err) => {
+    if (opts.json) {
+      if (!startupConfirmed) {
+        console.log(JSON.stringify({
+          success: false,
+          reason: `Console spawn failed: ${err.message}`,
+          nextAction: 'Check Node.js installation and console server entry. Re-run: npx create-principles-disciple',
+        }));
+      }
+    } else {
+      console.error(`Console spawn failed: ${err.message}`);
+    }
+    process.exit(1);
+    return;
+  });
+
+  child.on('exit', (code) => {
+    if (code !== 0 && code !== null) {
+      if (opts.json) {
+        if (!startupConfirmed) {
+          console.log(JSON.stringify({
+            success: false,
+            reason: `Console exited with code ${code}`,
+            nextAction: 'Check console logs above. Re-run: npx create-principles-disciple',
+          }));
+        }
+      } else {
+        console.error(`Console exited with code ${code}`);
+      }
+      process.exit(typeof code === 'number' ? code : 1);
+      return;
+    }
+    process.exit(0);
+  });
+
+  setTimeout(() => {
+    if (child.exitCode === null) {
+      startupConfirmed = true;
+      if (opts.json) {
+        console.log(JSON.stringify({
+          success: true,
+          status: 'running',
+          url: `http://${host}:${port}`,
+          workspace: workspaceDir,
+          nextAction: `Open http://${host}:${port} in your browser`,
+        }));
+      } else {
+        console.log(`Starting pd-console on http://${host}:${port}`);
+        console.log(`Workspace: ${workspaceDir}`);
+        console.log('Press Ctrl+C to stop');
+      }
+    }
+  }, 2000);
+
+  const cleanup = () => {
+    try { child.kill('SIGTERM'); } catch { /* ignore */ }
+    process.exit(0);
+  };
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+}

package/src/commands/context.ts

@@ -0,0 +1,72 @@
+/**
+ * pd context build — Assemble diagnostician context payload for a task.
+ *
+ * Usage:
+ *   pd context build <taskId>
+ */
+import {
+  SqliteConnection,
+  SqliteTaskStore,
+  SqliteRunStore,
+  SqliteHistoryQuery,
+  SqliteContextAssembler,
+  SqliteTrajectoryLocator,
+  SqliteSourceTraceLocator,
+} from '@principles/core';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface ContextBuildOptions {
+  json?: boolean;
+  workspace?: string;
+}
+
+export async function handleContextBuild(taskId: string, opts: ContextBuildOptions): Promise<void> {
+  const workspaceDir = resolveWorkspaceDir(opts.workspace);
+  const connection = new SqliteConnection(workspaceDir);
+
+  try {
+    const taskStore = new SqliteTaskStore(connection);
+    const runStore = new SqliteRunStore(connection);
+    const historyQuery = new SqliteHistoryQuery(connection);
+    const trajectoryLocator = new SqliteTrajectoryLocator(connection);
+    const sourceTraceLocator = new SqliteSourceTraceLocator(taskStore, trajectoryLocator);
+    const assembler = new SqliteContextAssembler(taskStore, historyQuery, runStore, { sourceTraceLocator });
+
+    const payload = await assembler.assemble(taskId);
+
+    if (opts.json) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    console.log(`\nContext for ${taskId}:\n`);
+    console.log(`  contextId:      ${payload.contextId}`);
+    console.log(`  contextHash:    ${payload.contextHash.substring(0, 16)}...`);
+    console.log(`  workspaceDir:   ${payload.workspaceDir}`);
+    console.log(`  sourceRefs:     ${payload.sourceRefs.join(', ')}`);
+    console.log(`  entries:        ${payload.conversationWindow.length}`);
+
+    if (payload.ambiguityNotes && payload.ambiguityNotes.length > 0) {
+      console.log(`  ambiguityNotes:`);
+      for (const note of payload.ambiguityNotes) {
+        console.log(`    - ${note}`);
+      }
+    }
+
+    const target = payload.diagnosisTarget;
+    const targetFields = Object.entries(target).filter(([, v]) => v !== undefined);
+    if (targetFields.length > 0) {
+      console.log(`  diagnosisTarget:`);
+      for (const [key, value] of targetFields) {
+        console.log(`    ${key}: ${value}`);
+      }
+    }
+    console.log('');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  } finally {
+    connection.close();
+  }
+}

package/src/commands/demo-story-a.ts

@@ -0,0 +1,195 @@
+import * as path from 'path';
+import * as os from 'os';
+import * as fs from 'fs';
+import { runStoryADemo } from '../services/demo-story-a-runner.js';
+import type { MvpChannel } from '@principles/core/runtime-v2';
+
+interface DemoStoryAOptions {
+  workspace?: string;
+  json?: boolean;
+  channels?: string;
+}
+
+function formatStage(stage: { name: string; status: string; reason?: string; evidenceRef?: string }): string {
+  const icon = stage.status === 'passed' ? '✓' : stage.status === 'degraded' ? '⚠' : '✗';
+  let line = `  ${icon} ${stage.name}: ${stage.status}`;
+  if (stage.evidenceRef) line += ` (ref: ${stage.evidenceRef})`;
+  if (stage.reason) line += `\n    reason: ${stage.reason}`;
+  return line;
+}
+
+function formatChannelOutcome(ch: { channel: string; status: string; failureReason?: string; evidenceSource: string }): string {
+  const icon = ch.status === 'passed' ? '✓' : ch.status === 'degraded' ? '⚠' : '✗';
+  const lines: string[] = [];
+  lines.push(`  ${icon} ${ch.channel}: ${ch.status}`);
+  lines.push(`    source: ${ch.evidenceSource}`);
+  if (ch.failureReason) {
+    lines.push(`    reason: ${ch.failureReason}`);
+  }
+  return lines.join('\n');
+}
+
+function formatTextOutput(result: Record<string, unknown>): string {
+  const lines: string[] = [];
+  const status = result.status as string;
+  const icon = status === 'passed' ? '✓' : status === 'degraded' ? '⚠' : '✗';
+
+  lines.push('PD Story A\' Demo (PRI-246)');
+  lines.push(`generatedAt: ${result.generatedAt as string}`);
+  lines.push(`OVERALL: ${icon} ${status.toUpperCase()}`);
+  lines.push('');
+
+  if (result.inputValidationFailure) {
+    const ivf = result.inputValidationFailure as Record<string, unknown>;
+    lines.push('Input Validation Failure:');
+    lines.push(`  reason: ${ivf.reason as string}`);
+    lines.push(`  message: ${ivf.message as string}`);
+    lines.push(`  nextAction: ${ivf.nextAction as string}`);
+    lines.push('');
+  }
+
+  lines.push('Stages:');
+  for (const stage of result.stages as Record<string, unknown>[]) {
+    lines.push(formatStage(stage as { name: string; status: string; reason?: string; evidenceRef?: string }));
+  }
+
+  lines.push('');
+  lines.push('Channel Outcomes:');
+  for (const ch of result.channelOutcomes as Record<string, unknown>[]) {
+    lines.push(formatChannelOutcome(ch as { channel: string; status: string; failureReason?: string; evidenceSource: string }));
+  }
+
+  lines.push('');
+  lines.push(`Runtime V2 Exclusive: ${result.isRuntimeV2Exclusive ? 'Yes' : 'No'}`);
+
+  lines.push('');
+  lines.push('--- Narrative ---');
+  lines.push(result.narrative as string);
+
+  return lines.join('\n');
+}
+
+export function cleanupTempWorkspace(workspaceDir: string, rmSyncImpl: (dir: string, opts: { recursive: boolean; force: boolean }) => void = fs.rmSync.bind(fs)): void {
+  try {
+    rmSyncImpl(workspaceDir, { recursive: true, force: true });
+  } catch (cleanupErr) {
+    const cleanupMsg = cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr);
+    console.error(`[pd-cli] cleanup warning: failed to remove temp workspace ${workspaceDir}: ${cleanupMsg}`);
+  }
+}
+
+interface ParseChannelResult {
+  channels: MvpChannel[] | undefined;
+  unknowns: string[];
+}
+
+function parseChannelList(raw: string | undefined): ParseChannelResult {
+  if (!raw || raw.trim().length === 0) {
+    // Empty string means user explicitly passed --channels "" → treat as empty request
+    if (raw !== undefined) return { channels: [], unknowns: [] };
+    return { channels: undefined, unknowns: [] };
+  }
+  const parts = raw.split(',').map(p => p.trim()).filter(p => p.length > 0);
+  if (parts.length === 0) return { channels: [], unknowns: [] };
+  const valid: MvpChannel[] = [];
+  const unknowns: string[] = [];
+  const mvpSet = new Set<string>(['prompt', 'code_tool_hook', 'defer_archive']);
+  for (const part of parts) {
+    if (mvpSet.has(part)) {
+      valid.push(part as MvpChannel);
+    } else {
+      unknowns.push(part);
+    }
+  }
+  return { channels: valid.length > 0 ? valid : undefined, unknowns };
+}
+
+export async function handleDemoStoryA(opts: DemoStoryAOptions): Promise<void> {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : fs.mkdtempSync(path.join(os.tmpdir(), 'pd-story-a-'));
+
+  const parsed = parseChannelList(opts.channels);
+
+  // Fail loud on empty channels before workspace creation (ERR-029)
+  if (parsed.channels?.length === 0) {
+    const errorResult = {
+      status: 'failed' as const,
+      generatedAt: new Date().toISOString(),
+      narrative: 'No channels specified.',
+      storyDescription: 'Input validation failed',
+      stages: [],
+      channelOutcomes: [],
+      isRuntimeV2Exclusive: true,
+      inputValidationFailure: {
+        reason: 'empty_channels',
+        message: 'No channels specified. At least one MVP channel required.',
+        nextAction: 'Provide channels: prompt, code_tool_hook, defer_archive',
+      },
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(errorResult, null, 2));
+    } else {
+      console.error('Error: No channels specified. At least one MVP channel required.');
+      console.error('Valid channels: prompt, code_tool_hook, defer_archive');
+    }
+    process.exitCode = 1;
+    if (!opts.workspace) {
+      cleanupTempWorkspace(workspaceDir);
+    }
+    return;
+  }
+
+  // Fail loud on unknown channels (ERR-029)
+  if (parsed.unknowns.length > 0) {
+    const errorResult = {
+      status: 'failed' as const,
+      generatedAt: new Date().toISOString(),
+      narrative: `Unknown channels: ${parsed.unknowns.join(', ')}`,
+      storyDescription: 'Input validation failed',
+      stages: [],
+      channelOutcomes: [],
+      isRuntimeV2Exclusive: true,
+      inputValidationFailure: {
+        reason: 'unknown_channels',
+        message: `Unknown channels: ${parsed.unknowns.join(', ')}. Valid: prompt, code_tool_hook, defer_archive`,
+        nextAction: 'Use only valid MVP channels: prompt, code_tool_hook, defer_archive',
+        unknownChannels: parsed.unknowns,
+      },
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(errorResult, null, 2));
+    } else {
+      console.error(`Error: Unknown channels: ${parsed.unknowns.join(', ')}`);
+      console.error('Valid channels: prompt, code_tool_hook, defer_archive');
+    }
+    process.exitCode = 1;
+    if (!opts.workspace) {
+      cleanupTempWorkspace(workspaceDir);
+    }
+    return;
+  }
+
+  try {
+    const result = await runStoryADemo({
+      channels: parsed.channels,
+      workspaceDir,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatTextOutput(result as unknown as Record<string, unknown>));
+    }
+
+    if (result.status !== 'passed') {
+      console.error('');
+      console.error(`FAIL: status=${result.status}`);
+      process.exitCode = 1;
+    }
+  } finally {
+    if (!opts.workspace) {
+      cleanupTempWorkspace(workspaceDir);
+    }
+  }
+}