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

package/fronds/scaffold/handlers/BuildFrondHandler.ts

@@ -8,17 +8,17 @@ export default class BuildFrondHandler {
   private cwd = process.cwd();
 
   /** Build a frond into a standalone deployable package. */
-  async execute(input: { name: string }): Promise<{ path: string; entities: string[] }> {
+  async execute(input: { frond: string }): Promise<{ path: string; entities: string[] }> {
     const conventions = resolveConventions((await loadConfig(this.cwd)).conventions);
-    const frondDir = join(this.cwd, conventions.fronds, input.name);
+    const frondDir = join(this.cwd, conventions.fronds, input.frond);
 
     if (!existsSync(frondDir)) {
-      throw new Error(`Frond '${input.name}' not found at ${frondDir}`);
+      throw new Error(`Frond '${input.frond}' not found at ${frondDir}`);
     }
 
     const entitiesDir = join(frondDir, conventions.dirs.entities);
     if (!existsSync(entitiesDir)) {
-      throw new Error(`No ${conventions.dirs.entities}/ directory in frond '${input.name}'`);
+      throw new Error(`No ${conventions.dirs.entities}/ directory in frond '${input.frond}'`);
     }
 
     // Discover entity files
@@ -67,7 +67,7 @@ export default class BuildFrondHandler {
     const pkgPath = join(frondDir, 'package.json');
     const pkg = existsSync(pkgPath)
       ? JSON.parse(readFileSync(pkgPath, 'utf-8'))
-      : { name: frondPackage(input.name, conventions), version: '0.0.1', type: 'module' };
+      : { name: frondPackage(input.frond, conventions), version: '0.0.1', type: 'module' };
 
     pkg.exports = {
       '.': {

package/fronds/scaffold/handlers/SyncHandler.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
-import { entitySourceOf, facadeTypeSourceOf, type SchemaDescriptor } from '@fougere/schema';
+import { upperFirst, EntityTypeSource, FacadeTypeSource, type SchemaDescriptor } from '@fougere/schema';
 // The card's shape is declared once, in core, and imported here. A private copy of it
 // lived in this file and went stale the day an op stopped being a bare name: nothing
 // compared the copy to the original, so the drift cost nothing until someone read it.
@@ -26,7 +26,7 @@ export function entityClassName(name: string): string {
   const identifier = name
     .split('-')
     .filter(Boolean)
-    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .map(upperFirst)
     .join('');
   if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(identifier)) {
     throw new Error(`Entity name '${name}' cannot be represented as a TypeScript identifier`);
@@ -93,8 +93,8 @@ export default class SyncHandler {
   private cwd = process.cwd();
 
   /** Mirror a remote frond's contract into local entities. */
-  async execute(input: { name: string; from: string }): Promise<{ path: string; entities: string[]; removed: string[] }> {
-    assertSafeName('frond', input.name);
+  async execute(input: { frond: string; from: string }): Promise<{ path: string; entities: string[]; removed: string[] }> {
+    assertSafeName('frond', input.frond);
     let remoteUrl: URL;
     try {
       remoteUrl = new URL(input.from);
@@ -121,9 +121,9 @@ export default class SyncHandler {
     if (rpc.error) throw new Error(`Remote error: ${rpc.error.message}`);
     const card = identityCardOf(rpc.result);
 
-    const target = card.fronds.find((f) => f.name === input.name);
+    const target = card.fronds.find((f) => f.name === input.frond);
     if (!target) {
-      throw new Error(`Frond '${input.name}' not found on ${baseUrl}. Available: ${card.fronds.map((f) => f.name).join(', ')}`);
+      throw new Error(`Frond '${input.frond}' not found on ${baseUrl}. Available: ${card.fronds.map((f) => f.name).join(', ')}`);
     }
 
     // The consumer's own convention: a synced frond is laid out like the ones they wrote,
@@ -132,7 +132,7 @@ export default class SyncHandler {
     const entities = conventions.dirs.entities;
     const handlers = conventions.dirs.handlers;
 
-    const frondDir = join(this.cwd, '.fougere', 'remotes', input.name);
+    const frondDir = join(this.cwd, '.fougere', 'remotes', input.frond);
     const entitiesDir = join(frondDir, entities);
     const handlersDir = join(frondDir, handlers);
     mkdirSync(entitiesDir, { recursive: true });
@@ -158,7 +158,7 @@ export default class SyncHandler {
     /**
      * One card, one class.
      *
-     * `reconstruct` gives the JUDGE — validate, from, getFields — and now takes the
+     * `Card.toSchema` gives the JUDGE — validate, from, getFields — and now takes the
      * row shape as a type argument, so the same declaration gives the TYPE. Both
      * come off the same card: nothing to keep in step, and the file a consumer reads
      * has the shape of the one they would have written by hand
@@ -167,10 +167,10 @@ export default class SyncHandler {
     const writeRow = (className: string, descriptor: SchemaDescriptor): void => {
       written.add(join(entitiesDir, `${className}.ts`));
       writeFileSync(join(entitiesDir, `${className}.ts`), [
-        `import { reconstruct } from '@fougere/schema';`,
+        `import { Card } from '@fougere/schema';`,
         ``,
         `// Generated by \`fougere sync\` from ${baseUrl} — do not edit.`,
-        entitySourceOf(descriptor, { name: className }),
+        EntityTypeSource.of(descriptor).render({ name: className }),
         ``,
         `export default ${className};`,
         ``,
@@ -203,7 +203,7 @@ export default class SyncHandler {
         `// contract, and a contract that drags a runtime dependency is not one.`,
         `type Invocation = { params?: Record<string, string>; query?: Record<string, unknown>; body?: unknown; state?: Record<string, unknown> };`,
         ``,
-        facadeTypeSourceOf(ops ?? [], {
+        FacadeTypeSource.of(ops ?? []).render({
           name: `${className}Handler`,
           ...(descriptor !== undefined ? { rowType: className } : {}),
         }),
@@ -239,10 +239,10 @@ export default class SyncHandler {
 
     // Package.json
     writeFileSync(join(frondDir, 'package.json'), JSON.stringify({
-      name: frondPackage(input.name, conventions),
+      name: frondPackage(input.frond, conventions),
       version: '0.0.0-synced',
       type: 'module',
-      fougere: { frond: input.name, synced: true, source: baseUrl },
+      fougere: { frond: input.frond, synced: true, source: baseUrl },
       exports: {
         '.': './index.ts',
         [`./${entities}/*`]: `./${entities}/*.ts`,
@@ -251,11 +251,11 @@ export default class SyncHandler {
       },
     }, null, 2) + '\n');
 
-    // Update .fougere/remotes.json — central registry of synced remotes
-    this.updateRemotesRegistry(input.name, baseUrl, frondDir);
+    // .fougere/remotes.json is the central registry of synced remotes.
+    this.updateRemotesRegistry(input.frond, baseUrl, frondDir);
 
-    // Update tsconfig paths if tsconfig.json exists (non-Nuxt projects)
-    this.updateTsconfigPaths(input.name, frondDir, conventions);
+    // Non-Nuxt projects only: Nuxt writes its own paths.
+    this.updateTsconfigPaths(input.frond, frondDir, conventions);
 
     /**
      * What the host no longer serves stops being importable here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/cli",
-  "version": "0.3.0-alpha.0",
+  "version": "0.5.0-alpha.0",
   "description": "The Fougere CLI — compose a workspace, serve a frond, call an operation.",
   "keywords": [
     "fougere",
@@ -32,7 +32,8 @@
     "dist",
     "app",
     "fronds",
-    "templates"
+    "templates",
+    "src"
   ],
   "dependencies": {
     "@clack/prompts": "^0.10.0",
@@ -40,12 +41,12 @@
     "consola": "^3.4.2",
     "jiti": "^2.4.2",
     "picocolors": "^1.1.1",
-    "@fougere/container": "0.3.0-alpha.0",
-    "@fougere/schema": "0.3.0-alpha.0",
-    "@fougere/adapter-sql": "0.3.0-alpha.0",
-    "@fougere/transport-http": "0.3.0-alpha.0",
-    "@fougere/core": "0.3.0-alpha.0",
-    "@fougere/defaults": "0.3.0-alpha.0"
+    "@fougere/adapter-sql": "0.5.0-alpha.0",
+    "@fougere/core": "0.5.0-alpha.0",
+    "@fougere/container": "0.5.0-alpha.0",
+    "@fougere/schema": "0.5.0-alpha.0",
+    "@fougere/defaults": "0.5.0-alpha.0",
+    "@fougere/transport-http": "0.5.0-alpha.0"
   },
   "devDependencies": {
     "vitest": "^4.1.0"

package/src/bin.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * fougere CLI — a Fougere app powered by citty.
+ *
+ * src/   → compiled (tsc → dist/)
+ * fronds/ → loaded at runtime by jiti (domain)
+ * app/   → loaded at runtime by jiti (presentation)
+ */
+import { createApp, setLogLevel, envLevel, type ScanResult } from '@fougere/core';
+import { scanProject, getModuleLoader, frondDirsOf, DEFAULT_CONVENTIONS } from '@fougere/core/node';
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createContainer } from '@fougere/container';
+import { ui } from './ui.js';
+import { run } from './runner.js';
+import { installLoader } from './loader.js';
+
+await installLoader(process.cwd());
+
+const cliRoot = new URL('..', import.meta.url).pathname;
+const container = createContainer();
+const terminal = ui();
+container.registerValue('ui', terminal);
+container.registerValue('cwd', process.cwd());
+
+// The CLI is a Fougere app — silence its boot chatter unless explicitly asked. The
+// threshold is SET, not only announced: a static import evaluates the logger module,
+// its env read included, before this line runs.
+process.env.FOUGERE_LOG_LEVEL ??= 'warn';
+setLogLevel(envLevel() ?? 'warn');
+
+/** The newest declaration under `fronds/`, or 0 when there is none to compare against. */
+async function newestDeclaration(root: string): Promise<number> {
+  const frondsDir = join(root, DEFAULT_CONVENTIONS.fronds);
+  const names = await readdir(frondsDir, { withFileTypes: true }).catch(() => []);
+  const dirs = names.filter((entry) => entry.isDirectory())
+    .flatMap((entry) => [
+      join(frondsDir, entry.name),
+      ...frondDirsOf(DEFAULT_CONVENTIONS).map((dir) => join(frondsDir, entry.name, dir)),
+    ]);
+
+  const times = await Promise.all(dirs.map(async (dir) => {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const stats = await Promise.all(entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.ts'))
+      .map((entry) => stat(join(dir, entry.name)).then((s) => s.mtimeMs).catch(() => 0)));
+    return Math.max(0, ...stats);
+  }));
+  return Math.max(0, ...times);
+}
+
+/**
+ * The CLI is a Fougere app, so it reads its own written-down scan like any deployment —
+ * producing the description reads the project, consuming it does not.
+ *
+ * Reading its own 44 declarations through the compiler cost 617 ms on every invocation,
+ * for a domain fixed at publish time. Staleness is decided by mtime rather than by a flag:
+ * editing a frond must not need a command, and a published package has nothing newer than
+ * its artefact.
+ */
+async function scanOf(root: string): Promise<ScanResult> {
+  const written = join(root, '.fougere/scan.generated.ts');
+  const writtenAt = await stat(written).then((s) => s.mtimeMs).catch(() => 0);
+  if (writtenAt > 0 && writtenAt >= await newestDeclaration(root)) {
+    return ((await getModuleLoader()(written)) as unknown as { scan: ScanResult }).scan;
+  }
+
+  // The only slow phase, and it announced nothing: the boot states it at `info`, which the
+  // threshold above lowers to `warn`. The terminal says it instead, and a pipe keeps its
+  // output parsable.
+  const spin = process.stdout.isTTY ? terminal.spinner('reading fronds') : undefined;
+  const scan = await scanProject(root);
+  spin?.stop(`${scan.fronds.length} frond(s)`);
+  return scan;
+}
+
+const scan = await scanOf(cliRoot);
+
+const app = await createApp({ scan, createContainer: () => container });
+
+container.registerValue('app', app);
+
+await run(app);

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/machine.ts

@@ -0,0 +1,23 @@
+/**
+ * A command's machine output — the one shape a pipe reads.
+ *
+ * There is no list of commands here: `json` is declared by an entity like any other
+ * field, so a command that declares it gets the door. The runner used to name `explain`
+ * in an `if`, and `graph --json` announced a flag it then ignored.
+ */
+export function machineWanted(raw: Record<string, unknown>): boolean {
+  return raw.json === true || typeof raw.names === 'string';
+}
+
+/**
+ * A `Map` serializes to `{}`, so the door converts it rather than each command flattening
+ * its own result: `GraphResult.nodes` is a Map, and `graph --json` would have printed a
+ * report with an empty graph in it.
+ */
+export function machineText(value: unknown): string {
+  return JSON.stringify(value, (_key, held) => (held instanceof Map ? Object.fromEntries(held) : held), 2);
+}
+
+export function printMachine(value: unknown): void {
+  process.stdout.write(machineText(value) + '\n');
+}