@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/demo-recording.mjs

@@ -0,0 +1,142 @@
+/**
+ * lib/demo-recording.mjs — load and validate Playwright recording manifests.
+ *
+ * Search order: .cx/demos/recordings/ then templates/demos/recordings/. Legacy
+ * dashboardDemo scripts synthesize a recording manifest when no JSON exists.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadDemoScript } from './demo-script.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..');
+
+export function demoRecordingSearchDirs({ cwd = process.cwd(), repoRoot = REPO_ROOT } = {}) {
+  return [
+    path.join(cwd, '.cx', 'demos', 'recordings'),
+    path.join(repoRoot, 'templates', 'demos', 'recordings'),
+  ];
+}
+
+export function resolveDemoRecordingPath(name, { cwd = process.cwd(), repoRoot = REPO_ROOT } = {}) {
+  for (const dir of demoRecordingSearchDirs({ cwd, repoRoot })) {
+    const candidate = path.join(dir, `${name}.json`);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+export function listDemoRecordings({ cwd = process.cwd(), repoRoot = REPO_ROOT } = {}) {
+  const seen = new Set();
+  const out = [];
+  for (const dir of demoRecordingSearchDirs({ cwd, repoRoot })) {
+    if (!fs.existsSync(dir)) continue;
+    for (const file of fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort()) {
+      const name = path.basename(file, '.json');
+      if (seen.has(name)) continue;
+      seen.add(name);
+      out.push(name);
+    }
+  }
+  return out.sort();
+}
+
+export function normalizeArtifactReveal(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const file = raw.file || raw.path;
+  if (!file) return null;
+  return {
+    mode: raw.mode || 'constructPreview',
+    staticDir: raw.staticDir || '.',
+    file,
+    scroll: raw.scroll !== false,
+  };
+}
+
+function validateRecording(raw, name) {
+  const errors = [];
+  if (!raw || typeof raw !== 'object') errors.push('recording must be an object');
+  if (raw.engine && raw.engine !== 'playwright') errors.push(`unsupported engine: ${raw.engine}`);
+  if (!raw.spec) errors.push('spec is required');
+  if (!raw.skipWebServer && !raw.webServer && !raw.baseUrl) {
+    errors.push('baseUrl or webServer required when skipWebServer is false');
+  }
+  return {
+    ok: errors.length === 0,
+    errors,
+    recording: errors.length === 0 ? normalizeRecording(raw, name) : null,
+  };
+}
+
+export function normalizeRecording(raw, name) {
+  return {
+    name: raw.name || name,
+    title: raw.title || name,
+    engine: raw.engine || 'playwright',
+    workspace: raw.workspace || '.',
+    spec: raw.spec,
+    baseUrl: raw.baseUrl || raw.webServer?.url || null,
+    webServer: raw.webServer || null,
+    skipWebServer: Boolean(raw.skipWebServer),
+    project: raw.project || null,
+    playwrightConfig: raw.playwrightConfig || null,
+    artifactReveal: normalizeArtifactReveal(raw.artifactReveal),
+    output: raw.output || { format: 'mp4', path: `.cx/demos/${name}.mp4` },
+    timeout: raw.timeout || null,
+    sourcePath: raw.sourcePath || null,
+    _legacy: Boolean(raw._legacy),
+  };
+}
+
+export function recordingFromDemoScript(name, { cwd = process.cwd(), repoRoot = REPO_ROOT } = {}) {
+  const script = loadDemoScript(name, { cwd, repoRoot });
+  if (!script?.dashboardDemo) return null;
+  const demoName = script.dashboardDemo;
+  const repo = repoRoot || REPO_ROOT;
+  return normalizeRecording({
+    name: script.name || name,
+    title: script.title || name,
+    engine: 'playwright',
+    workspace: 'apps/dashboard',
+    spec: `apps/dashboard/e2e/demo/${demoName}.spec.ts`,
+    baseUrl: 'http://127.0.0.1:4242',
+    project: 'demo-recording',
+    artifactReveal: script.artifactReveal,
+    output: { format: 'mp4', path: `.cx/demos/dashboard/${demoName}.mp4` },
+    _legacy: true,
+  }, name);
+}
+
+export function loadDemoRecording(name, { cwd = process.cwd(), repoRoot = REPO_ROOT } = {}) {
+  const filePath = resolveDemoRecordingPath(name, { cwd, repoRoot });
+  if (filePath) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      const validated = validateRecording(raw, name);
+      if (!validated.ok) return null;
+      return { ...validated.recording, sourcePath: filePath };
+    } catch {
+      return null;
+    }
+  }
+  return recordingFromDemoScript(name, { cwd, repoRoot });
+}
+
+export function loadDemoRecordingValidated(name, opts = {}) {
+  const filePath = resolveDemoRecordingPath(name, opts);
+  if (!filePath) {
+    const legacy = recordingFromDemoScript(name, opts);
+    if (legacy) return { ok: true, recording: legacy };
+    return { ok: false, errors: [`recording not found: ${name}`] };
+  }
+  try {
+    const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    const validated = validateRecording(raw, name);
+    if (!validated.ok) return { ok: false, errors: validated.errors, sourcePath: filePath };
+    return { ok: true, recording: { ...validated.recording, sourcePath: filePath } };
+  } catch (err) {
+    return { ok: false, errors: [err.message || 'invalid JSON'], sourcePath: filePath };
+  }
+}

package/lib/demo-script.mjs

@@ -0,0 +1,114 @@
+/**
+ * lib/demo-script.mjs — load committed demo scripts for chat-guided demos.
+ *
+ * Scripts live in templates/demos/scripts/ (shipped) and .cx/demos/scripts/
+ * (project overrides). Each script defines steps, system overlay, and optional
+ * tape/dashboard fallbacks when chat is unavailable.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..');
+
+export function demoScriptSearchDirs({ cwd = process.cwd(), repoRoot = REPO_ROOT } = {}) {
+  return [
+    path.join(cwd, '.cx', 'demos', 'scripts'),
+    path.join(repoRoot, 'templates', 'demos', 'scripts'),
+  ];
+}
+
+export function listDemoScripts({ cwd = process.cwd(), repoRoot = REPO_ROOT } = {}) {
+  const seen = new Set();
+  const out = [];
+  for (const dir of demoScriptSearchDirs({ cwd, repoRoot })) {
+    if (!fs.existsSync(dir)) continue;
+    for (const file of fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort()) {
+      const name = path.basename(file, '.json');
+      if (seen.has(name)) continue;
+      seen.add(name);
+      out.push(name);
+    }
+  }
+  return out.sort();
+}
+
+export function resolveDemoScriptPath(name, { cwd = process.cwd(), repoRoot = REPO_ROOT } = {}) {
+  for (const dir of demoScriptSearchDirs({ cwd, repoRoot })) {
+    const candidate = path.join(dir, `${name}.json`);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+export function loadDemoScript(name, { cwd = process.cwd(), repoRoot = REPO_ROOT } = {}) {
+  const filePath = resolveDemoScriptPath(name, { cwd, repoRoot });
+  if (!filePath) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    if (!raw || typeof raw !== 'object') return null;
+    const steps = Array.isArray(raw.steps) ? raw.steps.filter((s) => s && (s.prompt || s.command)) : [];
+    const artifactReveal = raw.artifactReveal && typeof raw.artifactReveal === 'object'
+      ? {
+          mode: raw.artifactReveal.mode || 'constructPreview',
+          staticDir: raw.artifactReveal.staticDir || '.',
+          file: raw.artifactReveal.file || raw.artifactReveal.path || null,
+          scroll: raw.artifactReveal.scroll !== false,
+        }
+      : null;
+
+    return {
+      name: raw.name || name,
+      title: raw.title || name,
+      summary: raw.summary || '',
+      systemOverlay: raw.systemOverlay || '',
+      tape: raw.tape || name,
+      dashboardDemo: raw.dashboardDemo || null,
+      recording: raw.recording || null,
+      engine: raw.engine || null,
+      artifactReveal,
+      fallbackSurface: raw.fallbackSurface || 'tape',
+      fixtures: raw.fixtures || {},
+      steps,
+      sourcePath: filePath,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function formatDemoWelcome(script) {
+  const lines = [
+    `Demo: ${script.title}`,
+    script.summary,
+    '',
+    'Steps (use /demo next for the next prompt, /demo steps to replay):',
+  ];
+  script.steps.forEach((step, i) => {
+    lines.push(`  ${i + 1}. ${step.title || step.prompt?.slice(0, 60) || 'step'}`);
+  });
+  lines.push('', 'Type /demo next to see the first prompt, or describe what you want in your own words.');
+  return lines.filter(Boolean).join('\n');
+}
+
+export function createDemoGuide(script) {
+  let index = 0;
+  return {
+    script,
+    currentIndex: () => index,
+    steps: () => script.steps,
+    reset() { index = 0; },
+    next() {
+      if (index >= script.steps.length) return null;
+      const step = script.steps[index];
+      index += 1;
+      return { index, ...step };
+    },
+    peek() {
+      if (index >= script.steps.length) return null;
+      return { index: index + 1, ...script.steps[index] };
+    },
+  };
+}

package/lib/demo-surface.mjs

@@ -0,0 +1,249 @@
+/**
+ * lib/demo-surface.mjs — chat-first demo execution with surface targeting and fallbacks.
+ *
+ * Default surface is construct chat (Ink on capable TTY, linear otherwise). Users
+ * may target web, tape (VHS), or dashboard explicitly. When chat is unavailable
+ * (no provider, non-interactive), the runner degrades through the script's
+ * fallback chain without failing the command.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { hasAnySecret } from './providers/secret-resolver.mjs';
+import { loadConstructEnv } from './env-config.mjs';
+import { loadDemoScript, formatDemoWelcome, createDemoGuide } from './demo-script.mjs';
+import { loadDemoRecording } from './demo-recording.mjs';
+import { recordDashboardDemo } from './dashboard-demo.mjs';
+import { recordPlaywrightDemo } from './playwright-demo.mjs';
+
+export const DEMO_SURFACES = ['chat', 'web', 'tape', 'dashboard', 'playwright'];
+
+const PROVIDER_KEYS = ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'OPENROUTER_API_KEY', 'GITHUB_TOKEN'];
+
+function which(bin) {
+  const result = spawnSync(process.platform === 'win32' ? 'where' : 'which', [bin], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return result.stdout.trim().split('\n')[0] || null;
+}
+
+export function detectChatDemoReady({ env = process.env, cwd = process.cwd() } = {}) {
+  const effective = loadConstructEnv({ rootDir: cwd, env, warn: false });
+  if (hasAnySecret(PROVIDER_KEYS, { env: effective, cwd })) {
+    return { ready: true, reason: 'provider configured' };
+  }
+  if (which('ollama')) {
+    return { ready: true, reason: 'local Ollama detected' };
+  }
+  return {
+    ready: false,
+    reason: 'No LLM provider configured. Set a key in ~/.construct/config.env, run `construct creds login copilot`, or start Ollama.',
+  };
+}
+
+export function buildDemoAttemptChain(requestedSurface, { script, recording = null, interactive = true } = {}) {
+  const chain = [];
+  const push = (surface) => { if (!chain.includes(surface)) chain.push(surface); };
+
+  if (requestedSurface === 'dashboard') {
+    push('dashboard');
+    push('playwright');
+    push('chat');
+    push('web');
+  } else if (requestedSurface === 'playwright') {
+    push('playwright');
+    push('dashboard');
+  } else if (requestedSurface === 'web') {
+    push('web');
+    push('chat');
+  } else if (requestedSurface === 'tape') {
+    push('tape');
+    return chain;
+  } else {
+    push('chat');
+    push('web');
+  }
+
+  if (script?.dashboardDemo && requestedSurface !== 'tape') push('dashboard');
+  if (recording?.engine === 'playwright' && requestedSurface !== 'tape') push('playwright');
+  push('tape');
+
+  if (!interactive && recording?.engine === 'playwright') {
+    const filtered = chain.filter((s) => s !== 'chat' && s !== 'web');
+    return filtered.length ? filtered : ['tape'];
+  }
+  if (!interactive && chain[0] === 'chat') {
+    const filtered = chain.filter((s) => s !== 'chat' && s !== 'web');
+    return filtered.length ? filtered : ['tape'];
+  }
+  return chain;
+}
+
+function buildChatArgs(name, opts) {
+  const args = [`--demo=${name}`];
+  if (opts.web) args.push('--web');
+  if (opts.plain) args.push('--plain');
+  if (opts.accessible) args.push('--accessible');
+  if (opts.free) args.push('--free');
+  if (opts.model) args.push(`--model=${opts.model}`);
+  return args;
+}
+
+async function tryChatDemo(name, opts, { web = false } = {}) {
+  const readiness = detectChatDemoReady({ env: opts.env, cwd: opts.cwd });
+  if (!readiness.ready) {
+    return { ok: false, surface: web ? 'web' : 'chat', soft: true, message: readiness.reason };
+  }
+
+  const script = loadDemoScript(name, opts);
+  if (!script) {
+    return { ok: false, surface: web ? 'web' : 'chat', soft: true, message: `No demo script for ${name}` };
+  }
+
+  const chatArgs = buildChatArgs(name, { ...opts, web });
+  const { runChat } = await import('./chat/cli.mjs');
+  const code = await runChat(chatArgs, {
+    cwd: opts.cwd,
+    env: { ...opts.env, CONSTRUCT_DEMO: name },
+    input: opts.input || process.stdin,
+    output: opts.output || process.stdout,
+    errorOutput: opts.errorOutput || process.stderr,
+  });
+
+  if (code === 0) {
+    return { ok: true, surface: web ? 'web' : 'chat', message: `Demo ${name} finished in chat` };
+  }
+  return { ok: false, surface: web ? 'web' : 'chat', soft: true, message: `Chat exited ${code}` };
+}
+
+async function tryTapeDemo(name, opts, { sourceOnly = false } = {}) {
+  const { runDemoRecord, resolveTapeSource, listProjectTapes } = await import('./demo.mjs');
+  const tapeName = loadDemoScript(name, opts)?.tape || name;
+  const hasTape = resolveTapeSource(tapeName, { cwd: opts.cwd })
+    || listProjectTapes(opts.cwd).includes(tapeName);
+  if (!hasTape) {
+    return { ok: false, surface: 'tape', soft: true, message: `No tape for ${tapeName}` };
+  }
+  const result = runDemoRecord(tapeName, {
+    cwd: opts.cwd,
+    format: opts.format || 'mp4',
+    out: opts.out,
+    sourceOnly: sourceOnly || opts.sourceOnly,
+    required: opts.required,
+  });
+  if (result.ok) {
+    return {
+      ok: true,
+      surface: 'tape',
+      ...result,
+      message: result.artifactPath
+        ? `Recorded tape demo to ${result.artifactPath}`
+        : `Tape source: ${result.tapePath}`,
+    };
+  }
+  return { ok: false, surface: 'tape', soft: !opts.required, ...result };
+}
+
+function tryPlaywrightDemo(name, opts) {
+  const recording = loadDemoRecording(name, opts);
+  if (!recording || recording.engine !== 'playwright') {
+    return { ok: false, surface: 'playwright', soft: true, message: 'No Playwright recording configured' };
+  }
+  const result = recordPlaywrightDemo(recording, {
+    cwd: opts.cwd,
+    repoRoot: opts.repoRoot,
+    outputPath: opts.out ? opts.out : null,
+    format: opts.format || 'mp4',
+  });
+  if (result.ok) return { ok: true, surface: 'playwright', ...result };
+  return { ok: false, surface: 'playwright', soft: true, ...result };
+}
+
+function tryDashboardDemo(name, opts) {
+  const script = loadDemoScript(name, opts);
+  const demoName = script?.dashboardDemo;
+  if (!demoName) {
+    return { ok: false, surface: 'dashboard', soft: true, message: 'No dashboard demo configured' };
+  }
+  const result = recordDashboardDemo(demoName, { cwd: opts.cwd, repoRoot: opts.repoRoot });
+  if (result.ok) return { ok: true, surface: 'dashboard', ...result };
+  return { ok: false, surface: 'dashboard', soft: true, ...result };
+}
+
+function printScriptFallback(name, opts, notices = []) {
+  const script = loadDemoScript(name, opts);
+  if (!script) {
+    return {
+      ok: false,
+      surface: 'script',
+      message: `Unknown demo: ${name}. Run \`construct demo list\` or add templates/demos/scripts/${name}.json`,
+    };
+  }
+  const out = opts.output || process.stdout;
+  for (const line of notices) out.write(`${line}\n`);
+  out.write(`\n${formatDemoWelcome(script)}\n\n`);
+  script.steps.forEach((step, i) => {
+    out.write(`${i + 1}. ${step.title || 'Step'}\n`);
+    if (step.prompt) out.write(`   prompt: ${step.prompt}\n`);
+    if (step.command) out.write(`   command: ${step.command}\n`);
+    out.write('\n');
+  });
+  return { ok: true, surface: 'script', message: 'Printed demo script (all surfaces unavailable)' };
+}
+
+export async function runDemoGuided(name, {
+  cwd = process.cwd(),
+  repoRoot,
+  surface = 'chat',
+  format = 'mp4',
+  out = null,
+  sourceOnly = false,
+  required = false,
+  model = null,
+  plain = false,
+  accessible = false,
+  web = false,
+  free = false,
+  env = process.env,
+  input,
+  output,
+  errorOutput,
+} = {}) {
+  const opts = {
+    cwd, repoRoot, format, out, sourceOnly, required, model, plain, accessible, web, free, env, input, output, errorOutput,
+  };
+
+  const script = loadDemoScript(name, opts);
+  const recording = loadDemoRecording(name, opts);
+  const requested = web ? 'web' : (DEMO_SURFACES.includes(surface) ? surface : 'chat');
+  const interactive = Boolean((input || process.stdin).isTTY && (output || process.stdout).isTTY);
+  const chain = buildDemoAttemptChain(requested, { script, recording, interactive });
+  const notices = [];
+
+  for (const attempt of chain) {
+    let result;
+    if (attempt === 'chat') result = await tryChatDemo(name, opts, { web: false });
+    else if (attempt === 'web') result = await tryChatDemo(name, opts, { web: true });
+    else if (attempt === 'tape') result = await tryTapeDemo(name, opts);
+    else if (attempt === 'playwright') result = tryPlaywrightDemo(name, opts);
+    else if (attempt === 'dashboard') result = tryDashboardDemo(name, opts);
+    else continue;
+
+    if (result.ok) {
+      return { ...result, notices, demoGuide: script ? createDemoGuide(script) : null };
+    }
+    if (result.message) notices.push(`${attempt} unavailable: ${result.message}`);
+    if (!result.soft && !required) break;
+  }
+
+  return printScriptFallback(name, opts, notices);
+}
+
+export function resolveDemoGuideForChat(name, { cwd = process.cwd(), repoRoot } = {}) {
+  const script = loadDemoScript(name, { cwd, repoRoot });
+  if (!script) return null;
+  return {
+    script,
+    guide: createDemoGuide(script),
+    welcome: formatDemoWelcome(script),
+    systemOverlay: script.systemOverlay,
+  };
+}