dokku-compose 0.12.0 → 0.13.0

package/README.md

@@ -101,9 +101,32 @@ Running `up` again produces no changes — every step checks current state befor
 | `--dry-run` | Print commands without executing |
 | `--sensitive` | Show sensitive values in output (masked by default) |
 | `--fail-fast` | Stop on first error (default: continue to next app) |
+| `--prune` | `up` only: also reset settings the file no longer declares (read `diff` first) |
 | `--remove-orphans` | Destroy services and networks not in config |
 | `--verbose` | Show git-style +/- diff (diff command only) |
 
+### Settings removed from the file
+
+`diff` marks with a red `-` every setting the server still has that the file no longer declares
+(managed env keys, nginx, logs, registry, scheduler, checks, `ps` and network properties, build
+args, and entries missing from a declared list), including when the whole block is gone. Only
+settable keys count, never read-only report lines, and a `-` counts as drift. It also warns when
+an app has no `links:` but has services linked on the server, because `up` unlinks them.
+
+`up` always unsets env keys removed from the file. For every other removal it leaves the setting in place and prints a one-line count per app of the leftovers it noticed in the blocks you declare; it does not look at removed whole blocks or checks. Run `dokku-compose diff` for the full list.
+
+**`up --prune`** resets those leftovers. Read `diff` first: every `-` it shows for the resources below is what `--prune` will reset, and there is no prompt (`diff` is the preview, the flag is the consent). Add `--dry-run` to print the reset commands without running them.
+
+| Resource | Reset command |
+|----------|---------------|
+| `nginx`, `logs`, `registry`, `ps` | `<plugin>:set <app> <key>` with no value (Dokku's default); nginx then rebuilds the proxy config |
+| `scheduler` | `scheduler:set <app> selected` |
+| `network` properties | `network:set <app> <key>` with no value (`attach_post_create` becomes `attach-post-create`, and so on) |
+| `checks` | `checks:enable <app> <types>` for the process types of a removed `disabled`/`skipped` list that the file declares in no list (a type the file does declare is left, with a warning naming the command to run by hand), `checks:set <app> wait-to-retire` |
+| `build.args` | `docker-options:remove <app> build "--build-arg KEY=VALUE"` for each stale key, by the exact option text (every occurrence); other build options stay |
+
+It covers a block that is gone from the file as well as keys removed from a declared block, and it reads the app once more for a block the file no longer has. `--prune` never destroys an app, service or network, never uninstalls a plugin, never changes `scale`, and does not clear whole `domains`, `ports`, `storage` or `networks` lists because their key is missing (those already prune inside a block the file declares). `proxy` is not a removal. `networks:` owns `attach-post-deploy`: `--prune` does not touch it, and a missing `networks:` key does not clear it (that could detach a running app from its network on the next deploy); `networks: []` does. After `up --prune`, `diff` shows no `-` for the resources above, except for checks that were skipped with a warning (their `-` lines stay).
+
 ### Errors
 
 A failing Dokku command (mutation) is never reported as a success. On `up` and `down`, a
@@ -123,7 +146,7 @@ All features are idempotent — running `up` twice produces no changes.
 |---------|-------------|-----------|
 | Apps | Create and destroy Dokku apps | [apps](docs/reference/apps.md) |
 | Dokku Version | Warn when the server's Dokku version is older than the pinned floor | [dokku](docs/reference/dokku.md) |
-| Environment Variables | Set config vars per app or globally, with full convergence | [config](docs/reference/config.md) |
+| Environment Variables | Set config vars per app or globally, with full convergence (keys removed from the YAML are unset) | [config](docs/reference/config.md) |
 | Build | Dockerfile path, build context, app.json, build args | [builder](docs/reference/builder.md) |
 | Docker Options | Custom Docker options per phase (build/deploy/run) | [docker_options](docs/reference/docker_options.md) |
 | Networks | Create shared Docker networks, attach to apps | [network](docs/reference/network.md) |
@@ -131,16 +154,29 @@ All features are idempotent — running `up` twice produces no changes.
 | Port Mappings | Map external ports to container ports | [ports](docs/reference/ports.md) |
 | SSL Certificates | Add or remove SSL certs | [certs](docs/reference/certs.md) |
 | Proxy | Enable/disable proxy, select implementation | [proxy](docs/reference/proxy.md) |
-| Storage | Persistent bind mounts with full convergence | [storage](docs/reference/storage.md) |
+| Storage | Persistent bind mounts with full convergence (keys removed from the YAML are unset) | [storage](docs/reference/storage.md) |
 | Nginx | Set any nginx property per app or globally | [nginx](docs/reference/nginx.md) |
 | Zero-Downtime Checks | Configure deploy checks, disable per process type | [checks](docs/reference/checks.md) |
 | Log Management | Log retention and vector sink configuration | [logs](docs/reference/logs.md) |
-| Plugins | Install Dokku plugins declaratively | [plugins](docs/reference/plugins.md) |
+| Plugins | Install Dokku plugins at pinned versions, updating forward only | [plugins](docs/reference/plugins.md) |
+| Process Scale & ps | Declare process counts (`ps:scale`) and ps properties (`ps:set`) | [scale](docs/reference/scale.md) |
 | Docker Auth | Authenticate the host docker daemon to private registries (e.g. ghcr.io) for `git:from-image` flows | [docker_auth](docs/reference/docker_auth.md) |
 | Postgres | Postgres services with optional S3 backups | [postgres](docs/reference/postgres.md) |
 | Redis | Redis service instances | [redis](docs/reference/redis.md) |
 | Service Links | Link postgres/redis services to apps | [plugins](docs/reference/plugins.md#linking-services-to-apps-appsapplinks) |
 
+## Variable interpolation
+
+`${VAR}` in a string value is replaced with the environment variable `VAR`. The file is parsed as YAML first and substituted afterwards, value by value, so a secret can contain any character (`"`, `'`, `#`, `\`, `:`, newlines) and arrives in the value unchanged; it can never change the file's structure. Keys and comments are never substituted. Every unset or empty variable is collected and reported together:
+
+```
+Unset environment variable(s) referenced in config: R2_HOST, GITHUB_TOKEN
+```
+
+To write a literal `${`, use `$${`: `"$${NOT_A_VAR}"` loads as `${NOT_A_VAR}`.
+
+Because substitution happens after parsing, a value that is a bare `${VAR}` is always a string, and a variable cannot inject YAML (extra keys, lists, quoting). Earlier versions substituted into the raw text, so anything that relied on that must now be written in the file.
+
 ## Execution Modes
 
 ```bash
@@ -197,7 +233,7 @@ dokku-compose/
 │   │   └── validate.ts       # validate command (offline)
 │   └── tests/
 │       ├── fixtures/         # Test YAML configs
-│       └── *.test.ts         # Unit tests per module
+│       └── *.test.ts         # Unit tests, beside src/modules and src/resources
 └── dokku-compose.yml.example
 ```
 
@@ -215,8 +251,8 @@ bun install
 # Run all tests
 bun test
 
-# Run a specific module's tests
-bun test src/modules/postgres.test.ts
+# Run a specific file's tests
+bun test src/resources/config.test.ts
 ```
 
 Tests use [Bun's test runner](https://bun.sh/docs/cli/test) with a mocked `Runner` — no real Dokku server needed.

package/dist/index.js

@@ -53,6 +53,12 @@ var AppSchema = z.object({
   logs: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
   registry: z.record(z.string(), z.union([z.string(), z.boolean()])).optional(),
   scheduler: z.string().optional(),
+  scale: z.record(z.string(), z.preprocess((v) => typeof v === "string" && /^\s*-?\d+\s*$/.test(v) ? Number(v) : v, z.number().int().min(0))).optional(),
+  ps: z.object({
+    "procfile-path": z.union([z.string(), z.number()]).optional(),
+    "restart-policy": z.union([z.string(), z.number()]).optional(),
+    "stop-timeout-seconds": z.union([z.string(), z.number()]).optional()
+  }).strict().optional(),
   checks: ChecksSchema.optional(),
   build: z.object({
     dockerfile: z.string().optional(),
@@ -117,16 +123,29 @@ function parseConfig(raw) {
 }
 
 // src/core/config.ts
-function interpolateEnvVars(content) {
+function interpolateValue(value, missing) {
+  if (typeof value === "string") {
+    return value.replace(/\$\$\{|\$\{([^}]+)\}/g, (match, name) => {
+      if (name === void 0) return "${";
+      const v = process.env[name];
+      if (v === void 0 || v === "") {
+        missing.push(name);
+        return "";
+      }
+      return v;
+    });
+  }
+  if (Array.isArray(value)) return value.map((v) => interpolateValue(v, missing));
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = interpolateValue(v, missing);
+    return out;
+  }
+  return value;
+}
+function interpolateEnvVars(raw) {
   const missing = [];
-  const result = content.replace(/\$\{([^}]+)\}/g, (_, name) => {
-    const value = process.env[name];
-    if (value === void 0 || value === "") {
-      missing.push(name);
-      return "";
-    }
-    return value;
-  });
+  const result = interpolateValue(raw, missing);
   if (missing.length > 0) {
     const unique = Array.from(new Set(missing));
     throw new Error(
@@ -140,7 +159,7 @@ function loadConfig(filePath) {
     throw new Error(`Config file not found: ${filePath}`);
   }
   const content = fs.readFileSync(filePath, "utf8");
-  const raw = yaml.load(interpolateEnvVars(content));
+  const raw = interpolateEnvVars(yaml.load(content));
   return parseConfig(raw);
 }
 
@@ -279,6 +298,11 @@ function createRunner(opts = {}) {
       const { stdout } = await execDokku(args);
       return stdout.trim();
     },
+    async queryStrict(...args) {
+      const { stdout, ok, exitCode, stderr } = await execDokku(args);
+      if (!ok) throw new DokkuCommandError(args, exitCode, stderr);
+      return stdout.trim();
+    },
     async check(...args) {
       const { ok } = await execDokku(args);
       return ok;
@@ -307,6 +331,9 @@ function createContext(runner) {
       }
       return cache.get(key);
     },
+    queryStrict(...args) {
+      return runner.queryStrict(...args);
+    },
     check(...args) {
       return runner.check(...args);
     },
@@ -355,6 +382,11 @@ function computeChange(before, after) {
   }
   return { before, after, changed: before !== after };
 }
+function computeAdditiveChange(before, after) {
+  const change = computeChange(before ?? {}, after);
+  change.changed = Object.keys(change.added).length > 0 || Object.keys(change.modified).length > 0;
+  return change;
+}
 
 // src/core/logger.ts
 import chalk from "chalk";
@@ -375,16 +407,41 @@ function logWarn(context, message) {
 }
 
 // src/core/reconcile.ts
-async function reconcile(resource, ctx, target, desired) {
-  if (desired === void 0) return;
+async function reconcile(resource, ctx, target, desired, onRemovals, prune = false) {
+  const canPrune = prune && !!resource.prune && !!resource.removals;
+  const pruneFrom = async (current) => {
+    const removed = resource.removals(current, desired);
+    if (removed.length === 0) return;
+    logAction(target, `${resource.key} (prune)`);
+    await resource.prune(ctx, target, removed, current, desired);
+    logDone();
+  };
+  if (desired === void 0) {
+    if (canPrune) await pruneFrom(await resource.read(ctx, target));
+    return;
+  }
   logAction(target, `${resource.key}`);
   if (resource.forceApply) {
     await resource.onChange(ctx, target, { before: void 0, after: desired, changed: true });
     logDone();
+    if (canPrune) await pruneFrom(await resource.read(ctx, target));
     return;
   }
   const before = await resource.read(ctx, target);
-  const change = computeChange(before, desired);
+  if (onRemovals && resource.removals) onRemovals(resource.removals(before, desired));
+  if (canPrune) {
+    const change2 = resource.additive ? computeAdditiveChange(before, desired) : computeChange(before, desired);
+    const pending = resource.removals(before, desired).length > 0;
+    if (change2.changed) {
+      await resource.onChange(ctx, target, change2, pending);
+      logDone();
+    } else {
+      logSkip();
+    }
+    await pruneFrom(before);
+    return;
+  }
+  const change = resource.additive ? computeAdditiveChange(before, desired) : computeChange(before, desired);
   if (!change.changed) {
     logSkip();
     return;
@@ -520,9 +577,69 @@ async function isAppDeployed(ctx, target) {
   const raw = await ctx.query("ps:report", target, "--deployed");
   return raw.trim() === "true";
 }
+var NGINX_KEYS = [
+  "access-log-format",
+  "access-log-path",
+  "bind-address-ipv4",
+  "bind-address-ipv6",
+  "client-body-timeout",
+  "client-header-timeout",
+  "client-max-body-size",
+  "disable-custom-config",
+  "error-log-path",
+  "hsts",
+  "hsts-include-subdomains",
+  "hsts-max-age",
+  "hsts-preload",
+  "keepalive-timeout",
+  "lingering-timeout",
+  "proxy-buffer-size",
+  "proxy-buffering",
+  "proxy-buffers",
+  "proxy-busy-buffers-size",
+  "proxy-connect-timeout",
+  "proxy-keepalive",
+  "proxy-read-timeout",
+  "proxy-send-timeout",
+  "send-timeout",
+  "underscore-in-headers",
+  "x-forwarded-for-value",
+  "x-forwarded-port-value",
+  "x-forwarded-proto-value",
+  "x-forwarded-ssl"
+];
+var LOGS_KEYS = ["app-label-alias", "max-size", "vector-cron-sink", "vector-sink"];
+var REGISTRY_KEYS = [
+  "auth-servers",
+  "image-repo",
+  "image-repo-template",
+  "push-extra-tags",
+  "push-on-release",
+  "server"
+];
+function propertyRemovals(allowed) {
+  return (current, desired) => Object.keys(current ?? {}).filter((k) => allowed.includes(k) && !(desired && k in desired));
+}
+function propertyPrune(setCmd, afterPrune = []) {
+  return async (ctx, target, removed) => {
+    for (const key of removed) await ctx.run(setCmd, target, key);
+    for (const cmd of afterPrune) {
+      try {
+        await ctx.run(cmd, target);
+      } catch (err) {
+        if (await isAppDeployed(ctx, target)) throw err;
+        logWarn(target, `${cmd} failed on an undeployed app \u2014 its proxy config will be built on first deploy`);
+      }
+    }
+  };
+}
 function propertyResource(opts) {
   return {
     key: opts.key,
+    // Keys only on the server never make the block "changed"; diff shows them as removals.
+    additive: true,
+    removals: propertyRemovals(opts.settable),
+    prune: propertyPrune(opts.setCmd, opts.afterChange),
     async read(ctx, target) {
       const raw = await ctx.query(`${opts.namespace}:report`, target);
       return parseReport(raw, opts.namespace);
@@ -531,11 +648,11 @@ function propertyResource(opts) {
       const raw = await ctx.query(`${opts.namespace}:report`);
       return parseBulkReport(raw, opts.namespace);
     },
-    async onChange(ctx, target, change) {
+    async onChange(ctx, target, change, deferFollowUp = false) {
       for (const [key, value] of Object.entries({ ...change.added, ...change.modified })) {
         await ctx.run(opts.setCmd, target, key, String(value));
       }
-      if (opts.afterChange) {
+      if (opts.afterChange && !deferFollowUp) {
         for (const cmd of opts.afterChange) {
           try {
             await ctx.run(cmd, target);
@@ -552,20 +669,28 @@ var Nginx = propertyResource({
   key: "nginx",
   namespace: "nginx",
   setCmd: "nginx:set",
+  settable: NGINX_KEYS,
   afterChange: ["proxy:build-config"]
 });
 var Logs = propertyResource({
   key: "logs",
   namespace: "logs",
-  setCmd: "logs:set"
+  setCmd: "logs:set",
+  settable: LOGS_KEYS
 });
 var Registry = propertyResource({
   key: "registry",
   namespace: "registry",
-  setCmd: "registry:set"
+  setCmd: "registry:set",
+  settable: REGISTRY_KEYS
 });
 var Scheduler = {
   key: "scheduler",
+  // A scheduler selected on the app but not declared in the file.
+  removals: (current, desired) => desired === void 0 && current ? ["scheduler"] : [],
+  prune: async (ctx, target) => {
+    await ctx.run("scheduler:set", target, "selected");
+  },
   async read(ctx, target) {
     const raw = await ctx.query("scheduler:report", target);
     const report = parseReport(raw, "scheduler");
@@ -606,21 +731,38 @@ var Proxy = {
   }
 };
 
+// src/core/config-json.ts
+function parseConfigJson(raw, what) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${what}: config:export did not return JSON`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${what}: config:export did not return a JSON object`);
+  }
+  const result = {};
+  for (const [k, v] of Object.entries(parsed)) result[k] = String(v);
+  return result;
+}
+
 // src/resources/config.ts
 var MANAGED_KEYS_VAR = "DOKKU_COMPOSE_MANAGED_KEYS";
+var MISSING = "\0missing";
 var Config = {
   key: "env",
+  removals: (current, desired) => Object.keys(current ?? {}).filter((k) => !(desired && typeof desired === "object" && k in desired)),
   read: async (ctx, target) => {
     const managedRaw = await ctx.query("config:get", target, MANAGED_KEYS_VAR);
     const managedKeys = managedRaw.trim() ? managedRaw.trim().split(",").filter(Boolean) : [];
     const result = {};
+    for (const k of managedKeys) result[k] = MISSING;
     if (managedKeys.length > 0) {
-      const raw = await ctx.query("config:export", target, "--format", "shell");
-      for (const line of raw.split("\n")) {
-        const match = line.match(/^export\s+(\w+)=['"]?(.*?)['"]?$/);
-        if (match && managedKeys.includes(match[1])) {
-          result[match[1]] = match[2];
-        }
+      const raw = await ctx.queryStrict("config:export", "--format", "json", target);
+      const current = parseConfigJson(raw, target);
+      for (const k of managedKeys) {
+        if (k in current) result[k] = current[k];
       }
     }
     return result;
@@ -630,9 +772,12 @@ var Config = {
     if (removed.length > 0) {
       await ctx.run("config:unset", "--no-restart", target, ...removed);
     }
-    const toSet = { ...added, ...modified };
     const allDesiredKeys = Object.keys(change.after);
-    const managedValue = allDesiredKeys.join(",");
+    if (allDesiredKeys.length === 0) {
+      await ctx.run("config:unset", "--no-restart", target, MANAGED_KEYS_VAR);
+      return;
+    }
+    const toSet = { ...added, ...modified };
     if (Object.keys(toSet).length > 0 || removed.length > 0) {
       const pairs = Object.entries(change.after).map(([k, v]) => `${k}=${v}`);
       await ctx.run(
@@ -640,7 +785,7 @@ var Config = {
         "--no-restart",
         target,
         ...pairs,
-        `${MANAGED_KEYS_VAR}=${managedValue}`
+        `${MANAGED_KEYS_VAR}=${allDesiredKeys.join(",")}`
       );
     }
   }
@@ -675,10 +820,17 @@ var Certs = {
 };
 
 // src/resources/builder.ts
+function parseBuildOptions(dockerOptsBuild) {
+  const out = [];
+  for (const raw of dockerOptsBuild.trim().split(/\s+(?=--\S)/)) {
+    const m = raw.match(/^--build-arg\s+([^=\s]+)=?(.*)$/s);
+    if (m) out.push({ key: m[1], value: m[2], raw });
+  }
+  return out;
+}
 function parseBuildArgs(dockerOptsBuild) {
   const args = {};
-  const matches = dockerOptsBuild.matchAll(/--build-arg\s+(\S+?)=(\S+)/g);
-  for (const m of matches) args[m[1]] = m[2];
+  for (const o of parseBuildOptions(dockerOptsBuild)) args[o.key] = o.value;
   return args;
 }
 function buildConfigFromReports(builderReport, dockerfileReport, appJsonReport, dockerOptsBuild) {
@@ -695,6 +847,19 @@ function buildConfigFromReports(builderReport, dockerfileReport, appJsonReport,
 }
 var Builder = {
   key: "build",
+  additive: true,
+  // Build args (`--build-arg KEY=...` build docker options) whose KEY is not in `build.args`.
+  removals: (current, desired) => Object.keys(current?.args ?? {}).filter((k) => !(desired?.args && k in desired.args)).map((k) => `args.${k}`),
+  // Remove exactly the stale `--build-arg` options; other build options stay.
+  prune: async (ctx, target, removed) => {
+    const stale = new Set(removed.map((l) => l.slice("args.".length)));
+    const report = parseReport(await ctx.query("docker-options:report", target), "docker-options");
+    const options = parseBuildOptions(report["build"] ?? "").filter((o) => stale.has(o.key));
+    for (const o of options) await ctx.run("docker-options:remove", target, "build", o.raw);
+    for (const k of stale) {
+      if (!options.some((o) => o.key === k)) logWarn(target, `build arg '${k}' not found as an exact docker option; left as is`);
+    }
+  },
   async read(ctx, target) {
     const [builderRaw, dockerfileRaw, appJsonRaw, dockerOptsRaw] = await Promise.all([
       ctx.query("builder:report", target),
@@ -766,6 +931,11 @@ function dockerOptsFromReport(report) {
 }
 var DockerOptions = {
   key: "docker_options",
+  // Pruned by `up` within a declared block only, so a missing block is not shown.
+  removals: (current, desired) => !desired ? [] : PHASES.flatMap((phase) => {
+    const wanted = new Set(desired?.[phase] ?? []);
+    return (current?.[phase] ?? []).filter((o) => !wanted.has(o)).map((o) => `${phase}: ${o}`);
+  }),
   async read(ctx, target) {
     const raw = await ctx.query("docker-options:report", target);
     return dockerOptsFromReport(parseReport(raw, "docker-options"));
@@ -793,6 +963,68 @@ var DockerOptions = {
   }
 };
 
+// src/resources/ps.ts
+var PS_KEYS = ["procfile-path", "restart-policy", "stop-timeout-seconds"];
+function parseScale(raw) {
+  const result = {};
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return result;
+  }
+  if (!Array.isArray(parsed)) return result;
+  for (const e of parsed) {
+    if (e && typeof e.process_type === "string" && e.quantity !== void 0) {
+      result[e.process_type] = String(e.quantity);
+    }
+  }
+  return result;
+}
+function parsePsReport(raw) {
+  const result = {};
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return result;
+  }
+  if (!parsed || typeof parsed !== "object") return result;
+  for (const key of PS_KEYS) {
+    const v = parsed[key];
+    if (v !== void 0 && v !== null && String(v) !== "") result[key] = String(v);
+  }
+  return result;
+}
+var Scale = {
+  key: "scale",
+  additive: true,
+  async read(ctx, target) {
+    return parseScale(await ctx.query("ps:scale", "--format", "json", target));
+  },
+  async onChange(ctx, target, change) {
+    const pairs = Object.entries({ ...change.added, ...change.modified }).map(([proc, count]) => `${proc}=${count}`);
+    if (pairs.length === 0) return;
+    await ctx.run("ps:scale", "--skip-deploy", target, ...pairs);
+  }
+};
+var Ps = {
+  key: "ps",
+  additive: true,
+  removals: (current, desired) => PS_KEYS.filter((k) => current?.[k] !== void 0 && !(desired && k in desired)),
+  prune: async (ctx, target, removed) => {
+    for (const key of removed) await ctx.run("ps:set", target, key);
+  },
+  async read(ctx, target) {
+    return parsePsReport(await ctx.queryStrict("ps:report", target, "--format", "json"));
+  },
+  async onChange(ctx, target, change) {
+    for (const [key, value] of Object.entries({ ...change.added, ...change.modified })) {
+      await ctx.run("ps:set", target, key, String(value));
+    }
+  }
+};
+
 // src/resources/git.ts
 var Git = {
   key: "git",
@@ -820,7 +1052,33 @@ var Git = {
 var Checks = {
   key: "checks",
   forceApply: true,
-  read: async () => ({}),
+  // Applying never reads (forceApply); the read only finds settings to report as removed.
+  // Settable state: the per-process lists and `wait-to-retire`. A list of "none" is empty.
+  read: async (ctx, target) => {
+    const report = parseReport(await ctx.query("checks:report", target), "checks");
+    const current = {};
+    for (const [reportKey, key] of [["disabled-list", "disabled"], ["skipped-list", "skipped"]]) {
+      const v = report[reportKey];
+      if (v && v !== "none" && v !== "_all_") current[key] = v;
+    }
+    if (report["wait-to-retire"]) current["wait-to-retire"] = report["wait-to-retire"];
+    return current;
+  },
+  removals: (current, desired) => desired === false ? [] : Object.keys(current || {}).filter((k) => !(desired && k in desired)),
+  prune: async (ctx, target, removed, current, desired) => {
+    const cur = current;
+    const split = (v) => (v ?? "").split(",").map((t) => t.trim()).filter(Boolean);
+    const declared = new Set(desired && desired !== false ? [...desired.disabled ?? [], ...desired.skipped ?? []] : []);
+    const stale = new Set(removed.filter((k) => k === "disabled" || k === "skipped").flatMap((k) => split(cur[k])));
+    const enable = [...stale].filter((t) => !declared.has(t));
+    for (const t of stale) {
+      if (declared.has(t)) {
+        logWarn(target, `checks: '${t}' is declared in the file but also set in a list the file does not declare; left as is. Run 'dokku checks:enable ${target} ${t}' and then 'up' to clear it`);
+      }
+    }
+    if (enable.length > 0) await ctx.run("checks:enable", target, ...enable);
+    if (removed.includes("wait-to-retire")) await ctx.run("checks:set", target, "wait-to-retire");
+  },
   onChange: async (ctx, target, { after }) => {
     if (after === false) {
       await ctx.run("checks:disable", target);
@@ -861,6 +1119,12 @@ var Networks = {
 };
 var NetworkProps = {
   key: "network",
+  additive: true,
+  removals: (current, desired) => Object.keys(current ?? {}).filter((k) => !(desired && k in desired)),
+  // Dokku's property names are hyphenated; the schema's are underscored.
+  prune: async (ctx, target, removed) => {
+    for (const key of removed) await ctx.run("network:set", target, key.replaceAll("_", "-"));
+  },
   read: async (ctx, target) => {
     const raw = await ctx.query("network:report", target);
     const report = parseReport(raw, "network");
@@ -907,19 +1171,90 @@ var NetworkProps = {
 };
 
 // src/modules/plugins.ts
+function parsePluginList(raw) {
+  const result = /* @__PURE__ */ new Map();
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`plugin:list --format json did not return JSON (does this Dokku support --format json?): ${raw.slice(0, 200)}`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`plugin:list --format json did not return a JSON array: ${raw.slice(0, 200)}`);
+  }
+  for (const p of parsed) {
+    if (p && typeof p.name === "string") {
+      result.set(p.name, {
+        version: typeof p.version === "string" ? p.version : "",
+        committish: typeof p.committish === "string" ? p.committish : ""
+      });
+    }
+  }
+  return result;
+}
+var SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+function compareVersions(a, b) {
+  const na = a.replace(/^v/, "");
+  const nb = b.replace(/^v/, "");
+  const ma = na.match(SEMVER);
+  const mb = nb.match(SEMVER);
+  if (!ma || !mb) return na === nb ? 0 : void 0;
+  for (let i = 1; i <= 3; i++) {
+    const d = Number(ma[i]) - Number(mb[i]);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+var SHA = /^[0-9a-f]{7,40}$/i;
+function planPlugins(listOutput, plugins) {
+  const installed = parsePluginList(listOutput);
+  return Object.entries(plugins).map(([name, config]) => {
+    const current = installed.get(name);
+    const desired = config.version;
+    if (current === void 0) return { name, action: "install", desired };
+    const installedVersion = current.version || current.committish.slice(0, 7) || void 0;
+    if (desired === void 0) return { name, action: "ok", installed: installedVersion };
+    if (SHA.test(desired) && current.committish) {
+      if (current.committish.toLowerCase().startsWith(desired.toLowerCase())) {
+        return { name, action: "ok", installed: installedVersion, desired };
+      }
+    }
+    if (!current.version) return { name, action: "unknown", installed: installedVersion, desired };
+    const cmp = compareVersions(current.version, desired);
+    const action = cmp === void 0 ? "unknown" : cmp < 0 ? "update" : cmp > 0 ? "newer" : "ok";
+    return { name, action, installed: installedVersion, desired };
+  });
+}
 async function ensurePlugins(ctx, plugins) {
-  const listOutput = await ctx.query("plugin:list");
-  const installedNames = new Set(
-    listOutput.split("\n").map((line) => line.trim().split(/\s+/)[0]).filter(Boolean)
-  );
-  for (const [name, config] of Object.entries(plugins)) {
-    logAction("plugins", `Installing ${name}`);
-    if (installedNames.has(name)) {
-      logSkip();
-      continue;
+  const plans = planPlugins(await ctx.queryStrict("plugin:list", "--format", "json"), plugins);
+  for (const plan of plans) {
+    const config = plugins[plan.name];
+    switch (plan.action) {
+      case "install":
+        logAction("plugins", `Installing ${plan.name}`);
+        await ctx.run(
+          "plugin:install",
+          config.url,
+          ...config.version ? ["--committish", config.version] : [],
+          "--name",
+          plan.name
+        );
+        logDone();
+        break;
+      case "update":
+        logAction("plugins", `Updating ${plan.name}`);
+        await ctx.run("plugin:update", plan.name, config.version);
+        logDone();
+        break;
+      case "newer":
+        logWarn("plugins", `${plan.name} is ${plan.installed}, newer than the declared ${plan.desired}; leaving it (never downgrades)`);
+        break;
+      case "unknown":
+        logWarn("plugins", `${plan.name} is ${plan.installed} and the declared ${plan.desired} cannot be compared; leaving it`);
+        break;
+      default:
+        break;
     }
-    await ctx.run("plugin:install", config.url, "--name", name);
-    logDone();
   }
 }
 
@@ -1248,27 +1583,53 @@ var UpFailedError = class extends Error {
     this.name = "UpFailedError";
   }
 };
-async function processApp(ctx, config, app, appConfig) {
+var AppStepsError = class extends AggregateError {
+  constructor(errors) {
+    super(errors, errors.map((e) => e instanceof Error ? e.message : String(e)).join("; "));
+    this.name = "AppStepsError";
+  }
+};
+async function processApp(ctx, config, app, appConfig, failFast = false, prune = false) {
+  const errors = [];
+  let leftOnServer = 0;
+  const count = prune ? void 0 : (removed) => {
+    leftOnServer += removed.length;
+  };
+  const step = async (fn) => {
+    try {
+      await fn();
+    } catch (error) {
+      if (failFast) throw error;
+      logError(app, error instanceof Error ? error.message : String(error));
+      errors.push(error);
+    }
+  };
   await reconcile(Apps, ctx, app, true);
-  await reconcile(Domains, ctx, app, appConfig.domains);
-  await reconcile(Networks, ctx, app, appConfig.networks);
-  await reconcile(NetworkProps, ctx, app, appConfig.network);
-  await reconcile(Proxy, ctx, app, appConfig.proxy?.enabled);
-  await reconcile(Ports, ctx, app, appConfig.ports);
+  await step(() => reconcile(Domains, ctx, app, appConfig.domains));
+  await step(() => reconcile(Networks, ctx, app, appConfig.networks));
+  await step(() => reconcile(NetworkProps, ctx, app, appConfig.network, count, prune));
+  await step(() => reconcile(Proxy, ctx, app, appConfig.proxy?.enabled));
+  await step(() => reconcile(Ports, ctx, app, appConfig.ports));
   if (config.postgres || config.redis) {
-    await ensureAppLinks(ctx, app, appConfig.links ?? [], config);
-  }
-  await reconcile(Certs, ctx, app, appConfig.ssl);
-  await reconcile(Storage, ctx, app, appConfig.storage);
-  await reconcile(Nginx, ctx, app, appConfig.nginx);
-  await reconcile(Checks, ctx, app, appConfig.checks);
-  await reconcile(Logs, ctx, app, appConfig.logs);
-  await reconcile(Registry, ctx, app, appConfig.registry);
-  await reconcile(Scheduler, ctx, app, appConfig.scheduler);
-  await reconcile(Config, ctx, app, appConfig.env);
-  await reconcile(Builder, ctx, app, appConfig.build);
-  await reconcile(Git, ctx, app, appConfig.git ?? config.git);
-  await reconcile(DockerOptions, ctx, app, appConfig.docker_options);
+    await step(() => ensureAppLinks(ctx, app, appConfig.links ?? [], config));
+  }
+  await step(() => reconcile(Certs, ctx, app, appConfig.ssl));
+  await step(() => reconcile(Storage, ctx, app, appConfig.storage));
+  await step(() => reconcile(Nginx, ctx, app, appConfig.nginx, count, prune));
+  await step(() => reconcile(Checks, ctx, app, appConfig.checks, void 0, prune));
+  await step(() => reconcile(Logs, ctx, app, appConfig.logs, count, prune));
+  await step(() => reconcile(Registry, ctx, app, appConfig.registry, count, prune));
+  await step(() => reconcile(Scheduler, ctx, app, appConfig.scheduler, count, prune));
+  await step(() => reconcile(Ps, ctx, app, appConfig.ps, count, prune));
+  await step(() => reconcile(Scale, ctx, app, appConfig.scale));
+  await step(() => reconcile(Config, ctx, app, appConfig.env || {}));
+  await step(() => reconcile(Builder, ctx, app, appConfig.build, count, prune));
+  await step(() => reconcile(Git, ctx, app, appConfig.git ?? config.git));
+  await step(() => reconcile(DockerOptions, ctx, app, appConfig.docker_options));
+  if (leftOnServer > 0) {
+    logWarn(app, `${leftOnServer} setting(s) no longer in the compose file were left on the server; run 'dokku-compose diff' to see them`);
+  }
+  if (errors.length > 0) throw new AppStepsError(errors);
 }
 async function runUp(ctx, config, appFilter, opts = {}) {
   const apps = appFilter.length > 0 ? appFilter : Object.keys(config.apps);
@@ -1288,11 +1649,12 @@ async function runUp(ctx, config, appFilter, opts = {}) {
     const appConfig = config.apps[app];
     if (!appConfig) continue;
     try {
-      await processApp(ctx, config, app, appConfig);
+      await processApp(ctx, config, app, appConfig, opts.failFast, opts.prune);
     } catch (error) {
       if (opts.failFast) throw error;
-      const message = error instanceof Error ? error.message : String(error);
-      logError(app, message);
+      if (!(error instanceof AppStepsError)) {
+        logError(app, error instanceof Error ? error.message : String(error));
+      }
       failures.push({ app, error });
     }
   }
@@ -1382,6 +1744,8 @@ var CONFIG_RESOURCES = [
   Logs,
   Registry,
   Scheduler,
+  Ps,
+  Scale,
   Config
 ];
 var BUILD_RESOURCES = [
@@ -1447,11 +1811,17 @@ function diffSslStatus(desired, current) {
   if (current === false || current === null) return "missing";
   return void 0;
 }
+function hasAdditionsOrChanges(change) {
+  const c = change;
+  if (c.added === void 0) return c.changed;
+  const added = Array.isArray(c.added) ? c.added.length : Object.keys(c.added).length;
+  return added > 0 || Object.keys(c.modified ?? {}).length > 0;
+}
 function isEmptyValue(value) {
   return value === null || value === void 0 || Array.isArray(value) && value.length === 0 || typeof value === "object" && Object.keys(value).length === 0;
 }
 async function computeDiff(ctx, config) {
-  const result = { apps: {}, services: {}, inSync: true, readWarnings: [] };
+  const result = { apps: {}, services: {}, plugins: {}, inSync: true, readWarnings: [] };
   const appNames = Object.keys(config.apps);
   await ensureDokkuVersion(ctx, config.dokku?.version);
   const appExists = /* @__PURE__ */ new Map();
@@ -1477,14 +1847,15 @@ async function computeDiff(ctx, config) {
     const appDiff = {};
     for (const resource of ALL_APP_RESOURCES) {
       if (resource.key.startsWith("_")) continue;
-      if (resource.forceApply) continue;
       let desired;
       if (resource.key === "proxy") {
         desired = appConfig.proxy?.enabled;
       } else {
         desired = appConfig[resource.key];
       }
-      if (desired === void 0) continue;
+      const checkRemovalsOnly = desired === void 0;
+      if (checkRemovalsOnly && (!resource.removals || !appExists.get(app))) continue;
+      if (resource.forceApply && !resource.removals) continue;
       if (!appExists.get(app)) {
         appDiff[resource.key] = { status: "missing", desired, current: void 0 };
         result.inSync = false;
@@ -1493,6 +1864,21 @@ async function computeDiff(ctx, config) {
       const bulk = prefetched.get(resource.key);
       let current;
       let bulkUnreadable = false;
+      if (checkRemovalsOnly) {
+        try {
+          current = bulk ? bulk.get(app) : await resource.read(ctx, app);
+          if (bulk === null || current === void 0) current = await resource.read(ctx, app);
+        } catch (err) {
+          result.readWarnings.push(`could not read '${resource.key}' for app '${app}' to look for removed settings: ${err instanceof Error ? err.message : String(err)}`);
+          continue;
+        }
+        const removed2 = resource.removals(current, void 0);
+        if (removed2.length > 0) {
+          appDiff[resource.key] = { status: "extra", current, removed: removed2 };
+          result.inSync = false;
+        }
+        continue;
+      }
       if (bulk === null) {
         bulkUnreadable = true;
         current = await resource.read(ctx, app);
@@ -1511,9 +1897,23 @@ async function computeDiff(ctx, config) {
         if (sslStatus !== "in-sync") result.inSync = false;
         continue;
       }
-      const change = computeChange(current, desired);
-      if (!change.changed) {
+      let removed = resource.removals ? resource.removals(current, desired) : [];
+      if (resource.forceApply) {
+        if (removed.length > 0) {
+          appDiff[resource.key] = { status: "extra", desired, current, removed };
+          result.inSync = false;
+        }
+        continue;
+      }
+      const change = resource.additive ? computeAdditiveChange(current, desired) : computeChange(current, desired);
+      if (!resource.removals && Array.isArray(current) && "removed" in change) {
+        removed = change.removed;
+      }
+      if (!change.changed && removed.length === 0) {
         appDiff[resource.key] = { status: "in-sync", desired, current };
+      } else if (removed.length > 0 && !hasAdditionsOrChanges(change)) {
+        appDiff[resource.key] = { status: "extra", desired, current, removed };
+        result.inSync = false;
       } else if (bulkUnreadable && isEmptyValue(current)) {
         appDiff[resource.key] = { status: "unknown", desired, current };
         result.inSync = false;
@@ -1526,9 +1926,34 @@ async function computeDiff(ctx, config) {
         appDiff[resource.key] = { status: "changed", desired, current };
         result.inSync = false;
       }
+      if (removed.length > 0 && appDiff[resource.key].status !== "extra") {
+        appDiff[resource.key].removed = removed;
+      }
+    }
+    if (appConfig.links === void 0 && appExists.get(app)) {
+      const linked = [];
+      for (const [plugin, services] of [["postgres", config.postgres], ["redis", config.redis]]) {
+        for (const svc of Object.keys(services ?? {})) {
+          if (await ctx.check(`${plugin}:linked`, svc, app)) linked.push(svc);
+        }
+      }
+      if (linked.length > 0) {
+        appDiff["links"] = { status: "extra", current: linked, removed: linked, note: "no links: in the file; up will unlink these" };
+        result.inSync = false;
+      }
     }
     result.apps[app] = appDiff;
   }
+  if (config.plugins) {
+    const plans = planPlugins(await ctx.queryStrict("plugin:list", "--format", "json"), config.plugins);
+    for (const plan of plans) {
+      if (plan.action === "ok") continue;
+      const status = plan.action === "install" ? "missing" : plan.action === "unknown" ? "unknown" : "changed";
+      const note = plan.action === "newer" ? "installed is newer; up warns and leaves it" : plan.action === "unknown" ? "versions cannot be compared; up leaves it" : void 0;
+      result.plugins[plan.name] = { status, desired: plan.desired, current: plan.installed, note };
+      if (plan.action !== "unknown") result.inSync = false;
+    }
+  }
   for (const svc of Object.keys(config.postgres ?? {})) {
     const exists = await ctx.check("postgres:exists", svc);
     result.services[svc] = { status: exists ? "in-sync" : "missing" };
@@ -1542,14 +1967,16 @@ async function computeDiff(ctx, config) {
   return result;
 }
 function maskDiffResult(diff) {
-  const masked = { apps: {}, services: diff.services, inSync: diff.inSync, readWarnings: diff.readWarnings };
+  const masked = { apps: {}, services: diff.services, plugins: diff.plugins, inSync: diff.inSync, readWarnings: diff.readWarnings };
   for (const [app, appDiff] of Object.entries(diff.apps)) {
     const maskedAppDiff = {};
     for (const [feature, d] of Object.entries(appDiff)) {
       maskedAppDiff[feature] = {
         status: d.status,
         desired: maskSensitiveData(d.desired),
-        current: maskSensitiveData(d.current)
+        current: maskSensitiveData(d.current),
+        ...d.removed ? { removed: d.removed } : {},
+        ...d.note ? { note: d.note } : {}
       };
     }
     masked.apps[app] = maskedAppDiff;
@@ -1566,18 +1993,24 @@ function formatSummary(diff) {
     } else {
       lines.push(`  app: ${chalk2.bold(app)}`);
       for (const [feature, d] of changes) {
-        const sym = d.status === "missing" ? chalk2.green("+") : d.status === "unknown" ? chalk2.red("?") : chalk2.yellow("~");
+        const sym = d.status === "missing" ? chalk2.green("+") : d.status === "unknown" ? chalk2.red("?") : d.status === "extra" ? chalk2.red("-") : chalk2.yellow("~");
         lines.push(`    ${sym} ${feature}: ${formatFeatureSummary(d)}`);
       }
     }
   }
+  for (const [name, d] of Object.entries(diff.plugins)) {
+    const sym = d.status === "missing" ? chalk2.green("+") : d.status === "unknown" ? chalk2.red("?") : chalk2.yellow("~");
+    const detail = d.status === "missing" ? `not installed (want ${d.desired ?? "any"})` : `${d.current} \u2192 ${d.desired}`;
+    lines.push(`  plugin: ${name}`);
+    lines.push(`    ${sym} version: ${detail}${d.note ? ` (${d.note})` : ""}`);
+  }
   for (const [svc, d] of Object.entries(diff.services)) {
     if (d.status === "missing") {
       lines.push(`  services:`);
       lines.push(`    ${chalk2.green("+")} ${svc}: not provisioned`);
     }
   }
-  const total = Object.values(diff.apps).flatMap((a) => Object.values(a)).filter((d) => d.status !== "in-sync").length + Object.values(diff.services).filter((d) => d.status !== "in-sync").length;
+  const total = Object.values(diff.apps).flatMap((a) => Object.values(a)).filter((d) => d.status !== "in-sync").length + Object.values(diff.services).filter((d) => d.status !== "in-sync").length + Object.values(diff.plugins).filter((d) => d.status !== "unknown").length;
   if (diff.readWarnings.length > 0) {
     lines.push("");
     lines.push(chalk2.red("  Could not read some server state \u2014 treated as unknown, not missing:"));
@@ -1593,12 +2026,21 @@ function formatSummary(diff) {
   return lines.join("\n");
 }
 function formatFeatureSummary(d) {
+  const gone = d.removed?.length ? `not in the file: ${d.removed.join(", ")}` : "";
+  if (d.status === "extra") return `${gone}${d.note ? ` (${d.note})` : ""}`;
+  const base = formatChange(d);
+  return gone ? `${base}; ${gone}` : base;
+}
+function formatChange(d) {
   if (d.status === "unknown") return "(could not read server state \u2014 not reported as missing)";
   if (d.status === "missing") return "(not set on server)";
   if (Array.isArray(d.desired) && Array.isArray(d.current)) {
     return `${d.current.length} \u2192 ${d.desired.length} items`;
   }
-  return `${JSON.stringify(d.current)} \u2192 ${JSON.stringify(d.desired)}`;
+  return `${JSON.stringify(d.current, showUnset)} \u2192 ${JSON.stringify(d.desired, showUnset)}`;
+}
+function showUnset(_key, value) {
+  return value === "\0missing" ? "(unset)" : value;
 }
 function formatVerbose(diff) {
   const lines = [""];
@@ -1611,12 +2053,23 @@ function formatVerbose(diff) {
         lines.push(chalk2.red(`  ? could not read server state \u2014 not reported as missing`));
         continue;
       }
-      const currentLines = d.current !== void 0 ? JSON.stringify(d.current, null, 2).split("\n") : [];
-      const desiredLines = JSON.stringify(d.desired, null, 2).split("\n");
+      if (d.status === "extra") {
+        for (const r of d.removed ?? []) lines.push(chalk2.red(`- ${r}`));
+        if (d.note) lines.push(`  (${d.note})`);
+        continue;
+      }
+      const currentLines = d.current !== void 0 ? JSON.stringify(d.current, showUnset, 2).split("\n") : [];
+      const desiredLines = JSON.stringify(d.desired, showUnset, 2).split("\n");
       for (const line of currentLines) lines.push(chalk2.red(`- ${line}`));
       for (const line of desiredLines) lines.push(chalk2.green(`+ ${line}`));
+      for (const r of d.removed ?? []) lines.push(chalk2.red(`- ${r} (not in the file)`));
     }
   }
+  for (const [name, d] of Object.entries(diff.plugins)) {
+    lines.push(`@@ plugin: ${name} @@`);
+    if (d.current !== void 0) lines.push(chalk2.red(`- ${d.current}`));
+    lines.push(chalk2.green(`+ ${d.desired ?? "(any version)"}`) + (d.note ? ` (${d.note})` : ""));
+  }
   for (const [svc, d] of Object.entries(diff.services)) {
     if (d.status === "missing") {
       lines.push(`@@ services @@`);
@@ -1693,12 +2146,12 @@ function makeRunner(opts) {
     dryRun: opts.dryRun ?? false
   });
 }
-program.command("up [apps...]").description("Create/update apps and services to match config").option("-f, --file <path>", "Config file", "dokku-compose.yml").option("--dry-run", "Print commands without executing").option("--sensitive", "Show sensitive values in dry-run output (masked by default)").option("--fail-fast", "Stop on first error").action(async (apps, opts) => {
+program.command("up [apps...]").description("Create/update apps and services to match config").option("-f, --file <path>", "Config file", "dokku-compose.yml").option("--dry-run", "Print commands without executing").option("--sensitive", "Show sensitive values in dry-run output (masked by default)").option("--fail-fast", "Stop on first error").option("--prune", "Also reset settings the file no longer declares (read `diff` first)").action(async (apps, opts) => {
   const config = loadConfig(opts.file);
   const runner = makeRunner(opts);
   const ctx = createContext(runner);
   try {
-    await runUp(ctx, config, apps, { failFast: opts.failFast ?? false });
+    await runUp(ctx, config, apps, { failFast: opts.failFast ?? false, prune: opts.prune ?? false });
     if (opts.dryRun) {
       console.log("\n# Commands that would run:");
       for (const cmd of runner.dryRunLog) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dokku-compose",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Docker Compose for Dokku — declare your entire server in a single YAML file.",
   "main": "dist/index.js",
   "exports": "./dist/index.js",