primitive-admin 1.0.53 → 1.0.55

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
@@ -37,9 +38,9 @@ export declare function computeExpandedContentHash(parsed: any): string;
  */
 export declare function shouldPushExpandedFile(parsed: any, storedHash: string | undefined): boolean;
 /**
- * Normalize a parsed workflow TOML object so that any of the five
- * serializer-emitted fields the *local* file omits are filled in with the
- * model default. Used by `diff` so a hand-authored workflow that omits e.g.
+ * Normalize a parsed workflow TOML object so that any of the
+ * serializer-emitted default fields the *local* file omits are filled in with
+ * the model default. Used by `diff` so a hand-authored workflow that omits e.g.
  * `perUserMaxRunning` compares equal to a server that defaulted it to 4
  * (the #1175 false-positive guard) — while a server value that was
  * *explicitly set* to a non-default (e.g. 8) still shows as Modified.
@@ -62,10 +63,190 @@ export declare function hashWorkflowTomlForDiff(parsed: any): string;
  * `getWorkflow` + active `getWorkflowConfig`), mirroring exactly what a fresh
  * `sync pull` would write to disk. Serializes via `serializeWorkflow`, parses
  * the resulting TOML (remote serialized TOML never carries `include`s, so a
- * plain `TOML.parse` is sufficient — no fragment path needed), then hashes
+ * plain `parseConfigToml` is sufficient — no fragment path needed), then hashes
  * 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).
+ *
+ * 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>;
+/**
+ * Translate the [auth] block of app.toml into app-settings fields (push
+ * 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
+ * native object form for `sync migrate-toml` (issue #1446).
+ *
+ * Purely local, no server fetch. Parses the raw source WITHOUT expanding
+ * fragment `include`s (so those directives survive the rewrite), swaps a
+ * JSON-string schema for its parsed object when it round-trips faithfully
+ * (`canEmitNative === null`), and re-serializes via `stringifyConfigToml`.
+ *
+ * Only rewrites when a field is actually converted: a file whose schemas are
+ * already native, absent, or un-representable (a `null` default) is returned
+ * with `changed: false` and its original bytes untouched — so migrate is
+ * idempotent and never reports a spurious migration or reformats a file it
+ * didn't need to touch.
+ */
+export declare function rewriteWorkflowSchemasToNative(rawToml: string, workflowKey?: string, log?: (message: string) => void): {
+    content: string;
+    changed: boolean;
+};
+export declare function serializeWorkflow(workflow: any, draft: any, configs: any[], logger?: (message: string) => void): string;
+export declare function serializeGroupTypeConfig(config: any, ruleSetIdToName: Map<string, string>): string;
 export declare function parseDatabaseTypeToml(tomlData: any): {
     typeConfig: any;
     operations: any[];
@@ -83,11 +264,6 @@ export declare function fetchAll<T>(listFn: (params: {
     items: T[];
     nextCursor?: string | null;
 }>, pageSize?: number, maxPages?: number): Promise<T[]>;
-/**
- * Safely parse a JSON field that may be a string or already an object.
- * TOML can parse inline tables as objects, so we need to handle both.
- */
-export declare function safeJsonParse(value: any): any;
 /**
  * Resolve a key-based rule set name reference to an ID.
  * Throws if the name cannot be resolved and throwOnMissing is true.
@@ -141,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 {};