@podosoft/podokit 0.13.0 → 0.14.0

package/dist/add.d.ts

@@ -7,7 +7,31 @@ interface Injection {
 }
 /** Highest `module.manifest.json` schema version this CLI understands. A package
  *  module declaring a higher version is rejected rather than mis-applied. */
-export declare const SUPPORTED_MANIFEST_VERSION = 1;
+export declare const SUPPORTED_MANIFEST_VERSION = 2;
+export interface ModulePathMove {
+    /** Project-relative file or directory path from an older module layout. */
+    from: string;
+    /** Project-relative destination. Existing files are never overwritten. */
+    to: string;
+}
+export interface ModuleTextReplacement {
+    /** Destination path after all migration moves have been applied. */
+    path: string;
+    /** Exact text expected in the existing generated file. */
+    from: string;
+    /** Replacement text written while preserving every other local edit. */
+    to: string;
+    /** Required number of matches. A mismatch aborts the migration atomically. */
+    expected: number;
+}
+export interface ModuleMigration {
+    /** Stable module-local identifier recorded after a successful apply. */
+    id: string;
+    /** File or directory moves performed as one atomic migration. */
+    moves: ModulePathMove[];
+    /** Optional exact rewrites needed after a move, such as renamed imports. */
+    replacements?: ModuleTextReplacement[];
+}
 export interface ModuleManifest {
     /** Manifest schema version. Absent (bundled modules) means "same as the CLI". */
     manifestVersion?: number;
@@ -35,6 +59,8 @@ export interface ModuleManifest {
     /** Module files that remain update-managed even when a broad default glob
      *  (for example `.claude/**`) would otherwise classify them as owned. */
     managedOverrides?: string[];
+    /** Idempotent path migrations applied by `podo update --apply`. */
+    migrations?: ModuleMigration[];
 }
 export interface PackageOverlay {
     dependencies?: Record<string, string>;

package/dist/add.js

@@ -14,7 +14,7 @@ const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const lockfile_1 = require("./lockfile");
 /** Highest `module.manifest.json` schema version this CLI understands. A package
  *  module declaring a higher version is rejected rather than mis-applied. */
-exports.SUPPORTED_MANIFEST_VERSION = 1;
+exports.SUPPORTED_MANIFEST_VERSION = 2;
 /** Return the legacy targetApp package fields plus any additional app overlays. */
 function modulePackageOverlays(manifest) {
     const overlays = new Map();
@@ -281,10 +281,12 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
     };
 }
 function moduleRecord(module) {
+    const migrations = readModuleManifest(module.dir).migrations ?? [];
     return {
         name: module.name,
         packageName: module.packageName,
         moduleVersion: module.moduleVersion,
+        appliedMigrations: migrations.map((migration) => migration.id),
     };
 }
 /** Copy a module overlay without clobbering app-owned presentation files. */

package/dist/index.js

@@ -288,7 +288,8 @@ async function main(argv) {
         try {
             if (args.apply) {
                 const result = (0, update_1.applyUpdate)(process.cwd(), templatesDir, { oldTemplatesDir: args.from });
-                process.stdout.write(`Applied: ${result.written.length} written, ${result.removed.length} removed, ` +
+                process.stdout.write(`Applied: ${result.written.length} written, ${result.moved.length} moved, ` +
+                    `${result.removed.length} removed, ` +
                     `${result.merged.length} merged, ${result.conflicts.length} conflict.\n`);
                 if (result.conflicts.length) {
                     process.stdout.write("\nResolve the following, then commit:\n" +
@@ -306,9 +307,11 @@ async function main(argv) {
             }
             else {
                 for (const c of shown) {
-                    process.stdout.write(`  ${c.action.padEnd(9)} ${c.path}  (${c.note})\n`);
+                    const path = c.fromPath ? `${c.fromPath} -> ${c.path}` : c.path;
+                    process.stdout.write(`  ${c.action.padEnd(9)} ${path}  (${c.note})\n`);
                 }
-                process.stdout.write(`\n${counts.update} update, ${counts.add} add, ${counts.remove} remove, ${counts.conflict} conflict. ` +
+                process.stdout.write(`\n${counts.update} update, ${counts.add} add, ${counts.move} move, ` +
+                    `${counts.remove} remove, ${counts.conflict} conflict. ` +
                     `Dry-run — nothing was written. Re-run with --apply to write (use --from <dir> for a 3-way merge).\n`);
             }
         }

package/dist/lib.d.ts

@@ -3,7 +3,7 @@ export type { CreateOptions, CreateResult } from "./create";
 export { TEMPLATES, DEFAULT_TEMPLATE, TEMPLATE_NAMES, isKnownTemplate } from "./templates";
 export type { TemplateInfo } from "./templates";
 export { listModules, addModule } from "./add";
-export type { ModuleManifest, AddOptions, AddResult } from "./add";
+export type { ModuleManifest, ModuleMigration, ModulePathMove, ModuleTextReplacement, AddOptions, AddResult, } from "./add";
 export { status, diff, doctor, SUPPORTED_FRAMEWORKS } from "./inspect";
 export type { StatusReport, DoctorFinding } from "./inspect";
 export { planUpdate, summarize } from "./update";

package/dist/lockfile.d.ts

@@ -3,7 +3,7 @@
  * `podo update` can rebuild the same inputs and detect user edits. See
  * ADR-0009 (update mechanism) and ADR-0010 (ownership model).
  */
-export declare const LOCK_SCHEMA_VERSION = 1;
+export declare const LOCK_SCHEMA_VERSION = 2;
 /** File ownership tier. See ADR-0010. */
 export type Tier = "managed" | "assembled" | "owned";
 export interface ManifestModule {
@@ -16,11 +16,14 @@ export interface ManifestModule {
     packageName?: string;
     /** Installed external-module version last applied to this project. */
     moduleVersion?: string;
+    /** Module-local update migrations already applied to this project. */
+    appliedMigrations?: string[];
 }
 export interface ManifestModuleInput {
     name: string;
     packageName?: string;
     moduleVersion?: string;
+    appliedMigrations?: string[];
 }
 export interface PodokitManifest {
     schemaVersion: number;

package/dist/lockfile.js

@@ -24,7 +24,7 @@ const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
  * `podo update` can rebuild the same inputs and detect user edits. See
  * ADR-0009 (update mechanism) and ADR-0010 (ownership model).
  */
-exports.LOCK_SCHEMA_VERSION = 1;
+exports.LOCK_SCHEMA_VERSION = 2;
 const PODOKIT_DIR = ".podokit";
 const MANIFEST_FILE = "manifest.json";
 const FILES_LOCK_FILE = "files.lock";
@@ -83,11 +83,11 @@ function readManifest(projectRoot) {
 }
 function writeManifest(projectRoot, manifest) {
     (0, node_fs_1.mkdirSync)(podokitDir(projectRoot), { recursive: true });
-    (0, node_fs_1.writeFileSync)(manifestPath(projectRoot), `${JSON.stringify(manifest, null, 2)}\n`);
+    (0, node_fs_1.writeFileSync)(manifestPath(projectRoot), `${JSON.stringify({ ...manifest, schemaVersion: exports.LOCK_SCHEMA_VERSION }, null, 2)}\n`);
 }
 function writeFilesLock(projectRoot, lock) {
     (0, node_fs_1.mkdirSync)(podokitDir(projectRoot), { recursive: true });
-    (0, node_fs_1.writeFileSync)(filesLockPath(projectRoot), `${JSON.stringify(lock, null, 2)}\n`);
+    (0, node_fs_1.writeFileSync)(filesLockPath(projectRoot), `${JSON.stringify({ ...lock, schemaVersion: exports.LOCK_SCHEMA_VERSION }, null, 2)}\n`);
 }
 /** Read the PodoKit CLI's own version to stamp into the manifest. */
 function podokitVersion() {
@@ -242,6 +242,7 @@ function recordModules(projectRoot, moduleInputs, version, ownedGlobs, lockSnaps
             addedWith: stampedWith,
             packageName: module.packageName,
             moduleVersion: module.moduleVersion,
+            appliedMigrations: module.appliedMigrations,
         });
         known.add(module.name);
     }

package/dist/module-migrations.d.ts

@@ -0,0 +1,25 @@
+import type { VfsTree } from "@podosoft/podokit-template-engine";
+import { type ModuleMigration } from "./add";
+import type { FilesLock, ManifestModule, Tier } from "./lockfile";
+export interface PendingModuleMigration {
+    module: string;
+    migration: ModuleMigration;
+}
+export interface PlannedPathMove {
+    from: string;
+    to: string;
+    tier: Tier;
+    content: Buffer;
+}
+export interface ModuleMigrationPlan {
+    pending: PendingModuleMigration[];
+    moves: PlannedPathMove[];
+    conflicts: string[];
+}
+export declare function collectPendingMigrations(projectRoot: string, templatesDir: string, modules: ManifestModule[]): PendingModuleMigration[];
+export declare function planModuleMigrations(projectRoot: string, targetTree: VfsTree, lock: FilesLock, pending: PendingModuleMigration[]): ModuleMigrationPlan;
+export declare function applyModuleMigrations(projectRoot: string, plan: ModuleMigrationPlan): {
+    from: string;
+    to: string;
+}[];
+export declare function migrateConfiguredPath(path: string, pending: PendingModuleMigration[]): string;

package/dist/module-migrations.js

@@ -0,0 +1,233 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectPendingMigrations = collectPendingMigrations;
+exports.planModuleMigrations = planModuleMigrations;
+exports.applyModuleMigrations = applyModuleMigrations;
+exports.migrateConfiguredPath = migrateConfiguredPath;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const add_1 = require("./add");
+function treeBuffer(tree, path) {
+    const file = tree.get(path);
+    if (!file)
+        return null;
+    return Buffer.isBuffer(file.content) ? file.content : Buffer.from(file.content);
+}
+function assertProjectPath(path, label) {
+    if (!path ||
+        path.startsWith("/") ||
+        path.endsWith("/") ||
+        node_path_1.posix.normalize(path) !== path ||
+        path.split("/").includes("..")) {
+        throw new Error(`${label} must be a normalized project-relative path: ${path}`);
+    }
+}
+function filesUnder(projectRoot, path) {
+    const absolute = (0, node_path_1.join)(projectRoot, path);
+    if (!(0, node_fs_1.existsSync)(absolute))
+        return [];
+    if (!(0, node_fs_1.statSync)(absolute).isDirectory())
+        return [path];
+    const files = [];
+    const visit = (relative) => {
+        for (const entry of (0, node_fs_1.readdirSync)((0, node_path_1.join)(projectRoot, relative), { withFileTypes: true })) {
+            const child = `${relative}/${entry.name}`;
+            if (entry.isDirectory())
+                visit(child);
+            else
+                files.push(child);
+        }
+    };
+    visit(path);
+    return files.sort();
+}
+function destinationFor(path, from, to) {
+    return path === from ? to : `${to}${path.slice(from.length)}`;
+}
+function occurrences(content, needle) {
+    if (!needle)
+        return 0;
+    let count = 0;
+    let offset = 0;
+    while (true) {
+        const index = content.indexOf(needle, offset);
+        if (index === -1)
+            return count;
+        count += 1;
+        offset = index + needle.length;
+    }
+}
+function transformedContent(path, content, pending, conflicts) {
+    let text = null;
+    for (const { module, migration } of pending) {
+        for (const replacement of migration.replacements ?? []) {
+            if (replacement.path !== path)
+                continue;
+            text ??= content.toString("utf8");
+            const currentCount = occurrences(text, replacement.from);
+            if (currentCount === replacement.expected) {
+                text = text.split(replacement.from).join(replacement.to);
+                continue;
+            }
+            const replacementCount = occurrences(text, replacement.to);
+            if (currentCount === 0 && replacementCount === replacement.expected)
+                continue;
+            conflicts.push(`${module}:${migration.id} expected ${replacement.expected} occurrence(s) in ` +
+                `${replacement.path}, found ${currentCount}`);
+        }
+    }
+    return text === null ? content : Buffer.from(text);
+}
+function matchesPathOrChild(path, prefix) {
+    return path === prefix || path.startsWith(`${prefix}/`);
+}
+function collectPendingMigrations(projectRoot, templatesDir, modules) {
+    const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
+    const pending = [];
+    for (const module of modules) {
+        const resolved = (0, add_1.resolveModule)(module.packageName ?? module.name, modulesDir, projectRoot);
+        if (!resolved)
+            continue;
+        const manifest = (0, add_1.readModuleManifest)(resolved.dir);
+        const applied = new Set(module.appliedMigrations ?? []);
+        for (const migration of manifest.migrations ?? []) {
+            if (applied.has(migration.id))
+                continue;
+            if (!migration.id || migration.moves.length === 0) {
+                throw new Error(`Module "${module.name}" declares an invalid migration.`);
+            }
+            for (const move of migration.moves) {
+                assertProjectPath(move.from, `${module.name}:${migration.id} move.from`);
+                assertProjectPath(move.to, `${module.name}:${migration.id} move.to`);
+                if (move.from === move.to) {
+                    throw new Error(`${module.name}:${migration.id} cannot move a path onto itself.`);
+                }
+            }
+            for (const replacement of migration.replacements ?? []) {
+                assertProjectPath(replacement.path, `${module.name}:${migration.id} replacement.path`);
+                if (!replacement.from || replacement.expected < 1) {
+                    throw new Error(`${module.name}:${migration.id} declares an invalid text replacement.`);
+                }
+            }
+            pending.push({ module: module.name, migration });
+        }
+    }
+    return pending;
+}
+function planModuleMigrations(projectRoot, targetTree, lock, pending) {
+    const conflicts = [];
+    const moveSources = new Set();
+    const moveTargets = new Set();
+    const candidates = [];
+    for (const { module, migration } of pending) {
+        for (const move of migration.moves) {
+            const staleTargetPaths = [...targetTree.keys()].filter((path) => matchesPathOrChild(path, move.from));
+            if (staleTargetPaths.length) {
+                conflicts.push(`${module}:${migration.id} target modules still provide legacy path ${move.from}; ` +
+                    `upgrade external modules before updating`);
+                continue;
+            }
+            for (const source of filesUnder(projectRoot, move.from)) {
+                const target = destinationFor(source, move.from, move.to);
+                if (moveSources.has(source)) {
+                    conflicts.push(`${module}:${migration.id} moves ${source} more than once`);
+                    continue;
+                }
+                if (moveTargets.has(target)) {
+                    conflicts.push(`${module}:${migration.id} has duplicate destination ${target}`);
+                    continue;
+                }
+                moveSources.add(source);
+                moveTargets.add(target);
+                candidates.push({
+                    from: source,
+                    to: target,
+                    tier: lock.files[source]?.tier ?? "owned",
+                });
+            }
+        }
+    }
+    for (const candidate of candidates) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(projectRoot, candidate.to)) && !moveSources.has(candidate.to)) {
+            conflicts.push(`cannot move ${candidate.from}: destination already exists at ${candidate.to}`);
+        }
+    }
+    const moves = candidates.map((candidate) => {
+        const sourceContent = (0, node_fs_1.readFileSync)((0, node_path_1.join)(projectRoot, candidate.from));
+        const locked = lock.files[candidate.from];
+        const targetContent = treeBuffer(targetTree, candidate.to);
+        const content = locked && locked.outHash === hashBuffer(sourceContent) && targetContent
+            ? targetContent
+            : transformedContent(candidate.to, sourceContent, pending, conflicts);
+        return { ...candidate, content };
+    });
+    for (const { module, migration } of pending) {
+        for (const replacement of migration.replacements ?? []) {
+            if (moves.some((move) => move.to === replacement.path))
+                continue;
+            const target = (0, node_path_1.join)(projectRoot, replacement.path);
+            if (!(0, node_fs_1.existsSync)(target))
+                continue;
+            transformedContent(replacement.path, (0, node_fs_1.readFileSync)(target), [{ module, migration }], conflicts);
+        }
+    }
+    return { pending, moves, conflicts: [...new Set(conflicts)] };
+}
+function hashBuffer(content) {
+    return `sha256:${(0, node_crypto_1.createHash)("sha256").update(content).digest("hex")}`;
+}
+function pruneEmptyDirectories(projectRoot, relative) {
+    let current = relative;
+    while (current && current !== "." && current !== "/") {
+        try {
+            (0, node_fs_1.rmdirSync)((0, node_path_1.join)(projectRoot, current));
+        }
+        catch {
+            return;
+        }
+        current = (0, node_path_1.dirname)(current);
+    }
+}
+function applyModuleMigrations(projectRoot, plan) {
+    if (plan.conflicts.length)
+        return [];
+    const moved = [];
+    const replacementByPath = new Map();
+    for (const move of plan.moves)
+        replacementByPath.set(move.to, move.content);
+    for (const { module, migration } of plan.pending) {
+        for (const replacement of migration.replacements ?? []) {
+            if (replacementByPath.has(replacement.path))
+                continue;
+            const target = (0, node_path_1.join)(projectRoot, replacement.path);
+            if (!(0, node_fs_1.existsSync)(target))
+                continue;
+            replacementByPath.set(replacement.path, transformedContent(replacement.path, (0, node_fs_1.readFileSync)(target), [{ module, migration }], []));
+        }
+    }
+    for (const move of plan.moves) {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)((0, node_path_1.join)(projectRoot, move.to)), { recursive: true });
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(projectRoot, move.to), replacementByPath.get(move.to) ?? move.content);
+        (0, node_fs_1.rmSync)((0, node_path_1.join)(projectRoot, move.from));
+        pruneEmptyDirectories(projectRoot, (0, node_path_1.dirname)(move.from));
+        moved.push({ from: move.from, to: move.to });
+    }
+    for (const [path, content] of replacementByPath) {
+        if (plan.moves.some((move) => move.to === path))
+            continue;
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(projectRoot, path), content);
+    }
+    return moved;
+}
+function migrateConfiguredPath(path, pending) {
+    let migrated = path;
+    for (const { migration } of pending) {
+        for (const move of migration.moves) {
+            if (matchesPathOrChild(migrated, move.from)) {
+                migrated = destinationFor(migrated, move.from, move.to);
+            }
+        }
+    }
+    return migrated;
+}

package/dist/templates/fullstack-nest-svelte/Dockerfile.dev

@@ -17,7 +17,9 @@ WORKDIR /app
 COPY package.json ./
 COPY apps/api/package.json ./apps/api/package.json
 COPY apps/web/package.json ./apps/web/package.json
-RUN npm install
+ARG PODOKIT_NPM_REGISTRY=""
+RUN if [ -n "$PODOKIT_NPM_REGISTRY" ]; then npm config set registry "$PODOKIT_NPM_REGISTRY"; fi \
+  && npm install
 
 # Baked source (kept in sync during development by `docker compose watch`).
 COPY . .

package/dist/templates/fullstack-nest-svelte/apps/api/package.json

@@ -14,7 +14,7 @@
     "migration:generate": "npm run typeorm -- migration:generate"
   },
   "dependencies": {
-    "@podosoft/podokit-contracts": "^0.3.0",
+    "@podosoft/podokit-contracts": "^0.4.0",
     "@nestjs/common": "^11.1.27",
     "@nestjs/config": "^4.0.4",
     "@nestjs/core": "^11.1.27",

package/dist/templates/fullstack-nest-svelte/apps/web/Dockerfile

@@ -16,6 +16,9 @@ RUN npm run build --workspace=apps/web
 FROM node:22-alpine AS runtime
 WORKDIR /app
 ENV NODE_ENV=production
+# Keep the adapter-node proxy above the 2 MiB application upload policy so the
+# API can return stable validation codes after accounting for multipart framing.
+ENV BODY_SIZE_LIMIT=3M
 RUN addgroup -S app && adduser -S app -G app
 COPY --from=build /app/node_modules ./node_modules
 COPY --from=deps /app/apps/web ./apps/web

package/dist/templates/fullstack-nest-svelte/apps/web/package.json

@@ -13,7 +13,7 @@
   "dependencies": {
     "@internationalized/date": "^3.12.2",
     "@lucide/svelte": "^1.23.0",
-    "@podosoft/podokit-api-client": "^0.7.0",
+    "@podosoft/podokit-api-client": "^0.8.0",
     "bits-ui": "^2.18.1",
     "clsx": "^2.1.1",
     "mode-watcher": "^1.1.0",

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/components/ui/input/input.svelte

@@ -16,6 +16,7 @@
 		files = $bindable(),
 		class: className,
 		"data-slot": dataSlot = "input",
+		onchange,
 		...restProps
 	}: Props = $props();
 </script>
@@ -30,7 +31,7 @@
 		)}
 		type="file"
 		bind:files
-		bind:value
+		{onchange}
 		{...restProps}
 	/>
 {:else}
@@ -43,6 +44,7 @@
 		)}
 		{type}
 		bind:value
+		{onchange}
 		{...restProps}
 	/>
 {/if}

package/dist/templates/fullstack-nest-svelte/apps/web/src/routes/+page.svelte

@@ -3,6 +3,8 @@
   import * as Card from "$lib/components/ui/card";
   import { api } from "$lib/api";
   import { ApiError } from "@podosoft/podokit-api-client";
+  // podokit:begin:landing-imports
+  // podokit:end:landing-imports
 
   type Health = { status: string } | { error: string };
 
@@ -17,6 +19,9 @@
   }
 </script>
 
+<!-- podokit:begin:landing-actions -->
+<!-- podokit:end:landing-actions -->
+
 <main class="mx-auto flex min-h-full max-w-2xl flex-col gap-6 p-8">
   <div>
     <h1 class="text-3xl font-bold">{{projectName}}</h1>

package/dist/templates/fullstack-nest-svelte/compose.dev.yaml

@@ -41,6 +41,8 @@ services:
     build:
       context: .
       dockerfile: Dockerfile.dev
+      args:
+        PODOKIT_NPM_REGISTRY: ${PODOKIT_NPM_REGISTRY:-}
     command: npm run dev -w {{projectName}}-web -- --host 0.0.0.0
     working_dir: /app
     env_file: .env.docker
@@ -64,6 +66,8 @@ services:
     build:
       context: .
       dockerfile: Dockerfile.dev
+      args:
+        PODOKIT_NPM_REGISTRY: ${PODOKIT_NPM_REGISTRY:-}
     init: true
     command: npm run dev -w {{projectName}}-api
     working_dir: /app
@@ -87,6 +91,8 @@ services:
     build:
       context: .
       dockerfile: Dockerfile.dev
+      args:
+        PODOKIT_NPM_REGISTRY: ${PODOKIT_NPM_REGISTRY:-}
     init: true
     command: npm run dev:worker -w {{projectName}}-api
     working_dir: /app

package/dist/templates/fullstack-nest-svelte/dot-env.example

@@ -13,6 +13,8 @@ POSTGRES_DB=podokit
 # Web -> API boundary (server-side only; not exposed to the browser)
 BACKEND_INTERNAL_URL=http://localhost:5002
 CORS_ORIGIN=http://localhost:5001
+# adapter-node request limit; leave room for a 2 MiB multipart upload
+BODY_SIZE_LIMIT=3M
 
 # ── Optional / development ───────────────────────────────────────────
 # Redis — only needed by cache/queue modules (redis, bullmq, rate-limit,

package/dist/templates/fullstack-nest-svelte/infra/k3s/configmap.yaml

@@ -8,5 +8,6 @@ data:
   PORT: "3000"
   CORS_ORIGIN: "https://example.com"
   BACKEND_INTERNAL_URL: "http://api:3000"
+  BODY_SIZE_LIMIT: "3M"
   ADDRESS_HEADER: "x-forwarded-for"
   XFF_DEPTH: "1"

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image-upload.interceptor.ts

@@ -0,0 +1,39 @@
+import {
+  type CallHandler,
+  type ExecutionContext,
+  Injectable,
+  PayloadTooLargeException,
+} from "@nestjs/common";
+import { FileInterceptor } from "@nestjs/platform-express";
+import {
+  AppException,
+  PROFILE_IMAGE_POLICY,
+  PROFILE_IMAGE_TOO_LARGE,
+} from "@podosoft/podokit-contracts";
+import type { Observable } from "rxjs";
+
+const ProfileImageFileInterceptor = FileInterceptor("file", {
+  limits: { fileSize: PROFILE_IMAGE_POLICY.maxBytes },
+});
+
+/** Preserve a stable error code when Multer rejects an oversized request. */
+@Injectable()
+export class ProfileImageUploadInterceptor extends ProfileImageFileInterceptor {
+  override async intercept(
+    context: ExecutionContext,
+    next: CallHandler,
+  ): Promise<Observable<unknown>> {
+    try {
+      return await super.intercept(context, next);
+    } catch (error: unknown) {
+      if (error instanceof PayloadTooLargeException) {
+        throw new AppException(
+          PROFILE_IMAGE_TOO_LARGE,
+          "Profile image must be 2 MB or smaller.",
+          413,
+        );
+      }
+      throw error;
+    }
+  }
+}

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.controller.ts

@@ -0,0 +1,73 @@
+/// <reference types="multer" />
+import {
+  Controller,
+  Delete,
+  Get,
+  Param,
+  Post,
+  Req,
+  Res,
+  StreamableFile,
+  UploadedFile,
+  UseInterceptors,
+} from "@nestjs/common";
+import { ApiConsumes, ApiTags } from "@nestjs/swagger";
+import { Public, Session, type UserSession } from "@thallesp/nestjs-better-auth";
+import {
+  AppException,
+  PROFILE_IMAGE_REQUIRED,
+  type ProfileImageResponse,
+} from "@podosoft/podokit-contracts";
+import { fromNodeHeaders } from "better-auth/node";
+import type { Request, Response } from "express";
+import { ProfileImageService } from "./profile-image.service";
+import { ProfileImageUploadInterceptor } from "./profile-image-upload.interceptor";
+
+@ApiTags("account")
+@Controller()
+export class ProfileImageController {
+  constructor(private readonly profileImages: ProfileImageService) {}
+
+  @Post("account/profile-image")
+  @ApiConsumes("multipart/form-data")
+  @UseInterceptors(ProfileImageUploadInterceptor)
+  async upload(
+    @Session() session: UserSession,
+    @Req() req: Request,
+    @UploadedFile() file?: Express.Multer.File,
+  ): Promise<ProfileImageResponse> {
+    if (!file) {
+      throw new AppException(
+        PROFILE_IMAGE_REQUIRED,
+        "A profile image file is required.",
+      );
+    }
+    return this.profileImages.upload(
+      session.user.image ?? null,
+      file,
+      fromNodeHeaders(req.headers),
+    );
+  }
+
+  @Delete("account/profile-image")
+  async remove(
+    @Session() session: UserSession,
+    @Req() req: Request,
+  ): Promise<ProfileImageResponse> {
+    return this.profileImages.remove(
+      session.user.image ?? null,
+      fromNodeHeaders(req.headers),
+    );
+  }
+
+  @Public()
+  @Get("profile-images/:fileName")
+  async get(
+    @Param("fileName") fileName: string,
+    @Res({ passthrough: true }) response: Response,
+  ): Promise<StreamableFile> {
+    const image = await this.profileImages.get(fileName);
+    response.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+    return new StreamableFile(image.body, { type: image.contentType });
+  }
+}

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.module.ts

@@ -0,0 +1,9 @@
+import { Module } from "@nestjs/common";
+import { ProfileImageController } from "./profile-image.controller";
+import { ProfileImageService } from "./profile-image.service";
+
+@Module({
+  controllers: [ProfileImageController],
+  providers: [ProfileImageService],
+})
+export class ProfileImageModule {}