primitive-admin 1.1.0-alpha.9 → 1.1.0

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

@@ -0,0 +1,459 @@
+/**
+ * `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 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.
+ *
+ * Nothing here is the CLI's own any more. Until #3376 this function added a
+ * five-field count check of its own, justified as "not a second copy of a
+ * rule" precisely because the declaration path never called `parseCron`. It
+ * calls it now — `functionTomlPreflightErrors` runs `checkCronTriggerEntry`,
+ * which is the server's grammar and the server's sentence — so the precheck
+ * was exactly the duplicate this project exists to remove, and went with the
+ * justification.
+ */
+export declare function normalizeFunctionTriggers(functionTable: any): 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;
+    limits?: Record<string, unknown>;
+    /**
+     * base64 of the project's authored `models/models.toml` bytes, or absent —
+     * #3455. Inside the envelope and covered by `envelopeHash`, so the version
+     * that is running carries the document schema its code was typed against and
+     * can seed a model's metadata on a function's first write.
+     */
+    documentSchema?: string;
+}
+/**
+ * The retired runtime keys a `functions/<key>.toml` still carries — #3482.
+ *
+ * NOT a refusal. Through phase 4 `mode`, `durable` and a cron entry's `mode`
+ * are accepted and ignored, with one warning each and every other key of the
+ * file applied; phase 5 (#3188) refuses them. The sentences come from the one
+ * vendored scanner, so the warning `config push` prints is the sentence the
+ * server answers with.
+ */
+export declare function functionTomlIgnoredKeyWarnings(options: {
+    functionKey: string;
+    tomlData: any;
+}): string[];
+/**
+ * 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 per-function failure when a server DID NOT retain the document schema it
+ * was sent — #3455 (D3455-010), criterion 7.
+ *
+ * The server builds its envelope from explicit known fields
+ * (`server-functions-controller.ts`) and answers the `envelopeHash` it stored.
+ * A server that predates this change drops `documentSchema` silently: it
+ * answers 200, the CLI reports the function pushed, first-writer seeding never
+ * works, and every later `config diff` reads Modified for a reason nobody can
+ * see. Comparing the hash it stored with the one this CLI built is the cheap
+ * acknowledgment that closes that.
+ *
+ * Gated on having SENT a schema, which is exactly what criterion 7 says
+ * ("reported successful only when the server retained the schema it was
+ * sent"): with nothing sent there is nothing to retain, and naming the
+ * document schema in a mismatch caused by something else would send an
+ * operator to the wrong place. A response with no `envelopeHash` at all is not
+ * judged — silence is not a disagreement.
+ */
+export declare function documentSchemaRetentionFailure(input: {
+    /** Whether this push carried a `documentSchema`. */
+    sentDocumentSchema: boolean;
+    /** The hash this CLI built. */
+    builtEnvelopeHash: string;
+    /** The hash the push response reported, if any. */
+    storedEnvelopeHash: unknown;
+}): string | null;
+/**
+ * What one version's `documentSchemaModels` says about whether this push drops
+ * a document schema — #3455 (D3455-004), criterion 7's visible half.
+ *
+ * Three answers, and keeping them apart is the whole point:
+ *
+ *   - an ARRAY — this version seeds these models, and a push from a tree that
+ *     resolved no schema takes that away: `drops`, and there is nothing more
+ *     to ask, because one sentence per run is what the operator needs;
+ *   - `null` — this version was pushed without a schema, so it has nothing to
+ *     lose. That is an answer about ONE function and says nothing about the
+ *     rest of the tree: `none`, keep asking;
+ *   - anything else, `undefined` included — the server does not answer this
+ *     question (it predates the field). That IS a property of the run, so
+ *     `unsupported` settles it rather than spending a read per function on a
+ *     server that will never say anything.
+ */
+export type DocumentSchemaDropAnswer = {
+    outcome: "drops";
+    message: string;
+} | {
+    outcome: "none";
+} | {
+    outcome: "unsupported";
+};
+export declare function documentSchemaDropAnswer(documentSchemaModels: unknown): DocumentSchemaDropAnswer;
+/**
+ * Says ONCE — for the whole push, not once per function — that this push drops
+ * a document schema a running version carries (#3455, D3455-004).
+ *
+ * Removing `models/models.toml` and its generated tree copy is a legitimate
+ * edit, so it is a warning and not a refusal; but it turns first-writer seeding
+ * off for every document these functions touch, and that must not be silent.
+ *
+ * The state this holds is "has the run been told yet", and the rule is that
+ * only an ANSWER settles it. A function whose active version carries no schema
+ * has told us nothing about its siblings, so the next function is still asked —
+ * getting that backwards silences a real drop whenever a schema-less function
+ * happens to be pushed first, which is the order nothing in the tree controls.
+ * The model names live inside the version's envelope rather than on its row,
+ * which is why this is a read and not a field of the listing already in hand.
+ */
+export declare function createDocumentSchemaDropWarner(deps: {
+    /** Whether the tree resolved a schema for this push: if so, nothing drops. */
+    treeCarriesSchema: boolean;
+    /** Reads one version's admin detail. */
+    readConfig: (functionId: string, configId: string) => Promise<any>;
+    /** Where the sentence goes. */
+    warn: (message: string) => void;
+}): (functionId: string, activeConfigId: string | undefined) => Promise<void>;
+/**
+ * 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;
+    /** 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 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>;
+/**
+ * Remove `mode`, `durable` and every cron entry's `mode` from authored TOML,
+ * preserving every other byte.
+ *
+ * The issue says `config pull` never writes them, and the pull plan writes the
+ * version's AUTHORED bytes verbatim — so without this a tree pulled from a
+ * version pushed before the retirement would carry keys phase 5 refuses, and
+ * could not be pushed again.
+ *
+ * ── Three jobs, kept apart ────────────────────────────────────────────────
+ *
+ * The PARSE decides what is removed and what is reported: `ignoredFunctionKeys`
+ * is the very scanner `config push` warns with, so what a pull takes out is
+ * exactly what a push said it was ignoring, whatever spelling the author used.
+ * TOML has several — `["function"]`, `function . mode = …`, an inline
+ * `triggers.cron = [ { mode = … } ]` — and a scan that reads the SOURCE has to
+ * know every one of them or it silently leaves a key behind (CR3482-002).
+ *
+ * The LINE EDIT decides how the bytes change, and is the path every real file
+ * takes. A re-serialization would rewrite every comment, blank line, quoting
+ * style and key order in a file a human wrote, so a pull would report a hundred
+ * changes to make three. Here exactly the matched assignments go and nothing
+ * else moves.
+ *
+ * The VERIFICATION decides whether the line edit was good enough, by parsing
+ * what it produced: the result must parse, must carry no retired key, and must
+ * otherwise say precisely what the file said. That is the contract stated as a
+ * check rather than as a hope — and it is what makes the line edit safe to keep
+ * narrow. A file it cannot reach by whole lines (a retired key sharing its line
+ * with keys that must survive, inside an inline table) falls back to a
+ * serialized rewrite, which is reported, because a pulled file that still
+ * carries the key — or one that no longer parses (CR3482-001) — is worse than a
+ * reformatted one.
+ *
+ * Returns the text and one line per removal, so the caller can report what it
+ * did rather than silently editing a developer's file.
+ */
+export declare function stripRetiredFunctionKeys(toml: string, label?: string): {
+    toml: string;
+    removals: string[];
+};
+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[];
+    /**
+     * One line per EDIT this pull made to the authored bytes on the way out —
+     * #3482. Today exactly the retired runtime keys it removed. Not a refusal:
+     * the file IS written, and this is what says so.
+     */
+    notes: string[];
+    /**
+     * Tree-relative files this pull DELETES — #3455. Today exactly one: a stale
+     * generated document-schema copy left by a version that carried a document
+     * schema, when the version being pulled carries none. Without the removal
+     * the tree would keep rebuilding an envelope with a schema the active
+     * version does not have, and `config diff` would read Modified for ever.
+     */
+    removals: Array<{
+        relative: string;
+        absolute: 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;
+        }>;
+        /** base64 of the version's document schema, absent when it has none (#3455). */
+        documentSchema?: string | null;
+    };
+    /**
+     * Whether this plan decides the tree's generated schema copy — CR3455-001.
+     *
+     * The copy is ONE file the whole tree resolves through, so a pull of several
+     * functions may not let each one decide it in turn: the last function
+     * applied would overwrite or DELETE the copy the earlier ones needed, and a
+     * repush from that tree would drop the schema a version really carries. A
+     * pull of many functions therefore passes `false` here and settles the copy
+     * once, through {@link planDocumentSchemaPull}. Defaults to true, which is
+     * the right answer for a plan that is the whole pull.
+     */
+    includeDocumentSchema?: boolean;
+}): FunctionPullPlan;
+/** One pulled function's answer to "does your version carry a schema?" */
+export interface PulledFunctionSchema {
+    functionKey: string;
+    /** base64 of the version's document schema, null when it carries none. */
+    documentSchema: string | null;
+}
+/** What a pull does about the tree's ONE generated schema copy. */
+export interface DocumentSchemaPullPlan {
+    configDir: string;
+    files: FunctionPullFile[];
+    removals: Array<{
+        relative: string;
+        absolute: string;
+    }>;
+    /** One line per thing the tree cannot say for every version it pulled. */
+    warnings: string[];
+}
+/**
+ * The tree's generated document-schema copy, decided ONCE for a whole pull —
+ * CR3455-001.
+ *
+ * Push and diff resolve the copy tree-wide (`resolveDocumentSchema`), so the
+ * tree can hold exactly one schema however many functions it has. Deciding it
+ * per function meant the last function applied won: a version carrying no
+ * schema DELETED the copy a schema-bearing sibling had just written, the
+ * sibling then diffed Modified for ever, and a repush from that tree dropped
+ * the schema — the one outcome D3455-009 exists to prevent.
+ *
+ * The rules, and what each is protecting:
+ *
+ *  - Any pulled version carrying a schema WINS over one carrying none. The
+ *    copy is a fallback consulted only when the project has no
+ *    `models/models.toml`; keeping it is what lets a fresh pull re-push.
+ *  - The copy is removed only when the pull read EVERY active function and
+ *    none carried a schema. A selective pull has not learned anything about
+ *    the functions it did not read, and deleting on that evidence would take
+ *    the schema away from a version that still pins one.
+ *  - Versions that disagree are reported rather than silently reconciled. One
+ *    file cannot reproduce two envelopes, so an operator is told which
+ *    function the tree now speaks for and which ones will read Modified until
+ *    they are pushed again.
+ */
+export declare function planDocumentSchemaPull(options: {
+    configDir: string;
+    functions: readonly PulledFunctionSchema[];
+    /** True when the pull read every active function the app has. */
+    coversEveryFunction: boolean;
+}): DocumentSchemaPullPlan;
+/** 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: Pick<FunctionPullPlan, "configDir" | "files" | "removals"> & {
+    sourcePaths?: readonly string[];
+}): FunctionPullOutcome;