@fougere/nuxt 0.1.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/README.md

@@ -0,0 +1,17 @@
+# @fougere/nuxt
+> The client primitives and the server surface
+`useQuery` / `useCommand` (the pair — a command on X revalidates the mounted queries on
+X), `useFormFor` (a contract, not a rendering), `useCurrentUser`, and `invoke` on the
+server side. The metadata IS the imported entity class — nothing is serialized to the
+browser.
+
+## Installation
+```bash
+pnpm add @fougere/nuxt
+```
+
+---
+
+Part of [Fougere](https://github.com/chok/fougere) — one schema, a gradient from
+monolith to distributed, the same user code.
+Reference documentation: [the site](https://chok.github.io/fougere/) (en/fr).

package/dist/module.d.ts

@@ -0,0 +1,16 @@
+import type { SeedEntry, FougereConfig } from '@fougere/core';
+export interface FougereModuleOptions {
+    /** Override fougere.config.ts values from nuxt.config. Optional. */
+    db?: FougereConfig['db'];
+    frondsDir?: string;
+    /**
+     * Where `fronds/` lives, relative to the app's rootDir. Default: the app
+     * itself. Set to `../..` for an app under `apps/*` in a workspace whose
+     * fronds are shared at the root. Config and `.fougere` stay app-local.
+     */
+    root?: string;
+}
+declare const module: import("@nuxt/schema").NuxtModule<FougereModuleOptions, FougereModuleOptions, false>;
+export default module;
+export declare function generateBootPlugin(config: FougereConfig, seeds: SeedEntry[], fougereAppPath: string): string;
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAK9D,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,EAAE,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAGD,QAAA,MAAM,MAAM,sFA4JV,CAAC;eAEY,MAAM;AAMrB,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,SAAS,EAAE,EAClB,cAAc,EAAE,MAAM,GACrB,MAAM,CA+DR"}

package/dist/module.js

@@ -0,0 +1,215 @@
+/**
+ * @fougere/nuxt — Nuxt module: scans fronds, registers the four
+ * primitives (useQuery/useCommand, useFormFor, useCurrentUser) and the
+ * server surface (call envelope, session, REST bridge, auth).
+ */
+import { defineNuxtModule, addServerHandler, addServerImportsDir, addServerPlugin, addPlugin, addTemplate, addImports, createResolver, } from '@nuxt/kit';
+import { scanProject, frondAliases, FROND_DIRS, setModuleLoader, loadCascadedConfig, orderSeeds } from '@fougere/core';
+import { declaresStorage } from '@fougere/runtime';
+import { createJiti } from 'jiti';
+import { resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+const module = defineNuxtModule({
+    meta: {
+        name: '@fougere/nuxt',
+        configKey: 'fougere',
+    },
+    defaults: {
+        frondsDir: 'fronds',
+    },
+    async setup(options, nuxt) {
+        const { resolve: resolveModule } = createResolver(import.meta.url);
+        const runtimeResolve = (...path) => resolveModule('../src/runtime', ...path);
+        const rootDir = nuxt.options.rootDir;
+        // Fronds may live at the workspace root (app under apps/*); config/.fougere stay app-local.
+        const scanRoot = options.root ? resolve(rootDir, options.root) : rootDir;
+        // The runtime app (fougereApp) scans fronds too; hand it the same root via
+        // env (the Nitro dev worker inherits the parent env, like FORCE_COLOR above).
+        process.env.FOUGERE_ROOT = scanRoot;
+        // Propagate color support to Nitro dev worker (inherits parent env but has no TTY)
+        if (process.stdout?.isTTY && !process.env.NO_COLOR) {
+            process.env.FORCE_COLOR ??= '1';
+        }
+        // Prevent Nitro from bundling the TypeScript compiler (~9 MB).
+        // @fougere/core lazy-imports it, but Rollup still code-splits dynamic imports
+        // into the bundle — only external truly excludes it.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        nuxt.hook('nitro:config', (nitroConfig) => {
+            nitroConfig.rollupConfig ??= {};
+            nitroConfig.rollupConfig.external ??= [];
+            if (Array.isArray(nitroConfig.rollupConfig.external)) {
+                nitroConfig.rollupConfig.external.push('typescript');
+            }
+            // invoke reads the current request (state) through nitro's async context
+            nitroConfig.experimental = { ...nitroConfig.experimental, asyncContext: true };
+        });
+        // ── 0. Setup TS-aware module loader before reading any user config ──
+        // The Vite alias below covers `.vue` pages; this covers the SCAN, which loads a
+        // frond's own sources — so `@frond/user/entities/User.js` inside a handler resolves
+        // for the same reason it does in a page.
+        const jiti = createJiti(import.meta.url, { interopDefault: true, alias: await frondAliases(scanRoot) });
+        setModuleLoader((filePath) => jiti.import(filePath));
+        // ── 0b. Load fougere.config.ts along the workspace→app cascade (scanRoot is
+        //        the workspace when the app declares `root`); module options override. ──
+        const fileConfig = await loadCascadedConfig(scanRoot, rootDir);
+        const optionsOverride = Object.fromEntries(Object.entries(options).filter(([, v]) => v !== undefined));
+        const config = { db: 'sqlite', ...fileConfig, ...optionsOverride };
+        // ── 1. Scan fronds (filtered by FOUGERE_FRONDS env var) ──
+        const frondsFilter = process.env.FOUGERE_FRONDS?.split(',').map((s) => s.trim()).filter(Boolean);
+        const { fronds } = await scanProject(scanRoot, frondsFilter);
+        // ── 1b. Register @frond/* aliases for all fronds, and watch them ──
+        // The scanned fronds ARE the watch list — nothing to declare. Without this, a
+        // frond under `apps/../..` sits outside rootDir, so Nuxt never restarts: the scan,
+        // the additive migration (once per boot) and the seeds all keep the previous shape,
+        // and a field you just added is simply absent with no error anywhere.
+        // The root frond IS the scan root, so watching its path would match every write in
+        // the project — `.nuxt/`, `node_modules/`, the build output. Its convention
+        // directories are the frond, and they are what changes when the domain changes.
+        for (const frond of fronds) {
+            nuxt.options.alias[`@frond/${frond.name}`] = frond.source.path;
+            const watched = frond.source.path === scanRoot
+                ? FROND_DIRS.map((dir) => resolve(scanRoot, dir))
+                : [frond.source.path];
+            nuxt.options.watch.push(...watched);
+        }
+        // ── 1c. Register aliases for synced remote fronds (.fougere/remotes.json) ──
+        const remotesPath = resolve(rootDir, '.fougere', 'remotes.json');
+        if (existsSync(remotesPath)) {
+            try {
+                const remotes = JSON.parse(readFileSync(remotesPath, 'utf-8'));
+                for (const [name, meta] of Object.entries(remotes)) {
+                    // Don't override locally scanned fronds
+                    if (!nuxt.options.alias[`@frond/${name}`]) {
+                        nuxt.options.alias[`@frond/${name}`] = meta.path;
+                        // Ensure Vite/Nitro can resolve files inside synced remotes
+                        nuxt.options.build.transpile.push(meta.path);
+                    }
+                }
+            }
+            catch { /* corrupt remotes.json — skip */ }
+        }
+        // ── 2. Composables — the primitives, nothing else ──
+        addImports([
+            { name: 'useQuery', from: runtimeResolve('composables/useFougereData') },
+            { name: 'useCommand', from: runtimeResolve('composables/useFougereData') },
+            { name: 'useFormFor', from: runtimeResolve('composables/useFormFor') },
+            { name: 'useCurrentUser', from: runtimeResolve('composables/useCurrentUser') },
+        ]);
+        // ── 3. Server: call envelope endpoint + catch-all route + shared utils ────
+        addServerHandler({
+            route: '/_fougere/call',
+            method: 'post',
+            handler: runtimeResolve('server/routes/call.post'),
+        });
+        // The same door, per audience: `/_fougere/call/public` serves the surface named
+        // `public`, the way `generateRoutes(app, { surface })` does for REST. The handler
+        // reads the segment (see `surfaceOf`).
+        addServerHandler({
+            route: '/_fougere/call/**',
+            method: 'post',
+            handler: runtimeResolve('server/routes/call.post'),
+        });
+        addServerHandler({
+            route: '/_fougere/session',
+            method: 'get',
+            handler: runtimeResolve('server/routes/session.get'),
+        });
+        // Session hydration — the page ships with its user, no round-trip
+        addPlugin({ src: runtimeResolve('plugins/session.server'), mode: 'server' });
+        addServerHandler({
+            route: '/api/**',
+            handler: runtimeResolve('server/api/crud'),
+        });
+        addServerImportsDir(runtimeResolve('server/utils'));
+        // ── 5b. Auth (mounted when fougere.config.ts declares `auth`) ──
+        if (config.auth) {
+            // Session middleware — resolves user on every request
+            addServerHandler({
+                middleware: true,
+                handler: runtimeResolve('server/auth/middleware/auth'),
+            });
+            // Auth catch-all route (login, register, callback, etc.)
+            addServerHandler({
+                route: '/auth/**',
+                handler: runtimeResolve('server/auth/routes/auth/[...]'),
+            });
+            // /api/me — current user endpoint
+            addServerHandler({
+                route: '/api/me',
+                method: 'get',
+                handler: runtimeResolve('server/auth/routes/api/me.get'),
+            });
+        }
+        // ── 6. Boot plugin (virtual — lives in .nuxt/) ───
+        const allSeeds = orderSeeds(fronds);
+        const bootTpl = addTemplate({
+            filename: 'fougere-boot.ts',
+            write: true,
+            getContents: () => generateBootPlugin(config, allSeeds, runtimeResolve('server/utils/fougereApp')),
+        });
+        addServerPlugin(bootTpl.dst);
+    },
+});
+export default module;
+// ── Boot plugin generation ─────────────────────────
+// Exported (not just module-internal) so its output is unit-testable without
+// spinning up a whole Nuxt build.
+export function generateBootPlugin(config, seeds, fougereAppPath) {
+    const lines = [];
+    lines.push(`// Auto-generated by @fougere/nuxt — do not edit`);
+    // Explicit imports — nitro's auto-imports don't reach this template in a prod build
+    lines.push(`import { defineNitroPlugin } from 'nitropack/runtime';`);
+    lines.push(`import { configureFougere } from '${fougereAppPath}';`);
+    if (seeds.length)
+        lines.push(`import { runSeeds } from '@fougere/core';`);
+    const db = config.db ?? 'sqlite';
+    // `declaresStorage` is the canonical reader of `db:` — asked, not re-interpreted.
+    // Reading `dialect` here made this codegen a SECOND reader, and the two disagreed:
+    // any value but 'sqlite' emitted an empty plugin, so no config, no seeds, not a word.
+    // resolveStorage now refuses an unresolvable dialect by name, at boot, out loud.
+    if (!declaresStorage(db)) {
+        lines.push(`export default defineNitroPlugin(() => {});`);
+        return lines.join('\n') + '\n';
+    }
+    // The generated plugin names no storage package — resolution lives in
+    // @fougere/runtime, the one place that knows which engine backs `db:`.
+    lines.push(`import { resolveStorage } from '@fougere/runtime';`);
+    lines.push(``);
+    // Seed imports
+    for (let i = 0; i < seeds.length; i++) {
+        lines.push(`import seed_${i} from '${seeds[i].filePath}';`);
+    }
+    if (seeds.length)
+        lines.push(``);
+    // Wrap all init in the plugin callback to avoid top-level native calls
+    lines.push(`export default defineNitroPlugin(async () => {`);
+    // Pass `db` through unchanged — resolveStorage (@fougere/runtime → setupSqlite)
+    // is the one place that defaults an absent path, so both call sites (this
+    // codegen'd plugin and fougereApp.ts's own fallback) land on the same file.
+    lines.push(`  const storage = resolveStorage(${JSON.stringify(db)});`);
+    lines.push(``);
+    lines.push(`  configureFougere({`);
+    lines.push(`    db: storage.db,`);
+    lines.push(`    ormFactory: storage.ormFactory,`);
+    lines.push(`    async afterBoot(app) {`);
+    lines.push(`      await storage.afterBoot?.(app);`);
+    if (seeds.length) {
+        // The seeding LOOP is core's (`runSeeds`), not written out here: a second copy
+        // drifted, and the one that had lost its storage fallback was this one — the one
+        // that actually runs when you open the app. Codegen's only job is the static
+        // imports, which is the one thing a bundler needs spelled out.
+        //
+        // `report` is passed: its default is a no-op, so the boot you actually open said
+        // nothing about a skipped seed — the very silence F-12 was aggravated by.
+        lines.push(`      await runSeeds(app, [`);
+        for (let i = 0; i < seeds.length; i++) {
+            lines.push(`        { entityName: '${seeds[i].entityName}', data: seed_${i}, filePath: ${JSON.stringify(seeds[i].filePath)} },`);
+        }
+        lines.push(`      ], (message) => console.log('[fougere:seed]' + message));`);
+    }
+    lines.push(`    },`);
+    lines.push(`  });`);
+    lines.push(`});`);
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=module.js.map

package/dist/module.js.map

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

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@fougere/nuxt",
+  "version": "0.1.0-alpha.0",
+  "description": "The Nuxt module: Fougere's client primitives and server surface.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chok/fougere.git",
+    "directory": "packages/app/nuxt"
+  },
+  "type": "module",
+  "main": "dist/module.js",
+  "types": "dist/module.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/runtime"
+  ],
+  "dependencies": {
+    "@nuxt/kit": "^4.5.1",
+    "jiti": "^2.6.1",
+    "@fougere/container-fougere": "0.1.0-alpha.0",
+    "@fougere/runtime": "0.1.0-alpha.0",
+    "@fougere/schema": "0.1.0-alpha.0",
+    "@fougere/core": "0.1.0-alpha.0",
+    "@fougere/transport-http": "0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "@nuxt/schema": "^4.5.1",
+    "nitropack": "^2.13.2",
+    "nuxt": "^4.5.1",
+    "vue": "^3.5.40",
+    "vitest": "^4.1.0"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.0.0",
+    "vue": "^3.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/runtime/composables/useCurrentUser.ts

@@ -0,0 +1,25 @@
+/**
+ * The session: resolved once server-side, hydrated with the page, read
+ * here as reactive state. refresh() re-reads it after a client-side
+ * auth change (login, logout) — no page reload, no hand-rolled /api/me.
+ *
+ * `session` is the whole view (extensible context); `user` is its
+ * everyday projection.
+ */
+import { useState, useRequestFetch } from '#imports';
+import { computed } from 'vue';
+import type { SessionView } from '../session/view.js';
+
+export function useCurrentUser<TUser = Record<string, unknown>>() {
+  const session = useState<SessionView>('fougere:session', () => ({ user: null }));
+  const fetcher = useRequestFetch();
+
+  const user = computed(() => (session.value.user ?? null) as TUser | null);
+  const loggedIn = computed(() => session.value.user != null);
+
+  async function refresh(): Promise<void> {
+    session.value = await fetcher<SessionView>('/_fougere/session');
+  }
+
+  return { session, user, loggedIn, refresh };
+}

package/src/runtime/composables/useFormFor.ts

@@ -0,0 +1,87 @@
+/**
+ * The form contract — state, validation, submission, error mapping.
+ * Never a widget: the page owns the rendering, this owns the mechanics.
+ *
+ * The cycle composes the other primitives: fields from the io axes,
+ * local pre-judgment with the same rules the handler enforces (one
+ * declaration, both sides), submission through the command (so the
+ * entity link revalidates mounted queries), and per-field errors in
+ * the same `{ path, message }` shape whoever judged.
+ */
+import { reactive, computed } from 'vue';
+import { FougereError, ErrorCode, toRegistrationName } from '@fougere/core/contract';
+import { useCommand } from './useFougereData.js';
+import { formFieldsOf, payloadOf, errorsByField, type FormEntity, type FormField } from '../form/fields.js';
+
+export interface FormOptions {
+  /** Command the submit rides. Default: 'create'. */
+  op?: string;
+  /** Initial values (edit mode: the loaded entity). */
+  initial?: Record<string, unknown>;
+  /** Call params designating the target (edit mode: { id }). */
+  params?: Record<string, string>;
+}
+
+export function useFormFor<T = Record<string, unknown>>(entity: FormEntity, options: FormOptions = {}) {
+  const entityKey = toRegistrationName(entity.name);
+  const fields: FormField[] = formFieldsOf(entity, entityKey);
+
+  // `initial` wins over the declared default: editing a row shows the row, including a
+  // value the author deliberately changed away from that default. On a create form
+  // there is no `initial`, so the field opens on what is about to be written — the
+  // schema's own literal, shown rather than guessed by the page.
+  const values = reactive<Record<string, unknown>>(
+    Object.fromEntries(fields.map((f) => [f.name, options.initial?.[f.name] ?? f.default])),
+  );
+  const errors = reactive<Record<string, string>>({});
+  const command = useCommand<T>(entity, options.op ?? 'create');
+
+  function clearErrors() {
+    for (const key of Object.keys(errors)) delete errors[key];
+  }
+
+  /** Local pre-judgment — same rules as the handler, saves a lost round-trip. */
+  function judge(): boolean {
+    clearErrors();
+    const result = entity.validate(payloadOf(values));
+    if (result.success) return true;
+    Object.assign(errors, errorsByField(result.errors));
+    return false;
+  }
+
+  /**
+   * Judge locally, then send through the command. Returns the created/updated
+   * value, or null when a judge (either side) rejected — the errors land per
+   * field either way, the form never knows who judged.
+   */
+  async function submit(): Promise<T | null> {
+    if (!judge()) return null;
+    try {
+      return await command.execute({ params: options.params, body: payloadOf(values) });
+    } catch (err) {
+      if (err instanceof FougereError && err.code === ErrorCode.VALIDATION_FAILED && Array.isArray(err.details)) {
+        Object.assign(errors, errorsByField(err.details as { path: string; message: string }[]));
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  return {
+    fields,
+    /**
+     * The same fields, keyed by name — a form that lays its inputs out by hand binds
+     * one at a time (`v-bind="fieldsByName.email.attrs"`), and still states no rule of
+     * its own. Without it, a page retypes `type="email"` next to a card that says
+     * `format: 'email'`, and the browser enforces the page rather than the declaration.
+     */
+    fieldsByName: Object.fromEntries(fields.map((f) => [f.name, f])) as Record<string, FormField>,
+    values,
+    errors,
+    submit,
+    loading: command.loading,
+    /** Non-validation failure of the last submit (unreachable host, conflict…). */
+    error: command.error,
+    valid: computed(() => Object.keys(errors).length === 0),
+  };
+}

package/src/runtime/composables/useFougereData.ts

@@ -0,0 +1,128 @@
+/**
+ * The couple — useQuery (reads) and useCommand (writes), the two dual
+ * gestures of a page talking to a Frond. Designation is class + verb:
+ * the imported entity class carries the metadata, its name carries the
+ * registration key.
+ *
+ * Both gestures ride the call envelope: the browser POSTs JSON-RPC to
+ * /_fougere/call; during SSR Nuxt collapses the same call to an
+ * in-process fetch (no network, no port).
+ *
+ * The link: a successful command on an entity revalidates every mounted
+ * query on that entity — designation gives the entity on both sides,
+ * nothing to declare.
+ */
+import { useAsyncData, useRequestFetch, refreshNuxtData } from '#imports';
+import { ref, computed, toValue, onScopeDispose, type MaybeRefOrGetter, type Ref } from 'vue';
+import {
+  FougereError,
+  ErrorCode,
+  toRegistrationName,
+  type InvocationContext,
+  type FrondCall,
+} from '@fougere/core/contract';
+import { frameCall, unframeResponse, type RpcResponse } from '@fougere/transport-http/client';
+
+/** An entity class is a designation: its name is the registration key. */
+type EntityClass = { name: string };
+
+/** What a page provides of an invocation — the rest is stamped server-side. */
+export type CallInput = Partial<Pick<InvocationContext, 'params' | 'query' | 'body'>>;
+
+let nextId = 1;
+
+/** Mounted queries per entity — the command side of the link reads this. */
+const mounted = new Map<string, Set<string>>();
+
+function invocationOf(input?: CallInput): InvocationContext {
+  return { params: {}, query: {}, body: undefined, state: {}, ...input };
+}
+
+type Fetcher = <T>(url: string, options: { method: 'POST'; body: unknown }) => Promise<T>;
+
+async function send(fetcher: Fetcher, call: FrondCall, invocation: InvocationContext): Promise<unknown> {
+  const response = await fetcher<RpcResponse>('/_fougere/call', {
+    method: 'POST',
+    body: frameCall(call, invocation, nextId++),
+  });
+  return unframeResponse(response, call);
+}
+
+export async function useQuery<T = Record<string, unknown>>(
+  entity: EntityClass,
+  op: string,
+  input?: MaybeRefOrGetter<CallInput | undefined>,
+  opts?: { immediate?: boolean },
+) {
+  const entityKey = toRegistrationName(entity.name);
+  const call: FrondCall = { entity: entityKey, op };
+  const key = `fougere:${entityKey}.${op}:${JSON.stringify(toValue(input) ?? {})}`;
+  const fetcher = useRequestFetch() as Fetcher;
+
+  // Register before any await — the link and scope cleanup need the setup scope.
+  if (import.meta.client) {
+    const keys = mounted.get(entityKey) ?? new Set<string>();
+    keys.add(key);
+    mounted.set(entityKey, keys);
+    onScopeDispose(() => keys.delete(key));
+  }
+
+  const { data, pending, error, refresh } = await useAsyncData(
+    key,
+    () => send(fetcher, call, invocationOf(toValue(input))),
+    {
+      ...(input === undefined ? {} : { watch: [() => toValue(input)] }),
+      ...(opts?.immediate === false ? { immediate: false } : {}),
+    },
+  );
+
+  // A list result reads as items/total/hasMore whatever the wire delivered.
+  const items = computed<T[]>(() => {
+    const v = data.value as unknown;
+    if (Array.isArray(v)) return v as T[];
+    if (v && typeof v === 'object' && Array.isArray((v as { items?: unknown }).items)) {
+      return (v as { items: T[] }).items;
+    }
+    return [];
+  });
+  const total = computed(() => (data.value as { total?: number } | null)?.total);
+  const hasMore = computed(() => (data.value as { hasMore?: boolean } | null)?.hasMore);
+
+  return { data: data as Ref<T | null>, items, total, hasMore, loading: pending, error, refresh };
+}
+
+export function useCommand<T = unknown>(entity: EntityClass, op: string) {
+  const entityKey = toRegistrationName(entity.name);
+  const call: FrondCall = { entity: entityKey, op };
+  const fetcher = useRequestFetch() as Fetcher;
+  const loading = ref(false);
+  const error = ref<FougereError | null>(null);
+
+  async function execute(input?: CallInput): Promise<T> {
+    loading.value = true;
+    error.value = null;
+    try {
+      const result = (await send(fetcher, call, invocationOf(input))) as T;
+      // The link: same entity designated on both sides → revalidate its queries.
+      const keys = mounted.get(entityKey);
+      if (keys?.size) await refreshNuxtData([...keys]);
+      return result;
+    } catch (err) {
+      error.value =
+        err instanceof FougereError
+          ? err
+          : new FougereError({
+              code: ErrorCode.SERVICE_UNAVAILABLE,
+              message: (err as Error)?.message ?? String(err),
+              entity: entityKey,
+              operation: op,
+              cause: err,
+            });
+      throw error.value;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  return { execute, loading, error };
+}