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

package/README.md

@@ -23,4 +23,4 @@ pnpm add @fougere/cli
 
 Part of [Fougere](https://github.com/chok/fougere) — one schema, a gradient from
 monolith to distributed, the same user code.
-Reference documentation: [the site](https://chok.github.io/fougere/) (en/fr).
+Reference documentation: [the site](https://fougere.dev/) (en/fr).

package/app/commands/BuildCommand.ts

@@ -3,6 +3,7 @@ import type { App } from '@fougere/core';
 import type { ui as createUi } from '../../src/ui.js';
 import type { BuildReport } from '../../fronds/analysis/handlers/BuildHandler.js';
 import pc from 'picocolors';
+import { machineWanted, printMachine } from '../../src/machine.js';
 
 type Ui = ReturnType<typeof createUi>;
 
@@ -22,6 +23,8 @@ export default class BuildCommand {
       { params: {}, query: {}, body: raw, state: {} },
     )) as BuildReport;
 
+    if (machineWanted(raw)) return printMachine(built);
+
     if (built.fronds.length === 0) {
       this.ui.warn('No fronds found. Run this from a Fougere project root.');
       return;

package/app/commands/CallCommand.ts

@@ -1,5 +1,5 @@
 import { createAppRunner } from '@fougere/core';
-import { registrationKeyOf } from '@fougere/core/contract';
+import { lowerFirst } from '@fougere/core/contract';
 import { bootAppFromConfig } from '@fougere/defaults';
 import type { App } from '@fougere/core';
 import type { ui as createUi } from '../../src/ui.js';
@@ -36,7 +36,7 @@ export default class CallCommand {
   constructor(private app: App, private ui: Ui) {}
 
   async run(raw: Record<string, unknown>) {
-    const target = raw.target as string | undefined;
+    const target = raw.operation as string | undefined;
     if (!target || !target.includes('.')) {
       this.ui.error('Usage: fougere call <entity>.<op> [--field value …]');
       return;
@@ -57,7 +57,7 @@ export default class CallCommand {
     const app = await bootAppFromConfig(process.cwd(), {});
     try {
       const result = await createAppRunner(app)(
-        { entity: registrationKeyOf(entityName), op },
+        { entity: lowerFirst(entityName), op },
         { params, query: {}, body, state: {} },
       );
       this.ui.note(JSON.stringify(result, null, 2), target);

package/app/commands/CheckCommand.ts

@@ -4,6 +4,7 @@ import { createAppRunner } from '@fougere/core';
 import type { ui as createUi } from '../../src/ui.js';
 import pc from 'picocolors';
 import { relative } from 'node:path';
+import { machineWanted, printMachine } from '../../src/machine.js';
 
 type Ui = ReturnType<typeof createUi>;
 
@@ -17,6 +18,13 @@ export default class CheckCommand {
       { params: {}, query: {}, body: raw, state: {} },
     ) as CheckResult;
 
+    // A non-zero exit is what makes this usable in CI, so it is decided before the two
+    // renderings rather than inside the terminal one.
+    const blocking = result.findings.filter((f) => f.severity === 'blocking').length;
+    if (blocking > 0) process.exitCode = 1;
+
+    if (machineWanted(raw)) return printMachine(result);
+
     if (result.fronds === 0) {
       this.ui.warn('No fronds found. Run this from a Fougere project root.');
       return;
@@ -31,14 +39,9 @@ export default class CheckCommand {
 
     this.ui.note(result.findings.map(render).join('\n\n'), 'Findings');
 
-    const blocking = result.findings.filter((f) => f.severity === 'blocking').length;
-    const warnings = result.findings.length - blocking;
-    this.ui.info(`${blocking} blocking, ${warnings} warning(s)`);
-
-    // A non-zero exit is what makes this usable in CI. Warnings do not fail:
-    // an unresolvable base class with no operation is ordinary, and a check that
-    // cries wolf stops being read.
-    if (blocking > 0) process.exitCode = 1;
+    // Warnings do not fail: an unresolvable base class with no operation is ordinary,
+    // and a check that cries wolf stops being read.
+    this.ui.info(`${blocking} blocking, ${result.findings.length - blocking} warning(s)`);
   }
 }
 

package/app/commands/DevtoolsCommand.ts

@@ -0,0 +1,92 @@
+import { createAppRunner } from '@fougere/core';
+import type { App, CallRecord } from '@fougere/core';
+import type { CallsView } from '../../fronds/analysis/handlers/DevtoolsHandler.js';
+import type { ui as createUi } from '../../src/ui.js';
+import { machineWanted, printMachine } from '../../src/machine.js';
+import pc from 'picocolors';
+
+type Ui = ReturnType<typeof createUi>;
+
+/** How long between two reads. Fast enough to read as a stream, cheap enough to ignore. */
+const EVERY_MS = 500;
+
+const ROUTE = { local: pc.green, remote: pc.cyan, system: pc.magenta } as const;
+
+/**
+ * `fougere devtools` — the call log of every running app of this project, followed.
+ *
+ * A cursor per address, because each app numbers its own ring: asking for what this reader
+ * has not seen is the whole protocol, and it is per source or nothing.
+ */
+export default class DevtoolsCommand {
+  constructor(private app: App, private ui: Ui) {}
+
+  async run(raw: Record<string, unknown>) {
+    const since: Record<string, number> = {};
+
+    if (machineWanted(raw)) return printMachine(await this.view(raw, since));
+
+    const first = await this.view(raw, since);
+    this.announce(first);
+
+    const told: Record<string, number> = {};
+    for (let view = first; ; view = await this.view(raw, since)) {
+      for (const source of view.sources) {
+        since[source.url] = source.cursor;
+
+        // Said once per address, and only when it grows: a ring that dropped is not a
+        // quiet period, and repeating it every half second would bury the calls.
+        if (source.dropped > (told[source.url] ?? 0)) {
+          this.ui.warn(`${source.url} dropped ${source.dropped - (told[source.url] ?? 0)} call(s) — its ring is smaller than this traffic`);
+          told[source.url] = source.dropped;
+        }
+      }
+
+      for (const call of view.calls) process.stdout.write(render(call, view.sources.length > 1) + '\n');
+      await new Promise((wake) => setTimeout(wake, EVERY_MS));
+    }
+  }
+
+  /** What is being watched, and what refused — stated before the first line scrolls. */
+  private announce(view: CallsView): void {
+    for (const source of view.sources) {
+      const name = source.frond ? `${pc.bold(source.frond)} ${pc.dim(source.url)}` : pc.bold(source.url);
+      if (source.refusal) this.ui.warn(`${name} — ${source.refusal}`);
+      else this.ui.step(`following ${name}`);
+    }
+    this.ui.info(pc.dim('ctrl-c to stop'));
+  }
+
+  private view(raw: Record<string, unknown>, since: Record<string, number>): Promise<CallsView> {
+    return createAppRunner(this.app)(
+      { entity: 'devtools', op: 'execute' },
+      { params: {}, query: {}, body: { ...raw, since }, state: {} },
+    ) as Promise<CallsView>;
+  }
+}
+
+function render(call: CallRecord & { source: string }, many: boolean): string {
+  // Padded BEFORE colouring: an escape sequence counts in a string's length, so padding a
+  // coloured value moves the column by however many bytes the colour took.
+  const at = many ? pc.dim(pad(new URL(call.source).port || call.source, 5)) : '';
+  const frond = pc.dim(pad(call.frond ?? '—', 9));
+  const address = pc.bold(pad(`${call.entity}.${call.operation}${call.surface ? `/${call.surface}` : ''}`, 22));
+  const route = call.route
+    ? (ROUTE[call.route] ?? pc.dim)(pad(call.route, 9))
+    : pc.red(pad('unrouted', 9));
+  const took = pc.dim(lead(call.ms === undefined ? '' : `${call.ms}ms`, 7));
+  const verdict = call.verdict === 'failed'
+    ? pc.red(call.refusal?.code ?? 'failed')
+    : call.verdict === 'ok' ? pc.dim('ok') : pc.yellow('running');
+
+  return [at, frond, address, route, took, verdict, call.trace ? pc.dim(call.trace.slice(3, 11)) : '']
+    .filter(Boolean).join(' ');
+}
+
+function pad(value: string, width: number): string {
+  return value.length >= width ? value : value + ' '.repeat(width - value.length);
+}
+
+function lead(value: string, width: number): string {
+  return value.length >= width ? value : ' '.repeat(width - value.length) + value;
+}

package/app/commands/ExplainCommand.ts

@@ -3,9 +3,11 @@ import { createAppRunner } from '@fougere/core';
 import type { ui as createUi } from '../../src/ui.js';
 import type {
   ExplainResult,
+  ExplainListing,
   ExplainedBinding,
 } from '../../fronds/analysis/handlers/ExplainHandler.js';
 import pc from 'picocolors';
+import { machineText, printMachine } from '../../src/machine.js';
 
 type Ui = ReturnType<typeof createUi>;
 
@@ -13,22 +15,48 @@ export default class ExplainCommand {
   constructor(private app: App, private ui: Ui) {}
 
   async run(raw: Record<string, unknown>) {
-    const result = await createAppRunner(this.app)(
-      { entity: 'explain', op: 'execute' },
-      { params: {}, query: {}, body: raw, state: {} },
-    ) as ExplainResult;
+    const names = raw.names as 'operations' | 'fronds' | undefined;
+    const operation = (raw.operation as string | undefined)?.trim();
+
+    // No operation named — the question is what this project serves at all. The same
+    // model answers both, so the door is the one that was asked, never a guess.
+    if (names || !operation) return this.listing(raw, names);
+
+    const result = await this.ask('execute', raw) as ExplainResult;
+
+    if (raw.json === true) return printMachine(result);
+
+    this.ui.note(renderExplain(result), result.operation);
+  }
+
+  private async listing(raw: Record<string, unknown>, names?: 'operations' | 'fronds') {
+    const listing = await this.ask('list', raw) as ExplainListing;
 
-    if (raw.json === true) {
-      process.stdout.write(renderExplainJson(result) + '\n');
+    // A completion script has no JSON parser: one name per line, nothing else on stdout.
+    if (names) {
+      const values = names === 'fronds'
+        ? listing.fronds.map((frond) => frond.name)
+        : listing.operations;
+      if (values.length > 0) process.stdout.write(values.join('\n') + '\n');
       return;
     }
 
-    this.ui.note(renderExplain(result), result.operation);
+    if (raw.json === true) return printMachine(listing);
+
+    this.ui.note(renderListing(listing), 'what this project serves');
+  }
+
+  private ask(op: string, raw: Record<string, unknown>) {
+    return createAppRunner(this.app)(
+      { entity: 'explain', op },
+      { params: {}, query: {}, body: raw, state: {} },
+    );
   }
 }
 
+/** Kept as the name `tests/explain.test.ts` pins the key order through. */
 export function renderExplainJson(result: ExplainResult): string {
-  return JSON.stringify(result, null, 2);
+  return machineText(result);
 }
 
 export function renderExplain(result: ExplainResult): string {
@@ -66,6 +94,21 @@ export function renderExplain(result: ExplainResult): string {
   return lines.join('\n');
 }
 
+export function renderListing(listing: ExplainListing): string {
+  const lines = [pc.bold('Fronds')];
+  if (listing.fronds.length === 0) lines.push('  —');
+  for (const frond of listing.fronds) {
+    const where = frond.remote ? `remote ${pc.dim(frond.remote)}` : 'local';
+    lines.push(`  ${frond.name} ${pc.dim('→')} ${where}, ${frond.operations} operation(s)`);
+  }
+
+  lines.push('', pc.bold('Operations'));
+  if (listing.operations.length === 0) lines.push('  —');
+  for (const operation of listing.operations) lines.push(`  ${operation}`);
+
+  return lines.join('\n');
+}
+
 function bindingName(binding: ExplainedBinding | null): string {
   if (!binding) return 'unbound';
   switch (binding.kind) {

package/app/commands/FreezeCommand.ts

@@ -4,6 +4,7 @@ import type { App } from '@fougere/core';
 import type { ui as createUi } from '../../src/ui.js';
 import type { FreezeInspection } from '../../fronds/analysis/handlers/FreezeHandler.js';
 import pc from 'picocolors';
+import { machineWanted, printMachine } from '../../src/machine.js';
 
 type Ui = ReturnType<typeof createUi>;
 
@@ -30,6 +31,10 @@ export default class FreezeCommand {
     // otherwise — so the first call is both the inspection and the happy path.
     const seen = await freeze(raw);
 
+    // The question below cannot be put to a machine, so the inspection is the answer:
+    // `ambiguous` says what a human still has to settle, and nothing was written.
+    if (machineWanted(raw)) return printMachine(seen);
+
     if (seen.entities.length === 0) {
       this.ui.warn('No entities found. Run this from a Fougere project root.');
       return;
@@ -74,7 +79,7 @@ export default class FreezeCommand {
           this.ui.warn(`${entity}.${removed} treated as dropped — say so explicitly if that is right.`);
           return undefined;
         }
-        renamed[entity] = { ...(renamed[entity] ?? {}), [removed]: answer };
+        renamed[entity] = { ...renamed[entity], [removed]: answer };
       }
     }
     return renamed;

package/app/commands/GraphCommand.ts

@@ -3,6 +3,7 @@ import type { EntityNode, DomainCluster, App } from '@fougere/core';
 import { createAppRunner } from '@fougere/core';
 import type { ui as createUi } from '../../src/ui.js';
 import pc from 'picocolors';
+import { machineWanted, printMachine } from '../../src/machine.js';
 
 type Ui = ReturnType<typeof createUi>;
 
@@ -16,6 +17,8 @@ export default class GraphCommand {
       { params: {}, query: {}, body: raw, state: {} },
     ) as GraphResult;
 
+    if (machineWanted(raw)) return printMachine(result);
+
     if (result.fronds.length === 0) {
       this.ui.warn('No fronds found. Run this from a Fougere project root.');
       return;

package/app/commands/KeysCommand.ts

@@ -36,7 +36,7 @@ export default class KeysCommand {
 
     this.ui.success(`root created — ${ROOT_KEY} (never commit it; added to .gitignore)`);
     this.ui.note(
-      `FOUGERE_ROOT=${packed(publicKey)}`,
+      `FOUGERE_ROOT_KEY=${packed(publicKey)}`,
       'Every frond that ANSWERS — public, safe in an image or a manifest',
     );
     this.ui.info('Then `fougere grant <frond>` for each frond that CALLS.');

package/app/commands/MigrateCommand.ts

@@ -3,6 +3,7 @@ import type { App } from '@fougere/core';
 import type { ui as createUi } from '../../src/ui.js';
 import type { MigrationPlan } from '../../fronds/analysis/handlers/MigrateHandler.js';
 import pc from 'picocolors';
+import { machineWanted, printMachine } from '../../src/machine.js';
 
 type Ui = ReturnType<typeof createUi>;
 
@@ -21,6 +22,8 @@ export default class MigrateCommand {
       { params: {}, query: {}, body: raw, state: {} },
     )) as MigrationPlan;
 
+    if (machineWanted(raw)) return printMachine(result);
+
     if (result.chain.length === 0) {
       this.ui.warn('No frozen step to apply. `fougere freeze <version>` records one.');
       return;

package/app/commands/ServeCommand.ts

@@ -1,5 +1,7 @@
 import { createLocalRunner, identityFromEnv } from '@fougere/core';
-import { setModuleLoader, loadConfig, resolveConventions, watchPathsOf } from '@fougere/core/node';
+import { watchPathsOf } from '@fougere/core/node';
+import { installLoader } from '../../src/loader.js';
+import type { Conventions } from '@fougere/core/node';
 import { bootAppFromConfig } from '@fougere/defaults';
 import { serve } from '@fougere/transport-http';
 import { watch } from 'node:fs';
@@ -14,16 +16,6 @@ const DRAIN_MS = 5_000;
 /** One save fires several events; the boot must not start once per event. */
 const SETTLE_MS = 60;
 
-/**
- * A loader that re-reads. Every loader caches by specifier, so a second boot in this
- * process would be handed the modules the first one read — a reload that changes nothing.
- */
-async function rereadingLoader(): Promise<void> {
-  const { createJiti } = await import('jiti');
-  const jiti = createJiti(import.meta.url, { interopDefault: true, moduleCache: false });
-  setModuleLoader((filePath) => jiti.import(filePath) as Promise<Record<string, unknown>>);
-}
-
 /**
  * The host end of the gradient: one frond, alone in this process, reachable
  * over HTTP. `topology: false` — a served frond IS the host, it never routes
@@ -40,8 +32,9 @@ export default class ServeCommand {
     const root = process.cwd();
     const watching = raw.watch === true;
 
-    // Cache-free from the FIRST boot, so every boot in this process reads the same way.
-    if (watching) await rereadingLoader();
+    // Cache-free from the FIRST boot when watching, so every boot in this process reads
+    // the same way rather than the first one being special.
+    const conventions = await installLoader(root, watching);
 
     let hosted = await bootAppFromConfig(root, { fronds: [frond], topology: false });
     if (!hosted.fronds.some((f) => f.name === frond)) {
@@ -59,7 +52,7 @@ export default class ServeCommand {
     const { verify, requireIdentity } = await identityFromEnv();
     const { port: bound } = await serve((call, inv) => current(call, inv), { port, verify, requireIdentity });
     this.ui.step(`frond ${frond} servie — POST http://127.0.0.1:${bound}/_fougere/call`);
-    this.ui.info(requireIdentity ? 'signed calls only (FOUGERE_ROOT is set)' : 'unsigned calls accepted — no FOUGERE_ROOT');
+    this.ui.info(requireIdentity ? 'signed calls only (FOUGERE_ROOT_KEY is set)' : 'unsigned calls accepted — no FOUGERE_ROOT_KEY');
 
     if (!watching) {
       this.ui.info('Ctrl-C pour arrêter.');
@@ -88,8 +81,6 @@ export default class ServeCommand {
       await previous.dispose();
     };
 
-    const config = await loadConfig(root);
-    const conventions = resolveConventions(config.conventions);
     let settling: NodeJS.Timeout | undefined;
     let watched = 0;
 

package/dist/bin.js

@@ -7,15 +7,14 @@
  * app/   → loaded at runtime by jiti (presentation)
  */
 import { createApp, setLogLevel, envLevel } from '@fougere/core';
-import { scanProject, setModuleLoader, frondDirsOf, DEFAULT_CONVENTIONS } from '@fougere/core/node';
+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';
-const { createJiti } = await import('jiti');
-const jiti = createJiti(import.meta.url, { interopDefault: true });
-setModuleLoader((filePath) => jiti.import(filePath));
+import { installLoader } from './loader.js';
+await installLoader(process.cwd());
 const cliRoot = new URL('..', import.meta.url).pathname;
 const container = createContainer();
 const terminal = ui();
@@ -57,7 +56,7 @@ async function scanOf(root) {
     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 jiti.import(written)).scan;
+        return (await getModuleLoader()(written)).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

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAmB,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACpG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,aAAa,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;AAEnC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;AACxD,MAAM,SAAS,GAAG,eAAe,EAAE,CAAC;AACpC,MAAM,QAAQ,GAAG,EAAE,EAAE,CAAC;AACtB,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACxC,SAAS,CAAC,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;AAE9C,mFAAmF;AACnF,qFAAqF;AACrF,gDAAgD;AAChD,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,MAAM,CAAC;AACzC,WAAW,CAAC,QAAQ,EAAE,IAAI,MAAM,CAAC,CAAC;AAElC,0FAA0F;AAC1F,KAAK,UAAU,iBAAiB,CAAC,IAAY;IAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAChF,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;SACtD,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;QAClB,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC;QAC3B,GAAG,WAAW,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;KACnF,CAAC,CAAC;IAEL,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACrD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QAC5E,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO;aACpC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;aAC/D,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC,CAAC;IACJ,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,MAAM,CAAC,IAAY;IAChC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,4BAA4B,CAAC,CAAC;IACzD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5E,IAAI,SAAS,GAAG,CAAC,IAAI,SAAS,IAAI,MAAM,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;QAChE,OAAQ,CAAC,MAAM,eAAe,EAAE,CAAC,OAAO,CAAC,CAAqC,CAAC,IAAI,CAAC;IACtF,CAAC;IAED,yFAAyF;IACzF,uFAAuF;IACvF,mBAAmB;IACnB,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACnF,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,WAAW,CAAC,CAAC;IAC7C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;AAEnC,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC;AAExE,SAAS,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAEpC,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC"}

package/dist/bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,KAAK,EAAE,OAAO,EAAU,MAAM,OAAO,CAAC;AAM7C,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CA+CpD"}
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,KAAK,EAAE,OAAO,EAAU,MAAM,OAAO,CAAC;AAM7C,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAqDpD"}

package/dist/bridge.js

@@ -1,5 +1,5 @@
 import { Lifecycle, Role } from '@fougere/schema';
-import { Anatomy, inputFields } from '@fougere/schema';
+import { Anatomy, Visibility } from '@fougere/schema';
 function toKebab(name) {
     return name.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
 }
@@ -9,7 +9,7 @@ export function entityToArgs(fields) {
     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(inputFields(fields))) {
+    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.
@@ -29,8 +29,15 @@ export function entityToArgs(fields) {
             case 'number':
             case 'integer':
             case 'string':
-                // A date-time string stays a named string — never a positional arg.
-                if (shape.type === 'string' && shape.format === 'date-time') {
+                // 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.type = 'enum';
+                    def.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.type = 'string';
                 }
                 else if (positionalIndex === 0 && def.required && key !== 'force') {

package/dist/bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAQlD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGvD,SAAS,OAAO,CAAC,IAAY;IAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,IAAI,GAAY,EAAE,CAAC;IACzB,IAAI,eAAe,GAAG,CAAC,CAAC;IAExB,4EAA4E;IAC5E,uEAAuE;IACvE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QAC/D,IAAI,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,QAAQ;YAAE,SAAS;QAEtC,0EAA0E;QAC1E,MAAM,YAAY,GAAG,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC;QACxD,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAE1D,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,GAAG,GAAW;YAClB,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE,WAAW;YACpC,QAAQ,EAAE,CAAC,QAAQ,IAAI,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,gBAAgB;SAC5D,CAAC;QAEF,QAAQ,KAAK,EAAE,IAAI,EAAE,CAAC;YACpB,KAAK,SAAS;gBACX,GAA+B,CAAC,IAAI,GAAG,SAAS,CAAC;gBAClD,IAAI,YAAY,KAAK,SAAS;oBAAE,GAAG,CAAC,OAAO,GAAG,YAAuB,CAAC;gBACtE,MAAM;YACR,KAAK,QAAQ,CAAC;YACd,KAAK,SAAS,CAAC;YACf,KAAK,QAAQ;gBACX,oEAAoE;gBACpE,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;oBAC3D,GAA+B,CAAC,IAAI,GAAG,QAAQ,CAAC;gBACnD,CAAC;qBAAM,IAAI,eAAe,KAAK,CAAC,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;oBACpE,mDAAmD;oBAClD,GAA+B,CAAC,IAAI,GAAG,YAAY,CAAC;oBACrD,eAAe,EAAE,CAAC;gBACpB,CAAC;qBAAM,CAAC;oBACL,GAA+B,CAAC,IAAI,GAAG,QAAQ,CAAC;gBACnD,CAAC;gBACD,IAAI,YAAY,KAAK,SAAS;oBAAE,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;gBACnE,MAAM;YACR;gBACG,GAA+B,CAAC,IAAI,GAAG,QAAQ,CAAC;QACrD,CAAC;QAED,IAAI,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;IAC1C,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"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"}

package/dist/completion.d.ts

@@ -1,7 +1,10 @@
 /**
  * Shell completion generator — outputs a script for bash/zsh.
  *
- * Sources: scanned frond handlers (commands) + entity fields (flags).
+ * 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';
 export declare function generateZshCompletion(app: App, binName?: string): string;

package/dist/completion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../src/completion.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAsCzC,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,SAAY,GAAG,MAAM,CAmC3E;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,SAAY,GAAG,MAAM,CA8B5E"}
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../src/completion.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAkDzC,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,SAAY,GAAG,MAAM,CAgD3E;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,SAAY,GAAG,MAAM,CA2C5E"}

package/dist/completion.js

@@ -1,7 +1,12 @@
-import { inputFields } from '@fougere/schema';
+import { entityToArgs } from './bridge.js';
 function toKebab(name) {
     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 = {
+    operation: 'operations',
+    frond: 'fronds',
+};
 function extractCommandMeta(app) {
     const commands = [];
     for (const frond of app.fronds) {
@@ -19,25 +24,37 @@ function extractCommandMeta(app) {
             }
             if (typeof facade.execute !== 'function')
                 continue;
-            const fields = entity.entityClass.getFields();
-            const flags = Object.keys(inputFields(fields))
-                .map((key) => `--${toKebab(key)}`);
-            commands.push({ name: toKebab(entity.name), flags });
+            // 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()));
+            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, binName = 'fougere') {
     const commands = extractCommandMeta(app);
-    const cmdNames = commands.map((c) => c.name).join(' ');
+    const valueCases = commands
+        .filter((cmd) => cmd.names)
+        .map((cmd) => `      ${cmd.name}) _${binName}_names ${cmd.names} ;;`)
+        .join('\n');
     const flagCases = commands
-        .map((cmd) => {
-        const flags = cmd.flags.join(' ');
-        return `      ${cmd.name}) flags="${flags}" ;;`;
-    })
+        .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(' ')})
@@ -48,14 +65,19 @@ _${binName}() {
   fi
 
   local cmd=\${words[2]}
+
+  if [[ "\${words[CURRENT]}" != --* ]]; then
+    case "$cmd" in
+${valueCases}
+    esac
+    return
+  fi
+
   case "$cmd" in
 ${flagCases}
       *) flags="" ;;
   esac
-
-  if [[ "\${words[CURRENT]}" == --* ]]; then
-    _values 'flags' \${(s: :)flags}
-  fi
+  _values 'flags' \${(s: :)flags}
 }
 
 compdef _${binName} ${binName}
@@ -64,17 +86,17 @@ compdef _${binName} ${binName}
 export function generateBashCompletion(app, binName = 'fougere') {
     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) => {
-        const flags = cmd.flags.join(' ');
-        return `      ${cmd.name}) COMPREPLY=( $(compgen -W "${flags}" -- "\${cur}") ) ;;`;
-    })
+        .map((cmd) => `      ${cmd.name}) COMPREPLY=( $(compgen -W "${cmd.flags.join(' ')}" -- "\${cur}") ) ;;`)
         .join('\n');
     return `# Auto-generated by @fougere/cli
 _${binName}_completions() {
-  local cur prev cmd
+  local cur cmd names
   cur="\${COMP_WORDS[COMP_CWORD]}"
-  prev="\${COMP_WORDS[COMP_CWORD-1]}"
   cmd="\${COMP_WORDS[1]}"
 
   if [[ \${COMP_CWORD} -eq 1 ]]; then
@@ -82,6 +104,18 @@ _${binName}_completions() {
     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