@fougere/cli 0.12.5-alpha.0 → 0.13.0-alpha.0

package/fronds/scaffold/handlers/SyncHandler.ts

@@ -1,376 +0,0 @@
-import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { upperFirst, type SchemaDescriptor } from '@fougere/schema';
-import { EntityTypes } from '../../../src/typescript/EntityTypes.js';
-import { FacadeTypes } from '../../../src/typescript/FacadeTypes.js';
-// The card's shape is declared once, in core, and imported here. A private copy of it
-// lived in this file and went stale the day an op stopped being a bare name: nothing
-// compared the copy to the original, so the drift cost nothing until someone read it.
-import { assertIdentityCard, type IdentityCard } from '@fougere/core';
-import { type Conventions, resolveConventions, frondPackage } from '@fougere/core';
-import { loadConfig } from '@fougere/core/node';
-import { facadeModule, type Served } from '@fougere/compiler';
-import { ErrorCode } from '@fougere/core/contract';
-
-/**
- * A union of enum MEMBERS, from what the card said this operation refuses.
- *
- * `ErrorCode` is a string enum, so `'CONFLICT'` is not assignable to it: a literal reads as the
- * right thing and then refuses to narrow `FougereError<Code>`, which is the whole point. A code
- * this version does not know is dropped rather than written — the far side may be newer, and a
- * name that resolves to nothing would stop the consumer's build.
- */
-function codesOf(errors: readonly string[] | undefined): string {
-  const known = (errors ?? []).filter((code) => code in ErrorCode);
-  if (known.length === 0) return 'never';
-
-  return known.map((code) => `ErrorCode.${code}`).join(' | ');
-}
-
-function assertSafeName(kind: string, name: string): void {
-  if (typeof name !== 'string' || !/^[A-Za-z_$][A-Za-z0-9_$-]*$/.test(name)) {
-    throw new Error(`Invalid ${kind} name '${name}' received from remote`);
-  }
-}
-
-/**
- * The line every generated file carries. It is what makes pruning safe: sync removes what
- * IT wrote and nothing else, so a file a human dropped into the folder survives.
- */
-const GENERATED = 'Generated by `fougere sync`';
-
-export function entityClassName(name: string): string {
-  assertSafeName('entity', name);
-  const identifier = name
-    .split('-')
-    .filter(Boolean)
-    .map(upperFirst)
-    .join('');
-  if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(identifier)) {
-    throw new Error(`Entity name '${name}' cannot be represented as a TypeScript identifier`);
-  }
-
-  return identifier;
-}
-
-/**
- * One entry — a facade or a fact — validated the same way, because sync consumes the same two
- * values from both: a name it can turn into a class, and a descriptor it can rebuild.
- *
- * A missing descriptor is legal on either side and means different things: a facade that
- * stores nothing (a health check, a search across shapes), or a fact whose announced type
- * is not a declared entity. Neither produces a row class, and demanding one here refused
- * the WHOLE card over a single entry.
- */
-function assertEntry(kind: string, frondName: string, entry: { name: string; schema?: SchemaDescriptor } | undefined): void {
-  if (!entry || typeof entry !== 'object') {
-    throw new Error(`Remote frond '${frondName}' contains an invalid ${kind} entry`);
-  }
-  assertSafeName(kind, entry.name);
-  if (entry.schema === undefined) return;
-  // `ops` is not checked because it is not used: sync writes entities, and the name
-  // and the descriptor below are the only two values that reach a file. The clause
-  // that stood here demanded strings — the shape ops had before they carried their
-  // kind and their views — and so refused every real host. Validate what you consume.
-  const descriptor = entry.schema as unknown;
-  if (
-    !descriptor
-    || typeof descriptor !== 'object'
-    || Array.isArray(descriptor)
-    || (descriptor as SchemaDescriptor).type !== 'object'
-    || !(descriptor as SchemaDescriptor).properties
-    || typeof (descriptor as SchemaDescriptor).properties !== 'object'
-    || Array.isArray((descriptor as SchemaDescriptor).properties)
-    || (descriptor as SchemaDescriptor)['x-fougere-version'] !== 1
-    || (descriptor as SchemaDescriptor)['x-fougere-vendor'] !== 'fougere'
-  ) {
-    throw new Error(`Remote ${kind} '${entry.name}' has no valid schema descriptor`);
-  }
-}
-
-function identityCardOf(value: unknown): IdentityCard {
-  // The card's own shape is validated by the package that declares it — `fronds`, and each
-  // frond's `facades`. What stays here is what only a writer of files needs: a name safe to
-  // become one, and the descriptor a class is generated from.
-  const card = assertIdentityCard(value, 'Remote rpc.discover');
-  for (const frond of card.fronds) {
-    assertSafeName('frond', frond.name);
-    // Absent rather than empty is tolerated: a host older than the fact list says nothing
-    // about facts, and refusing it would break sync against every previous version for a
-    // feature the consumer may not use.
-    if (frond.facts !== undefined && !Array.isArray(frond.facts)) {
-      throw new Error(`Remote frond '${frond.name}' has no valid facts array`);
-    }
-    for (const facade of frond.facades) assertEntry('facade', frond.name, facade);
-    for (const fact of frond.facts ?? []) assertEntry('fact', frond.name, fact);
-  }
-
-  return card;
-}
-
-export default class SyncHandler {
-  // cwd is ambient in a CLI — not a DI service (the container resolves by type).
-  private cwd = process.cwd();
-
-  /** Mirror a remote frond's contract into local entities. */
-  async execute(input: { frond: string; from: string }): Promise<{ path: string; entities: string[]; removed: string[] }> {
-    assertSafeName('frond', input.frond);
-    let remoteUrl: URL;
-    try {
-      remoteUrl = new URL(input.from);
-    } catch {
-      throw new Error(`Invalid remote URL '${input.from}'`);
-    }
-    if (remoteUrl.protocol !== 'http:' && remoteUrl.protocol !== 'https:') {
-      throw new Error(`Remote URL must use http or https, got '${remoteUrl.protocol}'`);
-    }
-    const baseUrl = remoteUrl.toString().replace(/\/$/, '');
-
-    // The served frond answers `rpc.discover` on its call endpoint with its
-    // identity card — the same surface every consumer reads, no side endpoint.
-    const res = await fetch(`${baseUrl}/_fougere/call`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'rpc.discover', params: { params: {}, query: {}, state: {} } }),
-      signal: AbortSignal.timeout(10_000),
-    });
-    if (!res.ok) {
-      throw new Error(`Failed to reach ${baseUrl}/_fougere/call: ${res.status} ${res.statusText}`);
-    }
-    const rpc = (await res.json()) as { result?: IdentityCard; error?: { message: string } };
-    if (rpc.error) throw new Error(`Remote error: ${rpc.error.message}`);
-    const card = identityCardOf(rpc.result);
-
-    const target = card.fronds.find((f) => f.name === input.frond);
-    if (!target) {
-      throw new Error(`Frond '${input.frond}' not found on ${baseUrl}. Available: ${card.fronds.map((f) => f.name).join(', ')}`);
-    }
-
-    // The consumer's own convention: a synced frond is laid out like the ones they wrote,
-    // and the export map below is what makes `@fronds/<name>/<dir>/X.js` resolve.
-    const conventions = resolveConventions((await loadConfig(this.cwd)).conventions);
-    const entities = conventions.dirs.entities;
-    const handlers = conventions.dirs.handlers;
-
-    const frondDir = join(this.cwd, '.fougere', 'remotes', input.frond);
-    const entitiesDir = join(frondDir, entities);
-    const handlersDir = join(frondDir, handlers);
-    mkdirSync(entitiesDir, { recursive: true });
-    mkdirSync(handlersDir, { recursive: true });
-
-    /**
-     * What was written under each name — the barrel below is a projection of exactly this.
-     *
-     * Three combinations, and all three occur: a facade with rows behind it (both files), a
-     * facade with none (the façade type alone), and a fact (the row class alone, because
-     * nothing calls a fact).
-     */
-    const generated = new Map<string, { row: boolean; facade: boolean }>();
-    /** Absolute paths written by THIS run — anything else generated here is now stale. */
-    const written = new Set<string>();
-    const claim = (name: string): string => {
-      const className = entityClassName(name);
-      if (generated.has(className)) throw new Error(`Remote declares duplicate entity '${className}'`);
-      generated.set(className, { row: false, facade: false });
-
-      return className;
-    };
-
-    /**
-     * One card, one class.
-     *
-     * `Card.toSchema` gives the JUDGE — validate, from, getFields — and now takes the
-     * row shape as a type argument, so the same declaration gives the TYPE. Both
-     * come off the same card: nothing to keep in step, and the file a consumer reads
-     * has the shape of the one they would have written by hand
-     * (`class Post extends entity({…}) {}`).
-     */
-    const writeRow = (className: string, descriptor: SchemaDescriptor): void => {
-      written.add(join(entitiesDir, `${className}.ts`));
-      writeFileSync(join(entitiesDir, `${className}.ts`), [
-        `import { Card } from '@fougere/schema';`,
-        ``,
-        `// Generated by \`fougere sync\` from ${baseUrl} — do not edit.`,
-        EntityTypes.of(descriptor).render({ name: className }),
-        ``,
-        `export default ${className};`,
-        ``,
-      ].join('\n'));
-      generated.get(className)!.row = true;
-    };
-
-    /** What the card says of each address — the same three facts a scan gives. */
-    const served: Served[] = [];
-
-    for (const { name, schema: descriptor, ops } of target.facades) {
-      const className = claim(name);
-      generated.get(className)!.facade = true;
-      served.push({
-        at: name,
-        handler: `import('./${handlers}/${className}Handler.js').${className}Handler`,
-        ops: (ops ?? []).map((op) => ({ name: op.name, codes: codesOf(op.errors) })),
-      });
-
-      // No shape behind this facade: its operations still travel, its rows do not exist.
-      // `rowType` falls back to `unknown`, which is the truth rather than an empty class.
-      if (descriptor !== undefined) writeRow(className, descriptor as SchemaDescriptor);
-
-      /**
-       * The facade's type, next to the row's — what `Facade<T>` needs and what nothing
-       * carried across a repository boundary.
-       *
-       * Writing `Facade<ArticleHandler>` used to require importing the handler's class.
-       * `sync` does not ship handlers and should not: a handler is behaviour with state,
-       * and behaviour does not travel. Its OPERATIONS do — the card names them, says how
-       * much each returns, and that is exactly a signature.
-       */
-      written.add(join(handlersDir, `${className}Handler.ts`));
-      writeFileSync(join(handlersDir, `${className}Handler.ts`), [
-        ...(descriptor !== undefined ? [`import type { ${className} } from '../entities/${className}.js';`, ``] : []),
-        `// Generated by \`fougere sync\` from ${baseUrl} — do not edit.`,
-        `// The shape of an invocation, restated rather than imported: this file is a`,
-        `// contract, and a contract that drags a runtime dependency is not one.`,
-        `type Invocation = { params?: Record<string, string>; query?: Record<string, unknown>; body?: unknown; state?: Record<string, unknown> };`,
-        ``,
-        FacadeTypes.of(ops ?? []).render({
-          name: `${className}Handler`,
-          ...(descriptor !== undefined ? { rowType: className } : {}),
-        }),
-        ``,
-      ].join('\n'));
-    }
-
-    /**
-     * The facts, which is the only reason a subscriber needs this command at all.
-     *
-     * A fact has no operation, so no façade type is written: a listener spells
-     * `reindex(fact: Fact<PostPublished>)` and the class is the whole of what it needs.
-     * Announced without a declared shape, there is nothing to write — a class built from
-     * a bare name would validate everything, which is worse than the absence.
-     */
-    for (const { name, schema: descriptor } of target.facts ?? []) {
-      const className = claim(name);
-      if (descriptor === undefined) {
-        generated.delete(className);
-        continue;
-      }
-      writeRow(className, descriptor as SchemaDescriptor);
-    }
-
-    /**
-     * The facade module, written from the CARD rather than from a scan.
-     *
-     * A frond in another repository cannot be scanned — there are no sources here. What the
-     * card carries is exactly the three facts the module needs: the addresses, the operations,
-     * and what each one refuses. The handler TYPE is the one thing it cannot carry, so the
-     * synthetic interface written above stands in its place: it names the same operations with
-     * the same answers, which is what a page reads.
-     *
-     * `facadeModule` is the compiler's own, not a copy: two spellings of one format would
-     * drift the day either gained a member.
-     */
-    writeFileSync(join(frondDir, 'facade.ts'), facadeModule(served, `${baseUrl} — a card, not a scan`));
-
-    // Barrel index
-    // One binding carries the value AND the type, because a class is both — the pair of
-    // re-exports that stood here was the price of declaring them separately.
-    const indexLines = [...generated].flatMap(([name, { row, facade }]) => [
-      ...(row ? [`export { default as ${name} } from './${entities}/${name}.js';`] : []),
-      ...(facade ? [`export type { ${name}Handler } from './${handlers}/${name}Handler.js';`] : []),
-    ]);
-    writeFileSync(join(frondDir, 'index.ts'), indexLines.join('\n') + '\n');
-
-    // Package.json
-    writeFileSync(join(frondDir, 'package.json'), JSON.stringify({
-      name: frondPackage(input.frond, conventions),
-      version: '0.0.0-synced',
-      type: 'module',
-      fougere: { frond: input.frond, synced: true, source: baseUrl },
-      exports: {
-        '.': './index.ts',
-        [`./${entities}/*`]: `./${entities}/*.ts`,
-        [`./${handlers}/*`]: `./${handlers}/*.ts`,
-        './package.json': './package.json',
-      },
-    }, null, 2) + '\n');
-
-    // .fougere/remotes.json is the central registry of synced remotes.
-    this.updateRemotesRegistry(input.frond, baseUrl, frondDir);
-
-    // Non-Nuxt projects only: Nuxt writes its own paths.
-    this.updateTsconfigPaths(input.frond, frondDir, conventions);
-
-    /**
-     * What the host no longer serves stops being importable here.
-     *
-     * The barrel is rewritten every run, so a dropped entity loses its export on its own
-     * — but the FILE stayed, and the generated `package.json` exports `'./entities/*'` as
-     * a wildcard, so `@fronds/blog/entities/Ticket.js` kept resolving to a class nothing
-     * behind it answers for. The consumer compiles, its local validator accepts, and the call
-     * comes back NOT_FOUND at the facade — or never leaves, because the page dropped the
-     * call and kept the type.
-     */
-    const removed = [...this.prune(entitiesDir, written), ...this.prune(handlersDir, written)];
-
-    return { path: entitiesDir, entities: [...generated.keys()], removed };
-  }
-
-  /** Delete the files this run did not write — and only the ones sync itself produced. */
-  private prune(dir: string, written: Set<string>): string[] {
-    const dropped: string[] = [];
-    for (const name of readdirSync(dir)) {
-      const path = join(dir, name);
-      if (written.has(path)) continue;
-      // Never remove what sync did not write. The folder is sync's, but a human who put
-      // something there meant it, and a delete is not the place to be clever.
-      if (!readFileSync(path, 'utf-8').includes(GENERATED)) continue;
-      rmSync(path);
-      dropped.push(name);
-    }
-
-    return dropped;
-  }
-
-  /** Write/update .fougere/remotes.json — read by @fougere/nuxt for auto-aliasing. */
-  private updateRemotesRegistry(name: string, baseUrl: string, localPath: string): void {
-    const registryPath = join(this.cwd, '.fougere', 'remotes.json');
-    let registry: Record<string, { url: string; path: string }> = {};
-
-    if (existsSync(registryPath)) {
-      try {
-        const parsed: unknown = JSON.parse(readFileSync(registryPath, 'utf-8'));
-        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('expected an object');
-        registry = parsed as Record<string, { url: string; path: string }>;
-      } catch (cause) {
-        throw new Error(`Cannot update corrupt remote registry at ${registryPath}`, { cause });
-      }
-    }
-
-    registry[name] = { url: baseUrl, path: localPath };
-    mkdirSync(join(this.cwd, '.fougere'), { recursive: true });
-    writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');
-  }
-
-  /** Add the frond's scoped name to tsconfig paths if tsconfig.json exists. */
-  private updateTsconfigPaths(name: string, localPath: string, conventions: Conventions): void {
-    const tsconfigPath = join(this.cwd, 'tsconfig.json');
-    if (!existsSync(tsconfigPath)) return;
-
-    try {
-      const raw = readFileSync(tsconfigPath, 'utf-8');
-      const tsconfig = JSON.parse(raw);
-
-      // Don't touch Nuxt-managed tsconfigs (extends .nuxt/tsconfig.json)
-      if (tsconfig.extends?.includes('.nuxt/')) return;
-
-      tsconfig.compilerOptions ??= {};
-      tsconfig.compilerOptions.paths ??= {};
-
-      const relative = localPath.replace(this.cwd, '.').replace(/\\/g, '/');
-      tsconfig.compilerOptions.paths[frondPackage(name, conventions)] = [`${relative}/index.ts`];
-      tsconfig.compilerOptions.paths[`${frondPackage(name, conventions)}/*`] = [`${relative}/*`];
-
-      writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + '\n');
-    } catch { /* tsconfig parse error — skip */ }
-  }
-}