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

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,
+  };
+}