@zaaxch/tailframe 0.1.0

package/assets/validate-architecture.mjs

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".vue"]);
+
+function toPosix(value) {
+	return value.split(path.sep).join("/");
+}
+
+function listEntries(target, kind) {
+	return fs.readdirSync(target, { withFileTypes: true })
+		.filter((entry) => kind === "directory" ? entry.isDirectory() : entry.isFile())
+		.map((entry) => entry.name)
+		.sort();
+}
+
+function walk(target) {
+	const results = [];
+	for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+		if (["node_modules", "dist", ".git"].includes(entry.name)) continue;
+		const absolute = path.join(target, entry.name);
+		if (entry.isDirectory()) results.push(...walk(absolute));
+		else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) results.push(absolute);
+	}
+	return results;
+}
+
+function extractImports(source, relative) {
+	const code = relative.endsWith(".vue")
+		? [...source.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/gi)].map((match) => match[1]).join("\n")
+		: source;
+	const script = code.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+	const imports = [];
+	const staticPattern = /(?:^|[;\n])\s*(?:import|export)\s+(?:type\s+)?(?:[^"'`;]*?\s+from\s+)?["']([^"']+)["']/g;
+	const dynamicPattern = /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+	for (const pattern of [staticPattern, dynamicPattern]) {
+		for (const match of script.matchAll(pattern)) imports.push(match[1]);
+	}
+	return [...new Set(imports)];
+}
+
+function resolveInternal(relativeFile, specifier) {
+	if (specifier.startsWith("@/")) return path.posix.normalize(`src/${specifier.slice(2)}`);
+	if (!specifier.startsWith(".")) return undefined;
+	return path.posix.normalize(path.posix.join(path.posix.dirname(relativeFile), specifier));
+}
+
+function isTestFile(relative) {
+	return relative.includes("/__tests__/") || /\.(?:test|spec)\.[^.]+$/.test(relative);
+}
+
+function moduleParts(relative) {
+	const match = relative.match(/^src\/modules\/([^/]+)\/([^/]+)(?:\/(.*))?$/);
+	if (!match) return undefined;
+	return { module: match[1], layer: match[2], remainder: match[3] ?? "" };
+}
+
+function isNamedUseCase(relative, expectedModule) {
+	const target = moduleParts(relative);
+	return Boolean(
+		target &&
+		target.module === expectedModule &&
+		target.layer === "use-cases" &&
+		target.remainder &&
+		!target.remainder.includes("/") &&
+		!isTestFile(relative)
+	);
+}
+
+function validateStructure(root, kind, fail) {
+	const src = path.join(root, "src");
+	if (!fs.existsSync(src) || !fs.statSync(src).isDirectory()) {
+		fail("Missing architecture directory: src");
+		return;
+	}
+
+	const checkEntries = (relative, entryKind, allowed) => {
+		const target = path.join(root, relative);
+		if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+			fail(`Missing architecture directory: ${relative}`);
+			return;
+		}
+		for (const name of listEntries(target, entryKind)) {
+			if (!allowed.includes(name)) fail(`Unexpected architecture ${entryKind}: ${relative}/${name}`);
+		}
+	};
+
+	if (kind === "service") {
+		checkEntries("src", "directory", ["__tests__", "app", "core", "modules", "platform"]);
+		checkEntries("src", "file", ["server.ts", "worker.ts"]);
+		checkEntries("src/app", "directory", ["__tests__", "cli", "jobs", "mcp", "scheduled-tasks", "workers"]);
+		checkEntries("src/core", "directory", []);
+	} else {
+		checkEntries("src", "directory", ["app", "core", "modules", "platform"]);
+		checkEntries("src", "file", ["main.ts"]);
+		checkEntries("src/app", "directory", ["__tests__", "components", "stores", "views"]);
+		checkEntries("src/core", "directory", []);
+	}
+
+	const platform = path.join(root, "src/platform");
+	if (!fs.existsSync(platform) || !fs.statSync(platform).isDirectory()) fail("Missing architecture directory: src/platform");
+	const modules = path.join(root, "src/modules");
+	if (!fs.existsSync(modules) || !fs.statSync(modules).isDirectory()) {
+		fail("Missing architecture directory: src/modules");
+		return;
+	}
+	const allowedModuleDirectories = kind === "service"
+		? ["__tests__", "domain", "http", "persistence", "use-cases"]
+		: ["__tests__", "api", "components", "composables", "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");
+		checkEntries(`src/modules/${moduleName}`, "directory", allowedModuleDirectories);
+		checkEntries(`src/modules/${moduleName}`, "file", []);
+	}
+}
+
+function validateServiceImport(source, target, external, fail, graph) {
+	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}`);
+		} else {
+			const expectedAssembly = source === "src/server.ts" ? "src/app/server" : "src/app/workers/";
+			if (!target.startsWith(expectedAssembly)) fail(`${source} may import only its matching app assembly, not ${target}`);
+		}
+		return;
+	}
+	if (source.startsWith("src/core/")) {
+		if (external || !target.startsWith("src/core/")) fail(`${source} violates core purity by importing ${external ?? target}`);
+		return;
+	}
+	if (source.startsWith("src/app/") || source.startsWith("src/__tests__/")) return;
+	if (source.startsWith("src/platform/")) {
+		if (external) return;
+		if (target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
+		if (source.startsWith("src/platform/integrations/") && /^src\/modules\/[^/]+\/use-cases\/ports\//.test(target)) return;
+		fail(`${source} may import only core, platform, or a module-owned integration port, not ${target}`);
+		return;
+	}
+
+	const sourceModule = moduleParts(source);
+	if (!sourceModule) return;
+	const moduleTest = isTestFile(source) || sourceModule.layer === "__tests__";
+	if (external) {
+		if (!moduleTest && ["domain", "use-cases"].includes(sourceModule.layer)) {
+			fail(`${source} in ${sourceModule.layer} may not import framework or vendor package ${external}`);
+		}
+		return;
+	}
+	if (target.startsWith("src/core/")) return;
+	const targetModule = moduleParts(target);
+	if (target.startsWith("src/platform/")) {
+		if (["http", "persistence"].includes(sourceModule.layer) || moduleTest) return;
+		fail(`${source} cannot import platform code from ${sourceModule.layer}`);
+		return;
+	}
+	if (target.startsWith("src/app/") || target.startsWith("src/__tests__/")) {
+		if (moduleTest) return;
+		fail(`${source} cannot import application assembly or cross-boundary test support`);
+		return;
+	}
+	if (!targetModule) {
+		fail(`${source} imports unsupported internal path ${target}`);
+		return;
+	}
+	if (targetModule.module !== sourceModule.module) {
+		if ((sourceModule.layer === "use-cases" || moduleTest) && isNamedUseCase(target, targetModule.module)) {
+			if (!moduleTest) {
+				if (!graph.has(sourceModule.module)) graph.set(sourceModule.module, new Set());
+				graph.get(sourceModule.module).add(targetModule.module);
+			}
+			return;
+		}
+		fail(`${source} may import another module only through a named use-case file, not ${target}`);
+		return;
+	}
+
+	if (moduleTest) return;
+	const allowedLayers = {
+		domain: ["domain"],
+		"use-cases": ["domain", "use-cases"],
+		http: ["domain", "http", "use-cases"],
+		persistence: ["domain", "persistence", "use-cases"]
+	}[sourceModule.layer] ?? [];
+	if (!allowedLayers.includes(targetModule.layer)) {
+		fail(`${source} in ${sourceModule.layer} cannot import its module's ${targetModule.layer} layer`);
+	}
+}
+
+function validateUiImport(source, target, external, fail) {
+	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;
+	}
+	if (source.startsWith("src/core/")) {
+		if (external || !target.startsWith("src/core/")) fail(`${source} violates core purity by importing ${external ?? target}`);
+		return;
+	}
+	if (source.startsWith("src/app/")) return;
+	if (source.startsWith("src/platform/")) {
+		if (external || target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
+		fail(`${source} may not import app or module code: ${target}`);
+		return;
+	}
+	const sourceModule = moduleParts(source);
+	if (!sourceModule || external) return;
+	if (target.startsWith("src/core/") || target.startsWith("src/platform/")) 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}`);
+}
+
+function detectCycles(graph, fail) {
+	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(" -> ")}`);
+			return;
+		}
+		if (visited.has(moduleName)) return;
+		visited.add(moduleName);
+		active.push(moduleName);
+		activeSet.add(moduleName);
+		for (const dependency of graph.get(moduleName) ?? []) visit(dependency);
+		active.pop();
+		activeSet.delete(moduleName);
+	};
+	for (const moduleName of graph.keys()) visit(moduleName);
+}
+
+export function validateArchitecture(rootArgument, kind) {
+	const root = path.resolve(rootArgument);
+	const errors = [];
+	const fail = (message) => errors.push(message);
+	if (!["service", "ui"].includes(kind)) return [`Architecture kind must be service or ui, received ${kind ?? "nothing"}`];
+	if (!fs.existsSync(root)) return [`Architecture root does not exist: ${root}`];
+	validateStructure(root, kind, fail);
+	const src = path.join(root, "src");
+	if (!fs.existsSync(src)) return errors;
+	const graph = new Map();
+	for (const absolute of walk(src)) {
+		const relative = toPosix(path.relative(root, absolute));
+		for (const specifier of extractImports(fs.readFileSync(absolute, "utf8"), relative)) {
+			const target = resolveInternal(relative, specifier);
+			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);
+		}
+	}
+	if (kind === "service") detectCycles(graph, fail);
+	return errors;
+}
+
+function parseCli(argv) {
+	const args = [...argv];
+	let kind;
+	let root = ".";
+	while (args.length) {
+		const value = args.shift();
+		if (value === "--kind") kind = args.shift();
+		else root = value;
+	}
+	return { kind, root };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	const { kind, root } = parseCli(process.argv.slice(2));
+	const errors = validateArchitecture(root, kind);
+	for (const error of errors) console.error(error);
+	if (errors.length) process.exit(1);
+	console.log(`Validated ${kind} architecture: ${path.resolve(root)}`);
+}

package/bin/tailframe.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { createRequire } from "node:module";
+import { runValidate } from "../src/validate.mjs";
+import { runGenerate, GenerateError } from "../src/generate.mjs";
+import { createProject } from "../src/new.mjs";
+
+const require = createRequire(import.meta.url);
+
+function usage() {
+	console.error("Usage: tailframe validate --kind service|ui [root]");
+	console.error("       tailframe new <name> [--path <parent>] [--auth none|firebase] [--ui] [--redis] [--worker]");
+	console.error("       tailframe generate <schematic> <args...> [--options]");
+	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>");
+	process.exit(2);
+}
+
+const args = process.argv.slice(2);
+const command = args.shift();
+
+if (command === "--version" || command === "-v") {
+	console.log(require("../package.json").version);
+	process.exit(0);
+}
+if (command === "new") {
+	try {
+		let name;
+		const rest = [];
+		for (let index = 0; index < args.length; index += 1) {
+			const value = args[index];
+			if (value === "--path" || value === "--auth") rest.push(value, args[++index]);
+			else if (value.startsWith("--")) rest.push(value);
+			else if (name === undefined) name = value;
+			else rest.push(value);
+		}
+		if (!rest.includes("--path")) rest.push("--path", ".");
+		const summary = createProject([...(name ? ["--name", name] : []), ...rest]);
+		console.log(JSON.stringify(summary, null, 2));
+		process.exit(0);
+	} catch (error) {
+		if (error instanceof GenerateError) {
+			console.error(error.message);
+			process.exit(1);
+		}
+		throw error;
+	}
+}
+if (command === "generate") {
+	try {
+		const { created, checklist } = runGenerate(".", args);
+		console.log("Created:");
+		for (const file of created) console.log(`  ${file}`);
+		console.log("Next steps:");
+		for (const step of checklist) console.log(`  - ${step}`);
+		process.exit(0);
+	} catch (error) {
+		if (error instanceof GenerateError) {
+			console.error(error.message);
+			process.exit(1);
+		}
+		throw error;
+	}
+}
+if (command !== "validate") usage();
+
+let kind;
+let root = ".";
+while (args.length) {
+	const value = args.shift();
+	if (value === "--kind") kind = args.shift();
+	else if (value.startsWith("-")) usage();
+	else root = value;
+}
+if (!["service", "ui"].includes(kind)) usage();
+
+const errors = runValidate(root, kind);
+for (const error of errors) console.error(error);
+if (errors.length) process.exit(1);
+console.log(`Validated ${kind} contract ${require("../package.json").version}: ${path.resolve(root)}`);

package/package.json

@@ -0,0 +1,21 @@
+{
+	"name": "@zaaxch/tailframe",
+	"version": "0.1.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": {
+		"tailframe": "bin/tailframe.mjs"
+	},
+	"files": [
+		"assets",
+		"bin",
+		"src"
+	],
+	"scripts": {
+		"test": "node test/run-tests.mjs"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"license": "UNLICENSED"
+}

package/src/architecture.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+
+
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".vue"]);
+
+export function toPosix(value) {
+	return value.split(path.sep).join("/");
+}
+
+function listEntries(target, kind) {
+	return fs.readdirSync(target, { withFileTypes: true })
+		.filter((entry) => kind === "directory" ? entry.isDirectory() : entry.isFile())
+		.map((entry) => entry.name)
+		.sort();
+}
+
+export function walk(target) {
+	const results = [];
+	for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+		if (["node_modules", "dist", ".git"].includes(entry.name)) continue;
+		const absolute = path.join(target, entry.name);
+		if (entry.isDirectory()) results.push(...walk(absolute));
+		else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) results.push(absolute);
+	}
+	return results;
+}
+
+function extractImports(source, relative) {
+	const code = relative.endsWith(".vue")
+		? [...source.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/gi)].map((match) => match[1]).join("\n")
+		: source;
+	const script = code.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+	const imports = [];
+	const staticPattern = /(?:^|[;\n])\s*(?:import|export)\s+(?:type\s+)?(?:[^"'`;]*?\s+from\s+)?["']([^"']+)["']/g;
+	const dynamicPattern = /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+	for (const pattern of [staticPattern, dynamicPattern]) {
+		for (const match of script.matchAll(pattern)) imports.push(match[1]);
+	}
+	return [...new Set(imports)];
+}
+
+function resolveInternal(relativeFile, specifier) {
+	if (specifier.startsWith("@/")) return path.posix.normalize(`src/${specifier.slice(2)}`);
+	if (!specifier.startsWith(".")) return undefined;
+	return path.posix.normalize(path.posix.join(path.posix.dirname(relativeFile), specifier));
+}
+
+export function isTestFile(relative) {
+	return relative.includes("/__tests__/") || /\.(?:test|spec)\.[^.]+$/.test(relative);
+}
+
+export function moduleParts(relative) {
+	const match = relative.match(/^src\/modules\/([^/]+)\/([^/]+)(?:\/(.*))?$/);
+	if (!match) return undefined;
+	return { module: match[1], layer: match[2], remainder: match[3] ?? "" };
+}
+
+function isNamedUseCase(relative, expectedModule) {
+	const target = moduleParts(relative);
+	return Boolean(
+		target &&
+		target.module === expectedModule &&
+		target.layer === "use-cases" &&
+		target.remainder &&
+		!target.remainder.includes("/") &&
+		!isTestFile(relative)
+	);
+}
+
+function validateStructure(root, kind, fail) {
+	const src = path.join(root, "src");
+	if (!fs.existsSync(src) || !fs.statSync(src).isDirectory()) {
+		fail("Missing architecture directory: src");
+		return;
+	}
+
+	const checkEntries = (relative, entryKind, allowed) => {
+		const target = path.join(root, relative);
+		if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+			fail(`Missing architecture directory: ${relative}`);
+			return;
+		}
+		for (const name of listEntries(target, entryKind)) {
+			if (!allowed.includes(name)) fail(`Unexpected architecture ${entryKind}: ${relative}/${name}`);
+		}
+	};
+
+	if (kind === "service") {
+		checkEntries("src", "directory", ["__tests__", "app", "core", "modules", "platform"]);
+		checkEntries("src", "file", ["server.ts", "worker.ts"]);
+		checkEntries("src/app", "directory", ["__tests__", "cli", "jobs", "mcp", "scheduled-tasks", "workers"]);
+		checkEntries("src/core", "directory", []);
+	} else {
+		checkEntries("src", "directory", ["app", "core", "modules", "platform"]);
+		checkEntries("src", "file", ["main.ts"]);
+		checkEntries("src/app", "directory", ["__tests__", "components", "stores", "views"]);
+		checkEntries("src/core", "directory", []);
+	}
+
+	const platform = path.join(root, "src/platform");
+	if (!fs.existsSync(platform) || !fs.statSync(platform).isDirectory()) fail("Missing architecture directory: src/platform");
+	const modules = path.join(root, "src/modules");
+	if (!fs.existsSync(modules) || !fs.statSync(modules).isDirectory()) {
+		fail("Missing architecture directory: src/modules");
+		return;
+	}
+	const allowedModuleDirectories = kind === "service"
+		? ["__tests__", "domain", "http", "persistence", "use-cases"]
+		: ["__tests__", "api", "components", "composables", "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");
+		checkEntries(`src/modules/${moduleName}`, "directory", allowedModuleDirectories);
+		checkEntries(`src/modules/${moduleName}`, "file", []);
+	}
+}
+
+function validateServiceImport(source, target, external, fail, graph) {
+	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}`);
+		} else {
+			const expectedAssembly = source === "src/server.ts" ? "src/app/server" : "src/app/workers/";
+			if (!target.startsWith(expectedAssembly)) fail(`${source} may import only its matching app assembly, not ${target}`);
+		}
+		return;
+	}
+	if (source.startsWith("src/core/")) {
+		if (external || !target.startsWith("src/core/")) fail(`${source} violates core purity by importing ${external ?? target}`);
+		return;
+	}
+	if (source.startsWith("src/app/") || source.startsWith("src/__tests__/")) return;
+	if (source.startsWith("src/platform/")) {
+		if (external) return;
+		if (target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
+		if (source.startsWith("src/platform/integrations/") && /^src\/modules\/[^/]+\/use-cases\/ports\//.test(target)) return;
+		fail(`${source} may import only core, platform, or a module-owned integration port, not ${target}`);
+		return;
+	}
+
+	const sourceModule = moduleParts(source);
+	if (!sourceModule) return;
+	const moduleTest = isTestFile(source) || sourceModule.layer === "__tests__";
+	if (external) {
+		if (!moduleTest && ["domain", "use-cases"].includes(sourceModule.layer)) {
+			fail(`${source} in ${sourceModule.layer} may not import framework or vendor package ${external}`);
+		}
+		return;
+	}
+	if (target.startsWith("src/core/")) return;
+	const targetModule = moduleParts(target);
+	if (target.startsWith("src/platform/")) {
+		if (["http", "persistence"].includes(sourceModule.layer) || moduleTest) return;
+		fail(`${source} cannot import platform code from ${sourceModule.layer}`);
+		return;
+	}
+	if (target.startsWith("src/app/") || target.startsWith("src/__tests__/")) {
+		if (moduleTest) return;
+		fail(`${source} cannot import application assembly or cross-boundary test support`);
+		return;
+	}
+	if (!targetModule) {
+		fail(`${source} imports unsupported internal path ${target}`);
+		return;
+	}
+	if (targetModule.module !== sourceModule.module) {
+		if ((sourceModule.layer === "use-cases" || moduleTest) && isNamedUseCase(target, targetModule.module)) {
+			if (!moduleTest) {
+				if (!graph.has(sourceModule.module)) graph.set(sourceModule.module, new Set());
+				graph.get(sourceModule.module).add(targetModule.module);
+			}
+			return;
+		}
+		fail(`${source} may import another module only through a named use-case file, not ${target}`);
+		return;
+	}
+
+	if (moduleTest) return;
+	const allowedLayers = {
+		domain: ["domain"],
+		"use-cases": ["domain", "use-cases"],
+		http: ["domain", "http", "use-cases"],
+		persistence: ["domain", "persistence", "use-cases"]
+	}[sourceModule.layer] ?? [];
+	if (!allowedLayers.includes(targetModule.layer)) {
+		fail(`${source} in ${sourceModule.layer} cannot import its module's ${targetModule.layer} layer`);
+	}
+}
+
+function validateUiImport(source, target, external, fail) {
+	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;
+	}
+	if (source.startsWith("src/core/")) {
+		if (external || !target.startsWith("src/core/")) fail(`${source} violates core purity by importing ${external ?? target}`);
+		return;
+	}
+	if (source.startsWith("src/app/")) return;
+	if (source.startsWith("src/platform/")) {
+		if (external || target.startsWith("src/core/") || target.startsWith("src/platform/")) return;
+		fail(`${source} may not import app or module code: ${target}`);
+		return;
+	}
+	const sourceModule = moduleParts(source);
+	if (!sourceModule || external) return;
+	if (target.startsWith("src/core/") || target.startsWith("src/platform/")) 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}`);
+}
+
+function detectCycles(graph, fail) {
+	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(" -> ")}`);
+			return;
+		}
+		if (visited.has(moduleName)) return;
+		visited.add(moduleName);
+		active.push(moduleName);
+		activeSet.add(moduleName);
+		for (const dependency of graph.get(moduleName) ?? []) visit(dependency);
+		active.pop();
+		activeSet.delete(moduleName);
+	};
+	for (const moduleName of graph.keys()) visit(moduleName);
+}
+
+export function validateArchitecture(rootArgument, kind) {
+	const root = path.resolve(rootArgument);
+	const errors = [];
+	const fail = (message) => errors.push(message);
+	if (!["service", "ui"].includes(kind)) return [`Architecture kind must be service or ui, received ${kind ?? "nothing"}`];
+	if (!fs.existsSync(root)) return [`Architecture root does not exist: ${root}`];
+	validateStructure(root, kind, fail);
+	const src = path.join(root, "src");
+	if (!fs.existsSync(src)) return errors;
+	const graph = new Map();
+	for (const absolute of walk(src)) {
+		const relative = toPosix(path.relative(root, absolute));
+		for (const specifier of extractImports(fs.readFileSync(absolute, "utf8"), relative)) {
+			const target = resolveInternal(relative, specifier);
+			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);
+		}
+	}
+	if (kind === "service") detectCycles(graph, fail);
+	return errors;
+}