@fougere/cli 0.6.0-alpha.0 → 0.8.0-alpha.0

package/src/runner.ts

@@ -1,11 +1,6 @@
 /**
- * CLI runner — scans frond entities for flags, looks for app commands
- * for presentation, dispatches via citty.
- *
- * Architecture:
- * - fronds/  → entities (flags) + handlers (domain logic)
- * - app/     → commands (prompts, TUI, presentation)
- * - src/     → runner + bridge (framework)
+ * CLI runner — scans frond entities for flags, looks for app commands for presentation, dispatches
+ * via citty.
  */
 import type { App } from '@fougere/core';
 import { createAppRunner } from '@fougere/core';
@@ -83,7 +78,7 @@ export async function run(app: App): Promise<void> {
       // App commands handle their own prompting — don't let citty reject missing args
       if (AppCommand) {
         for (const def of Object.values(args)) {
-          if (typeof def === 'object' && def) (def as Record<string, unknown>).required = false;
+          if (typeof def === 'object' && def) def.required = false;
         }
       }
 
@@ -121,15 +116,15 @@ export async function run(app: App): Promise<void> {
               // Ride the call contract — the same envelope every consumer uses.
               await createAppRunner(app)(
                 { entity: lowerFirst(entity.name), op: 'execute' },
-                { params: {}, query: {}, body: input, state: {} },
+                { params: {}, query: {}, input: input, state: {} },
               );
             }
           } catch (err) {
-            const said = err instanceof Error ? err.message : String(err);
+            const message = err instanceof Error ? err.message : String(err);
             // A machine reader parses stdout: a refusal printed there is a refusal that
             // breaks the parse instead of being read. stderr is where it belongs.
-            if (machineOutput) process.stderr.write(said + '\n');
-            else terminal.error(said);
+            if (machineOutput) process.stderr.write(message + '\n');
+            else terminal.error(message);
             process.exit(1);
           }
         },

package/src/typescript/EntityTypes.ts

@@ -0,0 +1,86 @@
+import { upperFirst, type FieldDescriptor, type SchemaDescriptor } from '@fougere/schema';
+import { docCommentOf, propertyKey } from './syntax.js';
+
+/** So a nullable field lands as a union. */
+function typeOf(field: FieldDescriptor): string {
+  const types = Array.isArray(field.type) ? field.type : field.type ? [field.type] : [];
+  const nullable = types.includes('null');
+  const base = types.find((t) => t !== 'null');
+  const inner = baseTypeOf(base, field);
+  return nullable ? `${inner} | null` : inner;
+}
+
+/** So `date-time` becomes a `Date`, the same thing the boundary decodes to. */
+function baseTypeOf(base: string | undefined, field: FieldDescriptor): string {
+  if (field.enum?.length) {
+    return field.enum.map((v) => (v === null ? 'null' : JSON.stringify(v))).join(' | ');
+  }
+  switch (base) {
+    case 'string':
+      return field.format === 'date-time' ? 'Date' : 'string';
+    case 'number':
+    case 'integer':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'array':
+      return field.items ? `${typeOf(field.items)}[]` : 'string[]';
+    case 'object':
+      return field.properties ? objectTypeOf(field.properties, field.required ?? []) : 'Record<string, unknown>';
+    default:
+      return 'unknown';
+  }
+}
+
+/** So a nested object keeps its optionality. */
+function objectTypeOf(properties: Record<string, FieldDescriptor>, required: readonly string[]): string {
+  const members = Object.entries(properties).map(([name, field]) => {
+    const optional = required.includes(name) ? '' : '?';
+    return `${propertyKey(name)}${optional}: ${typeOf(field)}`;
+  });
+  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 ?? {});
+  if (entries.length === 0) return '{}';
+
+  const lines = entries.map(([key, field]) => {
+    const doc = docCommentOf(field.description, `${indent}  `);
+    return `${doc}${indent}  ${propertyKey(key)}: ${typeOf(field)};`;
+  });
+  return `{\n${lines.join('\n')}\n${indent}}`;
+}
+
+export class EntityTypes {
+  private constructor(private readonly descriptor: SchemaDescriptor) {}
+
+  static of(descriptor: SchemaDescriptor): EntityTypes {
+    return new EntityTypes(descriptor);
+  }
+
+  render(options: EntityTypesOptions = {}): string {
+    const name = identifierOf(options.name ?? upperFirst(this.descriptor.title ?? 'Schema'));
+    const exported = options.exported === false ? '' : 'export ';
+    const card = JSON.stringify(this.descriptor, null, 2)
+      .split('\n')
+      .map((line, i) => (i === 0 ? line : `  ${line}`))
+      .join('\n');
+
+    return `${exported}class ${name} extends Card.fromDescriptor<${shapeTypeOf(this.descriptor)}>(${card}).toSchema() {}`;
+  }
+}
+
+/** So a name that cannot declare a class is refused before it reaches a file. */
+function identifierOf(name: string): string {
+  if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) {
+    throw new Error(`'${name}' is not a TypeScript identifier — it cannot name a generated declaration`);
+  }
+  return name;
+}

package/src/typescript/FacadeTypes.ts

@@ -0,0 +1,48 @@
+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';
+}
+
+/** So a consumer sees the cardinality in the type, not in a doc line. */
+function returnTypeOf(op: OpDescriptor, rowType: string): string {
+  switch (op.cardinality) {
+    case 'many': return `${rowType}[]`;
+    case 'page': return `${rowType}[] & { total?: number; endCursor?: string; hasMore?: boolean }`;
+    case 'maybe': return `${rowType} | undefined`;
+    case 'one': return rowType;
+    case 'none': return 'unknown';
+    default: return 'unknown';
+  }
+}
+
+export class FacadeTypes {
+  private constructor(private readonly operations: readonly OpDescriptor[]) {}
+
+  static of(operations: readonly OpDescriptor[]): FacadeTypes {
+    return new FacadeTypes(operations);
+  }
+
+  render(options: FacadeTypesOptions = {}): string {
+    const name = options.name ?? 'Facade';
+    const exported = options.exported === false ? '' : 'export ';
+    const rowType = options.rowType ?? 'unknown';
+    const members = this.operations.map((operation) => {
+      const doc = docCommentOf(operation.description, '  ');
+      return `${doc}  ${propertyKey(operation.name)}(invocation?: Invocation): Promise<${returnTypeOf(operation, rowType)}>;`;
+    });
+
+    if (members.length === 0) return `${exported}interface ${name} {}`;
+    return `${exported}interface ${name} {\n${members.join('\n')}\n}`;
+  }
+}

package/src/typescript/syntax.ts

@@ -0,0 +1,11 @@
+/** So a name that is not an identifier is still written as a key. */
+export function propertyKey(name: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+
+/** So a sentence shows on hover — and cannot close the comment it sits in. */
+export function docCommentOf(text: string | undefined, indent: string): string {
+  if (!text) return '';
+
+  return `${indent}/** ${text.replace(/\*\//g, '*\\/')} */\n`;
+}

package/src/ui.ts

@@ -1,14 +1,4 @@
-/**
- * Fougere CLI UI — beautiful terminal interface.
- *
- * Wraps @clack/prompts + picocolors + consola into a cohesive API.
- *
- * This was `@fougere/cli-ui`, a published package with exactly one consumer —
- * the CLI it is named after. A second name in the registry that nobody would
- * ever install on purpose is a name, not a boundary. Same dependency profile,
- * so it folds in as a module; a subpath export is one line the day something
- * outside the CLI wants it.
- */
+/** Fougere CLI UI — beautiful terminal interface. */
 import * as clack from '@clack/prompts';
 import pc from 'picocolors';
 import { consola } from 'consola';

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

@@ -7,7 +7,7 @@ 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. */
+  /** active→inactive — an operation, not a field write. Validate: active only. */
   async deactivate(id: string): Promise<User> {
     const user = await this.storage.findById(id);
     if (!user) {

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

@@ -7,7 +7,7 @@ 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. */
+  /** open→done — an operation, not a field write. Validate: open only. */
   async complete(id: string): Promise<Task> {
     const task = await this.storage.findById(id);
     if (!task) {

package/templates/blog/app/pages/index.vue

@@ -7,6 +7,6 @@
       <NuxtLink to="/posts/manage">Drafts &amp; publishing</NuxtLink> ·
       <NuxtLink to="/posts/new">New draft</NuxtLink>
     </p>
-    <p class="muted">The loop: create a draft → it stays private → publish it (a judged operation, not a field write) → it appears in the published list, live.</p>
+    <p class="muted">The loop: create a draft → it stays private → publish it (a validated operation, not a field write) → it appears in the published list, live.</p>
   </main>
 </template>

package/templates/blog/app/pages/posts/manage.vue

@@ -1,8 +1,8 @@
 <script setup lang="ts">
 import Post from '@fronds/blog/entities/Post';
 
-interface Row { id: string; title: string; status: 'draft' | 'published' }
-const { items: posts, loading } = await useQuery<Row>(Post, 'list');
+interface PostValues { id: string; title: string; status: 'draft' | 'published' }
+const { items: posts, loading } = await useQuery<PostValues>(Post, 'list');
 const publish = useCommand(Post, 'publish');
 const failed = ref('');
 

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

@@ -7,11 +7,11 @@ import Post from '../entities/Post.js';
 export class PostCard extends Post.pick('id', 'title', 'status') {}
 
 // Crud(Post) gives list/create/update/delete for free — the accelerator.
-// 'publish' is the real business contract: a state transition that judges
+// 'publish' is the real business contract: a state transition that validates
 // before it realises — an operation, not a field write. The golden path.
 export default class PostHandler extends Crud(Post) {
   /**
-   * The draft→published transition. Judge: exists, draft only.
+   * The draft→published transition. Validate: exists, draft only.
    * Realise: the server flips the owned field.
    */
   async publish(id: string): Promise<Post> {

package/templates/flat/CLAUDE.md

@@ -21,15 +21,15 @@ Two consequences worth stating, because they are what makes it hold:
   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.
+  fields — otherwise a new field is validated, 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,
+Every door 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 judge behind it, and the rules declared in the entities stop applying there.
+is a second door with no validator behind it, and the rules declared in the entities stop applying there.
 
 Before adding a surface, reach for its **projection**:
 
@@ -39,7 +39,7 @@ Before adding a surface, reach for its **projection**:
 | GraphQL | `registerAll(builder, app)` then `registerGraphQL(router, builder.toSchema())` — `@fougere/adapter-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`
+projection already derives, and drops the validator on the way. `registerType` / `registerOperations`
 exist to add what a projection cannot derive — never to replace it.
 
 ## Reading data

package/templates/frond/CLAUDE.md

@@ -21,15 +21,15 @@ Two consequences worth stating, because they are what makes it hold:
   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.
+  fields — otherwise a new field is validated, 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,
+Every door 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 judge behind it, and the rules declared in the entities stop applying there.
+is a second door with no validator behind it, and the rules declared in the entities stop applying there.
 
 Before adding a surface, reach for its **projection**:
 
@@ -39,7 +39,7 @@ Before adding a surface, reach for its **projection**:
 | GraphQL | `registerAll(builder, app)` then `registerGraphQL(router, builder.toSchema())` — `@fougere/adapter-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`
+projection already derives, and drops the validator on the way. `registerType` / `registerOperations`
 exist to add what a projection cannot derive — never to replace it.
 
 ## Reading data

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

@@ -1,5 +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. */
+/** The five ops, derived. Redefine one to validate it, add a method to name an operation. */
 export default class ItemHandler extends Crud(Item) {}

package/templates/workspace/CLAUDE.md

@@ -21,15 +21,15 @@ Two consequences worth stating, because they are what makes it hold:
   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.
+  fields — otherwise a new field is validated, 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,
+Every door 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 judge behind it, and the rules declared in the entities stop applying there.
+is a second door with no validator behind it, and the rules declared in the entities stop applying there.
 
 Before adding a surface, reach for its **projection**:
 
@@ -39,7 +39,7 @@ Before adding a surface, reach for its **projection**:
 | GraphQL | `registerAll(builder, app)` then `registerGraphQL(router, builder.toSchema())` — `@fougere/adapter-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`
+projection already derives, and drops the validator on the way. `registerType` / `registerOperations`
 exist to add what a projection cannot derive — never to replace it.
 
 ## Reading data