@zaaxch/tailframe 3.0.0 → 4.0.0

package/bin/tailframe.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import path from "node:path";
 import { createRequire } from "node:module";
+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";
@@ -9,10 +10,10 @@ import { runSync } from "../src/sync.mjs";
 const require = createRequire(import.meta.url);
 
 function usage() {
-	console.error("Usage: tailframe validate [root]");
+	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 <schematic> <args...> [--options]");
+	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>");
@@ -73,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:");
@@ -90,13 +99,16 @@ if (command === "generate") {
 if (command !== "validate") usage();
 
 let root = ".";
+let selectedKind;
 while (args.length) {
 	const value = args.shift();
-	if (value.startsWith("-")) usage();
+	if (value === "--app") selectedKind = args.shift();
+	else if (value.startsWith("-")) usage();
 	else root = value;
 }
+if (selectedKind && !APP_KINDS.has(selectedKind)) usage();
 
-const errors = runConfiguredValidate(root, contractVersion);
+const errors = runConfiguredValidate(root, contractVersion, selectedKind);
 for (const error of errors) console.error(error);
 if (errors.length) process.exit(1);
-console.log(`Validated Tailframe contract ${contractVersion}: ${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": "3.0.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

@@ -122,7 +122,7 @@ function validateStructure(root, kind, fail) {
 		checkEntries("src/core", "directory", []);
 	} else {
 		checkEntries("src", "directory", ["app", "core", "modules", "platform"]);
-		checkEntries("src", "file", kind === "extension" ? ["background.ts", "content.ts"] : ["main.ts"]);
+		checkEntries("src", "file", ["main.ts"]);
 		checkEntries("src/app", "directory", ["__tests__", "components", "public", "stores", "views"]);
 		checkEntries("src/core", "directory", []);
 		checkOptionalEntries("src/app/public", "directory", []);
@@ -228,7 +228,7 @@ function validateServiceImport(source, target, external, fail, graph) {
 }
 
 function validateUiImport(source, target, external, fail, graph, kind) {
-	const bootstraps = kind === "extension" ? ["src/background.ts", "src/content.ts"] : ["src/main.ts"];
+	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;
@@ -299,7 +299,7 @@ export function validateArchitecture(rootArgument, kind) {
 	const root = path.resolve(rootArgument);
 	const errors = [];
 	const fail = (message) => errors.push(message);
-	if (!["service", "ui", "extension"].includes(kind)) return [`Architecture kind must be service, ui, or extension, received ${kind ?? "nothing"}`];
+	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");

package/src/config.mjs

@@ -2,8 +2,13 @@ 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 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",
@@ -15,6 +20,29 @@ export const PROFILES = new Set([
 	"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);
@@ -26,34 +54,40 @@ export function loadConfig(rootArgument) {
 		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.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 (!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");
+	if (!Array.isArray(config.apps) || config.apps.length === 0) {
+		errors.push(`${CONFIG_FILE} apps must be a non-empty array`);
 	} 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`);
+		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 configSource({ kind, profiles, contractVersion }) {
-	return `${JSON.stringify({ schemaVersion: CONFIG_SCHEMA_VERSION, contractVersion, kind, profiles }, null, "\t")}\n`;
+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

@@ -2,7 +2,6 @@ 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]*$/;
@@ -115,9 +114,7 @@ export function validateConventions(rootArgument, kind) {
 	}
 	if (kind === "ui") {
 		validateRouteNames(root, src, flag);
-		validateCanonicalShell(root, flag, kind);
-	} else if (kind === "extension") {
-		validateCanonicalShell(root, flag, kind);
+		validateCanonicalShell(root, flag);
 	} else if (kind === "service") {
 		validateServiceComposition(root, flag);
 	}
@@ -213,10 +210,10 @@ function normalizeGeneratedSource(source) {
 	return source.replace(/\r\n/g, "\n");
 }
 
-function validateCanonicalShell(root, flag, kind = "ui") {
+function validateCanonicalShell(root, flag) {
 	const authRelative = "src/app/stores/auth.store.ts";
 	const authFile = path.join(root, authRelative);
-	const expectedAuth = kind === "extension" ? extensionAuthStoreSource : 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`);
 	}

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,5 +1,6 @@
 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, notificationStoreSource } from "./ui-templates.mjs";
@@ -528,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);
@@ -571,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();
@@ -586,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"] };
 }