@askrjs/cli 0.0.2 → 0.0.4

package/README.md

@@ -43,11 +43,50 @@ unless you opt out with `--no-skills`.
 - `askr skills sync [--cwd <dir>]`
 - `askr ssg --config <path> --output <dir> [--incremental]`
 - `askr openapi [--entry ./src/api.ts] [--output ./openapi.yml] [--check]`
-- `askr update [packages...] [-u] [-f] [--workspace <glob>] [--tag <tag>] [--json]`
+- `askr outdated [packages...] [--workspace <glob>] [--tag <tag>] [--json]`
+- `askr update [packages...] [--workspace <glob>] [--tag <tag>] [--json]`
+- `askr upgrade [packages...] [--workspace <glob>] [--tag <tag>] [--json]`
 
 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
@@ -69,24 +108,24 @@ registers it in route-first SPA branches (`src/pages/app/_routes.tsx` or
 
 ## Dependency updates
 
-`askr update` is an Askr-owned, dry-run-first dependency updater. It discovers
-the containing npm or pnpm workspace from nested directories, includes the root
+The dependency commands are Askr-owned and discover
+the containing npm or pnpm workspace from nested directories, include the root
 manifest and declared workspaces, and reports safe, breaking, local, manual,
 and failed decisions without running an install.
 
 ```bash
+askr outdated
 askr update
-askr update -u
-askr update -u -f
+askr upgrade
 askr update vite "@types/*"
 askr update --workspace "@scope/app" --tag next --json
 ```
 
-`-u` writes compatible range changes. `-u -f` additionally permits breaking
+`askr update` writes safe range changes. `askr upgrade` additionally permits next-version
 major changes for stable packages and breaking minor changes for `0.x`
 packages. Peer requirements from co-dependencies are still enforced: a target
 is left for manual review if it would move outside another selected package's
-published peer range. Force never bypasses that compatibility guard.
+published peer range. `askr upgrade` never bypasses that compatibility guard.
 
 The updater preserves exact, caret, tilde, and x-range styles. It can widen one
 bounded interval, and it updates only the highest clause of a simple OR union.

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

@@ -1,3 +1,560 @@
 #!/usr/bin/env node
-import { t as runAddCli } from "./add-DqhqRzBQ.js";
+import { t as isDirectExecution } from "./is-direct-execution-Cdlr-ZUl.js";
+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
+//#region src/bin/add.ts
+const BRANCH_CONFIG = {
+	app: {
+		badge: "app route",
+		pagesDir: [
+			"src",
+			"pages",
+			"app"
+		],
+		routesFile: [
+			"src",
+			"pages",
+			"app",
+			"_routes.tsx"
+		]
+	},
+	public: {
+		badge: "public route",
+		pagesDir: [
+			"src",
+			"pages",
+			"public"
+		],
+		routesFile: [
+			"src",
+			"pages",
+			"public",
+			"_routes.tsx"
+		]
+	}
+};
+function helpText() {
+	return [
+		"askr add - Generate code into an existing Askr project",
+		"",
+		"Usage:",
+		"  askr add page <name> [--branch app|public] [--cwd <dir>] [--title <title>] [--route <path>] [--force]",
+		"  askr add action <name> --route <path> [--cwd <dir>] [--force]",
+		"",
+		"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",
+		"",
+		"Options:",
+		"  --branch <name>  Route branch to target (default: app)",
+		"  --cwd <dir>      Project directory (default: current directory)",
+		"  --title <text>   Override the generated page title",
+		"  --route <path>   Override the generated route path",
+		"  --force          Overwrite an existing page file",
+		"  --help           Show this help message",
+		"",
+		"Examples:",
+		"  askr add page audit-log",
+		"  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}",
+		"",
+		"Notes:",
+		"  Page generation supports route-first SPA projects created from `askr create spa`.",
+		"  Action generation supports projects created from `askr create full-stack`."
+	].join("\n");
+}
+function parseArgs(args) {
+	const positional = [];
+	const parsed = {
+		branch: "app",
+		cwd: process.cwd(),
+		force: false,
+		help: false,
+		routePath: "",
+		title: "",
+		errors: []
+	};
+	for (let index = 0; index < args.length; index += 1) {
+		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 || 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 || 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 || 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 || 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] || "",
+		positionals: positional
+	};
+}
+async function pathExists(filePath) {
+	return Boolean(await fs.stat(filePath).catch(() => null));
+}
+function slugifySegment(value) {
+	return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function normalizePageSegments(input) {
+	const segments = input.replace(/^\/+|\/+$/g, "").split("/").map((segment) => slugifySegment(segment.trim())).filter(Boolean);
+	if (segments.length === 0 || segments.some((segment) => segment.startsWith("_"))) return [];
+	return segments;
+}
+function toWords(segments) {
+	return segments.flatMap((segment) => segment.split("-").filter(Boolean));
+}
+function toTitleCase(words) {
+	return words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function buildComponentName(segments) {
+	return `${toWords(segments).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("")}Page`;
+}
+function buildIdentifier(segments) {
+	const [first = "action", ...rest] = toWords(segments);
+	return [first.toLowerCase(), ...rest.map((word) => word.charAt(0).toUpperCase() + word.slice(1))].join("").replace(/^[^a-z_$]/i, "action");
+}
+function renderAuthorizationRegistry(actions) {
+	const imports = actions.map((action) => `import { ${action.descriptorName} } from './actions/${action.slug}.js';`);
+	const routes = /* @__PURE__ */ new Map();
+	for (const action of actions) {
+		const entries = routes.get(action.routePath) ?? [];
+		entries.push(action);
+		routes.set(action.routePath, entries);
+	}
+	const routeLines = [...routes].sort(([left], [right]) => left.localeCompare(right)).map(([routePath, entries]) => `  ${JSON.stringify(routePath)}: [${entries.map((entry) => entry.descriptorName).join(", ")}],`);
+	return [
+		"import type { ActionDescriptor } from '@askrjs/askr/actions';",
+		...imports,
+		"",
+		"const actionsByRoute: Readonly<Record<string, readonly ActionDescriptor[]>> = Object.freeze({",
+		...routeLines,
+		"});",
+		"",
+		"export function actionsFor(path: string): readonly ActionDescriptor[] {",
+		"  return actionsByRoute[path] ?? [];",
+		"}",
+		""
+	].join("\n");
+}
+function renderServerActionRegistry(actions) {
+	return [
+		"import { defineServerActions, handleAction } from '@askrjs/server/askr';",
+		...actions.map((action) => `import { ${action.descriptorName} } from '../actions/${action.slug}.js';`),
+		...actions.map((action) => `import { ${action.handlerName} } from './actions/${action.slug}.js';`),
+		"import type { AppDependencies } from './dependencies.js';",
+		"",
+		"export function createActions(deps: AppDependencies) {",
+		"  return defineServerActions({ dependencies: deps,",
+		"    csrf: { secret: process.env.CSRF_SECRET ?? 'development-only-secret' },",
+		"  },",
+		...actions.map((action) => `    handleAction(${action.descriptorName}, ${action.handlerName}),`),
+		"  );",
+		"}",
+		""
+	].join("\n");
+}
+async function discoverDeclaredActions(projectRoot, replacement) {
+	const actionsDir = path.join(projectRoot, "src", "actions");
+	const names = await fs.readdir(actionsDir).catch(() => []);
+	const files = new Set(names.filter((name) => name.endsWith(".ts")).map((name) => path.join(actionsDir, name)));
+	files.add(replacement.filePath);
+	const actions = [];
+	for (const filePath of [...files].sort()) {
+		const content = filePath === replacement.filePath ? replacement.content : await fs.readFile(filePath, "utf8");
+		const descriptor = /export const (\w+Action) = defineAction\(/.exec(content)?.[1];
+		if (!descriptor) continue;
+		const routeName = `${descriptor}Route`;
+		const routeMatch = new RegExp(`export const ${routeName} = (['"])(.*?)\\1;`).exec(content);
+		if (!routeMatch) throw new Error(`Action descriptor ${path.basename(filePath)} must declare ${routeName}.`);
+		const slug = path.basename(filePath, ".ts");
+		actions.push({
+			slug,
+			descriptorName: descriptor,
+			handlerName: buildIdentifier([slug]),
+			routePath: routeMatch[2]
+		});
+	}
+	return actions.sort((left, right) => left.slug.localeCompare(right.slug));
+}
+function renderActionDescriptor(options) {
+	return [
+		"import { defineAction } from '@askrjs/askr/actions';",
+		"import { schema } from '@askrjs/schema';",
+		"",
+		`export const ${options.descriptorName}Route = ${JSON.stringify(options.routePath)};`,
+		"",
+		`export const ${options.descriptorName} = defineAction({`,
+		`  id: '${options.slug}',`,
+		"  input: schema.object({ value: schema.string({ minLength: 1 }) }),",
+		"  invalidates: [],",
+		"});",
+		""
+	].join("\n");
+}
+function renderActionHandler(options) {
+	return [
+		"import type { InferSchema } from '@askrjs/schema';",
+		`import { ${options.descriptorName} } from '../../actions/${options.slug}.js';`,
+		"import type { AppDependencies } from '../dependencies.js';",
+		"",
+		`type Input = InferSchema<typeof ${options.descriptorName}.input>;`,
+		"",
+		`export async function ${options.handlerName}(`,
+		"  _context: unknown,",
+		"  input: Input,",
+		"  deps: Pick<AppDependencies, 'actions'>,",
+		") {",
+		"  await deps.actions.record({ action: " + JSON.stringify(options.slug) + ", value: input.value });",
+		"  return { result: { accepted: true } };",
+		"}",
+		""
+	].join("\n");
+}
+function renderActionTest(options) {
+	return [
+		"import { describe, expect, it } from 'vitest';",
+		`import { ${options.descriptorName} } from '../../src/actions/${options.slug}.js';`,
+		"",
+		`describe('${options.slug} action', () => {`,
+		"  it('should expose a browser-safe executable input contract', () => {",
+		`    expect(${options.descriptorName}.id).toBe('${options.slug}');`,
+		`    expect(${options.descriptorName}.input.safeParse({ value: 'example' }).success).toBe(true);`,
+		`    expect(${options.descriptorName}.input.safeParse({ value: '' }).success).toBe(false);`,
+		"  });",
+		"});",
+		""
+	].join("\n");
+}
+function buildRoutePath(branch, segments, overridePath = "") {
+	if (!overridePath) {
+		const suffix = segments.join("/");
+		return branch === "app" ? `/app/${suffix}` : `/${suffix}`;
+	}
+	const normalized = overridePath.startsWith("/") ? overridePath : `/${overridePath}`;
+	if (branch === "app") return normalized === "/app" || normalized.startsWith("/app/") ? normalized : `/app${normalized}`;
+	if (normalized === "/app" || normalized.startsWith("/app/")) throw new Error("Public branch routes cannot live under /app.");
+	return normalized;
+}
+function toImportSpecifier(fromFile, toFile) {
+	const withoutExtension = path.relative(path.dirname(fromFile), toFile).replace(/\\/g, "/").replace(/\.tsx$/i, "");
+	return withoutExtension.startsWith(".") ? withoutExtension : `./${withoutExtension}`;
+}
+function createUpdatedRouteFile(routeFileContent, options) {
+	const normalized = routeFileContent.replace(/\r\n/g, "\n");
+	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.`);
+	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 [
+		"import {",
+		"  Badge,",
+		"  Card,",
+		"  CardContent,",
+		"  CardDescription,",
+		"  CardHeader,",
+		"  CardTitle,",
+		"} from '@askrjs/themes/components';",
+		"import { Stack } from '@askrjs/themes/components';",
+		"",
+		`export default function ${options.componentName}() {`,
+		"  return (",
+		"    <Stack gap=\"5\">",
+		"      <section class=\"page-heading\">",
+		"        <Stack gap=\"2\">",
+		`          <Badge>${options.badge}</Badge>`,
+		`          <h1>${options.title}</h1>`,
+		"          <p class=\"lead\">",
+		`            Route-first scaffold for ${options.routePath}. Keep adapters, queries, and mutations outside the page as this surface grows.`,
+		"          </p>",
+		"        </Stack>",
+		"      </section>",
+		"",
+		"      <Card>",
+		"        <CardHeader>",
+		"          <CardTitle>Next step</CardTitle>",
+		"          <CardDescription>",
+		"            Move view logic into feature folders and keep loading, empty, error, and success states explicit.",
+		"          </CardDescription>",
+		"        </CardHeader>",
+		"        <CardContent>",
+		"          <Stack gap=\"3\">",
+		"            <p>Start with a focused feature boundary instead of inline data fetching.</p>",
+		"            <p>Prefer resource(), derive(), and For once the page takes on real state.</p>",
+		"          </Stack>",
+		"        </CardContent>",
+		"      </Card>",
+		"    </Stack>",
+		"  );",
+		"}",
+		""
+	].join("\n");
+}
+async function addPage(parsed, io, writeChanges) {
+	if (!parsed.name) {
+		io.error("Page name is required.");
+		return 1;
+	}
+	const branch = parsed.branch.toLowerCase();
+	const branchConfig = BRANCH_CONFIG[branch];
+	if (!branchConfig) {
+		io.error(`Unsupported branch '${parsed.branch}'. Use app or public.`);
+		return 1;
+	}
+	const segments = normalizePageSegments(parsed.name);
+	if (segments.length === 0) {
+		io.error("Page name must contain at least one non-empty path segment.");
+		return 1;
+	}
+	const projectRoot = path.resolve(parsed.cwd);
+	const routesFile = path.join(projectRoot, ...branchConfig.routesFile);
+	if (!await pathExists(routesFile)) {
+		io.error(`Unsupported project layout. Expected route file: ${routesFile}`);
+		io.error("askr add page currently supports route-first SPA projects created by `askr create spa`.");
+		return 1;
+	}
+	const pageFile = path.join(projectRoot, ...branchConfig.pagesDir, ...segments).concat(".tsx");
+	if (await pathExists(pageFile) && !parsed.force) {
+		io.error(`Page file already exists: ${pageFile}`);
+		io.error("Pass --force to overwrite the existing file.");
+		return 1;
+	}
+	const title = parsed.title || toTitleCase(toWords(segments));
+	const componentName = buildComponentName(segments);
+	let routePath = "";
+	try {
+		routePath = buildRoutePath(branch, segments, parsed.routePath);
+	} catch (error) {
+		io.error(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+	const importSpecifier = toImportSpecifier(routesFile, pageFile);
+	let updatedRoutes = "";
+	try {
+		updatedRoutes = createUpdatedRouteFile(await fs.readFile(routesFile, "utf8"), {
+			componentName,
+			importSpecifier,
+			routePath
+		});
+	} catch (error) {
+		io.error(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+	try {
+		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));
+		return 1;
+	}
+	io.log(`Added ${branch} page '${title}'.`);
+	io.log(`  File: ${path.relative(projectRoot, pageFile).replace(/\\/g, "/")}`);
+	io.log(`  Route: ${routePath}`);
+	io.log(`  Router: ${path.relative(projectRoot, routesFile).replace(/\\/g, "/")}`);
+	return 0;
+}
+async function addAction(parsed, io, writeChanges) {
+	if (!parsed.name) {
+		io.error("Action name is required.");
+		return 1;
+	}
+	if (!parsed.routePath || !parsed.routePath.startsWith("/")) {
+		io.error("Action generation requires an absolute --route path.");
+		return 1;
+	}
+	const segments = normalizePageSegments(parsed.name);
+	if (segments.length === 0) {
+		io.error("Action name must contain at least one non-empty path segment.");
+		return 1;
+	}
+	const projectRoot = path.resolve(parsed.cwd);
+	const slug = segments.join("-");
+	const handlerName = buildIdentifier(segments);
+	const descriptorName = `${handlerName}Action`;
+	const descriptorFile = path.join(projectRoot, "src", "actions", `${slug}.ts`);
+	const handlerFile = path.join(projectRoot, "src", "server", "actions", `${slug}.ts`);
+	const registryFile = path.join(projectRoot, "src", "server", "action-registry.ts");
+	const authorizationFile = path.join(projectRoot, "src", "action-authorizations.ts");
+	const testFile = path.join(projectRoot, "tests", "actions", `${slug}.test.ts`);
+	if (!await pathExists(registryFile) || !await pathExists(authorizationFile)) {
+		io.error("Unsupported project layout. Expected an `askr create full-stack` project.");
+		return 1;
+	}
+	if (!parsed.force && (await pathExists(descriptorFile) || await pathExists(handlerFile))) {
+		io.error(`Action '${slug}' already exists. Pass --force to replace its generated files.`);
+		return 1;
+	}
+	try {
+		const descriptor = renderActionDescriptor({
+			descriptorName,
+			routePath: parsed.routePath,
+			slug
+		});
+		const actions = await discoverDeclaredActions(projectRoot, {
+			filePath: descriptorFile,
+			content: descriptor
+		});
+		await writeChanges([
+			{
+				filePath: descriptorFile,
+				content: descriptor
+			},
+			{
+				filePath: handlerFile,
+				content: renderActionHandler({
+					descriptorName,
+					handlerName,
+					slug
+				})
+			},
+			{
+				filePath: testFile,
+				content: renderActionTest({
+					descriptorName,
+					slug
+				})
+			},
+			{
+				filePath: registryFile,
+				content: renderServerActionRegistry(actions)
+			},
+			{
+				filePath: authorizationFile,
+				content: renderAuthorizationRegistry(actions)
+			}
+		]);
+	} catch (error) {
+		io.error("Failed to write generated action artifacts.");
+		io.error(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+	io.log(`Added action '${slug}' for ${parsed.routePath}.`);
+	io.log(`  Descriptor: ${path.relative(projectRoot, descriptorFile).replace(/\\/g, "/")}`);
+	io.log(`  Handler: ${path.relative(projectRoot, handlerFile).replace(/\\/g, "/")}`);
+	io.log(`  Test: ${path.relative(projectRoot, testFile).replace(/\\/g, "/")}`);
+	return 0;
+}
+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);
+		return 1;
+	}
+	if (!parsed.command || parsed.help) {
+		io.log(helpText());
+		return 0;
+	}
+	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;
+}
+async function main() {
+	const code = await runAddCli(process.argv.slice(2));
+	process.exit(code);
+}
+if (isDirectExecution(import.meta.url)) main();
+//#endregion
 export { runAddCli };

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 };