@fougere/core 0.2.0-alpha.2 → 0.4.0-alpha.0

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;
+}

package/src/boot/binding.ts

@@ -0,0 +1,182 @@
+/**
+ * Where each parameter of an operation gets its value — decided once at boot from the
+ * parsed signature, replayed per call by `resolveArgs`.
+ *
+ * The branches are ORDERED and each states why it sits where it does; the list used to
+ * be repeated here too, and it had already lost `Fact` — the one whose position is
+ * load-bearing, since the fall-through would otherwise hand it the caller's body.
+ */
+import type { ParsedParam } from '../scan/handler-parser.js';
+import type { InvocationContext } from '../wire/invocation.js';
+import { lowerFirst } from '@fougere/schema';
+
+// ── Types ─────────────────────────────────────
+
+type ParamSource =
+  | { kind: 'collector'; typeName: string }
+  /**
+   * `Fact<PostPublished>` — something that happened, not something a caller typed.
+   *
+   * It resolves from the body exactly like `body` does, and that is deliberate: an
+   * emission and a direct call ARE the same call, so a subscriber cannot tell them apart
+   * and does not need to. The branch exists so the PLAN says what this parameter is —
+   * that sentence is what makes the subscriber index readable without reparsing types.
+   */
+  | { kind: 'fact'; factName: string }
+  | { kind: 'param'; name: string; coerce?: 'number' | 'boolean' }
+  | { kind: 'body' }
+  | { kind: 'context' }
+  /** The whole query bag, for an op whose argument IS the options (list). */
+  | { kind: 'query' };
+
+interface ParamBinding {
+  name: string;
+  source: ParamSource;
+  optional: boolean;
+}
+
+export type BindingPlan = ParamBinding[];
+
+// ── Primitives ────────────────────────────────
+
+const PRIMITIVES = new Set(['string', 'number', 'boolean']);
+
+function coercionFor(typeName: string): 'number' | 'boolean' | undefined {
+  if (typeName === 'number') return 'number';
+  if (typeName === 'boolean') return 'boolean';
+  return undefined;
+}
+
+// ── Compute ───────────────────────────────────
+
+/**
+ * Build a BindingPlan from parsed method params.
+ *
+ * @param params - Parsed parameter list from AST
+ * @param collectorTypeNames - Registration keys of the types a Collector answers for
+ */
+export function computeBindingPlan(
+  params: ParsedParam[],
+  collectorTypeNames: Set<string>,
+): BindingPlan {
+  return params.map((param) => {
+    const typeName = param.type.name;
+    // `lowerFirst`, never `toLowerCase()`: the collector set is keyed the way the
+    // scan spells it, and the two agree on one word only — `AuthorUser` looked up as
+    // `authoruser` missed `authorUser` and fell through to branch 4, the request body.
+    const typeKey = lowerFirst(typeName);
+
+    // 0. Fact — `Fact<X>` names itself, so nothing has to be known in advance. It comes
+    //    FIRST because branch 4 would otherwise hand it the caller's body under the name
+    //    of something that happened.
+    const factOf = param.type.name === 'Fact' ? param.type.generics?.[0]?.name : undefined;
+    if (factOf) {
+      return {
+        name: param.name,
+        source: { kind: 'fact' as const, factName: lowerFirst(factOf) },
+        optional: param.optional ?? false,
+      };
+    }
+
+    // 1. Collector — param type matches a type some collector answers for
+    if (collectorTypeNames.has(typeKey)) {
+      return {
+        name: param.name,
+        source: { kind: 'collector' as const, typeName: typeKey },
+        optional: param.optional ?? false,
+      };
+    }
+
+    // 2. InvocationContext — inject the full context
+    if (typeName === 'InvocationContext') {
+      return {
+        name: param.name,
+        source: { kind: 'context' as const },
+        optional: param.optional ?? false,
+      };
+    }
+
+    // 3. Primitives — matched by name from params > query
+    if (PRIMITIVES.has(typeName)) {
+      return {
+        name: param.name,
+        source: {
+          kind: 'param' as const,
+          name: param.name,
+          coerce: coercionFor(typeName),
+        },
+        optional: param.optional ?? false,
+      };
+    }
+
+    // 4. Everything else — body
+    return {
+      name: param.name,
+      source: { kind: 'body' as const },
+      optional: param.optional ?? false,
+    };
+  });
+}
+
+// ── Resolve ───────────────────────────────────
+
+export interface CollectorResolver {
+  collect(ctx: InvocationContext): Promise<unknown>;
+}
+
+/**
+ * Resolve handler arguments from a BindingPlan + InvocationContext.
+ */
+export async function resolveArgs(
+  plan: BindingPlan,
+  ctx: InvocationContext,
+  resolveCollector?: (typeName: string) => CollectorResolver | undefined,
+): Promise<unknown[]> {
+  const args: unknown[] = [];
+
+  for (const binding of plan) {
+    switch (binding.source.kind) {
+      case 'collector': {
+        const collector = resolveCollector?.(binding.source.typeName);
+        args.push(collector ? await collector.collect(ctx) : undefined);
+        break;
+      }
+      case 'context': {
+        args.push(ctx);
+        break;
+      }
+      case 'param': {
+        // `null` is a value, not a miss. Nullish coalescing used to make an explicit
+        // nullable path/GraphQL argument fall through to query (or become undefined),
+        // collapsing `T | null` into `T | undefined`. Only undefined means absent.
+        const fromParams = ctx.params[binding.source.name];
+        let val: unknown = fromParams === undefined
+          ? ctx.query[binding.source.name]
+          : fromParams;
+        if (val != null && binding.source.coerce === 'number') val = Number(val);
+        if (val != null && binding.source.coerce === 'boolean') val = val === 'true' || val === '1' || val === true;
+        args.push(val);
+        break;
+      }
+      case 'fact': {
+        // A fact IS the payload — the whole of what happened, never a piece of it.
+        // Identical to `body` today, and deliberately not sharing its branch: the two
+        // agree by coincidence, not by rule, and the day `body` learns to look up a
+        // value by parameter name a subscriber would receive ONE FIELD of the fact it
+        // subscribed to. Splitting it costs nothing and removes that trap.
+        args.push(ctx.body);
+        break;
+      }
+      case 'body': {
+        args.push(ctx.body);
+        break;
+      }
+      case 'query': {
+        args.push(ctx.query);
+        break;
+      }
+    }
+  }
+
+  return args;
+}

package/src/boot/boot.ts

@@ -0,0 +1,125 @@
+import { createApp } from './bootstrap.js';
+import { seeding } from './seed.js';
+import { scanProject } from '../scan/scanner.js';
+import { loadConfig, type FougereConfig } from '../config-loader.js';
+import { Logger } from '../builtins/logger.js';
+import { applyConfig } from './apply.js';
+import type { App, CreateAppOptions } from './types.js';
+import { migrating, type Extension } from './AppLifecycle.js';
+import type { Transport } from '../wire/call.js';
+import type { Container } from '@fougere/container';
+
+interface BootOptions {
+  /** Project root. Defaults to process.cwd(). */
+  root?: string;
+  /** Override config (merged with fougere.config.ts). */
+  config?: Partial<FougereConfig>;
+  /** Container factory. Required. */
+  createContainer: () => Container;
+  /** Only boot these fronds (by name). Absent = all. */
+  fronds?: string[];
+  /**
+   * Remote fronds — label → address. A declared remote wins over local
+   * presence (the frond runs elsewhere). Requires `remoteTransport`.
+   */
+  remotes?: Record<string, string>;
+  /** Builds the transport to reach `remotes`. Supplied by a layer-2 package. */
+  remoteTransport?: (url: string) => Transport;
+  /**
+   * Carries an announced fact out of this process. Forwarded rather than dropped: a
+   * caller handing one in has no other way to reach the emitter, and this path silently
+   * kept it to itself.
+   */
+  onEmit?: CreateAppOptions['onEmit'];
+  /**
+   * ORM setup — returns the storage handle (db), an ormFactory, and its two halves.
+   * The `db` value is forwarded to the auth provider via AuthContext when `auth` is set.
+   */
+  db?: (config: FougereConfig) => {
+    db?: unknown;
+    ormFactory: CreateAppOptions['ormFactory'];
+    /**
+     * Bring the schema up to date — an extension's `up`, because it runs after the
+     * container. It used to be called `afterBoot`, a word that also meant the host's
+     * post-boot and was read in four places under two senses.
+     */
+    migrate?: (app: App) => Promise<void> | void;
+    /** Closes what the factory opened — `boot()` called it, so `boot()` releases it. */
+    close?: () => Promise<void>;
+  };
+  /**
+   * What this app takes on beyond its fronds. Appended after the framework's own, so a
+   * host adds to the ascent — or replaces a member of it by declaring the same name.
+   */
+  extensions?: readonly (Extension | undefined)[];
+}
+
+/**
+ * Boot a Fougere app from fougere.config.ts.
+ *
+ * Handles: config loading, container creation, DB setup, seeding.
+ * Works for any surface (Nuxt, GraphQL standalone, CLI, tests).
+ */
+export async function boot(options: BootOptions): Promise<App> {
+  const bootStart = performance.now();
+  const log = new Logger('boot');
+
+  const root = options.root ?? process.cwd();
+  log.info(`root: ${root}`);
+
+  log.debug('loading config');
+  const fileConfig = await loadConfig(root);
+  const config: FougereConfig = { ...fileConfig, ...options.config };
+  // What this config changes in the process, said the same way at boot and at reload —
+  // there is one applier, and a host re-reading later calls the very same function.
+  applyConfig(config);
+  log.info('config loaded');
+
+  let dbSetup: ReturnType<NonNullable<BootOptions['db']>> | undefined;
+  if (options.db) {
+    log.debug('initializing database');
+    dbSetup = options.db(config);
+    log.info('database initialized');
+  }
+
+  log.debug('creating app (scan + container)');
+  const app = await createApp({
+    // boot() lives on the Node entry, so boot() is what reads the disk. `createApp` is
+    // handed the answer and reaches for nothing.
+    scan: await scanProject(root, options.fronds, config.conventions),
+    createContainer: options.createContainer,
+    ormFactory: dbSetup?.ormFactory,
+    db: dbSetup?.db,
+    auth: config.auth,
+    remotes: options.remotes,
+    ports: config.ports,
+    // Read from the config for the same reason `ports` is, one line up: it is a fact the
+    // project states, not one the caller passes. Absent here, `serveRest` and
+    // `serveGraphQL` both answered `pass` on an app whose config declared them — the
+    // hosts got it right through their own boot (`app/shared/src/boot.ts`), and this
+    // path, the conventional one, served nothing.
+    adapters: config.adapters,
+    // boot() called the factory, so boot() owns closing what it opened. Not an extension:
+    // it was opened before the container existed, so it closes after the container goes.
+    onDispose: dbSetup?.close,
+    /**
+     * The whole ascent, in one ordered list — tables, then rows, then whatever the host
+     * takes on. It was four call sites under the name `afterBoot`, two of which meant
+     * different things and one of which was generated into a Nitro plugin.
+     */
+    extensions: [
+      migrating(dbSetup?.migrate),
+      seeding((message) => log.debug(message)),
+      ...(options.extensions ?? []),
+    ],
+    onEmit: options.onEmit,
+    remoteTransport: options.remoteTransport,
+  });
+
+  log.info(`ascent: ${app.extensions().join(' → ') || 'nothing declared'}`);
+
+  const ms = (performance.now() - bootStart).toFixed(0);
+  log.info(`ready in ${ms}ms — ${app.fronds.length} frond(s)`);
+
+  return app;
+}