primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/function-db-types.d.ts

@@ -0,0 +1,202 @@
+/**
+ * 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).
+ */
+export declare const DB_TYPES_DECLARATION_FILE = "primitive-db-types.d.ts";
+export declare const SDK_TYPES_FILE = "primitive-functions.d.ts";
+export declare 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 declare const REGENERATED_DECLARATIONS: readonly string[];
+/** The scaffold's exclusion for the client invokers (#3281). */
+export declare const GENERATED_EXCLUDE = "generated/**";
+export interface DatabaseTypeSource {
+    databaseType: string;
+    tomlPath: string;
+    tomlContent: string;
+}
+/**
+ * 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 declare function renderDbTypesDeclaration(sources: readonly DatabaseTypeSource[]): string;
+/** The scaffolded compiler wiring. Written once; an author owns it after. */
+export declare function renderFunctionsTsconfig(): string;
+/** The bare specifier every function imports, and the tsconfig must resolve. */
+export declare const SDK_MODULE_SPECIFIER = "primitive-functions";
+/** What the inspection knows about the directory, beyond the file's text. */
+export interface TsconfigContext {
+    /** Whether `functions/generated/` exists on disk. */
+    generatedDirExists: boolean;
+}
+/** What push found wrong with a `functions/tsconfig.json` it will not rewrite. */
+export interface TsconfigWiringReport {
+    /** The document push should write, or null to leave the file as it is. */
+    repaired: string | null;
+    /**
+     * Wiring push could not repair, phrased for the author to act on. Empty when
+     * the file is fine or was repaired.
+     */
+    problems: string[];
+}
+/**
+ * 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 declare function inspectFunctionsTsconfig(existing: string | null, context?: TsconfigContext): TsconfigWiringReport;
+/**
+ * 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 declare function reconcileFunctionsTsconfig(existing: string | null, context?: TsconfigContext): string | null;
+export interface FunctionTypeArtifact {
+    /** Tree-relative, POSIX (or relative to the tree when `-o` points outside it). */
+    relative: string;
+    absolute: string;
+    contents: string;
+    /** Generated files are rewritten every push; the scaffold is written once. */
+    regenerated: boolean;
+}
+export interface FunctionTypeArtifactOptions {
+    /**
+     * Where the per-key client invokers go (#3281). Defaults to
+     * `<tree>/functions/generated/`; `primitive functions codegen -o <dir>` is
+     * the override, the `workflows codegen` shape.
+     */
+    invokerDir?: string;
+}
+/** The invoker directory a plan writes to, absolute. */
+export declare function functionInvokerDir(configDir: string, options?: FunctionTypeArtifactOptions): string;
+/**
+ * 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 declare function databaseTypeSources(configDir: string): DatabaseTypeSource[];
+/**
+ * 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 declare function treeHasFunctionsDir(configDir: string): boolean;
+/**
+ * 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 declare function planFunctionTypeArtifacts(configDir: string, sdkTypes?: string, options?: FunctionTypeArtifactOptions): FunctionTypeArtifact[];
+/**
+ * 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 declare function functionTypeWiringProblems(configDir: string, options?: FunctionTypeArtifactOptions): string[];
+/** Write them, and report the tree-relative paths that changed on disk. */
+export declare function writeFunctionTypeArtifacts(configDir: string, sdkTypes?: string, options?: FunctionTypeArtifactOptions): string[];
+/**
+ * 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 declare function staleFunctionTypeArtifacts(configDir: string, options?: FunctionTypeArtifactOptions): string[];