yaakdoc 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,313 @@
+import { a as createDevServer, n as eject, o as build, r as init, t as preview, u as VERSION } from "./preview-2YFamRKo.js";
+import { relative } from "node:path";
+import { consola } from "consola";
+import colors from "picocolors";
+import * as p from "@clack/prompts";
+import { defineCommand, runMain } from "citty";
+//#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)"
+	}
+};
+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 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")}       ${rel(context.exportPath)} ${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,177 @@
+import { ResolvedConfig, ResolvedConfig as ResolvedConfig$1, YaakdocConfig, YaakdocConfig as YaakdocConfig$1, defineConfig } from "@yaakdoc/config";
+import { ThemeDefinition, ThemeDefinition as ThemeDefinition$1, defineTheme } from "@yaakdoc/react/theme";
+import { Snippet, defineSnippet } from "@yaakdoc/snippets";
+import { PreparedDocument, YaakDocument } from "@yaakdoc/core";
+import { Plugin, ViteDevServer } from "vite";
+import { Server } from "node:http";
+import { PageData, SiteData } from "@yaakdoc/react";
+//#region src/node/theme.d.ts
+type ResolvedTheme = {
+  name: string;
+  definition: ThemeDefinition$1;
+  /** Directory of the theme manifest. */
+  root: string;
+  manifest: string;
+  /** Absolute paths. */
+  entry: string;
+  client: string | null;
+  styles: string[];
+  /** Validated theme options. */
+  options: Record<string, unknown>;
+  /** Package name, when the theme comes from npm. */
+  packageName: string | null;
+  /** Files (importers) used as fallbacks when a theme dependency is not installed locally. */
+  fallbackImporters: string[];
+  highlight: {
+    light: string;
+    dark: string;
+  };
+};
+export declare class ThemeError extends Error {
+  name: string;
+}
+/** Candidate package names for a theme spec: `kiseki` → `@yaakdoc/theme-kiseki`, `yaakdoc-theme-kiseki`. */
+export declare function themePackageCandidates(spec: string): string[];
+/** Loads and validates a theme from a short name, package name or local path. */
+export declare function resolveTheme(spec: string, options: {
+  root: string;
+  themeOptions: Record<string, unknown>;
+}): Promise<ResolvedTheme>;
+//#endregion
+//#region src/node/context.d.ts
+type YaakdocOptions = {
+  /** Project directory (default: `process.cwd()`). */
+  cwd?: string;
+  /** Explicit config file. */
+  configFile?: string;
+  /** Config overrides (e.g. from CLI flags). Takes precedence over the config file. */
+  overrides?: YaakdocConfig$1;
+};
+type Route = {
+  /** URL path including the base, e.g. `/docs/products/`. */
+  path: string;
+  /** Output file relative to outDir, e.g. `products/index.html`. */
+  file: string;
+  page: PageData;
+};
+type Context = {
+  cwd: string;
+  root: string;
+  configFile: string | null;
+  config: ResolvedConfig$1;
+  exportPath: string;
+  source: YaakDocument;
+  theme: ResolvedTheme;
+  document: PreparedDocument;
+  site: SiteData;
+  routes: Route[];
+  notFound: Route;
+  /** Markdown/text outputs keyed by URL path (e.g. `/products.md`, `/llms.txt`). */
+  textFiles: Map<string, string>;
+  /** Local branding assets keyed by URL path → absolute file path. */
+  assets: Map<string, string>;
+  /** Files that trigger a full rebuild of the context when changed. */
+  watchFiles: string[];
+};
+export declare const VERSION: string;
+/** Loads config, export and theme, and prepares everything needed to render the site. */
+export declare function resolveContext(options?: YaakdocOptions): Promise<Context>;
+/** Finds the route for a URL path (ignoring query/hash; `/x` matches `/x/`). */
+export declare function matchRoute(context: Context, pathname: string): Route | null;
+//#endregion
+//#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>;
+//#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";
+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 ResolvedConfig, type ResolvedTheme, type Route, type Snippet, type ThemeDefinition, type YaakdocConfig, type YaakdocOptions, defineConfig, defineSnippet, defineTheme };

package/dist/index.js

@@ -0,0 +1,5 @@
+import { a as createDevServer, c as VIRTUAL_SERVER, d as matchRoute, f as resolveContext, h as themePackageCandidates, i as schemaUrl, l as yaakdocPlugin, m as resolveTheme, n as eject, o as build, p as ThemeError, r as init, s as VIRTUAL_CLIENT, t as preview, u as VERSION } from "./preview-2YFamRKo.js";
+import { defineConfig } from "@yaakdoc/config";
+import { defineTheme } from "@yaakdoc/react/theme";
+import { defineSnippet } from "@yaakdoc/snippets";
+export { ThemeError, VERSION, VIRTUAL_CLIENT, VIRTUAL_SERVER, build, createDevServer, defineConfig, defineSnippet, defineTheme, eject, init, matchRoute, preview, resolveContext, resolveTheme, schemaUrl, themePackageCandidates, 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 };