@askrjs/cli 0.0.23 → 0.0.25

package/dist/add.d.ts

@@ -1,4 +1,4 @@
-import { n as writeFileChanges } from "./file-changes-cmFN-rF8.js";
+import { n as writeFileChanges } from "./file-changes-Va4jkhMm.js";
 //#region src/bin/add.d.ts
 type CliIo = Pick<Console, "error" | "log">;
 type WriteChanges = typeof writeFileChanges;

package/dist/add.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { t as isDirectExecution } from "./is-direct-execution-Cdlr-ZUl.js";
-import { t as writeFileChanges } from "./file-changes-BAFLhEHZ.js";
+import { t as writeFileChanges } from "./file-changes-CsrYAEYu.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 //#region src/bin/add.ts
@@ -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`.",
@@ -362,9 +365,11 @@ async function addPage(parsed, io, writeChanges) {
 		return 1;
 	}
 	const importSpecifier = toImportSpecifier(routesFile, pageFile);
+	let routeFileContent = "";
 	let updatedRoutes = "";
 	try {
-		updatedRoutes = createUpdatedRouteFile(await fs.readFile(routesFile, "utf8"), {
+		routeFileContent = await fs.readFile(routesFile, "utf8");
+		updatedRoutes = createUpdatedRouteFile(routeFileContent, {
 			componentName,
 			importSpecifier,
 			routePath
@@ -384,7 +389,8 @@ async function addPage(parsed, io, writeChanges) {
 			})
 		}, {
 			filePath: routesFile,
-			content: updatedRoutes
+			content: updatedRoutes,
+			expectedContent: routeFileContent
 		}]);
 	} catch (error) {
 		io.error("Failed to write generated page artifacts.");
@@ -434,6 +440,7 @@ async function addAction(parsed, io, writeChanges) {
 			routePath: parsed.routePath,
 			slug
 		});
+		const [registryContent, authorizationContent] = await Promise.all([fs.readFile(registryFile, "utf8"), fs.readFile(authorizationFile, "utf8")]);
 		const actions = await discoverDeclaredActions(projectRoot, {
 			filePath: descriptorFile,
 			content: descriptor
@@ -460,11 +467,13 @@ async function addAction(parsed, io, writeChanges) {
 			},
 			{
 				filePath: registryFile,
-				content: renderServerActionRegistry(actions)
+				content: renderServerActionRegistry(actions),
+				expectedContent: registryContent
 			},
 			{
 				filePath: authorizationFile,
-				content: renderAuthorizationRegistry(actions)
+				content: renderAuthorizationRegistry(actions),
+				expectedContent: authorizationContent
 			}
 		]);
 	} catch (error) {
@@ -478,6 +487,101 @@ 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 manifestContent = await fs.readFile(manifestFile, "utf8");
+		const manifest = JSON.parse(manifestContent);
+		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((error) => {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") return null;
+			throw error;
+		});
+		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,
+				expectedContent: currentEnvironment
+			},
+			{
+				filePath: manifestFile,
+				content: `${JSON.stringify(manifest, null, 2)}\n`,
+				expectedContent: manifestContent
+			}
+		]);
+	} 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 +598,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/analyze.d.ts

@@ -1,4 +1,4 @@
-import { t as FileChange } from "./file-changes-cmFN-rF8.js";
+import { t as FileChange } from "./file-changes-Va4jkhMm.js";
 import ts from "typescript";
 //#region src/analyze/types.d.ts
 declare const ANALYZE_SCHEMA_VERSION = 1;

package/dist/analyze.js

@@ -71,7 +71,7 @@ async function runAnalyzeCli(args = process.argv.slice(2), io = console, runtime
 			io.log(helpText.trimEnd());
 			return 0;
 		}
-		const report = await (runtime.analyze ?? (await import("./runner-D2iNzz9g.js")).runAnalysis)({
+		const report = await (runtime.analyze ?? (await import("./runner-CtcqO3cF.js")).runAnalysis)({
 			cwd: parsed.cwd,
 			workspacePatterns: parsed.workspacePatterns,
 			check: parsed.check

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,12 +92,16 @@ 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);
 	}
 	if (command === "check" || command === "doctor" || command === "repair") {
-		const { runGuardrailCli } = await import("./guardrails-BVxzrcBX.js");
+		const { runGuardrailCli } = await import("./guardrails-uLDOExsl.js");
 		return runGuardrailCli(command, args.slice(1), io);
 	}
 	if (command === "generate") {

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/file-changes-CsrYAEYu.js

@@ -0,0 +1,154 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/file-changes.ts
+const LOCK_RETRY_MS = 10;
+const LOCK_TIMEOUT_MS = 1e4;
+const ORPHANED_LOCK_AGE_MS = 3e4;
+function isNodeError(error, code) {
+	return error instanceof Error && "code" in error && error.code === code;
+}
+function delay(milliseconds) {
+	return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function ownerIsAlive(lockPath) {
+	try {
+		const owner = JSON.parse(await fs.readFile(path.join(lockPath, "owner.json"), "utf8"));
+		if (!Number.isInteger(owner.pid) || owner.pid <= 0) return void 0;
+		try {
+			process.kill(owner.pid, 0);
+			return true;
+		} catch (error) {
+			if (isNodeError(error, "ESRCH")) return false;
+			return true;
+		}
+	} catch {
+		return;
+	}
+}
+async function removeOrphanedLock(lockPath) {
+	const ownerAlive = await ownerIsAlive(lockPath);
+	if (ownerAlive === true) return false;
+	if (ownerAlive === void 0) {
+		const stat = await fs.stat(lockPath).catch(() => null);
+		if (!stat || Date.now() - stat.mtimeMs < ORPHANED_LOCK_AGE_MS) return false;
+	}
+	await fs.rm(lockPath, {
+		recursive: true,
+		force: true
+	});
+	return true;
+}
+async function acquireFileLock(filePath) {
+	const lockPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.askr-lock`);
+	const deadline = Date.now() + LOCK_TIMEOUT_MS;
+	while (true) try {
+		await fs.mkdir(lockPath);
+		await fs.writeFile(path.join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid })}\n`, { flag: "wx" });
+		return { lockPath };
+	} catch (error) {
+		if (!isNodeError(error, "EEXIST")) {
+			await fs.rm(lockPath, {
+				recursive: true,
+				force: true
+			}).catch(() => void 0);
+			throw error;
+		}
+		if (await removeOrphanedLock(lockPath)) continue;
+		if (Date.now() >= deadline) throw new Error(`Timed out waiting for file transaction lock: ${filePath}`);
+		await delay(LOCK_RETRY_MS);
+	}
+}
+async function releaseFileLocks(locks) {
+	await Promise.all([...locks].reverse().map((lock) => fs.rm(lock.lockPath, {
+		recursive: true,
+		force: true
+	})));
+}
+async function readCurrentContent(filePath) {
+	try {
+		return await fs.readFile(filePath, "utf8");
+	} catch (error) {
+		if (isNodeError(error, "ENOENT")) return null;
+		throw error;
+	}
+}
+function hasExpectedContent(change) {
+	return Object.prototype.hasOwnProperty.call(change, "expectedContent");
+}
+async function remove(paths) {
+	await Promise.all(paths.map((filePath) => fs.rm(filePath, { force: true }).catch(() => void 0)));
+}
+async function restore(changes) {
+	let complete = true;
+	for (const change of [...changes].reverse()) try {
+		if (change.original === null) {
+			await fs.rm(change.filePath, { force: true });
+			continue;
+		}
+		const rollbackPath = path.join(path.dirname(change.filePath), `.${path.basename(change.filePath)}.askr-rollback-${randomUUID()}`);
+		await fs.writeFile(rollbackPath, change.original, {
+			flag: "wx",
+			mode: change.mode
+		});
+		await fs.rename(rollbackPath, change.filePath);
+	} catch {
+		complete = false;
+	}
+	return complete;
+}
+async function writeFileChanges(changes, options = {}) {
+	const ordered = [...changes].sort((left, right) => left.filePath.localeCompare(right.filePath));
+	if (new Set(ordered.map((change) => change.filePath)).size !== ordered.length) throw new Error("File changes contain duplicate target paths.");
+	const replace = options.replace ?? fs.rename;
+	const guarded = ordered.filter(hasExpectedContent);
+	const locks = [];
+	try {
+		for (const change of guarded) {
+			await fs.mkdir(path.dirname(change.filePath), { recursive: true });
+			locks.push(await acquireFileLock(change.filePath));
+		}
+		for (const change of guarded) if (await readCurrentContent(change.filePath) !== change.expectedContent) throw new Error(`File changed before writing: ${change.filePath}`);
+		await writeStagedChanges(ordered, replace);
+	} finally {
+		await releaseFileLocks(locks);
+	}
+}
+async function writeStagedChanges(ordered, replace) {
+	const staged = [];
+	try {
+		for (const change of ordered) {
+			await fs.mkdir(path.dirname(change.filePath), { recursive: true });
+			const stat = await fs.stat(change.filePath).catch(() => null);
+			const original = stat ? await fs.readFile(change.filePath) : null;
+			const temporaryPath = path.join(path.dirname(change.filePath), `.${path.basename(change.filePath)}.askr-change-${randomUUID()}`);
+			const mode = stat?.mode ?? 420;
+			await fs.writeFile(temporaryPath, change.content, {
+				flag: "wx",
+				mode
+			});
+			staged.push({
+				...change,
+				original,
+				mode,
+				temporaryPath
+			});
+		}
+	} catch (error) {
+		await remove(staged.map((change) => change.temporaryPath));
+		throw error;
+	}
+	const replaced = [];
+	try {
+		for (const change of staged) {
+			await replace(change.temporaryPath, change.filePath);
+			replaced.push(change);
+		}
+	} catch {
+		const complete = await restore(replaced);
+		await remove(staged.map((change) => change.temporaryPath));
+		throw new Error(complete ? "File replacement failed; completed changes were rolled back." : "File replacement failed and rollback was incomplete.");
+	}
+}
+//#endregion
+export { writeFileChanges as t };

package/dist/{file-changes-cmFN-rF8.d.ts → file-changes-Va4jkhMm.d.ts}

@@ -2,6 +2,8 @@
 interface FileChange {
   readonly filePath: string;
   readonly content: string;
+  /** Content observed while planning a shared-file edit; `null` means the file was absent. */
+  readonly expectedContent?: string | null;
 }
 interface FileChangeWriterOptions {
   readonly replace?: (temporaryPath: string, filePath: string) => Promise<void>;

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/{guardrails-BVxzrcBX.js → guardrails-uLDOExsl.js}

@@ -98,7 +98,7 @@ async function runGuardrailCli(command, args = process.argv.slice(2), io = conso
 			cwd: parsed.cwd,
 			workspacePatterns: parsed.workspacePatterns
 		};
-		const { runCheck, runDoctor, runRepair } = await import("./runner-N2qHCBar.js");
+		const { runCheck, runDoctor, runRepair } = await import("./runner-D_GIsgIj.js");
 		const report = command === "doctor" ? await runDoctor(options, runtime) : command === "repair" ? await runRepair(options) : await runCheck(options, runtime);
 		if (parsed.json) io.log(JSON.stringify(report));
 		else if (report.command === "doctor") printDoctor(report, io);

package/dist/{runner-D2iNzz9g.js → runner-CtcqO3cF.js}

@@ -1,4 +1,4 @@
-import { t as writeFileChanges } from "./file-changes-BAFLhEHZ.js";
+import { t as writeFileChanges } from "./file-changes-CsrYAEYu.js";
 import { discoverWorkspaceProject } from "./discovery-DUDrZCIC.js";
 import fs from "node:fs/promises";
 import path from "node:path";

package/dist/{runner-N2qHCBar.js → runner-D_GIsgIj.js}

@@ -1,6 +1,6 @@
 import { t as inspectBundledSkills } from "./skills-C72Z3-Cr.js";
 import { discoverWorkspaceProject } from "./discovery-DUDrZCIC.js";
-import { analysisHasBlockingFindings, runAnalysis } from "./runner-D2iNzz9g.js";
+import { analysisHasBlockingFindings, runAnalysis } from "./runner-CtcqO3cF.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { spawn } from "node:child_process";

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,79 +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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askrjs/cli",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "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"
   },

package/dist/file-changes-BAFLhEHZ.js

@@ -1,66 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { randomUUID } from "node:crypto";
-//#region src/file-changes.ts
-async function remove(paths) {
-	await Promise.all(paths.map((filePath) => fs.rm(filePath, { force: true }).catch(() => void 0)));
-}
-async function restore(changes) {
-	let complete = true;
-	for (const change of [...changes].reverse()) try {
-		if (change.original === null) {
-			await fs.rm(change.filePath, { force: true });
-			continue;
-		}
-		const rollbackPath = path.join(path.dirname(change.filePath), `.${path.basename(change.filePath)}.askr-rollback-${randomUUID()}`);
-		await fs.writeFile(rollbackPath, change.original, {
-			flag: "wx",
-			mode: change.mode
-		});
-		await fs.rename(rollbackPath, change.filePath);
-	} catch {
-		complete = false;
-	}
-	return complete;
-}
-async function writeFileChanges(changes, options = {}) {
-	const ordered = [...changes].sort((left, right) => left.filePath.localeCompare(right.filePath));
-	if (new Set(ordered.map((change) => change.filePath)).size !== ordered.length) throw new Error("File changes contain duplicate target paths.");
-	const replace = options.replace ?? fs.rename;
-	const staged = [];
-	try {
-		for (const change of ordered) {
-			await fs.mkdir(path.dirname(change.filePath), { recursive: true });
-			const stat = await fs.stat(change.filePath).catch(() => null);
-			const original = stat ? await fs.readFile(change.filePath) : null;
-			const temporaryPath = path.join(path.dirname(change.filePath), `.${path.basename(change.filePath)}.askr-change-${randomUUID()}`);
-			const mode = stat?.mode ?? 420;
-			await fs.writeFile(temporaryPath, change.content, {
-				flag: "wx",
-				mode
-			});
-			staged.push({
-				...change,
-				original,
-				mode,
-				temporaryPath
-			});
-		}
-	} catch (error) {
-		await remove(staged.map((change) => change.temporaryPath));
-		throw error;
-	}
-	const replaced = [];
-	try {
-		for (const change of staged) {
-			await replace(change.temporaryPath, change.filePath);
-			replaced.push(change);
-		}
-	} catch {
-		const complete = await restore(replaced);
-		await remove(staged.map((change) => change.temporaryPath));
-		throw new Error(complete ? "File replacement failed; completed changes were rolled back." : "File replacement failed and rollback was incomplete.");
-	}
-}
-//#endregion
-export { writeFileChanges as t };