@arcote.tech/arc-cli 0.7.25 → 0.7.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcote.tech/arc-cli",
-  "version": "0.7.25",
+  "version": "0.7.27",
   "description": "CLI tool for Arc framework",
   "module": "index.ts",
   "main": "dist/index.js",
@@ -9,16 +9,16 @@
     "arc": "./dist/index.js"
   },
   "scripts": {
-    "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 '@opentelemetry/*' && chmod +x dist/index.js"
+    "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.25",
-    "@arcote.tech/arc-ds": "^0.7.25",
-    "@arcote.tech/arc-react": "^0.7.25",
-    "@arcote.tech/arc-host": "^0.7.25",
-    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.25",
-    "@arcote.tech/arc-adapter-db-postgres": "^0.7.25",
-    "@arcote.tech/arc-otel": "^0.7.25",
+    "@arcote.tech/arc": "^0.7.27",
+    "@arcote.tech/arc-ds": "^0.7.27",
+    "@arcote.tech/arc-react": "^0.7.27",
+    "@arcote.tech/arc-host": "^0.7.27",
+    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.27",
+    "@arcote.tech/arc-adapter-db-postgres": "^0.7.27",
+    "@arcote.tech/arc-otel": "^0.7.27",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.57.0",
     "@opentelemetry/core": "^1.30.0",
@@ -31,7 +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.25",
+    "@arcote.tech/platform": "^0.7.27",
+    "@arcote.tech/arc-map": "^0.7.27",
     "@clack/prompts": "^0.9.0",
     "commander": "^11.1.0",
     "chokidar": "^3.5.3",

package/src/builder/dependency-collector.ts

@@ -3,7 +3,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { basename, dirname, join } from "path";
 import { fileURLToPath } from "node:url";
 import { FRAMEWORK_PEERS, FRAMEWORK_PEER_SET } from "./framework-peers";
-import type { WorkspacePackage } from "./module-builder";
+import { readInstalledVersion } from "./hash";
+import type { ServerExternal, WorkspacePackage } from "./module-builder";
 
 export { FRAMEWORK_PEERS };
 
@@ -37,10 +38,17 @@ export function collectFrameworkDeps(
   rootDir: string,
   packages: WorkspacePackage[],
   sharedDeps: ReadonlyArray<{ name: string; version: string }> = [],
+  serverExternals: ReadonlyArray<ServerExternal> = [],
 ): CollectedDeps {
   mkdirSync(arcDir, { recursive: true });
 
   const versions = resolveFrameworkVersions(rootDir, packages);
+  // npm packages the server bundle left external — the runtime image must
+  // install them into /app/node_modules. This is the ONLY source for deps
+  // reached through a fragment the consumer never declares (e.g.
+  // `@arcote.tech/arc-files` → `@aws-sdk/client-s3`): the bundle records what
+  // it actually externalized, so the manifest tracks real usage, no whitelist.
+  mergeServerExternals(versions, rootDir, packages, serverExternals);
   // Shared deps (discovered across ≥ 2 workspace packages) join the framework
   // in the global manifest — installed once into <arcDir>/node_modules/ and
   // served via the shell so each module's browser bundle leaves them external.
@@ -178,12 +186,13 @@ function resolveFrameworkVersions(
   packages: WorkspacePackage[],
 ): Record<string, string> {
   // The framework manifest installs into /app/node_modules in the deploy
-  // image. It needs to cover:
+  // image. resolveFrameworkVersions covers the singleton @arcote.tech/* set:
   //   1. Static framework peers (FRAMEWORK_PEERS) — always present
   //   2. User-extension @arcote.tech/* peers (e.g. arc-ai-openai) declared
   //      as peerDeps on user context packages
-  //   3. npm runtime deps that server bundles leave external (non-workspace
-  //      deps not yet bundled inline)
+  // Plain npm runtime deps the server bundle leaves external are added
+  // separately by mergeServerExternals (driven by what the bundle actually
+  // externalized, not by what workspace packages happen to declare).
   // Resolution order for each: root package.json wins, then any workspace
   // package's deps/peerDeps, then "*" as last resort.
   const rootPkg = JSON.parse(
@@ -196,18 +205,10 @@ function resolveFrameworkVersions(
   const required = new Set<string>(FRAMEWORK_PEERS);
   for (const pkg of packages) {
     const peers = pkg.packageJson.peerDependencies ?? {};
-    const deps = (pkg.packageJson.dependencies ?? {}) as Record<string, string>;
     // Any @arcote.tech/* peer beyond the static list (e.g. arc-ai adapters).
     for (const name of Object.keys(peers)) {
       if (name.startsWith("@arcote.tech/")) required.add(name);
     }
-    // npm deps (non-workspace) — server bundles leave them external, so the
-    // image needs them in /app/node_modules.
-    for (const [name, spec] of Object.entries(deps)) {
-      if (spec.startsWith("workspace:")) continue;
-      if (name.startsWith("@arcote.tech/") || !isFrameworkExternal(name)) continue;
-      required.add(name);
-    }
   }
 
   const out: Record<string, string> = {};
@@ -217,32 +218,58 @@ function resolveFrameworkVersions(
       out[name] = rootSpec;
       continue;
     }
-    let found: string | undefined;
-    for (const pkg of packages) {
-      const spec =
-        (pkg.packageJson.dependencies ?? {})[name] ??
-        (pkg.packageJson.peerDependencies ?? {})[name];
-      if (spec) {
-        found = spec;
-        break;
-      }
-    }
-    out[name] = found ?? "*";
+    out[name] = findWorkspaceSpec(packages, name) ?? "*";
   }
   return out;
 }
 
+/** Version spec for `name` declared by any workspace package, if any. */
+function findWorkspaceSpec(
+  packages: WorkspacePackage[],
+  name: string,
+): string | undefined {
+  for (const pkg of packages) {
+    const spec =
+      (pkg.packageJson.dependencies ?? {})[name] ??
+      (pkg.packageJson.peerDependencies ?? {})[name];
+    if (spec) return spec;
+  }
+  return undefined;
+}
+
 /**
- * True if a non-arc npm dep is one the image must install globally for
- * runtime resolution. Today we include everything that user context packages
- * declare as deps but isn't `workspace:` — server bundles leave them external
- * so they MUST be present in /app/node_modules.
- *
- * Future optimization: bundle these inline into the server bundle to avoid
- * the install layer entirely. Left as a follow-up.
+ * Add server-bundle externals to the install manifest. For each, resolve a
+ * version spec by cascade so the image installs something compatible even when
+ * the consumer never declared the dep:
+ *   1. consumer root deps/devDeps   (their explicit pin — wins)
+ *   2. spec recorded from the importing package (e.g. arc-files peerDeps)
+ *   3. any workspace package's declaration
+ *   4. the version actually installed in node_modules (caret-ranged)
+ *   5. "*" as last resort
+ * Already-resolved names (framework peers) are left untouched.
  */
-function isFrameworkExternal(_name: string): boolean {
-  return true;
+function mergeServerExternals(
+  versions: Record<string, string>,
+  rootDir: string,
+  packages: WorkspacePackage[],
+  externals: ReadonlyArray<ServerExternal>,
+): void {
+  const rootPkg = JSON.parse(
+    readFileSync(join(rootDir, "package.json"), "utf-8"),
+  );
+  const rootDeps = (rootPkg.dependencies ?? {}) as Record<string, string>;
+  const rootDevDeps = (rootPkg.devDependencies ?? {}) as Record<string, string>;
+
+  for (const { name, version } of externals) {
+    if (versions[name]) continue;
+    const installed = readInstalledVersion(rootDir, name);
+    versions[name] =
+      rootDeps[name] ??
+      rootDevDeps[name] ??
+      version ??
+      findWorkspaceSpec(packages, name) ??
+      (installed ? `^${installed}` : "*");
+  }
 }
 
 function sha256OfFiles(paths: string[]): string {

package/src/builder/module-builder.ts

@@ -8,6 +8,7 @@ import {
   writeFileSync,
 } from "fs";
 import { basename, dirname, join, relative } from "path";
+import { builtinModules } from "node:module";
 import type { BuildManifest, ModuleDescriptor } from "@arcote.tech/platform";
 import { buildTypeDeclarations } from "../utils/build";
 import { i18nExtractPlugin, finalizeTranslations } from "../i18n";
@@ -18,7 +19,11 @@ import {
   type BuildCache,
 } from "./build-cache";
 import type { ChunkPlan } from "./chunk-planner";
-import { SHELL_EXTERNALS, FRAMEWORK_PEERS } from "./framework-peers";
+import {
+  SHELL_EXTERNALS,
+  FRAMEWORK_PEERS,
+  FRAMEWORK_PEER_SET,
+} from "./framework-peers";
 import {
   readInstalledVersion,
   sha256Hex,
@@ -97,30 +102,101 @@ function singleReactPlugin(rootDir: string): import("bun").BunPlugin {
   };
 }
 
+/** One external the server bundle leaves for the deploy image to install. */
+export interface ServerExternal {
+  /** Package name (subpath stripped): `@aws-sdk/client-s3`, `react`, … */
+  readonly name: string;
+  /** Version spec read from the importing package's package.json, if found. */
+  readonly version?: string;
+}
+
+const BUILTIN_SET = new Set<string>(builtinModules);
+
+/** Package name from a bare specifier, dropping any subpath. */
+function pkgNameOf(spec: string): string {
+  if (spec.startsWith("@")) return spec.split("/").slice(0, 2).join("/");
+  return spec.split("/")[0];
+}
+
+/** node:/bun: builtins — external by `target: "bun"`, never installed. */
+function isBuiltinSpec(spec: string): boolean {
+  if (spec.startsWith("node:") || spec.startsWith("bun:") || spec === "bun")
+    return true;
+  return BUILTIN_SET.has(spec) || BUILTIN_SET.has(pkgNameOf(spec));
+}
+
 /**
- * Marks heavy server-side packages as external. Bun.build's `external: string[]`
- * accepts only literal package names — wildcard like `@aws-sdk/*` is treated
- * verbatim and doesn't match anything. This plugin uses `onResolve` regex to
- * catch any subpackage matching the prefix and marks it external.
- *
- * Removes ~10-15 MB of AWS SDK v3 from every server bundle that transitively
- * pulls `@arcote.tech/arc-files` (e.g. `@ndt/content` was 340 MB before).
+ * Best-effort version spec for `name` as declared by the package that imports
+ * it. Walks up from the importer to the nearest package.json that lists `name`
+ * in deps/peerDeps/devDeps — e.g. `@aws-sdk/client-s3` resolves to the
+ * `^3.x` spec in `@arcote.tech/arc-files`'s peerDependencies. The collector
+ * falls back to root deps / installed version when this returns undefined.
+ */
+function versionFromImporter(importer: string, name: string): string | undefined {
+  let dir = importer ? dirname(importer) : "";
+  while (dir && dir !== dirname(dir)) {
+    const pj = join(dir, "package.json");
+    if (existsSync(pj)) {
+      try {
+        const json = JSON.parse(readFileSync(pj, "utf-8"));
+        const spec =
+          json.dependencies?.[name] ??
+          json.peerDependencies?.[name] ??
+          json.devDependencies?.[name];
+        if (typeof spec === "string") return spec;
+      } catch {
+        // unreadable package.json — keep walking
+      }
+    }
+    dir = dirname(dir);
+  }
+  return undefined;
+}
+
+/**
+ * Structural externalization for the combined server bundle: inline only
+ * first-party code (workspace `@ndt/*` source — handled earlier by
+ * `workspaceSourcePlugin` — plus non-peer `@arcote.tech/*` fragments like
+ * `arc-files`), and leave EVERY third-party npm package external. The deploy
+ * image installs externals into `/app/node_modules` anyway, so inlining them
+ * only bloats the bundle. Replaces the old hardcoded `@aws-sdk|@smithy` regex
+ * (a band-aid from the 1.1 GB nested-dist era, since fixed by the single
+ * source-based build) — no package-name whitelist to keep in sync.
  *
- * Runtime requirement: each external package must be available in
- * `node_modules/` at server startup (Bun resolves bare specifiers). Consumer
- * apps declare them in root `package.json` dependencies.
+ * Records each externalized package + the version spec of the package that
+ * imports it, so `collectFrameworkDeps` can emit them into the install
+ * manifest. This is what closes the gap for deps reached through a fragment
+ * the consumer never declares (arc-files → aws-sdk).
  */
-function serverExternalsPlugin(): import("bun").BunPlugin {
+function npmExternalsPlugin(
+  workspaceNames: ReadonlySet<string>,
+  recorded: Map<string, string | undefined>,
+): import("bun").BunPlugin {
   return {
-    name: "server-externals",
+    name: "npm-externals",
     setup(build) {
-      // @aws-sdk/* and @smithy/* — full AWS SDK v3 + low-level signing/HTTP
-      // primitives it depends on. Add more prefixes here if other heavy
-      // server-only libs appear (e.g. `@google-cloud/*`).
-      build.onResolve({ filter: /^(@aws-sdk|@smithy)\// }, (args) => ({
-        path: args.path,
-        external: true,
-      }));
+      // Bare specifiers only. An exact workspace name (`@ndt/foo`) is resolved
+      // to source earlier by workspaceSourcePlugin and never reaches here; a
+      // workspace SUBPATH (`@ndt/foo/bar`) does, and must NOT be externalized.
+      build.onResolve({ filter: /^[^./]/ }, (args) => {
+        if (isBuiltinSpec(args.path)) {
+          return { path: args.path, external: true };
+        }
+        const name = pkgNameOf(args.path);
+        // First-party workspace package (subpath import) — let Bun resolve and
+        // inline it; `workspace:*` is not installable from npm.
+        if (workspaceNames.has(name)) return null;
+        // First-party non-peer fragments inline from source/dist so
+        // SERVER_DEFINES (ONLY_SERVER…) apply and import cycles stay safe.
+        if (name.startsWith("@arcote.tech/") && !FRAMEWORK_PEER_SET.has(name)) {
+          return null;
+        }
+        const version = versionFromImporter(args.importer, name);
+        // Defensive: any `workspace:` dep is first-party — never externalize it.
+        if (version?.startsWith("workspace:")) return null;
+        if (!recorded.has(name)) recorded.set(name, version);
+        return { path: args.path, external: true };
+      });
     },
   };
 }
@@ -201,6 +277,11 @@ const SERVER_DEFINES = { ONLY_SERVER: "true", ONLY_BROWSER: "false", ONLY_CLIENT
  *  auto-emitted `chunk-<hash>.js` siblings are pulled in transitively. */
 export const SERVER_ENTRY_FILE = "_server.js";
 
+/** Sidecar listing third-party packages the server bundle left external.
+ *  Written next to the bundle so a cached rebuild can still feed the install
+ *  manifest (collectFrameworkDeps) without re-running Bun.build. */
+export const SERVER_EXTERNALS_FILE = "_externals.json";
+
 export interface WorkspacePackage {
   name: string;
   path: string;
@@ -502,6 +583,12 @@ export async function buildContextPackages(
 export interface ServerAppResult {
   readonly entryFile: string;
   readonly cached: boolean;
+  /**
+   * Third-party npm packages the bundle left external — the deploy image must
+   * install exactly these. Fed to `collectFrameworkDeps`. Empty on a cache hit
+   * (the manifest from the cached build is already on disk).
+   */
+  readonly externals: ReadonlyArray<ServerExternal>;
 }
 
 export async function buildServerApp(
@@ -548,9 +635,17 @@ export async function buildServerApp(
   });
 
   const entryFileAbs = join(serverDir, SERVER_ENTRY_FILE);
+  const externalsFileAbs = join(serverDir, SERVER_EXTERNALS_FILE);
   if (!noCache && isCacheHit(cache, unitId, inputHash, [entryFileAbs])) {
     console.log(`  ✓ cached: ${unitId}`);
-    return { entryFile: SERVER_ENTRY_FILE, cached: true };
+    // collectFrameworkDeps runs every build (uncached) and needs the external
+    // set to build the install manifest — reload it from the sidecar written
+    // by the last real build so a cache hit doesn't drop deps from the manifest.
+    return {
+      entryFile: SERVER_ENTRY_FILE,
+      cached: true,
+      externals: readServerExternals(externalsFileAbs),
+    };
   }
 
   console.log(`  building: ${unitId} (${contexts.length} server modules)`);
@@ -571,6 +666,10 @@ export async function buildServerApp(
     contexts.map((p) => `import "${p.name}";`).join("\n") + "\n",
   );
 
+  // npmExternalsPlugin records every third-party package it leaves external,
+  // plus the version spec of whatever imports it (best-effort).
+  const recorded = new Map<string, string | undefined>();
+
   let result;
   try {
     result = await Bun.build({
@@ -586,8 +685,11 @@ export async function buildServerApp(
       external,
       plugins: [
         jsxDevShimPlugin(),
-        serverExternalsPlugin(),
+        // workspaceSourcePlugin MUST precede npmExternalsPlugin: the first
+        // onResolve to return a result wins, so `@ndt/*` source is pinned
+        // before the catch-all externalizer can mark it external.
         workspaceSourcePlugin(srcByName),
+        npmExternalsPlugin(new Set(srcByName.keys()), recorded),
       ],
       define: SERVER_DEFINES,
     });
@@ -610,9 +712,28 @@ export async function buildServerApp(
     );
   }
 
+  // Third-party externals only — framework peers carry their own resolution in
+  // collectFrameworkDeps, so drop them here to avoid double-sourcing versions.
+  const externals: ServerExternal[] = [...recorded]
+    .filter(([name]) => !FRAMEWORK_PEER_SET.has(name))
+    .map(([name, version]) => ({ name, version }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  writeFileSync(externalsFileAbs, JSON.stringify(externals, null, 2) + "\n");
+
   const outputHash = sha256OfDir(serverDir);
   updateCache(cache, unitId, inputHash, { outputHash });
-  return { entryFile: SERVER_ENTRY_FILE, cached: false };
+  return { entryFile: SERVER_ENTRY_FILE, cached: false, externals };
+}
+
+/** Read the externals sidecar written by the last real server build. */
+function readServerExternals(path: string): ServerExternal[] {
+  if (!existsSync(path)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    return Array.isArray(parsed) ? (parsed as ServerExternal[]) : [];
+  } catch {
+    return [];
+  }
 }
 
 

package/src/commands/platform-dev.ts

@@ -3,12 +3,11 @@ import { resolveWorkspace } from "../platform/shared";
 
 /** `arc platform dev` — dev mode (watcher + SSE reload + no-cache headers). */
 export async function platformDev(
-  opts: { noCache?: boolean } = {},
+  opts: { noCache?: boolean; map?: 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.
-  void opts;
-  await startPlatform({ ws, devMode: true });
+  await startPlatform({ ws, devMode: true, map: opts.map });
 }

package/src/index.ts

@@ -34,8 +34,9 @@ platform
   .command("dev")
   .description("Start platform in dev mode (Bun server + Vite HMR)")
   .option("--no-cache", "Force full rebuild on startup")
-  .action((opts: { cache?: boolean }) =>
-    platformDev({ noCache: opts.cache === false }),
+  .option("--map", "Also start the Arc Context Map dev tool on a separate port")
+  .action((opts: { cache?: boolean; map?: boolean }) =>
+    platformDev({ noCache: opts.cache === false, map: opts.map }),
   );
 
 platform

package/src/platform/shared.ts

@@ -172,13 +172,8 @@ export async function buildAll(
   // into multi-hundred-MB files. The deploy image COPYs this dir wholesale;
   // loadServerContext + the access extractor import the entry, chunks ride along.
   const serverDir = join(ws.arcDir, "server");
-  const { entryFile: serverEntry } = await buildServerApp(
-    ws.rootDir,
-    serverDir,
-    ws.packages,
-    cache,
-    noCache,
-  );
+  const { entryFile: serverEntry, externals: serverExternals } =
+    await buildServerApp(ws.rootDir, serverDir, ws.packages, cache, noCache);
 
   // Phase 2 — extract access metadata (token name + hasCheck per module) in
   // an isolated subprocess that imports the combined server bundle. MUST run
@@ -223,7 +218,7 @@ export async function buildAll(
   // Phase 5 — framework peer manifest at `<arcDir>/package.json`. Used by
   // the deploy image build (single `bun install` for all peers, one copy
   // shared across module bundles).
-  collectFrameworkDeps(ws.arcDir, ws.rootDir, ws.packages);
+  collectFrameworkDeps(ws.arcDir, ws.rootDir, ws.packages, [], serverExternals);
 
   saveBuildCache(ws.arcDir, cache);
 

package/src/platform/startup.ts

@@ -35,6 +35,8 @@ export interface StartPlatformOptions {
   dbPath?: string;
   /** Dev mode: rebuild on startup, watch for changes, SSE-notify clients on rebuild. */
   devMode: boolean;
+  /** Dev-only: also start the Arc Context Map tool on a separate port. */
+  map?: boolean;
 }
 
 export async function startPlatform(
@@ -111,9 +113,16 @@ export async function startPlatform(
     ok("Commands, queries, WebSocket — all on same port");
   }
 
+  // 4a. Dev-only: optional Arc Context Map tool on a separate port, starting
+  // just above the platform's actual port (auto-increments if busy).
+  let onReload: (() => void) | undefined;
+  if (devMode && opts.map) {
+    onReload = await startMapTool(ws, actualPort + 1);
+  }
+
   // 4. Dev-only: file watcher + debounced rebuild + SSE notify.
   if (devMode) {
-    attachDevWatcher(ws, platform);
+    attachDevWatcher(ws, platform, onReload);
   }
 
   // 5. Graceful shutdown for both modes.
@@ -125,7 +134,42 @@ export async function startPlatform(
   process.on("SIGINT", cleanup);
 }
 
-function attachDevWatcher(ws: WorkspaceInfo, platform: PlatformServer): void {
+/**
+ * Start the Arc Context Map dev tool on a separate port. Loaded lazily so the
+ * ts-morph dependency stays out of the normal `platform dev` path. Returns a
+ * reload hook to wire into the file watcher, or undefined on failure.
+ */
+async function startMapTool(
+  ws: WorkspaceInfo,
+  port: number,
+): Promise<(() => void) | undefined> {
+  try {
+    const { startMapServer } = 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;
+
+    const map = await startMapServer({
+      getContext: () => getContext(),
+      scan: { globs, workspaceRoot: ws.rootDir, packageOf },
+      useCasePackages: ws.packages.map((p) => ({ name: p.name, path: p.path })),
+      port,
+    });
+    ok(`Context map → ${map.url}`);
+    return map.notifyReload;
+  } catch (e) {
+    err(`Context map failed to start: ${(e as Error).message}`);
+    return undefined;
+  }
+}
+
+function attachDevWatcher(
+  ws: WorkspaceInfo,
+  platform: PlatformServer,
+  onReload?: () => void,
+): void {
   log("Watching for changes...");
   let rebuildTimer: ReturnType<typeof setTimeout> | null = null;
   let isRebuilding = false;
@@ -140,6 +184,7 @@ function attachDevWatcher(ws: WorkspaceInfo, platform: PlatformServer): void {
         const next = await buildAll(ws);
         platform.setManifest(next);
         platform.notifyReload(next);
+        onReload?.();
         ok(
           `Rebuilt — initial + ${Object.keys(next.groups).length} group(s)`,
         );

package/src/utils/build.ts

@@ -1,5 +1,13 @@
 import { spawn } from "child_process";
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync,
+} from "fs";
 import { dirname, join } from "path";
 import type { ArcConfig, ContextInfo } from "./config";
 import { generateClientTypes } from "./config";
@@ -152,6 +160,37 @@ export interface DeclarationResult {
  * @param globalsContent  Optional ambient declarations (ONLY_SERVER etc.) —
  *                        written to a temp .d.ts and included in compilation.
  */
+/**
+ * Emituje deklaracje do katalogu TYMCZASOWEGO (siostra `outDir`), a po sukcesie
+ * scala je do `outDir`. Zapobiega TS5055 ("Cannot write file … would overwrite
+ * input file") gdy SAMO-REFERENCYJNY cykl importów pakietu (np. workspace →
+ * billing → workspace) wciąga własny `outDir/*.d.ts` do programu jako input —
+ * wtedy emisja wprost do `outDir` kolidowałaby z tym plikiem-inputem. Program ma
+ * `outDir` = temp, więc nie pisze po pliku czytanym jako wejście; świeże
+ * deklaracje przenosimy na miejsce dopiero po emisji.
+ */
+async function runDeclEmit(
+  files: string[],
+  outDir: string,
+  cwd: string,
+): Promise<DeclarationResult> {
+  const tmpOut = `${outDir}.decltmp`;
+  rmSync(tmpOut, { recursive: true, force: true });
+  try {
+    let result = await runTsgo(files, tmpOut, cwd);
+    if (result === null) {
+      result = await runTsc(files, tmpOut, cwd);
+    }
+    if (result.success) {
+      mkdirSync(outDir, { recursive: true });
+      cpSync(tmpOut, outDir, { recursive: true });
+    }
+    return result;
+  } finally {
+    rmSync(tmpOut, { recursive: true, force: true });
+  }
+}
+
 export async function buildTypeDeclarations(
   files: string[],
   outDir: string,
@@ -170,10 +209,7 @@ export async function buildTypeDeclarations(
     allFiles.push(globalsPath);
   }
 
-  let result = await runTsgo(allFiles, outDir, rootDir);
-  if (result === null) {
-    result = await runTsc(allFiles, outDir, rootDir);
-  }
+  const result = await runDeclEmit(allFiles, outDir, rootDir);
 
   // Clean up temp globals
   if (globalsPath && existsSync(globalsPath)) {
@@ -204,11 +240,7 @@ export async function buildContextDeclarations(
     ? [context.fullPath, arcTypesPath]
     : [context.fullPath];
 
-  let result = await runTsgo(files, outDir, configDir);
-  if (result === null) {
-    result = await runTsc(files, outDir, configDir);
-  }
-  return result;
+  return runDeclEmit(files, outDir, configDir);
 }
 
 // ---------------------------------------------------------------------------