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

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

@@ -784,6 +784,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 +1134,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 +1182,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 +1200,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 +1254,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 +1268,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 +1314,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 +1369,30 @@ 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).
+     *
+     * The types #2731 converted leave it off: for them a never-synced file
+     * differing from a same-named live entity IS the conflict they report, and
+     * that contract is unchanged.
+     */
+    adoptsUntrackedByKey?: boolean;
 }): PushGateOutcome;
 /**
  * The identity a file may leave to its name, written back into the parsed
@@ -1818,6 +1976,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 +2001,53 @@ export declare function pushTestCasesForBlock(params: {
     skipped: number;
 }>;
 /**
- * Classify one block's sidecar against the server's test-case names (#2769).
+ * Which live test case each sidecar manages (#2880 behavior 16).
  *
- * 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.
+ * The manifest id comes FIRST. A test case's slug is derived from its name, so
+ * matching on the slug alone made a rename — in either direction — read as a
+ * new local file plus a removable remote case: diff showed two rows for one
+ * case, and push created a duplicate. `entities.testCases[stateKey].id` is
+ * stable across every rename, so it is the identity, and the slug is only how
+ * a sidecar the manifest has never seen is ADOPTED.
+ *
+ * Adoption derives its slugs exactly the way pull writes them — same slugify,
+ * same collision suffixes, same listing order — so a `<slug>-2.toml` on disk IS
+ * the second colliding name and is paired with it.
+ *
+ * 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;
+    }> | undefined;
+}): {
+    bySlug: Map<string, any>;
+    localOnly: string[];
+    remoteOnly: any[];
+};
 /**
  * `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 +2055,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 +2072,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;