@geraldmaron/construct 1.2.3 → 1.3.1

package/lib/demo.mjs

@@ -2,19 +2,23 @@
  * lib/demo.mjs — `construct demo` terminal recordings via VHS `.tape` files.
  *
  * Shipped tapes live in templates/demos/tapes/; project overrides in
- * .cx/demos/tapes/. Built-in scaffolds via `construct demo init --from=`.
- * Default run mode launches construct chat with a demo script; use `record` or
- * --surface=tape for VHS. Dashboard demos delegate to lib/dashboard-demo.mjs.
+ * .cx/demos/tapes/. Built-in scaffolds via `construct demo init --from=`;
+ * `--from-project` scaffolds a project demo plug-in (manifest + script + tape)
+ * under .cx/demos/ seeded from real project signals (see lib/demo-project.mjs).
+ * Default run mode writes or records a VHS tape; use `tour` for a linear
+ * guided walkthrough and `--surface=playwright` for recording manifests.
  */
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join, resolve, dirname, basename, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { listDemoScripts } from './demo-script.mjs';
+import { listDemoScripts, loadDemoScript } from './demo-script.mjs';
 import { DEMO_SURFACES } from './demo-surface.mjs';
+import { renderTour } from './demo-tour-renderer.mjs';
 import { listDemoRecordings, loadDemoRecording } from './demo-recording.mjs';
 import { recordPlaywrightDemo } from './playwright-demo.mjs';
+import { scaffoldProjectDemo } from './demo-project.mjs';
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -219,7 +223,7 @@ export function initConstructCockpitRecording(name, { cwd, repoRoot = REPO_ROOT
     ...reference,
     name,
     title: reference.title,
-    output: { format: 'mp4', path: `.cx/demos/dashboard/${name}.mp4` },
+    output: { format: 'mp4', path: `.cx/demos/${name}.mp4` },
     _reference: 'agentic-platforms-prd',
   };
   delete recording.sourcePath;
@@ -228,7 +232,7 @@ export function initConstructCockpitRecording(name, { cwd, repoRoot = REPO_ROOT
   return {
     ok: true,
     recordingPath: recPath,
-    message: `Scaffolded Construct cockpit recording ${recPath} (references apps/dashboard spec)`,
+    message: `Scaffolded Construct cockpit recording ${recPath}`,
   };
 }
 
@@ -306,10 +310,6 @@ export function listProjectTapes({ cwd = process.cwd(), repoRoot = REPO_ROOT } =
 }
 
 export function resolveTapeSource(name, { cwd, repoRoot = REPO_ROOT, artifactPath } = {}) {
-  if (name.startsWith('dashboard:')) {
-    return { kind: 'dashboard', name: name.slice('dashboard:'.length) };
-  }
-
   const tapePath = resolveTapeFile(name, { cwd, repoRoot });
   if (tapePath) {
     let source = readFileSync(tapePath, 'utf8');
@@ -402,10 +402,6 @@ export function runDemoRecord(name, {
   required = false,
   surface = null,
 } = {}) {
-  if (name.startsWith('dashboard:')) {
-    return { ok: false, name, message: 'Use recordDashboardDemo for dashboard: demos' };
-  }
-
   const recording = loadDemoRecording(name, { cwd, repoRoot });
   const usePlaywright = surface !== 'tape'
     && (surface === 'playwright' || (recording && recording.engine === 'playwright'));
@@ -506,28 +502,28 @@ export function printHelp() {
 Commands:
   list                     List tapes, recordings, and demo scripts
   init <name> [--from=T]     Scaffold tape or Playwright recording
+  init <name> --from-project Scaffold a project demo plug-in under .cx/demos/
   record <name>              Record VHS tape or Playwright demo manifest
-  <name>                     Run guided demo (default: construct chat)
+  tour [name]                Linear, screen-reader-friendly guided tour
+  <name>                     Record or print the demo (default: tape)
 
-Default run uses construct chat with a demo script (templates/demos/scripts/).
-Falls back to web chat, VHS tape, Playwright, dashboard, or printed steps.
+Default run uses VHS tape templates and falls back to printed script steps.
 
 Options:
   --surface=<s>  ${surfaces}
-  --model <id>   Pin model for chat demo
-  --web          Open web chat (/chat/) instead of terminal
-  --plain        Linear chat renderer
-  --free         OpenRouter free-router mode
+  --accessible   Screen-reader-friendly linear renderer (tour)
+  --skip-input   Tour: auto-advance without waiting for Enter (headless/CI)
   --format <f>   gif (default) | mp4 | webm
   --out <path>   Output path (recording)
+  --from-project  init: scaffold a project demo plug-in under .cx/demos/
   --source-only  Tape: write .tape only; skip recording
   -h, --help     Show this message
 
 Examples:
   construct demo agentic-platforms-prd
+  construct demo tour agentic-platforms-prd --accessible
   construct demo record agentic-platforms-prd --format mp4
   construct demo init marketing --from=nextjs-static
-  construct demo dashboard:cockpit-tour
 `);
 }
 
@@ -539,22 +535,19 @@ function parseArgs(argv) {
     from: 'quickstart',
     command: null,
     name: null,
-    surface: 'chat',
-    model: null,
-    plain: false,
+    surface: 'tape',
     accessible: false,
-    web: false,
-    free: false,
+    skipInput: false,
+    fromProject: false,
   };
   const positional = [];
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--help' || arg === '-h') { options.help = true; continue; }
+    if (arg === '--from-project') { options.fromProject = true; continue; }
     if (arg === '--source-only') { options.sourceOnly = true; continue; }
-    if (arg === '--plain') { options.plain = true; continue; }
     if (arg === '--accessible') { options.accessible = true; continue; }
-    if (arg === '--web') { options.web = true; continue; }
-    if (arg === '--free') { options.free = true; continue; }
+    if (arg === '--skip-input') { options.skipInput = true; continue; }
     if (arg === '--format') { options.format = argv[++i]; continue; }
     if (arg.startsWith('--format=')) { options.format = arg.slice(9); continue; }
     if (arg === '--out') { options.out = argv[++i]; continue; }
@@ -563,13 +556,12 @@ function parseArgs(argv) {
     if (arg.startsWith('--from=')) { options.from = arg.slice(7); continue; }
     if (arg === '--surface') { options.surface = argv[++i]; continue; }
     if (arg.startsWith('--surface=')) { options.surface = arg.slice(10); continue; }
-    if (arg === '--model') { options.model = argv[++i]; continue; }
-    if (arg.startsWith('--model=')) { options.model = arg.slice(8); continue; }
     positional.push(arg);
   }
   if (positional[0] === 'list') options.command = 'list';
   else if (positional[0] === 'init') { options.command = 'init'; options.name = positional[1]; }
   else if (positional[0] === 'record') { options.command = 'record'; options.name = positional[1]; }
+  else if (positional[0] === 'tour') { options.command = 'tour'; options.name = positional[1] || null; }
   else options.name = positional[0] || null;
   return options;
 }
@@ -591,7 +583,7 @@ export async function runDemoCli(argv = [], { cwd = process.cwd(), repoRoot } =
     console.log('\nPlaywright recordings (.cx/demos/recordings/ overrides templates/demos/recordings/):');
     if (!recordings.length) console.log('  (none — run `construct demo init <name> --from=nextjs-static`)');
     else for (const r of recordings) console.log(`  ${r}`);
-    console.log('\nDemo scripts (chat-guided; templates/demos/scripts/):');
+    console.log('\nDemo scripts (tour steps; templates/demos/scripts/):');
     if (!scripts.length) console.log('  (none)');
     else for (const s of scripts) console.log(`  ${s}`);
     console.log(`\nScaffold templates: ${RECORDING_INIT_TEMPLATES.join(', ')}`);
@@ -599,8 +591,21 @@ export async function runDemoCli(argv = [], { cwd = process.cwd(), repoRoot } =
   }
 
   if (options.command === 'init') {
+    if (options.fromProject) {
+      if (!options.name) {
+        console.error('Usage: construct demo init <name> --from-project');
+        process.exit(1);
+      }
+      const result = scaffoldProjectDemo(options.name, { cwd, repoRoot });
+      if (!result.ok) {
+        console.error(result.message);
+        process.exit(1);
+      }
+      console.log(result.message);
+      return;
+    }
     if (!options.name) {
-      console.error(`Usage: construct demo init <name> [--from=${RECORDING_INIT_TEMPLATES.join('|')}]`);
+      console.error(`Usage: construct demo init <name> [--from=${RECORDING_INIT_TEMPLATES.join('|')}] | --from-project`);
       process.exit(1);
     }
     const result = initProjectRecording(options.name, { cwd, from: options.from, repoRoot });
@@ -612,28 +617,45 @@ export async function runDemoCli(argv = [], { cwd = process.cwd(), repoRoot } =
     return;
   }
 
-  const demoName = options.command === 'record' ? options.name : options.name;
-  if (!demoName) {
-    printHelp();
-    process.exit(1);
-  }
-
-  if (demoName.startsWith('dashboard:')) {
-    const { recordDashboardDemo } = await import('./dashboard-demo.mjs');
-    const result = recordDashboardDemo(demoName.slice('dashboard:'.length), { cwd, repoRoot });
+  if (options.command === 'tour') {
+    const scripts = listDemoScripts({ cwd, repoRoot });
+    const tourName = options.name || scripts[0] || null;
+    if (!tourName) {
+      console.error('No demo scripts found. Add one under templates/demos/scripts/ or .cx/demos/scripts/.');
+      process.exit(1);
+    }
+    const script = loadDemoScript(tourName, { cwd, repoRoot });
+    if (!script) {
+      console.error(`Unknown demo: ${tourName}. Run \`construct demo list\` to see available scripts.`);
+      process.exit(1);
+    }
+    // A non-TTY stdout (pipe, file, CI) advances on its own even without --skip-input.
+    const skipInput = options.skipInput || !process.stdout.isTTY;
+    const result = await renderTour({
+      script,
+      output: process.stdout,
+      input: process.stdin,
+      env: process.env,
+      accessible: options.accessible,
+      skipInput,
+    });
     if (!result.ok) {
       console.error(result.message);
-      process.exit(result.missing?.length ? 2 : 1);
+      process.exit(1);
     }
-    console.log(result.message);
-    for (const v of result.videos || []) console.log(`  ${v}`);
     return;
   }
 
+  const demoName = options.command === 'record' ? options.name : options.name;
+  if (!demoName) {
+    printHelp();
+    process.exit(1);
+  }
+
   const preferPlaywright = options.surface === 'playwright'
     || (options.command === 'record' && loadDemoRecording(demoName, { cwd, repoRoot })?.engine === 'playwright');
   const useTape = options.surface === 'tape'
-    || (options.command === 'record' && !preferPlaywright && options.surface !== 'dashboard');
+    || (options.command === 'record' && !preferPlaywright);
   if (useTape || (options.command === 'record' && preferPlaywright)) {
     const result = runDemoRecord(demoName, {
       cwd,
@@ -669,11 +691,7 @@ export async function runDemoCli(argv = [], { cwd = process.cwd(), repoRoot } =
     format: options.format,
     out: options.out,
     sourceOnly: options.sourceOnly,
-    model: options.model,
-    plain: options.plain,
     accessible: options.accessible,
-    web: options.web,
-    free: options.free,
   });
 
   if (!result.ok) {
@@ -684,9 +702,6 @@ export async function runDemoCli(argv = [], { cwd = process.cwd(), repoRoot } =
   if (result.notices?.length) {
     for (const n of result.notices) console.error(`note: ${n}`);
   }
-  if (result.surface === 'chat' || result.surface === 'web') {
-    return;
-  }
   if (result.artifactPath) {
     console.log(`Demo (${demoName}) [${result.surface}] recorded to:`);
     console.log(`  ${result.artifactPath}`);

package/lib/diagram-export.mjs

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const ICON_DIR = path.join(REPO_ROOT, 'templates', 'distribution', 'icons');
+const MERMAID_PPTR_CONFIG = path.join(REPO_ROOT, 'templates', 'distribution', 'mermaid-puppeteer.json');
 
 // Monochrome diagram palette, mirroring the ink ramp in construct-brand.typ so
 // embedded diagrams and surrounding body share one design language.
@@ -36,9 +37,9 @@ export const DISTRIBUTION_D2_SCALE = '0.72';
 export const DISTRIBUTION_D2_SKETCH = '1';
 export const DISTRIBUTION_D2_FONT_SIZE = '14';
 export const DISTRIBUTION_MERMAID_MIME = 'image/png';
-export const DISTRIBUTION_MERMAID_WIDTH = '480';
-export const DISTRIBUTION_MERMAID_SCALE = '1';
-export const DISTRIBUTION_FIGURE_MAX_WIDTH = '58%';
+export const DISTRIBUTION_MERMAID_WIDTH = '2400';
+export const DISTRIBUTION_MERMAID_SCALE = '2';
+export const DISTRIBUTION_FIGURE_MAX_WIDTH = '92%';
 
 // Handwritten font for Mermaid labels so its hand-drawn look matches D2 sketch
 // mode. Caveat ships bundled (templates/distribution/fonts/handwritten) and is
@@ -51,6 +52,9 @@ const MERMAID_INIT = `%%{init: {
   'theme': 'base',
   'look': 'handDrawn',
   'fontFamily': '${MERMAID_FONT}',
+  'flowchart': {
+    'htmlLabels': false
+  },
   'themeVariables': {
     'fontFamily': '${MERMAID_FONT}',
     'fontSize': '19px',
@@ -86,17 +90,8 @@ const MERMAID_INIT = `%%{init: {
   }
 }}%%`;
 
-const CHROME_CANDIDATES = [
-  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-  '/Applications/Chromium.app/Contents/MacOS/Chromium',
-  '/usr/bin/google-chrome',
-  '/usr/bin/chromium',
-  '/usr/bin/chromium-browser',
-];
-
-export function resolvePuppeteerExecutable(env = process.env) {
-  if (env.PUPPETEER_EXECUTABLE_PATH) return env.PUPPETEER_EXECUTABLE_PATH;
-  for (const candidate of CHROME_CANDIDATES) {
+function firstExistingPath(paths = []) {
+  for (const candidate of paths) {
     try {
       if (fs.existsSync(candidate)) return candidate;
     } catch {
@@ -106,6 +101,59 @@ export function resolvePuppeteerExecutable(env = process.env) {
   return null;
 }
 
+function playwrightChromeCandidates(home = process.env.HOME || '') {
+  if (!home) return [];
+  const cacheRoot = path.join(home, 'Library', 'Caches', 'ms-playwright');
+  let entries = [];
+  try {
+    entries = fs.readdirSync(cacheRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  entries = entries
+    .filter((entry) => entry.isDirectory())
+    .sort((a, b) => {
+      const aHeadless = a.name.startsWith('chromium_headless_shell-') ? 0 : 1;
+      const bHeadless = b.name.startsWith('chromium_headless_shell-') ? 0 : 1;
+      if (aHeadless !== bHeadless) return aHeadless - bHeadless;
+      const aVer = Number((a.name.match(/-(\d+)/) || [])[1] || 0);
+      const bVer = Number((b.name.match(/-(\d+)/) || [])[1] || 0);
+      return bVer - aVer;
+    });
+  const candidates = [];
+  for (const entry of entries) {
+    const base = path.join(cacheRoot, entry.name);
+    if (entry.name.startsWith('chromium_headless_shell-')) {
+      candidates.push(path.join(base, 'chrome-headless-shell-mac-arm64', 'chrome-headless-shell'));
+      candidates.push(path.join(base, 'chrome-headless-shell-mac', 'chrome-headless-shell'));
+    }
+    if (entry.name.startsWith('chromium-')) {
+      candidates.push(path.join(base, 'chrome-mac-arm64', 'Chromium.app', 'Contents', 'MacOS', 'Chromium'));
+      candidates.push(path.join(base, 'chrome-mac-arm64', 'chrome'));
+      candidates.push(path.join(base, 'chrome-mac', 'Chromium.app', 'Contents', 'MacOS', 'Chromium'));
+      candidates.push(path.join(base, 'chrome-mac', 'chrome'));
+    }
+  }
+  return candidates;
+}
+
+function chromeCandidates(env = process.env) {
+  return [
+    ...playwrightChromeCandidates(env.HOME),
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/usr/bin/google-chrome',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+  ];
+}
+
+export function resolvePuppeteerExecutable(env = process.env) {
+  if (env.PUPPETEER_EXECUTABLE_PATH) return env.PUPPETEER_EXECUTABLE_PATH;
+  return firstExistingPath(chromeCandidates(env));
+}
+
 export function injectMermaidBrandTheme(code) {
   const body = String(code || '').trim();
   if (!body) return body;
@@ -170,6 +218,7 @@ export function buildDistributionDiagramEnv(baseEnv = process.env) {
     CONSTRUCT_MERMAID_WIDTH: DISTRIBUTION_MERMAID_WIDTH,
     CONSTRUCT_MERMAID_SCALE: DISTRIBUTION_MERMAID_SCALE,
   };
+  if (fs.existsSync(MERMAID_PPTR_CONFIG)) env.CONSTRUCT_MERMAID_PPTR_CONFIG = MERMAID_PPTR_CONFIG;
   const chrome = resolvePuppeteerExecutable(baseEnv);
   if (chrome) env.PUPPETEER_EXECUTABLE_PATH = chrome;
   return env;

package/lib/doctor/cli.mjs

@@ -101,16 +101,26 @@ export async function runCli(args) {
   }
 
   if (sub === 'consistency') {
+    const strict = args.some((a) => a === '--strict' || a === '--all' || a === '--debug');
     const { runAllChecks } = await import('./watchers/consistency.mjs');
     const result = await runAllChecks();
     const blocking = result.findings.filter((f) => f.severity === 'blocking');
     const warnings = result.findings.filter((f) => f.severity === 'warning');
 
+    // Default output carries only user-actionable signal; package/maintainer drift
+    // (tier 'internal') is gated behind --strict so a clean install reads clean.
+
+    const visibleWarnings = strict ? warnings : warnings.filter((f) => f.tier !== 'internal');
+    const internalWarnings = warnings.filter((f) => f.tier === 'internal');
+
     for (const p of result.passed) console.log(`  ✓  ${p.category.padEnd(18)} ${p.summary}`);
-    for (const w of warnings) console.log(`  ⚠  ${w.category.padEnd(18)} ${w.summary}`);
+    for (const w of visibleWarnings) console.log(`  ⚠  ${w.category.padEnd(18)} ${w.summary}`);
     for (const b of blocking) console.log(`  ✗  ${b.category.padEnd(18)} ${b.summary}`);
 
-    console.log(`\n${result.passed.length} category(s) clean, ${warnings.length} warning(s), ${blocking.length} blocking finding(s)`);
+    console.log(`\n${result.passed.length} category(s) clean, ${visibleWarnings.length} warning(s), ${blocking.length} blocking finding(s)`);
+    if (!strict && internalWarnings.length > 0) {
+      console.log(`  (+${internalWarnings.length} package-internal diagnostic(s) — run \`construct doctor consistency --strict\` to view)`);
+    }
     return blocking.length > 0 ? 1 : 0;
   }
 

package/lib/doctor/source-checkout.mjs

@@ -2,8 +2,8 @@
  * lib/doctor/source-checkout.mjs — distinguish Construct source tree vs npm install.
  *
  * `isConstructPackageRepo` is true for both checkouts and consumer installs.
- * Source-only doctor checks (dashboard static export, certification role cards)
- * should run only when this returns true.
+ * Source-only doctor checks (certification role cards) should run only when this
+ * returns true.
  */
 
 import fs from 'node:fs';
@@ -11,6 +11,5 @@ import path from 'node:path';
 
 export function isConstructSourceCheckout(rootDir) {
   const root = path.resolve(rootDir);
-  return fs.existsSync(path.join(root, 'apps', 'dashboard'))
-    || fs.existsSync(path.join(root, 'tests', 'certification', 'specialists'));
+  return fs.existsSync(path.join(root, 'tests', 'certification', 'specialists'));
 }