@0xmaxma/claude-gateway 1.5.4 → 1.5.6

package/dist/apps/installer.d.ts

@@ -1,7 +1,7 @@
 import { SpawnSyncOptionsWithStringEncoding } from 'node:child_process';
 import { AppsRegistry, AppEntry } from './registry';
 import { RegistryClient } from './registry-client';
-import { ComposePort, ComposeSocket } from './compose-generator';
+import { ComposePort, ComposeSocket, GeneratedKey, AgentDeclaration } from './compose-generator';
 import { AgentManager } from './agent-manager';
 export interface InstallOptions {
     /** Registry app name (Mode A — registry install) */
@@ -16,6 +16,15 @@ export interface InstallOptions {
     localPath?: string;
     /** Pre-supplied env vars (secrets that would otherwise be prompted) */
     envVars?: Record<string, string>;
+    /** Host-port overrides per port name (default host comes from app.yaml) */
+    portOverrides?: Record<string, number>;
+}
+/** Options for {@link AppInstaller.reconfigure}. */
+export interface ReconfigureOptions {
+    /** Env vars to merge into the existing .env (unsent keys are preserved) */
+    envVars?: Record<string, string>;
+    /** Host-port overrides per port name (unset = app.yaml default) */
+    portOverrides?: Record<string, number>;
 }
 export interface InstallResult {
     appName: string;
@@ -26,6 +35,24 @@ export interface InstallResult {
         name: string;
     } | null;
 }
+/**
+ * Read-only preview of an install source, computed by fetching and parsing the
+ * app.yaml BEFORE any install. Surfaces the secrets an operator must supply
+ * ({@link InspectResult.secretKeys}) and the ones the gateway auto-generates
+ * ({@link InspectResult.generatedKeys}) so the pre-install summary is accurate
+ * even for a GitHub-URL app that has no registry entry.
+ */
+export interface InspectResult {
+    name: string;
+    version: string;
+    source: AppEntry['source'];
+    commit: string;
+    secretKeys: string[];
+    generatedKeys: GeneratedKey[];
+    ports: ComposePort[];
+    agentDeclaration: AgentDeclaration | null;
+    warnings: string[];
+}
 export interface JobState {
     id: string;
     status: 'pending' | 'running' | 'completed' | 'failed';
@@ -85,8 +112,36 @@ export declare class AppInstaller {
     /** Start an async install job. Returns jobId immediately. */
     install(options: InstallOptions): string;
     getJob(jobId: string): JobState | undefined;
+    /**
+     * Read-only inspection of an install source — no install side effects, no
+     * files left behind. Resolves the repo + commit, fetches the app.yaml
+     * (shallow clone into a tmp dir for registry/GitHub sources; direct read for
+     * a local path), parses it, and returns the metadata needed for an accurate
+     * pre-install summary: the required secrets (`secretKeys`, must be prompted)
+     * and the self-generated secrets (`generatedKeys`, auto-filled at install).
+     *
+     * This is what lets a GitHub-URL install surface its required secrets before
+     * installing — such apps have no registry entry, so `browse_registry` cannot
+     * reveal them.
+     */
+    inspectSource(options: InstallOptions): Promise<InspectResult>;
+    /**
+     * Parse the app.yaml in `appDir` and derive the pre-install metadata without
+     * mutating `appDir`. generateCompose writes the compose file to its output
+     * path, so we point it at a throwaway tmp file (removed here) to keep the
+     * inspection read-only even for a local source.
+     */
+    private inspectDir;
     /** Start an async update job. Returns jobId immediately. */
     update(appName: string): string;
+    /**
+     * Start an async reconfigure job — merge env vars and/or override host ports
+     * on an already-installed app, then force-recreate the container. Named
+     * volumes (and their data) survive because this is an `up --force-recreate`,
+     * never a `down -v`. Returns jobId immediately. Throws synchronously (409)
+     * if the app is mid install/update/reconfigure.
+     */
+    reconfigure(appName: string, options: ReconfigureOptions): string;
     uninstall(appName: string): Promise<void>;
     startStopRestart(appName: string, action: 'start' | 'stop' | 'restart'): Promise<void>;
     /**
@@ -130,6 +185,34 @@ export declare class AppInstaller {
         latestCommit: string | null;
         updateable: boolean;
     }>;
+    /**
+     * Reconfigure an installed app: merge env vars and/or override host ports,
+     * then force-recreate the container in place. No clone, no dir swap — the app
+     * stays at its current commit/appDir; only its .env and (optionally) its
+     * compose port mappings change. Named volumes and their data survive because
+     * this is an `up --force-recreate`, never a `down -v`.
+     */
+    private runReconfigure;
+    /**
+     * Return an error message if any of the given host ports is already bound by a
+     * *different* installed app, else null. Shared by install and reconfigure so
+     * the cross-app collision rule stays in one place.
+     */
+    findHostPortCollision(selfName: string, ports: Array<{
+        name: string;
+        hostPort: number;
+    }>): Promise<string | null>;
+    /**
+     * Write the app's .env file (mode 0600). Emits, in order: BASE_PATH for web
+     * ports, declared secretKeys, self-generating generatedKeys (a fresh random
+     * value unless already present in `envVars` — operator-pinned on install, or
+     * the existing value on reconfigure), then any extra vars. Returns the names
+     * of freshly generated secrets (for logging — never the values). Shared by
+     * runInstall and runReconfigure so the .env format cannot drift.
+     */
+    private writeEnvFile;
+    /** Parse an app's existing .env into a key→value map (empty if absent). */
+    private readEnvFile;
     /**
      * Resolve the repo URL and target commit to update an installed app to.
      * - `registry`: latest published version via the registry client.

package/dist/apps/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/apps/installer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/apps/installer.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,kCAAkC,EAAoB,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAa,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAmB,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAIL,WAAW,EACX,aAAa,EACb,YAAY,EAEZ,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAI/C,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gBAAgB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC1C,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACvD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAC5D,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7H,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,iBAAiB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAED,KAAK,OAAO,GAAG,CACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,CAAC,EAAE,kCAAkC,KACtC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE/D;;;;;GAKG;AACH,KAAK,YAAY,GAAG,CAClB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,KACxC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAAC;AAqBxE,qBAAa,YAAY;IAOrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAEtB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAZ7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA+B;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,kGAAkG;IAClG,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;gBAGlC,QAAQ,EAAE,YAAY,EACtB,cAAc,EAAE,cAAc,EAC9B,SAAS,EAAE,kBAAkB,EAC7B,KAAK,GAAE,OAAsB,EAC9C,OAAO,CAAC,EAAE,MAAM,EACC,YAAY,CAAC,EAAE,YAAY,YAAA,EAC3B,UAAU,GAAE,YAAgC;IAO/D,6DAA6D;IAC7D,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM;IA8BxC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAI3C;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA8BpE;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IA8BlB,4DAA4D;IAC5D,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IA2B/B;;;;;;OAMG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,MAAM;IA2B3D,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgEzC,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,GACnC,OAAO,CAAC,IAAI,CAAC;IAchB;;;;;;;;;;;;;;;;;;;OAmBG;IACG,kBAAkB,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;YA2B7F,UAAU;YAgVV,SAAS;IAkMvB;;;;;;OAMG;IACG,aAAa,CACjB,KAAK,EAAE,QAAQ,GACd,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;IAgB9F;;;;;;OAMG;YACW,cAAc;IA0L5B;;;;OAIG;IACG,qBAAqB,CACzB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,GAC/C,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkBzB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAoDpB,2EAA2E;IAC3E,OAAO,CAAC,WAAW;IAenB;;;;;;OAMG;YACW,mBAAmB;YA2BnB,aAAa;IA2F3B,wFAAwF;IACxF,OAAO,CAAC,IAAI;IAgBZ;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAUhB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IA2BjB;;;;;;;OAOG;YACW,cAAc;IAQ5B,gEAAgE;YAClD,QAAQ;IAStB,sEAAsE;IACtE,OAAO,CAAC,YAAY;IASpB;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;IA0BjC,OAAO,CAAC,GAAG;IAoBX,OAAO,CAAC,GAAG;IAKX,OAAO,CAAC,OAAO;CAMhB"}

package/dist/apps/installer.js

@@ -99,6 +99,80 @@ class AppInstaller {
     getJob(jobId) {
         return this.jobs.get(jobId);
     }
+    /**
+     * Read-only inspection of an install source — no install side effects, no
+     * files left behind. Resolves the repo + commit, fetches the app.yaml
+     * (shallow clone into a tmp dir for registry/GitHub sources; direct read for
+     * a local path), parses it, and returns the metadata needed for an accurate
+     * pre-install summary: the required secrets (`secretKeys`, must be prompted)
+     * and the self-generated secrets (`generatedKeys`, auto-filled at install).
+     *
+     * This is what lets a GitHub-URL install surface its required secrets before
+     * installing — such apps have no registry entry, so `browse_registry` cannot
+     * reveal them.
+     */
+    async inspectSource(options) {
+        // Mode B — local path: read app.yaml directly, no clone.
+        if (options.localPath) {
+            const resolved = path.resolve(options.localPath);
+            if (!fs.existsSync(path.join(resolved, 'app.yaml'))) {
+                throw new Error(`app.yaml not found in "${resolved}"`);
+            }
+            return this.inspectDir(resolved, 'local', 'local');
+        }
+        // Mode A — registry or GitHub: resolve, then shallow-clone into a tmp dir.
+        // Passing a null job keeps resolveSource silent (there is no install job).
+        const resolved = await this.resolveSource(null, options, options.version ?? '0.0.0');
+        const tmpDir = path.join(os.tmpdir(), `cg-inspect-${crypto.randomUUID()}`);
+        try {
+            fs.mkdirSync(tmpDir, { recursive: true });
+            this.run(['git', 'init'], tmpDir);
+            this.run(['git', 'remote', 'add', 'origin', resolved.githubUrl], tmpDir);
+            this.run(['git', 'fetch', '--depth', '1', 'origin', resolved.commit], tmpDir);
+            this.run(['git', 'checkout', 'FETCH_HEAD'], tmpDir);
+            return this.inspectDir(tmpDir, resolved.source, resolved.commit, resolved.version);
+        }
+        finally {
+            try {
+                this.rmrf(tmpDir);
+            }
+            catch {
+                /* best-effort cleanup of a read-only tmp clone */
+            }
+        }
+    }
+    /**
+     * Parse the app.yaml in `appDir` and derive the pre-install metadata without
+     * mutating `appDir`. generateCompose writes the compose file to its output
+     * path, so we point it at a throwaway tmp file (removed here) to keep the
+     * inspection read-only even for a local source.
+     */
+    inspectDir(appDir, source, commit, fallbackVersion) {
+        const appYaml = (0, compose_generator_1.parseAppYaml)(fs.readFileSync(path.join(appDir, 'app.yaml'), 'utf-8'), appDir);
+        const tmpCompose = path.join(os.tmpdir(), `cg-inspect-compose-${crypto.randomUUID()}.yml`);
+        try {
+            const generated = (0, compose_generator_1.generateCompose)(appYaml, appYaml.name, appDir, tmpCompose);
+            return {
+                name: appYaml.name,
+                version: appYaml.version || fallbackVersion || '0.0.0',
+                source,
+                commit,
+                secretKeys: generated.secretKeys,
+                generatedKeys: generated.generatedKeys,
+                ports: generated.ports,
+                agentDeclaration: generated.agentDeclaration,
+                warnings: generated.warnings,
+            };
+        }
+        finally {
+            try {
+                fs.rmSync(tmpCompose, { force: true });
+            }
+            catch {
+                /* best-effort cleanup of the throwaway compose file */
+            }
+        }
+    }
     /** Start an async update job. Returns jobId immediately. */
     update(appName) {
         this.pruneOldJobs();
@@ -122,6 +196,35 @@ class AppInstaller {
         });
         return jobId;
     }
+    /**
+     * Start an async reconfigure job — merge env vars and/or override host ports
+     * on an already-installed app, then force-recreate the container. Named
+     * volumes (and their data) survive because this is an `up --force-recreate`,
+     * never a `down -v`. Returns jobId immediately. Throws synchronously (409)
+     * if the app is mid install/update/reconfigure.
+     */
+    reconfigure(appName, options) {
+        this.pruneOldJobs();
+        if (this.installingNames.has(appName)) {
+            throw new Error(`App "${appName}" is already being installed or updated`);
+        }
+        this.installingNames.add(appName);
+        const jobId = crypto.randomUUID();
+        const job = {
+            id: jobId,
+            status: 'pending',
+            logs: [],
+            startedAt: Date.now(),
+            updatedAt: Date.now(),
+        };
+        this.jobs.set(jobId, job);
+        void this.runReconfigure(job, appName, options).catch((err) => {
+            this.failJob(job, err instanceof Error ? err.message : String(err));
+        }).finally(() => {
+            this.installingNames.delete(appName);
+        });
+        return jobId;
+    }
     async uninstall(appName) {
         const entry = await this.registry.get(appName);
         // Orphaned install: directory exists on disk but not in registry — clean up filesystem only
@@ -374,20 +477,11 @@ class AppInstaller {
             // ── Generate docker-compose.yml ───────────────────────────────────────
             this.log(job, 'Generating docker-compose.yml');
             const composePath = path.join(appDir, 'docker-compose.yml');
-            const generated = (0, compose_generator_1.generateCompose)(appYaml, appName, appDir, composePath);
+            const generated = (0, compose_generator_1.generateCompose)(appYaml, appName, appDir, composePath, options.portOverrides);
             // Conflict check — host port uniqueness across all installed apps
-            const installedApps = await this.registry.list();
-            const usedHostPorts = new Map();
-            for (const app of installedApps) {
-                for (const port of app.ports) {
-                    usedHostPorts.set(port.hostPort, app.name);
-                }
-            }
-            for (const port of generated.ports) {
-                const owner = usedHostPorts.get(port.hostPort);
-                if (owner) {
-                    throw new Error(`Host port ${port.hostPort} (port "${port.name}") is already used by app "${owner}"`);
-                }
+            const collision = await this.findHostPortCollision(appName, generated.ports.map((p) => ({ name: p.name, hostPort: p.hostPort })));
+            if (collision) {
+                throw new Error(collision);
             }
             // Conflict check — agent name (if app declares an agent), inside install lock
             if (generated.agentDeclaration && this.agentManager) {
@@ -413,50 +507,10 @@ class AppInstaller {
             }
             // ── Write .env ────────────────────────────────────────────────────────
             this.log(job, 'Writing .env');
-            const envVars = options.envVars ?? {};
-            const envLines = [];
-            // Inject BASE_PATH for web-type ports
-            for (const port of generated.ports) {
-                if (port.type === 'web') {
-                    envVars[`BASE_PATH`] = `/app/${appName}/${port.name}`;
-                }
-            }
-            for (const key of generated.secretKeys) {
-                const val = (envVars[key] ?? '').replace(/[\r\n]/g, '');
-                envLines.push(`${key}=${val}`);
-            }
-            // Self-generating secrets: write a fresh random value unless the operator
-            // pinned one via envVars. Log only the key names, never the values.
-            const generatedKeySet = new Set(generated.generatedKeys.map((g) => g.key));
-            const generatedNames = [];
-            for (const g of generated.generatedKeys) {
-                const pinned = envVars[g.key];
-                let val;
-                if (pinned !== undefined && pinned !== '') {
-                    val = pinned.replace(/[\r\n]/g, '');
-                }
-                else {
-                    val = (0, compose_generator_1.generateSecretValue)(g.encoding, g.bytes);
-                    generatedNames.push(g.key);
-                }
-                envLines.push(`${g.key}=${val}`);
-            }
+            const generatedNames = this.writeEnvFile(appDir, appName, generated, options.envVars ?? {});
             if (generatedNames.length > 0) {
                 this.log(job, `Generated secrets: ${generatedNames.join(', ')}`);
             }
-            // Also write any explicitly provided vars not already declared as secrets/generated
-            for (const [k, v] of Object.entries(envVars)) {
-                if (!generated.secretKeys.includes(k) && !generatedKeySet.has(k)) {
-                    envLines.push(`${k}=${v.replace(/[\r\n]/g, '')}`);
-                }
-            }
-            const envPath = path.join(appDir, '.env');
-            try {
-                fs.writeFileSync(envPath, envLines.join('\n') + '\n', { mode: 0o600 });
-            }
-            catch (err) {
-                throw new Error(`Failed to write .env: ${err.message}`);
-            }
             // ── Create socket files ───────────────────────────────────────────────
             // Use homedir so sockets are on the host-mounted volume and visible to remote
             // Docker daemons (e.g. docker-builder DinD) via a shared bind mount.
@@ -796,6 +850,266 @@ class AppInstaller {
             return { latestVersion: null, latestCommit: null, updateable: false };
         }
     }
+    /**
+     * Reconfigure an installed app: merge env vars and/or override host ports,
+     * then force-recreate the container in place. No clone, no dir swap — the app
+     * stays at its current commit/appDir; only its .env and (optionally) its
+     * compose port mappings change. Named volumes and their data survive because
+     * this is an `up --force-recreate`, never a `down -v`.
+     */
+    async runReconfigure(job, appName, options) {
+        job.status = 'running';
+        job.updatedAt = Date.now();
+        const entry = await this.registry.get(appName);
+        if (!entry)
+            throw new Error(`App "${appName}" is not installed`);
+        if (entry.source === 'local') {
+            throw new Error(`App "${appName}" is installed from a local path and cannot be reconfigured — reinstall from source instead`);
+        }
+        const appDir = entry.installPath;
+        const composePath = path.join(appDir, 'docker-compose.yml');
+        const portOverrides = options.portOverrides;
+        const hasPortChange = portOverrides !== undefined && Object.keys(portOverrides).length > 0;
+        // Parse the app's on-disk app.yaml (present from the original install/update).
+        const yamlPath = path.join(appDir, 'app.yaml');
+        if (!fs.existsSync(yamlPath)) {
+            throw new Error(`app.yaml not found for "${appName}" — cannot reconfigure`);
+        }
+        const appYaml = (0, compose_generator_1.parseAppYaml)(fs.readFileSync(yamlPath, 'utf-8'), appDir);
+        this.log(job, 'Preparing reconfigure');
+        // Snapshot the current on-disk state BEFORE any mutation so a failed
+        // recreate can be rolled back. Both an env-only and a port change rewrite
+        // .env and force-recreate the container; a port change additionally rewrites
+        // the live compose file and swaps proxy routes. If the new container never
+        // comes up the app would otherwise be left down (or, for a port change,
+        // unreachable with routes gone and compose/registry mismatched).
+        const envPath = path.join(appDir, '.env');
+        const oldComposeContent = hasPortChange && fs.existsSync(composePath) ? fs.readFileSync(composePath, 'utf-8') : null;
+        const oldEnvContent = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf-8') : null;
+        const oldPorts = entry.ports;
+        // Compute (and validate) the port metadata. Always generate to a TEMP file
+        // first: the live compose must not change until the overrides are validated
+        // (generateCompose checks them) and we are inside the guarded section below.
+        // Writing the live file here would leave the new ports on disk against the
+        // still-running old container if a later step (collision, agent inject)
+        // throws (finding F2). An env-only reconfigure never touches the compose.
+        let generated;
+        let newComposeContent;
+        {
+            const tmpCompose = path.join(os.tmpdir(), `cg-reconf-${appName}-${crypto.randomUUID()}.yml`);
+            try {
+                generated = (0, compose_generator_1.generateCompose)(appYaml, appName, appDir, tmpCompose, portOverrides);
+                newComposeContent = fs.readFileSync(tmpCompose, 'utf-8');
+            }
+            finally {
+                fs.rmSync(tmpCompose, { force: true });
+            }
+        }
+        // Host-port collision across other installed apps (only if ports changed).
+        // Runs before the live compose is touched, so a collision leaves nothing to
+        // undo on disk.
+        if (hasPortChange) {
+            const collision = await this.findHostPortCollision(appName, generated.ports.map((p) => ({ name: p.name, hostPort: p.hostPort })));
+            if (collision)
+                throw new Error(collision);
+        }
+        // Apply the reconfigure. Everything from here mutates live state (compose
+        // file, .env, proxy routes, the running container), so it is guarded: a
+        // reconfigure that fails to recreate is rolled back to the previous
+        // ports/compose/.env so the app stays reachable (planning §4.1 step 10 —
+        // best-effort reopen).
+        try {
+            // Swap in the newly-generated compose only now that we're inside the
+            // guard (finding F2). Regenerating drops the injected agent service, so we
+            // re-inject it. An env-only reconfigure leaves the compose untouched.
+            if (hasPortChange) {
+                this.log(job, 'Updating docker-compose.yml');
+                fs.writeFileSync(composePath, newComposeContent);
+                if (generated.agentDeclaration && this.agentManager) {
+                    const agentPaths = entry.agentPaths ?? this.agentManager.detectAgentPaths();
+                    this.agentManager.injectAgentService({ ...entry, agentPaths });
+                }
+            }
+            // Merge the new env vars onto the existing .env: keys not supplied are
+            // preserved, and existing generated-secret values are carried over rather
+            // than rotated (writeEnvFile treats an already-present value as pinned).
+            this.log(job, 'Writing .env');
+            const mergedEnv = { ...this.readEnvFile(appDir), ...(options.envVars ?? {}) };
+            this.writeEnvFile(appDir, appName, generated, mergedEnv);
+            // Deregister old proxy routes before the port mapping changes (the proxy is
+            // bound to the old hostPort).
+            if (hasPortChange) {
+                this.callbacks.deregisterRoutes(appName);
+            }
+            // Force-recreate so the container picks up the new .env / port mapping —
+            // compose does not detect an env_file content change on its own. This is an
+            // `up`, not a `down -v`, so named volumes (and their data) survive.
+            this.log(job, 'Recreating container');
+            this.composeUp(appName, appDir, job, { forceRecreate: true });
+            await this.registry.updateStatus(appName, 'running');
+            // Persist the reconfigure: always bump updatedAt so the registry reflects
+            // that the app was reconfigured; refresh the port mappings + re-register
+            // proxy routes only when a host port actually changed.
+            const updatedEntry = { ...entry, updatedAt: new Date().toISOString() };
+            if (hasPortChange) {
+                updatedEntry.ports = generated.ports.map((p) => ({
+                    name: p.name,
+                    service: p.service,
+                    hostPort: p.hostPort,
+                    containerPort: p.containerPort,
+                    type: p.type,
+                    rateLimit: p.rateLimit,
+                }));
+            }
+            await this.registry.upsert(updatedEntry);
+            if (hasPortChange) {
+                this.callbacks.registerRoutes(appName, generated.ports);
+            }
+        }
+        catch (reconfErr) {
+            // Roll back a failed reconfigure so the app stays reachable. Both a
+            // port change and an env-only change rewrite .env and force-recreate the
+            // container, so a bad value (failed healthcheck) or an unbindable port can
+            // leave the app down either way (finding F1). Restore the previous .env,
+            // restore the previous compose + re-register the old routes when a port
+            // change had swapped them, then bring the old container back on the old
+            // config. Best-effort: a failing rollback is logged, not thrown.
+            this.log(job, `Reconfigure failed — rolling back "${appName}"`);
+            try {
+                if (oldEnvContent !== null) {
+                    fs.writeFileSync(envPath, oldEnvContent, { mode: 0o600 });
+                    fs.chmodSync(envPath, 0o600);
+                }
+                if (hasPortChange && oldComposeContent !== null) {
+                    fs.writeFileSync(composePath, oldComposeContent);
+                }
+                this.composeUp(appName, appDir, job, { forceRecreate: true });
+                if (hasPortChange) {
+                    this.callbacks.registerRoutes(appName, oldPorts.map((p) => ({
+                        name: p.name,
+                        service: p.service,
+                        hostPort: p.hostPort,
+                        containerPort: p.containerPort,
+                        type: p.type,
+                        rateLimit: p.rateLimit,
+                    })));
+                }
+                await this.registry.updateStatus(appName, 'running');
+            }
+            catch (rollbackErr) {
+                this.log(job, `ROLLBACK FAILED — app "${appName}" may be in a broken state: ${rollbackErr.message}`);
+            }
+            throw reconfErr;
+        }
+        const proxyUrls = {};
+        for (const p of generated.ports) {
+            proxyUrls[p.name] = `/app/${appName}/${p.name}/`;
+        }
+        job.status = 'completed';
+        job.result = {
+            appName,
+            proxyUrls,
+            secretKeys: generated.secretKeys,
+            agentDeclaration: entry.agentDeclaration ?? null,
+        };
+        job.updatedAt = Date.now();
+        this.log(job, `Reconfigure complete: ${JSON.stringify(proxyUrls)}`);
+    }
+    /**
+     * Return an error message if any of the given host ports is already bound by a
+     * *different* installed app, else null. Shared by install and reconfigure so
+     * the cross-app collision rule stays in one place.
+     */
+    async findHostPortCollision(selfName, ports) {
+        const installedApps = await this.registry.list();
+        const usedHostPorts = new Map();
+        for (const app of installedApps) {
+            if (app.name === selfName)
+                continue;
+            for (const port of app.ports) {
+                usedHostPorts.set(port.hostPort, app.name);
+            }
+        }
+        for (const p of ports) {
+            const owner = usedHostPorts.get(p.hostPort);
+            if (owner) {
+                return `Host port ${p.hostPort} (port "${p.name}") is already used by app "${owner}"`;
+            }
+        }
+        return null;
+    }
+    /**
+     * Write the app's .env file (mode 0600). Emits, in order: BASE_PATH for web
+     * ports, declared secretKeys, self-generating generatedKeys (a fresh random
+     * value unless already present in `envVars` — operator-pinned on install, or
+     * the existing value on reconfigure), then any extra vars. Returns the names
+     * of freshly generated secrets (for logging — never the values). Shared by
+     * runInstall and runReconfigure so the .env format cannot drift.
+     */
+    writeEnvFile(appDir, appName, generated, envVars) {
+        const merged = { ...envVars };
+        // Inject BASE_PATH for web-type ports
+        for (const port of generated.ports) {
+            if (port.type === 'web') {
+                merged['BASE_PATH'] = `/app/${appName}/${port.name}`;
+            }
+        }
+        const envLines = [];
+        for (const key of generated.secretKeys) {
+            const val = (merged[key] ?? '').replace(/[\r\n]/g, '');
+            envLines.push(`${key}=${val}`);
+        }
+        const generatedKeySet = new Set(generated.generatedKeys.map((g) => g.key));
+        const generatedNames = [];
+        for (const g of generated.generatedKeys) {
+            const pinned = merged[g.key];
+            let val;
+            if (pinned !== undefined && pinned !== '') {
+                val = pinned.replace(/[\r\n]/g, '');
+            }
+            else {
+                val = (0, compose_generator_1.generateSecretValue)(g.encoding, g.bytes);
+                generatedNames.push(g.key);
+            }
+            envLines.push(`${g.key}=${val}`);
+        }
+        // Any explicitly provided vars not already declared as secrets/generated.
+        for (const [k, v] of Object.entries(merged)) {
+            if (!generated.secretKeys.includes(k) && !generatedKeySet.has(k)) {
+                envLines.push(`${k}=${v.replace(/[\r\n]/g, '')}`);
+            }
+        }
+        const envPath = path.join(appDir, '.env');
+        try {
+            fs.writeFileSync(envPath, envLines.join('\n') + '\n', { mode: 0o600 });
+            // writeFileSync's `mode` only applies when the file is created; on
+            // reconfigure the .env already exists, so re-assert 0600 explicitly to
+            // keep secrets owner-only regardless of the file's prior permissions.
+            fs.chmodSync(envPath, 0o600);
+        }
+        catch (err) {
+            throw new Error(`Failed to write .env: ${err.message}`);
+        }
+        return generatedNames;
+    }
+    /** Parse an app's existing .env into a key→value map (empty if absent). */
+    readEnvFile(appDir) {
+        const envPath = path.join(appDir, '.env');
+        const out = {};
+        if (!fs.existsSync(envPath))
+            return out;
+        const content = fs.readFileSync(envPath, 'utf-8');
+        for (const rawLine of content.split('\n')) {
+            const line = rawLine.trim();
+            if (!line || line.startsWith('#'))
+                continue;
+            const eq = line.indexOf('=');
+            if (eq <= 0)
+                continue;
+            out[line.slice(0, eq)] = line.slice(eq + 1);
+        }
+        return out;
+    }
     /**
      * Resolve the repo URL and target commit to update an installed app to.
      * - `registry`: latest published version via the registry client.
@@ -854,7 +1168,8 @@ class AppInstaller {
                 const latest = selectLatest(app.versions);
                 if (!latest)
                     throw new Error(`No versions available for "${options.registryApp}"`);
-                this.log(job, `Using latest version ${latest.version}`);
+                if (job)
+                    this.log(job, `Using latest version ${latest.version}`);
                 return {
                     appName: options.registryApp,
                     commit: latest.commit,
@@ -884,13 +1199,15 @@ class AppInstaller {
             }
             else {
                 // Auto-resolve HEAD commit via git ls-remote
-                this.log(job, `Resolving HEAD commit for ${options.githubUrl}`);
+                if (job)
+                    this.log(job, `Resolving HEAD commit for ${options.githubUrl}`);
                 const { stdout } = this.run(['git', 'ls-remote', options.githubUrl, 'HEAD'], process.cwd());
                 const match = stdout.trim().match(/^([0-9a-f]{40})\s+HEAD/);
                 if (!match)
                     throw new Error(`Could not resolve HEAD commit for ${options.githubUrl}`);
                 commit = match[1];
-                this.log(job, `Resolved HEAD → ${commit.slice(0, 8)}`);
+                if (job)
+                    this.log(job, `Resolved HEAD → ${commit.slice(0, 8)}`);
             }
             const appName = options.githubUrl.split('/').pop()?.replace(/\.git$/, '') ?? 'app';
             return {
@@ -943,10 +1260,14 @@ class AppInstaller {
      * Captures container logs into the job on failure before rethrowing.
      * job is optional — when omitted (e.g. startStopRestart) logs go to stderr.
      */
-    composeUp(appName, dir, job) {
+    composeUp(appName, dir, job, opts) {
         this.stopConflictingContainers(appName);
+        const args = ['docker', 'compose', '-p', appName, 'up', '-d', '--wait'];
+        if (opts?.forceRecreate) {
+            args.push('--force-recreate');
+        }
         try {
-            this.run(['docker', 'compose', '-p', appName, 'up', '-d', '--wait'], dir, 600000);
+            this.run(args, dir, 600000);
         }
         catch (upErr) {
             if (job) {