primitive-admin 1.0.54 → 1.0.56

package/dist/src/commands/sync-app-settings.js

@@ -0,0 +1,379 @@
+/**
+ * Shared app-settings sync helpers (issue #1033, Phase 2).
+ *
+ * The descriptor-driven `app.toml` round-trip (issue #1033, Phase 1) was born
+ * inside the big `sync pull` / `sync push` command flow. Phase 2 lifts the
+ * app-settings-specific pieces here so BOTH surfaces drive them:
+ *
+ *   - `sync pull` / `sync push` call the low-level helpers
+ *     (`serializeAppSettings`, `collectAppSettingsPushErrors`) — behavior
+ *     unchanged from Phase 1.
+ *   - the new `primitive settings show|pull|push|diff` command
+ *     (`cli/src/commands/settings.ts`) calls the higher-level orchestrators
+ *     (`pullAppSettings`, `pushAppSettings`, `diffAppSettings`, `showAppSettings`).
+ *
+ * Both directions share the same `app.toml`, the same field descriptor
+ * (`cli/src/lib/app-settings-descriptor.ts`), and the same single
+ * `entities.app.contentHash` sync-state entry, so `settings push` then
+ * `sync push` (or the reverse) is idempotent — the second one skips on the
+ * unchanged hash.
+ *
+ * `googleClientSecret` never leaves the server through here: pull omits it,
+ * push errors on it (pointing at `primitive apps update --google-client-secret`),
+ * and `settings show` redacts it in both the rendered and `--json` views.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { createHash } from "crypto";
+import { parseConfigToml, stringifyConfigToml } from "../lib/config-toml.js";
+import { APP_SETTINGS_DESCRIPTOR, APP_SETTINGS_SECTIONS, serializeAppSettingsToToml, parseTomlToAppSettings, } from "../lib/app-settings-descriptor.js";
+import { getServerUrl } from "../lib/config.js";
+import { success, error, info, warn, json, result as printResult, divider, } from "../lib/output.js";
+/** The app-settings file name inside a sync directory. */
+export const APP_TOML_FILENAME = "app.toml";
+/** Absolute path to `app.toml` inside a sync directory. */
+export function appTomlPath(configDir) {
+    return join(configDir, APP_TOML_FILENAME);
+}
+/**
+ * Serialize server settings into the `app.toml` string (pull direction).
+ * Descriptor-driven; `googleClientSecret` is never emitted. This is the single
+ * serializer both `sync pull` and `settings pull` use.
+ */
+export function serializeAppSettings(settings) {
+    return stringifyConfigToml(serializeAppSettingsToToml(settings));
+}
+/** SHA-256 of a file's bytes — the per-file content hash tracked in sync state. */
+function contentHashOfFile(filePath) {
+    return createHash("sha256").update(readFileSync(filePath)).digest("hex");
+}
+function ensureDir(dirPath) {
+    if (!existsSync(dirPath))
+        mkdirSync(dirPath, { recursive: true });
+}
+/**
+ * Write `app.toml` from server settings and return its content hash. Shared by
+ * `sync pull` and `settings pull` so the two produce byte-identical files and
+ * the same hash.
+ */
+export function writeAppSettingsToml(configDir, settings) {
+    const path = appTomlPath(configDir);
+    writeFileSync(path, serializeAppSettings(settings));
+    return contentHashOfFile(path);
+}
+/**
+ * Validate a parsed `app.toml` for push and return the fatal errors (a
+ * hand-added secret key, a type mismatch). An empty array means the push may
+ * proceed. Warnings (unrecognized keys) are intentionally not returned here —
+ * the caller surfaces those at apply time. Shared by the `sync push` preflight
+ * and `settings push`.
+ */
+export function collectAppSettingsPushErrors(tomlData, options = {}) {
+    return parseTomlToAppSettings(tomlData, options).errors;
+}
+// --- Shared single sync-state entry (entities.app) -------------------------
+// `settings pull/push` read and write the SAME `.primitive-sync.json` that
+// `sync` maintains, touching only `entities.app` and preserving every other
+// entity. Kept as small local load/save helpers (rather than importing
+// `sync.ts`) to avoid an import cycle — `sync.ts` imports the serializer above.
+function syncStatePath(configDir) {
+    return join(configDir, ".primitive-sync.json");
+}
+function loadSyncState(configDir) {
+    const p = syncStatePath(configDir);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function saveSyncState(configDir, state) {
+    writeFileSync(syncStatePath(configDir), JSON.stringify(state, null, 2));
+}
+/**
+ * Update `entities.app.contentHash`, preserving all other entities.
+ *
+ * On a cross-app stamp (the loaded state belongs to a different app than the
+ * one we just pulled from / pushed to) this mirrors `sync push` (see
+ * `sync.ts`): it rebinds the sync state to the target app with fresh entities,
+ * then records the app-settings hash. Without the rebind the stored
+ * `state.appId` would stay pointing at the source app, so every later
+ * `settings push <target>` would keep computing `isCrossAppPush` as true — it
+ * would ignore the stored hash and keep stripping `[app].name`, making it
+ * impossible to rename the target app via `app.toml`.
+ */
+function stampAppContentHash(configDir, appId, contentHash) {
+    const now = new Date().toISOString();
+    const existing = loadSyncState(configDir);
+    const isCrossAppStamp = !!(existing && existing.appId !== appId);
+    const state = existing && !isCrossAppStamp
+        ? existing
+        : {
+            appId,
+            serverUrl: existing?.serverUrl ?? getServerUrl(),
+            lastSyncedAt: now,
+            entities: {},
+        };
+    state.entities.app = { modifiedAt: now, contentHash };
+    saveSyncState(configDir, state);
+}
+// --- googleClientSecret redaction (settings show) --------------------------
+/** Placeholder shown in `settings show` in place of any secret field value. */
+export const REDACTED_PLACEHOLDER = "[redacted — set via: primitive apps update <appId> --google-client-secret]";
+/**
+ * Return a copy of the server settings with every secret descriptor field
+ * (currently `googleClientSecret`) redacted when a secret is stored. Used for
+ * BOTH the rendered and `--json` outputs of `settings show` so the real secret
+ * never leaves the server through this command (codex design-review concern #2).
+ *
+ * A secret counts as stored when either:
+ *  - the server sent a truthy raw value — a server older than #1603, which
+ *    still returns `googleClientSecret` on GET; or
+ *  - the companion `<field>Set` boolean is true — #1603 made the secret
+ *    write-only, so `GET /settings` omits the raw value entirely and reports
+ *    `googleClientSecretSet` instead. Without this branch a configured secret
+ *    renders as "(not set)", indistinguishable from an unconfigured one.
+ *
+ * When nothing is stored the field is left untouched, so it renders as
+ * "(not set)" — which is then accurate.
+ */
+export function redactSecretFields(settings) {
+    const out = { ...settings };
+    for (const d of APP_SETTINGS_DESCRIPTOR) {
+        if (!d.secret)
+            continue;
+        const isSet = !!out[d.field] || out[`${d.field}Set`] === true;
+        if (isSet)
+            out[d.field] = REDACTED_PLACEHOLDER;
+    }
+    return out;
+}
+// --- Display helpers -------------------------------------------------------
+function formatValue(value) {
+    if (value === undefined)
+        return "(not set)";
+    if (value === null)
+        return "(null)";
+    if (Array.isArray(value))
+        return value.length === 0 ? "[]" : `[${value.join(", ")}]`;
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
+/** Order-insensitive-free deep equality good enough for settings scalars/arrays. */
+function settingsEqual(a, b) {
+    return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+// --- Command orchestrators (used by cli/src/commands/settings.ts) ----------
+/**
+ * `settings show` — render the current server-effective settings grouped by
+ * `app.toml` section, with `googleClientSecret` redacted. `--json` emits the
+ * full (redacted) server response.
+ */
+export async function showAppSettings(client, appId, options = {}) {
+    try {
+        const settings = await client.getAppSettings(appId);
+        const redacted = redactSecretFields(settings ?? {});
+        if (options.json) {
+            json(redacted);
+            return;
+        }
+        for (const section of APP_SETTINGS_SECTIONS) {
+            const descriptors = APP_SETTINGS_DESCRIPTOR.filter((d) => d.section === section);
+            divider();
+            info(`[${section}]`);
+            for (const d of descriptors) {
+                printResult(`  ${d.key}`, formatValue(redacted[d.field]));
+            }
+        }
+    }
+    catch (err) {
+        error(err.message);
+        process.exit(1);
+    }
+}
+/**
+ * `settings pull` — fetch the server settings, write `app.toml`, and stamp the
+ * shared `entities.app.contentHash`. Same file and hash as `sync pull`.
+ */
+export async function pullAppSettings(client, appId, configDir, options = {}) {
+    try {
+        const settings = await client.getAppSettings(appId);
+        if (!settings) {
+            error(`No settings returned for app ${appId}.`);
+            process.exit(1);
+        }
+        ensureDir(configDir);
+        const contentHash = writeAppSettingsToml(configDir, settings);
+        stampAppContentHash(configDir, appId, contentHash);
+        if (options.json) {
+            json({ wrote: true, path: appTomlPath(configDir), contentHash });
+            return;
+        }
+        success(`Wrote ${appTomlPath(configDir)}`);
+    }
+    catch (err) {
+        error(err.message);
+        process.exit(1);
+    }
+}
+/**
+ * `settings push` — read `app.toml`, validate (abort before any PUT on a secret
+ * key or a type mismatch), skip when unchanged since the last sync unless
+ * `--force`, then apply via `PUT /settings` and re-stamp the shared content
+ * hash. Cross-app pushes (state's app differs from the target) always apply and
+ * strip `name`, matching `sync push`.
+ */
+export async function pushAppSettings(client, appId, configDir, options = {}) {
+    try {
+        const path = appTomlPath(configDir);
+        if (!existsSync(path)) {
+            error(`No ${APP_TOML_FILENAME} found at ${path}. Run 'primitive settings pull' first.`);
+            process.exit(1);
+        }
+        const state = loadSyncState(configDir);
+        const isCrossAppPush = !!(state && state.appId !== appId);
+        let tomlData;
+        try {
+            tomlData = parseConfigToml(readFileSync(path, "utf-8"));
+        }
+        catch (err) {
+            error(`Aborting push: could not parse ${APP_TOML_FILENAME}: ${err?.message || String(err)}`);
+            process.exit(1);
+        }
+        const { settings, warnings, errors } = parseTomlToAppSettings(tomlData, {
+            isCrossAppPush,
+        });
+        // Fail before any mutation on a secret key or a type mismatch.
+        if (errors.length > 0) {
+            error(`Aborting push: ${errors.length} validation error(s) in ${APP_TOML_FILENAME} — no changes were applied.`);
+            for (const e of errors)
+                error(`  ${e}`);
+            process.exit(1);
+        }
+        // Skip when nothing changed since the last sync (shared content hash).
+        const storedHash = isCrossAppPush
+            ? undefined
+            : state?.entities?.app?.contentHash;
+        const changed = options.force || !storedHash || contentHashOfFile(path) !== storedHash;
+        if (!changed) {
+            if (options.json) {
+                json({ applied: false, skipped: true, reason: "unchanged" });
+            }
+            else {
+                info("Skipped app settings (unchanged). Use --force to push anyway.");
+            }
+            return;
+        }
+        for (const w of warnings)
+            warn(`  ${w}`);
+        if (options.dryRun) {
+            if (options.json) {
+                json({ applied: false, dryRun: true, settings });
+            }
+            else {
+                info("[dry-run] Would update app settings.");
+            }
+            return;
+        }
+        await client.updateAppSettings(appId, settings);
+        stampAppContentHash(configDir, appId, contentHashOfFile(path));
+        if (options.json) {
+            json({ applied: true, fields: Object.keys(settings) });
+            return;
+        }
+        success("Updated app settings.");
+    }
+    catch (err) {
+        error(err.message);
+        process.exit(1);
+    }
+}
+/**
+ * `settings diff` — report per-field differences between the local `app.toml`
+ * push payload and the current server settings. Only keys present in the TOML
+ * are compared, so a server value that equals a descriptor default (and is
+ * therefore omitted from `app.toml`) is never flagged as a spurious difference.
+ */
+export async function diffAppSettings(client, appId, configDir, options = {}) {
+    try {
+        const path = appTomlPath(configDir);
+        if (!existsSync(path)) {
+            error(`No ${APP_TOML_FILENAME} found at ${path}. Run 'primitive settings pull' first.`);
+            process.exit(1);
+        }
+        // Local-parse-first, mirroring `settings push`: validate the file before
+        // touching the server so an unpushable file never issues `GET /settings`.
+        let tomlData;
+        try {
+            tomlData = parseConfigToml(readFileSync(path, "utf-8"));
+        }
+        catch (err) {
+            error(`Aborting diff: could not parse ${APP_TOML_FILENAME}: ${err?.message || String(err)}`);
+            process.exit(1);
+        }
+        // Mirror push's cross-app determination (pushAppSettings above): when the
+        // sync state belongs to a different app, the push parse strips `[app].name`
+        // before validating, so diff must strip it too — otherwise a malformed
+        // local `name` would abort diff on a file push would accept and ignore.
+        const state = loadSyncState(configDir);
+        const isCrossAppPush = !!(state && state.appId !== appId);
+        // Present-only push payload — omitted keys are absent, so they can't be
+        // flagged against a server default.
+        const { settings: local, errors } = parseTomlToAppSettings(tomlData, {
+            isCrossAppPush,
+        });
+        // Mirror the push preflight (pushAppSettings above): a file with validation
+        // errors is unpushable, so diff must not present its surviving values as
+        // clean (or as a partial diff) — that would advertise changes push will
+        // never apply. `--json` is ignored on this path, exactly as push does.
+        if (errors.length > 0) {
+            error(`Aborting diff: ${errors.length} validation error(s) in ${APP_TOML_FILENAME} — this file cannot be pushed.`);
+            for (const e of errors)
+                error(`  ${e}`);
+            process.exit(1);
+        }
+        const remote = (await client.getAppSettings(appId)) ?? {};
+        const diffs = [];
+        for (const d of APP_SETTINGS_DESCRIPTOR) {
+            if (d.secret)
+                continue;
+            if (!(d.field in local))
+                continue;
+            const localVal = local[d.field];
+            const remoteVal = remote[d.field];
+            if (!settingsEqual(localVal, remoteVal)) {
+                diffs.push({
+                    field: d.field,
+                    section: d.section,
+                    key: d.key,
+                    local: localVal,
+                    remote: remoteVal,
+                });
+            }
+        }
+        if (options.json) {
+            json({ diffs });
+            return;
+        }
+        if (diffs.length === 0) {
+            success(`No differences — ${APP_TOML_FILENAME} matches server settings.`);
+            return;
+        }
+        info(`${diffs.length} field(s) differ between ${APP_TOML_FILENAME} and the server:`);
+        for (const df of diffs) {
+            divider();
+            info(`[${df.section}].${df.key}`);
+            printResult("  local", formatValue(df.local));
+            printResult("  remote", formatValue(df.remote));
+        }
+    }
+    catch (err) {
+        error(err.message);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=sync-app-settings.js.map

package/dist/src/commands/sync-app-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-app-settings.js","sourceRoot":"","sources":["../../../src/commands/sync-app-settings.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/sync.d.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { ApiClient } from "../lib/api-client.js";
+import { type PresenceOutcome } from "../lib/sync-resource-types.js";
 /**
  * Wrap a server-side error so the printed message identifies which entity
  * was in flight. Used by every entity create/update/delete call site in the
@@ -66,32 +67,28 @@ export declare function hashWorkflowTomlForDiff(parsed: any): string;
  * through `hashWorkflowTomlForDiff` so it lines up with the local-file hash.
  */
 export declare function hashRemoteWorkflowForDiff(workflow: any, draft: any, configs: any[]): string;
+export interface ParsedAuthSettings {
+    settings: Record<string, any>;
+    warnings: string[];
+}
 /**
  * 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 declare function serializeAuthBlock(settings: any): Record<string, any>;
-export interface ParsedAuthSettings {
-    settings: Record<string, any>;
-    warnings: string[];
-}
 /**
  * Translate the [auth] block of app.toml into app-settings fields (push
- * direction).
- *
- * 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.
+ * 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 declare function parseAppAuthSettings(auth: Record<string, any>): ParsedAuthSettings;
 type VarEntity = {
@@ -249,14 +246,66 @@ export declare function rewriteWorkflowSchemasToNative(rawToml: string, workflow
     changed: boolean;
 };
 export declare function serializeWorkflow(workflow: any, draft: any, configs: any[], logger?: (message: string) => void): string;
+export declare function serializeRuleSet(ruleSet: any): string;
 export declare function serializeGroupTypeConfig(config: any, ruleSetIdToName: Map<string, string>): string;
+/**
+ * Issue #1567 — the TOML-owned scalar fields of a database-type config.
+ *
+ * These are fields the `database-types/*.toml` file OWNS: the local file is the
+ * source of truth, so removing one from the TOML must clear it server-side
+ * (config-as-code), not silently preserve the stale value. `schema` is NOT in
+ * this list — it keeps its own `hasSchema` prior-state discriminator, since a
+ * schema is a large sub-tree, not a scalar.
+ */
+export declare const DB_TYPE_OWNED_SCALARS: readonly ["ruleSetId", "triggers", "metadataAccess", "defaultAccess", "autoPopulatedFields", "timestamps", "metadataManifest"];
+/** The user-facing TOML key for a wire field (for push output). */
+export declare function dbTypeFieldLabel(key: string): string;
+/**
+ * True when a value carries real content. null/undefined, blank/whitespace
+ * strings, and empty objects/arrays all count as "no value" — the same
+ * normalization the server applies (`value || null`) when it decides whether a
+ * field is set.
+ */
+export declare function hasMeaningfulValue(v: any): boolean;
+/**
+ * Issue #1567 — always-send owned db-type scalars as value-or-`null`.
+ *
+ * The server PATCH endpoint distinguishes an omitted key (preserve) from an
+ * explicit `null` (clear), so sending every owned scalar as `value ?? null`
+ * converges the server to the local TOML: a field removed from the file lands
+ * as `null` and is cleared. Matches the always-send pattern the sibling
+ * `collection-type-config` push already uses.
+ */
+export declare function buildOwnedScalarUpdate(typeConfig: any): Record<string, any>;
+/**
+ * Issue #1567 — the owned scalars this push genuinely clears: the outgoing
+ * value is empty but the server currently holds a real value (a non-null →
+ * null transition). Used for the "Cleared <field>" report so removing an
+ * access gate is never silent, and to decide whether an otherwise
+ * type-field-less push still needs a type-config PATCH. Returns wire field
+ * names (map with `dbTypeFieldLabel` for output). `serverConfig` is the live
+ * GET; without it (fresh type or a failed fetch) nothing is reported cleared.
+ */
+export declare function ownedScalarsBeingCleared(updateData: Record<string, any>, serverConfig: any): string[];
 export declare function parseDatabaseTypeToml(tomlData: any): {
     typeConfig: any;
     operations: any[];
     subscriptions: any[];
 };
+export declare function parseRuleSetToml(tomlData: any): any;
 export declare function parseGroupTypeConfigToml(tomlData: any): any;
 export declare function parseCollectionTypeConfigToml(tomlData: any): any;
+export declare function hashLocalRuleSetForDiff(parsedToml: any): string;
+export declare function hashRemoteRuleSetForDiff(ruleSet: any): string;
+export declare function hashLocalGroupTypeConfigForDiff(parsedToml: any, ruleSetNameToId: Map<string, string>): string;
+export declare function hashRemoteGroupTypeConfigForDiff(config: any, ruleSetIdToName: Map<string, string>, ruleSetNameToId: Map<string, string>): string;
+export declare function hashLocalCollectionTypeConfigForDiff(parsedToml: any, ruleSetNameToId: Map<string, string>): string;
+export declare function hashRemoteCollectionTypeConfigForDiff(config: any, ruleSetIdToName: Map<string, string>, ruleSetNameToId: Map<string, string>): string;
+export declare function hashLocalDatabaseTypeForDiff(parsedToml: any, ruleSetNameToId: Map<string, string>): string;
+export declare function hashRemoteDatabaseTypeForDiff(typeConfig: any, operations: any[], subscriptions: any[], ruleSetIdToName: Map<string, string>, ruleSetNameToId: Map<string, string>): string;
+export declare function hashLocalMetadataCategoryForDiff(parsedToml: any): string;
+export declare function hashRemoteMetadataCategoryForDiff(config: any): string;
+export declare function parseTomlFile(filePath: string): any;
 /**
  * Paginate through a list endpoint, collecting all items.
  */
@@ -267,6 +316,54 @@ export declare function fetchAll<T>(listFn: (params: {
     items: T[];
     nextCursor?: string | null;
 }>, pageSize?: number, maxPages?: number): Promise<T[]>;
+/**
+ * Issue #976 / #1006: shared 409 → adopt-by-key recovery for `sync push`
+ * create paths. When a CREATE hits a per-app unique-key constraint, the resource
+ * is already on the server but missing from local sync state: orphaned by a
+ * prior push that aborted before recording it, a mid-apply crash, or an
+ * out-of-band create with the same key. Rather than hard-fail forever, this
+ * helper looks the resource up by its unique key and hands the matched item
+ * back so the caller can re-issue the create as an UPDATE and converge.
+ *
+ * The conflict surfaces inconsistently across create routes, so detection is
+ * deliberately broad (see `isConflict` below):
+ *   - a 409 status (webhooks, cron triggers, the standard case);
+ *   - an "already exists" message — some routes surface the 409 as HTTP 400,
+ *     e.g. workflows;
+ *   - a "must be unique" message — routes with no explicit conflict catch let
+ *     dynamo-bao's per-app unique-constraint error propagate verbatim (e.g. rule
+ *     sets, whose create route has no 409 translation). This matches the
+ *     server's own admin-api convention (`src/admin-api.ts`), which treats
+ *     "must be unique" as a duplicate-key conflict.
+ * Any other error is NOT a conflict and re-throws unchanged (see below).
+ *
+ * Safety (load-bearing): exact-key match only. The `lookup` is app-scoped, so a
+ * key match is also an ownership match — an unrelated resource is never
+ * overwritten. The three non-adopt outcomes each surface a clear error and do
+ * NOT touch the server:
+ *   - a non-409 create error is re-wrapped via `wrapEntityError` and re-thrown
+ *     (no lookup is attempted);
+ *   - a lookup failure throws a clear "already exists but could not be adopted
+ *     (lookup failed: …)";
+ *   - a 409 with no matching key re-throws the ORIGINAL create error rather
+ *     than silently proceeding.
+ *
+ * Pagination is the caller's concern: `lookup` must return the COMPLETE
+ * candidate set. For cursor-based lists (webhooks, integrations, prompts,
+ * workflows) wrap the list call in `fetchAll`; the cron-triggers route already
+ * drains every page server-side (#1668) so its flat `{ items }` is complete.
+ * The UPDATE re-issue and sync-state stamping stay with the caller because they
+ * differ per entity.
+ *
+ * @returns the matched existing item (guaranteed non-null on return).
+ */
+export declare function adoptByKeyOnCreate409<T>(opts: {
+    err: unknown;
+    kind: string;
+    key: string;
+    lookup: () => Promise<T[]>;
+    matchKey: (item: T) => boolean;
+}): Promise<T>;
 /**
  * Resolve a key-based rule set name reference to an ID.
  * Throws if the name cannot be resolved and throwOnMissing is true.
@@ -320,6 +417,24 @@ export declare function pullScripts(client: ApiClient, appId: string, configDir:
         contentHash?: string;
     }>;
     count: number;
+    /**
+     * Which scripts the server listed, for the #1659 prune pass. `ok: false` when
+     * the listing failed (an older server without the route, or a transient
+     * error) or when any per-script fetch failed — in either case this pull's
+     * picture of the type is incomplete and must not drive deletions. Scripts
+     * skipped for having no active config are still *present*, so their keys stay
+     * in the set and their local `.rhai` survives.
+     */
+    presence: PresenceOutcome;
+    /**
+     * Whether the script LISTING succeeded. Distinct from `presence`: a failed
+     * per-script fetch blocks pruning but still leaves the other scripts written,
+     * so their fresh state entries must be kept. Only a failed listing means
+     * nothing was written and the prior state slot should be preserved whole.
+     */
+    listOk: boolean;
+    /** Names the server listed, empty when the listing failed. */
+    serverKeys: string[];
 }>;
 export declare function registerSyncCommands(program: Command): void;
 export {};