@askrjs/cli 0.0.3 → 0.0.4

package/README.md

@@ -50,6 +50,43 @@ unless you opt out with `--no-skills`.
 The installed command is `askr`. Subcommands are intentionally not published
 as compatibility binaries.
 
+## Static sitemap generation
+
+`askr ssg` writes `sitemap.xml` from the concrete routes generated during the
+build. Set the canonical deploy URL in the TypeScript config:
+
+```ts
+export const staticConfig = {
+  registry,
+  outputDir: "./dist",
+  siteUrl: "https://example.com",
+  sitemap: {
+    defaults: { changeFrequency: "weekly" },
+    routes: {
+      "/404": false,
+      "/docs": { priority: 0.8, lastModified: "2026-07-18" },
+    },
+  },
+};
+```
+
+The sitemap config types are available from `@askrjs/cli/ssg` for projects that
+want an explicit annotation.
+
+Successful and incrementally skipped concrete routes are included by default.
+Failed routes and wildcard templates are excluded. Route settings support a
+canonical URL override, `lastModified`, `changeFrequency`, `priority`, and
+`hreflang` alternates. Use `resolve(route)` for data-driven metadata or return
+`false` to exclude a route. Set `sitemap: false` for an intentional opt-out.
+
+The CLI validates real calendar dates, bounds asynchronous metadata resolution,
+and enforces the sitemap protocol limits of 50,000 URLs and 50 MB per file.
+Larger sites receive deterministic sitemap chunks plus a sitemap index. It also
+creates or updates `robots.txt` while preserving unrelated directives and tracks
+owned files so stale chunks and previous output paths are removed. Full and
+incremental builds publish through a sibling staging directory, so route output,
+metadata, assets, and sitemap artifacts change together or not at all.
+
 ## OpenAPI artifacts
 
 `askr openapi` loads a TypeScript module whose default export exposes

package/dist/add.d.ts

@@ -0,0 +1,16 @@
+//#region src/file-changes.d.ts
+interface FileChange {
+  readonly filePath: string;
+  readonly content: string;
+}
+interface FileChangeWriterOptions {
+  readonly replace?: (temporaryPath: string, filePath: string) => Promise<void>;
+}
+declare function writeFileChanges(changes: readonly FileChange[], options?: FileChangeWriterOptions): Promise<void>;
+//#endregion
+//#region src/bin/add.d.ts
+type CliIo = Pick<Console, "error" | "log">;
+type WriteChanges = typeof writeFileChanges;
+declare function runAddCli(args?: string[], io?: CliIo, writeChanges?: WriteChanges): Promise<number>;
+//#endregion
+export { runAddCli };

package/dist/add.js

@@ -142,32 +142,34 @@ function parseArgs(args) {
 		const arg = args[index];
 		if (arg === "--help" || arg === "-h") parsed.help = true;
 		else if (arg === "--force") parsed.force = true;
-		else if (arg === "--branch") if (index + 1 >= args.length) parsed.errors.push("Missing value for --branch");
+		else if (arg === "--branch") if (index + 1 >= args.length || args[index + 1].startsWith("-")) parsed.errors.push("Missing value for --branch");
 		else {
 			parsed.branch = args[index + 1];
 			index += 1;
 		}
-		else if (arg === "--cwd") if (index + 1 >= args.length) parsed.errors.push("Missing value for --cwd");
+		else if (arg === "--cwd") if (index + 1 >= args.length || args[index + 1].startsWith("-")) parsed.errors.push("Missing value for --cwd");
 		else {
 			parsed.cwd = args[index + 1];
 			index += 1;
 		}
-		else if (arg === "--title") if (index + 1 >= args.length) parsed.errors.push("Missing value for --title");
+		else if (arg === "--title") if (index + 1 >= args.length || args[index + 1].startsWith("-")) parsed.errors.push("Missing value for --title");
 		else {
 			parsed.title = args[index + 1].trim();
 			index += 1;
 		}
-		else if (arg === "--route") if (index + 1 >= args.length) parsed.errors.push("Missing value for --route");
+		else if (arg === "--route") if (index + 1 >= args.length || args[index + 1].startsWith("-")) parsed.errors.push("Missing value for --route");
 		else {
 			parsed.routePath = args[index + 1].trim();
 			index += 1;
 		}
+		else if (arg.startsWith("-")) parsed.errors.push(`Unknown option: ${arg}`);
 		else positional.push(arg);
 	}
 	return {
 		...parsed,
 		command: positional[0] || "",
-		name: positional[1] || ""
+		name: positional[1] || "",
+		positionals: positional
 	};
 }
 async function pathExists(filePath) {
@@ -322,16 +324,12 @@ function toImportSpecifier(fromFile, toFile) {
 }
 function createUpdatedRouteFile(routeFileContent, options) {
 	const normalized = routeFileContent.replace(/\r\n/g, "\n");
-	const lines = normalized.split("\n");
-	const lastImportIndex = lines.reduce((currentIndex, line, index) => line.startsWith("import ") ? index : currentIndex, -1);
-	if (lastImportIndex === -1) throw new Error("Unsupported route file: could not find import block.");
 	const importLine = `import ${options.componentName} from '${options.importSpecifier}';`;
 	if (normalized.includes(importLine) || normalized.includes(`route('${options.routePath}',`) || normalized.includes(`route("${options.routePath}",`)) throw new Error(`Route '${options.routePath}' is already registered.`);
-	lines.splice(lastImportIndex + 1, 0, importLine);
-	const closingIndex = lines.map((line) => line.trim()).lastIndexOf("}");
-	if (closingIndex === -1) throw new Error("Unsupported route file: could not find registration function body.");
-	lines.splice(closingIndex, 0, `  route('${options.routePath}', ${options.componentName});`);
-	return `${lines.join("\n")}\n`;
+	const importMarker = "// askr:imports";
+	const routeMarker = "  // askr:routes";
+	if (normalized.split(importMarker).length !== 2 || normalized.split(routeMarker).length !== 2) throw new Error("Unsupported route file: expected exactly one // askr:imports and // askr:routes marker.");
+	return `${normalized.replace(importMarker, `${importMarker}\n${importLine}`).replace(routeMarker, `${routeMarker}\n  route('${options.routePath}', ${options.componentName});`).replace(/\n+$/, "")}\n`;
 }
 function renderPageFile(options) {
 	return [
@@ -378,7 +376,7 @@ function renderPageFile(options) {
 		""
 	].join("\n");
 }
-async function addPage(parsed, io) {
+async function addPage(parsed, io, writeChanges) {
 	if (!parsed.name) {
 		io.error("Page name is required.");
 		return 1;
@@ -429,14 +427,18 @@ async function addPage(parsed, io) {
 		return 1;
 	}
 	try {
-		await fs.mkdir(path.dirname(pageFile), { recursive: true });
-		await fs.writeFile(pageFile, renderPageFile({
-			badge: branchConfig.badge,
-			componentName,
-			routePath,
-			title
-		}), "utf8");
-		await fs.writeFile(routesFile, updatedRoutes, "utf8");
+		await writeChanges([{
+			filePath: pageFile,
+			content: renderPageFile({
+				badge: branchConfig.badge,
+				componentName,
+				routePath,
+				title
+			})
+		}, {
+			filePath: routesFile,
+			content: updatedRoutes
+		}]);
 	} catch (error) {
 		io.error("Failed to write generated page artifacts.");
 		io.error(error instanceof Error ? error.message : String(error));
@@ -448,7 +450,7 @@ async function addPage(parsed, io) {
 	io.log(`  Router: ${path.relative(projectRoot, routesFile).replace(/\\/g, "/")}`);
 	return 0;
 }
-async function addAction(parsed, io) {
+async function addAction(parsed, io, writeChanges) {
 	if (!parsed.name) {
 		io.error("Action name is required.");
 		return 1;
@@ -489,7 +491,7 @@ async function addAction(parsed, io) {
 			filePath: descriptorFile,
 			content: descriptor
 		});
-		await writeFileChanges([
+		await writeChanges([
 			{
 				filePath: descriptorFile,
 				content: descriptor
@@ -529,7 +531,7 @@ async function addAction(parsed, io) {
 	io.log(`  Test: ${path.relative(projectRoot, testFile).replace(/\\/g, "/")}`);
 	return 0;
 }
-async function runAddCli(args = process.argv.slice(2), io = console) {
+async function runAddCli(args = process.argv.slice(2), io = console, writeChanges = writeFileChanges) {
 	const parsed = parseArgs(args);
 	if (parsed.errors.length > 0) {
 		for (const message of parsed.errors) io.error(message);
@@ -539,8 +541,12 @@ async function runAddCli(args = process.argv.slice(2), io = console) {
 		io.log(helpText());
 		return 0;
 	}
-	if (parsed.command === "page") return addPage(parsed, io);
-	if (parsed.command === "action") return addAction(parsed, io);
+	if (parsed.positionals.length !== 2 || !parsed.name) {
+		io.error("A command and exactly one generator name are required.");
+		return 1;
+	}
+	if (parsed.command === "page") return addPage(parsed, io, writeChanges);
+	if (parsed.command === "action") return addAction(parsed, io, writeChanges);
 	io.error(`Unknown add command: ${parsed.command}`);
 	io.error("Run `askr add --help` to see available commands.");
 	return 1;
@@ -552,5 +558,3 @@ async function main() {
 if (isDirectExecution(import.meta.url)) main();
 //#endregion
 export { runAddCli };
-
-//# sourceMappingURL=add.js.map

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+//#region src/bin/cli.d.ts
+type CliIo = Pick<Console, "error" | "log">;
+declare function runCli(args?: string[], io?: CliIo): Promise<number>;
+//#endregion
+export { runCli };

package/dist/cli.js

@@ -116,5 +116,3 @@ async function main() {
 if (isDirectExecution(import.meta.url)) main();
 //#endregion
 export { runCli };
-
-//# sourceMappingURL=cli.js.map

package/dist/create.d.ts

@@ -0,0 +1,5 @@
+//#region src/bin/create.d.ts
+type CliIo = Pick<Console, "error" | "log">;
+declare function runCreateCli(args?: string[], io?: CliIo): Promise<number>;
+//#endregion
+export { runCreateCli };

package/dist/create.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { t as isDirectExecution } from "./is-direct-execution-Cdlr-ZUl.js";
-import { t as installBundledSkills } from "./skills-Bh0mEhIx.js";
+import { t as installBundledSkills } from "./skills-B7CbWur9.js";
+import { n as publishStagedDirectory, t as createSiblingStage } from "./directory-swap-DWoHtx7C.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
+import { isUtf8 } from "node:buffer";
 import readline from "node:readline";
 //#region src/bin/create.ts
 const TEMPLATE_LABELS = {
@@ -396,8 +398,8 @@ const TEMPLATE_INSPECT_PATHS = {
 	ssr: [
 		"AGENTS.md",
 		"src/main.tsx",
-		"src/server-entry.tsx",
-		"src/pages/_routes.tsx",
+		"src/entry-server.tsx",
+		"src/routes.tsx",
 		"server.ts"
 	],
 	ssg: [
@@ -432,7 +434,7 @@ const TEMPLATE_GOLDEN_EXAMPLES = {
 	],
 	ssr: [
 		"src/main.tsx",
-		"src/pages/_routes.tsx",
+		"src/routes.tsx",
 		"server.ts"
 	],
 	ssg: [
@@ -462,7 +464,7 @@ function helpText() {
 		"askr create - Project scaffolding for Askr",
 		"",
 		"Usage:",
-		"  askr create [template] <name> [--prompt <text>] [--no-install] [--no-skills]",
+		"  askr create [template] <name> [--dir <path>] [--prompt <text>] [--no-install] [--no-skills]",
 		"  askr create --prompt <text> [name] [--no-install] [--no-skills]",
 		"",
 		"Templates:",
@@ -470,6 +472,7 @@ function helpText() {
 		"",
 		"Options:",
 		"  --prompt <text>  Infer the best template from a product prompt and emit a builder blueprint",
+		"  --dir <path>     Explicit output directory (defaults to ./<name>)",
 		"  --no-install     Skip dependency installation",
 		"  --no-skills      Skip bundled Askr skill installation into skills/",
 		"  --help, -h       Show help",
@@ -495,6 +498,8 @@ async function prompt(question) {
 }
 function detectPm() {
 	const ua = process.env.npm_config_user_agent || "";
+	if (ua.startsWith("pnpm")) return "pnpm";
+	if (ua.startsWith("bun")) return "bun";
 	if (ua.startsWith("yarn")) return "yarn";
 	if (ua.startsWith("npm")) return "npm";
 	return "npm";
@@ -522,7 +527,12 @@ async function copyDir(src, dest, replacements) {
 			await copyDir(srcPath, destPath, replacements);
 			continue;
 		}
-		const replaced = (await fs.readFile(srcPath)).toString("utf8").replace(/\{\{\s*appName\s*\}\}/g, replacements.appName).replace(/\{\{appName\}\}/g, replacements.appName);
+		const buffer = await fs.readFile(srcPath);
+		if (!isUtf8(buffer)) {
+			await fs.writeFile(destPath, buffer);
+			continue;
+		}
+		const replaced = buffer.toString("utf8").replace(/\{\{\s*appName\s*\}\}/g, replacements.appName).replace(/\{\{appName\}\}/g, replacements.appName);
 		await fs.writeFile(destPath, replaced, "utf8");
 	}
 }
@@ -548,17 +558,24 @@ function parseArgs(args) {
 	let help = false;
 	let promptText = "";
 	let skills = true;
+	let targetDir = "";
 	const errors = [];
 	for (let i = 0; i < args.length; i += 1) {
 		const arg = args[i];
 		if (arg === "--no-install") install = false;
 		else if (arg === "--no-skills") skills = false;
-		else if (arg === "--prompt") if (i + 1 >= args.length) errors.push("Missing value for --prompt");
+		else if (arg === "--prompt") if (i + 1 >= args.length || args[i + 1].startsWith("-")) errors.push("Missing value for --prompt");
 		else {
 			promptText = normalizePromptText(args[i + 1]);
 			i += 1;
 		}
+		else if (arg === "--dir") if (i + 1 >= args.length || args[i + 1].startsWith("-")) errors.push("Missing value for --dir");
+		else {
+			targetDir = args[i + 1];
+			i += 1;
+		}
 		else if (arg === "--help" || arg === "-h") help = true;
+		else if (arg.startsWith("-")) errors.push(`Unknown option: ${arg}`);
 		else positional.push(arg);
 	}
 	return {
@@ -567,9 +584,15 @@ function parseArgs(args) {
 		help,
 		promptText,
 		skills,
-		errors
+		errors,
+		targetDir
 	};
 }
+function validateAppName(name) {
+	if (name.length > 214) return "App name must be 214 characters or fewer";
+	if (!/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/.test(name)) return "App name must be a lowercase npm package name without path separators";
+	if (/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/.test(name)) return `App name is reserved on Windows: ${name}`;
+}
 function normalizePromptText(promptText) {
 	return promptText.trim().replace(/\s+/g, " ");
 }
@@ -810,7 +833,17 @@ async function runCreateCli(args = process.argv.slice(2), io = console) {
 		io.error("App name is required");
 		return 1;
 	}
-	const target = path.resolve(process.cwd(), name);
+	const nameError = validateAppName(name);
+	if (nameError) {
+		io.error(nameError);
+		return 1;
+	}
+	const expectedPositionals = explicitTemplate ? 2 : 1;
+	if (parsed.positional.length > expectedPositionals) {
+		io.error("Too many positional arguments");
+		return 1;
+	}
+	const target = path.resolve(process.cwd(), parsed.targetDir || name);
 	const templateDir = await findTemplateDir(templateType);
 	try {
 		await fs.access(templateDir);
@@ -819,7 +852,12 @@ async function runCreateCli(args = process.argv.slice(2), io = console) {
 		return 1;
 	}
 	try {
-		if (await fs.stat(target).catch(() => null)) {
+		const stat = await fs.stat(target).catch(() => null);
+		if (stat) {
+			if (!stat.isDirectory()) {
+				io.error(`Target exists and is not a directory: ${target}`);
+				return 1;
+			}
 			if ((await fs.readdir(target).catch(() => [])).length > 0) {
 				io.error(`Directory ${target} already exists and is not empty.`);
 				return 1;
@@ -844,28 +882,48 @@ async function runCreateCli(args = process.argv.slice(2), io = console) {
 	}
 	io.log(`Creating ${TEMPLATE_LABELS[templateType]} project: ${name}...`);
 	io.log("");
+	let stagingTarget;
+	try {
+		stagingTarget = await createSiblingStage(target, "askr-create");
+	} catch (error) {
+		io.error("Failed to prepare project output");
+		io.error(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
 	try {
-		await copyDir(templateDir, target, { appName: name });
+		await copyDir(templateDir, stagingTarget, { appName: name });
 	} catch (error) {
+		await fs.rm(stagingTarget, {
+			recursive: true,
+			force: true
+		});
 		io.error("Failed to copy template");
 		io.error(error instanceof Error ? error.message : String(error));
 		return 1;
 	}
 	try {
-		await writeBlueprintFiles(target, blueprint);
+		await writeBlueprintFiles(stagingTarget, blueprint);
 	} catch (error) {
+		await fs.rm(stagingTarget, {
+			recursive: true,
+			force: true
+		});
 		io.error("Failed to write project blueprint");
 		io.error(error instanceof Error ? error.message : String(error));
 		return 1;
 	}
 	if (parsed.skills) try {
 		const { bundledNames, targetSkillsDir } = await installBundledSkills({
-			cwd: target,
+			cwd: stagingTarget,
 			force: true
 		});
 		io.log(`Installed ${bundledNames.length} bundled Askr skills into ${path.basename(targetSkillsDir)}/`);
 		io.log("");
 	} catch (error) {
+		await fs.rm(stagingTarget, {
+			recursive: true,
+			force: true
+		});
 		io.error("Failed to install bundled Askr skills");
 		io.error(error instanceof Error ? error.message : String(error));
 		return 1;
@@ -874,35 +932,57 @@ async function runCreateCli(args = process.argv.slice(2), io = console) {
 		io.log("Skipping bundled Askr skill installation (--no-skills)");
 		io.log("");
 	}
+	const pm = detectPm();
 	if (!parsed.install) {
+		try {
+			await publishStagedDirectory(stagingTarget, target);
+		} catch (error) {
+			await fs.rm(stagingTarget, {
+				recursive: true,
+				force: true
+			});
+			io.error("Failed to publish generated project");
+			io.error(error instanceof Error ? error.message : String(error));
+			return 1;
+		}
 		io.log("Skipping dependency installation (--no-install)");
 		io.log("");
 		io.log("Next steps:");
 		io.log(`  cd ${name}`);
 		io.log("  review .askr/builder-brief.md");
 		if (!parsed.skills) io.log("  askr skills install");
-		io.log("  npm install");
-		io.log("  npm run dev");
+		io.log(`  ${pm} install`);
+		io.log(`  ${pm} run dev`);
 		return 0;
 	}
-	const pm = detectPm();
 	io.log(`Installing dependencies with ${pm}...`);
 	io.log("");
 	const result = spawnSync(pm, ["install"], {
-		cwd: target,
+		cwd: stagingTarget,
 		stdio: "inherit",
 		shell: process.platform === "win32"
 	});
+	if (result.status !== 0) {
+		await fs.rm(stagingTarget, {
+			recursive: true,
+			force: true
+		});
+		io.error(`Dependency installation with ${pm} failed; no project files were published.`);
+		if (result.error) io.error(result.error.message);
+		return 1;
+	}
 	io.log("");
 	io.log(`Success! Created ${name}`);
 	io.log("");
-	if (result.status !== 0) {
-		io.log("Dependency installation failed. Please run manually:");
-		io.log(`  cd ${name}`);
-		io.log("  review .askr/builder-brief.md");
-		if (!parsed.skills) io.log("  askr skills install");
-		io.log(`  ${pm} install`);
-		io.log(`  ${pm} run dev`);
+	try {
+		await publishStagedDirectory(stagingTarget, target);
+	} catch (error) {
+		await fs.rm(stagingTarget, {
+			recursive: true,
+			force: true
+		});
+		io.error("Failed to publish generated project");
+		io.error(error instanceof Error ? error.message : String(error));
 		return 1;
 	}
 	io.log("Next steps:");
@@ -919,5 +999,3 @@ async function main() {
 if (isDirectExecution(import.meta.url)) main();
 //#endregion
 export { runCreateCli };
-
-//# sourceMappingURL=create.js.map

package/dist/directory-swap-DWoHtx7C.js

@@ -0,0 +1,35 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/directory-swap.ts
+async function exists(target) {
+	return Boolean(await fs.stat(target).catch(() => null));
+}
+async function createSiblingStage(target, label) {
+	const resolved = path.resolve(target);
+	const parent = path.dirname(resolved);
+	await fs.mkdir(parent, { recursive: true });
+	return fs.mkdtemp(path.join(parent, `.${path.basename(resolved)}.${label}-`));
+}
+async function publishStagedDirectory(stage, target) {
+	const resolvedTarget = path.resolve(target);
+	const backup = path.join(path.dirname(resolvedTarget), `.${path.basename(resolvedTarget)}.askr-backup-${randomUUID()}`);
+	const hadTarget = await exists(resolvedTarget);
+	let movedTarget = false;
+	try {
+		if (hadTarget) {
+			await fs.rename(resolvedTarget, backup);
+			movedTarget = true;
+		}
+		await fs.rename(stage, resolvedTarget);
+	} catch (error) {
+		if (movedTarget && !await exists(resolvedTarget) && await exists(backup)) await fs.rename(backup, resolvedTarget);
+		throw error;
+	}
+	if (movedTarget) await fs.rm(backup, {
+		recursive: true,
+		force: true
+	}).catch(() => void 0);
+}
+//#endregion
+export { publishStagedDirectory as n, createSiblingStage as t };

package/dist/discovery-Difb7Y4G.js

@@ -321,5 +321,3 @@ async function discoverProject(options) {
 }
 //#endregion
 export { discoverProject };
-
-//# sourceMappingURL=discovery-Difb7Y4G.js.map

package/dist/generate.d.ts

@@ -0,0 +1,5 @@
+//#region src/bin/generate.d.ts
+type Io = Pick<Console, "error" | "log">;
+declare function runGenerateCli(args: string[], io?: Io): Promise<number>;
+//#endregion
+export { runGenerateCli };