@arcote.tech/arc-cli 0.7.32 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcote.tech/arc-cli",
-  "version": "0.7.32",
+  "version": "0.8.1",
   "description": "CLI tool for Arc framework",
   "module": "index.ts",
   "main": "dist/index.js",
@@ -12,13 +12,13 @@
     "build": "bun build --target=bun ./src/index.ts --outdir=dist --external @arcote.tech/arc --external @arcote.tech/arc-ds --external @arcote.tech/arc-react --external @arcote.tech/platform --external @arcote.tech/arc-map --external '@opentelemetry/*' && chmod +x dist/index.js"
   },
   "dependencies": {
-    "@arcote.tech/arc": "^0.7.32",
-    "@arcote.tech/arc-ds": "^0.7.32",
-    "@arcote.tech/arc-react": "^0.7.32",
-    "@arcote.tech/arc-host": "^0.7.32",
-    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.32",
-    "@arcote.tech/arc-adapter-db-postgres": "^0.7.32",
-    "@arcote.tech/arc-otel": "^0.7.32",
+    "@arcote.tech/arc": "^0.8.1",
+    "@arcote.tech/arc-ds": "^0.8.1",
+    "@arcote.tech/arc-react": "^0.8.1",
+    "@arcote.tech/arc-host": "^0.8.1",
+    "@arcote.tech/arc-adapter-db-sqlite": "^0.8.1",
+    "@arcote.tech/arc-adapter-db-postgres": "^0.8.1",
+    "@arcote.tech/arc-otel": "^0.8.1",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.57.0",
     "@opentelemetry/core": "^1.30.0",
@@ -31,8 +31,8 @@
     "@opentelemetry/sdk-trace-base": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
     "@opentelemetry/semantic-conventions": "^1.27.0",
-    "@arcote.tech/platform": "^0.7.32",
-    "@arcote.tech/arc-map": "^0.7.32",
+    "@arcote.tech/platform": "^0.8.1",
+    "@arcote.tech/arc-map": "^0.8.1",
     "@clack/prompts": "^0.9.0",
     "commander": "^11.1.0",
     "chokidar": "^3.5.3",

package/src/builder/access-extractor.ts

@@ -41,10 +41,25 @@ export interface SerializedModuleAccess {
 
 export type SerializedAccessMap = Record<string, SerializedModuleAccess>;
 
+/** Deklaracja federacji modułu (module().exposeToHosts) odczytana build-time. */
+export interface SerializedModuleExposure {
+  exposure: "local" | "external" | "both";
+  permissions?: string[];
+  slots?: string[];
+}
+
+export type SerializedExposureMap = Record<string, SerializedModuleExposure>;
+
+export interface ExtractedModuleMeta {
+  access: SerializedAccessMap;
+  /** Moduły z exposeToHosts() — sterują buildem federowanym per moduł. */
+  exposure: SerializedExposureMap;
+}
+
 export async function extractAccessMap(
   rootDir: string,
   serverBundlePath: string,
-): Promise<SerializedAccessMap> {
+): Promise<ExtractedModuleMeta> {
   // The combined server bundle (`<arcDir>/server/_server.js`) side-effect-
   // registers every module via the platform singleton when imported. The
   // worker imports just this entry; Bun resolves its `chunk-<hash>.js` siblings
@@ -80,7 +95,7 @@ export async function extractAccessMap(
     if (exit !== 0) {
       throw new Error(`access-extractor subprocess exited with ${exit}`);
     }
-    return JSON.parse(readFileSync(outPath, "utf-8")) as SerializedAccessMap;
+    return JSON.parse(readFileSync(outPath, "utf-8")) as ExtractedModuleMeta;
   } finally {
     try {
       unlinkSync(workerPath);
@@ -126,16 +141,28 @@ for (const { name, path } of bundles) {
   }
 }
 
-const result = {};
-for (const [name, access] of platform.getAllModuleAccess()) {
-  result[name] = {
-    rules: (access.rules ?? []).map((r) => ({
+const access = {};
+for (const [name, a] of platform.getAllModuleAccess()) {
+  access[name] = {
+    rules: (a.rules ?? []).map((r) => ({
       token: { name: r.token?.name ?? "" },
       hasCheck: typeof r.check === "function",
     })),
   };
 }
 
+const exposure = {};
+const getExposure = platform.getAllModuleExposure;
+if (typeof getExposure === "function") {
+  for (const [name, e] of getExposure()) {
+    exposure[name] = {
+      exposure: e.exposure,
+      permissions: e.permissions ?? [],
+      slots: e.slots ?? [],
+    };
+  }
+}
+
 const { writeFileSync } = await import("node:fs");
-writeFileSync(out, JSON.stringify(result, null, 2) + "\\n");
+writeFileSync(out, JSON.stringify({ access, exposure }, null, 2) + "\\n");
 `.trim();

package/src/builder/framework-peers.ts

@@ -64,7 +64,13 @@ export const FRAMEWORK_PEERS = [...ARC_PEERS, ...REACT_PEERS] as const;
 export const SHELL_EXTERNALS = [
   ...FRAMEWORK_PEERS,
   "react/jsx-runtime",
-  "react/jsx-dev-runtime",
+  // `react/jsx-dev-runtime` CELOWO NIE jest external — jsxDevShimPlugin
+  // przepisuje go na eager re-export jsx-runtime (jsxDEV=jsx). Robienie go
+  // external + peer-shell wprowadzałoby lazy binding.
+  // Subpath react-dom — startApp robi `import { createRoot } from
+  // "react-dom/client"`; goły "react-dom" w external nie pokrywa subpathu
+  // w import mapie (brak trailing-slash mapowania), więc musi być jawnie.
+  "react-dom/client",
 ] as const;
 
 export const FRAMEWORK_PEER_SET = new Set<string>(FRAMEWORK_PEERS);

package/src/builder/module-builder.ts

@@ -24,6 +24,7 @@ import {
   FRAMEWORK_PEERS,
   FRAMEWORK_PEER_SET,
 } from "./framework-peers";
+import { runtimeExposePrelude } from "./peer-shell";
 import {
   readInstalledVersion,
   sha256Hex,
@@ -247,11 +248,12 @@ function jsxDevShimPlugin(): import("bun").BunPlugin {
         namespace: "jsx-dev-shim",
       }));
       build.onLoad({ filter: /.*/, namespace: "jsx-dev-shim" }, () => ({
-        contents: `import { jsx, jsxs, Fragment } from "react/jsx-runtime";
-export const jsxDEV = jsx;
-export const jsxsDEV = jsxs;
-export { Fragment };
-`,
+        // RE-EXPORT (nie `const jsxDEV = jsx`): przy external jsx-runtime
+        // (build federowany) computed-const trafia do lazy `__esm` wrappera
+        // Bun, którego init nie odpala przed użyciem jsxDEV w top-level
+        // literałach (jsxDEV undefined). Czysty re-export jest eager — binding
+        // jsxDEV istnieje od razu. Działa identycznie w bundled.
+        contents: `export { jsx as jsxDEV, jsxs as jsxsDEV, Fragment } from "react/jsx-runtime";`,
         loader: "ts",
       }));
     },
@@ -792,7 +794,26 @@ export async function buildBrowserApp(
   cache: BuildCache,
   noCache: boolean,
   i18nCollector: Map<string, Set<string>>,
+  opts?: {
+    /**
+     * Build FEDEROWALNY (spec/module-federation.md): framework peers
+     * (react, @arcote.tech/*) zostają external i rozwiązuje je import mapa
+     * shella (peer-shell). Chunki takiej aplikacji może importować host
+     * z innego originu — dostają JEGO singletony Reacta/rejestru.
+     */
+    federated?: boolean;
+    /** Cache unit id — inny dla drugiego (federowanego) buildu w tym samym workspace. */
+    unitId?: string;
+    /**
+     * HOST federacji: initial eksponuje bundled runtime na globalThis
+     * (peer-shell gościa go czyta). Build pozostaje BUNDLED (federated:false)
+     * — React inline, bez lazy-race. Patrz peer-shell.ts.
+     */
+    exposeRuntime?: boolean;
+  },
 ): Promise<BrowserAppResult> {
+  const federated = opts?.federated ?? false;
+  const exposeRuntime = opts?.exposeRuntime ?? false;
   mkdirSync(outDir, { recursive: true });
 
   const publicMembers = plan.groups.get("public") ?? [];
@@ -801,7 +822,7 @@ export async function buildBrowserApp(
     .map((c) => ({ name: c, members: plan.groups.get(c) ?? [] }))
     .filter((g) => g.members.length > 0);
 
-  const unitId = "browser-app";
+  const unitId = opts?.unitId ?? "browser-app";
 
   // Cache key spans every package's source plus the build config that
   // matters. If anything changes, full rebuild.
@@ -821,6 +842,14 @@ export async function buildBrowserApp(
       ...protectedGroups.map((g) => g.name).sort(),
     ],
     define: { ONLY_SERVER: "false", ONLY_BROWSER: "true", ONLY_CLIENT: "true" },
+    federated,
+    exposeRuntime,
+    // Zmiana listy peers (SHELL_EXTERNALS) musi unieważnić build federowany —
+    // stary bundle miałby zbundlowany peer, który teraz jest external.
+    externals: federated ? [...SHELL_EXTERNALS] : [],
+    // Podbij przy zmianie SEMANTYKI builda (pluginy/flagi), której nie widać
+    // w źródłach — inaczej cache odda bundle zbudowany starą logiką.
+    builderRev: 3,
   });
 
   if (!noCache && isCacheHit(cache, unitId, inputHash)) {
@@ -865,7 +894,10 @@ export async function buildBrowserApp(
   const initialEntry = join(tmpDir, "initial.ts");
   writeFileSync(
     initialEntry,
-    `${importLines(publicMembers)}\nexport { startApp } from "@arcote.tech/platform";\n`,
+    // Prelude ekspozycji runtime MUSI być PIERWSZY (przed importami modułów) —
+    // globalThis.__ARC_RT gotowe zanim cokolwiek innego się załaduje.
+    (exposeRuntime ? runtimeExposePrelude() + "\n" : "") +
+      `${importLines(publicMembers)}\nexport { startApp } from "@arcote.tech/platform";\n`,
   );
 
   const entryPaths: string[] = [initialEntry];
@@ -920,11 +952,17 @@ export async function buildBrowserApp(
       splitting: true,
       format: "esm",
       target: "browser",
-      // No externals. Framework peers (react, @arcote.tech/*) get bundled and
-      // deduped into shared chunks. No importmap needed in the HTML.
-      external: [],
+      // Bundled (default): no externals — framework peers trafiają do shared
+      // chunks, HTML bez importmapy. Federated: peers zostają external i
+      // rozwiązuje je import mapa shella (peer-shell) — warunek współdzielenia
+      // singletonów React/rejestru z hostem federacji.
+      external: federated ? [...SHELL_EXTERNALS] : [],
       plugins: [
-        singleReactPlugin(rootDir),
+        // Federated: singleReactPlugin MUSI zniknąć (jego onResolve wygrałby z
+        // `external` → React zbundlowany; singleton daje import mapa). Ale
+        // jsxDevShimPlugin ZOSTAJE (Bun i tak emituje jsxDEV) — jego shim jest
+        // teraz eager re-exportem, więc działa też przy external jsx-runtime.
+        ...(federated ? [] : [singleReactPlugin(rootDir)]),
         jsxDevShimPlugin(),
         i18nExtractPlugin(i18nCollector, rootDir),
       ],

package/src/builder/peer-shell.ts

@@ -0,0 +1,146 @@
+/**
+ * Peer-shell — współdzielony runtime dla federacji modułów
+ * (spec/module-federation.md).
+ *
+ * MODEL globalThis (a nie bundlowanie Reacta w peer-shell):
+ *  - HOST buduje się NORMALNIE (bundled — React inline, eager, bez lazy
+ *    __esm race w cyklicznych modułach) i w prelude initiala eksponuje swój
+ *    runtime: `globalThis.__ARC_RT[specifier] = <bundled module>`.
+ *  - Peer-shell emituje per specifier trywialny bundel, który RE-EKSPORTUJE
+ *    z `globalThis.__ARC_RT[specifier]` (eager — globalThis ustawia host
+ *    initial, zanim gość się załaduje). Import mapa w shell HTML kieruje gołe
+ *    specifiery gościa na te bundle.
+ *
+ * Dzięki temu chunk gościa (external peers) dostaje TEN SAM egzemplarz Reacta
+ * i rejestru platformy co host, a HOST nie płaci lazy-race (nie ma external
+ * Reacta — patrz historia buga „jsxDEV/jsx is not a function").
+ *
+ * Named exports wyliczamy BUILD-TIME (`import(specifier)` → Object.keys),
+ * bo `export * from globalThis` nie istnieje, a lista named React/@arcote/*
+ * jest za duża i zmienna, by wpisać ją ręcznie.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { basename, join } from "path";
+import { SHELL_EXTERNALS, FRAMEWORK_PEERS, shortNameOf } from "./framework-peers";
+import { isCacheHit, updateCache, type BuildCache } from "./build-cache";
+import { sha256Hex, sha256OfJson } from "./hash";
+
+/** Globalny slot runtime hosta — czytany przez peer-shell gościa. */
+export const RUNTIME_GLOBAL = "__ARC_RT";
+
+/** Wynik builda peer-shella — trafia do BuildManifest.shell. */
+export interface PeerShellResult {
+  /** specifier → ścieżka względna (`/shell/<short>.<hash>.js`). */
+  readonly imports: Record<string, string>;
+  /** Wersje peers (z zainstalowanych package.json) — polityka kompatybilności. */
+  readonly peers: Record<string, string>;
+  readonly cached: boolean;
+}
+
+function peerVersion(rootDir: string, pkg: string): string {
+  try {
+    const p = JSON.parse(
+      readFileSync(join(rootDir, "node_modules", pkg, "package.json"), "utf-8"),
+    ) as { version?: string };
+    return p.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/** Named exports specifiera (build-time introspekcja). */
+async function namedExportsOf(specifier: string): Promise<string[]> {
+  try {
+    const mod = (await import(specifier)) as Record<string, unknown>;
+    return Object.keys(mod).filter((k) => k !== "default" && /^[A-Za-z_$][\w$]*$/.test(k));
+  } catch {
+    return [];
+  }
+}
+
+/** Kod preludu ekspozycji runtime hosta — wstrzykiwany do initiala hosta. */
+export function runtimeExposePrelude(): string {
+  const lines = SHELL_EXTERNALS.map(
+    (spec, i) => `import * as __rt${i} from ${JSON.stringify(spec)};`,
+  );
+  const assigns = SHELL_EXTERNALS.map(
+    (spec, i) =>
+      `  ${JSON.stringify(spec)}: (__rt${i}.default ?? __rt${i}),\n` +
+      `  ${JSON.stringify(spec + "#ns")}: __rt${i},`,
+  );
+  return (
+    lines.join("\n") +
+    `\nglobalThis.${RUNTIME_GLOBAL} = Object.assign(globalThis.${RUNTIME_GLOBAL} ?? {}, {\n` +
+    assigns.join("\n") +
+    `\n});\n`
+  );
+}
+
+export async function buildPeerShell(
+  rootDir: string,
+  outDir: string,
+  cache: BuildCache,
+  noCache: boolean,
+): Promise<PeerShellResult> {
+  mkdirSync(outDir, { recursive: true });
+
+  const peers: Record<string, string> = {};
+  for (const pkg of FRAMEWORK_PEERS) peers[pkg] = peerVersion(rootDir, pkg);
+
+  // Named exports per specifier wchodzą do inputHash — zmiana wersji peera z
+  // nowym API unieważnia peer-shell.
+  const namedBySpec: Record<string, string[]> = {};
+  for (const spec of SHELL_EXTERNALS) namedBySpec[spec] = await namedExportsOf(spec);
+
+  const unitId = "peer-shell";
+  const inputHash = sha256OfJson({
+    peers,
+    externals: SHELL_EXTERNALS,
+    named: namedBySpec,
+    mode: "globalThis",
+    rev: 5,
+  });
+
+  if (!noCache && isCacheHit(cache, unitId, inputHash)) {
+    const cached = cache.units[unitId]?.outputHashes;
+    if (cached?._manifest) {
+      try {
+        const m = JSON.parse(cached._manifest) as PeerShellResult;
+        const files = Object.values(m.imports).map((p) => basename(p));
+        if (files.every((f) => existsSync(join(outDir, f)))) {
+          console.log(`  ✓ cached: ${unitId}`);
+          return { ...m, cached: true };
+        }
+      } catch {
+        // fall through to rebuild
+      }
+    }
+  }
+
+  console.log(`  building: ${unitId} (${SHELL_EXTERNALS.length} peers, globalThis)`);
+
+  const imports: Record<string, string> = {};
+  for (const specifier of SHELL_EXTERNALS) {
+    const short = shortNameOf(specifier).replace(/\//g, "-");
+    const named = namedBySpec[specifier] ?? [];
+    // Trywialny bundel czytający z globalThis — eager, żadnego CJS/lazy.
+    // `#ns` niesie pełny namespace (dla konsumentów `import *`).
+    const src =
+      `const M = globalThis.${RUNTIME_GLOBAL}[${JSON.stringify(specifier)}];\n` +
+      `const N = globalThis.${RUNTIME_GLOBAL}[${JSON.stringify(specifier + "#ns")}] ?? M;\n` +
+      `export default M;\n` +
+      named.map((n) => `export const ${n} = N[${JSON.stringify(n)}];`).join("\n") +
+      "\n";
+    const hash = sha256Hex(src).slice(0, 16);
+    const finalName = `${short}.${hash}.js`;
+    writeFileSync(join(outDir, finalName), src);
+    imports[specifier] = `/shell/${finalName}`;
+  }
+
+  const manifest: PeerShellResult = { imports, peers, cached: false };
+  updateCache(cache, unitId, inputHash, {
+    outputHashes: { _manifest: JSON.stringify(manifest) },
+  });
+  return manifest;
+}

package/src/commands/platform-deploy.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from "crypto";
 import { existsSync, readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -61,6 +62,19 @@ interface PlatformDeployOptions {
 //   7. For each env: updateEnvDeployment (atomic .env line + pull + up + health)
 // ---------------------------------------------------------------------------
 
+
+/**
+ * Czy aplikacja jest PARTNEREM federacji (wystawia moduły hostom).
+ *
+ * Czytamy deklarację z `package.json` (`arc.federation.slug`), a nie z manifestu
+ * builda — na tym etapie build jeszcze nie ruszył, a sekrety muszą istnieć,
+ * zanim compose zostanie wyrenderowany i wysłany. Host federacji
+ * (`arc.federation.host`) ich nie potrzebuje.
+ */
+function federationExposesModules(ws: { rootPkg: Record<string, any> }): boolean {
+  return Boolean(ws.rootPkg?.arc?.federation?.slug);
+}
+
 export async function platformDeploy(
   envArg: string | undefined,
   options: PlatformDeployOptions = {},
@@ -71,7 +85,7 @@ export async function platformDeploy(
   let cfg;
   if (!deployConfigExists(ws.rootDir)) {
     log("No deploy.arc.json found — launching survey.");
-    cfg = await runSurvey();
+    cfg = await runSurvey(ws.appName);
     saveDeployConfig(ws.rootDir, cfg);
     ok("Saved deploy.arc.json");
   }
@@ -88,6 +102,33 @@ export async function platformDeploy(
     );
   }
 
+  // Federacja: aplikacja wystawiająca moduły potrzebuje w prod DWÓCH stałych
+  // sekretów — inaczej `arc platform start` odmówi startu (startup.ts).
+  // Generujemy je tak jak hasło Postgresa: raz, do `deploy.arc.<env>.env`
+  // (gitignored), i odtąd każdy deploy używa tych samych.
+  //
+  // MUSZĄ być stałe: `.arc/` nie trafia ani do obrazu, ani na wolumen, więc
+  // sekret wygenerowany w kontenerze ginie przy pierwszym recreate — a wtedy
+  // hosty trzymające stary sekret przestają weryfikować asercje, CICHO.
+  if (federationExposesModules(ws)) {
+    for (const name of Object.keys(cfg.envs)) {
+      ensurePersistedSecret(ws.rootDir, name, "ARC_APP_SECRET", () =>
+        randomBytes(32).toString("base64url"),
+      );
+      ensurePersistedSecret(ws.rootDir, name, "ARC_PAIRING_TOKEN", () =>
+        randomBytes(16).toString("base64url"),
+      );
+    }
+    // Przeładowanie jest KONIECZNE: `loadDeployConfig` wczytał sidecar i scalił
+    // go do `cfg.envs[].envVars` ZANIM powyższe dopisało do pliku, a compose
+    // renderuje `environment` właśnie z `envVars`. Bez tego kontener startuje
+    // bez sekretów i pada na fail-fascie — przy czym DRUGI deploy by przeszedł
+    // (sidecar ma już klucze), co daje błąd zależny od historii, najgorszy do
+    // zdiagnozowania. Inaczej niż hasło Postgresa, które trafia do compose
+    // przez `${ARC_PG_PASSWORD_*}` z `/opt/arc/.env`, nie przez `envVars`.
+    cfg = loadDeployConfig(ws.rootDir);
+  }
+
   // Observability stack — one Grafana password per deployment (stack-wide,
   // not per-env). Persisted in `deploy.arc.env` (globals) so subsequent
   // deploys reuse the same login.

package/src/commands/platform-dev.ts

@@ -3,11 +3,16 @@ import { resolveWorkspace } from "../platform/shared";
 
 /** `arc platform dev` — dev mode (watcher + SSE reload + no-cache headers). */
 export async function platformDev(
-  opts: { noCache?: boolean; map?: boolean } = {},
+  opts: { noCache?: boolean; map?: boolean; headless?: boolean } = {},
 ): Promise<void> {
   const ws = resolveWorkspace();
   // noCache is consumed by buildAll inside startPlatform when devMode=true.
   // For now the dev startup always uses the cache after the first build;
   // explicit --no-cache here only matters if we wire it through later.
-  await startPlatform({ ws, devMode: true, map: opts.map });
+  await startPlatform({
+    ws,
+    devMode: true,
+    map: opts.map,
+    headless: opts.headless,
+  });
 }

package/src/deploy/assets/terraform/main.tf

@@ -1,4 +1,5 @@
 terraform {
+  required_version = ">= 1.1"
   required_providers {
     hcloud = {
       source  = "hetznercloud/hcloud"
@@ -11,17 +12,50 @@ provider "hcloud" {
   token = var.hcloud_token
 }
 
+locals {
+  # cloud-init injects the operator public key into the default image user's
+  # authorized_keys (root on Hetzner Ubuntu images) — matching the root-first
+  # ansible bootstrap. Used only when use_cloud_init_key = true.
+  cloud_init_user_data = <<-EOT
+    #cloud-config
+    ssh_pwauth: false
+    chpasswd:
+      expire: false
+    ssh_authorized_keys:
+      - ${trimspace(file(var.ssh_public_key))}
+    # Hetzner marks the root password expired (must-change-on-login) when no
+    # hcloud_ssh_key object is attached — which blocks non-interactive key
+    # login ("password change required, no TTY"). Clear the expiry so the
+    # deploy user / ansible can SSH in as root right away.
+    runcmd:
+      - chage -d $(date +%Y-%m-%d) -M -1 root
+  EOT
+}
+
+# Legacy path: a managed SSH key object in the Hetzner project. Skipped when
+# use_cloud_init_key = true, because several apps sharing one project with the
+# same local public key would collide on both key NAME and FINGERPRINT.
 resource "hcloud_ssh_key" "deploy" {
+  count      = var.use_cloud_init_key ? 0 : 1
   name       = "${var.server_name}-deploy"
   public_key = file(var.ssh_public_key)
 }
 
+# Re-home the pre-count address so an already-provisioned host (state created
+# before count existed) plans as a no-op instead of destroy+recreate — which
+# would ForceNew-replace the server. Ignored for fresh (empty) state.
+moved {
+  from = hcloud_ssh_key.deploy
+  to   = hcloud_ssh_key.deploy[0]
+}
+
 resource "hcloud_server" "arc" {
   name        = var.server_name
   image       = var.server_image
   server_type = var.server_type
   location    = var.server_location
-  ssh_keys    = [hcloud_ssh_key.deploy.id]
+  ssh_keys    = var.use_cloud_init_key ? [] : [hcloud_ssh_key.deploy[0].id]
+  user_data   = var.use_cloud_init_key ? local.cloud_init_user_data : null
 
   public_net {
     ipv4_enabled = true

package/src/deploy/assets/terraform/variables.tf

@@ -33,3 +33,9 @@ variable "ssh_public_key" {
   type        = string
   default     = "~/.ssh/id_ed25519.pub"
 }
+
+variable "use_cloud_init_key" {
+  description = "Inject the SSH public key via cloud-init user_data instead of a managed hcloud_ssh_key object (avoids name/fingerprint collisions when multiple apps share one Hetzner project)."
+  type        = bool
+  default     = false
+}

package/src/deploy/assets.ts

@@ -9,6 +9,7 @@
 // - Ansible/Jinja variables use {{ var }} which is safe in template literals.
 
 const TERRAFORM_MAIN_TF = `terraform {
+  required_version = ">= 1.1"
   required_providers {
     hcloud = {
       source  = "hetznercloud/hcloud"
@@ -21,17 +22,50 @@ provider "hcloud" {
   token = var.hcloud_token
 }
 
+locals {
+  # cloud-init injects the operator public key into the default image user's
+  # authorized_keys (root on Hetzner Ubuntu images) — matching the root-first
+  # ansible bootstrap. Used only when use_cloud_init_key = true.
+  cloud_init_user_data = <<-EOT
+    #cloud-config
+    ssh_pwauth: false
+    chpasswd:
+      expire: false
+    ssh_authorized_keys:
+      - \${trimspace(file(var.ssh_public_key))}
+    # Hetzner marks the root password expired (must-change-on-login) when no
+    # hcloud_ssh_key object is attached — which blocks non-interactive key
+    # login ("password change required, no TTY"). Clear the expiry so the
+    # deploy user / ansible can SSH in as root right away.
+    runcmd:
+      - chage -d $(date +%Y-%m-%d) -M -1 root
+  EOT
+}
+
+# Legacy path: a managed SSH key object in the Hetzner project. Skipped when
+# use_cloud_init_key = true, because several apps sharing one project with the
+# same local public key would collide on both key NAME and FINGERPRINT.
 resource "hcloud_ssh_key" "deploy" {
+  count      = var.use_cloud_init_key ? 0 : 1
   name       = "\${var.server_name}-deploy"
   public_key = file(var.ssh_public_key)
 }
 
+# Re-home the pre-count address so an already-provisioned host (state created
+# before count existed) plans as a no-op instead of destroy+recreate — which
+# would ForceNew-replace the server. Ignored for fresh (empty) state.
+moved {
+  from = hcloud_ssh_key.deploy
+  to   = hcloud_ssh_key.deploy[0]
+}
+
 resource "hcloud_server" "arc" {
   name        = var.server_name
   image       = var.server_image
   server_type = var.server_type
   location    = var.server_location
-  ssh_keys    = [hcloud_ssh_key.deploy.id]
+  ssh_keys    = var.use_cloud_init_key ? [] : [hcloud_ssh_key.deploy[0].id]
+  user_data   = var.use_cloud_init_key ? local.cloud_init_user_data : null
 
   public_net {
     ipv4_enabled = true
@@ -83,6 +117,12 @@ variable "ssh_public_key" {
   type        = string
   default     = "~/.ssh/id_ed25519.pub"
 }
+
+variable "use_cloud_init_key" {
+  description = "Inject the SSH public key via cloud-init user_data instead of a managed hcloud_ssh_key object (avoids name/fingerprint collisions when multiple apps share one Hetzner project)."
+  type        = bool
+  default     = false
+}
 `;
 
 const ANSIBLE_SITE_YML = `---

package/src/deploy/bootstrap.ts

@@ -82,10 +82,18 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
         `Environment variable ${cfg.provision.terraform.tokenEnv} is not set`,
       );
     }
+    // Server name: explicit config wins; legacy fallback `arc-<first env>`
+    // keeps existing single-app deploys from renaming their server. Set
+    // provision.terraform.serverName per app to share one Hetzner project.
+    const firstEnv = Object.keys(cfg.envs)[0] ?? "host";
+    const serverName = cfg.provision.terraform.serverName ?? `arc-${firstEnv}`;
+    const useCloudInitKey =
+      cfg.provision.terraform.sshKeyStrategy === "cloud-init";
     const tfOut = await runTerraform({
       tf: cfg.provision.terraform,
       token,
-      serverName: `arc-${Object.keys(cfg.envs)[0] ?? "host"}`,
+      serverName,
+      useCloudInitKey,
       workspaceDir: rootDir,
     });
     ok(`Server provisioned: ${tfOut.serverIp}`);