primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/sync-resource-types.js

@@ -0,0 +1,1073 @@
+/**
+ * Shared layout metadata for the per-entity resource types `config pull` writes
+ * into a sync slot (issue #1659).
+ *
+ * `config pull` writes one file per server entity and records what it wrote in
+ * `.sync-state.json` (`SyncState.entities[<slot>]`). Until #1659 it never
+ * removed a local file whose entity had disappeared server-side, so the next
+ * `config push` — which treats local TOML as the source of truth — silently
+ * re-created the just-deleted entity.
+ *
+ * This module holds the narrow descriptor the prune pass and `config diff` share:
+ * directory, extension, state slot, key→filename derivation, and the sidecar
+ * test-directory block type. The pull write loops deliberately stay as they are
+ * — this table is layout metadata, not a write framework.
+ */
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, unlinkSync, } from "fs";
+import { basename, dirname, join, resolve, sep } from "path";
+import { parseConfigToml } from "./config-toml.js";
+const tomlFile = (key) => `${key}.toml`;
+/**
+ * Rule sets are keyed on disk (and in sync state) by their name with
+ * filesystem-hostile characters replaced. Shared by the pull write loop and the
+ * prune pass so the two can never derive a different key for the same rule set.
+ */
+export function ruleSetFileKey(ruleSet) {
+    return String(ruleSet.name || ruleSet.ruleSetId || "").replace(/[/\\:*?"<>|]/g, "_");
+}
+/**
+ * Every per-entity resource type in a sync slot. `app.toml` and `vars.toml` are
+ * root singletons, not per-entity directories, so they are not listed here —
+ * var removal is already handled within-file by `config push` (`planVarsPush`).
+ */
+export const SYNC_RESOURCE_TYPES = [
+    {
+        label: "integration",
+        dir: "integrations",
+        ext: ".toml",
+        stateSlot: "integrations",
+        fileFromKey: tomlFile,
+        // #2769 — an integration's test cases live at `integrations/<key>.tests/`,
+        // pulled, pushed, diffed and pruned like every other block's.
+        testBlockType: "integration",
+        // `/admin/api/apps/{id}/integrations` paginates; pull drains it with fetchAll.
+        listingComplete: true,
+    },
+    {
+        label: "webhook",
+        dir: "webhooks",
+        ext: ".toml",
+        stateSlot: "webhooks",
+        fileFromKey: tomlFile,
+        // `/admin/api/apps/{id}/webhooks` paginates; pull drains it with fetchAll.
+        listingComplete: true,
+    },
+    {
+        label: "cron-trigger",
+        dir: "cron-triggers",
+        ext: ".toml",
+        stateSlot: "cronTriggers",
+        fileFromKey: tomlFile,
+        // Server drains `triggersByApp` and filters archived across the full set (#1668).
+        listingComplete: true,
+    },
+    {
+        label: "blob-bucket",
+        dir: "blob-buckets",
+        ext: ".toml",
+        stateSlot: "blobBuckets",
+        fileFromKey: tomlFile,
+        // Server drains `bucketsForApp` across all pages (#1668).
+        listingComplete: true,
+    },
+    {
+        label: "prompt",
+        dir: "prompts",
+        ext: ".toml",
+        stateSlot: "prompts",
+        fileFromKey: tomlFile,
+        testBlockType: "prompt",
+        // `/admin/api/apps/{id}/prompts` paginates; pull drains it with fetchAll.
+        listingComplete: true,
+    },
+    {
+        label: "workflow",
+        dir: "workflows",
+        ext: ".toml",
+        stateSlot: "workflows",
+        fileFromKey: tomlFile,
+        testBlockType: "workflow",
+        // #2645 — named config bodies live in `workflows/<key>.configs/`.
+        namedConfigsDirFromKey: (key) => `${key}.configs`,
+        // `/admin/api/apps/{id}/workflows` paginates; pull drains it with fetchAll.
+        listingComplete: true,
+    },
+    {
+        // Rhai scripts: `.rhai` bodies, not TOML, with tests at
+        // `transforms/<name>.tests/`.
+        label: "transform",
+        dir: "transforms",
+        ext: ".rhai",
+        stateSlot: "scripts",
+        fileFromKey: (key) => `${key}.rhai`,
+        testBlockType: "script",
+        // Server drains `scriptsByApp` across all pages (#1668).
+        listingComplete: true,
+    },
+    {
+        // #3179 — server functions. `functions/<key>.toml` states the function and
+        // names its `entry`; the TypeScript the entry reaches lives beside it in
+        // the same tree and is captured into the version envelope on push, so the
+        // entity spans more than its one file. Prune removes the TOML; the sources
+        // it pulled are tracked in the state slot and removed with it.
+        label: "function",
+        dir: "functions",
+        ext: ".toml",
+        stateSlot: "functions",
+        fileFromKey: tomlFile,
+        // Server drains `functionsByApp` across all pages (#1668's rule, applied at
+        // birth in `server-functions-controller.ts`).
+        listingComplete: true,
+    },
+    {
+        label: "database-type-config",
+        dir: "database-type-configs",
+        ext: ".toml",
+        stateSlot: "databaseTypes",
+        fileFromKey: tomlFile,
+        // Server drains `databaseTypeConfigsForApp` across all pages (#1668).
+        listingComplete: true,
+    },
+    {
+        // The state key is already the sanitized filename the write loop derives
+        // from the rule set's name (`name.replace(/[/\\:*?"<>|]/g, "_")`), so the
+        // filename is the key plus the extension.
+        label: "rule-set",
+        dir: "rule-sets",
+        ext: ".toml",
+        stateSlot: "ruleSets",
+        fileFromKey: tomlFile,
+        // Server drains `ruleSetsForApp` across all pages (#1668).
+        listingComplete: true,
+    },
+    {
+        label: "group-type-config",
+        dir: "group-type-configs",
+        ext: ".toml",
+        stateSlot: "groupTypeConfigs",
+        fileFromKey: tomlFile,
+        // Server drains `configsForApp` across all pages (#1668).
+        listingComplete: true,
+    },
+    {
+        label: "collection-type-config",
+        dir: "collection-type-configs",
+        ext: ".toml",
+        stateSlot: "collectionTypeConfigs",
+        fileFromKey: tomlFile,
+        // Server drains `collectionConfigsForApp` across all pages (#1668).
+        listingComplete: true,
+    },
+    {
+        // State key is the `resourceType#category` pair; the file on disk is
+        // `resourceType.category.toml`.
+        label: "metadata-category-config",
+        dir: "metadata-category-configs",
+        ext: ".toml",
+        stateSlot: "metadataCategoryConfigs",
+        fileFromKey: (key) => `${key.replace("#", ".")}.toml`,
+        // Server drains `metadataCategoriesForApp` across all pages (#1668).
+        listingComplete: true,
+    },
+    {
+        label: "email-template",
+        dir: "email-templates",
+        ext: ".toml",
+        stateSlot: "emailTemplates",
+        fileFromKey: tomlFile,
+        // Server drains `templatesByApp` across all pages (#1668). Independently
+        // safe (#1684): the email-template list is the fixed, bounded `EMAIL_TYPES`
+        // enum (`src/admin-api.ts`), fully returned every call with no pagination —
+        // so there is no version-skew hazard even against a pre-#1668 server.
+        // `planPrune` still prunes only MANAGED keys, so hand-authored files that
+        // were never pulled are left alone.
+        listingComplete: true,
+    },
+];
+/** Generic try/catch wrapper for a server fetch, in the ok/error shape. */
+export async function attemptFetch(fn) {
+    try {
+        return { ok: true, value: await fn() };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+}
+/**
+ * A filename must stay inside its type's directory. State is read from a file
+ * on disk, so a corrupt or hand-edited `.sync-state.json` must never be
+ * able to steer an `unlinkSync` outside the sync slot.
+ */
+export function isSafeSyncFilename(filename) {
+    if (!filename || filename === "." || filename === "..")
+        return false;
+    if (filename.includes("/") || filename.includes("\\"))
+        return false;
+    if (filename.includes("\0"))
+        return false;
+    return true;
+}
+/**
+ * Whether a test-case attachment filename may be written to (or read from) the
+ * sidecar attachment directory (#2769).
+ *
+ * Attachment names come from the SERVER: pull writes each one into
+ * `<key>.tests/<slug>/`, so a stored name carrying a separator or a `..`
+ * segment would place a file outside the sync tree entirely. The rule is the
+ * same one state-derived filenames follow, plus a refusal of any leading-dot
+ * traversal spelling.
+ */
+export function isSafeAttachmentFilename(filename) {
+    if (!isSafeSyncFilename(filename))
+        return false;
+    // `.` and `..` are caught above; `...` and friends are not path traversal but
+    // are not names a fixture file needs either.
+    if (/^\.+$/.test(filename))
+        return false;
+    return true;
+}
+/**
+ * The absolute path an attachment may be written to, or `null` when the name is
+ * unsafe or resolves outside `attachDir` (#2769). Both halves matter: the name
+ * check states the rule, and the resolved-path check enforces it against
+ * platform quirks the name check cannot anticipate.
+ */
+export function attachmentWritePath(attachDir, filename) {
+    if (!isSafeAttachmentFilename(filename))
+        return null;
+    const destination = resolve(attachDir, filename);
+    const root = resolve(attachDir);
+    if (destination !== join(root, filename))
+        return null;
+    if (!destination.startsWith(root + sep))
+        return null;
+    return destination;
+}
+/**
+ * Decide which of a type's managed entity keys should have their local file
+ * removed, given the prior sync state and the outcome of this pull's fetch.
+ *
+ * A key is pruned iff it was **managed** (present in the prior
+ * `SyncState.entities[<slot>]`, so a previous pull wrote its file) and is
+ * **absent from the server keys** this pull fetched. A local file that was
+ * never in prior state was hand-authored — it is left alone and reported by
+ * `config diff` as new.
+ *
+ * Pure and side-effect-free (the caller owns the `unlinkSync`) so the safety
+ * rules are unit-testable without a live server.
+ */
+export function planPrune(input) {
+    const { resourceType, priorKeys, presence, enabled } = input;
+    // Which managed keys the server did not list. Only meaningful when the fetch
+    // succeeded; on a failed fetch we know nothing and must not act.
+    const absentKeys = presence.ok
+        ? priorKeys.filter((key) => !new Set(presence.serverKeys).has(key))
+        : [];
+    if (!enabled) {
+        return {
+            keys: [],
+            skipped: true,
+            skipReason: "disabled",
+            unsafeKeys: [],
+            unprunedAbsentKeys: absentKeys,
+        };
+    }
+    if (!presence.ok) {
+        return {
+            keys: [],
+            skipped: true,
+            skipReason: "fetch-failed",
+            unsafeKeys: [],
+            unprunedAbsentKeys: [],
+        };
+    }
+    // A 200 is not a complete list. Deleting a file because a truncated listing
+    // omitted its entity is unrecoverable-looking to the operator (the entity is
+    // still live, so no later pull rewrites the file), which is worse than
+    // leaving a stale file behind. See `listingComplete`.
+    if (!resourceType.listingComplete) {
+        return {
+            keys: [],
+            skipped: true,
+            skipReason: "listing-incomplete",
+            unsafeKeys: [],
+            unprunedAbsentKeys: absentKeys,
+        };
+    }
+    const keys = [];
+    const unsafeKeys = [];
+    for (const key of absentKeys) {
+        if (!isSafeSyncFilename(resourceType.fileFromKey(key))) {
+            unsafeKeys.push(key);
+            continue;
+        }
+        keys.push(key);
+    }
+    return { keys, skipped: false, unsafeKeys, unprunedAbsentKeys: [] };
+}
+/**
+ * Copy prior state entries for entities the server listed but this pull did not
+ * write (e.g. a script with no active config, or an email template whose detail
+ * fetch failed). Without this the entity would drop out of the state slot and
+ * look hand-authored to the next pull, so its stale file could never be pruned.
+ */
+export function preserveUnwrittenEntries(written, prior, serverKeys) {
+    if (!prior)
+        return written;
+    for (const key of serverKeys) {
+        if (!(key in written) && key in prior) {
+            written[key] = prior[key];
+        }
+    }
+    return written;
+}
+/**
+ * Best-effort check for uncommitted git changes at `path` (a file or a
+ * directory). Returns false when git isn't available, the path isn't in a
+ * repository, or anything else goes wrong — the caller treats "unknown" as
+ * "no local edits", so this never blocks on a non-git checkout.
+ *
+ * `path` is passed as an argument, never interpolated into a shell string:
+ * on the prune path its basename derives from a server entity name, and entity
+ * names are free-form (a rule set may legitimately be named ``a`b`` or `a$b`).
+ * `execFileSync` runs git directly with no shell, so no name can be read as
+ * a command.
+ *
+ * `includeUntracked` decides whether an untracked file counts as a change:
+ * - `true` (default) suits "am I about to overwrite something?" — `config revert`
+ *   would clobber an untracked file just the same.
+ * - `false` suits "did the operator edit this file?" — an untracked file is the
+ *   ordinary state of a pulled file in a sync dir that was never committed, and
+ *   is not evidence of a local edit.
+ */
+export async function hasUncommittedChanges(path, options = {}) {
+    const { includeUntracked = true } = options;
+    if (!existsSync(path))
+        return false;
+    try {
+        const { execFileSync } = await import("child_process");
+        // Run git from the path's own location, not the process cwd: the sync slot
+        // can sit in a different repository than the one the CLI was invoked from
+        // (or in none at all).
+        const cwd = statSync(path).isDirectory() ? path : dirname(path);
+        const args = ["status", "--porcelain"];
+        if (!includeUntracked)
+            args.push("-uno");
+        args.push("--", path);
+        const out = execFileSync("git", args, {
+            cwd,
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf-8",
+        });
+        return out.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The phrase pull and diff both use for an entity that is no longer exported.
+ *
+ * The plan of record asked for "archived or deleted" on the assumption that
+ * archiving drops an entity from the export. It does not: the list endpoints
+ * filter by status only when `?status=` is passed and pull never passes it
+ * (`listAppPrompts`/`listAppIntegrations` in `src/admin-api.ts`; `fetchAll` in
+ * `cli/src/commands/sync.ts`). An archived entity stays in the export and its
+ * TOML is rewritten with `status = "archived"`, so it is never pruned. The only
+ * way to be absent from the export is to have been deleted.
+ */
+export const ABSENT_FROM_EXPORT = "absent from sync export (deleted on server)";
+/** `config diff` status for a local file whose managed entity is gone. */
+export const LOCAL_ONLY_ABSENT = "local only (absent from export)";
+/** `config diff` status for a local file the operator authored themselves. */
+export const LOCAL_ONLY_NEW = "local only";
+/**
+ * `config diff` status for a local file `config push` would refuse (#2880).
+ *
+ * Its own status rather than a hint on a Synced row: the whole point is that
+ * the file is NOT pushable, and the counts a caller reads to decide "is there
+ * anything to do?" have to say so.
+ */
+export const VALIDATION_ERROR = "validation error";
+/**
+ * Classify a local file that has no matching server entity (issue #1659).
+ *
+ * The two cases look identical on disk but mean opposite things. A key a prior
+ * pull managed means the entity was deleted server-side and this stale file
+ * will RE-create it on the next push. A key never pulled means the operator
+ * authored the file and push creating it is the intent.
+ */
+export function classifyLocalOnly(priorEntities, slot, key) {
+    const managed = (priorEntities?.[slot] ?? {});
+    return key in managed ? LOCAL_ONLY_ABSENT : LOCAL_ONLY_NEW;
+}
+/**
+ * Whether `target` is still inside `root` once symlinks are resolved.
+ *
+ * A lexical prefix check answers a question about strings; this one answers the
+ * question the `unlinkSync` actually asks. `functions/shared` pointing at an
+ * external directory passes the string test and deletes someone else's file.
+ */
+function realPathStaysInside(root, target) {
+    try {
+        if (lstatSync(target).isSymbolicLink())
+            return false;
+        const realRoot = realpathSync(root);
+        const real = realpathSync(target);
+        return real.startsWith(realRoot + sep);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remove the local files for `keys` (as decided by `planPrune`), along with any
+ * sidecar `<key>.tests/` directory.
+ *
+ * A file with uncommitted git edits is kept and reported instead: the operator
+ * may be mid-way through authoring a change they meant to push — and for an
+ * entity that owns source files beyond its TOML (#3179), an edit to any of them
+ * keeps the whole entity. Everything removed here is recoverable from the
+ * pre-pull snapshot via `config revert`.
+ */
+export async function applyPrune(options) {
+    const { configDir, resourceType, keys, testCaseEntities, extraFilesForKey, retainedFiles, logger, } = options;
+    const log = logger ?? (() => { });
+    const result = {
+        prunedKeys: [],
+        removed: [],
+        keptWithLocalEdits: [],
+        removedTestCaseKeys: [],
+    };
+    for (const key of keys) {
+        const filename = resourceType.fileFromKey(key);
+        const relativePath = `${resourceType.dir}/${filename}`;
+        const filePath = join(configDir, resourceType.dir, filename);
+        if (!existsSync(filePath))
+            continue;
+        // #3179 — the entity's own source files, recorded by the pull that wrote
+        // them. Each path is re-confined here: it came out of a JSON file on disk,
+        // so a corrupt or hand-edited sync state must never steer an `unlinkSync`
+        // out of the tree — lexically first, then against the real path, because a
+        // symlinked directory inside the tree resolves outside it.
+        const extras = [];
+        for (const extra of extraFilesForKey?.(key) ?? []) {
+            if (retainedFiles?.has(extra)) {
+                log(`  Kept ${extra} — another entity still uses it`);
+                continue;
+            }
+            const target = resolve(configDir, extra);
+            const root = resolve(configDir);
+            if (target === root || !target.startsWith(root + sep)) {
+                log(`  Skipped removing '${extra}' — it resolves outside the config tree`);
+                continue;
+            }
+            if (!existsSync(target))
+                continue;
+            if (!realPathStaysInside(root, target)) {
+                log(`  Skipped removing '${extra}' — a symlink takes it outside the config tree`);
+                continue;
+            }
+            extras.push({ relative: extra, absolute: target });
+        }
+        // Untracked does not mean edited: in a sync dir that was never committed
+        // (or in no repository at all) every pulled file is untracked, and counting
+        // that as a local edit would keep every stale file and leave #1659 unfixed.
+        //
+        // The entity's source files are asked the same question BEFORE anything is
+        // removed (#3179): a half-pruned function — TOML gone, edited TypeScript
+        // kept — is neither state the operator can act on, so an edit anywhere in
+        // the entity keeps all of it.
+        const edited = [];
+        if (await hasUncommittedChanges(filePath, { includeUntracked: false })) {
+            edited.push(relativePath);
+        }
+        for (const extra of extras) {
+            if (await hasUncommittedChanges(extra.absolute, { includeUntracked: false })) {
+                edited.push(extra.relative);
+            }
+        }
+        if (edited.length > 0) {
+            result.keptWithLocalEdits.push(key);
+            log(`  Kept ${relativePath} — ${ABSENT_FROM_EXPORT} but ${edited.join(", ")} ` +
+                "has uncommitted local edits; remove it yourself or re-create the entity on the server");
+            continue;
+        }
+        unlinkSync(filePath);
+        result.prunedKeys.push(key);
+        result.removed.push(relativePath);
+        log(`  Removed ${relativePath} — ${ABSENT_FROM_EXPORT}`);
+        for (const extra of extras) {
+            if (!existsSync(extra.absolute))
+                continue;
+            unlinkSync(extra.absolute);
+            result.removed.push(extra.relative);
+            log(`  Removed ${extra.relative} — ${ABSENT_FROM_EXPORT}`);
+        }
+        // #2645 — the entity's named config bodies go with it. They describe
+        // configurations of a block the server no longer has, and leaving them
+        // would have the next push re-create the block from its own leftovers.
+        const configsDirName = resourceType.namedConfigsDirFromKey?.(key);
+        if (configsDirName) {
+            const configsDir = join(configDir, resourceType.dir, configsDirName);
+            if (existsSync(configsDir) && isSafeSyncFilename(configsDirName)) {
+                rmSync(configsDir, { recursive: true, force: true });
+                result.removed.push(`${resourceType.dir}/${configsDirName}`);
+                log(`  Removed ${resourceType.dir}/${configsDirName} — ${ABSENT_FROM_EXPORT}`);
+            }
+        }
+        if (!resourceType.testBlockType)
+            continue;
+        // Sidecar tests: `<key>.tests/` holds the block's test-case TOMLs and their
+        // attachment directories. With the block gone there is nothing to run them
+        // against, so they go too — along with their sync-state records.
+        const testsDirName = `${key}.tests`;
+        const testsDir = join(configDir, resourceType.dir, testsDirName);
+        if (existsSync(testsDir) && isSafeSyncFilename(testsDirName)) {
+            rmSync(testsDir, { recursive: true, force: true });
+            result.removed.push(`${resourceType.dir}/${testsDirName}`);
+            log(`  Removed ${resourceType.dir}/${testsDirName} — ${ABSENT_FROM_EXPORT}`);
+        }
+        if (testCaseEntities) {
+            for (const [stateKey, entry] of Object.entries(testCaseEntities)) {
+                if (entry?.blockType === resourceType.testBlockType &&
+                    entry?.blockKey === key) {
+                    delete testCaseEntities[stateKey];
+                    result.removedTestCaseKeys.push(stateKey);
+                }
+            }
+        }
+    }
+    return result;
+}
+/** Read `id` from an id-addressed slot's state entry. */
+export const addressById = (_key, entry) => entry && typeof entry.id === "string" && entry.id ? entry.id : undefined;
+/** Key-addressed slots are addressed by the state key itself. */
+export const addressByKey = (key) => key || undefined;
+/**
+ * Live modified timestamp used by the drift check. Most admin/app detail
+ * endpoints serialize `modifiedAt` at the top level (the same field `config pull`
+ * records into state), with `updatedAt` as a defensive fallback. Two detail
+ * endpoints nest the entity under a wrapper key and need their own extractors
+ * below (`workflowPruneModifiedAt`, `emailTemplatePruneModifiedAt`) so the
+ * drift check reads the real timestamp instead of `undefined` — a top-level
+ * read there always looks like drift and blocks `--prune` without `--force`.
+ */
+export const pruneModifiedAt = (detail) => (detail && (detail.modifiedAt ?? detail.updatedAt)) || undefined;
+/**
+ * Workflow detail-read extractor. `getWorkflow` (server `getAppWorkflow`,
+ * src/admin-api.ts) returns `{ workflow, draft, revisions, configs }` — the
+ * entity and its `modifiedAt` are nested under `workflow`, unlike every other
+ * detail endpoint. Read there, not the top level.
+ */
+export const workflowPruneModifiedAt = (detail) => pruneModifiedAt(detail && detail.workflow);
+/**
+ * Email-template detail-read extractor. `getEmailTemplate` returns
+ * `{ emailType, label, hasOverride, override, default, variables }`; the
+ * editable copy `sync` manages — and its `modifiedAt` — live under `override`
+ * (null when there is no override). `config pull` likewise records
+ * `template.override?.modifiedAt`, so the drift check must read the same path.
+ */
+export const emailTemplatePruneModifiedAt = (detail) => pruneModifiedAt(detail && detail.override);
+/**
+ * Read a declared identity field (`[<section>].<field>`) from a managed TOML
+ * file. Returns `undefined` when the field is absent, empty, or the file cannot
+ * be parsed — callers fall back to the filename-derived key, matching the
+ * `<field> || basename(file)` convention every `config push` parser uses.
+ *
+ * Parsed via `parseConfigToml` (not `parseTomlFile`): the identity fields
+ * pruning reads are author-declared top-level values, unaffected by the
+ * workflow-fragment expander, so this avoids depending on `commands/sync.ts`
+ * (which would be a circular import) while producing the same key push does.
+ */
+function declaredTomlKey(filePath, section, field) {
+    let parsed;
+    try {
+        parsed = parseConfigToml(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+    const value = parsed && parsed[section] && parsed[section][field];
+    return typeof value === "string" && value ? value : undefined;
+}
+/**
+ * Build a `keyFromFile` for a TOML type whose entity key is declared at
+ * `[<section>].<field>`, falling back to the file basename (the exact key the
+ * matching `config push` loop derives). This is what lets prune recognize an
+ * entity declared inside a **renamed** file and keep it out of the prune set,
+ * instead of deleting a remote entity that push just updated (issue #1655).
+ */
+function tomlDeclaredKeyFromFile(section, field) {
+    return (filePath) => declaredTomlKey(filePath, section, field) ?? basename(filePath, ".toml");
+}
+/**
+ * `keyFromFile` for types keyed purely by filename — Rhai transforms (the
+ * script `name` is the `.rhai` basename) and rule-sets (the state key is the
+ * sanitized basename). These have no in-file identity, so a rename genuinely
+ * changes the entity and the basename is the correct key.
+ */
+function basenameKeyFromFile(ext) {
+    return (filePath) => basename(filePath, ext);
+}
+/**
+ * Split a metadata-category key into the `resourceType`/`category` pair it
+ * names, or `null` when it is not exactly two non-empty components joined by a
+ * single `#`.
+ *
+ * Load-bearing for prune (#2762). Prune point-reads a candidate BEFORE deciding
+ * what to do with it, and only a missing address short-circuits that fetch — so
+ * a corrupt state key that still produced an address would be read with
+ * `undefined` in the request path, and the resulting 404 would be classified
+ * "already gone", silently dropping the state entry. Failing here instead
+ * routes such a key to the `no-id` skip: no client call, state retained.
+ */
+export function parseMetadataCategoryKey(key) {
+    if (typeof key !== "string")
+        return null;
+    const parts = key.split("#");
+    if (parts.length !== 2)
+        return null;
+    const [resourceType, category] = parts;
+    if (!resourceType || !category)
+        return null;
+    return { resourceType, category };
+}
+/** The same parse, for the spec's read/delete — safe when called standalone. */
+function requireMetadataCategoryKey(key) {
+    const parsed = parseMetadataCategoryKey(key);
+    if (!parsed) {
+        throw new Error(`'${key}' is not a metadata category key — expected <resourceType>#<category>`);
+    }
+    return parsed;
+}
+/**
+ * `keyFromFile` for metadata-category-configs, whose key is the
+ * `resourceType#category` pair. Push reads `[metadataCategoryConfig]`
+ * `resourceType`/`category` and falls back to the filename
+ * (`resourceType.category.toml`, split on the first `.`) for EACH component it
+ * did not find — mirror that per-component fallback exactly. Requiring both
+ * fields before honouring the declaration would key a half-declared file by its
+ * filename while push keyed it by the mix, and prune would then read the
+ * pushed key as undeclared and delete a definition a local file still owns.
+ */
+function metadataCategoryKeyFromFile(filePath) {
+    let resourceType = declaredTomlKey(filePath, "metadataCategoryConfig", "resourceType");
+    let category = declaredTomlKey(filePath, "metadataCategoryConfig", "category");
+    const base = basename(filePath, ".toml");
+    const dot = base.indexOf(".");
+    if (dot > 0) {
+        resourceType = resourceType || base.slice(0, dot);
+        category = category || base.slice(dot + 1);
+    }
+    if (resourceType && category)
+        return `${resourceType}#${category}`;
+    return base;
+}
+function pruneTypeFor(label) {
+    const found = SYNC_RESOURCE_TYPES.find((t) => t.label === label);
+    if (!found)
+        throw new Error(`no sync resource type '${label}'`);
+    return found;
+}
+/**
+ * Every resource type push-prune can retire. Id-addressed types (integrations,
+ * webhooks, cron-triggers, blob-buckets, prompts, workflows, transforms,
+ * rule-sets) fetch/delete by the stored id; key-addressed types (database-type-configs,
+ * group-type-configs, collection-type-configs, email-templates) by the key.
+ *
+ * `--force` (the CLI's existing "override baseline drift" flag) only relaxes the
+ * drift check — it deliberately does NOT pass a server-side force flag on the
+ * delete, so each type's existing 409 dangling-ref guard stays active and a
+ * still-referenced entity is reported "blocked", not force-deleted.
+ */
+export const PUSH_PRUNE_SPECS = [
+    {
+        resourceType: pruneTypeFor("integration"),
+        keyFromFile: tomlDeclaredKeyFromFile("integration", "key"),
+        addressOf: addressById,
+        fetchDetail: (c, a, id) => c.getIntegration(a, id),
+        modifiedAtOf: pruneModifiedAt,
+        // Hard-delete rather than archive (#2803, following #2232's webhook
+        // reasoning). `--prune` is the CLI's hard-delete path: the file that
+        // declared this integration is gone from the config tree, and an archived
+        // row keeps holding its `integrationKey` with no way to reclaim it from
+        // `config`.
+        deleteEntity: async (c, a, id) => {
+            await c.deleteIntegration(a, id, { hard: true });
+        },
+    },
+    {
+        resourceType: pruneTypeFor("webhook"),
+        keyFromFile: tomlDeclaredKeyFromFile("webhook", "key"),
+        addressOf: addressById,
+        fetchDetail: (c, a, id) => c.getWebhook(a, id),
+        modifiedAtOf: pruneModifiedAt,
+        // Hard-delete rather than archive (#2232). Webhooks are the one pruned type with
+        // a per-app cap that archived rows still consume, so an archiving prune
+        // would burn a slot — and keep holding the `webhookKey` — with no way to
+        // reclaim it from `sync`. Enough prune cycles and the app could never
+        // create a webhook again. `--prune` is opt-in and confirmed, and the file
+        // that declared this webhook is gone from the config dir, so a hard delete
+        // is what "retire it" means here. Delivery rows are left behind either way.
+        deleteEntity: async (c, a, id) => {
+            await c.deleteWebhook(a, id, { hard: true });
+        },
+    },
+    {
+        resourceType: pruneTypeFor("cron-trigger"),
+        keyFromFile: tomlDeclaredKeyFromFile("cronTrigger", "key"),
+        addressOf: addressById,
+        fetchDetail: (c, a, id) => c.getCronTrigger(a, id),
+        modifiedAtOf: pruneModifiedAt,
+        // Hard-delete rather than archive (#2803, following #2232's webhook
+        // reasoning). Cron triggers have a per-app cap that archived rows still
+        // consume, and an archived row keeps holding its `triggerKey` with no way
+        // to reclaim it from `config`. `--prune` is opt-in and confirmed, and the
+        // file that declared this trigger is gone from the config tree, so a hard
+        // delete is what "retire it" means here.
+        deleteEntity: async (c, a, id) => {
+            await c.deleteCronTrigger(a, id, { hard: true });
+        },
+    },
+    {
+        resourceType: pruneTypeFor("blob-bucket"),
+        keyFromFile: tomlDeclaredKeyFromFile("bucket", "key"),
+        addressOf: addressById,
+        fetchDetail: (c, a, id) => c.getBlobBucket(a, id),
+        modifiedAtOf: pruneModifiedAt,
+        deleteEntity: async (c, a, id) => {
+            await c.deleteBlobBucket(a, id);
+        },
+    },
+    {
+        resourceType: pruneTypeFor("prompt"),
+        keyFromFile: tomlDeclaredKeyFromFile("prompt", "key"),
+        addressOf: addressById,
+        fetchDetail: (c, a, id) => c.getPrompt(a, id),
+        modifiedAtOf: pruneModifiedAt,
+        // Hard-delete rather than archive (#2887, following #2232's webhook
+        // reasoning). A plain DELETE archives now, and an archived prompt keeps
+        // holding its `promptKey` with no way to reclaim it from `config`. This
+        // had to change in the SAME commit that made the plain DELETE soft, or
+        // `--prune` would have silently stopped destroying anything.
+        deleteEntity: async (c, a, id) => {
+            await c.deletePrompt(a, id, true);
+        },
+    },
+    {
+        // #3179 — server functions. Hard-delete rather than archive, following the
+        // same reasoning as every sibling: an archived function keeps holding its
+        // key in the app's SINGLE key namespace, which now blocks not just another
+        // function but a workflow, a script or a webhook wanting that key, with no
+        // way to reclaim it from `config`. The hard delete is also what destroys
+        // the versions' R2 objects, so a pruned function leaves no bundles behind.
+        resourceType: pruneTypeFor("function"),
+        keyFromFile: tomlDeclaredKeyFromFile("function", "key"),
+        addressOf: addressById,
+        fetchDetail: (c, a, id) => c.getFunction(a, id),
+        modifiedAtOf: pruneModifiedAt,
+        deleteEntity: async (c, a, id) => {
+            await c.deleteFunction(a, id, { hard: true });
+        },
+    },
+    {
+        resourceType: pruneTypeFor("workflow"),
+        keyFromFile: tomlDeclaredKeyFromFile("workflow", "key"),
+        addressOf: addressById,
+        fetchDetail: (c, a, id) => c.getWorkflow(a, id),
+        // `getWorkflow` nests the entity (and modifiedAt) under `workflow`.
+        modifiedAtOf: workflowPruneModifiedAt,
+        // Hard-delete rather than archive (#2887) — same reasoning as the prompt
+        // spec above: the file that declared this workflow is gone from the config
+        // tree, `--prune` is opt-in and confirmed, and an archived row would go on
+        // holding its `workflowKey`.
+        deleteEntity: async (c, a, id) => {
+            await c.deleteWorkflow(a, id, { hard: true });
+        },
+    },
+    {
+        resourceType: pruneTypeFor("transform"),
+        // Rhai scripts are keyed by the `.rhai` basename — no in-file identity.
+        keyFromFile: basenameKeyFromFile(".rhai"),
+        addressOf: addressById,
+        fetchDetail: (c, a, id) => c.getScript(a, id),
+        modifiedAtOf: pruneModifiedAt,
+        deleteEntity: async (c, a, id) => {
+            await c.deleteScript(a, id);
+        },
+    },
+    {
+        resourceType: pruneTypeFor("rule-set"),
+        // Rule sets are keyed by the sanitized basename — no in-file identity.
+        keyFromFile: basenameKeyFromFile(".toml"),
+        addressOf: addressById,
+        fetchDetail: (c, a, id) => c.getRuleSet(a, id),
+        modifiedAtOf: pruneModifiedAt,
+        deleteEntity: async (c, a, id) => {
+            await c.deleteRuleSet(a, id);
+        },
+    },
+    {
+        resourceType: pruneTypeFor("database-type-config"),
+        keyFromFile: tomlDeclaredKeyFromFile("type", "databaseType"),
+        addressOf: addressByKey,
+        fetchDetail: (c, a, key) => c.getDatabaseTypeConfig(a, key),
+        modifiedAtOf: pruneModifiedAt,
+        // No server-side force: the type's 409 dangling-ref guard must stay active.
+        deleteEntity: async (c, a, key) => {
+            await c.deleteDatabaseTypeConfig(a, key);
+        },
+    },
+    {
+        resourceType: pruneTypeFor("group-type-config"),
+        keyFromFile: tomlDeclaredKeyFromFile("groupTypeConfig", "groupType"),
+        addressOf: addressByKey,
+        fetchDetail: (c, a, key) => c.getGroupTypeConfig(a, key),
+        modifiedAtOf: pruneModifiedAt,
+        deleteEntity: async (c, a, key) => {
+            await c.deleteGroupTypeConfig(a, key);
+        },
+    },
+    {
+        resourceType: pruneTypeFor("collection-type-config"),
+        keyFromFile: tomlDeclaredKeyFromFile("collectionTypeConfig", "collectionType"),
+        addressOf: addressByKey,
+        fetchDetail: (c, a, key) => c.getCollectionTypeConfig(a, key),
+        modifiedAtOf: pruneModifiedAt,
+        deleteEntity: async (c, a, key) => {
+            await c.deleteCollectionTypeConfig(a, key);
+        },
+    },
+    {
+        resourceType: pruneTypeFor("email-template"),
+        keyFromFile: tomlDeclaredKeyFromFile("template", "emailType"),
+        addressOf: addressByKey,
+        fetchDetail: (c, a, key) => c.getEmailTemplate(a, key),
+        // `getEmailTemplate` nests the managed override (and modifiedAt) under `override`.
+        modifiedAtOf: emailTemplatePruneModifiedAt,
+        deleteEntity: async (c, a, key) => {
+            await c.deleteEmailTemplate(a, key);
+        },
+    },
+    {
+        // The admin-gated config-delete route (#1364) and its client wrapper are
+        // shipped, so this type retires exactly like its siblings: delete the file,
+        // `config push --prune` (#2762). The interactive `metadata categories delete`
+        // verb this replaced is gone.
+        resourceType: pruneTypeFor("metadata-category-config"),
+        keyFromFile: metadataCategoryKeyFromFile,
+        // Key-addressed like the other config types, but the key is a PAIR: one
+        // that does not parse has no address at all, which routes the candidate to
+        // the `no-id` skip BEFORE the point read (see parseMetadataCategoryKey).
+        addressOf: (key) => (parseMetadataCategoryKey(key) ? key : undefined),
+        fetchDetail: async (c, a, key) => {
+            // The state key is the `resourceType#category` pair; the getter is
+            // path-addressed by both.
+            const { resourceType, category } = requireMetadataCategoryKey(key);
+            return c.getMetadataCategoryConfig(a, resourceType, category);
+        },
+        modifiedAtOf: pruneModifiedAt,
+        deleteEntity: async (c, a, key) => {
+            const { resourceType, category } = requireMetadataCategoryKey(key);
+            await c.deleteMetadataCategoryConfig(a, resourceType, category);
+        },
+        // The warning the retired verb's confirm prompt used to carry.
+        deleteCaveat: "stored metadata values are NOT deleted and become unreachable — delete values first ('primitive metadata delete') if you need them gone",
+    },
+];
+/**
+ * The set of entity keys the local managed files of a type declare — collected
+ * the way `config push` derives keys: parse every file in the type's directory
+ * and read its declared identity (`<in-file key> || basename`), NOT by assuming
+ * the file lives at its canonical `<key>.toml` path.
+ *
+ * This is the crux of the #1655 destructive-delete fix. `config push` accepts a
+ * managed file at a **noncanonical filename** (e.g. `prompts/custom.toml` with
+ * `prompt.key = "greeting"`) and still updates the `greeting` entity. Collecting
+ * declared keys — rather than checking whether `greeting.toml` exists — means a
+ * renamed-but-same-key file keeps its entity out of the prune set, so prune
+ * never deletes an entity push just updated.
+ */
+export function collectLocalDeclaredKeys(input) {
+    const { spec, configDir } = input;
+    const dirPath = join(configDir, spec.resourceType.dir);
+    const keys = new Set();
+    if (!existsSync(dirPath))
+        return keys;
+    for (const file of readdirSync(dirPath)) {
+        if (!file.endsWith(spec.resourceType.ext))
+            continue;
+        const key = spec.keyFromFile(join(dirPath, file));
+        if (key)
+            keys.add(key);
+    }
+    return keys;
+}
+/**
+ * A managed entity whose local declaration is gone — a candidate for
+ * server-side deletion. Pure and side-effect-free: computed from the prior sync
+ * state and the filesystem only (no server call), so it is immune to listing
+ * truncation.
+ *
+ * A key is a candidate iff it was in the prior state slot (a prior pull managed
+ * it) AND **no** local file in the type's directory declares that key (via
+ * {@link collectLocalDeclaredKeys}, mirroring how `config push` derives keys). A
+ * key still declared by some file — even one renamed away from the canonical
+ * `<key>.toml` path — is left alone, since `config push` would update it, not
+ * delete it (issue #1655). A file whose key was never in prior state was
+ * hand-authored and is left for `config push` to create; it is never a candidate.
+ */
+export function collectPushPruneCandidates(input) {
+    const { spec, configDir, priorEntities } = input;
+    if (!priorEntities)
+        return [];
+    const localKeys = collectLocalDeclaredKeys({ spec, configDir });
+    const candidates = [];
+    for (const [key, entry] of Object.entries(priorEntities)) {
+        if (!localKeys.has(key)) {
+            candidates.push({ key, entry });
+        }
+    }
+    return candidates;
+}
+/**
+ * Decide what to do with one prune candidate, given the point read's outcome.
+ * Pure so the safety rules are unit-testable without a live server.
+ *
+ * Fail-closed throughout: a candidate is deleted ONLY on a successful read whose
+ * live `modifiedAt` matches prior state (or under `--force`). A 404 means the
+ * work is already done (drop the stale state). Any other read failure, a missing
+ * address, or a type without a delete surface leaves everything untouched.
+ */
+export function decidePushPruneCandidate(input) {
+    const { spec, address, priorModifiedAt, fetch: fetchOutcome, force } = input;
+    if (!address)
+        return { action: "skip", reason: "no-id" };
+    if (!spec.deleteEntity)
+        return { action: "skip", reason: "unsupported" };
+    if (fetchOutcome.ok) {
+        const serverModifiedAt = spec.modifiedAtOf(fetchOutcome.detail);
+        const unchanged = !!priorModifiedAt &&
+            !!serverModifiedAt &&
+            serverModifiedAt === priorModifiedAt;
+        if (force || unchanged) {
+            return { action: "delete", address, serverModifiedAt };
+        }
+        return { action: "skip", reason: "drift", serverModifiedAt };
+    }
+    // Fetch failed: a 404 means already gone (drop stale state); any other error
+    // means presence could not be confirmed — leave everything intact.
+    if (fetchOutcome.status === 404)
+        return { action: "drop-state" };
+    return { action: "skip", reason: "unconfirmed" };
+}
+/**
+ * Classify an error thrown by a prune delete — one arm for every type.
+ *
+ * Keyed on the status alone (`ConflictError` is an `ApiError` with 409), so no
+ * per-type carve-out can creep into the push command's delete loop and make the
+ * race recovery true for some types and not others (#2762).
+ */
+export function classifyPruneDeleteFailure(err) {
+    const status = err?.statusCode;
+    if (status === 404)
+        return "raced-absent";
+    if (status === 409)
+        return "blocked";
+    return "failed";
+}
+const PRUNE_SKIP_LABELS = {
+    drift: "skipped — modified on server since last sync (use --force)",
+    unconfirmed: "skipped — could not confirm (fetch failed)",
+    "no-id": "skipped — no id in sync state",
+    unsupported: "skipped — no delete surface for this type",
+};
+/**
+ * Render the prune plan the operator reads before the batch confirmation.
+ *
+ * Pure, and here rather than in `sync.ts`, so what the plan states about a type
+ * is testable without a server — specifically that a type's `deleteCaveat`
+ * (metadata's orphaned values, which used to live in the retired verb's confirm
+ * prompt) appears under its delete lines and nowhere else. `config push` renders
+ * the plan ONCE, before the `--dry-run` branch, so both paths print the same
+ * lines (#2762).
+ */
+export function formatPrunePlan(items) {
+    return items.map(({ spec, key, decision }) => {
+        const detail = `${spec.resourceType.label}: ${key}`;
+        if (decision.action === "delete") {
+            return {
+                kind: "delete",
+                status: "will delete",
+                detail,
+                note: spec.deleteCaveat,
+            };
+        }
+        if (decision.action === "drop-state") {
+            return { kind: "absent", status: "already absent", detail };
+        }
+        return {
+            kind: "skip",
+            status: PRUNE_SKIP_LABELS[decision.reason] ?? "skipped",
+            detail,
+        };
+    });
+}
+/**
+ * Remove a pruned block's sidecar `<key>.tests/` directory and its
+ * `entities.testCases` state records. The main file is already gone (that is
+ * what made this a prune candidate), so `applyPrune` above — which bails when
+ * the main file is absent — does not clean the sidecar; this does.
+ */
+export function removePrunedSidecar(options) {
+    const { configDir, resourceType, key, testCaseEntities, logger } = options;
+    const log = logger ?? (() => { });
+    const removed = [];
+    const removedTestCaseKeys = [];
+    // #2645 — the entity's named config bodies orphan the same way its tests do.
+    const configsDirName = resourceType.namedConfigsDirFromKey?.(key);
+    if (configsDirName) {
+        const configsDir = join(configDir, resourceType.dir, configsDirName);
+        if (existsSync(configsDir) && isSafeSyncFilename(configsDirName)) {
+            rmSync(configsDir, { recursive: true, force: true });
+            removed.push(`${resourceType.dir}/${configsDirName}`);
+            log(`  Removed orphaned ${resourceType.dir}/${configsDirName}`);
+        }
+    }
+    if (!resourceType.testBlockType)
+        return { removed, removedTestCaseKeys };
+    const testsDirName = `${key}.tests`;
+    const testsDir = join(configDir, resourceType.dir, testsDirName);
+    if (existsSync(testsDir) && isSafeSyncFilename(testsDirName)) {
+        rmSync(testsDir, { recursive: true, force: true });
+        removed.push(`${resourceType.dir}/${testsDirName}`);
+        log(`  Removed orphaned ${resourceType.dir}/${testsDirName}`);
+    }
+    if (testCaseEntities) {
+        for (const [stateKey, entry] of Object.entries(testCaseEntities)) {
+            if (entry?.blockType === resourceType.testBlockType &&
+                entry?.blockKey === key) {
+                delete testCaseEntities[stateKey];
+                removedTestCaseKeys.push(stateKey);
+            }
+        }
+    }
+    return { removed, removedTestCaseKeys };
+}
+/** `config diff` status for a managed remote entity whose local file is gone. */
+export const REMOTE_ONLY_WILL_DELETE = "remote only (will delete with push --prune)";
+/** `config diff` status for a server entity that was never synced (hand-created). */
+export const REMOTE_ONLY_UNMANAGED = "remote only (left alone)";
+/**
+ * Classify a "remote only" entity (present server-side, no local file) for
+ * `config diff` (issue #1655). A key the prior pull managed means the operator
+ * deleted its local file and `push --prune` will delete the remote entity; a key
+ * never synced was authored on the server and is left alone. Prior sync state is
+ * the discriminator, exactly as it is for the local-only / pull-prune split.
+ */
+export function classifyRemoteOnly(priorEntities, slot, key) {
+    const managed = (priorEntities?.[slot] ?? {});
+    return key in managed ? REMOTE_ONLY_WILL_DELETE : REMOTE_ONLY_UNMANAGED;
+}
+//# sourceMappingURL=sync-resource-types.js.map