primitive-admin 1.1.0-alpha.46 → 1.1.0-alpha.48

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

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { ApiClient } from "../lib/api-client.js";
+import { type PresenceOutcome } from "../lib/sync-resource-types.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
@@ -66,34 +67,164 @@ export declare function hashWorkflowTomlForDiff(parsed: any): string;
  * through `hashWorkflowTomlForDiff` so it lines up with the local-file hash.
  */
 export declare function hashRemoteWorkflowForDiff(workflow: any, draft: any, configs: any[]): string;
+export interface ParsedAuthSettings {
+    settings: Record<string, any>;
+    warnings: string[];
+}
 /**
  * Build the [auth] block of app.toml from server settings (pull direction).
  *
- * Apple/OTP fields round-trip alongside the legacy google/passkey/magic-link
- * keys. Two asymmetries are handled deliberately:
- *  - `appleSignInEnabled` comes back as `boolean | null`; smol-toml throws on
- *    null, so an unset value (null) is omitted rather than written.
- *  - `appleAudiences` is omitted when empty. An empty array and an omitted key
- *    both mean "no audiences" (the server normalizes [] -> null), so omitting
- *    an empty list on pull is not lossy.
+ * Thin wrapper over the shared field descriptor
+ * (`cli/src/lib/app-settings-descriptor.ts`), which now owns the [auth] field
+ * set that `AUTH_BOOLEAN_KEYS`/`RECOGNIZED_AUTH_KEYS` used to hard-code. The
+ * descriptor drives all four sections in one place, so pull, push, and the
+ * unrecognized-key warning can never drift apart. `googleClientSecret` is a
+ * secret descriptor entry and is never written.
  */
 export declare function serializeAuthBlock(settings: any): Record<string, any>;
-export interface ParsedAuthSettings {
-    settings: Record<string, any>;
-    warnings: string[];
-}
 /**
  * Translate the [auth] block of app.toml into app-settings fields (push
- * direction).
- *
- * Only keys actually present in the TOML are forwarded — an omitted key is left
- * untouched so it never overwrites server state (e.g. flipping a previously-true
- * flag to false). An explicit value, including `false`, is forwarded as-is.
- * `appleAudiences = []` is forwarded too; the server normalizes [] -> null
- * ("no audiences"). Keys outside RECOGNIZED_AUTH_KEYS produce a warning rather
- * than a hard error, so a typo or a future key doesn't silently drop.
+ * direction). Kept as a focused helper over the shared descriptor; the full
+ * push path uses `parseTomlToAppSettings` for every section. Only keys present
+ * in the TOML are forwarded, so an omitted key never overwrites server state.
+ * Descriptor errors (a secret key, a type mismatch) are surfaced alongside the
+ * unrecognized-key warnings.
  */
 export declare function parseAppAuthSettings(auth: Record<string, any>): ParsedAuthSettings;
+type VarEntity = {
+    modifiedAt: string;
+    contentHash?: string;
+};
+/**
+ * Decide whether `sync pull` should (over)write `vars.toml`, given the outcome
+ * of fetching the app's config vars.
+ *
+ * The distinction that matters (issue #1423 review): a SUCCESSFUL fetch that
+ * returns zero vars is safe to write — the comment-only file is the intended
+ * empty state. A FAILED fetch (transient 401/500/network) must NOT write,
+ * because `serializeVars([])` would clobber a good local `vars.toml` with a
+ * comment-only file while the pull otherwise reports success. On failure we
+ * keep the prior manifest entries so the untouched file and the sync state stay
+ * consistent.
+ *
+ * Pure and side-effect-free (the caller owns the actual `writeFileSync`) so the
+ * clobber guard is unit-testable without a live server.
+ */
+export declare function planVarsPull(outcome: {
+    ok: true;
+    vars: any[];
+} | {
+    ok: false;
+}, priorVars?: Record<string, VarEntity>): {
+    write: boolean;
+    content: string | null;
+    varEntities: Record<string, VarEntity>;
+};
+/**
+ * Validate a parsed `vars.toml` table against the same key/value constraints
+ * the server enforces (key format, string type, non-empty, size cap) plus the
+ * aggregate per-app var-count cap. Returns a list of human-readable errors
+ * (empty when valid).
+ *
+ * Run in `sync push`'s up-front preflight pass (issue #1423 review) so an
+ * invalid entry — or a file that would exceed the server's `MAX_VARS_PER_APP`
+ * cap — aborts BEFORE any mutation is applied. Validating only individual
+ * entries let a 101-entry file create/update many vars before the server
+ * rejected a later create at the cap, leaving a partial push (issue #1423
+ * review pass 3). Pure and side-effect-free so it's unit-testable without a
+ * live server.
+ */
+export declare function validateVarsFile(parsedVars: Record<string, unknown>): string[];
+/**
+ * Plan the config-var writes a `sync push` should make, detecting concurrent
+ * remote edits before overwriting them (issue #1423 review).
+ *
+ * This is the client-side half of a two-layer concurrency guard. The vars
+ * PUT/DELETE endpoints now honor an `expectedModifiedAt` precondition (issue
+ * #1423 review r-2 P1) and raise a `ConflictError` when the server row changed
+ * since the caller's snapshot — the atomic, server-side check every other
+ * synced entity relies on. This function is the fast fail-before-mutate layer:
+ * it compares the recorded baseline against the current remote snapshot and, for
+ * a var whose remote value has drifted from what we last synced, reports a
+ * conflict (fed into the same `conflicts[]` accumulator the other entities use)
+ * before any write is attempted. A var tracked at the baseline but absent from
+ * the remote snapshot (deleted remotely while edited locally) is remote drift
+ * too, and also reported as a conflict rather than silently recreated.
+ * Conversely, a var removed locally that is already absent remotely is NOT
+ * planned for deletion — its desired (absent) state is already met, so a DELETE
+ * would 404 and fail the push. The same drift check guards deletions: a var
+ * removed locally whose remote value no longer matches the baseline was edited
+ * remotely since the last sync, and deleting it would silently discard that
+ * edit — reported as a conflict instead. `force` skips the conflict guard,
+ * matching `sync push --force` for every other entity.
+ *
+ * Pure and side-effect-free (the caller owns the API calls and sync-state
+ * updates) so the guard is unit-testable without a live server. Assumes
+ * `parsedVars` has already passed `validateVarsFile` (values are strings). The
+ * caller normally fails the push closed when the remote snapshot can't be
+ * fetched, but under `--force` it falls back to an empty snapshot and sets
+ * `snapshotUnavailable` — which keeps removed-key deletions in the plan (they'd
+ * otherwise be mistaken for already-deleted and dropped) and leans on the apply
+ * loop's idempotent 404 handling (issue #1423 review r-2 P2).
+ */
+export declare function planVarsPush(parsedVars: Record<string, string>, baseline: Record<string, VarEntity> | undefined, remoteVars: Array<{
+    key: string;
+    value?: string;
+    updatedAt?: string;
+}>, options?: {
+    force?: boolean;
+    snapshotUnavailable?: boolean;
+}): {
+    upserts: Array<{
+        action: "create" | "update";
+        key: string;
+        value: string;
+        valueHash: string;
+    }>;
+    deletions: string[];
+    conflicts: Array<{
+        key: string;
+        serverModifiedAt: string;
+        localModifiedAt: string;
+    }>;
+    skippedCount: number;
+};
+/**
+ * Compute the number of config vars the server would hold after a push plan
+ * is applied (issue #1423 review pass 5). Validating only the local file's
+ * entry count misses remote-only vars: 95 local entries plus 10 vars that
+ * exist only on the server passes a local-count check, and the creates then
+ * exceed the server's cap mid-push, after earlier writes were already
+ * applied. Counted from the fetched remote snapshot: planned deletions remove
+ * keys that exist remotely (the plan already omits deletes for absent keys),
+ * and only upserts whose key is NOT already on the server add to the total.
+ * Conflicted keys are not mutated, so they contribute nothing beyond their
+ * current remote presence. Pure and side-effect-free so it's unit-testable
+ * without a live server.
+ */
+export declare function countVarsAfterPush(remoteVars: Array<{
+    key: string;
+}>, plan: {
+    upserts: Array<{
+        key: string;
+    }>;
+    deletions: string[];
+}): number;
+/**
+ * Compute the `sync diff` rows for config vars (issue #1423 review). Before
+ * this, `sync diff` ignored vars entirely, so an add/remove/value-drift between
+ * the local `vars.toml` and the server read as no difference. Value-aware: a
+ * var present on both sides whose value differs is reported as `modified`
+ * (framed like the other content-aware entities — `sync pull` would rewrite the
+ * local value). Pure and side-effect-free so it's unit-testable without a live
+ * server.
+ */
+export declare function diffVars(localVars: Map<string, string>, remoteVars: Map<string, string>): Array<{
+    type: "var";
+    key: string;
+    status: string;
+    hint?: string;
+}>;
 export declare function serializeWebhook(webhook: any): string;
 /**
  * Rewrite a workflow TOML file's string-form `inputSchema` / `outputSchema` to
@@ -186,5 +317,24 @@ export declare function pullScripts(client: ApiClient, appId: string, configDir:
         contentHash?: string;
     }>;
     count: number;
+    /**
+     * Which scripts the server listed, for the #1659 prune pass. `ok: false` when
+     * the listing failed (an older server without the route, or a transient
+     * error) or when any per-script fetch failed — in either case this pull's
+     * picture of the type is incomplete and must not drive deletions. Scripts
+     * skipped for having no active config are still *present*, so their keys stay
+     * in the set and their local `.rhai` survives.
+     */
+    presence: PresenceOutcome;
+    /**
+     * Whether the script LISTING succeeded. Distinct from `presence`: a failed
+     * per-script fetch blocks pruning but still leaves the other scripts written,
+     * so their fresh state entries must be kept. Only a failed listing means
+     * nothing was written and the prior state slot should be preserved whole.
+     */
+    listOk: boolean;
+    /** Names the server listed, empty when the listing failed. */
+    serverKeys: string[];
 }>;
 export declare function registerSyncCommands(program: Command): void;
+export {};