@fougere/cli 0.4.0-alpha.0 → 0.5.0-alpha.1

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/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

@@ -7,6 +7,7 @@ import type {
   ExplainedBinding,
 } from '../../fronds/analysis/handlers/ExplainHandler.js';
 import pc from 'picocolors';
+import { machineText, printMachine } from '../../src/machine.js';
 
 type Ui = ReturnType<typeof createUi>;
 
@@ -23,10 +24,7 @@ export default class ExplainCommand {
 
     const result = await this.ask('execute', raw) as ExplainResult;
 
-    if (raw.json === true) {
-      process.stdout.write(renderExplainJson(result) + '\n');
-      return;
-    }
+    if (raw.json === true) return printMachine(result);
 
     this.ui.note(renderExplain(result), result.operation);
   }
@@ -43,10 +41,7 @@ export default class ExplainCommand {
       return;
     }
 
-    if (raw.json === true) {
-      process.stdout.write(JSON.stringify(listing, null, 2) + '\n');
-      return;
-    }
+    if (raw.json === true) return printMachine(listing);
 
     this.ui.note(renderListing(listing), 'what this project serves');
   }
@@ -59,8 +54,9 @@ export default class ExplainCommand {
   }
 }
 
+/** 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 {

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;

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

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function machineWanted(raw: Record<string, unknown>): boolean;
+/**
+ * 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 declare function machineText(value: unknown): string;
+export declare function printMachine(value: unknown): void;
+//# sourceMappingURL=machine.d.ts.map

package/dist/machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../src/machine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAElD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEjD"}

package/dist/machine.js

@@ -0,0 +1,22 @@
+/**
+ * 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) {
+    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) {
+    return JSON.stringify(value, (_key, held) => (held instanceof Map ? Object.fromEntries(held) : held), 2);
+}
+export function printMachine(value) {
+    process.stdout.write(machineText(value) + '\n');
+}
+//# sourceMappingURL=machine.js.map

package/dist/machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.js","sourceRoot":"","sources":["../src/machine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAA4B;IACxD,OAAO,GAAG,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC;AAC5D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,YAAY,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AAC3G,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;AAClD,CAAC"}

package/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAuCzC,wBAAsB,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CA0FjD"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAwCzC,wBAAsB,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAgGjD"}

package/dist/runner.js

@@ -2,6 +2,7 @@ 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';
@@ -31,7 +32,6 @@ async function loadAppCommands(cliRoot, loader) {
 export async function run(app) {
     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) => jiti.import(path);
@@ -76,10 +76,12 @@ export async function run(app) {
                 },
                 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');
+                    // 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);
+                    // `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
@@ -98,7 +100,13 @@ export async function run(app) {
                         }
                     }
                     catch (err) {
-                        terminal.error(err instanceof Error ? err.message : String(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);
                     }
                 },

package/dist/runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}

package/fronds/analysis/entities/Build.ts

@@ -1,7 +1,8 @@
-import { entity, text, optional } from "@fougere/schema";
+import { entity, bool, text, optional } from "@fougere/schema";
 
 /** `fougere build` — write down what a scan found, so a deployment reads no disk. */
 export default class Build extends entity({
   root: optional(text({ description: "Project to read. Default: the current directory" })),
   out: optional(text({ description: "Where to write it. Default: .fougere/scan.generated.ts" })),
+  json: bool({ default: false, description: "Print the report as JSON, with nothing else on stdout" }),
 }) {}

package/fronds/analysis/entities/Check.ts

@@ -1,5 +1,6 @@
-import { entity, text } from '@fougere/schema';
+import { entity, bool, text } from '@fougere/schema';
 
 export default class Check extends entity({
   root: text({ description: 'Project root directory (default: cwd)' }),
+  json: bool({ default: false, description: 'Print the report as JSON, with nothing else on stdout' }),
 }) {}

package/fronds/analysis/entities/Devtools.ts

@@ -0,0 +1,8 @@
+import { entity, bool, text, optional } from '@fougere/schema';
+
+/** `fougere devtools` — what the running apps of this project are dispatching. */
+export default class Devtools extends entity({
+  url: optional(text({ description: 'One app to read. Absent: every address this project declares' })),
+  root: optional(text({ description: 'Project to read the addresses from. Default: the current directory' })),
+  json: bool({ default: false, description: 'Print one page as JSON and stop, instead of following' }),
+}) {}

package/fronds/analysis/entities/Freeze.ts

@@ -1,7 +1,8 @@
-import { entity, text, optional } from "@fougere/schema";
+import { entity, bool, text, optional } from "@fougere/schema";
 
 /** `fougere freeze <version>` — record today's shapes under a name, for good. */
 export default class Freeze extends entity({
   version: text({ min: 1, description: "Name to record these shapes under (e.g. v2)" }),
   root: optional(text({ description: "Project to read. Default: the current directory" })),
+  json: bool({ default: false, description: "Print the report as JSON, with nothing else on stdout" }),
 }) {}

package/fronds/analysis/entities/Graph.ts

@@ -1,6 +1,7 @@
-import { entity, text, number } from '@fougere/schema';
+import { entity, bool, text, number } from '@fougere/schema';
 
 export default class Graph extends entity({
   root: text({ description: 'Project root directory (default: cwd)' }),
   minEntities: number({ default: 6, description: 'Minimum entities before suggesting split' }),
+  json: bool({ default: false, description: 'Print the report as JSON, with nothing else on stdout' }),
 }) {}

package/fronds/analysis/entities/Migrate.ts

@@ -4,4 +4,5 @@ import { entity, bool, optional, text } from "@fougere/schema";
 export default class Migrate extends entity({
   apply: bool({ default: false, description: "Run it. Without this the plan is printed and nothing moves" }),
   root: optional(text({ description: "Project to read. Default: the current directory" })),
+  json: bool({ default: false, description: "Print the report as JSON, with nothing else on stdout" }),
 }) {}

package/fronds/analysis/handlers/BuildHandler.ts

@@ -39,7 +39,8 @@ export default class BuildHandler {
   constructor(private projectScan: ProjectScan) {}
 
   /** Write down what a scan found, so a deployment reads no disk. */
-  async execute(input: Build): Promise<BuildReport> {
+  /** `json` is the presentation's, so it is not part of what this operation receives. */
+  async execute(input: Omit<Build, 'json'>): Promise<BuildReport> {
     const scan = await this.projectScan.at(input.root ?? undefined);
     const out = resolve(scan.root, input.out || DEFAULT_OUT);
 

package/fronds/analysis/handlers/DevtoolsHandler.ts

@@ -0,0 +1,86 @@
+import { createHttpTransport } from '@fougere/transport-http/client';
+import type { CallPage, CallRecord } from '@fougere/core';
+import ProjectScan from '../services/ProjectScan.js';
+
+/** The default address of an app in development — Nuxt, Next and the site all sit there. */
+const LOCAL = 'http://127.0.0.1:3000';
+
+/** One address that was asked, and what came back from it. */
+export interface CallSource {
+  url: string;
+  /** The frond `remotes:` names at this address, when that is where it came from. */
+  frond?: string;
+  cursor: number;
+  inFlight: number;
+  dropped: number;
+  /** Present instead of the numbers when the address did not answer, or serves no log. */
+  refusal?: string;
+}
+
+/**
+ * Every app of this project, read at once.
+ *
+ * A reader pulls: no app registers anywhere, and an app started alone depends on nothing.
+ * The price is knowing the addresses, which the project already states — `remotes:` says
+ * where a call goes, so it also says where the other half of a call can be watched.
+ */
+export interface CallsView {
+  sources: CallSource[];
+  /** Every call, oldest first, each carrying the address it was read from. */
+  calls: (CallRecord & { source: string })[];
+}
+
+export default class DevtoolsHandler {
+  constructor(private projectScan: ProjectScan) {}
+
+  /** Read what the running apps have dispatched since a cursor per address. */
+  async execute(input: { url?: string; root?: string; since?: Record<string, number> }): Promise<CallsView> {
+    const asked = input.url ? [{ url: trimmed(input.url) }] : await this.addresses(input.root);
+    const since = input.since ?? {};
+
+    const read = await Promise.all(asked.map(async (one): Promise<CallSource & { calls: CallRecord[] }> => {
+      try {
+        const page = await createHttpTransport(one.url)(
+          { entity: 'rpc', op: 'calls' },
+          { params: {}, query: {}, body: { since: since[one.url] ?? 0 }, state: {} },
+        ) as CallPage;
+
+        return { ...one, cursor: page.cursor, inFlight: page.inFlight, dropped: page.dropped, calls: page.calls };
+      } catch (err) {
+        // An address that does not answer is a source with a reason, not a missing source:
+        // an app not started and an app without the package are different facts, and both
+        // are worth seeing beside the ones that answered.
+        return { ...one, cursor: since[one.url] ?? 0, inFlight: 0, dropped: 0, calls: [], refusal: said(err) };
+      }
+    }));
+
+    return {
+      sources: read.map(({ calls: _calls, ...source }) => source),
+      calls: read
+        .flatMap(({ url, calls }) => calls.map((call) => ({ ...call, source: url })))
+        .sort((a, b) => a.startedAt - b.startedAt || a.seq - b.seq),
+    };
+  }
+
+  /**
+   * The addresses this project declares, plus the local one.
+   *
+   * `remotes:` is the operator's statement of where a call goes; reading it here is not a
+   * second source of truth, it is the same one read for the other direction.
+   */
+  private async addresses(root?: string): Promise<{ url: string; frond?: string }[]> {
+    const { config } = await this.projectScan.at(root);
+    const remotes = Object.entries(config.remotes ?? {})
+      .map(([frond, url]) => ({ url: trimmed(url), frond }));
+
+    return [{ url: LOCAL }, ...remotes.filter((one) => one.url !== LOCAL)];
+  }
+}
+
+function trimmed(url: string): string {
+  return url.replace(/\/$/, '');
+}
+
+function said(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/fronds/analysis/handlers/FreezeHandler.ts

@@ -40,7 +40,8 @@ export default class FreezeHandler {
    * ambiguities and calls again with `renamed`. Splitting it would let a caller write
    * a version it never inspected.
    */
-  async execute(input: Freeze & { renamed?: Record<string, Record<string, string>> }): Promise<FreezeInspection> {
+  /** `json` is the presentation's, so it is not part of what this operation receives. */
+  async execute(input: Omit<Freeze, 'json'> & { renamed?: Record<string, Record<string, string>> }): Promise<FreezeInspection> {
     const fronds = await this.read(input);
     const version = input.version;
     const entities = fronds.flatMap(({ bundle }) => Object.keys(bundle.$defs ?? {}));
@@ -97,7 +98,7 @@ export default class FreezeHandler {
    * `Fronds.schemas()` is deliberately flat — a fact heard in one frond is declared in
    * another — so the per-frond map is built here, where the question IS per frond.
    */
-  private async read(input: Freeze) {
+  private async read(input: Omit<Freeze, 'json'>) {
     const scan = await this.projectScan.at(input.root ?? undefined);
     return Promise.all(
       scan.fronds

package/fronds/analysis/handlers/MigrateHandler.ts

@@ -31,7 +31,8 @@ export default class MigrateHandler {
   constructor(private projectScan: ProjectScan) {}
 
   /** Realise the frozen steps this database has not caught up with. */
-  async execute(input: Migrate): Promise<MigrationPlan> {
+  /** `json` is the presentation's, so it is not part of what this operation receives. */
+  async execute(input: Omit<Migrate, 'json'>): Promise<MigrationPlan> {
     const scan = await this.projectScan.at(input.root ?? undefined);
     const perFrond = await Promise.all(scan.fronds.map((frond) => stepsOf(frond.source.path)));
     const steps = perFrond.flat();

package/fronds/scaffold/handlers/SyncHandler.ts

@@ -251,10 +251,10 @@ export default class SyncHandler {
       },
     }, null, 2) + '\n');
 
-    // Update .fougere/remotes.json — central registry of synced remotes
+    // .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)
+    // Non-Nuxt projects only: Nuxt writes its own paths.
     this.updateTsconfigPaths(input.frond, frondDir, conventions);
 
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/cli",
-  "version": "0.4.0-alpha.0",
+  "version": "0.5.0-alpha.1",
   "description": "The Fougere CLI — compose a workspace, serve a frond, call an operation.",
   "keywords": [
     "fougere",
@@ -41,12 +41,12 @@
     "consola": "^3.4.2",
     "jiti": "^2.4.2",
     "picocolors": "^1.1.1",
-    "@fougere/adapter-sql": "0.4.0-alpha.0",
-    "@fougere/defaults": "0.4.0-alpha.0",
-    "@fougere/transport-http": "0.4.0-alpha.0",
-    "@fougere/core": "0.4.0-alpha.0",
-    "@fougere/schema": "0.4.0-alpha.0",
-    "@fougere/container": "0.4.0-alpha.0"
+    "@fougere/core": "0.5.0-alpha.1",
+    "@fougere/adapter-sql": "0.5.0-alpha.1",
+    "@fougere/transport-http": "0.5.0-alpha.1",
+    "@fougere/schema": "0.5.0-alpha.1",
+    "@fougere/container": "0.5.0-alpha.1",
+    "@fougere/defaults": "0.5.0-alpha.1"
   },
   "devDependencies": {
     "vitest": "^4.1.0"

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');
+}

package/src/runner.ts

@@ -12,6 +12,7 @@ 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';
@@ -50,7 +51,6 @@ 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>>;
@@ -98,10 +98,13 @@ export async function run(app: App): Promise<void> {
         },
         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');
+          // 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
@@ -122,7 +125,11 @@ export async function run(app: App): Promise<void> {
               );
             }
           } catch (err) {
-            terminal.error(err instanceof Error ? err.message : String(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);
           }
         },

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 }));
   }