@akanjs/devkit 3.0.0-alpha.8 → 3.0.0-alpha.81

package/akanApp/devHostPolicy.ts

@@ -0,0 +1,412 @@
+import path from "node:path";
+import type {
+  BuilderMessage,
+  BuildPhase,
+  ChangeBatch,
+  DevBuildStatus,
+  DevChangePlan,
+  DevChangeRole,
+} from "akanjs/server";
+import type { IncrementalBuilderStatus } from "../incrementalBuilder";
+
+const BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
+
+/**
+ * How many requests may wait for a builder that is coming back. Generous — a page load asks for
+ * several routes — but finite, so a builder that never returns cannot grow this without bound. Past
+ * it, requests are failed as they were before, which is the behaviour this limit falls back to.
+ */
+const HELD_BUILDER_REQUEST_LIMIT = 64;
+
+export const BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS = 30_000;
+
+const BUILDER_TIGHT_RSS_REPORT_LIMIT = 2;
+
+// Far enough above the ceiling that no purge would rescue it; recycle without waiting.
+const BUILDER_RSS_HARD_MULTIPLE = 1.5;
+
+// A sandbox between user turns pays for a watcher that is watching nothing change. Suspending build
+// capacity after this long returns the builder's residency until the next edit or route request.
+const DEV_IDLE_SUSPEND_MS = 300_000;
+
+// A wake that immediately suspends again would flap around whatever woke it.
+const DEV_IDLE_MIN_UPTIME_MS = 30_000;
+
+export const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+
+/\.(css|scss|sass|less|json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav|html)$/i;
+const SERVER_SUFFIXES = [".service.ts", ".document.ts"];
+
+const SHARED_SUFFIXES = [".constant.ts", ".dictionary.ts", ".signal.ts"];
+
+const RUNTIME_METADATA_BASENAMES = new Set(["dict.ts", "sig.ts", "useClient.ts", "useServer.ts"]);
+
+export const shouldRestartBackendByDevPlan = (
+  message: Extract<BuilderMessage, { type: "invalidate" }>,
+): boolean | null => {
+  if (!message.devPlan) return null;
+  if (message.devPlan.actions.includes("report-error")) return false;
+  if (message.devPlan.actions.includes("restart-builder")) return false;
+  return message.devPlan.actions.includes("restart-backend");
+};
+
+export const shouldRestartBuilderByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
+  message.devPlan?.actions.includes("restart-builder") ?? false;
+
+/**
+ * A backend that keeps dying isn't going to heal by retrying the same code; after this many
+ * consecutive attempts the host idles and the next server-side edit triggers a fresh restart.
+ */
+export const shouldAbandonBackendRecovery = (attempts: number, maxAttempts = BACKEND_RECOVERY_MAX_ATTEMPTS): boolean =>
+  attempts >= maxAttempts;
+
+/** The gateway reports backend failures with `generation: -1`; the host assigns its own counter then. */
+export const normalizeBackendReportedGeneration = (generation: number): number | undefined =>
+  generation >= 0 ? generation : undefined;
+
+export const shouldRestartDevHostByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
+  message.devPlan?.actions.includes("restart-dev-host") ?? message.kinds.includes("config");
+
+export type BackendLifecycleState = "starting" | "ready" | "restart-pending" | "stopping" | "recovering" | "stopped";
+
+export interface BackendRestartReason {
+  generation?: number;
+  files: string[];
+  roles: Extract<DevChangeRole, "server" | "shared" | "barrel" | "config">[];
+}
+
+const RESTART_ROLE_ORDER: BackendRestartReason["roles"] = ["server", "shared", "barrel", "config"];
+
+const generationValue = (generation: number | undefined): number => generation ?? -1;
+
+export const isLegacyBackendFallbackFile = (file: string, workspaceRoot: string): boolean => {
+  const abs = path.resolve(file);
+  const ext = path.extname(abs).toLowerCase();
+  if (!SOURCE_EXTS.has(ext)) return false;
+  const rel = path.relative(path.resolve(workspaceRoot), abs);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return false;
+  const parts = rel.split(path.sep).filter(Boolean);
+  const [scope] = parts;
+  if (scope !== "apps" && scope !== "libs" && scope !== "pkgs") return false;
+
+  const base = path.basename(abs);
+  return (
+    parts.includes("srvkit") ||
+    parts.includes("common") ||
+    SERVER_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||
+    SHARED_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||
+    RUNTIME_METADATA_BASENAMES.has(base) ||
+    base === "main.ts" ||
+    base === "server.ts"
+  );
+};
+
+export const shouldMarkBuildPhaseRecovered = (
+  previousByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
+  status: DevBuildStatus,
+): boolean => {
+  const previous = previousByPhase.get(status.phase);
+  return Boolean(previous && status.ok && !previous.ok && generationValue(status.generation) >= previous.generation);
+};
+
+export const createBackendBuildStatus = ({
+  generation,
+  ok,
+  files = [],
+  message,
+}: {
+  generation: number;
+  ok: boolean;
+  files?: string[];
+  message?: string;
+}): DevBuildStatus => ({
+  generation,
+  phase: "backend",
+  ok,
+  files,
+  message,
+});
+
+export const backendRestartReasonFromMessage = (
+  message: Extract<BuilderMessage, { type: "invalidate" }>,
+): BackendRestartReason => {
+  const roleSet = new Set<BackendRestartReason["roles"][number]>();
+  for (const role of message.devPlan?.roles ?? []) {
+    if (role === "server" || role === "shared" || role === "barrel" || role === "config") roleSet.add(role);
+  }
+  return {
+    generation: message.devPlan?.generation ?? message.generation,
+    files: [...new Set(message.files)].sort(),
+    roles: RESTART_ROLE_ORDER.filter((role) => roleSet.has(role)),
+  };
+};
+
+export const mergeBackendRestartReasons = (
+  current: BackendRestartReason | null,
+  next: BackendRestartReason,
+): BackendRestartReason => ({
+  generation:
+    generationValue(next.generation) >= generationValue(current?.generation) ? next.generation : current?.generation,
+  files: [...new Set([...(current?.files ?? []), ...next.files])].sort(),
+  roles: RESTART_ROLE_ORDER.filter((role) => current?.roles.includes(role) || next.roles.includes(role)),
+});
+
+export const shouldReplaceLastGoodMessage = (
+  current:
+    | Extract<BuilderMessage, { type: "pages-updated" }>
+    | Extract<BuilderMessage, { type: "css-updated" }>
+    | undefined,
+  next: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
+): boolean => !current || generationValue(next.data.generation) >= generationValue(current.data.generation);
+
+export const shouldQueueBuildStatusReplay = (backendReady: boolean, pendingReplayCount: number): boolean =>
+  !backendReady || pendingReplayCount > 0;
+
+/**
+ * Recycling the builder/backend on a generation whose build already failed is guaranteed to strand
+ * the dev server: the rebooted builder hits the same compile error and exits before builder-ready.
+ * Failing phase statuses for a generation arrive over IPC before that generation's invalidate, so
+ * the host can check them here and defer the recycle until a healthy batch lands.
+ */
+export const hasBuildFailureForGeneration = (
+  statusByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
+  generation: number | undefined,
+): boolean => {
+  if (typeof generation !== "number") return false;
+  for (const status of statusByPhase.values()) {
+    if (!status.ok && status.generation === generation) return true;
+  }
+  return false;
+};
+
+export type BuilderRssRecycleDecision = "unbounded" | "below-ceiling" | "build-failed" | "too-soon" | "recycle";
+
+/**
+ * Whether an over-ceiling builder should be replaced now.
+ *
+ * `Bun.build` never returns its native arenas, so the builder's RSS only comes back when the process
+ * exits. Recycling it is therefore the only bound available — but it costs a boot build, so the two
+ * cases where a recycle cannot help are excluded: a generation whose build already failed (the
+ * replacement would hit the same compile error), and a recycle so soon after the last one that the
+ * ceiling is evidently unreachable for this app.
+ */
+export const decideBuilderRssRecycle = ({
+  rssBytes,
+  ceilingBytes,
+  buildFailed,
+  msSinceLastRecycle,
+  minIntervalMs = BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS,
+}: {
+  rssBytes: number;
+  ceilingBytes: number | null;
+  buildFailed: boolean;
+  msSinceLastRecycle: number | null;
+  minIntervalMs?: number;
+}): BuilderRssRecycleDecision => {
+  if (!ceilingBytes) return "unbounded";
+  if (rssBytes < ceilingBytes) return "below-ceiling";
+  if (buildFailed) return "build-failed";
+  if (msSinceLastRecycle !== null && msSinceLastRecycle < minIntervalMs) return "too-soon";
+  return "recycle";
+};
+
+export type BuilderRssSettleDecision = "recycle-now" | "wait-and-recheck";
+
+/**
+ * Whether an armed recycle should wait out the allocator's purge window before committing. A builder
+ * far enough over the ceiling is not going to be rescued by a purge, so waiting there only delays a
+ * recycle that has to happen.
+ */
+export const decideBuilderRssSettle = ({
+  rssBytes,
+  ceilingBytes,
+  hardMultiple = BUILDER_RSS_HARD_MULTIPLE,
+}: {
+  rssBytes: number;
+  ceilingBytes: number;
+  hardMultiple?: number;
+}): BuilderRssSettleDecision => (rssBytes >= ceilingBytes * hardMultiple ? "recycle-now" : "wait-and-recheck");
+
+export type IdleSuspendDecision =
+  | "disabled"
+  | "already-suspended"
+  | "builder-not-ready"
+  | "backend-not-ready"
+  | "build-failed"
+  | "restart-pending"
+  | "too-soon"
+  | "suspend";
+
+/**
+ * Whether the dev host may drop its build capacity now. Every "no" here is a case where suspending
+ * would either lose work or produce a wake that immediately re-suspends:
+ *
+ * - a red build means the developer is mid-fix and about to save again, and a wake would boot straight
+ *   back into the same error via the degraded-boot path
+ * - a pending restart/recovery already has its own plan for the builder
+ * - `too-soon` keeps a wake from flapping around whatever triggered it
+ */
+export const decideIdleSuspend = ({
+  enabled,
+  suspended,
+  builderReady,
+  backendReady,
+  buildFailed,
+  restartPending,
+  msSinceWake,
+  minUptimeMs = DEV_IDLE_MIN_UPTIME_MS,
+}: {
+  enabled: boolean;
+  suspended: boolean;
+  builderReady: boolean;
+  backendReady: boolean;
+  buildFailed: boolean;
+  restartPending: boolean;
+  msSinceWake: number | null;
+  minUptimeMs?: number;
+}): IdleSuspendDecision => {
+  if (!enabled) return "disabled";
+  if (suspended) return "already-suspended";
+  if (!builderReady) return "builder-not-ready";
+  if (!backendReady) return "backend-not-ready";
+  if (buildFailed) return "build-failed";
+  if (restartPending) return "restart-pending";
+  if (msSinceWake !== null && msSinceWake < minUptimeMs) return "too-soon";
+  return "suspend";
+};
+
+/** `undefined` env means the default is on; any non-positive value turns idle suspend off. */
+export const resolveIdleSuspendMs = (raw: string | undefined): number | null => {
+  if (raw === undefined || raw === "") return DEV_IDLE_SUSPEND_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return null;
+  return Math.round(parsed);
+};
+
+/** Any red phase blocks a suspend, unlike the rss recycle which only cares about one generation. */
+export const hasAnyBuildFailure = (statusByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>): boolean =>
+  [...statusByPhase.values()].some((status) => !status.ok);
+
+/**
+ * A config change while suspended cannot be applied by restarting the builder alone — the dev host
+ * itself has to re-read the config, which is the same path an ordinary config save takes.
+ */
+export const shouldRefreshConfigOnIdleWake = (batch: ChangeBatch | null): boolean =>
+  !!batch && batch.kinds.has("config");
+
+/**
+ * Whether a request that arrived while the builder was away should wait for the one coming back.
+ *
+ * A recycle or a crash-restart is a gap, not a failure — the request that lands in it is the page a
+ * developer is waiting on. A stopped builder is a different thing: nothing is bringing it back, so
+ * waiting would only delay the error.
+ *
+ * `recycling` is in here for the same reason as `restarting`, and was the hole this decision shipped
+ * with: a draining builder is still alive, so the request reached it and came back refused while the
+ * host still thought there was nothing to wait for.
+ */
+const RETURNING_BUILDER_STATUSES = new Set<IncrementalBuilderStatus>(["starting", "recycling", "restarting"]);
+export const shouldHoldForReturningBuilder = ({
+  status,
+  heldCount,
+  limit = HELD_BUILDER_REQUEST_LIMIT,
+}: {
+  status: IncrementalBuilderStatus;
+  heldCount: number;
+  limit?: number;
+}): boolean => RETURNING_BUILDER_STATUSES.has(status) && heldCount < limit;
+
+/**
+ * Whether a builder that is over the ceiling again this soon after being replaced is worth saying so
+ * about, once. Not a reason to stop enforcing the ceiling: the minimum interval already bounds what
+ * this costs at one recycle per interval, and dropping the bound is how a container gets OOM-killed.
+ *
+ * This used to disable the ceiling for the session, on a count that a single page load reaches — two
+ * route builds, two reports, both inside the interval. That is normal work on any app whose builds sit
+ * above the ceiling, which is the same app the ceiling was derived for.
+ */
+export const shouldWarnBuilderRssCeilingTight = (
+  reportsSinceRecycle: number,
+  limit = BUILDER_TIGHT_RSS_REPORT_LIMIT,
+): boolean => reportsSinceRecycle >= limit;
+
+/**
+ * Whether recycling can ever bring this builder under the ceiling.
+ *
+ * Measured on a replacement the moment it is ready, before it has built anything on demand: that is
+ * the floor every future replacement lands on, so a floor already over the ceiling is the one case
+ * where the recycle loop is pure cost. It is also the case the escape hatch was always described as
+ * being for — the previous rule inferred it from report timing and caught ordinary work instead.
+ */
+export const isRssCeilingUnreachable = (freshRssBytes: number | null, ceilingBytes: number | null): boolean =>
+  freshRssBytes !== null && ceilingBytes !== null && freshRssBytes >= ceilingBytes;
+
+/**
+ * Whether a recycled builder's re-announced boot artifact actually differs from what the backend
+ * already has. Both payload identities are content hashes — `pages-[hash].js` and
+ * `<name>-[hash].css` — so an unchanged recycle produces identical ones and needs no reload. Only a
+ * save that raced the recycle moves them, and that is the case worth pushing.
+ */
+export const shouldRelayRecycledFrontendState = (
+  current:
+    | Extract<BuilderMessage, { type: "pages-updated" }>
+    | Extract<BuilderMessage, { type: "css-updated" }>
+    | undefined,
+  next: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
+): boolean => {
+  if (!current || current.type !== next.type) return true;
+  if (current.type === "pages-updated" && next.type === "pages-updated")
+    return current.data.bundlePath !== next.data.bundlePath;
+  if (current.type === "css-updated" && next.type === "css-updated")
+    return JSON.stringify(current.data.cssAssets) !== JSON.stringify(next.data.cssAssets);
+  return true;
+};
+
+const mergeDevPlans = (current?: DevChangePlan, next?: DevChangePlan): DevChangePlan | undefined => {
+  if (!current) return next;
+  if (!next) return current;
+  const reasonByFile: Record<string, string[]> = { ...current.reasonByFile };
+  for (const [file, reasons] of Object.entries(next.reasonByFile)) {
+    reasonByFile[file] = [...new Set([...(reasonByFile[file] ?? []), ...reasons])].sort();
+  }
+  return {
+    generation: Math.max(current.generation, next.generation),
+    files: [...new Set([...current.files, ...next.files])].sort(),
+    generatedFiles: [...new Set([...current.generatedFiles, ...next.generatedFiles])].sort(),
+    roles: [...new Set([...current.roles, ...next.roles])].sort(),
+    actions: [...new Set([...current.actions, ...next.actions])].sort(),
+    reasonByFile,
+  };
+};
+
+/** A deferred recycle accumulates every batch it skipped so the eventual restart covers them all. */
+export const mergeInvalidateMessages = (
+  current: Extract<BuilderMessage, { type: "invalidate" }>,
+  next: Extract<BuilderMessage, { type: "invalidate" }>,
+): Extract<BuilderMessage, { type: "invalidate" }> => {
+  const generation = Math.max(generationValue(current.generation), generationValue(next.generation));
+  return {
+    type: "invalidate",
+    kinds: [...new Set([...current.kinds, ...next.kinds])].sort(),
+    files: [...new Set([...current.files, ...next.files])].sort(),
+    generation: generation >= 0 ? generation : undefined,
+    devPlan: mergeDevPlans(current.devPlan, next.devPlan),
+  };
+};
+
+export const buildStatusReplaySequence = (
+  pendingReplay: readonly DevBuildStatus[],
+  latestByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
+): DevBuildStatus[] => [...pendingReplay, ...latestByPhase.values()];
+
+/** `(mtimeMs, size)` per file — what a save moves, and what a rebuild of identical content does not. */
+export type SourceFingerprints = ReadonlyMap<string, string>;
+
+/**
+ * Which of the files in `before` are no longer stamped the way they were.
+ *
+ * Only files present in `before` are compared. The question this answers is which *running* code went
+ * stale while nothing was watching, and a file that did not exist then is not running anywhere.
+ */
+export const filesChangedSince = (before: SourceFingerprints, after: SourceFingerprints): string[] =>
+  [...before].filter(([file, stamp]) => after.get(file) !== stamp).map(([file]) => file);

package/akanApp/index.ts

@@ -1 +1,3 @@
 export * from "./akanApp.host";
+export * from "./BackendImportGraph";
+export * from "./devHostPolicy";

package/akanConfig/akanConfig.test.ts

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { AppExecutor, WorkspaceExecutor } from "../executors";
 import type { PackageJson } from "../types";
 import { AkanAppConfig, AkanLibConfig, deriveDefaultAppId } from "./akanConfig";
 import type { DeepPartial, LibConfigResult } from "./types";
@@ -19,7 +20,6 @@ const packageJson: PackageJson = {
     react: "19.0.0",
     "react-dom": "19.0.0",
     "react-server-dom-webpack": "19.0.0",
-    sharp: "1.0.0",
     "@external/runtime": "2.0.0",
   },
 };
@@ -64,7 +64,8 @@ describe("AkanAppConfig", () => {
     expect(config.barrelImports).toEqual(
       expect.arrayContaining(["@apps/portal/ui", "@libs/shared/server", "akanjs/common", "akanjs/server"]),
     );
-    expect(config.docker.content).toContain("ENV AKAN_PUBLIC_APP_NAME=portal");
+    expect(config.dockerfile).toContain("ENV AKAN_PUBLIC_APP_NAME=portal");
+    expect(config.dockerfile).toContain("ENV AKAN_LOG_TO_FILE=0");
     expect(process.env.AKAN_PUBLIC_DEFAULT_LOCALE).toBe("en");
   });
 
@@ -128,9 +129,67 @@ describe("AkanAppConfig", () => {
     });
     expect(config.publicEnv).toEqual(["AKAN_PUBLIC_FEATURE"]);
     expect(config.optimizeImports).toContain("custom-icons");
-    expect(config.docker.content).toContain('CMD ["bun","server.js"]');
-    expect(config.docker.content).toContain("FROM oven/bun:amd64 AS amd64");
-    expect(config.docker.content).toContain('RUN if [ "$TARGETARCH" = "arm64"');
+    expect(config.dockerfile).toContain('CMD ["bun","server.js"]');
+    expect(config.dockerfile).toContain("FROM oven/bun:amd64 AS amd64");
+    expect(config.dockerfile).toContain('RUN if [ "$TARGETARCH" = "arm64"');
+  });
+
+  test("defaults both web surfaces on and keeps the image free of web env overrides", () => {
+    const config = new AkanAppConfig(app, [], packageJson, {}, baseDevEnv);
+
+    expect(config.web).toEqual({ ssr: true, csr: true });
+    expect(config.dockerfile).not.toContain("AKAN_SSR");
+    expect(config.dockerfile).not.toContain("AKAN_CSR");
+  });
+
+  test("bakes the disabled surface into the image env so the default matches what was built", () => {
+    const ssrOnly = new AkanAppConfig(app, [], packageJson, { web: { csr: false } }, baseDevEnv);
+    expect(ssrOnly.web).toEqual({ ssr: true, csr: false });
+    expect(ssrOnly.dockerfile).toContain("ENV AKAN_CSR=false");
+    expect(ssrOnly.dockerfile).not.toContain("ENV AKAN_SSR=false");
+
+    const apiOnly = new AkanAppConfig(app, [], packageJson, { web: false }, baseDevEnv);
+    expect(apiOnly.web).toEqual({ ssr: false, csr: false });
+    expect(apiOnly.dockerfile).toContain("ENV AKAN_SSR=false");
+    expect(apiOnly.dockerfile).toContain("ENV AKAN_CSR=false");
+
+    expect(new AkanAppConfig(app, [], packageJson, { web: true }, baseDevEnv).web).toEqual({ ssr: true, csr: true });
+  });
+
+  test("refuses a csr-less build that ships a mobile app", () => {
+    expect(
+      () => new AkanAppConfig(app, [], packageJson, { web: { csr: false }, mobile: { appName: "portal" } }, baseDevEnv),
+    ).toThrow("the Capacitor build ships that bundle");
+  });
+
+  test("installs only ca-certificates and tzdata in the default image", () => {
+    const config = new AkanAppConfig(app, [], packageJson, {}, baseDevEnv);
+
+    expect(config.dockerfile).toContain(
+      "RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends ca-certificates tzdata && rm -rf /var/lib/apt/lists/*",
+    );
+    // The Chromium/ffmpeg toolchain moved to per-app `preRuns`; keeping it here paid for it in every image.
+    for (const dropped of ["libnss3", "ffmpeg", "build-essential", "redis", "xdg-utils"])
+      expect(config.dockerfile).not.toContain(dropped);
+  });
+
+  test("keeps a declared Dockerfile string verbatim", () => {
+    const dockerfile = 'FROM oven/bun:1-slim\nCOPY . .\nCMD ["bun","main.js"]';
+    const config = new AkanAppConfig(app, [], packageJson, { docker: dockerfile }, baseDevEnv);
+
+    expect(config.docker).toBe(dockerfile);
+    expect(config.dockerfile).toBe(dockerfile);
+  });
+
+  test("resolves the image parts, defaulting the base image and the command", () => {
+    const config = new AkanAppConfig(app, [], packageJson, { docker: { preRuns: ["echo hi"] } }, baseDevEnv);
+
+    expect(config.docker).toEqual({
+      image: "oven/bun:1-slim",
+      preRuns: ["echo hi"],
+      postRuns: [],
+      command: ["bun", "main.js"],
+    });
   });
 
   test("creates production package json and reports missing external versions", () => {
@@ -144,8 +203,6 @@ describe("AkanAppConfig", () => {
         react: "19.0.0",
         "react-dom": "19.0.0",
         "react-server-dom-webpack": "19.0.0",
-        croner: akanPackageJson.peerDependencies?.croner,
-        sharp: "1.0.0",
         "@external/runtime": "2.0.0",
       },
     });
@@ -184,8 +241,6 @@ describe("AkanAppConfig", () => {
       react: runtimeDependencies.react,
       "react-dom": runtimeDependencies["react-dom"],
       "react-server-dom-webpack": runtimeDependencies["react-server-dom-webpack"],
-      croner: runtimeDependencies.croner,
-      sharp: runtimeDependencies.sharp,
     });
   });
 
@@ -198,9 +253,6 @@ describe("AkanAppConfig", () => {
     const multipleConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "multiple" }, baseDevEnv);
     const clusterConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "cluster" }, baseDevEnv);
 
-    expect(singleConfig.getProductionPackageJson().dependencies).toMatchObject({
-      croner: runtimeDependencies.croner,
-    });
     expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("ioredis");
     expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("bullmq");
     expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("@libsql/client");
@@ -210,7 +262,6 @@ describe("AkanAppConfig", () => {
     expect(multipleConfig.getProductionPackageJson().dependencies).toMatchObject({
       "@libsql/client": runtimeDependencies["@libsql/client"],
       bullmq: runtimeDependencies.bullmq,
-      croner: runtimeDependencies.croner,
       ioredis: runtimeDependencies.ioredis,
       protobufjs: runtimeDependencies.protobufjs,
     });
@@ -218,7 +269,6 @@ describe("AkanAppConfig", () => {
 
     expect(clusterConfig.getProductionPackageJson().dependencies).toMatchObject({
       bullmq: runtimeDependencies.bullmq,
-      croner: runtimeDependencies.croner,
       ioredis: runtimeDependencies.ioredis,
       postgres: runtimeDependencies.postgres,
       protobufjs: runtimeDependencies.protobufjs,
@@ -392,6 +442,115 @@ describe("deriveDefaultAppId", () => {
   });
 });
 
+describe("AkanAppConfig lib externalLibs", () => {
+  test("merges lib-declared external libs into the app's own, deduped", () => {
+    const libAwarePackageJson: PackageJson = {
+      ...packageJson,
+      dependencies: { ...packageJson.dependencies, puppeteer: "24.0.0" },
+    };
+    const config = new AkanAppConfig(
+      app,
+      ["shared"],
+      libAwarePackageJson,
+      { externalLibs: ["@external/runtime"] },
+      baseDevEnv,
+      [],
+      { externalLibs: ["@external/runtime", "puppeteer"], docker: { preRuns: [], postRuns: [] } },
+    );
+
+    expect(config.externalLibs).toEqual(["@external/runtime", "puppeteer"]);
+    expect(config.getProductionPackageJson().dependencies).toMatchObject({
+      "@external/runtime": "2.0.0",
+      puppeteer: "24.0.0",
+    });
+  });
+
+  test("reads them off every workspace lib config on load", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-config-libext-"));
+    try {
+      fs.mkdirSync(path.join(root, "apps/extapp"), { recursive: true });
+      fs.mkdirSync(path.join(root, "libs/extlib"), { recursive: true });
+      fs.writeFileSync(path.join(root, "apps/extapp/akan.config.ts"), "export default { externalLibs: ['shiki'] };\n");
+      fs.writeFileSync(
+        path.join(root, "libs/extlib/akan.config.ts"),
+        "export default { externalLibs: ['puppeteer'] };\n",
+      );
+      fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "extrepo", version: "1.0.0" }));
+      fs.writeFileSync(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=extrepo\nAKAN_PUBLIC_SERVE_DOMAIN=ext.test\n");
+
+      const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "extrepo" });
+      const config = await AppExecutor.from(workspace, "extapp").getConfig();
+
+      expect(config.externalLibs).toEqual(["shiki", "puppeteer"]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("AkanAppConfig lib docker runs", () => {
+  const libDocker = (preRuns: string[], postRuns: string[] = []) => ({
+    externalLibs: [],
+    docker: { preRuns, postRuns },
+  });
+
+  test("runs lib steps before the app's own, deduped", () => {
+    const config = new AkanAppConfig(
+      app,
+      ["shared"],
+      packageJson,
+      { docker: { preRuns: ["apt-get install -y ffmpeg", "echo app"], postRuns: ["echo app-post"] } },
+      baseDevEnv,
+      [],
+      libDocker(["apt-get install -y ffmpeg", "echo lib"], ["echo lib-post"]),
+    );
+
+    expect(config.docker).toMatchObject({
+      preRuns: ["apt-get install -y ffmpeg", "echo lib", "echo app"],
+      postRuns: ["echo lib-post", "echo app-post"],
+    });
+    expect(config.dockerfile).toContain("RUN echo lib\nRUN echo app\n");
+    expect(config.dockerfile.match(/RUN apt-get install -y ffmpeg/g)).toHaveLength(1);
+  });
+
+  test("drops them when the app hands over a whole Dockerfile", () => {
+    const config = new AkanAppConfig(
+      app,
+      ["shared"],
+      packageJson,
+      { docker: "FROM scratch" },
+      baseDevEnv,
+      [],
+      libDocker(["echo lib"]),
+    );
+
+    expect(config.dockerfile).toBe("FROM scratch");
+  });
+
+  test("reads them off every workspace lib config on load", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-config-libdocker-"));
+    try {
+      fs.mkdirSync(path.join(root, "apps/extapp"), { recursive: true });
+      fs.mkdirSync(path.join(root, "libs/extlib"), { recursive: true });
+      fs.writeFileSync(path.join(root, "apps/extapp/akan.config.ts"), "export default {};\n");
+      fs.writeFileSync(
+        path.join(root, "libs/extlib/akan.config.ts"),
+        "export default { docker: { preRuns: ['echo from-lib'], postRuns: [{ arm64: 'echo arm-only' }] } };\n",
+      );
+      fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "extrepo", version: "1.0.0" }));
+      fs.writeFileSync(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=extrepo\nAKAN_PUBLIC_SERVE_DOMAIN=ext.test\n");
+
+      const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "extrepo" });
+      const config = await AppExecutor.from(workspace, "extapp").getConfig();
+
+      expect(config.dockerfile).toContain("RUN echo from-lib");
+      expect(config.dockerfile).toContain('RUN if [ "$TARGETARCH" = "arm64"');
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("AkanLibConfig", () => {
   test("uses empty external libs by default and preserves explicit libs", () => {
     const lib = { name: "shared" } as never;
@@ -402,6 +561,15 @@ describe("AkanLibConfig", () => {
     };
     expect(new AkanLibConfig(lib, config).externalLibs).toEqual(["firebase-admin"]);
   });
+
+  test("defaults docker runs to empty lists and preserves declared ones", () => {
+    const lib = { name: "shared" } as never;
+    expect(new AkanLibConfig(lib, {}).docker).toEqual({ preRuns: [], postRuns: [] });
+    expect(new AkanLibConfig(lib, { docker: { preRuns: ["echo lib"] } }).docker).toEqual({
+      preRuns: ["echo lib"],
+      postRuns: [],
+    });
+  });
 });
 
 describe("AkanAppConfig.importConfigModule", () => {