primitive-admin 1.1.0-alpha.8 → 1.1.0-alpha.80

package/dist/src/lib/function-sync.d.ts

@@ -0,0 +1,263 @@
+/**
+ * `functions/<key>.toml` on the wire and back (#3179, project
+ * `server-functions`).
+ *
+ * A function is the one configuration object whose file is not its whole
+ * authored surface: the TOML states the gate, the entry and the limits, and the
+ * TypeScript the entry reaches is the rest of it. `config push` therefore sends
+ * TWO things — a header (create/update) and an immutable config VERSION
+ * carrying the authored TOML bytes, every source file and the built bundle —
+ * and `config pull` writes both halves back.
+ *
+ * ── The envelope hash is the shared answer to "changed?" ──────────────────
+ *
+ * The server decides whether a push is a no-op on `envelopeHash` (sha256 over
+ * the TOML bytes, the sources and the bundle), because a comment-only or
+ * CRLF-only edit leaves the BUNDLE identical and must still make a version
+ * (F-003). The CLI computes the same number to decide whether to make the call
+ * at all, through `function-bundle.ts`'s copy of the server's canonical
+ * encoding. If those two encodings ever drift, one side re-pushes forever and
+ * the other silently drops an edit — `function-bundle-3179.test.ts` pins them
+ * against each other.
+ *
+ * ── Pull writes bytes ────────────────────────────────────────────────────
+ *
+ * Canonical re-serialization cannot preserve comments, key order or line
+ * endings, so the envelope stores the AUTHORED bytes and pull writes those
+ * (F-009). It also never trusts a stored path: the files it writes are named by
+ * the server, so a path that normalizes outside the tree — or into
+ * `node_modules`, which is never authored source — is refused rather than
+ * written to a developer's disk. The lexical rules cannot see a symlinked
+ * directory inside the tree, so the write step resolves the real path one last
+ * time and refuses a destination that lands outside the real root.
+ */
+import { type FunctionMode, type TriggerDeclaration } from "./generated-config-surfaces.js";
+import { type FunctionManifest as CollectedManifest } from "./function-collect.js";
+/**
+ * Collect one function's manifest, or answer from this command's memo.
+ *
+ * `FunctionCollectError` is translated to the push loop's one failure class by
+ * the callers, so a collect failure reads like any other build failure for
+ * that function and lands nothing.
+ */
+export declare function collectManifestForBundle(options: {
+    configDir: string;
+    entry: string;
+    functionKey: string;
+    contentHash: string;
+    /** The built bundle's source, for the static scan (#3279). */
+    bundle?: string;
+}): Promise<CollectedManifest>;
+/**
+ * The server's own `[function.triggers.*]` rules, applied to a parsed
+ * `[function]` table, with "nothing declared" spelled as null so a caller can
+ * skip the work.
+ *
+ * `normalizeTriggerDeclaration` comes from `generated-config-surfaces.ts` —
+ * `src/config-surface/trigger-declaration.ts` vendored verbatim. Until #3320
+ * the CLI ran a hand-written restatement of those rules
+ * (`cli/src/lib/function-triggers.ts`), kept in step only by a paired-fixture
+ * test; the artifact's `--check` makes drift a build failure instead.
+ *
+ * One check is the CLI's OWN and is deliberately not on that path: the cron
+ * expression's field count. The authority for cron grammar is the server's
+ * `src/cron-parser.ts` (`parseCron`, run at the push boundary), which the
+ * declaration rules never call — so this is a shape precheck that turns the
+ * commonest typo into a named local error, not a second copy of a rule.
+ */
+export declare function normalizeFunctionTriggers(functionTable: any, options?: {
+    mode?: FunctionMode;
+}): TriggerDeclaration | null;
+export interface FunctionConfigPush {
+    entry: string;
+    /** base64 of the authored `functions/<key>.toml` bytes. */
+    toml: string;
+    sources: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** base64 of the built bundle. */
+    bundle: string;
+    contentHash: string;
+    /**
+     * base64 of the collected query manifest JSON (#3187). Part of the envelope,
+     * so it is part of the version's identity.
+     */
+    manifest: string | null;
+    /** The number BOTH sides compare to decide "is this a no-op?". */
+    envelopeHash: string;
+    /** `mode = "request" | "task"` (#3281), resolved from the file's two spellings. */
+    mode: FunctionMode;
+    /**
+     * The same resolution as `mode`, in the alias's spelling: a new CLI against
+     * a server that predates `mode` still pushes a task function as a task.
+     */
+    durable: boolean;
+    limits?: Record<string, unknown>;
+}
+/**
+ * Resolve the file's mode — `mode`, its alias `durable`, or neither — through
+ * the ONE vendored rule (#3281). A disagreement or an unknown word is a
+ * `FunctionBuildError` naming the function, like every other preflight
+ * refusal, so nothing is built or sent for that file.
+ */
+export declare function resolveFunctionMode(functionKey: string, table: any): FunctionMode;
+/**
+ * Everything about one `functions/<key>.toml` that `config push` can decide
+ * from the file alone (#3320).
+ *
+ * This is the seam the issue is about. These checks used to run inside the
+ * APPLY loop, so a `durable = true` beside a webhook block — or a missing
+ * `entry`, or a signed scheme with no `signingSecret` — was raised after app
+ * settings, vars, integrations, webhooks, cron triggers and database types had
+ * already been written, while the command's own framing promised that a
+ * refusal meant nothing was applied. Running them in the front-loaded pass
+ * (#976) makes that framing true for this class of error.
+ *
+ * Every rule here is the SERVER's, reached through the generated surface
+ * artifact (#3320 part 0), not a local imitation of it. What is deliberately
+ * absent is app-state-dependent by construction: whether the referenced secret
+ * exists, whether the scheme's `config` is valid under this environment's JWKS
+ * policy, per-app caps, key collisions, archived tombstones. A local guess at
+ * any of those would be a preflight that gives a false all-clear.
+ *
+ * Returns the messages the apply loop would have raised, verbatim — so the
+ * author reads the same sentence wherever it reaches them, and `config diff`
+ * can report it under Invalid (#2880 symmetry).
+ */
+export declare function functionTomlPreflightErrors(options: {
+    filePath: string;
+    functionKey: string;
+    /** The already-parsed document, so the file is read once. */
+    tomlData: any;
+}): string[];
+/**
+ * Build everything the config-version route needs for one function file.
+ *
+ * Throws `FunctionBuildError` for a missing `entry`, a missing entry file, a
+ * build error, or an import that escapes the config tree — one class, so the
+ * push loop has one thing to report and pushes nothing for that function.
+ *
+ * The file-decidable checks are `functionTomlPreflightErrors`', kept here as
+ * defense in depth (#3179's dual-validation shape): `config push` runs them in
+ * its preflight now, but `functions` commands and a direct caller reach this
+ * function without one.
+ */
+export declare function buildFunctionConfigPush(options: {
+    configDir: string;
+    functionKey: string;
+    /** Absolute path of `functions/<key>.toml`. */
+    filePath: string;
+    /** The already-parsed document, so the file is read once. */
+    tomlData: any;
+}): Promise<FunctionConfigPush>;
+/**
+ * The create body. `functionKey` is attached here rather than spread from the
+ * table: the identity comes from the file name, exactly as it does for every
+ * other keyed type.
+ */
+export declare function buildFunctionCreatePayload(functionKey: string, table: any): Record<string, any>;
+/**
+ * The update body. The key is NOT re-sent — it is the function's claim on the
+ * app's single key namespace and the URL already names the row — and `status`
+ * is server-owned on the sixth carrying type as on the other five.
+ *
+ * #3317 — the schemas are TOML-owned on exactly the terms `description` is
+ * (#1567), which is what prompts have sent since then: the update handler
+ * preserves a field the body omits, so dropping the key would leave a schema
+ * live that the file no longer declares, and the comparison — which reads an
+ * absent schema as `null` — would report that difference again on every run.
+ * Removing `[function.inputSchema]` clears it, and the next diff is Synced.
+ */
+export declare function buildFunctionUpdatePayload(table: any): Record<string, any>;
+/** The version-carried keys, as the config-version row holds them. */
+export interface ActiveFunctionVersion {
+    entry?: string;
+    /** #3281 — serialized beside `durable` by a server that knows the word. */
+    mode?: string;
+    /** The stored column; the only thing an older server serializes. */
+    durable?: boolean;
+    /** JSON string on the row; an object is accepted too. */
+    limits?: unknown;
+    /** #3182 — the capabilities the server derived from the authored TOML. */
+    capabilities?: string[];
+}
+/**
+ * The canonical TOML for a function with no stored authored bytes — a function
+ * created through the API that has never had code pushed. When bytes exist,
+ * pull writes THOSE; this is the fallback that still produces a pushable file.
+ */
+export declare function serializeFunction(record: any, active?: ActiveFunctionVersion, log?: (message: string) => void): string;
+/**
+ * The mode a server's config-version row is in, whichever of the two fields
+ * this server serializes: `mode` since #3281, `durable` before it.
+ */
+export declare function activeVersionMode(active?: ActiveFunctionVersion | null): FunctionMode;
+/**
+ * The entity both sides of `config diff` are projected onto: the header's
+ * authored fields plus the keys the VERSION carries. Stated once so a
+ * local file and a server record cannot be read into different shapes.
+ *
+ * Text the server rewrites on the way in is read the same way it will come
+ * back (the DSO-003 rule the webhook comparator states): `access` is stored
+ * trimmed and `entry` normalized, so an authored value that differs only in
+ * that respect is not permanent drift.
+ */
+export declare function functionDiffEntity(tomlData: any): Record<string, any>;
+export interface FunctionPullFile {
+    /** Tree-relative, POSIX. */
+    relative: string;
+    absolute: string;
+    content: Buffer;
+}
+export interface FunctionPullPlan {
+    configDir: string;
+    functionKey: string;
+    files: FunctionPullFile[];
+    /** The source paths written, for the sync-state record prune reads. */
+    sourcePaths: string[];
+    /** One line per stored path this pull refused to write. */
+    refusals: string[];
+}
+/**
+ * Why a stored source path may not be written, or null.
+ *
+ * The same rule the server applies on the way in, applied again on the way out:
+ * the file is written to a developer's disk from a path the SERVER chose, so a
+ * second check here is the one that matters.
+ */
+export declare function unsafePulledPath(path: string): string | null;
+/**
+ * Plan the files `config pull` writes for one function: the authored TOML at
+ * `functions/<key>.toml`, and each stored source at its own path.
+ *
+ * Pure — the caller applies it — so the refusal rules are testable without a
+ * server and without touching a disk.
+ */
+export declare function planFunctionPull(options: {
+    configDir: string;
+    functionKey: string;
+    envelope: {
+        entry?: string;
+        toml?: string;
+        sources?: Array<{
+            path: string;
+            content: string;
+        }>;
+    };
+}): FunctionPullPlan;
+/** What one `applyFunctionPull` actually did. */
+export interface FunctionPullOutcome {
+    /** The source paths written — what the sync state records for prune. */
+    writtenSources: string[];
+    /** One line per file the write step refused. */
+    refusals: string[];
+}
+/**
+ * Write a plan's files, creating the directories they need.
+ *
+ * Returns what was written and what was refused; a refusal is reported by the
+ * caller and keeps the file out of the sync state, so prune never claims to
+ * own a path this pull did not write.
+ */
+export declare function applyFunctionPull(plan: FunctionPullPlan): FunctionPullOutcome;