primitive-admin 1.0.54 → 1.0.56

package/dist/src/lib/sync-resource-types.d.ts

@@ -0,0 +1,437 @@
+/**
+ * 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 type { SyncState } from "../types/index.js";
+import type { ApiClient } from "./api-client.js";
+export type SyncEntitySlot = keyof SyncState["entities"];
+export interface SyncResourceType {
+    /** Singular name used in pull/diff output, e.g. `"rule-set"`. */
+    label: string;
+    /** Directory under the sync slot holding this type's files. */
+    dir: string;
+    /** Extension of this type's files. */
+    ext: ".toml" | ".rhai";
+    /** Slot in `SyncState.entities` recording what a prior pull managed. */
+    stateSlot: SyncEntitySlot;
+    /**
+     * Entity key → the file basename `sync pull` writes for it. This must match
+     * the write side exactly, so prune only ever targets a file pull created.
+     */
+    fileFromKey(key: string): string;
+    /**
+     * Block type for the sidecar `<key>.tests/` directory, when the type has one.
+     * Pruning an entity also removes its test directory and the matching
+     * `entities.testCases` records.
+     */
+    testBlockType?: "prompt" | "workflow" | "script";
+    /**
+     * Whether this type's server listing returns *every* key, so "absent from the
+     * listing" really means "gone from the server".
+     *
+     * Prune deletes files, so a successful fetch is not enough — the response also
+     * has to be complete. Two shapes make a listing complete: the cursor-paginating
+     * admin endpoints (integrations/webhooks/prompts/workflows — server returns
+     * `nextCursor` and `sync pull` drains it with `fetchAll`), and the config
+     * listings that drain every DynamoDB page server-side via `queryAllPages`
+     * (#1668). Before #1668 the config listings returned a single 100-row page with
+     * a 200 and no cursor, so an app past the page boundary got a silently
+     * truncated list and prune would have removed files of still-live entities;
+     * those types were held at `false`. The server now drains them, so all shipping
+     * types are complete.
+     *
+     * Version-skew assumption (accepted risk): setting a config type `true` assumes
+     * the target server carries #1668's drain. The CLI can target an independently
+     * versioned environment, so a new CLI against a pre-#1668 server still gets a
+     * silently 100-row-truncated listing and prune would delete local files for
+     * still-live entities past the page boundary. This is accepted per the sponsor
+     * ruling on PR #1689 / issue #1668 rather than gated on a server capability or
+     * version marker: the CLI npm publish is coupled to the production deploy (so
+     * new-CLI-vs-old-server is a narrow window), the worst case is git-recoverable
+     * local file deletion touching nothing server-side, and it only affects apps
+     * with >100 entities of one config type — whose `sync pull` was already
+     * silently incomplete before this change.
+     *
+     * The flag remains as a guard: a future type whose listing is not yet complete
+     * ships `false` and prune skips it (`listing-incomplete`) until its server side
+     * drains.
+     */
+    listingComplete: boolean;
+}
+/**
+ * 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 declare function ruleSetFileKey(ruleSet: {
+    name?: string;
+    ruleSetId?: string;
+}): string;
+/**
+ * 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 declare const SYNC_RESOURCE_TYPES: SyncResourceType[];
+/**
+ * Outcome of a server fetch that establishes which entities of a type exist.
+ *
+ * `sync pull` historically swallowed several list errors with `.catch(() => [])`,
+ * which makes a transient 401/500/network error indistinguishable from "the app
+ * has none of these". Pruning off that empty list would delete every local file
+ * of the type, so prune consumes this explicit outcome instead.
+ */
+export type PresenceOutcome = {
+    ok: true;
+    serverKeys: string[];
+} | {
+    ok: false;
+};
+/** Generic try/catch wrapper for a server fetch, in the ok/error shape. */
+export declare function attemptFetch<T>(fn: () => Promise<T>): Promise<{
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: any;
+}>;
+/**
+ * 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 declare function isSafeSyncFilename(filename: string): boolean;
+export interface PrunePlan {
+    /** Entity keys whose managed file should be removed. */
+    keys: string[];
+    /** True when no prune runs for this type at all. */
+    skipped: boolean;
+    /** Why prune was skipped, for the operator-facing warning. */
+    skipReason?: "disabled" | "fetch-failed" | "listing-incomplete";
+    /**
+     * Managed keys whose derived filename is unsafe. Never removed — reported so
+     * a corrupt sync state is visible rather than silent.
+     */
+    unsafeKeys: string[];
+    /**
+     * Managed keys absent from the server listing that this plan is NOT pruning
+     * (`--no-prune`, or a listing that may be truncated). Their files stay on
+     * disk, so the caller must keep their prior state entry — otherwise the key
+     * drops out of `entities[<slot>]` and the file silently stops being managed.
+     * Empty when presence could not be established at all.
+     */
+    unprunedAbsentKeys: string[];
+}
+/**
+ * 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 declare function planPrune(input: {
+    resourceType: SyncResourceType;
+    /** Keys from the prior `SyncState.entities[<slot>]`. */
+    priorKeys: string[];
+    /** Presence of this type's entities server-side, this pull. */
+    presence: PresenceOutcome;
+    /** False when the operator passed `--no-prune`. */
+    enabled: boolean;
+}): PrunePlan;
+/**
+ * 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 declare function preserveUnwrittenEntries<T>(written: Record<string, T>, prior: Record<string, T> | undefined, serverKeys: string[]): Record<string, T>;
+/**
+ * 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 declare function hasUncommittedChanges(path: string, options?: {
+    includeUntracked?: boolean;
+}): Promise<boolean>;
+/**
+ * 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 declare const ABSENT_FROM_EXPORT = "absent from sync export (deleted on server)";
+/** `sync diff` status for a local file whose managed entity is gone. */
+export declare const LOCAL_ONLY_ABSENT = "local only (absent from export)";
+/** `sync diff` status for a local file the operator authored themselves. */
+export declare 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 declare function classifyLocalOnly(priorEntities: SyncState["entities"] | undefined, slot: SyncEntitySlot, key: string): typeof LOCAL_ONLY_NEW | typeof LOCAL_ONLY_ABSENT;
+export interface PruneResult {
+    /** Entity keys whose file was removed — what the "Pruned" count reports. */
+    prunedKeys: string[];
+    /** Slot-relative paths removed (files and sidecar test directories). */
+    removed: string[];
+    /** Keys left in place because the file carries uncommitted local edits. */
+    keptWithLocalEdits: string[];
+    /** `entities.testCases` state keys the pruned blocks owned. */
+    removedTestCaseKeys: string[];
+}
+/**
+ * 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 declare function applyPrune(options: {
+    configDir: string;
+    resourceType: SyncResourceType;
+    keys: string[];
+    /** `entities.testCases` built by this pull; pruned blocks' records are dropped. */
+    testCaseEntities?: Record<string, {
+        blockType?: string;
+        blockKey?: string;
+    }>;
+    logger?: (msg: string) => void;
+}): Promise<PruneResult>;
+/** Address a prior-state entry for detail-fetch and delete. */
+export type PruneAddressOf = (key: string, entry: any) => string | undefined;
+/** Read `id` from an id-addressed slot's state entry. */
+export declare const addressById: PruneAddressOf;
+/** Key-addressed slots are addressed by the state key itself. */
+export declare const addressByKey: PruneAddressOf;
+/**
+ * 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 declare const pruneModifiedAt: (detail: any) => string | 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 declare const workflowPruneModifiedAt: (detail: any) => string | undefined;
+/**
+ * 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 declare const emailTemplatePruneModifiedAt: (detail: any) => string | undefined;
+/**
+ * How to confirm and delete one resource type during push-prune. Narrow by
+ * design (state slot + address + detail-fetch + drift field + delete) rather
+ * than widening `SyncResourceType`, which is pull/diff layout metadata.
+ */
+export interface PushPruneSpec {
+    /** The layout descriptor (dir/ext/fileFromKey/stateSlot/label/testBlockType). */
+    resourceType: SyncResourceType;
+    /**
+     * Derive the entity key a local managed file declares — the SAME derivation
+     * the type's `sync push` loop uses (`<in-file identity> || basename`). Prune
+     * collects the set of these across every file in the type's directory and
+     * treats a prior-state key as a candidate only when NO local file declares
+     * it. This must mirror push exactly: a file renamed but keeping its internal
+     * key is still updated by push, so it must NOT be seen as a delete (#1655).
+     */
+    keyFromFile: (filePath: string) => string;
+    /** Address a prior-state entry for the point read and delete. */
+    addressOf: PruneAddressOf;
+    /** Point-read the live entity; rejects with `ApiError` status 404 when gone. */
+    fetchDetail: (client: ApiClient, appId: string, address: string) => Promise<any>;
+    /** Live `modifiedAt` for the drift check. */
+    modifiedAtOf: (detail: any) => string | undefined;
+    /**
+     * Delete the confirmed entity; rejects with `ConflictError` (409) when the
+     * entity is still referenced. `null` for a type whose CLI delete surface has
+     * not landed yet (metadata-category-configs, gated on #1426): a candidate of
+     * such a type is reported "no delete surface yet" rather than deleted.
+     */
+    deleteEntity: ((client: ApiClient, appId: string, address: string) => Promise<void>) | null;
+}
+/**
+ * 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 declare const PUSH_PRUNE_SPECS: PushPruneSpec[];
+/**
+ * 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 declare function collectLocalDeclaredKeys(input: {
+    spec: PushPruneSpec;
+    configDir: string;
+}): Set<string>;
+/**
+ * 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 declare function collectPushPruneCandidates(input: {
+    spec: PushPruneSpec;
+    configDir: string;
+    priorEntities: Record<string, any> | undefined;
+}): Array<{
+    key: string;
+    entry: any;
+}>;
+/**
+ * Outcome of the point read that confirms (or denies) a candidate's presence.
+ * A flat shape (rather than a discriminated union) because the CLI compiles with
+ * `strict: false`, where union narrowing on `ok` does not hold: `detail` is set
+ * only when `ok`, `status` only on a failed fetch (`status === 404` ⇒ gone).
+ */
+export interface PushPruneFetch {
+    ok: boolean;
+    detail?: any;
+    status?: number;
+}
+export type PushPruneSkipReason = 
+/** State entry has no usable id/key (corrupt or partial state). */
+"no-id"
+/** Type has no CLI delete surface yet (metadata-category-configs, #1426). */
+ | "unsupported"
+/** Live `modifiedAt` differs from prior state — edited out-of-band. */
+ | "drift"
+/** A non-404 fetch error — presence could not be confirmed. */
+ | "unconfirmed";
+export type PushPruneDecision = 
+/** Confirmed present and unchanged (or `--force`): delete it. */
+{
+    action: "delete";
+    address: string;
+    serverModifiedAt?: string;
+}
+/** 404: already gone server-side. Drop its stale state, do not delete. */
+ | {
+    action: "drop-state";
+}
+/** Leave the entity and its prior-state slot intact. */
+ | {
+    action: "skip";
+    reason: PushPruneSkipReason;
+    serverModifiedAt?: string;
+};
+/**
+ * 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 declare function decidePushPruneCandidate(input: {
+    spec: PushPruneSpec;
+    address: string | undefined;
+    priorModifiedAt: string | undefined;
+    fetch: PushPruneFetch;
+    force: boolean;
+}): PushPruneDecision;
+/**
+ * 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 declare function removePrunedSidecar(options: {
+    configDir: string;
+    resourceType: SyncResourceType;
+    key: string;
+    testCaseEntities?: Record<string, {
+        blockType?: string;
+        blockKey?: string;
+    }>;
+    logger?: (msg: string) => void;
+}): {
+    removed: string[];
+    removedTestCaseKeys: string[];
+};
+/** `sync diff` status for a managed remote entity whose local file is gone. */
+export declare 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 declare 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 declare function classifyRemoteOnly(priorEntities: SyncState["entities"] | undefined, slot: SyncEntitySlot, key: string): typeof REMOTE_ONLY_WILL_DELETE | typeof REMOTE_ONLY_UNMANAGED;