@fougere/cli 0.12.5-alpha.0 → 0.12.6-alpha.0

package/dist/fronds/analysis/handlers/BuildHandler.d.ts

@@ -0,0 +1,50 @@
+import ProjectScan from '../services/ProjectScan.js';
+import type Build from '../entities/Build.js';
+/**
+ * Where the module lands when nobody says otherwise.
+ *
+ * `.fougere/` because the artefact is REGENERABLE — which is exactly the test `freeze`
+ * failed: a recorded version is a past nobody can recompute, so it lives in the tree.
+ * This is the same scan the next build performs again, so it is gitignored.
+ */
+export declare const DEFAULT_OUT = ".fougere/scan.generated.ts";
+/** Types only, beside the module — what lets a client narrow a refusal it might meet. */
+export declare const FACADE_OUT = "facade.generated.ts";
+/** Types only — what a config may NAME, so a string cannot designate a class that is not there. */
+export declare const NAMES_OUT = "names.generated.d.ts";
+export interface BuildReport {
+    /** Absolute, so a caller can print it or read it back. */
+    out: string;
+    /** Relative to the project root — what a human recognizes. */
+    path: string;
+    /** Where the facades were written — one export per address, the page's facade in. */
+    facade: string;
+    /** Where the names went — the unions a config is judged against. */
+    names: string;
+    fronds: string[];
+    entities: number;
+    handlers: number;
+    /**
+     * What the scan could not settle, carried rather than swallowed: the module holds the
+     * same diagnostics, so a boot from it warns exactly as a boot from a disk would.
+     */
+    diagnostics: string[];
+}
+/**
+ * Writing the scan down — the half of the gradient a runtime without a disk needs.
+ *
+ * Producing the description reads the project; consuming it does not. `createApp` takes
+ * `scan:` and never looks for a filesystem, so this command is what stands between a
+ * project and a Worker: it runs where `node:fs` exists, once, at build time.
+ */
+export default class BuildHandler {
+    private projectScan;
+    constructor(projectScan: ProjectScan);
+    /**
+     * Write down what a scan found, so a deployment reads no disk.
+     *
+     * `json` is the presentation's, so it is not part of what this operation receives.
+     */
+    execute(input: Omit<Build, 'json'>): Promise<BuildReport>;
+}
+//# sourceMappingURL=BuildHandler.d.ts.map

package/dist/fronds/analysis/handlers/BuildHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuildHandler.d.ts","sourceRoot":"","sources":["../../../../fronds/analysis/handlers/BuildHandler.ts"],"names":[],"mappings":"AAIA,OAAO,WAAW,MAAM,4BAA4B,CAAC;AACrD,OAAO,KAAK,KAAK,MAAM,sBAAsB,CAAC;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,+BAA+B,CAAC;AACxD,yFAAyF;AACzF,eAAO,MAAM,UAAU,wBAAwB,CAAC;AAChD,mGAAmG;AACnG,eAAO,MAAM,SAAS,yBAAyB,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,OAAO,YAAY;IACnB,OAAO,CAAC,WAAW;IAA/B,YAAoB,WAAW,EAAE,WAAW,EAAI;IAEhD;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CA+B9D;CACF"}

package/dist/fronds/analysis/handlers/BuildHandler.js

@@ -0,0 +1,63 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { loadConfig } from '@fougere/core/node';
+import { dirname, join, relative, resolve } from 'node:path';
+import { emitFacade, emitNames, emitScan } from '@fougere/compiler';
+/**
+ * Where the module lands when nobody says otherwise.
+ *
+ * `.fougere/` because the artefact is REGENERABLE — which is exactly the test `freeze`
+ * failed: a recorded version is a past nobody can recompute, so it lives in the tree.
+ * This is the same scan the next build performs again, so it is gitignored.
+ */
+export const DEFAULT_OUT = '.fougere/scan.generated.ts';
+/** Types only, beside the module — what lets a client narrow a refusal it might meet. */
+export const FACADE_OUT = 'facade.generated.ts';
+/** Types only — what a config may NAME, so a string cannot designate a class that is not there. */
+export const NAMES_OUT = 'names.generated.d.ts';
+/**
+ * Writing the scan down — the half of the gradient a runtime without a disk needs.
+ *
+ * Producing the description reads the project; consuming it does not. `createApp` takes
+ * `scan:` and never looks for a filesystem, so this command is what stands between a
+ * project and a Worker: it runs where `node:fs` exists, once, at build time.
+ */
+export default class BuildHandler {
+    projectScan;
+    constructor(projectScan) {
+        this.projectScan = projectScan;
+    }
+    /**
+     * Write down what a scan found, so a deployment reads no disk.
+     *
+     * `json` is the presentation's, so it is not part of what this operation receives.
+     */
+    async execute(input) {
+        const scan = await this.projectScan.at(input.root ?? undefined);
+        const out = resolve(scan.root, input.out || DEFAULT_OUT);
+        // The emitter writes every import relative to where the module will SIT, so the
+        // directory has to be settled before the source is produced, not after.
+        await mkdir(dirname(out), { recursive: true });
+        await writeFile(out, emitScan(scan, { outFile: out }));
+        // The same scan, projected a third way. It holds no value and reaches no bundle: what a
+        // client cannot otherwise know is which refusals one facade can answer, because TypeScript
+        // records nothing about what a function throws.
+        const facade = join(dirname(out), FACADE_OUT);
+        await writeFile(facade, emitFacade(scan, { outFile: facade }));
+        // And a fourth, for the only place a name is still written as a string: a config file. The
+        // sources are the config's own keys, which no scan can find.
+        const config = await loadConfig(scan.root).catch(() => ({}));
+        const names = join(dirname(out), NAMES_OUT);
+        await writeFile(names, emitNames(scan, { sources: Object.keys(config.sources ?? {}) }));
+        return {
+            out,
+            path: relative(scan.root, out),
+            facade: relative(scan.root, facade),
+            names: relative(scan.root, names),
+            fronds: scan.fronds.map((frond) => frond.name),
+            entities: scan.fronds.reduce((total, frond) => total + frond.entities.length, 0),
+            handlers: scan.fronds.reduce((total, frond) => total + frond.handlers.length, 0),
+            diagnostics: scan.diagnostics.map((d) => `${d.severity} ${d.code}: ${d.message}`),
+        };
+    }
+}
+//# sourceMappingURL=BuildHandler.js.map

package/dist/fronds/analysis/handlers/BuildHandler.js.map

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

package/dist/fronds/analysis/handlers/CheckHandler.d.ts

@@ -0,0 +1,30 @@
+import { type Diagnostic } from '@fougere/core';
+import ProjectScan from '../services/ProjectScan.js';
+export interface CheckResult {
+    fronds: number;
+    handlers: number;
+    findings: Diagnostic[];
+}
+/**
+ * What does not hold in this app — derived from its declarations, not from tests.
+ *
+ * It scans rather than boots — see `ProjectScan`, which states what that costs.
+ *
+ * It raises no operation-resolution rule of its own: those findings come from the same
+ * EffectiveOperation resolver boot consumes. The remaining findings come from their
+ * existing owners — scan diagnostics, the import reader and domain clustering. A second
+ * opinion here would report what the runtime does not serve, precisely what a checker
+ * must avoid.
+ *
+ * A rule about an ABSENCE is only sound if the analysis attests it looked, which is
+ * why the scan's diagnostics had to exist before this command could.
+ */
+export default class CheckHandler {
+    private projectScan;
+    constructor(projectScan: ProjectScan);
+    /** Report what does not hold in a Fougere app, without booting it. */
+    execute(input: {
+        root?: string;
+    }): Promise<CheckResult>;
+}
+//# sourceMappingURL=CheckHandler.d.ts.map

package/dist/fronds/analysis/handlers/CheckHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CheckHandler.d.ts","sourceRoot":"","sources":["../../../../fronds/analysis/handlers/CheckHandler.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AAGvB,OAAO,WAAW,MAAM,4BAA4B,CAAC;AAMrD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAKD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,OAAO,YAAY;IACnB,OAAO,CAAC,WAAW;IAA/B,YAAoB,WAAW,EAAE,WAAW,EAAI;IAEhD,sEAAsE;IAChE,OAAO,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CA4I5D;CACF"}

package/dist/fronds/analysis/handlers/CheckHandler.js

@@ -0,0 +1,196 @@
+import { Shapes } from '@fougere/schema';
+import safeRegex from 'safe-regex';
+import { buildGraph, clusterEntities, resolveEffectiveOperations, } from '@fougere/core';
+import { adaptersOf, crossFrondImports, handlerDeclarations, outsideConventions } from '@fougere/compiler';
+import { resolveConventions } from '@fougere/core';
+import { statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { FACADE_OUT, DEFAULT_OUT } from './BuildHandler.js';
+import { remotesOf } from '@fougere/core/node';
+/** Shared with `fougere graph` — one threshold, so the two never disagree. */
+const DOMAIN_SPLIT_MIN_ENTITIES = 6;
+/**
+ * What does not hold in this app — derived from its declarations, not from tests.
+ *
+ * It scans rather than boots — see `ProjectScan`, which states what that costs.
+ *
+ * It raises no operation-resolution rule of its own: those findings come from the same
+ * EffectiveOperation resolver boot consumes. The remaining findings come from their
+ * existing owners — scan diagnostics, the import reader and domain clustering. A second
+ * opinion here would report what the runtime does not serve, precisely what a checker
+ * must avoid.
+ *
+ * A rule about an ABSENCE is only sound if the analysis attests it looked, which is
+ * why the scan's diagnostics had to exist before this command could.
+ */
+export default class CheckHandler {
+    projectScan;
+    constructor(projectScan) {
+        this.projectScan = projectScan;
+    }
+    /** Report what does not hold in a Fougere app, without booting it. */
+    async execute(input) {
+        const { fronds, diagnostics, config, root } = await this.projectScan.at(input.root);
+        // This is the same pure resolution the boot consumes. No app lifecycle, database,
+        // migration, seed or adapter mount is needed for a global semantic check.
+        const model = resolveEffectiveOperations(fronds, {
+            diagnostics,
+            remotes: remotesOf(config),
+            adapters: config.adapters,
+        });
+        const findings = [...model.diagnostics];
+        const handlers = fronds.reduce((count, frond) => count + frond.handlers.length, 0);
+        /**
+         * Entity groups with no `ref()` between them, in one frond. Reported as a FACT, not a
+         * verdict: it means either a missing relation or a frond that has not been named, and
+         * nothing here can tell which. `fougere graph` shows the groups.
+         */
+        if (fronds.length === 1) {
+            // `clusterEntities`, not `suggestSplit`: the latter invents a cut on a connected
+            // graph, which is its job and not this question. Here only real components count.
+            const nodes = buildGraph(fronds);
+            const clusters = clusterEntities(nodes);
+            // Same threshold as `fougere graph`'s own tip: below it, two components are a small
+            // app that has not grown its links yet, not a frond holding two domains.
+            if (clusters.length > 1 && nodes.size >= DOMAIN_SPLIT_MIN_ENTITIES) {
+                findings.push({
+                    severity: 'warning',
+                    code: 'frond-holds-several-domains',
+                    filePath: fronds[0].source.path,
+                    message: `'${fronds[0].name}': ${clusters.length} entity groups with no relation between `
+                        + `them (${clusters.map((c) => c.name).join(', ')}). Either a relation is missing, or `
+                        + `they are separate fronds — see \`fougere graph\`.`,
+                });
+            }
+        }
+        /**
+         * An entity addressing an adapter this project does not depend on. Judged HERE and
+         * not at boot: a process only knows the adapters it loaded, so an entity stating a
+         * Postgres column type in an app running on `adapter/memory` is indistinguishable
+         * from a typo. A project's dependencies name every adapter it could ever load.
+         *
+         * Silent when the project depends on none — there would be nothing to compare against,
+         * and reporting every key as unknown is worse than saying nothing.
+         */
+        const known = await adaptersOf(root);
+        if (known.length > 0) {
+            for (const frond of fronds) {
+                for (const entity of frond.entities) {
+                    for (const name of Object.keys(entity.entityClass.getAdapters() ?? {})) {
+                        if (known.includes(name))
+                            continue;
+                        findings.push({
+                            severity: 'warning',
+                            code: 'unknown-adapter',
+                            filePath: entity.filePath,
+                            subject: entity.name,
+                            message: `states \`adapters: { ${name} }\`, and this project depends on no adapter `
+                                + `that answers to it. It depends on ${known.join(', ')}. Nothing reads the entry, `
+                                + 'so it is inert — a typo, or a dependency that was never added.',
+                        });
+                    }
+                }
+            }
+        }
+        /**
+         * A `pattern` that backtracks super-linearly. The pattern is fixed at declaration and
+         * the string tested against it is not: whoever calls the facade chooses it, so the cost
+         * of one match is theirs to set. Judged HERE because a regex says the same thing on
+         * every run — checking it per row would pay for a verdict that never changes.
+         *
+         * `safe-regex` reads the star height, which is the common shape and not every one:
+         * `(a|a)*b` backtracks too and passes. Reported as a suspicion, never as a refusal.
+         */
+        for (const frond of fronds) {
+            for (const entity of frond.entities) {
+                for (const [key, field] of Object.entries(entity.entityClass.getFields())) {
+                    for (const pattern of Shapes.patterns(field.shape)) {
+                        if (safeRegex(pattern))
+                            continue;
+                        findings.push({
+                            severity: 'warning',
+                            code: 'super-linear-pattern',
+                            filePath: entity.filePath,
+                            subject: `${entity.name}.${key}`,
+                            message: `states \`pattern: ${JSON.stringify(pattern)}\`, whose nested repetition `
+                                + 'backtracks super-linearly. A value a caller chooses can hold the event loop '
+                                + 'for seconds — rewrite the repeated group, or bound the field with `max`.',
+                        });
+                    }
+                }
+            }
+        }
+        /**
+         * A warning, not a refusal: it resolves today and the app runs. What it costs is
+         * paid once, late — the day the frond it reaches into is deployed on its own.
+         */
+        for (const reach of await crossFrondImports(fronds)) {
+            findings.push({
+                severity: 'warning',
+                code: reach.rule,
+                filePath: reach.filePath,
+                message: reach.message,
+            });
+        }
+        const conventions = resolveConventions(config.conventions);
+        /**
+         * What no convention names. Reported before the declarations below, because a frond
+         * with nowhere to put a word is why the word ends up in a handler.
+         */
+        for (const unplaced of await outsideConventions(fronds, conventions)) {
+            findings.push({
+                severity: 'warning',
+                code: unplaced.rule,
+                filePath: unplaced.filePath,
+                subject: unplaced.frond,
+                message: unplaced.message,
+            });
+        }
+        /**
+         * The same shape of warning, one file lower: what the handler holds still runs, and
+         * what it costs is the next caller — a test, a second operation, another handler —
+         * that cannot reach it without moving it first.
+         */
+        for (const held of await handlerDeclarations(fronds, conventions)) {
+            findings.push({
+                severity: 'warning',
+                code: held.rule,
+                filePath: held.filePath,
+                subject: `${held.handler}.${held.subject}`,
+                message: held.message,
+            });
+        }
+        findings.push(...facadeFindings(root, fronds));
+        return { fronds: fronds.length, handlers, findings };
+    }
+}
+/**
+ * A facade module older than the handlers it was read off.
+ *
+ * An ABSENT module needs no finding: a page importing one fails to resolve, loudly, and a
+ * backend project never imports one at all — warning there would fire on every project that
+ * does not want a facade, which is most of them.
+ *
+ * A STALE one is the silent case. The import resolves, the operations are the old ones, and a
+ * renamed op compiles against a name nothing serves any more. An mtime is the whole check.
+ */
+function facadeFindings(root, fronds) {
+    const facade = join(root, dirname(DEFAULT_OUT), FACADE_OUT);
+    const written = statSync(facade, { throwIfNoEntry: false })?.mtimeMs;
+    if (written === undefined)
+        return [];
+    const newer = fronds
+        .flatMap((frond) => frond.handlers)
+        .filter((handler) => (statSync(handler.filePath, { throwIfNoEntry: false })?.mtimeMs ?? 0) > written);
+    if (newer.length === 0)
+        return [];
+    return [{
+            severity: 'warning',
+            code: 'facade-stale',
+            filePath: facade,
+            subject: `${newer.length} handler${newer.length > 1 ? 's' : ''}`,
+            message: 'The facade module is older than the handlers it was read off, so a page checks its '
+                + 'calls against operations that may no longer exist. Run `fougere build`.',
+        }];
+}
+//# sourceMappingURL=CheckHandler.js.map

package/dist/fronds/analysis/handlers/CheckHandler.js.map

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

package/dist/fronds/analysis/handlers/DevtoolsHandler.d.ts

@@ -0,0 +1,45 @@
+import type { CallRecord } from '@fougere/core';
+import ProjectScan from '../services/ProjectScan.js';
+/** 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 {
+    private projectScan;
+    constructor(projectScan: ProjectScan);
+    /** Read what the running apps have dispatched since a cursor per address. */
+    execute(input: {
+        url?: string;
+        root?: string;
+        since?: Record<string, number>;
+    }): Promise<CallsView>;
+    /**
+     * 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 addresses;
+}
+//# sourceMappingURL=DevtoolsHandler.d.ts.map

package/dist/fronds/analysis/handlers/DevtoolsHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DevtoolsHandler.d.ts","sourceRoot":"","sources":["../../../../fronds/analysis/handlers/DevtoolsHandler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAY,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,WAAW,MAAM,4BAA4B,CAAC;AAerD,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,4EAA4E;IAC5E,KAAK,EAAE,CAAC,UAAU,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAC;CAC5C;AAED,MAAM,CAAC,OAAO,OAAO,eAAe;IACtB,OAAO,CAAC,WAAW;IAA/B,YAAoB,WAAW,EAAE,WAAW,EAAI;IAEhD,6EAA6E;IACvE,OAAO,CAAC,KAAK,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CA0BxG;IAED;;;;;OAKG;YACW,SAAS;CAQxB"}

package/dist/fronds/analysis/handlers/DevtoolsHandler.js

@@ -0,0 +1,61 @@
+import { createHttpTransport } from '@fougere/transport-http/client';
+import { remotesOf } from '@fougere/core/node';
+/**
+ * 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() {
+    return trimmed(process.env.FOUGERE_URL || LOCAL);
+}
+export default class DevtoolsHandler {
+    projectScan;
+    constructor(projectScan) {
+        this.projectScan = projectScan;
+    }
+    /** Read what the running apps have dispatched since a cursor per address. */
+    async execute(input) {
+        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) => {
+            try {
+                const page = await createHttpTransport(one.url)({ entity: 'rpc', op: 'calls' }, { params: {}, query: {}, input: { since: since[one.url] ?? 0 }, state: {} });
+                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.
+     */
+    async addresses(root) {
+        const { config } = await this.projectScan.at(root);
+        const here = local();
+        const remotes = Object.entries(remotesOf(config))
+            .map(([frond, url]) => ({ url: trimmed(url), frond }));
+        return [{ url: here }, ...remotes.filter((one) => one.url !== here)];
+    }
+}
+function trimmed(url) {
+    return url.replace(/\/$/, '');
+}
+function said(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=DevtoolsHandler.js.map

package/dist/fronds/analysis/handlers/DevtoolsHandler.js.map

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

package/dist/fronds/analysis/handlers/ExplainHandler.d.ts

@@ -0,0 +1,99 @@
+import { type EffectiveOperation, type OperationContract } from '@fougere/core';
+import ProjectScan from '../services/ProjectScan.js';
+type Cardinality = NonNullable<OperationContract['cardinality']>;
+export type ExplainedBinding = {
+    kind: 'collector';
+    typeName: string;
+} | {
+    kind: 'fact';
+    factName: string;
+} | {
+    kind: 'param';
+    name: string;
+    coerce?: 'number' | 'boolean';
+} | {
+    kind: 'input';
+} | {
+    kind: 'context';
+} | {
+    kind: 'query';
+};
+export interface ExplainedParameter {
+    name: string;
+    type: string | null;
+    optional: boolean;
+    nullable: boolean;
+    undefinable: boolean;
+    binding: ExplainedBinding | null;
+}
+export interface ExplainedCollector {
+    typeName: string;
+    class: string;
+    file: string;
+}
+/** Stable, JSON-shaped projection of core's canonical EffectiveOperation. */
+export interface ExplainResult {
+    operation: string;
+    handler: {
+        class: string;
+        address: string;
+        method: string;
+        file: string | null;
+    };
+    kind: 'query' | 'command';
+    description: string | null;
+    input: string | null;
+    output: {
+        type: string;
+        cardinality: Cardinality | null;
+    } | null;
+    parameters: ExplainedParameter[];
+    collectors: ExplainedCollector[];
+    contexts: string[];
+    semantics: EffectiveOperation['semantics'];
+    exposure: {
+        surfaces: string[];
+        adapters: string[];
+    };
+    placement: {
+        frond: string;
+        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. */
+export interface ExplainListing {
+    fronds: {
+        name: string;
+        runtime: 'local' | 'remote';
+        remote: string | null;
+        operations: number;
+    }[];
+    operations: string[];
+}
+/** Read one operation directly from the model boot and check also consume. */
+export default class ExplainHandler {
+    private projectScan;
+    constructor(projectScan: ProjectScan);
+    /** The names this project serves — the list `explain` used to spell in a refusal only. */
+    list(input: {
+        root?: string;
+    }): Promise<ExplainListing>;
+    private modelOf;
+    /** Print the contract one operation will be served under. */
+    execute(input: {
+        operation?: string;
+        root?: string;
+        json?: boolean;
+    }): Promise<ExplainResult>;
+}
+export {};
+//# sourceMappingURL=ExplainHandler.d.ts.map

package/dist/fronds/analysis/handlers/ExplainHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExplainHandler.d.ts","sourceRoot":"","sources":["../../../../fronds/analysis/handlers/ExplainHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,WAAW,MAAM,4BAA4B,CAAC;AAIrD,KAAK,WAAW,GAAG,WAAW,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC,CAAC;AAGjE,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;KACrB,CAAC;IACF,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC;IAC3C,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,SAAS,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC;QAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,CAAC;IACF,6FAA6F;IAC7F,KAAK,EAAE;QACL,MAAM,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAA;SAAE,EAAE,CAAC;QACzD,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC;QAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;KACpB,EAAE,CAAC;IACJ,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AASD,8EAA8E;AAC9E,MAAM,CAAC,OAAO,OAAO,cAAc;IACrB,OAAO,CAAC,WAAW;IAA/B,YAAoB,WAAW,EAAE,WAAW,EAAI;IAEhD,0FAA0F;IACpF,IAAI,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAkB5D;YAEa,OAAO;IAarB,6DAA6D;IACvD,OAAO,CAAC,KAAK,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAqClG;CACF"}