@design-drafts/cli 0.0.0 → 0.2.0

package/dist/index.mjs

@@ -0,0 +1,1396 @@
+import { createHash } from "node:crypto";
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { cli } from "cli-forge";
+import { confirm, isCancel, select, text } from "@clack/prompts";
+import { execSync, spawn } from "node:child_process";
+import { createServer } from "node:http";
+//#region package.json
+var version = "0.2.0";
+//#endregion
+//#region src/config.ts
+const CONFIG_FILENAME = "design-drafts.config.json";
+const DEFAULT_PREFIX = "drafts/";
+const homeConfigPath = join(homedir(), CONFIG_FILENAME);
+const homeJsonProvider = {
+	resolve: () => existsSync(homeConfigPath) ? homeConfigPath : void 0,
+	load: (filename) => JSON.parse(readFileSync(filename, "utf-8"))
+};
+function readConfig(configPath) {
+	return existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : {};
+}
+/** Reads a single key from the home config without prompting. Used by the magic
+* `init` to decide whether the host has already been set up. */
+function readHomeConfigValue(key) {
+	const value = readConfig(homeConfigPath)[key];
+	return typeof value === "string" ? value : void 0;
+}
+/** Resolves a value, prompting (with optional validation) when it's missing.
+* Does NOT persist — callers that want the answer remembered should call
+* `persistHomeConfigValue` only after the operation it feeds succeeds, so a
+* value that led nowhere (e.g. a repo that failed to push) never becomes a
+* sticky default. */
+async function promptForValue(existing, label, promptMessage, validate) {
+	if (existing) return existing;
+	const value = await text({
+		message: promptMessage,
+		validate: (v) => {
+			if (!v?.trim()) return `${label} is required`;
+			return validate?.(v);
+		}
+	});
+	if (typeof value !== "string") process.exit(1);
+	return value;
+}
+function persistHomeConfigValue(key, value) {
+	const previousFile = readConfig(homeConfigPath);
+	if (previousFile[key] === value) return;
+	writeFileSync(homeConfigPath, JSON.stringify({
+		...previousFile,
+		[key]: value
+	}, null, 2) + "\n");
+}
+function resolvePrefix(existing) {
+	if (typeof existing === "string") {
+		persistHomeConfigValue("prefix", existing);
+		return existing;
+	}
+	persistHomeConfigValue("prefix", DEFAULT_PREFIX);
+	return DEFAULT_PREFIX;
+}
+//#endregion
+//#region src/errors.ts
+/**
+* An expected, user-facing failure. The top-level handler prints its message
+* verbatim (no stack trace) and exits non-zero. Use it for situations the user
+* can act on — a push that was rejected, a template that couldn't be fetched —
+* as opposed to programmer errors, which should surface as ordinary Errors.
+*/
+var CliError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CliError";
+	}
+};
+/** Prints a failure as a single clean message and exits non-zero. A CliError's
+* message is shown verbatim; anything else is an unexpected bug, labelled as
+* such (with the stack only under DESIGN_DRAFTS_DEBUG). */
+function reportError(error) {
+	if (error instanceof CliError) console.error(`\n${error.message}`);
+	else if (process.env.DESIGN_DRAFTS_DEBUG) console.error(error);
+	else {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(`\nUnexpected error: ${message}\nRe-run with DESIGN_DRAFTS_DEBUG=1 for details.`);
+	}
+	process.exit(1);
+}
+/**
+* Runs a command handler, converting any thrown failure into a clean message +
+* non-zero exit. We catch and exit here rather than letting the error escape,
+* because cli-forge's own runCommand catch prints the raw error (with stack)
+* and the help text — exiting first keeps the output clean.
+*/
+async function runHandler(fn) {
+	try {
+		await fn();
+	} catch (error) {
+		reportError(error);
+	}
+}
+//#endregion
+//#region src/exec.ts
+/** Runs a command, streaming its output to the user's terminal. Throws on a
+* non-zero exit. */
+function exec(command, cwd) {
+	execSync(command, {
+		cwd,
+		stdio: "inherit"
+	});
+}
+/** Runs a command and returns its trimmed stdout, or undefined if it fails or
+* produces no output. Stderr is suppressed — callers use this to probe state
+* (does this tag exist? is gh authed?) where failure is an expected answer. */
+function capture(command, cwd) {
+	try {
+		return execSync(command, {
+			cwd,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).toString("utf-8").trim() || void 0;
+	} catch {
+		return;
+	}
+}
+/** True when the command exits zero. */
+function succeeds(command, cwd) {
+	try {
+		execSync(command, {
+			cwd,
+			stdio: "ignore"
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/github.ts
+/**
+* Picks a remote URL for a GitHub repo using auth that actually works.
+*
+* `gh config get git_protocol` reflects the transport the user authenticated
+* with — if they set up gh over HTTPS, gh installs a git credential helper and
+* HTTPS pushes succeed while SSH would fail (no key), and vice versa. We honor
+* that signal and fall back to SSH (git's traditional default) when gh isn't
+* present to ask.
+*/
+function githubRemoteUrl(repo, cwd) {
+	if (capture("gh config get git_protocol", cwd) === "https") return `https://github.com/${repo}.git`;
+	return `git@github.com:${repo}.git`;
+}
+//#endregion
+//#region src/site-name.ts
+const SITE_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]{0,62}$/;
+function slugifySiteName(input) {
+	return input.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+/, "").replace(/-+$/, "").replace(/^[-_]+/, "").slice(0, 63);
+}
+function validateSiteName(name) {
+	if (!name || !name.trim()) return {
+		ok: false,
+		reason: "site-name must not be empty"
+	};
+	if (name.length > 63) return {
+		ok: false,
+		reason: "site-name must be 63 characters or fewer",
+		suggestion: slugifySiteName(name) || void 0
+	};
+	if (!SITE_NAME_PATTERN.test(name)) return {
+		ok: false,
+		reason: "site-name must start with a lowercase letter or digit and contain only lowercase letters, digits, hyphens, or underscores",
+		suggestion: slugifySiteName(name) || void 0
+	};
+	return { ok: true };
+}
+//#endregion
+//#region src/init/templates.ts
+const HOST_MARKER = "# design-drafts: host deploy workflow";
+const DEPLOY_WORKFLOW = `${HOST_MARKER}
+name: Deploy Preview
+
+on:
+  push:
+    branches:
+      - 'drafts/**'
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: [main]
+  delete:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'Branch to deploy a preview for'
+        required: true
+        type: string
+
+# The gh-pages branch is the durable store of every preview (NOT the Pages
+# source — Pages serves the artifact uploaded below). Each run reconstructs the
+# full site from gh-pages, swaps in the changed preview, and republishes.
+concurrency:
+  group: deploy-preview
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: |
+      (github.event_name == 'push' && startsWith(github.ref_name, 'drafts/')) ||
+      (github.event_name == 'pull_request' && startsWith(github.head_ref, 'drafts/')) ||
+      (github.event_name == 'delete' && github.event.ref_type == 'branch' && startsWith(github.event.ref, 'drafts/')) ||
+      github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: write
+    env:
+      BRANCH_NAME: \${{ inputs.branch || github.head_ref || github.ref_name }}
+      DRAFT_BRANCH_PREFIX: drafts/
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Configure git identity
+        run: |
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
+
+      - name: Checkout gh-pages store to staging
+        run: |
+          if git fetch origin gh-pages:gh-pages 2>/dev/null; then
+            git worktree add .gh-pages-staging gh-pages
+          else
+            echo "gh-pages store does not exist yet, starting fresh"
+            git worktree add --orphan -b gh-pages .gh-pages-staging
+          fi
+
+      - name: Resolve preview directory name
+        run: |
+          if [ "\${{ github.event_name }}" = "delete" ]; then
+            BRANCH_NAME="\${{ github.event.ref }}"
+          fi
+          # Strip the draft prefix so branch "drafts/my-site" maps to "/my-site/".
+          PREVIEW_DIR="\${BRANCH_NAME#\${DRAFT_BRANCH_PREFIX}}"
+          if [ -z "$PREVIEW_DIR" ] || [ "$PREVIEW_DIR" = "$BRANCH_NAME" ]; then
+            PREVIEW_DIR="$BRANCH_NAME"
+          fi
+          echo "PREVIEW_DIR=$PREVIEW_DIR" >> "$GITHUB_ENV"
+
+      - name: Stage branch content
+        if: github.event_name != 'delete'
+        run: |
+          git clone --depth 1 --branch "$BRANCH_NAME" \\
+            "https://x-access-token:\${{ secrets.GITHUB_TOKEN }}@github.com/\${{ github.repository }}.git" \\
+            /tmp/branch-content
+          rm -rf /tmp/branch-content/.git
+          # The CLI embeds this workflow on the draft branch so the push event
+          # can resolve it. Strip it back out so it never ships into the preview.
+          rm -rf /tmp/branch-content/.github
+          rm -rf ".gh-pages-staging/\${PREVIEW_DIR}"
+          mkdir -p ".gh-pages-staging/\${PREVIEW_DIR}"
+          cp -a /tmp/branch-content/. ".gh-pages-staging/\${PREVIEW_DIR}/"
+
+      - name: Remove deleted branch's directory
+        if: github.event_name == 'delete'
+        run: rm -rf ".gh-pages-staging/\${PREVIEW_DIR}"
+
+      - name: Build index site
+        run: pnpm build
+        env:
+          PAGES_DIR: \${{ github.workspace }}/.gh-pages-staging
+          DESIGN_DRAFTS_PREFIX: drafts/
+          DESIGN_DRAFTS_REPO: \${{ github.repository }}
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+
+      - name: Copy index site into staging
+        run: |
+          cp -r dist/client/* .gh-pages-staging/ 2>/dev/null || true
+          touch .gh-pages-staging/.nojekyll
+
+      - name: Persist preview store to gh-pages
+        run: |
+          cd .gh-pages-staging
+          git add -A
+          git commit -m "deploy: \${PREVIEW_DIR}" || echo "no changes to persist"
+          git push origin HEAD:gh-pages
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .gh-pages-staging
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+`;
+const GITIGNORE = `node_modules
+dist
+.gh-pages-staging
+`;
+/**
+* The starter manifest written by `init draft`. It is a valid DraftManifest
+* (see `@design-drafts/conventions`): a single-page, axis-free proposal whose
+* one page is `index.html`. A schema-valid manifest matters because the toolbar
+* silently no-ops on a manifest missing `name`/`pages`, so a stub with the wrong
+* shape would leave a fresh draft without a working toolbar. The push command
+* reads the `prompt` field for the commit trailer; the author fills in `axes`
+* and additional `pages` as the draft grows.
+*/
+function draftConfig(siteName, createdAt) {
+	return JSON.stringify({
+		$schema: "https://design-drafts.dev/schemas/draft-manifest.schema.json",
+		name: siteName,
+		prompt: "",
+		pages: [{
+			coordinates: {},
+			path: "index.html"
+		}],
+		createdAt
+	}, null, 2) + "\n";
+}
+const DRAFT_INDEX_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Draft preview</title>
+  </head>
+  <body>
+    <main>
+      <h1>Draft preview</h1>
+      <p>Replace this with your design draft, then run <code>design-drafts</code> to publish.</p>
+    </main>
+
+    <!--
+      design-drafts overlays, loaded from the CDN — no build step, no file to copy:
+        - toolbar:  switches between the axes declared in design-drafts.config.json
+        - annotate: lets reviewers leave comments anchored to the page
+      Both are inert until they have something to do (the toolbar needs a
+      design-drafts.config.json; annotate waits for ?annotate=1 or its toggle), so they
+      are safe to keep on every page. Pinned to the current major (@0); drop a
+      tag to remove that overlay, or bump the pin when you upgrade. See each
+      package's README for self-hosting and version options.
+    -->
+    <script src="https://unpkg.com/@design-drafts/toolbar@0/dist/toolbar.js" defer><\/script>
+    <script src="https://unpkg.com/@design-drafts/annotate@0/dist/annotate.js" defer><\/script>
+  </body>
+</html>
+`;
+//#endregion
+//#region src/init/draft.ts
+/** Writes the file only if it is absent, logging which path it created and
+* which it left untouched. Returns true when a file was written. */
+function writeIfAbsent(filePath, contents) {
+	const name = basename(filePath);
+	if (existsSync(filePath)) {
+		console.log(`  skipped ${name} (already exists)`);
+		return false;
+	}
+	writeFileSync(filePath, contents);
+	console.log(`  created ${name}`);
+	return true;
+}
+async function initDraft(opts) {
+	const targetDir = resolve(opts.path);
+	if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
+	let siteName = await promptForValue(opts.siteName, "site-name", "Site name for this draft:");
+	const validation = validateSiteName(siteName);
+	if (!validation.ok) {
+		const fixed = validation.suggestion ?? slugifySiteName(siteName);
+		console.warn(`"${siteName}" is not a valid site-name (${validation.reason}); using "${fixed}".`);
+		siteName = fixed;
+	}
+	console.log(`\nScaffolding draft "${siteName}" in ${targetDir}:`);
+	const wroteManifest = writeIfAbsent(join(targetDir, "design-drafts.config.json"), draftConfig(siteName, (/* @__PURE__ */ new Date()).toISOString()));
+	const wroteIndex = writeIfAbsent(join(targetDir, "index.html"), DRAFT_INDEX_HTML);
+	if (!wroteManifest && !wroteIndex) {
+		console.log(`\nDraft "${siteName}" was already scaffolded; nothing to write.`);
+		return;
+	}
+	console.log(`\nDraft "${siteName}" ready.\nEdit index.html, then run \`design-drafts\` here to publish a preview.`);
+}
+//#endregion
+//#region src/validate.ts
+const REPO_PATTERN = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+const PREFIX_PATTERN = /^[A-Za-z0-9._/-]*$/;
+const REF_PATTERN = /^[A-Za-z0-9._/-]+$/;
+function validateRepo(repo) {
+	if (!repo.trim()) return {
+		ok: false,
+		reason: "repo must not be empty"
+	};
+	if (!REPO_PATTERN.test(repo)) return {
+		ok: false,
+		reason: "repo must be in \"owner/name\" form using only letters, digits, \".\", \"_\", or \"-\""
+	};
+	return { ok: true };
+}
+function validatePrefix(prefix) {
+	if (!PREFIX_PATTERN.test(prefix)) return {
+		ok: false,
+		reason: "prefix may contain only letters, digits, \"/\", \".\", \"_\", or \"-\""
+	};
+	return { ok: true };
+}
+function validateTemplateRef(ref) {
+	if (!REF_PATTERN.test(ref)) return {
+		ok: false,
+		reason: "template-ref may contain only letters, digits, \"/\", \".\", \"_\", or \"-\""
+	};
+	return { ok: true };
+}
+//#endregion
+//#region src/init/rewrites.ts
+const CATALOG_PREFIX = "catalog:";
+function resolveDepBlock(block, catalog) {
+	if (!block) return block;
+	const resolved = {};
+	for (const [name, spec] of Object.entries(block)) {
+		if (!spec.startsWith(CATALOG_PREFIX)) {
+			resolved[name] = spec;
+			continue;
+		}
+		if (spec.slice(8)) throw new Error(`Cannot resolve "${name}": named catalogs ("${spec}") are not supported`);
+		const version = catalog[name];
+		if (!version) throw new Error(`Cannot resolve "${name}": "${spec}" but no catalog entry exists for it`);
+		resolved[name] = version;
+	}
+	return resolved;
+}
+/**
+* Rewrites a site package.json for life in a standalone host repo: every
+* `catalog:` dependency specifier is replaced with the concrete version from
+* the canonical workspace catalog, the nx project config is removed, and a
+* `packageManager` field is set (so `pnpm/action-setup` can resolve a version
+* in the generated repo — without it the first deploy fails).
+*/
+function resolveSitePackageJson(raw, catalog, packageManager) {
+	const pkg = JSON.parse(raw);
+	const next = { ...pkg };
+	next.dependencies = resolveDepBlock(pkg.dependencies, catalog);
+	next.devDependencies = resolveDepBlock(pkg.devDependencies, catalog);
+	delete next.nx;
+	if (packageManager) next.packageManager = packageManager;
+	if (next.dependencies && Object.keys(next.dependencies).length === 0) delete next.dependencies;
+	if (next.devDependencies && Object.keys(next.devDependencies).length === 0) delete next.devDependencies;
+	return JSON.stringify(next, null, 2) + "\n";
+}
+/**
+* Parses the `catalog:` block out of a canonical pnpm-workspace.yaml. We keep
+* the parser intentionally small (flat `key: value` pairs under `catalog:`)
+* rather than pulling in a YAML dependency — the catalog is always a flat map
+* of package name to version string.
+*/
+function parseCatalog(workspaceYaml) {
+	const lines = workspaceYaml.split("\n");
+	const catalog = {};
+	let inCatalog = false;
+	let catalogIndent = 0;
+	for (const line of lines) {
+		if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
+		const indent = line.length - line.trimStart().length;
+		if (!inCatalog) {
+			if (line.trim() === "catalog:") {
+				inCatalog = true;
+				catalogIndent = indent;
+			}
+			continue;
+		}
+		if (indent <= catalogIndent) break;
+		const match = line.trim().match(/^['"]?([^'":]+)['"]?\s*:\s*(.+)$/);
+		if (match) {
+			const name = match[1].trim();
+			catalog[name] = match[2].trim().replace(/^['"]|['"]$/g, "");
+		}
+	}
+	return catalog;
+}
+/**
+* Rewrites the Vite `base` so asset URLs resolve under the host repo's Pages
+* subpath (https://<owner>.github.io/<repo>/). Accepts `org/repo` or a bare
+* repo name and uses just the repo segment.
+*/
+function rewriteViteBase(source, repo) {
+	const base = `/${repo.includes("/") ? repo.split("/").pop() : repo}/`;
+	const replaced = source.replace(/base:\s*(['"])(?:[^'"]*)\1/, `base: '${base}'`);
+	if (replaced === source) throw new Error("Could not find a `base:` option in vite.config to rewrite");
+	return replaced;
+}
+/**
+* Folds the canonical base tsconfig's compilerOptions into the site tsconfig and
+* drops `extends`, so the host needs no `tsconfig.base.json` at its root. The
+* site's own compilerOptions win on conflict.
+*/
+function inlineTsconfig(siteRaw, baseRaw) {
+	const site = JSON.parse(siteRaw);
+	const base = JSON.parse(baseRaw);
+	const merged = { ...site };
+	delete merged.extends;
+	merged.compilerOptions = {
+		...base.compilerOptions ?? {},
+		...site.compilerOptions ?? {}
+	};
+	return JSON.stringify(merged, null, 2) + "\n";
+}
+/**
+* Picks the template ref to check the site out from. An explicit override wins;
+* otherwise prefer the release tag matching the CLI version when it exists,
+* falling back to the default branch.
+*/
+function resolveTemplateRef(opts) {
+	if (opts.override) return opts.override;
+	const tag = `v${opts.cliVersion}`;
+	if (opts.tagExists(tag)) return tag;
+	return opts.defaultBranch;
+}
+//#endregion
+//#region src/init/host.ts
+const CANONICAL_REPO = "AgentEnder/design-drafts";
+const CANONICAL_URL = `https://github.com/${CANONICAL_REPO}.git`;
+const DEFAULT_BRANCH$1 = "main";
+const SITE_SUBDIR = "packages/site";
+const WORKFLOW_PATH$1 = ".github/workflows/deploy-preview.yml";
+const TRANSFORMED = new Set([
+	"package.json",
+	"vite.config.ts",
+	"tsconfig.json"
+]);
+function repoName(repo) {
+	return repo.includes("/") ? repo.split("/").pop() : repo;
+}
+function detectRemoteRepo(targetDir) {
+	const url = capture("git remote get-url origin", targetDir);
+	if (!url) return void 0;
+	return url.match(/github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?$/)?.[1];
+}
+/** True when the target already carries our generated workflow. */
+function alreadyConfigured(targetDir) {
+	const workflow = join(targetDir, WORKFLOW_PATH$1);
+	if (!existsSync(workflow)) return false;
+	return readFileSync(workflow, "utf-8").includes(HOST_MARKER);
+}
+/** Sparse-checks-out the canonical site source into a temp dir, returning that
+* path. Cone mode (the recommended default) always materialises top-level
+* files, so the root files we read to resolve the site (pnpm-workspace.yaml's
+* catalog and tsconfig.base.json) come along without listing them, while the
+* sibling packages stay excluded. */
+function sparseCheckout(ref) {
+	const tmp = mkdtempSync(join(tmpdir(), "design-drafts-host-"));
+	try {
+		exec(`git clone --filter=blob:none --no-checkout ${CANONICAL_URL} .`, tmp);
+		exec(`git sparse-checkout set ${SITE_SUBDIR}`, tmp);
+		exec(`git checkout ${ref}`, tmp);
+	} catch {
+		rmSync(tmp, {
+			recursive: true,
+			force: true
+		});
+		throw new CliError(`Could not fetch the host template from ${CANONICAL_REPO}@${ref}.\nCheck your network connection and that the ref exists (try --template-ref main).`);
+	}
+	return tmp;
+}
+function writeScaffold(checkout, targetDir, repo) {
+	const siteDir = join(checkout, SITE_SUBDIR);
+	cpSync(siteDir, targetDir, {
+		recursive: true,
+		filter: (src) => !TRANSFORMED.has(src.slice(siteDir.length + 1))
+	});
+	const catalog = parseCatalog(readFileSync(join(checkout, "pnpm-workspace.yaml"), "utf-8"));
+	const rootPkg = JSON.parse(readFileSync(join(checkout, "package.json"), "utf-8"));
+	writeFileSync(join(targetDir, "package.json"), resolveSitePackageJson(readFileSync(join(siteDir, "package.json"), "utf-8"), catalog, rootPkg.packageManager));
+	const viteRaw = readFileSync(join(siteDir, "vite.config.ts"), "utf-8");
+	writeFileSync(join(targetDir, "vite.config.ts"), rewriteViteBase(viteRaw, repo));
+	writeFileSync(join(targetDir, "tsconfig.json"), inlineTsconfig(readFileSync(join(siteDir, "tsconfig.json"), "utf-8"), readFileSync(join(checkout, "tsconfig.base.json"), "utf-8")));
+	const workflowDest = join(targetDir, WORKFLOW_PATH$1);
+	mkdirSync(dirname(workflowDest), { recursive: true });
+	writeFileSync(workflowDest, DEPLOY_WORKFLOW);
+	writeFileSync(join(targetDir, ".nojekyll"), "");
+	writeFileSync(join(targetDir, ".gitignore"), GITIGNORE);
+}
+function commitScaffold(targetDir) {
+	if (!existsSync(join(targetDir, ".git"))) exec(`git init -b ${DEFAULT_BRANCH$1}`, targetDir);
+	exec("git add .", targetDir);
+	if (capture("git status --porcelain", targetDir)) exec("git commit -m \"chore: scaffold design-drafts host\"", targetDir);
+}
+/** Best-effort GitHub wiring. Never hard-fails: the local scaffold already
+* succeeded, so any gh gap becomes printed manual steps. Returns true when the
+* repo is set up and pushed (so the caller can discard a throwaway scaffold). */
+function configureGitHub(targetDir, repo, isPrivate) {
+	if (!succeeds("gh auth status", targetDir)) {
+		printManualSteps(repo, targetDir, isPrivate, "GitHub CLI (`gh`) is not installed or authenticated");
+		return false;
+	}
+	const visibility = isPrivate ? "--private" : "--public";
+	if (!succeeds(`gh repo view ${repo}`, targetDir)) {
+		if (!succeeds(`gh repo create ${repo} ${visibility} --source ${JSON.stringify(targetDir)} --remote origin --push`, targetDir)) {
+			printManualSteps(repo, targetDir, isPrivate, `could not create ${repo}`);
+			return false;
+		}
+		enablePages(targetDir, repo, isPrivate);
+		return true;
+	}
+	if (!detectRemoteRepo(targetDir)) exec(`git remote add origin ${githubRemoteUrl(repo, targetDir)}`, targetDir);
+	if (!succeeds(`git push -u origin ${DEFAULT_BRANCH$1}`, targetDir)) {
+		printManualSteps(repo, targetDir, isPrivate, `could not push to ${repo} (does its ${DEFAULT_BRANCH$1} already have commits?)`);
+		return false;
+	}
+	enablePages(targetDir, repo, isPrivate);
+	return true;
+}
+/** Sets the Pages source to "GitHub Actions" (build_type=workflow). */
+function enablePages(targetDir, repo, isPrivate) {
+	const create = `gh api -X POST /repos/${repo}/pages -f build_type=workflow`;
+	const update = `gh api -X PUT /repos/${repo}/pages -f build_type=workflow`;
+	if (succeeds(create, targetDir) || succeeds(update, targetDir)) {
+		console.log(`Enabled GitHub Pages (Actions source) on ${repo}.`);
+		return;
+	}
+	console.warn(`Warning: could not enable GitHub Pages on ${repo}.${isPrivate ? " Private repos need GitHub Pro/Team for Pages — make the repo public or upgrade." : ""}\nEnable it manually: Settings -> Pages -> Build and deployment -> Source: GitHub Actions.`);
+}
+function printManualSteps(repo, targetDir, isPrivate, reason) {
+	console.warn(`\nScaffold is at ${targetDir}, but GitHub setup was skipped (${reason}).\nFinish manually:\n  gh repo create ${repo} ${isPrivate ? "--private" : "--public"} --source ${JSON.stringify(targetDir)} --remote origin --push\n  Settings -> Pages -> Source: GitHub Actions\n`);
+}
+/** Resolves repo visibility, prompting interactively when not preset. */
+async function resolveVisibility(opts) {
+	if (typeof opts.private === "boolean") return opts.private;
+	const choice = await select({
+		message: "Repository visibility:",
+		options: [{
+			value: false,
+			label: "Public",
+			hint: "required for free GitHub Pages"
+		}, {
+			value: true,
+			label: "Private",
+			hint: "Pages needs GitHub Pro/Team"
+		}],
+		initialValue: false
+	});
+	if (isCancel(choice)) process.exit(1);
+	return choice;
+}
+/** Confirmation gate before the outward GitHub actions (create/push/Pages). */
+async function confirmGitHub(repo, isPrivate) {
+	const answer = await confirm({ message: `Create ${isPrivate ? "private" : "public"} repo ${repo} on GitHub, push the scaffold, and enable Pages?` });
+	if (isCancel(answer)) process.exit(1);
+	return answer === true;
+}
+async function initHost(opts) {
+	const usingTmp = !opts.path;
+	const targetDir = opts.path ? resolve(opts.path) : mkdtempSync(join(tmpdir(), "design-drafts-host-scaffold-"));
+	if (opts.path && !existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
+	const repo = await promptForValue(opts.repo ?? readHomeConfigValue("repo") ?? (opts.path ? detectRemoteRepo(targetDir) : void 0), "repo", "GitHub repo for the host (org/repo):", (v) => validateRepo(v).ok ? void 0 : "use \"owner/name\" form");
+	const repoCheck = validateRepo(repo);
+	if (!repoCheck.ok) {
+		console.error(`Invalid repo "${repo}": ${repoCheck.reason}`);
+		process.exit(1);
+	}
+	if (opts.templateRef) {
+		const refCheck = validateTemplateRef(opts.templateRef);
+		if (!refCheck.ok) {
+			console.error(`Invalid template-ref "${opts.templateRef}": ${refCheck.reason}`);
+			process.exit(1);
+		}
+	}
+	if (opts.path && alreadyConfigured(targetDir)) {
+		console.log(`Host already configured at ${targetDir}; re-ensuring Pages.`);
+		enablePages(targetDir, repo, opts.private ?? false);
+		return;
+	}
+	const ref = resolveTemplateRef({
+		override: opts.templateRef,
+		cliVersion: opts.cliVersion,
+		defaultBranch: DEFAULT_BRANCH$1,
+		tagExists: (tag) => Boolean(capture(`git ls-remote --tags ${CANONICAL_URL} ${tag}`, targetDir))
+	});
+	console.log(`Scaffolding host "${repoName(repo)}" from ${CANONICAL_REPO}@${ref}...`);
+	const checkout = sparseCheckout(ref);
+	try {
+		writeScaffold(checkout, targetDir, repo);
+	} finally {
+		rmSync(checkout, {
+			recursive: true,
+			force: true
+		});
+	}
+	commitScaffold(targetDir);
+	const isPrivate = await resolveVisibility(opts);
+	if (!(opts.yes || await confirmGitHub(repo, isPrivate))) {
+		console.log(`\nStopped before GitHub setup. The scaffold is at ${targetDir}.`);
+		printManualSteps(repo, targetDir, isPrivate, "cancelled");
+		return;
+	}
+	const pushed = configureGitHub(targetDir, repo, isPrivate);
+	if (pushed) persistHomeConfigValue("repo", repo);
+	if (!usingTmp) {
+		console.log(`\nHost scaffolded at ${targetDir}.`);
+		return;
+	}
+	if (pushed) {
+		rmSync(targetDir, {
+			recursive: true,
+			force: true
+		});
+		console.log(`\nHost ready at https://github.com/${repo} (local scaffold discarded).`);
+	} else console.log(`\nKept the scaffold at ${targetDir} so you can finish the push.`);
+}
+//#endregion
+//#region src/init/init.ts
+/**
+* The "from nothing to ready-to-publish" path. Scaffolds a host the first time
+* (detected by the absence of a configured `repo`), then scaffolds a draft in
+* the target directory. Stops short of auto-pushing a placeholder — it prints
+* the single command to publish instead.
+*/
+async function init(opts) {
+	if (!Boolean(opts.repo ?? readHomeConfigValue("repo"))) {
+		console.log("No host configured yet — setting one up first.\n");
+		await initHost({
+			repo: opts.repo,
+			templateRef: opts.templateRef,
+			cliVersion: opts.cliVersion
+		});
+		console.log("");
+	}
+	await initDraft({
+		path: opts.path,
+		siteName: opts.siteName
+	});
+	console.log("\nWhen the draft looks right, run `design-drafts` to publish.");
+}
+//#endregion
+//#region src/draft-dir.ts
+/**
+* Resolves the draft directory a command should act on: the explicit path when
+* given, otherwise the current working directory. Throws when the resolved
+* directory has no `design-drafts.config.json`, so callers fail with an
+* actionable message instead of silently operating on a non-draft directory.
+*/
+function resolveDraftDir(explicit) {
+	const candidate = resolve(explicit ?? process.cwd());
+	if (!existsSync(join(candidate, "design-drafts.config.json"))) throw new Error(`No design-drafts.config.json at ${candidate}. Run from inside a draft directory or pass --draft <dir>.`);
+	return candidate;
+}
+//#endregion
+//#region src/preview.ts
+const DEFAULT_PORT = 4321;
+const PORT_SCAN_ATTEMPTS = 20;
+const MIME_TYPES = {
+	".html": "text/html; charset=utf-8",
+	".htm": "text/html; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".map": "application/json; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp",
+	".gif": "image/gif",
+	".ico": "image/x-icon",
+	".avif": "image/avif",
+	".woff": "font/woff",
+	".woff2": "font/woff2",
+	".ttf": "font/ttf",
+	".otf": "font/otf",
+	".txt": "text/plain; charset=utf-8",
+	".md": "text/markdown; charset=utf-8"
+};
+/** Maps a file path to a Content-Type by extension, defaulting to a generic
+* binary type for anything unrecognised. */
+function contentTypeFor(filePath) {
+	return MIME_TYPES[extname(filePath).toLowerCase()] ?? "application/octet-stream";
+}
+/**
+* Resolves a request URL to an absolute path inside `draftDir`, or `null` when
+* the request is malformed or tries to escape the draft root.
+*
+* The query string and hash are stripped, percent-escapes are decoded (so an
+* encoded `..` can't sneak past), and the result is confirmed to live under
+* `draftDir` via a `relative()` check. The returned path may be a file or a
+* directory — the caller decides how to serve it.
+*/
+function resolveServedFile(draftDir, urlPath) {
+	const withoutQuery = urlPath.split("?")[0].split("#")[0];
+	let decoded;
+	try {
+		decoded = decodeURIComponent(withoutQuery);
+	} catch {
+		return null;
+	}
+	const candidate = resolve(draftDir, "." + (decoded.startsWith("/") ? decoded : `/${decoded}`));
+	const rel = relative(draftDir, candidate);
+	if (rel && (rel.startsWith("..") || isAbsolute(rel))) return null;
+	return candidate;
+}
+/**
+* Recursively collects every `.html` file beneath `dir`, returned as
+* root-relative POSIX paths (e.g. `pages/sub/p.html`) sorted for stable output.
+* Used to build the generated index when a directory has no index.html.
+*/
+function collectHtmlPages(dir) {
+	const pages = [];
+	const walk = (current) => {
+		for (const entry of readdirSync(current, { withFileTypes: true })) {
+			const abs = join(current, entry.name);
+			if (entry.isDirectory()) walk(abs);
+			else if (entry.isFile() && extname(entry.name).toLowerCase() === ".html") pages.push(relative(dir, abs).split(sep).join("/"));
+		}
+	};
+	walk(dir);
+	return pages.sort();
+}
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/**
+* Renders a fallback index page that links to every `.html` page in the draft,
+* shown when the requested directory has no index.html of its own. Links are
+* root-absolute so they resolve regardless of which directory was requested.
+*/
+function renderDirectoryIndex(draftDir) {
+	const pages = collectHtmlPages(draftDir);
+	return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Draft pages</title>
+    <style>
+      body { font: 16px/1.5 system-ui, sans-serif; margin: 3rem auto; max-width: 40rem; padding: 0 1rem; }
+      h1 { font-size: 1.25rem; }
+      ul { list-style: none; padding: 0; }
+      li { margin: 0.25rem 0; }
+      a { color: #2563eb; text-decoration: none; }
+      a:hover { text-decoration: underline; }
+      .empty { color: #6b7280; }
+    </style>
+  </head>
+  <body>
+    <h1>Draft pages</h1>
+    <p>No <code>index.html</code> here — listing the pages in this draft:</p>
+    <ul>
+${pages.length ? pages.map((page) => `        <li><a href="/${page}">${escapeHtml(page)}</a></li>`).join("\n") : "        <li class=\"empty\">No pages found in this draft yet.</li>"}
+    </ul>
+  </body>
+</html>
+`;
+}
+/** Builds the static file server for a draft directory without binding it to a
+* port, so it can be exercised directly in tests. */
+function createPreviewServer(draftDir) {
+	return createServer((req, res) => {
+		const safePath = resolveServedFile(draftDir, req.url ?? "/");
+		if (safePath === null) {
+			res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
+			res.end("Forbidden");
+			return;
+		}
+		try {
+			let filePath = safePath;
+			if (statSync(filePath).isDirectory()) {
+				const indexPath = join(filePath, "index.html");
+				if (!existsSync(indexPath)) {
+					const listing = renderDirectoryIndex(draftDir);
+					res.writeHead(200, {
+						"Content-Type": "text/html; charset=utf-8",
+						"Content-Length": Buffer.byteLength(listing)
+					});
+					res.end(listing);
+					return;
+				}
+				filePath = indexPath;
+			}
+			const body = readFileSync(filePath);
+			res.writeHead(200, {
+				"Content-Type": contentTypeFor(filePath),
+				"Content-Length": body.length
+			});
+			res.end(body);
+		} catch {
+			res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+			res.end("Not found");
+		}
+	});
+}
+/**
+* Binds the server to a port. With an explicit `requestedPort` we try only that
+* port and surface a clear error if it's taken; without one we scan upward from
+* the default until a free port is found.
+*/
+function listen(server, requestedPort) {
+	const startPort = requestedPort ?? DEFAULT_PORT;
+	const maxAttempts = requestedPort === void 0 ? PORT_SCAN_ATTEMPTS : 1;
+	const tryPort = (port, attempt) => new Promise((resolvePort, rejectPort) => {
+		const onError = (error) => {
+			server.removeListener("listening", onListening);
+			if (error.code === "EADDRINUSE" && attempt + 1 < maxAttempts) {
+				resolvePort(tryPort(port + 1, attempt + 1));
+				return;
+			}
+			if (error.code === "EADDRINUSE") {
+				rejectPort(new CliError(`Port ${port} is already in use. Pass --port <n> to pick another.`));
+				return;
+			}
+			rejectPort(error);
+		};
+		const onListening = () => {
+			server.removeListener("error", onError);
+			resolvePort(port);
+		};
+		server.once("error", onError);
+		server.once("listening", onListening);
+		server.listen(port, "localhost");
+	});
+	return tryPort(startPort, 0);
+}
+/** Opens the given URL in the user's default browser. Best-effort: a missing
+* opener or a spawn failure is swallowed so it never breaks the server. */
+function openBrowser(url) {
+	const { platform } = process;
+	const [command, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", [
+		"/c",
+		"start",
+		"",
+		url
+	]] : ["xdg-open", [url]];
+	try {
+		const child = spawn(command, args, {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+/** Serves a work-in-progress draft directory over HTTP for local viewing. */
+async function preview(opts) {
+	const url = `http://localhost:${await listen(createPreviewServer(resolveDraftDir(opts.draft)), opts.port)}/`;
+	console.log(`\nServing draft at ${url}`);
+	console.log("Press Ctrl+C to stop.");
+	if (opts.open !== false) openBrowser(url);
+}
+//#endregion
+//#region src/ref-add.ts
+const IMAGE_EXTENSIONS = new Set([
+	".png",
+	".webp",
+	".jpg",
+	".jpeg"
+]);
+const REFERENCES_DIRNAME = "references";
+const INSPIRATION_DIRNAME = "inspiration";
+const LINKS_FILENAME = "links.md";
+const LINKS_HEADER = "# Links\n\nAnnotated reference URLs. See `docs/conventions/references-protocol.md` — one URL per bullet, an em-dash, then a sentence saying what is being cited.\n\n";
+async function refAdd(options) {
+	const draftDir = resolveDraftDir(options.draft);
+	ensureReferencesScaffold(draftDir);
+	if (isUrl(options.source)) {
+		if (looksLikeImageUrl(options.source)) {
+			await downloadInspiration({
+				url: options.source,
+				draftDir,
+				name: options.name,
+				note: options.note
+			});
+			return;
+		}
+		if (!options.note?.trim()) throw new Error("URL references require --note explaining what is being cited (e.g. 'typography pairing, NOT the color').");
+		appendLink({
+			url: options.source,
+			draftDir,
+			note: options.note
+		});
+		return;
+	}
+	copyLocalInspiration({
+		filePath: options.source,
+		draftDir,
+		name: options.name
+	});
+}
+function isUrl(source) {
+	try {
+		const parsed = new URL(source);
+		return parsed.protocol === "http:" || parsed.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+function looksLikeImageUrl(url) {
+	const pathname = new URL(url).pathname.toLowerCase();
+	return IMAGE_EXTENSIONS.has(extname(pathname));
+}
+function ensureReferencesScaffold(draftDir) {
+	const refs = join(draftDir, REFERENCES_DIRNAME);
+	if (!existsSync(refs)) mkdirSync(refs, { recursive: true });
+	const linksPath = join(refs, LINKS_FILENAME);
+	if (!existsSync(linksPath)) writeFileSync(linksPath, LINKS_HEADER);
+}
+function appendLink({ url, draftDir, note }) {
+	const linksPath = join(draftDir, REFERENCES_DIRNAME, LINKS_FILENAME);
+	const existing = existsSync(linksPath) ? readFileSync(linksPath, "utf-8") : LINKS_HEADER;
+	const line = `- ${url} — ${note.trim()}\n`;
+	writeFileSync(linksPath, existing.endsWith("\n") ? existing + line : existing + "\n" + line);
+	process.stdout.write(`Added link to ${join(REFERENCES_DIRNAME, LINKS_FILENAME)}: ${url}\n`);
+}
+async function downloadInspiration({ url, draftDir, name, note }) {
+	const inspirationDir = join(draftDir, REFERENCES_DIRNAME, INSPIRATION_DIRNAME);
+	if (!existsSync(inspirationDir)) mkdirSync(inspirationDir, { recursive: true });
+	const ext = extname(new URL(url).pathname).toLowerCase() || ".png";
+	const finalName = uniqueFilename(inspirationDir, ensureExtension(name ?? deriveImageName(url), ext));
+	const finalPath = join(inspirationDir, finalName);
+	const response = await fetch(url);
+	if (!response.ok) throw new Error(`Failed to fetch ${url}: HTTP ${response.status}`);
+	writeFileSync(finalPath, new Uint8Array(await response.arrayBuffer()));
+	const relPath = join(REFERENCES_DIRNAME, INSPIRATION_DIRNAME, finalName);
+	process.stdout.write(`Downloaded to ${relPath}\n`);
+	if (!name) process.stdout.write(`  Heads up: filename was derived from the URL. Per the references protocol,
+  the filename IS the citation — rename to describe what's being cited
+  (e.g. linear-empty-state-density${ext}).\n`);
+	if (note?.trim()) appendLink({
+		url,
+		draftDir,
+		note: `${note.trim()} (see ${INSPIRATION_DIRNAME}/${finalName})`
+	});
+}
+function copyLocalInspiration({ filePath, draftDir, name }) {
+	const absPath = resolve(filePath);
+	if (!existsSync(absPath)) throw new Error(`File does not exist: ${absPath}`);
+	if (!statSync(absPath).isFile()) throw new Error(`Not a regular file: ${absPath}`);
+	const ext = extname(absPath).toLowerCase();
+	if (!IMAGE_EXTENSIONS.has(ext)) throw new Error(`Inspiration files must be one of ${[...IMAGE_EXTENSIONS].join(", ")} per the references protocol. Got: ${ext || "(no extension)"}`);
+	const inspirationDir = join(draftDir, REFERENCES_DIRNAME, INSPIRATION_DIRNAME);
+	if (!existsSync(inspirationDir)) mkdirSync(inspirationDir, { recursive: true });
+	const finalName = uniqueFilename(inspirationDir, ensureExtension(name ?? basename(absPath), ext));
+	copyFileSync(absPath, join(inspirationDir, finalName));
+	const relPath = join(REFERENCES_DIRNAME, INSPIRATION_DIRNAME, finalName);
+	process.stdout.write(`Copied to ${relPath}\n`);
+	if (!name) process.stdout.write("  Heads up: kept the original filename. Per the references protocol,\n  the filename IS the citation — rename to describe what's being cited.\n");
+}
+function deriveImageName(url) {
+	try {
+		const parsed = new URL(url);
+		const segments = parsed.pathname.split("/").filter(Boolean);
+		const stem = (segments[segments.length - 1] ?? "").replace(/\.[a-z0-9]+$/i, "");
+		const host = parsed.hostname.replace(/^www\./, "").replace(/\./g, "-");
+		return slugify(stem ? `${host}-${stem}` : host);
+	} catch {
+		return "reference";
+	}
+}
+function slugify(input) {
+	return input.toLowerCase().replace(/[^a-z0-9-_]+/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+}
+function ensureExtension(name, ext) {
+	return extname(name).toLowerCase() === ext.toLowerCase() ? name : `${name}${ext}`;
+}
+function uniqueFilename(dir, candidate) {
+	if (!existsSync(join(dir, candidate))) return candidate;
+	const ext = extname(candidate);
+	const stem = candidate.slice(0, candidate.length - ext.length);
+	for (let i = 2; i < 1e3; i++) {
+		const next = `${stem}-${i}${ext}`;
+		if (!existsSync(join(dir, next))) return next;
+	}
+	throw new Error(`Could not find a unique filename for ${candidate} in ${dir}`);
+}
+//#endregion
+//#region src/index.ts
+const CLI_VERSION = version;
+const DEFAULT_BRANCH = "main";
+const WORKFLOW_PATH = ".github/workflows/deploy-preview.yml";
+async function embedDeployWorkflow(repo, tmpDir) {
+	const url = `https://raw.githubusercontent.com/${repo}/${DEFAULT_BRANCH}/${WORKFLOW_PATH}`;
+	let contents;
+	try {
+		const response = await fetch(url);
+		if (!response.ok) throw new Error(`HTTP ${response.status}`);
+		contents = await response.text();
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		console.warn(`Warning: could not fetch deploy workflow from ${url} (${reason}).\nThe preview will not auto-deploy. Trigger it manually with:\n  gh workflow run deploy-preview.yml -f branch=<branch> --repo ${repo}`);
+		return;
+	}
+	const destination = join(tmpDir, WORKFLOW_PATH);
+	mkdirSync(dirname(destination), { recursive: true });
+	writeFileSync(destination, contents);
+}
+function getSourceMetadata(sourcePath) {
+	return {
+		sha: capture("git rev-parse HEAD", sourcePath),
+		repo: capture("git remote get-url origin", sourcePath),
+		authorName: capture("git config user.name", sourcePath),
+		authorEmail: capture("git config user.email", sourcePath)
+	};
+}
+function hashManifest(manifestPath) {
+	try {
+		const content = readFileSync(manifestPath, "utf-8");
+		return createHash("sha256").update(content).digest("hex");
+	} catch {
+		return;
+	}
+}
+function readManifestPrompt(manifestPath, sourcePath) {
+	let raw;
+	try {
+		raw = readFileSync(manifestPath, "utf-8");
+	} catch {
+		return;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	if (!parsed || typeof parsed !== "object" || !("prompt" in parsed)) return;
+	const prompt = parsed.prompt;
+	if (typeof prompt !== "string" || !prompt.trim()) return;
+	const candidatePath = isAbsolute(prompt) ? prompt : join(sourcePath, prompt);
+	try {
+		const stat = statSync(candidatePath);
+		if (stat.isFile() && stat.size < 200) {
+			const inline = readFileSync(candidatePath, "utf-8").trim();
+			if (inline) return inline.replace(/\s+/g, " ");
+		}
+	} catch {}
+	return prompt.replace(/\s+/g, " ");
+}
+/** Reads the manifest's human-readable `name` so the push can derive a
+* site-name from it. Returns undefined when there is no manifest, it doesn't
+* parse, or it has no usable `name`. */
+function readManifestName(manifestPath) {
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(manifestPath, "utf-8"));
+	} catch {
+		return;
+	}
+	if (!parsed || typeof parsed !== "object") return void 0;
+	const name = parsed.name;
+	return typeof name === "string" && name.trim() ? name : void 0;
+}
+/**
+* Resolves the site-name (the branch/preview directory name) for a push.
+*
+* Precedence: an explicit `--site-name` wins; otherwise we derive it from the
+* manifest's `name` by slugifying it (so "Toolbar redesign demo" becomes
+* "toolbar-redesign-demo"). Only when there is no manifest to read from do we
+* fall back to prompting. The manifest is the single per-draft store now, so we
+* never persist the answer to a separate file.
+*/
+async function resolveSiteName(explicit, manifestPath) {
+	if (explicit) return explicit;
+	const fromManifest = readManifestName(manifestPath);
+	if (fromManifest) {
+		const slug = slugifySiteName(fromManifest);
+		if (slug) return slug;
+	}
+	return promptForValue(void 0, "site-name", "Site name for this preview:");
+}
+function sanitizeAuthorName(name) {
+	return name.replace(/</g, "(").replace(/>/g, ")");
+}
+/**
+* Builds the structured commit message used for every draft push.
+*
+* Format:
+*
+*     push: <site-name>
+*
+*     source-sha: <sha>
+*     source-repo: <repo>
+*     author: <Name <email>>
+*     prompt: <one-line summary or path>
+*     draft-config-sha: <sha256 of design-drafts.config.json>
+*
+* Each trailer line is omitted when its data is unavailable (no source git
+* repo, no manifest, no `prompt` field, etc.). The site-name subject line is
+* always present.
+*/
+function buildCommitMessage(opts) {
+	const lines = [`push: ${opts.siteName}`, ""];
+	const { metadata } = opts;
+	if (metadata.sha) lines.push(`source-sha: ${metadata.sha}`);
+	if (metadata.repo) lines.push(`source-repo: ${metadata.repo}`);
+	if (metadata.authorName && metadata.authorEmail) {
+		const safeName = sanitizeAuthorName(metadata.authorName);
+		lines.push(`author: ${safeName} <${metadata.authorEmail}>`);
+	}
+	if (opts.prompt) lines.push(`prompt: ${opts.prompt}`);
+	if (opts.draftConfigSha) lines.push(`draft-config-sha: ${opts.draftConfigSha}`);
+	if (lines.length === 2) lines.pop();
+	return lines.join("\n") + "\n";
+}
+async function pushHandler(args) {
+	const repo = await promptForValue(args.repo, "repo", "GitHub repo (org/repo):", (v) => validateRepo(v).ok ? void 0 : "use \"owner/name\" form");
+	const sourcePath = resolve(args.path ?? ".");
+	if (!existsSync(sourcePath)) {
+		console.error(`Path does not exist: ${sourcePath}`);
+		process.exit(1);
+	}
+	const manifestPath = join(sourcePath, "design-drafts.config.json");
+	const siteName = await resolveSiteName(args["site-name"], manifestPath);
+	const prefix = resolvePrefix(args.prefix);
+	const validation = validateSiteName(siteName);
+	if (!validation.ok) {
+		console.error(`Invalid site-name "${siteName}": ${validation.reason}`);
+		if (validation.suggestion) console.error(`Try: ${validation.suggestion}`);
+		process.exit(1);
+	}
+	const repoCheck = validateRepo(repo);
+	if (!repoCheck.ok) {
+		console.error(`Invalid repo "${repo}": ${repoCheck.reason}`);
+		process.exit(1);
+	}
+	const prefixCheck = validatePrefix(prefix);
+	if (!prefixCheck.ok) {
+		console.error(`Invalid prefix "${prefix}": ${prefixCheck.reason}`);
+		process.exit(1);
+	}
+	const metadata = getSourceMetadata(sourcePath);
+	const draftConfigSha = hashManifest(manifestPath);
+	const commitMessage = buildCommitMessage({
+		siteName,
+		metadata,
+		prompt: readManifestPrompt(manifestPath, sourcePath),
+		draftConfigSha
+	});
+	const branchName = `${prefix}${siteName}`;
+	const tmpDir = mkdtempSync(join(tmpdir(), "design-drafts-"));
+	const messageFile = join(tmpdir(), `design-drafts-msg-${process.pid}.txt`);
+	writeFileSync(messageFile, commitMessage);
+	try {
+		cpSync(sourcePath, tmpDir, { recursive: true });
+		await embedDeployWorkflow(repo, tmpDir);
+		exec(`git init -b ${branchName}`, tmpDir);
+		exec(`git remote add origin ${githubRemoteUrl(repo, tmpDir)}`, tmpDir);
+		exec("git add .", tmpDir);
+		exec(`git commit -F ${JSON.stringify(messageFile)}`, tmpDir);
+		try {
+			exec(`git push --force origin ${branchName}`, tmpDir);
+		} catch {
+			throw new CliError(`Failed to push "${branchName}" to ${repo}.\nCheck that the repo exists and you have push access (\`gh auth status\`),\nthen re-run. Nothing was saved as a default.`);
+		}
+		persistHomeConfigValue("repo", repo);
+		console.log(`\nPushed "${branchName}" to ${repo}`);
+	} finally {
+		rmSync(tmpDir, {
+			recursive: true,
+			force: true
+		});
+		rmSync(messageFile, { force: true });
+	}
+}
+await cli("design-drafts", {
+	description: "Push static site previews as branches to a design-drafts repo",
+	builder: (args) => args.option("repo", {
+		type: "string",
+		description: "GitHub repo in org/repo form"
+	}).option("site-name", {
+		type: "string",
+		description: "Name for this site preview (becomes the branch name)"
+	}).option("template-ref", {
+		type: "string",
+		description: "Ref of the canonical repo to scaffold the host site from (default: matching version tag, else main)"
+	}).env({ prefix: "DESIGN_DRAFTS" }).config(homeJsonProvider).command("init", {
+		description: "Set up a host (if needed) and scaffold a draft, ready to publish",
+		builder: (initArgs) => initArgs.command("host", {
+			description: "Scaffold a GitHub repo to host draft previews",
+			builder: (b) => b.option("path", {
+				type: "string",
+				description: "Persist the scaffold to this directory instead of a throwaway tmpdir"
+			}).option("private", {
+				type: "boolean",
+				description: "Create a private repo (default: prompt; Pages needs Pro/Team for private)"
+			}).option("yes", {
+				type: "boolean",
+				description: "Skip the confirmation prompt before GitHub setup"
+			}),
+			handler: (a) => runHandler(() => initHost({
+				path: a.path,
+				repo: a.repo,
+				templateRef: a["template-ref"],
+				private: a.private,
+				yes: a.yes,
+				cliVersion: CLI_VERSION
+			}))
+		}).command("draft", {
+			description: "Scaffold a new draft directory",
+			builder: (b) => b.positional("path", {
+				type: "string",
+				default: ".",
+				description: "Directory to scaffold the draft into"
+			}),
+			handler: (a) => runHandler(() => initDraft({
+				path: a.path,
+				siteName: a["site-name"]
+			}))
+		}),
+		handler: (a) => runHandler(() => init({
+			path: ".",
+			repo: a.repo,
+			siteName: a["site-name"],
+			templateRef: a["template-ref"],
+			cliVersion: CLI_VERSION
+		}))
+	}).command("ref", {
+		description: "Manage a draft's references/ directory (links and inspiration screenshots).",
+		builder: (refArgs) => refArgs.command("add", {
+			description: "Add a reference URL or screenshot to references/. URL → references/links.md (with --note); image URL or local image → references/inspiration/.",
+			builder: (b) => b.positional("source", {
+				type: "string",
+				description: "URL or local file path to add as a reference"
+			}).option("note", {
+				type: "string",
+				description: "Annotation describing what is being cited. Required for non-image URLs."
+			}).option("name", {
+				type: "string",
+				description: "Override the filename used in references/inspiration/ (extension is added if missing)."
+			}).option("draft", {
+				type: "string",
+				description: "Path to the draft directory containing design-drafts.config.json (default: cwd)."
+			}),
+			handler: (a) => runHandler(() => {
+				if (!a.source) throw new CliError("design-drafts ref add requires a <source> argument (URL or file path).");
+				return refAdd({
+					source: a.source,
+					note: a.note,
+					name: a.name,
+					draft: a.draft
+				});
+			})
+		})
+	}).command("preview", {
+		description: "Serve a work-in-progress draft directory over HTTP for local viewing",
+		builder: (b) => b.positional("path", {
+			type: "string",
+			default: ".",
+			description: "Draft directory to serve (must contain design-drafts.config.json; default: cwd)"
+		}).option("port", {
+			type: "number",
+			description: "Port to serve on (default: 4321; auto-increments if busy unless set explicitly)"
+		}).option("open", {
+			type: "boolean",
+			default: true,
+			description: "Open the preview in a browser (use --no-open to just print the URL)"
+		}),
+		handler: (a) => runHandler(() => preview({
+			draft: a.path,
+			port: a.port,
+			open: a.open
+		}))
+	}).command("push", {
+		alias: ["$0"],
+		description: "Push a built directory as a draft preview branch",
+		builder: (b) => b.positional("path", {
+			type: "string",
+			default: ".",
+			description: "Directory to push as a site preview"
+		}).option("prefix", {
+			type: "string",
+			description: "Branch prefix used when pushing previews (default: \"drafts/\"). Pass an empty string to push without a prefix."
+		}),
+		handler: (a) => runHandler(() => pushHandler(a))
+	})
+}).forge();
+//#endregion
+export {};