@fougere/cli 0.1.0-alpha.0

package/templates/fronds/blank/handlers/ItemHandler.ts

@@ -0,0 +1,5 @@
+import { Crud } from '@fougere/core';
+import Item from '../entities/Item.js';
+
+/** The five ops, derived. Redefine one to judge it, add a method to name an operation. */
+export default class ItemHandler extends Crud(Item) {}

package/templates/fronds/blank/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@frond/__name__",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    "./entities/*.js": "./entities/*.ts",
+    "./entities/*": "./entities/*.ts",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@fougere/schema": "latest",
+    "@fougere/core": "latest"
+  }
+}

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

@@ -0,0 +1,10 @@
+import { entity, primary, text, auto, oneOf, readOnly } from '@fougere/schema';
+
+export default class Post extends entity({
+  id: primary(),
+  title: text({ min: 1, max: 200 }),
+  body: text(),
+  createdAt: auto(),
+  // Server-owned: born a draft, flipped by the publish operation.
+  status: readOnly(oneOf('draft', 'published', { default: 'draft' })),
+}) {}

package/templates/fronds/blog/handlers/PostHandler.ts

@@ -0,0 +1,38 @@
+import { Crud, FougereError, ErrorCode } from '@fougere/core';
+import Post from '../entities/Post.js';
+
+/** What a client may propose when drafting — `status` is not its to write. */
+export class NewPost extends Post.pick('title', 'body') {}
+
+/** What the outside world reads in a list — the body stays home. */
+export class PostCard extends Post.pick('id', 'title', 'status') {}
+
+export default class PostHandler extends Crud(Post) {
+  /**
+   * Crud gives the five ops; this one narrows its contract. `readOnly` already
+   * bars `status` for the whole entity — `NewPost` says what *this* op accepts.
+   */
+  async create(input: NewPost): Promise<Post> {
+    return this.orm.create(input);
+  }
+
+  /** The draft→published transition — an operation, not a field write. */
+  async publish(id: string): Promise<Post> {
+    const post = await this.orm.findById(id);
+    if (!post) {
+      throw new FougereError({ code: ErrorCode.NOT_FOUND, message: `Post '${id}' not found`, entity: 'post', operation: 'publish' });
+    }
+    if (post.status === 'published') {
+      throw new FougereError({ code: ErrorCode.CONFLICT, message: 'Already published', entity: 'post', operation: 'publish' });
+    }
+    return this.orm.update(id, { status: 'published' });
+  }
+
+  /** Only published posts, projected to the card. */
+  async published(): Promise<PostCard[]> {
+    const all = await this.orm.list();
+    return all
+      .filter((p) => p.status === 'published')
+      .map(({ id, title, status }) => ({ id, title, status }));
+  }
+}

package/templates/fronds/blog/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@frond/__name__",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    "./entities/*.js": "./entities/*.ts",
+    "./entities/*": "./entities/*.ts",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@fougere/schema": "latest",
+    "@fougere/core": "latest"
+  }
+}

package/templates/workspace/CLAUDE.md

@@ -0,0 +1,65 @@
+# Working in this application
+
+Built with **Fougere**. This file is read by coding agents before they touch anything — it states
+the few facts that change what they should write.
+
+## One declaration, everything derives
+
+A field belongs to its entity and to nowhere else. Adding it there alone produces the SQL column,
+the validation, the input contract, the write and the output shape. Additive storage changes need no
+hand-written migration; renames, removals and type changes still do. No DTO or permitted-params list
+needs to stay in step.
+
+```ts
+// fronds/<frond>/entities/Product.ts — and nothing else
+sku: text({ min: 3, max: 32 }),
+```
+
+Two consequences worth stating, because they are what makes it hold:
+
+- **An input view derives from the entity** — `Order.omit('id', 'status').extend({ items })`, never
+  a parallel entity that repeats the same fields. A field added to the entity is then accepted
+  without touching the view.
+- **A handler writes what the input carries** (`{ ...attributes }`), it does not enumerate its
+  fields — otherwise a new field is judged, then silently not written.
+
+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
+
+Every door goes through the handler **façade**, which is the judge: validation, unknown-key refusal,
+collectors. A resolver or route you wire yourself against the ORM — or worse, against the database —
+is a second door with no judge behind it, and the rules declared in the entities stop applying there.
+
+Before adding a surface, reach for its **projection**:
+
+| surface | the call |
+|---|---|
+| REST | `generateRoutes(app)` then `registerRoutes(router, routes)` — `@fougere/schema-rest` |
+| GraphQL | `registerAll(builder, app)` then `registerGraphQL(router, builder.toSchema())` — `@fougere/schema-graphql` |
+
+Hand-writing the types (`buildSchema`, raw SDL, one Pothos resolver per field) rebuilds what the
+projection already derives, and drops the judge on the way. `registerType` / `registerOperations`
+exist to add what a projection cannot derive — never to replace it.
+
+## Reading data
+
+`EntityOrm`, injected by type, is the only data access:
+
+```
+list(options?)        every row — `options.where` filters, plus paging and sorting
+findById(id)          one row by id
+findBy(criteria)      one row by criteria      — findBy({ email })
+findAllBy(criteria)   every row of a criteria  — findAllBy({ order_id }) IS a one-to-many relation
+create / update / delete
+```
+
+Read a relation with `findAllBy`. Never read a whole table to filter it in memory.
+
+## Checking your work
+
+```bash
+pnpm typecheck    # the compiler — free, immediate, and it catches most of it
+```
+
+Run it. It is the first judge, and the cheapest.

package/templates/workspace/_gitignore

@@ -0,0 +1,6 @@
+node_modules
+.nuxt
+.output
+.data
+dist
+*.log

package/templates/workspace/fougere.config.ts

@@ -0,0 +1,5 @@
+import type { FougereConfig } from '@fougere/core';
+
+export default {
+  db: { dialect: 'sqlite', path: '.data/app.db' },
+} satisfies FougereConfig;

package/templates/workspace/fronds/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  // A frond is autonomous TypeScript domain code — it typechecks on its own, against
+  // this file, without Nuxt and without `.nuxt/tsconfig.json`. `pnpm typecheck` at the
+  // workspace root runs it, and it is the cheapest judge you have.
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ESNext"],
+    "types": ["node"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": ["."]
+}

package/templates/workspace/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "fougere-workspace",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@11.20.0",
+  "scripts": {
+    "dev": "pnpm --filter './apps/*' --parallel dev",
+    "build": "pnpm --filter './apps/*' -r build",
+    "typecheck": "tsc -p fronds"
+  },
+  "dependencies": {
+    "@fougere/core": "latest",
+    "@fougere/schema": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/workspace/pnpm-workspace.yaml

@@ -0,0 +1,10 @@
+packages:
+  - fronds/*
+  - apps/*
+
+# pnpm 11 fails an install rather than warning about a build script it was not
+# told to run, and it reads the allowlist here — `pnpm.onlyBuiltDependencies` in
+# package.json is the pnpm 10 location, now ignored in silence.
+allowBuilds:
+  better-sqlite3: true
+  esbuild: true