primitive-admin 1.1.0-alpha.46 → 1.1.0-alpha.47

package/dist/src/commands/sync.js

@@ -341,6 +341,312 @@ function serializeAppSettings(settings) {
     }
     return stringifyConfigToml(data);
 }
+// --- Config vars (issue #1423) ---------------------------------------------
+// Per-environment non-secret scalars, round-tripped as a single flat
+// `vars.toml` at the sync-dir root (like app.toml). They bind as
+// `{{ vars.KEY }}` in workflow/integration config and `vars.*` in CEL rules.
+/** Key format shared with the vars service (`^[A-Z][A-Z0-9_]{0,63}$`). */
+const VARS_KEY_RE = /^[A-Z][A-Z0-9_]{0,63}$/;
+/** SHA-256 of a var's value — the per-key content hash tracked in sync state. */
+function hashVarValue(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+/**
+ * Serialize the app config vars to a flat TOML table (keys sorted for a stable,
+ * diff-friendly file). Values are non-secret plaintext; a header comment says
+ * so loudly. An empty var set yields a comment-only file.
+ */
+function serializeVars(vars) {
+    const data = {};
+    for (const v of [...vars].sort((a, b) => a.key.localeCompare(b.key))) {
+        data[v.key] = String(v.value ?? "");
+    }
+    const header = "# Per-environment non-secret config vars (issue #1423).\n" +
+        "# Bind as {{ vars.KEY }} in workflow/integration config and vars.* in CEL\n" +
+        "# rules. Values are checked into the repo and NOT secret — never put a\n" +
+        "# credential here; use `primitive secrets` for that.\n\n";
+    return header + stringifyConfigToml(data);
+}
+/**
+ * Decide whether `sync pull` should (over)write `vars.toml`, given the outcome
+ * of fetching the app's config vars.
+ *
+ * The distinction that matters (issue #1423 review): a SUCCESSFUL fetch that
+ * returns zero vars is safe to write — the comment-only file is the intended
+ * empty state. A FAILED fetch (transient 401/500/network) must NOT write,
+ * because `serializeVars([])` would clobber a good local `vars.toml` with a
+ * comment-only file while the pull otherwise reports success. On failure we
+ * keep the prior manifest entries so the untouched file and the sync state stay
+ * consistent.
+ *
+ * Pure and side-effect-free (the caller owns the actual `writeFileSync`) so the
+ * clobber guard is unit-testable without a live server.
+ */
+export function planVarsPull(outcome, priorVars) {
+    const varEntities = {};
+    if (!outcome.ok) {
+        // Preserve the prior manifest entries for the (untouched) local file.
+        if (priorVars)
+            Object.assign(varEntities, priorVars);
+        return { write: false, content: null, varEntities };
+    }
+    for (const v of outcome.vars) {
+        varEntities[v.key] = {
+            // The vars API returns `updatedAt` (see toVarResponse); record it as the
+            // baseline server timestamp so `sync push` can detect a concurrent remote
+            // edit. Fall back to `modifiedAt`/now only for older/partial responses.
+            modifiedAt: v.updatedAt || v.modifiedAt || new Date().toISOString(),
+            contentHash: hashVarValue(String(v.value ?? "")),
+        };
+    }
+    return { write: true, content: serializeVars(outcome.vars), varEntities };
+}
+/**
+ * Maximum var value size, in bytes — mirrors the server's `MAX_VALUE_BYTES`
+ * (app-secrets-service.ts). Kept in sync manually because the CLI can't import
+ * the Worker service module.
+ */
+const MAX_VAR_VALUE_BYTES = 2048;
+/**
+ * Maximum number of vars per app — mirrors the server's `MAX_VARS_PER_APP`
+ * (app-config-vars-service.ts). Kept in sync manually because the CLI can't
+ * import the Worker service module.
+ */
+const MAX_VARS_PER_APP = 100;
+/**
+ * Validate a parsed `vars.toml` table against the same key/value constraints
+ * the server enforces (key format, string type, non-empty, size cap) plus the
+ * aggregate per-app var-count cap. Returns a list of human-readable errors
+ * (empty when valid).
+ *
+ * Run in `sync push`'s up-front preflight pass (issue #1423 review) so an
+ * invalid entry — or a file that would exceed the server's `MAX_VARS_PER_APP`
+ * cap — aborts BEFORE any mutation is applied. Validating only individual
+ * entries let a 101-entry file create/update many vars before the server
+ * rejected a later create at the cap, leaving a partial push (issue #1423
+ * review pass 3). Pure and side-effect-free so it's unit-testable without a
+ * live server.
+ */
+export function validateVarsFile(parsedVars) {
+    const errors = [];
+    const keyCount = Object.keys(parsedVars).length;
+    if (keyCount > MAX_VARS_PER_APP) {
+        errors.push(`vars.toml declares ${keyCount} vars, exceeding the maximum of ${MAX_VARS_PER_APP} vars per app. Remove ${keyCount - MAX_VARS_PER_APP} entr${keyCount - MAX_VARS_PER_APP === 1 ? "y" : "ies"}.`);
+    }
+    for (const [key, rawValue] of Object.entries(parsedVars)) {
+        if (!VARS_KEY_RE.test(key)) {
+            errors.push(`Invalid var key "${key}" in vars.toml: must match ^[A-Z][A-Z0-9_]{0,63}$ (uppercase letters, digits, underscores; start with a letter; max 64 chars)`);
+            continue;
+        }
+        if (typeof rawValue !== "string") {
+            errors.push(`Var "${key}" in vars.toml must be a string value (got ${typeof rawValue}) — quote the value.`);
+            continue;
+        }
+        const byteLength = new TextEncoder().encode(rawValue).length;
+        if (byteLength === 0) {
+            errors.push(`Var "${key}" in vars.toml must not be empty.`);
+        }
+        else if (byteLength > MAX_VAR_VALUE_BYTES) {
+            errors.push(`Var "${key}" in vars.toml exceeds the maximum value size of ${MAX_VAR_VALUE_BYTES} bytes (got ${byteLength}).`);
+        }
+    }
+    return errors;
+}
+/**
+ * Plan the config-var writes a `sync push` should make, detecting concurrent
+ * remote edits before overwriting them (issue #1423 review).
+ *
+ * This is the client-side half of a two-layer concurrency guard. The vars
+ * PUT/DELETE endpoints now honor an `expectedModifiedAt` precondition (issue
+ * #1423 review r-2 P1) and raise a `ConflictError` when the server row changed
+ * since the caller's snapshot — the atomic, server-side check every other
+ * synced entity relies on. This function is the fast fail-before-mutate layer:
+ * it compares the recorded baseline against the current remote snapshot and, for
+ * a var whose remote value has drifted from what we last synced, reports a
+ * conflict (fed into the same `conflicts[]` accumulator the other entities use)
+ * before any write is attempted. A var tracked at the baseline but absent from
+ * the remote snapshot (deleted remotely while edited locally) is remote drift
+ * too, and also reported as a conflict rather than silently recreated.
+ * Conversely, a var removed locally that is already absent remotely is NOT
+ * planned for deletion — its desired (absent) state is already met, so a DELETE
+ * would 404 and fail the push. The same drift check guards deletions: a var
+ * removed locally whose remote value no longer matches the baseline was edited
+ * remotely since the last sync, and deleting it would silently discard that
+ * edit — reported as a conflict instead. `force` skips the conflict guard,
+ * matching `sync push --force` for every other entity.
+ *
+ * Pure and side-effect-free (the caller owns the API calls and sync-state
+ * updates) so the guard is unit-testable without a live server. Assumes
+ * `parsedVars` has already passed `validateVarsFile` (values are strings). The
+ * caller normally fails the push closed when the remote snapshot can't be
+ * fetched, but under `--force` it falls back to an empty snapshot and sets
+ * `snapshotUnavailable` — which keeps removed-key deletions in the plan (they'd
+ * otherwise be mistaken for already-deleted and dropped) and leans on the apply
+ * loop's idempotent 404 handling (issue #1423 review r-2 P2).
+ */
+export function planVarsPush(parsedVars, baseline, remoteVars, options = {}) {
+    const remoteByKey = new Map(remoteVars.map((r) => [r.key, r]));
+    const upserts = [];
+    const conflicts = [];
+    const deletions = [];
+    let skippedCount = 0;
+    const localKeys = new Set();
+    for (const [key, value] of Object.entries(parsedVars)) {
+        localKeys.add(key);
+        const valueHash = hashVarValue(value);
+        const existing = baseline?.[key];
+        // Unchanged since last sync — skip (unless forced), mirroring the
+        // content-hash skip the other file-backed entities use.
+        if (!options.force && existing && existing.contentHash === valueHash) {
+            skippedCount++;
+            continue;
+        }
+        const action = existing ? "update" : "create";
+        // Concurrent-edit guard: if the remote value has drifted from the baseline
+        // we last synced (for an update) — or a var with this key was created
+        // remotely with a different value (for a create) — pushing would silently
+        // clobber that remote change. Report a conflict instead. `--force`
+        // overrides, exactly like the other entities.
+        if (!options.force) {
+            const remote = remoteByKey.get(key);
+            if (remote && typeof remote.value === "string") {
+                const remoteHash = hashVarValue(remote.value);
+                const remoteDrifted = existing?.contentHash
+                    ? remoteHash !== existing.contentHash
+                    : remoteHash !== valueHash;
+                if (remoteDrifted) {
+                    conflicts.push({
+                        key,
+                        serverModifiedAt: remote.updatedAt || "unknown",
+                        localModifiedAt: existing?.modifiedAt || "unknown",
+                    });
+                    continue;
+                }
+            }
+            else if (existing) {
+                // Tracked at the baseline but absent from the remote snapshot: the var
+                // was deleted remotely since our last sync while we edited it locally
+                // (we only reach here past the unchanged-skip above, so the local value
+                // differs from the baseline). Upserting would recreate the
+                // remotely-deleted var — that missing remote value is remote drift too,
+                // so report a conflict instead (issue #1423 review pass 3). `--force`
+                // overrides.
+                conflicts.push({
+                    key,
+                    serverModifiedAt: "deleted",
+                    localModifiedAt: existing.modifiedAt || "unknown",
+                });
+                continue;
+            }
+        }
+        upserts.push({ action, key, value, valueHash });
+    }
+    // Prune vars tracked in the baseline but removed from the local file
+    // (hard-delete; nested-entity precedent). Skip keys already absent from the
+    // remote snapshot: a var independently deleted remotely and also removed
+    // locally is already in its desired (absent) state, and a server DELETE would
+    // 404 and fail the whole push (issue #1423 review pass 3). `--force` does not
+    // resurrect these deletes — the desired state is met either way.
+    for (const [key, entry] of Object.entries(baseline ?? {})) {
+        if (localKeys.has(key))
+            continue;
+        const remote = remoteByKey.get(key);
+        if (!remote) {
+            // Normally an absent remote entry means the var is already gone, so its
+            // desired (deleted) state is met and a DELETE would 404 — skip it. But
+            // when the remote snapshot could NOT be fetched (the `--force` fallback
+            // after a failed `listAppConfigVars`, which passes an empty snapshot),
+            // "absent from the snapshot" means "unknown", not "gone". Suppressing the
+            // delete would silently keep a var the user removed from `vars.toml` while
+            // the push still reports success (issue #1423 review r-2 P2). Enqueue the
+            // removal and rely on the apply loop's idempotent 404 handling to absorb a
+            // key that really was already absent.
+            if (options.snapshotUnavailable)
+                deletions.push(key);
+            continue;
+        }
+        // Concurrent-edit guard, mirroring the upsert path (issue #1423 review
+        // pass 4): deleting a var whose remote value drifted from the last-synced
+        // baseline would silently discard that remote edit. When drift cannot be
+        // verified (no baseline hash, or no remote value in the snapshot), fail
+        // closed and report the conflict. `--force` deletes unconditionally.
+        if (!options.force) {
+            const remoteDrifted = typeof remote.value !== "string" ||
+                !entry.contentHash ||
+                hashVarValue(remote.value) !== entry.contentHash;
+            if (remoteDrifted) {
+                conflicts.push({
+                    key,
+                    serverModifiedAt: remote.updatedAt || "unknown",
+                    localModifiedAt: entry.modifiedAt || "unknown",
+                });
+                continue;
+            }
+        }
+        deletions.push(key);
+    }
+    return { upserts, deletions, conflicts, skippedCount };
+}
+/**
+ * Compute the number of config vars the server would hold after a push plan
+ * is applied (issue #1423 review pass 5). Validating only the local file's
+ * entry count misses remote-only vars: 95 local entries plus 10 vars that
+ * exist only on the server passes a local-count check, and the creates then
+ * exceed the server's cap mid-push, after earlier writes were already
+ * applied. Counted from the fetched remote snapshot: planned deletions remove
+ * keys that exist remotely (the plan already omits deletes for absent keys),
+ * and only upserts whose key is NOT already on the server add to the total.
+ * Conflicted keys are not mutated, so they contribute nothing beyond their
+ * current remote presence. Pure and side-effect-free so it's unit-testable
+ * without a live server.
+ */
+export function countVarsAfterPush(remoteVars, plan) {
+    const remoteKeys = new Set(remoteVars.map((r) => r.key));
+    let count = remoteKeys.size;
+    for (const key of plan.deletions) {
+        if (remoteKeys.has(key))
+            count--;
+    }
+    for (const upsert of plan.upserts) {
+        if (!remoteKeys.has(upsert.key))
+            count++;
+    }
+    return count;
+}
+/**
+ * Compute the `sync diff` rows for config vars (issue #1423 review). Before
+ * this, `sync diff` ignored vars entirely, so an add/remove/value-drift between
+ * the local `vars.toml` and the server read as no difference. Value-aware: a
+ * var present on both sides whose value differs is reported as `modified`
+ * (framed like the other content-aware entities — `sync pull` would rewrite the
+ * local value). Pure and side-effect-free so it's unit-testable without a live
+ * server.
+ */
+export function diffVars(localVars, remoteVars) {
+    const rows = [];
+    for (const [key, localValue] of localVars) {
+        if (!remoteVars.has(key)) {
+            rows.push({ type: "var", key, status: "local only" });
+        }
+        else if (remoteVars.get(key) !== localValue) {
+            rows.push({
+                type: "var",
+                key,
+                status: "modified",
+                hint: "run `sync pull` to rewrite vars.toml to match the server value",
+            });
+        }
+        else {
+            rows.push({ type: "var", key, status: "exists" });
+        }
+    }
+    for (const key of remoteVars.keys()) {
+        if (!localVars.has(key)) {
+            rows.push({ type: "var", key, status: "remote only" });
+        }
+    }
+    return rows;
+}
 function serializeIntegration(integration) {
     const data = {
         integration: {
@@ -1645,6 +1951,38 @@ Directory Structure:
                 writeFileSync(appTomlPath, serializeAppSettings(settings));
                 info("  Wrote app.toml");
             }
+            // Write config vars (issue #1423). A single flat vars.toml at the
+            // sync-dir root (like app.toml), holding the per-environment non-secret
+            // scalars. Written (comment-only when empty) so the managed file exists
+            // and a later push knows the vars surface is under sync control.
+            //
+            // Distinguish "app genuinely has zero vars" (a successful empty
+            // response — safe to write the comment-only file) from "fetch failed"
+            // (a transient 401/500/network error). Previously a `.catch(() => [])`
+            // conflated the two, so a transient error silently clobbered a good
+            // local vars.toml with a comment-only file while reporting success. On a
+            // fetch error we now leave the existing vars.toml untouched and preserve
+            // the prior manifest entry so state stays consistent with the file.
+            const varsTomlPathPull = join(configDir, "vars.toml");
+            let varsOutcome;
+            try {
+                varsOutcome = { ok: true, vars: await client.listAppConfigVars(resolvedAppId) };
+            }
+            catch (varErr) {
+                varsOutcome = { ok: false, error: varErr };
+            }
+            const varsPlan = planVarsPull(varsOutcome, varsOutcome.ok ? undefined : loadSyncState(configDir)?.entities?.vars);
+            const varEntities = varsPlan.varEntities;
+            if (varsPlan.write && varsPlan.content !== null) {
+                writeFileSync(varsTomlPathPull, varsPlan.content);
+                const count = varsOutcome.vars.length;
+                info(`  Wrote vars.toml (${count} var${count === 1 ? "" : "s"})`);
+            }
+            else {
+                const err = varsOutcome.error;
+                error(`  Skipped vars.toml — failed to fetch config vars: ${err?.message ?? err}. ` +
+                    "Left the existing vars.toml untouched.");
+            }
             // Write integrations
             const integrationEntities = {};
             for (const integration of integrations) {
@@ -1974,6 +2312,7 @@ Directory Structure:
                     testCases: Object.keys(testCaseEntities).length > 0 ? testCaseEntities : undefined,
                     databaseTypes: Object.keys(databaseTypeEntities).length > 0 ? databaseTypeEntities : undefined,
                     ruleSets: Object.keys(ruleSetEntities).length > 0 ? ruleSetEntities : undefined,
+                    vars: Object.keys(varEntities).length > 0 ? varEntities : undefined,
                     groupTypeConfigs: Object.keys(groupTypeConfigEntities).length > 0 ? groupTypeConfigEntities : undefined,
                     collectionTypeConfigs: Object.keys(collectionTypeConfigEntities).length > 0
                         ? collectionTypeConfigEntities
@@ -1986,6 +2325,7 @@ Directory Structure:
             saveSyncState(configDir, state);
             divider();
             success(`Pulled configuration to ${configDir}`);
+            keyValue("Config Vars", Object.keys(varEntities).length);
             keyValue("Integrations", integrations.length);
             keyValue("Webhooks", webhooks.length);
             keyValue("Cron Triggers", cronTriggerItems.length);
@@ -2251,10 +2591,91 @@ Directory Structure:
                     }
                 }
             }
+            // Validate config vars up-front (issue #1423 review). Parse vars.toml
+            // and check the same key/value constraints the server enforces here, in
+            // the preflight pass, so an invalid entry aborts BEFORE any mutation
+            // (app settings or a var upsert) is applied. Previously validation ran
+            // mid-push, after app settings could already have been updated.
+            const preflightVarsTomlPath = join(configDir, "vars.toml");
+            let preflightParsedVars = null;
+            if (existsSync(preflightVarsTomlPath)) {
+                try {
+                    const parsed = parseTomlFile(preflightVarsTomlPath);
+                    for (const e of validateVarsFile(parsed)) {
+                        preflightValidationErrors.push(`  ${e}`);
+                    }
+                    preflightParsedVars = parsed;
+                }
+                catch (err) {
+                    preflightValidationErrors.push(`  vars.toml: ${err?.message || String(err)}`);
+                }
+            }
             if (preflightValidationErrors.length > 0) {
                 throw new Error(`Aborting push: ${preflightValidationErrors.length} TOML validation error(s) — no changes were applied.\n` +
                     preflightValidationErrors.join("\n"));
             }
+            // Fetch the current remote config vars up-front — before ANY mutation
+            // (issue #1423 review pass 3). `planVarsPush` needs this snapshot both
+            // to detect concurrent remote edits and to decide which already-absent
+            // deletes to skip. A failed fetch must FAIL CLOSED: proceeding with an
+            // empty snapshot would silently disable the concurrency guard and let a
+            // changed local value clobber a remote edit. Abort unless `--force`.
+            // Fetching here (not mid-push) keeps the abort fail-before-mutate.
+            let remoteVarsSnapshot = [];
+            // Whether the snapshot above is authoritative. A failed fetch under
+            // `--force` leaves it empty but UNKNOWN (not "the server has no vars") —
+            // `planVarsPush` needs this so it doesn't mistake "absent from the empty
+            // snapshot" for "already deleted remotely" and silently drop deletions
+            // the user asked for (issue #1423 review r-2 P2).
+            let varSnapshotUnavailable = false;
+            if (existsSync(preflightVarsTomlPath)) {
+                try {
+                    remoteVarsSnapshot = await client.listAppConfigVars(resolvedAppId);
+                }
+                catch (err) {
+                    if (!options.force) {
+                        throw new Error(`Aborting push: could not fetch remote config vars to check for ` +
+                            `concurrent edits (${err?.message || String(err)}) — no changes ` +
+                            `were applied. Re-run with --force to push without the ` +
+                            `concurrency guard.`);
+                    }
+                    // --force: proceed without a snapshot; the guard is intentionally
+                    // bypassed and every local var is upserted as authoritative. The
+                    // snapshot is unknown, so deletions of removed keys are still
+                    // enqueued (idempotent 404 handling absorbs already-absent keys).
+                    remoteVarsSnapshot = [];
+                    varSnapshotUnavailable = true;
+                }
+            }
+            // Plan the var writes up-front and validate the FINAL server var
+            // count against the cap BEFORE any mutation (issue #1423 review pass
+            // 5). `validateVarsFile` above caps the local file's entry count, but
+            // remote-only vars (on the server, not in vars.toml) still count
+            // toward the server's limit: 95 local entries plus 10 remote-only
+            // vars passes the local check, then a later create is rejected at the
+            // cap after earlier writes were already applied. Computed from the
+            // remote snapshot plus planned creates minus planned deletions. The
+            // check applies even with `--force`: the cap is a server hard limit,
+            // not a conflict guard, so a push that would exceed it cannot succeed
+            // and forcing it would only leave a partial push. (Under `--force`
+            // with a failed snapshot fetch the remote count is unknown; the check
+            // then degrades to the local file count, like the concurrency guard.)
+            let varPlan = null;
+            if (preflightParsedVars) {
+                varPlan = planVarsPush(preflightParsedVars, syncState?.entities?.vars, remoteVarsSnapshot, { force: options.force, snapshotUnavailable: varSnapshotUnavailable });
+                const finalVarCount = countVarsAfterPush(remoteVarsSnapshot, varPlan);
+                if (finalVarCount > MAX_VARS_PER_APP) {
+                    const localKeys = new Set(Object.keys(preflightParsedVars));
+                    const plannedDeletes = new Set(varPlan.deletions);
+                    const remoteOnlyCount = remoteVarsSnapshot.filter((r) => !localKeys.has(r.key) && !plannedDeletes.has(r.key)).length;
+                    throw new Error(`Aborting push: it would leave ${finalVarCount} config vars on the server, ` +
+                        `exceeding the maximum of ${MAX_VARS_PER_APP} vars per app ` +
+                        `(server has ${remoteVarsSnapshot.length} vars, ${remoteOnlyCount} of ` +
+                        `which are not in vars.toml) — no changes were applied. Run ` +
+                        `\`sync pull\` to bring the remote-only vars into vars.toml, or ` +
+                        `delete unneeded vars, then push again.`);
+                }
+            }
             // Process app settings
             const appTomlPath = join(configDir, "app.toml");
             if (existsSync(appTomlPath)) {
@@ -2302,6 +2723,135 @@ Directory Structure:
                     }
                 }
             }
+            // Process config vars (issue #1423). Read the flat vars.toml, upsert
+            // each key (PUT by key is idempotent — one call covers create+update),
+            // and hard-delete keys removed from the file (nested-entity precedent:
+            // database operations/subscriptions). Pruning runs ONLY when the file
+            // is present, so an absent vars.toml never mass-deletes server vars.
+            //
+            // Key/value validation now runs up-front in the preflight pass above,
+            // so by the time we get here the file is known-valid (values are
+            // strings). The remote-vars snapshot was also fetched up-front (fail
+            // closed) so `planVarsPush` can detect a concurrent remote edit and
+            // report it as a conflict instead of silently overwriting it (review
+            // r-2 P1), and the plan itself was computed up-front so the final
+            // server var count could be validated against the cap before any
+            // mutation (review pass 5).
+            if (varPlan) {
+                skippedCount += varPlan.skippedCount;
+                // Feed var conflicts into the shared accumulator — same convention as
+                // every other entity, so the end-of-run report renders them as
+                // `CONFLICT var: KEY` and the push exits non-zero.
+                for (const c of varPlan.conflicts) {
+                    conflicts.push({
+                        type: "var",
+                        key: c.key,
+                        serverModifiedAt: c.serverModifiedAt,
+                        localModifiedAt: c.localModifiedAt,
+                    });
+                }
+                // Delete removed keys BEFORE upserting new ones (issue #1423 review
+                // pass 3). At the server's 100-var cap, a replacement (remove one key,
+                // add another) is a valid final state, but upserting the new key first
+                // would transiently exceed the cap and the create would be rejected.
+                // Freeing the removed slots first lets the replacement synchronize.
+                // Each removal prints an "Unsetting var X" line so the destructive
+                // action is visible.
+                for (const key of varPlan.deletions) {
+                    changes.push({ type: "var", action: "delete", key });
+                    if (!options.dryRun) {
+                        // Server-side concurrency guard (issue #1423 review r-2 P1): send
+                        // the `updatedAt` we last synced so the server rejects the delete
+                        // (409 CONFLICT) if the var was edited remotely since — closing the
+                        // race between the client snapshot and this DELETE that the
+                        // client-side `planVarsPush` guard alone can't. `--force` omits it
+                        // and deletes unconditionally.
+                        const expectedModifiedAt = options.force
+                            ? undefined
+                            : syncState?.entities?.vars?.[key]?.modifiedAt;
+                        try {
+                            await client.deleteAppConfigVar(resolvedAppId, key, expectedModifiedAt);
+                            info(`  Unsetting var ${key}`);
+                            if (syncState?.entities?.vars)
+                                delete syncState.entities.vars[key];
+                        }
+                        catch (err) {
+                            // A remote edit landed since our snapshot — report a conflict
+                            // instead of discarding it (feeds the shared accumulator →
+                            // `CONFLICT var: KEY`, non-zero exit).
+                            if (err instanceof ConflictError) {
+                                conflicts.push({
+                                    type: "var",
+                                    key,
+                                    serverModifiedAt: err.serverModifiedAt,
+                                    localModifiedAt: expectedModifiedAt || "unknown",
+                                });
+                            }
+                            else if (err instanceof ApiError && err.statusCode === 404) {
+                                // A 404 means the var is already absent — the desired
+                                // (deleted) state is met, so treat it as an idempotent success
+                                // rather than failing the whole push (issue #1423 review pass
+                                // 3). The plan omits deletes for keys absent from a fetched
+                                // snapshot; this also absorbs the forced no-snapshot fallback
+                                // (r-2 P2), where removed keys are enqueued unconditionally.
+                                info(`  Var ${key} already absent (nothing to unset)`);
+                                if (syncState?.entities?.vars)
+                                    delete syncState.entities.vars[key];
+                            }
+                            else {
+                                throw wrapEntityError(err, "delete", "var", key);
+                            }
+                        }
+                    }
+                }
+                for (const item of varPlan.upserts) {
+                    changes.push({ type: "var", action: item.action, key: item.key });
+                    if (!options.dryRun) {
+                        // Server-side concurrency guard (issue #1423 review r-2 P1): for an
+                        // update, send the `updatedAt` we last synced so the server rejects
+                        // the write (409 CONFLICT) if the var changed remotely since — this
+                        // closes the snapshot→PUT race the client-side guard can't. A
+                        // create has no baseline, so instead it sends a create-only
+                        // precondition (`expectNotExists`, review r-3 P1a): the server 409s
+                        // if the key was created remotely since our snapshot rather than
+                        // silently overwriting that concurrent create. `--force` overrides
+                        // both.
+                        const isCreate = item.action === "create";
+                        const expectedModifiedAt = options.force || isCreate
+                            ? undefined
+                            : syncState?.entities?.vars?.[item.key]?.modifiedAt;
+                        try {
+                            const result = await client.upsertAppConfigVar(resolvedAppId, item.key, { value: item.value }, expectedModifiedAt, { expectNotExists: !options.force && isCreate });
+                            if (syncState) {
+                                if (!syncState.entities.vars)
+                                    syncState.entities.vars = {};
+                                syncState.entities.vars[item.key] = {
+                                    // Record the server's returned timestamp (updatedAt) so the
+                                    // next push's concurrent-edit guard has an accurate baseline.
+                                    modifiedAt: result?.updatedAt || result?.modifiedAt || new Date().toISOString(),
+                                    contentHash: item.valueHash,
+                                };
+                            }
+                        }
+                        catch (err) {
+                            // A remote edit landed since our snapshot — report a conflict
+                            // instead of clobbering it (feeds the shared accumulator →
+                            // `CONFLICT var: KEY`, non-zero exit).
+                            if (err instanceof ConflictError) {
+                                conflicts.push({
+                                    type: "var",
+                                    key: item.key,
+                                    serverModifiedAt: err.serverModifiedAt,
+                                    localModifiedAt: expectedModifiedAt || "unknown",
+                                });
+                            }
+                            else {
+                                throw wrapEntityError(err, item.action, "var", item.key);
+                            }
+                        }
+                    }
+                }
+            }
             // Process rule sets first (other entities may reference them by name)
             const ruleSetsDir = join(configDir, "rule-sets");
             if (existsSync(ruleSetsDir)) {
@@ -4982,6 +5532,31 @@ Directory Structure:
                     localScripts.set(name, readFileSync(join(transformsDirPath, file), "utf-8"));
                 }
             }
+            // Config vars — issue #1423. Before this, `sync diff` ignored vars
+            // entirely, so an add/remove/value-drift between the local `vars.toml`
+            // and the server silently read as no difference right before a push
+            // would change or unset them. Fetch the remote vars (value included —
+            // vars are non-secret) and read the local `vars.toml` so the comparison
+            // below can report added/removed/modified vars.
+            let remoteVarItemsDiff = [];
+            try {
+                remoteVarItemsDiff = await client.listAppConfigVars(resolvedAppId);
+            }
+            catch {
+                // Older server without the vars route — treat as no remote vars.
+            }
+            const remoteVars = new Map(remoteVarItemsDiff
+                .filter((v) => typeof v?.key === "string")
+                .map((v) => [v.key, String(v.value ?? "")]));
+            const localVars = new Map();
+            const varsTomlPathDiff = join(configDir, "vars.toml");
+            if (existsSync(varsTomlPathDiff)) {
+                const parsed = parseTomlFile(varsTomlPathDiff);
+                for (const [key, rawValue] of Object.entries(parsed)) {
+                    if (typeof rawValue === "string")
+                        localVars.set(key, rawValue);
+                }
+            }
             // Compare
             const differences = [];
             // Integrations
@@ -5186,6 +5761,10 @@ Directory Structure:
                     differences.push({ type: "transform", key: name, status: "remote only" });
                 }
             }
+            // Config vars — issue #1423 (see `diffVars`).
+            for (const row of diffVars(localVars, remoteVars)) {
+                differences.push(row);
+            }
             // Compare test cases for synced prompts and workflows
             const testCaseDiffs = [];
             // Helper to compare test cases for a block