@podosoft/podokit 1.2.0 → 1.4.0

package/dist/templates/modules/sse/files/apps/api/src/events/events.module.spec.ts

@@ -4,7 +4,12 @@ import { MemoryEventBus } from "@podosoft/podokit-runtime";
 import { Elysia } from "elysia";
 import type { RequestIdentity } from "../core/services";
 import { ReadinessService } from "../health/readiness.service";
-import { eventsRoutes, requestEventIdentity, type EventIdentity } from "./events.module";
+import {
+  eventsRoutes,
+  maxStreamsPerUser,
+  requestEventIdentity,
+  type EventIdentity,
+} from "./events.module";
 import { EventsService } from "./events.service";
 
 /** Maps the `x-user`, `x-admin`, `x-roles`, and `x-org` test headers to the request identity. */
@@ -201,3 +206,45 @@ describe("default event identity", () => {
     expect(await identity.subscriber(new Request("http://localhost/events/stream"))).toBeUndefined();
   });
 });
+
+describe("stream limit configuration", () => {
+  it("reads SSE_MAX_STREAMS_PER_USER and defaults to eight", () => {
+    expect(maxStreamsPerUser({})).toBe(8);
+    expect(maxStreamsPerUser({ SSE_MAX_STREAMS_PER_USER: "3" })).toBe(3);
+    for (const value of ["0", "-1", "1.5", "many"]) {
+      expect(() => maxStreamsPerUser({ SSE_MAX_STREAMS_PER_USER: value })).toThrow(
+        "SSE_MAX_STREAMS_PER_USER must be a positive integer",
+      );
+    }
+  });
+
+  it("answers 429 EVENTS_STREAM_LIMIT over HTTP", async () => {
+    const events = new EventsService(new MemoryEventBus(), new ReadinessService(), {
+      maxStreamsPerUser: 1,
+    });
+    await events.connect();
+    const controllers: AbortController[] = [];
+    opened.push({ events, controllers });
+    const app = new Elysia()
+      .onError(({ error, set }) => {
+        if (!(error instanceof AppException)) return undefined;
+        set.status = error.statusCode;
+        return { code: error.code };
+      })
+      .use(eventsRoutes(events, headerIdentity));
+    const send = (): Promise<Response> => {
+      const controller = new AbortController();
+      controllers.push(controller);
+      return app.handle(
+        new Request("http://localhost/events/stream", {
+          headers: { "x-user": "u1" },
+          signal: controller.signal,
+        }),
+      );
+    };
+    expect((await send()).status).toBe(200);
+    const refused = await send();
+    expect(refused.status).toBe(429);
+    expect(await refused.json()).toEqual({ code: "EVENTS_STREAM_LIMIT" });
+  });
+});

package/dist/templates/modules/sse/files/apps/api/src/events/events.module.ts

@@ -22,6 +22,15 @@ import { EventsService } from "./events.service";
 
 export const SSE_EVENTS = Symbol("sse-events") as ServiceKey<EventsService>;
 
+/** `SSE_MAX_STREAMS_PER_USER`: open streams one user may hold on each API replica. */
+export function maxStreamsPerUser(env: Record<string, string | undefined> = process.env): number {
+  const value = Number(env.SSE_MAX_STREAMS_PER_USER ?? 8);
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error("SSE_MAX_STREAMS_PER_USER must be a positive integer");
+  }
+  return value;
+}
+
 /** Resolves who opens a stream. Register one in app.extensions.ts to replace the default. */
 export interface EventIdentity {
   subscriber(request: Request): Promise<EventSubscriber | undefined>;
@@ -84,7 +93,9 @@ export function eventsRoutes(
           "Signed-in users only. `topics` is a comma-separated list; without it the stream " +
           "carries every topic that has no authorizer. Each data event is a default " +
           "`message` whose data is `{ topic, data }`. A `resync` event means events were " +
-          "dropped and the client should reload its state.",
+          "dropped and the client should reload its state. A user may hold " +
+          "`SSE_MAX_STREAMS_PER_USER` streams (default 8) on each API replica; another " +
+          "answers 429 `EVENTS_STREAM_LIMIT`.",
       },
     })
     .post("/events", async ({ request, body, set }) => {
@@ -132,7 +143,9 @@ const eventsPlugin: AppPlugin = ({ services }) =>
 export const eventsModule: PodokitModule = {
   name: "sse",
   configure: (_env, services): void => {
-    const events = new EventsService(services.resolve(EVENTS), services.resolve(READINESS));
+    const events = new EventsService(services.resolve(EVENTS), services.resolve(READINESS), {
+      maxStreamsPerUser: maxStreamsPerUser(),
+    });
     services.register(SSE_EVENTS, events, () => events.close());
     services.onStart(() => events.connect());
   },

package/dist/templates/modules/sse/files/apps/api/src/events/events.service.spec.ts

@@ -38,6 +38,22 @@ function user(userId: string, roles: string[] = [], organizationId?: string): Ev
   return { userId, roles, ...(organizationId ? { organizationId } : {}) };
 }
 
+/** A memory bus that can report a transport interruption, as the Redis bus does after reconnecting. */
+class InterruptibleBus extends MemoryEventBus {
+  readonly listeners = new Set<() => void>();
+
+  onInterruption(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  interrupt(): void {
+    for (const listener of this.listeners) listener();
+  }
+}
+
 const services: EventsService[] = [];
 
 async function service(
@@ -268,6 +284,23 @@ describe("per-connection safety", () => {
     expect(decoded(await stream.next())).toEqual({ topic: "t", data: 6 });
   });
 
+  it("tells every open stream to resync after a transport interruption", async () => {
+    const bus = new InterruptibleBus();
+    const events = await service({}, bus);
+    const topical = await open(events, user("a"), ["t"]);
+    const everything = await open(events, user("b"));
+    await events.publishAsync({ topic: "t", data: 1 });
+
+    bus.interrupt();
+    expect(await topical.next()).toEqual({ kind: "resync" });
+    expect(await everything.next()).toEqual({ kind: "resync" });
+    await events.publishAsync({ topic: "t", data: 2 });
+    expect(decoded(await topical.next())).toEqual({ topic: "t", data: 2 });
+
+    await events.close();
+    expect(bus.listeners.size).toBe(0);
+  });
+
   it("reuses one heartbeat timer per connection and releases it on disconnect", async () => {
     const scheduler = fakeScheduler();
     const events = await service({ scheduler });
@@ -353,6 +386,41 @@ describe("per-connection safety", () => {
   });
 });
 
+describe("per-user stream limit", () => {
+  it("refuses a user's stream beyond the limit on this replica and frees slots on close", async () => {
+    const events = await service({ maxStreamsPerUser: 2 });
+    const first = await open(events, user("a"));
+    await open(events, user("a"));
+
+    const refused = await open(events, user("a")).catch((error: unknown) => error);
+    expect(refused).toBeInstanceOf(AppException);
+    expect((refused as AppException).code).toBe("EVENTS_STREAM_LIMIT");
+    expect((refused as AppException).statusCode).toBe(429);
+    expect(events.streamCount).toBe(2);
+
+    // Other users keep their own allowance.
+    await open(events, user("b"));
+    first.close();
+    await open(events, user("a"));
+    expect(events.streamCount).toBe(3);
+  });
+
+  it("counts only live streams after a client disconnects", async () => {
+    const events = await service({ maxStreamsPerUser: 1 });
+    const controller = new AbortController();
+    await events.open(user("a"), undefined, controller.signal);
+    controller.abort();
+    await open(events, user("a"));
+    expect(events.streamCount).toBe(1);
+  });
+
+  it("allows eight streams per user by default", async () => {
+    const events = await service();
+    for (let index = 0; index < 8; index += 1) await open(events, user("a"));
+    await expect(open(events, user("a"))).rejects.toThrow("Too many open event streams");
+  });
+});
+
 describe("SSE wire format", () => {
   it("encodes data events as default messages and control frames separately", () => {
     expect(encodeFrame({ kind: "event", id: "7", data: '{"topic":"t","data":1}' })).toBe(

package/dist/templates/modules/sse/files/apps/api/src/events/events.service.ts

@@ -27,6 +27,8 @@ export interface EventsServiceOptions {
   retryMs?: number;
   /** Streams end after this long so clients reconnect with a fresh identity. */
   maxConnectionMs?: number;
+  /** Open streams one user may hold on this replica. */
+  maxStreamsPerUser?: number;
   scheduler?: Scheduler;
   now?: () => number;
 }
@@ -35,11 +37,14 @@ export class EventsService {
   readonly topics = new TopicAuthorizers();
   readonly retryMs: number;
   private readonly streamOptions: EventStreamOptions;
+  private readonly maxStreamsPerUser: number;
   private readonly streams = new Set<EventStream>();
+  private readonly byUser = new Map<string, Set<EventStream>>();
   private readonly byTopic = new Map<string, Set<EventStream>>();
   private readonly everyTopic = new Set<EventStream>();
   private unregisterReadiness?: () => void;
   private unsubscribe?: Unsubscribe;
+  private stopResync?: () => void;
 
   constructor(
     private readonly transport: EventBus,
@@ -47,6 +52,7 @@ export class EventsService {
     options: EventsServiceOptions = {},
   ) {
     this.retryMs = options.retryMs ?? 3_000;
+    this.maxStreamsPerUser = options.maxStreamsPerUser ?? 8;
     this.streamOptions = {
       queueLimit: options.queueLimit ?? 256,
       heartbeatMs: options.heartbeatMs ?? 5_000,
@@ -69,6 +75,11 @@ export class EventsService {
       }
       this.deliver(envelope);
     });
+    // Events published while the transport was down never arrive, so open
+    // streams are told to reload once it is back.
+    this.stopResync = this.transport.onInterruption?.(() => {
+      for (const stream of this.streams) stream.resync();
+    });
     this.unregisterReadiness = this.readiness.register("events", () => this.transport.ready());
   }
 
@@ -93,7 +104,9 @@ export class EventsService {
 
   /**
    * Opens a stream for `subscriber`. Without `topics` the stream receives every
-   * topic that has no authorizer; guarded topics must be requested by name.
+   * topic that has no authorizer; guarded topics must be requested by name. A
+   * user beyond the per-user limit is refused rather than closing an older
+   * stream, which would make that client reconnect and refuse the next one.
    */
   async open(
     subscriber: EventSubscriber,
@@ -109,6 +122,10 @@ export class EventsService {
         );
       }
     }
+    // No await between this check and attach(), so concurrent opens cannot pass it together.
+    if ((this.byUser.get(subscriber.userId)?.size ?? 0) >= this.maxStreamsPerUser) {
+      throw new AppException("EVENTS_STREAM_LIMIT", "Too many open event streams", 429);
+    }
     const stream = new EventStream(
       subscriber,
       topics ? new Set(topics) : undefined,
@@ -122,6 +139,7 @@ export class EventsService {
 
   async close(): Promise<void> {
     this.unregisterReadiness?.();
+    this.stopResync?.();
     await this.unsubscribe?.();
     for (const stream of [...this.streams]) stream.close();
   }
@@ -142,6 +160,9 @@ export class EventsService {
 
   private attach(stream: EventStream): void {
     this.streams.add(stream);
+    const held = this.byUser.get(stream.subscriber.userId) ?? new Set<EventStream>();
+    held.add(stream);
+    this.byUser.set(stream.subscriber.userId, held);
     if (!stream.topics) {
       this.everyTopic.add(stream);
       return;
@@ -155,6 +176,9 @@ export class EventsService {
 
   private detach(stream: EventStream): void {
     this.streams.delete(stream);
+    const held = this.byUser.get(stream.subscriber.userId);
+    held?.delete(stream);
+    if (held?.size === 0) this.byUser.delete(stream.subscriber.userId);
     if (!stream.topics) {
       this.everyTopic.delete(stream);
       return;

package/dist/templates/modules/sse/files/tests/api/events.api.spec.ts

@@ -119,6 +119,52 @@ test("sse: streams require a session and a valid topic list", async ({ playwrigh
   }
 });
 
+function openStream(cookie: string, controller: AbortController): Promise<Response> {
+  return fetch(`${base}/api/events/stream?topics=${uniqueTopic()}`, {
+    headers: { ...origin, cookie },
+    signal: controller.signal,
+  });
+}
+
+test("sse: a user's open streams are capped per replica", async ({ playwright }) => {
+  const member = await newContext(playwright);
+  const other = await newContext(playwright);
+  const controllers: AbortController[] = [];
+  try {
+    test.skip(!(await signUp(member)), "requires the auth module");
+    expect(await signUp(other)).toBeDefined();
+    const cookie = await cookieHeader(member);
+    // The limit is SSE_MAX_STREAMS_PER_USER on the server, so open until refused.
+    let refused: Response | undefined;
+    for (let attempt = 0; attempt < 64 && !refused; attempt += 1) {
+      const controller = new AbortController();
+      const response = await openStream(cookie, controller);
+      if (response.status === 200) controllers.push(controller);
+      else refused = response;
+    }
+    expect(controllers.length).toBeGreaterThan(0);
+    expect(refused?.status).toBe(429);
+    expect((await refused?.json()).error.code).toBe("EVENTS_STREAM_LIMIT");
+
+    // Another user is unaffected, and closing a stream frees its slot.
+    const otherController = new AbortController();
+    controllers.push(otherController);
+    expect((await openStream(await cookieHeader(other), otherController)).status).toBe(200);
+    controllers.shift()?.abort();
+    await expect.poll(async () => {
+      const controller = new AbortController();
+      const response = await openStream(cookie, controller);
+      if (response.status === 200) controllers.push(controller);
+      else controller.abort();
+      return response.status;
+    }, { timeout: 8_000 }).toBe(200);
+  } finally {
+    for (const controller of controllers) controller.abort();
+    await member.dispose();
+    await other.dispose();
+  }
+});
+
 test("sse: only administrators may publish", async ({ playwright }) => {
   const member = await newContext(playwright);
   try {

package/dist/templates/modules/sse/module.manifest.json

@@ -17,7 +17,9 @@
   "targetApp": "api",
   "env": [
     "# Maximum encoded Server-Sent Event payload",
-    "SSE_MAX_EVENT_BYTES=65536"
+    "SSE_MAX_EVENT_BYTES=65536",
+    "# Open event streams per user on each API replica",
+    "SSE_MAX_STREAMS_PER_USER=8"
   ],
   "inject": [
     { "file": "apps/api/src/app.ts", "marker": "// podokit:end:imports", "text": "import { eventsModule } from \"./events/events.module\";" },

package/dist/templates/todo/AGENTS.md

@@ -42,6 +42,14 @@ Merge added module settings from `.env.example` into an existing `.env`.
 
 - **Ports: web = 5001, api = 5002.** The web app reaches the API only through its
   SvelteKit server proxy (`/api/*`), never with a direct browser `fetch`.
+- The proxy (`apps/web/src/lib/server/backend-proxy.ts`) is managed and passes only
+  allowlisted headers. List extra request and response header names in the
+  app-owned `apps/web/src/lib/server/proxy-headers.ts`
+  (`APP_FORWARDED_REQUEST_HEADERS`, `APP_RELAYED_RESPONSE_HEADERS`); never edit the
+  managed lists. Cap a route's request body in the app-owned
+  `apps/web/src/lib/server/body-limits.ts` (`APP_BODY_LIMITS`, 413
+  `PAYLOAD_TOO_LARGE`). `BODY_SIZE_LIMIT` is the ceiling for every web route, so
+  uploads larger than it must use a direct API path (`apiPaths`) instead.
 - Build: `{{rootRun}} build`  ·  Type-check/lint: `{{rootRun}} lint`  ·  Unit tests: `{{rootRun}} test`
 - Per workspace: `{{apiRun}} build` / `{{webRun}} build`.
 - Application migrations (PostgreSQL or SQLite): `{{apiRun}} migration:run`.
@@ -92,7 +100,7 @@ Useful commands:
 - `podo remove <module>` — un-apply a module (inverse of add; refuses if another module needs it, keeps files you edited).
 - `podo status` / `podo diff` — see your local edits vs. what PodoKit generated.
 - `podo update` — pull in template/module improvements (3-way merges your edits; never touches owned files).
-- `podo deploy` — plan, apply, verify, or roll back an immutable release on Kubernetes or one Docker host. Production API WebSocket paths belong in the deployment profile's exact `exposure.webSocketPaths` allowlist; Compose trusts forwarding headers only from `exposure.trustedProxyCidrs`. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.
+- `podo deploy` — plan, apply, verify, or roll back an immutable release on Kubernetes or one Docker host. Production API WebSocket paths belong in the deployment profile's exact `exposure.webSocketPaths` allowlist, and API routes that take bodies above the web server's `BODY_SIZE_LIMIT` (file uploads) in `exposure.apiPaths` (and `.podokit/dev.json` `apiPaths` for `podo dev`; `podo add` and `podo deploy init` fill in the paths modules declare), which reach the API without the web proxy, so the API must check their size, session, and `Origin` itself; Compose trusts forwarding headers only from `exposure.trustedProxyCidrs`. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.
 - `podo deploy sync` — copy local build output into a running Compose deployment and restart it, for iterating without a release. Not a release: no image is published and the next `apply` discards it. Use `.agents/skills/podokit-deploy-fast`.
 
 ## Commit conventions

package/dist/templates/todo/README.md

@@ -63,8 +63,17 @@ the same topology, with one route and no project-specific host port.
 
 When the API exposes WebSocket endpoints, add their exact paths to
 `.podokit/dev.json` under `webSocketPaths`. The shared gateway sends only those paths
-directly to the API and leaves every other path on the web app. Add `publicUrl` to the
-same file when an HTTPS tunnel preserves its public `Host` header.
+directly to the API and leaves every other path on the web app. Routes that accept
+bodies larger than the web server's `BODY_SIZE_LIMIT`, such as file uploads, go under
+`apiPaths` as prefixes like `/api/files/uploads/`; the gateway removes `/api` and
+sends them to the API without the web proxy. `podo add` adds the paths a module
+declares, such as `file-upload`'s, to this file and to every deployment profile. Add `publicUrl` to the same file when
+an HTTPS tunnel preserves its public `Host` header.
+
+The containers read `.env.docker`, which Git ignores. `dev` commands create it from
+the committed `.env.docker.example` when it is missing, as in a fresh clone, and fill
+each empty `*_SECRET` value with a random one; `dev env` does only that. Keep shared
+defaults in the example and credentials only in `.env.docker`.
 
 In a second terminal, apply the included Todo migration and use the lifecycle helpers:
 
@@ -80,7 +89,9 @@ In a second terminal, apply the included Todo migration and use the lifecycle he
 `dev watch` reads `.podokit/manifest.json` and automatically activates `cache`,
 `storage`, and `queue` when installed modules require Redis, Silo, or a worker.
 `dev up` uses the same shared gateway and module profiles without keeping Compose
-Watch attached.
+Watch attached. It rebuilds the images from the current source first, because Compose
+Watch syncs edits into running containers only: a container recreated from an older
+image would lose them. Pass `--no-build` to start from the existing images.
 You can still activate an additional Compose profile explicitly:
 
 ```bash
@@ -88,7 +99,8 @@ You can still activate an additional Compose profile explicitly:
 ```
 
 Explicit profile flags are preserved for other lifecycle commands. `dev down`
-activates all profiles while removing this project's stack and route. If it is
+first stops this project's running `dev watch`, so the next `dev watch` starts
+cleanly, then activates all profiles while removing this project's stack and route. If it is
 the final registered
 project, it also removes the shared gateway and network. Source changes are synced
 through Compose Watch, including Vite HMR on the same portless browser origin.
@@ -149,5 +161,6 @@ PodoKit [deployment guide](https://github.com/podosoft-dev/podokit/blob/main/doc
 
 For a Docker Compose deployment with API WebSockets, list their exact paths under
 `exposure.webSocketPaths`. The driver keeps one published port, routes those paths
-to API, and sends every other request to web. If an external reverse proxy supplies
+to API, and sends every other request to web. Large-upload routes listed under
+`exposure.apiPaths` reach the API the same way, with `/api` removed. If an external reverse proxy supplies
 forwarding headers, list only its direct CIDR blocks in `exposure.trustedProxyCidrs`.

package/dist/update.d.ts

@@ -1,6 +1,8 @@
 import { type TemplateVars } from "@podosoft/podokit-template-engine";
 import { type Tier } from "./lockfile";
+import type { ProviderCapability } from "@podosoft/podokit-runtime";
 import type { Toolchain } from "./toolchain";
+import { type ApiPathResult } from "./module-api-paths";
 /**
  * `podo update` planner. For now it produces a dry-run plan only: it assembles
  * the new-version tree from the installed CLI's templates and compares it to the
@@ -17,12 +19,26 @@ export interface FileChange {
     /** Why the action was chosen (for the report). */
     note: string;
 }
+/** A module the target version needs that the project does not record yet. */
+export interface AddedModule {
+    name: string;
+    /** Installed or added module that needs it. */
+    requiredBy: string;
+    /** Provider capability it implements, when added for a capability requirement. */
+    capability?: ProviderCapability;
+    /** Selected provider it implements. */
+    provider?: string;
+}
 export interface UpdatePlan {
     fromVersion: string;
     toVersion: string;
     template: string;
     modules: string[];
+    /** Modules the update adds, ordered ahead of the modules that need them. */
+    addedModules: AddedModule[];
     changes: FileChange[];
+    /** Direct API paths that modules newly declare, per configuration file. */
+    apiPaths: ApiPathResult;
 }
 /**
  * Build the update plan. `templatesDir` is the installed CLI's template set (the
@@ -51,6 +67,8 @@ export interface ApplyOptions {
     abortOnConflict?: boolean;
 }
 export interface ApplyResult {
+    /** Modules added because the target version requires them. */
+    addedModules: string[];
     written: string[];
     /** Files relocated by module update migrations. */
     moved: {
@@ -62,6 +80,8 @@ export interface ApplyResult {
     merged: string[];
     /** Files written with conflict markers for manual resolution. */
     conflicts: string[];
+    /** Direct API paths added to `.podokit/dev.json` and deployment profiles. */
+    apiPaths: ApiPathResult;
 }
 /**
  * Apply an update to the working copy. Clean updates and additions are written,
@@ -71,5 +91,7 @@ export interface ApplyResult {
  * stamps the new version.
  */
 export declare function applyUpdate(projectRoot: string, templatesDir: string, options?: ApplyOptions): ApplyResult;
+/** Why an update adds a module, for the plan report. */
+export declare function addedModuleReason(module: AddedModule): string;
 /** Count actions for a one-line summary. */
 export declare function summarize(plan: UpdatePlan): Record<Action, number>;

package/dist/update.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.planUpdate = planUpdate;
 exports.applyUpdate = applyUpdate;
+exports.addedModuleReason = addedModuleReason;
 exports.summarize = summarize;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
@@ -13,6 +14,7 @@ const lockfile_1 = require("./lockfile");
 const inspect_1 = require("./inspect");
 const add_1 = require("./add");
 const module_migrations_1 = require("./module-migrations");
+const module_api_paths_1 = require("./module-api-paths");
 function treeText(tree, path) {
     const file = tree.get(path);
     if (!file)
@@ -25,17 +27,21 @@ function diskContent(projectRoot, path) {
 }
 /**
  * Expand the recorded module list against the target manifests. A module may
- * gain a new requirement after it was first added to a project; updates must
- * apply that requirement before rebuilding the dependent module or the target
- * tree can contain imports and wiring for files that were never installed.
+ * gain a new requirement after it was first added to a project, either another
+ * module or a provider capability. Updates must apply that requirement before
+ * the dependent module: modules configure in this order, and the target tree
+ * would otherwise wire files that were never installed. A capability resolves
+ * to the module implementing the project's selected provider, as `podo add`
+ * would choose it.
  */
-function targetModules(projectRoot, templatesDir, modules) {
+function targetModules(projectRoot, templatesDir, modules, providers) {
     const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
     const recorded = new Map(modules.map((module) => [module.name, module]));
     const ordered = [];
+    const added = [];
     const visiting = new Set();
     const visited = new Set();
-    const visit = (name, requiredBy) => {
+    const visit = (name, requiredBy, capability) => {
         if (visited.has(name))
             return;
         if (visiting.has(name)) {
@@ -52,12 +58,24 @@ function targetModules(projectRoot, templatesDir, modules) {
         const moduleManifest = (0, add_1.readModuleManifest)(resolved.dir);
         for (const required of moduleManifest.requires ?? [])
             visit(required, name);
+        for (const required of moduleManifest.requiresCapabilities ?? []) {
+            visit((0, add_1.selectedProviderModule)(modulesDir, projectRoot, providers, required), name, required);
+        }
         visiting.delete(name);
         visited.add(name);
+        if (!existing && requiredBy) {
+            added.push({
+                name: resolved.name,
+                requiredBy,
+                ...(capability ? { capability, provider: providers[capability] } : {}),
+            });
+        }
         ordered.push({
             ...(existing ?? {
                 name: resolved.name,
                 addedWith: (0, lockfile_1.podokitVersion)(),
+                // A freshly added module ships its current layout, as `podo add` records it.
+                appliedMigrations: (moduleManifest.migrations ?? []).map((migration) => migration.id),
             }),
             order: ordered.length,
             ...(resolved.packageName
@@ -71,7 +89,19 @@ function targetModules(projectRoot, templatesDir, modules) {
     for (const module of [...modules].sort((a, b) => a.order - b.order)) {
         visit(module.name);
     }
-    return ordered;
+    return { modules: ordered, added };
+}
+function targetApiPaths(projectRoot, templatesDir, modules) {
+    const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
+    const declared = new Map();
+    const pending = [];
+    for (const module of modules) {
+        const resolved = (0, add_1.resolveModule)(module.packageName ?? module.name, modulesDir, projectRoot);
+        const paths = resolved ? ((0, add_1.readModuleManifest)(resolved.dir).apiPaths ?? []) : [];
+        declared.set(module.name, paths);
+        pending.push(...(0, module_api_paths_1.pendingApiPaths)(module, paths));
+    }
+    return { declared, pending };
 }
 function targetManagedOverrides(projectRoot, templatesDir, modules, current = []) {
     const overrides = new Set(current);
@@ -102,7 +132,7 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
     const lock = (0, lockfile_1.readFilesLock)(projectRoot);
     if (!manifest || !lock)
         throw new inspect_1.NotAProjectError();
-    const modules = targetModules(projectRoot, templatesDir, manifest.modules);
+    const { modules, added } = targetModules(projectRoot, templatesDir, manifest.modules, manifest.providers);
     const newTree = (0, assemble_1.assembleProject)({
         templatesDir,
         template: manifest.template,
@@ -205,12 +235,24 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
             note: edited ? "you edited this; update would need a merge" : "clean update",
         });
     }
+    // A configuration file the update creates, such as a missing
+    // .podokit/dev.json, receives the paths after it is written.
+    const created = new Set(changes.filter((change) => change.action === "add").map((change) => change.path));
+    const apiPaths = options.onlyPaths
+        ? { changed: [], skipped: [] }
+        : (0, module_api_paths_1.addApiPaths)(projectRoot, targetApiPaths(projectRoot, templatesDir, modules).pending, {
+            dryRun: true,
+            read: (file) => diskContent(projectRoot, file)?.toString("utf8")
+                ?? (created.has(file) ? treeText(newTree, file) : null),
+        });
     return {
         fromVersion: manifest.podokitVersion,
         toVersion: (0, lockfile_1.podokitVersion)(),
         template: manifest.template,
         modules: modules.map((module) => module.name),
+        addedModules: added,
         changes,
+        apiPaths,
     };
 }
 function assertRecordedExternalModules(moduleRoot, templatesDir, modules) {
@@ -333,7 +375,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         forceManagedPaths: options.forceManagedPaths,
         onlyPaths: options.onlyPaths,
     });
-    const modules = targetModules(projectRoot, templatesDir, manifest.modules);
+    const { modules } = targetModules(projectRoot, templatesDir, manifest.modules, manifest.providers);
     const newTree = (0, assemble_1.assembleProject)({
         templatesDir,
         template: manifest.template,
@@ -396,11 +438,13 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         }
     }
     const result = {
+        addedModules: plan.addedModules.map((module) => module.name),
         written: [],
         moved: (0, module_migrations_1.applyModuleMigrations)(projectRoot, migrationPlan),
         removed: [],
         merged: [],
         conflicts: [],
+        apiPaths: { changed: [], skipped: [] },
     };
     for (const change of plan.changes) {
         const newText = treeText(newTree, change.path);
@@ -428,6 +472,9 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
                 result.merged.push(change.path);
         }
     }
+    const apiPaths = options.onlyPaths ? undefined : targetApiPaths(projectRoot, templatesDir, modules);
+    if (apiPaths)
+        result.apiPaths = (0, module_api_paths_1.addApiPaths)(projectRoot, apiPaths.pending);
     // Keep the assembled target as the managed baseline. A merged working file
     // intentionally remains drifted so a future update performs another 3-way
     // merge instead of treating the user's lines as clean generated output.
@@ -447,6 +494,12 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
                 ...(appliedMigrations.get(module.name) ?? []),
             ]),
         ];
+        const appliedApiPaths = [
+            ...new Set([
+                ...(module.appliedApiPaths ?? []),
+                ...(apiPaths?.declared.get(module.name) ?? []),
+            ]),
+        ];
         return {
             ...module,
             ...(resolved?.packageName
@@ -456,6 +509,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
                 }
                 : {}),
             ...(applied.length ? { appliedMigrations: applied } : {}),
+            ...(appliedApiPaths.length ? { appliedApiPaths } : {}),
         };
     });
     (0, lockfile_1.writeManifest)(projectRoot, {
@@ -469,6 +523,12 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
     });
     return result;
 }
+/** Why an update adds a module, for the plan report. */
+function addedModuleReason(module) {
+    return module.capability
+        ? `${module.capability} provider "${module.provider}" required by ${module.requiredBy}`
+        : `required by ${module.requiredBy}`;
+}
 /** Count actions for a one-line summary. */
 function summarize(plan) {
     const counts = {