@podosoft/podokit 1.2.0 → 1.4.0

package/dist/deploy-profile.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.profilePath = exports.profileDirectory = void 0;
+exports.parseDeploymentProfile = parseDeploymentProfile;
 exports.loadDeploymentProfile = loadDeploymentProfile;
 exports.listDeploymentProfiles = listDeploymentProfiles;
 exports.initializeDeploymentProfile = initializeDeploymentProfile;
@@ -11,6 +12,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const lockfile_1 = require("./lockfile");
 const deploy_schema_1 = require("./deploy-schema");
+const api_paths_1 = require("./api-paths");
 const websocket_paths_1 = require("./websocket-paths");
 var deploy_schema_2 = require("./deploy-schema");
 Object.defineProperty(exports, "profileDirectory", { enumerable: true, get: function () { return deploy_schema_2.profileDirectory; } });
@@ -84,7 +86,7 @@ function parseStatefulDependency(value, field, extraKeys = []) {
 function parseRedisDependency(value, field) {
     return parseStatefulDependency(value, field);
 }
-function parseProfile(value) {
+function parseDeploymentProfile(value) {
     if (!(0, deploy_schema_1.isRecord)(value))
         throw new Error("Deployment profile must be a JSON object.");
     (0, deploy_schema_1.assertOnlyKeys)(value, [
@@ -117,7 +119,7 @@ function parseProfile(value) {
     const runtimeConfig = (0, deploy_schema_1.requiredRecord)(value, "runtimeConfig");
     (0, deploy_schema_1.assertOnlyKeys)(target, ["context", "clusterFingerprint", "namespace", "release", "createNamespace"], "target");
     (0, deploy_schema_1.assertOnlyKeys)(release, ["strategy", "tagPattern", "apiRepository", "webRepository"], "release");
-    (0, deploy_schema_1.assertOnlyKeys)(exposure, ["mode", "host", "ingressClassName", "tlsSecretName", "webSocketPaths"], "exposure");
+    (0, deploy_schema_1.assertOnlyKeys)(exposure, ["mode", "host", "ingressClassName", "tlsSecretName", "webSocketPaths", "apiPaths"], "exposure");
     (0, deploy_schema_1.assertOnlyKeys)(workloads, ["api", "web", "worker"], "workloads");
     (0, deploy_schema_1.assertOnlyKeys)(dependencies, ["postgres", "redis", "objectStorage"], "dependencies");
     (0, deploy_schema_1.assertOnlyKeys)(secrets, ["api", "web", "imagePull"], "secrets");
@@ -167,6 +169,10 @@ function parseProfile(value) {
     if (exposureMode === "nodePort" && webSocketPaths.length > 0) {
         throw new Error("Deployment exposure.webSocketPaths requires exposure.mode ingress.");
     }
+    const apiPaths = (0, api_paths_1.parseApiPaths)(exposure.apiPaths ?? [], "exposure.apiPaths", webSocketPaths);
+    if (exposureMode === "nodePort" && apiPaths.length > 0) {
+        throw new Error("Deployment exposure.apiPaths requires exposure.mode ingress.");
+    }
     const postgres = parseStatefulDependency((0, deploy_schema_1.requiredRecord)(dependencies, "postgres"), "dependencies.postgres");
     const redis = parseRedisDependency((0, deploy_schema_1.requiredRecord)(dependencies, "redis"), "dependencies.redis");
     const objectStorageRecord = (0, deploy_schema_1.requiredRecord)(dependencies, "objectStorage");
@@ -210,6 +216,7 @@ function parseProfile(value) {
             ingressClassName,
             tlsSecretName,
             webSocketPaths,
+            apiPaths,
         },
         workloads: {
             api: parseWorkload((0, deploy_schema_1.requiredRecord)(workloads, "api"), "workloads.api"),
@@ -246,7 +253,7 @@ function loadDeploymentProfile(projectRoot, name) {
     catch (error) {
         throw new Error(`Cannot read deployment profile "${name}": ${error.message}`);
     }
-    return parseProfile(parsed);
+    return parseDeploymentProfile(parsed);
 }
 function listDeploymentProfiles(projectRoot) {
     const directory = (0, deploy_schema_1.profileDirectory)(projectRoot);
@@ -319,6 +326,7 @@ function initializeDeploymentProfile(projectRoot, name, options) {
             ingressClassName: "traefik",
             tlsSecretName: null,
             webSocketPaths: [],
+            apiPaths: (0, api_paths_1.installedApiPaths)(manifest.modules),
         },
         workloads: {
             api: {
@@ -418,7 +426,7 @@ function initializeDeploymentProfile(projectRoot, name, options) {
             ],
         },
     };
-    const validated = parseProfile(defaultProfile);
+    const validated = parseDeploymentProfile(defaultProfile);
     (0, node_fs_1.mkdirSync)((0, deploy_schema_1.profileDirectory)(projectRoot), { recursive: true });
     (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(validated, null, 2)}\n`, { flag: "wx" });
     return { name, path, profile: validated };

package/dist/deploy-render.js

@@ -5,6 +5,7 @@ const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
 const deploy_profile_1 = require("./deploy-profile");
+const api_paths_1 = require("./api-paths");
 const lockfile_1 = require("./lockfile");
 const toolchain_1 = require("./toolchain");
 function quote(value) {
@@ -525,6 +526,57 @@ spec:
       app.kubernetes.io/name: ${name}
 `;
 }
+function ingressPath(path, pathType, service) {
+    return `          - path: ${quote(path)}
+            pathType: ${pathType}
+            backend:
+              service:
+                name: ${service}
+                port: { number: 3000 }
+`;
+}
+/**
+ * Direct API paths need /api removed on the way to the API, which a standard
+ * Ingress cannot express, so they get their own Ingress with a Traefik
+ * stripPrefix middleware. ImplementationSpecific makes Traefik match the
+ * trailing-slash prefix as a plain PathPrefix, and the Exact path adds the bare
+ * path, so every controller version routes the same set of requests.
+ */
+function apiPathIngress(profile, tls) {
+    if (profile.exposure.apiPaths.length === 0)
+        return "";
+    const apiService = `${profile.target.release}-api`;
+    const middleware = `${profile.target.release}-strip-api-prefix`;
+    const paths = profile.exposure.apiPaths
+        .map((path) => {
+        const base = (0, api_paths_1.apiPathBase)(path);
+        return (ingressPath(base, "Exact", apiService) +
+            ingressPath(`${base}/`, "ImplementationSpecific", apiService));
+    })
+        .join("");
+    return `---
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: ${middleware}
+spec:
+  stripPrefix:
+    prefixes: [${quote(api_paths_1.API_PATH_PREFIX)}]
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: ${profile.target.release}-api-paths
+  annotations:
+    traefik.ingress.kubernetes.io/router.middlewares: ${quote(`${profile.target.namespace}-${middleware}@kubernetescrd`)}
+spec:
+  ingressClassName: ${quote(profile.exposure.ingressClassName)}
+${tls}  rules:
+    - host: ${quote(profile.exposure.host)}
+      http:
+        paths:
+${paths}`;
+}
 function exposure(profile) {
     const webService = `${profile.target.release}-web`;
     const apiService = `${profile.target.release}-api`;
@@ -548,13 +600,7 @@ spec:
 `
         : "";
     const webSocketPaths = profile.exposure.webSocketPaths
-        .map((path) => `          - path: ${quote(path)}
-            pathType: Exact
-            backend:
-              service:
-                name: ${apiService}
-                port: { number: 3000 }
-`)
+        .map((path) => ingressPath(path, "Exact", apiService))
         .join("");
     return `apiVersion: networking.k8s.io/v1
 kind: Ingress
@@ -572,7 +618,7 @@ ${webSocketPaths}          - path: /
               service:
                 name: ${webService}
                 port: { number: 3000 }
-`;
+${apiPathIngress(profile, tls)}`;
 }
 function applicationManifest(profile, images, rolloutStateDigest, workerCommand) {
     const runtimeConfigDigest = derivedRuntimeConfigDigest(profile);

package/dist/deploy.js

@@ -13,6 +13,7 @@ const node_crypto_1 = require("node:crypto");
 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 deploy_profile_1 = require("./deploy-profile");
 const deploy_render_1 = require("./deploy-render");
 function defaultRunner(command, args, options) {
@@ -168,6 +169,25 @@ function doctorDeployment(projectRoot, profileName, runner = defaultRunner) {
                 ? `IngressClass ${profile.exposure.ingressClassName} exists.`
                 : `IngressClass ${profile.exposure.ingressClassName} is missing or inaccessible.`,
         });
+        if (profile.exposure.apiPaths.length > 0) {
+            // Direct API paths remove /api with a Traefik Middleware resource.
+            const middlewareCrd = runner("kubectl", [
+                "--context",
+                profile.target.context,
+                "get",
+                "crd",
+                "middlewares.traefik.io",
+                "-o",
+                "name",
+            ], { capture: true });
+            findings.push({
+                code: "crd:middlewares.traefik.io",
+                ok: middlewareCrd.status === 0,
+                message: middlewareCrd.status === 0
+                    ? "Traefik Middleware resources are available for exposure.apiPaths."
+                    : "exposure.apiPaths needs the Traefik Middleware CRD (middlewares.traefik.io); serve the IngressClass with Traefik or remove exposure.apiPaths.",
+            });
+        }
         if (profile.exposure.tlsSecretName) {
             const tlsType = runner("kubectl", kubectlArgs(profile, [
                 "get",
@@ -465,7 +485,7 @@ function planDeployment(projectRoot, profileName, release, runner = defaultRunne
             {
                 order: 3,
                 kind: "application",
-                description: `Roll out API, web${profile.workloads.worker ? ", and worker" : ""} workloads with zero unavailable replicas.`,
+                description: `Roll out API, web${profile.workloads.worker ? ", and worker" : ""} workloads with zero unavailable replicas.${(0, api_paths_1.directApiRoutes)(profile.exposure.apiPaths)}`,
             },
             {
                 order: 4,

package/dist/dev.d.ts

@@ -3,6 +3,8 @@ export interface DevConfig {
     hostname: string;
     publicUrl?: string;
     webSocketPaths: string[];
+    /** Path prefixes under /api/ that skip the web proxy and reach the API directly. */
+    apiPaths: string[];
 }
 export interface DevRuntime {
     alias: string;
@@ -24,5 +26,17 @@ 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;
+/**
+ * Create the untracked `.env.docker` from the committed `.env.docker.example`
+ * when it is missing, filling every empty `*_SECRET` value with a random one.
+ * An existing file is never changed. Returns true when the file was created.
+ */
+export declare function ensureContainerEnv(projectRoot: string): boolean;
+/**
+ * Process IDs of the Compose Watch that `podo dev watch` started for this
+ * project. The project-specific runtime overlay path in the command line
+ * identifies it, so watches of other projects never match.
+ */
+export declare function findWatchProcesses(runtime: DevRuntime, psOutput: string): number[];
 export declare function runDevCommand(projectRoot: string, action: string | undefined, args: string[], runner?: CommandRunner): void;
 export {};

package/dist/dev.js

@@ -5,12 +5,15 @@ exports.resolveDevRuntime = resolveDevRuntime;
 exports.installedDevProfiles = installedDevProfiles;
 exports.renderRuntimeCompose = renderRuntimeCompose;
 exports.renderRoute = renderRoute;
+exports.ensureContainerEnv = ensureContainerEnv;
+exports.findWatchProcesses = findWatchProcesses;
 exports.runDevCommand = runDevCommand;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
 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 lockfile_1 = require("./lockfile");
 const websocket_paths_1 = require("./websocket-paths");
 const GATEWAY_CONTAINER = "podokit-dev-gateway";
@@ -21,6 +24,9 @@ const GATEWAY_VERSION_LABEL = "io.podosoft.podokit.dev-gateway.version";
 const GATEWAY_NETWORK = "podokit-dev-gateway";
 const RUNTIME_COMPOSE = ".podokit/runtime/dev.compose.yaml";
 const DEV_CONFIG = ".podokit/dev.json";
+const CONTAINER_ENV = ".env.docker";
+const CONTAINER_ENV_EXAMPLE = ".env.docker.example";
+const GENERATED_SECRET = /^([A-Z][A-Z0-9_]*_SECRET)=[ \t]*(\r?)$/gm;
 const DEV_PROFILE_BY_MODULE = new Map([
     ["redis", "cache"],
     ["object-storage-s3", "storage"],
@@ -81,16 +87,23 @@ function readDevConfig(projectRoot) {
         throw new Error("PodoKit manifest is missing answers.projectName.");
     const config = (0, node_fs_1.existsSync)(path)
         ? parseJson(path)
-        : { schemaVersion: 1, hostname: `${fallbackName}.localhost`, webSocketPaths: [] };
+        : {
+            schemaVersion: 1,
+            hostname: `${fallbackName}.localhost`,
+            webSocketPaths: [],
+            apiPaths: [],
+        };
     if (config.schemaVersion !== 1) {
         throw new Error(`Unsupported ${DEV_CONFIG} schemaVersion: ${String(config.schemaVersion)}`);
     }
     validateHostname(config.hostname);
     if (config.publicUrl)
         validatePublicUrl(config.publicUrl);
+    const webSocketPaths = (0, websocket_paths_1.parseExactWebSocketPaths)(config.webSocketPaths ?? [], `${DEV_CONFIG}.webSocketPaths`);
     return {
         ...config,
-        webSocketPaths: (0, websocket_paths_1.parseExactWebSocketPaths)(config.webSocketPaths ?? [], `${DEV_CONFIG}.webSocketPaths`),
+        webSocketPaths,
+        apiPaths: (0, api_paths_1.parseApiPaths)(config.apiPaths ?? [], `${DEV_CONFIG}.apiPaths`, webSocketPaths),
     };
 }
 function stableId(projectRoot) {
@@ -123,8 +136,15 @@ function installedDevProfiles(projectRoot) {
             .filter((profile) => profile !== undefined)),
     ];
 }
+function routesToApi(config) {
+    return config.webSocketPaths.length > 0 || config.apiPaths.length > 0;
+}
+/** Traefik v3 matchers take one value each, so several paths are joined with ||. */
+function anyOf(matchers) {
+    return matchers.length > 1 ? `(${matchers.join(" || ")})` : (matchers[0] ?? "");
+}
 function renderRuntimeCompose(runtime) {
-    const api = runtime.config.webSocketPaths.length
+    const api = routesToApi(runtime.config)
         ? `  api:\n    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`;
@@ -133,14 +153,24 @@ function renderRoute(runtime) {
     const { alias, config, routeId } = runtime;
     const hosts = routeHosts(config);
     const hostRule = hosts.map((host) => `Host(\`${host}\`)`).join(" || ");
-    const webSocketHostRule = hosts.length > 1 ? `(${hostRule})` : hostRule;
+    const scopedHostRule = hosts.length > 1 ? `(${hostRule})` : hostRule;
     const webSocketRouter = config.webSocketPaths.length
-        ? `    ${routeId}-websocket:\n      entryPoints: [web]\n      rule: ${webSocketHostRule} && Path(${config.webSocketPaths.map((path) => `\`${path}\``).join(", ")})\n      priority: 100\n      service: ${routeId}-api\n`
+        ? `    ${routeId}-websocket:\n      entryPoints: [web]\n      rule: ${scopedHostRule} && ${anyOf(config.webSocketPaths.map((path) => `Path(\`${path}\`)`))}\n      priority: 100\n      service: ${routeId}-api\n`
+        : "";
+    const apiPathMatchers = config.apiPaths.flatMap((path) => {
+        const base = (0, api_paths_1.apiPathBase)(path);
+        return [`Path(\`${base}\`)`, `PathPrefix(\`${base}/\`)`];
+    });
+    const apiPathRouter = config.apiPaths.length
+        ? `    ${routeId}-api-paths:\n      entryPoints: [web]\n      rule: ${scopedHostRule} && ${anyOf(apiPathMatchers)}\n      priority: 100\n      middlewares: [${routeId}-api-prefix]\n      service: ${routeId}-api\n`
         : "";
-    const apiService = config.webSocketPaths.length
+    const apiService = routesToApi(config)
         ? `    ${routeId}-api:\n      loadBalancer:\n        servers:\n          - url: http://${alias}-api:5002\n`
         : "";
-    return `http:\n  routers:\n${webSocketRouter}    ${routeId}:\n      entryPoints: [web]\n      rule: ${hostRule}\n      service: ${routeId}\n      middlewares: [${routeId}-compression]\n  services:\n${apiService}    ${routeId}:\n      loadBalancer:\n        servers:\n          - url: http://${alias}:5001\n  middlewares:\n    ${routeId}-compression:\n      compress: {}\n`;
+    const apiPrefixMiddleware = config.apiPaths.length
+        ? `    ${routeId}-api-prefix:\n      stripPrefix:\n        prefixes: ["${api_paths_1.API_PATH_PREFIX}"]\n`
+        : "";
+    return `http:\n  routers:\n${webSocketRouter}${apiPathRouter}    ${routeId}:\n      entryPoints: [web]\n      rule: ${hostRule}\n      service: ${routeId}\n      middlewares: [${routeId}-compression]\n  services:\n${apiService}    ${routeId}:\n      loadBalancer:\n        servers:\n          - url: http://${alias}:5001\n  middlewares:\n    ${routeId}-compression:\n      compress: {}\n${apiPrefixMiddleware}`;
 }
 function devHome() {
     return process.env.PODOKIT_DEV_HOME ?? (0, node_path_1.join)((0, node_os_1.homedir)(), ".podokit", "dev-gateway");
@@ -182,6 +212,28 @@ function activeEntries() {
     }
     return entries;
 }
+/**
+ * Create the untracked `.env.docker` from the committed `.env.docker.example`
+ * when it is missing, filling every empty `*_SECRET` value with a random one.
+ * An existing file is never changed. Returns true when the file was created.
+ */
+function ensureContainerEnv(projectRoot) {
+    const target = (0, node_path_1.join)(projectRoot, CONTAINER_ENV);
+    if ((0, node_fs_1.existsSync)(target))
+        return false;
+    const example = (0, node_path_1.join)(projectRoot, CONTAINER_ENV_EXAMPLE);
+    if (!(0, node_fs_1.existsSync)(example)) {
+        const compose = (0, node_path_1.join)(projectRoot, "compose.dev.yaml");
+        if ((0, node_fs_1.existsSync)(compose) && (0, node_fs_1.readFileSync)(compose, "utf8").includes(CONTAINER_ENV)) {
+            throw new Error(`${CONTAINER_ENV} is missing and there is no ${CONTAINER_ENV_EXAMPLE} to create it from. Run podo update --apply to add the example, or create ${CONTAINER_ENV} by hand.`);
+        }
+        return false;
+    }
+    const content = (0, node_fs_1.readFileSync)(example, "utf8").replace(GENERATED_SECRET, (_line, name, carriageReturn) => `${name}=${(0, node_crypto_1.randomBytes)(32).toString("base64url")}${carriageReturn}`);
+    (0, node_fs_1.writeFileSync)(target, content, { mode: 0o600 });
+    process.stdout.write(`Created ${CONTAINER_ENV} from ${CONTAINER_ENV_EXAMPLE} with generated secrets.\n`);
+    return true;
+}
 function writeRuntimeFiles(runtime) {
     (0, node_fs_1.mkdirSync)((0, node_path_1.join)(runtime.projectRoot, ".podokit", "runtime"), { recursive: true });
     (0, node_fs_1.writeFileSync)(runtime.runtimeComposePath, renderRuntimeCompose(runtime));
@@ -296,6 +348,69 @@ function runCompose(runtime, args, runner) {
         throw new Error(`docker compose ${args.join(" ")} exited with status ${String(result.status)}.`);
     }
 }
+// Exit statuses of a Compose process stopped by SIGINT or SIGTERM.
+const STOPPED_STATUSES = new Set([130, 143]);
+const WATCH_STOP_TIMEOUT_MS = 10_000;
+function pause(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+/**
+ * Process IDs of the Compose Watch that `podo dev watch` started for this
+ * project. The project-specific runtime overlay path in the command line
+ * identifies it, so watches of other projects never match.
+ */
+function findWatchProcesses(runtime, psOutput) {
+    const prefix = `compose ${composeArgs(runtime, []).slice(1).join(" ")} `;
+    const pids = [];
+    for (const line of psOutput.split("\n")) {
+        const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+        if (!match?.[1] || !match[2])
+            continue;
+        const start = match[2].indexOf(prefix);
+        if (start === -1)
+            continue;
+        const tokens = match[2].slice(start + prefix.length).split(/\s+/);
+        let index = 0;
+        while (tokens[index] === "--profile" || tokens[index]?.startsWith("--profile=")) {
+            index += tokens[index] === "--profile" ? 2 : 1;
+        }
+        if (tokens[index] === "watch")
+            pids.push(Number(match[1]));
+    }
+    return pids;
+}
+function anyAlive(pids, runner) {
+    return pids.some((pid) => commandSucceeded(runner("kill", ["-0", String(pid)], { capture: true })));
+}
+/**
+ * Stop this project's Compose Watch. Compose holds a per-project lock for as
+ * long as it watches, so a watch left behind by `down` made the next
+ * `podo dev watch` fail with "cannot take exclusive lock".
+ */
+function stopWatch(runtime, runner) {
+    let listing;
+    try {
+        listing = runner("ps", ["-A", "-ww", "-o", "pid=,args="], { capture: true });
+    }
+    catch {
+        return;
+    }
+    if (!commandSucceeded(listing))
+        return;
+    const pids = findWatchProcesses(runtime, listing.stdout);
+    if (pids.length === 0)
+        return;
+    runner("kill", ["-TERM", ...pids.map(String)], { capture: true });
+    const deadline = Date.now() + WATCH_STOP_TIMEOUT_MS;
+    while (anyAlive(pids, runner)) {
+        if (Date.now() >= deadline) {
+            runner("kill", ["-KILL", ...pids.map(String)], { capture: true });
+            break;
+        }
+        pause(100);
+    }
+    process.stdout.write(`Stopped podo dev watch for this project (pid ${pids.join(", ")}).\n`);
+}
 function composeCommand(action, args, installedProfiles) {
     const global = [];
     const command = [];
@@ -320,6 +435,12 @@ function composeCommand(action, args, installedProfiles) {
             command.push(value);
         }
     }
+    // Compose Watch syncs edits into the running containers, not into the image.
+    // A plain `up` that recreates a container would start it from the last
+    // built image and drop those edits, so `up` rebuilds unless told otherwise.
+    if (action === "up" && !command.includes("--build") && !command.includes("--no-build")) {
+        command.unshift("--build");
+    }
     const activeProfiles = action === "down"
         ? ["--profile", "*"]
         : installedProfiles
@@ -333,6 +454,7 @@ function stopGatewayWhenUnused(runner) {
     runner("docker", ["rm", "--force", GATEWAY_CONTAINER], { capture: true });
     runner("docker", ["network", "rm", GATEWAY_NETWORK], { capture: true });
 }
+const DOCKER_ACTIONS = new Set(["watch", "up", "exec", "logs", "ps", "down"]);
 function runDevCommand(projectRoot, action, args, runner = defaultRunner) {
     const runtime = resolveDevRuntime(projectRoot);
     const profiles = installedDevProfiles(projectRoot);
@@ -343,6 +465,16 @@ function runDevCommand(projectRoot, action, args, runner = defaultRunner) {
             process.stdout.write(`${runtime.config.publicUrl}\n`);
         return;
     }
+    if (!DOCKER_ACTIONS.has(action ?? "") && action !== "env") {
+        throw new Error("Usage: podo dev <watch|up|exec|logs|ps|down|url|env> [docker compose options]");
+    }
+    // Git ignores .env.docker, so a fresh clone gets it from the committed example.
+    const createdEnv = ensureContainerEnv(projectRoot);
+    if (action === "env") {
+        if (!createdEnv)
+            process.stdout.write(`${CONTAINER_ENV} already exists; left unchanged.\n`);
+        return;
+    }
     ensureDocker(runner);
     if (action === "watch") {
         ensureNetwork(runner);
@@ -352,7 +484,18 @@ 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, profiles), runner);
+            const watchArgs = composeCommand("watch", args, profiles);
+            const result = runner("docker", composeArgs(runtime, watchArgs), { capture: false });
+            if (!commandSucceeded(result)) {
+                // `podo dev down` or Ctrl+C ends the watch with SIGTERM or SIGINT.
+                if (result.status !== null && STOPPED_STATUSES.has(result.status)) {
+                    unregisterRoute(runtime);
+                    stopGatewayWhenUnused(runner);
+                    process.stdout.write("Stopped watching.\n");
+                    return;
+                }
+                throw new Error(`docker compose ${watchArgs.join(" ")} exited with status ${String(result.status)}.`);
+            }
         }
         catch (error) {
             unregisterRoute(runtime);
@@ -379,6 +522,7 @@ function runDevCommand(projectRoot, action, args, runner = defaultRunner) {
         return;
     }
     if (action === "down") {
+        stopWatch(runtime, runner);
         runCompose(runtime, composeCommand("down", args, profiles), runner);
         unregisterRoute(runtime);
         stopGatewayWhenUnused(runner);
@@ -386,7 +530,5 @@ function runDevCommand(projectRoot, action, args, runner = defaultRunner) {
     }
     if (action === "exec" || action === "logs" || action === "ps") {
         runCompose(runtime, composeCommand(action, args, profiles), runner);
-        return;
     }
-    throw new Error("Usage: podo dev <watch|up|exec|logs|ps|down|url> [docker compose options]");
 }

package/dist/index.js

@@ -23,6 +23,7 @@ const deploy_compose_render_1 = require("./deploy-compose-render");
 const deploy_compose_1 = require("./deploy-compose");
 const deploy_compose_sync_1 = require("./deploy-compose-sync");
 const provider_1 = require("./provider");
+const module_api_paths_1 = require("./module-api-paths");
 const HELP = `podo — PodoKit project generator
 
 Usage:
@@ -219,6 +220,11 @@ function parseArgs(argv) {
     parsed.positionals = positionals;
     return parsed;
 }
+function writeApiPaths(heading, result, verb) {
+    const lines = (0, module_api_paths_1.describeApiPaths)(result, verb);
+    if (lines.length)
+        process.stdout.write(`\n${heading}\n${lines.join("\n")}\n`);
+}
 function fail(message) {
     process.stderr.write(`error: ${message}\n`);
     process.exit(1);
@@ -402,6 +408,7 @@ async function main(argv) {
             if (result.adopted.length) {
                 process.stdout.write(`\nAdopted as module-managed file(s):\n${result.adopted.map((file) => `  ${file}`).join("\n")}\n`);
             }
+            writeApiPaths("Direct API paths (the gateway sends them to the API without the web proxy):", result.apiPaths, "add");
             if (result.instructions.length) {
                 process.stdout.write(`\nNext steps:\n${result.instructions.map((i) => `  ${i}`).join("\n")}\n`);
             }
@@ -428,6 +435,7 @@ async function main(argv) {
                     result.keptEdited.map((f) => `  ${f}`).join("\n") +
                     "\n");
             }
+            writeApiPaths("Direct API paths:", result.apiPaths, "remove");
         }
         catch (err) {
             fail(err.message);
@@ -652,9 +660,13 @@ async function main(argv) {
         try {
             if (args.apply) {
                 const result = (0, update_1.applyUpdate)(process.cwd(), templatesDir, { oldTemplatesDir: args.from });
+                if (result.addedModules.length) {
+                    process.stdout.write(`Added required module(s): ${result.addedModules.join(", ")}\n`);
+                }
                 process.stdout.write(`Applied: ${result.written.length} written, ${result.moved.length} moved, ` +
                     `${result.removed.length} removed, ` +
                     `${result.merged.length} merged, ${result.conflicts.length} conflict.\n`);
+                writeApiPaths("Direct API paths:", result.apiPaths, "add");
                 if (result.conflicts.length) {
                     process.stdout.write("\nResolve the following, then commit:\n" +
                         result.conflicts.map((f) => `  ${f}`).join("\n") +
@@ -666,7 +678,16 @@ async function main(argv) {
             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 (!shown.length) {
+            if (plan.addedModules.length) {
+                process.stdout.write("Modules to add:\n" +
+                    plan.addedModules.map((module) => `  ${module.name}  (${(0, update_1.addedModuleReason)(module)})`).join("\n") +
+                    "\n\n");
+            }
+            const apiPathLines = (0, module_api_paths_1.describeApiPaths)(plan.apiPaths, "add");
+            if (apiPathLines.length) {
+                process.stdout.write(`Direct API paths to add:\n${apiPathLines.join("\n")}\n\n`);
+            }
+            if (!shown.length && !plan.apiPaths.changed.length) {
                 process.stdout.write("Everything is up to date.\n");
             }
             else {
@@ -674,7 +695,7 @@ async function main(argv) {
                     const path = c.fromPath ? `${c.fromPath} -> ${c.path}` : c.path;
                     process.stdout.write(`  ${c.action.padEnd(9)} ${path}  (${c.note})\n`);
                 }
-                process.stdout.write(`\n${counts.update} update, ${counts.add} add, ${counts.move} move, ` +
+                process.stdout.write(`${shown.length ? "\n" : ""}${counts.update} update, ${counts.add} add, ${counts.move} move, ` +
                     `${counts.remove} remove, ${counts.conflict} conflict. ` +
                     `Dry-run — nothing was written. Re-run with --apply to write (use --from <dir> for a 3-way merge).\n`);
             }

package/dist/lib.d.ts

@@ -6,10 +6,12 @@ export { TEMPLATES, DEFAULT_TEMPLATE, TEMPLATE_NAMES, isKnownTemplate } from "./
 export type { TemplateInfo } from "./templates";
 export { listModules, addModule } from "./add";
 export type { ModuleManifest, ModuleMigration, ModulePathMove, ModuleTextReplacement, AddOptions, AddResult, } from "./add";
+export type { ApiPathChange, ApiPathResult, ApiPathSkip, ModuleApiPath, } from "./module-api-paths";
+export { describeApiPaths } from "./module-api-paths";
 export { status, diff, doctor, SUPPORTED_FRAMEWORKS } from "./inspect";
 export type { StatusReport, DoctorFinding } from "./inspect";
-export { planUpdate, summarize } from "./update";
-export type { UpdatePlan, FileChange } from "./update";
+export { addedModuleReason, planUpdate, summarize } from "./update";
+export type { AddedModule, 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";

package/dist/lib.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getComposeStatus = exports.doctorComposeDeployment = exports.applyComposeDeployment = exports.renderComposeDeployment = exports.parseComposeProfile = exports.initializeComposeProfile = exports.readDeploymentDriver = exports.loadKubernetesProfile = exports.loadComposeProfile = exports.loadAnyDeploymentProfile = exports.listAnyDeploymentProfiles = exports.assertAnyReleaseTag = exports.DEPLOY_DRIVERS = 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.PROVIDERS_SOURCE = exports.providerSource = exports.planProviderChange = exports.listProviders = exports.applyProviderChange = exports.create = void 0;
-exports.verifyAnyDeployment = exports.planAnyDeployment = exports.getAnyDeploymentStatus = exports.doctorAnyDeployment = exports.describeDeploymentTarget = exports.verifyComposeDeployment = exports.rollbackComposeDeployment = exports.planComposeRollback = exports.planComposeDeployment = exports.inspectComposeEndpointFingerprint = void 0;
+exports.applyComposeDeployment = exports.renderComposeDeployment = exports.parseComposeProfile = exports.initializeComposeProfile = exports.readDeploymentDriver = exports.loadKubernetesProfile = exports.loadComposeProfile = exports.loadAnyDeploymentProfile = exports.listAnyDeploymentProfiles = exports.assertAnyReleaseTag = exports.DEPLOY_DRIVERS = 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.addedModuleReason = exports.SUPPORTED_FRAMEWORKS = exports.doctor = exports.diff = exports.status = exports.describeApiPaths = exports.addModule = exports.listModules = exports.isKnownTemplate = exports.TEMPLATE_NAMES = exports.DEFAULT_TEMPLATE = exports.TEMPLATES = exports.PROVIDERS_SOURCE = exports.providerSource = exports.planProviderChange = exports.listProviders = exports.applyProviderChange = exports.create = void 0;
+exports.verifyAnyDeployment = exports.planAnyDeployment = exports.getAnyDeploymentStatus = exports.doctorAnyDeployment = exports.describeDeploymentTarget = exports.verifyComposeDeployment = exports.rollbackComposeDeployment = exports.planComposeRollback = exports.planComposeDeployment = exports.inspectComposeEndpointFingerprint = exports.getComposeStatus = exports.doctorComposeDeployment = void 0;
 exports.builtinTemplatesDir = builtinTemplatesDir;
 exports.builtinModulesDir = builtinModulesDir;
 // Library entry point: the reusable functions behind the `podo` CLI, for other
@@ -23,12 +23,15 @@ Object.defineProperty(exports, "isKnownTemplate", { enumerable: true, get: funct
 var add_1 = require("./add");
 Object.defineProperty(exports, "listModules", { enumerable: true, get: function () { return add_1.listModules; } });
 Object.defineProperty(exports, "addModule", { enumerable: true, get: function () { return add_1.addModule; } });
+var module_api_paths_1 = require("./module-api-paths");
+Object.defineProperty(exports, "describeApiPaths", { enumerable: true, get: function () { return module_api_paths_1.describeApiPaths; } });
 var inspect_1 = require("./inspect");
 Object.defineProperty(exports, "status", { enumerable: true, get: function () { return inspect_1.status; } });
 Object.defineProperty(exports, "diff", { enumerable: true, get: function () { return inspect_1.diff; } });
 Object.defineProperty(exports, "doctor", { enumerable: true, get: function () { return inspect_1.doctor; } });
 Object.defineProperty(exports, "SUPPORTED_FRAMEWORKS", { enumerable: true, get: function () { return inspect_1.SUPPORTED_FRAMEWORKS; } });
 var update_1 = require("./update");
+Object.defineProperty(exports, "addedModuleReason", { enumerable: true, get: function () { return update_1.addedModuleReason; } });
 Object.defineProperty(exports, "planUpdate", { enumerable: true, get: function () { return update_1.planUpdate; } });
 Object.defineProperty(exports, "summarize", { enumerable: true, get: function () { return update_1.summarize; } });
 var dev_1 = require("./dev");

package/dist/lockfile.d.ts

@@ -21,12 +21,15 @@ export interface ManifestModule {
     moduleVersion?: string;
     /** Module-local update migrations already applied to this project. */
     appliedMigrations?: string[];
+    /** Direct API paths of the module already merged into the app's gateway configuration. */
+    appliedApiPaths?: string[];
 }
 export interface ManifestModuleInput {
     name: string;
     packageName?: string;
     moduleVersion?: string;
     appliedMigrations?: string[];
+    appliedApiPaths?: string[];
 }
 export interface PodokitManifest {
     schemaVersion: number;
@@ -116,4 +119,6 @@ export declare function mergeOwnedGlobs(existing: string[], add: string[]): stri
  * `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, moduleInputs: (string | ManifestModuleInput)[], version?: string, ownedGlobs?: string[], lockSnapshot?: RecordModulesLockSnapshot, managedOverrides?: string[]): void;
+export declare function recordModules(projectRoot: string, moduleInputs: (string | ManifestModuleInput)[], version?: string, ownedGlobs?: string[], lockSnapshot?: RecordModulesLockSnapshot, managedOverrides?: string[], 
+/** Installed module that newly recorded modules must configure before. */
+insertBefore?: string): void;