@fougere/cli 0.2.0-alpha.2 → 0.4.0-alpha.0

package/src/bridge.ts

@@ -0,0 +1,70 @@
+import { Lifecycle, Role } from '@fougere/schema';
+/**
+ * Entity → citty bridge.
+ *
+ * Converts Entity fields into citty ArgsDef.
+ * The Entity IS the CLI definition — no duplicate schema.
+ */
+import type { Fields } from '@fougere/schema';
+import { Anatomy, Visibility } from '@fougere/schema';
+import type { ArgsDef, ArgDef } from 'citty';
+
+function toKebab(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+}
+
+/** 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)) {
+    if (Role.of(field).relation) continue;
+
+    // A `default(v)` travels as the create rule `{ value }` — citty shows it.
+    const defaultValue = Lifecycle.of(field).literal?.value;
+    const { base: shape, nullable } = Anatomy.of(field.shape);
+
+    const kebab = toKebab(key);
+    const def: ArgDef = {
+      description: field.meta?.description,
+      required: !nullable && Lifecycle.of(field).requiredAtCreate,
+    };
+
+    switch (shape?.type) {
+      case 'boolean':
+        (def as Record<string, unknown>).type = 'boolean';
+        if (defaultValue !== undefined) def.default = defaultValue as boolean;
+        break;
+      case 'number':
+      case 'integer':
+      case 'string':
+        // A closed set is citty's `enum`: the shape already names the legal values, so the
+        // refusal and the `--help` listing come from the declaration rather than a check
+        // written beside it.
+        if (shape.type === 'string' && shape.enum?.length) {
+          (def as Record<string, unknown>).type = 'enum';
+          (def as Record<string, unknown>).options = shape.enum.filter((v) => v !== null);
+        // A date-time string stays a named string — never a positional arg.
+        } else if (shape.type === 'string' && shape.format === 'date-time') {
+          (def as Record<string, unknown>).type = 'string';
+        } else if (positionalIndex === 0 && def.required && key !== 'force') {
+          // First non-bool required field becomes positional
+          (def as Record<string, unknown>).type = 'positional';
+          positionalIndex++;
+        } else {
+          (def as Record<string, unknown>).type = 'string';
+        }
+        if (defaultValue !== undefined) def.default = String(defaultValue);
+        break;
+      default:
+        (def as Record<string, unknown>).type = 'string';
+    }
+
+    args[kebab === key ? key : kebab] = def;
+  }
+
+  return args;
+}

package/src/completion.ts

@@ -0,0 +1,152 @@
+/**
+ * Shell completion generator — outputs a script for bash/zsh.
+ *
+ * Commands and flags are the CLI's own entities, read once at generation. The VALUES a
+ * positional accepts belong to the project the shell sits in, so they are not written
+ * down here: the script asks `fougere explain --names` at the moment of the TAB. A list
+ * frozen into a script is stale the first time a handler is added.
+ */
+import type { App } from '@fougere/core';
+import { entityToArgs } from './bridge.js';
+
+function toKebab(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase()).replace(/^-/, '');
+}
+
+/** What a positional names, said by the field's own name — no table to keep in step. */
+const NAMES: Record<string, 'operations' | 'fronds' | undefined> = {
+  operation: 'operations',
+  frond: 'fronds',
+};
+
+interface CommandMeta {
+  name: string;
+  flags: string[];
+  names?: 'operations' | 'fronds';
+}
+
+function extractCommandMeta(app: App): CommandMeta[] {
+  const commands: CommandMeta[] = [];
+
+  for (const frond of app.fronds) {
+    const handlerMap = new Map(frond.handlers.map((h) => [h.address, h]));
+
+    for (const entity of frond.entities) {
+      const handler = handlerMap.get(entity.name);
+      if (!handler) continue;
+
+      let facade: Record<string, Function>;
+      try { facade = app.resolve(handler.name); } catch { continue; }
+      if (typeof facade.execute !== 'function') continue;
+
+      // The same function the runner builds citty's args from, so the positional and the
+      // flags are the ones the command actually has.
+      const args = Object.entries(entityToArgs(entity.entityClass.getFields())) as
+        [string, { type?: string }][];
+      const positional = args.find(([, def]) => def.type === 'positional')?.[0];
+
+      commands.push({
+        name: toKebab(entity.name),
+        flags: args.filter(([, def]) => def.type !== 'positional').map(([key]) => `--${key}`),
+        ...(positional && NAMES[positional] ? { names: NAMES[positional]! } : {}),
+      });
+    }
+  }
+
+  return commands;
+}
+
+export function generateZshCompletion(app: App, binName = 'fougere'): string {
+  const commands = extractCommandMeta(app);
+
+  const valueCases = commands
+    .filter((cmd) => cmd.names)
+    .map((cmd) => `      ${cmd.name}) _${binName}_names ${cmd.names} ;;`)
+    .join('\n');
+
+  const flagCases = commands
+    .map((cmd) => `      ${cmd.name}) flags="${cmd.flags.join(' ')}" ;;`)
+    .join('\n');
+
+  return `# Auto-generated by @fougere/cli
+
+# The project answers; a stale list in this file would not.
+_${binName}_names() {
+  local -a values
+  values=(\${(f)"$(${binName} explain --names $1 2>/dev/null)"})
+  (( \${#values} )) && compadd -- \${values}
+}
+
+_${binName}() {
+  local -a commands flags
+  commands=(${commands.map((c) => `'${c.name}'`).join(' ')})
+
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+
+  local cmd=\${words[2]}
+
+  if [[ "\${words[CURRENT]}" != --* ]]; then
+    case "$cmd" in
+${valueCases}
+    esac
+    return
+  fi
+
+  case "$cmd" in
+${flagCases}
+      *) flags="" ;;
+  esac
+  _values 'flags' \${(s: :)flags}
+}
+
+compdef _${binName} ${binName}
+`;
+}
+
+export function generateBashCompletion(app: App, binName = 'fougere'): string {
+  const commands = extractCommandMeta(app);
+  const cmdNames = commands.map((c) => c.name).join(' ');
+
+  const valueCases = commands
+    .filter((cmd) => cmd.names)
+    .map((cmd) => `      ${cmd.name}) names="${cmd.names}" ;;`)
+    .join('\n');
+
+  const flagCases = commands
+    .map((cmd) => `      ${cmd.name}) COMPREPLY=( $(compgen -W "${cmd.flags.join(' ')}" -- "\${cur}") ) ;;`)
+    .join('\n');
+
+  return `# Auto-generated by @fougere/cli
+_${binName}_completions() {
+  local cur cmd names
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  cmd="\${COMP_WORDS[1]}"
+
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "${cmdNames}" -- "\${cur}") )
+    return
+  fi
+
+  if [[ "\${cur}" != --* ]]; then
+    names=""
+    case "$cmd" in
+${valueCases}
+    esac
+    if [[ -n "\${names}" ]]; then
+      # The project answers; a stale list in this file would not.
+      COMPREPLY=( $(compgen -W "$(${binName} explain --names "\${names}" 2>/dev/null | tr '\\n' ' ')" -- "\${cur}") )
+      return
+    fi
+  fi
+
+  case "$cmd" in
+${flagCases}
+  esac
+}
+
+complete -F _${binName}_completions ${binName}
+`;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { run } from './runner.js';
+export { entityToArgs } from './bridge.js';
+export { generateZshCompletion, generateBashCompletion } from './completion.js';

package/src/loader.ts

@@ -0,0 +1,28 @@
+import {
+  setModuleLoader, loadConfig, resolveConventions, frondAliases,
+} from '@fougere/core/node';
+import type { Conventions } from '@fougere/core/node';
+
+/**
+ * The loader every command needs: `alias` is what makes `@fronds/user/entities/User.js`
+ * resolve when one frond names its neighbour, in any command that loads user code.
+ *
+ * Two jitis, because the config is read BEFORE the aliases — it names the scope they are
+ * built from. `reread` drops the module cache: every loader caches by specifier, so a
+ * second boot in one process would be handed what the first one read.
+ */
+export async function installLoader(root: string, reread = false): Promise<Conventions> {
+  const { createJiti } = await import('jiti');
+  const bare = createJiti(import.meta.url, { interopDefault: true });
+  setModuleLoader((filePath) => bare.import(filePath) as Promise<Record<string, unknown>>);
+
+  const conventions = resolveConventions((await loadConfig(root)).conventions);
+  const jiti = createJiti(import.meta.url, {
+    interopDefault: true,
+    alias: await frondAliases(root, conventions),
+    ...(reread ? { moduleCache: false } : {}),
+  });
+  setModuleLoader((filePath) => jiti.import(filePath) as Promise<Record<string, unknown>>);
+
+  return conventions;
+}

package/src/runner.ts

@@ -0,0 +1,139 @@
+/**
+ * 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)
+ */
+import type { App } from '@fougere/core';
+import { createAppRunner } from '@fougere/core';
+import { lowerFirst } from '@fougere/core/contract';
+import { defineCommand, runMain } from 'citty';
+import { ui } from './ui.js';
+import { entityToArgs } from './bridge.js';
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+function toKebab(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase()).replace(/^-/, '');
+}
+
+function toCamel(kebab: string): string {
+  return kebab.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/** Scan app/commands/ for command classes. */
+async function loadAppCommands(
+  cliRoot: 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 files = await readdir(dir, { withFileTypes: true }).catch(() => []);
+
+  for (const f of files) {
+    if (!f.isFile() || !(f.name.endsWith('.ts') || f.name.endsWith('.js'))) continue;
+    const name = f.name.replace(/Command\.(ts|js)$/, '').replace(/\.(ts|js)$/, '');
+    const kebab = toKebab(name);
+    const mod = await loader(join(dir, f.name));
+    if (mod.default && typeof mod.default === 'function') {
+      map.set(kebab, mod.default);
+    }
+  }
+
+  return map;
+}
+
+export async function run(app: App): Promise<void> {
+  const terminal = ui();
+  const cliRoot = new URL('..', import.meta.url).pathname;
+
+  // Load app commands (presentation layer)
+  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 subCommands: Record<string, ReturnType<typeof defineCommand>> = {};
+
+  for (const frond of app.fronds) {
+    const handlerMap = new Map(frond.handlers.map((h) => [h.address, h]));
+
+    for (const entity of frond.entities) {
+      const handlerEntry = handlerMap.get(entity.name);
+      if (!handlerEntry) continue;
+
+      const handlerName = `${entity.name}Handler`;
+      let handler: Record<string, Function>;
+      try {
+        handler = app.resolve<Record<string, Function>>(handlerName);
+      } catch { continue; }
+
+      if (typeof handler.execute !== 'function') continue;
+
+      const cmdName = toKebab(entity.name);
+      const fields = entity.entityClass.getFields();
+      const args = entityToArgs(fields);
+
+      // Check for an app command (presentation layer)
+      const AppCommand = appCommands.get(cmdName);
+
+      // 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;
+        }
+      }
+
+      subCommands[cmdName] = defineCommand({
+        meta: {
+          name: cmdName,
+          // `--help` reads the operation's own doc sentence, which the scan already
+          // carries for every door (`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,
+        },
+        args,
+        run: async ({ args: parsed }) => {
+          // JSON is a protocol: a branded intro before `{` makes it unparsable. The
+          // explain command owns its machine output and therefore gets a clean stdout.
+          const machineOutput = cmdName === 'explain'
+            && (parsed.json === true || typeof parsed.names === 'string');
+          if (cmdName !== 'completion' && !machineOutput) terminal.intro();
+
+          // citty adds `_` (raw positionals) and `--` (passthrough); strip them
+          // so only the entity's own fields reach the handler.
+          const input = { ...(parsed as Record<string, unknown>) };
+          delete input._;
+          delete input['--'];
+
+          try {
+            if (AppCommand) {
+              const cmd = new (AppCommand as new (...a: unknown[]) => { run: (raw: Record<string, unknown>) => Promise<void> })(app, terminal);
+              await cmd.run(input);
+            } else {
+              // Ride the call contract — the same envelope every consumer uses.
+              await createAppRunner(app)(
+                { entity: lowerFirst(entity.name), op: 'execute' },
+                { params: {}, query: {}, body: input, state: {} },
+              );
+            }
+          } catch (err) {
+            terminal.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+          }
+        },
+      });
+    }
+  }
+
+  const main = defineCommand({
+    meta: { name: 'fougere', description: 'Fougere CLI' },
+    subCommands,
+  });
+
+  await runMain(main);
+}

package/src/theme.ts

@@ -0,0 +1,19 @@
+import pc from 'picocolors';
+
+export interface ThemeColors {
+  brand: (text: string) => string;
+  success: (text: string) => string;
+  error: (text: string) => string;
+  warn: (text: string) => string;
+  muted: (text: string) => string;
+  bold: (text: string) => string;
+}
+
+export const defaultTheme: ThemeColors = {
+  brand: pc.green,
+  success: pc.green,
+  error: pc.red,
+  warn: pc.yellow,
+  muted: pc.dim,
+  bold: pc.bold,
+};

package/src/ui.ts

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ */
+import * as clack from '@clack/prompts';
+import pc from 'picocolors';
+import { consola } from 'consola';
+import { defaultTheme, type ThemeColors } from './theme.js';
+
+export interface UiTheme {
+  colors?: Partial<ThemeColors>;
+}
+
+export function ui(options?: UiTheme) {
+  const c = { ...defaultTheme, ...options?.colors };
+
+  return {
+    // ── Lifecycle ─────────────────────────────────
+
+    /** Start a new CLI session with a branded header. */
+    intro(title = 'Fougere') {
+      clack.intro(c.brand(title));
+    },
+
+    /** End the session with a message. */
+    outro(message: string) {
+      clack.outro(c.success(message));
+    },
+
+    /** Cancel and exit. */
+    cancel(message = 'Cancelled.') {
+      clack.cancel(c.muted(message));
+      process.exit(0);
+    },
+
+    // ── Prompts ───────────────────────────────────
+
+    /** Text input. */
+    async text(opts: { message: string; placeholder?: string; defaultValue?: string; validate?: (value: string) => string | undefined }) {
+      const result = await clack.text(opts);
+      if (clack.isCancel(result)) { this.cancel(); return ''; }
+      return result as string;
+    },
+
+    /** Yes/no confirmation. */
+    async confirm(opts: { message: string; initialValue?: boolean }) {
+      const result = await clack.confirm(opts);
+      if (clack.isCancel(result)) { this.cancel(); return false; }
+      return result as boolean;
+    },
+
+    /** Select one from a list. */
+    async select(opts: {
+      message: string;
+      options: { value: string; label?: string; hint?: string }[];
+      initialValue?: string;
+    }) {
+      const result = await clack.select(opts as Parameters<typeof clack.select>[0]);
+      if (clack.isCancel(result)) { this.cancel(); return ''; }
+      return result as string;
+    },
+
+    /** Multi-select from a list. */
+    async multiselect(opts: {
+      message: string;
+      options: { value: string; label?: string; hint?: string }[];
+      required?: boolean;
+    }) {
+      const result = await clack.multiselect(opts as Parameters<typeof clack.multiselect>[0]);
+      if (clack.isCancel(result)) { this.cancel(); return [] as string[]; }
+      return result as string[];
+    },
+
+    // ── Spinner ───────────────────────────────────
+
+    /** Start a spinner. Returns stop/update functions. */
+    spinner(message?: string) {
+      const s = clack.spinner();
+      s.start(message);
+      return {
+        update: (msg: string) => s.message(msg),
+        stop: (msg?: string) => s.stop(msg),
+      };
+    },
+
+    // ── Output ────────────────────────────────────
+
+    /** Informational message. */
+    info(message: string) {
+      clack.log.info(message);
+    },
+
+    /** Success message. */
+    success(message: string) {
+      clack.log.success(c.success(message));
+    },
+
+    /** Warning message. */
+    warn(message: string) {
+      clack.log.warn(c.warn(message));
+    },
+
+    /** Error message. */
+    error(message: string) {
+      clack.log.error(c.error(message));
+    },
+
+    /** Step indicator. */
+    step(message: string) {
+      clack.log.step(message);
+    },
+
+    /** Note box — multiline content in a box. */
+    note(message: string, title?: string) {
+      clack.note(message, title);
+    },
+
+    // ── Raw colors/consola ────────────────────────
+
+    colors: c,
+    pc,
+    consola,
+  };
+}

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

@@ -13,7 +13,7 @@ export default class UserHandler extends Crud(User) {
     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') {
+    if (user.status === 'inactive') {
       throw new FougereError({ code: ErrorCode.CONFLICT, message: 'Already inactive', entity: 'user', operation: 'deactivate' });
     }
     return this.orm.update(id, { status: 'inactive' });
@@ -21,9 +21,7 @@ export default class UserHandler extends Crud(User) {
 
   /** 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[];
+    const users = await this.orm.list({ where: { status: 'active' } });
+    return users.map(({ id, name, status }) => ({ id, name, status }));
   }
 }

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

@@ -1,5 +1,5 @@
 {
-  "name": "@frond/admin",
+  "name": "@fronds/admin",
   "version": "0.0.1",
   "type": "module",
   "exports": {

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

@@ -13,7 +13,7 @@ export default class TaskHandler extends Crud(Task) {
     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') {
+    if (task.status === 'done') {
       throw new FougereError({ code: ErrorCode.CONFLICT, message: 'Already done', entity: 'task', operation: 'complete' });
     }
     return this.orm.update(id, { status: 'done' });
@@ -21,9 +21,7 @@ export default class TaskHandler extends Crud(Task) {
 
   /** 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[];
+    const tasks = await this.orm.list({ where: { status: 'open' } });
+    return tasks.map(({ id, title, status }) => ({ id, title, status }));
   }
 }

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

@@ -1,5 +1,5 @@
 {
-  "name": "@frond/api",
+  "name": "@fronds/api",
   "version": "0.0.1",
   "type": "module",
   "exports": {

package/templates/apps/nuxt/app/pages/index.vue

@@ -3,7 +3,7 @@
 // They take an ENTITY, so this page names none: what is composed here is yours, and a
 // scaffold that guessed at an entity shipped a page that could not run.
 //
-//   import Post from '@frond/<your-frond>/entities/Post'
+//   import Post from '@fronds/<your-frond>/entities/Post'
 //   const { items, loading } = await useQuery(Post, 'list')
 //   const { values, errors, submit } = useFormFor(Post)
 //   const { execute } = useCommand(Post, 'publish')

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

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import Post from '@frond/blog/entities/Post';
+import Post from '@fronds/blog/entities/Post';
 
 interface Card { id: string; title: string; status: string }
 const { items: posts, loading, error } = await useQuery<Card>(Post, 'published');

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

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import Post from '@frond/blog/entities/Post';
+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');

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

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import Post from '@frond/blog/entities/Post';
+import Post from '@fronds/blog/entities/Post';
 
 const { values, errors, submit, loading, error } = useFormFor(Post);
 

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

@@ -19,7 +19,7 @@ export default class PostHandler extends Crud(Post) {
     if (!post) {
       throw new FougereError({ code: ErrorCode.NOT_FOUND, message: `Post '${id}' not found`, entity: 'post', operation: 'publish' });
     }
-    if ((post as { status?: string }).status === 'published') {
+    if (post.status === 'published') {
       throw new FougereError({ code: ErrorCode.CONFLICT, message: 'Already published', entity: 'post', operation: 'publish' });
     }
     return this.orm.update(id, { status: 'published' });
@@ -27,9 +27,7 @@ export default class PostHandler extends Crud(Post) {
 
   /** Only published posts exist for the outside world, projected to the card. */
   async published(): Promise<PostCard[]> {
-    const all = await this.orm.list();
-    return all
-      .filter((p) => (p as { status?: string }).status === 'published')
-      .map((p) => ({ id: String(p.id), title: String(p.title), status: 'published' })) as PostCard[];
+    const posts = await this.orm.list({ where: { status: 'published' } });
+    return posts.map(({ id, title, status }) => ({ id, title, status }));
   }
 }

package/templates/blog/fronds/blog/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@frond/blog",
+  "name": "@fronds/blog",
   "version": "0.0.1",
   "type": "module",
   "exports": {