primitive-admin 1.1.0-alpha.65 → 1.1.0-alpha.67

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

@@ -6,6 +6,7 @@ import { type PushMode } from "../lib/config-payload.js";
 import { type ConfigObjectSurface, type ConfigTable } from "../lib/generated-config-surfaces.js";
 import { type PresenceOutcome, type TestBlockType } from "../lib/sync-resource-types.js";
 import type { SyncState } from "../types/index.js";
+import { type SyncSelection } from "../lib/sync-selectors.js";
 /**
  * Wrap a server-side error so the printed message identifies which entity
  * was in flight. Used by every entity create/update/delete call site in the
@@ -526,6 +527,36 @@ export declare function archivedTombstoneEntries(items: any[], select: {
     id: string;
     modifiedAt: string;
 }>;
+/**
+ * Fold one type's tombstone entries into the sync state this pull is building
+ * (#2803, corrected by #2887).
+ *
+ * Two rules, and the second one is the fix. A tombstone is recorded only for a
+ * key this pull did NOT export (an exported key is a live row and its own
+ * record) and only when the selection covers it. And a recorded key is marked
+ * as MATCHED: archived rows are dropped before `selectPull` runs, so the
+ * selector that named one never reached the set that decides whether the pull
+ * found what it was asked for. `config pull --only workflow/<key>` against an
+ * archived managed row therefore removed the file, saved the tombstone, and
+ * then exited 1 saying "the server has no workflow/<key>" — a failure report
+ * about a mutation that had already succeeded, which is the worst thing an
+ * automation can be told. The fix is generic, so integrations and webhooks
+ * (which had the bug first) get it too.
+ *
+ * Mutates `built` and `matchedSelectors` and returns the keys it recorded, so
+ * the caller can report each one. Pure otherwise, and unit-testable.
+ */
+export declare function recordArchivedTombstones(built: Record<string, {
+    id: string;
+    modifiedAt: string;
+}>, tombstones: Record<string, {
+    id: string;
+    modifiedAt: string;
+}>, context: {
+    label: string;
+    selection: SyncSelection | null;
+    matchedSelectors: Set<string>;
+}): string[];
 /**
  * The `config diff` annotation for an object an operator took out of service
  * (issue #2645, criterion 9; #2803).
@@ -784,6 +815,32 @@ export declare function unknownKeyPreflightTargets(): Array<{
     surface: ConfigObjectSurface;
     tables: ConfigTable[];
 }>;
+/** One config file the TOML preflight rejects, and the row it belongs to. */
+export interface ConfigFileValidationError {
+    /** The `config diff` row type, e.g. `prompt`. */
+    type: string;
+    /** The row key the local file pairs on. */
+    key: string;
+    filePath: string;
+    /** The messages, verbatim — the same text `config push` aborts with. */
+    messages: string[];
+}
+/**
+ * Every per-entity config file whose TOML `config push` would refuse (#2880
+ * criterion 1, symmetry).
+ *
+ * One collector, two commands. Push aborts on the messages before issuing a
+ * request; `config diff` renders them as their own rows, because the failure
+ * this closes is a file diff calls Synced and push then rejects — the state the
+ * issue's reporter hit after #2803 retired `[prompt].status`, where a local key
+ * with no server counterpart is invisible to a comparison and fatal to a push.
+ *
+ * Three checks, all definition-driven: the document's table shape, keys no
+ * definition declares (retired keys among them), and — since #2880 — values
+ * whose spelling is not the declared type. A file that does not parse is left
+ * to the per-type loop that reads it, which names the parse error itself.
+ */
+export declare function collectConfigFileValidationErrors(configDir: string): ConfigFileValidationError[];
 /**
  * Every `<key>.tests/*.toml` sidecar under a config directory.
  *
@@ -1108,12 +1165,47 @@ export interface ConfigDiffMaps {
 export interface ConfigDiffSpec {
     label: string;
     table: ConfigTable;
-    /** TOML doc -> the wire-shaped entity (the same parse `config push` uses). */
-    parse(doc: any): any;
+    /**
+     * TOML doc -> the wire-shaped entity (the same parse `config push` uses).
+     *
+     * `extra` is the per-type context the projection needs and the document does
+     * not carry (#2880): a test case's id→name lookups, through which the two
+     * spellings of a reference meet. Mirrors `serialize`, which has taken one
+     * since the database types joined.
+     */
+    parse(doc: any, extra?: any): any;
     /** Server entity -> the TOML `config pull` would write. */
     serialize(record: any, maps: ConfigDiffMaps, extra?: any): string;
     /** Structural values to hash beside the definition's fields. */
-    extras?(entity: any, doc: any): Record<string, any>;
+    extras?(entity: any, doc: any, extra?: any): Record<string, any>;
+    /**
+     * Rewrite the parsed entity the way the SERVER rewrites an accepted one
+     * (#2880 DSO-003).
+     *
+     * Some handlers canonicalize on the way in — an integration's base URL gains
+     * a trailing slash, its methods are upper-cased — so the state the server
+     * returns is not the text the file holds. Comparing them raw makes an
+     * authored-but-noncanonical value `local-edited` on every run and push
+     * re-apply the same update forever; restamping the baseline cannot fix it,
+     * because the local side never moves. Applied to both sides (the remote
+     * reaches it through the same projection), so it must be idempotent.
+     */
+    canonicalize?(entity: any): void;
+    /**
+     * The projected keys THIS FILE does not manage (#2880 criterion 3).
+     *
+     * A handful of fields are present-only by design: push sends them when the
+     * file spells them and leaves the server's value alone when it does not,
+     * because "absent" here means "not authored here" rather than "cleared" — a
+     * webhook with no `[verification]` section at all, whose signing material a
+     * push must not revoke as a side effect. Comparing such a field against a
+     * server that holds one reports a difference push will never act on: the
+     * update omits the key, the server keeps its value, and the row comes back
+     * Modified on every run. So the local side inherits the remote value for
+     * exactly the keys the file leaves unmanaged, and the two commands agree
+     * that there is nothing to do.
+     */
+    unmanaged?(doc: any): string[];
     /** Whether the entity carries a rule-set reference needing resolution. */
     ruleSetRef?: boolean;
     /** How the type names itself in the rule-set resolution message. */
@@ -1121,9 +1213,10 @@ export interface ConfigDiffSpec {
 }
 /**
  * Every type the shared comparator serves — the types `config diff` compares
- * field-for-field, and that `config push` gates on the same projection wherever
- * it has adopted the shared gate (#2731 B1/B2; webhooks joined the comparator
- * in #2757 while push keeps its own byte-hash gate).
+ * field-for-field, and that `config push` gates on the same projection
+ * (#2731 B1/B2; webhooks joined the comparator in #2757 and their push joined
+ * the same gate in #2880, so no registered type answers "changed?" from the
+ * file's bytes any more).
  *
  * Published so the round-trip acceptance bar (#2731 B9) can require a fixture
  * per type instead of listing them a second time by hand: converting a type is
@@ -1138,11 +1231,41 @@ export declare function configDiffSpec(label: string): ConfigDiffSpec;
  * a push that needs to SAY what differs and a diff that only needs to know THAT
  * something differs read the same projection.
  */
-export declare function projectLocalConfig(spec: ConfigDiffSpec, parsedToml: any, maps: ConfigDiffMaps): Record<string, any>;
+export declare function projectLocalConfig(spec: ConfigDiffSpec, parsedToml: any, maps: ConfigDiffMaps, extra?: any): Record<string, any>;
 /** The same projection for a SERVER entity — see `hashRemoteConfigForDiff`. */
 export declare function projectRemoteConfig(spec: ConfigDiffSpec, record: any, maps: ConfigDiffMaps, extra?: any): Record<string, any>;
+/**
+ * BOTH sides of one comparison, with the file's unmanaged keys reconciled
+ * (#2880) — the one place `spec.unmanaged` is honored, so `config diff` and
+ * `config push` cannot read the same file differently.
+ */
+export declare function projectConfigPair(spec: ConfigDiffSpec, localParsed: any, remoteRecord: any, maps: ConfigDiffMaps, extra?: any, localExtra?: any): {
+    local: Record<string, any>;
+    remote: Record<string, any>;
+};
+/**
+ * One `config diff` row's content verdict for a registered type (#2880).
+ *
+ * The three outcomes the per-type blocks were each spelling out by hand:
+ * equal (`exists`), different (`modified`, framed as a preview of
+ * `config pull`), and "could not tell" — a missing record or a comparison that
+ * threw, which degrades THIS row and never the whole diff. Written once so a
+ * type joining the comparator cannot accidentally report a fourth thing.
+ *
+ * The two `extra` arguments are the same split `decidePushForConfig` makes:
+ * `extra` carries what only the SERVER side has (a database type's operation
+ * rows), while `localExtra` is context BOTH sides read a value through — a test
+ * case's id→name lookups. Giving the local side nothing was a silent
+ * mistranslation: a sidecar pinned by a resolvable `configId` projected the id
+ * while the server's projection resolved it to the name, so an untouched file
+ * reported Modified in diff and drifted in push.
+ */
+export declare function compareLocalToRemote(spec: ConfigDiffSpec, localParsed: any, remoteRecord: any, maps?: ConfigDiffMaps, extra?: any, localExtra?: any): {
+    status: string;
+    hint?: string;
+};
 /** Hash a LOCAL config file's definition-projected field set (#2644). */
-export declare function hashLocalConfigForDiff(spec: ConfigDiffSpec, parsedToml: any, maps: ConfigDiffMaps): string;
+export declare function hashLocalConfigForDiff(spec: ConfigDiffSpec, parsedToml: any, maps: ConfigDiffMaps, extra?: any): string;
 /**
  * Hash a SERVER entity the same way, by serializing it into the file `sync
  * pull` would write and hashing that — so the two sides are normalized
@@ -1162,10 +1285,13 @@ export interface PushFieldDiff {
 /**
  * What `config push` should do with one converted-type file, and why.
  *
- * `create`/`skip`/`update` are the applying outcomes; `drift`, `conflict` and
- * `immutable` are the three ways push declines to apply and says so.
+ * `create`/`skip`/`update` are the applying outcomes; `drift`, `conflict`,
+ * `immutable` and `live-unavailable` are the four ways push declines to apply
+ * and says so.
  */
 export type PushGateOutcome = {
+    action: "live-unavailable";
+} | {
     action: "create";
 } | {
     action: "skip";
@@ -1173,7 +1299,7 @@ export type PushGateOutcome = {
     remoteHash: string;
 } | {
     action: "update";
-    direction: "local-edited" | "forced";
+    direction: "local-edited" | "forced" | "adopt-untracked";
     localHash: string;
     remoteHash?: string;
     expectedModifiedAt?: string;
@@ -1219,7 +1345,47 @@ export interface PushBaselineEntry {
  *
  * Declining is a first-class outcome here. `drift`, `conflict` and `immutable`
  * each carry the field diff their report prints, and nothing is applied.
- */
+ *
+ * `adoptsUntrackedByKey` is the one exception a type can ask for, and it is
+ * documented on the field: an object the manifest has never recorded is the
+ * adopt its create path would have performed via a 409 (#1006/#2909), not a
+ * difference to refuse.
+ */
+/**
+ * What the DEGRADED gate does with one file — the path a converted type takes
+ * when its live read failed (#2880 criterion 7).
+ *
+ * Falling back to the manifest's byte hash is right while there is one to fall
+ * back to. Without one, `shouldPushFile(file, undefined)` answers "push it",
+ * so a fresh checkout or a lost manifest turned "we could not read the server"
+ * into "overwrite the server", unconditionally and silently — the one shape of
+ * blind write this issue's direction attribution exists to prevent. So a
+ * baseline-less update DECLINES: the resource is not written and the operator
+ * is told which of `config pull` / `--force` clears it.
+ *
+ * A file the manifest does not name is declined for the same reason, and this
+ * is the part that is easy to get wrong: an unrecorded file looks like a
+ * create, but only LIVE STATE can say the server has nothing under that key —
+ * and live state is exactly what this path could not read. The create that
+ * follows is adopted by key on the 409 and re-issued as an update, so
+ * "there is no recorded entity to overwrite" would have been a blind overwrite
+ * of a resource this run never compared. Every section's degraded gate is
+ * reached only when the live read failed, so there is no case here where
+ * absence was proved.
+ */
+export type DegradedPushDecision = {
+    action: "skip";
+} | {
+    action: "send";
+} | {
+    action: "decline";
+    reason: "no-baseline";
+};
+export declare function decideDegradedPush(input: {
+    force?: boolean;
+    storedContentHash?: string;
+    currentFileHash?: string;
+}): DegradedPushDecision;
 export declare function decidePushForConfig(input: {
     spec: ConfigDiffSpec;
     maps: ConfigDiffMaps;
@@ -1234,7 +1400,38 @@ export declare function decidePushForConfig(input: {
     entry?: PushBaselineEntry | null;
     /** Byte hash of the local file — the legacy direction signal. */
     localFileHash?: string;
+    /**
+     * Per-type context for the LOCAL projection (#2880) — a test case's id→name
+     * lookups. Separate from `live.extra`, which carries remote-only rows (a
+     * database type's operations) the local parse must never see.
+     */
+    localExtra?: any;
     force?: boolean;
+    /**
+     * Whether this type's push path ADOPTS an existing object by key (#2909).
+     *
+     * Opt-in, and it changes exactly one outcome: a live entity the manifest has
+     * no row for at all. Prompts (#1006), and the other types whose create path
+     * recovers a 409 through `adoptByKeyOnCreate409`, treat that as the adopt it
+     * has always been — an object pushed from another slot, created out of band,
+     * or orphaned by a push that aborted before recording it, which the local
+     * file is the declared intent for. Without this the gate reads that same
+     * shape as a difference it cannot attribute, refuses, and the create the
+     * adopt guard recovers from is never even sent (the #2909 regression).
+     *
+     * #2934 — the criterion is the CREATE PATH, not which issue converted the
+     * type: cron triggers, webhooks, integrations, blob buckets and the
+     * group/collection type configs all recover their create's key conflict the
+     * same way, so they pass it too. Passing it at one call site left the other
+     * five reporting a conflict for the adopt their own create documents.
+     *
+     * Rule sets keep it OFF, and that is a decision rather than an omission:
+     * #2731 made a never-synced rule set differing from a same-named live one the
+     * conflict the operator resolves with `config pull` or `--force`, its own
+     * tests pin that, and `resourceType` — the field a wrong adopt would silently
+     * strand — is one an update cannot repair.
+     */
+    adoptsUntrackedByKey?: boolean;
 }): PushGateOutcome;
 /**
  * The identity a file may leave to its name, written back into the parsed
@@ -1585,7 +1782,16 @@ export declare function unselectedRuleSetIds(params: {
     nameForFile: (file: string) => string | undefined;
 }): Map<string, string>;
 export declare function slugifyTestCaseName(name: string): string;
-export declare function resolveSlugCollisions(slug: string, usedSlugs: Set<string>): string;
+/**
+ * The name to use for `slug`, given the names already taken.
+ *
+ * `occupy` decides what "already taken" means, and `usedSlugs` holds names in
+ * that form (#2896): a file name is occupied CASE-INSENSITIVELY on the
+ * filesystems most of these trees live on, so `Foo` and `foo` are one file even
+ * though they are two strings. The returned name keeps its own casing — only
+ * the occupancy check is normalized.
+ */
+export declare function resolveSlugCollisions(slug: string, usedSlugs: Set<string>, occupy?: (name: string) => string): string;
 export declare function getTestsDir(configDir: string, blockType: string, blockKey: string): string;
 export interface TestCaseLookupMaps {
     configIdToName: Map<string, string>;
@@ -1795,6 +2001,24 @@ export declare function planAttachmentPush(params: {
     upload: string[];
     removedRemotely: string[];
 };
+/**
+ * Create a test case carrying the identity its file name asserts (#2896).
+ *
+ * The one case protocol detection cannot answer is a create into an EMPTY
+ * block: there is no listed record to read `key` off. Push is optimistic there,
+ * and an older server's 400 is the answer — retried once without the key, and
+ * named, because a case created without one will duplicate on the next clone.
+ */
+export declare function createTestCaseWithIdentity(params: {
+    client: ApiClient;
+    appId: string;
+    blockType: TestBlockType;
+    blockId: string;
+    payload: any;
+    /** Omitted when the server has no keys; then this is exactly the old call. */
+    key?: string;
+    logger?: (message: string) => void;
+}): Promise<any>;
 /**
  * Push one block's authored test-case sidecar. Exported so the unit tests can
  * drive it against a stubbed client on a temp directory.
@@ -1818,6 +2042,23 @@ export declare function pushTestCasesForBlock(params: {
     }>;
     /** Where a rejected create/update/upload goes — it fails the push (#2731 B2). */
     failures: ApplyFailure[];
+    /**
+     * What push DECLINED to apply (#2880): server drift, a conflict, a live read
+     * that failed with no baseline. Reported exactly as every other converted
+     * type reports it — the caller passes its `recordDeclined`.
+     */
+    declined?: (type: string, key: string, outcome: Extract<PushGateOutcome, {
+        action: "drift" | "conflict" | "immutable" | "live-unavailable";
+    }>, storedModifiedAt?: string) => void;
+    /** The id→name lookups the comparison reads a reference through (#2880). */
+    lookupMaps?: TestCaseLookupMaps;
+    /**
+     * Re-derive `lookupMaps` from the caller's name→id maps (#2880). Called after
+     * this case's references are resolved and before it is compared: resolution
+     * is what LOADS a block's configs, so the comparison would otherwise read a
+     * reference the same push just learned how to read.
+     */
+    refreshLookupMaps?: () => void;
     resolutionMaps?: PushResolutionMaps;
     options?: {
         force?: boolean;
@@ -1826,25 +2067,101 @@ export declare function pushTestCasesForBlock(params: {
     skipped: number;
 }>;
 /**
- * Classify one block's sidecar against the server's test-case names (#2769).
+ * The file name each live test case belongs in (#2896).
+ *
+ * A KEYED case is named by its key: that is what the key is — the basename the
+ * committed tree carries. An unkeyed one (created by web-admin, an older CLI or
+ * the raw API) keeps the slug-of-name naming, with the collision suffixes
+ * resolved only AFTER the keys have claimed theirs, so a slug can never take a
+ * name a key owns.
+ *
+ * One function for pull, for pairing's adoption pass and for the diff's
+ * remote-only rows, because three commands that name a case's file differently
+ * is the disagreement this issue reports.
+ *
+ * Two names that differ only by CASE are one file on a case-insensitive
+ * filesystem, so occupancy is tracked the way the server's key constraint
+ * normalizes: a keyed `Foo` and an unkeyed case named "foo" get `Foo.toml` and
+ * `foo-2.toml`, rather than one pull silently overwriting the other's sidecar.
+ */
+export declare function testCaseFileBasenames(liveCases: any[], onUnusableKey?: (live: any, reason: string) => void, isSafeName?: (name: string) => boolean): Map<any, string>;
+/**
+ * Whether a sidecar and a live case say the same thing (#2896).
+ *
+ * The corroboration the adoption passes below need: identity nothing states can
+ * only be inferred from content, and only when the inference is unique. It is
+ * the SAME projection `config diff` compares with, memoized per file and per
+ * record, so pairing and the change verdict can never disagree. A file that
+ * cannot be read matches nothing — an unparseable sidecar fails its own push
+ * with a message that names it.
+ */
+export declare function testCaseContentMatcher(params: {
+    testsDir: string;
+    spec: ConfigDiffSpec;
+    extra?: any;
+}): (localSlug: string, live: any) => boolean;
+/**
+ * Which live test case each sidecar manages (#2880 behavior 16, #2896).
+ *
+ * The manifest id comes FIRST, then the identity the COMMITTED tree carries —
+ * the file's basename, matched against the case's stored `key`. Everything
+ * after that is adoption of a case whose identity nothing states: a rename the
+ * manifest still remembers under the old name, a legacy case matched by
+ * content, and finally the slug-of-name rule #2880 shipped.
+ *
+ * The order matters because every pass consumes its claims: identity that IS
+ * recorded always wins over a guess, and a guess is only made when it is
+ * unambiguous in BOTH directions. Where it is not, the file stays unpaired and
+ * is barred from the create path — push refusing to guess is the whole point,
+ * since the failure it replaces is a silently duplicated test case.
  *
- * Remote slugs are derived exactly the way pull writes them — same slugify,
- * same collision suffixes, same order — because a `<slug>-2.toml` on disk IS
- * the second colliding name and must not read as an unpushed local file.
+ * Against a server with no keys the passes that depend on them are skipped
+ * entirely, so pairing is bit-for-bit what #2880 shipped.
+ *
+ * One function for both commands, because a diff row and a push decision that
+ * pair differently are two answers to the same question.
  */
-export declare function classifyTestCaseSidecarDiff(params: {
-    remoteNames: string[];
+export declare function pairTestCases(input: {
+    blockType: string;
+    blockKey: string;
     localSlugs: string[];
-}): Array<{
-    slug: string;
-    status: string;
-}>;
+    liveCases: any[];
+    managed: Record<string, {
+        id?: string;
+        slug?: string;
+        blockKey?: string;
+    }> | undefined;
+    /** Whether the server carries identity keys at all (#2896). */
+    serverSupportsKeys?: boolean;
+    /** Whether a local sidecar's content equals a live case's projection. */
+    contentMatches?: (localSlug: string, live: any) => boolean;
+}): {
+    bySlug: Map<string, any>;
+    localOnly: string[];
+    remoteOnly: any[];
+    /** Files adopted from a stale manifest entry: basename → that entry's key. */
+    renamedFrom: Map<string, string>;
+    /** Files barred from the create path this run, with the reason to report. */
+    refused: Map<string, string>;
+};
 /**
  * `config diff` for one block's test-case sidecar (#2769). A failed listing is
  * an OUTCOME the caller reports as "not compared" — the old helper returned
  * silently, so a block whose tests could not be fetched simply disappeared from
  * a report that still read as exhaustive.
  */
+export interface TestCaseDiffRow {
+    blockType: string;
+    blockKey: string;
+    slug: string;
+    status: string;
+    /** What a validation error or a degraded comparison has to say. */
+    hint?: string;
+    /** Attachments push would upload from this sidecar (#2880 behavior 19). */
+    attachmentUploads?: string[];
+    /** Managed attachments `push --prune` would delete (never a plain push). */
+    attachmentDeletions?: string[];
+}
 export declare function compareTestCasesForBlock(params: {
     client: ApiClient;
     appId: string;
@@ -1852,14 +2169,12 @@ export declare function compareTestCasesForBlock(params: {
     blockId: string;
     blockKey: string;
     configDir: string;
+    /** The manifest — identity, and the attachment hashes the plan reads. */
+    syncState?: SyncState | null;
+    lookupMaps?: TestCaseLookupMaps;
 }): Promise<{
     ok: true;
-    rows: Array<{
-        blockType: string;
-        blockKey: string;
-        slug: string;
-        status: string;
-    }>;
+    rows: TestCaseDiffRow[];
 } | {
     ok: false;
 }>;
@@ -1871,6 +2186,17 @@ export declare function compareTestCasesForBlock(params: {
  * on the way to it, pushing a test case that tested something else.
  */
 export declare function testCaseSidecarErrors(filePath: string, tomlData: any): string[];
+/**
+ * EVERY reason `config push` refuses one test-case sidecar (#2880 criterion 1).
+ *
+ * The four checks the push preflight ran inline: the document's shape, the keys
+ * the definition recognizes, the declared type of each value, and the sidecar's
+ * own authoring rules (#2769). Collected in one place because `config diff`
+ * runs the identical list — it used to run only the last of the four, so a
+ * sidecar with an unknown key or a mistyped ordinary field was reported Synced
+ * by the command whose whole promise is that a Synced file pushes.
+ */
+export declare function testCaseSidecarPreflightErrors(filePath: string, tomlData: any): string[];
 /** A managed test case whose authored file is gone (#2769). */
 export interface TestCaseDeletionCandidate {
     stateKey: string;
@@ -1880,6 +2206,13 @@ export interface TestCaseDeletionCandidate {
     slug: string;
     /** Absent when the case was never successfully created server-side. */
     id?: string;
+    /**
+     * The state entry — with a file still on disk — that holds this same id
+     * (#2896). Set when the missing file was RENAMED rather than deleted: the
+     * case is alive under another name, so the row is cleared and nothing is
+     * deleted server-side.
+     */
+    supersededBy?: string;
 }
 /** A managed attachment whose local file is gone (#2769). */
 export interface AttachmentDeletionCandidate extends TestCaseDeletionCandidate {