@zaaxch/tailframe 0.1.0

package/src/conventions.mjs

@@ -0,0 +1,188 @@
+import fs from "node:fs";
+import path from "node:path";
+import { toPosix, walk } from "./architecture.mjs";
+
+const PASCAL = /^[A-Z][A-Za-z0-9]*$/;
+const CAMEL = /^[a-z][A-Za-z0-9]*$/;
+const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const ROLES = new Set(["routes", "schemas", "api", "store", "types", "documents"]);
+const NOT_PLURAL = new Set(["status", "analysis"]);
+const BRAND_PATTERN = /\bBrand\s*<|unique symbol/;
+
+function parseName(fileName) {
+	if (fileName.endsWith(".d.ts")) return undefined;
+	const extension = path.extname(fileName);
+	let stem = fileName.slice(0, -extension.length);
+	let isTest = false;
+	for (const suffix of [".integration.test", ".test", ".spec"]) {
+		if (stem.endsWith(suffix)) {
+			stem = stem.slice(0, -suffix.length);
+			isTest = true;
+			break;
+		}
+	}
+	if (!stem.includes(".")) return { stem, isTest, extension, subject: undefined, role: undefined };
+	const parts = stem.split(".");
+	return { stem, isTest, extension, subject: parts.slice(0, -1).join("."), role: parts.at(-1) };
+}
+
+function looksPlural(name) {
+	const last = name.split("-").at(-1);
+	return last.endsWith("s") && !last.endsWith("ss") && !NOT_PLURAL.has(last);
+}
+
+export function validateConventions(rootArgument, kind) {
+	const root = path.resolve(rootArgument);
+	const src = path.join(root, "src");
+	if (!fs.existsSync(src)) return [];
+	const violations = [];
+	const seenModules = new Set();
+	const flag = (rule, relative, message) => violations.push({ rule, path: relative, message });
+
+	for (const absolute of walk(src)) {
+		const relative = toPosix(path.relative(root, absolute));
+		const name = parseName(path.basename(relative));
+		if (!name) continue;
+		const moduleMatch = relative.match(/^src\/modules\/([^/]+)\/(.*)$/);
+
+		if (name.role !== undefined && !ROLES.has(name.role)) {
+			flag("G2", relative, `${relative} uses role suffix ".${name.role}"; the only role suffixes are ${[...ROLES].join(", ")}`);
+			continue;
+		}
+		if (name.role !== undefined && !KEBAB.test(name.subject)) {
+			flag("G2", relative, `${relative} role-suffix subject must be lowercase kebab-case`);
+			continue;
+		}
+
+		if (!moduleMatch) {
+			validateShared(relative, name, flag);
+			if ((relative.startsWith("src/core/") && name.extension === ".ts") && BRAND_PATTERN.test(fs.readFileSync(absolute, "utf8"))) {
+				flag("S5", relative, `${relative} defines identifier branding in core; branded IDs and the Brand helper belong in the owning module's domain/identifiers.ts`);
+			}
+			continue;
+		}
+
+		const [, moduleName, remainder] = moduleMatch;
+		const modulePath = `src/modules/${moduleName}`;
+		if (!seenModules.has(moduleName)) {
+			seenModules.add(moduleName);
+			if (!KEBAB.test(moduleName)) flag("G4", modulePath, `module "${moduleName}" must be lowercase kebab-case`);
+			else if (looksPlural(moduleName)) flag("G4", modulePath, `module "${moduleName}" looks plural; module names are singular unless the project root AGENTS.md records the exception`);
+		}
+		if (name.stem === "index") {
+			flag("G3", relative, `${relative} is a barrel; import the named file instead`);
+			continue;
+		}
+		if (name.isTest && remainder !== `__tests__/${path.basename(relative)}`) {
+			flag(kind === "service" ? "S7" : "U4", relative, `${relative} is a test outside the module-root __tests__ directory`);
+			continue;
+		}
+		if (!name.isTest && remainder.startsWith("__tests__/")) {
+			flag(kind === "service" ? "S7" : "U4", relative, `${relative} is a non-test file inside __tests__`);
+			continue;
+		}
+		if (name.isTest) {
+			if (!PASCAL.test(name.stem) && !CAMEL.test(name.stem)) flag("G1", relative, `${relative} test subject must be PascalCase or camelCase`);
+			continue;
+		}
+
+		const layer = remainder.split("/")[0];
+		if (kind === "service") validateServiceFile(relative, moduleName, layer, remainder, name, flag);
+		else validateUiFile(relative, moduleName, layer, name, flag);
+
+		if (kind === "service" && name.extension === ".ts" && relative !== `${modulePath}/domain/identifiers.ts` &&
+			BRAND_PATTERN.test(fs.readFileSync(absolute, "utf8"))) {
+			flag("S5", relative, `${relative} declares identifier branding outside domain/identifiers.ts; each module keeps its brands, Brand helper, and boundary helpers in one domain/identifiers.ts`);
+		}
+	}
+	return violations;
+}
+
+function validateShared(relative, name, flag) {
+	if (name.stem === "index") return;
+	const directory = path.posix.basename(path.posix.dirname(relative));
+	if (name.role !== undefined) {
+		const allowedHere = (name.role === "store" && directory === "stores") || (name.role === "routes" && directory === "http");
+		if (!allowedHere) flag("G2", relative, `${relative} role suffix ".${name.role}" is not valid in this directory`);
+		return;
+	}
+	if (name.extension === ".vue") {
+		if (!PASCAL.test(name.stem)) flag("G1", relative, `${relative} Vue components are PascalCase`);
+		else if (directory === "views" && !name.stem.endsWith("View")) flag("U2", relative, `${relative} views are named <Name>View.vue`);
+		return;
+	}
+	if (!PASCAL.test(name.stem) && !CAMEL.test(name.stem)) {
+		flag("G1", relative, `${relative} must be named after its primary export in that export's casing (PascalCase or camelCase)`);
+	}
+}
+
+function validateServiceFile(relative, moduleName, layer, remainder, name, flag) {
+	if (layer === "domain") {
+		if (name.role !== undefined) flag("G2", relative, `${relative} role-suffix files do not belong in domain`);
+		else if (!PASCAL.test(name.stem) && !CAMEL.test(name.stem)) flag("G1", relative, `${relative} domain files are PascalCase types or camelCase functions`);
+		return;
+	}
+	if (layer === "use-cases") {
+		if (remainder.split("/")[1] === "ports") {
+			if (name.role !== undefined || !PASCAL.test(name.stem)) flag("S2", relative, `${relative} ports are one PascalCase interface per file, named after the interface`);
+			else if (/(?:Ports|Repositories)$/.test(name.stem)) flag("G5", relative, `${relative} aggregates ports; define one port per file`);
+			return;
+		}
+		if (/^validatedidentifiers$/i.test(name.stem)) flag("S5", relative, `${relative} identifier helpers belong in domain/identifiers.ts`);
+		else if (name.role !== undefined || !PASCAL.test(name.stem)) flag("S1", relative, `${relative} use cases are one PascalCase verb phrase per file`);
+		else if (/UseCases$/.test(name.stem)) flag("G5", relative, `${relative} aggregates use cases; define one operation per file`);
+		return;
+	}
+	if (layer === "persistence") {
+		if (name.role !== undefined) {
+			if (name.role !== "documents" || name.subject !== moduleName) {
+				flag("S3", relative, `${relative} the only persistence role file is ${moduleName}.documents.ts`);
+			}
+			return;
+		}
+		if (!PASCAL.test(name.stem) && !CAMEL.test(name.stem)) flag("G1", relative, `${relative} persistence adapters are PascalCase classes; helpers are camelCase`);
+		else if (/Repositories$/.test(name.stem)) flag("G5", relative, `${relative} aggregates adapters; define one adapter per file`);
+		return;
+	}
+	if (layer === "http") {
+		if (name.role === undefined || !["routes", "schemas"].includes(name.role) || name.subject !== moduleName) {
+			flag("S6", relative, `${relative} http files are ${moduleName}.routes.ts and ${moduleName}.schemas.ts`);
+		}
+	}
+}
+
+function validateUiFile(relative, moduleName, layer, name, flag) {
+	if (layer === "api") {
+		if (name.role !== "api" || name.subject !== moduleName) flag("U1", relative, `${relative} API clients are named ${moduleName}.api.ts`);
+		return;
+	}
+	if (layer === "routes") {
+		if (name.extension === ".vue") flag("U2", relative, `${relative} .vue files do not belong under routes/; module shells belong in components/ or views/`);
+		else if (name.role !== "routes" || name.subject !== moduleName) flag("U2", relative, `${relative} route definitions are named ${moduleName}.routes.ts`);
+		return;
+	}
+	if (layer === "views") {
+		if (name.extension === ".vue" && (!PASCAL.test(name.stem) || !name.stem.endsWith("View"))) flag("U2", relative, `${relative} views are named <Name>View.vue`);
+		return;
+	}
+	if (layer === "components") {
+		if (name.extension === ".vue" && !PASCAL.test(name.stem)) flag("U2", relative, `${relative} components are PascalCase .vue files`);
+		else if (name.extension !== ".vue" && !PASCAL.test(name.stem) && !CAMEL.test(name.stem)) flag("G1", relative, `${relative} must follow primary-export casing`);
+		return;
+	}
+	if (layer === "composables") {
+		if (name.role !== undefined || !/^use[A-Z][A-Za-z0-9]*$/.test(name.stem)) flag("U3", relative, `${relative} composables are named use<Name>.ts`);
+		return;
+	}
+	if (layer === "stores") {
+		if (name.role !== "store") flag("U3", relative, `${relative} stores are named <name>.store.ts`);
+		return;
+	}
+	if (layer === "types") {
+		if (name.role !== undefined) {
+			if (name.role !== "types" || name.subject !== moduleName) flag("U3", relative, `${relative} the module types role file is ${moduleName}.types.ts`);
+		} else if (!PASCAL.test(name.stem) && !CAMEL.test(name.stem)) {
+			flag("G1", relative, `${relative} must follow primary-export casing`);
+		}
+	}
+}

package/src/exceptions.mjs

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function parseExceptionSection(markdown) {
+	const lines = markdown.split(/\r?\n/);
+	const start = lines.findIndex((line) => /^##\s+Tailframe exceptions\s*$/.test(line));
+	if (start === -1) return [];
+	const covered = [];
+	for (const line of lines.slice(start + 1)) {
+		if (/^##\s/.test(line)) break;
+		const match = line.match(/^-\s+`([^`]+)`/);
+		if (match) covered.push(match[1].replace(/\/+$/, ""));
+	}
+	return covered;
+}
+
+export function loadExceptions(rootArgument) {
+	const root = path.resolve(rootArgument);
+	const repositoryName = path.basename(root);
+	const covered = [];
+	const own = path.join(root, "AGENTS.md");
+	if (fs.existsSync(own)) covered.push(...parseExceptionSection(fs.readFileSync(own, "utf8")));
+	const project = path.join(path.dirname(root), "AGENTS.md");
+	if (fs.existsSync(project)) {
+		for (const entry of parseExceptionSection(fs.readFileSync(project, "utf8"))) {
+			if (entry === repositoryName || entry.startsWith(`${repositoryName}/`)) {
+				covered.push(entry.slice(repositoryName.length + 1) || ".");
+			}
+		}
+	}
+	return covered;
+}
+
+export function isExcepted(relative, exceptions) {
+	return exceptions.some((covered) => covered === "." || relative === covered || relative.startsWith(`${covered}/`));
+}

package/src/generate.mjs

@@ -0,0 +1,353 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadExceptions, isExcepted } from "./exceptions.mjs";
+
+const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const PASCAL = /^[A-Z][A-Za-z0-9]*$/;
+const NOT_PLURAL = new Set(["status", "analysis"]);
+
+export class GenerateError extends Error {}
+
+const fail = (message) => { throw new GenerateError(message); };
+const pascal = (kebab) => kebab.split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join("");
+const camel = (kebab) => { const value = pascal(kebab); return value[0].toLowerCase() + value.slice(1); };
+
+function detectKind(root) {
+	const service = fs.existsSync(path.join(root, "src/server.ts"));
+	const ui = fs.existsSync(path.join(root, "src/main.ts"));
+	if (service && ui) fail("Repository has both src/server.ts and src/main.ts; cannot determine kind");
+	if (!service && !ui) fail("Run tailframe generate from a Tailframe repository root (src/server.ts or src/main.ts not found)");
+	return service ? "service" : "ui";
+}
+
+function requireModuleName(root, name) {
+	if (!name || !KEBAB.test(name)) fail(`Module name must be lowercase kebab-case, received "${name ?? ""}"`);
+	const last = name.split("-").at(-1);
+	if (last.endsWith("s") && !last.endsWith("ss") && !NOT_PLURAL.has(last) &&
+		!isExcepted(`src/modules/${name}`, loadExceptions(root))) {
+		fail(`Module "${name}" looks plural; module names are singular (G4). If the capability is inherently a plurality, record the exception in the project root AGENTS.md under "## Tailframe exceptions" and rerun.`);
+	}
+	return name;
+}
+
+function requirePascal(value, label, forbiddenSuffixes = []) {
+	if (!value || !PASCAL.test(value)) fail(`${label} must be PascalCase, received "${value ?? ""}"`);
+	for (const suffix of forbiddenSuffixes) {
+		if (value.endsWith(suffix) && value !== suffix) fail(`${label} "${value}" is an aggregate name; one concept per file (G5)`);
+	}
+	return value;
+}
+
+function operationName(moduleName, verbNoun) {
+	const moduleSuffix = pascal(moduleName);
+	if (verbNoun.endsWith(moduleSuffix) && verbNoun !== moduleSuffix) {
+		const prefix = verbNoun.slice(0, -moduleSuffix.length);
+		return prefix[0].toLowerCase() + prefix.slice(1);
+	}
+	return verbNoun[0].toLowerCase() + verbNoun.slice(1);
+}
+
+function plan(files) {
+	return {
+		files,
+		write(root) {
+			const existing = Object.keys(files).filter((relative) => fs.existsSync(path.join(root, relative)));
+			if (existing.length) fail(`Refusing to overwrite existing file(s):\n${existing.map((file) => `  ${file}`).join("\n")}`);
+			for (const [relative, content] of Object.entries(files)) {
+				const absolute = path.join(root, relative);
+				fs.mkdirSync(path.dirname(absolute), { recursive: true });
+				fs.writeFileSync(absolute, content);
+			}
+			return Object.keys(files);
+		}
+	};
+}
+
+function useCaseFiles(moduleName, verbNoun) {
+	return {
+		[`src/modules/${moduleName}/use-cases/${verbNoun}.ts`]:
+`import type { UseCase } from "@/core/UseCase";
+import type { RequestContext } from "@/core/RequestContext";
+
+export interface ${verbNoun}Input {}
+
+export interface ${verbNoun}Output {}
+
+export class ${verbNoun} implements UseCase<${verbNoun}Input, ${verbNoun}Output> {
+	async execute(_context: RequestContext, _input: ${verbNoun}Input): Promise<${verbNoun}Output> {
+		throw new Error("${verbNoun} is not implemented");
+	}
+}
+`,
+		[`src/modules/${moduleName}/__tests__/${verbNoun}.test.ts`]:
+`import { ${verbNoun} } from "@/modules/${moduleName}/use-cases/${verbNoun}";
+
+describe("${verbNoun}", () => {
+	it("is not implemented yet", async () => {
+		await expect(new ${verbNoun}().execute({ requestId: "test", roles: [] }, {})).rejects.toThrow();
+	});
+});
+`
+	};
+}
+
+function httpFiles(moduleName, verbNoun) {
+	const operation = operationName(moduleName, verbNoun);
+	const dependency = verbNoun[0].toLowerCase() + verbNoun.slice(1);
+	return {
+		[`src/modules/${moduleName}/http/${moduleName}.schemas.ts`]:
+`import Joi from "joi";
+
+export const ${verbNoun}Schema = Joi.object({}).unknown(false);
+`,
+		[`src/modules/${moduleName}/http/${moduleName}.routes.ts`]:
+`import { Router } from "express";
+import type { ${verbNoun} } from "@/modules/${moduleName}/use-cases/${verbNoun}";
+import { ${verbNoun}Schema } from "@/modules/${moduleName}/http/${moduleName}.schemas";
+import { createRequestContext } from "@/platform/http/createRequestContext";
+import { rpcResult } from "@/platform/http/rpc";
+
+export function ${camel(moduleName)}Routes(${dependency}: ${verbNoun}) {
+	const router = Router();
+	router.post("/${moduleName}.${operation}", async (req, res, next) => {
+		try {
+			const input = await ${verbNoun}Schema.validateAsync(req.body ?? {});
+			rpcResult(res, await ${dependency}.execute(await createRequestContext(req), input));
+		} catch (error) {
+			next(error);
+		}
+	});
+	return router;
+}
+`
+	};
+}
+
+const serviceSchematics = {
+	module(root, [name, verbNoun], options) {
+		requireModuleName(root, name);
+		requirePascal(verbNoun, "First use case", ["UseCases"]);
+		const files = { ...useCaseFiles(name, verbNoun), ...(options.has("--no-http") ? {} : httpFiles(name, verbNoun)) };
+		return [plan(files), [
+			`Register ${verbNoun} in src/app/container.ts`,
+			...(options.has("--no-http") ? [] : [`Mount ${camel(name)}Routes in src/app/routes.ts`]),
+			`Implement ${verbNoun}.execute and replace the placeholder test`
+		]];
+	},
+	"use-case"(root, [moduleName, verbNoun]) {
+		requireModuleName(root, moduleName);
+		requirePascal(verbNoun, "Use case", ["UseCases"]);
+		return [plan(useCaseFiles(moduleName, verbNoun)), [
+			`Register ${verbNoun} in src/app/container.ts`,
+			`Expose it from an entry point (http route, worker, job, or cli) if the capability needs one`,
+			`Implement ${verbNoun}.execute and replace the placeholder test`
+		]];
+	},
+	http(root, [moduleName, verbNoun]) {
+		requireModuleName(root, moduleName);
+		requirePascal(verbNoun, "Use case", ["UseCases"]);
+		if (!fs.existsSync(path.join(root, `src/modules/${moduleName}/use-cases/${verbNoun}.ts`)))
+			fail(`Use case src/modules/${moduleName}/use-cases/${verbNoun}.ts does not exist; generate it first`);
+		return [plan(httpFiles(moduleName, verbNoun)), [
+			`Mount ${camel(moduleName)}Routes in src/app/routes.ts`,
+			`Define the real request schema in ${moduleName}.schemas.ts`
+		]];
+	},
+	port(root, [moduleName, portName]) {
+		requireModuleName(root, moduleName);
+		requirePascal(portName, "Port", ["Ports", "Repositories"]);
+		return [plan({
+			[`src/modules/${moduleName}/use-cases/ports/${portName}.ts`]:
+`export interface ${portName} {}
+`
+		}), [
+			`Declare the port's methods with domain-owned types`,
+			`Implement it: tailframe generate adapter ${moduleName} ${portName} --db mongo`,
+			`Bind the implementation in src/app/container.ts`
+		]];
+	},
+	adapter(root, [moduleName, portName], options) {
+		requireModuleName(root, moduleName);
+		requirePascal(portName, "Port", ["Ports", "Repositories"]);
+		const technology = options.get("--db") ?? "mongo";
+		if (!/^[a-z][a-z0-9]*$/.test(technology)) fail(`--db must be a lowercase technology name, received "${technology}"`);
+		if (!fs.existsSync(path.join(root, `src/modules/${moduleName}/use-cases/ports/${portName}.ts`)))
+			fail(`Port src/modules/${moduleName}/use-cases/ports/${portName}.ts does not exist; generate it first`);
+		const className = `${technology[0].toUpperCase()}${technology.slice(1)}${portName}`;
+		return [plan({
+			[`src/modules/${moduleName}/persistence/${className}.ts`]:
+`import type { ${portName} } from "@/modules/${moduleName}/use-cases/ports/${portName}";
+
+export class ${className} implements ${portName} {}
+`
+		}), [
+			`Implement the port using platform ${technology} mechanisms; keep driver types (ObjectId, rows, documents) inside this file`,
+			`Bind ${className} to ${portName} in src/app/container.ts`
+		]];
+	},
+	identifiers(root, [moduleName, ...idNames]) {
+		requireModuleName(root, moduleName);
+		if (!idNames.length) fail("Provide at least one identifier name, e.g. tailframe generate identifiers project ProjectId");
+		for (const idName of idNames) {
+			if (!/^[A-Z][A-Za-z0-9]*Id$/.test(idName)) fail(`Identifier "${idName}" must be PascalCase and end with "Id"`);
+		}
+		const body = idNames.map((idName) => {
+			const value = idName[0].toLowerCase() + idName.slice(1);
+			return `export type ${idName} = Brand<string, "${idName}">;
+
+export function hydrate${idName}(value: string): ${idName} {
+	return value as ${idName};
+}
+
+export function ${value}Value(id: ${idName}): string {
+	return id;
+}`;
+		}).join("\n\n");
+		return [plan({
+			[`src/modules/${moduleName}/domain/identifiers.ts`]:
+`declare const identifierBrand: unique symbol;
+
+type Brand<Value, Name extends string> = Value & { readonly [identifierBrand]: Name };
+
+${body}
+`
+		}), [
+			`Use the branded types in this module's domain, use cases, and ports`,
+			`Convert at boundaries only: hydrate after http validation or persistence reads, unwrap with the *Value helpers when serializing or querying`
+		]];
+	},
+	integration(root, [provider]) {
+		if (!provider || !KEBAB.test(provider)) fail(`Provider must be lowercase kebab-case, received "${provider ?? ""}"`);
+		const className = `${pascal(provider)}Client`;
+		return [plan({
+			[`src/platform/integrations/${provider}/${className}.ts`]:
+`export class ${className} {}
+`
+		}), [
+			`Define a port in the owning module (tailframe generate port <module> <Name>) and implement it with ${className}`,
+			`Register the integration in src/app/container.ts`
+		]];
+	}
+};
+
+function uiArtifacts(moduleName, kindOptions) {
+	const files = {};
+	if (kindOptions.api) {
+		files[`src/modules/${moduleName}/api/${moduleName}.api.ts`] =
+`import { http } from "@/platform/http";
+import type { RpcResponse } from "@/core/rpc";
+
+export async function get${pascal(moduleName)}() {
+	return (await http.post<RpcResponse<unknown>>("${moduleName}.get")).data.result;
+}
+`;
+	}
+	if (kindOptions.view) {
+		const viewName = kindOptions.view.endsWith("View") ? kindOptions.view : `${kindOptions.view}View`;
+		files[`src/modules/${moduleName}/views/${viewName}.vue`] =
+`<script setup lang="ts"></script>
+
+<template>
+	<main>
+		<h1>${viewName}</h1>
+	</main>
+</template>
+`;
+	}
+	if (kindOptions.component) {
+		files[`src/modules/${moduleName}/components/${kindOptions.component}.vue`] =
+`<script setup lang="ts"></script>
+
+<template>
+	<div></div>
+</template>
+`;
+	}
+	if (kindOptions.store) {
+		files[`src/modules/${moduleName}/stores/${kindOptions.store}.store.ts`] =
+`import { reactive } from "vue";
+
+export const ${camel(kindOptions.store)}Store = reactive({});
+`;
+	}
+	if (kindOptions.composable) {
+		files[`src/modules/${moduleName}/composables/use${pascal(kindOptions.composable)}.ts`] =
+`export function use${pascal(kindOptions.composable)}() {
+	return {};
+}
+`;
+	}
+	return files;
+}
+
+const uiSchematics = {
+	module(root, [name], options) {
+		requireModuleName(root, name);
+		const artifacts = {
+			api: options.has("--api"),
+			view: options.get("--view"),
+			component: options.get("--component"),
+			store: options.get("--store"),
+			composable: options.get("--composable")
+		};
+		if (artifacts.view) requirePascal(artifacts.view, "View");
+		if (artifacts.component) requirePascal(artifacts.component, "Component");
+		if (artifacts.store && !KEBAB.test(artifacts.store)) fail(`Store name must be lowercase kebab-case, received "${artifacts.store}"`);
+		if (artifacts.composable && !KEBAB.test(artifacts.composable)) fail(`Composable name must be lowercase kebab-case, received "${artifacts.composable}"`);
+		const files = uiArtifacts(name, artifacts);
+		if (!Object.keys(files).length) fail("A UI module needs at least one artifact: pass --api, --view <Name>, --component <Name>, --store <name>, or --composable <name> (empty layers are forbidden)");
+		return [plan(files), [
+			...(artifacts.view ? [`Register the view in a route and mount it from src/app/router.ts`] : []),
+			...(artifacts.api ? [`Point ${name}.api.ts at the real RPC operation`] : []),
+			`Compose the module from src/app only; other modules must not import it`
+		]];
+	},
+	api(root, [moduleName]) {
+		requireModuleName(root, moduleName);
+		return [plan(uiArtifacts(moduleName, { api: true })), [`Point ${moduleName}.api.ts at the real RPC operation`]];
+	},
+	view(root, [moduleName, name]) {
+		requireModuleName(root, moduleName);
+		requirePascal(name, "View");
+		return [plan(uiArtifacts(moduleName, { view: name })), [`Register the view in a route and mount it from src/app/router.ts`]];
+	},
+	component(root, [moduleName, name]) {
+		requireModuleName(root, moduleName);
+		requirePascal(name, "Component");
+		return [plan(uiArtifacts(moduleName, { component: name })), [`Use the component from this module's views only`]];
+	},
+	store(root, [moduleName, name]) {
+		requireModuleName(root, moduleName);
+		if (!name || !KEBAB.test(name)) fail(`Store name must be lowercase kebab-case, received "${name ?? ""}"`);
+		return [plan(uiArtifacts(moduleName, { store: name })), [`Keep the store module-private; cross-module state belongs in src/app`]];
+	},
+	composable(root, [moduleName, name]) {
+		requireModuleName(root, moduleName);
+		if (!name || !KEBAB.test(name)) fail(`Composable name must be lowercase kebab-case, received "${name ?? ""}"`);
+		return [plan(uiArtifacts(moduleName, { composable: name })), [`Use the composable from this module only`]];
+	}
+};
+
+export function runGenerate(rootArgument, argv) {
+	const root = path.resolve(rootArgument);
+	const positionals = [];
+	const options = new Map();
+	const flags = new Set();
+	const args = [...argv];
+	while (args.length) {
+		const value = args.shift();
+		if (value === "--no-http" || value === "--api") flags.add(value);
+		else if (value.startsWith("--")) options.set(value, args.shift());
+		else positionals.push(value);
+	}
+	options.has = (key) => flags.has(key) || Map.prototype.has.call(options, key);
+	const schematic = positionals.shift();
+	const kind = detectKind(root);
+	const registry = kind === "service" ? serviceSchematics : uiSchematics;
+	if (!schematic || !registry[schematic]) {
+		fail(`Unknown ${kind} schematic "${schematic ?? ""}". Available: ${Object.keys(registry).join(", ")}`);
+	}
+	const [filePlan, checklist] = registry[schematic](root, positionals, options);
+	const created = filePlan.write(root);
+	return { kind, created, checklist: [...checklist, "Run npm run validate:architecture, then focused type checks and tests"] };
+}