@fougere/core 0.3.0-alpha.0 → 0.4.0-alpha.0

package/src/boot/HandlerFacade.ts

@@ -0,0 +1,242 @@
+import { lowerFirst, type Fields } from '@fougere/schema';
+import type { Container } from '@fougere/container';
+import type { AppMiddleware } from '../wire/middleware.js';
+import type { CollectorResolver } from './binding.js';
+import { collectorKeyOf } from '../prefab/collector.js';
+import { presenterKeyOf } from '../prefab/presenter.js';
+import { repositoryKeyOf } from '../prefab/repository.js';
+import { targetOf } from '../prefab/prefab.js';
+import type { OperationContract, OperationsMap } from '../wire/operation.js';
+import type { EffectiveOperation, EffectiveOperationsMap } from '../effective-operation.js';
+import type { InvocationContext } from '../wire/invocation.js';
+import type { Emissions } from './Emissions.js';
+import type { Logger } from '../builtins/logger.js';
+import type { EntityEntry, HandlerEntry, PresenterEntry } from '../scan/frond.js';
+import { InputValidator } from '../dispatch/InputValidator.js';
+import { ArgumentResolver } from '../dispatch/ArgumentResolver.js';
+import { OperationExecutor } from '../dispatch/OperationExecutor.js';
+import { OutputProjector } from '../dispatch/OutputProjector.js';
+import { OutputView } from '../dispatch/OutputView.js';
+import { PresenterExecutor } from '../dispatch/PresenterExecutor.js';
+import { PresenterArgumentResolver } from '../dispatch/PresenterArgumentResolver.js';
+
+/** What this door is about: a handler, the entity behind it when there is one, and where it resolves. */
+export interface Doorway {
+  handler: HandlerEntry;
+  /** Handlers in the owning frond, used to realize a resolved implementation override. */
+  handlers: readonly HandlerEntry[];
+  /** The canonical operation table resolved before boot performs any side effect. */
+  operations: EffectiveOperationsMap;
+  /** The subject — absent is ordinary: a health check owns no row. */
+  entity: EntityEntry | undefined;
+  /** The scope the handler and its collectors resolve in — a surface gets its own. */
+  scope: Container;
+  /** The container key this door answers under. */
+  key: string;
+}
+
+/** What the frond and the boot supply to every door alike. */
+export interface Wiring {
+  /** The frond this door belongs to — travels on every OperationContext. */
+  frond: string;
+  /** The frond's own scope — where presenters live, whatever sub-scope the door uses. */
+  frondScope: Container;
+  log: Logger;
+  /** Entity names this frond has a collector for. */
+  collectors: Set<string>;
+  presenters: Map<string, PresenterEntry>;
+  /** The middlewares that apply to an address, read at call time and never at boot. */
+  middlewaresFor: (address: string) => AppMiddleware[];
+  emissions: Emissions;
+}
+
+/** Adapts one handler door to executable operations. */
+export class HandlerFacade {
+  /** Rich operation facts shared with check, explain and adapters. */
+  readonly effectiveOperations: EffectiveOperationsMap;
+  /** Contracts served by this door. */
+  readonly contracts: OperationsMap;
+
+  /** The callable surface: op name → the function a caller reaches. */
+  readonly ops: Record<string, Function> = {};
+
+  private readonly cachedViews = new Map<string, OutputView>();
+  private instance: any;
+  private readonly implementationKeys = new Map<string, string>();
+  private readonly implementationInstances = new Map<string, any>();
+  private readonly inputValidator = new InputValidator();
+  private readonly argumentResolver = new ArgumentResolver(
+    (typeName) => this.collectorResolver(typeName),
+  );
+  private readonly presenterArguments: PresenterArgumentResolver;
+
+  constructor(private readonly door: Doorway, private readonly wiring: Wiring) {
+    const { handler, entity } = door;
+    this.presenterArguments = new PresenterArgumentResolver(
+      this.argumentResolver,
+      wiring.collectors,
+    );
+    this.refuseCrudWithoutRepository(handler);
+
+    door.scope.register(this.handlerKey, handler.ctor, { deps: this.depsOf(handler) });
+
+    this.effectiveOperations = door.operations;
+    this.contracts = new Map(
+      [...door.operations].map(([name, operation]) => [name, operation as OperationContract] as const),
+    );
+    handler.operations = this.contracts;
+
+    // Register model-selected implementations in the same execution scope.
+    for (const [name, operation] of door.operations) {
+      if (this.isBaseImplementation(operation)) continue;
+      const implementation = this.implementationHandler(name);
+      this.refuseCrudWithoutRepository(implementation);
+      const key = `${this.handlerKey}:implementation:${operation.implementation.className}`;
+      if (!this.implementationKeys.has(operation.implementation.className)) {
+        door.scope.register(key, implementation.ctor, { deps: this.depsOf(implementation) });
+        this.implementationKeys.set(operation.implementation.className, key);
+      }
+    }
+
+    // Emissions use the same contracts and execution path as direct calls.
+    wiring.emissions.note(this.contracts, door.key);
+    // Only declared operations become callable façade members.
+    for (const op of this.contracts.keys()) this.ops[op] = this.wrap(op);
+
+    if (this.inheritsCrud(handler) && !entity) {
+      // An installed Crud subject may be absent from the local scan.
+      wiring.log.debug(`${handler.ctor.name} extends Crud() and no scanned entity is named `
+        + `'${this.subjectOf(handler)}' — installed entity, or a missing one: no ORM will be injected`);
+    }
+  }
+
+  /** Storage follows the Crud subject, which may differ from the door address. */
+  private subjectOf(handler: HandlerEntry): string {
+    const target = targetOf(handler.ctor);
+    return target?.name ? lowerFirst(target.name) : handler.address;
+  }
+
+  private inheritsCrud(handler: HandlerEntry): boolean {
+    const proto = handler.ctor.prototype;
+    return typeof proto?.list === 'function' && typeof proto?.findById === 'function';
+  }
+
+  private get handlerKey(): string {
+    return `_handler:${this.door.key}`;
+  }
+
+  private depsOf(handler: HandlerEntry): string[] {
+    const { deps } = handler;
+    if (deps.length > 0) return deps;
+    return this.inheritsCrud(handler) ? [repositoryKeyOf(this.subjectOf(handler))] : [];
+  }
+
+  /** A custom Crud constructor must explicitly receive its repository. */
+  private refuseCrudWithoutRepository(handler: HandlerEntry): void {
+    const repoTypeName = repositoryKeyOf(this.subjectOf(handler));
+    if (!this.inheritsCrud(handler) || handler.deps.length === 0 || handler.deps.includes(repoTypeName)) return;
+    throw new Error(
+      `${handler.ctor.name} extends Crud() and declares a constructor, so its storage is no ` +
+      `longer injected for it — but it does not take any.\n` +
+      `  Add it and hand it to super():\n` +
+      `    constructor(repo: ${repoTypeName}, …) { super(repo); }`,
+    );
+  }
+
+  /** Resolve and cache the output view declared for one operation. */
+  private viewOf(op: string): OutputView {
+    const known = this.cachedViews.get(op);
+    if (known) return known;
+
+    const operation = this.effectiveOperations.get(op);
+    const schema = operation?.output as { getFields?: () => Fields } | undefined;
+    const resolved = new OutputView(
+      typeof schema?.getFields === 'function' ? schema.getFields() : {},
+      operation?.outputClosed ?? false,
+    );
+    this.cachedViews.set(op, resolved);
+    return resolved;
+  }
+
+  private collectorResolver = (typeName: string): CollectorResolver | undefined => {
+    try { return this.door.scope.resolve(collectorKeyOf(typeName)) as CollectorResolver; }
+    catch { return undefined; }
+  };
+
+  /** The handler itself, resolved on first call — never at boot. */
+  private resolvedHandler(): any {
+    if (!this.instance) this.instance = this.door.scope.resolve(this.handlerKey);
+    return this.instance;
+  }
+
+  private isBaseImplementation(operation: EffectiveOperation): boolean {
+    return operation.implementation.className === this.door.handler.ctor.name
+      && operation.implementation.address === this.door.handler.address
+      && operation.implementation.filePath === this.door.handler.filePath;
+  }
+
+  /** The exact handler entry the pure model selected; no name-only retry or fallback. */
+  private implementationHandler(operationName: string): HandlerEntry {
+    const operation = this.effectiveOperations.get(operationName)!;
+    const matches = this.door.handlers.filter((handler) =>
+      handler.ctor.name === operation.implementation.className
+      && handler.address === operation.implementation.address
+      && handler.filePath === operation.implementation.filePath);
+    if (matches.length !== 1) {
+      throw new Error(
+        `EffectiveOperation '${operation.id}' names ${operation.implementation.className}.`
+        + `${operation.implementation.method}, but boot found ${matches.length} matching handlers.`,
+      );
+    }
+    return matches[0]!;
+  }
+
+  private resolvedImplementation(operationName: string): { instance: any; method: string } {
+    const operation = this.effectiveOperations.get(operationName)!;
+    if (this.isBaseImplementation(operation)) {
+      return { instance: this.resolvedHandler(), method: operation.implementation.method };
+    }
+
+    const className = operation.implementation.className;
+    const key = this.implementationKeys.get(className);
+    if (!key) throw new Error(`No registered implementation for EffectiveOperation '${operation.id}'.`);
+    let instance = this.implementationInstances.get(key);
+    if (!instance) {
+      instance = this.door.scope.resolve(key);
+      this.implementationInstances.set(key, instance);
+    }
+    return { instance, method: operation.implementation.method };
+  }
+
+  private wrap(op: string): (invocation?: InvocationContext) => Promise<unknown> {
+    const address = this.door.handler.address;
+    const contract = this.contracts.get(op);
+    const view = this.viewOf(op);
+    const presenter = this.wiring.presenters.get(address);
+    const executor = new OperationExecutor({
+      entity: address,
+      frond: this.wiring.frond,
+      operation: op,
+      contract,
+      middlewares: () => this.wiring.middlewaresFor(address),
+      validator: this.inputValidator,
+      arguments: this.argumentResolver,
+      invoke: async (args) => {
+        const implementation = this.resolvedImplementation(op);
+        return implementation.instance[implementation.method](...args);
+      },
+      projector: new OutputProjector(view),
+      ...(view.closed || !presenter ? {} : {
+        present: async (result: unknown, effective: InvocationContext) =>
+          new PresenterExecutor(
+            this.wiring.frondScope.resolve(presenterKeyOf(address)),
+            presenter.fields,
+            address,
+            op,
+          ).present(result, await this.presenterArguments.resolve(presenter, effective)),
+      }),
+    });
+
+    return (invocation) => executor.execute(invocation);
+  }
+}

package/src/boot/Lifecycle.ts

@@ -0,0 +1,3 @@
+/** Compatibility module. Prefer AppLifecycle for the process-level lifecycle. */
+export { AppLifecycle, AppLifecycle as Lifecycle, migrating } from './AppLifecycle.js';
+export type { Extension } from './AppLifecycle.js';

package/src/boot/ambient-port.ts

@@ -0,0 +1,41 @@
+/**
+ * What a call needs to know about the call it is inside, and the two ways to answer it.
+ *
+ * One realization reads an async context (`ambient.als.ts`), the other cannot and waits
+ * its turn instead (`ambient.queue.ts`). `#ambient` in package.json picks one per runtime,
+ * so a bundle for a host without async context never names `node:async_hooks`.
+ */
+export interface Ambient {
+  /** True when this runtime has no async context, and the boot says so. */
+  readonly degraded: boolean;
+
+  /**
+   * Run `fn` as the frame `key`. A frame opened inside another must not proceed.
+   *
+   * Measured on SQLite: a second transaction on the same connection WAITS for the first,
+   * so a nested frame hangs on one engine and returns when split across two.
+   */
+  enterFrame<R>(key: string, fn: () => Promise<R>): Promise<R>;
+
+  /**
+   * Settle before `fact` is dispatched: a fact announced inside a frame that then rolls
+   * back is a lie. Refuses when the caller's own frame can be told, waits when it cannot.
+   */
+  beforeAnnounce(fact: string): Promise<void>;
+
+  /**
+   * The facts already being announced up the stack, so a fact cannot cause itself.
+   *
+   * A CHAIN and not a depth: `A → B → D` and `A → C → D` is a diamond, perfectly legal,
+   * while `A → … → A` never ends. Empty where it cannot be followed.
+   *
+   * Detecting this at boot was the first idea and it was wrong: `Emit<G>` is a CONSTRUCTOR
+   * dependency, so it belongs to the handler and not to one of its methods. A handler that
+   * subscribes to `A` in one method and emits `G` from another would have been refused for
+   * a cycle it never walks.
+   */
+  currentChain(): readonly string[];
+
+  /** Run `fn` with `fact` appended to the emission chain. */
+  enterChain<R>(fact: string, fn: () => Promise<R>): Promise<R>;
+}

package/src/boot/ambient.als.ts

@@ -0,0 +1,43 @@
+/**
+ * The realization that can tell whose frame is open: an async context.
+ *
+ * Chosen by `#ambient` wherever `node:async_hooks` exists — Node, Deno, Bun, and workerd
+ * with `nodejs_als`. Every refusal here is immediate and names its cause.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Ambient } from './ambient-port.js';
+
+const frame = new AsyncLocalStorage<string>();
+const chain = new AsyncLocalStorage<readonly string[]>();
+
+export const ambient: Ambient = {
+  degraded: false,
+
+  enterFrame<R>(key: string, fn: () => Promise<R>): Promise<R> {
+    const held = frame.getStore();
+    if (held !== undefined) {
+      return Promise.reject(new Error(
+        `Together<[…]> (${key}) cannot be opened inside ${held}: on one engine the second `
+        + `transaction waits for the first and the call hangs. Two frames that must both hold `
+        + `are ONE frame — declare a single Together naming every member.`,
+      ));
+    }
+    return frame.run(key, fn);
+  },
+
+  beforeAnnounce(fact: string): Promise<void> {
+    const held = frame.getStore();
+    if (held === undefined) return Promise.resolve();
+    return Promise.reject(new Error(
+      `${fact} cannot be announced inside Together<[…]> (${held}): announcing is dispatch, `
+      + `so subscribers and the carrier would have it while these writes can still be taken `
+      + `back. Announce after run() returns, when it is true.`,
+    ));
+  },
+
+  currentChain: () => chain.getStore() ?? [],
+
+  enterChain<R>(fact: string, fn: () => Promise<R>): Promise<R> {
+    return chain.run([...(chain.getStore() ?? []), fact], fn);
+  },
+};

package/src/boot/ambient.queue.ts

@@ -0,0 +1,75 @@
+/**
+ * The realization for a runtime with no async context: it cannot tell whose frame is
+ * open, so it never guesses — it waits its turn.
+ *
+ * Two consequences the boot reports rather than hides: frames run one at a time, and a
+ * frame opened inside another is not refused, it waits for itself and times out.
+ */
+import type { Ambient } from './ambient-port.js';
+
+/** What a nested frame waits before it is told what it did — the hang, measured, plus a name. */
+const NESTED_TIMEOUT_MS = 5_000;
+
+let busy: Promise<void> | undefined;
+let holder: string | undefined;
+
+const settled = () => undefined;
+
+/** Resolves when `p` settles or `ms` elapses, whichever comes first, holding no timer after. */
+function raceWith(p: Promise<void>, ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    const clear = () => { clearTimeout(timer); resolve(); };
+    void p.then(clear, clear);
+  });
+}
+
+export const ambient: Ambient = {
+  degraded: true,
+
+  async enterFrame<R>(key: string, fn: () => Promise<R>): Promise<R> {
+    const deadline = Date.now() + NESTED_TIMEOUT_MS;
+    for (;;) {
+      // Nothing may await between this test and the reservation below, or two waiters
+      // woken in the same tick would both take the frame.
+      if (busy === undefined) break;
+      const left = deadline - Date.now();
+      if (left <= 0) {
+        throw new Error(
+          `Together<[…]> (${key}) waited ${NESTED_TIMEOUT_MS}ms for ${holder} and gave up. `
+          + `This runtime has no async context, so a frame opened inside another waits for `
+          + `itself instead of being refused. Two frames that must both hold are ONE frame — `
+          + `declare a single Together naming every member.`,
+        );
+      }
+      await raceWith(busy, left);
+    }
+    // Held BEFORE `fn` runs: the first thing a frame's body does may be to open another,
+    // and reserving on the returned promise would be one tick too late to see it.
+    let release = settled as () => void;
+    busy = new Promise<void>((resolve) => { release = resolve; });
+    holder = key;
+    try {
+      return await fn();
+    } finally {
+      busy = undefined;
+      holder = undefined;
+      release();
+    }
+  },
+
+  /**
+   * Waits rather than refuses: whose frame is open cannot be told here, and refusing on
+   * that would refuse an announcement made by an unrelated call.
+   */
+  async beforeAnnounce(_fact: string): Promise<void> {
+    while (busy) await raceWith(busy, NESTED_TIMEOUT_MS);
+  },
+
+  /** No chain can be followed here — an emission ring is not detected. Said at boot. */
+  currentChain: () => [],
+
+  enterChain<R>(_fact: string, fn: () => Promise<R>): Promise<R> {
+    return fn();
+  },
+};

package/src/boot/apply.ts

@@ -0,0 +1,47 @@
+import type { FougereConfig } from '../config-loader.js';
+import { setLogLevel, logLevel, envLevel } from '../builtins/logger.js';
+import { dequal } from 'dequal';
+
+export interface ConfigApplication {
+  /** What this call changed in the running process. */
+  applied: string[];
+  /** What differs from the config in force and did NOT take effect. */
+  pending: string[];
+}
+
+/**
+ * What a (re-)read config changes in a process that is already running.
+ *
+ * The rule it realizes, and the only one worth remembering: **a value that is
+ * CONSULTED can change under a running app; a value that was CONSUMED to build
+ * something cannot, without rebuilding what it built.** `logLevel` is consulted at
+ * every emission, so it moves. `db` opened a connection, `ports:` registered a class,
+ * the entities built façades — those are consumed, and this function reports them
+ * rather than pretending.
+ *
+ * The list of consulted keys is not declared anywhere: a key is consulted when this
+ * function does something with it, which is the only definition that cannot go stale.
+ */
+export function applyConfig(next: FougereConfig, inForce?: FougereConfig): ConfigApplication {
+  const applied: string[] = [];
+  const pending: string[] = [];
+
+  // The CLI speaks through the environment, so it keeps winning over the file — read
+  // through `envLevel`, which is where the environment is already judged. Casting it
+  // here was a second reader that validated nothing: `FOUGERE_LOG_LEVEL=verbose` set
+  // the threshold to `undefined` and every log passed.
+  const wanted = envLevel() ?? next.logLevel ?? 'debug';
+  const before = logLevel();
+  if (wanted !== before) {
+    setLogLevel(wanted);
+    applied.push(`logLevel: ${before} → ${wanted}`);
+  }
+
+  for (const key of new Set([...Object.keys(next), ...Object.keys(inForce ?? {})])) {
+    if (key === 'logLevel' || !inForce) continue;
+    if (!dequal((next as Record<string, unknown>)[key], (inForce as Record<string, unknown>)[key])) {
+      pending.push(key);
+    }
+  }
+  return { applied, pending };
+}

package/src/boot/auth.ts

@@ -0,0 +1,55 @@
+/**
+ * What an auth provider promises the boot, and what the boot hands it — the whole of
+ * the contract between core and an `@fougere/auth-*` package.
+ */
+import type { SchemaView } from '@fougere/schema';
+import type { EntityOrm, OrmFactory } from '../orm.js';
+
+/**
+ * Lazy auth declaration written in fougere.config.ts.
+ *
+ * Each @fougere/auth-* package exports a factory (e.g. `betterAuth(opts)`) that
+ * returns this shape. The `create()` method is called once at boot with the
+ * resolved db + ormFactory, so the provider can wire its engine through Fougere.
+ */
+export interface AuthConfig {
+  /** Build the runtime — invoked by createApp at boot with the resolved storage handles. */
+  create(ctx: AuthContext): AuthRuntime | Promise<AuthRuntime>;
+  /**
+   * Entities the provider will use. Optional metadata — useful for the core's
+   * future migration registry to know which tables auth needs.
+   */
+  entities?: Record<string, SchemaView>;
+}
+
+/**
+ * Context passed by the core to an auth provider's create() function.
+ * Provides the resources the provider needs to integrate with the app.
+ */
+export interface AuthContext {
+  /** Storage handle (Kysely DB instance, Prisma client, etc.) — opaque to core. */
+  db: unknown;
+  /** Per-entity ORM factory — auth provider uses this to back its adapter. */
+  ormFactory: OrmFactory;
+}
+
+/**
+ * Runtime returned by an auth provider's create(config, ctx) function.
+ * The core mounts this on the App and the HTTP layer (Nuxt module / router) uses it.
+ */
+export interface AuthRuntime {
+  /** Entities used by the provider, including any defaults it filled in. */
+  entities: Record<string, SchemaView>;
+  /**
+   * Per-entity ORMs the provider built for itself. Exposed so app code can
+   * query auth tables (e.g. list active sessions for a user) without rebuilding
+   * the same EntityOrm.
+   */
+  orms: Record<string, EntityOrm>;
+  /** Web Standard handler that processes /auth/* requests. */
+  handler: (request: Request) => Promise<Response>;
+  /** Programmatic API exposed by the provider (getSession, signOut, ...). */
+  api: Record<string, unknown>;
+  /** Effective mount path (echoes config.basePath or the provider's default). */
+  basePath: string;
+}