mdzilla 0.0.1 → 0.0.2

package/README.md

@@ -56,9 +56,24 @@ Flatten any docs source into plain `.md` files:
 npx mdzilla <source> --export <outdir>
 ```
 
+### Single Page
+
+Print a specific page by path and exit:
+
+```sh
+npx mdzilla gh:nuxt/nuxt --page /getting-started/seo-meta
+npx mdzilla gh:nuxt/nuxt --plain --page /getting-started/seo-meta
+```
+
 ### Headless Mode
 
-Use `--plain` for non-interactive output — auto-enabled when called by AI agents or when stdout is not a TTY.
+Use `--plain` (or `--headless`) for non-interactive output — works like `cat` but for rendered markdown. Auto-enabled when piping output or when called by AI agents.
+
+```sh
+npx mdzilla README.md --plain          # Pretty-print a markdown file
+npx mdzilla README.md | head           # Auto-plain when piped (no TTY)
+npx mdzilla gh:unjs/h3 --plain         # List all pages in plain text
+```
 
 ### Keyboard Controls
 

package/dist/_chunks/exporter.mjs

@@ -40,6 +40,45 @@ var DocsManager = class {
 	filter(query) {
 		return fuzzyFilter(this.flat, query, ({ entry }) => [entry.title, entry.path]);
 	}
+	/** Flat entries that are navigable pages (excludes directory stubs). */
+	get pages() {
+		return this.flat.filter((f) => f.entry.page !== false);
+	}
+	/** Find a flat entry by path (exact or with trailing slash). */
+	findByPath(path) {
+		return this.flat.find((f) => f.entry.page !== false && (f.entry.path === path || f.entry.path === path + "/"));
+	}
+	/**
+	* Resolve a page path to its content, trying:
+	* 1. Exact match in the navigation tree
+	* 2. Stripped common prefix (e.g., /docs/guide/... → /guide/...)
+	* 3. Direct source fetch (for HTTP sources with uncrawled paths)
+	*/
+	async resolvePage(path) {
+		const normalized = path.startsWith("/") ? path : "/" + path;
+		const entry = this.findByPath(normalized);
+		if (entry) {
+			const raw = await this.getContent(entry);
+			if (raw) return {
+				entry,
+				raw
+			};
+		}
+		const prefixed = normalized.match(/^\/[^/]+(\/.+)$/);
+		if (prefixed) {
+			const stripped = this.findByPath(prefixed[1]);
+			if (stripped) {
+				const raw = await this.getContent(stripped);
+				if (raw) return {
+					entry: stripped,
+					raw
+				};
+			}
+		}
+		const raw = await this.source.readContent(normalized).catch(() => void 0);
+		if (raw) return { raw };
+		return {};
+	}
 	/** Return indices of matching flat entries (case-insensitive substring). */
 	matchIndices(query) {
 		if (!query) return [];
@@ -341,6 +380,64 @@ var DocsSourceGit = class extends DocsSource {
 	}
 };
 //#endregion
+//#region src/docs/sources/_npm.ts
+/**
+* Parse an npm package spec: `[@scope/]name[@version][/subdir]`
+*/
+function parseNpmSpec(input) {
+	let rest = input;
+	let subdir = "";
+	if (rest.startsWith("@")) {
+		const secondSlash = rest.indexOf("/", rest.indexOf("/") + 1);
+		if (secondSlash > 0) {
+			subdir = rest.slice(secondSlash);
+			rest = rest.slice(0, secondSlash);
+		}
+	} else {
+		const firstSlash = rest.indexOf("/");
+		if (firstSlash > 0) {
+			subdir = rest.slice(firstSlash);
+			rest = rest.slice(0, firstSlash);
+		}
+	}
+	const versionSep = rest.startsWith("@") ? rest.indexOf("@", 1) : rest.indexOf("@");
+	const hasVersion = versionSep > 0;
+	return {
+		name: hasVersion ? rest.slice(0, versionSep) : rest,
+		version: hasVersion ? rest.slice(versionSep + 1) : "latest",
+		subdir
+	};
+}
+/**
+* Fetch package metadata from the npm registry.
+* When `version` is provided, fetches that specific version.
+* Otherwise fetches the full package document.
+*/
+async function fetchNpmInfo(name, version) {
+	const registryURL = version ? `https://registry.npmjs.org/${name}/${version}` : `https://registry.npmjs.org/${name}`;
+	const res = await fetch(registryURL);
+	if (!res.ok) throw new Error(`Failed to fetch package info for ${name}${version ? `@${version}` : ""}: ${res.status} ${res.statusText}`);
+	return res.json();
+}
+/**
+* Detect npmjs.com URLs and extract the package name.
+* Supports: npmjs.com/\<pkg\>, npmjs.com/package/\<pkg\>, www.npmjs.com/package/\<pkg\>
+* Also handles scoped packages: npmjs.com/package/@scope/name
+*/
+function parseNpmURL(url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return;
+	}
+	if (parsed.hostname !== "www.npmjs.com" && parsed.hostname !== "npmjs.com") return;
+	const pkgMatch = parsed.pathname.match(/^\/package\/((?:@[^/]+\/)?[^/]+)\/?$/);
+	if (pkgMatch) return pkgMatch[1];
+	const shortMatch = parsed.pathname.match(/^\/((?:@[^/]+\/)?[^/]+)\/?$/);
+	if (shortMatch && !/^(package|settings|signup|login|org|search)$/.test(shortMatch[1])) return shortMatch[1];
+}
+//#endregion
 //#region src/docs/sources/http.ts
 var DocsSourceHTTP = class extends DocsSource {
 	url;
@@ -352,7 +449,7 @@ var DocsSourceHTTP = class extends DocsSource {
 	constructor(url, options = {}) {
 		super();
 		this.url = url.replace(/\/+$/, "");
-		this._npmPackage = _parseNpmURL(this.url);
+		this._npmPackage = parseNpmURL(this.url);
 		this.options = options;
 	}
 	async load() {
@@ -436,15 +533,10 @@ var DocsSourceHTTP = class extends DocsSource {
 	}
 	/** Load an npm package README from the registry */
 	async _loadNpm(pkg) {
-		const registryURL = `https://registry.npmjs.org/${pkg}`;
 		let markdown;
 		try {
-			const res = await fetch(registryURL, { headers: { accept: "application/json" } });
-			if (!res.ok) markdown = `# ${res.status} ${res.statusText}\n\nFailed to fetch package \`${pkg}\` from npm registry`;
-			else {
-				const data = await res.json();
-				markdown = data.readme || `# ${data.name || pkg}\n\n${data.description || "No README available."}`;
-			}
+			const data = await fetchNpmInfo(pkg);
+			markdown = data.readme || `# ${data.name || pkg}\n\n${data.description || "No README available."}`;
 		} catch (err) {
 			markdown = `# Fetch Error\n\nFailed to fetch package \`${pkg}\`\n\n> ${err instanceof Error ? err.message : String(err)}`;
 		}
@@ -606,24 +698,6 @@ function _extractLinks(markdown, baseURL) {
 		tocPaths
 	};
 }
-/**
-* Detect npmjs.com URLs and extract the package name.
-* Supports: npmjs.com/<pkg>, npmjs.com/package/<pkg>, www.npmjs.com/package/<pkg>
-* Also handles scoped packages: npmjs.com/package/@scope/name
-*/
-function _parseNpmURL(url) {
-	let parsed;
-	try {
-		parsed = new URL(url);
-	} catch {
-		return;
-	}
-	if (parsed.hostname !== "www.npmjs.com" && parsed.hostname !== "npmjs.com") return;
-	const pkgMatch = parsed.pathname.match(/^\/package\/((?:@[^/]+\/)?[^/]+)\/?$/);
-	if (pkgMatch) return pkgMatch[1];
-	const shortMatch = parsed.pathname.match(/^\/((?:@[^/]+\/)?[^/]+)\/?$/);
-	if (shortMatch && !/^(package|settings|signup|login|org|search)$/.test(shortMatch[1])) return shortMatch[1];
-}
 /** Resolve an href relative to a base URL, returning null for external links */
 function _resolveHref(href, baseURL) {
 	try {
@@ -649,14 +723,17 @@ var DocsSourceNpm = class extends DocsSource {
 		this.options = options;
 	}
 	async load() {
-		const source = this.options.subdir ? `${this.src}/${this.options.subdir}` : this.src;
+		const pkg = this.src.startsWith("npm:") ? this.src : `npm:${this.src}`;
+		const source = this.options.subdir ? `${pkg}/${this.options.subdir}` : pkg;
 		const id = source.replace(/[/#:@]/g, "_");
 		const dir = join(tmpdir(), "mdzilla", "npm", id);
 		const { downloadTemplate } = await import("giget");
 		await downloadTemplate(source, {
 			dir,
 			force: true,
-			install: false
+			install: false,
+			providers: { npm: npmProvider },
+			registry: false
 		});
 		let docsDir = dir;
 		for (const sub of ["docs/content", "docs"]) {
@@ -674,6 +751,16 @@ var DocsSourceNpm = class extends DocsSource {
 		return this._fs.readContent(filePath);
 	}
 };
+async function npmProvider(input) {
+	const { name, version, subdir } = parseNpmSpec(input);
+	const info = await fetchNpmInfo(name, version);
+	return {
+		name: info.name,
+		version: info.version,
+		subdir,
+		tar: info.dist.tarball
+	};
+}
 //#endregion
 //#region src/docs/exporter.ts
 var DocsExporter = class {};

package/dist/cli/main.mjs

@@ -3,11 +3,12 @@ import { a as DocsSourceGit, c as DocsManager, i as DocsSourceHTTP, n as DocsExp
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { parseMeta, renderToAnsi, renderToText } from "md4x";
-import { execSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { isAgent } from "std-env";
 import { highlightText } from "@speed-highlight/core/terminal";
-//#region src/cli/ansi.ts
+import { execSync } from "node:child_process";
+//#region src/cli/_ansi.ts
+const noColor = !!(process.env.NO_COLOR || process.env.TERM === "dumb" || !process.stdout.isTTY || isAgent);
 const ESC = "\x1B[";
 const ANSI_RE = /\x1B(?:\[[0-9;]*[a-zA-Z]|\][^\x07\x1B]*(?:\x07|\x1B\\))/g;
 const clear = () => process.stdout.write(`${ESC}2J${ESC}3J${ESC}H`);
@@ -15,11 +16,12 @@ const enterAltScreen = () => process.stdout.write(`${ESC}?1049h`);
 const leaveAltScreen = () => process.stdout.write(`${ESC}?1049l`);
 const hideCursor = () => process.stdout.write(`${ESC}?25l`);
 const showCursor = () => process.stdout.write(`${ESC}?25h`);
-const bold = (s) => `${ESC}1m${s}${ESC}0m`;
-const dim = (s) => `${ESC}2m${s}${ESC}0m`;
-const cyan = (s) => `${ESC}36m${s}${ESC}0m`;
-const yellow = (s) => `${ESC}33m${s}${ESC}0m`;
+const bold = (s) => noColor ? s : `${ESC}1m${s}${ESC}0m`;
+const dim = (s) => noColor ? s : `${ESC}2m${s}${ESC}0m`;
+const cyan = (s) => noColor ? s : `${ESC}36m${s}${ESC}0m`;
+const yellow = (s) => noColor ? s : `${ESC}33m${s}${ESC}0m`;
 const bgGray = (s) => {
+	if (noColor) return s;
 	const bg = `${ESC}48;5;237m`;
 	return `${bg}${s.replaceAll(`${ESC}0m`, `${ESC}0m${bg}`)}${ESC}0m`;
 };
@@ -151,7 +153,155 @@ function highlight(text, query) {
 	return text.slice(0, idx) + bold(yellow(text.slice(idx, idx + query.length))) + text.slice(idx + query.length);
 }
 //#endregion
-//#region src/cli/nav.ts
+//#region src/cli/_usage.ts
+function printUsage(hasInput) {
+	const bin = `${bold(cyan("npx"))} ${bold("mdzilla")}`;
+	const banner = isAgent ? [] : [
+		dim("        /\\    /\\    /\\"),
+		dim("       /  \\  /  \\  /  \\"),
+		dim("      ╭────────────────╮"),
+		dim("      │") + bold(" # ") + dim(" ░░░░░       │"),
+		dim("      │    ░░░░░░░░    │"),
+		dim("      │    ░░░░░░      │"),
+		dim("      │    ░░░░░░░     │"),
+		dim("      │    ░░░░        │"),
+		dim("      │   ") + cyan("◉") + dim("        ") + cyan("◉") + dim("   │"),
+		dim("      ╰─┬──┬──┬──┬──┬──╯"),
+		dim("        ▽  ▽  ▽  ▽  ▽"),
+		""
+	];
+	console.log([
+		...banner,
+		`  ${bold("mdzilla")} ${dim("— Markdown browser for humans and agents")}`,
+		"",
+		`${bold("Usage:")}`,
+		`  ${bin} ${cyan("<dir>")}                 ${dim("Browse local docs directory")}`,
+		`  ${bin} ${cyan("<file.md>")}             ${dim("Render a single markdown file")}`,
+		`  ${bin} ${cyan("gh:owner/repo")}         ${dim("Browse GitHub repo docs")}`,
+		`  ${bin} ${cyan("npm:package-name")}      ${dim("Browse npm package docs")}`,
+		`  ${bin} ${cyan("https://example.com")}   ${dim("Browse remote docs via HTTP")}`,
+		"",
+		`${bold("Options:")}`,
+		`  ${cyan("--export")} ${dim("<dir>")}   Export docs to flat .md files`,
+		`  ${cyan("--page")} ${dim("<path>")}    Print a single page and exit`,
+		`  ${cyan("--plain")}          Plain text output (no TUI)`,
+		`  ${cyan("--headless")}       Alias for --plain`,
+		`  ${cyan("-h, --help")}       Show this help message`,
+		"",
+		`${bold("Remarks:")}`,
+		`  ${dim("Headless mode is auto-enabled when called by AI agents or when stdout is not a TTY.")}`,
+		`  ${dim("GitHub source (gh:) looks for a docs/ directory in the repository.")}`,
+		`  ${dim("HTTP source tries /llms.txt first, then fetches with Accept: text/markdown,")}`,
+		`  ${dim("and falls back to HTML-to-markdown conversion.")}`
+	].join("\n"));
+	process.exit(hasInput ? 0 : 1);
+}
+//#endregion
+//#region src/cli/content.ts
+async function renderContent(content, entry, navWidth) {
+	const contentWidth = (process.stdout.columns || 80) - navWidth - 2;
+	const codeBlocks = [];
+	const codeRe = /```(\w+)[^\n]*\n([\s\S]*?)```/g;
+	let m;
+	while ((m = codeRe.exec(content)) !== null) codeBlocks.push({
+		lang: m[1],
+		code: m[2]
+	});
+	const highlights = /* @__PURE__ */ new Map();
+	if (codeBlocks.length > 0) await Promise.all(codeBlocks.map(({ lang, code }) => highlightText(code, lang).then((h) => highlights.set(code, h)).catch(() => {})));
+	const rawLines = renderToAnsi(content).split("\n");
+	const lines = [];
+	lines.push(dim(entry.path));
+	lines.push("");
+	let inDim = false;
+	let dimLines = [];
+	let blockIdx = 0;
+	for (const rawLine of rawLines) {
+		if (!inDim && rawLine.includes("\x1B[2m") && !rawLine.includes("\x1B[22m")) {
+			inDim = true;
+			dimLines = [rawLine];
+			continue;
+		}
+		if (inDim) {
+			if (rawLine.startsWith("\x1B[22m")) {
+				inDim = false;
+				const block = codeBlocks[blockIdx];
+				const hl = block ? highlights.get(block.code) : void 0;
+				if (hl) {
+					const hlLines = hl.split("\n");
+					if (hlLines.length > 0 && hlLines[hlLines.length - 1] === "") hlLines.pop();
+					for (const hlLine of hlLines) for (const w of wrapAnsi("  " + hlLine, contentWidth)) lines.push(w + "\x1B[0m");
+				} else for (const dl of dimLines) for (const w of wrapAnsi(dl, contentWidth)) lines.push(w + "\x1B[0m");
+				blockIdx++;
+				lines.push("");
+			} else dimLines.push(rawLine);
+			continue;
+		}
+		for (const w of wrapAnsi(rawLine, contentWidth)) lines.push(w + "\x1B[0m");
+	}
+	return lines;
+}
+//#endregion
+//#region src/cli/render.ts
+async function singleFileMode(filePath, plain, isURL) {
+	const raw = isURL ? await fetch(filePath, { headers: { accept: "text/markdown, text/plain;q=0.9, text/html;q=0.8" } }).then((r) => r.text()) : await readFile(filePath, "utf8");
+	if (plain) {
+		process.stdout.write(renderToText(raw) + "\n");
+		return;
+	}
+	const meta = parseMeta(raw);
+	const slug = isURL ? new URL(filePath).pathname.split("/").pop()?.replace(/\.md$/i, "") || "page" : basename(filePath, ".md");
+	const lines = await renderContent(raw, {
+		slug,
+		path: "/" + slug,
+		title: meta.title || slug,
+		order: 0
+	}, 0);
+	process.stdout.write(lines.join("\n") + "\n");
+}
+async function pageMode(docs, pagePath, plain) {
+	const normalized = pagePath.startsWith("/") ? pagePath : "/" + pagePath;
+	const { entry, raw } = await docs.resolvePage(normalized);
+	if (!raw) {
+		console.error(`Page not found: ${pagePath}`);
+		process.exit(1);
+	}
+	const slug = (entry?.entry.path || normalized).split("/").pop() || "";
+	const navEntry = entry?.entry || {
+		slug,
+		path: normalized,
+		title: parseMeta(raw).title || slug,
+		order: 0
+	};
+	if (plain) process.stdout.write(renderToText(raw) + "\n");
+	else {
+		const lines = await renderContent(raw, navEntry, 0);
+		process.stdout.write(lines.join("\n") + "\n");
+	}
+}
+async function plainMode(docs, pagePath) {
+	const navigable = docs.pages;
+	if (navigable.length === 0) {
+		console.log("No pages found.");
+		return;
+	}
+	const tocLines = ["Table of Contents", ""];
+	for (const f of navigable) {
+		const indent = "  ".repeat(f.depth);
+		tocLines.push(`${indent}- [${f.entry.title}](${f.entry.path})`);
+	}
+	process.stdout.write(tocLines.join("\n") + "\n");
+	let targetEntry = navigable[0];
+	if (pagePath) {
+		const resolved = await docs.resolvePage(pagePath);
+		if (resolved.raw) process.stdout.write(renderToText(resolved.raw) + "\n\n");
+	} else {
+		const raw = await docs.getContent(targetEntry);
+		if (raw) process.stdout.write(renderToText(raw) + "\n\n");
+	}
+}
+//#endregion
+//#region src/cli/interactive/nav.ts
 function calcNavWidth(flat) {
 	const cols = process.stdout.columns || 80;
 	let max = 6;
@@ -224,52 +374,7 @@ function computeTreePrefixes(flat, isLast) {
 	return prefixes;
 }
 //#endregion
-//#region src/cli/content.ts
-async function renderContent(content, entry, navWidth) {
-	const contentWidth = (process.stdout.columns || 80) - navWidth - 2;
-	const codeBlocks = [];
-	const codeRe = /```(\w+)[^\n]*\n([\s\S]*?)```/g;
-	let m;
-	while ((m = codeRe.exec(content)) !== null) codeBlocks.push({
-		lang: m[1],
-		code: m[2]
-	});
-	const highlights = /* @__PURE__ */ new Map();
-	if (codeBlocks.length > 0) await Promise.all(codeBlocks.map(({ lang, code }) => highlightText(code, lang).then((h) => highlights.set(code, h)).catch(() => {})));
-	const rawLines = renderToAnsi(content).split("\n");
-	const lines = [];
-	lines.push(dim(entry.path));
-	lines.push("");
-	let inDim = false;
-	let dimLines = [];
-	let blockIdx = 0;
-	for (const rawLine of rawLines) {
-		if (!inDim && rawLine.includes("\x1B[2m") && !rawLine.includes("\x1B[22m")) {
-			inDim = true;
-			dimLines = [rawLine];
-			continue;
-		}
-		if (inDim) {
-			if (rawLine.startsWith("\x1B[22m")) {
-				inDim = false;
-				const block = codeBlocks[blockIdx];
-				const hl = block ? highlights.get(block.code) : void 0;
-				if (hl) {
-					const hlLines = hl.split("\n");
-					if (hlLines.length > 0 && hlLines[hlLines.length - 1] === "") hlLines.pop();
-					for (const hlLine of hlLines) for (const w of wrapAnsi("  " + hlLine, contentWidth)) lines.push(w + "\x1B[0m");
-				} else for (const dl of dimLines) for (const w of wrapAnsi(dl, contentWidth)) lines.push(w + "\x1B[0m");
-				blockIdx++;
-				lines.push("");
-			} else dimLines.push(rawLine);
-			continue;
-		}
-		for (const w of wrapAnsi(rawLine, contentWidth)) lines.push(w + "\x1B[0m");
-	}
-	return lines;
-}
-//#endregion
-//#region src/cli/render.ts
+//#region src/cli/interactive/render.ts
 function renderSplit(flat, cursor, contentLines, contentScroll, search, focus, contentSearch, searchMatches, sidebarVisible = true) {
 	const rows = process.stdout.rows || 24;
 	const navWidth = sidebarVisible ? calcNavWidth(flat) : 0;
@@ -292,79 +397,41 @@ function renderSplit(flat, cursor, contentLines, contentScroll, search, focus, c
 	return output.map((l) => l + eol).join("\n");
 }
 //#endregion
-//#region src/cli/main.ts
-async function main() {
-	const { values, positionals } = parseArgs({
-		args: process.argv.slice(2),
-		options: {
-			help: {
-				type: "boolean",
-				short: "h"
-			},
-			export: { type: "string" },
-			plain: {
-				type: "boolean",
-				default: isAgent || !process.stdout.isTTY
-			},
-			headless: { type: "boolean" }
-		},
-		allowPositionals: true
-	});
-	const exportDir = values.export;
-	const docsDir = positionals[0];
-	const plain = values.plain || values.headless || docsDir?.startsWith("npm:") || false;
-	if (values.help || !docsDir) {
-		const bin = `${bold(cyan("npx"))} ${bold("mdzilla")}`;
-		console.log([
-			dim("        /\\    /\\    /\\"),
-			dim("       /  \\  /  \\  /  \\"),
-			dim("      ╭────────────────╮"),
-			dim("      │") + bold(" # ") + dim(" ░░░░░       │"),
-			dim("      │    ░░░░░░░░    │"),
-			dim("      │    ░░░░░░      │"),
-			dim("      │    ░░░░░░░     │"),
-			dim("      │    ░░░░        │"),
-			dim("      │   ") + cyan("◉") + dim("        ") + cyan("◉") + dim("   │"),
-			dim("      ╰─┬──┬──┬──┬──┬──╯"),
-			dim("        ▽  ▽  ▽  ▽  ▽"),
-			"",
-			`  ${bold("mdzilla")} ${dim("— Markdown browser for humans and agents")}`,
-			"",
-			`${bold("Usage:")}`,
-			`  ${bin} ${cyan("<dir>")}                 ${dim("Browse local docs directory")}`,
-			`  ${bin} ${cyan("<file.md>")}             ${dim("Render a single markdown file")}`,
-			`  ${bin} ${cyan("gh:owner/repo")}         ${dim("Browse GitHub repo docs")}`,
-			`  ${bin} ${cyan("npm:package-name")}      ${dim("Browse npm package docs")}`,
-			`  ${bin} ${cyan("https://example.com")}   ${dim("Browse remote docs via HTTP")}`,
-			"",
-			`${bold("Options:")}`,
-			`  ${cyan("--export")} ${dim("<dir>")}   Export docs to flat .md files`,
-			`  ${cyan("--plain")}          Plain text output (no TUI)`,
-			`  ${cyan("--headless")}       Alias for --plain`,
-			`  ${cyan("-h, --help")}       Show this help message`,
-			"",
-			`${bold("Remarks:")}`,
-			`  ${dim("Headless mode is auto-enabled when called by AI agents or when stdout is not a TTY.")}`,
-			`  ${dim("GitHub source (gh:) looks for a docs/ directory in the repository.")}`,
-			`  ${dim("HTTP source tries /llms.txt first, then fetches with Accept: text/markdown,")}`,
-			`  ${dim("and falls back to HTML-to-markdown conversion.")}`
-		].join("\n"));
-		process.exit(docsDir ? 0 : 1);
-	}
-	if (docsDir.endsWith(".md")) return singleFileMode(docsDir, plain);
-	const docs = new DocsManager(docsDir.startsWith("http://") || docsDir.startsWith("https://") ? new DocsSourceHTTP(docsDir) : docsDir.startsWith("gh:") ? new DocsSourceGit(docsDir) : docsDir.startsWith("npm:") ? new DocsSourceNpm(docsDir) : new DocsSourceFS(docsDir));
-	await docs.load();
-	if (exportDir) {
-		await new DocsExporterFS(exportDir).export(docs, { plainText: plain });
-		console.log(`Exported ${docs.flat.filter((f) => f.entry.page !== false).length} pages to ${exportDir}`);
-		return;
-	}
-	if (plain) return plainMode(docs);
+//#region src/cli/interactive/index.ts
+async function interactiveMode(docs) {
 	const flat = docs.flat;
 	if (flat.length === 0) {
 		console.log("No pages found.");
 		process.exit(0);
 	}
+	const isNavigable = (list, i) => list[i]?.entry.page !== false;
+	const nextNavigable = (list, from, dir) => {
+		let i = from + dir;
+		while (i >= 0 && i < list.length) {
+			if (isNavigable(list, i)) return i;
+			i += dir;
+		}
+		return from;
+	};
+	const firstNavigable = (list) => {
+		for (let i = 0; i < list.length; i++) if (isNavigable(list, i)) return i;
+		return 0;
+	};
+	let cursor = firstNavigable(flat);
+	let searching = false;
+	let searchQuery = "";
+	let searchMatches = [];
+	let contentScroll = 0;
+	let contentLines = [];
+	let loadedPath = "";
+	let focusContent = false;
+	let contentSearching = false;
+	let contentSearchQuery = "";
+	let contentMatches = [];
+	let contentMatchIdx = 0;
+	let sidebarVisible = true;
+	let contentLinks = [];
+	let linkIdx = -1;
 	const extractLinks = (lines) => {
 		const links = [];
 		const re = /\x1B\]8;;([^\x07\x1B]+?)(?:\x07|\x1B\\)/g;
@@ -396,34 +463,6 @@ async function main() {
 		}
 		return line;
 	};
-	const isNavigable = (list, i) => list[i]?.entry.page !== false;
-	const nextNavigable = (list, from, dir) => {
-		let i = from + dir;
-		while (i >= 0 && i < list.length) {
-			if (isNavigable(list, i)) return i;
-			i += dir;
-		}
-		return from;
-	};
-	const firstNavigable = (list) => {
-		for (let i = 0; i < list.length; i++) if (isNavigable(list, i)) return i;
-		return 0;
-	};
-	let cursor = firstNavigable(flat);
-	let searching = false;
-	let searchQuery = "";
-	let searchMatches = [];
-	let contentScroll = 0;
-	let contentLines = [];
-	let loadedPath = "";
-	let focusContent = false;
-	let contentSearching = false;
-	let contentSearchQuery = "";
-	let contentMatches = [];
-	let contentMatchIdx = 0;
-	let sidebarVisible = true;
-	let contentLinks = [];
-	let linkIdx = -1;
 	const findContentMatches = (query) => {
 		if (!query) return [];
 		const lower = query.toLowerCase();
@@ -569,8 +608,8 @@ async function main() {
 		} catch {}
 		else {
 			const target = url.replace(/^\.\//, "/").replace(/\/$/, "");
-			const idx = flat.findIndex((f) => f.entry.path === target || f.entry.path === target + "/");
-			if (idx >= 0 && isNavigable(flat, idx)) {
+			const idx = flat.indexOf(docs.findByPath(target));
+			if (idx >= 0) {
 				cursor = idx;
 				focusContent = false;
 				linkIdx = -1;
@@ -690,36 +729,54 @@ async function main() {
 		}
 	}
 }
-async function singleFileMode(filePath, plain) {
-	const raw = await readFile(filePath, "utf8");
-	if (plain) {
-		process.stdout.write(renderToText(raw) + "\n");
-		return;
-	}
-	const meta = parseMeta(raw);
-	const slug = basename(filePath, ".md");
-	const lines = await renderContent(raw, {
-		slug,
-		path: "/" + slug,
-		title: meta.title || slug,
-		order: 0
-	}, 0);
-	process.stdout.write(lines.join("\n") + "\n");
-}
-async function plainMode(docs) {
-	const navigable = docs.flat.filter((f) => f.entry.page !== false);
-	if (navigable.length === 0) {
-		console.log("No pages found.");
+//#endregion
+//#region src/cli/main.ts
+async function main() {
+	process.stdout.on("error", (err) => {
+		if (err.code === "EPIPE") process.exit(0);
+		throw err;
+	});
+	const { values, positionals } = parseArgs({
+		args: process.argv.slice(2),
+		options: {
+			help: {
+				type: "boolean",
+				short: "h"
+			},
+			export: { type: "string" },
+			page: {
+				type: "string",
+				short: "p"
+			},
+			plain: {
+				type: "boolean",
+				default: isAgent || !process.stdout.isTTY
+			},
+			headless: { type: "boolean" }
+		},
+		allowPositionals: true
+	});
+	const exportDir = values.export;
+	const docsDir = positionals[0];
+	const plain = values.plain || values.headless || docsDir?.startsWith("npm:") || false;
+	if (values.help || !docsDir) return printUsage(!!docsDir);
+	const isURL = docsDir.startsWith("http://") || docsDir.startsWith("https://");
+	if (docsDir.endsWith(".md")) return singleFileMode(docsDir, plain, isURL);
+	const docs = new DocsManager(isURL ? new DocsSourceHTTP(docsDir) : docsDir.startsWith("gh:") ? new DocsSourceGit(docsDir) : docsDir.startsWith("npm:") ? new DocsSourceNpm(docsDir) : new DocsSourceFS(docsDir));
+	await docs.load();
+	if (exportDir) {
+		await new DocsExporterFS(exportDir).export(docs, { plainText: plain });
+		console.log(`Exported ${docs.pages.length} pages to ${exportDir}`);
 		return;
 	}
-	const tocLines = ["# Table of Contents", ""];
-	for (const f of navigable) {
-		const indent = "  ".repeat(f.depth);
-		tocLines.push(`${indent}- [${f.entry.title}](${f.entry.path})`);
+	let pagePath = values.page;
+	if (!pagePath && isURL) {
+		const urlPath = new URL(docsDir).pathname.replace(/\/+$/, "");
+		if (urlPath && urlPath !== "/") pagePath = urlPath;
 	}
-	process.stdout.write(tocLines.join("\n") + "\n\n---\n\n");
-	const raw = await docs.getContent(navigable[0]);
-	if (raw) process.stdout.write(renderToText(raw) + "\n");
+	if (pagePath && !plain) return pageMode(docs, pagePath, plain);
+	if (plain) return plainMode(docs, pagePath);
+	return interactiveMode(docs);
 }
 main().catch((err) => {
 	showCursor();

package/dist/index.d.mts

@@ -124,6 +124,20 @@ declare class DocsManager {
   invalidate(filePath: string): void;
   /** Fuzzy filter flat entries by query string. */
   filter(query: string): FlatEntry[];
+  /** Flat entries that are navigable pages (excludes directory stubs). */
+  get pages(): FlatEntry[];
+  /** Find a flat entry by path (exact or with trailing slash). */
+  findByPath(path: string): FlatEntry | undefined;
+  /**
+   * Resolve a page path to its content, trying:
+   * 1. Exact match in the navigation tree
+   * 2. Stripped common prefix (e.g., /docs/guide/... → /guide/...)
+   * 3. Direct source fetch (for HTTP sources with uncrawled paths)
+   */
+  resolvePage(path: string): Promise<{
+    entry?: FlatEntry;
+    raw?: string;
+  }>;
   /** Return indices of matching flat entries (case-insensitive substring). */
   matchIndices(query: string): number[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdzilla",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "",
   "license": "MIT",
   "repository": "pi0/mdzilla",