@fougere/oclif 0.10.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fougere contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bridge.d.ts

@@ -0,0 +1,27 @@
+/**
+ * An operation's input contract, as oclif's args and flags.
+ *
+ * The same derivation `@fougere/cli` does for citty, against another target: what an entity
+ * states is read once — a closed set becomes an `enum`, a `default(v)` is shown in `--help`,
+ * and a field's own sentence is its description. Nothing is written down twice.
+ *
+ * The ARGUMENTS come from the operation's own input, never from the entity: `list` accepts
+ * nothing while `create` accepts a draft, and an entity-wide derivation would demand a price
+ * to read a list.
+ */
+import { type Fields } from '@fougere/schema';
+import type { ArgInput, FlagInput } from '@oclif/core/interfaces';
+export interface Shape {
+    args: ArgInput;
+    flags: FlagInput;
+}
+export declare function paramsToShape(params: readonly {
+    name: string;
+    type: {
+        name?: string;
+    };
+    optional?: boolean;
+}[]): Shape;
+/** One operation's input, as the pair oclif parses a command line into. */
+export declare function inputToShape(fields: Fields): Shape;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAuC,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEnF,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAclE,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;CAClB;AAcD,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,GAAG,KAAK,CAwBrH;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAmClD"}

package/dist/bridge.js

@@ -0,0 +1,89 @@
+/**
+ * An operation's input contract, as oclif's args and flags.
+ *
+ * The same derivation `@fougere/cli` does for citty, against another target: what an entity
+ * states is read once — a closed set becomes an `enum`, a `default(v)` is shown in `--help`,
+ * and a field's own sentence is its description. Nothing is written down twice.
+ *
+ * The ARGUMENTS come from the operation's own input, never from the entity: `list` accepts
+ * nothing while `create` accepts a draft, and an entity-wide derivation would demand a price
+ * to read a list.
+ */
+import { Lifecycle, Role, Shapes, Visibility } from '@fougere/schema';
+import { Args, Flags } from '@oclif/core';
+/** What a caller supplies: the fields the axes admit, or the PRIMARY when they admit nothing. */
+function suppliedIn(fields) {
+    const written = Visibility.of(fields).input;
+    if (Object.keys(written).length > 0)
+        return written;
+    return Object.fromEntries(Object.entries(fields).filter(([, field]) => Role.of(field).isPrimary));
+}
+const kebab = (name) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+/**
+ * A parameter the scan read off the signature, when the operation names no view.
+ *
+ * `Crud(Product).findById(id: string)` takes a bare string — there is no entity to read axes
+ * from, and the terminal would otherwise offer nothing at all. The signature is what remains,
+ * and it says the name, the type, and whether it is optional.
+ *
+ * A parameter the framework fills is skipped: `user?: User` is resolved from the session, and
+ * `invocation` is the envelope. Neither is a caller's to type.
+ */
+const RESOLVED = new Set(['user', 'invocation', 'ctx', 'context']);
+export function paramsToShape(params) {
+    const args = {};
+    const flags = {};
+    let positional = false;
+    for (const param of params) {
+        if (RESOLVED.has(param.name))
+            continue;
+        const type = param.type.name ?? 'string';
+        if (!/^(string|number|boolean)$/.test(type))
+            continue;
+        const required = param.optional !== true;
+        if (!positional && required && type === 'string') {
+            args[param.name] = Args.string({ required: true });
+            positional = true;
+            continue;
+        }
+        const at = kebab(param.name);
+        flags[at] = type === 'boolean' ? Flags.boolean({})
+            : type === 'number' ? Flags.integer({ required })
+                : Flags.string({ required });
+    }
+    return { args: args, flags: flags };
+}
+/** One operation's input, as the pair oclif parses a command line into. */
+export function inputToShape(fields) {
+    const args = {};
+    const flags = {};
+    let positional = false;
+    for (const [key, field] of Object.entries(suppliedIn(fields))) {
+        if (Role.of(field).isRelation)
+            continue;
+        const { base: shape, nullable } = Shapes.of(field.shape);
+        const type = Shapes.typeOf(field.shape);
+        const description = field.meta?.description;
+        const required = Role.of(field).isPrimary || (!nullable && Lifecycle.of(field).requiredAtCreate);
+        const options = shape?.type === 'string' && shape.enum?.length
+            ? shape.enum.filter((value) => typeof value === 'string')
+            : undefined;
+        // The first required plain string becomes positional, the rule `fougere explain --root`
+        // and `fougere graph <root>` already follow. A closed set stays a flag: its legal values
+        // read better named than guessed by position.
+        if (!positional && required && type === 'text' && !options) {
+            args[key] = Args.string({ description, required: true });
+            positional = true;
+            continue;
+        }
+        const at = kebab(key);
+        const fallback = Lifecycle.of(field).literal?.value;
+        flags[at] = options
+            ? Flags.string({ description, options, required, default: fallback })
+            : type === 'boolean' ? Flags.boolean({ description, default: fallback })
+                : type === 'number' ? Flags.integer({ description, required, default: fallback })
+                    : Flags.string({ description, required, default: fallback });
+    }
+    return { args: args, flags: flags };
+}
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A frond's operations, as a terminal.
+ *
+ * oclif finds its commands in FILES at build time; a frond's are known only after the scan, so
+ * they are built here and handed over as one plugin. What that buys, beside a command per
+ * operation: topics (`product:list` groups under `product` on its own), `--help` per topic and
+ * per command, `--json`, and a parser that refuses a missing flag or a value outside a closed
+ * set before anything runs.
+ *
+ * It is an HOST, at the same rank as `@fougere/nuxt` — the frond decides nothing about it, and
+ * `@fougere/cli` stays on citty: its fifteen commands are flat, one op each, and want none of
+ * the topics that make this worth its weight.
+ */
+import { Command } from '@oclif/core';
+import type { App } from '@fougere/core';
+import { type Shape } from './bridge.js';
+/**
+ * What oclif runs: a command's shape in its cache, plus the way to reach the class.
+ *
+ * Written here rather than imported: `Command.Loadable` lives behind an entry `@oclif/core`
+ * does not export, and what this package builds is exactly these fields.
+ */
+interface Loadable {
+    id: string;
+    aliases: string[];
+    args: Shape['args'];
+    flags: Shape['flags'];
+    description?: string;
+    hidden: boolean;
+    pluginAlias: string;
+    pluginName: string;
+    pluginType: string;
+    load(): Promise<typeof Command>;
+}
+/**
+ * Every operation of every frond, as oclif sees them.
+ *
+ * The identifier is `address:op`, which is what makes a topic: oclif groups by the part before
+ * the colon, so `product:list` and `product:create` answer under `product` without anything
+ * saying so.
+ */
+export declare function commandsOf(app: App): Loadable[];
+/**
+ * Run the app's operations as a CLI.
+ *
+ * The commands are inserted through the door oclif keeps for plugins that produce theirs at
+ * runtime. Its name says `legacy` — it exists for Heroku's older plugins — and it is the only
+ * entry that takes commands nobody read from disk; the alternative is writing a file per
+ * operation, which is the fact this package exists to derive.
+ */
+export declare function serve(app: App, argv?: string[]): Promise<void>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,OAAO,EAAmC,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAE,GAAG,EAAmB,MAAM,eAAe,CAAC;AAC1D,OAAO,EAA+B,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEtE;;;;;GAKG;AACH,UAAU,QAAQ;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACpB,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,IAAI,OAAO,CAAC,OAAO,OAAO,CAAC,CAAC;CACjC;AA8BD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,EAAE,CAyC/C;AAED;;;;;;;GAOG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC3F"}

package/dist/index.js

@@ -0,0 +1,114 @@
+/**
+ * A frond's operations, as a terminal.
+ *
+ * oclif finds its commands in FILES at build time; a frond's are known only after the scan, so
+ * they are built here and handed over as one plugin. What that buys, beside a command per
+ * operation: topics (`product:list` groups under `product` on its own), `--help` per topic and
+ * per command, `--json`, and a parser that refuses a missing flag or a value outside a closed
+ * set before anything runs.
+ *
+ * It is an HOST, at the same rank as `@fougere/nuxt` — the frond decides nothing about it, and
+ * `@fougere/cli` stays on citty: its fifteen commands are flat, one op each, and want none of
+ * the topics that make this worth its weight.
+ */
+import { Command, Config, handle, run as runOclif } from '@oclif/core';
+import { inputToShape, paramsToShape } from './bridge.js';
+const kebab = (name) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`).replace(/^-/, '');
+/** Each entry carries the key it is filed under — what a class-on-disk gets for free. */
+function named(entries) {
+    return Object.fromEntries(Object.entries(entries).map(([name, entry]) => [name, { ...entry, name }]));
+}
+/** One operation, as the class oclif runs. */
+function commandFor(id, call, shape, describe) {
+    const Built = class extends Command {
+        static args = shape.args;
+        static flags = shape.flags;
+        static description = describe;
+        static enableJsonFlag = true;
+        async run() {
+            const { args, flags } = await this.parse(Built);
+            return this.logJson(await call({ ...args, ...flags }));
+        }
+    };
+    Built.id = id;
+    return Built;
+}
+/**
+ * Every operation of every frond, as oclif sees them.
+ *
+ * The identifier is `address:op`, which is what makes a topic: oclif groups by the part before
+ * the colon, so `product:list` and `product:create` answer under `product` without anything
+ * saying so.
+ */
+export function commandsOf(app) {
+    const loadables = [];
+    for (const frond of app.fronds) {
+        for (const handler of frond.handlers) {
+            const facade = app.facadeFor(handler.address);
+            for (const [name, contract] of handler.operations ?? []) {
+                // A view when the op names one, its signature otherwise: `findById(id: string)` takes
+                // a bare parameter, and an entity-shaped derivation would offer nothing at all for it.
+                const fields = contract.input?.getFields?.();
+                const shape = fields
+                    ? inputToShape(fields)
+                    : paramsToShape(contract.signature?.params ?? []);
+                const Built = commandFor(`${handler.address}:${kebab(name)}`, (parsed) => facade[name](fields ? { input: parsed } : { params: parsed }), shape, contract.description);
+                loadables.push({
+                    id: Built.id,
+                    aliases: [],
+                    // `--help` renders from the CACHED shapes, and oclif fills each entry's `name` when
+                    // it reads a class off disk. Nothing reads these off disk, so they are named here —
+                    // without it the renderer meets `undefined.toUpperCase()`.
+                    args: named(Built.args),
+                    flags: named(Built.flags),
+                    description: Built.description,
+                    hidden: false,
+                    pluginAlias: 'fougere',
+                    pluginName: 'fougere',
+                    pluginType: 'core',
+                    load: async () => Built,
+                });
+            }
+        }
+    }
+    return loadables;
+}
+/**
+ * Run the app's operations as a CLI.
+ *
+ * The commands are inserted through the door oclif keeps for plugins that produce theirs at
+ * runtime. Its name says `legacy` — it exists for Heroku's older plugins — and it is the only
+ * entry that takes commands nobody read from disk; the alternative is writing a file per
+ * operation, which is the fact this package exists to derive.
+ */
+export async function serve(app, argv = process.argv.slice(2)) {
+    const config = await Config.load({ root: process.cwd() });
+    const commands = commandsOf(app);
+    // `insertLegacyPlugins` is typed private: it exists for Heroku's older plugins, and it is the
+    // only entry that takes commands nobody read from disk. The cast is the whole risk this
+    // package carries — the alternative is a file per operation, which is the fact it derives.
+    const insert = config;
+    insert.insertLegacyPlugins([{
+            name: 'fougere',
+            alias: 'fougere',
+            commands,
+            commandIDs: commands.map((one) => one.id),
+            topics: [],
+            hooks: {},
+            isRoot: false,
+            moduleType: 'module',
+            pjson: { name: 'fougere', version: '0.0.0', oclif: {} },
+            root: process.cwd(),
+            type: 'core',
+            valid: true,
+            version: '0.0.0',
+            _base: '',
+            hasManifest: false,
+            options: {},
+            commandsDir: undefined,
+            load: async () => { },
+            findCommand: async (id) => commands.find((one) => one.id === id)?.load(),
+        }]);
+    await runOclif(argv, config).catch(handle);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@fougere/oclif",
+  "version": "0.10.0-alpha.0",
+  "description": "A frond's operations, as a terminal: topics, flags and help derived from what it declares.",
+  "keywords": [
+    "fougere",
+    "oclif",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chok/fougere.git",
+    "directory": "packages/app/oclif"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "template"
+  ],
+  "dependencies": {
+    "@fougere/core": "0.10.0-alpha.0",
+    "@fougere/schema": "0.10.0-alpha.0"
+  },
+  "devDependencies": {
+    "@oclif/core": "^5.0.0",
+    "vitest": "^4.1.2"
+  },
+  "peerDependencies": {
+    "@oclif/core": "^4.0.0 || ^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json"
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,107 @@
+/**
+ * An operation's input contract, as oclif's args and flags.
+ *
+ * The same derivation `@fougere/cli` does for citty, against another target: what an entity
+ * states is read once — a closed set becomes an `enum`, a `default(v)` is shown in `--help`,
+ * and a field's own sentence is its description. Nothing is written down twice.
+ *
+ * The ARGUMENTS come from the operation's own input, never from the entity: `list` accepts
+ * nothing while `create` accepts a draft, and an entity-wide derivation would demand a price
+ * to read a list.
+ */
+import { Lifecycle, Role, Shapes, Visibility, type Fields } from '@fougere/schema';
+import { Args, Flags } from '@oclif/core';
+import type { ArgInput, FlagInput } from '@oclif/core/interfaces';
+
+/** What a caller supplies: the fields the axes admit, or the PRIMARY when they admit nothing. */
+function suppliedIn(fields: Fields): Fields {
+  const written = Visibility.of(fields).input;
+  if (Object.keys(written).length > 0) return written;
+
+  return Object.fromEntries(
+    Object.entries(fields).filter(([, field]) => Role.of(field).isPrimary),
+  ) as Fields;
+}
+
+const kebab = (name: string): string => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+
+export interface Shape {
+  args: ArgInput;
+  flags: FlagInput;
+}
+
+/**
+ * A parameter the scan read off the signature, when the operation names no view.
+ *
+ * `Crud(Product).findById(id: string)` takes a bare string — there is no entity to read axes
+ * from, and the terminal would otherwise offer nothing at all. The signature is what remains,
+ * and it says the name, the type, and whether it is optional.
+ *
+ * A parameter the framework fills is skipped: `user?: User` is resolved from the session, and
+ * `invocation` is the envelope. Neither is a caller's to type.
+ */
+const RESOLVED = new Set(['user', 'invocation', 'ctx', 'context']);
+
+export function paramsToShape(params: readonly { name: string; type: { name?: string }; optional?: boolean }[]): Shape {
+  const args: Record<string, unknown> = {};
+  const flags: Record<string, unknown> = {};
+  let positional = false;
+
+  for (const param of params) {
+    if (RESOLVED.has(param.name)) continue;
+    const type = param.type.name ?? 'string';
+    if (!/^(string|number|boolean)$/.test(type)) continue;
+
+    const required = param.optional !== true;
+    if (!positional && required && type === 'string') {
+      args[param.name] = Args.string({ required: true });
+      positional = true;
+      continue;
+    }
+
+    const at = kebab(param.name);
+    flags[at] = type === 'boolean' ? Flags.boolean({})
+      : type === 'number' ? Flags.integer({ required })
+      : Flags.string({ required });
+  }
+
+  return { args: args as ArgInput, flags: flags as FlagInput };
+}
+
+/** One operation's input, as the pair oclif parses a command line into. */
+export function inputToShape(fields: Fields): Shape {
+  const args: Record<string, unknown> = {};
+  const flags: Record<string, unknown> = {};
+  let positional = false;
+
+  for (const [key, field] of Object.entries(suppliedIn(fields))) {
+    if (Role.of(field).isRelation) continue;
+
+    const { base: shape, nullable } = Shapes.of(field.shape);
+    const type = Shapes.typeOf(field.shape);
+    const description = field.meta?.description;
+    const required = Role.of(field).isPrimary || (!nullable && Lifecycle.of(field).requiredAtCreate);
+    const options = shape?.type === 'string' && shape.enum?.length
+      ? shape.enum.filter((value): value is string => typeof value === 'string')
+      : undefined;
+
+    // The first required plain string becomes positional, the rule `fougere explain --root`
+    // and `fougere graph <root>` already follow. A closed set stays a flag: its legal values
+    // read better named than guessed by position.
+    if (!positional && required && type === 'text' && !options) {
+      args[key] = Args.string({ description, required: true });
+      positional = true;
+      continue;
+    }
+
+    const at = kebab(key);
+    const fallback = Lifecycle.of(field).literal?.value;
+    flags[at] = options
+      ? Flags.string({ description, options, required, default: fallback as string | undefined })
+      : type === 'boolean' ? Flags.boolean({ description, default: fallback as boolean | undefined })
+      : type === 'number' ? Flags.integer({ description, required, default: fallback as number | undefined })
+      : Flags.string({ description, required, default: fallback as string | undefined });
+  }
+
+  return { args: args as ArgInput, flags: flags as FlagInput };
+}

package/src/index.ts

@@ -0,0 +1,155 @@
+/**
+ * A frond's operations, as a terminal.
+ *
+ * oclif finds its commands in FILES at build time; a frond's are known only after the scan, so
+ * they are built here and handed over as one plugin. What that buys, beside a command per
+ * operation: topics (`product:list` groups under `product` on its own), `--help` per topic and
+ * per command, `--json`, and a parser that refuses a missing flag or a value outside a closed
+ * set before anything runs.
+ *
+ * It is an HOST, at the same rank as `@fougere/nuxt` — the frond decides nothing about it, and
+ * `@fougere/cli` stays on citty: its fifteen commands are flat, one op each, and want none of
+ * the topics that make this worth its weight.
+ */
+import { Command, Config, handle, run as runOclif } from '@oclif/core';
+import type { App, FrondDescriptor } from '@fougere/core';
+import { inputToShape, paramsToShape, type Shape } from './bridge.js';
+
+/**
+ * What oclif runs: a command's shape in its cache, plus the way to reach the class.
+ *
+ * Written here rather than imported: `Command.Loadable` lives behind an entry `@oclif/core`
+ * does not export, and what this package builds is exactly these fields.
+ */
+interface Loadable {
+  id: string;
+  aliases: string[];
+  args: Shape['args'];
+  flags: Shape['flags'];
+  description?: string;
+  hidden: boolean;
+  pluginAlias: string;
+  pluginName: string;
+  pluginType: string;
+  load(): Promise<typeof Command>;
+}
+
+const kebab = (name: string): string => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`).replace(/^-/, '');
+
+/** Each entry carries the key it is filed under — what a class-on-disk gets for free. */
+function named<T extends Record<string, object>>(entries: T): T {
+  return Object.fromEntries(
+    Object.entries(entries).map(([name, entry]) => [name, { ...entry, name }]),
+  ) as T;
+}
+
+/** One operation, as the class oclif runs. */
+function commandFor(id: string, call: (input: Record<string, unknown>) => Promise<unknown>, shape: Shape, describe?: string) {
+  const Built = class extends Command {
+    static override args = shape.args;
+    static override flags = shape.flags;
+    static override description = describe;
+    static override enableJsonFlag = true;
+
+    async run(): Promise<unknown> {
+      const { args, flags } = await this.parse(Built);
+
+      return this.logJson(await call({ ...args, ...flags }));
+    }
+  };
+  Built.id = id;
+
+  return Built;
+}
+
+/**
+ * Every operation of every frond, as oclif sees them.
+ *
+ * The identifier is `address:op`, which is what makes a topic: oclif groups by the part before
+ * the colon, so `product:list` and `product:create` answer under `product` without anything
+ * saying so.
+ */
+export function commandsOf(app: App): Loadable[] {
+  const loadables: Loadable[] = [];
+
+  for (const frond of app.fronds as readonly FrondDescriptor[]) {
+    for (const handler of frond.handlers) {
+      const facade = app.facadeFor(handler.address) as Record<string, (input?: unknown) => Promise<unknown>>;
+
+      for (const [name, contract] of handler.operations ?? []) {
+        // A view when the op names one, its signature otherwise: `findById(id: string)` takes
+        // a bare parameter, and an entity-shaped derivation would offer nothing at all for it.
+        const fields = contract.input?.getFields?.();
+        const shape = fields
+          ? inputToShape(fields)
+          : paramsToShape(contract.signature?.params ?? []);
+        const Built = commandFor(
+          `${handler.address}:${kebab(name)}`,
+          (parsed) => facade[name]!(fields ? { input: parsed } : { params: parsed }),
+          shape,
+          contract.description,
+        );
+
+        loadables.push({
+          id: Built.id,
+          aliases: [],
+          // `--help` renders from the CACHED shapes, and oclif fills each entry's `name` when
+          // it reads a class off disk. Nothing reads these off disk, so they are named here —
+          // without it the renderer meets `undefined.toUpperCase()`.
+          args: named(Built.args),
+          flags: named(Built.flags),
+          description: Built.description,
+          hidden: false,
+          pluginAlias: 'fougere',
+          pluginName: 'fougere',
+          pluginType: 'core',
+          load: async () => Built,
+        } as Loadable);
+      }
+    }
+  }
+
+  return loadables;
+}
+
+/**
+ * Run the app's operations as a CLI.
+ *
+ * The commands are inserted through the door oclif keeps for plugins that produce theirs at
+ * runtime. Its name says `legacy` — it exists for Heroku's older plugins — and it is the only
+ * entry that takes commands nobody read from disk; the alternative is writing a file per
+ * operation, which is the fact this package exists to derive.
+ */
+export async function serve(app: App, argv: string[] = process.argv.slice(2)): Promise<void> {
+  const config = await Config.load({ root: process.cwd() });
+  const commands = commandsOf(app);
+
+  // `insertLegacyPlugins` is typed private: it exists for Heroku's older plugins, and it is the
+  // only entry that takes commands nobody read from disk. The cast is the whole risk this
+  // package carries — the alternative is a file per operation, which is the fact it derives.
+  const insert = config as unknown as { insertLegacyPlugins(plugins: unknown[]): void };
+
+  insert.insertLegacyPlugins([{
+    name: 'fougere',
+    alias: 'fougere',
+    commands,
+    commandIDs: commands.map((one) => one.id),
+    topics: [],
+    hooks: {},
+    isRoot: false,
+    moduleType: 'module',
+    pjson: { name: 'fougere', version: '0.0.0', oclif: {} },
+    root: process.cwd(),
+    type: 'core',
+    valid: true,
+    version: '0.0.0',
+    _base: '',
+    hasManifest: false,
+    options: {},
+    commandsDir: undefined,
+    load: async () => {},
+    findCommand: async (id: string) => commands.find((one) => one.id === id)?.load(),
+  }]);
+
+  await runOclif(argv, config).catch(handle);
+}

package/template/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "fougere-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/main.ts"
+  },
+  "dependencies": {
+    "@fougere/core": "latest",
+    "@fougere/defaults": "latest",
+    "@fougere/oclif": "latest",
+    "@fougere/schema": "latest",
+    "@fougere/container": "latest",
+    "@oclif/core": "^5.0.0",
+    "better-sqlite3": "^13.0.3",
+    "kysely": "^0.28.17"
+  },
+  "devDependencies": {
+    "tsx": "^4.21.0"
+  }
+}

package/template/src/main.ts

@@ -0,0 +1,20 @@
+/**
+ * Every operation of every frond, as a command.
+ *
+ * Try `--help`: the topics are the addresses, the flags are the entity's fields, and the
+ * legal values of a closed set are listed because `oneOf` named them. Nothing below says
+ * anything about a terminal.
+ */
+import { bootApp } from '@fougere/defaults';
+import { setLogLevel } from '@fougere/core';
+import { serve } from '@fougere/oclif';
+import { join } from 'node:path';
+
+// stdout is a protocol here — `--json` is meant to reach `jq`, and the boot writes with
+// `console.info`. A refusal still reaches stderr, where a shell expects it.
+setLogLevel('error');
+
+const app = await bootApp(join(import.meta.dirname, '..', '..', '..'));
+
+await serve(app);
+await app.dispose();

package/template/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "types": [
+      "node"
+    ],
+    "paths": {
+      "@fronds/facade": [
+        "./.fougere/facade.generated.ts"
+      ]
+    }
+  },
+  "include": [
+    "src"
+  ]
+}