@fougere/cli 0.3.0-alpha.0 → 0.5.0-alpha.0

package/src/runner.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 { machineWanted } from './machine.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;
+
+  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. Read from
+          // the invocation's own args, so any command declaring `json` gets a clean stdout
+          // — naming `explain` here is what let `graph --json` print its decorated box.
+          const machineOutput = machineWanted(parsed as Record<string, unknown>);
+
+          // `completion` is exempt by nature, not by flag: its output IS a shell script,
+          // there is no invocation of it that wants decoration.
+          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) {
+            const said = 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);
+            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/blog/fronds/blog/handlers/PostHandler.ts

@@ -26,7 +26,7 @@ export default class PostHandler extends Crud(Post) {
   }
 
   /** Only published posts exist for the outside world, projected to the card. */
-  async published(): Promise<PostCard[]> {
+  async listPublished(): Promise<PostCard[]> {
     const posts = await this.orm.list({ where: { status: 'published' } });
     return posts.map(({ id, title, status }) => ({ id, title, status }));
   }

package/templates/frond/fronds/__name__/handlers/PostHandler.ts

@@ -17,7 +17,7 @@ export default class PostHandler extends Crud(Post) {
   }
 
   /** Only published posts, projected to the card. */
-  async published(): Promise<PostCard[]> {
+  async listPublished(): Promise<PostCard[]> {
     const posts = await this.orm.list({ where: { status: 'published' } });
     return posts.map(({ id, title, status }) => ({ id, title, status }));
   }

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

@@ -29,7 +29,7 @@ export default class PostHandler extends Crud(Post) {
   }
 
   /** Only published posts, projected to the card. */
-  async published(): Promise<PostCard[]> {
+  async listPublished(): Promise<PostCard[]> {
     const posts = await this.orm.list({ where: { status: 'published' } });
     return posts.map(({ id, title, status }) => ({ id, title, status }));
   }