@fougere/cli 0.9.2-alpha.0 → 0.10.0-alpha.0

package/fronds/analysis/handlers/DevtoolsHandler.ts

@@ -2,9 +2,18 @@ import { createHttpTransport } from '@fougere/transport-http/client';
 import type { CallPage, CallRecord } from '@fougere/core';
 import ProjectScan from '../services/ProjectScan.js';
 
-/** The default address of an app in development — Nuxt, Next and the site all sit there. */
+/**
+ * Where an app answers in development — Nuxt, Next and the site all sit there, so it is a
+ * convention and not a setting. A port belongs to the HOST, though, and this project states
+ * none: an app served anywhere else is named the way `FOUGERE_LOG_LEVEL` names a level the
+ * file did not, and `--url` still wins over both.
+ */
 const LOCAL = 'http://127.0.0.1:3000';
 
+function local(): string {
+  return trimmed(process.env.FOUGERE_URL || LOCAL);
+}
+
 /** One address that was asked, and what came back from it. */
 export interface CallSource {
   url: string;
@@ -70,10 +79,11 @@ export default class DevtoolsHandler {
    */
   private async addresses(root?: string): Promise<{ url: string; frond?: string }[]> {
     const { config } = await this.projectScan.at(root);
+    const here = local();
     const remotes = Object.entries(config.remotes ?? {})
       .map(([frond, url]) => ({ url: trimmed(url), frond }));
 
-    return [{ url: LOCAL }, ...remotes.filter((one) => one.url !== LOCAL)];
+    return [{ url: here }, ...remotes.filter((one) => one.url !== here)];
   }
 }
 

package/fronds/analysis/handlers/ExplainHandler.ts

@@ -59,6 +59,11 @@ export interface ExplainResult {
     runtime: 'local' | 'remote';
     remote: string | null;
   };
+  /** Where the work GOES, next to where it answers — and how much of it leaves the process. */
+  reach: {
+    fronds: { frond: string; runtime: 'local' | 'remote' }[];
+    hops: number;
+  };
 }
 
 /** What this project serves, when no single operation was named. */
@@ -193,6 +198,7 @@ function project(operation: EffectiveOperation, root: string): ExplainResult {
       runtime: operation.placement.runtime,
       remote: operation.placement.remote ?? null,
     },
+    reach: operation.reach,
   };
 }
 

package/fronds/analysis/handlers/GraphHandler.ts

@@ -1,11 +1,13 @@
 import {
-  buildGraph, suggestSplit,
-  type EntityNode, type DomainCluster, type FrondDescriptor,
+  buildGraph, declaredTopologyOf, suggestSplit,
+  type DeclaredTopology, type EntityNode, type DomainCluster, type FrondDescriptor,
 } from '@fougere/core';
 import ProjectScan from '../services/ProjectScan.js';
 
 export interface GraphResult {
   fronds: FrondDescriptor[];
+  /** Where the fronds run and which reaches which — the same picture, one altitude up. */
+  declared: DeclaredTopology;
   nodes: Map<string, EntityNode>;
   clusters: DomainCluster[];
   totalEntities: number;
@@ -17,12 +19,13 @@ export default class GraphHandler {
 
   /** Report how a workspace's fronds and entities reference each other. */
   async execute(input: { root?: string; minEntities?: number }): Promise<GraphResult> {
-    const { fronds } = await this.projectScan.at(input.root);
+    const { fronds, config } = await this.projectScan.at(input.root);
     const nodes = buildGraph(fronds);
     const clusters = suggestSplit(nodes);
 
     return {
       fronds,
+      declared: declaredTopologyOf({ fronds, remotes: config.remotes ?? {} }),
       nodes,
       clusters,
       totalEntities: nodes.size,

package/fronds/analysis/handlers/LoadHandler.ts

@@ -0,0 +1,43 @@
+import { loadScript, reachableOps } from '@fougere/testing';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import ProjectScan from '../services/ProjectScan.js';
+
+export interface LoadScenario {
+  /** Where it was written, or `null` when it was only printed. */
+  file: string | null;
+  facade: string;
+  /** Every operation the scenario calls, in the order it lists them. */
+  operations: string[];
+  script: string;
+}
+
+/**
+ * A load scenario, written from what the project serves.
+ *
+ * Read from the SCAN rather than a boot: an app that boots runs its migrations and plants its
+ * seeds, and a command that describes a project has no business writing to its database.
+ */
+export default class LoadHandler {
+  constructor(private projectScan: ProjectScan) {}
+
+  /** Generate a k6 scenario covering every operation the default facade answers. */
+  async execute(input: { root?: string; facade?: string; out?: string }): Promise<LoadScenario> {
+    const { root, fronds, config } = await this.projectScan.at(input.root);
+    const facade = input.facade?.trim() || undefined;
+    // The topology statement travels with it: an op that crosses a process is not held to the
+    // same figure as one that never leaves, and `remotes:` is what says which is which.
+    const remotes = config.remotes ?? {};
+    const script = loadScript({ fronds }, { ...(facade ? { facade } : {}), remotes });
+
+    const file = input.out === undefined ? join(root, 'load.js') : input.out || null;
+    if (file) await writeFile(file, script, 'utf8');
+
+    return {
+      file,
+      facade: facade ?? 'http://127.0.0.1:3000/_fougere/call',
+      operations: reachableOps({ fronds }, {}, remotes).map((one) => one.method),
+      script,
+    };
+  }
+}

package/fronds/scaffold/handlers/BuildFrondHandler.ts

@@ -1,5 +1,5 @@
 import { execSync } from 'node:child_process';
-import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { existsSync, writeFileSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { resolveConventions, frondPackage } from '@fougere/core';
 import { loadConfig } from '@fougere/core/node';

package/fronds/scaffold/handlers/SyncHandler.ts

@@ -1,14 +1,31 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { upperFirst, type SchemaDescriptor } from '@fougere/schema';
-import { EntityTypes } from '../../../src/typescript/EntityTypes.js';
-import { FacadeTypes } from '../../../src/typescript/FacadeTypes.js';
+import { EntityTypes } from '../../../src/typescript/EntityTypes/EntityTypes.js';
+import { FacadeTypes } from '../../../src/typescript/FacadeTypes/FacadeTypes.js';
 // The card's shape is declared once, in core, and imported here. A private copy of it
 // lived in this file and went stale the day an op stopped being a bare name: nothing
 // compared the copy to the original, so the drift cost nothing until someone read it.
 import { assertIdentityCard, type IdentityCard } from '@fougere/core';
 import { type Conventions, resolveConventions, frondPackage } from '@fougere/core';
 import { loadConfig } from '@fougere/core/node';
+import { facadeModule, type Served } from '@fougere/compiler';
+import { ErrorCode } from '@fougere/core/contract';
+
+/**
+ * A union of enum MEMBERS, from what the card said this operation refuses.
+ *
+ * `ErrorCode` is a string enum, so `'CONFLICT'` is not assignable to it: a literal reads as the
+ * right thing and then refuses to narrow `FougereError<Code>`, which is the whole point. A code
+ * this version does not know is dropped rather than written — the far side may be newer, and a
+ * name that resolves to nothing would stop the consumer's build.
+ */
+function codesOf(errors: readonly string[] | undefined): string {
+  const known = (errors ?? []).filter((code) => code in ErrorCode);
+  if (known.length === 0) return 'never';
+
+  return known.map((code) => `ErrorCode.${code}`).join(' | ');
+}
 
 function assertSafeName(kind: string, name: string): void {
   if (typeof name !== 'string' || !/^[A-Za-z_$][A-Za-z0-9_$-]*$/.test(name)) {
@@ -36,10 +53,10 @@ export function entityClassName(name: string): string {
 }
 
 /**
- * One entry — a door or a fact — validated the same way, because sync consumes the same two
+ * One entry — a facade or a fact — validated the same way, because sync consumes the same two
  * values from both: a name it can turn into a class, and a descriptor it can rebuild.
  *
- * A missing descriptor is legal on either side and means different things: a door that
+ * A missing descriptor is legal on either side and means different things: a facade that
  * stores nothing (a health check, a search across shapes), or a fact whose announced type
  * is not a declared entity. Neither produces a row class, and demanding one here refused
  * the WHOLE card over a single entry.
@@ -72,7 +89,7 @@ function assertEntry(kind: string, frondName: string, entry: { name: string; sch
 
 function identityCardOf(value: unknown): IdentityCard {
   // The card's own shape is validated by the package that declares it — `fronds`, and each
-  // frond's `doors`. What stays here is what only a writer of files needs: a name safe to
+  // frond's `facades`. What stays here is what only a writer of files needs: a name safe to
   // become one, and the descriptor a class is generated from.
   const card = assertIdentityCard(value, 'Remote rpc.discover');
   for (const frond of card.fronds) {
@@ -83,7 +100,7 @@ function identityCardOf(value: unknown): IdentityCard {
     if (frond.facts !== undefined && !Array.isArray(frond.facts)) {
       throw new Error(`Remote frond '${frond.name}' has no valid facts array`);
     }
-    for (const door of frond.doors) assertEntry('door', frond.name, door);
+    for (const facade of frond.facades) assertEntry('facade', frond.name, facade);
     for (const fact of frond.facts ?? []) assertEntry('fact', frond.name, fact);
   }
   return card;
@@ -142,17 +159,17 @@ export default class SyncHandler {
     /**
      * What was written under each name — the barrel below is a projection of exactly this.
      *
-     * Three combinations, and all three occur: a door with rows behind it (both files), a
-     * door with none (the façade type alone), and a fact (the row class alone, because
+     * Three combinations, and all three occur: a facade with rows behind it (both files), a
+     * facade with none (the façade type alone), and a fact (the row class alone, because
      * nothing calls a fact).
      */
-    const generated = new Map<string, { row: boolean; door: boolean }>();
+    const generated = new Map<string, { row: boolean; facade: boolean }>();
     /** Absolute paths written by THIS run — anything else generated here is now stale. */
     const written = new Set<string>();
     const claim = (name: string): string => {
       const className = entityClassName(name);
       if (generated.has(className)) throw new Error(`Remote declares duplicate entity '${className}'`);
-      generated.set(className, { row: false, door: false });
+      generated.set(className, { row: false, facade: false });
       return className;
     };
 
@@ -179,16 +196,24 @@ export default class SyncHandler {
       generated.get(className)!.row = true;
     };
 
-    for (const { name, schema: descriptor, ops } of target.doors) {
-      const className = claim(name);
-      generated.get(className)!.door = true;
+    /** What the card says of each address — the same three facts a scan gives. */
+    const served: Served[] = [];
 
-      // No shape behind this door: its operations still travel, its rows do not exist.
+    for (const { name, schema: descriptor, ops } of target.facades) {
+      const className = claim(name);
+      generated.get(className)!.facade = true;
+      served.push({
+        at: name,
+        handler: `import('./${handlers}/${className}Handler.js').${className}Handler`,
+        ops: (ops ?? []).map((op) => ({ name: op.name, codes: codesOf(op.errors) })),
+      });
+
+      // No shape behind this facade: its operations still travel, its rows do not exist.
       // `rowType` falls back to `unknown`, which is the truth rather than an empty class.
       if (descriptor !== undefined) writeRow(className, descriptor as SchemaDescriptor);
 
       /**
-       * The door's type, next to the row's — what `Facade<T>` needs and what nothing
+       * The facade's type, next to the row's — what `Facade<T>` needs and what nothing
        * carried across a repository boundary.
        *
        * Writing `Facade<ArticleHandler>` used to require importing the handler's class.
@@ -229,12 +254,26 @@ export default class SyncHandler {
       writeRow(className, descriptor as SchemaDescriptor);
     }
 
+    /**
+     * The facade module, written from the CARD rather than from a scan.
+     *
+     * A frond in another repository cannot be scanned — there are no sources here. What the
+     * card carries is exactly the three facts the module needs: the addresses, the operations,
+     * and what each one refuses. The handler TYPE is the one thing it cannot carry, so the
+     * synthetic interface written above stands in its place: it names the same operations with
+     * the same answers, which is what a page reads.
+     *
+     * `facadeModule` is the compiler's own, not a copy: two spellings of one format would
+     * drift the day either gained a member.
+     */
+    writeFileSync(join(frondDir, 'facade.ts'), facadeModule(served, `${baseUrl} — a card, not a scan`));
+
     // Barrel index
     // One binding carries the value AND the type, because a class is both — the pair of
     // re-exports that stood here was the price of declaring them separately.
-    const indexLines = [...generated].flatMap(([name, { row, door }]) => [
+    const indexLines = [...generated].flatMap(([name, { row, facade }]) => [
       ...(row ? [`export { default as ${name} } from './${entities}/${name}.js';`] : []),
-      ...(door ? [`export type { ${name}Handler } from './${handlers}/${name}Handler.js';`] : []),
+      ...(facade ? [`export type { ${name}Handler } from './${handlers}/${name}Handler.js';`] : []),
     ]);
     writeFileSync(join(frondDir, 'index.ts'), indexLines.join('\n') + '\n');
 
@@ -265,7 +304,7 @@ export default class SyncHandler {
      * — but the FILE stayed, and the generated `package.json` exports `'./entities/*'` as
      * a wildcard, so `@fronds/blog/entities/Ticket.js` kept resolving to a class nothing
      * behind it answers for. The consumer compiles, its local validator accepts, and the call
-     * comes back NOT_FOUND at the door — or never leaves, because the page dropped the
+     * comes back NOT_FOUND at the facade — or never leaves, because the page dropped the
      * call and kept the type.
      */
     const removed = [...this.prune(entitiesDir, written), ...this.prune(handlersDir, written)];

package/fronds/scaffold/services/ProjectWriter.ts

@@ -30,6 +30,52 @@ function monorepoPackages(): string | undefined {
  */
 const TEMPLATES = fileURLToPath(new URL('../../../templates/', import.meta.url));
 
+/**
+ * Where a HOST keeps its starter, or nothing when it ships none.
+ *
+ * The package that owns the wiring owns the files: `@fougere/nuxt` knows what a
+ * `nuxt.config.ts` must say, and a copy of it here would be that knowledge written twice —
+ * which is how `templates/apps/` came to hold one host while six were published.
+ *
+ * Resolved from the main entry and walked up to the manifest, because a host does not export
+ * its own `package.json` and has no reason to.
+ *
+ * `import.meta.resolve` and not `createRequire().resolve`: a host's `exports` states only the
+ * `import` condition, so the CJS resolver answers `ERR_PACKAGE_PATH_NOT_EXPORTED` for every
+ * one of them.
+ */
+function starterOf(pkg: string): string | undefined {
+  let dir: string;
+  try {
+    dir = dirname(fileURLToPath(import.meta.resolve(pkg)));
+  } catch { return undefined; }
+
+  while (!existsSync(join(dir, 'package.json')) && dir !== dirname(dir)) dir = dirname(dir);
+  const template = join(dir, 'template');
+
+  return existsSync(template) ? template : undefined;
+}
+
+/**
+ * The hosts this CLI can scaffold: its own `@fougere/*` dependencies that ship a starter.
+ *
+ * The dependency list IS the registry — nothing to declare, and a host added to the family
+ * appears here the day the CLI depends on it.
+ */
+function hosts(): Map<string, string> {
+  const manifest = JSON.parse(readFileSync(fileURLToPath(new URL('../../../package.json', import.meta.url)), 'utf8')) as
+    { dependencies?: Record<string, string> };
+  const found = new Map<string, string>();
+
+  for (const pkg of Object.keys(manifest.dependencies ?? {})) {
+    if (!pkg.startsWith('@fougere/')) continue;
+    const starter = starterOf(pkg);
+    if (starter) found.set(pkg.slice('@fougere/'.length), starter);
+  }
+
+  return found;
+}
+
 /** The version that scaffolds is the version the templates were written for. */
 const scaffoldVersion = (): string =>
   (JSON.parse(readFileSync(fileURLToPath(new URL('../../../package.json', import.meta.url)), 'utf8')) as
@@ -102,19 +148,31 @@ export default class ProjectWriter {
     return { path: dest };
   }
 
-  /** Add an app (consumer) under apps/<name>. */
+  /** Add an app (consumer) under apps/<name>, from the host package that owns its wiring. */
   addApp(wsDir: string, template: string, name: string): { path: string } {
     const dest = join(wsDir, 'apps', name);
-    cpSync(join(TEMPLATES, 'apps', template), dest, { recursive: true });
+    const starter = hosts().get(template);
+    if (!starter) throw new Error(`No host ships a starter for '${template}'. Served: ${[...hosts().keys()].join(', ')}.`);
+
+    cpSync(starter, dest, { recursive: true });
     restoreGitignore(dest);
     setPackageName(dest, name);
     return { path: dest };
   }
 
-  /** Available templates of a kind ('fronds' | 'apps') — the directory is the registry. */
+  /**
+   * What can be scaffolded, of a kind.
+   *
+   * A FROND comes from this package: it is Fougere's own vocabulary, entities and handlers,
+   * and no other package owns it. An APP comes from its HOST — the registry is the hosts this
+   * CLI depends on, so `fougere new` offers what is published rather than what was copied here.
+   */
   listTemplates(kind: 'fronds' | 'apps'): string[] {
+    if (kind === 'apps') return [...hosts().keys()].sort();
+
     const dir = join(TEMPLATES, kind);
     if (!existsSync(dir)) return [];
+
     return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/cli",
-  "version": "0.9.2-alpha.0",
+  "version": "0.10.0-alpha.0",
   "description": "The Fougere CLI — compose a workspace, serve a frond, call an operation.",
   "keywords": [
     "fougere",
@@ -42,13 +42,20 @@
     "jiti": "^2.4.2",
     "picocolors": "^1.1.1",
     "safe-regex": "^2.1.1",
-    "@fougere/container": "0.9.2-alpha.0",
-    "@fougere/core": "0.9.2-alpha.0",
-    "@fougere/schema": "0.9.2-alpha.0",
-    "@fougere/compiler": "0.9.2-alpha.0",
-    "@fougere/transport-http": "0.9.2-alpha.0",
-    "@fougere/adapter-sql": "0.9.2-alpha.0",
-    "@fougere/defaults": "0.9.2-alpha.0"
+    "@fougere/adapter-sql": "0.10.0-alpha.0",
+    "@fougere/core": "0.10.0-alpha.0",
+    "@fougere/defaults": "0.10.0-alpha.0",
+    "@fougere/nuxt": "0.10.0-alpha.0",
+    "@fougere/compiler": "0.10.0-alpha.0",
+    "@fougere/container": "0.10.0-alpha.0",
+    "@fougere/svelte": "0.10.0-alpha.0",
+    "@fougere/testing": "0.10.0-alpha.0",
+    "@fougere/react": "0.10.0-alpha.0",
+    "@fougere/transport-http": "0.10.0-alpha.0",
+    "@fougere/schema": "0.10.0-alpha.0",
+    "@fougere/next": "0.10.0-alpha.0",
+    "@fougere/admin": "0.10.0-alpha.0",
+    "@fougere/oclif": "0.10.0-alpha.0"
   },
   "devDependencies": {
     "vitest": "^4.1.0"

package/src/bridge.ts

@@ -8,23 +8,46 @@ function toKebab(name: string): string {
   return name.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
 }
 
+/**
+ * What a caller supplies: the fields the axes admit, or the PRIMARY when they admit nothing.
+ *
+ * `Visibility.input` answers who may WRITE a field, and a primary is the server's — right for a
+ * form, wrong for an operation whose whole input is `Product.pick('id')`. That contract asks the
+ * caller to NAME a row, and the axes leave it with no argument at all: `product:archive abc-9`
+ * answered `Unexpected argument`.
+ *
+ * Only when nothing else remains, so `create` over a full entity is untouched — its input holds
+ * twelve writable fields and the primary stays the server's.
+ */
+function suppliedIn(fields: Fields): Fields {
+  const written = Visibility.of(fields).input;
+  if (Object.keys(written).length > 0) return written;
+
+  return Object.fromEntries(
+    Object.entries(fields).filter(([, field]) => Role.of(field).isPrimary),
+  ) as Fields;
+}
+
 /** Convert an Entity's fields into citty args definition. */
 export function entityToArgs(fields: Fields): ArgsDef {
   const args: ArgsDef = {};
   let positionalIndex = 0;
 
-  // Axes-derived ingress membership; the CLI additionally skips ALL relations
-  // (a ref is not a flag — supplying related rows is not a CLI gesture).
-  for (const [key, field] of Object.entries(Visibility.of(fields).input)) {
+  // The CLI additionally skips ALL relations: a ref is not a flag — supplying related rows is
+  // not a CLI gesture.
+  for (const [key, field] of Object.entries(suppliedIn(fields))) {
     if (Role.of(field).isRelation) continue;
 
     // A `default(v)` travels as the create rule `{ value }` — citty shows it.
     const defaultValue = Lifecycle.of(field).literal?.value;
     const { base: shape, nullable } = Shapes.of(field.shape);
     const type = Shapes.typeOf(field.shape);
+    // Naming a row is required by definition: a generator fills a primary the server writes,
+    // never one a caller hands in to designate.
+    const designates = Role.of(field).isPrimary;
     const common = {
       description: field.meta?.description,
-      required: !nullable && Lifecycle.of(field).requiredAtCreate,
+      required: designates || (!nullable && Lifecycle.of(field).requiredAtCreate),
     };
 
     // A closed set is citty's `enum`: the shape already names the legal values, so the

package/src/machine.ts

@@ -4,7 +4,7 @@ export function machineWanted(raw: Record<string, unknown>): boolean {
 }
 
 /**
- * A `Map` serializes to `{}`, so the door converts it rather than each command flattening its own
+ * A `Map` serializes to `{}`, so the facade converts it rather than each command flattening its own
  * result: `GraphResult.nodes` is a Map, and `graph --json` would have printed a report with an
  * empty graph in it.
  */

package/src/runner.ts

@@ -22,11 +22,11 @@ function toCamel(kebab: string): string {
 
 /** Scan app/commands/ for command classes. */
 async function loadAppCommands(
-  cliRoot: string,
+  root: string,
   loader: (path: string) => Promise<Record<string, unknown>>,
 ): Promise<Map<string, new (...args: unknown[]) => { run: (raw: Record<string, unknown>) => Promise<void> }>> {
   const map = new Map();
-  const dir = join(cliRoot, 'app', 'commands');
+  const dir = join(root, 'app', 'commands');
   const files = await readdir(dir, { withFileTypes: true }).catch(() => []);
 
   for (const f of files) {
@@ -42,14 +42,21 @@ async function loadAppCommands(
   return map;
 }
 
-export async function run(app: App): Promise<void> {
+/**
+ * Every operation of an app, as a terminal command.
+ *
+ * `root` is where the PRESENTATION classes are looked for — `app/commands/`, one per command
+ * that wants to print something of its own. It defaults to this package, which is how
+ * `npx fougere` finds its fifteen; a project passes its own and gets the same treatment for
+ * the operations it declares, with no class at all where a default rendering will do.
+ */
+export async function run(app: App, root = new URL('..', import.meta.url).pathname): Promise<void> {
   const terminal = ui();
-  const cliRoot = new URL('..', import.meta.url).pathname;
 
   const { createJiti } = await import('jiti');
   const jiti = createJiti(import.meta.url, { interopDefault: true });
   const loader = (path: string) => jiti.import(path) as Promise<Record<string, unknown>>;
-  const appCommands = await loadAppCommands(cliRoot, loader);
+  const appCommands = await loadAppCommands(root, loader);
 
   const subCommands: Record<string, ReturnType<typeof defineCommand>> = {};
 
@@ -86,7 +93,7 @@ export async function run(app: App): Promise<void> {
         meta: {
           name: cmdName,
           // `--help` reads the operation's own doc sentence, which the scan already
-          // carries for every door (`OperationContract.description`). A table here
+          // carries for every facade (`OperationContract.description`). A table here
           // would be the same fact written twice, and it drifted: it described `add`
           // and `doctor`, which do not exist, and had nothing for `call` or `serve`.
           description: handlerEntry.operations.get('execute')?.description,

package/src/typescript/{EntityTypes.ts → EntityTypes/EntityTypes.ts}

@@ -1,5 +1,6 @@
 import { upperFirst, type FieldDescriptor, type SchemaDescriptor } from '@fougere/schema';
-import { docCommentOf, propertyKey } from './syntax.js';
+import { docCommentOf, propertyKey } from '../syntax.js';
+import type { EntityTypesOptions } from './EntityTypesOptions.js';
 
 /** So a nullable field lands as a union. */
 function typeOf(field: FieldDescriptor): string {
@@ -41,11 +42,6 @@ function objectTypeOf(properties: Record<string, FieldDescriptor>, required: rea
   return `{ ${members.join('; ')} }`;
 }
 
-export interface EntityTypesOptions {
-  name?: string;
-  exported?: boolean;
-}
-
 /** So the generated class carries its row type. */
 function shapeTypeOf(descriptor: SchemaDescriptor, indent = ''): string {
   const entries = Object.entries(descriptor.properties ?? {});

package/src/typescript/EntityTypes/EntityTypesOptions.ts

@@ -0,0 +1,4 @@
+export interface EntityTypesOptions {
+  name?: string;
+  exported?: boolean;
+}

package/src/typescript/{FacadeTypes.ts → FacadeTypes/FacadeTypes.ts}

@@ -1,18 +1,6 @@
-import type { SchemaDescriptor } from '@fougere/schema';
-import { docCommentOf, propertyKey } from './syntax.js';
-
-export interface FacadeTypesOptions {
-  name?: string;
-  exported?: boolean;
-  rowType?: string;
-}
-
-export interface OpDescriptor {
-  name: string;
-  description?: string;
-  output?: SchemaDescriptor;
-  cardinality?: 'one' | 'maybe' | 'many' | 'page' | 'none';
-}
+import { docCommentOf, propertyKey } from '../syntax.js';
+import type { FacadeTypesOptions } from './FacadeTypesOptions.js';
+import type { OpDescriptor } from './OpDescriptor.js';
 
 /** So a consumer sees the cardinality in the type, not in a doc line. */
 function returnTypeOf(op: OpDescriptor, rowType: string): string {

package/src/typescript/FacadeTypes/FacadeTypesOptions.ts

@@ -0,0 +1,5 @@
+export interface FacadeTypesOptions {
+  name?: string;
+  exported?: boolean;
+  rowType?: string;
+}

package/src/typescript/FacadeTypes/OpDescriptor.ts

@@ -0,0 +1,8 @@
+import type { SchemaDescriptor } from '@fougere/schema';
+
+export interface OpDescriptor {
+  name: string;
+  description?: string;
+  output?: SchemaDescriptor;
+  cardinality?: 'one' | 'maybe' | 'many' | 'page' | 'none';
+}

package/templates/blog/fronds/blog/entities/Post.ts

@@ -7,6 +7,6 @@ export default class Post extends entity({
   createdAt: created(),
   // Server-owned: a post is born a draft and flipped by the publish
   // operation, never by a client writing the field. readOnly closes
-  // the inbound door — the field is projected out, never accepted in.
+  // the inbound facade — the field is projected out, never accepted in.
   status: readOnly(oneOf('draft', 'published', { default: 'draft' })),
 }) {}

package/templates/flat/CLAUDE.md

@@ -25,11 +25,11 @@ Two consequences worth stating, because they are what makes it hold:
 
 If you are about to write the same constraint in two places, you have missed the derivation.
 
-## A surface is a door, never a logic
+## A surface is a facade, never a logic
 
-Every door goes through the handler **façade**, which is where validation sits: unknown-key refusal,
+Every facade goes through the handler **façade**, which is where validation sits: unknown-key refusal,
 collectors. A resolver or route you wire yourself against the storage — or worse, against the database —
-is a second door with no validator behind it, and the rules declared in the entities stop applying there.
+is a second facade with no validator behind it, and the rules declared in the entities stop applying there.
 
 Before adding a surface, reach for its **projection**:
 

package/templates/frond/CLAUDE.md

@@ -25,11 +25,11 @@ Two consequences worth stating, because they are what makes it hold:
 
 If you are about to write the same constraint in two places, you have missed the derivation.
 
-## A surface is a door, never a logic
+## A surface is a facade, never a logic
 
-Every door goes through the handler **façade**, which is where validation sits: unknown-key refusal,
+Every facade goes through the handler **façade**, which is where validation sits: unknown-key refusal,
 collectors. A resolver or route you wire yourself against the storage — or worse, against the database —
-is a second door with no validator behind it, and the rules declared in the entities stop applying there.
+is a second facade with no validator behind it, and the rules declared in the entities stop applying there.
 
 Before adding a surface, reach for its **projection**:
 

package/templates/workspace/CLAUDE.md

@@ -25,11 +25,11 @@ Two consequences worth stating, because they are what makes it hold:
 
 If you are about to write the same constraint in two places, you have missed the derivation.
 
-## A surface is a door, never a logic
+## A surface is a facade, never a logic
 
-Every door goes through the handler **façade**, which is where validation sits: unknown-key refusal,
+Every facade goes through the handler **façade**, which is where validation sits: unknown-key refusal,
 collectors. A resolver or route you wire yourself against the storage — or worse, against the database —
-is a second door with no validator behind it, and the rules declared in the entities stop applying there.
+is a second facade with no validator behind it, and the rules declared in the entities stop applying there.
 
 Before adding a surface, reach for its **projection**: