primitive-admin 1.0.55 → 1.0.57

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

@@ -14,6 +14,7 @@
  * — 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"`. */
@@ -40,17 +41,31 @@ export interface SyncResourceType {
      * listing" really means "gone from the server".
      *
      * Prune deletes files, so a successful fetch is not enough — the response also
-     * has to be complete. Only the four listings below paginate (server returns
-     * `nextCursor`, and `sync pull` drains it with `fetchAll`). The rest call
-     * `queryByIndex` with no cursor and return a single DynamoDB page (~1MB), so
-     * a big enough app gets a truncated list with a 200 and no error: the entities
-     * past the page boundary would look deleted and prune would remove the files
-     * of entities that are still live. `cron-triggers` is the sharpest case — a
-     * hard `{ limit: 100 }` with the archived filter applied after the query, so
-     * its effective ceiling is below 100 rows.
+     * 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.
      *
-     * Those types are skipped for pruning until their listings are complete
-     * (#1668). Flip this to `true` per type as each listing learns to paginate.
+     * 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;
 }
@@ -223,3 +238,200 @@ export declare function applyPrune(options: {
     }>;
     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;