yaakdoc 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,343 @@
+import { c as VERSION } from "./site-X7q76qYf.js";
+import { a as createDevServer, n as eject, o as build, r as init, t as preview } from "./preview-Ba1BfVZV.js";
+import { ConfigError, mergeConfig } from "@yaakdoc/config";
+import { relative, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { consola } from "consola";
+import colors from "picocolors";
+import * as p from "@clack/prompts";
+import { defineCommand, runMain } from "citty";
+//#region src/cli/overrides.ts
+/**
+* Reads the value of `--overrides`: inline JSON (starting with `{`) or the path of a JSON file. The
+* result is merged over the config file and validated together with it.
+*/
+function readOverrides(value, cwd = process.cwd()) {
+	const inline = value.trimStart().startsWith("{");
+	let text = value;
+	if (!inline) try {
+		text = readFileSync(resolve(cwd, value), "utf8");
+	} catch (error) {
+		throw new ConfigError(`Could not read overrides ${value}: ${error.message}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw new ConfigError(`Invalid JSON in ${inline ? "--overrides" : `overrides ${value}`}: ${error.message}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new ConfigError("--overrides must be a JSON object");
+	return parsed;
+}
+//#endregion
+//#region src/cli/index.ts
+const sharedArgs = {
+	export: {
+		type: "positional",
+		required: false,
+		description: "Path to the Yaak export (auto-detected by default)"
+	},
+	config: {
+		type: "string",
+		alias: "c",
+		description: "Path to the config file"
+	},
+	theme: {
+		type: "string",
+		alias: "t",
+		description: "Theme name, package or local path"
+	},
+	pages: {
+		type: "enum",
+		options: ["single", "per-request"],
+		description: "Page layout: one page or a page per request"
+	},
+	base: {
+		type: "string",
+		description: "Base path the site is served from, e.g. /docs/"
+	},
+	environment: {
+		type: "string",
+		alias: "e",
+		description: "Environment used to resolve variables"
+	},
+	workspace: {
+		type: "string",
+		alias: "w",
+		description: "Workspace to document (id or name)"
+	},
+	overrides: {
+		type: "string",
+		description: "Config values merged over the config file (a JSON file or inline JSON)"
+	}
+};
+function overridesFrom(args) {
+	const overrides = {};
+	if (args.export) overrides.export = args.export;
+	if (args.theme) overrides.theme = args.theme;
+	if (args.pages) overrides.pages = args.pages;
+	if (args.base) overrides.base = args.base;
+	if (args.environment) overrides.environment = args.environment;
+	if (args.workspace) overrides.workspace = args.workspace;
+	return args.overrides ? mergeConfig(readOverrides(args.overrides), overrides) : overrides;
+}
+const rel = (path) => relative(process.cwd(), path) || ".";
+function summary(context) {
+	const requests = Object.keys(context.document.requests).length;
+	const folders = Object.keys(context.document.folders).length;
+	return [
+		`${colors.dim("Export")}       ${context.exportPath ? rel(context.exportPath) : "(in memory)"} ${colors.dim(`(Yaak ${context.source.yaakVersion})`)}`,
+		`${colors.dim("Workspace")}    ${context.document.workspace.name} ${colors.dim(`· ${requests} requests, ${folders} folders`)}`,
+		`${colors.dim("Environment")}  ${context.document.environment?.name ?? colors.dim("none")}`,
+		`${colors.dim("Theme")}        ${context.theme.name} ${colors.dim(context.theme.packageName ?? rel(context.theme.root))}`,
+		`${colors.dim("Config")}       ${context.configFile ? rel(context.configFile) : colors.dim("none (defaults)")}`
+	].map((line) => `  ${line}`).join("\n");
+}
+const banner = () => `\n  ${colors.bold(colors.magenta("yaakdoc"))} ${colors.dim(`v${VERSION}`)}\n`;
+const subCommands = {
+	dev: defineCommand({
+		meta: {
+			name: "dev",
+			description: "Start the docs dev server (default command)"
+		},
+		args: {
+			...sharedArgs,
+			port: {
+				type: "string",
+				alias: "p",
+				description: "Port (default: 4000)"
+			},
+			host: {
+				type: "string",
+				description: "Host to listen on (use --host 0.0.0.0 to expose)"
+			},
+			open: {
+				type: "boolean",
+				alias: "o",
+				description: "Open the browser"
+			},
+			watch: {
+				type: "boolean",
+				default: true,
+				negativeDescription: "Don't reload when the export or config changes"
+			}
+		},
+		async run({ args }) {
+			const server = await createDevServer({
+				...args.config ? { configFile: args.config } : {},
+				overrides: overridesFrom(args),
+				...args.port ? { port: Number(args.port) } : {},
+				...args.host ? { host: args.host === "true" ? true : args.host } : {},
+				...args.open ? { open: true } : {},
+				watch: args.watch
+			});
+			const context = server.getContext();
+			console.log(banner());
+			console.log(summary(context));
+			console.log(`\n  ${colors.green("➜")}  ${colors.bold("Local")}   ${colors.cyan(server.url)}`);
+			if (context.config.llms.enabled) console.log(`  ${colors.green("➜")}  ${colors.bold("LLMs")}    ${colors.cyan(`${server.url}llms.txt`)}`);
+			console.log(`\n  ${colors.dim(args.watch ? "Watching for changes. Press Ctrl+C to stop." : "Press Ctrl+C to stop.")}\n`);
+			const shutdown = async () => {
+				await server.close();
+				process.exit(0);
+			};
+			process.once("SIGINT", shutdown);
+			process.once("SIGTERM", shutdown);
+		}
+	}),
+	build: defineCommand({
+		meta: {
+			name: "build",
+			description: "Build a static site"
+		},
+		args: {
+			...sharedArgs,
+			outDir: {
+				type: "string",
+				alias: "o",
+				description: "Output directory (default: dist)"
+			}
+		},
+		async run({ args }) {
+			console.log(banner());
+			const started = performance.now();
+			const overrides = overridesFrom(args);
+			if (args.outDir) overrides.outDir = args.outDir;
+			const result = await build({
+				...args.config ? { configFile: args.config } : {},
+				overrides
+			});
+			console.log(summary(result.context));
+			const pages = result.files.filter((file) => file.endsWith(".html")).length;
+			const markdown = result.files.filter((file) => file.endsWith(".md") || file.endsWith(".txt")).length;
+			console.log(`\n  ${colors.green("✔")} Built ${pages} page${pages === 1 ? "" : "s"} and ${markdown} Markdown/llms files into ${colors.cyan(rel(result.outDir))} ${colors.dim(`in ${Math.round(performance.now() - started)}ms`)}\n`);
+		}
+	}),
+	preview: defineCommand({
+		meta: {
+			name: "preview",
+			description: "Serve the built site locally"
+		},
+		args: {
+			config: sharedArgs.config,
+			outDir: {
+				type: "string",
+				description: "Directory to serve (default: dist)"
+			},
+			port: {
+				type: "string",
+				alias: "p",
+				description: "Port (default: 4000)"
+			},
+			host: {
+				type: "string",
+				description: "Host to listen on"
+			},
+			open: {
+				type: "boolean",
+				alias: "o",
+				description: "Open the browser"
+			}
+		},
+		async run({ args }) {
+			const server = await preview({
+				...args.config ? { configFile: args.config } : {},
+				...args.outDir ? { outDir: args.outDir } : {},
+				...args.port ? { port: Number(args.port) } : {},
+				...args.host ? { host: args.host } : {},
+				...args.open ? { open: true } : {}
+			});
+			console.log(banner());
+			console.log(`  ${colors.green("➜")}  ${colors.bold("Preview")} ${colors.cyan(server.url)}\n`);
+		}
+	}),
+	init: defineCommand({
+		meta: {
+			name: "init",
+			description: "Create a yaakdoc.config.json"
+		},
+		args: {
+			yes: {
+				type: "boolean",
+				alias: "y",
+				description: "Use defaults without prompting"
+			},
+			force: {
+				type: "boolean",
+				description: "Overwrite an existing config"
+			}
+		},
+		async run({ args }) {
+			const config = {};
+			if (!args.yes && process.stdin.isTTY) {
+				p.intro(colors.bold(colors.magenta(" yaakdoc init ")));
+				const answers = await p.group({
+					title: () => p.text({
+						message: "Site title",
+						placeholder: "Defaults to the workspace name"
+					}),
+					primary: () => p.text({
+						message: "Primary brand color",
+						placeholder: "#7c3aed",
+						defaultValue: ""
+					}),
+					pages: () => p.select({
+						message: "Page layout",
+						options: [{
+							value: "single",
+							label: "Single page",
+							hint: "everything on one page, like Insomnia Documenter"
+						}, {
+							value: "per-request",
+							label: "Page per request",
+							hint: "better for large APIs"
+						}]
+					}),
+					llms: () => p.confirm({
+						message: "Generate llms.txt and Markdown pages for LLMs?",
+						initialValue: true
+					})
+				}, { onCancel: () => process.exit(1) });
+				if (answers.title) config.branding = {
+					...config.branding,
+					title: answers.title
+				};
+				if (answers.primary) config.branding = {
+					...config.branding,
+					colors: { primary: answers.primary }
+				};
+				config.pages = answers.pages;
+				if (!answers.llms) config.llms = { enabled: false };
+			}
+			const { file } = await init({
+				config,
+				force: Boolean(args.force)
+			});
+			if (!args.yes && process.stdin.isTTY) p.outro(`Created ${colors.cyan(rel(file))}. Run ${colors.bold("npx yaakdoc")} to start.`);
+			else consola.success(`Created ${rel(file)}`);
+		}
+	}),
+	eject: defineCommand({
+		meta: {
+			name: "eject",
+			description: "Copy the theme into your project to customize it"
+		},
+		args: {
+			config: sharedArgs.config,
+			out: {
+				type: "string",
+				description: "Destination directory (default: ./theme)"
+			},
+			force: {
+				type: "boolean",
+				description: "Overwrite a non-empty destination"
+			}
+		},
+		async run({ args }) {
+			const result = await eject({
+				...args.config ? { configFile: args.config } : {},
+				...args.out ? { out: args.out } : {},
+				force: Boolean(args.force)
+			});
+			consola.success(`Ejected theme ${colors.bold(result.theme)} into ${colors.cyan(rel(result.out))} (${result.files.length} files)`);
+			if (result.config?.updated) consola.info(`${result.config.created ? "Created" : "Updated"} ${rel(result.config.file)} → "theme": "./${rel(result.out)}"`);
+			else if (result.config) consola.warn(`Set \`theme: "./${rel(result.out)}"\` in ${rel(result.config.file)} to use the ejected theme.`);
+			if (result.dependencies.length > 0) consola.info(`The theme's dependencies are provided by yaakdoc. To pin your own versions, install:\n  npm i -D ${result.dependencies.join(" ")}`);
+		}
+	})
+};
+const main = defineCommand({
+	meta: {
+		name: "yaakdoc",
+		version: VERSION,
+		description: "API documentation sites from Yaak exports"
+	},
+	default: "dev",
+	subCommands
+});
+/** `yaakdoc ./api.json --port 3000` → `yaakdoc dev ./api.json --port 3000` */
+function normalizeArgs(argv) {
+	const first = argv.find((arg) => !arg.startsWith("-"));
+	if (argv.length > 0 && argv.every((arg) => [
+		"-h",
+		"--help",
+		"-v",
+		"--version"
+	].includes(arg))) return argv;
+	if (first && first in subCommands) return argv;
+	return argv.length === 0 ? argv : ["dev", ...argv];
+}
+async function run(argv = process.argv.slice(2)) {
+	process.on("unhandledRejection", (error) => {
+		consola.error(error instanceof Error ? error.message : error);
+		process.exit(1);
+	});
+	try {
+		await runMain(main, { rawArgs: normalizeArgs(argv) });
+	} catch (error) {
+		consola.error(error.message);
+		process.exit(1);
+	}
+}
+//#endregion
+export { normalizeArgs, run };

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+import { _ as themePackageCandidates, a as withBase, c as Route, f as resolveContext, g as themeFromDefinition, h as resolveTheme, i as emptyOutDir, l as YaakdocOptions, m as ThemeError, n as RenderEntry, o as writeSite, p as ResolvedTheme, r as assertSafeOutDir, s as Context, t as VERSION, u as matchRoute } from "./version-Bwv0ibuY.js";
+import { ResolvedConfig, YaakdocConfig, YaakdocConfig as YaakdocConfig$1, defineConfig } from "@yaakdoc/config";
+import { ThemeDefinition, defineTheme } from "@yaakdoc/react/theme";
+import { Snippet, defineSnippet } from "@yaakdoc/snippets";
+import { Plugin, ViteDevServer } from "vite";
+import { Server } from "node:http";
+import { Assets } from "@yaakdoc/react";
+//#region src/node/build.d.ts
+type BuildResult = {
+  outDir: string;
+  /** Written files, relative to outDir. */
+  files: string[];
+  context: Context;
+};
+/** Builds the static site: client assets, prerendered HTML for every route, Markdown and llms.txt. */
+export declare function build(options?: YaakdocOptions): Promise<BuildResult>;
+type ThemeBundle = {
+  /** Client assets, relative to the output directory. */
+  assets: Assets;
+  /** The SSR entry (exports `render`), in a temporary directory inside the output directory. */
+  ssrEntry: string;
+};
+/**
+ * Builds the theme with Vite: the island runtime and CSS into `outDir` (emptied first), and the SSR
+ * entry, fully bundled so it runs from anywhere. Pass `base: "./"` for client assets that work
+ * under any base path (used to precompile the theme bundled into the Yaak plugin).
+ */
+export declare function bundleTheme(context: Context, outDir: string, options?: {
+  base?: string;
+}): Promise<ThemeBundle>;
+//#endregion
+//#region src/node/dev.d.ts
+type DevServerOptions = YaakdocOptions & {
+  port?: number;
+  host?: string | boolean;
+  open?: boolean;
+  /** Reload when the export/config/assets change (default: true). */
+  watch?: boolean;
+  /** Called after the context is rebuilt because a watched file changed. */
+  onReload?: (context: Context) => void;
+};
+type DevServer = {
+  url: string;
+  vite: ViteDevServer;
+  httpServer: Server;
+  getContext: () => Context;
+  close: () => Promise<void>;
+};
+/** Starts the development server with SSR, HMR for theme code/CSS and reload on export changes. */
+export declare function createDevServer(options?: DevServerOptions): Promise<DevServer>;
+//#endregion
+//#region src/node/eject.d.ts
+type EjectOptions = {
+  cwd?: string;
+  configFile?: string;
+  /** Destination directory (default: `./theme`). */
+  out?: string;
+  /** Overwrite a non-empty destination. */
+  force?: boolean;
+  /** Update (or create) the config to use the ejected theme (default: true). */
+  updateConfig?: boolean;
+};
+type EjectResult = {
+  out: string;
+  files: string[];
+  theme: string;
+  dependencies: string[];
+  config: {
+    file: string;
+    updated: boolean;
+    created: boolean;
+  } | null;
+};
+/** Copies the current theme's source into the project so it can be customized freely. */
+export declare function eject(options?: EjectOptions): Promise<EjectResult>;
+//#endregion
+//#region src/node/init.d.ts
+/** `$schema` value for yaakdoc.config.json: local copy when installed, otherwise unpkg. */
+export declare function schemaUrl(cwd: string): string;
+type InitOptions = {
+  cwd?: string;
+  config?: YaakdocConfig$1;
+  force?: boolean;
+};
+/** Writes a yaakdoc.config.json (with `$schema` for editor autocomplete). */
+export declare function init(options?: InitOptions): Promise<{
+  file: string;
+  config: YaakdocConfig$1;
+}>;
+//#endregion
+//#region src/node/plugin.d.ts
+export declare const VIRTUAL_SERVER = "virtual:yaakdoc/entry-server";
+/** The SSR entry exports `render` (see `RenderEntry`). */
+export declare const VIRTUAL_CLIENT = "virtual:yaakdoc/entry-client";
+/**
+ * The yaakdoc Vite plugin: virtual SSR/client entries, theme-scoped `@/` alias, and fallback
+ * resolution of theme dependencies from the yaakdoc installation (so ejected themes and `npx` work
+ * without installing anything in the project).
+ */
+export declare function yaakdocPlugin(getContext: () => Context, onSsrUpdate?: () => void): Plugin;
+//#endregion
+//#region src/node/preview.d.ts
+type PreviewOptions = {
+  cwd?: string;
+  configFile?: string;
+  outDir?: string;
+  port?: number;
+  host?: string | boolean;
+  open?: boolean;
+};
+/** Serves a built site (like a static host would, including 404.html and base path). */
+export declare function preview(options?: PreviewOptions): Promise<{
+  url: string;
+  server: Server;
+  close: () => Promise<void>;
+}>;
+//#endregion
+export { type BuildResult, type Context, type DevServer, type DevServerOptions, type EjectOptions, type EjectResult, type InitOptions, type PreviewOptions, type RenderEntry, type ResolvedConfig, type ResolvedTheme, type Route, type Snippet, type ThemeBundle, type ThemeDefinition, ThemeError, VERSION, type YaakdocConfig, type YaakdocOptions, assertSafeOutDir, defineConfig, defineSnippet, defineTheme, emptyOutDir, matchRoute, resolveContext, resolveTheme, themeFromDefinition, themePackageCandidates, withBase, writeSite };

package/dist/index.js

@@ -0,0 +1,6 @@
+import { a as matchRoute, c as VERSION, d as themeFromDefinition, f as themePackageCandidates, i as writeSite, l as ThemeError, n as emptyOutDir, r as withBase, s as resolveContext, t as assertSafeOutDir, u as resolveTheme } from "./site-X7q76qYf.js";
+import { a as createDevServer, c as VIRTUAL_CLIENT, i as schemaUrl, l as VIRTUAL_SERVER, n as eject, o as build, r as init, s as bundleTheme, t as preview, u as yaakdocPlugin } from "./preview-Ba1BfVZV.js";
+import { defineConfig } from "@yaakdoc/config";
+import { defineTheme } from "@yaakdoc/react/theme";
+import { defineSnippet } from "@yaakdoc/snippets";
+export { ThemeError, VERSION, VIRTUAL_CLIENT, VIRTUAL_SERVER, assertSafeOutDir, build, bundleTheme, createDevServer, defineConfig, defineSnippet, defineTheme, eject, emptyOutDir, init, matchRoute, preview, resolveContext, resolveTheme, schemaUrl, themeFromDefinition, themePackageCandidates, withBase, writeSite, yaakdocPlugin };

package/dist/open-C4Bh1af9.js

@@ -0,0 +1,19 @@
+import { spawn } from "node:child_process";
+//#region src/node/open.ts
+/** Opens a URL in the default browser (best effort). */
+function openBrowser(url) {
+	const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", [
+		"/c",
+		"start",
+		"",
+		url
+	]] : ["xdg-open", [url]];
+	try {
+		spawn(command, args, {
+			stdio: "ignore",
+			detached: true
+		}).on("error", () => {}).unref();
+	} catch {}
+}
+//#endregion
+export { openBrowser as default };