@podosoft/podokit 0.14.0 → 0.16.0

package/dist/dev.d.ts

@@ -20,6 +20,7 @@ export type CommandRunner = (command: string, args: string[], options: {
 }) => CommandResult;
 export declare function readDevConfig(projectRoot: string): DevConfig;
 export declare function resolveDevRuntime(projectRoot: string): DevRuntime;
+export declare function installedDevProfiles(projectRoot: string): string[];
 export declare function renderRuntimeCompose(runtime: DevRuntime): string;
 export declare function renderRoute(runtime: DevRuntime): string;
 export declare function runDevCommand(projectRoot: string, action: string | undefined, args: string[], runner?: CommandRunner): void;

package/dist/dev.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readDevConfig = readDevConfig;
 exports.resolveDevRuntime = resolveDevRuntime;
+exports.installedDevProfiles = installedDevProfiles;
 exports.renderRuntimeCompose = renderRuntimeCompose;
 exports.renderRoute = renderRoute;
 exports.runDevCommand = runDevCommand;
@@ -17,6 +18,11 @@ const GATEWAY_LABEL = "io.podosoft.podokit.dev-gateway";
 const GATEWAY_NETWORK = "podokit-dev-gateway";
 const RUNTIME_COMPOSE = ".podokit/runtime/dev.compose.yaml";
 const DEV_CONFIG = ".podokit/dev.json";
+const DEV_PROFILE_BY_MODULE = new Map([
+    ["redis", "cache"],
+    ["object-storage-s3", "storage"],
+    ["bullmq", "queue"],
+]);
 function defaultRunner(command, args, options) {
     const result = (0, node_child_process_1.spawnSync)(command, args, {
         encoding: "utf8",
@@ -96,6 +102,16 @@ function resolveDevRuntime(projectRoot) {
         runtimeComposePath: (0, node_path_1.join)(root, RUNTIME_COMPOSE),
     };
 }
+function installedDevProfiles(projectRoot) {
+    const manifest = (0, lockfile_1.readManifest)(projectRoot);
+    if (!manifest)
+        return [];
+    return [
+        ...new Set(manifest.modules
+            .map((module) => DEV_PROFILE_BY_MODULE.get(module.name))
+            .filter((profile) => profile !== undefined)),
+    ];
+}
 function renderRuntimeCompose(runtime) {
     return `# Generated by podo dev. Do not edit.\nservices:\n  traefik:\n    profiles: [podokit-legacy-proxy]\n  web:\n    networks:\n      ${GATEWAY_NETWORK}:\n        aliases: [${runtime.alias}]\nnetworks:\n  ${GATEWAY_NETWORK}:\n    external: true\n    name: ${GATEWAY_NETWORK}\n`;
 }
@@ -226,9 +242,10 @@ function runCompose(runtime, args, runner) {
         throw new Error(`docker compose ${args.join(" ")} exited with status ${String(result.status)}.`);
     }
 }
-function composeCommand(action, args) {
+function composeCommand(action, args, installedProfiles) {
     const global = [];
     const command = [];
+    const explicitProfiles = new Set();
     for (let index = 0; index < args.length; index += 1) {
         const value = args[index];
         if (value === undefined)
@@ -238,16 +255,22 @@ function composeCommand(action, args) {
             if (!profile)
                 throw new Error("--profile requires a value.");
             global.push(value, profile);
+            explicitProfiles.add(profile);
             index += 1;
         }
         else if (value.startsWith("--profile=")) {
             global.push(value);
+            explicitProfiles.add(value.slice("--profile=".length));
         }
         else {
             command.push(value);
         }
     }
-    const activeProfiles = action === "down" ? ["--profile", "*"] : [];
+    const activeProfiles = action === "down"
+        ? ["--profile", "*"]
+        : installedProfiles
+            .filter((profile) => !explicitProfiles.has(profile))
+            .flatMap((profile) => ["--profile", profile]);
     return [...activeProfiles, ...global, action, ...command];
 }
 function stopGatewayWhenUnused(runner) {
@@ -258,6 +281,7 @@ function stopGatewayWhenUnused(runner) {
 }
 function runDevCommand(projectRoot, action, args, runner = defaultRunner) {
     const runtime = resolveDevRuntime(projectRoot);
+    const profiles = installedDevProfiles(projectRoot);
     writeRuntimeFiles(runtime);
     if (action === "url") {
         process.stdout.write(`http://${runtime.config.hostname}\n`);
@@ -274,7 +298,7 @@ function runDevCommand(projectRoot, action, args, runner = defaultRunner) {
             process.stdout.write(`Development URL: http://${runtime.config.hostname}\n`);
             if (runtime.config.publicUrl)
                 process.stdout.write(`Public OAuth URL: ${runtime.config.publicUrl}\n`);
-            runCompose(runtime, composeCommand("watch", args), runner);
+            runCompose(runtime, composeCommand("watch", args, profiles), runner);
         }
         catch (error) {
             unregisterRoute(runtime);
@@ -284,13 +308,13 @@ function runDevCommand(projectRoot, action, args, runner = defaultRunner) {
         return;
     }
     if (action === "down") {
-        runCompose(runtime, composeCommand("down", args), runner);
+        runCompose(runtime, composeCommand("down", args, profiles), runner);
         unregisterRoute(runtime);
         stopGatewayWhenUnused(runner);
         return;
     }
     if (action === "exec" || action === "logs" || action === "ps") {
-        runCompose(runtime, composeCommand(action, args), runner);
+        runCompose(runtime, composeCommand(action, args, profiles), runner);
         return;
     }
     throw new Error("Usage: podo dev <watch|exec|logs|ps|down|url> [docker compose options]");

package/dist/index.d.ts

@@ -16,6 +16,14 @@ interface ParsedArgs {
     positionals: string[];
     localeName?: string;
     localeDirection?: LocaleDirection;
+    profile?: string;
+    release?: string;
+    confirm?: string;
+    revision?: number;
+    context?: string;
+    clusterFingerprint?: string;
+    host?: string;
+    json: boolean;
 }
 export declare function parseArgs(argv: string[]): ParsedArgs;
 export {};

package/dist/index.js

@@ -14,6 +14,9 @@ const update_1 = require("./update");
 const eject_1 = require("./eject");
 const dev_1 = require("./dev");
 const locale_1 = require("./locale");
+const deploy_1 = require("./deploy");
+const deploy_profile_1 = require("./deploy-profile");
+const deploy_render_1 = require("./deploy-render");
 const HELP = `podo — PodoKit project generator
 
 Usage:
@@ -24,6 +27,7 @@ Usage:
   podo diff                List PodoKit-managed files you have edited
   podo doctor              Check framework versions against supported ranges
   podo dev <action> [...]  Run the shared, portless container development gateway
+  podo deploy <action>     Plan, apply, verify, or roll back a Kubernetes deployment
   podo locale <command>    Add, validate, activate, or list JSON locales
   podo update [--apply]    Preview (or apply) what a version update would change
   podo eject <path...>     Take ownership of managed files (update skips them)
@@ -34,6 +38,14 @@ Options:
   --pm <name>    Package manager: npm | pnpm | yarn (default: npm)
   --name <label> Display name for a locale
   --direction <direction>  Text direction: ltr | rtl (default: ltr)
+  --profile <name>         Deployment profile name
+  --release <tag>          Immutable shared API/web release tag
+  --confirm <plan-hash>    Exact deployment or rollback plan hash
+  --revision <number>      Helm revision for rollback
+  --context <name>         Explicit Kubernetes context for profile initialization
+  --cluster-fingerprint <sha256:...>  Expected cluster fingerprint (auto-detected if omitted)
+  --host <hostname>        Public hostname for profile initialization
+  --json                   Emit machine-readable JSON when supported
   --adopt        Adopt colliding paths explicitly declared managed by a module
   --no-ai        Skip AI agent guidance (AGENTS.md, CLAUDE.md, editor rules)
   -y, --yes      Skip prompts and accept defaults
@@ -47,6 +59,22 @@ Example:
   npx @podosoft/podokit create my-app --template todo
   cd my-app && npx @podosoft/podokit add auth
 `;
+const DEPLOY_HELP = `podo deploy — Kubernetes and Helm deployment workflow
+
+Usage:
+  podo deploy init --profile <name> --context <context> [--host <hostname>]
+  podo deploy doctor --profile <name> [--json]
+  podo deploy render --profile <name> --release <tag> [--json]
+  podo deploy plan --profile <name> --release <tag> [--json]
+  podo deploy apply --profile <name> --release <tag> --confirm <plan-hash>
+  podo deploy status --profile <name> [--json]
+  podo deploy verify --profile <name> [--json]
+  podo deploy rollback --profile <name> --revision <number> [--confirm <plan-hash>]
+
+The namespace, referenced Secrets, ingress controller, and storage classes must
+already exist. Plan and rollback require access to the profile's exact cluster.
+Apply and rollback require confirmation of the exact plan hash.
+`;
 function parseArgs(argv) {
     const parsed = {
         help: false,
@@ -54,6 +82,7 @@ function parseArgs(argv) {
         apply: false,
         adopt: false,
         ai: true,
+        json: false,
         positionals: [],
     };
     const positionals = [];
@@ -96,6 +125,34 @@ function parseArgs(argv) {
             }
             parsed.localeDirection = direction;
         }
+        else if (arg === "--profile") {
+            parsed.profile = argv[++i];
+        }
+        else if (arg === "--release") {
+            parsed.release = argv[++i];
+        }
+        else if (arg === "--confirm") {
+            parsed.confirm = argv[++i];
+        }
+        else if (arg === "--revision") {
+            const revision = Number(argv[++i]);
+            if (!Number.isInteger(revision) || revision < 1) {
+                throw new Error("--revision must be a positive integer.");
+            }
+            parsed.revision = revision;
+        }
+        else if (arg === "--context") {
+            parsed.context = argv[++i];
+        }
+        else if (arg === "--cluster-fingerprint") {
+            parsed.clusterFingerprint = argv[++i];
+        }
+        else if (arg === "--host") {
+            parsed.host = argv[++i];
+        }
+        else if (arg === "--json") {
+            parsed.json = true;
+        }
         else if (arg !== undefined && !arg.startsWith("-")) {
             positionals.push(arg);
         }
@@ -112,7 +169,7 @@ function fail(message) {
 async function main(argv) {
     const args = parseArgs(argv);
     if (args.help || !args.command) {
-        process.stdout.write(HELP);
+        process.stdout.write(args.help && args.command === "deploy" ? DEPLOY_HELP : HELP);
         return;
     }
     const modulesDir = (0, node_path_1.join)(__dirname, "templates", "modules");
@@ -236,6 +293,95 @@ async function main(argv) {
         }
         return;
     }
+    if (args.command === "deploy") {
+        const action = args.positionals[1] ?? "status";
+        const profileName = args.profile;
+        if (!profileName) {
+            fail("Deployment commands require --profile <name>.");
+        }
+        try {
+            if (action === "init") {
+                if (!args.context) {
+                    fail("Usage: podo deploy init --profile <name> --context <context> [--host <hostname>].");
+                }
+                const clusterFingerprint = args.clusterFingerprint ?? (0, deploy_1.inspectClusterFingerprint)(args.context);
+                const initialized = (0, deploy_profile_1.initializeDeploymentProfile)(process.cwd(), profileName, {
+                    context: args.context,
+                    clusterFingerprint,
+                    host: args.host,
+                });
+                process.stdout.write(args.json
+                    ? `${JSON.stringify(initialized, null, 2)}\n`
+                    : `Created deployment profile ${initialized.name} at ${initialized.path}.\n`);
+                return;
+            }
+            if (action === "doctor") {
+                const findings = (0, deploy_1.doctorDeployment)(process.cwd(), profileName);
+                process.stdout.write(args.json
+                    ? `${JSON.stringify(findings, null, 2)}\n`
+                    : `${findings.map((finding) => `${finding.ok ? "ok  " : "FAIL"} ${finding.message}`).join("\n")}\n`);
+                if (findings.some((finding) => !finding.ok))
+                    process.exitCode = 1;
+                return;
+            }
+            if (action === "render") {
+                if (!args.release)
+                    fail("podo deploy render requires --release <tag>.");
+                const profile = (0, deploy_profile_1.loadDeploymentProfile)(process.cwd(), profileName);
+                const plan = (0, deploy_1.planDeployment)(process.cwd(), profileName, args.release);
+                const runtime = (0, deploy_render_1.renderDeployment)(process.cwd(), profileName, profile, args.release, plan.images, plan.rolloutStateDigest);
+                process.stdout.write(args.json
+                    ? `${JSON.stringify({ plan, runtime }, null, 2)}\n`
+                    : `Rendered deployment into ${runtime.root}.\nPlan hash: ${plan.planHash}\n`);
+                return;
+            }
+            if (action === "plan") {
+                if (!args.release)
+                    fail("podo deploy plan requires --release <tag>.");
+                const plan = (0, deploy_1.planDeployment)(process.cwd(), profileName, args.release);
+                process.stdout.write(args.json
+                    ? `${JSON.stringify(plan, null, 2)}\n`
+                    : `${plan.actions.map((entry) => `${entry.order}. ${entry.description}`).join("\n")}\nPlan hash: ${plan.planHash}\n`);
+                return;
+            }
+            if (action === "apply") {
+                if (!args.release || !args.confirm) {
+                    fail("podo deploy apply requires --release <tag> --confirm <plan-hash>.");
+                }
+                const result = await (0, deploy_1.applyDeployment)(process.cwd(), profileName, args.release, args.confirm);
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            if (action === "status") {
+                const result = (0, deploy_1.getDeploymentStatus)(process.cwd(), profileName);
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            if (action === "verify") {
+                const result = await (0, deploy_1.verifyDeployment)(process.cwd(), profileName);
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                if (!result.ok)
+                    process.exitCode = 1;
+                return;
+            }
+            if (action === "rollback") {
+                if (!args.revision)
+                    fail("podo deploy rollback requires --revision <number>.");
+                if (!args.confirm) {
+                    const plan = (0, deploy_1.planRollback)(process.cwd(), profileName, args.revision);
+                    process.stdout.write(`${JSON.stringify(plan, null, 2)}\nRe-run with --confirm ${plan.planHash}.\n`);
+                    return;
+                }
+                const result = await (0, deploy_1.rollbackDeployment)(process.cwd(), profileName, args.revision, args.confirm);
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            fail(`Unknown deploy command "${action}". Use init, doctor, render, plan, apply, status, verify, or rollback.`);
+        }
+        catch (err) {
+            fail(err.message);
+        }
+    }
     if (args.command === "locale") {
         const action = args.positionals[1] ?? "list";
         const code = args.positionals[2];

package/dist/lib.d.ts

@@ -10,6 +10,12 @@ export { planUpdate, summarize } from "./update";
 export type { UpdatePlan, FileChange } from "./update";
 export { readDevConfig, renderRoute, renderRuntimeCompose, resolveDevRuntime, runDevCommand } from "./dev";
 export type { CommandRunner, DevConfig, DevRuntime } from "./dev";
+export { applyDeployment, doctorDeployment, getDeploymentStatus, inspectClusterFingerprint, planDeployment, planRollback, rollbackDeployment, verifyDeployment, } from "./deploy";
+export type { DeploymentDoctorFinding, DeploymentPlan, DeploymentPlanAction, DeploymentStatus, VerificationResult, } from "./deploy";
+export { assertReleaseTag, deploymentProfileDigest, initializeDeploymentProfile, listDeploymentProfiles, loadDeploymentProfile, } from "./deploy-profile";
+export type { DependencyMode, DeployProfileV1, DeploymentProfileSummary, InitializeDeploymentProfileOptions, ObjectStorageDependencyProfile, RedisDependencyProfile, ResourceProfile, StatefulDependencyProfile, WorkloadProfile, } from "./deploy-profile";
+export { renderDeployment } from "./deploy-render";
+export type { DeploymentRuntime } from "./deploy-render";
 /** Absolute path to the templates bundled in this installed package. */
 export declare function builtinTemplatesDir(): string;
 /** Absolute path to the modules bundled in this installed package. */

package/dist/lib.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runDevCommand = exports.resolveDevRuntime = exports.renderRuntimeCompose = exports.renderRoute = exports.readDevConfig = exports.summarize = exports.planUpdate = exports.SUPPORTED_FRAMEWORKS = exports.doctor = exports.diff = exports.status = exports.addModule = exports.listModules = exports.isKnownTemplate = exports.TEMPLATE_NAMES = exports.DEFAULT_TEMPLATE = exports.TEMPLATES = exports.create = void 0;
+exports.renderDeployment = exports.loadDeploymentProfile = exports.listDeploymentProfiles = exports.initializeDeploymentProfile = exports.deploymentProfileDigest = exports.assertReleaseTag = exports.verifyDeployment = exports.rollbackDeployment = exports.planRollback = exports.planDeployment = exports.inspectClusterFingerprint = exports.getDeploymentStatus = exports.doctorDeployment = exports.applyDeployment = exports.runDevCommand = exports.resolveDevRuntime = exports.renderRuntimeCompose = exports.renderRoute = exports.readDevConfig = exports.summarize = exports.planUpdate = exports.SUPPORTED_FRAMEWORKS = exports.doctor = exports.diff = exports.status = exports.addModule = exports.listModules = exports.isKnownTemplate = exports.TEMPLATE_NAMES = exports.DEFAULT_TEMPLATE = exports.TEMPLATES = exports.create = void 0;
 exports.builtinTemplatesDir = builtinTemplatesDir;
 exports.builtinModulesDir = builtinModulesDir;
 // Library entry point: the reusable functions behind the `podo` CLI, for other
@@ -30,6 +30,23 @@ Object.defineProperty(exports, "renderRoute", { enumerable: true, get: function
 Object.defineProperty(exports, "renderRuntimeCompose", { enumerable: true, get: function () { return dev_1.renderRuntimeCompose; } });
 Object.defineProperty(exports, "resolveDevRuntime", { enumerable: true, get: function () { return dev_1.resolveDevRuntime; } });
 Object.defineProperty(exports, "runDevCommand", { enumerable: true, get: function () { return dev_1.runDevCommand; } });
+var deploy_1 = require("./deploy");
+Object.defineProperty(exports, "applyDeployment", { enumerable: true, get: function () { return deploy_1.applyDeployment; } });
+Object.defineProperty(exports, "doctorDeployment", { enumerable: true, get: function () { return deploy_1.doctorDeployment; } });
+Object.defineProperty(exports, "getDeploymentStatus", { enumerable: true, get: function () { return deploy_1.getDeploymentStatus; } });
+Object.defineProperty(exports, "inspectClusterFingerprint", { enumerable: true, get: function () { return deploy_1.inspectClusterFingerprint; } });
+Object.defineProperty(exports, "planDeployment", { enumerable: true, get: function () { return deploy_1.planDeployment; } });
+Object.defineProperty(exports, "planRollback", { enumerable: true, get: function () { return deploy_1.planRollback; } });
+Object.defineProperty(exports, "rollbackDeployment", { enumerable: true, get: function () { return deploy_1.rollbackDeployment; } });
+Object.defineProperty(exports, "verifyDeployment", { enumerable: true, get: function () { return deploy_1.verifyDeployment; } });
+var deploy_profile_1 = require("./deploy-profile");
+Object.defineProperty(exports, "assertReleaseTag", { enumerable: true, get: function () { return deploy_profile_1.assertReleaseTag; } });
+Object.defineProperty(exports, "deploymentProfileDigest", { enumerable: true, get: function () { return deploy_profile_1.deploymentProfileDigest; } });
+Object.defineProperty(exports, "initializeDeploymentProfile", { enumerable: true, get: function () { return deploy_profile_1.initializeDeploymentProfile; } });
+Object.defineProperty(exports, "listDeploymentProfiles", { enumerable: true, get: function () { return deploy_profile_1.listDeploymentProfiles; } });
+Object.defineProperty(exports, "loadDeploymentProfile", { enumerable: true, get: function () { return deploy_profile_1.loadDeploymentProfile; } });
+var deploy_render_1 = require("./deploy-render");
+Object.defineProperty(exports, "renderDeployment", { enumerable: true, get: function () { return deploy_render_1.renderDeployment; } });
 /** Absolute path to the templates bundled in this installed package. */
 function builtinTemplatesDir() {
     return (0, node_path_1.join)(__dirname, "templates");

package/dist/lockfile.js

@@ -53,6 +53,7 @@ exports.DEFAULT_OWNED_GLOBS = [
     // AI agent guidance — yours to customize; update never touches it.
     "AGENTS.md",
     "CLAUDE.md",
+    ".agents/**",
     ".claude/**",
     ".cursor/**",
     ".github/copilot-instructions.md",
@@ -66,6 +67,8 @@ exports.DEFAULT_OWNED_GLOBS = [
     ".env.docker",
     "infra/traefik/**",
     ".podokit/dev.json",
+    // Optional application-owned Playwright device/browser projects.
+    "tests/playwright.projects.cjs",
 ];
 const TEXT_EXT = /\.(json|md|ts|tsx|js|mjs|cjs|css|html|yml|yaml|txt|env|svelte|gitignore|example)$/i;
 function podokitDir(projectRoot) {

package/dist/remove.js

@@ -110,6 +110,13 @@ function removeModule(options) {
     const sharedManagedOverrides = new Set(others.flatMap((other) => other.manifest.managedOverrides ?? []));
     const targetManagedOverrides = new Set(targetManifest.managedOverrides ?? []);
     manifest.managedOverrides = (manifest.managedOverrides ?? []).filter((glob) => !targetManagedOverrides.has(glob) || sharedManagedOverrides.has(glob));
+    const defaultOwnedGlobs = new Set(lockfile_1.DEFAULT_OWNED_GLOBS);
+    const sharedOwnedGlobs = new Set(others.flatMap((other) => other.manifest.ownedGlobs ?? []));
+    const targetOwnedGlobs = new Set(targetManifest.ownedGlobs ?? []);
+    manifest.ownedGlobs = manifest.ownedGlobs.filter((glob) => !targetOwnedGlobs.has(glob) ||
+        defaultOwnedGlobs.has(glob) ||
+        sharedOwnedGlobs.has(glob) ||
+        keptEdited.some((path) => (0, lockfile_1.matchGlob)(path, glob)));
     (0, lockfile_1.writeManifest)(projectRoot, manifest);
     (0, lockfile_1.writeFilesLock)(projectRoot, (0, lockfile_1.computeFilesLock)(projectRoot, manifest.ownedGlobs, manifest.managedOverrides));
     return { module, removed, keptEdited, keptShared, unwired };

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

@@ -69,6 +69,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 Kubernetes release. Use `.agents/skills/podokit-deploy`.
 
 ## Commit conventions
 

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

@@ -33,16 +33,17 @@ npx @podosoft/podokit dev exec api npm run migration:run -w {{projectName}}-api
 npx @podosoft/podokit dev down
 ```
 
-If installed modules require extra services, use their profiles on the initial
-watch command instead:
+`dev watch` reads `.podokit/manifest.json` and automatically activates `cache`,
+`storage`, and `queue` when installed modules require Redis, MinIO, or a worker.
+You can still activate an additional Compose profile explicitly:
 
 ```bash
-npx @podosoft/podokit dev watch \
-  --profile cache --profile storage --profile queue
+npx @podosoft/podokit dev watch --profile dev
 ```
 
-Pass the same profile flags to other lifecycle commands when applicable. `dev down`
-removes this project's stack and route. If it is the final registered
+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
+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.
 
@@ -79,8 +80,18 @@ stable HTTPS tunnel, see the PodoKit [development guide](https://github.com/podo
 
 ## Deploy
 
-Docker Compose in `infra/docker`; example k3s manifests in `infra/k3s`
-(use `secret.example.yaml` as a template — never commit real secrets).
+Docker Compose lives in `infra/docker`; the basic k3s manifests in `infra/k3s`
+route every public path through the web proxy. For a managed release on an
+existing cluster, initialize an application-owned profile:
+
+```bash
+npx @podosoft/podokit deploy init --profile production --context production --host app.example.com
+npx @podosoft/podokit deploy doctor --profile production
+npx @podosoft/podokit deploy plan --profile production --release v1.2.3
+```
+
+Use existing Kubernetes Secrets and never commit their values. See the PodoKit
+[deployment guide](https://github.com/podosoft-dev/podokit/blob/main/docs/deployment.md).
 
 Build production images from the workspace root so Docker can use the committed
 lockfile and all workspace package manifests:

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

@@ -16,12 +16,12 @@ RUN npm run build --workspace=apps/api
 FROM node:22-alpine AS runtime
 WORKDIR /app
 ENV NODE_ENV=production
-RUN addgroup -S app && adduser -S app -G app
+RUN addgroup -S -g 101 app && adduser -S -D -H -u 100 -G app app
 COPY --from=build /app/node_modules ./node_modules
 COPY --from=deps /app/apps/api ./apps/api
 COPY --from=build /app/apps/api/dist ./apps/api/dist
 COPY --from=build /app/apps/api/scripts ./apps/api/scripts
 WORKDIR /app/apps/api
-USER app
+USER 100:101
 EXPOSE 3000
 CMD ["node", "dist/main"]

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

@@ -8,6 +8,7 @@
     "start": "node dist/main",
     "lint": "tsc -p tsconfig.json --noEmit",
     "test": "jest --passWithNoTests",
+    "migrate:all": "node dist/database/migrate",
     "typeorm": "typeorm-ts-node-commonjs -d src/database/data-source.ts",
     "migration:run": "npm run typeorm -- migration:run",
     "migration:revert": "npm run typeorm -- migration:revert",

package/dist/templates/fullstack-nest-svelte/apps/api/src/config/redis.connection.spec.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "@jest/globals";
+import { redisConnectionOptions } from "./redis.connection";
+
+describe("redisConnectionOptions", () => {
+  it("prefers an authenticated URL over individual settings", () => {
+    expect(
+      redisConnectionOptions({
+        REDIS_URL: "rediss://user:p%40ss@cache.example.com:6381/4",
+        REDIS_HOST: "ignored",
+        REDIS_PASSWORD: "ignored",
+      }),
+    ).toEqual({
+      host: "cache.example.com",
+      port: 6381,
+      db: 4,
+      username: "user",
+      password: "p@ss",
+      tls: {},
+    });
+  });
+
+  it("uses authenticated host settings when a URL is absent", () => {
+    expect(
+      redisConnectionOptions({
+        REDIS_HOST: "cache",
+        REDIS_PORT: "6380",
+        REDIS_DB: "2",
+        REDIS_USERNAME: "app",
+        REDIS_PASSWORD: "secret",
+        REDIS_TLS: "true",
+      }),
+    ).toEqual({
+      host: "cache",
+      port: 6380,
+      db: 2,
+      username: "app",
+      password: "secret",
+      tls: {},
+    });
+  });
+
+  it("does not include a malformed URL value in its error", () => {
+    const secretUrl = "not-a-url-with-a-secret";
+    expect(() => redisConnectionOptions({ REDIS_URL: secretUrl })).toThrow(
+      "REDIS_URL must be a valid redis:// or rediss:// URL",
+    );
+    try {
+      redisConnectionOptions({ REDIS_URL: secretUrl });
+    } catch (error) {
+      expect(String(error)).not.toContain(secretUrl);
+    }
+  });
+});

package/dist/templates/fullstack-nest-svelte/apps/api/src/config/redis.connection.ts

@@ -0,0 +1,69 @@
+export interface RedisConnectionOptions {
+  host: string;
+  port: number;
+  db: number;
+  username?: string;
+  password?: string;
+  tls?: Record<string, never>;
+  lazyConnect?: boolean;
+  enableReadyCheck?: boolean;
+  enableOfflineQueue?: boolean;
+  maxRetriesPerRequest?: number | null;
+  connectTimeout?: number;
+  commandTimeout?: number;
+}
+
+function integer(name: string, value: string | undefined, fallback: number): number {
+  if (value === undefined || value === "") return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${name} must be a non-negative integer`);
+  }
+  return parsed;
+}
+
+function decoded(value: string, name: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    throw new Error(`${name} contains invalid percent encoding`);
+  }
+}
+
+function fromUrl(value: string): RedisConnectionOptions {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("REDIS_URL must be a valid redis:// or rediss:// URL");
+  }
+  if (url.protocol !== "redis:" && url.protocol !== "rediss:") {
+    throw new Error("REDIS_URL must use the redis:// or rediss:// protocol");
+  }
+  const dbPath = url.pathname.replace(/^\/+/, "");
+  return {
+    host: url.hostname || "localhost",
+    port: integer("REDIS_URL port", url.port, 6379),
+    db: integer("REDIS_URL database", dbPath, 0),
+    ...(url.username ? { username: decoded(url.username, "REDIS_URL username") } : {}),
+    ...(url.password ? { password: decoded(url.password, "REDIS_URL password") } : {}),
+    ...(url.protocol === "rediss:" ? { tls: {} } : {}),
+  };
+}
+
+export function redisConnectionOptions(
+  env: NodeJS.ProcessEnv = process.env,
+  overrides: Partial<RedisConnectionOptions> = {},
+): RedisConnectionOptions {
+  const base = env.REDIS_URL
+    ? fromUrl(env.REDIS_URL)
+    : {
+        host: env.REDIS_HOST ?? "localhost",
+        port: integer("REDIS_PORT", env.REDIS_PORT, 6379),
+        db: integer("REDIS_DB", env.REDIS_DB, 0),
+        ...(env.REDIS_USERNAME ? { username: env.REDIS_USERNAME } : {}),
+        ...(env.REDIS_PASSWORD ? { password: env.REDIS_PASSWORD } : {}),
+        ...(env.REDIS_TLS === "true" ? { tls: {} } : {}),
+      };
+  return { ...base, ...overrides };
+}

package/dist/templates/fullstack-nest-svelte/apps/api/src/database/migrate.ts

@@ -0,0 +1,16 @@
+import dataSource from "./data-source";
+
+async function migrate(): Promise<void> {
+  await dataSource.initialize();
+  try {
+    await dataSource.runMigrations({ transaction: "all" });
+  } finally {
+    await dataSource.destroy();
+  }
+}
+
+void migrate().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`Migration failed: ${message}\n`);
+  process.exitCode = 1;
+});