@askrjs/cli 0.0.22 → 0.0.24

package/dist/add.js

@@ -41,10 +41,12 @@ function helpText() {
 		"Usage:",
 		"  askr add page <name> [--branch app|public] [--cwd <dir>] [--title <title>] [--route <path>] [--force]",
 		"  askr add action <name> --route <path> [--cwd <dir>] [--force]",
+		"  askr add database postgres|sqlite [--cwd <dir>]",
 		"",
 		"Commands:",
 		"  page      Scaffold a route page and register it in a route-first SPA branch",
 		"  action    Scaffold a browser descriptor, server handler, registration, authorization, and test",
+		"  database  Scaffold a dialect-specific Askr ORM database definition",
 		"",
 		"Options:",
 		"  --branch <name>  Route branch to target (default: app)",
@@ -59,6 +61,7 @@ function helpText() {
 		"  askr add page ops/audit-log --branch public",
 		"  askr add page approvals --title \"Human approvals\" --route /app/approvals",
 		"  askr add action approve-request --route /requests/{id}",
+		"  askr add database sqlite",
 		"",
 		"Notes:",
 		"  Page generation supports route-first SPA projects created from `askr create spa`.",
@@ -478,6 +481,95 @@ async function addAction(parsed, io, writeChanges) {
 	io.log(`  Test: ${path.relative(projectRoot, testFile).replace(/\\/g, "/")}`);
 	return 0;
 }
+async function addDatabase(parsed, io, writeChanges) {
+	if (parsed.name !== "postgres" && parsed.name !== "sqlite") {
+		io.error("Database dialect must be `postgres` or `sqlite`.");
+		return 1;
+	}
+	const projectRoot = path.resolve(parsed.cwd);
+	const manifestFile = path.join(projectRoot, "package.json");
+	const definitionFile = path.join(projectRoot, "src", "database", "index.ts");
+	const generatedFile = path.join(projectRoot, "src", "database", "generated.ts");
+	const migrationKeep = path.join(projectRoot, "src", "database", "migrations", ".gitkeep");
+	const environmentFile = path.join(projectRoot, ".env.example");
+	if (!await pathExists(manifestFile)) {
+		io.error("Database generation requires a project package.json.");
+		return 1;
+	}
+	if (!parsed.force && (await pathExists(definitionFile) || await pathExists(generatedFile))) {
+		io.error("Database files already exist. Pass --force to replace generated scaffolding.");
+		return 1;
+	}
+	try {
+		const manifest = JSON.parse(await fs.readFile(manifestFile, "utf8"));
+		manifest.dependencies = {
+			...manifest.dependencies,
+			"@askrjs/orm": "0.0.0",
+			...parsed.name === "postgres" ? {
+				pg: "^8.16.0",
+				"pg-query-stream": "^4.10.0"
+			} : {}
+		};
+		manifest.dependencies = Object.fromEntries(Object.entries(manifest.dependencies).sort(([left], [right]) => left.localeCompare(right)));
+		const currentEnvironment = await fs.readFile(environmentFile, "utf8").catch(() => "");
+		const additions = (parsed.name === "postgres" ? ["DATABASE_URL=postgres://postgres:postgres@localhost:5432/app", "DATABASE_SHADOW_URL=postgres://postgres:postgres@localhost:5432/app_shadow"] : ["DATABASE_PATH=./data/app.sqlite"]).filter((line) => !currentEnvironment.includes(`${line.split("=")[0]}=`));
+		const environment = `${currentEnvironment}${currentEnvironment && !currentEnvironment.endsWith("\n") ? "\n" : ""}${additions.join("\n")}${additions.length ? "\n" : ""}`;
+		const driverImport = parsed.name;
+		const definition = [
+			"import { defineDatabase } from '@askrjs/orm';",
+			`import { ${driverImport} } from '@askrjs/orm/${driverImport}';`,
+			"import { generated } from './generated.js';",
+			"",
+			"export const database = defineDatabase({",
+			`  driver: ${driverImport}(),`,
+			"  tables: {},",
+			"  queries: {},",
+			"  generated,",
+			"});",
+			""
+		].join("\n");
+		const generated = [
+			"import type { GeneratedDatabaseArtifact } from '@askrjs/orm';",
+			"",
+			"// Generated by `askr database generate`; commit this file.",
+			"export const generated = {",
+			"  manifest: { migrations: [] },",
+			"  queries: {},",
+			"} as const satisfies GeneratedDatabaseArtifact;",
+			""
+		].join("\n");
+		await writeChanges([
+			{
+				filePath: definitionFile,
+				content: definition
+			},
+			{
+				filePath: generatedFile,
+				content: generated
+			},
+			{
+				filePath: migrationKeep,
+				content: ""
+			},
+			{
+				filePath: environmentFile,
+				content: environment
+			},
+			{
+				filePath: manifestFile,
+				content: `${JSON.stringify(manifest, null, 2)}\n`
+			}
+		]);
+	} catch (error) {
+		io.error("Failed to write generated database artifacts.");
+		io.error(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+	io.log(`Added ${parsed.name} database support.`);
+	io.log("  Definition: src/database/index.ts");
+	io.log("  Migrations: src/database/migrations");
+	return 0;
+}
 async function runAddCli(args = process.argv.slice(2), io = console, writeChanges = writeFileChanges) {
 	const parsed = parseArgs(args);
 	if (parsed.errors.length > 0) {
@@ -494,6 +586,7 @@ async function runAddCli(args = process.argv.slice(2), io = console, writeChange
 	}
 	if (parsed.command === "page") return addPage(parsed, io, writeChanges);
 	if (parsed.command === "action") return addAction(parsed, io, writeChanges);
+	if (parsed.command === "database") return addDatabase(parsed, io, writeChanges);
 	io.error(`Unknown add command: ${parsed.command}`);
 	io.error("Run `askr add --help` to see available commands.");
 	return 1;

package/dist/cli.js

@@ -37,6 +37,7 @@ function printHelp(io = console) {
 	io.log("  check      Run the complete project validation path");
 	io.log("  create     Create a new Askr app from a template or product prompt");
 	io.log("  database   Generate, validate, and migrate project databases");
+	io.log("  docs       Check or snapshot consumer-visible API documentation");
 	io.log("  doctor     Diagnose environment and Askr project health");
 	io.log("  generate   Generate an @askrjs/fetch client from OpenAPI");
 	io.log("  openapi    Generate or check an OpenAPI YAML artifact");
@@ -91,6 +92,10 @@ async function runCli(args = process.argv.slice(2), io = console) {
 		const { runDatabaseCommand } = await import("./database.js");
 		return runDatabaseCommand(args.slice(1), io);
 	}
+	if (command === "docs") {
+		const { runDocsCli } = await import("./docs-BSPiXiAW.js");
+		return runDocsCli(args.slice(1), io);
+	}
 	if (command === "analyze") {
 		const { runAnalyzeCli } = await import("./analyze.js");
 		return runAnalyzeCli(args.slice(1), io);

package/dist/database.js

@@ -14,7 +14,7 @@ async function loadOrmTooling(cwd) {
 		if (!relative) throw new Error("Missing import export for @askrjs/orm/tooling.");
 		entry = path.resolve(path.dirname(manifestPath), relative);
 	} catch (error) {
-		throw new Error("This project does not have @askrjs/orm installed. Install it before running `askr database`.", { cause: error });
+		throw new Error("This project does not have @askrjs/orm installed. Run `npm install @askrjs/orm` before `askr database`.", { cause: error });
 	}
 	const tooling = await import(pathToFileURL(entry).href);
 	if (typeof tooling.runDatabaseCli !== "function") throw new Error("The installed @askrjs/orm package does not expose compatible database tooling.");

package/dist/docs-BSPiXiAW.js

@@ -0,0 +1,224 @@
+import { t as isDirectExecution } from "./is-direct-execution-Cdlr-ZUl.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import ts from "typescript";
+//#region src/docs.ts
+const text = (parts) => ts.displayPartsToString([...parts]).trim();
+const commentText = (comment) => typeof comment === "string" ? comment.trim() : comment ? String(comment).trim() : "";
+function tagsFor(symbol, checker) {
+	const result = {};
+	for (const tag of symbol.getJsDocTags(checker)) {
+		const value = typeof tag.text === "string" ? tag.text : ts.displayPartsToString([...tag.text ?? []]);
+		(result[tag.name] ??= []).push(value.trim());
+	}
+	return result;
+}
+function declarationFor(symbol) {
+	return symbol.declarations?.find((declaration) => /\.d\.(?:ts|mts|cts)$/.test(declaration.getSourceFile().fileName));
+}
+function signatureFor(symbol, checker) {
+	const declaration = declarationFor(symbol);
+	if (!declaration) return symbol.name;
+	if (ts.isTypeAliasDeclaration(declaration)) return `${symbol.name}: ${declaration.type.getText(declaration.getSourceFile())}`;
+	if (ts.isInterfaceDeclaration(declaration) || ts.isClassDeclaration(declaration) || ts.isEnumDeclaration(declaration)) return declaration.getText(declaration.getSourceFile());
+	const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+	return `${symbol.name}: ${checker.typeToString(type, declaration, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope)}`;
+}
+function memberDocs(symbol, checker) {
+	const declaration = declarationFor(symbol);
+	if (!declaration) return [];
+	if (ts.isVariableDeclaration(declaration)) return checker.getTypeOfSymbolAtLocation(symbol, declaration).getProperties().flatMap((property) => {
+		const propertyDeclaration = declarationFor(property);
+		if (!propertyDeclaration) return [];
+		const summary = text(property.getDocumentationComment(checker));
+		return [{
+			name: property.name,
+			summary,
+			tags: tagsFor(property, checker),
+			signature: checker.typeToString(checker.getTypeOfSymbolAtLocation(property, propertyDeclaration), propertyDeclaration)
+		}];
+	});
+	if (!(ts.isInterfaceDeclaration(declaration) || ts.isClassDeclaration(declaration) || ts.isEnumDeclaration(declaration) || ts.isTypeLiteralNode(declaration))) return [];
+	return (ts.isEnumDeclaration(declaration) ? declaration.members : ts.isTypeLiteralNode(declaration) ? declaration.members : declaration.members).flatMap((member) => {
+		const name = member.name && ts.isIdentifier(member.name) ? member.name.text : void 0;
+		if (!name) return [];
+		const docs = ts.getJSDocCommentsAndTags(member);
+		const summary = docs.filter(ts.isJSDoc).map((doc) => commentText(doc.comment)).filter(Boolean).join("\n");
+		const tags = {};
+		for (const tag of docs) {
+			if (!("tagName" in tag)) continue;
+			const name = tag.tagName.text;
+			(tags[name] ??= []).push(tag.comment ? String(tag.comment) : "");
+		}
+		return [{
+			name,
+			summary,
+			tags,
+			signature: member.getText(member.getSourceFile())
+		}];
+	});
+}
+function resolveTypes(value, out) {
+	if (typeof value === "string") out.push(value);
+	else if (value && typeof value === "object") {
+		for (const [key, child] of Object.entries(value)) if (key === "types") resolveTypes(child, out);
+		else if (key !== "default" && key !== "import" && key !== "require" && key !== "node" && key !== "browser") resolveTypes(child, out);
+	}
+}
+async function walk(directory) {
+	const entries = await fs.readdir(directory, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		const current = path.join(directory, entry.name);
+		if (entry.isDirectory()) files.push(...await walk(current));
+		else files.push(current);
+	}
+	return files;
+}
+async function declarationEntrypoints(root, pkg) {
+	const targets = [];
+	resolveTypes(pkg.exports, targets);
+	if (targets.length === 0) targets.push("./dist/index.d.ts", "./dist/index.d.mts", "./dist/index.d.cts");
+	const files = await walk(root);
+	const result = [];
+	for (const target of new Set(targets)) {
+		if (!target.endsWith(".d.ts") && !target.endsWith(".d.mts") && !target.endsWith(".d.cts")) continue;
+		if (target.includes("*")) {
+			const prefix = target.slice(0, target.indexOf("*"));
+			const suffix = target.slice(target.indexOf("*") + 1);
+			for (const file of files) if (file.startsWith(path.resolve(root, prefix)) && file.endsWith(suffix)) result.push({
+				name: target,
+				file
+			});
+		} else {
+			const file = path.resolve(root, target);
+			if (files.includes(file)) result.push({
+				name: target,
+				file
+			});
+		}
+	}
+	return result;
+}
+async function inspectDocs(root = process.cwd()) {
+	const pkg = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8"));
+	const entries = await declarationEntrypoints(root, pkg);
+	const program = ts.createProgram(entries.map((entry) => entry.file), {
+		allowJs: false,
+		skipLibCheck: true,
+		moduleResolution: ts.ModuleResolutionKind.Bundler
+	});
+	const checker = program.getTypeChecker();
+	const symbols = [];
+	const diagnostics = [];
+	for (const entry of entries) {
+		const source = program.getSourceFile(entry.file);
+		const module = source && checker.getSymbolAtLocation(source);
+		if (!module) continue;
+		for (const exported of checker.getExportsOfModule(module)) {
+			const symbol = exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported;
+			const declaration = declarationFor(symbol) ?? declarationFor(exported);
+			if (!declaration) continue;
+			const summary = text(symbol.getDocumentationComment(checker));
+			const tags = tagsFor(symbol, checker);
+			const signature = signatureFor(symbol, checker);
+			const members = memberDocs(symbol, checker);
+			const declarationPath = path.relative(root, declaration.getSourceFile().fileName);
+			const base = {
+				package: pkg.name ?? path.basename(root),
+				entrypoint: entry.name,
+				symbol: exported.name,
+				declaration: declarationPath
+			};
+			if (!summary || summary === exported.name) diagnostics.push({
+				...base,
+				missing: "summary"
+			});
+			const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+			for (const signatureInfo of type.getCallSignatures()) {
+				for (const parameter of signatureInfo.parameters) if (!tags.param?.some((value) => {
+					return (value.trim().split(/\s+/, 1)[0] ?? "").replace(/^\{[^}]+\}\s*/, "") === parameter.name;
+				})) diagnostics.push({
+					...base,
+					missing: `@param ${parameter.name}`
+				});
+				if (signatureInfo.getReturnType().flags !== ts.TypeFlags.Void && !tags.returns) diagnostics.push({
+					...base,
+					missing: "@returns"
+				});
+			}
+			for (const member of members) if (!member.summary || member.summary === member.name) diagnostics.push({
+				...base,
+				symbol: `${exported.name}.${member.name}`,
+				missing: "member summary"
+			});
+			symbols.push({
+				name: exported.name,
+				entrypoint: entry.name,
+				declaration: declarationPath,
+				summary,
+				...tags.remarks ? { remarks: tags.remarks.join("\n") } : {},
+				tags,
+				signature,
+				members
+			});
+		}
+	}
+	symbols.sort((a, b) => `${a.entrypoint}:${a.name}`.localeCompare(`${b.entrypoint}:${b.name}`));
+	diagnostics.sort((a, b) => `${a.entrypoint}:${a.symbol}:${a.missing}`.localeCompare(`${b.entrypoint}:${b.symbol}:${b.missing}`));
+	return {
+		snapshot: {
+			package: pkg.name ?? path.basename(root),
+			version: pkg.version,
+			generatedBy: "askr docs snapshot",
+			symbols
+		},
+		diagnostics
+	};
+}
+//#endregion
+//#region src/bin/docs.ts
+async function runDocsCli(args = process.argv.slice(2), io = console) {
+	const command = args[0] ?? "check";
+	const json = args.includes("--json");
+	const rootIndex = args.findIndex((arg) => arg === "--root" || arg.startsWith("--root="));
+	const rootArg = rootIndex >= 0 ? args[rootIndex].includes("=") ? args[rootIndex].slice(7) : args[rootIndex + 1] : void 0;
+	const root = path.resolve(rootArg ?? process.cwd());
+	if (command === "--help" || command === "-h") {
+		io.log("askr docs check|snapshot [--json] [--root <path>] [--output <path>]");
+		return 0;
+	}
+	if (command !== "check" && command !== "snapshot") {
+		io.error(`Unknown docs command: ${command}`);
+		return 1;
+	}
+	try {
+		const result = await inspectDocs(root);
+		if (command === "snapshot") {
+			const outputIndex = args.findIndex((arg) => arg === "--output" || arg.startsWith("--output="));
+			const outputArg = outputIndex >= 0 ? args[outputIndex].includes("=") ? args[outputIndex].slice(9) : args[outputIndex + 1] : void 0;
+			const output = outputArg ? path.resolve(root, outputArg) : path.join(root, "docs", "api-snapshot.json");
+			await fs.mkdir(path.dirname(output), { recursive: true });
+			await fs.writeFile(output, `${JSON.stringify(result.snapshot, null, 2)}\n`, "utf8");
+			if (json) io.log(JSON.stringify({
+				output,
+				symbols: result.snapshot.symbols.length,
+				diagnostics: result.diagnostics.length
+			}));
+			else io.log(`Wrote ${path.relative(root, output)} (${result.snapshot.symbols.length} symbols)`);
+			return result.diagnostics.length === 0 ? 0 : 1;
+		}
+		if (json) io.log(JSON.stringify(result.diagnostics));
+		else if (result.diagnostics.length) for (const diagnostic of result.diagnostics) io.error(`${diagnostic.package} ${diagnostic.entrypoint} ${diagnostic.symbol} (${diagnostic.declaration}): missing ${diagnostic.missing}`);
+		else io.log(`Documentation check passed (${result.snapshot.symbols.length} symbols)`);
+		return result.diagnostics.length === 0 ? 0 : 1;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (json) io.log(JSON.stringify({ error: message }));
+		else io.error(`Documentation check failed: ${message}`);
+		return 1;
+	}
+}
+if (isDirectExecution(import.meta.url)) runDocsCli();
+//#endregion
+export { runDocsCli };

package/dist/generate.js

@@ -588,11 +588,13 @@ async function writeGenerated(directory, files, check) {
 			force: true
 		});
 	} catch (error) {
-		await rm(output, {
-			recursive: true,
-			force: true
-		});
-		if (moved) await rename(backup, output);
+		if (moved) {
+			await rm(output, {
+				recursive: true,
+				force: true
+			});
+			await rename(backup, output);
+		}
 		throw error;
 	} finally {
 		await rm(stage, {

package/dist/ssg-config.d.ts

@@ -1,23 +1,31 @@
 //#region src/ssg/sitemap.d.ts
+/** Allowed XML sitemap change-frequency values. */
 type SitemapChangeFrequency = "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+/** Metadata emitted for one generated sitemap URL. */
 interface SitemapRouteConfig {
   /** Canonical URL. Relative values resolve against siteUrl. */
   url?: string;
   /** W3C date/datetime or Date describing the last meaningful page update. */
   lastModified?: string | Date;
+  /** How often the resource is expected to change. */
   changeFrequency?: SitemapChangeFrequency;
   /** Relative crawl priority from 0 through 1. */
   priority?: number;
   /** hreflang to canonical URL mapping, including optional x-default. */
   alternates?: Readonly<Record<string, string>>;
 }
+/** Route information passed to a sitemap metadata resolver. */
 interface SitemapRouteContext {
+  /** Published route pathname. */
   path: string;
+  /** Generated file path for the route. */
   filePath: string;
+  /** Render status reported by the SSG pipeline. */
   status: string;
   /** Resolved rendered canonical URL, when the document declares one. */
   canonical?: string;
 }
+/** Configuration for sitemap generation during static-site generation. */
 interface SitemapConfig {
   /** Site-wide values inherited by included routes. */
   defaults?: Omit<SitemapRouteConfig, "url" | "alternates">;
@@ -28,77 +36,108 @@ interface SitemapConfig {
   /** Output path relative to the SSG output directory. */
   output?: string;
   /** Maintain a Sitemap directive in robots.txt. Defaults to true. */
+  /** Maintain a Sitemap directive in robots.txt; an object selects its output path. */
   robots?: boolean | {
     output?: string;
   };
   /** Optional lower limits for deterministic partitioning and tests. */
   limits?: {
-    urlsPerFile?: number;
-    bytesPerFile?: number;
+    /** Maximum URLs per generated file. */ urlsPerFile?: number;
+    /** Maximum bytes per generated file. */ bytesPerFile?: number;
   };
   /** Maximum concurrent async route metadata resolvers. Defaults to 16. */
   resolverConcurrency?: number;
 }
 //#endregion
 //#region src/ssg/output-report.d.ts
+/** Raw and gzip byte limits for one emitted artifact. */
 interface SsgByteBudget {
+  /** Maximum uncompressed byte count. */
   raw?: number;
+  /** Maximum gzip-compressed byte count. */
   gzip?: number;
 }
+/** Optional limits applied while validating an SSG output report. */
 interface SsgOutputBudgets {
   /** Default raw/gzip HTML limits for every route. */
   routes?: SsgByteBudget;
   /** Exact route overrides merged with defaults; false exempts a route. */
   routeOverrides?: Readonly<Record<string, SsgByteBudget | false>>;
+  /** Hydration-size limits, expressed as a share of raw HTML. */
   hydration?: {
     /** Maximum hydration bytes as a 0..1 share of raw HTML. */
+    /** Default maximum hydration share from 0 through 1. */
     share?: number;
     /** Exact share overrides; false exempts a route. */
+    /** Exact route shares; false exempts a route. */
     routes?: Readonly<Record<string, number | false>>;
   };
   /** Exact emitted asset raw/gzip limits; false exempts an asset. */
   assets?: Readonly<Record<string, SsgByteBudget | false>>;
+  /** Aggregate JavaScript and CSS limits. */
   aggregate?: {
     javascript?: SsgByteBudget;
     css?: SsgByteBudget;
   };
 }
+/** Configuration for generating and validating an SSG output report. */
 interface SsgOutputReportConfig {
+  /** Deployment pathname prefix stripped from root-absolute asset references. */
+  basePath?: string;
+  /** Byte and hydration limits to enforce. */
   budgets?: SsgOutputBudgets;
   /** Number of largest pages retained in the summary. Defaults to 20. */
   largestPages?: number;
   /** Number of largest assets retained in the summary. Defaults to 20. */
   largestAssets?: number;
 }
+/** Raw and gzip sizes measured for an emitted resource. */
 interface SsgOutputSize {
+  /** Uncompressed byte count. */
   raw: number;
+  /** Gzip-compressed byte count. */
   gzip: number;
 }
+/** An emitted JavaScript, CSS, or other static asset. */
 interface SsgOutputAsset extends SsgOutputSize {
+  /** Output-relative asset path. */
   path: string;
+  /** Classified asset type. */
   type: "javascript" | "css" | "other";
 }
+/** Size and initial-asset information for one generated route. */
 interface SsgOutputRoute {
+  /** Published route pathname. */
   route: string;
+  /** Output-relative HTML file path. */
   filePath: string;
+  /** Rendered HTML sizes. */
   html: SsgOutputSize;
+  /** Hydration payload size and share of HTML. */
   hydration: {
     raw: number;
     share: number;
   };
+  /** Initial JavaScript and CSS assets referenced by the route. */
   initial: {
     javascript: SsgOutputAsset[];
     css: SsgOutputAsset[];
   };
 }
+/** Complete size report produced for one SSG output directory. */
 interface SsgOutputReport {
+  /** Schema version of this report. */
   version: 1;
+  /** All generated route measurements. */
   routes: SsgOutputRoute[];
+  /** All emitted non-HTML assets. */
   assets: SsgOutputAsset[];
+  /** Aggregate JavaScript and CSS sizes. */
   aggregate: {
     javascript: SsgOutputSize;
     css: SsgOutputSize;
   };
+  /** Largest pages and assets retained for diagnostics. */
   largest: {
     pages: SsgOutputRoute[];
     assets: SsgOutputAsset[];

package/dist/ssg.js

@@ -404,7 +404,7 @@ function isReportableAsset(filePath) {
 async function removeSsgOutputReport(outputDir) {
 	await fs.rm(path.join(outputDir, REPORT_PATH), { force: true });
 }
-function localReference(reference, documentPath) {
+function localReference(reference, documentPath, basePath) {
 	let resolved;
 	try {
 		const portableDocumentPath = documentPath.replaceAll("\\", "/");
@@ -416,11 +416,25 @@ function localReference(reference, documentPath) {
 	}
 	if (resolved.origin !== "https://askr.invalid") return void 0;
 	try {
-		return decodeURIComponent(resolved.pathname).replace(/^\/+/, "");
+		let pathname = decodeURIComponent(resolved.pathname);
+		if (basePath && reference.startsWith("/") && (pathname === basePath || pathname.startsWith(`${basePath}/`))) pathname = pathname.slice(basePath.length);
+		return pathname.replace(/^\/+/, "");
 	} catch {
 		return;
 	}
 }
+function deploymentBasePath(value) {
+	if (value === void 0 || value === "" || value === "/") return "";
+	if (typeof value !== "string" || !value.startsWith("/") || value.startsWith("//") || value.includes("?") || value.includes("#") || value.includes("\\")) throw new Error("outputReport.basePath must be an absolute URL pathname");
+	let decoded;
+	try {
+		decoded = decodeURIComponent(value);
+	} catch {
+		throw new Error("outputReport.basePath must use valid URL encoding");
+	}
+	if (decoded.split("/").some((segment) => segment === "." || segment === "..")) throw new Error("outputReport.basePath must not contain dot-segment traversal");
+	return decoded.replace(/\/+$/, "");
+}
 function positiveCount(value, fallback, label) {
 	const resolved = value ?? fallback;
 	if (!Number.isSafeInteger(resolved) || resolved < 1) throw new Error(`${label} must be a positive integer`);
@@ -433,6 +447,7 @@ function validateByteBudget(budget, label) {
 	}
 }
 function validateConfig(config) {
+	const basePath = deploymentBasePath(config.basePath);
 	const budgets = config.budgets;
 	validateByteBudget(budgets?.routes, "outputReport.budgets.routes");
 	for (const [route, budget] of Object.entries(budgets?.routeOverrides ?? {})) if (budget !== false) validateByteBudget(budget, `route override ${route}`);
@@ -443,6 +458,7 @@ function validateConfig(config) {
 	for (const [route, share] of hydrationShares) if (share !== void 0 && share !== false && (!Number.isFinite(share) || share < 0 || share > 1)) throw new Error(`hydration share for ${route} must be from 0 through 1`);
 	positiveCount(config.largestPages, 20, "outputReport.largestPages");
 	positiveCount(config.largestAssets, 20, "outputReport.largestAssets");
+	return basePath;
 }
 function budgetViolations(report, budgets = {}) {
 	const violations = [];
@@ -474,7 +490,7 @@ function budgetViolations(report, budgets = {}) {
 	return violations;
 }
 async function writeSsgOutputReport(outputDir, routes, inspections, config = {}) {
-	validateConfig(config);
+	const basePath = validateConfig(config);
 	const assets = [];
 	for (const filePath of (await emittedFiles(outputDir)).filter(isReportableAsset)) {
 		const measured = size(await fs.readFile(path.join(outputDir, filePath)));
@@ -495,7 +511,7 @@ async function writeSsgOutputReport(outputDir, routes, inspections, config = {})
 		const referenced = (references, type) => {
 			const resolved = [];
 			for (const reference of references) {
-				const localPath = localReference(reference, inspection.filePath);
+				const localPath = localReference(reference, inspection.filePath, basePath);
 				if (!localPath) continue;
 				const asset = assetMap.get(localPath);
 				if (!asset) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askrjs/cli",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "Unified CLI for the Askr platform",
   "homepage": "https://github.com/askrjs/askr-cli#readme",
   "bugs": {
@@ -43,13 +43,16 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:changelog": "vp test run -c vitest.config.ts tests/changelog.test.ts",
     "test:peer-floor": "vp test run -c vitest.integration.config.ts tests/integration/peer-floor.test.ts",
+    "test:registry-database": "vp test run -c vitest.integration.config.ts tests/integration/registry-database.test.ts",
     "test:publint": "publint",
     "pack:check": "npm pack --ignore-scripts --dry-run --json",
     "test:templates": "vp test run -c vitest.integration.config.ts tests/integration/packed-templates.test.ts",
     "bench": "npm run build --silent && npm run bench:analyze && node --import tsx benchmarks/cli.mjs --gate",
     "bench:analyze": "vp test bench --run -c vitest.bench.config.ts",
     "bench:json": "npm run build --silent && node --import tsx benchmarks/cli.mjs --gate --json",
-    "check": "npm run lint && npm run typecheck && npm run test:coverage && npm run test:changelog && npm run build && npm run test:publint && npm run pack:check",
+    "docs:check": "npm run build && node ./dist/cli.js docs check",
+    "docs:snapshot": "npm run build && node ./dist/cli.js docs snapshot",
+    "check": "npm run lint && npm run typecheck && npm run test:coverage && npm run test:changelog && npm run build && npm run docs:check && npm run test:publint && npm run pack:check",
     "prepack": "npm run build",
     "prepublishOnly": "npm run check && npm run test:templates && npm run test:peer-floor"
   },