forgedock 1.0.21 → 1.1.1

package/bin/cinema.mjs

@@ -0,0 +1,320 @@
+/**
+ * bin/cinema.mjs — Cinematic rendering primitives for ForgeDock's TUI.
+ *
+ * Zero-dependency. Pure presentation: gradients, the block-art F mark, and
+ * (in Task 2) shimmer / reveal / progress animation primitives.
+ *
+ * Two independent gates (spec: degradation ladder):
+ *   colorMode()     — 'truecolor' | '256' | 'none'  (NO_COLOR, TTY, TERM)
+ *   motionEnabled() — animation frames on/off        (TTY, FORGE_NO_MOTION, CI, --fast)
+ *
+ * All functions take env/stdout/argv as parameters (with process defaults)
+ * so tests never need module-cache busting.
+ */
+
+// ---------------------------------------------------------------------------
+// Palette (spec: Chrome & Ember)
+// ---------------------------------------------------------------------------
+
+export const CHROME_STOPS = ["#f7f3ea", "#d9cfba", "#a99a82", "#6e6252"];
+export const EMBER_STOPS = ["#ff4d00", "#ff8c1a", "#ffd166"];
+
+// ---------------------------------------------------------------------------
+// Gates
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide the color capability of the terminal.
+ * @returns {'truecolor'|'256'|'none'}
+ */
+export function colorMode(env = process.env, stdout = process.stdout) {
+  if (stdout.isTTY !== true) return "none";
+  if (env.NO_COLOR) return "none";
+  if (env.TERM === "dumb") return "none";
+  const ct = (env.COLORTERM || "").toLowerCase();
+  if (ct.includes("truecolor") || ct.includes("24bit")) return "truecolor";
+  if ((env.TERM || "").includes("256")) return "256";
+  // Windows Terminal / modern conhost support truecolor but don't set COLORTERM.
+  if (process.platform === "win32") return "truecolor";
+  return "256";
+}
+
+/**
+ * Decide whether animation frames run. Independent of color:
+ * NO_COLOR keeps motion (monochrome choreography); non-TTY/CI/--fast kill it.
+ * @returns {boolean}
+ */
+export function motionEnabled(
+  argv = process.argv,
+  env = process.env,
+  stdout = process.stdout,
+) {
+  if (stdout.isTTY !== true) return false;
+  if (env.FORGE_NO_MOTION) return false;
+  if (env.CI) return false;
+  if (argv.includes("--fast")) return false;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Gradient math
+// ---------------------------------------------------------------------------
+
+function hexToRgb(hex) {
+  const h = hex.replace("#", "");
+  return [
+    parseInt(h.slice(0, 2), 16),
+    parseInt(h.slice(2, 4), 16),
+    parseInt(h.slice(4, 6), 16),
+  ];
+}
+
+/**
+ * Sample a multi-stop gradient at position t ∈ [0,1].
+ * @returns {[number, number, number]} RGB triple.
+ */
+export function sampleGradient(stops, t) {
+  const rgb = stops.map(hexToRgb);
+  const clamped = Math.min(Math.max(t, 0), 1);
+  const seg = Math.min(Math.floor(clamped * (rgb.length - 1)), rgb.length - 2);
+  const localT = clamped * (rgb.length - 1) - seg;
+  const [a, b] = [rgb[seg], rgb[seg + 1]];
+  const mix = (x, y) => Math.round(x + (y - x) * localT);
+  return [mix(a[0], b[0]), mix(a[1], b[1]), mix(a[2], b[2])];
+}
+
+/** Quantize an RGB triple to the xterm-256 6×6×6 color cube. */
+function to256([r, g, b]) {
+  const q = (v) => Math.round((v / 255) * 5);
+  return 16 + 36 * q(r) + 6 * q(g) + q(b);
+}
+
+/** Foreground escape for an RGB triple in the given mode ('' for none). */
+function fg(rgb, mode) {
+  if (mode === "none") return "";
+  if (mode === "256") return `\x1b[38;5;${to256(rgb)}m`;
+  return `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m`;
+}
+
+/**
+ * Render one line of text with a per-character horizontal gradient.
+ * Spaces stay uncolored. `phase` shifts the gradient start (for diagonals).
+ * In 'none' mode returns the input text verbatim (no reset appended).
+ */
+export function gradientLine(text, stops, mode, phase = 0) {
+  if (mode === "none") return text;
+  const chars = [...text];
+  const n = Math.max(chars.length - 1, 1);
+  let out = "";
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === " ") {
+      out += " ";
+      continue;
+    }
+    const t = Math.min(i / n + phase, 1);
+    out += fg(sampleGradient(stops, t), mode) + chars[i];
+  }
+  return out + "\x1b[0m";
+}
+
+/**
+ * Render a block of lines with a diagonal gradient (each row's phase shifts
+ * slightly, approximating the logo's 135° gradient).
+ * @returns {string[]}
+ */
+export function gradientBlock(lines, stops, mode) {
+  return lines.map((line, row) => gradientLine(line, stops, mode, row * 0.06));
+}
+
+// ---------------------------------------------------------------------------
+// The mark — block-art interpretation of the ForgeDock "F" (design approved
+// from the 2026-07-03 brainstorm mockups; geometry may be pixel-tuned).
+// ---------------------------------------------------------------------------
+
+export const HERO_MARK = [
+  "            ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄",
+  "        ▄▄██████████████████",
+  "     ▄█████████████▀▀▀▀▀▀▀▀▀",
+  "   ▄██████████▀▀",
+  "    ▀▀▀▀▀  ▄▄███████▀",
+  "        ▄████████▀",
+  "      ▄██████▀",
+  "       ▀▀▀▀",
+];
+
+export const COMPACT_MARK = [
+  "   ▄▄████████",
+  " ▄█████▀▀▀▀▀",
+  " ▀▀ ▄████▀",
+  "   ▀▀▀",
+];
+
+/**
+ * Render the chrome-gradient mark.
+ * @param {'hero'|'compact'} size
+ * @param {'truecolor'|'256'|'none'} mode
+ * @returns {string[]}
+ */
+export function renderMark(size, mode) {
+  const art = size === "hero" ? HERO_MARK : COMPACT_MARK;
+  if (mode === "none") return [...art];
+  return gradientBlock(art, CHROME_STOPS, mode);
+}
+
+/** Ember-gradient text shorthand (wordmarks, act headers). */
+export function ember(text, mode) {
+  return gradientLine(text, EMBER_STOPS, mode);
+}
+
+/** Promise-based sleep for animation pacing. */
+export function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// ---------------------------------------------------------------------------
+// Animation primitives (Task 2)
+// ---------------------------------------------------------------------------
+
+import { box } from "./tui.mjs";
+
+const BRAILLE = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/** Ember-tinted status glyph for a result row. */
+function statusGlyph(ok, mode) {
+  const rgb = ok ? [255, 179, 71] : [224, 112, 80]; // amber / ember-red
+  const glyph = ok ? "✔" : "✖";
+  if (mode === "none") return glyph;
+  return `${fg(rgb, mode)}${glyph}\x1b[0m`;
+}
+
+/** Dim wrapper honoring the mode gate. */
+function dimText(s, mode) {
+  return mode === "none" ? s : `\x1b[2m${s}\x1b[22m`;
+}
+
+/** Badge like [high] / [med] / [low], colorized per confidence. */
+function badgeText(badge, mode) {
+  const label = badge === "medium" ? "med" : badge;
+  if (mode === "none") return `[${label}]`;
+  const rgb = badge === "high" ? [125, 219, 132] : badge === "medium" ? [232, 192, 96] : [224, 112, 80];
+  return `${fg(rgb, mode)}[${label}]\x1b[0m`;
+}
+
+/** Ember-bordered fix card (wraps tui.box; border color applied when able). */
+export function fixCard(lines, mode) {
+  const boxed = box(lines.map((l) => ` ${l} `), { title: "fix" });
+  if (mode === "none") return boxed;
+  const ember = fg([255, 107, 53], mode);
+  return boxed
+    .split("\n")
+    .map((l) => l.replace(/[╭╮╰╯─│]/gu, (m) => `${ember}${m}\x1b[0m`))
+    .join("\n");
+}
+
+function formatRow(label, res, mode) {
+  const parts = [`  ${statusGlyph(res.ok, mode)} ${label.padEnd(16)}`];
+  if (res.detail) parts.push(dimText(String(res.detail), mode));
+  if (res.badge) parts.push(badgeText(res.badge, mode));
+  return parts.join("  ");
+}
+
+/**
+ * Reveal rows one at a time: spinner while `run()` is in flight, settling to
+ * a ✔/✖ line (+ optional fix card). Without motion: run, print final line.
+ * Every row's `run` executes regardless of motion — this is display-only.
+ */
+export async function revealRows(
+  rows,
+  { mode, motion, writer = process.stdout, interval = 80, minDisplayMs = 120 } = {},
+) {
+  const results = [];
+  for (const row of rows) {
+    let res;
+    if (!motion) {
+      res = await row.run();
+    } else {
+      let frame = 0;
+      const spinnerColor = fg([255, 107, 53], mode);
+      const reset = mode === "none" ? "" : "\x1b[0m";
+      writer.write(`  ${spinnerColor}${BRAILLE[0]}${reset} ${row.label}\n`);
+      const timer = setInterval(() => {
+        frame = (frame + 1) % BRAILLE.length;
+        writer.write(`\x1b[1A\x1b[2K  ${spinnerColor}${BRAILLE[frame]}${reset} ${row.label}\n`);
+      }, interval);
+      const started = Date.now();
+      try {
+        res = await row.run();
+        const elapsed = Date.now() - started;
+        if (elapsed < minDisplayMs) await sleep(minDisplayMs - elapsed);
+      } finally {
+        clearInterval(timer);
+      }
+      writer.write("\x1b[1A\x1b[2K");
+    }
+    writer.write(formatRow(row.label, res, mode) + "\n");
+    if (!res.ok && res.fix && res.fix.length > 0) {
+      writer.write(fixCard(res.fix, mode) + "\n");
+    }
+    results.push(res);
+  }
+  return results;
+}
+
+/**
+ * One-pass highlight sweep over gradient block art, settling to the static
+ * gradientBlock render. In-place redraw via cursor-up; never alt-screen.
+ */
+export async function shimmer(
+  lines,
+  stops,
+  { mode, motion, writer = process.stdout, frames = 14, interval = 55 } = {},
+) {
+  const settled = gradientBlock(lines, stops, mode);
+  if (!motion || mode === "none") {
+    writer.write(settled.join("\n") + "\n");
+    return;
+  }
+  const width = Math.max(...lines.map((l) => l.length));
+  for (let f = 0; f <= frames; f++) {
+    const band = (f / frames) * (width + 16) - 8;
+    const frameLines = lines.map((line, row) => {
+      const chars = [...line];
+      let out = "";
+      for (let i = 0; i < chars.length; i++) {
+        if (chars[i] === " ") {
+          out += " ";
+          continue;
+        }
+        const t = Math.min(i / Math.max(chars.length - 1, 1) + row * 0.06, 1);
+        let rgb = sampleGradient(stops, t);
+        const dist = Math.abs(i - band + row * 1.5);
+        if (dist < 6) {
+          const boost = 1 - dist / 6;
+          rgb = rgb.map((v) => Math.round(v + (255 - v) * boost));
+        }
+        out += `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${chars[i]}`;
+      }
+      return out + "\x1b[0m";
+    });
+    if (f > 0) writer.write(`\x1b[${lines.length}A`);
+    writer.write(frameLines.join("\n") + "\n");
+    await sleep(interval);
+  }
+  writer.write(`\x1b[${lines.length}A`);
+  writer.write(settled.join("\n") + "\n");
+}
+
+/**
+ * One static frame of the molten progress bar: solid fill with a ▓▒ leading
+ * edge and dim ░ remainder. Caller redraws with cursor-up for animation.
+ */
+export function moltenBar(current, total, { width = 24, mode } = {}) {
+  const ratio = total === 0 ? 1 : Math.min(current / total, 1);
+  const filled = Math.round(ratio * width);
+  const solidLen = Math.max(filled - 2, 0);
+  const edge = "▓▒".slice(0, filled - solidLen);
+  const body = "█".repeat(solidLen) + edge;
+  const rest = "░".repeat(Math.max(width - filled, 0));
+  if (mode === "none") return `[${body}${rest}]`;
+  return gradientLine(body, EMBER_STOPS, mode) + dimText(rest, mode);
+}

package/bin/demo.mjs

@@ -0,0 +1,386 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * bin/demo.mjs — `forgedock demo` one-command demo mode (issue #1145).
+ *
+ * Stands up a runnable ForgeDock demo at a PREDICTABLE location with ZERO
+ * required decisions, then prints the exact next steps. It removes the
+ * clone → cd → init → open friction that loses first-time users.
+ *
+ * Source precedence (robust + offline-friendly):
+ *   1. `git clone` the live demo repo (RapierCraftStudios/forgedock-demo).
+ *   2. On failure (repo absent / no network), fall back to copying the bundled
+ *      scaffold shipped inside the installed package at
+ *      `FORGE_HOME/examples/forgedock-demo`, then `git init` + initial commit.
+ *
+ * Re-runs are idempotent: an existing git clone is fast-forwarded
+ * (`git pull --ff-only`); a scaffold copy is reused, never clobbered.
+ *
+ * Design notes:
+ *   - All side effects (process spawning, filesystem, PATH lookup) are injected
+ *     via `opts` so the unit tests in bin/tests/demo.test.mjs run with no
+ *     network and no git/claude on the host.
+ *   - Pure helpers (parseDemoArgs, resolveTargetDir, renderNextSteps,
+ *     demoUsage, demoForgeYaml) are exported for direct testing.
+ *
+ * Exports:
+ *   DEFAULT_DEMO_REPO, DEFAULT_DEMO_DIRNAME
+ *   parseDemoArgs(args)            → {positional, dir, open, repo, help, error}
+ *   resolveTargetDir(opts)         → string  (absolute target path)
+ *   isGitRepo(dir, fsx)            → boolean
+ *   demoUsage()                    → string
+ *   demoForgeYaml(repoSlug)        → string
+ *   renderNextSteps(ctx)           → string
+ *   runDemo(opts)                  → Promise<{status, ...}>
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  cpSync,
+  readdirSync,
+  writeFileSync,
+} from "fs";
+import { join, dirname, resolve, isAbsolute, basename } from "path";
+import { homedir } from "os";
+import { spawnSync, spawn } from "child_process";
+
+export const DEFAULT_DEMO_REPO = "RapierCraftStudios/forgedock-demo";
+export const DEFAULT_DEMO_DIRNAME = "forgedock-demo";
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse `forgedock demo` arguments.
+ *
+ * Flags:
+ *   --dir <path> | --dir=<path>   Target directory (default: ~/forgedock-demo).
+ *   --repo <slug> | --repo=<slug> Override the demo repo (owner/name).
+ *   --open                        Launch Claude Code in the demo dir when found.
+ *   --no-open                     Explicitly disable launching (the default).
+ *   --help | -h                   Show usage.
+ *
+ * The first non-flag argument is treated as the target directory (positional
+ * convenience equivalent to --dir).
+ *
+ * @param {string[]} args
+ * @returns {{positional: string|undefined, dir: string|undefined,
+ *            repo: string|undefined, open: boolean, help: boolean,
+ *            error: string|null}}
+ */
+export function parseDemoArgs(args = []) {
+  const out = {
+    positional: undefined,
+    dir: undefined,
+    repo: undefined,
+    open: false,
+    help: false,
+    error: null,
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--help" || a === "-h") {
+      out.help = true;
+    } else if (a === "--open") {
+      out.open = true;
+    } else if (a === "--no-open") {
+      out.open = false;
+    } else if (a === "--dir") {
+      out.dir = args[++i];
+      if (out.dir === undefined) out.error = "--dir requires a path argument";
+    } else if (a.startsWith("--dir=")) {
+      out.dir = a.slice("--dir=".length);
+    } else if (a === "--repo") {
+      out.repo = args[++i];
+      if (out.repo === undefined) out.error = "--repo requires an owner/name argument";
+    } else if (a.startsWith("--repo=")) {
+      out.repo = a.slice("--repo=".length);
+    } else if (a.startsWith("--")) {
+      out.error = `Unknown flag: ${a}`;
+    } else if (out.positional === undefined) {
+      out.positional = a;
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve the predictable target directory. Priority: --dir, then positional,
+ * then ~/forgedock-demo. Always returned as an absolute path.
+ *
+ * @param {{dir?: string, positional?: string, home?: string, cwd?: string}} opts
+ * @returns {string}
+ */
+export function resolveTargetDir({ dir, positional, home = homedir(), cwd = process.cwd() } = {}) {
+  const chosen = dir || positional;
+  if (chosen && chosen.trim() !== "") {
+    return isAbsolute(chosen) ? chosen : resolve(cwd, chosen);
+  }
+  return join(home, DEFAULT_DEMO_DIRNAME);
+}
+
+/**
+ * @param {string} dir
+ * @param {{existsSync: Function}} fsx
+ * @returns {boolean} true if dir contains a `.git` entry (worktree or repo).
+ */
+export function isGitRepo(dir, fsx) {
+  return fsx.existsSync(join(dir, ".git"));
+}
+
+function isEmptyDir(dir, fsx) {
+  try {
+    return fsx.readdirSync(dir).length === 0;
+  } catch {
+    return true;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+export function demoUsage() {
+  return [
+    "Usage: forgedock demo [dir] [--dir <path>] [--repo <owner/name>] [--open]",
+    "",
+    "Stand up a runnable ForgeDock demo at a predictable location (default",
+    "~/forgedock-demo) and print the exact next steps. No configuration needed.",
+    "",
+    "  [dir]            Target directory (same as --dir).",
+    "  --dir <path>     Where to create the demo (default: ~/forgedock-demo).",
+    "  --repo <slug>    Demo repo to clone (default: RapierCraftStudios/forgedock-demo).",
+    "  --open           Launch Claude Code in the demo directory if available.",
+    "  --no-open        Do not launch Claude Code (default).",
+    "  -h, --help       Show this help.",
+  ].join("\n");
+}
+
+/**
+ * Minimal, valid forge.yaml for the demo repo so /work-on is usable immediately.
+ * @param {string} repoSlug - "owner/name"
+ * @returns {string}
+ */
+export function demoForgeYaml(repoSlug) {
+  const [owner = "your-org", repo = DEFAULT_DEMO_DIRNAME] = String(repoSlug).split("/");
+  return [
+    "# forge.yaml — minimal ForgeDock config for the demo repo.",
+    "# Auto-generated by: npx forgedock demo",
+    "project:",
+    '  name: "ForgeDock Demo"',
+    `  owner: "${owner}"`,
+    `  repo: "${repo}"`,
+    '  description: "A tiny Notes API for trying ForgeDock risk-free."',
+    "paths:",
+    '  root: "."',
+    '  worktree_base: ".claude/worktrees"',
+    "branches:",
+    '  default: "main"',
+    '  staging: "main"',
+    "",
+  ].join("\n");
+}
+
+/**
+ * Render the success / next-steps card.
+ * @param {{target: string, source: string, claudeAvailable: boolean}} ctx
+ * @returns {string}
+ */
+export function renderNextSteps({ target, source, claudeAvailable }) {
+  const sourceNote = {
+    cloned: "Cloned the live demo repo.",
+    pulled: "Demo already present — pulled the latest.",
+    scaffold: "Live repo unavailable — built the demo from the bundled scaffold.",
+    exists: "Reused the existing demo directory.",
+  }[source] || "";
+
+  const lines = [
+    "",
+    `✔ Demo repo ready at ${target}`,
+    ...(sourceNote ? [`  (${sourceNote})`] : []),
+    "",
+    "Next: open Claude Code in that directory and run:",
+    "",
+    "    /work-on 1",
+    "",
+    "This picks up a pre-written bug issue and runs the full",
+    "investigate → architect → build → review → merge pipeline.",
+    "",
+    `  cd ${target}`,
+    claudeAvailable
+      ? "  claude            # open Claude Code here (or re-run with --open)"
+      : "  # then open Claude Code in this directory",
+  ];
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Default injectable side-effect implementations
+// ---------------------------------------------------------------------------
+
+const defaultFsx = { existsSync, mkdirSync, cpSync, readdirSync, writeFileSync };
+
+/**
+ * Run a command without throwing. Returns a normalized result.
+ * @returns {{status: number, stdout: string, stderr: string}}
+ */
+function defaultExec(cmd, cmdArgs, opts = {}) {
+  const r = spawnSync(cmd, cmdArgs, { encoding: "utf8", ...opts });
+  return {
+    status: r.error ? 127 : (typeof r.status === "number" ? r.status : 1),
+    stdout: r.stdout || "",
+    stderr: r.stderr || "",
+  };
+}
+
+/** @returns {boolean} whether `bin` resolves on PATH. */
+function defaultCommandExists(bin) {
+  const probe = process.platform === "win32" ? "where" : "which";
+  const r = spawnSync(probe, [bin], { encoding: "utf8" });
+  return !r.error && r.status === 0;
+}
+
+/** Launch an interactive process in `cwd`, inheriting stdio. */
+function defaultLaunch(bin, launchArgs, opts = {}) {
+  spawn(bin, launchArgs, { stdio: "inherit", ...opts });
+}
+
+const defaultLogger = {
+  log: (m) => process.stdout.write(`${m}\n`),
+  error: (m) => process.stderr.write(`${m}\n`),
+};
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Stand up the demo.
+ *
+ * @param {object} opts
+ * @param {string}  opts.forgeHome            - Package root (for bundled scaffold).
+ * @param {string[]} [opts.args]              - CLI args after `demo`.
+ * @param {string}  [opts.home]               - Home dir (default os.homedir()).
+ * @param {string}  [opts.cwd]                - Working dir (default process.cwd()).
+ * @param {string}  [opts.demoRepo]           - Override demo repo slug.
+ * @param {Function} [opts.exec]              - (cmd, args, {cwd}) => {status,...}.
+ * @param {object}  [opts.fsx]                - Filesystem facade.
+ * @param {Function} [opts.commandExists]     - (bin) => boolean.
+ * @param {Function} [opts.launch]            - (bin, args, {cwd}) => void.
+ * @param {{log:Function,error:Function}} [opts.logger]
+ * @returns {Promise<{status: string, target?: string, source?: string, error?: string}>}
+ */
+export async function runDemo(opts = {}) {
+  const {
+    forgeHome,
+    args = [],
+    home = homedir(),
+    cwd = process.cwd(),
+    exec = defaultExec,
+    fsx = defaultFsx,
+    commandExists = defaultCommandExists,
+    launch = defaultLaunch,
+    logger = defaultLogger,
+  } = opts;
+
+  const parsed = parseDemoArgs(args);
+  if (parsed.help) {
+    logger.log(demoUsage());
+    return { status: "help" };
+  }
+  if (parsed.error) {
+    logger.error(parsed.error);
+    logger.error(demoUsage());
+    return { status: "error", error: parsed.error };
+  }
+
+  const demoRepo =
+    parsed.repo || opts.demoRepo || process.env.FORGEDOCK_DEMO_REPO || DEFAULT_DEMO_REPO;
+  const target = resolveTargetDir({ dir: parsed.dir, positional: parsed.positional, home, cwd });
+  const scaffold = forgeHome
+    ? join(forgeHome, "examples", "forgedock-demo")
+    : null;
+
+  let source;
+
+  if (fsx.existsSync(target) && !isEmptyDir(target, fsx)) {
+    // Idempotent re-run — never clobber an existing demo.
+    if (isGitRepo(target, fsx)) {
+      const pull = exec("git", ["pull", "--ff-only"], { cwd: target });
+      source = pull.status === 0 ? "pulled" : "exists";
+      if (pull.status !== 0) {
+        logger.log("Could not fast-forward the existing demo — leaving it untouched.");
+      }
+    } else {
+      source = "exists";
+    }
+  } else {
+    // Fresh setup: prefer the live repo, fall back to the bundled scaffold.
+    fsx.mkdirSync(dirname(target), { recursive: true });
+    const clone = exec(
+      "git",
+      ["clone", "--depth", "1", `https://github.com/${demoRepo}.git`, target],
+      { cwd },
+    );
+    if (clone.status === 0) {
+      source = "cloned";
+    } else {
+      if (!scaffold || !fsx.existsSync(scaffold)) {
+        const msg =
+          `Could not clone ${demoRepo} and no bundled scaffold was found` +
+          (scaffold ? ` at ${scaffold}` : "") +
+          ". Check your network or reinstall ForgeDock.";
+        logger.error(msg);
+        return { status: "error", error: msg };
+      }
+      // Copy everything except bootstrap.sh (that script is for standing up a
+      // *live* GitHub repo and is not needed for a local demo).
+      fsx.mkdirSync(target, { recursive: true });
+      fsx.cpSync(scaffold, target, {
+        recursive: true,
+        filter: (src) => basename(src) !== "bootstrap.sh",
+      });
+      // Best-effort local git history so the demo feels like a real repo.
+      exec("git", ["init", "-q"], { cwd: target });
+      exec("git", ["add", "."], { cwd: target });
+      exec(
+        "git",
+        [
+          "-c",
+          "user.name=forgedock-demo",
+          "-c",
+          "user.email=demo@forgedock.dev",
+          "commit",
+          "-q",
+          "-m",
+          "chore: initial demo scaffold",
+        ],
+        { cwd: target },
+      );
+      source = "scaffold";
+    }
+  }
+
+  // Ensure a usable forge.yaml exists (the bundled scaffold ships without one).
+  const forgeYamlPath = join(target, "forge.yaml");
+  if (!fsx.existsSync(forgeYamlPath)) {
+    fsx.writeFileSync(forgeYamlPath, demoForgeYaml(demoRepo));
+  }
+
+  const claudeAvailable = commandExists("claude");
+  logger.log(renderNextSteps({ target, source, claudeAvailable }));
+
+  if (parsed.open) {
+    if (claudeAvailable) {
+      logger.log("Launching Claude Code…");
+      launch("claude", [], { cwd: target });
+    } else {
+      logger.log("`claude` was not found on PATH — open Claude Code manually in the demo directory.");
+    }
+  }
+
+  return { status: "ok", target, source };
+}