primitive-admin 1.0.54 → 1.0.56

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

@@ -0,0 +1,781 @@
+/**
+ * Shared layout metadata for the per-entity resource types `sync pull` writes
+ * into a sync slot (issue #1659).
+ *
+ * `sync pull` writes one file per server entity and records what it wrote in
+ * `.primitive-sync.json` (`SyncState.entities[<slot>]`). Until #1659 it never
+ * removed a local file whose entity had disappeared server-side, so the next
+ * `sync 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 `sync 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, readFileSync, readdirSync, rmSync, statSync, unlinkSync } from "fs";
+import { basename, dirname, join } 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 `sync push` (`planVarsPush`).
+ */
+export const SYNC_RESOURCE_TYPES = [
+    {
+        label: "integration",
+        dir: "integrations",
+        ext: ".toml",
+        stateSlot: "integrations",
+        fileFromKey: tomlFile,
+        // `/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",
+        // `/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,
+    },
+    {
+        label: "database-type",
+        dir: "database-types",
+        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 `.primitive-sync.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;
+}
+/**
+ * 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
+ * `sync 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?" — `sync 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)";
+/** `sync diff` status for a local file whose managed entity is gone. */
+export const LOCAL_ONLY_ABSENT = "local only (absent from export)";
+/** `sync diff` status for a local file the operator authored themselves. */
+export const LOCAL_ONLY_NEW = "local only";
+/**
+ * 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;
+}
+/**
+ * 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. Everything
+ * removed here is recoverable from the pre-pull snapshot via `sync revert`.
+ */
+export async function applyPrune(options) {
+    const { configDir, resourceType, keys, testCaseEntities, 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;
+        // 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.
+        if (await hasUncommittedChanges(filePath, { includeUntracked: false })) {
+            result.keptWithLocalEdits.push(key);
+            log(`  Kept ${relativePath} — ${ABSENT_FROM_EXPORT} but the file 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}`);
+        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 `sync 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). `sync 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 `sync 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 `sync 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);
+}
+/**
+ * `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 `.`).
+ */
+function metadataCategoryKeyFromFile(filePath) {
+    const resourceType = declaredTomlKey(filePath, "metadataCategoryConfig", "resourceType");
+    const category = declaredTomlKey(filePath, "metadataCategoryConfig", "category");
+    if (resourceType && category)
+        return `${resourceType}#${category}`;
+    const base = basename(filePath, ".toml");
+    const dot = base.indexOf(".");
+    if (dot > 0) {
+        return `${base.slice(0, dot)}#${base.slice(dot + 1)}`;
+    }
+    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-types,
+ * 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,
+        deleteEntity: async (c, a, id) => {
+            await c.deleteIntegration(a, id);
+        },
+    },
+    {
+        resourceType: pruneTypeFor("webhook"),
+        keyFromFile: tomlDeclaredKeyFromFile("webhook", "key"),
+        addressOf: addressById,
+        fetchDetail: (c, a, id) => c.getWebhook(a, id),
+        modifiedAtOf: pruneModifiedAt,
+        deleteEntity: async (c, a, id) => {
+            await c.deleteWebhook(a, id);
+        },
+    },
+    {
+        resourceType: pruneTypeFor("cron-trigger"),
+        keyFromFile: tomlDeclaredKeyFromFile("cronTrigger", "key"),
+        addressOf: addressById,
+        fetchDetail: (c, a, id) => c.getCronTrigger(a, id),
+        modifiedAtOf: pruneModifiedAt,
+        deleteEntity: async (c, a, id) => {
+            await c.deleteCronTrigger(a, id);
+        },
+    },
+    {
+        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,
+        deleteEntity: async (c, a, id) => {
+            await c.deletePrompt(a, id);
+        },
+    },
+    {
+        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,
+        deleteEntity: async (c, a, id) => {
+            await c.deleteWorkflow(a, id);
+        },
+    },
+    {
+        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"),
+        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);
+        },
+    },
+    {
+        // #1426 owns the config-delete admin-client wrapper; `deleteResourceMetadata`
+        // is a metadata-*value* delete, not a config delete. Until then a candidate
+        // of this type is reported "no delete surface yet (#1426)", never deleted.
+        resourceType: pruneTypeFor("metadata-category-config"),
+        keyFromFile: metadataCategoryKeyFromFile,
+        addressOf: addressByKey,
+        fetchDetail: (c, a, key) => {
+            // The state key is the `resourceType#category` pair; the getter is
+            // path-addressed by both. (Never actually called — `deleteEntity` is null,
+            // so a candidate short-circuits to "unsupported" before any fetch.)
+            const [resourceType, category] = key.split("#");
+            return c.getMetadataCategoryConfig(a, resourceType, category);
+        },
+        modifiedAtOf: pruneModifiedAt,
+        deleteEntity: null,
+    },
+];
+/**
+ * The set of entity keys the local managed files of a type declare — collected
+ * the way `sync 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. `sync 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 `sync push` derives keys). A
+ * key still declared by some file — even one renamed away from the canonical
+ * `<key>.toml` path — is left alone, since `sync 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 `sync 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" };
+}
+/**
+ * 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 = [];
+    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 };
+}
+/** `sync 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)";
+/** `sync 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
+ * `sync 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