Make CLI success output copy-paste-safe; add --serve, docs hub, key hygiene

A successful clone printed a bare, timestamped app path that wrapped mid-word
in the terminal, so users' `cd` failed and `npm install && npm run dev` ran in
the wrong directory — a confusing failure from a successful clone. Plus there
was no first-party "see it locally" path, no central docs page, "clone" was
conflated with `git clone`, and key hygiene wasn't stated.

CLI (compiler):
- Add compiler/src/cliSummary.ts: a copy-paste-safe success block on stderr — a
  single QUOTED `cd "<app>" && npm install && npm run dev` line that survives
  terminal wrapping — plus the AGENTS.md safe-to-edit pointers (content.ts,
  components/). The machine-readable {"event":"done",...} JSON stays on stdout.
- Add --serve (npm install + npm run dev in the generated app) and --open
  (also open the browser at the detected dev URL). Wired into single + multi.
- Add writeLatestPointer(): refresh a runs/<site>/latest symlink to the newest
  run so there's a stable, timestamp-free cd/script target. The reuse/regen
  scanners already filter to digit-prefixed run dirs, so `latest` is ignored.
- Tests: cliSummary (quoting, single-line command, Next/Vite roots, stable-path
  preference, --serve/--open hint) and runsLayout (symlink write + in-place
  refresh, timestamp-free stable path).

Docs:
- Add docs/README.md as a central documentation index.
- State prominently that ditto "cloning" = generating a codebase from a live
  URL, NOT `git clone` (no source repo required), in README + docs hub.
- Add "keys are secrets: use $DITTO_API_KEY, never inline/commit, rotate
  anytime" beside the key/auth examples in README + docs/SERVICE.md.
- Document --serve/--open and the latest symlink in README + compiler/README.

Note: the live ditto.site/docs web route and the dashboard's inline-token
snippet live in the marketing-site repo and still need a change there.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

compiler/README.md

@@ -16,6 +16,8 @@ npm install
 npx playwright install chromium
 
 npm run clone -- https://example.com/
+npm run clone -- https://example.com/ --serve   # then npm install + npm run dev
+npm run clone -- https://example.com/ --open    # ...and open the browser too
 npm run clone -- https://example.com/ --mode=multi --styling=tailwind
 npm run clone -- https://example.com/ --mode=single --framework=vite
 npm run clone-site -- https://example.com/
@@ -34,6 +36,13 @@ npm run typecheck
 Root-level scripts forward to these commands, so `npm run clone -- <url>` works
 from the repository root too.
 
+("Clone" here = generating a codebase from a live URL, not `git clone`; no source
+repo required.) On success the CLI prints a copy-paste-safe summary: a single
+quoted `cd … && npm install && npm run dev` line plus safe-to-edit pointers. Pass
+`--serve` to run install + dev automatically, or `--open` to also launch the
+browser. Without `--out`, a `runs/<site>/latest` symlink always points at the
+newest run so paths aren't timestamp-fragile.
+
 Multi-page generation defaults to the fast no-validation path. Use `--validate`
 when the clone command itself should run the full build/render/gates QA pass, or
 run `validate-site` separately. `--concurrency` controls source route capture;

compiler/src/cli.ts

@@ -1,11 +1,12 @@
 #!/usr/bin/env -S npx tsx
 import { basename, dirname, join, resolve, sep } from "node:path";
-import { cpSync, existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { captureSite, REQUIRED_VIEWPORTS, SAMPLE_VIEWPORTS, type CaptureResult } from "./capture/capture.js";
 import { fileURLToPath } from "node:url";
 import { generateAll } from "./generate/pipeline.js";
 import { refineSizing } from "./generate/refineSizing.js";
 import { writeJSON, writeText, ensureDir, readJSON, fileExists } from "./util/fsx.js";
+import { doneSummary, serveApp } from "./cliSummary.js";
 import type { AppFramework } from "./generate/app.js";
 
 export type CloneOptions = {
@@ -34,6 +35,9 @@ export type CloneResult = {
   sourceDir: string;
   appDir: string;
   sourceUrl: string;
+  /** A stable, timestamp-free path to the app (via the `runs/<site>/latest` symlink),
+   *  present in runs-layout mode when the symlink could be created. */
+  stableAppDir?: string;
 };
 
 export function siteIdFromUrl(url: string): string {
@@ -462,16 +466,34 @@ export async function runClone(opts: CloneOptions): Promise<CloneResult> {
 
   writeText(join(runDir, "logs", "compiler.log.jsonl"), logEvents.map((e) => JSON.stringify(e)).join("\n") + "\n");
 
+  let stableAppDir: string | undefined;
   if (out) {
     // Publish the deliverable to <siteName>/app; keep working artifacts in .clone.
     exportApp(appDir, out.appDir);
     logBoth({ event: "exported", app: out.appDir });
   } else {
-    // latest pointer (runs/ layout, used by --reuse / regen)
-    writeJSON(join(runsDir, siteId, "latest.json"), { runDir, ts: timestamp() });
+    // latest pointer (runs/ layout, used by --reuse / regen) + a `latest` symlink so the
+    // app has a stable, timestamp-free path that survives copy-paste.
+    stableAppDir = writeLatestPointer(runsDir, siteId, runDir);
   }
 
-  return { runDir, sourceDir, appDir: out ? out.appDir : appDir, sourceUrl: opts.url };
+  return { runDir, sourceDir, appDir: out ? out.appDir : appDir, sourceUrl: opts.url, stableAppDir };
+}
+
+/** Record the newest run for a site in the runs layout: a `latest.json` breadcrumb (used by
+ *  `--reuse`/regen) and a `latest` symlink → runDir. Returns the stable app path when the
+ *  symlink was created (symlinks can be unavailable, e.g. Windows without privilege — non-fatal). */
+export function writeLatestPointer(runsDir: string, siteId: string, runDir: string): string | undefined {
+  writeJSON(join(runsDir, siteId, "latest.json"), { runDir, ts: timestamp() });
+  const link = join(runsDir, siteId, "latest");
+  try {
+    // Refresh an existing symlink; refuse (via non-recursive rm) to clobber a real directory.
+    rmSync(link, { force: true });
+    symlinkSync(runDir, link, "junction");
+    return join(link, "generated", "app");
+  } catch {
+    return undefined;
+  }
 }
 
 function copySourceRef(from: string, to: string): void {
@@ -543,12 +565,22 @@ async function main(): Promise<void> {
   const args = process.argv.slice(2);
   const url = args.find((a) => !a.startsWith("--"));
   if (!url) {
-    console.error("usage: clone-static <url> [--mode=single|multi] [--styling=tailwind|css] [--framework=next|vite] [--out=<dir>]");
+    console.error("usage: clone-static <url> [--mode=single|multi] [--styling=tailwind|css] [--framework=next|vite] [--out=<dir>] [--serve] [--open]");
     process.exit(1);
   }
   const mode = parseProductMode(args);
   const styling = parseProductStyling(args);
   const framework = parseProductFramework(args);
+  // --serve installs deps + starts the dev server after cloning; --open also launches the browser.
+  const open = hasAnyFlag(args, ["--open"]);
+  const serve = open || hasAnyFlag(args, ["--serve"]);
+  const finish = async (res: { appDir: string; stableAppDir?: string }) => {
+    if (serve) {
+      await serveApp(res.appDir, { open });
+    } else {
+      process.stderr.write(doneSummary({ url, appDir: res.appDir, framework, stableAppDir: res.stableAppDir }));
+    }
+  };
   const vpArg = firstFlagValue(args, ["--dev-viewports", "--viewports"]);
   const runsArg = firstFlagValue(args, ["--dev-runs", "--runs"]);
   // --out=<dir>: clean <dir>/<siteName>/{app,.clone} layout (default: ./output when bare --out).
@@ -604,7 +636,8 @@ async function main(): Promise<void> {
       tier,
       log: (e) => console.log(JSON.stringify(e)),
     });
-    console.log(JSON.stringify({ event: "done", runDir: res.runDir, app: res.appDir }));
+    console.log(JSON.stringify({ event: "done", runDir: res.runDir, app: res.appDir, stableApp: res.stableAppDir }));
+    await finish(res);
     return;
   }
 
@@ -625,7 +658,8 @@ async function main(): Promise<void> {
     reuseSource,
     log: (e) => console.log(JSON.stringify(e)),
   });
-  console.log(JSON.stringify({ event: "done", runDir: res.runDir, app: res.appDir }));
+  console.log(JSON.stringify({ event: "done", runDir: res.runDir, app: res.appDir, stableApp: res.stableAppDir }));
+  await finish(res);
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {

compiler/src/cliSummary.ts

@@ -0,0 +1,112 @@
+/**
+ * Human-facing success output for the `clone-static` CLI.
+ *
+ * The CLI streams machine-readable JSON events to stdout; this module renders the
+ * copy-paste-friendly summary a person actually reads at the end, plus the optional
+ * `--serve` runner that installs deps and starts the dev server for them.
+ *
+ * Why this exists: a bare `runs/<domain>/<timestamp>/generated/app` path pasted into a
+ * terminal wraps mid-word, so `cd` fails and the follow-up `npm run dev` runs in the
+ * wrong directory. The preview command here is a single quoted line that survives
+ * wrapping.
+ */
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+
+export type DoneSummaryInput = {
+  url: string;
+  /** The exact generated app directory for this run. */
+  appDir: string;
+  framework: "next" | "vite";
+  /** Stable path (a `runs/<site>/latest` symlink target) preferred as the `cd` target when present. */
+  stableAppDir?: string;
+};
+
+/** Double-quote a path for a POSIX shell so spaces and wrapping don't break copy-paste. */
+export function shellQuote(p: string): string {
+  return `"${p.replace(/(["\\$`])/g, "\\$1")}"`;
+}
+
+/** The success block. The preview command is one quoted line on purpose. */
+export function doneSummary(input: DoneSummaryInput): string {
+  const root = input.framework === "next" ? "src/app" : "src";
+  const cdTarget = input.stableAppDir ?? input.appDir;
+  const lines: string[] = [
+    "",
+    `✓ Done — cloned ${input.url}`,
+    "",
+    "  Preview it locally (copy-paste this one line):",
+    "",
+    `    cd ${shellQuote(cdTarget)} && npm install && npm run dev`,
+    "",
+    "  What's safe to edit — full guide in AGENTS.md inside the app:",
+    `    • page copy & content  →  ${root}/content.ts`,
+    `    • components           →  ${root}/components/`,
+    "",
+    "  Or re-run with --serve to install deps and start the dev server for you",
+    "  (add --open to launch the browser too).",
+  ];
+  if (input.stableAppDir && input.stableAppDir !== input.appDir) {
+    lines.push("");
+    lines.push(`  The path above is a stable pointer to the newest clone. This exact run:`);
+    lines.push(`    ${input.appDir}`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+function openBrowser(url: string): void {
+  const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
+  const args = platform() === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {}); // opening a browser is best-effort
+    child.unref();
+  } catch {
+    /* best-effort */
+  }
+}
+
+function runToCompletion(cmd: string, args: string[], cwd: string): Promise<void> {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(cmd, args, { cwd, stdio: "inherit", shell: platform() === "win32" });
+    child.on("error", reject);
+    child.on("exit", (code) =>
+      code === 0 ? resolvePromise() : reject(new Error(`\`${cmd} ${args.join(" ")}\` exited with code ${code}`)),
+    );
+  });
+}
+
+/**
+ * Run `npm install` then `npm run dev` in the generated app (foreground — `npm run dev`
+ * keeps running until the user stops it). With `open`, launches the default browser at
+ * the dev URL once the server prints it.
+ */
+export async function serveApp(appDir: string, opts: { open: boolean }): Promise<void> {
+  process.stderr.write(`\n→ Installing dependencies in ${appDir}\n`);
+  await runToCompletion("npm", ["install"], appDir);
+
+  process.stderr.write(`→ Starting the dev server (Ctrl-C to stop)\n\n`);
+  await new Promise<void>((resolvePromise, reject) => {
+    const dev = spawn("npm", ["run", "dev"], {
+      cwd: appDir,
+      stdio: opts.open ? ["inherit", "pipe", "inherit"] : "inherit",
+      shell: platform() === "win32",
+    });
+    if (opts.open && dev.stdout) {
+      let opened = false;
+      dev.stdout.on("data", (chunk: Buffer) => {
+        process.stdout.write(chunk);
+        if (opened) return;
+        const m = String(chunk).match(/https?:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?\S*/i);
+        if (m) {
+          opened = true;
+          openBrowser(m[0]);
+        }
+      });
+    }
+    dev.on("error", reject);
+    dev.on("exit", (code) =>
+      code === 0 || code === null ? resolvePromise() : reject(new Error(`\`npm run dev\` exited with code ${code}`)),
+    );
+  });
+}

compiler/src/site/cloneSite.ts

@@ -21,7 +21,7 @@ import { structurallySimilar } from "./signature.js";
 import { generateSiteApp, routeToSegment, routeKey, type RouteArtifact } from "./generateSite.js";
 import { detectSharedChrome, chromeSignatureId } from "./sharedLayout.js";
 import { validateSite, type SiteReport } from "./validateSite.js";
-import { siteIdFromUrl, namedOutDirs, exportApp } from "../cli.js";
+import { siteIdFromUrl, namedOutDirs, exportApp, writeLatestPointer } from "../cli.js";
 import { writeJSON, readJSON, ensureDir, fileExists, writeText } from "../util/fsx.js";
 import { seoInventoryToMarkdown } from "../generate/seo.js";
 import type { AppFramework } from "../generate/app.js";
@@ -56,6 +56,8 @@ export type CloneSiteResult = {
   plan: RoutePlan;
   routes: RouteArtifact[];
   siteReport?: SiteReport;
+  /** Stable, timestamp-free path to the app (via the `runs/<site>/latest` symlink), when created. */
+  stableAppDir?: string;
 };
 
 function timestamp(): string {
@@ -236,8 +238,10 @@ export async function runCloneSite(opts: CloneSiteOptions): Promise<CloneSiteRes
     siteReport = await validateSite(runDir, { tier: opts.tier ?? "stage2", routeConcurrency: opts.validationConcurrency, viewportConcurrency: opts.viewportConcurrency, log });
   }
 
+  let stableAppDir: string | undefined;
   if (out) { exportApp(appDir, out.appDir); log({ event: "exported", app: out.appDir }); }
-  return { runDir, appDir: out ? out.appDir : appDir, siteId, plan, routes, siteReport };
+  else { stableAppDir = writeLatestPointer(runsDir, siteId, runDir); }
+  return { runDir, appDir: out ? out.appDir : appDir, siteId, plan, routes, siteReport, stableAppDir };
 }
 
 type ManifestForRegen = {

compiler/test/cliSummary.test.ts

@@ -0,0 +1,53 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { doneSummary, shellQuote } from "../src/cliSummary.js";
+
+describe("shellQuote", () => {
+  it("wraps a path in double quotes so spaces survive copy-paste", () => {
+    assert.equal(shellQuote("/Users/x/runs/site/20260701/generated/app"), '"/Users/x/runs/site/20260701/generated/app"');
+    assert.equal(shellQuote("/Users/x/My Sites/app"), '"/Users/x/My Sites/app"');
+  });
+
+  it("escapes characters the shell would otherwise interpret inside double quotes", () => {
+    assert.equal(shellQuote('/a/"b"/$c/`d`/e\\f'), '"/a/\\"b\\"/\\$c/\\`d\\`/e\\\\f"');
+  });
+});
+
+describe("doneSummary", () => {
+  const base = { url: "https://academyux.com/", appDir: "/runs/academyux.com/20260701-173012/generated/app", framework: "next" as const };
+
+  it("emits a single quoted preview line (no mid-word wrap on the path)", () => {
+    const out = doneSummary(base);
+    const line = out.split("\n").find((l) => l.includes("cd "));
+    assert.ok(line, "has a cd line");
+    // one line, path is quoted so a wrapping terminal can't split the command
+    assert.match(line!, /cd "\/runs\/academyux\.com\/20260701-173012\/generated\/app" && npm install && npm run dev/);
+  });
+
+  it("points at the Next safe-edit areas from AGENTS.md", () => {
+    const out = doneSummary(base);
+    assert.match(out, /src\/app\/content\.ts/);
+    assert.match(out, /src\/app\/components\//);
+    assert.match(out, /AGENTS\.md/);
+  });
+
+  it("uses the Vite src root when framework is vite", () => {
+    const out = doneSummary({ ...base, framework: "vite" });
+    assert.match(out, /cd .* && npm install && npm run dev/);
+    assert.match(out, /• page copy & content {2}→ {2}src\/content\.ts/);
+    assert.match(out, /• components {11}→ {2}src\/components\//);
+  });
+
+  it("prefers the stable path as the cd target and still shows the exact run", () => {
+    const out = doneSummary({ ...base, stableAppDir: "/runs/academyux.com/latest/generated/app" });
+    const cdLine = out.split("\n").find((l) => l.includes("cd "))!;
+    assert.match(cdLine, /cd "\/runs\/academyux\.com\/latest\/generated\/app"/);
+    assert.match(out, /This exact run/);
+    assert.match(out, /\/runs\/academyux\.com\/20260701-173012\/generated\/app/);
+  });
+
+  it("mentions the --serve / --open shortcut", () => {
+    assert.match(doneSummary(base), /--serve/);
+    assert.match(doneSummary(base), /--open/);
+  });
+});

compiler/test/runsLayout.test.ts

@@ -0,0 +1,31 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, existsSync, readlinkSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeLatestPointer } from "../src/cli.js";
+
+describe("writeLatestPointer", () => {
+  it("writes latest.json and a `latest` symlink to the newest run, refreshing it in place", () => {
+    const runs = mkdtempSync(join(tmpdir(), "ditto-runs-"));
+    const siteId = "example.com";
+
+    const run1 = join(runs, siteId, "20260701-100000");
+    mkdirSync(join(run1, "generated", "app"), { recursive: true });
+    const stable1 = writeLatestPointer(runs, siteId, run1);
+
+    assert.ok(existsSync(join(runs, siteId, "latest.json")), "writes latest.json breadcrumb");
+    assert.ok(stable1 && existsSync(stable1), "returned stable app path resolves through the symlink");
+    assert.equal(realpathSync(readlinkSync(join(runs, siteId, "latest"))), realpathSync(run1));
+
+    // A second run must re-point the existing symlink, not throw on the collision.
+    const run2 = join(runs, siteId, "20260701-200000");
+    mkdirSync(join(run2, "generated", "app"), { recursive: true });
+    const stable2 = writeLatestPointer(runs, siteId, run2);
+
+    assert.equal(realpathSync(readlinkSync(join(runs, siteId, "latest"))), realpathSync(run2));
+    assert.ok(stable2 && existsSync(stable2));
+    // The stable path is timestamp-free (goes through `latest`, not the run's timestamp).
+    assert.match(stable2!, /example\.com\/latest\/generated\/app$/);
+  });
+});