@podosoft/podokit 1.4.2 → 1.6.0

package/dist/deploy-schema.d.ts

@@ -1,3 +1,4 @@
+import type { AppProxyTimeout, AppProxyTimeouts } from "./app-proxy-timeouts";
 /**
  * Validation primitives shared by every deployment driver.
  *
@@ -30,6 +31,23 @@ export declare const SENSITIVE_KEY: RegExp;
 export declare const STABLE_SEMVER_TAG_PATTERN = "^v(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$";
 /** Keys PodoKit derives itself, so a profile may not set them. */
 export declare const MANAGED_RUNTIME_CONFIG_KEYS: string[];
+/**
+ * Keys that decide which forwarded address web and API record. They follow from
+ * the proxies in front of the deployment, so a profile states that one number and
+ * PodoKit renders the four values that agree with it.
+ */
+export declare const CLIENT_ADDRESS_KEYS: string[];
+export declare function parseEdgeProxies(exposure: Record<string, unknown>, fallback: number): number;
+/**
+ * What the web server and the API trust, given how many proxies each request to
+ * the web server has passed. Behind at least one, the web server takes its origin
+ * from X-Forwarded-Proto and X-Forwarded-Host and the client from the
+ * X-Forwarded-For entry the outermost trusted proxy wrote (XFF_DEPTH); with none
+ * it trusts no forwarded header. It forwards that one address to the API, so the
+ * API always trusts one hop: the web proxy, the Compose gateway, or an Ingress
+ * that trusts no proxy in front of it.
+ */
+export declare function proxyTrustConfig(webProxyHops: number, trustForwardedOrigin?: boolean): Record<string, string>;
 export declare function containsUrlCredentials(value: string): boolean;
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function assertOnlyKeys(value: Record<string, unknown>, allowed: string[], field: string): void;
@@ -50,6 +68,49 @@ export declare function validateImage(value: string, field: string): void;
 export declare function validateImageRepository(value: string, field: string): void;
 export declare function parseReleaseProfile(release: Record<string, unknown>): ReleaseProfile;
 export declare function parseRuntimeConfig(runtimeConfig: Record<string, unknown>): Record<string, string>;
+/**
+ * An application-owned PostgreSQL pool each API or worker process opens beside
+ * PodoKit's own: `sizeKey` names the runtimeConfig key that caps it, and
+ * `extraConnections` counts connections it opens beyond that cap, such as one to
+ * check a server that stopped answering.
+ */
+export interface AppConnectionPool {
+    sizeKey: string;
+    extraConnections: number;
+}
+/** What the connection budget needs to know about the database, beyond its mode. */
+export interface PostgresBudgetProfile {
+    /** The server's max_connections; PodoKit sets it on a database it runs. */
+    maxConnections?: number;
+    appPools?: AppConnectionPool[];
+}
+export declare function parsePostgresBudget(value: Record<string, unknown>, field: string, runtimeConfig: Record<string, string>): PostgresBudgetProfile;
+/** Bun closes silent connections on a 4-second tick, up to 4 seconds before their idle timeout. */
+export declare const IDLE_TICK_SECONDS = 4;
+export declare const MAX_IDLE_TIMEOUT_SECONDS = 255;
+export declare const IDLE_TIMEOUT_KEYS: readonly ["CONNECTION_IDLE_TIMEOUT", "API_IDLE_TIMEOUT"];
+/** The longest the /api proxy waits for response headers, and what sets it. */
+export interface LongestProxyWait {
+    /** Milliseconds, or null for a route without a deadline. */
+    timeoutMs: number | null;
+    source: string;
+}
+/**
+ * BACKEND_PROXY_TIMEOUT_MS, or the application's longest APP_PROXY_TIMEOUTS
+ * entry when that waits longer; an entry without a deadline wins outright.
+ */
+export declare function longestProxyWait(runtimeConfig: Record<string, string>, entries: AppProxyTimeout[]): LongestProxyWait;
+export declare function describeProxyWait(wait: LongestProxyWait): string;
+/** Whether an idle timeout keeps a silent connection open for the whole wait. */
+export declare function idleTimeoutCovers(seconds: number, wait: LongestProxyWait): boolean;
+/**
+ * The idle timeouts of the web server (CONNECTION_IDLE_TIMEOUT) and the API
+ * (API_IDLE_TIMEOUT), both run by Bun. Each is the profile's own value, or else
+ * the fewest seconds that keep a silent connection open past the /api proxy's
+ * longest wait: 35 for the default 30000 ms, and 0 (off) when an application
+ * route has no deadline.
+ */
+export declare function idleTimeoutConfig(runtimeConfig: Record<string, string>, proxyTimeouts: AppProxyTimeouts): Record<string, string>;
 export declare function validateHttpsOrigin(value: string): void;
 export declare function parseVerification(verification: Record<string, unknown>): VerificationProfile;
 export declare function profileDirectory(projectRoot: string): string;

package/dist/deploy-schema.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MANAGED_RUNTIME_CONFIG_KEYS = exports.STABLE_SEMVER_TAG_PATTERN = exports.SENSITIVE_KEY = exports.DNS_LABEL = exports.PROFILE_NAME = void 0;
+exports.IDLE_TIMEOUT_KEYS = exports.MAX_IDLE_TIMEOUT_SECONDS = exports.IDLE_TICK_SECONDS = exports.CLIENT_ADDRESS_KEYS = exports.MANAGED_RUNTIME_CONFIG_KEYS = exports.STABLE_SEMVER_TAG_PATTERN = exports.SENSITIVE_KEY = exports.DNS_LABEL = exports.PROFILE_NAME = void 0;
+exports.parseEdgeProxies = parseEdgeProxies;
+exports.proxyTrustConfig = proxyTrustConfig;
 exports.containsUrlCredentials = containsUrlCredentials;
 exports.isRecord = isRecord;
 exports.assertOnlyKeys = assertOnlyKeys;
@@ -17,6 +19,11 @@ exports.validateImage = validateImage;
 exports.validateImageRepository = validateImageRepository;
 exports.parseReleaseProfile = parseReleaseProfile;
 exports.parseRuntimeConfig = parseRuntimeConfig;
+exports.parsePostgresBudget = parsePostgresBudget;
+exports.longestProxyWait = longestProxyWait;
+exports.describeProxyWait = describeProxyWait;
+exports.idleTimeoutCovers = idleTimeoutCovers;
+exports.idleTimeoutConfig = idleTimeoutConfig;
 exports.validateHttpsOrigin = validateHttpsOrigin;
 exports.parseVerification = parseVerification;
 exports.profileDirectory = profileDirectory;
@@ -35,6 +42,43 @@ exports.MANAGED_RUNTIME_CONFIG_KEYS = [
     "PROTOCOL_HEADER",
     "HOST_HEADER",
 ];
+/**
+ * Keys that decide which forwarded address web and API record. They follow from
+ * the proxies in front of the deployment, so a profile states that one number and
+ * PodoKit renders the four values that agree with it.
+ */
+exports.CLIENT_ADDRESS_KEYS = ["ADDRESS_HEADER", "XFF_DEPTH", "TRUSTED_PROXY_HOPS", "TRUSTED_PROXY_HEADER"];
+/** Edge proxies are counted, not configured; more than this is a typo. */
+const MAX_EDGE_PROXIES = 8;
+function parseEdgeProxies(exposure, fallback) {
+    const value = exposure.edgeProxies ?? fallback;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > MAX_EDGE_PROXIES) {
+        throw new Error(`Deployment profile field "exposure.edgeProxies" must be an integer from 0 to ${MAX_EDGE_PROXIES}.`);
+    }
+    return value;
+}
+/**
+ * What the web server and the API trust, given how many proxies each request to
+ * the web server has passed. Behind at least one, the web server takes its origin
+ * from X-Forwarded-Proto and X-Forwarded-Host and the client from the
+ * X-Forwarded-For entry the outermost trusted proxy wrote (XFF_DEPTH); with none
+ * it trusts no forwarded header. It forwards that one address to the API, so the
+ * API always trusts one hop: the web proxy, the Compose gateway, or an Ingress
+ * that trusts no proxy in front of it.
+ */
+function proxyTrustConfig(webProxyHops, trustForwardedOrigin = webProxyHops > 0) {
+    return {
+        ...(trustForwardedOrigin ? { PROTOCOL_HEADER: "x-forwarded-proto", HOST_HEADER: "x-forwarded-host" } : {}),
+        ...(webProxyHops > 0 ? { ADDRESS_HEADER: "x-forwarded-for", XFF_DEPTH: String(webProxyHops) } : {}),
+        TRUSTED_PROXY_HOPS: "1",
+        TRUSTED_PROXY_HEADER: "x-forwarded-for",
+    };
+}
+/** Keys the generated API no longer reads; it refuses to start while they are set. */
+const RENAMED_RUNTIME_CONFIG_KEYS = {
+    RATE_LIMIT_TRUSTED_PROXY_HOPS: "TRUSTED_PROXY_HOPS",
+    RATE_LIMIT_PROXY_HEADER: "TRUSTED_PROXY_HEADER",
+};
 function containsUrlCredentials(value) {
     if (!value.includes("://"))
         return false;
@@ -183,6 +227,14 @@ function parseRuntimeConfig(runtimeConfig) {
         if (exports.MANAGED_RUNTIME_CONFIG_KEYS.includes(key)) {
             throw new Error(`Deployment runtimeConfig key "${key}" is managed by PodoKit.`);
         }
+        if (exports.CLIENT_ADDRESS_KEYS.includes(key)) {
+            throw new Error(`Deployment runtimeConfig key "${key}" is derived from exposure.edgeProxies, the number of reverse ` +
+                "proxies in front of the deployment; remove it and set exposure.edgeProxies instead.");
+        }
+        const renamed = RENAMED_RUNTIME_CONFIG_KEYS[key];
+        if (renamed) {
+            throw new Error(`Deployment runtimeConfig key "${key}" was renamed to "${renamed}".`);
+        }
         if (typeof entry !== "string") {
             throw new Error(`Deployment runtimeConfig value "${key}" must be a string.`);
         }
@@ -193,6 +245,110 @@ function parseRuntimeConfig(runtimeConfig) {
     }
     return parsed;
 }
+/** PostgreSQL's own ceiling for max_connections. */
+const MAX_POSTGRES_CONNECTIONS = 262_143;
+/** Pools whose sizes the connection budget already reads. */
+const PODOKIT_POOL_KEYS = ["DB_POOL_MAX", "DB_AUTH_POOL_MAX"];
+function parsePostgresBudget(value, field, runtimeConfig) {
+    const parsed = {};
+    if (value.maxConnections !== undefined) {
+        const maxConnections = value.maxConnections;
+        if (typeof maxConnections !== "number" ||
+            !Number.isInteger(maxConnections) ||
+            maxConnections < 4 ||
+            maxConnections > MAX_POSTGRES_CONNECTIONS) {
+            throw new Error(`Deployment profile field "${field}.maxConnections" must be an integer from 4 to ${MAX_POSTGRES_CONNECTIONS}.`);
+        }
+        parsed.maxConnections = maxConnections;
+    }
+    if (value.appPools !== undefined) {
+        if (!Array.isArray(value.appPools)) {
+            throw new Error(`Deployment profile field "${field}.appPools" must be an array.`);
+        }
+        const seen = new Set();
+        parsed.appPools = value.appPools.map((entry, index) => {
+            const entryField = `${field}.appPools[${index}]`;
+            if (!isRecord(entry))
+                throw new Error(`Deployment profile field "${entryField}" must be an object.`);
+            assertOnlyKeys(entry, ["sizeKey", "extraConnections"], entryField);
+            const sizeKey = requiredString(entry, "sizeKey");
+            if (!/^[A-Z][A-Z0-9_]*$/.test(sizeKey) || PODOKIT_POOL_KEYS.includes(sizeKey) || seen.has(sizeKey)) {
+                throw new Error(`Deployment profile field "${entryField}.sizeKey" must name another pool's runtimeConfig key, once; ` +
+                    `${PODOKIT_POOL_KEYS.join(" and ")} are counted already.`);
+            }
+            seen.add(sizeKey);
+            if (!/^[1-9][0-9]*$/.test(runtimeConfig[sizeKey] ?? "")) {
+                throw new Error(`Deployment profile field "${entryField}.sizeKey" names ${sizeKey}, which runtimeConfig must set to a positive integer.`);
+            }
+            const extraConnections = entry.extraConnections ?? 0;
+            if (typeof extraConnections !== "number" || !Number.isInteger(extraConnections) || extraConnections < 0) {
+                throw new Error(`Deployment profile field "${entryField}.extraConnections" must be a non-negative integer.`);
+            }
+            return { sizeKey, extraConnections };
+        });
+    }
+    return parsed;
+}
+/** Bun closes silent connections on a 4-second tick, up to 4 seconds before their idle timeout. */
+exports.IDLE_TICK_SECONDS = 4;
+exports.MAX_IDLE_TIMEOUT_SECONDS = 255;
+const DEFAULT_BACKEND_PROXY_TIMEOUT_MS = 30_000;
+exports.IDLE_TIMEOUT_KEYS = ["CONNECTION_IDLE_TIMEOUT", "API_IDLE_TIMEOUT"];
+/**
+ * BACKEND_PROXY_TIMEOUT_MS, or the application's longest APP_PROXY_TIMEOUTS
+ * entry when that waits longer; an entry without a deadline wins outright.
+ */
+function longestProxyWait(runtimeConfig, entries) {
+    const proxyTimeout = runtimeConfig.BACKEND_PROXY_TIMEOUT_MS?.trim();
+    let longest = {
+        timeoutMs: proxyTimeout && /^\d+$/.test(proxyTimeout) ? Number(proxyTimeout) : DEFAULT_BACKEND_PROXY_TIMEOUT_MS,
+        source: "BACKEND_PROXY_TIMEOUT_MS",
+    };
+    for (const entry of entries) {
+        if (longest.timeoutMs !== null && (entry.timeoutMs === null || entry.timeoutMs > longest.timeoutMs)) {
+            longest = { timeoutMs: entry.timeoutMs, source: `APP_PROXY_TIMEOUTS entry ${entry.pathPrefix}` };
+        }
+    }
+    return longest;
+}
+function describeProxyWait(wait) {
+    return `${wait.timeoutMs === null ? "no deadline" : `${wait.timeoutMs} ms`}, ${wait.source}`;
+}
+/** Whether an idle timeout keeps a silent connection open for the whole wait. */
+function idleTimeoutCovers(seconds, wait) {
+    return seconds === 0 || (wait.timeoutMs !== null && (seconds - exports.IDLE_TICK_SECONDS) * 1000 > wait.timeoutMs);
+}
+/**
+ * The idle timeouts of the web server (CONNECTION_IDLE_TIMEOUT) and the API
+ * (API_IDLE_TIMEOUT), both run by Bun. Each is the profile's own value, or else
+ * the fewest seconds that keep a silent connection open past the /api proxy's
+ * longest wait: 35 for the default 30000 ms, and 0 (off) when an application
+ * route has no deadline.
+ */
+function idleTimeoutConfig(runtimeConfig, proxyTimeouts) {
+    const config = {};
+    for (const name of exports.IDLE_TIMEOUT_KEYS) {
+        const configured = runtimeConfig[name];
+        if (configured !== undefined) {
+            config[name] = configured;
+            continue;
+        }
+        if ("error" in proxyTimeouts)
+            throw new Error(proxyTimeouts.error);
+        const wait = longestProxyWait(runtimeConfig, proxyTimeouts.entries);
+        if (wait.timeoutMs === null) {
+            config[name] = "0";
+            continue;
+        }
+        const derived = Math.floor(wait.timeoutMs / 1000) + exports.IDLE_TICK_SECONDS + 1;
+        if (derived > exports.MAX_IDLE_TIMEOUT_SECONDS) {
+            throw new Error(`The /api proxy waits up to ${wait.timeoutMs} ms (${wait.source}), longer than the longest idle timeout ` +
+                `(${exports.MAX_IDLE_TIMEOUT_SECONDS} seconds); set ${name} to "0" to turn it off.`);
+        }
+        config[name] = String(derived);
+    }
+    return config;
+}
 function validateHttpsOrigin(value) {
     let parsed;
     try {

package/dist/deploy.d.ts

@@ -1,10 +1,7 @@
+import { type DeployFinding } from "./deploy-checks";
 import type { CommandRunner } from "./dev";
 import { type DeploymentImages } from "./deploy-render";
-export interface DeploymentDoctorFinding {
-    code: string;
-    ok: boolean;
-    message: string;
-}
+export type DeploymentDoctorFinding = DeployFinding;
 export interface DeploymentPlanAction {
     order: number;
     kind: "dependencies" | "migration" | "application" | "verification" | "rollback";

package/dist/deploy.js

@@ -14,6 +14,8 @@ const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const api_paths_1 = require("./api-paths");
+const app_proxy_timeouts_1 = require("./app-proxy-timeouts");
+const deploy_checks_1 = require("./deploy-checks");
 const deploy_profile_1 = require("./deploy-profile");
 const deploy_render_1 = require("./deploy-render");
 function defaultRunner(command, args, options) {
@@ -143,7 +145,7 @@ function apiSecretRequirements(profile) {
 }
 function doctorDeployment(projectRoot, profileName, runner = defaultRunner) {
     const profile = (0, deploy_profile_1.loadDeploymentProfile)(projectRoot, profileName);
-    const findings = [];
+    const findings = (0, deploy_checks_1.profileFindings)(projectRoot, profile);
     const fingerprint = inspectClusterFingerprint(profile.target.context, runner);
     findings.push({
         code: "cluster-fingerprint",
@@ -496,11 +498,12 @@ function planDeployment(projectRoot, profileName, release, runner = defaultRunne
         warnings: [
             "Application rollback does not reverse database migrations.",
             "PersistentVolumeClaims and Kubernetes Secrets are never deleted by apply or rollback.",
+            ...[(0, deploy_checks_1.connectionBudgetWarning)(profile, (0, deploy_checks_1.installedModules)(projectRoot))].filter((warning) => warning !== null),
         ],
     };
     const temporaryRoot = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "podokit-deploy-plan-"));
     try {
-        const runtime = (0, deploy_render_1.renderDeployment)(temporaryRoot, profileName, profile, release, images, state.rolloutStateDigest);
+        const runtime = (0, deploy_render_1.renderDeployment)(temporaryRoot, profileName, profile, release, images, state.rolloutStateDigest, (0, app_proxy_timeouts_1.readAppProxyTimeouts)(projectRoot));
         return { ...base, planHash: planDigest(base, runtime) };
     }
     finally {

package/dist/dev.d.ts

@@ -9,6 +9,10 @@ export interface DevConfig {
 export interface DevRuntime {
     alias: string;
     config: DevConfig;
+    /** Browser origins of the development stack, for CORS_ORIGIN. */
+    origins: string[];
+    /** BETTER_AUTH_URL for the containers. */
+    authUrl: string;
     projectRoot: string;
     routeId: string;
     runtimeComposePath: string;
@@ -22,8 +26,25 @@ export type CommandRunner = (command: string, args: string[], options: {
     capture: boolean;
 }) => CommandResult;
 export declare function readDevConfig(projectRoot: string): DevConfig;
+/**
+ * The origins a browser reaches the development stack on: the gateway
+ * hostname, the HTTPS tunnel origin when one is declared, and plain localhost
+ * for the compose file's own proxy.
+ */
+export declare function devOrigins(config: Pick<DevConfig, "hostname" | "publicUrl">): string[];
+/**
+ * Template variables for files that name the development host. They follow
+ * `.podokit/dev.json` when it exists and is valid, so a renamed host renders
+ * the same way it is routed; otherwise the project name's default.
+ */
+export declare function devTemplateVars(projectName: string, projectRoot?: string): Record<string, string>;
 export declare function resolveDevRuntime(projectRoot: string): DevRuntime;
 export declare function installedDevProfiles(projectRoot: string): string[];
+/**
+ * The compose overlay `podo dev` adds. Besides the gateway network it sets
+ * CORS_ORIGIN and BETTER_AUTH_URL for web and api from `.podokit/dev.json`, so
+ * the browser origins follow the routed hostname whatever `.env.docker` says.
+ */
 export declare function renderRuntimeCompose(runtime: DevRuntime): string;
 export declare function renderRoute(runtime: DevRuntime): string;
 /**

package/dist/dev.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readDevConfig = readDevConfig;
+exports.devOrigins = devOrigins;
+exports.devTemplateVars = devTemplateVars;
 exports.resolveDevRuntime = resolveDevRuntime;
 exports.installedDevProfiles = installedDevProfiles;
 exports.renderRuntimeCompose = renderRuntimeCompose;
@@ -106,6 +108,68 @@ function readDevConfig(projectRoot) {
         apiPaths: (0, api_paths_1.parseApiPaths)(config.apiPaths ?? [], `${DEV_CONFIG}.apiPaths`, webSocketPaths),
     };
 }
+/**
+ * The origins a browser reaches the development stack on: the gateway
+ * hostname, the HTTPS tunnel origin when one is declared, and plain localhost
+ * for the compose file's own proxy.
+ */
+function devOrigins(config) {
+    return [
+        ...new Set([
+            `http://${config.hostname}`,
+            ...(config.publicUrl ? [new URL(config.publicUrl).origin] : []),
+            "http://localhost",
+        ]),
+    ];
+}
+/**
+ * Template variables for files that name the development host. They follow
+ * `.podokit/dev.json` when it exists and is valid, so a renamed host renders
+ * the same way it is routed; otherwise the project name's default.
+ */
+function devTemplateVars(projectName, projectRoot) {
+    let config = { hostname: `${projectName}.localhost` };
+    const path = projectRoot ? (0, node_path_1.join)(projectRoot, DEV_CONFIG) : undefined;
+    if (path && (0, node_fs_1.existsSync)(path)) {
+        try {
+            const parsed = JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+            if (typeof parsed.hostname === "string") {
+                validateHostname(parsed.hostname);
+                if (parsed.publicUrl)
+                    validatePublicUrl(parsed.publicUrl);
+                config = { hostname: parsed.hostname, publicUrl: parsed.publicUrl };
+            }
+        }
+        catch {
+            // podo dev reports an unreadable dev.json; rendering keeps the default.
+        }
+    }
+    return {
+        devHostname: config.hostname,
+        devCorsOrigin: devOrigins(config).join(","),
+        devAuthUrl: `http://${config.hostname}`,
+    };
+}
+/**
+ * BETTER_AUTH_URL for the containers: the gateway origin, or the origin named
+ * by PODOKIT_DEV_AUTH_URL for an OAuth round trip through `publicUrl`.
+ */
+function devAuthUrl(config, origins) {
+    const requested = process.env.PODOKIT_DEV_AUTH_URL?.trim();
+    if (!requested)
+        return `http://${config.hostname}`;
+    let origin;
+    try {
+        origin = new URL(requested).origin;
+    }
+    catch {
+        origin = "";
+    }
+    if (!origins.includes(origin) || origin === "http://localhost") {
+        throw new Error(`PODOKIT_DEV_AUTH_URL must be http://${config.hostname}${config.publicUrl ? ` or ${new URL(config.publicUrl).origin}` : ""} (from ${DEV_CONFIG}).`);
+    }
+    return origin;
+}
 function stableId(projectRoot) {
     return (0, node_crypto_1.createHash)("sha256").update(projectRoot).digest("hex").slice(0, 10);
 }
@@ -118,9 +182,12 @@ function resolveDevRuntime(projectRoot) {
     const config = readDevConfig(root);
     const id = stableId(root);
     const projectSlug = slug(config.hostname.replace(/\.localhost$/, ""));
+    const origins = devOrigins(config);
     return {
         alias: `podokit-${projectSlug}-${id}`,
         config,
+        origins,
+        authUrl: devAuthUrl(config, origins),
         projectRoot: root,
         routeId: `route-${projectSlug}-${id}`,
         runtimeComposePath: (0, node_path_1.join)(root, RUNTIME_COMPOSE),
@@ -143,11 +210,19 @@ function routesToApi(config) {
 function anyOf(matchers) {
     return matchers.length > 1 ? `(${matchers.join(" || ")})` : (matchers[0] ?? "");
 }
+/**
+ * The compose overlay `podo dev` adds. Besides the gateway network it sets
+ * CORS_ORIGIN and BETTER_AUTH_URL for web and api from `.podokit/dev.json`, so
+ * the browser origins follow the routed hostname whatever `.env.docker` says.
+ */
 function renderRuntimeCompose(runtime) {
-    const api = routesToApi(runtime.config)
-        ? `  api:\n    networks:\n      ${GATEWAY_NETWORK}:\n        aliases: [${runtime.alias}-api]\n`
+    const environment = `    environment:\n` +
+        `      CORS_ORIGIN: ${JSON.stringify(runtime.origins.join(","))}\n` +
+        `      BETTER_AUTH_URL: ${JSON.stringify(runtime.authUrl)}\n`;
+    const apiNetworks = routesToApi(runtime.config)
+        ? `    networks:\n      ${GATEWAY_NETWORK}:\n        aliases: [${runtime.alias}-api]\n`
         : "";
-    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}]\n${api}networks:\n  ${GATEWAY_NETWORK}:\n    external: true\n    name: ${GATEWAY_NETWORK}\n`;
+    return `# Generated by podo dev. Do not edit.\nservices:\n  traefik:\n    profiles: [podokit-legacy-proxy]\n  web:\n${environment}    networks:\n      ${GATEWAY_NETWORK}:\n        aliases: [${runtime.alias}]\n  api:\n${environment}${apiNetworks}networks:\n  ${GATEWAY_NETWORK}:\n    external: true\n    name: ${GATEWAY_NETWORK}\n`;
 }
 function renderRoute(runtime) {
     const { alias, config, routeId } = runtime;

package/dist/eject.js

@@ -17,6 +17,8 @@ function eject(projectRoot, paths) {
             continue;
         }
         if (entry.tier !== "owned") {
+            // A managed file's baseline is what the template generated.
+            entry.templateHash = entry.outHash;
             entry.tier = "owned";
             result.ejected.push(path);
         }

package/dist/index.js

@@ -12,12 +12,14 @@ const remove_1 = require("./remove");
 const inspect_1 = require("./inspect");
 const update_1 = require("./update");
 const eject_1 = require("./eject");
+const template_files_1 = require("./template-files");
 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 deploy_driver_1 = require("./deploy-driver");
+const deploy_checks_1 = require("./deploy-checks");
 const deploy_compose_profile_1 = require("./deploy-compose-profile");
 const deploy_compose_render_1 = require("./deploy-compose-render");
 const deploy_compose_1 = require("./deploy-compose");
@@ -33,7 +35,7 @@ Usage:
   podo provider set <capability> <provider> [--apply]
   podo remove <module>     Un-apply a module (inverse of add)
   podo status              Show version, modules, file tiers, and local edits
-  podo diff                List PodoKit-managed files you have edited
+  podo diff [path...]      List edited managed files, or diff files against the template
   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 deployment
@@ -41,6 +43,7 @@ Usage:
   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)
+  podo restore <path...>   Rewrite managed or ejected files from the template
 
 Options:
   --template <t> Template to scaffold (see below)
@@ -220,6 +223,26 @@ function parseArgs(argv) {
     parsed.positionals = positionals;
     return parsed;
 }
+/** Explain owned files whose template changed, with the upstream diff when the previous templates are given. */
+function writeOwnedTemplateNotes(plan, templatesDir, from) {
+    if (plan.changes.some((change) => change.action === "review")) {
+        if (from) {
+            process.stdout.write("\nTemplate changes to files you own (not applied):\n");
+            for (const change of (0, update_1.upstreamChanges)(process.cwd(), templatesDir, plan, from)) {
+                process.stdout.write(change.diff || `${change.path}: new in this version's template.\n`);
+            }
+        }
+        else {
+            process.stdout.write("\nreview: the template changed for a file you own. podo update never writes it; " +
+                "podo diff <path> compares it with the new template, and --from <previous templates> shows what changed upstream.\n");
+        }
+    }
+    if (plan.ownedWithoutTemplate.length) {
+        process.stdout.write(`\n${plan.ownedWithoutTemplate.length} owned file(s) differ from this version's templates, and the lock does not record ` +
+            "the template they came from. podo diff <path> shows the difference; applying this update records the template " +
+            "so the next update reports only real template changes.\n");
+    }
+}
 function writeApiPaths(heading, result, verb) {
     const lines = (0, module_api_paths_1.describeApiPaths)(result, verb);
     if (lines.length)
@@ -258,7 +281,7 @@ async function runComposeDeploy(action, args, profileName) {
         const findings = (0, deploy_compose_1.doctorComposeDeployment)(cwd, profileName, undefined, args.release);
         process.stdout.write(args.json
             ? `${JSON.stringify(findings, null, 2)}\n`
-            : `${findings.map((f) => `${f.ok ? "ok  " : "FAIL"} ${f.message}`).join("\n")}\n`);
+            : `${findings.map(deploy_checks_1.formatFinding).join("\n")}\n`);
         if (findings.some((finding) => !finding.ok))
             process.exitCode = 1;
         return;
@@ -461,7 +484,33 @@ async function main(argv) {
         return;
     }
     if (args.command === "diff") {
+        const targets = args.positionals.slice(1);
         try {
+            if (targets.length) {
+                const result = (0, template_files_1.templateDiff)(process.cwd(), (0, node_path_1.join)(__dirname, "templates"), targets);
+                if (result.projectVersion !== result.templateVersion) {
+                    process.stdout.write(`Comparing with PodoKit ${result.templateVersion} templates; this project is on ${result.projectVersion}.\n`);
+                }
+                for (const file of result.files) {
+                    const tier = file.tier ? ` (${file.tier})` : "";
+                    if (file.status === "not-generated") {
+                        process.stdout.write(`${file.path}: PodoKit does not generate this file.\n`);
+                    }
+                    else if (file.status === "missing") {
+                        process.stdout.write(`${file.path}${tier}: missing; podo restore ${file.path} writes the template's version.\n`);
+                    }
+                    else if (file.status === "same") {
+                        process.stdout.write(`${file.path}${tier}: same as the template.\n`);
+                    }
+                    else if (file.binary) {
+                        process.stdout.write(`${file.path}${tier}: binary file differs from the template.\n`);
+                    }
+                    else {
+                        process.stdout.write(file.diff);
+                    }
+                }
+                return;
+            }
             const { drifted, missing } = (0, inspect_1.diff)(process.cwd());
             if (!drifted.length && !missing.length) {
                 process.stdout.write("No local edits to PodoKit-managed files.\n");
@@ -539,7 +588,7 @@ async function main(argv) {
                 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`);
+                    : `${findings.map(deploy_checks_1.formatFinding).join("\n")}\n`);
                 if (findings.some((finding) => !finding.ok))
                     process.exitCode = 1;
                 return;
@@ -561,7 +610,9 @@ async function main(argv) {
                 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`);
+                    : `${plan.actions.map((entry) => `${entry.order}. ${entry.description}`).join("\n")}\n` +
+                        `${plan.warnings.map((warning) => `warning: ${warning}`).join("\n")}\n` +
+                        `Plan hash: ${plan.planHash}\n`);
                 return;
             }
             if (action === "apply") {
@@ -672,12 +723,23 @@ async function main(argv) {
                         result.conflicts.map((f) => `  ${f}`).join("\n") +
                         "\n");
                 }
+                if (result.review.length) {
+                    process.stdout.write("\nThe template changed for these files you own; they were left as they are. " +
+                        "Compare each with podo diff <path>:\n" +
+                        result.review.map((f) => `  ${f}`).join("\n") +
+                        "\n");
+                }
                 return;
             }
             const plan = (0, update_1.planUpdate)(process.cwd(), templatesDir);
             const counts = (0, update_1.summarize)(plan);
             const shown = plan.changes.filter((c) => c.action !== "up-to-date" && c.action !== "skip");
             process.stdout.write(`podo update ${plan.fromVersion} -> ${plan.toVersion}  (template: ${plan.template}; modules: ${plan.modules.join(", ") || "none"})\n\n`);
+            if (plan.moduleDowngrades.length) {
+                process.stdout.write("WARN older external modules are installed than this project applied:\n" +
+                    `${(0, update_1.describeDowngrades)(plan.moduleDowngrades)}\n` +
+                    "--apply refuses until you install the recorded versions; the plan below would downgrade them.\n\n");
+            }
             if (plan.addedModules.length) {
                 process.stdout.write("Modules to add:\n" +
                     plan.addedModules.map((module) => `  ${module.name}  (${(0, update_1.addedModuleReason)(module)})`).join("\n") +
@@ -696,9 +758,10 @@ async function main(argv) {
                     process.stdout.write(`  ${c.action.padEnd(9)} ${path}  (${c.note})\n`);
                 }
                 process.stdout.write(`${shown.length ? "\n" : ""}${counts.update} update, ${counts.add} add, ${counts.move} move, ` +
-                    `${counts.remove} remove, ${counts.conflict} conflict. ` +
+                    `${counts.remove} remove, ${counts.conflict} conflict, ${counts.review} review. ` +
                     `Dry-run — nothing was written. Re-run with --apply to write (use --from <dir> for a 3-way merge).\n`);
             }
+            writeOwnedTemplateNotes(plan, templatesDir, args.from);
         }
         catch (err) {
             fail(err.message);
@@ -727,6 +790,23 @@ async function main(argv) {
         }
         return;
     }
+    if (args.command === "restore") {
+        const targets = args.positionals.slice(1);
+        if (!targets.length) {
+            fail("Usage: podo restore <path...>");
+        }
+        try {
+            const result = (0, template_files_1.restore)(process.cwd(), (0, node_path_1.join)(__dirname, "templates"), targets);
+            process.stdout.write(`Restored from the template: ${result.restored.join(", ")}\n`);
+            if (result.remanaged.length) {
+                process.stdout.write(`Managed by PodoKit again: ${result.remanaged.join(", ")}\n`);
+            }
+        }
+        catch (err) {
+            fail(err.message);
+        }
+        return;
+    }
     if (args.command !== "create") {
         fail(`Unknown command "${args.command}". Run "podo --help".`);
     }

package/dist/lib.d.ts

@@ -11,6 +11,8 @@ export { describeApiPaths } from "./module-api-paths";
 export { status, diff, doctor, SUPPORTED_FRAMEWORKS } from "./inspect";
 export type { StatusReport, DoctorFinding } from "./inspect";
 export { addedModuleReason, planUpdate, summarize } from "./update";
+export { restore, templateDiff } from "./template-files";
+export type { RestoreResult, TemplateDiffResult, TemplateFileDiff } from "./template-files";
 export type { AddedModule, UpdatePlan, FileChange } from "./update";
 export { readDevConfig, renderRoute, renderRuntimeCompose, resolveDevRuntime, runDevCommand } from "./dev";
 export type { CommandRunner, DevConfig, DevRuntime } from "./dev";