primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/function-db-types.js

@@ -0,0 +1,870 @@
+/**
+ * The typed database handle's generated declarations — #3182 phase 4.
+ *
+ * The intent settles what the handle is before unified-schemas: "generated at
+ * push time from the database type's TOML schema (js-bao's
+ * `loadSchemaFromTomlString`; not the client's runtime Yjs discovery): model
+ * names and field types in phase 2". So this is a THIRD renderer over the same
+ * `describeDbType` IR the TypeScript and Swift client generators already share
+ * — not a second parser and not a second idea of what a model is. Inline
+ * filter typing waits for unified-schemas, as the intent says.
+ *
+ * ── Why these files, in `functions/` ─────────────────────────────────────
+ *
+ * A generated declaration nothing loads is decoration (D3182-006). Function
+ * sources live under an environment- and app-specific config-tree path, the
+ * CLI's esbuild step never typechecks, and a project's own `tsconfig.json`
+ * commonly includes only `src`. So `config push` writes, beside the sources it
+ * serves:
+ *
+ *   - `primitive-db-types.d.ts` — the app's database types, and the module
+ *     augmentation that binds them to `ctx.db`;
+ *   - `primitive-functions.d.ts` — the SDK's own types. The package is not on
+ *     npm yet, and even when it is, a config tree is not an npm project:
+ *     without this the bare `primitive-functions` specifier every function
+ *     imports would not resolve at all, and the augmentation would have
+ *     nothing to augment;
+ *   - `primitive-function-types.d.ts` (#3281, rendered by
+ *     `function-schema-codegen.ts`) — every function's `<Key>Input` and
+ *     `<Key>Output` from its declared schemas, and the `FunctionSchemas`
+ *     augmentation that types `defineFunction("<key>", handler)`;
+ *   - `primitive-document-types.d.ts` (#3281, rendered by
+ *     `function-document-types.ts`) — the project's document models from
+ *     `models/models.toml`, and the `DocumentSchemas` augmentation that types
+ *     `ctx.doc(documentId).model("<Model>")`; open when the project has none;
+ *   - `generated/<key>.generated.ts` (#3281, same renderer) — the per-key
+ *     CLIENT invoker, carrying every verb since #3482. Excluded from
+ *     the scaffolded program (it imports `js-bao-wss-client`), and written to
+ *     `-o <dir>` instead when `functions codegen` is told so;
+ *   - `tsconfig.json` — the wiring, so an editor and a bare `tsc` both see the
+ *     declarations with nothing for an author to configure.
+ *
+ * The `.d.ts` files and the invokers are GENERATED and rewritten on every
+ * push; an invoker whose TOML is gone is removed with it. The tsconfig
+ * is SCAFFOLDED once and then left to its author, because it is the file an
+ * author has a legitimate reason to adjust — with one exception: the two facts
+ * that make the wiring work at all (the `primitive-functions` path mapping and
+ * the declarations being in the program) are repaired when they are missing,
+ * so a tsconfig written by hand, or scaffolded before the #3209 rename, does
+ * not leave push reporting success over a program no compiler can load
+ * (SO3182-004). Everything else in the file is left exactly as written.
+ *
+ * None of the three is part of the pushed envelope: they are regenerated, not
+ * round-tripped, and the bundler never sees them (types are erased, and the
+ * tsconfig is not a module).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "fs";
+import { basename, dirname, join, relative, resolve, sep } from "path";
+import { parseConfigToml } from "./config-toml.js";
+import { FUNCTION_INVOKERS_DIR, FUNCTION_TYPES_DECLARATION_FILE, GENERATED_FILE_SUFFIX, functionSchemaSources, renderFunctionInvokers, renderFunctionSchemasDeclaration, } from "./function-schema-codegen.js";
+import { DOCUMENT_TYPES_DECLARATION_FILE, DOCUMENT_SCHEMA_TREE_FILE, resolveDocumentSchema, renderDocumentTypesDeclaration, } from "./function-document-types.js";
+import { AGENT_CLIENT_FILE_SUFFIX, PROMPT_TYPES_DECLARATION_FILE, promptSchemaSources, renderAgentClientFiles, renderPromptSchemasDeclaration, } from "./prompt-schema-codegen.js";
+import { describeDbType } from "./db-codegen/dbTypeIR.js";
+import { tsTypeForDbFieldType } from "./db-codegen/dbTsTypes.js";
+import { objectPropertyKey } from "./db-codegen/dbNaming.js";
+import { SDK_TYPES_SOURCE } from "./generated-sdk-types.js";
+export const DB_TYPES_DECLARATION_FILE = "primitive-db-types.d.ts";
+export const SDK_TYPES_FILE = "primitive-functions.d.ts";
+export const FUNCTIONS_TSCONFIG_FILE = "tsconfig.json";
+/**
+ * Every regenerated declaration a `functions/tsconfig.json` has to load, in
+ * the order the scaffold lists them (#3281, D3281-SO-004). The inspection
+ * requires each of these in an explicit `include`/`files` list — a tree that
+ * customized its list to name only the two #3182 wrote would otherwise
+ * generate the newer ones and never load them.
+ */
+export const REGENERATED_DECLARATIONS = [
+    DB_TYPES_DECLARATION_FILE,
+    SDK_TYPES_FILE,
+    FUNCTION_TYPES_DECLARATION_FILE,
+    DOCUMENT_TYPES_DECLARATION_FILE,
+    // #3330 — the prompt output types, from the tree's `prompts/*.toml`.
+    PROMPT_TYPES_DECLARATION_FILE,
+];
+/** The scaffold's exclusion for the client invokers (#3281). */
+export const GENERATED_EXCLUDE = `${FUNCTION_INVOKERS_DIR}/**`;
+const HEADER = `// GENERATED by \`primitive config push\` from database-type-configs/*.toml.
+// DO NOT EDIT — your changes are overwritten on the next push.
+//
+// It gives \`ctx.db(databaseId, "<type>").model("<Model>")\` the model names and
+// field types this app's database types declare. Inline filter typing arrives
+// with unified schemas; until then a filter is an ordinary object.
+//
+// A row a READ hands back also carries \`id: string\` — the record identity the
+// platform owns rather than the schema, added by the SDK's own row type, so it
+// is not repeated per model here whether or not a model declares one.
+`;
+function quote(value) {
+    return JSON.stringify(value);
+}
+/**
+ * A model or field name as a TYPE member key.
+ *
+ * Model and field names are whatever the TOML says — js-bao preserves them
+ * verbatim — so `Order-Item` and `first-name` are ordinary schemas and are not
+ * TypeScript identifiers. Emitting one raw makes the whole declaration a syntax
+ * error, which breaks the editor and `tsc` wiring for every OTHER type in the
+ * tree too. The client generators' own `objectPropertyKey` answers this,
+ * except that its `__proto__` case is a computed key — legal in an object
+ * literal, not in a type member — so that one is quoted instead.
+ */
+function memberKey(name) {
+    const key = objectPropertyKey(name);
+    return key.startsWith("[") ? quote(name) : key;
+}
+/** A TS string-literal union, or `string` when there is nothing to narrow to. */
+function fieldType(type, enumValues) {
+    if (type === "string" && Array.isArray(enumValues) && enumValues.length > 0) {
+        return enumValues.map((v) => quote(v)).join(" | ");
+    }
+    return tsTypeForDbFieldType(type);
+}
+/**
+ * The declaration for a whole config tree's database types.
+ *
+ * Sorted by type and by model so the bytes depend on the SCHEMAS and not on
+ * the order the files were read in — push rewrites this on every run, and
+ * unstable output would be a permanent diff in a developer's repository.
+ */
+export function renderDbTypesDeclaration(sources) {
+    const types = [...sources].sort((a, b) => a.databaseType < b.databaseType ? -1 : a.databaseType > b.databaseType ? 1 : 0);
+    const lines = [HEADER, "export interface PrimitiveDatabaseSchemas {"];
+    for (const source of types) {
+        let records = [];
+        try {
+            const ir = describeDbType({
+                databaseType: source.databaseType,
+                tomlPath: source.tomlPath,
+                tomlContent: source.tomlContent,
+            });
+            records = [...ir.records]
+                .sort((a, b) => (a.modelName < b.modelName ? -1 : 1))
+                .map((record) => {
+                const declared = new Set();
+                const members = [];
+                for (const field of record.fields) {
+                    declared.add(field.name);
+                    members.push(`      ${memberKey(field.name)}${field.required ? "" : "?"}: ${fieldType(field.type, field.enum)};`);
+                }
+                // Server-stamped fields exist on a read row but not on one a
+                // function just built, so they are optional — the same call the
+                // client renderer makes.
+                for (const stamped of [...ir.stampedFields].sort()) {
+                    if (declared.has(stamped))
+                        continue;
+                    declared.add(stamped);
+                    members.push(`      ${memberKey(stamped)}?: string;`);
+                }
+                return { modelName: record.modelName, members };
+            });
+        }
+        catch {
+            // A type whose TOML this renderer cannot describe contributes no models
+            // rather than failing the push: its own preflight reports the file, and
+            // an untyped handle is what a schemaless type gets anyway.
+            records = [];
+        }
+        if (records.length === 0) {
+            lines.push(`  ${quote(source.databaseType)}: {};`);
+            continue;
+        }
+        lines.push(`  ${quote(source.databaseType)}: {`);
+        for (const record of records) {
+            if (record.members.length === 0) {
+                lines.push(`    ${memberKey(record.modelName)}: Record<string, unknown>;`);
+                continue;
+            }
+            lines.push(`    ${memberKey(record.modelName)}: {`);
+            lines.push(...record.members);
+            lines.push(`    };`);
+        }
+        lines.push(`  };`);
+    }
+    lines.push("}");
+    lines.push("");
+    // The augmentation. Only emitted when there is something to bind: an empty
+    // one would claim the app has no database types, and `ctx.db` would stop
+    // accepting any type key at all rather than staying open.
+    if (types.length > 0) {
+        lines.push(`declare module "primitive-functions" {`);
+        lines.push(`  interface DatabaseSchemas extends PrimitiveDatabaseSchemas {}`);
+        lines.push(`}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/** The scaffolded compiler wiring. Written once; an author owns it after. */
+export function renderFunctionsTsconfig() {
+    return (JSON.stringify({
+        // Scaffolded by `primitive config push` (#3182). Yours to adjust — push
+        // writes it once and then leaves it alone. What it must keep doing is
+        // pointing `primitive-functions` at the generated declaration beside
+        // it, so
+        // your editor and `tsc` type your functions with no other setup.
+        compilerOptions: {
+            target: "ES2022",
+            module: "ESNext",
+            moduleResolution: "Bundler",
+            // A function runs in a Worker, so the globals it may use are the
+            // worker ones: `fetch`, `Response`, `URL`, `crypto`, `console`, the
+            // timers. `ES2022` alone typechecks the language and none of the
+            // runtime, so ordinary deployed code reports "Cannot find name
+            // 'fetch'" — which reads as broken types and is fixed by editing
+            // this file, the one thing the scaffold exists to avoid
+            // (F3182-003).
+            lib: ["ES2022", "WebWorker"],
+            strict: true,
+            noEmit: true,
+            skipLibCheck: true,
+            types: [],
+            paths: {
+                "primitive-functions": [`./${SDK_TYPES_FILE}`],
+            },
+        },
+        include: ["**/*.ts", ...REGENERATED_DECLARATIONS.map((file) => `./${file}`)],
+        // The client invokers (#3281) import `js-bao-wss-client`, which a
+        // config tree does not install: they are for the app's client code,
+        // and an editor program that swept them in would report every one of
+        // them as a broken import.
+        exclude: [GENERATED_EXCLUDE],
+    }, null, 2) + "\n");
+}
+/** The bare specifier every function imports, and the tsconfig must resolve. */
+export const SDK_MODULE_SPECIFIER = "primitive-functions";
+/** The include entry that covers every source AND both declarations. */
+const SOURCES_INCLUDE = "**/*.ts";
+/**
+ * A tsconfig's contents with `//` and block comments blanked out.
+ *
+ * A tsconfig is JSONC — comments are legal and common — and the difference
+ * matters twice: push must not reformat a commented file out from under its
+ * author, and it must still be able to READ one well enough to say whether the
+ * typed handle will load. Blanking rather than deleting keeps the text length
+ * (and so any offsets) intact; only `JSON.parse` ever sees the result.
+ */
+function stripJsonComments(text) {
+    let out = "";
+    let inString = false;
+    let escaped = false;
+    let inLine = false;
+    let inBlock = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        const next = text[i + 1];
+        if (inLine) {
+            if (ch === "\n") {
+                inLine = false;
+                out += ch;
+            }
+            else
+                out += " ";
+            continue;
+        }
+        if (inBlock) {
+            if (ch === "*" && next === "/") {
+                inBlock = false;
+                out += "  ";
+                i++;
+            }
+            else
+                out += ch === "\n" ? ch : " ";
+            continue;
+        }
+        if (inString) {
+            out += ch;
+            if (escaped)
+                escaped = false;
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            inLine = true;
+            out += " ";
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            inBlock = true;
+            out += " ";
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+function isGlobEntry(entry) {
+    return typeof entry === "string" && entry.includes("*");
+}
+function isDeclarationEntry(entry, file) {
+    return entry === `./${file}` || entry === file;
+}
+/** `"./**\/*.ts"` and `"**\/*.ts"` name the same set; read them the same way. */
+function normalizeEntry(entry) {
+    return entry.startsWith("./") ? entry.slice(2) : entry;
+}
+/**
+ * Does this `include` entry cover a `.ts` file sitting BESIDE the tsconfig —
+ * which is where every regenerated declaration goes?
+ *
+ * TypeScript matches a `.d.ts` file with a `*.ts` pattern, and both the
+ * top-level `"*.ts"` and the recursive `"**\/*.ts"` reach the directory's own
+ * files. Recognizing only the scaffold's literal `"**\/*.ts"` reported an
+ * author's equivalent glob as missing every declaration (CR3281-003).
+ */
+function coversDeclarations(entry) {
+    if (typeof entry !== "string")
+        return false;
+    const normalized = normalizeEntry(entry);
+    if (normalized === "**")
+        return true;
+    const slash = normalized.lastIndexOf("/");
+    const dir = slash < 0 ? "" : normalized.slice(0, slash + 1);
+    if (dir !== "" && dir !== "**/")
+        return false;
+    const leaf = normalized.slice(slash + 1);
+    return leaf === "*" || leaf === "*.ts" || leaf === "*.d.ts";
+}
+/**
+ * Does this `include` entry reach BELOW the tsconfig's own directory — and so
+ * sweep the generated client invokers into the program?
+ *
+ * Any `**` segment does, as does an entry that names the generated directory
+ * itself. A top-level `"*.ts"` does not, which is why this is a separate
+ * question from {@link coversDeclarations} (CR3281-003).
+ */
+function coversSubdirectories(entry) {
+    if (typeof entry !== "string")
+        return false;
+    const normalized = normalizeEntry(entry);
+    return (normalized === "**" ||
+        normalized.startsWith("**/") ||
+        normalized.includes("/**") ||
+        normalized.startsWith(`${FUNCTION_INVOKERS_DIR}/`));
+}
+function isSourceEntry(entry) {
+    if (typeof entry !== "string")
+        return false;
+    if (REGENERATED_DECLARATIONS.some((file) => isDeclarationEntry(entry, file))) {
+        return false;
+    }
+    return isGlobEntry(entry) || entry.endsWith(".ts");
+}
+/** Does an `exclude` list keep `generated/` out of the program? */
+function excludesGenerated(exclude) {
+    // Any entry rooted at the directory keeps it out — `generated`,
+    // `generated/`, `generated/**` and `generated/**/*` all do — so an author's
+    // own spelling is honoured rather than repaired into a duplicate.
+    return exclude.some((entry) => {
+        if (typeof entry !== "string")
+            return false;
+        const normalized = normalizeEntry(entry);
+        return (normalized === FUNCTION_INVOKERS_DIR ||
+            normalized.startsWith(`${FUNCTION_INVOKERS_DIR}/`));
+    });
+}
+/**
+ * The gaps in an already-parsed tsconfig object.
+ *
+ * Three separate facts, because two of them used to be one: a config that
+ * listed the two declarations and nothing else counted as "covered" while no
+ * function source was in the program at all, so `tsc` typechecked the
+ * declarations against themselves and push reported success (CR3182-003).
+ */
+function tsconfigWiringGaps(parsed, context) {
+    const compilerOptions = parsed.compilerOptions && typeof parsed.compilerOptions === "object"
+        ? parsed.compilerOptions
+        : {};
+    const paths = compilerOptions.paths && typeof compilerOptions.paths === "object"
+        ? compilerOptions.paths
+        : {};
+    const mapped = Array.isArray(paths[SDK_MODULE_SPECIFIER])
+        ? paths[SDK_MODULE_SPECIFIER]
+        : [];
+    const include = Array.isArray(parsed.include) ? parsed.include : [];
+    const files = Array.isArray(parsed.files) ? parsed.files : [];
+    // With neither `include` nor `files`, TypeScript takes every file under the
+    // directory — sources and declarations alike — so there is nothing to add.
+    const implicitlyAll = parsed.include === undefined && parsed.files === undefined;
+    const listed = [...include, ...files];
+    // Two separate questions, because an author's glob can answer them
+    // differently: `"*.ts"` covers the declarations without reaching
+    // `generated/`, and `"generated/**"` the reverse (CR3281-003).
+    const declarationsCovered = listed.some(coversDeclarations);
+    const reachesSubdirectories = listed.some(coversSubdirectories);
+    const exclude = Array.isArray(parsed.exclude) ? parsed.exclude : [];
+    return {
+        mapping: !mapped.includes(`./${SDK_TYPES_FILE}`),
+        missingDeclarations: implicitlyAll || declarationsCovered
+            ? []
+            : REGENERATED_DECLARATIONS.filter((file) => !listed.some((entry) => isDeclarationEntry(entry, file))),
+        sources: !implicitlyAll && !declarationsCovered && !listed.some(isSourceEntry),
+        // Only a program that would SEE the directory needs the exclusion: an
+        // explicit list that reaches no subdirectory never sweeps it in.
+        generatedExclusion: context.generatedDirExists &&
+            (implicitlyAll || reachesSubdirectories) &&
+            !excludesGenerated(exclude),
+    };
+}
+function hasGaps(gaps) {
+    return (gaps.mapping || gaps.missingDeclarations.length > 0 || gaps.sources || gaps.generatedExclusion);
+}
+function describeGaps(gaps) {
+    const problems = [];
+    if (gaps.mapping) {
+        problems.push(`\`compilerOptions.paths\` does not map "${SDK_MODULE_SPECIFIER}" to ` +
+            `"./${SDK_TYPES_FILE}", so a function's import of the SDK does not resolve`);
+    }
+    if (gaps.missingDeclarations.length > 0) {
+        problems.push(`\`include\` does not cover ${gaps.missingDeclarations
+            .map((file) => `"./${file}"`)
+            .join(", ")}, so the generated augmentation(s) there are never loaded`);
+    }
+    if (gaps.sources) {
+        problems.push("`include` covers no function source, so `tsc` typechecks none of them");
+    }
+    if (gaps.generatedExclusion) {
+        problems.push(`\`exclude\` does not cover "${GENERATED_EXCLUDE}", so the generated client ` +
+            "invokers (which import `js-bao-wss-client`) are swept into the program");
+    }
+    return problems;
+}
+/**
+ * Whether an existing tsconfig still carries the wiring the handle needs — the
+ * repaired document when push can fix it, and the problems when it cannot.
+ *
+ * The scaffold is written once and then belongs to its author, but "belongs to
+ * its author" cannot mean "silently stops working": a tree scaffolded before
+ * the `primitive-functions` rename (#3209) points at a declaration push no
+ * longer writes, and a tsconfig an author wrote by hand never had the wiring at
+ * all. Either way push claims success while no compiler can load the
+ * augmentation (SO3182-004).
+ *
+ * So the three REQUIRED facts — the module path mapping, the declarations being
+ * in the program, and the SOURCES being in the program — are repaired in a
+ * plain-JSON file, and everything else in it is left exactly as written. The
+ * mapping is APPENDED to any the author already has, so a deliberate mapping
+ * still wins and ours is only the fallback.
+ *
+ * A JSONC file (comments are legal in a tsconfig) is never rewritten —
+ * reformatting an author's file is worse than leaving it — but it IS read, and
+ * anything missing is reported instead of passing in silence (CR3182-003).
+ */
+export function inspectFunctionsTsconfig(existing, context = { generatedDirExists: false }) {
+    if (existing === null) {
+        return { repaired: renderFunctionsTsconfig(), problems: [] };
+    }
+    let parsed;
+    let plainJson = true;
+    try {
+        parsed = JSON.parse(existing);
+    }
+    catch {
+        plainJson = false;
+        try {
+            parsed = JSON.parse(stripJsonComments(existing));
+        }
+        catch {
+            return {
+                repaired: null,
+                problems: [
+                    "it is not valid JSON or JSONC, so neither push nor a compiler can " +
+                        "read it — fix the syntax, or delete it and let push scaffold a new one",
+                ],
+            };
+        }
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            repaired: null,
+            problems: ["it is not a JSON object, so it configures no compiler"],
+        };
+    }
+    const gaps = tsconfigWiringGaps(parsed, context);
+    if (!hasGaps(gaps)) {
+        return { repaired: null, problems: [] };
+    }
+    if (!plainJson) {
+        // Comments are the author's; repairing would strip them. Say what is
+        // missing instead of reporting success over a program that cannot load the
+        // handle.
+        return { repaired: null, problems: describeGaps(gaps) };
+    }
+    const compilerOptions = parsed.compilerOptions && typeof parsed.compilerOptions === "object"
+        ? parsed.compilerOptions
+        : (parsed.compilerOptions = {});
+    const paths = compilerOptions.paths && typeof compilerOptions.paths === "object"
+        ? compilerOptions.paths
+        : (compilerOptions.paths = {});
+    if (gaps.mapping) {
+        const mapped = Array.isArray(paths[SDK_MODULE_SPECIFIER])
+            ? paths[SDK_MODULE_SPECIFIER]
+            : [];
+        paths[SDK_MODULE_SPECIFIER] = [...mapped, `./${SDK_TYPES_FILE}`];
+    }
+    if (gaps.missingDeclarations.length > 0 || gaps.sources) {
+        const include = Array.isArray(parsed.include) ? parsed.include : [];
+        const added = [];
+        // The sources come back through the same wildcard the scaffold uses, which
+        // covers the declarations too — so it is added first and the explicit
+        // declaration entries only when it is not. Only the MISSING declarations
+        // are added, beside the ones the author already named (#3281).
+        if (gaps.sources)
+            added.push(SOURCES_INCLUDE);
+        else
+            added.push(...gaps.missingDeclarations.map((file) => `./${file}`));
+        parsed.include = [...include, ...added];
+    }
+    if (gaps.generatedExclusion ||
+        // The wildcard just added sweeps `generated/` in too.
+        (gaps.sources && context.generatedDirExists && !excludesGenerated(parsed.exclude ?? []))) {
+        const exclude = Array.isArray(parsed.exclude) ? parsed.exclude : [];
+        parsed.exclude = [...exclude, GENERATED_EXCLUDE];
+    }
+    return { repaired: JSON.stringify(parsed, null, 2) + "\n", problems: [] };
+}
+/**
+ * The repaired document alone, or null to leave the file alone.
+ *
+ * Kept as the narrow answer `planFunctionTypeArtifacts` needs; the problems a
+ * repair cannot cover travel through `inspectFunctionsTsconfig`.
+ */
+export function reconcileFunctionsTsconfig(existing, context = { generatedDirExists: false }) {
+    return inspectFunctionsTsconfig(existing, context).repaired;
+}
+/** The invoker directory a plan writes to, absolute. */
+export function functionInvokerDir(configDir, options = {}) {
+    return options.invokerDir
+        ? resolve(options.invokerDir)
+        : join(configDir, "functions", FUNCTION_INVOKERS_DIR);
+}
+/** A path as the plan reports it: tree-relative POSIX when inside the tree. */
+function reportedPath(configDir, absolute) {
+    const rel = relative(resolve(configDir), absolute);
+    if (rel && !rel.startsWith(".."))
+        return rel.split(sep).join("/");
+    return absolute;
+}
+/**
+ * Every database-type TOML in the tree, read once.
+ *
+ * The type KEY is the one push and the grant preflight use — `[type]
+ * databaseType` when the file declares it, the file name only as the fallback.
+ * Taking the file name unconditionally would type the handle under a key the
+ * platform never hears about, so `ctx.db(id, "<declared-type>")` — the key the
+ * grant names — would not compile while a wrong one would (SO3182-003).
+ *
+ * Every `.toml` here is a database type. The generated document-schema copy is
+ * a rule about `functions/`, so it is not filtered out here (CR3455-003): a
+ * type that happens to share its base name is this directory's own business.
+ */
+export function databaseTypeSources(configDir) {
+    const dir = join(configDir, "database-type-configs");
+    if (!existsSync(dir))
+        return [];
+    const sources = [];
+    for (const file of readdirSync(dir).filter((f) => f.endsWith(".toml"))) {
+        const tomlPath = join(dir, file);
+        let tomlContent;
+        try {
+            tomlContent = readFileSync(tomlPath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        let declared = null;
+        try {
+            const parsed = parseConfigToml(tomlContent);
+            if (parsed?.type?.databaseType)
+                declared = String(parsed.type.databaseType);
+        }
+        catch {
+            // A file that does not parse is reported by its own preflight; the
+            // renderer falls back to the name push would fall back to.
+        }
+        sources.push({
+            databaseType: declared || basename(file, ".toml"),
+            tomlPath,
+            tomlContent,
+        });
+    }
+    return sources;
+}
+/**
+ * Whether the tree has a `functions/` directory of its own — one holding
+ * anything besides the `generated/` directory codegen itself writes.
+ *
+ * #3798, DSO-3798-005 — a tree whose only generated output is an agent's
+ * client artifact gets `functions/generated/` created FOR it; that directory
+ * must not then count as function sources to serve, or the next run would
+ * start writing declarations and a tsconfig for functions that do not exist.
+ */
+export function treeHasFunctionsDir(configDir) {
+    const functionsDir = join(configDir, "functions");
+    if (!existsSync(functionsDir))
+        return false;
+    // An EMPTY `functions/` is the author's own and keeps its meaning; only one
+    // holding nothing but `generated/` is codegen's.
+    const entries = readdirSync(functionsDir);
+    return entries.length === 0 || entries.some((entry) => entry !== FUNCTION_INVOKERS_DIR);
+}
+/**
+ * The client-side artifact of every agent prompt in the tree (#3798), where
+ * the invokers go.
+ */
+function planAgentClientArtifacts(configDir, options) {
+    const dir = functionInvokerDir(configDir, options);
+    return renderAgentClientFiles(promptSchemaSources(configDir)).map((file) => {
+        const absolute = join(dir, file.fileName);
+        return {
+            relative: reportedPath(configDir, absolute),
+            absolute,
+            contents: file.content,
+            regenerated: true,
+        };
+    });
+}
+/**
+ * What push would write, without writing it.
+ *
+ * Only the agents' client artifacts when the tree has no `functions/`
+ * directory (#3798, DSO-3798-005), and nothing at all when it has neither:
+ * the other artifacts exist to type function sources, and a tree with none
+ * needs no compiler wiring.
+ */
+export function planFunctionTypeArtifacts(configDir, sdkTypes, options = {}) {
+    const functionsDir = join(configDir, "functions");
+    const agentArtifacts = planAgentClientArtifacts(configDir, options);
+    if (!treeHasFunctionsDir(configDir))
+        return agentArtifacts;
+    // #3455 — one resolution for both the declaration below and the tree copy.
+    const documentSchema = resolveDocumentSchema(configDir);
+    const declaration = renderDbTypesDeclaration(databaseTypeSources(configDir));
+    // #3281 — the functions declaration and the per-key invokers, from the same
+    // `functions/*.toml`. A malformed schema throws naming the file: the honest
+    // `unknown` is for an absent schema, and typing a broken one as anything
+    // would be a declaration that lies.
+    const functionSources = functionSchemaSources(configDir);
+    const functionsDeclaration = renderFunctionSchemasDeclaration(functionSources);
+    const invokerDir = functionInvokerDir(configDir, options);
+    const invokers = renderFunctionInvokers(functionSources);
+    const artifacts = [
+        {
+            relative: `functions/${DB_TYPES_DECLARATION_FILE}`,
+            absolute: join(functionsDir, DB_TYPES_DECLARATION_FILE),
+            contents: declaration,
+            regenerated: true,
+        },
+        {
+            relative: `functions/${SDK_TYPES_FILE}`,
+            absolute: join(functionsDir, SDK_TYPES_FILE),
+            contents: sdkTypes ?? loadSdkTypes(),
+            regenerated: true,
+        },
+        {
+            relative: `functions/${FUNCTION_TYPES_DECLARATION_FILE}`,
+            absolute: join(functionsDir, FUNCTION_TYPES_DECLARATION_FILE),
+            contents: functionsDeclaration,
+            regenerated: true,
+        },
+        // #3281 — the document handle's declaration, from the project's
+        // `models/models.toml` (open when the project has none).
+        //
+        // #3455 (D3455-009) — through the SAME resolution push and diff use, so a
+        // tree pulled into a project with no `models/models.toml` is typed from
+        // the schema its active version was pushed with rather than losing its
+        // types the moment it is pulled.
+        {
+            relative: `functions/${DOCUMENT_TYPES_DECLARATION_FILE}`,
+            absolute: join(functionsDir, DOCUMENT_TYPES_DECLARATION_FILE),
+            contents: renderDocumentTypesDeclaration(documentSchema.declarationSource),
+            regenerated: true,
+        },
+        // #3330 — `ctx.prompts.run`'s output types, from this tree's
+        // `prompts/*.toml` (open when the tree declares none).
+        {
+            relative: `functions/${PROMPT_TYPES_DECLARATION_FILE}`,
+            absolute: join(functionsDir, PROMPT_TYPES_DECLARATION_FILE),
+            contents: renderPromptSchemasDeclaration(promptSchemaSources(configDir)),
+            regenerated: true,
+        },
+        // #3455 (D3455-009) — the project's document schema, copied into the tree
+        // so a fresh `config pull` into a project that has no `models/models.toml`
+        // still rebuilds the same envelope and reads Synced.
+        //
+        // Regenerated from the PROJECT file whenever there is one, and otherwise
+        // left exactly alone: when the copy is itself what the resolution answered
+        // (rule 2) it IS the source, and rewriting a file from itself would be the
+        // second source of truth the fixed precedence exists to avoid.
+        ...(documentSchema.origin === "project" && documentSchema.source
+            ? [
+                {
+                    relative: `functions/${DOCUMENT_SCHEMA_TREE_FILE}`,
+                    absolute: join(functionsDir, DOCUMENT_SCHEMA_TREE_FILE),
+                    contents: documentSchema.source.content,
+                    regenerated: true,
+                },
+            ]
+            : []),
+        ...invokers.map((invoker) => {
+            const absolute = join(invokerDir, invoker.fileName);
+            return {
+                relative: reportedPath(configDir, absolute),
+                absolute,
+                contents: invoker.content,
+                regenerated: true,
+            };
+        }),
+        // #3798 — each agent's client-side types, beside the invokers and owned
+        // by the same plan (so the orphan sweep keeps them while the agent does).
+        ...agentArtifacts,
+    ];
+    // The tsconfig is planned against what is on disk: scaffolded when absent,
+    // repaired when its wiring is missing, and left alone otherwise — so an
+    // author's own edits survive a push and a broken program does not.
+    const tsconfigPath = join(functionsDir, FUNCTIONS_TSCONFIG_FILE);
+    let onDisk = null;
+    if (existsSync(tsconfigPath)) {
+        try {
+            onDisk = readFileSync(tsconfigPath, "utf-8");
+        }
+        catch {
+            onDisk = null;
+        }
+    }
+    const tsconfig = reconcileFunctionsTsconfig(onDisk, tsconfigContext(configDir, options));
+    if (tsconfig !== null) {
+        artifacts.push({
+            relative: `functions/${FUNCTIONS_TSCONFIG_FILE}`,
+            absolute: tsconfigPath,
+            contents: tsconfig,
+            regenerated: false,
+        });
+    }
+    return artifacts;
+}
+/**
+ * The tsconfig wiring push could not repair, phrased for the author.
+ *
+ * Push repairs a plain-JSON tsconfig in place, but it will not rewrite one that
+ * carries comments and it cannot read one that is broken. Reporting is what is
+ * left, and it is not optional: a typed handle that no compiler loads is the
+ * failure mode this whole artifact exists to prevent, and staying silent about
+ * it is how it reaches an author as "my types just don't work" (CR3182-003).
+ */
+export function functionTypeWiringProblems(configDir, options = {}) {
+    const functionsDir = join(configDir, "functions");
+    if (!treeHasFunctionsDir(configDir))
+        return [];
+    const tsconfigPath = join(functionsDir, FUNCTIONS_TSCONFIG_FILE);
+    if (!existsSync(tsconfigPath))
+        return [];
+    let onDisk;
+    try {
+        onDisk = readFileSync(tsconfigPath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    return inspectFunctionsTsconfig(onDisk, tsconfigContext(configDir, options)).problems;
+}
+/**
+ * What the inspection knows about the directory: whether `generated/` will
+ * exist beside the tsconfig once this plan is written (it exists now, or this
+ * plan writes an invoker into the default location).
+ */
+function tsconfigContext(configDir, options) {
+    const defaultDir = join(configDir, "functions", FUNCTION_INVOKERS_DIR);
+    const writesThere = functionInvokerDir(configDir, options) === defaultDir &&
+        functionSchemaSources(configDir).length > 0;
+    return { generatedDirExists: existsSync(defaultDir) || writesThere };
+}
+/**
+ * Invokers in the plan's directory that the plan no longer writes — a
+ * function whose TOML was removed. Owned by the `.generated.ts` suffix, the
+ * rule the other two generators apply to their own `generated/` directories.
+ */
+function orphanedInvokers(configDir, planned, options) {
+    const dir = functionInvokerDir(configDir, options);
+    if (!existsSync(dir))
+        return [];
+    const keep = new Set(planned.map((a) => a.absolute));
+    // #3798 (CSO-3798-003) — with no `functions/` at all, an agent's client
+    // artifact is the only thing a run could have written here (an `-o`
+    // directory the functions run never owned before), so only those are swept.
+    const suffix = existsSync(join(configDir, "functions"))
+        ? GENERATED_FILE_SUFFIX
+        : AGENT_CLIENT_FILE_SUFFIX;
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(suffix))
+        .map((f) => join(dir, f))
+        .filter((absolute) => !keep.has(absolute));
+}
+/** Write them, and report the tree-relative paths that changed on disk. */
+export function writeFunctionTypeArtifacts(configDir, sdkTypes, options = {}) {
+    // No early return for an empty plan (CSO-3798-003): removing a tree's last
+    // agent (or its last function) plans nothing, and its artifacts still go.
+    const artifacts = planFunctionTypeArtifacts(configDir, sdkTypes, options);
+    const written = [];
+    for (const artifact of artifacts) {
+        const exists = existsSync(artifact.absolute);
+        if (exists && readFileSync(artifact.absolute, "utf-8") === artifact.contents) {
+            written.push(artifact.relative);
+            continue;
+        }
+        mkdirSync(dirname(artifact.absolute), { recursive: true });
+        writeFileSync(artifact.absolute, artifact.contents);
+        written.push(artifact.relative);
+    }
+    // A removed function's invoker goes with it (#3281): a stale generated file
+    // an app still imports is a compile error naming a function that no longer
+    // exists, which is the right failure, but one left behind forever is not.
+    for (const orphan of orphanedInvokers(configDir, artifacts, options)) {
+        rmSync(orphan, { force: true });
+    }
+    return written;
+}
+/**
+ * The artifacts a `--check` run would rewrite: the freshness answer for CI and
+ * for an editor that wants to know its types are current.
+ *
+ * The tsconfig is only ever planned when it is missing or its wiring is (see
+ * `reconcileFunctionsTsconfig`), so a hand-edited but correctly wired one is
+ * never reported — and one that would leave the declarations unloadable always
+ * is.
+ */
+export function staleFunctionTypeArtifacts(configDir, options = {}) {
+    const stale = [];
+    const planned = planFunctionTypeArtifacts(configDir, undefined, options);
+    for (const artifact of planned) {
+        if (!existsSync(artifact.absolute)) {
+            stale.push(artifact.relative);
+            continue;
+        }
+        if (readFileSync(artifact.absolute, "utf-8") !== artifact.contents) {
+            stale.push(artifact.relative);
+        }
+    }
+    for (const orphan of orphanedInvokers(configDir, planned, options)) {
+        stale.push(reportedPath(configDir, orphan));
+    }
+    return stale;
+}
+/**
+ * The SDK's own declaration, as the CLI ships it.
+ *
+ * Vendored at build time by `cli/scripts/gen-sdk-types.mjs` from
+ * `packages/primitive-functions/index.d.ts` — the file `pnpm functions:profile`
+ * generates — so the types a config tree gets are the types the platform bakes
+ * into the sandbox, and the CLI still imports server source at build time only.
+ */
+function loadSdkTypes() {
+    return SDK_TYPES_SOURCE;
+}
+//# sourceMappingURL=function-db-types.js.map