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

package/src/entry/DynamicFacade.ts

@@ -0,0 +1,28 @@
+type Operation = (...args: any[]) => unknown;
+
+/** Facade for a remote contract whose operation names are not known before discovery. */
+export class DynamicFacade {
+  readonly operations: Record<string, Operation>;
+
+  constructor(private readonly operation: (name: string) => Operation) {
+    this.operations = new Proxy({}, {
+      get: (_target, name) => this.isOperationName(name) ? this.operation(name) : undefined,
+      has: (_target, name) => this.isOperationName(name),
+      getOwnPropertyDescriptor: (_target, name) => this.isOperationName(name)
+        ? {
+            value: this.operation(name),
+            writable: false,
+            enumerable: true,
+            configurable: true,
+          }
+        : undefined,
+    });
+  }
+
+  private isOperationName(name: string | symbol): name is string {
+    return typeof name === 'string'
+      && name !== 'then'
+      && name !== 'toJSON'
+      && !Object.hasOwn(Object.prototype, name);
+  }
+}

package/src/entry/FacadeEntry.ts

@@ -0,0 +1,32 @@
+import { Call } from '../contract/Call.js';
+import type { InvocationInput } from '../contract/Invocation.js';
+import { RouteAddress } from '../contract/RouteAddress.js';
+import type { DispatchPort } from '../dispatch/DispatchPort.js';
+import { DynamicFacade } from './DynamicFacade.js';
+
+/** Object-shaped entry that turns facade method calls into canonical dispatches. */
+export class FacadeEntry {
+  readonly operations: Record<string, Function>;
+
+  constructor(
+    private readonly dispatcher: DispatchPort,
+    private readonly entity: string,
+    operationNames?: Iterable<string>,
+    private readonly surface?: string,
+  ) {
+    this.operations = operationNames
+      ? Object.fromEntries([...operationNames].map((name) => [name, this.operation(name)]))
+      : new DynamicFacade((name) => this.operation(name)).operations;
+  }
+
+  private operation(name: string): (invocation?: InvocationInput) => Promise<unknown> {
+    return (invocation) => this.dispatcher.dispatch(new Call(
+      new RouteAddress({
+        entity: this.entity,
+        operation: name,
+        ...(this.surface !== undefined ? { surface: this.surface } : {}),
+      }),
+      invocation,
+    ));
+  }
+}

package/src/entry/TransportEntry.ts

@@ -0,0 +1,30 @@
+import { Call } from '../contract/Call.js';
+import { RouteAddress } from '../contract/RouteAddress.js';
+import type { DispatchPort } from '../dispatch/DispatchPort.js';
+import type { FrondCall, Transport } from '../wire/call.js';
+import type { InvocationContext } from '../contract/Invocation.js';
+
+/** Object entry for the historical transport contract. */
+export class TransportEntry {
+  constructor(
+    private readonly dispatcher: DispatchPort,
+    private readonly surface?: string,
+  ) {}
+
+  receive(legacy: FrondCall, invocation: InvocationContext): Promise<unknown> {
+    return this.dispatcher.dispatch(new Call(
+      new RouteAddress({
+        entity: legacy.entity,
+        operation: legacy.op,
+        ...(this.surface !== undefined ? { surface: this.surface } : {}),
+      }),
+      invocation,
+    ));
+  }
+}
+
+/** Adapt the historical transport signature to the canonical dispatch port. */
+export function createTransportEntry(dispatcher: DispatchPort, surface?: string): Transport {
+  const entry = new TransportEntry(dispatcher, surface);
+  return entry.receive.bind(entry);
+}

package/src/frond-config.ts

@@ -0,0 +1,138 @@
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import type { EntityConstructor, SchemaView } from '@fougere/schema';
+import type { BindingPlan } from './boot/binding.js';
+
+// ── Types ────────────────────────────────────────
+
+/**
+ * Per-operation override. Config takes precedence over conventions (isReadOp, facade lookup).
+ *
+ * Two families of keys, and they act at different depths:
+ *
+ * - **Resolution** (`kind`, `handler`, `method`) — intent and implementation, resolved
+ *   once into core's `EffectiveOperation`; every local or remote door consumes it.
+ * - **Projection** (`graphql`) — protocol vocabulary, read only by that adapter.
+ * - **Contract** (`input`, `output`, `binding`) — what the op IS. Read by the façade,
+ *   and this is the third producer of an {@link OperationContract}: a prefab DECLARES its
+ *   ops (`Crud.__ops`), the scan DERIVES them from source, config STATES them outright.
+ *   The façade cannot tell the three apart.
+ *
+ * Stating a contract here makes the scan optional rather than load-bearing. Two cases it
+ * answers that nothing else does:
+ * - a method inherited from an **installed** base class — the scan resolves nothing there
+ *   (workspace-only heritage) and says nothing, so the op silently misses the façade;
+ * - an operation inherited from a declaration unavailable to the project's type checker.
+ *
+ * Config wins over both other producers — it is the most explicit statement, made by
+ * whoever assembles the app. Precedence: CLI > frond config > fougere config > scan >
+ * conventions.
+ */
+export interface OperationOverride {
+  /**
+   * Force operation kind, over the naming convention (`isReadOp`).
+   *
+   * The convention reads the NAME, which is a weak signal — an app naming its reads in
+   * domain terms (`ofBook`, `roots`, `bySlug`) matches no prefix and every one of them is
+   * published as a mutation and a POST. This is the only place that fixes it.
+   */
+  kind?: 'query' | 'command';
+  /**
+   * The GraphQL root field this op answers to. Defaults to the method name.
+   *
+   * A GraphQL root is flat, so two handlers naming a method `ofBook` claim one field and
+   * the build is refused, naming both. Nothing is renamed for you: the root vocabulary is
+   * the app's, and a derived name would move the day a distant frond gained an entity.
+   */
+  graphql?: string;
+  /**
+   * Handler class to delegate to (overrides the default `{Entity}Handler` lookup).
+   * Class name is used to resolve from DI. E.g. `ArchiveHandler` → `app.resolve('ArchiveHandler')`.
+   */
+  handler?: EntityConstructor;
+  /** Method name on `handler` (defaults to the operation name). */
+  method?: string;
+  /**
+   * CASL ability check (e.g. 'archive Post'). **Declared, not implemented** — no
+   * reader interprets it today, in any adapter. Kept as the named slot for the
+   * question rather than silently dropped, but do not rely on it: a config that
+   * states a policy is not enforced anywhere.
+   *
+   * Wiring it means adopting a rules engine, which is precisely what the design
+   * turns down: an identity-dependent right is judged INSIDE the operation
+   * (`publish` reads `post.authorId !== user.id`), and a door-dependent one is a
+   * surface. Neither needs a second vocabulary evaluated by a second engine.
+   */
+  policy?: string;
+
+  // ── The contract itself — see the note above ──
+
+  /** What judges the input. The view carries its own mode (`partial()` → patch). */
+  input?: SchemaView;
+  /**
+   * Where each argument is read from — states what the scan would otherwise derive
+   * from the method signature. An empty array is meaningful: "this op takes nothing".
+   */
+  binding?: BindingPlan;
+
+  /** Per-operation output view, below prefab declarations and above handler/entity defaults. */
+  output?: SchemaView;
+}
+
+export interface FrondConfig {
+  /** Class names exposed as the frond's public contract (all surfaces). */
+  expose?: string[];
+  /**
+   * The entities this frond may read ACROSS sources, by name.
+   *
+   * It is not a permission checked after the fact: the list IS the environment a
+   * cross-source query runs in — a source holding none of these is never opened, so
+   * its tables do not exist in that connection. `facadeFor` excludes an entity with no
+   * door on purpose ("it would publish the auth tables to anyone who asks"), and a SQL
+   * door at app scope would hand them over; this is what keeps it shut.
+   *
+   * Declaring it is what makes `Sources` injectable here. A frond that declares none
+   * asks for none, and nothing is attached on its behalf.
+   */
+  reads?: string[];
+  /** Per-surface entity lists. Overrides default deduction for each named surface. */
+  surfaces?: Record<string, string[]>;
+  /** Interface → implementation bindings for DI (e.g. { Database: 'SqliteDatabase' }). */
+  bindings?: Record<string, string>;
+  /** Per-operation overrides. Key = operation name (method name on a handler). */
+  operations?: Record<string, OperationOverride>;
+}
+
+// ── Helper ───────────────────────────────────────
+
+/**
+ * Define a frond configuration (typed identity helper).
+ *
+ * ```ts
+ * // fronds/auth/frond.config.ts
+ * import { defineFrond } from '@fougere/core'
+ * export default defineFrond({ expose: ['User', 'AuthHandler'] })
+ * ```
+ */
+export function defineFrond(config: FrondConfig): FrondConfig {
+  return config;
+}
+
+// ── Loading ──────────────────────────────────────
+
+const FROND_CONFIG_FILES = ['frond.config.ts', 'frond.config.js', 'frond.config.mjs'];
+
+/**
+ * Load a frond's `frond.config.{ts,js,mjs}` from the given frond directory.
+ * Returns `undefined` if no config file is found.
+ */
+export async function loadFrondConfig(frondPath: string): Promise<FrondConfig | undefined> {
+  for (const file of FROND_CONFIG_FILES) {
+    const path = resolve(frondPath, file);
+    if (existsSync(path)) {
+      const mod = await import(path);
+      return mod.default ?? mod;
+    }
+  }
+  return undefined;
+}

package/src/graph.ts

@@ -0,0 +1,180 @@
+import { Role } from '@fougere/schema';
+/**
+ * Entity dependency graph — analyzes ref() links between entities
+ * to suggest domain boundaries for splitting fronds.
+ */
+import type { FrondDescriptor } from './scan/frond.js';
+
+export interface EntityNode {
+  name: string;
+  frond: string;
+  refs: string[];       // entity names this entity references
+  referencedBy: string[]; // entity names that reference this entity
+}
+
+export interface DomainCluster {
+  name: string;
+  entities: string[];
+  crossRefs: { from: string; to: string; targetCluster: string }[];
+}
+
+/** Build the full entity dependency graph from scanned fronds. */
+export function buildGraph(fronds: FrondDescriptor[]): Map<string, EntityNode> {
+  const nodes = new Map<string, EntityNode>();
+
+  // First pass: create nodes and collect refs
+  for (const frond of fronds) {
+    for (const entity of frond.entities) {
+      const refs: string[] = [];
+      for (const [, field] of Object.entries(entity.entityClass.getFields())) {
+        if (Role.of(field).isReference) {
+          const resolved = Role.of(field).target;
+          const targetName = typeof resolved === 'function' && 'name' in resolved
+            ? (resolved.name as string).toLowerCase()
+            : undefined;
+          if (targetName) refs.push(targetName);
+        }
+      }
+      nodes.set(entity.name, { name: entity.name, frond: frond.name, refs, referencedBy: [] });
+    }
+  }
+
+  // Second pass: populate referencedBy
+  for (const [, node] of nodes) {
+    for (const ref of node.refs) {
+      const target = nodes.get(ref);
+      if (target) target.referencedBy.push(node.name);
+    }
+  }
+
+  return nodes;
+}
+
+/**
+ * Cluster entities into domains using connected component analysis.
+ * Entities linked by refs (in either direction) belong to the same cluster.
+ */
+export function clusterEntities(nodes: Map<string, EntityNode>): DomainCluster[] {
+  const visited = new Set<string>();
+  const clusters: string[][] = [];
+
+  // BFS to find connected components
+  for (const [name] of nodes) {
+    if (visited.has(name)) continue;
+
+    const cluster: string[] = [];
+    const queue = [name];
+
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      if (visited.has(current)) continue;
+      visited.add(current);
+      cluster.push(current);
+
+      const node = nodes.get(current)!;
+      for (const ref of [...node.refs, ...node.referencedBy]) {
+        if (!visited.has(ref) && nodes.has(ref)) {
+          queue.push(ref);
+        }
+      }
+    }
+
+    if (cluster.length > 0) clusters.push(cluster);
+  }
+
+  // Name each cluster by its hub (most referenced entity)
+  return clusters.map((entities) => {
+    const hub = entities
+      .map((name) => ({ name, score: nodes.get(name)!.referencedBy.length }))
+      .sort((a, b) => b.score - a.score)[0];
+
+    return {
+      name: hub.name,
+      entities,
+      crossRefs: [],
+    };
+  });
+}
+
+/**
+ * If there's only one big cluster, try to split it using Kernighan-Lin-style
+ * heuristic: find the entity with the fewest cross-links and use it as a cut point.
+ */
+export function suggestSplit(
+  nodes: Map<string, EntityNode>,
+  minClusterSize = 2,
+): DomainCluster[] {
+  const clusters = clusterEntities(nodes);
+
+  // If already multiple clusters, just annotate cross-refs
+  if (clusters.length > 1) {
+    return annotateCrossRefs(clusters, nodes);
+  }
+
+  // No entities at all — nothing to cluster (empty or fresh workspace).
+  if (clusters.length === 0) return clusters;
+
+  // Single cluster — try to find natural cut points
+  const allEntities = clusters[0].entities;
+  if (allEntities.length <= minClusterSize) return clusters;
+
+  // Score each entity by how many unique "groups" it connects
+  // Entities with high betweenness are boundaries, not cluster members
+  const subClusters: string[][] = [];
+  const assigned = new Set<string>();
+
+  // Start with entities that have no outgoing refs (leaves/roots)
+  const roots = allEntities.filter((name) => nodes.get(name)!.refs.length === 0);
+
+  for (const root of roots) {
+    if (assigned.has(root)) continue;
+    const group: string[] = [root];
+    assigned.add(root);
+
+    // Add entities that reference this root
+    for (const refBy of nodes.get(root)!.referencedBy) {
+      if (!assigned.has(refBy)) {
+        group.push(refBy);
+        assigned.add(refBy);
+      }
+    }
+    subClusters.push(group);
+  }
+
+  // Any remaining unassigned entities form their own group
+  const remaining = allEntities.filter((name) => !assigned.has(name));
+  if (remaining.length > 0) subClusters.push(remaining);
+
+  // Convert to domain clusters
+  const result = subClusters.map((entities) => {
+    const hub = entities
+      .map((name) => ({ name, score: nodes.get(name)!.referencedBy.length }))
+      .sort((a, b) => b.score - a.score)[0];
+    return { name: hub.name, entities, crossRefs: [] as DomainCluster['crossRefs'] };
+  });
+
+  return annotateCrossRefs(result, nodes);
+}
+
+function annotateCrossRefs(clusters: DomainCluster[], nodes: Map<string, EntityNode>): DomainCluster[] {
+  const entityToCluster = new Map<string, string>();
+  for (const cluster of clusters) {
+    for (const entity of cluster.entities) {
+      entityToCluster.set(entity, cluster.name);
+    }
+  }
+
+  for (const cluster of clusters) {
+    for (const entity of cluster.entities) {
+      const node = nodes.get(entity)!;
+      for (const ref of node.refs) {
+        const targetCluster = entityToCluster.get(ref);
+        if (targetCluster && targetCluster !== cluster.name) {
+          cluster.crossRefs.push({ from: entity, to: ref, targetCluster });
+        }
+      }
+    }
+  }
+
+  return clusters;
+}

package/src/identity-keys.ts

@@ -0,0 +1,43 @@
+/**
+ * Making keys and issuing grants — the half of identity that runs at a DEPLOYMENT.
+ *
+ * It sits on the Node entry because it is the CLI speaking: `fougere keys` generates a
+ * pair, `fougere grant` binds a name to one, and both happen once, on a machine with a
+ * filesystem. Neither is reachable from a request path, so nothing here is on any hot
+ * path and `generateKeyPairSync` — the one gesture WebCrypto could not replace without
+ * changing what a key IS — never has to leave `node:crypto`.
+ *
+ * The verifying half is elsewhere (`identity.ts`) because it runs per call, everywhere.
+ */
+import { createPrivateKey, createPublicKey, generateKeyPairSync, sign } from 'node:crypto';
+import { b64url } from './crypto/encoding.js';
+
+/** A fresh Ed25519 pair, PEM both ways. The root's and a frond's are the same kind. */
+export function generateKeyPair(): { privateKey: string; publicKey: string } {
+  const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+  return {
+    privateKey: privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(),
+    publicKey: publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+  };
+}
+
+/**
+ * Bind a name to a public key, signed by the root — the whole of what a receiver
+ * needs to recognize a frond it has never seen.
+ *
+ * `ttlDays` bounds the damage of a leaked frond key without a revocation list:
+ * re-issuing is a deployment, which is the same gesture that leaked it.
+ */
+export function issueGrant(
+  rootPrivateKey: string,
+  name: string,
+  frondPublicKey: string,
+  ttlDays = 90,
+): string {
+  const jwk = createPublicKey(frondPublicKey).export({ format: 'jwk' });
+  const now = Date.now();
+  const header = b64url(JSON.stringify({ alg: 'EdDSA', typ: 'fougere-grant' }));
+  const payload = b64url(JSON.stringify({ sub: name, jwk, iat: now, exp: now + ttlDays * 86_400_000 }));
+  const signingInput = `${header}.${payload}`;
+  return `${signingInput}.${b64url(new Uint8Array(sign(null, Buffer.from(signingInput), createPrivateKey(rootPrivateKey))))}`;
+}