@zaaxch/tailframe 4.0.8 → 4.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "4.0.8",
+	"version": "4.0.10",
 	"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/generate.mjs

@@ -404,35 +404,14 @@ export function themeToggleSource() {
 		:title="\`Switch to \${themeStore.isDark ? 'light' : 'dark'} mode\`"
 		@click="themeStore.toggleTheme"
 	>
-		<svg
-			v-if="themeStore.isDark"
-			aria-hidden="true"
-			class="size-5"
-			viewBox="0 0 24 24"
-			fill="none"
-			stroke="currentColor"
-			stroke-width="1.8"
-		>
-			<circle cx="12" cy="12" r="4" />
-			<path
-				d="M12 2v2m0 16v2M4.93 4.93l1.42 1.42m11.3 11.3 1.42 1.42M2 12h2m16 0h2M4.93 19.07l1.42-1.42m11.3-11.3 1.42-1.42"
-			/>
-		</svg>
-		<svg
-			v-else
-			aria-hidden="true"
-			class="size-5"
-			viewBox="0 0 24 24"
-			fill="none"
-			stroke="currentColor"
-			stroke-width="1.8"
-		>
-			<path d="M20.5 15.2A8.5 8.5 0 0 1 8.8 3.5a8.5 8.5 0 1 0 11.7 11.7Z" />
-		</svg>
+		<FontAwesomeIcon v-if="themeStore.isDark" :icon="faSun" aria-hidden="true" class="size-5" />
+		<FontAwesomeIcon v-else :icon="faMoon" aria-hidden="true" class="size-5" />
 	</button>
 </template>
 
 <script setup lang="ts">
+import { faMoon, faSun } from "@fortawesome/free-solid-svg-icons";
+import { FontAwesomeIcon } from "@fortawesome/vue-fontawesome";
 import { useThemeStore } from "@/app/stores/theme.store";
 
 const themeStore = useThemeStore();

package/src/new.mjs

@@ -202,7 +202,7 @@ Use this workflow for any new domain capability or operation. Add only the layer
 2. Read the root and every applicable child \`AGENTS.md\`.
 3. Inspect the nearest working module and tests.
 4. Create architecture files only with the tailframe CLI: \`tailframe generate --app <service|ui>\` creates canonical service and UI architecture files. Hand-creating architecture files or editing generated shell-catalog implementations is a conformance violation; inspect the generated diff and complete only the behavior-specific checklist.
-5. Colocate product capability behavior under \`src/modules/<module>\` in both the service and UI. Never substitute \`features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories. UI \`app/stores\` is closed to generated \`auth.store.ts\`, \`notification.store.ts\`, and \`theme.store.ts\`; \`app/public\` is closed to generated \`ThemeToggle.vue\`. Never create \`src/modules/theme\`, \`src/modules/auth\`, or \`src/modules/notification\`. Product records, current-user domain records, selections, filters, and workflows stay in their owning module; when the service exposes a user capability, its current-user record belongs to a UI \`user\` module. Start backend modules with \`use-cases/\`, \`http/\`, and tests; add \`domain/\` or \`persistence/\` only when required. Add only the UI module directories earned by the capability.
+5. Colocate product capability behavior under \`src/modules/<module>\` in both the service and UI. Never substitute \`features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories. UI \`app/stores\` is closed to generated \`auth.store.ts\`, \`notification.store.ts\`, and \`theme.store.ts\`; \`app/public\` is closed to generated \`ThemeToggle.vue\`. Never create \`src/modules/theme\`, \`src/modules/auth\`, or \`src/modules/notification\`. Product records, current-user domain records, selections, filters, and workflows stay in their owning module; when the service exposes a user capability, its current-user record belongs to a UI \`user\` module. Start backend modules with \`use-cases/\`, \`http/\`, and tests; add \`domain/\` or \`persistence/\` only when required. Add only the UI module directories earned by the capability. Font Awesome's Vue component and free solid icon set are the standard icon system for shell and product UI.
 6. Define use cases as \`execute(context, input)\`. Keep trusted \`RequestContext\` separate from client input.
 7. Put ownership, RBAC, entitlements, and domain policies in use-case or domain code, not client bodies or route metadata.
 8. Define repository contracts in the owning module and implement them in persistence adapters.
@@ -595,7 +595,7 @@ Run \`pnpm validate:architecture\` and \`pnpm format:check\` after changing file
 `);
 
 if (options.ui) {
-const uiDeps = { "@tailwindcss/vite": "^4.1.18", "@vueuse/core": "^14.3.0", axios: "^1.9.0", pinia: "^3.0.1", primevue: "^4.2.5", vue: "^3.5.13", "vue-router": "^4.5.0", ...(options.auth === "firebase" ? { firebase: "^11.0.0" } : {}) };
+const uiDeps = { "@fortawesome/fontawesome-svg-core": "^7.3.1", "@fortawesome/free-solid-svg-icons": "^7.3.1", "@fortawesome/vue-fontawesome": "^3.3.3", "@tailwindcss/vite": "^4.1.18", "@vueuse/core": "^14.3.0", axios: "^1.9.0", pinia: "^3.0.1", primevue: "^4.2.5", vue: "^3.5.13", "vue-router": "^4.5.0", ...(options.auth === "firebase" ? { firebase: "^11.0.0" } : {}) };
 const uiDevDeps = { "@tsconfig/node22": "^22.0.1", "@types/node": "^22.13.14", "@vitejs/plugin-vue": "^5.2.3", "@vue/test-utils": "^2.4.10", "@vue/tsconfig": "^0.7.0", jsdom: "^29.1.1", "npm-run-all2": "^7.0.2", prettier: "3.5.3", typescript: "~5.8.0", vite: "^6.2.4", vitest: "^4.1.7", "vue-tsc": "^2.2.8" };
 add(`${ui}/package.json`, JSON.stringify({ name: uiPackage, version: "0.1.0", private: true, type: "module", scripts: { dev: "vite --host 0.0.0.0", build: "run-p type-check \"build-only {@}\" --", "build-only": "vite build", "type-check": "vue-tsc --build", test: "vitest run", "test:watch": "vitest", "validate:architecture": "tailframe validate ../.. --app ui", "sync:architecture": "tailframe sync --check ../..", format: "prettier --write src/", "format:check": "prettier --check src/" }, dependencies: uiDeps, devDependencies: uiDevDeps }, null, "\t"));
 
@@ -604,7 +604,24 @@ add(`${ui}/.gitattributes`, gitAttributes);
 add(`${ui}/tsconfig.json`, JSON.stringify({ files: [], references: [{ path: "./tsconfig.app.json" }, { path: "./tsconfig.node.json" }] }, null, "\t"));
 add(`${ui}/tsconfig.app.json`, JSON.stringify({ extends: "@vue/tsconfig/tsconfig.dom.json", include: ["env.d.ts", "src/**/*", "src/**/*.vue"], compilerOptions: { composite: true, noEmit: true, tsBuildInfoFile: "./.tmp/tsconfig.app.tsbuildinfo", types: ["vitest/globals"], baseUrl: ".", paths: { "@/*": ["./src/*"] } } }, null, "\t"));
 add(`${ui}/tsconfig.node.json`, JSON.stringify({ extends: "@tsconfig/node22/tsconfig.json", include: ["vite.config.ts"], compilerOptions: { composite: true, noEmit: true, tsBuildInfoFile: "./.tmp/tsconfig.node.tsbuildinfo", types: ["node"] } }, null, "\t"));
-add(`${ui}/vite.config.ts`, `import { fileURLToPath, URL } from "node:url";\nimport { defineConfig } from "vitest/config";\nimport vue from "@vitejs/plugin-vue";\nimport tailwindcss from "@tailwindcss/vite";\nexport default defineConfig({ plugins: [vue(), tailwindcss()], resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } }, server: { proxy: { "/api": { target: "http://localhost:3000", changeOrigin: true } } }, test: { environment: "jsdom", globals: true } });`);
+add(`${ui}/vite.config.ts`, `import { fileURLToPath, URL } from "node:url";
+import { defineConfig } from "vitest/config";
+import vue from "@vitejs/plugin-vue";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+	plugins: [vue(), tailwindcss()],
+	resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } },
+	server: {
+		proxy: {
+			"/api": {
+				target: process.env.VITE_API_PROXY_TARGET ?? "http://localhost:3000",
+				changeOrigin: true
+			}
+		}
+	},
+	test: { environment: "jsdom", globals: true }
+});`);
 add(`${ui}/env.d.ts`, `/// <reference types="vite/client" />`);
 add(`${ui}/index.html`, `<!doctype html>
 <html lang="en">
@@ -717,7 +734,7 @@ These conventions apply to \`${ui}/src\`. Inspect the nearest working module bef
 - Use \`src/core\` only for small technology-neutral client contracts.
 - Use \`src/platform\` for Axios, Firebase, browser APIs, and other technical adapters.
 - Use \`src/modules/<module>\` for every product capability. Never substitute \`src/features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories.
-- These are the only UI architecture roots. Keep \`src/core\` flat. Shared capability code belongs to the module that owns it. \`src/app/stores\` is closed to generated \`auth.store.ts\`, \`notification.store.ts\`, and \`theme.store.ts\`; \`src/app/public\` is closed to generated \`ThemeToggle.vue\`. Do not edit their implementations; only the generated theme storage key varies. Internal shell components remain private under \`src/app/components\`.
+- These are the only UI architecture roots. Keep \`src/core\` flat. Shared capability code belongs to the module that owns it. \`src/app/stores\` is closed to generated \`auth.store.ts\`, \`notification.store.ts\`, and \`theme.store.ts\`; \`src/app/public\` is closed to generated \`ThemeToggle.vue\`. Do not edit their implementations; only the generated theme storage key varies. Internal shell components remain private under \`src/app/components\`. Font Awesome's Vue component and free solid icon set are the standard icon system for shell and product UI.
 - Never create \`src/modules/theme\`, \`src/modules/auth\`, or \`src/modules/notification\`. Product records, current-user domain records, selections, filters, workflows, and module API calls always belong to the owning product module. When the service exposes a user capability, its current-user record belongs to a UI \`user\` module rather than whichever consumer happens to use fields from the response.
 
 ## Change placement
@@ -748,7 +765,7 @@ Use named routes.${options.auth === "firebase" ? " Preserve Firebase authenticat
 
 ## State management
 Keep local state local. Use Pinia only for state shared across routes or unrelated components.
-Keep all product state in the owning module. The auth/notification/theme stores, NotificationHost, and ThemeToggle are Tailframe-owned generated sources shared byte-for-byte across projects apart from the explicit theme storage key.
+Keep all product state in the owning module. The auth/notification/theme stores, NotificationHost, and ThemeToggle are Tailframe-owned generated sources shared byte-for-byte across projects apart from the explicit theme storage key. ThemeToggle uses Tailframe's Font Awesome Vue integration.
 
 ## UI behavior
 - Prefer PrimeVue for standard interactive controls and overlays when an appropriate component exists. Use native HTML for semantic structure, links, and genuinely custom interactions; use Tailwind for layout and composition.
@@ -760,7 +777,7 @@ Keep all product state in the owning module. The auth/notification/theme stores,
 - Keep \`src/app/styles.css\` limited to Tailwind imports, theme tokens, and true global base behavior.
 
 ## Production packaging
-The UI runs through Vite in development but has no production container. The service's multi-stage Dockerfile builds this application and copies its output into \`dist/public\`; Express serves it with SPA fallback. AWS ECR stores the combined \`linux/amd64\` production image under the default immutable \`<product-sha>\` tag, and production Compose requires that exact tag.${options.auth === "firebase" ? ` Provide \`${ui}/.env.production\` before a production build; the service build mounts it as a required BuildKit secret only while Vite compiles the browser bundle and does not copy it into the final image.` : ""}
+Development Compose runs Vite from the UI's development-only container on the product's private network; its proxy target is configurable and all development ports remain internal-only so multiple products can run concurrently. The UI has no independent production container. The service's multi-stage Dockerfile builds this application and copies its output into \`dist/public\`; Express serves it with SPA fallback. AWS ECR stores the combined \`linux/amd64\` production image under the default immutable \`<product-sha>\` tag, and production Compose requires that exact tag.${options.auth === "firebase" ? ` Provide \`${ui}/.env.production\` before a production build; the service build mounts it as a required BuildKit secret only while Vite compiles the browser bundle and does not copy it into the final image.` : ""}
 
 ## Product language
 The product domain is undefined. Do not invent entities, workflows, roles, claims, navigation, or customer-facing promises.
@@ -799,6 +816,18 @@ WORKDIR /workspace/apps/service
 EXPOSE 3000
 CMD ["pnpm", "dev"]
 `);
+if (options.ui) add(`${ui}/Dockerfile.dev`, `FROM node:22.13-alpine
+RUN npm install --global corepack@0.34.5 && corepack enable
+WORKDIR /workspace
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY apps/service/package.json apps/service/package.json
+COPY apps/ui/package.json apps/ui/package.json
+RUN pnpm install --frozen-lockfile --filter ${uiPackage}...
+COPY apps/ui apps/ui
+WORKDIR /workspace/apps/ui
+EXPOSE 5173
+CMD ["pnpm", "dev"]
+`);
 add(`${svc}/scripts/build_and_push.sh`, `#!/usr/bin/env bash
 set -euo pipefail
 
@@ -1552,17 +1581,17 @@ networks:
 
 const devWorker = options.worker ? `\n  worker:
     build:
-      context: .
-      dockerfile: Dockerfile.dev
+      context: ../..
+      dockerfile: apps/service/Dockerfile.dev
     env_file:
       - .env.development
-    command: ["npm", "run", "dev:worker"]${developmentEnvironmentBlock}
+    command: ["pnpm", "dev:worker"]${developmentEnvironmentBlock}
     volumes:
 ${devVolumes.join("\n")}${devDependsBlock}` : "";
 const devDatabase = postgres ? `\n  postgres:
     image: postgres:17
-    ports:
-      - "5432:5432"
+    expose:
+      - "5432"
     environment:
       POSTGRES_DB: ${databaseName}
       POSTGRES_USER: ${options.name}-app
@@ -1576,8 +1605,8 @@ const devDatabase = postgres ? `\n  postgres:
       retries: 30` : `\n  mongodb:
     image: mongo:8
     command: mongod --replSet rs0 --bind_ip_all
-    ports:
-      - "27017:27017"
+    expose:
+      - "27017"
     volumes:
       - mongodb-dev-data:/data/db
     healthcheck:
@@ -1604,10 +1633,22 @@ const devDatabase = postgres ? `\n  postgres:
         '`;
 const devRedis = options.redis ? `\n  redis:
     image: redis:7-alpine
-    ports:
-      - "6379:6379"
+    expose:
+      - "6379"
     volumes:
       - redis-dev-data:/data` : "";
+const devUi = options.ui ? `\n  ui:
+    build:
+      context: ../..
+      dockerfile: apps/ui/Dockerfile.dev
+${options.auth === "firebase" ? "    env_file:\n      - ../ui/.env.development\n" : ""}    environment:
+      VITE_API_PROXY_TARGET: http://${options.name}:3000
+    volumes:
+      - ../ui:/workspace/apps/ui
+      - /workspace/node_modules
+      - /workspace/apps/ui/node_modules
+    expose:
+      - "5173"` : "";
 const devNamedVolumes = [
 	postgres ? "  postgres-dev-data:" : "  mongodb-dev-data:",
 	...(options.redis ? ["  redis-dev-data:"] : [])
@@ -1616,11 +1657,11 @@ add(`${svc}/docker-compose.dev.yml`, `name: ${options.name}-dev
 services:
   schema-init:
     build:
-      context: .
-      dockerfile: Dockerfile.dev
+      context: ../..
+      dockerfile: apps/service/Dockerfile.dev
     env_file:
       - .env.development
-    command: ["npm", "run", "schema:apply:dev"]${developmentEnvironmentBlock}
+    command: ["pnpm", "schema:apply:dev"]${developmentEnvironmentBlock}
     volumes:
 ${devVolumes.join("\n")}
     depends_on:
@@ -1628,14 +1669,14 @@ ${devVolumes.join("\n")}
         condition: ${postgres ? "service_healthy" : "service_completed_successfully"}
   ${options.name}:
     build:
-      context: .
-      dockerfile: Dockerfile.dev
+      context: ../..
+      dockerfile: apps/service/Dockerfile.dev
     env_file:
       - .env.development
-    ports:
-      - "3000:3000"${developmentEnvironmentBlock}
+    expose:
+      - "3000"${developmentEnvironmentBlock}
     volumes:
-${devVolumes.join("\n")}${devDependsBlock}${devWorker}${devDatabase}${devRedis}
+${devVolumes.join("\n")}${devDependsBlock}${devUi}${devWorker}${devDatabase}${devRedis}
 volumes:
 ${devNamedVolumes.join("\n")}
 `);

package/src/sync.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { appRoot, loadConfig } from "./config.mjs";
+import { themeToggleSource } from "./generate.mjs";
 import { appGuidance, OWNED_GUIDANCE_END, OWNED_GUIDANCE_START, productGuidance } from "./owned-guidance.mjs";
 import { ownedSources } from "./owned-sources.mjs";
 
@@ -47,7 +48,11 @@ export function runSync(rootArgument, mode, runningVersion, selectedKind) {
 			continue;
 		}
 		syncGuidance(loaded.root, root, appGuidance(loaded.config, app), mode, changed, errors, app.path);
-		for (const [relative, expected] of Object.entries(ownedSources(app))) {
+		const sources = ownedSources(app);
+		if (app.kind === "ui" && fs.existsSync(path.join(root, "src/app/public/ThemeToggle.vue"))) {
+			sources["src/app/public/ThemeToggle.vue"] = themeToggleSource();
+		}
+		for (const [relative, expected] of Object.entries(sources)) {
 			const absolute = path.join(root, relative);
 			const productRelative = path.join(app.path, relative);
 			const actual = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : undefined;

package/src/validate.mjs

@@ -8,6 +8,11 @@ import { runSync } from "./sync.mjs";
 
 const NON_EXCEPTABLE_RULES = new Set(["S8", "S9", "U5", "U6", "U7"]);
 const PNPM_VERSION = "11.22.0";
+const FONT_AWESOME_UI_DEPENDENCIES = {
+	"@fortawesome/fontawesome-svg-core": "^7.3.1",
+	"@fortawesome/free-solid-svg-icons": "^7.3.1",
+	"@fortawesome/vue-fontawesome": "^3.3.3"
+};
 
 export function runValidate(root, kind) {
 	const structural = validateArchitecture(root, kind);
@@ -61,7 +66,7 @@ function validateVersionMetadata(root, runningVersion) {
 	return errors;
 }
 
-function validateAppMetadata(productRoot, app) {
+function validateAppMetadata(productRoot, app, productConfig) {
 	const errors = [];
 	const root = appRoot(productRoot, app);
 	if (!fs.existsSync(root)) return [`Missing configured application root: ${app.path}`];
@@ -71,6 +76,7 @@ function validateAppMetadata(productRoot, app) {
 		else {
 			const compose = fs.readFileSync(composeFile, "utf8");
 			const generatedProcessCount = app.profiles.includes("worker") ? 3 : 2;
+			const hasUi = productConfig.apps.some((candidate) => candidate.kind === "ui");
 			const count = (term) => compose.split(term).length - 1;
 			for (const term of [
 				"      - .:/workspace/apps/service",
@@ -84,6 +90,14 @@ function validateAppMetadata(productRoot, app) {
 			if (compose.includes("      - .:/app\n")) {
 				errors.push(`${app.path}/docker-compose.dev.yml uses the obsolete /app service source mount`);
 			}
+			if (compose.includes("    ports:")) {
+				errors.push(`${app.path}/docker-compose.dev.yml must keep generated development ports internal-only`);
+			}
+			if (hasUi) {
+				for (const term of ["  ui:", "dockerfile: apps/ui/Dockerfile.dev", "VITE_API_PROXY_TARGET:", "      - ../ui:/workspace/apps/ui", "      - /workspace/apps/ui/node_modules"]) {
+					if (!compose.includes(term)) errors.push(`${app.path}/docker-compose.dev.yml is missing the development UI container contract: ${term.trim()}`);
+				}
+			}
 			if (app.profiles.includes("firebase")) {
 				for (const term of [
 					"      FIREBASE_SERVICE_ACCOUNT_PATH: /app/firebase-service-account.development.json",
@@ -97,6 +111,7 @@ function validateAppMetadata(productRoot, app) {
 		}
 	}
 	if (app.kind === "ui") {
+		if (!fs.existsSync(path.join(root, "Dockerfile.dev"))) errors.push(`${app.path}/Dockerfile.dev is required`);
 		const generatedArtifacts = fs.readdirSync(root, { withFileTypes: true })
 			.filter(
 				(entry) =>
@@ -123,6 +138,13 @@ function validateAppMetadata(productRoot, app) {
 			if (manifest.devDependencies?.["@zaaxch/tailframe"] || manifest.dependencies?.["@zaaxch/tailframe"]) {
 				errors.push(`${app.path}/package.json must not depend on @zaaxch/tailframe; pin it at the product root`);
 			}
+			if (app.kind === "ui") {
+				for (const [dependency, version] of Object.entries(FONT_AWESOME_UI_DEPENDENCIES)) {
+					if (manifest.dependencies?.[dependency] !== version) {
+						errors.push(`${app.path}/package.json must pin Tailframe's ${dependency} dependency to ${version}`);
+					}
+				}
+			}
 		} catch {
 			errors.push(`${app.path}/package.json is not valid JSON`);
 		}
@@ -140,7 +162,7 @@ export function runConfiguredValidate(rootArgument, runningVersion, selectedKind
 		errors.push(`tailframe.json does not declare a ${selectedKind} app`);
 	}
 	errors.push(...validateVersionMetadata(loaded.root, runningVersion));
-	for (const app of loaded.config.apps) errors.push(...validateAppMetadata(loaded.root, app));
+	for (const app of loaded.config.apps) errors.push(...validateAppMetadata(loaded.root, app, loaded.config));
 	if (errors.length) return errors;
 	const apps = selectedKind ? loaded.config.apps.filter((app) => app.kind === selectedKind) : loaded.config.apps;
 	for (const app of apps) {