@0xmaxma/claude-gateway 1.6.4 → 1.6.6

package/mcp/tools/apps/module.ts

@@ -78,7 +78,7 @@ export class AppsModule implements ToolModule {
       },
       {
         name: 'inspect_app',
-        description: 'Preview an install source WITHOUT installing: fetch and parse the app.yaml and return the required secrets (secretKeys, must be provided) and auto-generated secrets (generatedKeys, filled by the gateway), plus name, version, ports, and warnings. Call this BEFORE install_app for a GitHub URL — such apps have no registry entry, so browse_registry cannot reveal their required secrets. Pass github_url (+ optional commit), registry_app (+ optional version), or local_path.',
+        description: 'Preview an install source WITHOUT installing: fetch and parse the app.yaml and return the required secrets (secretKeys, must be provided) and auto-generated secrets (generatedKeys, filled by the gateway), plus name, version, ports, and warnings. Also returns secretDefaults — defaults for prompt-with-default secrets declared as KEY=!default:<value>: the key is still in secretKeys (prompted/editable) but this default pre-fills the field and is written to .env when left blank. Call this BEFORE install_app for a GitHub URL — such apps have no registry entry, so browse_registry cannot reveal their required secrets. Pass github_url (+ optional commit), registry_app (+ optional version), or local_path.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -149,6 +149,58 @@ export class AppsModule implements ToolModule {
           additionalProperties: false,
         },
       },
+      {
+        name: 'docker_housekeeping',
+        description: 'Reclaim leaked Docker build cache and dangling images left behind by app install/update. mode "report" (default) returns a read-only reclaim report: reclaimable build cache, dangling image count, and orphan volume names. mode "prune" executes ONLY the safe reclaim (build cache older than the configured window + dangling <none> images) — it NEVER removes another app\'s tagged images, and NEVER deletes a volume. Orphan volumes are reported but never auto-deleted (they can hold real app data).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            mode: {
+              type: 'string',
+              enum: ['report', 'prune'],
+              description: 'report (default) = read-only reclaim report; prune = execute the safe reclaim (build cache + dangling images only)',
+            },
+          },
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'backup_app',
+        description: 'Back up an installed app — a permission-safe snapshot of its Docker named volumes, bind-mount data directories under the app dir, and config (.env/app.yaml) into a single archive. The app is briefly stopped for a consistent snapshot and restarted afterward. Returns a jobId; poll with poll_install_job. Older backups beyond the retention limit are pruned automatically.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'App name to back up' },
+          },
+          required: ['name'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'restore_app',
+        description: "Restore an app's Docker named volumes, bind-mount data directories under the app dir, and config from a prior backup, then start it on the restored data. Restoring a backup from a different app version is allowed but may warn about schema/migration mismatch. Returns a jobId; poll with poll_install_job. Use list_backups to pick a backup_id.",
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'App name to restore' },
+            backup_id: { type: 'string', description: 'Backup id to restore (from list_backups)' },
+          },
+          required: ['name', 'backup_id'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'list_backups',
+        description: "List an app's backups, newest first: each entry has id, createdAt, sizeBytes, and appVersion. Use the id with restore_app.",
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'App name' },
+          },
+          required: ['name'],
+          additionalProperties: false,
+        },
+      },
     ];
   }
 
@@ -227,6 +279,31 @@ export class AppsModule implements ToolModule {
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
       }
 
+      case 'docker_housekeeping': {
+        const mode = (args['mode'] as 'report' | 'prune' | undefined) ?? 'report';
+        const data = await client.housekeeping(mode);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      }
+
+      case 'backup_app': {
+        const appName = args['name'] as string;
+        const data = await client.backup(appName);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      }
+
+      case 'restore_app': {
+        const appName = args['name'] as string;
+        const backupId = args['backup_id'] as string;
+        const data = await client.restore(appName, backupId);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      }
+
+      case 'list_backups': {
+        const appName = args['name'] as string;
+        const data = await client.listBackups(appName);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      }
+
       default:
         return {
           content: [{ type: 'text', text: `Unknown tool: ${name}` }],

package/mcp/tools/apps/skills/create-app-yaml/SKILL.md

@@ -80,6 +80,9 @@ Rules for port type:
 Rules for environment variables:
 - If the Dockerfile has `ENV FOO=bar` → `FOO=bar` (has default)
 - If you see `ARG FOO` or `ENV FOO` with no value → `FOO` (secret, no default — installer prompts for it)
+- If the value has a **sensible default the operator should still be able to override** (e.g. `NEXTAUTH_URL`, a public base URL, a tunable timeout) → `FOO=!default:<value>`. It is prompted like a bare key (visible and editable in the install UI, pre-filled with `<value>`), but if the operator leaves it blank the default is written to `.env` — so the app never boots with an empty required field.
+  - The value is taken verbatim and may contain `:` and `/` — e.g. `NEXTAUTH_URL=!default:http://localhost:3737`.
+  - Prefer this over a bare `FOO` whenever a good default exists, and over a static `FOO=value` whenever the operator should be able to change it at install.
 - If the value is a **per-install random string** the user cannot meaningfully supply (session secret, DB password, internal API token) → `FOO=!generate:<encoding>:<bytes>`. The installer fills it with a fresh random value automatically, so the install never stalls asking for it.
   - Encodings: `hex`, `base64`, `base64url` (use `base64url` when the value is embedded in a URL or connection string — it has no `+` `/` `=`). Length is `8`–`512` bytes.
   - Examples: `NEXTAUTH_SECRET=!generate:base64:32`, `DB_PASSWORD=!generate:base64url:24`

package/mcp/tools/apps/skills/install-app/SKILL.md

@@ -54,23 +54,32 @@ Call `inspect_app` with the same source you will install (`github_url` [+ `commi
 - `generatedKeys` — secrets the gateway **auto-generates** at install time
   (declared as `KEY=!generate:...`). Do **not** prompt for these; just note they
   will be generated.
+- `secretDefaults` — defaults for prompt-with-default secrets (declared as
+  `KEY=!default:<value>`). These keys still appear in `secretKeys`, so prompt for
+  them — but **pre-fill the default** and tell the user they can keep it. If they
+  leave it blank, the default is written to `.env` (operator value → default →
+  empty).
 
 This is essential for a **GitHub-URL** install: such apps have no registry entry,
 so `browse_registry` cannot reveal their secrets — only `inspect_app` can.
 
-If `inspect_app` reports `secretKeys`, prompt the user for each:
+If `inspect_app` reports `secretKeys`, prompt the user for each (showing the
+default from `secretDefaults` when one exists):
 
 ```
 This app requires the following environment variables:
   MY_API_KEY — (no default)
   SOME_TOKEN — (no default)
+  NEXTAUTH_URL — default: http://localhost:3737 (press enter to keep)
 
 Please provide values, e.g.:
   MY_API_KEY=xxx
   SOME_TOKEN=yyy
 ```
 
-Wait for the user's reply. Parse key=value pairs.
+Wait for the user's reply. Parse key=value pairs. For a key with a default, an
+omitted or blank value means "use the default" — do not send an empty string
+expecting the app to fail.
 
 If `secretKeys` is empty (only `generatedKeys`, or no secrets at all), proceed
 immediately — do not invent secrets or ask for ones the app did not declare.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xmaxma/claude-gateway",
-  "version": "1.6.4",
+  "version": "1.6.6",
   "description": "Multi-agent gateway for Claude",
   "repository": {
     "type": "git",