@arcote.tech/arc-cli 0.7.31 → 0.8.0

package/src/platform/shared.ts

@@ -23,6 +23,8 @@ import {
   type BuildCache,
 } from "../builder/build-cache";
 import { extractAccessMap } from "../builder/access-extractor";
+import { buildPeerShell, type PeerShellResult } from "../builder/peer-shell";
+import type { FederationConfig } from "@arcote.tech/platform";
 import { assertOneModulePerPackage, planChunks } from "../builder/chunk-planner";
 import { collectFrameworkDeps } from "../builder/dependency-collector";
 import {
@@ -156,6 +158,7 @@ export async function buildAll(
   const cache = loadBuildCache(ws.arcDir);
   const noCache = opts.noCache ?? false;
   const themePath = ws.rootPkg.arc?.theme as string | undefined;
+  const federation = getFederationConfig(ws);
 
   log(`Building (concurrency parallel${noCache ? ", no-cache" : ""})...`);
 
@@ -188,27 +191,77 @@ export async function buildAll(
   mkdirSync(ws.arcDir, { recursive: true });
   writeFileSync(
     join(ws.arcDir, "access.json"),
-    JSON.stringify(accessMap, null, 2) + "\n",
+    JSON.stringify(accessMap.access, null, 2) + "\n",
+  );
+
+  // Federacja per-moduł (spec/module-federation.md): rola HOSTA (arc.federation
+  // .host — importuje cudze moduły) i rola PARTNERA (moduły z exposeToHosts —
+  // eksportowane) są niezależne.
+  const isHost = Boolean(federation?.host);
+  const moduleNameOf = (name: string) => name.split("/").pop() ?? name;
+  const exposureOf = (pkgName: string): "local" | "external" | "both" =>
+    accessMap.exposure[moduleNameOf(pkgName)]?.exposure ?? "local";
+  // Normalna platforma: moduły local/both (external-only ukryte w macierzystej
+  // platformie). Host bierze wszystko (nie ukrywa niczego przed sobą).
+  const localPackages = isHost
+    ? ws.packages
+    : ws.packages.filter((p) => exposureOf(p.name) !== "external");
+  // Build federowany: moduły external/both → browser-fed/.
+  const fedPackages = ws.packages.filter((p) =>
+    ["external", "both"].includes(exposureOf(p.name)),
+  );
+  const hasFederatedModules = fedPackages.length > 0;
+  // Peer-shell (import mapa) potrzebny, gdy współdzielimy runtime: host
+  // (ładuje gości) lub partner (jego chunki są external-peers).
+  const needsPeerShell = isHost || hasFederatedModules;
+  log(
   );
 
   // Phase 3 — group modules into chunks (one Bun.build per group).
-  const plan = planChunks(ws.packages, accessMap);
+  const plan = planChunks(localPackages, accessMap.access);
   ok(
     `Chunks: ${plan.chunks
       .map((c) => `${c}(${plan.groups.get(c)?.length ?? 0})`)
       .join(", ")}`,
   );
+  const fedPlan = hasFederatedModules
+    ? planChunks(fedPackages, accessMap.access)
+    : null;
+  if (fedPlan) {
+    ok(
+      `Federated modules: ${fedPackages.map((p) => moduleNameOf(p.name)).join(", ")}`,
+    );
+  }
 
-  // Phase 4 — independent parallel build units. The browser app is a single
-  // Bun.build call covering initial + all token groups (replaces ~25 separate
-  // Bun.builds for shell + per-chunk + per-package).
+  // Phase 4 — independent parallel build units. Normalny build (bundled, chyba
+  // że host → external peers) + opcjonalny build federowany (browser-fed/,
+  // zawsze external peers) + peer-shell.
   const i18nCollector = new Map<string, Set<string>>();
 
-  const [browserResult] = await Promise.all([
-    buildBrowserApp(ws.rootDir, ws.browserDir, plan, cache, noCache, i18nCollector),
+  const [browserResult, , , , shellResult, fedResult] = await Promise.all([
+    // HOST buduje się BUNDLED (React inline, eager — bez lazy-race), a initial
+    // eksponuje runtime na globalThis; gościa obsłuży peer-shell (globalThis).
+    buildBrowserApp(ws.rootDir, ws.browserDir, plan, cache, noCache, i18nCollector, {
+      federated: false,
+      exposeRuntime: isHost,
+    }),
     buildStyles(ws.rootDir, ws.arcDir, ws.packages, themePath, cache, noCache),
     copyBrowserAssets(ws, cache, noCache),
     buildTranslations(ws.rootDir, ws.arcDir, cache, noCache),
+    needsPeerShell
+      ? buildPeerShell(ws.rootDir, join(ws.arcDir, "shell"), cache, noCache)
+      : Promise.resolve(undefined),
+    fedPlan
+      ? buildBrowserApp(
+          ws.rootDir,
+          join(ws.arcDir, "browser-fed"),
+          fedPlan,
+          cache,
+          noCache,
+          i18nCollector,
+          { federated: true, unitId: "browser-app-fed" },
+        )
+      : Promise.resolve(undefined),
   ]);
 
   // Finalize i18n catalogs once after all chunks + initial bundle collected.
@@ -222,7 +275,43 @@ export async function buildAll(
 
   saveBuildCache(ws.arcDir, cache);
 
-  const finalManifest = assembleManifest(ws, browserResult, cache);
+  const federationBuild =
+    fedResult && hasFederatedModules
+      ? {
+          config: {
+            slug: federation?.slug,
+            auth: federation?.auth,
+          } as FederationConfig,
+          modules: fedPackages.map((p) => moduleNameOf(p.name)),
+          permissions: [
+            ...new Set(
+              fedPackages.flatMap(
+                (p) => accessMap.exposure[moduleNameOf(p.name)]?.permissions ?? [],
+              ),
+            ),
+          ],
+          slots: [
+            ...new Set(
+              fedPackages.flatMap(
+                (p) => accessMap.exposure[moduleNameOf(p.name)]?.slots ?? [],
+              ),
+            ),
+          ],
+          build: {
+            initial: fedResult.initial,
+            groups: fedResult.groups,
+            sharedChunks: fedResult.sharedChunks,
+          },
+        }
+      : undefined;
+
+  const finalManifest = assembleManifest(
+    ws,
+    browserResult,
+    cache,
+    shellResult,
+    federationBuild,
+  );
   writeFileSync(
     join(ws.arcDir, "manifest.json"),
     JSON.stringify(finalManifest, null, 2),
@@ -237,6 +326,8 @@ function assembleManifest(
   ws: WorkspaceInfo,
   browser: BrowserAppResult,
   cache: BuildCache,
+  shell?: PeerShellResult,
+  federation?: BuildManifest["federation"],
 ): BuildManifest {
   const stylesHash = cache.units["styles"]?.outputHash ?? "";
 
@@ -246,9 +337,29 @@ function assembleManifest(
     sharedChunks: browser.sharedChunks,
     stylesHash,
     buildTime: new Date().toISOString(),
+    ...(shell ? { shell: { imports: shell.imports, peers: shell.peers } } : {}),
+    ...(federation ? { federation } : {}),
   };
 }
 
+/**
+ * Konfiguracja federacji z root package.json (`arc.federation`) — tożsamość
+ * aplikacji (slug/auth) + rola hosta. Które MODUŁY są wystawione, decyduje
+ * `module().exposeToHosts()` (spec/module-federation.md). Waliduje slug.
+ */
+export function getFederationConfig(
+  ws: WorkspaceInfo,
+): FederationConfig | undefined {
+  const raw = ws.rootPkg.arc?.federation as FederationConfig | undefined;
+  if (!raw) return undefined;
+  if (raw.slug && !/^[a-z0-9-]+$/.test(raw.slug)) {
+    throw new Error(
+      `arc.federation.slug "${raw.slug}" — dozwolone tylko [a-z0-9-]+`,
+    );
+  }
+  return raw;
+}
+
 // ---------------------------------------------------------------------------
 // Browser assets — @arcote.tech/* deps deklarują w `arc.browserAssets` jakie
 // pliki muszą być dostępne w przeglądarce (np. SQLite WASM worker + .wasm).

package/src/platform/startup.ts

@@ -1,4 +1,5 @@
-import { existsSync, readFileSync, watch } from "fs";
+import { randomBytes } from "crypto";
+import { existsSync, mkdirSync, readFileSync, watch, writeFileSync } from "fs";
 import { join } from "path";
 import { startPlatformServer, type PlatformServer } from "./server";
 import type { BuildManifest } from "./shared";
@@ -37,6 +38,12 @@ export interface StartPlatformOptions {
   devMode: boolean;
   /** Dev-only: also start the Arc Context Map tool on a separate port. */
   map?: boolean;
+  /**
+   * Headless (spec/platform-headless.md): pełny host API + chunki federowane
+   * + mapa, ale BEZ shella SPA — dla aplikacji rozwijanych jako moduły
+   * konsumowane przez hosta federacji (BMF). Implikuje `map`.
+   */
+  headless?: boolean;
 }
 
 export async function startPlatform(
@@ -63,6 +70,20 @@ export async function startPlatform(
     manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
   }
 
+  // 1b. Tożsamość federacji — MUSI być gotowa przed `loadServerContext`, bo kod
+  // aplikacji czyta `ARC_APP_SECRET` na poziomie modułu (`token().secret(...)`).
+  // Jeden token parowania obsługuje mapę (discovery) i rejestrację hosta na
+  // platformie — deweloper wkleja hostowi JEDEN token, nie dwa.
+  assertProdFederationSecrets(devMode, !!manifest.federation);
+  const needsPairing =
+    !!manifest.federation || (devMode && (opts.map || opts.headless));
+  const pairingToken = needsPairing
+    ? resolvePairingToken(ws.rootDir)
+    : undefined;
+  if (manifest.federation) {
+    process.env.ARC_APP_SECRET = resolveAppSecret(ws.rootDir);
+  }
+
   // 2. Server context — same code path in both modes; loadServerContext
   // imports the combined server bundle at .arc/platform/server/_server.js
   // (produced by the buildServerApp step in buildAll).
@@ -90,6 +111,14 @@ export async function startPlatform(
         moduleAccess,
         dbPath,
         devMode,
+        headless: opts.headless,
+        federation:
+          manifest.federation && pairingToken
+            ? {
+                registrationToken: pairingToken,
+                appSecret: process.env.ARC_APP_SECRET!,
+              }
+            : undefined,
       });
       break;
     } catch (e) {
@@ -115,9 +144,26 @@ export async function startPlatform(
 
   // 4a. Dev-only: optional Arc Context Map tool on a separate port, starting
   // just above the platform's actual port (auto-increments if busy).
+  // Headless implikuje mapę (parowanie + discovery to jego interfejs).
   let onReload: (() => void) | undefined;
-  if (devMode && opts.map) {
-    onReload = await startMapTool(ws, actualPort + 1);
+  if (devMode && (opts.map || opts.headless)) {
+    // Mapa startuje PO platformie, więc jej adres ogłaszamy w `/api/discovery`
+    // dopiero teraz (setMapUrl). W prod mapy nie ma i pole zostaje `null`.
+    onReload = await startMapTool(ws, actualPort + 1, pairingToken!, platform, {
+      platformUrl: `http://localhost:${actualPort}`,
+      // Discovery: meta modułów wystawionych (federation.build pominięte —
+      // konsument bierze artefakty z /api/federation/manifest).
+      federation: manifest.federation
+        ? {
+            slug: manifest.federation.config.slug,
+            auth: manifest.federation.config.auth,
+            modules: manifest.federation.modules,
+            permissions: manifest.federation.permissions,
+            slots: manifest.federation.slots,
+          }
+        : undefined,
+      peers: manifest.shell?.peers,
+    });
   }
 
   // 4. Dev-only: file watcher + debounced rebuild + SSE notify.
@@ -142,22 +188,42 @@ export async function startPlatform(
 async function startMapTool(
   ws: WorkspaceInfo,
   port: number,
+  /** Token parowania — ten sam, którym host rejestruje się na platformie. */
+  authToken: string,
+  /** Serwer platformy — dostaje adres mapy do ogłoszenia w `/api/discovery`. */
+  platformServer: PlatformServer,
+  platform?: {
+    /** Adres serwera platformy (discovery: gdzie żyją komendy/query/WS). */
+    platformUrl: string;
+    federation?: unknown;
+    peers?: Readonly<Record<string, string>>;
+  },
 ): Promise<(() => void) | undefined> {
   try {
-    const { startMapServer } = await import("@arcote.tech/arc-map");
+    const { startMapServer, MAP_SCHEMA_VERSION } = await import(
+      "@arcote.tech/arc-map"
+    );
     const { getContext } = await import("@arcote.tech/platform");
     const globs = ws.packages
       .map((p) => join(p.path, "src", "**", "*.{ts,tsx}"));
     const packageOf = (absFile: string): string | undefined =>
       ws.packages.find((p) => absFile.startsWith(join(p.path, "src")))?.name;
 
+    // Tożsamość aplikacji dla zewnętrznych konsumentów (import do BMF).
+    const meta = readAppMeta(ws.rootDir, MAP_SCHEMA_VERSION);
+
     const map = await startMapServer({
       getContext: () => getContext(),
       scan: { globs, workspaceRoot: ws.rootDir, packageOf },
       useCasePackages: ws.packages.map((p) => ({ name: p.name, path: p.path })),
       port,
+      authToken,
+      meta,
+      platform,
     });
+    platformServer.setMapUrl(map.url);
     ok(`Context map → ${map.url}`);
+    ok(`Pairing token: ${authToken}`);
     return map.notifyReload;
   } catch (e) {
     err(`Context map failed to start: ${(e as Error).message}`);
@@ -165,6 +231,144 @@ async function startMapTool(
   }
 }
 
+/**
+ * PROD + federacja → sekrety MUSZĄ pochodzić z env. Twarda odmowa startu.
+ *
+ * DLACZEGO tak ostro: `.arc/` nie trafia ani do obrazu (deploy kopiuje tylko
+ * `.arc/platform/`), ani na wolumen (montowane jest tylko `.arc/data`). Plik
+ * wygenerowany wewnątrz kontenera przeżywa `restart`, ale **ginie przy pierwszym
+ * `recreate`** (nowy obraz = nowy kontener). Wtedy:
+ *   - nowy `ARC_APP_SECRET` → hosty trzymają STARY sekret, więc żadna asercja
+ *     tożsamości się nie zweryfikuje i aplikacja przestaje działać u wszystkich,
+ *     bez jednego błędu przy starcie,
+ *   - nowy token parowania → istniejące parowania martwe.
+ *
+ * Cicha awaria dzień po deployu jest dużo gorsza niż głośna odmowa startu.
+ * Wymieniamy WSZYSTKIE braki naraz — inaczej operator poprawia po jednej na deploy.
+ */
+function assertProdFederationSecrets(
+  devMode: boolean,
+  hasFederation: boolean,
+): void {
+  if (devMode || !hasFederation) return;
+  const missing: string[] = [];
+  if (!process.env.ARC_APP_SECRET) missing.push("ARC_APP_SECRET");
+  if (!process.env.ARC_PAIRING_TOKEN && !process.env.ARC_MAP_TOKEN) {
+    missing.push("ARC_PAIRING_TOKEN");
+  }
+  if (missing.length === 0) return;
+
+  err(
+    `Federacja w produkcji wymaga zmiennych środowiskowych: ${missing.join(", ")}.\n` +
+      `  Bez nich sekret i token są generowane w kontenerze i GINĄ przy pierwszym\n` +
+      `  recreate — hosty musiałyby przeinstalować aplikację, bez żadnego błędu.\n` +
+      `  Ustaw je w deployu (deploy.arc.json → envVars + deploy.arc.<env>.env).`,
+  );
+  process.exit(1);
+}
+
+/**
+ * Sekret aplikacji — WŁASNOŚĆ PARTNERA, stały między restartami. Kolejność:
+ *   1. `ARC_APP_SECRET` (env) — jawna kontrola (prod, rotacja)
+ *   2. `.arc/app-secret` — wygenerowany raz, przeżywa restart
+ *   3. wygeneruj i zapisz
+ *
+ * Tym sekretem host federacji (BMF) podpisuje asercje tożsamości, a aplikacja
+ * je weryfikuje (`token("hostIdentity", …).secret(process.env.ARC_APP_SECRET)`).
+ * Sekret NALEŻY do aplikacji i host go POBIERA przy rejestracji
+ * (`POST /api/federation/register`) — nie odwrotnie. Dzięki temu aplikacja ma
+ * go już przy starcie i instalacja u hosta nie wymaga wklejania niczego do env
+ * ani restartu partnera (to było źródłem błędnego koła: instalacja → restart →
+ * nowy token parowania → parowanie martwe).
+ *
+ * Ustawiany do `process.env` PRZED `loadServerContext`, bo kod aplikacji czyta
+ * go na poziomie modułu. `.arc/` jest gitignorowane.
+ */
+function resolveAppSecret(rootDir: string): string {
+  const fromEnv = process.env.ARC_APP_SECRET;
+  if (fromEnv) return fromEnv;
+
+  const file = join(rootDir, ".arc", "app-secret");
+  try {
+    const saved = readFileSync(file, "utf-8").trim();
+    if (saved) return saved;
+  } catch {
+    // brak pliku lub nieczytelny — generujemy nowy poniżej
+  }
+
+  const secret = randomBytes(32).toString("base64url");
+  try {
+    mkdirSync(join(rootDir, ".arc"), { recursive: true });
+    writeFileSync(file, secret, { mode: 0o600 });
+  } catch (e) {
+    // Nie fatal, ale sekret zmieni się po restarcie → hosty stracą ważność.
+    err(
+      `App secret not persisted (${(e as Error).message}) — hosts will need re-install after restart`,
+    );
+  }
+  return secret;
+}
+
+/**
+ * Token parowania — STAŁY między restartami. Kolejność:
+ *   1. `ARC_PAIRING_TOKEN` (env), alias `ARC_MAP_TOKEN` — jawna kontrola
+ *      (prod, CI, wiele instancji obok siebie)
+ *   2. `.arc/pairing-token` — wygenerowany raz, przeżywa restart
+ *   3. wygeneruj i zapisz
+ *
+ * Nazwa `ARC_MAP_TOKEN` jest historyczna: token bramkuje dziś także
+ * `/api/discovery` i `/api/federation/register` NA PLATFORMIE, nie tylko mapę.
+ * Zostaje jako alias, żeby nie łamać istniejących deployów.
+ *
+ * Token losowany przy każdym starcie unieważniał parowanie z hostem (host
+ * trzyma go po swojej stronie), przez co instalacja aplikacji federowanej
+ * wpadała w błędne koło: instalacja wymagała restartu partnera, a restart
+ * zabijał parowanie. `.arc/` jest gitignorowane, więc token nie wycieka do repo.
+ */
+function resolvePairingToken(rootDir: string): string {
+  const fromEnv = process.env.ARC_PAIRING_TOKEN || process.env.ARC_MAP_TOKEN;
+  if (fromEnv) return fromEnv;
+
+  const file = join(rootDir, ".arc", "pairing-token");
+  try {
+    const saved = readFileSync(file, "utf-8").trim();
+    if (saved) return saved;
+  } catch {
+    // brak pliku lub nieczytelny — generujemy nowy poniżej
+  }
+
+  const token = randomBytes(16).toString("base64url");
+  try {
+    mkdirSync(join(rootDir, ".arc"), { recursive: true });
+    writeFileSync(file, token, { mode: 0o600 });
+  } catch (e) {
+    // Nie fatal, ale użytkownik MUSI wiedzieć — inaczej wraca błędne koło.
+    err(
+      `Pairing token not persisted (${(e as Error).message}) — it will change on restart`,
+    );
+  }
+  return token;
+}
+
+/** Nazwa+wersja aplikacji z root package.json (best effort). */
+function readAppMeta(
+  rootDir: string,
+  schemaVersion: number,
+): { schemaVersion: number; name: string; version?: string } {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(rootDir, "package.json"), "utf-8"),
+    ) as { name?: string; version?: string };
+    return {
+      schemaVersion,
+      name: pkg.name ?? rootDir.split("/").pop() ?? "arc-app",
+      version: pkg.version,
+    };
+  } catch {
+    return { schemaVersion, name: rootDir.split("/").pop() ?? "arc-app" };
+  }
+}
+
 function attachDevWatcher(
   ws: WorkspaceInfo,
   platform: PlatformServer,