@zaaxch/tailframe 2.2.0 → 3.0.0

package/bin/tailframe.mjs

@@ -1,30 +1,51 @@
 #!/usr/bin/env node
 import path from "node:path";
 import { createRequire } from "node:module";
-import { runValidate } from "../src/validate.mjs";
+import { runConfiguredValidate } from "../src/validate.mjs";
 import { runGenerate, GenerateError } from "../src/generate.mjs";
 import { createProject } from "../src/new.mjs";
+import { runSync } from "../src/sync.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("Usage: tailframe validate [root]");
+	console.error("       tailframe sync --check|--write [root]");
+	console.error("       tailframe new <name> [--path <parent>] [--db mongo|postgres] [--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>|--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");
+	console.error("    public <module> <name>, public-component <module> <Name>, app-store auth|notification, app-store theme --storage-key <key>, app-component ThemeToggle");
 	process.exit(2);
 }
 
 const args = process.argv.slice(2);
 const command = args.shift();
+const contractVersion = require("../package.json").version;
 
 if (command === "--version" || command === "-v") {
-	console.log(require("../package.json").version);
+	console.log(contractVersion);
+	process.exit(0);
+}
+if (command === "sync") {
+	let mode;
+	let root = ".";
+	while (args.length) {
+		const value = args.shift();
+		if (value === "--check") mode = "check";
+		else if (value === "--write") mode = "write";
+		else if (value.startsWith("-")) usage();
+		else root = value;
+	}
+	if (!mode) usage();
+	const result = runSync(root, mode, contractVersion);
+	for (const error of result.errors) console.error(error);
+	for (const file of result.changed) console.log(`Updated ${file}`);
+	if (result.errors.length) process.exit(1);
+	if (mode === "check") console.log(`Canonical Tailframe sources match ${contractVersion}: ${path.resolve(root)}`);
 	process.exit(0);
 }
 if (command === "new") {
@@ -33,7 +54,7 @@ if (command === "new") {
 		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]);
+			if (value === "--path" || value === "--auth" || value === "--db") rest.push(value, args[++index]);
 			else if (value.startsWith("--")) rest.push(value);
 			else if (name === undefined) name = value;
 			else rest.push(value);
@@ -68,17 +89,14 @@ if (command === "generate") {
 }
 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();
+	if (value.startsWith("-")) usage();
 	else root = value;
 }
-if (!["service", "ui"].includes(kind)) usage();
 
-const errors = runValidate(root, kind);
+const errors = runConfiguredValidate(root, contractVersion);
 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)}`);
+console.log(`Validated Tailframe contract ${contractVersion}: ${path.resolve(root)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "2.2.0",
+	"version": "3.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,9 +4,13 @@ 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_STORE_FILES = ["auth.store.ts", "notification.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_STORE_TARGETS = new Set([
+	"src/app/stores/auth.store",
+	"src/app/stores/notification.store",
+	"src/app/stores/theme.store"
+]);
 const APP_PUBLIC_TARGETS = new Set(["src/app/public/ThemeToggle"]);
 
 function withoutSourceExtension(target) {
@@ -118,7 +122,7 @@ function validateStructure(root, kind, fail) {
 		checkEntries("src/core", "directory", []);
 	} else {
 		checkEntries("src", "directory", ["app", "core", "modules", "platform"]);
-		checkEntries("src", "file", ["main.ts"]);
+		checkEntries("src", "file", kind === "extension" ? ["background.ts", "content.ts"] : ["main.ts"]);
 		checkEntries("src/app", "directory", ["__tests__", "components", "public", "stores", "views"]);
 		checkEntries("src/core", "directory", []);
 		checkOptionalEntries("src/app/public", "directory", []);
@@ -138,8 +142,8 @@ function validateStructure(root, kind, fail) {
 		? ["__tests__", "domain", "http", "persistence", "use-cases"]
 		: ["__tests__", "api", "components", "composables", "public", "routes", "stores", "types", "views"];
 	for (const moduleName of listEntries(modules, "directory")) {
-		if (kind === "ui" && ["auth", "theme"].includes(moduleName)) {
-			fail(`Application ${moduleName === "auth" ? "authentication" : "theme"} must live under src/app, not src/modules/${moduleName}`);
+		if (kind !== "service" && ["auth", "notification", "theme"].includes(moduleName)) {
+			fail(`Application ${moduleName} capability must live under src/app, not src/modules/${moduleName}`);
 		}
 		checkEntries(`src/modules/${moduleName}`, "directory", allowedModuleDirectories);
 		checkEntries(`src/modules/${moduleName}`, "file", []);
@@ -223,9 +227,10 @@ function validateServiceImport(source, target, external, fail, graph) {
 	}
 }
 
-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}`);
+function validateUiImport(source, target, external, fail, graph, kind) {
+	const bootstraps = kind === "extension" ? ["src/background.ts", "src/content.ts"] : ["src/main.ts"];
+	if (bootstraps.includes(source)) {
+		if (external || !target.startsWith("src/app/")) fail(`${source} may import only app bootstrap code, not ${external ?? target}`);
 		return;
 	}
 	if (source.startsWith("src/core/")) {
@@ -294,7 +299,7 @@ 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 (!["service", "ui", "extension"].includes(kind)) return [`Architecture kind must be service, ui, or extension, received ${kind ?? "nothing"}`];
 	if (!fs.existsSync(root)) return [`Architecture root does not exist: ${root}`];
 	validateStructure(root, kind, fail);
 	const src = path.join(root, "src");
@@ -313,7 +318,7 @@ export function validateArchitecture(rootArgument, kind) {
 				continue;
 			}
 			if (kind === "service") validateServiceImport(relative, target, target ? undefined : specifier, fail, graph);
-			else validateUiImport(relative, target, target ? undefined : specifier, fail, graph);
+			else validateUiImport(relative, target, target ? undefined : specifier, fail, graph, kind);
 		}
 	}
 	detectCycles(graph, fail, kind === "service" ? "Cross-module use-case dependency cycle" : "Cross-module UI public dependency cycle");

package/src/config.mjs

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const CONFIG_FILE = "tailframe.json";
+export const CONFIG_SCHEMA_VERSION = 1;
+export const KINDS = new Set(["service", "ui", "extension", "flutter"]);
+export const PROFILES = new Set([
+	"firebase",
+	"mongo",
+	"postgres",
+	"redis",
+	"worker",
+	"rate-limit",
+	"ui-host",
+	"notifications"
+]);
+
+export function loadConfig(rootArgument) {
+	const root = path.resolve(rootArgument);
+	const file = path.join(root, CONFIG_FILE);
+	if (!fs.existsSync(file)) return { root, errors: [`Missing ${CONFIG_FILE}`] };
+	let config;
+	try {
+		config = JSON.parse(fs.readFileSync(file, "utf8"));
+	} catch (error) {
+		return { root, errors: [`Invalid ${CONFIG_FILE}: ${error instanceof Error ? error.message : error}`] };
+	}
+	const errors = [];
+	if (config.schemaVersion !== CONFIG_SCHEMA_VERSION) {
+		errors.push(`${CONFIG_FILE} schemaVersion must be ${CONFIG_SCHEMA_VERSION}`);
+	}
+	if (typeof config.contractVersion !== "string" || !/^\d+\.\d+\.\d+$/.test(config.contractVersion)) {
+		errors.push(`${CONFIG_FILE} contractVersion must be an exact semantic version`);
+	}
+	if (!KINDS.has(config.kind)) errors.push(`${CONFIG_FILE} kind must be service, ui, extension, or flutter`);
+	if (!Array.isArray(config.profiles) || config.profiles.some((profile) => !PROFILES.has(profile))) {
+		errors.push(`${CONFIG_FILE} profiles contain an unsupported value`);
+	} else if (new Set(config.profiles).size !== config.profiles.length) {
+		errors.push(`${CONFIG_FILE} profiles must not contain duplicates`);
+	}
+	const profiles = new Set(config.profiles ?? []);
+	if (config.kind === "service") {
+		if (profiles.has("mongo") === profiles.has("postgres")) {
+			errors.push("Service profiles must select exactly one of mongo or postgres");
+		}
+		if (profiles.has("worker") && !profiles.has("redis")) errors.push("The worker profile requires redis");
+		if (profiles.has("rate-limit") && !profiles.has("redis")) errors.push("The rate-limit profile requires redis");
+		if (profiles.has("notifications")) errors.push("The notifications profile is client-only");
+	} else {
+		for (const profile of ["mongo", "postgres", "redis", "worker", "rate-limit", "ui-host"]) {
+			if (profiles.has(profile)) errors.push(`${profile} is a service-only profile`);
+		}
+	}
+	return { root, config, errors };
+}
+
+export function configSource({ kind, profiles, contractVersion }) {
+	return `${JSON.stringify({ schemaVersion: CONFIG_SCHEMA_VERSION, contractVersion, kind, profiles }, null, "\t")}\n`;
+}

package/src/conventions.mjs

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { toPosix, walk } from "./architecture.mjs";
 import { authAppStoreSource, themeAppStoreSource, themeToggleSource } from "./generate.mjs";
+import { extensionAuthStoreSource } from "./ui-templates.mjs";
 
 const PASCAL = /^[A-Z][A-Za-z0-9]*$/;
 const CAMEL = /^[a-z][A-Za-z0-9]*$/;
@@ -114,8 +115,10 @@ export function validateConventions(rootArgument, kind) {
 	}
 	if (kind === "ui") {
 		validateRouteNames(root, src, flag);
-		validateCanonicalShell(root, flag);
-	} else {
+		validateCanonicalShell(root, flag, kind);
+	} else if (kind === "extension") {
+		validateCanonicalShell(root, flag, kind);
+	} else if (kind === "service") {
 		validateServiceComposition(root, flag);
 	}
 	return violations;
@@ -129,6 +132,12 @@ function validateServiceSource(relative, moduleName, layer, remainder, name, sou
 		} 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 (/^\s*(?:async\s+)?execute\s*\(/m.test(source) && !/^\s*(?:async\s+)?execute\s*\(\s*[_a-zA-Z][A-Za-z0-9]*\s*:\s*RequestContext\s*,\s*[_a-zA-Z][A-Za-z0-9]*\s*:/m.test(source)) {
+			flag("S1", relative, `${relative} execute must receive RequestContext first and an explicit input second; internal policies use a descriptive method instead`);
+		}
+	}
+	if (["domain", "use-cases"].includes(layer) && /\b_id\b/.test(source)) {
+		flag("S5", relative, `${relative} exposes MongoDB _id outside persistence; domain and use-case code use id`);
 	}
 
 	if (layer !== "http") return;
@@ -143,6 +152,11 @@ function validateServiceSource(relative, moduleName, layer, remainder, name, sou
 		if (postCount > rpcHandlerCount) {
 			flag("S8", relative, `${relative} must translate every RPC POST through rpcHandler; found ${postCount} POST routes and ${rpcHandlerCount} rpcHandler calls`);
 		}
+		for (const match of source.matchAll(/\brouter\.post\s*\(\s*["']\/([^"']+)["']/g)) {
+			if (!match[1].startsWith(`${moduleName}.`)) {
+				flag("S8", relative, `${relative} exposes ${match[1]}; RPC operations use the owning module namespace ${moduleName}.*`);
+			}
+		}
 	}
 	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]);
@@ -199,10 +213,11 @@ function normalizeGeneratedSource(source) {
 	return source.replace(/\r\n/g, "\n");
 }
 
-function validateCanonicalShell(root, flag) {
+function validateCanonicalShell(root, flag, kind = "ui") {
 	const authRelative = "src/app/stores/auth.store.ts";
 	const authFile = path.join(root, authRelative);
-	if (fs.existsSync(authFile) && normalizeGeneratedSource(fs.readFileSync(authFile, "utf8")) !== authAppStoreSource()) {
+	const expectedAuth = kind === "extension" ? extensionAuthStoreSource : authAppStoreSource();
+	if (fs.existsSync(authFile) && normalizeGeneratedSource(fs.readFileSync(authFile, "utf8")) !== expectedAuth) {
 		flag("U7", authRelative, `${authRelative} differs from the canonical Tailframe auth store; regenerate it instead of maintaining a project-local variant`);
 	}
 
@@ -279,7 +294,9 @@ function validateShared(relative, name, flag) {
 		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`);
+		if (!new Set(["auth.store", "notification.store", "theme.store"]).has(name.stem)) {
+			flag("U3", relative, `${relative} is not a canonical app store; app/stores is closed to auth.store.ts, notification.store.ts, and theme.store.ts`);
+		}
 		return;
 	}
 	if (!PASCAL.test(name.stem) && !CAMEL.test(name.stem)) {

package/src/flutter.mjs

@@ -0,0 +1,111 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const ALLOWED_ROOTS = new Set(["app", "core", "modules", "platform"]);
+const ALLOWED_APP_DIRECTORIES = new Set(["components", "public", "state", "theme", "views"]);
+const ALLOWED_MODULE_DIRECTORIES = new Set(["api", "components", "public", "state", "types", "views"]);
+const IMPORT_PATTERN = /(?:import|export)\s+["']([^"']+)["']/g;
+
+const toPosix = (value) => value.split(path.sep).join("/");
+
+function walk(target) {
+	const results = [];
+	for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+		if ([".dart_tool", "build", ".git"].includes(entry.name)) continue;
+		const absolute = path.join(target, entry.name);
+		if (entry.isDirectory()) results.push(...walk(absolute));
+		else if (entry.name.endsWith(".dart")) results.push(absolute);
+	}
+	return results;
+}
+
+function resolveImport(source, specifier, packageName) {
+	if (specifier.startsWith(`package:${packageName}/`)) return specifier.slice(`package:${packageName}/`.length);
+	if (specifier.startsWith(".")) return path.posix.normalize(path.posix.join(path.posix.dirname(source), specifier));
+	return undefined;
+}
+
+export function readFlutterPackageName(rootArgument) {
+	try {
+		return fs.readFileSync(path.join(path.resolve(rootArgument), "pubspec.yaml"), "utf8").match(/^name:\s*([a-zA-Z0-9_]+)/m)?.[1];
+	} catch {
+		return undefined;
+	}
+}
+
+export function validateFlutter(rootArgument) {
+	const root = path.resolve(rootArgument);
+	const lib = path.join(root, "lib");
+	const errors = [];
+	if (!fs.existsSync(lib)) return ["Missing Flutter architecture directory: lib"];
+	const packageName = readFlutterPackageName(root);
+	if (!packageName) errors.push("pubspec.yaml must declare a package name");
+	for (const entry of fs.readdirSync(lib, { withFileTypes: true })) {
+		if (entry.isDirectory() && !ALLOWED_ROOTS.has(entry.name)) errors.push(`lib/${entry.name} is not a recognized architecture root`);
+		if (entry.isFile() && entry.name !== "main.dart") errors.push(`lib/${entry.name} is not the root bootstrap lib/main.dart`);
+	}
+	const files = walk(lib);
+	const relativeFiles = new Set(files.map((file) => toPosix(path.relative(lib, file))));
+	const graph = new Map();
+	for (const relative of relativeFiles) {
+		const parts = relative.split("/");
+		if (relative === "main.dart") {
+			// Checked after imports resolve below.
+		} else if (!ALLOWED_ROOTS.has(parts[0])) {
+			errors.push(`lib/${relative} is outside an architecture root`);
+		}
+		if (parts[0] === "core" && parts.length !== 2) errors.push(`lib/${relative} violates the flat core contract`);
+		if (parts[0] === "app" && parts.length > 2 && !ALLOWED_APP_DIRECTORIES.has(parts[1])) {
+			errors.push(`lib/${relative} uses an unsupported app directory`);
+		}
+		if (parts[0] === "modules") {
+			if (parts.length < 4 || !ALLOWED_MODULE_DIRECTORIES.has(parts[2])) errors.push(`lib/${relative} is not in a canonical module layer`);
+			if (parts[2] === "public" && (parts.length !== 4 || parts.at(-1) === "index.dart")) errors.push(`lib/${relative} is not a named direct module public entry`);
+		}
+		const source = fs.readFileSync(path.join(lib, relative), "utf8");
+		for (const match of source.matchAll(IMPORT_PATTERN)) {
+			const specifier = match[1];
+			const target = packageName ? resolveImport(relative, specifier, packageName) : undefined;
+			if (!target) {
+				if (parts[0] === "core" && specifier.startsWith("package:")) {
+					errors.push(`lib/${relative} violates core purity by importing ${specifier}`);
+				}
+				continue;
+			}
+			if (!relativeFiles.has(target)) {
+				errors.push(`lib/${relative} references missing lib/${target}`);
+				continue;
+			}
+			if (relative === "main.dart" && !target.startsWith("app/")) errors.push(`lib/main.dart may import only application bootstrap code, not lib/${target}`);
+			if (parts[0] === "core" && !target.startsWith("core/")) errors.push(`lib/${relative} crosses outward from core to lib/${target}`);
+			if (parts[0] === "platform" && (target.startsWith("app/") || target.startsWith("modules/"))) errors.push(`lib/${relative} crosses from platform to lib/${target}`);
+			if (parts[0] === "app" && target.startsWith("modules/")) {
+				const targetParts = target.split("/");
+				if (targetParts[2] !== "public" || targetParts.length !== 4) errors.push(`lib/${relative} imports private module file lib/${target}`);
+			}
+			if (parts[0] !== "modules") continue;
+			if (target.startsWith("app/") && !target.startsWith("app/public/")) errors.push(`lib/${relative} imports private app file lib/${target}`);
+			if (!target.startsWith("modules/")) continue;
+			const targetParts = target.split("/");
+			if (targetParts[1] === parts[1]) continue;
+			if (targetParts[2] !== "public" || targetParts.length !== 4) errors.push(`lib/${relative} imports private sibling file lib/${target}`);
+			else {
+				if (!graph.has(parts[1])) graph.set(parts[1], new Set());
+				graph.get(parts[1]).add(targetParts[1]);
+			}
+		}
+	}
+	const visiting = new Set();
+	const visited = new Set();
+	const visit = (module) => {
+		if (visiting.has(module)) return true;
+		if (visited.has(module)) return false;
+		visiting.add(module);
+		for (const dependency of graph.get(module) ?? []) if (visit(dependency)) return true;
+		visiting.delete(module);
+		visited.add(module);
+		return false;
+	};
+	for (const module of graph.keys()) if (visit(module)) errors.push(`Flutter module dependency graph contains a cycle involving ${module}`);
+	return [...new Set(errors)];
+}

package/src/generate.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { loadExceptions, isExcepted } from "./exceptions.mjs";
 import { serviceHttpFiles, serviceOperationName } from "./service-templates.mjs";
-import { moduleApiSource } from "./ui-templates.mjs";
+import { moduleApiSource, notificationStoreSource } from "./ui-templates.mjs";
 
 const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const PASCAL = /^[A-Z][A-Za-z0-9]*$/;
@@ -470,7 +470,8 @@ function appStoreFiles(name, options) {
 		return { "src/app/stores/theme.store.ts": themeAppStoreSource(storageKey) };
 	}
 	if (name === "auth") return { "src/app/stores/auth.store.ts": authAppStoreSource() };
-	fail(`App store must be one of auth or theme, received "${name ?? ""}"`);
+	if (name === "notification") return { "src/app/stores/notification.store.ts": notificationStoreSource };
+	fail(`App store must be one of auth, notification, or theme, received "${name ?? ""}"`);
 }
 
 function appPublicComponentFiles(name) {