nimbus-docs 0.0.2

package/dist/cli/index.js

@@ -0,0 +1,692 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { dirname, join, relative } from "node:path";
+import mri from "mri";
+import * as p from "@clack/prompts";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { determineAgent } from "@vercel/detect-agent";
+
+//#region src/cli/_registry.generated.ts
+const REGISTRY_BASE_URL = "https://nimbus-docs.com/registry";
+const BUNDLED_INDEX = {
+	"version": 1,
+	"items": {
+		"cn": {
+			"name": "cn",
+			"type": "registry:lib",
+			"title": "cn",
+			"description": "Tailwind-aware className merger built on clsx + tailwind-merge."
+		},
+		"accordion": {
+			"name": "accordion",
+			"type": "registry:ui",
+			"title": "Accordion",
+			"description": "Vertically stacked collapsible sections."
+		},
+		"aside": {
+			"name": "aside",
+			"type": "registry:ui",
+			"title": "Aside",
+			"description": "Generic boxed callout. Building block for Callout, Note, Warning."
+		},
+		"badge": {
+			"name": "badge",
+			"type": "registry:ui",
+			"title": "Badge",
+			"description": "Small status / category pill."
+		},
+		"banner": {
+			"name": "banner",
+			"type": "registry:ui",
+			"title": "Banner",
+			"description": "Site-wide dismissible announcement bar."
+		},
+		"breadcrumbs": {
+			"name": "breadcrumbs",
+			"type": "registry:ui",
+			"title": "Breadcrumbs",
+			"description": "Page-context navigation crumbs."
+		},
+		"callout": {
+			"name": "callout",
+			"type": "registry:ui",
+			"title": "Callout",
+			"description": "Inline note / tip / warning / danger / info card."
+		},
+		"card": {
+			"name": "card",
+			"type": "registry:ui",
+			"title": "Card",
+			"description": "Generic content card with optional title and footer."
+		},
+		"card-grid": {
+			"name": "card-grid",
+			"type": "registry:ui",
+			"title": "CardGrid",
+			"description": "Responsive grid layout for cards."
+		},
+		"code": {
+			"name": "code",
+			"type": "registry:ui",
+			"title": "Code",
+			"description": "Inline / block code wrapper. Re-exports Astro's built-in <Code> (Shiki)."
+		},
+		"code-group": {
+			"name": "code-group",
+			"type": "registry:ui",
+			"title": "CodeGroup",
+			"description": "Tabbed group of code blocks."
+		},
+		"collapsible": {
+			"name": "collapsible",
+			"type": "registry:ui",
+			"title": "Collapsible",
+			"description": "Headless show/hide primitive — building block for Accordion and Sidebar groups."
+		},
+		"dialog": {
+			"name": "dialog",
+			"type": "registry:ui",
+			"title": "Dialog",
+			"description": "Modal dialog with focus-trap and body-scroll lock."
+		},
+		"embed": {
+			"name": "embed",
+			"type": "registry:ui",
+			"title": "Embed",
+			"description": "Responsive iframe / video / external content wrapper."
+		},
+		"file-tree": {
+			"name": "file-tree",
+			"type": "registry:ui",
+			"title": "FileTree",
+			"description": "Render a directory tree as nested markup."
+		},
+		"frame": {
+			"name": "frame",
+			"type": "registry:ui",
+			"title": "Frame",
+			"description": "Decorative outer frame for screenshots and demos."
+		},
+		"layer-card": {
+			"name": "layer-card",
+			"type": "registry:ui",
+			"title": "LayerCard",
+			"description": "Stacked-card container with sticky header. Base for CodeGroup and PackageManagers."
+		},
+		"link-button": {
+			"name": "link-button",
+			"type": "registry:ui",
+			"title": "LinkButton",
+			"description": "Anchor styled as a button."
+		},
+		"link-card": {
+			"name": "link-card",
+			"type": "registry:ui",
+			"title": "LinkCard",
+			"description": "Card whose entire surface is a link."
+		},
+		"package-managers": {
+			"name": "package-managers",
+			"type": "registry:ui",
+			"title": "PackageManagers",
+			"description": "Tabbed install command block translated across npm / pnpm / yarn / bun."
+		},
+		"pagination": {
+			"name": "pagination",
+			"type": "registry:ui",
+			"title": "Pagination",
+			"description": "Prev / next page navigation."
+		},
+		"popover": {
+			"name": "popover",
+			"type": "registry:ui",
+			"title": "Popover",
+			"description": "Floating panel anchored to a trigger element."
+		},
+		"search": {
+			"name": "search",
+			"type": "registry:ui",
+			"title": "Search",
+			"description": "Command-palette search dialog with a provider seam. Defaults to Pagefind."
+		},
+		"sidebar": {
+			"name": "sidebar",
+			"type": "registry:ui",
+			"title": "Sidebar",
+			"description": "Docs sidebar with nested groups and active-link tracking."
+		},
+		"steps": {
+			"name": "steps",
+			"type": "registry:ui",
+			"title": "Steps",
+			"description": "Numbered ordered-list with vertical connectors."
+		},
+		"tabs": {
+			"name": "tabs",
+			"type": "registry:ui",
+			"title": "Tabs",
+			"description": "Tabbed content panels (manual + Starlight-compatible modes)."
+		},
+		"theme-toggle": {
+			"name": "theme-toggle",
+			"type": "registry:ui",
+			"title": "ThemeToggle",
+			"description": "Light / dark theme switcher button."
+		},
+		"toc": {
+			"name": "toc",
+			"type": "registry:ui",
+			"title": "TOC",
+			"description": "On-page table of contents with active-heading tracking."
+		},
+		"404-page": {
+			"name": "404-page",
+			"type": "registry:feature",
+			"title": "Custom 404 page",
+			"description": "Generate a brand-matched 404 page for the docs site."
+		},
+		"ai-native": {
+			"name": "ai-native",
+			"type": "registry:feature",
+			"title": "AI-native static surface",
+			"description": "Add llms.txt, markdown variants, robots.txt, and an AgentDirective to a Nimbus docs site."
+		},
+		"pagefind-search": {
+			"name": "pagefind-search",
+			"type": "registry:feature",
+			"title": "Pagefind search",
+			"description": "Add static Pagefind indexing and the Nimbus search dialog to an existing docs site."
+		}
+	}
+};
+
+//#endregion
+//#region src/cli/pm.ts
+/**
+* Package-manager detection + install command helpers.
+*
+* Detection prefers lockfile presence in the user's cwd, then falls back
+* to the `npm_config_user_agent` env var the active package manager sets
+* when invoking the CLI. Finally falls back to `npm`.
+*/
+const LOCKFILES = [
+	["pnpm-lock.yaml", "pnpm"],
+	["yarn.lock", "yarn"],
+	["bun.lockb", "bun"],
+	["bun.lock", "bun"],
+	["package-lock.json", "npm"]
+];
+function detectPackageManager(cwd) {
+	for (const [lockfile, pm] of LOCKFILES) if (existsSync(join(cwd, lockfile))) return pm;
+	const ua = process.env.npm_config_user_agent ?? "";
+	if (ua.startsWith("pnpm")) return "pnpm";
+	if (ua.startsWith("yarn")) return "yarn";
+	if (ua.startsWith("bun")) return "bun";
+	return "npm";
+}
+/**
+* Command + args to install one or more new npm deps. Each PM picks the
+* verb that both adds to package.json AND installs:
+*
+*   npm  install <deps...>
+*   pnpm add     <deps...>
+*   yarn add     <deps...>
+*   bun  add     <deps...>
+*/
+function addCommand$1(pm, deps) {
+	if (deps.length === 0) throw new Error("addCommand called with empty deps");
+	switch (pm) {
+		case "npm": return {
+			bin: "npm",
+			args: ["install", ...deps]
+		};
+		case "pnpm": return {
+			bin: "pnpm",
+			args: ["add", ...deps]
+		};
+		case "yarn": return {
+			bin: "yarn",
+			args: ["add", ...deps]
+		};
+		case "bun": return {
+			bin: "bun",
+			args: ["add", ...deps]
+		};
+	}
+}
+
+//#endregion
+//#region src/cli/component.ts
+/**
+* Component / utility installer.
+*
+* Walks the resolved list of items, writes each file (per-file overwrite
+* prompt on conflict), then collects all npm `dependencies` across the
+* tree and runs `<pm> add` once for the dedup'd set.
+*
+* File destination: `<cwd>/src/<path>`. The `path` field already encodes
+* the directory layout (e.g. `components/ui/dialog/Dialog.astro`).
+*/
+async function installComponents(items, options) {
+	const report = {
+		written: [],
+		skipped: [],
+		npmDepsInstalled: []
+	};
+	const srcDir = join(options.cwd, "src");
+	for (const item of items) {
+		const filePlans = item.files.map((file) => {
+			const targetAbs = join(srcDir, file.path);
+			return {
+				targetAbs,
+				targetRel: relative(options.cwd, targetAbs),
+				content: file.content,
+				exists: existsSync(targetAbs)
+			};
+		});
+		const conflicts = filePlans.filter((f) => f.exists);
+		if (conflicts.length > 0 && !options.yes) {
+			const total = filePlans.length;
+			const message = conflicts.length === total ? `${item.name} is already installed (${total} file${total === 1 ? "" : "s"}). Overwrite?` : `${item.name} is partially installed (${conflicts.length} of ${total} file${total === 1 ? "" : "s"} present). Overwrite all?`;
+			const choice = await p.select({
+				message,
+				options: [
+					{
+						value: "overwrite",
+						label: "Overwrite — replace existing files"
+					},
+					{
+						value: "skip",
+						label: "Skip — leave files as-is"
+					},
+					{
+						value: "cancel",
+						label: "Cancel install"
+					}
+				],
+				initialValue: "overwrite"
+			});
+			if (p.isCancel(choice) || choice === "cancel") {
+				p.cancel("Cancelled.");
+				process.exit(0);
+			}
+			if (choice === "skip") {
+				report.skipped.push(item.name);
+				continue;
+			}
+		}
+		for (const plan of filePlans) {
+			mkdirSync(dirname(plan.targetAbs), { recursive: true });
+			writeFileSync(plan.targetAbs, plan.content);
+			report.written.push(plan.targetRel);
+		}
+	}
+	const allDeps = /* @__PURE__ */ new Set();
+	for (const item of items) for (const dep of item.dependencies) allDeps.add(dep);
+	if (allDeps.size > 0) {
+		const newDeps = filterAlreadyInstalled(options.cwd, [...allDeps]);
+		if (newDeps.length > 0) {
+			const pm = detectPackageManager(options.cwd);
+			const { bin, args } = addCommand$1(pm, newDeps);
+			const spinner = p.spinner();
+			spinner.start(`${pm} add ${newDeps.join(" ")}`);
+			try {
+				await runCommand(bin, args, options.cwd);
+				spinner.stop(`Installed ${newDeps.length} dep${newDeps.length === 1 ? "" : "s"}.`);
+				report.npmDepsInstalled = newDeps;
+			} catch (err) {
+				spinner.stop("Dependency install failed.");
+				p.log.warn(`Could not install ${newDeps.join(", ")}. Run \`${bin} ${args.join(" ")}\` manually.`);
+			}
+		}
+	}
+	return report;
+}
+/**
+* Filter out deps already present in `dependencies` or `devDependencies`
+* of the user's package.json. If package.json is missing, returns all.
+*/
+function filterAlreadyInstalled(cwd, deps) {
+	const pkgPath = join(cwd, "package.json");
+	if (!existsSync(pkgPath)) return deps;
+	try {
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+		const installed = new Set([...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})]);
+		return deps.filter((d) => !installed.has(d));
+	} catch {
+		return deps;
+	}
+}
+function runCommand(bin, args, cwd) {
+	return new Promise((resolveP, rejectP) => {
+		const child = spawn(bin, args, {
+			cwd,
+			stdio: [
+				"ignore",
+				"ignore",
+				"inherit"
+			]
+		});
+		child.on("close", (code) => code === 0 ? resolveP() : rejectP(/* @__PURE__ */ new Error(`${bin} ${args.join(" ")} exited ${code}`)));
+		child.on("error", rejectP);
+	});
+}
+
+//#endregion
+//#region src/cli/dotenv.ts
+/**
+* Tiny .env loader — no dependency.
+*
+* Reads `.env` from the user's cwd at CLI startup and sets any KEY=VALUE
+* pairs into `process.env` IF the variable isn't already set (so a shell-
+* provided env always wins over the file). Supports the basic cases:
+*
+*   KEY=value
+*   KEY="quoted value"
+*   KEY='quoted value'
+*   # comments
+*
+* Used so `examples/local/.env` can carry `NIMBUS_REGISTRY_URL=...` without
+* the user having to prefix every CLI invocation.
+*/
+function loadDotenv(cwd) {
+	const path = join(cwd, ".env");
+	if (!existsSync(path)) return;
+	let raw;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
+	for (const rawLine of raw.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (!line || line.startsWith("#")) continue;
+		const eq = line.indexOf("=");
+		if (eq <= 0) continue;
+		const key = line.slice(0, eq).trim();
+		if (!/^[A-Z_][A-Z0-9_]*$/i.test(key)) continue;
+		let value = line.slice(eq + 1).trim();
+		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+		if (process.env[key] === void 0) process.env[key] = value;
+	}
+}
+
+//#endregion
+//#region src/cli/resolver.ts
+/**
+* Registry resolver.
+*
+* Two entry points:
+*
+*   - `resolveComponentTree(slug)` walks `registryDependencies` transitively
+*     and returns a flat ordered list of components/utilities to install
+*     (dependencies first, root last). Cycles are detected as repeated
+*     visits and skipped.
+*
+*   - `fetchFeatureMarkdown(slug)` returns the raw markdown for an
+*     agent-handoff feature; the caller decides what to do with it.
+*
+* The base URL for hosted artifacts is read from the bundled index, with
+* an `NIMBUS_REGISTRY_URL` env override for local development.
+*/
+/**
+* Read the registry base URL on every call so `.env` files loaded after
+* module-import time (see cli/dotenv.ts) are picked up. The cost is
+* negligible — string interpolation of an env var.
+*/
+function getBaseUrl() {
+	return (process.env.NIMBUS_REGISTRY_URL ?? REGISTRY_BASE_URL).replace(/\/$/, "");
+}
+function getIndexEntry(slug) {
+	return BUNDLED_INDEX.items[slug];
+}
+function listEntries(filter) {
+	const all = Object.values(BUNDLED_INDEX.items);
+	if (!filter?.type) return all;
+	return all.filter((e) => e.type === filter.type);
+}
+async function httpGet(url) {
+	let res;
+	try {
+		res = await fetch(url);
+	} catch (err) {
+		const cause = err.message;
+		throw new Error(`Could not reach the registry at ${url}.\n  Underlying error: ${cause}\n\n  Things to try:\n    - Is the registry server running? Start it with \`pnpm local\` (in the monorepo root).\n    - Override the URL: NIMBUS_REGISTRY_URL=https://example.com nimbus add ...\n    - Check the value in your project's .env file.`);
+	}
+	if (!res.ok) throw new Error(`Registry returned ${res.status} ${res.statusText} for ${url}. The server is up but doesn't know about this slug — check \`nimbus list\` for valid names.`);
+	return res;
+}
+async function fetchComponent(slug) {
+	return await (await httpGet(`${getBaseUrl()}/components/${slug}.json`)).json();
+}
+async function fetchFeatureMarkdown(slug) {
+	return await (await httpGet(`${getBaseUrl()}/features/${slug}.md`)).text();
+}
+/**
+* Depth-first walk of registryDependencies. Returns items in install order
+* (deps before dependents), deduplicated by slug.
+*/
+async function resolveComponentTree(rootSlug) {
+	const visited = /* @__PURE__ */ new Set();
+	const ordered = [];
+	async function visit(slug) {
+		if (visited.has(slug)) return;
+		visited.add(slug);
+		const item = await fetchComponent(slug);
+		for (const dep of item.registryDependencies) await visit(dep);
+		ordered.push(item);
+	}
+	await visit(rootSlug);
+	return ordered;
+}
+
+//#endregion
+//#region src/cli/feature.ts
+/**
+* Feature installer — Flue-style agent-handoff.
+*
+* Same rule Flue uses for `flue add`: if `--print` is set OR
+* `determineAgent()` says the CLI is running inside a known coding agent,
+* the markdown is piped to stdout for the agent to consume. Otherwise we
+* print human-friendly instructions on stderr telling the user exactly
+* how to pipe the output to their agent of choice.
+*
+* No picker, no clipboard mode — the printed pipe commands cover both.
+*/
+async function installFeature(slug, options) {
+	const markdown = await fetchFeatureMarkdown(slug);
+	const detected = await determineAgent().catch(() => ({ isAgent: false }));
+	if (options.print || detected.isAgent === true) {
+		process.stdout.write(markdown);
+		if (!markdown.endsWith("\n")) process.stdout.write("\n");
+		return;
+	}
+	printHumanInstructions(slug);
+}
+/**
+* Stderr-only. We don't put this on stdout because if the user pipes our
+* output anywhere by accident, only the markdown should reach the agent.
+*
+* Formatting mirrors Flue's `printHumanInstructions` 1:1 — agents listed
+* with a blank line between the "first-tier" CLIs (claude/codex/cursor-agent)
+* and the rest (opencode/pi).
+*/
+function printHumanInstructions(slug) {
+	const cmd = `nimbus add ${slug}`;
+	const stream = process.stderr;
+	stream.write(`${cmd}\n\n`);
+	stream.write("To install this feature, pipe it to your coding agent:\n\n");
+	stream.write(`  ${cmd} --print | claude\n`);
+	stream.write(`  ${cmd} --print | codex\n`);
+	stream.write(`  ${cmd} --print | cursor-agent\n\n`);
+	stream.write(`  ${cmd} --print | opencode\n`);
+	stream.write(`  ${cmd} --print | pi\n`);
+	stream.write("Or paste this prompt into any agent:\n\n");
+	stream.write(`  Run "${cmd} --print" and follow the instructions.\n`);
+}
+
+//#endregion
+//#region src/cli/index.ts
+/**
+* `nimbus` CLI entry.
+*
+* Surface:
+*
+*   nimbus                        → list (table of installable items)
+*   nimbus list                   → list
+*   nimbus list --type ui|lib|feature
+*   nimbus add                    → list
+*   nimbus add <slug>             → install (component path or feature path)
+*   nimbus add <slug> --yes       → component: skip overwrite prompts
+*   nimbus add <slug> --print     → feature: print markdown to stdout (skip detect)
+*
+* Feature behavior mirrors Flue's `add` command: print markdown to stdout
+* iff `--print` OR an agent is detected; otherwise print human-friendly
+* pipe instructions to stderr.
+*
+* The bundled index makes `list` (and `add` with no slug) work offline.
+* Per-item content is fetched from `REGISTRY_BASE_URL` only when actually
+* installing a slug — override via `NIMBUS_REGISTRY_URL` for local dev.
+*/
+loadDotenv(process.cwd());
+const HELP = `
+  Usage: nimbus <command> [args]
+
+  Commands:
+    list [--type ui|lib|feature]   List available registry items
+    add                            Same as \`list\`
+    add <slug>                     Install a component or hand off a feature
+
+  Flags:
+    --yes, -y                      Component: overwrite conflicts without prompting
+    --print                        Feature: print markdown to stdout (skip agent detect)
+    --type <ui|lib|feature>        \`list\`: filter by type
+    --help, -h
+    --version, -v
+
+  Examples:
+    nimbus add dialog                              # component: resolve + install
+    nimbus add 404-page                            # feature: detect agent or print
+                                                   #   pipe instructions for humans
+    nimbus add 404-page --print | claude           # explicit pipe to claude
+    nimbus add 404-page --print | codex            # …or any other agent
+`;
+async function main() {
+	const args = mri(process.argv.slice(2), {
+		boolean: [
+			"yes",
+			"print",
+			"help",
+			"version"
+		],
+		string: ["type"],
+		alias: {
+			y: "yes",
+			h: "help",
+			v: "version"
+		}
+	});
+	if (args.help) {
+		process.stdout.write(HELP);
+		return;
+	}
+	if (args.version) {
+		process.stdout.write(`0.0.2\n`);
+		return;
+	}
+	const [command, slug] = args._;
+	if (command === "list" || command === "add" && !slug || !command) {
+		listCommand(args.type);
+		return;
+	}
+	if (command === "add") {
+		await addCommand(slug, {
+			yes: args.yes,
+			print: args.print
+		});
+		return;
+	}
+	p.log.error(`Unknown command: \`${command}\`. Try \`nimbus --help\`.`);
+	process.exit(1);
+}
+function listCommand(typeFilter) {
+	const typeMap = {
+		ui: "registry:ui",
+		lib: "registry:lib",
+		feature: "registry:feature"
+	};
+	const filter = typeFilter && typeFilter in typeMap ? { type: typeMap[typeFilter] } : void 0;
+	if (typeFilter && !(typeFilter in typeMap)) {
+		p.log.error(`Unknown --type "${typeFilter}". Valid: ui, lib, feature.`);
+		process.exit(1);
+	}
+	const items = listEntries(filter);
+	if (items.length === 0) {
+		p.log.info("No items match the filter.");
+		return;
+	}
+	const grouped = {
+		"registry:ui": [],
+		"registry:lib": [],
+		"registry:feature": []
+	};
+	for (const item of items) grouped[item.type].push(item);
+	const labels = {
+		"registry:ui": "Components",
+		"registry:lib": "Utilities",
+		"registry:feature": "Features"
+	};
+	const widths = items.reduce((m, i) => Math.max(m, i.name.length), 0);
+	process.stdout.write("\n");
+	for (const [type, label] of Object.entries(labels)) {
+		const group = grouped[type];
+		if (!group || group.length === 0) continue;
+		process.stdout.write(`  ${label}\n`);
+		for (const item of group) process.stdout.write(`    ${item.name.padEnd(widths + 2)}${item.description}\n`);
+		process.stdout.write("\n");
+	}
+	process.stdout.write(`  Install:  nimbus add <name>     ·  ${items.length} item${items.length === 1 ? "" : "s"}\n\n`);
+}
+async function addCommand(slug, flags) {
+	const entry = getIndexEntry(slug);
+	if (!entry) {
+		p.log.error(`Unknown registry item: \`${slug}\`. Try \`nimbus list\` to see what's available.`);
+		process.exit(1);
+	}
+	if (entry.type === "registry:feature") {
+		await installFeature(slug, { print: flags.print });
+		return;
+	}
+	p.intro(`nimbus add ${slug}`);
+	p.log.info(`${entry.title} — ${entry.description}`);
+	const spinner = p.spinner();
+	spinner.start("Resolving dependencies");
+	let items;
+	try {
+		items = await resolveComponentTree(slug);
+		spinner.stop(`Resolved ${items.length} item${items.length === 1 ? "" : "s"}.`);
+	} catch (err) {
+		spinner.stop("Failed to resolve.");
+		p.log.error(err.message);
+		process.exit(1);
+	}
+	if (items.length > 1) p.log.message("Install order:\n  " + items.map((i) => i.name).join(" → "));
+	const report = await installComponents(items, {
+		cwd: process.cwd(),
+		yes: flags.yes
+	});
+	const lines = [];
+	if (report.written.length > 0) lines.push(`✓ Wrote ${report.written.length} file${report.written.length === 1 ? "" : "s"}`);
+	if (report.skipped.length > 0) lines.push(`↷ Skipped: ${report.skipped.join(", ")}`);
+	if (report.npmDepsInstalled.length > 0) lines.push(`+ Installed ${report.npmDepsInstalled.length} npm dep${report.npmDepsInstalled.length === 1 ? "" : "s"}: ${report.npmDepsInstalled.join(", ")}`);
+	if (lines.length === 0) p.outro("Nothing to do.");
+	else p.outro(lines.join("\n"));
+}
+main().catch((err) => {
+	p.log.error(`${err.message}`);
+	process.exit(1);
+});
+
+//#endregion
+export {  };
+//# sourceMappingURL=index.js.map