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

package/dist/src/commands/sync.js

@@ -13,9 +13,12 @@ import { createSnapshot, listSnapshots, resolveSnapshot, restoreSnapshot, pruneS
 import { validateWorkflowToml, formatWorkflowTomlErrors, } from "../lib/workflow-toml-validator.js";
 import { expandWorkflowTomlData } from "../lib/workflow-fragments.js";
 import { parseConfigToml, stringifyConfigToml } from "../lib/config-toml.js";
+import { serializeSection, parseTomlToAppSettings, } from "../lib/app-settings-descriptor.js";
+import { serializeAppSettings, collectAppSettingsPushErrors, } from "./sync-app-settings.js";
 import { applyWorkflowBody } from "../lib/workflow-apply.js";
 import { buildWorkflowPayloadFromToml } from "../lib/workflow-payload.js";
 import { detectLayout, migrateLegacyToV2 } from "../lib/block-layout.js";
+import { ABSENT_FROM_EXPORT, LOCAL_ONLY_ABSENT, LOCAL_ONLY_NEW, SYNC_RESOURCE_TYPES, applyPrune, attemptFetch, classifyLocalOnly, hasUncommittedChanges, planPrune, preserveUnwrittenEntries, ruleSetFileKey, } from "../lib/sync-resource-types.js";
 import { success, error, printApiError, info, warn, keyValue, json, divider, } from "../lib/output.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
 import chalk from "chalk";
@@ -238,108 +241,340 @@ export function hashRemoteWorkflowForDiff(workflow, draft, configs) {
     const parsed = parseConfigToml(serialized);
     return hashWorkflowTomlForDiff(parsed);
 }
-// Boolean [auth] keys in app.toml that map 1:1 to app-settings fields.
-const AUTH_BOOLEAN_KEYS = [
-    "googleOAuthEnabled",
-    "passkeyEnabled",
-    "magicLinkEnabled",
-    "appleSignInEnabled",
-    "otpEnabled",
-];
-// Every recognized [auth] key. Single source of truth shared by pull
-// serialization, push parsing, and the unrecognized-key warning so the three
-// never drift apart. `appleAudiences` is a string array and `passkeys` is the
-// passkey RP config object; the rest are booleans.
-const RECOGNIZED_AUTH_KEYS = new Set([
-    ...AUTH_BOOLEAN_KEYS,
-    "appleAudiences",
-    "passkeys",
-]);
 /**
  * Build the [auth] block of app.toml from server settings (pull direction).
  *
- * Apple/OTP fields round-trip alongside the legacy google/passkey/magic-link
- * keys. Two asymmetries are handled deliberately:
- *  - `appleSignInEnabled` comes back as `boolean | null`; smol-toml throws on
- *    null, so an unset value (null) is omitted rather than written.
- *  - `appleAudiences` is omitted when empty. An empty array and an omitted key
- *    both mean "no audiences" (the server normalizes [] -> null), so omitting
- *    an empty list on pull is not lossy.
+ * Thin wrapper over the shared field descriptor
+ * (`cli/src/lib/app-settings-descriptor.ts`), which now owns the [auth] field
+ * set that `AUTH_BOOLEAN_KEYS`/`RECOGNIZED_AUTH_KEYS` used to hard-code. The
+ * descriptor drives all four sections in one place, so pull, push, and the
+ * unrecognized-key warning can never drift apart. `googleClientSecret` is a
+ * secret descriptor entry and is never written.
  */
 export function serializeAuthBlock(settings) {
-    const auth = {
-        googleOAuthEnabled: settings.googleOAuthEnabled,
-        passkeyEnabled: settings.passkeyEnabled,
-        magicLinkEnabled: settings.magicLinkEnabled,
-    };
-    if (typeof settings.appleSignInEnabled === "boolean") {
-        auth.appleSignInEnabled = settings.appleSignInEnabled;
-    }
-    if (Array.isArray(settings.appleAudiences) &&
-        settings.appleAudiences.length > 0) {
-        auth.appleAudiences = settings.appleAudiences;
+    return serializeSection(settings, "auth");
+}
+/**
+ * Translate the [auth] block of app.toml into app-settings fields (push
+ * direction). Kept as a focused helper over the shared descriptor; the full
+ * push path uses `parseTomlToAppSettings` for every section. Only keys present
+ * in the TOML are forwarded, so an omitted key never overwrites server state.
+ * Descriptor errors (a secret key, a type mismatch) are surfaced alongside the
+ * unrecognized-key warnings.
+ */
+export function parseAppAuthSettings(auth) {
+    const { settings, warnings, errors } = parseTomlToAppSettings({ auth });
+    return { settings, warnings: [...warnings, ...errors] };
+}
+// `serializeAppSettings` (pull) and the app.toml push validation now live in
+// `sync-app-settings.ts`, shared with the `primitive settings` command — see
+// the imports above. Both directions stay descriptor-driven
+// (`cli/src/lib/app-settings-descriptor.ts`).
+// --- 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 ?? "");
     }
-    if (typeof settings.otpEnabled === "boolean") {
-        auth.otpEnabled = settings.otpEnabled;
+    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 };
     }
-    if (settings.passkeyRpConfig) {
-        auth.passkeys = settings.passkeyRpConfig;
+    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 auth;
+    return { write: true, content: serializeVars(outcome.vars), varEntities };
 }
 /**
- * Translate the [auth] block of app.toml into app-settings fields (push
- * direction).
+ * 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).
  *
- * Only keys actually present in the TOML are forwarded — an omitted key is left
- * untouched so it never overwrites server state (e.g. flipping a previously-true
- * flag to false). An explicit value, including `false`, is forwarded as-is.
- * `appleAudiences = []` is forwarded too; the server normalizes [] -> null
- * ("no audiences"). Keys outside RECOGNIZED_AUTH_KEYS produce a warning rather
- * than a hard error, so a typo or a future key doesn't silently drop.
+ * 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 parseAppAuthSettings(auth) {
-    const settings = {};
-    const warnings = [];
-    for (const key of AUTH_BOOLEAN_KEYS) {
-        if (key in auth)
-            settings[key] = auth[key];
+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"}.`);
     }
-    if ("appleAudiences" in auth) {
-        settings.appleAudiences = auth.appleAudiences;
+    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}).`);
+        }
     }
-    if ("passkeys" in auth) {
-        settings.passkeyRpConfig = auth.passkeys;
+    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 });
     }
-    for (const key of Object.keys(auth)) {
-        if (!RECOGNIZED_AUTH_KEYS.has(key)) {
-            warnings.push(`Unrecognized [auth] key "${key}" in app.toml — ignored. ` +
-                `Recognized keys: ${[...RECOGNIZED_AUTH_KEYS].join(", ")}.`);
+    // 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 { settings, warnings };
+    return { upserts, deletions, conflicts, skippedCount };
 }
-// TOML serialization helpers
-function serializeAppSettings(settings) {
-    const data = {
-        app: {
-            name: settings.name,
-            mode: settings.mode,
-            waitlistEnabled: settings.waitlistEnabled,
-            baseUrl: settings.baseUrl,
-        },
-        auth: serializeAuthBlock(settings),
-    };
-    if (settings.corsMode === "custom") {
-        data.cors = {
-            mode: settings.corsMode,
-            allowedOrigins: settings.corsAllowedOrigins,
-            allowCredentials: settings.corsAllowCredentials,
-            allowedMethods: settings.corsAllowedMethods,
-            maxAge: settings.corsMaxAge,
-        };
+/**
+ * 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--;
     }
-    return stringifyConfigToml(data);
+    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 = {
@@ -1111,8 +1346,15 @@ export async function pullScripts(client, appId, configDir, logger = () => { })
         items = result.items || [];
     }
     catch {
-        return { scriptEntities, count: 0 };
+        return {
+            scriptEntities,
+            count: 0,
+            presence: { ok: false },
+            listOk: false,
+            serverKeys: [],
+        };
     }
+    let detailsOk = true;
     let written = 0;
     for (const script of items) {
         const name = script?.name;
@@ -1131,6 +1373,7 @@ export async function pullScripts(client, appId, configDir, logger = () => { })
             full = await client.getScript(appId, script.scriptId);
         }
         catch {
+            detailsOk = false;
             logger(`  Skipped transforms/${name}.rhai (could not fetch config)`);
             continue;
         }
@@ -1155,7 +1398,11 @@ export async function pullScripts(client, appId, configDir, logger = () => { })
         written += 1;
         logger(`  Wrote transforms/${filename}`);
     }
-    return { scriptEntities, count: written };
+    const serverKeys = items.map((s) => s?.name).filter(Boolean);
+    const presence = detailsOk
+        ? { ok: true, serverKeys }
+        : { ok: false };
+    return { scriptEntities, count: written, presence, listOk: true, serverKeys };
 }
 async function pullTestCasesForBlock(client, appId, blockType, blockId, blockKey, configDir, testCaseEntities, lookupMaps) {
     let testCases;
@@ -1521,6 +1768,7 @@ Directory Structure:
         .option("--app <app-id>", "App ID")
         .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
         .option("--json", "Output as JSON instead of writing files")
+        .option("--no-prune", "Keep local files for entities that are absent from the sync export (the next push will re-create them)")
         .action(async (appId, options) => {
         const resolvedAppId = resolveAppId(appId, options);
         const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
@@ -1533,14 +1781,24 @@ Directory Structure:
         const client = new ApiClient();
         info(`Pulling configuration for app ${resolvedAppId}...`);
         try {
-            // Fetch all data
-            const [settings, integrationItems, promptItems, workflowItems, emailTemplatesResult] = await Promise.all([
+            // Fetch all data. Issue #1659: prune decides whether a local file's
+            // entity still exists server-side, so every fetch that establishes
+            // presence must report success or failure explicitly — an error that
+            // reads as an empty list would prune every local file of that type.
+            // `integrations`/`prompts`/`workflows` throw straight out of the pull
+            // on failure (no `.catch`), so reaching the prune pass at all proves
+            // their listings succeeded. The types that swallow errors below carry
+            // an explicit outcome instead.
+            const [settings, integrationItems, promptItems, workflowItems, emailTemplatesOutcome] = await Promise.all([
                 client.getAppSettings(resolvedAppId).catch(() => null),
                 fetchAll((p) => client.listIntegrations(resolvedAppId, p)),
                 fetchAll((p) => client.listPrompts(resolvedAppId, p)),
                 fetchAll((p) => client.listWorkflows(resolvedAppId, p)),
-                client.listEmailTemplates(resolvedAppId).catch(() => ({ templates: [] })),
+                attemptFetch(() => client.listEmailTemplates(resolvedAppId)),
             ]);
+            const emailTemplatesResult = emailTemplatesOutcome.ok
+                ? emailTemplatesOutcome.value
+                : { templates: [] };
             // Fetch details for each entity
             const integrations = await Promise.all(integrationItems.map((i) => client.getIntegration(resolvedAppId, i.integrationId)));
             const prompts = await Promise.all(promptItems.map((p) => client.getPrompt(resolvedAppId, p.promptId)));
@@ -1565,30 +1823,71 @@ Directory Structure:
                 }
                 return workflowData;
             }));
-            // Fetch full details for email template overrides
+            // Fetch full details for email template overrides. Only overrides get a
+            // local file, so they are the type's server key set. A detail fetch that
+            // fails leaves the override unwritten — presence for that key is no
+            // longer established, so the type is skipped for pruning (#1659).
             const emailTemplateOverrides = emailTemplatesResult.templates.filter((t) => t.hasOverride);
-            const emailTemplates = await Promise.all(emailTemplateOverrides.map((t) => client.getEmailTemplate(resolvedAppId, t.emailType).catch(() => null))).then((results) => results.filter(Boolean));
+            const emailTemplateOutcomes = await Promise.all(emailTemplateOverrides.map((t) => attemptFetch(() => client.getEmailTemplate(resolvedAppId, t.emailType))));
+            const emailTemplates = emailTemplateOutcomes
+                .map((o) => (o.ok ? o.value : null))
+                .filter(Boolean);
+            const emailTemplateDetailsOk = emailTemplateOutcomes.every((o) => o.ok && o.value);
+            const emailTemplatePresence = emailTemplatesOutcome.ok && emailTemplateDetailsOk
+                ? {
+                    ok: true,
+                    serverKeys: emailTemplateOverrides.map((t) => t.emailType),
+                }
+                : { ok: false };
             if (options.json) {
                 json({ settings, integrations, prompts, workflows, emailTemplates });
                 return;
             }
             // Fetch database config resources
-            const [databaseTypeConfigsResult, ruleSetsResult, groupTypeConfigsResult, collectionTypeConfigsResult, metadataCategoryConfigsResult,] = await Promise.all([
-                client.listDatabaseTypeConfigs(resolvedAppId).catch(() => []),
-                client.listRuleSets(resolvedAppId).catch(() => []),
-                client.listGroupTypeConfigs(resolvedAppId).catch(() => []),
-                client.listCollectionTypeConfigs(resolvedAppId).catch(() => []),
-                client.listMetadataCategoryConfigs(resolvedAppId).catch(() => []),
+            // These five listings previously used `.catch(() => [])`, which made a
+            // transient 401/500/network error indistinguishable from "the app has
+            // none of these". Pull still tolerates the failure the same way (it
+            // writes nothing for that type and carries on), but it now records the
+            // outcome so the prune pass can skip a type whose presence is unknown
+            // rather than delete every local file of it (#1659).
+            const [databaseTypeConfigsOutcome, ruleSetsOutcome, groupTypeConfigsOutcome, collectionTypeConfigsOutcome, metadataCategoryConfigsOutcome,] = await Promise.all([
+                attemptFetch(() => client.listDatabaseTypeConfigs(resolvedAppId)),
+                attemptFetch(() => client.listRuleSets(resolvedAppId)),
+                attemptFetch(() => client.listGroupTypeConfigs(resolvedAppId)),
+                attemptFetch(() => client.listCollectionTypeConfigs(resolvedAppId)),
+                attemptFetch(() => client.listMetadataCategoryConfigs(resolvedAppId)),
             ]);
+            const databaseTypeConfigsResult = databaseTypeConfigsOutcome.ok
+                ? databaseTypeConfigsOutcome.value
+                : [];
+            const ruleSetsResult = ruleSetsOutcome.ok ? ruleSetsOutcome.value : [];
+            const groupTypeConfigsResult = groupTypeConfigsOutcome.ok
+                ? groupTypeConfigsOutcome.value
+                : [];
+            const collectionTypeConfigsResult = collectionTypeConfigsOutcome.ok
+                ? collectionTypeConfigsOutcome.value
+                : [];
+            const metadataCategoryConfigsResult = metadataCategoryConfigsOutcome.ok
+                ? metadataCategoryConfigsOutcome.value
+                : [];
             // Fetch operations + subscriptions for each database type. Issue #803:
             // subscriptions are pulled symmetrically with operations so a
             // pull → push cycle round-trips `[[subscriptions]]` blocks without a
             // spurious diff. The list endpoint already excludes archived rows.
+            //
+            // A failed operation/subscription fetch also disqualifies the type from
+            // pruning (#1659): the file we write for it is then incomplete, so the
+            // pull's picture of that type is not one to reconcile against.
+            let databaseTypeDetailsOk = true;
             const databaseTypesWithOps = await Promise.all((Array.isArray(databaseTypeConfigsResult) ? databaseTypeConfigsResult : []).map(async (typeConfig) => {
-                const [ops, subs] = await Promise.all([
-                    client.listDatabaseTypeOperations(resolvedAppId, typeConfig.databaseType).catch(() => []),
-                    client.listDatabaseTypeSubscriptions(resolvedAppId, typeConfig.databaseType).catch(() => []),
+                const [opsOutcome, subsOutcome] = await Promise.all([
+                    attemptFetch(() => client.listDatabaseTypeOperations(resolvedAppId, typeConfig.databaseType)),
+                    attemptFetch(() => client.listDatabaseTypeSubscriptions(resolvedAppId, typeConfig.databaseType)),
                 ]);
+                if (!opsOutcome.ok || !subsOutcome.ok)
+                    databaseTypeDetailsOk = false;
+                const ops = opsOutcome.ok ? opsOutcome.value : [];
+                const subs = subsOutcome.ok ? subsOutcome.value : [];
                 return {
                     typeConfig,
                     operations: Array.isArray(ops) ? ops : [],
@@ -1639,12 +1938,50 @@ Directory Structure:
             ensureDir(join(configDir, "collection-type-configs"));
             ensureDir(join(configDir, "metadata-category-configs"));
             ensureDir(join(configDir, "email-templates"));
+            // The prior sync state is the record of which local files a previous
+            // pull wrote — the discriminator the prune pass keys off (#1659). Read
+            // it now: `saveSyncState` at the end of the pull overwrites it, and the
+            // files themselves are about to be rewritten.
+            const priorState = loadSyncState(configDir);
+            const priorEntities = priorState?.entities ?? {};
             // Write app settings
             if (settings) {
                 const appTomlPath = join(configDir, "app.toml");
                 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 : priorEntities.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) {
@@ -1675,15 +2012,13 @@ Directory Structure:
                 };
             }
             info(`  Pulled ${webhooks.length} webhook(s)`);
-            // Pull cron triggers
-            let cronTriggerItems = [];
-            try {
-                const cronResult = await client.listCronTriggers(resolvedAppId);
-                cronTriggerItems = cronResult.items || [];
-            }
-            catch {
-                // Cron triggers may not be available on older servers
-            }
+            // Pull cron triggers. An older server without the route (or any other
+            // failure) leaves the type unlisted — tolerated as before, but recorded
+            // so prune skips it rather than reading it as "no cron triggers".
+            const cronTriggersOutcome = await attemptFetch(() => client.listCronTriggers(resolvedAppId));
+            const cronTriggerItems = cronTriggersOutcome.ok
+                ? cronTriggersOutcome.value.items || []
+                : [];
             const cronTriggersDir = join(configDir, "cron-triggers");
             mkdirSync(cronTriggersDir, { recursive: true });
             const cronTriggerEntities = {};
@@ -1699,8 +2034,10 @@ Directory Structure:
             }
             info(`  Pulled ${cronTriggerItems.length} cron trigger(s)`);
             // Pull blob buckets
-            const blobBucketsResult = await client.listBlobBuckets(resolvedAppId).catch(() => ({ items: [] }));
-            const blobBucketItems = blobBucketsResult.items || [];
+            const blobBucketsOutcome = await attemptFetch(() => client.listBlobBuckets(resolvedAppId));
+            const blobBucketItems = blobBucketsOutcome.ok
+                ? blobBucketsOutcome.value.items || []
+                : [];
             const blobBucketsDir = join(configDir, "blob-buckets");
             mkdirSync(blobBucketsDir, { recursive: true });
             const blobBucketEntities = {};
@@ -1753,7 +2090,7 @@ Directory Structure:
             // `transforms/<name>.rhai`, and record `{id, modifiedAt,
             // contentHash}` under `entities.scripts[name]` so a subsequent
             // `sync push` round-trips without false diffs.
-            const { scriptEntities, count: pulledScriptsCount } = await pullScripts(client, resolvedAppId, configDir, info);
+            const { scriptEntities, count: pulledScriptsCount, presence: scriptPresence, listOk: scriptListOk, serverKeys: scriptServerKeys, } = await pullScripts(client, resolvedAppId, configDir, info);
             if (pulledScriptsCount > 0) {
                 info(`  Pulled ${pulledScriptsCount} transform(s)`);
             }
@@ -1805,19 +2142,10 @@ Directory Structure:
                 };
                 info(`  Wrote email-templates/${filename}`);
             }
-            // Clean up local email template files for remotely-deleted overrides
-            const emailTemplatesDir = join(configDir, "email-templates");
-            if (existsSync(emailTemplatesDir)) {
-                const pulledTypes = new Set(emailTemplates.map((t) => t.emailType));
-                const localFiles = readdirSync(emailTemplatesDir).filter((f) => f.endsWith(".toml"));
-                for (const file of localFiles) {
-                    const localType = basename(file, ".toml");
-                    if (!pulledTypes.has(localType)) {
-                        unlinkSync(join(emailTemplatesDir, file));
-                        info(`  Removed email-templates/${file} (override deleted on server)`);
-                    }
-                }
-            }
+            // Email-template files for removed overrides used to be cleaned up here
+            // by a hand-coded loop — the only type that pruned at all (#1659). It is
+            // now folded into the general prune pass below, under the same rules and
+            // the same `--no-prune` flag as every other type.
             // Pull test cases for prompts and workflows
             const testCaseEntities = {};
             let totalTestCases = 0;
@@ -1900,7 +2228,7 @@ Directory Structure:
             // Write rule sets
             const ruleSetEntities = {};
             for (const ruleSet of ruleSets) {
-                const fileKey = (ruleSet.name || ruleSet.ruleSetId).replace(/[/\\:*?"<>|]/g, "_");
+                const fileKey = ruleSetFileKey(ruleSet);
                 const filename = `${fileKey}.toml`;
                 const filePath = join(configDir, "rule-sets", filename);
                 writeFileSync(filePath, serializeRuleSet(ruleSet));
@@ -1956,6 +2284,182 @@ Directory Structure:
                 };
                 info(`  Wrote metadata-category-configs/${filename}`);
             }
+            // ── Prune reconciliation (issue #1659) ───────────────────────────────
+            //
+            // Every write above is done, so we now know which entities the server
+            // still exports. A local file is removed iff its key was MANAGED (a
+            // prior pull wrote it, so it is in `priorEntities[<slot>]`) and is
+            // ABSENT from this pull's server keys. A file that was never in prior
+            // state was hand-authored — it stays, and `sync diff` reports it as new.
+            //
+            // Presence comes from the server LISTING, never from "what we just
+            // wrote": several types legitimately skip writing a present entity (a
+            // script with no active config), and pruning those would delete a live
+            // entity's file. A type whose presence could not be established is
+            // skipped whole, and its prior state slot is preserved so the managed
+            // discriminator survives to the next pull.
+            //
+            // This runs after the pre-pull snapshot, so `sync revert` restores
+            // anything pruned in error.
+            const presenceBySlot = {
+                integrations: { ok: true, serverKeys: integrationItems.map((i) => i.integrationKey) },
+                webhooks: { ok: true, serverKeys: webhookItems.map((w) => w.webhookKey) },
+                prompts: { ok: true, serverKeys: promptItems.map((p) => p.promptKey) },
+                workflows: { ok: true, serverKeys: workflowItems.map((w) => w.workflowKey) },
+                cronTriggers: cronTriggersOutcome.ok
+                    ? { ok: true, serverKeys: cronTriggerItems.map((t) => t.triggerKey) }
+                    : { ok: false },
+                blobBuckets: blobBucketsOutcome.ok
+                    ? { ok: true, serverKeys: blobBucketItems.map((b) => b.bucketKey) }
+                    : { ok: false },
+                scripts: scriptPresence,
+                emailTemplates: emailTemplatePresence,
+                databaseTypes: databaseTypeConfigsOutcome.ok && databaseTypeDetailsOk
+                    ? { ok: true, serverKeys: databaseTypesWithOps.map((d) => d.typeConfig.databaseType) }
+                    : { ok: false },
+                ruleSets: ruleSetsOutcome.ok
+                    ? { ok: true, serverKeys: ruleSets.map((rs) => ruleSetFileKey(rs)) }
+                    : { ok: false },
+                groupTypeConfigs: groupTypeConfigsOutcome.ok
+                    ? { ok: true, serverKeys: groupTypeConfigs.map((c) => c.groupType) }
+                    : { ok: false },
+                collectionTypeConfigs: collectionTypeConfigsOutcome.ok
+                    ? { ok: true, serverKeys: collectionTypeConfigs.map((c) => c.collectionType) }
+                    : { ok: false },
+                metadataCategoryConfigs: metadataCategoryConfigsOutcome.ok
+                    ? {
+                        ok: true,
+                        serverKeys: metadataCategoryConfigs.map((c) => `${c.resourceType}#${c.category}`),
+                    }
+                    : { ok: false },
+            };
+            let prunedCount = 0;
+            // Keys whose file this prune deliberately left in place. They are absent
+            // server-side, so nothing wrote them into this pull's entity map — see
+            // the restore pass below `keepPrior`.
+            const keptKeysBySlot = {};
+            for (const resourceType of SYNC_RESOURCE_TYPES) {
+                const presence = presenceBySlot[resourceType.stateSlot] ?? { ok: false };
+                const plan = planPrune({
+                    resourceType,
+                    priorKeys: Object.keys(priorEntities[resourceType.stateSlot] ?? {}),
+                    presence,
+                    enabled: options.prune !== false,
+                });
+                if (plan.skipped) {
+                    // `--no-prune` is the operator's explicit choice — no warning for it.
+                    // A failed fetch is worth saying out loud: stale files survive this
+                    // pull, and the next push would re-create their entities.
+                    if (plan.skipReason === "fetch-failed" && Object.keys(priorEntities[resourceType.stateSlot] ?? {}).length > 0) {
+                        warn(`  Skipped pruning ${resourceType.dir} — could not establish which entities the server has; ` +
+                            "local files left untouched");
+                    }
+                    // Only worth saying when a file is actually being left behind:
+                    // this listing is incomplete on every pull, so warning
+                    // unconditionally would just train operators to ignore it.
+                    if (plan.skipReason === "listing-incomplete" && plan.unprunedAbsentKeys.length > 0) {
+                        warn(`  Skipped pruning ${plan.unprunedAbsentKeys.length} ${resourceType.dir} file(s) — ` +
+                            `the server's ${resourceType.dir} listing is not paginated, so an entity missing from it ` +
+                            "may still be live (#1668). Delete the file yourself if the entity is really gone: " +
+                            plan.unprunedAbsentKeys.join(", "));
+                    }
+                    // The files stayed, so their keys stay managed — same rule as the
+                    // kept-file restore below.
+                    if (plan.unprunedAbsentKeys.length > 0) {
+                        keptKeysBySlot[resourceType.stateSlot] = [...plan.unprunedAbsentKeys];
+                    }
+                    continue;
+                }
+                for (const key of plan.unsafeKeys) {
+                    warn(`  Skipped pruning ${resourceType.dir} entry "${key}" — its sync-state key does not map to a safe filename`);
+                }
+                const result = await applyPrune({
+                    configDir,
+                    resourceType,
+                    keys: plan.keys,
+                    testCaseEntities,
+                    logger: info,
+                });
+                prunedCount += result.prunedKeys.length;
+                const kept = [...result.keptWithLocalEdits, ...plan.unsafeKeys];
+                if (kept.length > 0) {
+                    keptKeysBySlot[resourceType.stateSlot] = kept;
+                }
+            }
+            // Preserve prior state for types whose listing failed: nothing was
+            // written for them, so the untouched local files must keep their
+            // managed marker (the same rule `planVarsPull` applies to vars.toml).
+            // For a type that listed fine but had a per-entity fetch failure, keep
+            // the prior entry for that one key — see `preserveUnwrittenEntries`.
+            const keepPrior = (ok, built, slot) => ok ? built : (priorEntities[slot] ?? built);
+            preserveUnwrittenEntries(scriptEntities, priorEntities.scripts, scriptServerKeys);
+            preserveUnwrittenEntries(emailTemplateEntities, priorEntities.emailTemplates, emailTemplatesOutcome.ok
+                ? emailTemplateOverrides.map((t) => t.emailType)
+                : []);
+            const finalCronTriggerEntities = keepPrior(cronTriggersOutcome.ok, cronTriggerEntities, "cronTriggers");
+            const finalBlobBucketEntities = keepPrior(blobBucketsOutcome.ok, blobBucketEntities, "blobBuckets");
+            const finalScriptEntities = keepPrior(scriptListOk, scriptEntities, "scripts");
+            const finalEmailTemplateEntities = keepPrior(emailTemplatesOutcome.ok, emailTemplateEntities, "emailTemplates");
+            const finalDatabaseTypeEntities = keepPrior(databaseTypeConfigsOutcome.ok, databaseTypeEntities, "databaseTypes");
+            const finalRuleSetEntities = keepPrior(ruleSetsOutcome.ok, ruleSetEntities, "ruleSets");
+            const finalGroupTypeConfigEntities = keepPrior(groupTypeConfigsOutcome.ok, groupTypeConfigEntities, "groupTypeConfigs");
+            const finalCollectionTypeConfigEntities = keepPrior(collectionTypeConfigsOutcome.ok, collectionTypeConfigEntities, "collectionTypeConfigs");
+            const finalMetadataCategoryConfigEntities = keepPrior(metadataCategoryConfigsOutcome.ok, metadataCategoryConfigEntities, "metadataCategoryConfigs");
+            // Keep the managed marker on every file prune deliberately left in
+            // place: uncommitted local edits, an unsafe filename, `--no-prune`, or
+            // a listing too incomplete to trust.
+            //
+            // Those keys are absent from the server, so this pull wrote no entry for
+            // them: `preserveUnwrittenEntries` only rescues keys the server LISTED,
+            // and `keepPrior` only fires when a whole listing failed. Without this
+            // pass the key drops out of `entities[<slot>]` here, and on the next pull
+            // the file is indistinguishable from a hand-authored one — never pruned,
+            // never warned about, and reported by `sync diff` as "local only" rather
+            // than absent-from-export. The skip-with-warning safety hatch would work
+            // once and then quietly stop, re-creating the entity on the next push.
+            // Carrying the prior entry forward keeps the file managed until it is
+            // actually gone.
+            const entitiesBySlot = {
+                integrations: integrationEntities,
+                webhooks: webhookEntities,
+                cronTriggers: finalCronTriggerEntities,
+                blobBuckets: finalBlobBucketEntities,
+                prompts: promptEntities,
+                workflows: workflowEntities,
+                scripts: finalScriptEntities,
+                emailTemplates: finalEmailTemplateEntities,
+                databaseTypes: finalDatabaseTypeEntities,
+                ruleSets: finalRuleSetEntities,
+                groupTypeConfigs: finalGroupTypeConfigEntities,
+                collectionTypeConfigs: finalCollectionTypeConfigEntities,
+                metadataCategoryConfigs: finalMetadataCategoryConfigEntities,
+            };
+            for (const [slot, keys] of Object.entries(keptKeysBySlot)) {
+                const built = entitiesBySlot[slot];
+                const prior = priorEntities[slot];
+                if (!built || !prior)
+                    continue;
+                for (const key of keys) {
+                    if (!(key in built) && key in prior) {
+                        built[key] = prior[key];
+                    }
+                }
+                // The block's sidecar test cases were not written either (the block is
+                // gone from the export), and its `<key>.tests/` files are still on disk
+                // because the block's own file was kept — so their records carry
+                // forward on the same rule.
+                const resourceType = SYNC_RESOURCE_TYPES.find((rt) => rt.stateSlot === slot);
+                const blockType = resourceType?.testBlockType;
+                if (!blockType || !priorEntities.testCases)
+                    continue;
+                for (const [tcKey, tcValue] of Object.entries(priorEntities.testCases)) {
+                    if (tcValue.blockType === blockType &&
+                        keys.includes(tcValue.blockKey) &&
+                        !(tcKey in testCaseEntities)) {
+                        testCaseEntities[tcKey] = tcValue;
+                    }
+                }
+            }
             // Save sync state
             const state = {
                 appId: resolvedAppId,
@@ -1965,27 +2469,29 @@ Directory Structure:
                     app: settings ? { modifiedAt: new Date().toISOString(), contentHash: computeFileHash(join(configDir, "app.toml")) } : undefined,
                     integrations: integrationEntities,
                     webhooks: webhookEntities,
-                    cronTriggers: Object.keys(cronTriggerEntities).length > 0 ? cronTriggerEntities : undefined,
-                    blobBuckets: Object.keys(blobBucketEntities).length > 0 ? blobBucketEntities : undefined,
+                    cronTriggers: Object.keys(finalCronTriggerEntities).length > 0 ? finalCronTriggerEntities : undefined,
+                    blobBuckets: Object.keys(finalBlobBucketEntities).length > 0 ? finalBlobBucketEntities : undefined,
                     prompts: promptEntities,
                     workflows: workflowEntities,
-                    scripts: Object.keys(scriptEntities).length > 0 ? scriptEntities : undefined,
-                    emailTemplates: Object.keys(emailTemplateEntities).length > 0 ? emailTemplateEntities : undefined,
+                    scripts: Object.keys(finalScriptEntities).length > 0 ? finalScriptEntities : undefined,
+                    emailTemplates: Object.keys(finalEmailTemplateEntities).length > 0 ? finalEmailTemplateEntities : undefined,
                     testCases: Object.keys(testCaseEntities).length > 0 ? testCaseEntities : undefined,
-                    databaseTypes: Object.keys(databaseTypeEntities).length > 0 ? databaseTypeEntities : undefined,
-                    ruleSets: Object.keys(ruleSetEntities).length > 0 ? ruleSetEntities : undefined,
-                    groupTypeConfigs: Object.keys(groupTypeConfigEntities).length > 0 ? groupTypeConfigEntities : undefined,
-                    collectionTypeConfigs: Object.keys(collectionTypeConfigEntities).length > 0
-                        ? collectionTypeConfigEntities
+                    databaseTypes: Object.keys(finalDatabaseTypeEntities).length > 0 ? finalDatabaseTypeEntities : undefined,
+                    ruleSets: Object.keys(finalRuleSetEntities).length > 0 ? finalRuleSetEntities : undefined,
+                    vars: Object.keys(varEntities).length > 0 ? varEntities : undefined,
+                    groupTypeConfigs: Object.keys(finalGroupTypeConfigEntities).length > 0 ? finalGroupTypeConfigEntities : undefined,
+                    collectionTypeConfigs: Object.keys(finalCollectionTypeConfigEntities).length > 0
+                        ? finalCollectionTypeConfigEntities
                         : undefined,
-                    metadataCategoryConfigs: Object.keys(metadataCategoryConfigEntities).length > 0
-                        ? metadataCategoryConfigEntities
+                    metadataCategoryConfigs: Object.keys(finalMetadataCategoryConfigEntities).length > 0
+                        ? finalMetadataCategoryConfigEntities
                         : undefined,
                 },
             };
             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);
@@ -2000,6 +2506,7 @@ Directory Structure:
             keyValue("Group Type Configs", groupTypeConfigs.length);
             keyValue("Collection Type Configs", collectionTypeConfigs.length);
             keyValue("Metadata Category Configs", metadataCategoryConfigs.length);
+            keyValue("Pruned", prunedCount);
         }
         catch (err) {
             error(err.message);
@@ -2251,10 +2758,110 @@ Directory Structure:
                     }
                 }
             }
+            // Validate app.toml settings up-front (issue #1033). A hand-added
+            // `googleClientSecret` key or a mistyped value is a hard error that must
+            // abort BEFORE any mutation — same fail-before-mutate contract as the
+            // vars preflight below. The apply block re-parses for the payload.
+            const preflightAppTomlPath = join(configDir, "app.toml");
+            if (existsSync(preflightAppTomlPath)) {
+                try {
+                    const parsedApp = parseTomlFile(preflightAppTomlPath);
+                    const appErrors = collectAppSettingsPushErrors(parsedApp, {
+                        isCrossAppPush,
+                    });
+                    for (const e of appErrors) {
+                        preflightValidationErrors.push(`  app.toml: ${e}`);
+                    }
+                }
+                catch (err) {
+                    preflightValidationErrors.push(`  app.toml: ${err?.message || String(err)}`);
+                }
+            }
+            // 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)) {
@@ -2266,27 +2873,13 @@ Directory Structure:
                 }
                 else {
                     const tomlData = parseTomlFile(appTomlPath);
-                    const settings = {};
-                    if (tomlData.app) {
-                        Object.assign(settings, tomlData.app);
-                        // Don't overwrite the target app's name during cross-app push
-                        if (isCrossAppPush) {
-                            delete settings.name;
-                        }
-                    }
-                    if (tomlData.auth) {
-                        const { settings: authSettings, warnings: authWarnings } = parseAppAuthSettings(tomlData.auth);
-                        Object.assign(settings, authSettings);
-                        for (const w of authWarnings) {
-                            warn(`  ${w}`);
-                        }
-                    }
-                    if (tomlData.cors) {
-                        settings.corsMode = tomlData.cors.mode;
-                        settings.corsAllowedOrigins = tomlData.cors.allowedOrigins;
-                        settings.corsAllowCredentials = tomlData.cors.allowCredentials;
-                        settings.corsAllowedMethods = tomlData.cors.allowedMethods;
-                        settings.corsMaxAge = tomlData.cors.maxAge;
+                    // Descriptor-driven parse of every section ([app]/[auth]/[cors]/
+                    // [invitations]) — issue #1033. `name` is stripped on cross-app
+                    // push. Errors (secret key / type mismatch) already aborted the
+                    // push in the preflight pass above, so only warnings remain here.
+                    const { settings, warnings: appWarnings } = parseTomlToAppSettings(tomlData, { isCrossAppPush });
+                    for (const w of appWarnings) {
+                        warn(`  ${w}`);
                     }
                     changes.push({ type: "app", action: "update", key: "settings" });
                     if (!options.dryRun) {
@@ -2302,6 +2895,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,12 +5704,45 @@ 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 = [];
+            // Issue #1659: a local file with no server entity means one of two very
+            // different things, and the operator needs to tell them apart. If a
+            // prior pull managed the key, the entity was deleted server-side and
+            // this stale file will RE-create it on the next push.
+            // If it was never pulled, the operator authored it and push creating it
+            // is the point. Prior sync state is the discriminator, exactly as it is
+            // for the pull-side prune.
+            const localOnlyStatus = (slot, key) => classifyLocalOnly(syncState?.entities, slot, key);
             // Integrations
             for (const key of localIntegrations) {
                 if (!remoteIntegrations.has(key)) {
-                    differences.push({ type: "integration", key, status: "local only" });
+                    differences.push({ type: "integration", key, status: localOnlyStatus("integrations", key) });
                 }
                 else {
                     differences.push({ type: "integration", key, status: "exists" });
@@ -5001,7 +5756,7 @@ Directory Structure:
             // Webhooks
             for (const key of localWebhooks) {
                 if (!remoteWebhooks.has(key)) {
-                    differences.push({ type: "webhook", key, status: "local only" });
+                    differences.push({ type: "webhook", key, status: localOnlyStatus("webhooks", key) });
                 }
                 else {
                     differences.push({ type: "webhook", key, status: "exists" });
@@ -5015,7 +5770,7 @@ Directory Structure:
             // Cron Triggers
             for (const key of localCronTriggers) {
                 if (!remoteCronTriggers.has(key)) {
-                    differences.push({ type: "cron-trigger", key, status: "local only" });
+                    differences.push({ type: "cron-trigger", key, status: localOnlyStatus("cronTriggers", key) });
                 }
                 else {
                     differences.push({ type: "cron-trigger", key, status: "exists" });
@@ -5029,7 +5784,7 @@ Directory Structure:
             // Blob Buckets
             for (const key of localBlobBuckets) {
                 if (!remoteBlobBuckets.has(key)) {
-                    differences.push({ type: "blob-bucket", key, status: "local only" });
+                    differences.push({ type: "blob-bucket", key, status: localOnlyStatus("blobBuckets", key) });
                 }
                 else {
                     differences.push({ type: "blob-bucket", key, status: "exists" });
@@ -5043,7 +5798,7 @@ Directory Structure:
             // Prompts
             for (const key of localPrompts) {
                 if (!remotePrompts.has(key)) {
-                    differences.push({ type: "prompt", key, status: "local only" });
+                    differences.push({ type: "prompt", key, status: localOnlyStatus("prompts", key) });
                 }
                 else {
                     differences.push({ type: "prompt", key, status: "exists" });
@@ -5075,7 +5830,7 @@ Directory Structure:
             const remoteWorkflowIds = new Map(workflowItems.map((w) => [w.workflowKey, w.workflowId]));
             for (const key of localWorkflows) {
                 if (!remoteWorkflows.has(key)) {
-                    differences.push({ type: "workflow", key, status: "local only" });
+                    differences.push({ type: "workflow", key, status: localOnlyStatus("workflows", key) });
                     continue;
                 }
                 // Present on both sides → compare content.
@@ -5126,7 +5881,7 @@ Directory Structure:
             // Email Templates
             for (const key of localEmailTemplates) {
                 if (!remoteEmailTemplates.has(key)) {
-                    differences.push({ type: "email-template", key, status: "local only" });
+                    differences.push({ type: "email-template", key, status: localOnlyStatus("emailTemplates", key) });
                 }
                 else {
                     differences.push({ type: "email-template", key, status: "exists" });
@@ -5147,7 +5902,7 @@ Directory Structure:
             for (const [name, localBody] of localScripts) {
                 const remote = remoteScripts.get(name);
                 if (!remote) {
-                    differences.push({ type: "transform", key: name, status: "local only" });
+                    differences.push({ type: "transform", key: name, status: localOnlyStatus("scripts", name) });
                     continue;
                 }
                 let status = "exists";
@@ -5186,6 +5941,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
@@ -5210,7 +5969,7 @@ Directory Structure:
                 }
                 for (const slug of localTestSlugs) {
                     if (!remoteTestNames.has(slug)) {
-                        testCaseDiffs.push({ blockType, blockKey, slug, status: "local only" });
+                        testCaseDiffs.push({ blockType, blockKey, slug, status: LOCAL_ONLY_NEW });
                     }
                     else {
                         testCaseDiffs.push({ blockType, blockKey, slug, status: "exists" });
@@ -5234,17 +5993,29 @@ Directory Structure:
                 }
             }
             divider();
-            const localOnly = differences.filter((d) => d.status === "local only");
+            const localOnly = differences.filter((d) => d.status === LOCAL_ONLY_NEW);
+            const localOnlyAbsent = differences.filter((d) => d.status === LOCAL_ONLY_ABSENT);
             const remoteOnly = differences.filter((d) => d.status === "remote only");
             const modified = differences.filter((d) => d.status === "modified");
             const existing = differences.filter((d) => d.status === "exists");
             if (localOnly.length > 0) {
-                info("Local only (will be created on push):");
+                info("Local only — new (will be created on push):");
                 for (const d of localOnly) {
                     console.log(`  ${chalk.green("+")} ${d.type}: ${d.key}`);
                 }
                 console.log();
             }
+            // #1659: these files were written by a prior pull, so their entity was
+            // deleted server-side afterwards. `sync pull` prunes them by
+            // default; they only survive under `--no-prune` or a skipped prune, and
+            // while they sit here the next push re-creates what was deleted.
+            if (localOnlyAbsent.length > 0) {
+                warn(`Local only — ${ABSENT_FROM_EXPORT}; push will RE-create these unless you remove them:`);
+                for (const d of localOnlyAbsent) {
+                    console.log(`  ${chalk.yellow("!")} ${d.type}: ${d.key}`);
+                }
+                console.log();
+            }
             if (remoteOnly.length > 0) {
                 warn("Remote only (not in local config):");
                 for (const d of remoteOnly) {
@@ -5271,7 +6042,7 @@ Directory Structure:
                 }
             }
             // Show test case differences
-            const tcLocalOnly = testCaseDiffs.filter((d) => d.status === "local only");
+            const tcLocalOnly = testCaseDiffs.filter((d) => d.status === LOCAL_ONLY_NEW);
             const tcRemoteOnly = testCaseDiffs.filter((d) => d.status === "remote only");
             const tcSynced = testCaseDiffs.filter((d) => d.status === "exists");
             if (tcLocalOnly.length > 0 || tcRemoteOnly.length > 0) {
@@ -5288,7 +6059,8 @@ Directory Structure:
                 }
             }
             divider();
-            keyValue("Local only", localOnly.length);
+            keyValue("Local only (new)", localOnly.length);
+            keyValue("Local only (absent from export)", localOnlyAbsent.length);
             keyValue("Remote only", remoteOnly.length);
             keyValue("Modified", modified.length);
             keyValue("Synced", existing.length);
@@ -5615,24 +6387,4 @@ Directory Structure:
         info("Run 'primitive sync diff' to inspect the restored state versus the server.");
     });
 }
-/**
- * Best-effort check for uncommitted git changes under `dir`. Used only to warn
- * before a revert overwrites local edits — never fatal. Returns false if git
- * isn't available, the dir isn't in a repo, or anything goes wrong.
- */
-async function hasUncommittedChanges(dir) {
-    if (!existsSync(dir))
-        return false;
-    try {
-        const { execSync } = await import("child_process");
-        const out = execSync(`git status --porcelain -- "${dir}"`, {
-            stdio: ["ignore", "pipe", "ignore"],
-            encoding: "utf-8",
-        });
-        return out.trim().length > 0;
-    }
-    catch {
-        return false;
-    }
-}
 //# sourceMappingURL=sync.js.map