primitive-admin 1.1.0-alpha.4 → 1.1.0-alpha.41

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

@@ -0,0 +1,159 @@
+/**
+ * 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`.
+ */
+import { tsTypeForDbField, tsTypeForDbParamType } from "./dbTsTypes.js";
+const HEADER_BANNER = "// AUTO-GENERATED FROM database-types TOML — DO NOT EDIT.";
+const REGEN_INSTRUCTION = "// Run `primitive databases codegen <database-type>` to regenerate.";
+/** The shared generic result aliases, keyed off `op.type`. */
+export const RESULT_ALIASES_BLOCK = `// Generic per-op result shapes, keyed off the operation type. The op
+// return contract is NOT stored in the TOML — these mirror the runtime
+// result shapes produced by the database-operations controller.
+
+/** \`query\` ops return a page of records. */
+export interface QueryResult<T = Record<string, unknown>> {
+  data: T[];
+  hasMore?: boolean;
+  nextCursor?: string;
+}
+
+/** \`mutation\` ops return per-step results. */
+export interface MutationResult {
+  results: unknown[];
+}
+
+/** \`count\` ops return a single count. */
+export interface CountResult {
+  count: number;
+}
+
+/** \`aggregate\` ops return a single result object. */
+export interface AggregateResult {
+  result: Record<string, unknown>;
+}
+
+/** \`applyToQuery\` ops return match/affect/fail counts. */
+export interface ApplyToQueryResult {
+  matched: number;
+  affected: number;
+  failed: number;
+  sample?: unknown[];
+}
+
+/** \`pipeline\` ops return per-step results keyed by step name. */
+export interface PipelineResult {
+  steps: Record<string, unknown>;
+}
+`;
+/**
+ * Render the header (banner + regen hint + fingerprint).
+ */
+export function renderHeader(fingerprint) {
+    return [
+        HEADER_BANNER,
+        REGEN_INSTRUCTION,
+        `// fingerprint: ${fingerprint}`,
+    ].join("\n");
+}
+/**
+ * Render a single record interface (read shape). Stamped fields
+ * (`createdAt`, `modifiedAt`, `ownerId`, …) are appended as OPTIONAL props
+ * if not already present in `fields`.
+ */
+export function renderRecordInterface(input) {
+    const { interfaceName, fields, stampedFields } = input;
+    const memberLines = [];
+    const declared = new Set();
+    for (const f of fields) {
+        declared.add(f.name);
+        const optional = f.required ? "" : "?";
+        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
+    // them yet, so claiming them as required would be a type lie.
+    for (const stamped of stampedFields) {
+        if (declared.has(stamped))
+            continue;
+        declared.add(stamped);
+        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");
+}
+/**
+ * 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 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) {
+        const optional = p.required ? "" : "?";
+        lines.push(`  ${p.name}${optional}: ${tsTypeForDbParamType(p.type, p.enum)};`);
+    }
+    lines.push(`}`);
+    return lines.join("\n");
+}
+/**
+ * Render a per-op result alias keyed off `op.type`.
+ */
+export function renderOpResultAlias(input) {
+    const { aliasName, opType, recordInterfaceName } = input;
+    switch (opType) {
+        case "query": {
+            const generic = recordInterfaceName ?? "Record<string, unknown>";
+            return `export type ${aliasName} = QueryResult<${generic}>;`;
+        }
+        case "mutation":
+            return `export type ${aliasName} = MutationResult;`;
+        case "count":
+            return `export type ${aliasName} = CountResult;`;
+        case "aggregate":
+            return `export type ${aliasName} = AggregateResult;`;
+        case "applyToQuery":
+            return `export type ${aliasName} = ApplyToQueryResult;`;
+        case "pipeline":
+            return `export type ${aliasName} = PipelineResult;`;
+        default:
+            // Unknown op type — emit a permissive alias rather than throwing,
+            // so one stray op doesn't block codegen for the whole file.
+            return `export type ${aliasName} = unknown;`;
+    }
+}
+//# sourceMappingURL=dbTemplates.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dbTemplates.js","sourceRoot":"","sources":["../../../../src/lib/db-codegen/dbTemplates.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,112 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function tsTypeForDbFieldType(fieldType) {
+    switch (fieldType) {
+        case "string":
+        case "id":
+        case "date":
+            return "string";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "stringset":
+            // StringSet serializes to a string array on the wire.
+            return "string[]";
+        default:
+            return "unknown";
+    }
+}
+/**
+ * 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 function tsUnionFromEnum(values) {
+    return values.map((v) => JSON.stringify(v)).join(" | ");
+}
+/**
+ * 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 function tsTypeForDbField(fieldType, enumValues) {
+    if (fieldType === "string" &&
+        Array.isArray(enumValues) &&
+        enumValues.length > 0) {
+        return tsUnionFromEnum(enumValues);
+    }
+    return tsTypeForDbFieldType(fieldType);
+}
+/**
+ * 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 function tsTypeForDbParamType(paramType, enumValues) {
+    if (paramType === "string" &&
+        Array.isArray(enumValues) &&
+        enumValues.length > 0) {
+        return tsUnionFromEnum(enumValues);
+    }
+    switch (paramType) {
+        case "string":
+            return "string";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "object":
+            return "Record<string, unknown>";
+        default:
+            return "unknown";
+    }
+}
+//# sourceMappingURL=dbTsTypes.js.map

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

@@ -0,0 +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,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/env-resolver.js

@@ -0,0 +1,121 @@
+/**
+ * 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 { loadProjectConfig, findProjectConfigPath, findProjectRoot, PROJECT_CONFIG_DISPLAY_NAME, } from "./project-config.js";
+/** Process-lifetime cache for resolution results. */
+let cachedResolution;
+let explicitEnvName = null;
+let cachedProjectConfig;
+/**
+ * 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 function setCurrentEnvName(name) {
+    explicitEnvName = name;
+    // Invalidate any cached resolution so the next getCurrentEnvironment()
+    // picks up the new override.
+    cachedResolution = undefined;
+}
+/**
+ * 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 function resetEnvResolver() {
+    cachedResolution = undefined;
+    cachedProjectConfig = undefined;
+}
+/**
+ * Loads and caches the project config. Returns null if no
+ * .primitive/config.json is present. Throws ProjectConfigError on a broken config.
+ */
+export function getProjectConfig() {
+    if (cachedProjectConfig === undefined) {
+        cachedProjectConfig = loadProjectConfig();
+    }
+    return cachedProjectConfig ?? 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 function getCurrentEnvironment() {
+    if (cachedResolution !== undefined)
+        return cachedResolution;
+    const project = getProjectConfig();
+    if (!project) {
+        cachedResolution = null;
+        return null;
+    }
+    const configPath = findProjectConfigPath();
+    const projectRoot = findProjectRoot();
+    // Determine the environment name.
+    const requested = explicitEnvName ??
+        process.env.PRIMITIVE_ENV ??
+        project.defaultEnvironment ??
+        null;
+    let name;
+    if (requested) {
+        if (!project.environments[requested]) {
+            const available = Object.keys(project.environments).join(", ") || "(none)";
+            throw new Error(`Environment "${requested}" is not defined in ${PROJECT_CONFIG_DISPLAY_NAME}. Available: ${available}`);
+        }
+        name = requested;
+    }
+    else {
+        const names = Object.keys(project.environments);
+        if (names.length === 1) {
+            name = names[0];
+        }
+        else if (names.length === 0) {
+            throw new Error(`${PROJECT_CONFIG_DISPLAY_NAME} has no environments defined. Run 'primitive env add <name>' or 'primitive init'.`);
+        }
+        else {
+            throw new Error(`No environment selected. Set "defaultEnvironment" in ${PROJECT_CONFIG_DISPLAY_NAME}, pass --env <name>, or export PRIMITIVE_ENV. Available: ${names.join(", ")}`);
+        }
+    }
+    cachedResolution = {
+        name,
+        config: project.environments[name],
+        projectConfigPath: configPath,
+        projectRoot,
+    };
+    return cachedResolution;
+}
+/**
+ * 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 function getCurrentEnvNameSafe() {
+    try {
+        return getCurrentEnvironment()?.name ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns the explicit name set via setCurrentEnvName(), for commands that
+ * need to know whether the user passed --env vs. relying on defaults.
+ */
+export function getExplicitEnvName() {
+    return explicitEnvName;
+}
+//# sourceMappingURL=env-resolver.js.map

package/dist/src/lib/env-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-resolver.js","sourceRoot":"","sources":["../../../src/lib/env-resolver.ts"],"names":[],"mappings":"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"}

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>;