@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/demo-project.mjs

@@ -0,0 +1,188 @@
+/**
+ * lib/demo-project.mjs — project-level demo plug-in scaffold (.cx/demos).
+ *
+ * `construct demo init --from-project` calls scaffoldProjectDemo to seed a
+ * project-defined demo from real project signals (no fabricated scenario
+ * content): a manifest (<name>.project.json) plus the demo script and terminal
+ * tape stub it ships with, all under .cx/demos/. The manifest is
+ * validated against schemas/project-demo.schema.json by a hand-rolled checker
+ * (Construct stays dependency-free at startup — no ajv).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readContextState } from './context-state.mjs';
+
+const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export const PROJECT_DEMO_SCHEMA = 'construct/project-demo/1';
+
+export function projectDemosDir(cwd) {
+  return join(cwd, '.cx', 'demos');
+}
+
+export function projectDemoManifestPath(cwd, name) {
+  return join(projectDemosDir(cwd), `${name}.project.json`);
+}
+
+export function projectDemoScriptRel(name) {
+  return `.cx/demos/scripts/${name}.json`;
+}
+
+export function projectDemoTapeRel(name) {
+  return `.cx/demos/tapes/${name}.tape`;
+}
+
+// The project name is read, never invented: prefer the durable context state,
+// then package.json, and only then the directory basename as a last resort.
+
+export function resolveProjectName(cwd) {
+  const state = readContextState(cwd);
+  if (state?.projectName && typeof state.projectName === 'string') return state.projectName;
+
+  const pkgPath = join(cwd, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      if (pkg?.name && typeof pkg.name === 'string') return pkg.name;
+    } catch { /* unreadable package.json falls through to the directory name */ }
+  }
+
+  return basename(cwd) || 'project';
+}
+
+function projectScriptSource(name, projectName) {
+  return {
+    name,
+    title: `${projectName} demo — ${name}`,
+    summary: `Project demo for ${projectName}: walk Construct's read-only status and capability surfaces.`,
+    systemOverlay: `Demo mode for the ${projectName} project. Run the exact construct CLI commands from each step. Every command here is read-only and secret-free; report exactly what each command emits and do not invent output.`,
+    tape: name,
+    fallbackSurface: 'tape',
+    steps: [
+      {
+        title: 'Status — system health',
+        prompt: `Run construct status to show ${projectName}'s system health and configured credentials.`,
+        command: 'node bin/construct status',
+      },
+      {
+        title: 'Capability — what this install can do',
+        prompt: 'Run construct capability describe --json to emit the read-only capability contract for this install.',
+        command: 'node bin/construct capability describe --json',
+      },
+    ],
+  };
+}
+
+function projectTapeSource(name, projectName) {
+  return `Require node
+Require vhs
+# construct demo: ${name} — ${projectName} project plug-in
+Output ${projectDemoTapeRel(name)}
+Set FontSize 18
+Set Width 1100
+Set Height 600
+Set TypingSpeed 60ms
+
+Type "node bin/construct status"
+Sleep 500ms
+Enter
+Sleep 2s
+
+Type "node bin/construct capability describe --json"
+Sleep 500ms
+Enter
+Sleep 2s
+`;
+}
+
+export function buildProjectDemoManifest(name, { cwd, projectName, now = () => new Date() } = {}) {
+  const resolvedProject = projectName || resolveProjectName(cwd);
+  return {
+    $schema: '../../schemas/project-demo.schema.json',
+    schema: PROJECT_DEMO_SCHEMA,
+    name,
+    title: `${resolvedProject} demo — ${name}`,
+    summary: `Project-defined Construct demo for ${resolvedProject}.`,
+    project: resolvedProject,
+    script: projectDemoScriptRel(name),
+    tape: projectDemoTapeRel(name),
+    fallbackSurface: 'tape',
+    createdAt: now().toISOString(),
+  };
+}
+
+// A hand-rolled validator against schemas/project-demo.schema.json. Construct
+// stays dependency-free at startup, so this mirrors the schema's required
+// fields, const, and patterns rather than loading ajv.
+
+export function validateProjectDemoManifest(manifest) {
+  const errors = [];
+  if (!manifest || typeof manifest !== 'object') return { valid: false, errors: ['manifest is not an object'] };
+
+  if (manifest.schema !== PROJECT_DEMO_SCHEMA) errors.push(`schema must equal ${PROJECT_DEMO_SCHEMA}`);
+  if (typeof manifest.name !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(manifest.name)) {
+    errors.push('name required, lowercase slug ([a-z0-9][a-z0-9-]*)');
+  }
+  if (typeof manifest.title !== 'string' || !manifest.title) errors.push('title required');
+  if (typeof manifest.project !== 'string' || !manifest.project) errors.push('project required');
+  if (typeof manifest.script !== 'string' || !/^\.cx\/demos\/scripts\/.+\.json$/.test(manifest.script)) {
+    errors.push('script must be a .cx/demos/scripts/*.json path');
+  }
+  if (manifest.fallbackSurface && !['tape', 'playwright'].includes(manifest.fallbackSurface)) {
+    errors.push('fallbackSurface must be tape or playwright');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function loadProjectDemoManifest(name, { cwd } = {}) {
+  const manifestPath = projectDemoManifestPath(cwd, name);
+  if (!existsSync(manifestPath)) return { ok: false, errors: [`project demo not found: ${name}`], manifestPath };
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const validated = validateProjectDemoManifest(manifest);
+    if (!validated.valid) return { ok: false, errors: validated.errors, manifestPath };
+    return { ok: true, manifest, manifestPath };
+  } catch (err) {
+    return { ok: false, errors: [err.message || 'invalid JSON'], manifestPath };
+  }
+}
+
+export function scaffoldProjectDemo(name, { cwd, projectName, repoRoot = REPO_ROOT, now = () => new Date() } = {}) {
+  if (!name) return { ok: false, message: 'A demo name is required: construct demo init <name> --from-project' };
+
+  const manifestPath = projectDemoManifestPath(cwd, name);
+  if (existsSync(manifestPath)) return { ok: false, message: `Project demo already exists: ${manifestPath}` };
+
+  const resolvedProject = projectName || resolveProjectName(cwd);
+  const demosDir = projectDemosDir(cwd);
+  const scriptsDir = join(demosDir, 'scripts');
+  const tapesDir = join(demosDir, 'tapes');
+  mkdirSync(scriptsDir, { recursive: true });
+  mkdirSync(tapesDir, { recursive: true });
+
+  const scriptPath = join(cwd, projectDemoScriptRel(name));
+  const tapePath = join(cwd, projectDemoTapeRel(name));
+
+  const script = projectScriptSource(name, resolvedProject);
+  writeFileSync(scriptPath, `${JSON.stringify(script, null, 2)}\n`, 'utf8');
+  writeFileSync(tapePath, projectTapeSource(name, resolvedProject), 'utf8');
+
+  const manifest = buildProjectDemoManifest(name, { cwd, projectName: resolvedProject, now });
+  const validated = validateProjectDemoManifest(manifest);
+  if (!validated.valid) {
+    return { ok: false, message: `Scaffolded manifest failed validation: ${validated.errors.join('; ')}` };
+  }
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+
+  return {
+    ok: true,
+    manifestPath,
+    scriptPath,
+    tapePath,
+    project: resolvedProject,
+    message: `Scaffolded project demo ${name} for ${resolvedProject}:\n  ${manifestPath}\n  ${scriptPath}\n  ${tapePath}`,
+  };
+}

package/lib/demo-recording.mjs

@@ -1,14 +1,12 @@
 /**
  * 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.
+ * Search order: .cx/demos/recordings/ then templates/demos/recordings/.
  */
 
 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, '..');
@@ -90,45 +88,22 @@ export function normalizeRecording(raw, name) {
   };
 }
 
-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;
-    }
+  if (!filePath) return null;
+  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 {

package/lib/demo-script.mjs

@@ -1,9 +1,9 @@
 /**
- * lib/demo-script.mjs — load committed demo scripts for chat-guided demos.
+ * lib/demo-script.mjs — load committed demo scripts.
  *
  * 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.
+ * recording fallbacks.
  */
 
 import fs from 'node:fs';

package/lib/demo-surface.mjs

@@ -1,119 +1,31 @@
 /**
- * lib/demo-surface.mjs — chat-first demo execution with surface targeting and fallbacks.
+ * lib/demo-surface.mjs — demo execution with recording surfaces 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.
+ * Default surface is VHS tape recording. Users may target Playwright explicitly.
+ * When a recorder is unavailable, the runner prints the demo script steps.
  */
 
-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 const DEMO_SURFACES = ['tape', 'playwright'];
 
 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') {
+  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');
+    push('tape');
   }
 
-  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;
@@ -157,17 +69,6 @@ function tryPlaywrightDemo(name, opts) {
   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) {
@@ -192,39 +93,31 @@ function printScriptFallback(name, opts, notices = []) {
 export async function runDemoGuided(name, {
   cwd = process.cwd(),
   repoRoot,
-  surface = 'chat',
+  surface = 'tape',
   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 errOut = errorOutput || process.stderr;
+
   const opts = {
-    cwd, repoRoot, format, out, sourceOnly, required, model, plain, accessible, web, free, env, input, output, errorOutput,
+    cwd, repoRoot, format, out, sourceOnly, required, output, errorOutput: errOut,
   };
 
   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 requested = DEMO_SURFACES.includes(surface) ? surface : 'tape';
+  const interactive = Boolean((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);
+    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) {
@@ -236,14 +129,3 @@ export async function runDemoGuided(name, {
 
   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,
-  };
-}

package/lib/demo-tour-renderer.mjs

@@ -0,0 +1,92 @@
+/**
+ * lib/demo-tour-renderer.mjs — linear, screen-reader-friendly demo tour renderer.
+ *
+ * Renders a loaded demo script (lib/demo-script.mjs) as a numbered, top-to-bottom
+ * walkthrough with no Ink/interactive widgets, so `construct demo tour --accessible`
+ * stays WCAG-plain: color is opt-in via the caller's palette and off under
+ * NO_COLOR / non-TTY, prose wraps at a readable width, and every step is announced
+ * as "Step N of M". Headless runs pass { skipInput: true } to auto-advance without
+ * touching stdin; an interactive run without that flag pauses for Enter between
+ * steps. This renderer stays independent of host UI code — the tour is built on the demo
+ * surface only.
+ */
+
+import { resolveColors, termWidth, wrapText } from './term-format.mjs';
+
+function writeWrapped(output, text, width) {
+  output.write(`${wrapText(String(text), width)}\n`);
+}
+
+function renderHeader(output, script, colors, width, total) {
+  output.write(`${colors.bold}Demo tour: ${script.title}${colors.reset}\n`);
+  if (script.summary) writeWrapped(output, `${colors.dim}${script.summary}${colors.reset}`, width);
+  output.write(`\n${colors.dim}${total} step${total === 1 ? '' : 's'}. Each step shows the prompt to ask and the command it runs.${colors.reset}\n`);
+}
+
+function renderStep(output, step, position, total, colors, width) {
+  const title = step.title || step.prompt?.slice(0, 60) || `Step ${position}`;
+  output.write(`\n${colors.bold}Step ${position} of ${total}: ${title}${colors.reset}\n`);
+  if (step.prompt) {
+    output.write(`${colors.dim}Prompt:${colors.reset}\n`);
+    writeWrapped(output, `  ${step.prompt}`, width);
+  }
+  if (step.command) {
+    output.write(`${colors.dim}Command:${colors.reset}\n`);
+    output.write(`  ${step.command}\n`);
+  }
+}
+
+// Pause for Enter only when a real interactive TTY is driving and the caller did
+// not request auto-advance. A single readable() line keeps the wait keyboard-only
+// and free of cursor positioning so screen readers track it as plain output.
+
+function waitForEnter(input, output, colors) {
+  return new Promise((resolve) => {
+    output.write(`${colors.dim}Press Enter for the next step…${colors.reset}`);
+    const onData = () => {
+      input.removeListener('data', onData);
+      input.pause?.();
+      output.write('\n');
+      resolve();
+    };
+    input.resume?.();
+    input.once('data', onData);
+  });
+}
+
+export async function renderTour({
+  script,
+  output = process.stdout,
+  input = process.stdin,
+  env = process.env,
+  accessible = false,
+  plain = false,
+  skipInput = false,
+  color,
+} = {}) {
+  if (!script || !Array.isArray(script.steps)) {
+    return { ok: false, steps: 0, message: 'No demo script to tour' };
+  }
+
+  const linear = accessible || plain;
+  const useColor = color !== undefined ? color : (!linear);
+  const colors = resolveColors({ enabled: useColor, stream: output, env });
+  const width = termWidth(output);
+  const total = script.steps.length;
+
+  // Linear and headless contexts never block on input; interactivity requires a
+  // TTY on both ends so a piped or CI run advances on its own.
+  const interactive = !skipInput && !linear && Boolean(input?.isTTY) && Boolean(output?.isTTY);
+
+  renderHeader(output, script, colors, width, total);
+
+  for (let i = 0; i < total; i += 1) {
+    renderStep(output, script.steps[i], i + 1, total, colors, width);
+    if (interactive && i < total - 1) {
+      await waitForEnter(input, output, colors);
+    }
+  }
+
+  output.write(`\n${colors.bold}Tour complete.${colors.reset} ${colors.dim}Run any step above in OpenCode, or run \`construct demo ${script.name}\` to drive it live.${colors.reset}\n`);
+  return { ok: true, steps: total, surface: 'tour', accessible: linear };
+}