@fougere/cli 0.1.0-alpha.0

package/fronds/scaffold/handlers/SyncHandler.ts

@@ -0,0 +1,329 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { entitySourceOf, facadeTypeSourceOf, type SchemaDescriptor } from '@fougere/schema';
+// 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 type { IdentityCard } from '@fougere/core';
+
+function assertSafeName(kind: string, name: string): void {
+  if (typeof name !== 'string' || !/^[A-Za-z_$][A-Za-z0-9_$-]*$/.test(name)) {
+    throw new Error(`Invalid ${kind} name '${name}' received from remote`);
+  }
+}
+
+/**
+ * The line every generated file carries. It is what makes pruning safe: sync removes what
+ * IT wrote and nothing else, so a file a human dropped into the folder survives.
+ */
+const GENERATED = 'Generated by `fougere sync`';
+
+export function entityClassName(name: string): string {
+  assertSafeName('entity', name);
+  const identifier = name
+    .split('-')
+    .filter(Boolean)
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join('');
+  if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(identifier)) {
+    throw new Error(`Entity name '${name}' cannot be represented as a TypeScript identifier`);
+  }
+  return identifier;
+}
+
+/**
+ * One entry — a door or a fact — judged 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
+ * 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.
+ */
+function assertEntry(kind: string, frondName: string, entry: { name: string; schema?: SchemaDescriptor } | undefined): void {
+  if (!entry || typeof entry !== 'object') {
+    throw new Error(`Remote frond '${frondName}' contains an invalid ${kind} entry`);
+  }
+  assertSafeName(kind, entry.name);
+  if (entry.schema === undefined) return;
+  // `ops` is not checked because it is not used: sync writes entities, and the name
+  // and the descriptor below are the only two values that reach a file. The clause
+  // that stood here demanded strings — the shape ops had before they carried their
+  // kind and their views — and so refused every real host. Judge what you consume.
+  const descriptor = entry.schema as unknown;
+  if (
+    !descriptor
+    || typeof descriptor !== 'object'
+    || Array.isArray(descriptor)
+    || (descriptor as SchemaDescriptor).type !== 'object'
+    || !(descriptor as SchemaDescriptor).properties
+    || typeof (descriptor as SchemaDescriptor).properties !== 'object'
+    || Array.isArray((descriptor as SchemaDescriptor).properties)
+    || (descriptor as SchemaDescriptor)['x-fougere-version'] !== 1
+    || (descriptor as SchemaDescriptor)['x-fougere-vendor'] !== 'fougere'
+  ) {
+    throw new Error(`Remote ${kind} '${entry.name}' has no valid schema descriptor`);
+  }
+}
+
+function identityCardOf(value: unknown): IdentityCard {
+  if (!value || typeof value !== 'object' || !Array.isArray((value as IdentityCard).fronds)) {
+    throw new Error('Remote rpc.discover returned an invalid identity card');
+  }
+  const card = value as IdentityCard;
+  for (const frond of card.fronds) {
+    if (!frond || typeof frond !== 'object') {
+      throw new Error('Remote rpc.discover returned an invalid frond entry');
+    }
+    assertSafeName('frond', frond.name);
+    if (!Array.isArray(frond.doors)) {
+      throw new Error(`Remote frond '${frond.name}' has no valid doors array`);
+    }
+    // Absent rather than empty is tolerated: a host older than the fact list says nothing
+    // about facts, and refusing it would break sync against every previous version for a
+    // feature the consumer may not use.
+    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 fact of frond.facts ?? []) assertEntry('fact', frond.name, fact);
+  }
+  return card;
+}
+
+export default class SyncHandler {
+  // cwd is ambient in a CLI — not a DI service (the container resolves by type).
+  private cwd = process.cwd();
+
+  /** Mirror a remote frond's contract into local entities. */
+  async execute(input: { name: string; from: string }): Promise<{ path: string; entities: string[]; removed: string[] }> {
+    assertSafeName('frond', input.name);
+    let remoteUrl: URL;
+    try {
+      remoteUrl = new URL(input.from);
+    } catch {
+      throw new Error(`Invalid remote URL '${input.from}'`);
+    }
+    if (remoteUrl.protocol !== 'http:' && remoteUrl.protocol !== 'https:') {
+      throw new Error(`Remote URL must use http or https, got '${remoteUrl.protocol}'`);
+    }
+    const baseUrl = remoteUrl.toString().replace(/\/$/, '');
+
+    // The served frond answers `rpc.discover` on its call endpoint with its
+    // identity card — the same surface every consumer reads, no side endpoint.
+    const res = await fetch(`${baseUrl}/_fougere/call`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'rpc.discover', params: { params: {}, query: {}, state: {} } }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+      throw new Error(`Failed to reach ${baseUrl}/_fougere/call: ${res.status} ${res.statusText}`);
+    }
+    const rpc = (await res.json()) as { result?: IdentityCard; error?: { message: string } };
+    if (rpc.error) throw new Error(`Remote error: ${rpc.error.message}`);
+    const card = identityCardOf(rpc.result);
+
+    const target = card.fronds.find((f) => f.name === input.name);
+    if (!target) {
+      throw new Error(`Frond '${input.name}' not found on ${baseUrl}. Available: ${card.fronds.map((f) => f.name).join(', ')}`);
+    }
+
+    const frondDir = join(this.cwd, '.fougere', 'remotes', input.name);
+    const entitiesDir = join(frondDir, 'entities');
+    const handlersDir = join(frondDir, 'handlers');
+    mkdirSync(entitiesDir, { recursive: true });
+    mkdirSync(handlersDir, { recursive: true });
+
+    /**
+     * 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
+     * nothing calls a fact).
+     */
+    const generated = new Map<string, { row: boolean; door: 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 });
+      return className;
+    };
+
+    /**
+     * One card, one class.
+     *
+     * `reconstruct` gives the JUDGE — validate, from, getFields — and now takes the
+     * row shape as a type argument, so the same declaration gives the TYPE. Both
+     * come off the same card: nothing to keep in step, and the file a consumer reads
+     * has the shape of the one they would have written by hand
+     * (`class Post extends entity({…}) {}`).
+     */
+    const writeRow = (className: string, descriptor: SchemaDescriptor): void => {
+      written.add(join(entitiesDir, `${className}.ts`));
+      writeFileSync(join(entitiesDir, `${className}.ts`), [
+        `import { reconstruct } from '@fougere/schema';`,
+        ``,
+        `// Generated by \`fougere sync\` from ${baseUrl} — do not edit.`,
+        entitySourceOf(descriptor, { name: className }),
+        ``,
+        `export default ${className};`,
+        ``,
+      ].join('\n'));
+      generated.get(className)!.row = true;
+    };
+
+    for (const { name, schema: descriptor, ops } of target.doors) {
+      const className = claim(name);
+      generated.get(className)!.door = true;
+
+      // No shape behind this door: 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
+       * carried across a repository boundary.
+       *
+       * Writing `Facade<ArticleHandler>` used to require importing the handler's class.
+       * `sync` does not ship handlers and should not: a handler is behaviour with state,
+       * and behaviour does not travel. Its OPERATIONS do — the card names them, says how
+       * much each returns, and that is exactly a signature.
+       */
+      written.add(join(handlersDir, `${className}Handler.ts`));
+      writeFileSync(join(handlersDir, `${className}Handler.ts`), [
+        ...(descriptor !== undefined ? [`import type { ${className} } from '../entities/${className}.js';`, ``] : []),
+        `// Generated by \`fougere sync\` from ${baseUrl} — do not edit.`,
+        `// The shape of an invocation, restated rather than imported: this file is a`,
+        `// contract, and a contract that drags a runtime dependency is not one.`,
+        `type Invocation = { params?: Record<string, string>; query?: Record<string, unknown>; body?: unknown; state?: Record<string, unknown> };`,
+        ``,
+        facadeTypeSourceOf(ops ?? [], {
+          name: `${className}Handler`,
+          ...(descriptor !== undefined ? { rowType: className } : {}),
+        }),
+        ``,
+      ].join('\n'));
+    }
+
+    /**
+     * The facts, which is the only reason a subscriber needs this command at all.
+     *
+     * A fact has no operation, so no façade type is written: a listener spells
+     * `reindex(fact: Fact<PostPublished>)` and the class is the whole of what it needs.
+     * Announced without a declared shape, there is nothing to write — a class built from
+     * a bare name would validate everything, which is worse than the absence.
+     */
+    for (const { name, schema: descriptor } of target.facts ?? []) {
+      const className = claim(name);
+      if (descriptor === undefined) {
+        generated.delete(className);
+        continue;
+      }
+      writeRow(className, descriptor as SchemaDescriptor);
+    }
+
+    // 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 }]) => [
+      ...(row ? [`export { default as ${name} } from './entities/${name}.js';`] : []),
+      ...(door ? [`export type { ${name}Handler } from './handlers/${name}Handler.js';`] : []),
+    ]);
+    writeFileSync(join(frondDir, 'index.ts'), indexLines.join('\n') + '\n');
+
+    // Package.json
+    writeFileSync(join(frondDir, 'package.json'), JSON.stringify({
+      name: `@frond/${input.name}`,
+      version: '0.0.0-synced',
+      type: 'module',
+      fougere: { frond: input.name, synced: true, source: baseUrl },
+      exports: {
+        '.': './index.ts',
+        './entities/*': './entities/*.ts',
+        './handlers/*': './handlers/*.ts',
+        './package.json': './package.json',
+      },
+    }, null, 2) + '\n');
+
+    // Update .fougere/remotes.json — central registry of synced remotes
+    this.updateRemotesRegistry(input.name, baseUrl, frondDir);
+
+    // Update tsconfig paths if tsconfig.json exists (non-Nuxt projects)
+    this.updateTsconfigPaths(input.name, frondDir);
+
+    /**
+     * What the host no longer serves stops being importable here.
+     *
+     * The barrel is rewritten every run, so a dropped entity loses its export on its own
+     * — but the FILE stayed, and the generated `package.json` exports `'./entities/*'` as
+     * a wildcard, so `@frond/blog/entities/Ticket.js` kept resolving to a class nothing
+     * behind it answers for. The consumer compiles, its local judge accepts, and the call
+     * comes back NOT_FOUND at the door — or never leaves, because the page dropped the
+     * call and kept the type.
+     */
+    const removed = [...this.prune(entitiesDir, written), ...this.prune(handlersDir, written)];
+
+    return { path: entitiesDir, entities: [...generated.keys()], removed };
+  }
+
+  /** Delete the files this run did not write — and only the ones sync itself produced. */
+  private prune(dir: string, written: Set<string>): string[] {
+    const dropped: string[] = [];
+    for (const name of readdirSync(dir)) {
+      const path = join(dir, name);
+      if (written.has(path)) continue;
+      // Never remove what sync did not write. The folder is sync's, but a human who put
+      // something there meant it, and a delete is not the place to be clever.
+      if (!readFileSync(path, 'utf-8').includes(GENERATED)) continue;
+      rmSync(path);
+      dropped.push(name);
+    }
+    return dropped;
+  }
+
+  /** Write/update .fougere/remotes.json — read by @fougere/nuxt for auto-aliasing. */
+  private updateRemotesRegistry(name: string, baseUrl: string, localPath: string): void {
+    const registryPath = join(this.cwd, '.fougere', 'remotes.json');
+    let registry: Record<string, { url: string; path: string }> = {};
+
+    if (existsSync(registryPath)) {
+      try {
+        const parsed: unknown = JSON.parse(readFileSync(registryPath, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('expected an object');
+        registry = parsed as Record<string, { url: string; path: string }>;
+      } catch (cause) {
+        throw new Error(`Cannot update corrupt remote registry at ${registryPath}`, { cause });
+      }
+    }
+
+    registry[name] = { url: baseUrl, path: localPath };
+    mkdirSync(join(this.cwd, '.fougere'), { recursive: true });
+    writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');
+  }
+
+  /** Add @frond/{name} to tsconfig paths if tsconfig.json exists. */
+  private updateTsconfigPaths(name: string, localPath: string): void {
+    const tsconfigPath = join(this.cwd, 'tsconfig.json');
+    if (!existsSync(tsconfigPath)) return;
+
+    try {
+      const raw = readFileSync(tsconfigPath, 'utf-8');
+      const tsconfig = JSON.parse(raw);
+
+      // Don't touch Nuxt-managed tsconfigs (extends .nuxt/tsconfig.json)
+      if (tsconfig.extends?.includes('.nuxt/')) return;
+
+      tsconfig.compilerOptions ??= {};
+      tsconfig.compilerOptions.paths ??= {};
+
+      const relative = localPath.replace(this.cwd, '.').replace(/\\/g, '/');
+      tsconfig.compilerOptions.paths[`@frond/${name}`] = [`${relative}/index.ts`];
+      tsconfig.compilerOptions.paths[`@frond/${name}/*`] = [`${relative}/*`];
+
+      writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + '\n');
+    } catch { /* tsconfig parse error — skip */ }
+  }
+}

package/fronds/scaffold/services/ProjectWriter.ts

@@ -0,0 +1,176 @@
+import { cpSync, existsSync, renameSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Scaffolds from real template files (create-vite pattern: stdlib copy, no
+ * token engine). The workspace model composes at every scale:
+ *  - a workspace shell (`workspace/`),
+ *  - fronds added from `fronds/<template>`  (business hexagons),
+ *  - apps added from `apps/<template>`      (consumers: nuxt, cli).
+ * The only per-piece edits are the package names.
+ */
+const TEMPLATES = fileURLToPath(new URL('../../../templates/', import.meta.url));
+
+// npm strips a literal .gitignore from published packages — it ships as
+// _gitignore and the name is restored on copy.
+function restoreGitignore(dir: string): void {
+  const gi = join(dir, '_gitignore');
+  if (existsSync(gi)) renameSync(gi, join(dir, '.gitignore'));
+}
+
+function setPackageName(dir: string, name: string): void {
+  const pkgPath = join(dir, 'package.json');
+  if (!existsSync(pkgPath)) return;
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { name: string };
+  pkg.name = name;
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+}
+
+export default class ProjectWriter {
+  /** The workspace shell — fougere.config, pnpm-workspace (fronds/* apps/*), package.json. */
+  createWorkspace(dir: string, name: string): { path: string } {
+    cpSync(join(TEMPLATES, 'workspace'), dir, { recursive: true });
+    restoreGitignore(dir);
+    setPackageName(dir, name);
+    return { path: dir };
+  }
+
+  /**
+   * The flat shell — one Nuxt app whose root carries the convention, so no `fronds/`
+   * and no workspace. `templates/flat/` is that shell; what separates the two shapes is
+   * only where the domain lands.
+   */
+  createFlat(dir: string, name: string): { path: string } {
+    cpSync(join(TEMPLATES, 'flat'), dir, { recursive: true });
+    restoreGitignore(dir);
+    setPackageName(dir, name);
+    return { path: dir };
+  }
+
+  /**
+   * Put a frond template's directories at the project root. Only the directories: at the
+   * root the app's own `package.json` is the frond's, and `@frond/<name>` comes from the
+   * directory through the Nuxt module's alias, so the template's package would only
+   * duplicate it under a second name.
+   */
+  addRootFrond(dir: string, template: string): { path: string } {
+    const src = join(TEMPLATES, 'fronds', template);
+    for (const entry of readdirSync(src, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      cpSync(join(src, entry.name), join(dir, entry.name), { recursive: true });
+    }
+    return { path: dir };
+  }
+
+  /** Add a frond (business hexagon) under fronds/<name>. */
+  addFrond(wsDir: string, template: string, name: string): { path: string } {
+    const dest = join(wsDir, 'fronds', name);
+    cpSync(join(TEMPLATES, 'fronds', template), dest, { recursive: true });
+    // Only the import name. Carrying the convention is what makes a frond — the scan
+    // reads directories. `fougere.frond` IS read now (`scanner.ts`, `frondNameOf`), but
+    // it renames the contract, which a freshly scaffolded frond has no reason to do.
+    const pkgPath = join(dest, 'package.json');
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { name: string };
+      pkg.name = `@frond/${name}`;
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    }
+    return { path: dest };
+  }
+
+  /** Add an app (consumer) under apps/<name>. */
+  addApp(wsDir: string, template: string, name: string): { path: string } {
+    const dest = join(wsDir, 'apps', name);
+    cpSync(join(TEMPLATES, 'apps', template), dest, { recursive: true });
+    restoreGitignore(dest);
+    setPackageName(dest, name);
+    return { path: dest };
+  }
+
+  /** Available templates of a kind ('fronds' | 'apps') — the directory is the registry. */
+  listTemplates(kind: 'fronds' | 'apps'): string[] {
+    const dir = join(TEMPLATES, kind);
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+  }
+
+  /**
+   * Every app depends on every frond of the workspace — stated once composition is done,
+   * because that is when the names exist.
+   *
+   * A template cannot carry it: the frond is named at composition time (`blog:catalog`),
+   * so a dependency written into `templates/apps/nuxt` would name the template instead
+   * and resolve to nothing. Which is what happened — the generated app imported
+   * `@frond/blog` whatever you had called it, and did not start.
+   *
+   * `fronds/` and `apps/` are the registry, like `listTemplates`: nothing to declare.
+   */
+  linkFronds(wsDir: string): void {
+    const dirs = (kind: string): string[] => {
+      const dir = join(wsDir, kind);
+      if (!existsSync(dir)) return [];
+
+      return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    };
+
+    const fronds = dirs('fronds');
+    if (fronds.length === 0) return;
+
+    for (const app of dirs('apps')) {
+      const pkgPath = join(wsDir, 'apps', app, 'package.json');
+      if (!existsSync(pkgPath)) continue;
+
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { dependencies?: Record<string, string> };
+      pkg.dependencies ??= {};
+      for (const frond of fronds) pkg.dependencies[`@frond/${frond}`] = 'workspace:*';
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    }
+  }
+
+  /**
+   * Dev mode: rewrite every `@fougere/*` dependency in the workspace to a
+   * `link:` into this monorepo, so `pnpm install` resolves offline (the
+   * packages aren't on npm yet). No-op once the packages are published.
+   */
+  linkLocal(wsDir: string): void {
+    const packages = fileURLToPath(new URL('../../../../', import.meta.url));
+    // Read off the monorepo rather than listed here: a hand-kept map knew the seven
+    // packages the default templates use, so the first step beyond the default — a
+    // GraphQL surface, auth — added a dependency it had never heard of, which stayed
+    // on `latest` and broke the install. `@fougere/nuxt` lives in `app/nuxt/` and
+    // `@fougere/transport-http` in `transport/http/`, which is exactly why the name is
+    // read from each package.json instead of guessed from its directory.
+    const dirOf = new Map<string, string>();
+    const scan = (dir: string, depth = 0): void => {
+      for (const e of readdirSync(dir, { withFileTypes: true })) {
+        if (!e.isDirectory() || e.name === 'node_modules') continue;
+        const sub = join(dir, e.name);
+        const pkgPath = join(sub, 'package.json');
+        if (existsSync(pkgPath)) {
+          const { name } = JSON.parse(readFileSync(pkgPath, 'utf8')) as { name?: string };
+          if (name?.startsWith('@fougere/')) dirOf.set(name, sub);
+        } else if (depth === 0) {
+          scan(sub, depth + 1);
+        }
+      }
+    };
+    scan(packages);
+    const walk = (d: string): void => {
+      for (const e of readdirSync(d, { withFileTypes: true })) {
+        if (e.name === 'node_modules') continue;
+        const f = join(d, e.name);
+        if (e.isDirectory()) { walk(f); continue; }
+        if (e.name !== 'package.json') continue;
+        const pkg = JSON.parse(readFileSync(f, 'utf8')) as { dependencies?: Record<string, string> };
+        let changed = false;
+        for (const dep of Object.keys(pkg.dependencies ?? {})) {
+          const local = dirOf.get(dep);
+          if (local) { pkg.dependencies![dep] = `link:${local}`; changed = true; }
+        }
+        if (changed) writeFileSync(f, JSON.stringify(pkg, null, 2) + '\n');
+      }
+    };
+    walk(wsDir);
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@fougere/cli",
+  "version": "0.1.0-alpha.0",
+  "description": "The Fougere CLI — compose a workspace, serve a frond, call an operation.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chok/fougere.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "fougere": "dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "app",
+    "fronds",
+    "templates"
+  ],
+  "dependencies": {
+    "citty": "^0.2.1",
+    "jiti": "^2.4.2",
+    "picocolors": "^1.1.1",
+    "@fougere/cli-ui": "0.1.0-alpha.0",
+    "@fougere/container-fougere": "0.1.0-alpha.0",
+    "@fougere/transport-http": "0.1.0-alpha.0",
+    "@fougere/runtime": "0.1.0-alpha.0",
+    "@fougere/core": "0.1.0-alpha.0",
+    "@fougere/schema": "0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc && chmod +x dist/bin.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.runtime.json && tsc -p tsconfig.templates.json"
+  }
+}

package/templates/admin/fronds/admin/entities/User.ts

@@ -0,0 +1,10 @@
+import { entity, primary, text, email, auto, oneOf, readOnly } from '@fougere/schema';
+
+export default class User extends entity({
+  id: primary(),
+  name: text({ min: 1, max: 100 }),
+  email: email(),
+  createdAt: auto(),
+  // Server-owned: a user is born active and flipped by the deactivate operation.
+  status: readOnly(oneOf('active', 'inactive', { default: 'active' })),
+}) {}

package/templates/admin/fronds/admin/handlers/UserHandler.ts

@@ -0,0 +1,29 @@
+import { Crud, FougereError, ErrorCode } from '@fougere/core';
+import User from '../entities/User.js';
+
+// An Output contract — a read projection of the entity, declared once.
+export class UserCard extends User.pick('id', 'name', 'status') {}
+
+// Crud(User) gives list/create/update/delete for free — the accelerator.
+// 'deactivate' is the business contract: a state transition, not a field write.
+export default class UserHandler extends Crud(User) {
+  /** active→inactive — an operation, not a field write. Judge: active only. */
+  async deactivate(id: string): Promise<User> {
+    const user = await this.orm.findById(id);
+    if (!user) {
+      throw new FougereError({ code: ErrorCode.NOT_FOUND, message: `User '${id}' not found`, entity: 'user', operation: 'deactivate' });
+    }
+    if ((user as { status?: string }).status === 'inactive') {
+      throw new FougereError({ code: ErrorCode.CONFLICT, message: 'Already inactive', entity: 'user', operation: 'deactivate' });
+    }
+    return this.orm.update(id, { status: 'inactive' });
+  }
+
+  /** Active users, projected to the card contract. */
+  async active(): Promise<UserCard[]> {
+    const all = await this.orm.list();
+    return all
+      .filter((u) => (u as { status?: string }).status === 'active')
+      .map((u) => ({ id: String(u.id), name: String(u.name), status: 'active' })) as UserCard[];
+  }
+}

package/templates/admin/fronds/admin/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@frond/admin",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    "./entities/*.js": "./entities/*.ts",
+    "./entities/*": "./entities/*.ts",
+    "./package.json": "./package.json"
+  }
+}

package/templates/api/fronds/api/entities/Task.ts

@@ -0,0 +1,9 @@
+import { entity, primary, text, auto, oneOf, readOnly } from '@fougere/schema';
+
+export default class Task extends entity({
+  id: primary(),
+  title: text({ min: 1, max: 200 }),
+  createdAt: auto(),
+  // Server-owned: a task is born open and flipped by the complete operation.
+  status: readOnly(oneOf('open', 'done', { default: 'open' })),
+}) {}

package/templates/api/fronds/api/handlers/TaskHandler.ts

@@ -0,0 +1,29 @@
+import { Crud, FougereError, ErrorCode } from '@fougere/core';
+import Task from '../entities/Task.js';
+
+// An Output contract — a read projection of the entity, declared once.
+export class TaskCard extends Task.pick('id', 'title', 'status') {}
+
+// Crud(Task) gives list/create/update/delete for free — the accelerator.
+// 'complete' is the business contract: a state transition, not a field write.
+export default class TaskHandler extends Crud(Task) {
+  /** open→done — an operation, not a field write. Judge: open only. */
+  async complete(id: string): Promise<Task> {
+    const task = await this.orm.findById(id);
+    if (!task) {
+      throw new FougereError({ code: ErrorCode.NOT_FOUND, message: `Task '${id}' not found`, entity: 'task', operation: 'complete' });
+    }
+    if ((task as { status?: string }).status === 'done') {
+      throw new FougereError({ code: ErrorCode.CONFLICT, message: 'Already done', entity: 'task', operation: 'complete' });
+    }
+    return this.orm.update(id, { status: 'done' });
+  }
+
+  /** Still-open tasks, projected to the card contract. */
+  async open(): Promise<TaskCard[]> {
+    const all = await this.orm.list();
+    return all
+      .filter((t) => (t as { status?: string }).status === 'open')
+      .map((t) => ({ id: String(t.id), title: String(t.title), status: 'open' })) as TaskCard[];
+  }
+}

package/templates/api/fronds/api/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@frond/api",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    "./entities/*.js": "./entities/*.ts",
+    "./entities/*": "./entities/*.ts",
+    "./package.json": "./package.json"
+  }
+}