@zaaxch/tailframe 2.2.0 → 4.0.0

package/bin/tailframe.mjs

@@ -1,30 +1,52 @@
 #!/usr/bin/env node
 import path from "node:path";
 import { createRequire } from "node:module";
-import { runValidate } from "../src/validate.mjs";
+import { APP_KINDS } from "../src/config.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("       tailframe generate <schematic> <args...> [--options]");
+	console.error("Usage: tailframe validate [root] [--app service|ui]");
+	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 --app service|ui <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 +55,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);
@@ -52,7 +74,15 @@ if (command === "new") {
 }
 if (command === "generate") {
 	try {
-		const { created, checklist } = runGenerate(".", args);
+		let selectedKind;
+		const rest = [];
+		while (args.length) {
+			const value = args.shift();
+			if (value === "--app") selectedKind = args.shift();
+			else rest.push(value);
+		}
+		if (!APP_KINDS.has(selectedKind)) usage();
+		const { created, checklist } = runGenerate(".", rest, selectedKind);
 		console.log("Created:");
 		for (const file of created) console.log(`  ${file}`);
 		console.log("Next steps:");
@@ -68,17 +98,17 @@ if (command === "generate") {
 }
 if (command !== "validate") usage();
 
-let kind;
 let root = ".";
+let selectedKind;
 while (args.length) {
 	const value = args.shift();
-	if (value === "--kind") kind = args.shift();
+	if (value === "--app") selectedKind = args.shift();
 	else if (value.startsWith("-")) usage();
 	else root = value;
 }
-if (!["service", "ui"].includes(kind)) usage();
+if (selectedKind && !APP_KINDS.has(selectedKind)) usage();
 
-const errors = runValidate(root, kind);
+const errors = runConfiguredValidate(root, contractVersion, selectedKind);
 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}${selectedKind ? ` for ${selectedKind}` : ""}: ${path.resolve(root)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "2.2.0",
+	"version": "4.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) {
@@ -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 = ["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/")) {
@@ -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,93 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const CONFIG_FILE = "tailframe.json";
+export const CONFIG_SCHEMA_VERSION = 2;
+export const PRODUCT_KIND = "product";
+export const APP_KINDS = new Set(["service", "ui"]);
+export const APP_PATHS = Object.freeze({
+	service: "apps/service",
+	ui: "apps/ui"
+});
+export const PROFILES = new Set([
+	"firebase",
+	"mongo",
+	"postgres",
+	"redis",
+	"worker",
+	"rate-limit",
+	"ui-host",
+	"notifications"
+]);
+
+function validateProfiles(app, errors) {
+	if (!Array.isArray(app.profiles) || app.profiles.some((profile) => !PROFILES.has(profile))) {
+		errors.push(`${CONFIG_FILE} app ${app.kind ?? "unknown"} profiles contain an unsupported value`);
+		return;
+	}
+	if (new Set(app.profiles).size !== app.profiles.length) {
+		errors.push(`${CONFIG_FILE} app ${app.kind} profiles must not contain duplicates`);
+	}
+	const profiles = new Set(app.profiles);
+	if (app.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`);
+		}
+	}
+}
+
+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 (config.kind !== PRODUCT_KIND) errors.push(`${CONFIG_FILE} kind must be product`);
+	if (typeof config.contractVersion !== "string" || !/^\d+\.\d+\.\d+$/.test(config.contractVersion)) {
+		errors.push(`${CONFIG_FILE} contractVersion must be an exact semantic version`);
+	}
+	if (!Array.isArray(config.apps) || config.apps.length === 0) {
+		errors.push(`${CONFIG_FILE} apps must be a non-empty array`);
+	} else {
+		const seen = new Set();
+		for (const app of config.apps) {
+			if (!app || !APP_KINDS.has(app.kind)) {
+				errors.push(`${CONFIG_FILE} app kind must be service or ui`);
+				continue;
+			}
+			if (seen.has(app.kind)) errors.push(`${CONFIG_FILE} contains duplicate ${app.kind} apps`);
+			seen.add(app.kind);
+			if (app.path !== APP_PATHS[app.kind]) {
+				errors.push(`${CONFIG_FILE} ${app.kind} path must be ${APP_PATHS[app.kind]}`);
+			}
+			validateProfiles(app, errors);
+		}
+		if (!seen.has("service")) errors.push(`${CONFIG_FILE} must declare exactly one service app`);
+	}
+	return { root, config, errors };
+}
+
+export function appConfig(productConfig, kind) {
+	return productConfig.apps.find((app) => app.kind === kind);
+}
+
+export function appRoot(productRoot, app) {
+	return path.join(productRoot, app.path);
+}
+
+export function configSource({ apps, contractVersion }) {
+	return `${JSON.stringify({ schemaVersion: CONFIG_SCHEMA_VERSION, contractVersion, kind: PRODUCT_KIND, apps }, null, "\t")}\n`;
+}

package/src/conventions.mjs

@@ -115,7 +115,7 @@ export function validateConventions(rootArgument, kind) {
 	if (kind === "ui") {
 		validateRouteNames(root, src, flag);
 		validateCanonicalShell(root, flag);
-	} else {
+	} else if (kind === "service") {
 		validateServiceComposition(root, flag);
 	}
 	return violations;
@@ -129,6 +129,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 +149,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]);
@@ -202,7 +213,8 @@ function normalizeGeneratedSource(source) {
 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()) {
+	const expectedAuth = 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 +291,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/exceptions.mjs

@@ -14,19 +14,29 @@ function parseExceptionSection(markdown) {
 	return covered;
 }
 
+function normalize(relative) {
+	return relative.split(path.sep).join("/");
+}
+
 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) || ".");
+
+	let ancestor = path.dirname(root);
+	while (ancestor !== path.dirname(ancestor)) {
+		const guidance = path.join(ancestor, "AGENTS.md");
+		if (fs.existsSync(guidance)) {
+			const appPath = normalize(path.relative(ancestor, root));
+			for (const entry of parseExceptionSection(fs.readFileSync(guidance, "utf8"))) {
+				if (entry === appPath || entry.startsWith(`${appPath}/`)) {
+					covered.push(entry.slice(appPath.length + 1) || ".");
+				}
 			}
 		}
+		if (fs.existsSync(path.join(ancestor, "tailframe.json"))) break;
+		ancestor = path.dirname(ancestor);
 	}
 	return covered;
 }

package/src/generate.mjs

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
+import { appRoot, loadConfig } from "./config.mjs";
 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 +471,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) {
@@ -527,7 +529,7 @@ const uiSchematics = {
 	store(root, [moduleName, name]) {
 		requireUiModuleName(root, moduleName);
 		if (!name || !KEBAB.test(name)) fail(`Store name must be lowercase kebab-case, received "${name ?? ""}"`);
-		return [plan(uiArtifacts(moduleName, { store: name })), [`Keep product state in this owning module; expose a deliberate facade with tailframe generate public ${moduleName} use${pascal(name)}Store only when another module needs it`]];
+		return [plan(uiArtifacts(moduleName, { store: name })), [`Keep product state in this owning module; when another module needs the capability, design the smallest stable public entry instead of re-exporting the store by default`]];
 	},
 	composable(root, [moduleName, name]) {
 		requireUiModuleName(root, moduleName);
@@ -570,8 +572,13 @@ const uiSchematics = {
 	}
 };
 
-export function runGenerate(rootArgument, argv) {
-	const root = path.resolve(rootArgument);
+export function runGenerate(rootArgument, argv, selectedKind) {
+	const loaded = loadConfig(rootArgument);
+	if (loaded.errors.length) fail(loaded.errors.join("\n"));
+	if (!selectedKind) fail("tailframe generate requires --app service or ui");
+	const app = loaded.config.apps.find((candidate) => candidate.kind === selectedKind);
+	if (!app) fail(`tailframe.json does not declare a ${selectedKind} app`);
+	const root = appRoot(loaded.root, app);
 	const positionals = [];
 	const options = new Map();
 	const flags = new Set();
@@ -585,11 +592,14 @@ export function runGenerate(rootArgument, argv) {
 	options.has = (key) => flags.has(key) || Map.prototype.has.call(options, key);
 	const schematic = positionals.shift();
 	const kind = detectKind(root);
+	if (kind !== selectedKind) {
+		fail(`Configured ${selectedKind} app at ${app.path} has ${kind} entry-point shape`);
+	}
 	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"] };
+	return { kind, created: created.map((relative) => path.join(app.path, relative)), checklist: [...checklist, "Run pnpm validate:architecture, then focused type checks and tests"] };
 }