@zaaxch/tailframe 0.1.1 → 2.0.0

package/bin/tailframe.mjs

@@ -14,8 +14,9 @@ function usage() {
 	console.error("  service schematics: module <name> <VerbNoun> [--no-http], use-case <module> <VerbNoun>,");
 	console.error("    http <module> <VerbNoun>, port <module> <Name>, adapter <module> <PortName> --db <technology>,");
 	console.error("    identifiers <module> <NameId...>, integration <provider>");
-	console.error("  ui schematics: module <name> --api|--view <Name>|--component <Name>|--store <name>|--composable <name>,");
-	console.error("    api <module>, view <module> <Name>, component <module> <Name>, store <module> <name>, composable <module> <name>");
+	console.error("  ui schematics: module <name> --api|--view <Name>|--component <Name>|--store <name>|--composable <name>|--public <name>|--public-component <Name>,");
+	console.error("    api <module>, view <module> <Name>, component <module> <Name>, store <module> <name>, composable <module> <name>,");
+	console.error("    public <module> <name>, public-component <module> <Name>, app-store auth, app-store theme --storage-key <key>, app-component ThemeToggle");
 	process.exit(2);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "0.1.1",
+	"version": "2.0.0",
 	"description": "Tailframe architecture toolkit: validates the Tailframe structure, import-boundary, and file-convention contracts. The package version is the contract version.",
 	"type": "module",
 	"bin": {

package/src/architecture.mjs

@@ -4,6 +4,22 @@ import path from "node:path";
 
 
 const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".vue"]);
+const APP_STORE_FILES = ["auth.store.ts", "theme.store.ts"];
+const APP_PUBLIC_FILES = ["ThemeToggle.vue"];
+const APP_STORE_TARGETS = new Set(["src/app/stores/auth.store", "src/app/stores/theme.store"]);
+const APP_PUBLIC_TARGETS = new Set(["src/app/public/ThemeToggle"]);
+
+function withoutSourceExtension(target) {
+	return target?.replace(/\.(?:ts|tsx|vue)$/, "");
+}
+
+function isPublicAppStore(target) {
+	return APP_STORE_TARGETS.has(withoutSourceExtension(target));
+}
+
+function isPublicAppUi(target) {
+	return APP_PUBLIC_TARGETS.has(withoutSourceExtension(target));
+}
 
 export function toPosix(value) {
 	return value.split(path.sep).join("/");
@@ -47,6 +63,10 @@ function resolveInternal(relativeFile, specifier) {
 	return path.posix.normalize(path.posix.join(path.posix.dirname(relativeFile), specifier));
 }
 
+function looksLikeUnsupportedInternalAlias(specifier) {
+	return /^(?:(?:~|#|\$)\/(?:src\/)?|@(?:app|core|platform|modules)\/|(?:src\/)?(?:app|core|platform|modules)\/)/.test(specifier);
+}
+
 export function isTestFile(relative) {
 	return relative.includes("/__tests__/") || /\.(?:test|spec)\.[^.]+$/.test(relative);
 }
@@ -86,6 +106,10 @@ function validateStructure(root, kind, fail) {
 			if (!allowed.includes(name)) fail(`Unexpected architecture ${entryKind}: ${relative}/${name}`);
 		}
 	};
+	const checkOptionalEntries = (relative, entryKind, allowed) => {
+		const target = path.join(root, relative);
+		if (fs.existsSync(target) && fs.statSync(target).isDirectory()) checkEntries(relative, entryKind, allowed);
+	};
 
 	if (kind === "service") {
 		checkEntries("src", "directory", ["__tests__", "app", "core", "modules", "platform"]);
@@ -95,8 +119,12 @@ function validateStructure(root, kind, fail) {
 	} else {
 		checkEntries("src", "directory", ["app", "core", "modules", "platform"]);
 		checkEntries("src", "file", ["main.ts"]);
-		checkEntries("src/app", "directory", ["__tests__", "components", "stores", "views"]);
+		checkEntries("src/app", "directory", ["__tests__", "components", "public", "stores", "views"]);
 		checkEntries("src/core", "directory", []);
+		checkOptionalEntries("src/app/public", "directory", []);
+		checkOptionalEntries("src/app/public", "file", APP_PUBLIC_FILES);
+		checkOptionalEntries("src/app/stores", "directory", []);
+		checkOptionalEntries("src/app/stores", "file", APP_STORE_FILES);
 	}
 
 	const platform = path.join(root, "src/platform");
@@ -108,15 +136,22 @@ function validateStructure(root, kind, fail) {
 	}
 	const allowedModuleDirectories = kind === "service"
 		? ["__tests__", "domain", "http", "persistence", "use-cases"]
-		: ["__tests__", "api", "components", "composables", "routes", "stores", "types", "views"];
+		: ["__tests__", "api", "components", "composables", "public", "routes", "stores", "types", "views"];
 	for (const moduleName of listEntries(modules, "directory")) {
-		if (kind === "ui" && moduleName === "theme") fail("Application theme must live under src/app, not src/modules/theme");
+		if (kind === "ui" && ["auth", "theme"].includes(moduleName)) {
+			fail(`Application ${moduleName === "auth" ? "authentication" : "theme"} must live under src/app, not src/modules/${moduleName}`);
+		}
 		checkEntries(`src/modules/${moduleName}`, "directory", allowedModuleDirectories);
 		checkEntries(`src/modules/${moduleName}`, "file", []);
+		if (kind === "ui") checkOptionalEntries(`src/modules/${moduleName}/public`, "directory", []);
 	}
 }
 
 function validateServiceImport(source, target, external, fail, graph) {
+	if (external === "tsyringe" && source !== "src/app/container.ts") {
+		fail(`${source} may not import tsyringe; dependency-injection framework code is confined to src/app/container.ts`);
+		return;
+	}
 	if (source === "src/server.ts" || source === "src/worker.ts") {
 		if (external) {
 			if (external !== "reflect-metadata") fail(`${source} may import only reflect-metadata and app bootstrap code, not ${external}`);
@@ -188,7 +223,7 @@ function validateServiceImport(source, target, external, fail, graph) {
 	}
 }
 
-function validateUiImport(source, target, external, fail) {
+function validateUiImport(source, target, external, fail, graph) {
 	if (source === "src/main.ts") {
 		if (external || !target.startsWith("src/app/")) fail(`src/main.ts may import only app bootstrap code, not ${external ?? target}`);
 		return;
@@ -197,6 +232,22 @@ function validateUiImport(source, target, external, fail) {
 		if (external || !target.startsWith("src/core/")) fail(`${source} violates core purity by importing ${external ?? target}`);
 		return;
 	}
+	if (source.startsWith("src/app/stores/")) {
+		if (external || target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
+		fail(`${source} is a canonical shell store and may import only framework packages, core, or platform, not ${target}`);
+		return;
+	}
+	if (source.startsWith("src/app/public/")) {
+		if (external || target.startsWith("src/core/") || target.startsWith("src/platform/") || isPublicAppStore(target)) return;
+		fail(`${source} is canonical public shell UI and may import only framework packages, core, platform, or a canonical app store, not ${target}`);
+		return;
+	}
+	if (/^src\/app\/(?:components|views)\//.test(source)) {
+		const targetModule = moduleParts(target ?? "");
+		if (!targetModule || targetModule.layer === "public") return;
+		fail(`${source} may compose a product module only through a named module public entry, not ${target}; route module views directly from src/app/router.ts`);
+		return;
+	}
 	if (source.startsWith("src/app/")) return;
 	if (source.startsWith("src/platform/")) {
 		if (external || target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
@@ -205,20 +256,27 @@ function validateUiImport(source, target, external, fail) {
 	}
 	const sourceModule = moduleParts(source);
 	if (!sourceModule || external) return;
-	if (target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
+	if (target.startsWith("src/core/") || target.startsWith("src/platform/") || isPublicAppStore(target) || isPublicAppUi(target)) return;
 	const targetModule = moduleParts(target);
 	if (targetModule?.module === sourceModule.module) return;
-	fail(`${source} may import only its own UI module, core, or platform, not ${target}`);
+	if (targetModule?.layer === "public" && targetModule.remainder && !targetModule.remainder.includes("/")) {
+		if (!isTestFile(source) && sourceModule.layer !== "__tests__") {
+			if (!graph.has(sourceModule.module)) graph.set(sourceModule.module, new Set());
+			graph.get(sourceModule.module).add(targetModule.module);
+		}
+		return;
+	}
+	fail(`${source} may import only its own UI module, core, platform, the canonical auth/theme app stores, ThemeToggle, or a named file directly under another module's public directory, not ${target}`);
 }
 
-function detectCycles(graph, fail) {
+function detectCycles(graph, fail, label) {
 	const visited = new Set();
 	const active = [];
 	const activeSet = new Set();
 	const visit = (moduleName) => {
 		if (activeSet.has(moduleName)) {
 			const start = active.indexOf(moduleName);
-			fail(`Cross-module use-case dependency cycle: ${[...active.slice(start), moduleName].join(" -> ")}`);
+			fail(`${label}: ${[...active.slice(start), moduleName].join(" -> ")}`);
 			return;
 		}
 		if (visited.has(moduleName)) return;
@@ -246,14 +304,18 @@ export function validateArchitecture(rootArgument, kind) {
 		const relative = toPosix(path.relative(root, absolute));
 		for (const specifier of extractImports(fs.readFileSync(absolute, "utf8"), relative)) {
 			const target = resolveInternal(relative, specifier);
+			if (!target && looksLikeUnsupportedInternalAlias(specifier)) {
+				fail(`${relative} uses unsupported internal import alias ${specifier}; use @/ or a relative import so boundaries remain enforceable`);
+				continue;
+			}
 			if (target && !target.startsWith("src/")) {
 				fail(`${relative} has a relative import outside src: ${specifier}`);
 				continue;
 			}
 			if (kind === "service") validateServiceImport(relative, target, target ? undefined : specifier, fail, graph);
-			else validateUiImport(relative, target, target ? undefined : specifier, fail);
+			else validateUiImport(relative, target, target ? undefined : specifier, fail, graph);
 		}
 	}
-	if (kind === "service") detectCycles(graph, fail);
+	detectCycles(graph, fail, kind === "service" ? "Cross-module use-case dependency cycle" : "Cross-module UI public dependency cycle");
 	return errors;
 }

package/src/conventions.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { toPosix, walk } from "./architecture.mjs";
+import { authAppStoreSource, themeAppStoreSource, themeToggleSource } from "./generate.mjs";
 
 const PASCAL = /^[A-Z][A-Za-z0-9]*$/;
 const CAMEL = /^[a-z][A-Za-z0-9]*$/;
@@ -8,6 +9,16 @@ 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/;
+const ROUTE_NAMES_FILE = "src/core/RouteNames.ts";
+const ROUTE_NAMES_DECLARATION = /\b(?:enum|const|type)\s+RouteNames\b/;
+const ROUTE_NAMES_CANONICAL_DECLARATION = /\bexport\s+enum\s+RouteNames\b/;
+const ROUTE_NAMES_VALUE = /^\s*[A-Z][A-Z0-9_]*\s*=\s*["']([^"']+)["']/gm;
+const ROUTE_NAME_REFERENCE = /\bname:\s*["']([^"']+)["']/g;
+
+const camel = (kebab) => {
+	const value = kebab.split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join("");
+	return value[0].toLowerCase() + value.slice(1);
+};
 
 function parseName(fileName) {
 	if (fileName.endsWith(".d.ts")) return undefined;
@@ -59,6 +70,9 @@ export function validateConventions(rootArgument, kind) {
 			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`);
 			}
+			if (kind === "ui" && relative.startsWith("src/app/public/") && relative.slice("src/app/public/".length).includes("/")) {
+				flag("U6", relative, `${relative} is nested under app/public; public shell entries are named files directly under src/app/public`);
+			}
 			continue;
 		}
 
@@ -89,15 +103,168 @@ export function validateConventions(rootArgument, kind) {
 		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") {
+			validateServiceSource(relative, moduleName, layer, remainder, name, fs.readFileSync(absolute, "utf8"), 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`);
 		}
 	}
+	if (kind === "ui") {
+		validateRouteNames(root, src, flag);
+		validateCanonicalShell(root, flag);
+	} else {
+		validateServiceComposition(root, flag);
+	}
 	return violations;
 }
 
+function validateServiceSource(relative, moduleName, layer, remainder, name, source, flag) {
+	if (layer === "use-cases" && remainder.split("/")[1] !== "ports") {
+		const exportedClasses = [...source.matchAll(/^export\s+class\s+([A-Z][A-Za-z0-9]*)\b/gm)].map((match) => match[1]);
+		if (exportedClasses.length > 1) {
+			flag("G5", relative, `${relative} exports multiple classes (${exportedClasses.join(", ")}); keep one named use-case class per file`);
+		} else if (exportedClasses.length === 1 && exportedClasses[0] !== name.stem) {
+			flag("G1", relative, `${relative} must be named ${exportedClasses[0]}.ts after its exported use-case class`);
+		}
+	}
+
+	if (layer !== "http") return;
+	if (name.role === "routes" && name.subject === moduleName) {
+		const factories = [...source.matchAll(/^export\s+function\s+([A-Za-z][A-Za-z0-9]*Routes)\s*\(/gm)].map((match) => match[1]);
+		const expected = `${camel(moduleName)}Routes`;
+		if (factories.length !== 1 || factories[0] !== expected) {
+			flag("S8", relative, `${relative} must export exactly one module route factory named ${expected}`);
+		}
+		const postCount = [...source.matchAll(/\brouter\.post\s*\(/g)].length;
+		const rpcHandlerCount = [...source.matchAll(/\brpcHandler\s*\(/g)].length;
+		if (postCount > rpcHandlerCount) {
+			flag("S8", relative, `${relative} must translate every RPC POST through rpcHandler; found ${postCount} POST routes and ${rpcHandlerCount} rpcHandler calls`);
+		}
+	}
+	if (name.role === "schemas" && name.subject === moduleName) {
+		const schemas = [...source.matchAll(/^export\s+const\s+([A-Za-z][A-Za-z0-9]*)\s*=/gm)].map((match) => match[1]);
+		if (schemas.length === 0) flag("S8", relative, `${relative} must export at least one PascalCase operation schema`);
+		for (const schema of schemas) {
+			if (!PASCAL.test(schema) || !schema.endsWith("Schema")) {
+				flag("S8", relative, `${relative} exports ${schema}; operation schemas are PascalCase and end with Schema`);
+			}
+		}
+	}
+}
+
+function validateServiceComposition(root, flag) {
+	const containerRelative = "src/app/container.ts";
+	const containerFile = path.join(root, containerRelative);
+	if (!fs.existsSync(containerFile)) {
+		flag("S9", containerRelative, `${containerRelative} is required as the explicit application composition root`);
+	} else {
+		const source = fs.readFileSync(containerFile, "utf8");
+		for (const [pattern, message] of [
+			[/\bexport\s+function\s+registerDependencies\s*\(/, "must export registerDependencies"],
+			[/\bcontainer\.reset\s*\(/, "must reset the container before registration"],
+			[/\bregisterInstance\s*\(/, "must register explicit instances"]
+		]) {
+			if (!pattern.test(source)) flag("S9", containerRelative, `${containerRelative} ${message}`);
+		}
+		if (/\bregisterSingleton\s*\(|\binstanceCachingFactory\s*\(|@inject(?:able)?\b/.test(source)) {
+			flag("S9", containerRelative, `${containerRelative} must use explicit construction and instance registration, not decorators, singleton factories, or implicit resolution`);
+		}
+	}
+
+	const serverRelative = "src/app/server.ts";
+	const serverFile = path.join(root, serverRelative);
+	if (!fs.existsSync(serverFile)) {
+		flag("S9", serverRelative, `${serverRelative} is required as the HTTP application assembly`);
+	} else if (!/\bregisterDependencies\s*\(/.test(fs.readFileSync(serverFile, "utf8"))) {
+		flag("S9", serverRelative, `${serverRelative} must initialize the app-owned composition root after infrastructure connects`);
+	}
+
+	const workerRelative = "src/app/workers/startWorker.ts";
+	const workerFile = path.join(root, workerRelative);
+	if (fs.existsSync(workerFile)) {
+		const source = fs.readFileSync(workerFile, "utf8");
+		if (!/\bregisterDependencies\s*\(/.test(source)) {
+			flag("S9", workerRelative, `${workerRelative} must initialize the same app-owned composition root as the HTTP server`);
+		}
+		if (/\bprocess\.exit\s*\(/.test(source)) {
+			flag("S9", workerRelative, `${workerRelative} must return an awaitable shutdown path instead of forcing process.exit`);
+		}
+	}
+}
+
+function normalizeGeneratedSource(source) {
+	return source.replace(/\r\n/g, "\n");
+}
+
+function validateCanonicalShell(root, flag) {
+	const authRelative = "src/app/stores/auth.store.ts";
+	const authFile = path.join(root, authRelative);
+	if (fs.existsSync(authFile) && normalizeGeneratedSource(fs.readFileSync(authFile, "utf8")) !== authAppStoreSource()) {
+		flag("U7", authRelative, `${authRelative} differs from the canonical Tailframe auth store; regenerate it instead of maintaining a project-local variant`);
+	}
+
+	const themeRelative = "src/app/stores/theme.store.ts";
+	const themeFile = path.join(root, themeRelative);
+	if (fs.existsSync(themeFile)) {
+		const source = normalizeGeneratedSource(fs.readFileSync(themeFile, "utf8"));
+		const storageKeyMatch = source.match(/useLocalStorage<Theme>\(("(?:\\.|[^"\\])*"), preferredTheme\(\)\)/);
+		let expected;
+		if (storageKeyMatch) {
+			try { expected = themeAppStoreSource(JSON.parse(storageKeyMatch[1])); } catch { /* reported below */ }
+		}
+		if (!expected || source !== expected) {
+			flag("U7", themeRelative, `${themeRelative} differs from the canonical Tailframe theme store; only its generated storage-key value may vary`);
+		}
+	}
+
+	const toggleRelative = "src/app/public/ThemeToggle.vue";
+	const toggleFile = path.join(root, toggleRelative);
+	if (fs.existsSync(toggleFile)) {
+		if (!fs.existsSync(themeFile)) flag("U7", toggleRelative, `${toggleRelative} requires ${themeRelative}`);
+		if (normalizeGeneratedSource(fs.readFileSync(toggleFile, "utf8")) !== themeToggleSource()) {
+			flag("U7", toggleRelative, `${toggleRelative} differs from the canonical Tailframe theme toggle; regenerate it instead of maintaining a project-local variant`);
+		}
+	}
+}
+
+/**
+ * Route names are the one piece of shell vocabulary a module legitimately needs, so they live in a
+ * core enum both sides may import. A module that cannot reach the enum hardcodes the string instead,
+ * and a later rename breaks navigation silently.
+ */
+function validateRouteNames(root, src, flag) {
+	const declarationFile = path.join(root, ROUTE_NAMES_FILE);
+	const declared = new Set();
+	if (!fs.existsSync(declarationFile)) {
+		flag("U5", ROUTE_NAMES_FILE, `${ROUTE_NAMES_FILE} is required; route names are one exported enum shared by the router and modules`);
+	} else {
+		const text = fs.readFileSync(declarationFile, "utf8");
+		if (!ROUTE_NAMES_CANONICAL_DECLARATION.test(text)) {
+			flag("U5", ROUTE_NAMES_FILE, `${ROUTE_NAMES_FILE} must declare export enum RouteNames`);
+		}
+		for (const match of text.matchAll(ROUTE_NAMES_VALUE)) declared.add(match[1]);
+		if (declared.size === 0) flag("U5", ROUTE_NAMES_FILE, `${ROUTE_NAMES_FILE} must declare at least one string-valued route name`);
+	}
+	for (const absolute of walk(src)) {
+		const relative = toPosix(path.relative(root, absolute));
+		if (![".ts", ".vue"].includes(path.extname(relative))) continue;
+		const text = fs.readFileSync(absolute, "utf8");
+		if (relative !== ROUTE_NAMES_FILE && ROUTE_NAMES_DECLARATION.test(text)) {
+			flag("U5", relative, `${relative} declares RouteNames outside ${ROUTE_NAMES_FILE}; route names are one core enum imported by the router and by modules`);
+		}
+		if (!relative.startsWith("src/modules/") || declared.size === 0) continue;
+		for (const match of text.matchAll(ROUTE_NAME_REFERENCE)) {
+			if (declared.has(match[1])) {
+				flag("U5", relative, `${relative} hardcodes the route name "${match[1]}"; import RouteNames from ${ROUTE_NAMES_FILE}`);
+				break;
+			}
+		}
+	}
+}
+
 function validateShared(relative, name, flag) {
 	if (name.stem === "index") return;
 	const directory = path.posix.basename(path.posix.dirname(relative));
@@ -111,6 +278,10 @@ function validateShared(relative, name, flag) {
 		else if (directory === "views" && !name.stem.endsWith("View")) flag("U2", relative, `${relative} views are named <Name>View.vue`);
 		return;
 	}
+	if (relative.startsWith("src/app/stores/") && name.extension === ".ts") {
+		flag("U3", relative, `${relative} is not a canonical app store; app/stores is closed to auth.store.ts and theme.store.ts`);
+		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)`);
 	}
@@ -178,6 +349,14 @@ function validateUiFile(relative, moduleName, layer, name, flag) {
 		if (name.role !== "store") flag("U3", relative, `${relative} stores are named <name>.store.ts`);
 		return;
 	}
+	if (layer === "public") {
+		const remainder = relative.slice(`src/modules/${moduleName}/public/`.length);
+		if (remainder.includes("/")) flag("U6", relative, `${relative} is nested; module public entries are named files directly under public/`);
+		else if (name.role !== undefined || (!PASCAL.test(name.stem) && !CAMEL.test(name.stem))) {
+			flag("U6", relative, `${relative} must be a named public entry in primary-export casing, not a role-suffix file or barrel`);
+		}
+		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`);