@podosoft/podokit 0.11.1 → 0.12.0

package/README.md

@@ -11,11 +11,13 @@ npx @podosoft/podokit create my-app
 cd my-app
 npm install
 cp .env.example .env
-npm run dev
+npx @podosoft/podokit dev watch
 ```
 
-- API: http://localhost:5002 (health at `/health`)
-- Web: http://localhost:5001
+Open **http://my-app.localhost**. The first project starts one user-level
+Traefik gateway on loopback port 80; later projects reuse it and route by
+hostname. Stop this project with `npx @podosoft/podokit dev down`. The traditional
+`npm run dev` loop remains available on web port 5001 and API port 5002.
 
 When run in a terminal, `podo create` lists the templates with descriptions and asks which one (and which package manager) to use. Pass flags (or `--yes`) to skip the prompts.
 
@@ -32,8 +34,10 @@ The `todo` template (`--template todo`) generates a working todo app (SvelteKit
 | `podo status` | Show the PodoKit version, modules, file tiers, and local edits |
 | `podo diff` | List the PodoKit-managed files you've edited since generation |
 | `podo doctor` | Check framework versions against the supported ranges |
+| `podo locale <command>` | Add, validate, activate, deactivate, or list JSON locales |
 | `podo update [--apply]` | Preview (or apply) what a version update would change |
 | `podo eject <path…>` | Take ownership of a managed file so updates skip it |
+| `podo dev <action>` | Watch, inspect, execute in, or stop a container stack behind the shared `*.localhost` gateway |
 
 ## Usage
 

package/dist/add.d.ts

@@ -18,6 +18,9 @@ export interface ModuleManifest {
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;
     scripts?: Record<string, string>;
+    /** Extra package.json overlays keyed by app name. Use when a module's files
+     *  span more than its primary targetApp. */
+    packageOverlays?: Record<string, PackageOverlay>;
     env?: string[];
     inject?: Injection[];
     instructions?: string[];
@@ -29,7 +32,17 @@ export interface ModuleManifest {
     /** Paths that an existing app may explicitly hand back to this module with
      *  `podo add --adopt`. Broad app-owned route globs are never removed. */
     managedGlobs?: string[];
+    /** Module files that remain update-managed even when a broad default glob
+     *  (for example `.claude/**`) would otherwise classify them as owned. */
+    managedOverrides?: string[];
 }
+export interface PackageOverlay {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+}
+/** Return the legacy targetApp package fields plus any additional app overlays. */
+export declare function modulePackageOverlays(manifest: ModuleManifest): Map<string, PackageOverlay>;
 export interface AddOptions {
     projectRoot: string;
     module: string;
@@ -46,6 +59,8 @@ export interface AddResult {
     added: string[];
     /** ownedGlobs declared by this module and every module it pulled in. */
     ownedGlobs: string[];
+    /** Managed exceptions declared by this module and its requirements. */
+    managedOverrides: string[];
     /** Existing owned presentation files intentionally left untouched. */
     preserved: string[];
     /** Paths explicitly adopted as module-managed files. */
@@ -75,6 +90,7 @@ export declare function listModules(modulesDir: string, projectRoot?: string): {
     name: string;
     description: string;
 }[];
+export declare function readModuleManifest(moduleDir: string): ModuleManifest;
 /**
  * Apply a module to an existing generated project: overlay files, merge the
  * target app's package.json dependencies and scripts, append env example lines,

package/dist/add.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SUPPORTED_MANIFEST_VERSION = void 0;
+exports.modulePackageOverlays = modulePackageOverlays;
 exports.resolveModuleDir = resolveModuleDir;
 exports.resolveModule = resolveModule;
 exports.listModules = listModules;
+exports.readModuleManifest = readModuleManifest;
 exports.addModule = addModule;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -13,6 +15,34 @@ const lockfile_1 = require("./lockfile");
 /** Highest `module.manifest.json` schema version this CLI understands. A package
  *  module declaring a higher version is rejected rather than mis-applied. */
 exports.SUPPORTED_MANIFEST_VERSION = 1;
+/** Return the legacy targetApp package fields plus any additional app overlays. */
+function modulePackageOverlays(manifest) {
+    const overlays = new Map();
+    const merge = (app, overlay) => {
+        const current = overlays.get(app) ?? {};
+        overlays.set(app, {
+            ...(current.dependencies || overlay.dependencies
+                ? { dependencies: { ...current.dependencies, ...overlay.dependencies } }
+                : {}),
+            ...(current.devDependencies || overlay.devDependencies
+                ? { devDependencies: { ...current.devDependencies, ...overlay.devDependencies } }
+                : {}),
+            ...(current.scripts || overlay.scripts
+                ? { scripts: { ...current.scripts, ...overlay.scripts } }
+                : {}),
+        });
+    };
+    if (manifest.dependencies || manifest.devDependencies || manifest.scripts) {
+        merge(manifest.targetApp, {
+            dependencies: manifest.dependencies,
+            devDependencies: manifest.devDependencies,
+            scripts: manifest.scripts,
+        });
+    }
+    for (const [app, overlay] of Object.entries(manifest.packageOverlays ?? {}))
+        merge(app, overlay);
+    return overlays;
+}
 const PACKAGE_PREFIX = "@podosoft/podokit-module-";
 /**
  * Resolve a module's directory by name: first the bundled `modulesDir`, then a
@@ -38,7 +68,7 @@ function resolveModule(name, modulesDir, projectRoot) {
     const dir = resolveModuleDir(name, modulesDir, projectRoot);
     if (!dir)
         return null;
-    const manifest = readManifest(dir);
+    const manifest = readModuleManifest(dir);
     const bundled = (0, node_path_1.join)(modulesDir, manifest.name);
     if (dir === bundled)
         return { dir, name: manifest.name };
@@ -66,7 +96,7 @@ function listModules(modulesDir, projectRoot) {
     if ((0, node_fs_1.existsSync)(modulesDir)) {
         for (const name of (0, node_fs_1.readdirSync)(modulesDir)) {
             if ((0, node_fs_1.existsSync)((0, node_path_1.join)(modulesDir, name, "module.manifest.json"))) {
-                out.set(name, readManifest((0, node_path_1.join)(modulesDir, name)).description);
+                out.set(name, readModuleManifest((0, node_path_1.join)(modulesDir, name)).description);
             }
         }
     }
@@ -79,7 +109,7 @@ function listModules(modulesDir, projectRoot) {
                 const manifestPath = (0, node_path_1.join)(scope, dir, "module.manifest.json");
                 if (!(0, node_fs_1.existsSync)(manifestPath))
                     continue;
-                const manifest = readManifest((0, node_path_1.join)(scope, dir));
+                const manifest = readModuleManifest((0, node_path_1.join)(scope, dir));
                 if (!out.has(manifest.name))
                     out.set(manifest.name, manifest.description);
             }
@@ -87,7 +117,7 @@ function listModules(modulesDir, projectRoot) {
     }
     return [...out].map(([name, description]) => ({ name, description }));
 }
-function readManifest(moduleDir) {
+function readModuleManifest(moduleDir) {
     return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8"));
 }
 function readJson(path) {
@@ -113,7 +143,7 @@ function isApplied(projectRoot, modulesDir, module) {
     const moduleDir = resolveModuleDir(module, modulesDir, projectRoot);
     if (!moduleDir)
         return false;
-    const manifest = readManifest(moduleDir);
+    const manifest = readModuleManifest(moduleDir);
     const firstInject = manifest.inject?.[0];
     if (firstInject) {
         const target = (0, node_path_1.join)(projectRoot, firstInject.file);
@@ -153,7 +183,7 @@ function addModule(options) {
             modulePaths: [...new Set(result.touched)],
             adoptedPaths: result.adopted,
         }
-        : undefined);
+        : undefined, result.managedOverrides);
     return result;
 }
 function applyModule(projectRoot, module, modulesDir, applied, adopt) {
@@ -163,16 +193,18 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
         throw new Error(`Unknown module "${module}".${available.length ? ` Available: ${available.join(", ")}.` : ""}`);
     }
     const moduleDir = resolved.dir;
-    const manifest = readManifest(moduleDir);
+    const manifest = readModuleManifest(moduleDir);
     assertManifestVersion(module, manifest);
-    const appPkgPath = (0, node_path_1.join)(projectRoot, "apps", manifest.targetApp, "package.json");
-    if (!(0, node_fs_1.existsSync)(appPkgPath)) {
-        throw new Error(`This does not look like a PodoKit project: ${(0, node_path_1.join)("apps", manifest.targetApp, "package.json")} not found. Run inside a generated project.`);
+    const requiredApps = new Set([manifest.targetApp, ...Object.keys(manifest.packageOverlays ?? {})]);
+    const missingApp = [...requiredApps].find((app) => !(0, node_fs_1.existsSync)((0, node_path_1.join)(projectRoot, "apps", app, "package.json")));
+    if (missingApp) {
+        throw new Error(`This does not look like a PodoKit project: ${(0, node_path_1.join)("apps", missingApp, "package.json")} not found. Run inside a generated project.`);
     }
     applied.add(module);
     // 0) apply required modules first (auto-add if missing)
     const added = [];
     const ownedGlobs = [...(manifest.ownedGlobs ?? [])];
+    const managedOverrides = [...(manifest.managedOverrides ?? [])];
     const preserved = [];
     const adopted = [];
     const touched = [];
@@ -182,6 +214,7 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
         const result = applyModule(projectRoot, required, modulesDir, applied, adopt);
         added.push(required, ...result.added);
         ownedGlobs.push(...result.ownedGlobs);
+        managedOverrides.push(...result.managedOverrides);
         preserved.push(...result.preserved);
         adopted.push(...result.adopted);
         touched.push(...result.touched);
@@ -202,18 +235,19 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
         adopted.push(...copied.adopted);
         touched.push(...copied.touched);
     }
-    // 2) merge dependencies and scripts into the target app
-    if (manifest.dependencies || manifest.devDependencies || manifest.scripts) {
+    // 2) merge dependencies and scripts into every declared app package
+    for (const [app, declaration] of modulePackageOverlays(manifest)) {
+        const appPkgPath = (0, node_path_1.join)(projectRoot, "apps", app, "package.json");
         const overlay = {};
-        if (manifest.dependencies)
-            overlay.dependencies = manifest.dependencies;
-        if (manifest.devDependencies)
-            overlay.devDependencies = manifest.devDependencies;
-        if (manifest.scripts)
-            overlay.scripts = manifest.scripts;
+        if (declaration.dependencies)
+            overlay.dependencies = declaration.dependencies;
+        if (declaration.devDependencies)
+            overlay.devDependencies = declaration.devDependencies;
+        if (declaration.scripts)
+            overlay.scripts = declaration.scripts;
         const merged = (0, podokit_template_engine_1.mergePackageJson)(readJson(appPkgPath), overlay);
         (0, node_fs_1.writeFileSync)(appPkgPath, `${JSON.stringify(merged, null, 2)}\n`);
-        touched.push(`apps/${manifest.targetApp}/package.json`);
+        touched.push(`apps/${app}/package.json`);
     }
     // 3) append env example lines
     if (manifest.env?.length) {
@@ -235,7 +269,16 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
         touched.push(injection.file);
     }
     const instructions = (manifest.instructions ?? []).map((line) => line.replace(/<app>/g, appName));
-    return { module: manifest.name, instructions, added, ownedGlobs, preserved, adopted, touched };
+    return {
+        module: manifest.name,
+        instructions,
+        added,
+        ownedGlobs,
+        managedOverrides,
+        preserved,
+        adopted,
+        touched,
+    };
 }
 function moduleRecord(module) {
     return {

package/dist/assemble.js

@@ -22,17 +22,17 @@ function applyModuleToTree(tree, moduleDir, vars) {
         for (const [path, file] of (0, podokit_template_engine_1.renderTemplate)(filesDir, vars))
             tree.set(path, file);
     }
-    // 2) merge dependencies/scripts into the target app's package.json
-    if (manifest.dependencies || manifest.devDependencies || manifest.scripts) {
-        const pkgPath = `apps/${manifest.targetApp}/package.json`;
+    // 2) merge dependencies/scripts into every declared app package.json
+    for (const [app, declaration] of (0, add_1.modulePackageOverlays)(manifest)) {
+        const pkgPath = `apps/${app}/package.json`;
         const base = JSON.parse(textOf(tree, pkgPath) || "{}");
         const overlay = {};
-        if (manifest.dependencies)
-            overlay.dependencies = manifest.dependencies;
-        if (manifest.devDependencies)
-            overlay.devDependencies = manifest.devDependencies;
-        if (manifest.scripts)
-            overlay.scripts = manifest.scripts;
+        if (declaration.dependencies)
+            overlay.dependencies = declaration.dependencies;
+        if (declaration.devDependencies)
+            overlay.devDependencies = declaration.devDependencies;
+        if (declaration.scripts)
+            overlay.scripts = declaration.scripts;
         setText(tree, pkgPath, `${JSON.stringify((0, podokit_template_engine_1.mergePackageJson)(base, overlay), null, 2)}\n`);
     }
     // 3) append env example lines (deduped)

package/dist/dev.d.ts

@@ -0,0 +1,26 @@
+export interface DevConfig {
+    schemaVersion: 1;
+    hostname: string;
+    publicUrl?: string;
+}
+export interface DevRuntime {
+    alias: string;
+    config: DevConfig;
+    projectRoot: string;
+    routeId: string;
+    runtimeComposePath: string;
+}
+interface CommandResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type CommandRunner = (command: string, args: string[], options: {
+    capture: boolean;
+}) => CommandResult;
+export declare function readDevConfig(projectRoot: string): DevConfig;
+export declare function resolveDevRuntime(projectRoot: string): DevRuntime;
+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;
+export {};

package/dist/dev.js

@@ -0,0 +1,297 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readDevConfig = readDevConfig;
+exports.resolveDevRuntime = resolveDevRuntime;
+exports.renderRuntimeCompose = renderRuntimeCompose;
+exports.renderRoute = renderRoute;
+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 lockfile_1 = require("./lockfile");
+const GATEWAY_CONTAINER = "podokit-dev-gateway";
+const GATEWAY_IMAGE = "traefik:v3.5";
+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";
+function defaultRunner(command, args, options) {
+    const result = (0, node_child_process_1.spawnSync)(command, args, {
+        encoding: "utf8",
+        stdio: options.capture ? "pipe" : "inherit",
+    });
+    if (result.error)
+        throw result.error;
+    return {
+        status: result.status,
+        stdout: options.capture ? (result.stdout ?? "") : "",
+        stderr: options.capture ? (result.stderr ?? "") : "",
+    };
+}
+function parseJson(path) {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Cannot read ${path}: ${error.message}`);
+    }
+}
+function validateHostname(hostname) {
+    if (hostname.length > 253 ||
+        !hostname.endsWith(".localhost") ||
+        !/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?\.localhost$/.test(hostname)) {
+        throw new Error(`Invalid development hostname "${hostname}". Use a lowercase *.localhost hostname without a scheme or port.`);
+    }
+}
+function validatePublicUrl(publicUrl) {
+    let parsed;
+    try {
+        parsed = new URL(publicUrl);
+    }
+    catch {
+        throw new Error(`Invalid publicUrl "${publicUrl}". Use an absolute HTTPS URL.`);
+    }
+    if (parsed.protocol !== "https:" || parsed.pathname !== "/" || parsed.search || parsed.hash) {
+        throw new Error(`Invalid publicUrl "${publicUrl}". Use an HTTPS origin without a path.`);
+    }
+}
+function readDevConfig(projectRoot) {
+    const path = (0, node_path_1.join)(projectRoot, DEV_CONFIG);
+    const manifest = (0, lockfile_1.readManifest)(projectRoot);
+    if (!manifest)
+        throw new Error("Not a PodoKit project: .podokit/manifest.json is missing.");
+    const fallbackName = manifest.answers.projectName;
+    if (!fallbackName)
+        throw new Error("PodoKit manifest is missing answers.projectName.");
+    const config = (0, node_fs_1.existsSync)(path)
+        ? parseJson(path)
+        : { schemaVersion: 1, hostname: `${fallbackName}.localhost` };
+    if (config.schemaVersion !== 1) {
+        throw new Error(`Unsupported ${DEV_CONFIG} schemaVersion: ${String(config.schemaVersion)}`);
+    }
+    validateHostname(config.hostname);
+    if (config.publicUrl)
+        validatePublicUrl(config.publicUrl);
+    return config;
+}
+function stableId(projectRoot) {
+    return (0, node_crypto_1.createHash)("sha256").update(projectRoot).digest("hex").slice(0, 10);
+}
+function slug(value) {
+    const normalized = value.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+    return normalized.slice(0, 36) || "app";
+}
+function resolveDevRuntime(projectRoot) {
+    const root = (0, node_path_1.resolve)(projectRoot);
+    const config = readDevConfig(root);
+    const id = stableId(root);
+    const projectSlug = slug(config.hostname.replace(/\.localhost$/, ""));
+    return {
+        alias: `podokit-${projectSlug}-${id}`,
+        config,
+        projectRoot: root,
+        routeId: `route-${projectSlug}-${id}`,
+        runtimeComposePath: (0, node_path_1.join)(root, RUNTIME_COMPOSE),
+    };
+}
+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`;
+}
+function renderRoute(runtime) {
+    const { alias, config, routeId } = runtime;
+    return `http:\n  routers:\n    ${routeId}:\n      entryPoints: [web]\n      rule: Host(\`${config.hostname}\`)\n      service: ${routeId}\n      middlewares: [${routeId}-compression]\n  services:\n    ${routeId}:\n      loadBalancer:\n        servers:\n          - url: http://${alias}:5001\n  middlewares:\n    ${routeId}-compression:\n      compress: {}\n`;
+}
+function devHome() {
+    return process.env.PODOKIT_DEV_HOME ?? (0, node_path_1.join)((0, node_os_1.homedir)(), ".podokit", "dev-gateway");
+}
+function registryDirectory() {
+    return (0, node_path_1.join)(devHome(), "projects");
+}
+function routesDirectory() {
+    return (0, node_path_1.join)(devHome(), "routes");
+}
+function registryPath(runtime) {
+    return (0, node_path_1.join)(registryDirectory(), `${runtime.routeId}.json`);
+}
+function routePath(runtime) {
+    return (0, node_path_1.join)(routesDirectory(), `${runtime.routeId}.yml`);
+}
+function activeEntries() {
+    const dir = registryDirectory();
+    if (!(0, node_fs_1.existsSync)(dir))
+        return [];
+    const entries = [];
+    for (const name of (0, node_fs_1.readdirSync)(dir).filter((entry) => entry.endsWith(".json"))) {
+        const path = (0, node_path_1.join)(dir, name);
+        const entry = parseJson(path);
+        if (!(0, node_fs_1.existsSync)(entry.projectRoot)) {
+            (0, node_fs_1.rmSync)(path, { force: true });
+            (0, node_fs_1.rmSync)((0, node_path_1.join)(routesDirectory(), `${entry.routeId}.yml`), { force: true });
+            continue;
+        }
+        entries.push(entry);
+    }
+    return entries;
+}
+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));
+}
+function registerRoute(runtime) {
+    const collision = activeEntries().find((entry) => entry.hostname === runtime.config.hostname && entry.projectRoot !== runtime.projectRoot);
+    if (collision) {
+        throw new Error(`Development hostname ${runtime.config.hostname} is already registered by ${collision.projectRoot}. Change .podokit/dev.json or run podo dev down there.`);
+    }
+    (0, node_fs_1.mkdirSync)(registryDirectory(), { recursive: true });
+    (0, node_fs_1.mkdirSync)(routesDirectory(), { recursive: true });
+    (0, node_fs_1.writeFileSync)(routePath(runtime), renderRoute(runtime));
+    const entry = {
+        hostname: runtime.config.hostname,
+        projectRoot: runtime.projectRoot,
+        routeId: runtime.routeId,
+    };
+    (0, node_fs_1.writeFileSync)(registryPath(runtime), `${JSON.stringify(entry, null, 2)}\n`);
+}
+function unregisterRoute(runtime) {
+    (0, node_fs_1.rmSync)(registryPath(runtime), { force: true });
+    (0, node_fs_1.rmSync)(routePath(runtime), { force: true });
+}
+function commandSucceeded(result) {
+    return result.status === 0;
+}
+function ensureDocker(runner) {
+    const result = runner("docker", ["info", "--format", "{{.ServerVersion}}"], { capture: true });
+    if (!commandSucceeded(result)) {
+        throw new Error(`Docker is not available. ${result.stderr.trim()}`.trim());
+    }
+}
+function ensureNetwork(runner) {
+    const inspect = runner("docker", ["network", "inspect", GATEWAY_NETWORK], { capture: true });
+    if (commandSucceeded(inspect))
+        return;
+    const create = runner("docker", ["network", "create", GATEWAY_NETWORK], { capture: true });
+    if (!commandSucceeded(create)) {
+        throw new Error(`Cannot create Docker network ${GATEWAY_NETWORK}: ${create.stderr.trim()}`);
+    }
+}
+function ensureGateway(runner) {
+    const inspect = runner("docker", ["inspect", "--format", `{{ index .Config.Labels \"${GATEWAY_LABEL}\" }} {{.State.Running}}`, GATEWAY_CONTAINER], { capture: true });
+    if (commandSucceeded(inspect)) {
+        const [label, running] = inspect.stdout.trim().split(/\s+/);
+        if (label !== "1") {
+            throw new Error(`Container ${GATEWAY_CONTAINER} exists but is not managed by PodoKit.`);
+        }
+        if (running !== "true") {
+            const start = runner("docker", ["start", GATEWAY_CONTAINER], { capture: true });
+            if (!commandSucceeded(start)) {
+                throw new Error(`Cannot start ${GATEWAY_CONTAINER}: ${start.stderr.trim()}`);
+            }
+        }
+        return;
+    }
+    (0, node_fs_1.mkdirSync)(routesDirectory(), { recursive: true });
+    const run = runner("docker", [
+        "run",
+        "--detach",
+        "--name",
+        GATEWAY_CONTAINER,
+        "--label",
+        `${GATEWAY_LABEL}=1`,
+        "--restart",
+        "unless-stopped",
+        "--network",
+        GATEWAY_NETWORK,
+        "--publish",
+        "127.0.0.1:80:80",
+        "--volume",
+        `${routesDirectory()}:/etc/traefik/dynamic:ro`,
+        GATEWAY_IMAGE,
+        "--providers.file.directory=/etc/traefik/dynamic",
+        "--providers.file.watch=true",
+        "--entrypoints.web.address=:80",
+        "--api.dashboard=false",
+    ], { capture: true });
+    if (!commandSucceeded(run)) {
+        throw new Error(`Cannot start the shared PodoKit gateway on 127.0.0.1:80. Stop the current port owner, then retry. ${run.stderr.trim()}`.trim());
+    }
+}
+function composeArgs(runtime, args) {
+    return ["compose", "-f", "compose.dev.yaml", "-f", runtime.runtimeComposePath, ...args];
+}
+function runCompose(runtime, args, runner) {
+    const result = runner("docker", composeArgs(runtime, args), { capture: false });
+    if (!commandSucceeded(result)) {
+        throw new Error(`docker compose ${args.join(" ")} exited with status ${String(result.status)}.`);
+    }
+}
+function composeCommand(action, args) {
+    const global = [];
+    const command = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value === undefined)
+            continue;
+        if (value === "--profile") {
+            const profile = args[index + 1];
+            if (!profile)
+                throw new Error("--profile requires a value.");
+            global.push(value, profile);
+            index += 1;
+        }
+        else if (value.startsWith("--profile=")) {
+            global.push(value);
+        }
+        else {
+            command.push(value);
+        }
+    }
+    const activeProfiles = action === "down" ? ["--profile", "*"] : [];
+    return [...activeProfiles, ...global, action, ...command];
+}
+function stopGatewayWhenUnused(runner) {
+    if (activeEntries().length > 0)
+        return;
+    runner("docker", ["rm", "--force", GATEWAY_CONTAINER], { capture: true });
+    runner("docker", ["network", "rm", GATEWAY_NETWORK], { capture: true });
+}
+function runDevCommand(projectRoot, action, args, runner = defaultRunner) {
+    const runtime = resolveDevRuntime(projectRoot);
+    writeRuntimeFiles(runtime);
+    if (action === "url") {
+        process.stdout.write(`http://${runtime.config.hostname}\n`);
+        if (runtime.config.publicUrl)
+            process.stdout.write(`${runtime.config.publicUrl}\n`);
+        return;
+    }
+    ensureDocker(runner);
+    if (action === "watch") {
+        ensureNetwork(runner);
+        registerRoute(runtime);
+        try {
+            ensureGateway(runner);
+            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);
+        }
+        catch (error) {
+            unregisterRoute(runtime);
+            stopGatewayWhenUnused(runner);
+            throw error;
+        }
+        return;
+    }
+    if (action === "down") {
+        runCompose(runtime, composeCommand("down", args), runner);
+        unregisterRoute(runtime);
+        stopGatewayWhenUnused(runner);
+        return;
+    }
+    if (action === "exec" || action === "logs" || action === "ps") {
+        runCompose(runtime, composeCommand(action, args), runner);
+        return;
+    }
+    throw new Error("Usage: podo dev <watch|exec|logs|ps|down|url> [docker compose options]");
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { type PackageManager } from "./create";
+import { type LocaleDirection } from "./locale";
 interface ParsedArgs {
     command?: string;
     name?: string;
@@ -12,6 +13,9 @@ interface ParsedArgs {
     yes: boolean;
     help: boolean;
     ai: boolean;
+    positionals: string[];
+    localeName?: string;
+    localeDirection?: LocaleDirection;
 }
 export declare function parseArgs(argv: string[]): ParsedArgs;
 export {};