@podosoft/podokit 0.6.0 → 0.7.0

package/dist/add.d.ts

@@ -5,7 +5,12 @@ interface Injection {
     /** Skip (instead of failing) if the target file or marker is absent. */
     optional?: boolean;
 }
+/** 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 interface ModuleManifest {
+    /** Manifest schema version. Absent (bundled modules) means "same as the CLI". */
+    manifestVersion?: number;
     name: string;
     description: string;
     requires?: string[];
@@ -16,6 +21,11 @@ export interface ModuleManifest {
     env?: string[];
     inject?: Injection[];
     instructions?: string[];
+    /** App-relative globs this module's files should own (durably user-editable,
+     *  never touched by `podo update`). Merged into the project's ownedGlobs so
+     *  they survive lock recompute. Use for public presentation pages a consumer
+     *  restyles, while keeping the module's `$lib` logic managed. */
+    ownedGlobs?: string[];
 }
 export interface AddOptions {
     projectRoot: string;
@@ -29,9 +39,19 @@ export interface AddResult {
     instructions: string[];
     /** Required modules that were auto-added because they were missing. */
     added: string[];
+    /** ownedGlobs declared by this module and every module it pulled in. */
+    ownedGlobs: string[];
 }
-/** List modules available under `modulesDir` (each has a module.manifest.json). */
-export declare function listModules(modulesDir: string): {
+/**
+ * Resolve a module's directory by name: first the bundled `modulesDir`, then a
+ * node-resolvable npm package `@podosoft/podokit-module-<name>` installed in the
+ * project (or a fully-qualified `@scope/pkg` name). Returns null if not found.
+ */
+export declare function resolveModuleDir(name: string, modulesDir: string, projectRoot: string): string | null;
+/** List modules available to a project: the bundled ones under `modulesDir` plus,
+ *  when `projectRoot` is given, any `@podosoft/podokit-module-*` packages installed
+ *  in it. Bundled names take precedence on a clash. */
+export declare function listModules(modulesDir: string, projectRoot?: string): {
     name: string;
     description: string;
 }[];

package/dist/add.js

@@ -1,21 +1,69 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_MANIFEST_VERSION = void 0;
+exports.resolveModuleDir = resolveModuleDir;
 exports.listModules = listModules;
 exports.addModule = addModule;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const node_module_1 = require("node:module");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const lockfile_1 = require("./lockfile");
-/** List modules available under `modulesDir` (each has a module.manifest.json). */
-function listModules(modulesDir) {
-    if (!(0, node_fs_1.existsSync)(modulesDir))
-        return [];
-    return (0, node_fs_1.readdirSync)(modulesDir)
-        .filter((name) => (0, node_fs_1.existsSync)((0, node_path_1.join)(modulesDir, name, "module.manifest.json")))
-        .map((name) => {
-        const manifest = readManifest((0, node_path_1.join)(modulesDir, name));
-        return { name, description: manifest.description };
-    });
+/** 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;
+const PACKAGE_PREFIX = "@podosoft/podokit-module-";
+/**
+ * Resolve a module's directory by name: first the bundled `modulesDir`, then a
+ * node-resolvable npm package `@podosoft/podokit-module-<name>` installed in the
+ * project (or a fully-qualified `@scope/pkg` name). Returns null if not found.
+ */
+function resolveModuleDir(name, modulesDir, projectRoot) {
+    const bundled = (0, node_path_1.join)(modulesDir, name);
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(bundled, "module.manifest.json")))
+        return bundled;
+    const pkg = name.includes("/") ? name : `${PACKAGE_PREFIX}${name}`;
+    try {
+        const req = (0, node_module_1.createRequire)((0, node_path_1.join)(projectRoot, "package.json"));
+        return (0, node_path_1.dirname)(req.resolve(`${pkg}/module.manifest.json`));
+    }
+    catch {
+        return null;
+    }
+}
+function assertManifestVersion(name, manifest) {
+    if ((manifest.manifestVersion ?? exports.SUPPORTED_MANIFEST_VERSION) > exports.SUPPORTED_MANIFEST_VERSION) {
+        throw new Error(`Module "${name}" needs a newer PodoKit (manifest v${manifest.manifestVersion}, this CLI supports v${exports.SUPPORTED_MANIFEST_VERSION}). Update @podosoft/podokit.`);
+    }
+}
+/** List modules available to a project: the bundled ones under `modulesDir` plus,
+ *  when `projectRoot` is given, any `@podosoft/podokit-module-*` packages installed
+ *  in it. Bundled names take precedence on a clash. */
+function listModules(modulesDir, projectRoot) {
+    const out = new Map();
+    if ((0, node_fs_1.existsSync)(modulesDir)) {
+        for (const name of (0, node_fs_1.readdirSync)(modulesDir)) {
+            if ((0, node_fs_1.existsSync)((0, node_path_1.join)(modulesDir, name, "module.manifest.json"))) {
+                out.set(name, readManifest((0, node_path_1.join)(modulesDir, name)).description);
+            }
+        }
+    }
+    if (projectRoot) {
+        const scope = (0, node_path_1.join)(projectRoot, "node_modules", "@podosoft");
+        if ((0, node_fs_1.existsSync)(scope)) {
+            for (const dir of (0, node_fs_1.readdirSync)(scope)) {
+                if (!dir.startsWith("podokit-module-"))
+                    continue;
+                const manifestPath = (0, node_path_1.join)(scope, dir, "module.manifest.json");
+                if (!(0, node_fs_1.existsSync)(manifestPath))
+                    continue;
+                const manifest = readManifest((0, node_path_1.join)(scope, dir));
+                if (!out.has(manifest.name))
+                    out.set(manifest.name, manifest.description);
+            }
+        }
+    }
+    return [...out].map(([name, description]) => ({ name, description }));
 }
 function readManifest(moduleDir) {
     return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8"));
@@ -40,10 +88,10 @@ function appendEnv(projectRoot, lines) {
 }
 /** Heuristic: is `module` already applied to the project? */
 function isApplied(projectRoot, modulesDir, module) {
-    const manifestPath = (0, node_path_1.join)(modulesDir, module, "module.manifest.json");
-    if (!(0, node_fs_1.existsSync)(manifestPath))
+    const moduleDir = resolveModuleDir(module, modulesDir, projectRoot);
+    if (!moduleDir)
         return false;
-    const manifest = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf8"));
+    const manifest = readManifest(moduleDir);
     const firstInject = manifest.inject?.[0];
     if (firstInject) {
         const target = (0, node_path_1.join)(projectRoot, firstInject.file);
@@ -58,17 +106,19 @@ function isApplied(projectRoot, modulesDir, module) {
  */
 function addModule(options) {
     const result = applyModule(options.projectRoot, options.module, options.modulesDir, new Set());
-    // Record the module (and any auto-added requirements) and refresh the lock.
-    (0, lockfile_1.recordModules)(options.projectRoot, [...result.added, result.module], options.podokitVersion);
+    // Record the module (and any auto-added requirements), fold in the modules'
+    // declared ownedGlobs, and refresh the lock.
+    (0, lockfile_1.recordModules)(options.projectRoot, [...result.added, result.module], options.podokitVersion, result.ownedGlobs);
     return result;
 }
 function applyModule(projectRoot, module, modulesDir, applied) {
-    const moduleDir = (0, node_path_1.join)(modulesDir, module);
-    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"))) {
-        const available = listModules(modulesDir).map((m) => m.name);
+    const moduleDir = resolveModuleDir(module, modulesDir, projectRoot);
+    if (!moduleDir) {
+        const available = listModules(modulesDir, projectRoot).map((m) => m.name);
         throw new Error(`Unknown module "${module}".${available.length ? ` Available: ${available.join(", ")}.` : ""}`);
     }
     const manifest = readManifest(moduleDir);
+    assertManifestVersion(module, manifest);
     const appPkgPath = (0, node_path_1.join)(projectRoot, "apps", manifest.targetApp, "package.json");
     if (!(0, node_fs_1.existsSync)(appPkgPath)) {
         throw new Error(`This does not look like a PodoKit project: ${(0, node_path_1.join)("apps", manifest.targetApp, "package.json")} not found. Run inside a generated project.`);
@@ -76,11 +126,13 @@ function applyModule(projectRoot, module, modulesDir, applied) {
     applied.add(module);
     // 0) apply required modules first (auto-add if missing)
     const added = [];
+    const ownedGlobs = [...(manifest.ownedGlobs ?? [])];
     for (const required of manifest.requires ?? []) {
         if (applied.has(required) || isApplied(projectRoot, modulesDir, required))
             continue;
         const result = applyModule(projectRoot, required, modulesDir, applied);
         added.push(required, ...result.added);
+        ownedGlobs.push(...result.ownedGlobs);
     }
     const appName = projectName(projectRoot);
     const vars = { projectName: appName };
@@ -119,5 +171,5 @@ function applyModule(projectRoot, module, modulesDir, applied) {
         (0, node_fs_1.writeFileSync)(target, (0, podokit_template_engine_1.insertAtMarker)(content, injection.marker, injection.text));
     }
     const instructions = (manifest.instructions ?? []).map((line) => line.replace(/<app>/g, appName));
-    return { module, instructions, added };
+    return { module, instructions, added, ownedGlobs };
 }

package/dist/eject.js

@@ -21,7 +21,15 @@ function eject(projectRoot, paths) {
             result.ejected.push(path);
         }
     }
-    if (result.ejected.length)
+    if (result.ejected.length) {
         (0, lockfile_1.writeFilesLock)(projectRoot, lock);
+        // Persist ejected paths into the manifest's ownedGlobs so they stay owned
+        // across the next add/update, which rebuilds every tier from ownedGlobs.
+        const manifest = (0, lockfile_1.readManifest)(projectRoot);
+        if (manifest) {
+            manifest.ownedGlobs = (0, lockfile_1.mergeOwnedGlobs)(manifest.ownedGlobs, result.ejected);
+            (0, lockfile_1.writeManifest)(projectRoot, manifest);
+        }
+    }
     return result;
 }

package/dist/index.js

@@ -89,7 +89,7 @@ async function main(argv) {
     if (args.command === "add") {
         const moduleName = args.name;
         if (!moduleName) {
-            const available = (0, add_1.listModules)(modulesDir);
+            const available = (0, add_1.listModules)(modulesDir, process.cwd());
             const list = available.length
                 ? available.map((m) => `  ${m.name}  ${m.description}`).join("\n")
                 : "  (none available)";

package/dist/lockfile.d.ts

@@ -72,9 +72,14 @@ export interface InitLockOptions {
 }
 /** Write the initial `.podokit/` lockfile for a freshly created project. */
 export declare function initLockfile(projectRoot: string, options: InitLockOptions): void;
+/** Union two glob lists, preserving order and dropping duplicates. Used to fold
+ *  module-declared and ejected owned paths into the project's `ownedGlobs`, which
+ *  is the durable source of truth `computeFilesLock` re-reads on every recompute. */
+export declare function mergeOwnedGlobs(existing: string[], add: string[]): string[];
 /**
  * Record applied modules in the manifest and recompute the files.lock. Modules
  * already present are left in place (idempotent); the lock always reflects disk.
- * No-op on projects without a manifest (pre-lockfile projects; see `podo adopt`).
+ * `ownedGlobs` a module declares are merged into the manifest so its owned paths
+ * survive every future recompute. No-op on projects without a manifest.
  */
-export declare function recordModules(projectRoot: string, moduleNames: string[], version?: string): void;
+export declare function recordModules(projectRoot: string, moduleNames: string[], version?: string, ownedGlobs?: string[]): void;

package/dist/lockfile.js

@@ -14,6 +14,7 @@ exports.computeFilesLock = computeFilesLock;
 exports.readFilesLock = readFilesLock;
 exports.computeDrift = computeDrift;
 exports.initLockfile = initLockfile;
+exports.mergeOwnedGlobs = mergeOwnedGlobs;
 exports.recordModules = recordModules;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -44,6 +45,8 @@ const WALK_IGNORE = new Set([
 exports.DEFAULT_OWNED_GLOBS = [
     "apps/web/src/routes/**",
     "apps/web/src/lib/components/ui/**",
+    // Owned Nest DI extension slot — override providers here; update never touches it.
+    "apps/api/src/app.extensions.ts",
     // AI agent guidance — yours to customize; update never touches it.
     "AGENTS.md",
     "CLAUDE.md",
@@ -186,12 +189,27 @@ function initLockfile(projectRoot, options) {
     writeManifest(projectRoot, manifest);
     writeFilesLock(projectRoot, computeFilesLock(projectRoot, ownedGlobs));
 }
+/** Union two glob lists, preserving order and dropping duplicates. Used to fold
+ *  module-declared and ejected owned paths into the project's `ownedGlobs`, which
+ *  is the durable source of truth `computeFilesLock` re-reads on every recompute. */
+function mergeOwnedGlobs(existing, add) {
+    const seen = new Set(existing);
+    const out = [...existing];
+    for (const glob of add) {
+        if (seen.has(glob))
+            continue;
+        seen.add(glob);
+        out.push(glob);
+    }
+    return out;
+}
 /**
  * Record applied modules in the manifest and recompute the files.lock. Modules
  * already present are left in place (idempotent); the lock always reflects disk.
- * No-op on projects without a manifest (pre-lockfile projects; see `podo adopt`).
+ * `ownedGlobs` a module declares are merged into the manifest so its owned paths
+ * survive every future recompute. No-op on projects without a manifest.
  */
-function recordModules(projectRoot, moduleNames, version) {
+function recordModules(projectRoot, moduleNames, version, ownedGlobs) {
     const manifest = readManifest(projectRoot);
     if (!manifest)
         return;
@@ -203,6 +221,8 @@ function recordModules(projectRoot, moduleNames, version) {
         manifest.modules.push({ name, order: manifest.modules.length, addedWith: stampedWith });
         known.add(name);
     }
+    if (ownedGlobs?.length)
+        manifest.ownedGlobs = mergeOwnedGlobs(manifest.ownedGlobs, ownedGlobs);
     writeManifest(projectRoot, manifest);
     writeFilesLock(projectRoot, computeFilesLock(projectRoot, manifest.ownedGlobs));
 }

package/dist/templates/fullstack-nest-svelte/AGENTS.md

@@ -59,7 +59,7 @@ changes need an e2e/unit test.
 This project is managed by the `podo` CLI. Files have an ownership tier recorded
 in `.podokit/files.lock` — respect it:
 
-- **owned** (your code: `apps/web/src/routes/**`, your components/services, and this `AGENTS.md`) — edit freely.
+- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. To add or override Nest providers/modules, use `app.extensions.ts` (spread into `AppModule` after the module-wired providers, so a same-token override wins) rather than editing `app.module.ts`.
 - **assembled** (e.g. `apps/api/src/app.module.ts`, `auth.ts`) — contain `// podokit:begin:… / …:end` fenced regions that the toolkit recomputes. Edit outside the fences only; **never hand-edit inside the fences**.
 - **managed** (bootstrap/config like `main.ts`) — the toolkit may update these; avoid gratuitous edits.
 

package/dist/templates/fullstack-nest-svelte/apps/api/src/app.extensions.ts

@@ -0,0 +1,21 @@
+import type { DynamicModule, Provider, Type } from "@nestjs/common";
+
+// Owned extension slot for the Nest app. This file is yours — PodoKit never
+// writes to it, so `podo update` leaves it alone. Use it to add your own modules
+// or providers, or to override a PodoKit-provided provider without editing
+// managed code. Because these are spread in *after* the module-wired providers,
+// an override here takes precedence.
+//
+// Example — swap the mailer transport for your own implementation:
+//   import { Mailer } from "./mailer/mailer";
+//   import { MyMailer } from "./my-mailer";
+//   export const extensionProviders: Provider[] = [
+//     { provide: Mailer, useClass: MyMailer },
+//   ];
+
+/** Extra modules to import into AppModule (or DynamicModule overrides). */
+export const extensionImports: (Type | DynamicModule)[] = [];
+
+/** Extra or overriding providers for AppModule. Same-token providers listed here
+ *  win over the ones PodoKit modules registered. */
+export const extensionProviders: Provider[] = [];

package/dist/templates/fullstack-nest-svelte/apps/api/src/app.module.ts

@@ -4,6 +4,7 @@ import { TypeOrmModule } from "@nestjs/typeorm";
 import { validateEnv } from "./config/env.validation";
 import { dataSourceOptions } from "./database/data-source";
 import { HealthModule } from "./health/health.module";
+import { extensionImports, extensionProviders } from "./app.extensions";
 // podokit:begin:imports
 // podokit:end:imports
 
@@ -14,10 +15,12 @@ import { HealthModule } from "./health/health.module";
     HealthModule,
     // podokit:begin:module-imports
     // podokit:end:module-imports
+    ...extensionImports,
   ],
   providers: [
     // podokit:begin:providers
     // podokit:end:providers
+    ...extensionProviders,
   ],
 })
 export class AppModule {}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/registry.svelte.ts

@@ -0,0 +1,37 @@
+import type { Component } from "svelte";
+import type { Messages } from "$lib/i18n/messages";
+// Modules import their nav-entry icons here.
+// podokit:begin:admin-nav-imports
+// podokit:end:admin-nav-imports
+
+// Module-driven admin menu registry. Modules append their sidebar nav entries and
+// settings tabs at the markers below via `podo add` injection, so the admin menu
+// grows and shrinks with the installed module set — no edits to app-sidebar or
+// the settings page. Empty until a module registers.
+
+/** A sidebar nav entry contributed by a module: a link, a label resolved from the
+ *  current locale (from the module's own i18n block), and an icon. */
+export type AdminNavEntry = {
+  href: string;
+  label: (t: Messages) => string;
+  icon: Component;
+  adminOnly?: boolean;
+};
+
+/** A settings tab contributed by a module: a tab value, a label resolved from the
+ *  current locale, and the panel component. */
+export type AdminSettingsSection = {
+  value: string;
+  label: (t: Messages) => string;
+  component: Component;
+};
+
+export const moduleNavEntries: AdminNavEntry[] = [
+  // podokit:begin:admin-nav-entries
+  // podokit:end:admin-nav-entries
+];
+
+export const moduleSettingsSections: AdminSettingsSection[] = [
+  // podokit:begin:admin-settings
+  // podokit:end:admin-settings
+];

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/app-sidebar.svelte

@@ -10,25 +10,26 @@
   import SettingsIcon from "@lucide/svelte/icons/settings";
   import HouseIcon from "@lucide/svelte/icons/house";
   import { getI18n } from "$lib/i18n";
+  import { moduleNavEntries, type AdminNavEntry } from "$lib/admin/registry.svelte";
   import type { SessionUser } from "../../app.d.ts";
-  import type { Messages } from "$lib/i18n/messages";
-  import type { Component } from "svelte";
 
   let { user, capabilities }: { user: SessionUser; capabilities?: { auditLog?: boolean; organization?: boolean } } = $props();
   const i18n = getI18n();
 
-  type NavItem = { href: string; key: keyof Messages["nav"]; icon: Component; adminOnly?: boolean };
+  type NavItem = AdminNavEntry;
   const items = $derived<NavItem[]>([
-    { href: "/admin", key: "overview", icon: LayoutDashboardIcon },
-    { href: "/admin/users", key: "users", icon: UsersIcon, adminOnly: true },
-    { href: "/admin/sessions", key: "sessions", icon: MonitorSmartphoneIcon, adminOnly: true },
+    { href: "/admin", label: (t) => t.nav.overview, icon: LayoutDashboardIcon },
+    { href: "/admin/users", label: (t) => t.nav.users, icon: UsersIcon, adminOnly: true },
+    { href: "/admin/sessions", label: (t) => t.nav.sessions, icon: MonitorSmartphoneIcon, adminOnly: true },
     ...(capabilities?.organization
-      ? [{ href: "/admin/organizations", key: "organizations", icon: Building2Icon, adminOnly: true } as NavItem]
+      ? [{ href: "/admin/organizations", label: (t) => t.nav.organizations, icon: Building2Icon, adminOnly: true } as NavItem]
       : []),
     ...(capabilities?.auditLog
-      ? [{ href: "/admin/audit", key: "audit", icon: ScrollTextIcon, adminOnly: true } as NavItem]
+      ? [{ href: "/admin/audit", label: (t) => t.nav.audit, icon: ScrollTextIcon, adminOnly: true } as NavItem]
       : []),
-    { href: "/admin/settings", key: "settings", icon: SettingsIcon, adminOnly: true },
+    // Module-contributed entries (present only for installed modules).
+    ...moduleNavEntries,
+    { href: "/admin/settings", label: (t) => t.nav.settings, icon: SettingsIcon, adminOnly: true },
   ]);
   const visible = $derived(items.filter((item) => !item.adminOnly || user.role === "admin"));
 </script>
@@ -47,11 +48,11 @@
       <Sidebar.Menu>
         {#each visible as item (item.href)}
           <Sidebar.MenuItem>
-            <Sidebar.MenuButton isActive={page.url.pathname === item.href} tooltipContent={i18n.t.nav[item.key]}>
+            <Sidebar.MenuButton isActive={page.url.pathname === item.href} tooltipContent={item.label(i18n.t)}>
               {#snippet child({ props })}
                 <a href={item.href} {...props}>
                   <item.icon />
-                  <span>{i18n.t.nav[item.key]}</span>
+                  <span>{item.label(i18n.t)}</span>
                 </a>
               {/snippet}
             </Sidebar.MenuButton>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/i18n/messages.ts

@@ -307,6 +307,9 @@ const en = {
     verified: "Verified",
     unverified: "Unverified",
   },
+  // Modules add their i18n blocks here.
+  // podokit:begin:messages-en
+  // podokit:end:messages-en
 };
 
 export type Messages = typeof en;
@@ -610,6 +613,9 @@ const ko: Messages = {
     verified: "인증됨",
     unverified: "미인증",
   },
+  // Modules add their i18n blocks here.
+  // podokit:begin:messages-ko
+  // podokit:end:messages-ko
 };
 
 export const messages: Record<Locale, Messages> = { en, ko };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/admin/settings/+page.svelte

@@ -9,6 +9,7 @@
   import * as Dialog from "$lib/components/ui/dialog";
   import * as Tabs from "$lib/components/ui/tabs";
   import GeneralSettings from "./general-settings.svelte";
+  import { moduleSettingsSections } from "$lib/admin/registry.svelte";
   import { toast } from "svelte-sonner";
   import { api } from "$lib/api";
   import { getI18n } from "$lib/i18n";
@@ -226,6 +227,9 @@
     <Tabs.List>
       <Tabs.Trigger value="general">{i18n.t.general.tab}</Tabs.Trigger>
       <Tabs.Trigger value="auth">{i18n.t.settings.tab}</Tabs.Trigger>
+      {#each moduleSettingsSections as s (s.value)}
+        <Tabs.Trigger value={s.value}>{s.label(i18n.t)}</Tabs.Trigger>
+      {/each}
     </Tabs.List>
 
     <Tabs.Content value="general" class="mt-6">
@@ -247,6 +251,12 @@
         </section>
       {/each}
     </Tabs.Content>
+
+    {#each moduleSettingsSections as s (s.value)}
+      <Tabs.Content value={s.value} class="mt-6">
+        <s.component />
+      </Tabs.Content>
+    {/each}
   </Tabs.Root>
 </div>
 

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/+layout.server.ts

@@ -4,7 +4,17 @@ import { redirect } from "@sveltejs/kit";
 // "/" is a public landing page. Auth pages send signed-in users to /admin, and
 // the admin area requires a session. /maintenance is public so it renders while
 // the rest of the site is held back.
-const PUBLIC_PATHS = ["/", "/login", "/signup", "/forgot-password", "/reset-password", "/maintenance"];
+const PUBLIC_PATHS = [
+  "/",
+  "/login",
+  "/signup",
+  "/forgot-password",
+  "/reset-password",
+  "/maintenance",
+  // Modules add their public (no-session) page prefixes here.
+  // podokit:begin:public-paths
+  // podokit:end:public-paths
+];
 const AUTH_PATHS = ["/login", "/signup", "/forgot-password", "/reset-password"];
 
 function isPublic(pathname: string): boolean {

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -59,7 +59,7 @@
     "Set ADMIN_EMAILS in .env (comma-separated). Those emails become admins on sign-up.",
     "Re-run the auth migration to add the admin columns:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
     "Start the app (npm run dev), open /signup, register an ADMIN_EMAILS address, then sign in.",
-    "Admin pages: /dashboard/users (list, ban, set role, revoke sessions). Everyone: /dashboard/sessions, /dashboard/account.",
-    "Password reset: the reset link is logged to the API console in dev; wire a real mailer via emailAndPassword.sendResetPassword for production."
+    "Admin pages: /admin/users (list, ban, set role, revoke sessions). Everyone: /admin/sessions, /admin/account.",
+    "Password reset emails go through the mailer module (installed automatically with auth); in dev without SMTP they are logged to the API console. Configure SMTP in admin settings or via SMTP_* env for production."
   ]
 }

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

@@ -1,7 +1,7 @@
 {
   "name": "auth",
   "description": "Full authentication (better-auth): email/password, sessions, and \u2014 via config \u2014 OAuth and 2FA. Installs a global guard so the API is secure by default; health and /api/auth stay public.",
-  "requires": [],
+  "requires": ["mailer"],
   "targetApp": "api",
   "dependencies": {
     "@podosoft/podokit-auth": "^0.1.0",
@@ -9,14 +9,12 @@
     "better-auth": "^1.6.23",
     "@thallesp/nestjs-better-auth": "^2.7.0",
     "pg": "^8.12.0",
-    "nodemailer": "^7.0.9",
     "@better-auth/api-key": "^1.6.23",
     "@better-auth/passkey": "^1.6.23",
     "@better-auth/oauth-provider": "^1.6.23"
   },
   "devDependencies": {
-    "@types/pg": "^8.11.10",
-    "@types/nodemailer": "^7.0.4"
+    "@types/pg": "^8.11.10"
   },
   "env": [
     "# \u2500\u2500 Auth (better-auth) \u2014 the only required secrets \u2500\u2500",
@@ -32,10 +30,7 @@
     "# override (e.g. for secrets-manager injection in production); the DB takes",
     "# precedence when set.",
     "# --- Optional overrides / local development ---",
-    "# Email (Mailpit in local dev: docker compose --profile dev up \u2192 http://localhost:8025)",
-    "# SMTP_HOST=localhost",
-    "# SMTP_PORT=1025",
-    "# MAIL_FROM=PodoKit <no-reply@example.com>",
+    "# Email/SMTP is provided by the mailer module (see its .env block).",
     "# Phone-number SMS webhook (dev: SMS sink on port 8095)",
     "# SMS_WEBHOOK_URL=http://localhost:8095/sms",
     "# AUTH_HIBP=false",

package/dist/templates/modules/mailer/files/apps/api/src/mail/db.ts

@@ -0,0 +1,13 @@
+import { Pool } from "pg";
+
+// The mailer's own pg pool, in its own module so the mailer stays independent of
+// any other module. Used only to read the optional admin-configured SMTP settings
+// from `auth_config` when the auth module is present; with no such table the read
+// fails softly and the mailer falls back to SMTP_* env (see mailer.ts).
+export const pool = new Pool({
+  host: process.env.POSTGRES_HOST ?? "localhost",
+  port: Number(process.env.POSTGRES_PORT ?? 5432),
+  user: process.env.POSTGRES_USER ?? "podokit",
+  password: process.env.POSTGRES_PASSWORD ?? "podokit",
+  database: process.env.POSTGRES_DB ?? "podokit",
+});

package/dist/templates/modules/{auth → mailer}/files/apps/api/src/mail/mailer.ts

@@ -1,14 +1,40 @@
 import nodemailer, { type Transporter } from "nodemailer";
-import { pool } from "../auth/db";
+import { pool } from "./db";
 import { createConfigStore, type SmtpConfig } from "@podosoft/podokit-auth";
 
-// SMTP is admin-configurable in the DB (auth_config), falling back to SMTP_* env,
-// and applied live: the transport is rebuilt when the config changes (short TTL),
-// so no restart is needed. With neither DB nor env config, fall back to a transport
-// that just logs the message so nothing crashes for lack of mail config.
+// Reusable email sending. SMTP is resolved in priority order, applied live (short
+// TTL) so no restart is needed:
+//   1. admin-configured DB settings (auth_config) — only when the auth module is
+//      installed; read via the config store, which decrypts the SMTP password;
+//   2. SMTP_* env (fallback / production secrets-manager injection);
+//   3. none → a JSON transport that logs the message so dev links are grabbable.
+// The whole transport can also be overridden from app code (setMailTransport),
+// e.g. from apps/api/src/app.extensions.ts, to plug in a provider SDK.
 const store = createConfigStore(pool);
 const TTL_MS = 3_000;
 
+function envSmtp(): SmtpConfig | null {
+  if (!process.env.SMTP_HOST) return null;
+  return {
+    host: process.env.SMTP_HOST,
+    port: Number(process.env.SMTP_PORT ?? 1025),
+    secure: process.env.SMTP_SECURE === "true",
+    user: process.env.SMTP_USER,
+    pass: process.env.SMTP_PASS,
+    from: process.env.MAIL_FROM,
+  };
+}
+
+async function resolveSmtp(): Promise<SmtpConfig | null> {
+  try {
+    // Reads auth_config and falls back to env internally when auth is installed.
+    return await store.smtpConfig();
+  } catch {
+    // No auth_config table (auth not installed) — use env directly.
+    return envSmtp();
+  }
+}
+
 function buildTransport(smtp: SmtpConfig | null): Transporter {
   if (!smtp) return nodemailer.createTransport({ jsonTransport: true });
   return nodemailer.createTransport({
@@ -24,12 +50,20 @@ let transportFrom = process.env.MAIL_FROM ?? "PodoKit <no-reply@example.com>";
 let hasSmtp = false;
 let checkedAt = 0;
 let signature = "";
+let override: Transporter | null = null;
+
+/** Override the transport from app code (e.g. a provider SDK). Pass null to
+ *  restore the config-driven transport. Set this from app.extensions.ts. */
+export function setMailTransport(custom: Transporter | null): void {
+  override = custom;
+}
 
 async function getTransport(): Promise<Transporter> {
+  if (override) return override;
   if (checkedAt !== 0 && Date.now() - checkedAt < TTL_MS) return transport;
   checkedAt = Date.now();
   try {
-    const smtp = await store.smtpConfig();
+    const smtp = await resolveSmtp();
     const next = JSON.stringify(smtp ?? null);
     if (next !== signature) {
       transport = buildTransport(smtp);
@@ -48,7 +82,7 @@ export type Mail = { to: string; subject: string; text: string; html?: string };
 export async function sendMail(mail: Mail): Promise<void> {
   const t = await getTransport();
   const info = await t.sendMail({ from: transportFrom, ...mail });
-  if (!hasSmtp) {
+  if (!override && !hasSmtp) {
     // JSON transport: surface the message so the link is grabbable from logs.
     console.log(`[mailer] no SMTP configured; message not delivered:\n${info.message as string}`);
   }

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

@@ -0,0 +1,38 @@
+{
+  "name": "mailer",
+  "description": "Reusable email sending (nodemailer). Resolves SMTP from the admin-configured DB settings when auth is installed, else SMTP_* env, else logs to the console. Used by auth and contact-form; the transport is overridable from app.extensions.ts.",
+  "requires": [],
+  "targetApp": "api",
+  "dependencies": {
+    "nodemailer": "^7.0.9",
+    "@podosoft/podokit-auth": "^0.1.0",
+    "pg": "^8.12.0"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^7.0.4",
+    "@types/pg": "^8.11.10"
+  },
+  "env": [
+    "# ── Mailer (SMTP) — optional ──",
+    "# With auth installed, configure SMTP on the admin Settings page (stored",
+    "# encrypted in the DB, applied live). These env vars are a fallback/override;",
+    "# with no SMTP configured at all the mailer logs messages to the console.",
+    "# Local dev uses Mailpit: docker compose --profile dev up → http://localhost:8025",
+    "# SMTP_HOST=localhost",
+    "# SMTP_PORT=1025",
+    "# MAIL_FROM=PodoKit <no-reply@example.com>"
+  ],
+  "inject": [
+    {
+      "file": "AGENTS.md",
+      "marker": "<!-- podokit:end:agents-modules -->",
+      "optional": true,
+      "text": "### mailer\n- Send email with `import { sendMail, actionEmail } from \"../mail/mailer\"` (path relative to your file). `sendMail({ to, subject, text, html? })`.\n- SMTP comes from the admin Settings page (when auth is installed) or `SMTP_*` env; with neither, messages are logged to the console (dev links are grabbable from logs).\n- To use a provider SDK instead of SMTP, call `setMailTransport(...)` from `apps/api/src/app.extensions.ts`.\n"
+    }
+  ],
+  "instructions": [
+    "Send mail from anywhere in the API:  import { sendMail } from \"../mail/mailer\"  then  await sendMail({ to, subject, text }).",
+    "SMTP is optional: with auth installed, configure it on the admin Settings page (DB, applied live); otherwise set SMTP_HOST/SMTP_PORT/MAIL_FROM in .env. With none set, messages are logged to the console.",
+    "To send through a provider SDK, override the transport in apps/api/src/app.extensions.ts:  import { setMailTransport } from \"./mail/mailer\";  setMailTransport(myTransport)."
+  ]
+}

package/dist/templates/todo/AGENTS.md

@@ -60,7 +60,7 @@ changes need an e2e/unit test.
 This project is managed by the `podo` CLI. Files have an ownership tier recorded
 in `.podokit/files.lock` — respect it:
 
-- **owned** (your code: `apps/web/src/routes/**`, your components/services, and this `AGENTS.md`) — edit freely.
+- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. To add or override Nest providers/modules, use `app.extensions.ts` (spread into `AppModule` after the module-wired providers, so a same-token override wins) rather than editing `app.module.ts`.
 - **assembled** (e.g. `apps/api/src/app.module.ts`, `auth.ts`) — contain `// podokit:begin:… / …:end` fenced regions that the toolkit recomputes. Edit outside the fences only; **never hand-edit inside the fences**.
 - **managed** (bootstrap/config like `main.ts`) — the toolkit may update these; avoid gratuitous edits.
 

package/dist/templates/todo/apps/api/src/app.extensions.ts

@@ -0,0 +1,21 @@
+import type { DynamicModule, Provider, Type } from "@nestjs/common";
+
+// Owned extension slot for the Nest app. This file is yours — PodoKit never
+// writes to it, so `podo update` leaves it alone. Use it to add your own modules
+// or providers, or to override a PodoKit-provided provider without editing
+// managed code. Because these are spread in *after* the module-wired providers,
+// an override here takes precedence.
+//
+// Example — override a provider with your own implementation:
+//   import { SomeService } from "./some/some.service";
+//   import { MyService } from "./my-service";
+//   export const extensionProviders: Provider[] = [
+//     { provide: SomeService, useClass: MyService },
+//   ];
+
+/** Extra modules to import into AppModule (or DynamicModule overrides). */
+export const extensionImports: (Type | DynamicModule)[] = [];
+
+/** Extra or overriding providers for AppModule. Same-token providers listed here
+ *  win over the ones PodoKit modules registered. */
+export const extensionProviders: Provider[] = [];

package/dist/templates/todo/apps/api/src/app.module.ts

@@ -5,6 +5,7 @@ import { validateEnv } from "./config/env.validation";
 import { dataSourceOptions } from "./database/data-source";
 import { HealthModule } from "./health/health.module";
 import { TodosModule } from "./todos/todos.module";
+import { extensionImports, extensionProviders } from "./app.extensions";
 // podokit:begin:imports
 // podokit:end:imports
 
@@ -16,10 +17,12 @@ import { TodosModule } from "./todos/todos.module";
     TodosModule,
     // podokit:begin:module-imports
     // podokit:end:module-imports
+    ...extensionImports,
   ],
   providers: [
     // podokit:begin:providers
     // podokit:end:providers
+    ...extensionProviders,
   ],
 })
 export class AppModule {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "An opinionated but extensible starter toolkit and CLI for full-stack TypeScript apps with NestJS, SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {