@design-drafts/cli 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Craigory Coppola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @design-drafts/cli
+
+Push static site previews as branches to a **design-drafts** repo, and have
+them deployed to GitHub Pages automatically.
+
+A *host* repo collects many *draft* previews. You scaffold a host once, then
+push any built static directory as a draft branch; a GitHub Actions workflow
+publishes each branch under its own path on GitHub Pages and an index site
+links them all together.
+
+## Install
+
+```sh
+# one-off
+npx @design-drafts/cli --help
+
+# or install globally for the `design-drafts` binary
+npm i -g @design-drafts/cli
+```
+
+## Commands
+
+### `design-drafts push [path]`
+
+Push a built static directory (default `.`) as a draft preview branch. This is
+the default command, so `design-drafts ./dist` works too.
+
+```sh
+design-drafts push ./dist --repo my-org/design-previews --site-name homepage-v2
+```
+
+- `--repo <org/repo>` — the host repo to push to (remembered after the first run).
+- `--site-name <name>` — branch/preview name (prompted if omitted).
+- `--prefix <prefix>` — branch prefix for previews (default `drafts/`; pass `""` to push without one).
+
+### `design-drafts init host`
+
+Scaffold a new GitHub repo configured to host draft previews (deploy workflow,
+index site, Pages setup).
+
+```sh
+design-drafts init host --repo my-org/design-previews
+```
+
+- `--private` — create the GitHub repo as private.
+- `--yes` — skip the confirmation prompt before GitHub setup.
+
+### `design-drafts init draft [directory]`
+
+Scaffold a new draft directory locally.
+
+```sh
+design-drafts init draft ./my-draft
+```
+
+## Configuration
+
+Shared options (`--repo`, `--site-name`, `--template-ref`) can be supplied via
+flags, the `DESIGN_DRAFTS_*` environment variables, or a JSON config file. The
+`--repo` value is persisted to a per-user config after the first successful
+push, so subsequent runs don't need it.
+
+## License
+
+MIT

package/bin.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('./dist/index.mjs');

package/dist/index.mjs

@@ -0,0 +1,964 @@
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { ConfigurationProviders, cli } from "cli-forge";
+import { confirm, isCancel, select, text } from "@clack/prompts";
+import { execSync } from "node:child_process";
+//#region package.json
+var version = "0.1.0";
+//#endregion
+//#region src/config.ts
+const CONFIG_FILENAME = "design-drafts.config.json";
+const DEFAULT_PREFIX = "drafts/";
+const homeConfigPath = join(homedir(), CONFIG_FILENAME);
+const localConfigPath = join(process.cwd(), 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;
+}
+async function promptAndPersist(existing, argKey, configPath, promptMessage, validate) {
+	if (existing) return existing;
+	const value = await promptForValue(existing, argKey, promptMessage, validate);
+	writeFileSync(configPath, JSON.stringify({
+		...readConfig(configPath),
+		[argKey]: value
+	}, null, 2) + "\n");
+	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\`. The push command reads the
+* \`prompt\` field for the commit trailer.
+*/
+function draftConfig(siteName) {
+	return JSON.stringify({
+		siteName,
+		prompt: ""
+	}, 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>
+  </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 promptAndPersist(opts.siteName, "site-name", localConfigPath, "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, "draft.config.json"), draftConfig(siteName));
+	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/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, " ");
+}
+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 draft.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 siteName = await promptAndPersist(args["site-name"], "site-name", localConfigPath, "Site name for this preview:");
+	const prefix = resolvePrefix(args.prefix);
+	const sourcePath = resolve(args.path ?? ".");
+	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);
+	}
+	if (!existsSync(sourcePath)) {
+		console.error(`Path does not exist: ${sourcePath}`);
+		process.exit(1);
+	}
+	const manifestPath = join(sourcePath, "draft.config.json");
+	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).config(ConfigurationProviders.JsonFile(CONFIG_FILENAME)).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("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 {};

package/package.json

@@ -1,8 +1,56 @@
 {
   "name": "@design-drafts/cli",
-  "version": "0.0.0",
-  "description": "Shell package for @design-drafts/cli",
+  "version": "0.1.0",
+  "description": "CLI for scaffolding and deploying design-drafts previews to GitHub Pages.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "design-drafts": "./bin.js"
+  },
+  "files": [
+    "dist",
+    "bin.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentEnder/design-drafts.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/AgentEnder/design-drafts/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/AgentEnder/design-drafts/issues"
+  },
+  "keywords": [
+    "design-drafts",
+    "cli",
+    "preview",
+    "github-pages",
+    "static-site"
+  ],
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "cli-forge": "^1.9.2"
+  },
+  "devDependencies": {
+    "@types/node": "18.16.9",
+    "tsdown": "^0.21.7",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.4",
+    "yaml": "^2.8.3"
+  },
+  "nx": {
+    "name": "cli"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --out-dir dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
 }