primitive-admin 1.0.49 → 1.0.51

package/dist/src/lib/db-codegen/dbTemplates.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Pure string templates for the `databases codegen` generator (issue #814).
+ *
+ * Mirrors the codegen-v2 template style
+ * (`packages/js-bao/src/cli/v2/templates.ts`): total functions (no I/O, no
+ * hidden state), an auto-generated banner + fingerprint header, and
+ * deterministic ordering so `--check` can compare byte-for-byte.
+ *
+ * Diverges from codegen-v2 in two ways:
+ *   1. Database-DO records are schemaless documents, NOT `BaseModel` ORM
+ *      classes — so we emit plain `export interface` types with no class
+ *      shell, no barrel registration, and `import type` only.
+ *   2. We add an OPERATIONS half codegen-v2 has no analog for: per-op
+ *      input-params interfaces + per-op result aliases keyed off `op.type`.
+ */
+/** A field on a record interface (read shape). */
+export interface RecordField {
+    name: string;
+    /** TOML field type (`string|number|boolean|date|id|stringset`). */
+    type: string;
+    /** Required props render as `name: T`; otherwise `name?: T`. */
+    required: boolean;
+    /**
+     * Allowed-value set for a `string` field (#843). When non-empty, the field
+     * renders a TS string-literal union (`"a" | "b"`) instead of bare `string`.
+     */
+    enum?: string[];
+}
+export interface RenderRecordInterfaceInput {
+    /** PascalCase interface name (e.g. `Account`). */
+    interfaceName: string;
+    /** TOML model name (e.g. `accounts`). */
+    modelName: string;
+    fields: RecordField[];
+    /**
+     * Server-stamped field names (timestamps + auto-populated fields) that
+     * appear on the READ record interface as OPTIONAL props, and only if not
+     * already declared in `fields`.
+     */
+    stampedFields: string[];
+}
+/** One declared param on an op-input interface (write shape). */
+export interface ParamField {
+    name: string;
+    /** TOML param type (`string|number|boolean|object`). */
+    type: string;
+    required: boolean;
+    /**
+     * Allowed-value set for a `string` param → string-literal union (#861).
+     * Validated server-side (`validateParams`) at config-push time; the emitter
+     * renders the union when present and falls back to the base type otherwise.
+     */
+    enum?: string[];
+}
+export interface RenderOpParamsInterfaceInput {
+    /** PascalCase params interface name (e.g. `SaveAccountParams`). */
+    interfaceName: string;
+    /** Operation name (e.g. `saveAccount`). */
+    opName: string;
+    params: ParamField[];
+}
+export interface RenderOpResultAliasInput {
+    /** Per-op result alias name (e.g. `SaveAccountResult`). */
+    aliasName: string;
+    /** Operation name (e.g. `saveAccount`). */
+    opName: string;
+    /** Operation type (`query|mutation|count|aggregate|pipeline|applyToQuery`). */
+    opType: string;
+    /**
+     * For `query` ops, the record interface name the result is generic over
+     * (`QueryResult<Account>`). Null when the op's model has no record
+     * interface (e.g. pipeline) — falls back to `QueryResult<Record<string, unknown>>`.
+     */
+    recordInterfaceName: string | null;
+}
+/** The shared generic result aliases, keyed off `op.type`. */
+export declare const RESULT_ALIASES_BLOCK = "// Generic per-op result shapes, keyed off the operation type. The op\n// return contract is NOT stored in the TOML \u2014 these mirror the runtime\n// result shapes produced by the database-operations controller.\n\n/** `query` ops return a page of records. */\nexport interface QueryResult<T = Record<string, unknown>> {\n  data: T[];\n  hasMore?: boolean;\n  nextCursor?: string;\n}\n\n/** `mutation` ops return per-step results. */\nexport interface MutationResult {\n  results: unknown[];\n}\n\n/** `count` ops return a single count. */\nexport interface CountResult {\n  count: number;\n}\n\n/** `aggregate` ops return a single result object. */\nexport interface AggregateResult {\n  result: Record<string, unknown>;\n}\n\n/** `applyToQuery` ops return match/affect/fail counts. */\nexport interface ApplyToQueryResult {\n  matched: number;\n  affected: number;\n  failed: number;\n  sample?: unknown[];\n}\n\n/** `pipeline` ops return per-step results keyed by step name. */\nexport interface PipelineResult {\n  steps: Record<string, unknown>;\n}\n";
+/**
+ * Render the header (banner + regen hint + fingerprint).
+ */
+export declare function renderHeader(fingerprint: string): string;
+/**
+ * Render a single record interface (read shape). Stamped fields
+ * (`createdAt`, `modifiedAt`, `ownerId`, …) are appended as OPTIONAL props
+ * if not already present in `fields`.
+ */
+export declare function renderRecordInterface(input: RenderRecordInterfaceInput): string;
+/**
+ * Render a single op-input-params interface (write shape). `required: true`
+ * params are non-optional; others are optional. `object` params render as
+ * `Record<string, any>`.
+ */
+export declare function renderOpParamsInterface(input: RenderOpParamsInterfaceInput): string;
+/**
+ * Render a per-op result alias keyed off `op.type`.
+ */
+export declare function renderOpResultAlias(input: RenderOpResultAliasInput): string;

package/dist/src/lib/db-codegen/dbTemplates.js

@@ -22,7 +22,7 @@ export const RESULT_ALIASES_BLOCK = `// Generic per-op result shapes, keyed off
 // result shapes produced by the database-operations controller.
 
 /** \`query\` ops return a page of records. */
-export interface QueryResult<T = Record<string, any>> {
+export interface QueryResult<T = Record<string, unknown>> {
   data: T[];
   hasMore?: boolean;
   nextCursor?: string;
@@ -30,7 +30,7 @@ export interface QueryResult<T = Record<string, any>> {
 
 /** \`mutation\` ops return per-step results. */
 export interface MutationResult {
-  results: any[];
+  results: unknown[];
 }
 
 /** \`count\` ops return a single count. */
@@ -40,7 +40,7 @@ export interface CountResult {
 
 /** \`aggregate\` ops return a single result object. */
 export interface AggregateResult {
-  result: Record<string, any>;
+  result: Record<string, unknown>;
 }
 
 /** \`applyToQuery\` ops return match/affect/fail counts. */
@@ -48,12 +48,12 @@ export interface ApplyToQueryResult {
   matched: number;
   affected: number;
   failed: number;
-  sample?: any[];
+  sample?: unknown[];
 }
 
 /** \`pipeline\` ops return per-step results keyed by step name. */
 export interface PipelineResult {
-  steps: Record<string, any>;
+  steps: Record<string, unknown>;
 }
 `;
 /**
@@ -73,13 +73,12 @@ export function renderHeader(fingerprint) {
  */
 export function renderRecordInterface(input) {
     const { interfaceName, fields, stampedFields } = input;
-    const lines = [];
-    lines.push(`export interface ${interfaceName} {`);
+    const memberLines = [];
     const declared = new Set();
     for (const f of fields) {
         declared.add(f.name);
         const optional = f.required ? "" : "?";
-        lines.push(`  ${f.name}${optional}: ${tsTypeForDbField(f.type, f.enum)};`);
+        memberLines.push(`  ${f.name}${optional}: ${tsTypeForDbField(f.type, f.enum)};`);
     }
     // Server-stamped fields appear on the read interface as optional —
     // the runtime populates them, but a freshly-built object may not have
@@ -88,8 +87,23 @@ export function renderRecordInterface(input) {
         if (declared.has(stamped))
             continue;
         declared.add(stamped);
-        lines.push(`  ${stamped}?: string;`);
+        memberLines.push(`  ${stamped}?: string;`);
+    }
+    // A record with no fields and no stamped fields would render an empty
+    // `interface X {}`, which trips `@typescript-eslint/no-empty-object-type`.
+    // Emit a `Record<string, unknown>` type alias instead. Database-DO records
+    // are SCHEMALESS — arbitrary runtime keys can exist — so the empty-schema
+    // shape must stay OPEN (`Record<string, unknown>`), NOT `Record<string,
+    // never>`. `Record<string, never>` forbids every key, which would make real
+    // returned records unassignable to `QueryResult<X>` and unusable in TS.
+    // (Contrast with the no-param-op case in `renderOpParamsInterface`, where
+    // `Record<string, never>` is correct: it means "no params allowed".)
+    if (memberLines.length === 0) {
+        return `export type ${interfaceName} = Record<string, unknown>;`;
     }
+    const lines = [];
+    lines.push(`export interface ${interfaceName} {`);
+    lines.push(...memberLines);
     lines.push(`}`);
     return lines.join("\n");
 }
@@ -100,6 +114,13 @@ export function renderRecordInterface(input) {
  */
 export function renderOpParamsInterface(input) {
     const { interfaceName, params } = input;
+    // An op with no declared params has no input shape. Emitting an empty
+    // `interface X {}` trips `@typescript-eslint/no-empty-object-type`, so
+    // render a `Record<string, never>` type alias instead — it types "no
+    // params allowed" and stays call-site compatible (`op({})`).
+    if (params.length === 0) {
+        return `export type ${interfaceName} = Record<string, never>;`;
+    }
     const lines = [];
     lines.push(`export interface ${interfaceName} {`);
     for (const p of params) {
@@ -116,7 +137,7 @@ export function renderOpResultAlias(input) {
     const { aliasName, opType, recordInterfaceName } = input;
     switch (opType) {
         case "query": {
-            const generic = recordInterfaceName ?? "Record<string, any>";
+            const generic = recordInterfaceName ?? "Record<string, unknown>";
             return `export type ${aliasName} = QueryResult<${generic}>;`;
         }
         case "mutation":

package/dist/src/lib/db-codegen/dbTemplates.js.map

@@ -1 +1 @@
-{"version":3,"file":"dbTemplates.js","sourceRoot":"","sources":["../../../../src/lib/db-codegen/dbTemplates.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dbTemplates.js","sourceRoot":"","sources":["../../../../src/lib/db-codegen/dbTemplates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAExE,MAAM,aAAa,GACjB,2DAA2D,CAAC;AAC9D,MAAM,iBAAiB,GACrB,qEAAqE,CAAC;AAmExE,8DAA8D;AAC9D,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCnC,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,WAAmB;IAC9C,OAAO;QACL,aAAa;QACb,iBAAiB;QACjB,mBAAmB,WAAW,EAAE;KACjC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAiC;IAEjC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,KAAK,CAAC;IACvD,MAAM,WAAW,GAAa,EAAE,CAAC;IAEjC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACrB,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QACvC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,QAAQ,KAAK,gBAAgB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnF,CAAC;IAED,mEAAmE;IACnE,sEAAsE;IACtE,8DAA8D;IAC9D,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;QACpC,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,SAAS;QACpC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtB,WAAW,CAAC,IAAI,CAAC,KAAK,OAAO,YAAY,CAAC,CAAC;IAC7C,CAAC;IAED,sEAAsE;IACtE,2EAA2E;IAC3E,2EAA2E;IAC3E,0EAA0E;IAC1E,wEAAwE;IACxE,4EAA4E;IAC5E,wEAAwE;IACxE,0EAA0E;IAC1E,qEAAqE;IACrE,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,eAAe,aAAa,6BAA6B,CAAC;IACnE,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,oBAAoB,aAAa,IAAI,CAAC,CAAC;IAClD,KAAK,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAmC;IAEnC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACxC,sEAAsE;IACtE,uEAAuE;IACvE,qEAAqE;IACrE,6DAA6D;IAC7D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,eAAe,aAAa,2BAA2B,CAAC;IACjE,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,oBAAoB,aAAa,IAAI,CAAC,CAAC;IAClD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,QAAQ,KAAK,oBAAoB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjF,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAA+B;IACjE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,GAAG,KAAK,CAAC;IACzD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,OAAO,GAAG,mBAAmB,IAAI,yBAAyB,CAAC;YACjE,OAAO,eAAe,SAAS,kBAAkB,OAAO,IAAI,CAAC;QAC/D,CAAC;QACD,KAAK,UAAU;YACb,OAAO,eAAe,SAAS,oBAAoB,CAAC;QACtD,KAAK,OAAO;YACV,OAAO,eAAe,SAAS,iBAAiB,CAAC;QACnD,KAAK,WAAW;YACd,OAAO,eAAe,SAAS,qBAAqB,CAAC;QACvD,KAAK,cAAc;YACjB,OAAO,eAAe,SAAS,wBAAwB,CAAC;QAC1D,KAAK,UAAU;YACb,OAAO,eAAe,SAAS,oBAAoB,CAAC;QACtD;YACE,kEAAkE;YAClE,4DAA4D;YAC5D,OAAO,eAAe,SAAS,aAAa,CAAC;IACjD,CAAC;AACH,CAAC"}

package/dist/src/lib/db-codegen/dbTsTypes.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Map database-type TOML field/param types → TypeScript types for the
+ * `databases codegen` generator (issue #814).
+ *
+ * The record-interface half reuses the SAME `FieldType` vocabulary that
+ * powers the document-model codegen-v2 generator
+ * (`packages/js-bao/src/cli/v2/tsTypes.ts`): the database-type
+ * `[models.<m>.fields.<f>]` blocks round-trip through the same
+ * `loadSchemaFromTomlString` loader, so the field→TS mapping is identical
+ * (`string|id|date → string`, `number → number`, `boolean → boolean`,
+ * `stringset → StringSet`).
+ *
+ * The op-params half maps the operation `params.{type}` vocabulary
+ * (`string|number|boolean|object`, validated server-side in
+ * `database-type-operations-controller.ts`). `object` has no field-type
+ * analog and carries no nested schema, so it renders as `Record<string, unknown>`.
+ *
+ * NOTE (#842 — infer required record fields from operation params): when that
+ * issue is scheduled, the op-params analysis it needs (which fields a `$params.X`
+ * binding writes, and whether the param is `required`) already exists in
+ * `inferParamFieldTypes(op)` in
+ * `src/app-api/controllers/database-type-config-controller.ts` (issue #845 /
+ * #812 Phase 2). Its return shape was deliberately made growable (it can carry
+ * a `requiredInThisOp` flag) so it can be lifted into a shared `analyzeOpParams`
+ * pass consumed by BOTH the scaffold (#845, field *type*) and codegen (#842,
+ * field *required-ness*). Lift it rather than re-walking the ops here.
+ */
+/**
+ * Field types accepted in a database-type `[models.*]` schema. Mirrors
+ * `FieldType` in `packages/js-bao/src/types/ormTypes.ts`. Declared locally
+ * (rather than imported from `js-bao`) because `FieldType` is not part of
+ * the published `js-bao` entry point and the CLI does not depend on the
+ * library's internal type paths.
+ */
+export type DbFieldType = "string" | "number" | "boolean" | "date" | "id" | "stringset";
+/** Param types accepted in an `[[operations]]` `params` block. */
+export type DbParamType = "string" | "number" | "boolean" | "object";
+/**
+ * Returns the TS type expression for a record field type. Unknown types
+ * fall back to `unknown` rather than throwing: the database-type TOML is
+ * author-curated and may legitimately carry a field type the CLI's vendored
+ * vocabulary predates, and a hard throw would block codegen for the whole
+ * file over one unrecognized field.
+ */
+export declare function tsTypeForDbFieldType(fieldType: string): string;
+/**
+ * Render a TypeScript string-literal union from an `enum` allowed-value set
+ * (e.g. `["a", "b"]` → `"a" | "b"`). Each value is emitted via
+ * `JSON.stringify` so quotes, backslashes, and other special characters are
+ * properly escaped into a valid TS string literal.
+ *
+ * Shared enum vocabulary with the doc-model v2 codegen
+ * (`packages/js-bao/src/cli/v2/tsTypes.ts`). The `enum` array is validated
+ * upstream by the TOML loader (`parseFieldOptions`): non-empty, all-string,
+ * string-field-only. This renderer assumes that contract has held.
+ */
+export declare function tsUnionFromEnum(values: string[]): string;
+/**
+ * Returns the TS type expression for a record field, honoring an optional
+ * string `enum` allowed-value set (#843). A non-empty `enum` on a `string`
+ * field renders a string-literal union; otherwise falls back to the base
+ * `tsTypeForDbFieldType` mapping.
+ */
+export declare function tsTypeForDbField(fieldType: string, enumValues?: string[]): string;
+/**
+ * Returns the TS type expression for an op param, honoring an optional string
+ * `enum` allowed-value set (#861). A non-empty `enum` on a `string` param
+ * renders a string-literal union (`"a" | "b"`); otherwise falls back to the
+ * base param-type mapping below. Mirrors `tsTypeForDbField` (the record-field
+ * sibling) and reuses `tsUnionFromEnum` for a single escaping implementation.
+ *
+ * Unlike the record-field path (validated upstream by `parseFieldOptions`,
+ * which throws), op-param enum *shape* is validated server-side in
+ * `validateParams` at config-push time. So this renderer just falls back to
+ * the base type for a non-string param or an empty enum rather than throwing —
+ * the server is the source of truth for rejecting a malformed param `enum`.
+ */
+export declare function tsTypeForDbParamType(paramType: string, enumValues?: string[]): string;

package/dist/src/lib/db-codegen/dbTsTypes.js

@@ -13,7 +13,7 @@
  * The op-params half maps the operation `params.{type}` vocabulary
  * (`string|number|boolean|object`, validated server-side in
  * `database-type-operations-controller.ts`). `object` has no field-type
- * analog and carries no nested schema, so it renders as `Record<string, any>`.
+ * analog and carries no nested schema, so it renders as `Record<string, unknown>`.
  *
  * NOTE (#842 — infer required record fields from operation params): when that
  * issue is scheduled, the op-params analysis it needs (which fields a `$params.X`
@@ -104,7 +104,7 @@ export function tsTypeForDbParamType(paramType, enumValues) {
         case "boolean":
             return "boolean";
         case "object":
-            return "Record<string, any>";
+            return "Record<string, unknown>";
         default:
             return "unknown";
     }

package/dist/src/lib/db-codegen/dbTsTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"dbTsTypes.js","sourceRoot":"","sources":["../../../../src/lib/db-codegen/dbTsTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAoBH;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,QAAQ,CAAC;QACd,KAAK,IAAI,CAAC;QACV,KAAK,MAAM;YACT,OAAO,QAAQ,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,WAAW;YACd,sDAAsD;YACtD,OAAO,UAAU,CAAC;QACpB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,MAAgB;IAC9C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,UAAqB;IAErB,IACE,SAAS,KAAK,QAAQ;QACtB,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QACzB,UAAU,CAAC,MAAM,GAAG,CAAC,EACrB,CAAC;QACD,OAAO,eAAe,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,oBAAoB,CAAC,SAAS,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,UAAqB;IAErB,IACE,SAAS,KAAK,QAAQ;QACtB,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QACzB,UAAU,CAAC,MAAM,GAAG,CAAC,EACrB,CAAC;QACD,OAAO,eAAe,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,QAAQ;YACX,OAAO,qBAAqB,CAAC;QAC/B;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}
+{"version":3,"file":"dbTsTypes.js","sourceRoot":"","sources":["../../../../src/lib/db-codegen/dbTsTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAoBH;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,QAAQ,CAAC;QACd,KAAK,IAAI,CAAC;QACV,KAAK,MAAM;YACT,OAAO,QAAQ,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,WAAW;YACd,sDAAsD;YACtD,OAAO,UAAU,CAAC;QACpB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,MAAgB;IAC9C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,UAAqB;IAErB,IACE,SAAS,KAAK,QAAQ;QACtB,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QACzB,UAAU,CAAC,MAAM,GAAG,CAAC,EACrB,CAAC;QACD,OAAO,eAAe,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,oBAAoB,CAAC,SAAS,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,UAAqB;IAErB,IACE,SAAS,KAAK,QAAQ;QACtB,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QACzB,UAAU,CAAC,MAAM,GAAG,CAAC,EACrB,CAAC;QACD,OAAO,eAAe,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,QAAQ;YACX,OAAO,yBAAyB,CAAC;QACnC;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/src/lib/env-resolver.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Environment resolution.
+ *
+ * Decides which named environment the CLI is currently targeting. The
+ * resolution order is:
+ *
+ *   1. Explicit --env <name> flag (set via setCurrentEnvName from bin/primitive.ts)
+ *   2. PRIMITIVE_ENV environment variable
+ *   3. The project config's defaultEnvironment
+ *   4. If the project has exactly one environment, that one
+ *   5. null (legacy mode — fall back to ~/.primitive/credentials.json)
+ *
+ * Commands read the resolved environment once via getCurrentEnvironment().
+ * The resolution is cached for the lifetime of the process.
+ */
+import { type ProjectConfig, type ProjectEnvironment } from "./project-config.js";
+export interface ResolvedEnvironment {
+    /** The environment name (e.g. "dev", "prod"). */
+    name: string;
+    /** The config entry for this environment. */
+    config: ProjectEnvironment;
+    /** Absolute path to .primitive/config.json. */
+    projectConfigPath: string;
+    /** Absolute path to the project root (the parent of .primitive/). */
+    projectRoot: string;
+}
+/**
+ * Called by bin/primitive.ts when the user passes --env <name> on the command
+ * line. Must be called before any command code runs so subsequent calls to
+ * getCurrentEnvironment() see the override.
+ */
+export declare function setCurrentEnvName(name: string | null): void;
+/**
+ * Forces the resolver to re-read the project config on the next call.
+ * Used by tests and by commands that mutate the project config.
+ */
+export declare function resetEnvResolver(): void;
+/**
+ * Loads and caches the project config. Returns null if no
+ * .primitive/config.json is present. Throws ProjectConfigError on a broken config.
+ */
+export declare function getProjectConfig(): ProjectConfig | null;
+/**
+ * Resolves the current environment, or returns null if we're running in
+ * legacy mode (no .primitive/config.json present).
+ *
+ * This never throws for a missing project config — that's legitimate
+ * "legacy mode" usage. It DOES throw if the project config exists but the
+ * requested environment doesn't.
+ */
+export declare function getCurrentEnvironment(): ResolvedEnvironment | null;
+/**
+ * Returns the current environment name for display purposes (e.g. in status
+ * headers). Returns null in legacy mode. Swallows resolution errors so the
+ * header never crashes the CLI.
+ */
+export declare function getCurrentEnvNameSafe(): string | null;
+/**
+ * Returns the explicit name set via setCurrentEnvName(), for commands that
+ * need to know whether the user passed --env vs. relying on defaults.
+ */
+export declare function getExplicitEnvName(): string | null;

package/dist/src/lib/fetch.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Custom fetch that accepts self-signed certificates for localhost.
+ * Used for local development with HTTPS.
+ */
+export declare function fetchWithTLS(url: string, options?: RequestInit): Promise<Response>;

package/dist/src/lib/generated-allowlist.d.ts

@@ -0,0 +1,28 @@
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Source of truth: the server step runners in `src/workflows/steps/*.ts` and
+ * the universal `BaseStepDefinition` shape in
+ * `src/workflows/runner/types.ts`.
+ *
+ * Regenerate with:
+ *   node cli/scripts/gen-allowlist.mjs       (runs automatically at CLI prebuild)
+ *
+ * A CI freshness guard (`cli/scripts/gen-allowlist.mjs --check`, also asserted
+ * by `cli/tests/unit/workflow-toml-validator-drift-guard.test.ts`) fails if this
+ * committed artifact does not match a fresh scan — see issue #998.
+ *
+ * Two exports:
+ *   - `GENERATED_ALLOWLISTED_FIELDS` — the union of universal step fields,
+ *     per-kind fields each runner READS (not what the type declares), and the
+ *     `collect` `step` structural pass-through. The validator accepts these as
+ *     top-level step fields for KNOWN kinds.
+ *   - `GENERATED_KNOWN_KINDS` — the step kinds the server registers. The
+ *     validator skips the per-field check for an UNKNOWN kind (an old CLI
+ *     against a newer server) while still running the kind-agnostic
+ *     misnested-header footgun detector (#685).
+ */
+/** Top-level step fields the validator accepts for a known kind (#998). */
+export declare const GENERATED_ALLOWLISTED_FIELDS: readonly string[];
+/** Step kinds the server registers (`defaultRegistry`). Unknown kinds skip the per-field check (#998). */
+export declare const GENERATED_KNOWN_KINDS: readonly string[];

package/dist/src/lib/generated-allowlist.js

@@ -0,0 +1,181 @@
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Source of truth: the server step runners in `src/workflows/steps/*.ts` and
+ * the universal `BaseStepDefinition` shape in
+ * `src/workflows/runner/types.ts`.
+ *
+ * Regenerate with:
+ *   node cli/scripts/gen-allowlist.mjs       (runs automatically at CLI prebuild)
+ *
+ * A CI freshness guard (`cli/scripts/gen-allowlist.mjs --check`, also asserted
+ * by `cli/tests/unit/workflow-toml-validator-drift-guard.test.ts`) fails if this
+ * committed artifact does not match a fresh scan — see issue #998.
+ *
+ * Two exports:
+ *   - `GENERATED_ALLOWLISTED_FIELDS` — the union of universal step fields,
+ *     per-kind fields each runner READS (not what the type declares), and the
+ *     `collect` `step` structural pass-through. The validator accepts these as
+ *     top-level step fields for KNOWN kinds.
+ *   - `GENERATED_KNOWN_KINDS` — the step kinds the server registers. The
+ *     validator skips the per-field check for an UNKNOWN kind (an old CLI
+ *     against a newer server) while still running the kind-agnostic
+ *     misnested-header footgun detector (#685).
+ */
+/** Top-level step fields the validator accepts for a known kind (#998). */
+export const GENERATED_ALLOWLISTED_FIELDS = [
+    "_testSteps",
+    "action",
+    "aliasKey",
+    "appId",
+    "as",
+    "asBase64",
+    "attachments",
+    "blobId",
+    "bodyMode",
+    "bucketId",
+    "bucketKey",
+    "cacheTtlSeconds",
+    "cases",
+    "concurrency",
+    "configId",
+    "content",
+    "contentBase64",
+    "contentType",
+    "context",
+    "continueOnError",
+    "cursor",
+    "cursorField",
+    "data",
+    "databaseId",
+    "default",
+    "description",
+    "direction",
+    "documentAlias",
+    "documentId",
+    "dryRun",
+    "durationMs",
+    "email",
+    "events",
+    "expiresInSeconds",
+    "feature",
+    "filename",
+    "filter",
+    "filters",
+    "forEach",
+    "groupBy",
+    "groupId",
+    "groupType",
+    "htmlBody",
+    "id",
+    "includeUserDetails",
+    "input",
+    "integrationKey",
+    "itemsField",
+    "iterationName",
+    "kind",
+    "limit",
+    "limits",
+    "maxItems",
+    "maxPages",
+    "message",
+    "messages",
+    "metrics",
+    "model",
+    "modelName",
+    "modelOverride",
+    "ms",
+    "multipartFields",
+    "name",
+    "onConflict",
+    "onPartialFailure",
+    "operationName",
+    "options",
+    "output",
+    "page",
+    "pageSize",
+    "params",
+    "payload",
+    "perUser",
+    "plugins",
+    "prompt",
+    "promptKey",
+    "query",
+    "queryType",
+    "recordId",
+    "ref",
+    "request",
+    "route",
+    "runIf",
+    "saveAs",
+    "scope",
+    "selector",
+    "sort",
+    "source",
+    "step",
+    "strict",
+    "subject",
+    "successWhen",
+    "tags",
+    "temperature",
+    "templateType",
+    "textBody",
+    "thinkingLevel",
+    "timeout",
+    "to",
+    "toUserId",
+    "tool_choice",
+    "tools",
+    "top_p",
+    "type",
+    "user",
+    "userId",
+    "userUlid",
+    "variables",
+    "windowDays",
+    "with",
+    "workflowKey",
+];
+/** Step kinds the server registers (`defaultRegistry`). Unknown kinds skip the per-field check (#998). */
+export const GENERATED_KNOWN_KINDS = [
+    "analytics.query",
+    "analytics.write",
+    "blob.download",
+    "blob.signedUrl",
+    "blob.upload",
+    "collect",
+    "database.aggregate",
+    "database.applyToQuery",
+    "database.count",
+    "database.mutate",
+    "database.pipeline",
+    "database.query",
+    "delay",
+    "document.count",
+    "document.delete",
+    "document.patch",
+    "document.query",
+    "document.queryOne",
+    "document.resolveAlias",
+    "document.save",
+    "email.send",
+    "event.wait",
+    "gemini.countTokens",
+    "gemini.generate",
+    "gemini.generateRaw",
+    "group.addMember",
+    "group.checkMembership",
+    "group.listMembers",
+    "group.listUserMemberships",
+    "group.removeMember",
+    "integration.call",
+    "iterate-users",
+    "llm.chat",
+    "noop",
+    "prompt.execute",
+    "script",
+    "switch",
+    "transform",
+    "workflow.call",
+];
+//# sourceMappingURL=generated-allowlist.js.map

package/dist/src/lib/generated-allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-allowlist.js","sourceRoot":"","sources":["../../../src/lib/generated-allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,4BAA4B,GAAsB;IAC7D,YAAY;IACZ,QAAQ;IACR,UAAU;IACV,OAAO;IACP,IAAI;IACJ,UAAU;IACV,aAAa;IACb,QAAQ;IACR,UAAU;IACV,UAAU;IACV,WAAW;IACX,iBAAiB;IACjB,OAAO;IACP,aAAa;IACb,UAAU;IACV,SAAS;IACT,eAAe;IACf,aAAa;IACb,SAAS;IACT,iBAAiB;IACjB,QAAQ;IACR,aAAa;IACb,MAAM;IACN,YAAY;IACZ,SAAS;IACT,aAAa;IACb,WAAW;IACX,eAAe;IACf,YAAY;IACZ,QAAQ;IACR,YAAY;IACZ,OAAO;IACP,QAAQ;IACR,kBAAkB;IAClB,SAAS;IACT,UAAU;IACV,QAAQ;IACR,SAAS;IACT,SAAS;IACT,SAAS;IACT,SAAS;IACT,WAAW;IACX,UAAU;IACV,IAAI;IACJ,oBAAoB;IACpB,OAAO;IACP,gBAAgB;IAChB,YAAY;IACZ,eAAe;IACf,MAAM;IACN,OAAO;IACP,QAAQ;IACR,UAAU;IACV,UAAU;IACV,SAAS;IACT,UAAU;IACV,SAAS;IACT,OAAO;IACP,WAAW;IACX,eAAe;IACf,IAAI;IACJ,iBAAiB;IACjB,MAAM;IACN,YAAY;IACZ,kBAAkB;IAClB,eAAe;IACf,SAAS;IACT,QAAQ;IACR,MAAM;IACN,UAAU;IACV,QAAQ;IACR,SAAS;IACT,SAAS;IACT,SAAS;IACT,QAAQ;IACR,WAAW;IACX,OAAO;IACP,WAAW;IACX,UAAU;IACV,KAAK;IACL,SAAS;IACT,OAAO;IACP,OAAO;IACP,QAAQ;IACR,OAAO;IACP,UAAU;IACV,MAAM;IACN,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,SAAS;IACT,aAAa;IACb,MAAM;IACN,aAAa;IACb,cAAc;IACd,UAAU;IACV,eAAe;IACf,SAAS;IACT,IAAI;IACJ,UAAU;IACV,aAAa;IACb,OAAO;IACP,OAAO;IACP,MAAM;IACN,MAAM;IACN,QAAQ;IACR,UAAU;IACV,WAAW;IACX,YAAY;IACZ,MAAM;IACN,aAAa;CACd,CAAC;AAEF,0GAA0G;AAC1G,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,iBAAiB;IACjB,iBAAiB;IACjB,eAAe;IACf,gBAAgB;IAChB,aAAa;IACb,SAAS;IACT,oBAAoB;IACpB,uBAAuB;IACvB,gBAAgB;IAChB,iBAAiB;IACjB,mBAAmB;IACnB,gBAAgB;IAChB,OAAO;IACP,gBAAgB;IAChB,iBAAiB;IACjB,gBAAgB;IAChB,gBAAgB;IAChB,mBAAmB;IACnB,uBAAuB;IACvB,eAAe;IACf,YAAY;IACZ,YAAY;IACZ,oBAAoB;IACpB,iBAAiB;IACjB,oBAAoB;IACpB,iBAAiB;IACjB,uBAAuB;IACvB,mBAAmB;IACnB,2BAA2B;IAC3B,oBAAoB;IACpB,kBAAkB;IAClB,eAAe;IACf,UAAU;IACV,MAAM;IACN,gBAAgB;IAChB,QAAQ;IACR,QAAQ;IACR,WAAW;IACX,eAAe;CAChB,CAAC"}

package/dist/src/lib/init-config.d.ts

@@ -0,0 +1,46 @@
+export declare const INIT_CONFIG_FILENAME = ".primitive-init.toml";
+export interface InitConfig {
+    /** Whether to create a new app or use an existing one */
+    action: "create" | "use-existing";
+    /** App name (required for action = "create") */
+    app_name?: string;
+    /** Existing app ID (required for action = "use-existing") */
+    app_id?: string;
+    /** Project directory name */
+    dir?: string;
+    /** Access mode for the app */
+    access_mode?: "public" | "domain" | "invite-only";
+    /** Port for local dev server */
+    dev_port?: number;
+    /** Whether to skip npm install */
+    skip_install?: boolean;
+    /** Custom server URL */
+    server?: string;
+    /** Email addresses to invite (for invite-only mode) */
+    invite_emails?: string[];
+    /** Allowed email domains (for domain mode) */
+    allowed_domains?: string[];
+    /** Whether to overwrite a non-empty target directory (default: false) */
+    overwrite?: boolean;
+    /** Target platform for the scaffolded app */
+    platform?: "web" | "ios";
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Parses a TOML string into an InitConfig object.
+ * Throws if the string contains invalid TOML.
+ */
+export declare function parseInitConfigToml(content: string): InitConfig;
+/**
+ * Loads and parses a .primitive-init.toml file from the given directory.
+ * Returns null if the file does not exist.
+ * Throws if the file exists but contains invalid TOML.
+ */
+export declare function loadInitConfig(dir: string): InitConfig | null;
+/**
+ * Validates an InitConfig object. Returns a ValidationResult with any errors.
+ */
+export declare function validateInitConfig(config: InitConfig): ValidationResult;