@fougere/cli 0.9.2-alpha.0 → 0.9.3-alpha.0

package/app/commands/ExplainCommand.ts

@@ -88,12 +88,26 @@ export function renderExplain(result: ExplainResult): string {
     `${pc.dim('Surfaces:')}  ${result.exposure.surfaces.join(', ') || '—'}`,
     `${pc.dim('Adapters:')}  ${result.exposure.adapters.join(', ') || '—'}`,
     `${pc.dim('Placement:')} ${result.placement.frond} / ${result.placement.runtime}${result.placement.remote ? ` (${result.placement.remote})` : ''}`,
+    // Where the work GOES, under where it answers. The hop count is what a sampling rate, a
+    // histogram's bounds and a load threshold are all a function of — each hard-coded today.
+    `${pc.dim('Reach:')}     ${renderReach(result.reach)}`,
   );
 
   if (result.handler.file) lines.push(`${pc.dim('Source:')}    ${result.handler.file}`);
   return lines.join('\n');
 }
 
+/** What this op reaches, and the part of it that costs a round trip. */
+function renderReach(reach: ExplainResult['reach']): string {
+  if (reach.fronds.length === 0) return pc.dim('nothing outside its own frond');
+
+  const named = reach.fronds
+    .map((one) => (one.runtime === 'remote' ? pc.yellow(one.frond) : pc.cyan(one.frond)))
+    .join(', ');
+
+  return `${named} ${pc.dim(`— ${reach.hops} hop(s)`)}`;
+}
+
 export function renderListing(listing: ExplainListing): string {
   const lines = [pc.bold('Fronds')];
   if (listing.fronds.length === 0) lines.push('  —');

package/app/commands/GraphCommand.ts

@@ -1,5 +1,5 @@
 import type { GraphResult } from '../../fronds/analysis/handlers/GraphHandler.js';
-import type { EntityNode, DomainCluster, App } from '@fougere/core';
+import type { DeclaredTopology, EntityNode, DomainCluster, App } from '@fougere/core';
 import { createAppRunner } from '@fougere/core';
 import type { ui as createUi } from '../../src/ui.js';
 import pc from 'picocolors';
@@ -25,6 +25,7 @@ export default class GraphCommand {
     }
 
     this.ui.step(`${pc.bold(String(result.totalEntities))} entities, ${pc.bold(String(result.totalRefs))} refs, ${pc.bold(String(result.fronds.length))} frond(s)`);
+    this.ui.note(renderFronds(result.declared), 'Fronds');
     this.ui.note(renderGraph(result.nodes), 'Entity Graph');
 
     const min = (raw.minEntities as number) ?? 6;
@@ -39,6 +40,29 @@ export default class GraphCommand {
   }
 }
 
+/**
+ * Where each frond runs, and which reaches which. Read from `remotes:` and from what handlers
+ * ask for — never from a call, so this says the same thing with nothing running.
+ */
+function renderFronds(declared: DeclaredTopology): string {
+  const reached = new Map<string, string[]>();
+  for (const edge of declared.edges) {
+    reached.set(edge.from, [...(reached.get(edge.from) ?? []), edge.to]);
+  }
+
+  const width = Math.max(0, ...declared.fronds.map((one) => one.frond.length));
+
+  return declared.fronds.map((one) => {
+    const name = pc.bold(one.frond.padEnd(width));
+    const where = one.placement === 'local' ? pc.dim('local ') : pc.yellow('remote');
+    const at = one.at ? `  ${pc.dim(one.at)}` : '';
+    const calls = reached.get(one.frond);
+    const out = calls ? `  ${pc.dim('→')} ${calls.map((to) => pc.cyan(to)).join(', ')}` : '';
+
+    return `  ${name}  ${where}${at}${out}`;
+  }).join('\n');
+}
+
 function renderGraph(nodes: Map<string, EntityNode>): string {
   return [...nodes.entries()].map(([name, node]) => {
     const refs = node.refs.length > 0

package/app/commands/LoadCommand.ts

@@ -0,0 +1,44 @@
+import type { App } from '@fougere/core';
+import { createAppRunner } from '@fougere/core';
+import type { LoadScenario } from '../../fronds/analysis/handlers/LoadHandler.js';
+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>;
+
+/**
+ * The command the generated header has been naming all along.
+ *
+ * What it writes is derived — the operations from what the project serves, a body for each from
+ * the entity's own fields, the envelope from the one function that states it. What it cannot
+ * derive is what the load IS: the weights, the stages and the thresholds are facts about your
+ * users, and the file says so where they sit.
+ */
+export default class LoadCommand {
+  constructor(private app: App, private ui: Ui) {}
+
+  async run(raw: Record<string, unknown>) {
+    const result = await createAppRunner(this.app)(
+      { entity: 'load', op: 'execute' },
+      { params: {}, query: {}, input: raw, state: {} },
+    ) as LoadScenario;
+
+    if (machineWanted(raw)) return printMachine(result);
+
+    if (result.operations.length === 0) {
+      this.ui.warn('No operation answers the default door — nothing to put under load.');
+      return;
+    }
+
+    if (!result.file) {
+      process.stdout.write(result.script);
+      return;
+    }
+
+    this.ui.step(`${pc.bold(String(result.operations.length))} operation(s) against ${pc.dim(result.door)}`);
+    this.ui.note(result.operations.map((one) => `  ${one}`).join('\n'), 'Under load');
+    this.ui.info(`${pc.dim('Written to')} ${result.file}  ${pc.dim('— edit the weights, the stages and the thresholds.')}`);
+    this.ui.info(`${pc.dim('Then:')} k6 run ${result.file}`);
+  }
+}

package/fronds/analysis/entities/Load.ts

@@ -0,0 +1,8 @@
+import { entity, bool, text } from '@fougere/schema';
+
+export default class Load extends entity({
+  root: text({ description: 'Project root directory (default: cwd)' }),
+  door: text({ description: 'Where the calls go (default: http://127.0.0.1:3000/_fougere/call)' }),
+  out: text({ description: 'Where to write it, or empty to print it on stdout (default: <root>/load.js)' }),
+  json: bool({ default: false, description: 'Print the scenario as JSON, with nothing else on stdout' }),
+}) {}

package/fronds/analysis/handlers/DevtoolsHandler.ts

@@ -2,9 +2,18 @@ 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. */
+/**
+ * Where an app answers in development — Nuxt, Next and the site all sit there, so it is a
+ * convention and not a setting. A port belongs to the HOST, though, and this project states
+ * none: an app served anywhere else is named the way `FOUGERE_LOG_LEVEL` names a level the
+ * file did not, and `--url` still wins over both.
+ */
 const LOCAL = 'http://127.0.0.1:3000';
 
+function local(): string {
+  return trimmed(process.env.FOUGERE_URL || LOCAL);
+}
+
 /** One address that was asked, and what came back from it. */
 export interface CallSource {
   url: string;
@@ -70,10 +79,11 @@ export default class DevtoolsHandler {
    */
   private async addresses(root?: string): Promise<{ url: string; frond?: string }[]> {
     const { config } = await this.projectScan.at(root);
+    const here = local();
     const remotes = Object.entries(config.remotes ?? {})
       .map(([frond, url]) => ({ url: trimmed(url), frond }));
 
-    return [{ url: LOCAL }, ...remotes.filter((one) => one.url !== LOCAL)];
+    return [{ url: here }, ...remotes.filter((one) => one.url !== here)];
   }
 }
 

package/fronds/analysis/handlers/ExplainHandler.ts

@@ -59,6 +59,11 @@ export interface ExplainResult {
     runtime: 'local' | 'remote';
     remote: string | null;
   };
+  /** Where the work GOES, next to where it answers — and how much of it leaves the process. */
+  reach: {
+    fronds: { frond: string; runtime: 'local' | 'remote' }[];
+    hops: number;
+  };
 }
 
 /** What this project serves, when no single operation was named. */
@@ -193,6 +198,7 @@ function project(operation: EffectiveOperation, root: string): ExplainResult {
       runtime: operation.placement.runtime,
       remote: operation.placement.remote ?? null,
     },
+    reach: operation.reach,
   };
 }
 

package/fronds/analysis/handlers/GraphHandler.ts

@@ -1,11 +1,13 @@
 import {
-  buildGraph, suggestSplit,
-  type EntityNode, type DomainCluster, type FrondDescriptor,
+  buildGraph, declaredTopologyOf, suggestSplit,
+  type DeclaredTopology, type EntityNode, type DomainCluster, type FrondDescriptor,
 } from '@fougere/core';
 import ProjectScan from '../services/ProjectScan.js';
 
 export interface GraphResult {
   fronds: FrondDescriptor[];
+  /** Where the fronds run and which reaches which — the same picture, one altitude up. */
+  declared: DeclaredTopology;
   nodes: Map<string, EntityNode>;
   clusters: DomainCluster[];
   totalEntities: number;
@@ -17,12 +19,13 @@ export default class GraphHandler {
 
   /** Report how a workspace's fronds and entities reference each other. */
   async execute(input: { root?: string; minEntities?: number }): Promise<GraphResult> {
-    const { fronds } = await this.projectScan.at(input.root);
+    const { fronds, config } = await this.projectScan.at(input.root);
     const nodes = buildGraph(fronds);
     const clusters = suggestSplit(nodes);
 
     return {
       fronds,
+      declared: declaredTopologyOf({ fronds, remotes: config.remotes ?? {} }),
       nodes,
       clusters,
       totalEntities: nodes.size,

package/fronds/analysis/handlers/LoadHandler.ts

@@ -0,0 +1,43 @@
+import { loadScript, reachableOps } from '@fougere/testing';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import ProjectScan from '../services/ProjectScan.js';
+
+export interface LoadScenario {
+  /** Where it was written, or `null` when it was only printed. */
+  file: string | null;
+  door: string;
+  /** Every operation the scenario calls, in the order it lists them. */
+  operations: string[];
+  script: string;
+}
+
+/**
+ * A load scenario, written from what the project serves.
+ *
+ * Read from the SCAN rather than a boot: an app that boots runs its migrations and plants its
+ * seeds, and a command that describes a project has no business writing to its database.
+ */
+export default class LoadHandler {
+  constructor(private projectScan: ProjectScan) {}
+
+  /** Generate a k6 scenario covering every operation the default door answers. */
+  async execute(input: { root?: string; door?: string; out?: string }): Promise<LoadScenario> {
+    const { root, fronds, config } = await this.projectScan.at(input.root);
+    const door = input.door?.trim() || undefined;
+    // The topology statement travels with it: an op that crosses a process is not held to the
+    // same figure as one that never leaves, and `remotes:` is what says which is which.
+    const remotes = config.remotes ?? {};
+    const script = loadScript({ fronds }, { ...(door ? { door } : {}), remotes });
+
+    const file = input.out === undefined ? join(root, 'load.js') : input.out || null;
+    if (file) await writeFile(file, script, 'utf8');
+
+    return {
+      file,
+      door: door ?? 'http://127.0.0.1:3000/_fougere/call',
+      operations: reachableOps({ fronds }, {}, remotes).map((one) => one.method),
+      script,
+    };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/cli",
-  "version": "0.9.2-alpha.0",
+  "version": "0.9.3-alpha.0",
   "description": "The Fougere CLI — compose a workspace, serve a frond, call an operation.",
   "keywords": [
     "fougere",
@@ -42,13 +42,14 @@
     "jiti": "^2.4.2",
     "picocolors": "^1.1.1",
     "safe-regex": "^2.1.1",
-    "@fougere/container": "0.9.2-alpha.0",
-    "@fougere/core": "0.9.2-alpha.0",
-    "@fougere/schema": "0.9.2-alpha.0",
-    "@fougere/compiler": "0.9.2-alpha.0",
-    "@fougere/transport-http": "0.9.2-alpha.0",
-    "@fougere/adapter-sql": "0.9.2-alpha.0",
-    "@fougere/defaults": "0.9.2-alpha.0"
+    "@fougere/transport-http": "0.9.3-alpha.0",
+    "@fougere/adapter-sql": "0.9.3-alpha.0",
+    "@fougere/testing": "0.9.3-alpha.0",
+    "@fougere/defaults": "0.9.3-alpha.0",
+    "@fougere/container": "0.9.3-alpha.0",
+    "@fougere/schema": "0.9.3-alpha.0",
+    "@fougere/compiler": "0.9.3-alpha.0",
+    "@fougere/core": "0.9.3-alpha.0"
   },
   "devDependencies": {
     "vitest": "^4.1.0"