npm - @design-drafts/cli - Versions diffs - 0.1.0 → 0.2.0 - Mend

@design-drafts/cli 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -53,6 +53,24 @@ Scaffold a new draft directory locally.
 design-drafts init draft ./my-draft
 ```
+### `design-drafts preview [path]`
+Serve a work-in-progress draft directory (default `.`) over HTTP so you can view
+it locally before pushing. The directory must contain a `design-drafts.config.json`.
+```sh
+design-drafts preview ./my-draft
+```
+- `--port <n>` — port to serve on (default `4321`; auto-increments to the next
+  free port unless you set it explicitly).
+- `--no-open` — don't open a browser, just print the URL.
+When a requested directory has no `index.html` (e.g. a draft whose pages are
+`about.html`, `pricing.html`, … with no home page yet), the server returns a
+generated index linking to every `.html` page in the draft so you can navigate
+without one.
 ## Configuration
 Shared options (`--repo`, `--site-name`, `--template-ref`) can be supplied via

package/dist/index.mjs CHANGED Viewed

@@ -1,18 +1,18 @@
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, 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 { 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 } from "node:child_process";
+import { execSync, spawn } from "node:child_process";
+import { createServer } from "node:http";
 //#region package.json
-var version = "0.1.0";
+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 localConfigPath = join(process.cwd(), CONFIG_FILENAME);
 const homeJsonProvider = {
 	resolve: () => existsSync(homeConfigPath) ? homeConfigPath : void 0,
 	load: (filename) => JSON.parse(readFileSync(filename, "utf-8"))
@@ -43,15 +43,6 @@ async function promptForValue(existing, label, promptMessage, validate) {
 	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;
@@ -331,13 +322,24 @@ dist
 .gh-pages-staging
 `;
 /**
-* The starter manifest written by \`init draft\`. The push command reads the
-* \`prompt\` field for the commit trailer.
+* 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) {
+function draftConfig(siteName, createdAt) {
 	return JSON.stringify({
-		siteName,
-		prompt: ""
+		$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>
@@ -352,6 +354,19 @@ const DRAFT_INDEX_HTML = `<!doctype html>
       <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>
 `;
@@ -372,7 +387,7 @@ function writeIfAbsent(filePath, contents) {
 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:");
+	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);
@@ -380,7 +395,7 @@ async function initDraft(opts) {
 		siteName = fixed;
 	}
 	console.log(`\nScaffolding draft "${siteName}" in ${targetDir}:`);
-	const wroteManifest = writeIfAbsent(join(targetDir, "draft.config.json"), draftConfig(siteName));
+	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.`);
@@ -738,6 +753,345 @@ async function init(opts) {
 	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";
@@ -800,6 +1154,38 @@ function readManifestPrompt(manifestPath, sourcePath) {
 	} 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, ")");
 }
@@ -814,7 +1200,7 @@ function sanitizeAuthorName(name) {
 *     source-repo: <repo>
 *     author: <Name <email>>
 *     prompt: <one-line summary or path>
-*     draft-config-sha: <sha256 of draft.config.json>
+*     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
@@ -836,9 +1222,14 @@ function buildCommitMessage(opts) {
 }
 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 ?? ".");
+	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}`);
@@ -855,11 +1246,6 @@ async function pushHandler(args) {
 		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({
@@ -905,7 +1291,7 @@ await cli("design-drafts", {
 	}).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", {
+	}).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",
@@ -946,6 +1332,52 @@ await cli("design-drafts", {
 			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",

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@design-drafts/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI for scaffolding and deploying design-drafts previews to GitHub Pages.",
   "license": "MIT",
   "type": "module",
@@ -43,7 +43,8 @@
     "tsdown": "^0.21.7",
     "typescript": "5.9.3",
     "vitest": "^4.1.4",
-    "yaml": "^2.8.3"
+    "yaml": "^2.8.3",
+    "@design-drafts/conventions": "0.0.0"
   },
   "nx": {
     "name": "cli"