primitive-admin 1.1.0-alpha.8 → 1.1.0-alpha.80

package/dist/src/lib/db-codegen/generated-operation-def-descriptor.js

@@ -0,0 +1,211 @@
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Vendored byte-for-byte from the canonical server module
+ * `src/app-api/controllers/operation-definition-descriptor.ts` — the SAME
+ * allow-lists the server validator (`validateDefinition` / `validateParams`)
+ * enforces. The client operation-definition types
+ * (`src/client/api/operationDefinition.ts`) hand-author the matching union;
+ * a key-parity test compares them against this committed copy.
+ *
+ * Regenerate with:
+ *   node cli/scripts/gen-operation-def-descriptor.mjs   (runs at CLI prebuild)
+ *
+ * A CI freshness guard
+ * (`cli/scripts/gen-operation-def-descriptor.mjs --check`, also asserted by
+ * `cli/tests/unit/operation-def-descriptor-drift-guard.test.ts`) fails if
+ * this committed copy does not match the source — see issue #1544 / #1442.
+ */
+/**
+ * Canonical, dependency-free descriptor of the database operation-definition
+ * schema (issue #1544).
+ *
+ * The server validator (`validateDefinition` / `validateParams` in
+ * `database-type-operations-controller.ts`) and the CLIENT operation-definition
+ * types (`src/client/api/operationDefinition.ts`, consumed by
+ * `createOperation` / `updateOperation` / `DatabaseOperationInfo`) must agree on
+ * the set of operation types and the allowed keys for each definition shape —
+ * otherwise a hand-authored `OperationDefinition` member promises a key the
+ * runtime rejects (or omits one the runtime accepts).
+ *
+ * This module is the single source of that declarative contract: the op-type
+ * list, the per-type allowed definition-key sets, the per-type mutation/action
+ * op-name enums, and the param-schema key/type enums. The validator imports
+ * these constants directly (so a change here changes what the server enforces),
+ * and the CLI vendors a byte-for-byte copy as a committed artifact via
+ * `cli/scripts/gen-operation-def-descriptor.mjs` (the #1442 workflow
+ * schema-descriptor pattern). A drift-guard test runs that generator in
+ * `--check` mode, and a key-parity test asserts the hand-authored client type
+ * members' keys equal the corresponding allow-lists here — so the validator and
+ * the client types can never silently diverge. The CLI never imports server
+ * `src/` at runtime; only the build-time generator reads this file.
+ *
+ * The value-shape checks that are NOT purely declarative (requiredness, nested
+ * object structure, CEL parsing) stay imperative in the validator. This
+ * descriptor captures the declarative allow-lists — the part that is genuinely
+ * shared between the runtime boundary and the descriptive client types.
+ *
+ * Ordering is significant: the validator joins these arrays into its 400-level
+ * error messages (`Must be one of: ${X.join(", ")}`), so reordering an array
+ * changes an error string. Keep entries in their current order.
+ */
+/** The operation `type` values accepted by `createOperation` / `updateOperation`. */
+export const OPERATION_TYPES = [
+    "query",
+    "mutation",
+    "count",
+    "aggregate",
+    "pipeline",
+    "applyToQuery",
+];
+// ── Per-type definition key allow-lists ──
+/** Allowed top-level keys in a `query` definition. `cache` (#1247) is query-only. */
+export const QUERY_DEF_KEYS = [
+    "filter",
+    "sort",
+    "limit",
+    "projection",
+    "include",
+    "cache",
+];
+/** Allowed top-level keys in a `mutation` definition. */
+export const MUTATION_DEF_KEYS = ["operations"];
+/** Allowed top-level keys in a `count` definition. */
+export const COUNT_DEF_KEYS = ["filter"];
+/** Allowed top-level keys in an `aggregate` definition. */
+export const AGGREGATE_DEF_KEYS = [
+    "groupBy",
+    "operations",
+    "filter",
+    "limit",
+    "sort",
+];
+/** Allowed top-level keys in a `pipeline` definition. */
+export const PIPELINE_DEF_KEYS = ["steps", "return"];
+/** Allowed top-level keys in an `applyToQuery` definition. */
+export const APPLY_TO_QUERY_DEF_KEYS = ["source", "action"];
+// ── Op-name enums nested inside definitions ──
+/** Mutation op names allowed in a `mutation` definition's `operations[]`. */
+export const MUTATION_OPS = [
+    "save",
+    "patch",
+    "delete",
+    "increment",
+    "addToSet",
+    "removeFromSet",
+];
+/**
+ * Aggregate op `type` names allowed in an `aggregate` definition's
+ * `operations[]`.
+ */
+export const AGGREGATE_OP_TYPES = [
+    "count",
+    "sum",
+    "avg",
+    "min",
+    "max",
+];
+/**
+ * Allowed keys on a single nested aggregate op (an entry in an `aggregate`
+ * definition's `operations[]`, and in a pipeline `aggregate` step's
+ * `operations[]`). Only `type` and `field` are honored by the runtime — the
+ * aggregate SELECT always aliases columns to the fixed output names
+ * (`count` / `<type>_<field>`), so there is no supported way to rename an
+ * output. `outputField` was historically accepted here but read by no code
+ * (issue #1767); any key outside this list is now rejected at registration so
+ * dead config can't be silently stored.
+ */
+export const AGGREGATE_OP_KEYS = ["type", "field"];
+/**
+ * `applyToQuery` action ops. Only mutation ops that operate on existing matched
+ * records — `save` is excluded because it makes no sense in a find-and-mutate
+ * flow.
+ */
+export const APPLY_TO_QUERY_ACTIONS = [
+    "delete",
+    "patch",
+    "increment",
+    "addToSet",
+    "removeFromSet",
+];
+/** Allowed keys in an `applyToQuery` `source` block. */
+export const APPLY_TO_QUERY_SOURCE_KEYS = [
+    "filter",
+    "sort",
+    "limit",
+];
+/** Allowed keys in an `applyToQuery` `action` block. */
+export const APPLY_TO_QUERY_ACTION_KEYS = [
+    "op",
+    "data",
+    "fields",
+    "stringSets",
+];
+// ── Pipeline step allow-lists ──
+/** Step `type` values allowed inside a `pipeline` definition's `steps[]`. */
+export const PIPELINE_STEP_TYPES = [
+    "query",
+    "count",
+    "aggregate",
+];
+/** Allowed keys on a pipeline `query` step. */
+export const PIPELINE_QUERY_STEP_KEYS = [
+    "name",
+    "type",
+    "modelName",
+    "filter",
+    "sort",
+    "limit",
+    "projection",
+    "include",
+];
+/** Allowed keys on a pipeline `count` step. */
+export const PIPELINE_COUNT_STEP_KEYS = [
+    "name",
+    "type",
+    "modelName",
+    "filter",
+];
+/** Allowed keys on a pipeline `aggregate` step. */
+export const PIPELINE_AGGREGATE_STEP_KEYS = [
+    "name",
+    "type",
+    "modelName",
+    "groupBy",
+    "operations",
+    "filter",
+    "limit",
+    "sort",
+];
+// ── Param-schema enums ──
+/**
+ * Built-in param types. `integer` (#1488) is accepted here and by the runtime
+ * coercion path. `array` (#1488) declares a list param with a scalar `items`
+ * element type. Keep in step with the runtime coercion list
+ * (`MODEL_PARAM_SCALAR_TYPES` in `database-operations-controller.ts`).
+ */
+export const PARAM_TYPES = [
+    "string",
+    "number",
+    "boolean",
+    "integer",
+    "object",
+    "array",
+];
+/** Scalar element types allowed for an `array` param's `items` (#1488). */
+export const ARRAY_ELEMENT_TYPES = [
+    "string",
+    "number",
+    "boolean",
+    "integer",
+];
+/** Allowed keys in a single param definition. */
+export const PARAM_DEF_KEYS = [
+    "type",
+    "required",
+    "access",
+    "coerce",
+    "enum",
+    "items",
+];
+//# sourceMappingURL=generated-operation-def-descriptor.js.map

package/dist/src/lib/db-codegen/generated-operation-def-descriptor.js.map

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

package/dist/src/lib/document-export-permissions.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The `permissions.json` rows `primitive documents export` writes.
+ *
+ * Extracted from `exportSingleDocument` (#2951) so the shape change it went
+ * through is testable without a server. The export used to merge the legacy
+ * `GET /documents/:id/invitations` array — filtering `accepted` and
+ * `expiresAt` client-side — into the permission rows. That route is removed;
+ * pending entries now come from `GET /documents/:id/pending-invitations`,
+ * which returns a `{ items }` envelope of deferred grants the server has
+ * already filtered down to unresolved, unexpired, still-invited ones.
+ *
+ * The export tolerates the pending read failing (an older server answers 403
+ * or 404): the caller swallows the error and passes `null`, and the export
+ * still writes the permission rows.
+ */
+export interface ExportedPermissionRow {
+    email: string;
+    permission: string;
+    grantedAt?: string;
+    source?: "invitation";
+    status?: "pending";
+}
+/**
+ * Merge a document's permission rows and its pending deferred grants into the
+ * single email-keyed list `permissions.json` carries.
+ *
+ * @param permissionsResponse - `GET /documents/:id/permissions`, or `null` when the read failed.
+ * @param pendingResponse - `GET /documents/:id/pending-invitations`, or `null` when the read failed.
+ */
+export declare function buildPermissionsExport(permissionsResponse: unknown, pendingResponse: unknown): ExportedPermissionRow[];

package/dist/src/lib/document-export-permissions.js

@@ -0,0 +1,54 @@
+/**
+ * The `permissions.json` rows `primitive documents export` writes.
+ *
+ * Extracted from `exportSingleDocument` (#2951) so the shape change it went
+ * through is testable without a server. The export used to merge the legacy
+ * `GET /documents/:id/invitations` array — filtering `accepted` and
+ * `expiresAt` client-side — into the permission rows. That route is removed;
+ * pending entries now come from `GET /documents/:id/pending-invitations`,
+ * which returns a `{ items }` envelope of deferred grants the server has
+ * already filtered down to unresolved, unexpired, still-invited ones.
+ *
+ * The export tolerates the pending read failing (an older server answers 403
+ * or 404): the caller swallows the error and passes `null`, and the export
+ * still writes the permission rows.
+ */
+/** Unwrap a list that may arrive bare, or under `items`, or under a named key. */
+function rows(value, key) {
+    if (Array.isArray(value))
+        return value;
+    if (value && typeof value === "object") {
+        const envelope = value;
+        for (const candidate of ["items", key]) {
+            if (Array.isArray(envelope[candidate]))
+                return envelope[candidate];
+        }
+    }
+    return [];
+}
+/**
+ * Merge a document's permission rows and its pending deferred grants into the
+ * single email-keyed list `permissions.json` carries.
+ *
+ * @param permissionsResponse - `GET /documents/:id/permissions`, or `null` when the read failed.
+ * @param pendingResponse - `GET /documents/:id/pending-invitations`, or `null` when the read failed.
+ */
+export function buildPermissionsExport(permissionsResponse, pendingResponse) {
+    const granted = rows(permissionsResponse, "permissions")
+        .filter((p) => p?.email)
+        .map((p) => ({
+        email: p.email,
+        permission: p.permission,
+        grantedAt: p.grantedAt,
+    }));
+    const pending = rows(pendingResponse, "invitations")
+        .filter((i) => i?.email)
+        .map((i) => ({
+        email: i.email,
+        permission: i.permission,
+        source: "invitation",
+        status: "pending",
+    }));
+    return [...granted, ...pending];
+}
+//# sourceMappingURL=document-export-permissions.js.map

package/dist/src/lib/document-export-permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-export-permissions.js","sourceRoot":"","sources":["../../../src/lib/document-export-permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,kFAAkF;AAClF,SAAS,IAAI,CAAC,KAAc,EAAE,GAAW;IACvC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,KAAgC,CAAC;QAClD,KAAK,MAAM,SAAS,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;YACvC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;gBAAE,OAAO,QAAQ,CAAC,SAAS,CAAU,CAAC;QAC9E,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,mBAA4B,EAC5B,eAAwB;IAExB,MAAM,OAAO,GAAG,IAAI,CAAC,mBAAmB,EAAE,aAAa,CAAC;SACrD,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC;SAC5B,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC;QAChB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,SAAS,EAAE,CAAC,CAAC,SAAS;KACvB,CAAC,CAAC,CAAC;IAEN,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC;SACjD,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC;SAC5B,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC;QAChB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,MAAM,EAAE,YAAqB;QAC7B,MAAM,EAAE,SAAkB;KAC3B,CAAC,CAAC,CAAC;IAEN,OAAO,CAAC,GAAG,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC;AAClC,CAAC"}

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

@@ -0,0 +1,253 @@
+/**
+ * The shared Primitive environment resolver (#2873).
+ *
+ * Three surfaces have to agree on which backend/app a project is pointed at:
+ * the CLI, the Vue build (`primitive-app`'s `primitiveEnv()` plugin), and the
+ * Swift template's pre-build script. This module is the single algorithm they
+ * share. The CLI owns it; `packages/primitive-app` carries a byte-identical
+ * GENERATED copy (`cli/scripts/gen-primitive-env-resolver.mjs`, checked for
+ * freshness by `cli/tests/unit/env-resolver-copy-drift-guard.test.ts`); the
+ * Swift script is an independent bash+python3 port pinned by a parity test.
+ *
+ * ── COPYABILITY (load-bearing) ────────────────────────────────────────────
+ * This file MUST stay self-contained: node builtins only, ZERO relative
+ * imports. The generator copies it verbatim into a package that cannot depend
+ * on the CLI, so any `./x.js` import here would break that copy at runtime.
+ * The drift guard asserts this.
+ *
+ * Scope: config discovery, the schema `version` check, structural validation,
+ * the local selection, the precedence, and the http→ws scheme swap. It
+ * deliberately does NOT duplicate the CLI's full field-level validation
+ * (`validateProjectConfig` in `project-config.ts`) — the CLI wrapper runs that
+ * first, and the other readers only need "version understood, shape sane, fail
+ * loudly otherwise".
+ *
+ * Precedence (one order, everywhere):
+ *   1. an explicit name (`--env` / `--primitive-env`)
+ *   2. PRIMITIVE_ENV                (per-invocation intent, keeps CI working)
+ *   3. .primitive/local.json        (this machine's `primitive env use`)
+ *   4. defaultEnvironment           (the committed team default)
+ *   5. the sole environment, if there is exactly one
+ */
+/** Schema version of `primitive/config.json` this core understands. */
+export declare const PRIMITIVE_CONFIG_VERSION = 1;
+/** Schema version of `.primitive/local.json` this core writes and reads. */
+export declare const PRIMITIVE_LOCAL_STATE_VERSION = 1;
+/**
+ * The two directories, split apart by #3153 so one name never means two
+ * things: `primitive/` is the COMMITTED tree (the config and every
+ * environment's TOML), `.primitive/` is MACHINE-LOCAL state (credentials, this
+ * machine's selection, snapshot backups) and is gitignored whole.
+ */
+export declare const PROJECT_TREE_DIR = "primitive";
+export declare const PROJECT_LOCAL_STATE_DIR = ".primitive";
+export declare const PROJECT_CONFIG_FILENAME = "config.json";
+export declare const LOCAL_STATE_FILENAME = "local.json";
+export declare const PROJECT_CONFIG_DISPLAY_NAME = "primitive/config.json";
+export declare const LOCAL_STATE_DISPLAY_NAME = ".primitive/local.json";
+/** The docs-site slug of the migration procedure (#3155 publishes the page). */
+export declare const MIGRATION_GUIDE_SLUG = "getting-started/cli-project-migration";
+/**
+ * The one refusal for a project still holding the pre-#3153 layout.
+ *
+ * There is no fallback read: a tool that quietly read `.primitive/sync/` after
+ * the move would let a half-migrated project look healthy while push and pull
+ * disagreed about which tree is the truth. So every reader — this core, the
+ * generated Vite-plugin copy, the Swift pre-build script — stops here and names
+ * the document that says what to move where.
+ */
+export declare function staleLayoutMessage(detail: string): string;
+/**
+ * The one refusal for a command run outside a Primitive project (#3154,
+ * intent criterion 5).
+ *
+ * There is exactly one way to resolve the configuration tree, the credentials
+ * and the app: the environment named by `primitive/config.json`. Outside a
+ * project there is no such thing, and the CLI says so once, in these words,
+ * wherever the question is asked — the resolver core, the CLI's
+ * `requireCurrentEnvironment()`, and the credentials store.
+ *
+ * Two constraints on the wording, both test-asserted:
+ *
+ *   - it names `primitive init`, the one command that creates what is missing;
+ *   - it never names `primitive env add`, which after this change also fails
+ *     outside a project — an error may only offer an invocation it does not
+ *     itself block.
+ */
+export declare function missingConfigMessage(where: string): string;
+/**
+ * Error kinds callers branch on. Every failure is one of these — no reader is
+ * ever left guessing what a broken config meant.
+ */
+export type PrimitiveEnvErrorKind = "missing-config" | "malformed-config" | "unsupported-version" | "corrupt-local-state" | "unknown-environment" | "no-selection" | "missing-app-id" | "stale-layout";
+export declare class PrimitiveEnvError extends Error {
+    readonly kind: PrimitiveEnvErrorKind;
+    readonly path?: string;
+    constructor(kind: PrimitiveEnvErrorKind, message: string, path?: string);
+}
+export interface CoreEnvironmentEntry {
+    apiUrl: string;
+    /**
+     * The one app this environment names (#3152). Required: selecting an
+     * environment selects exactly one app, so there is no per-machine "current
+     * app" for a second reader to disagree with.
+     */
+    appId: string;
+    appName?: string;
+    /**
+     * The app's web counterpart for this environment, as a normalized origin
+     * (#2982). Read through `normalizeWebOrigin`, so a value this reader carries
+     * is always an origin — see that function for why the typed read other
+     * fields get is not enough here.
+     */
+    webUrl?: string;
+    description?: string;
+}
+/**
+ * The app's web counterpart as a normalized ORIGIN, or undefined when the
+ * value cannot be one (#2982).
+ *
+ * Unlike `appId`/`appName`, a typed read is not enough. This value is not
+ * merely carried: the Swift app points its emailed sign-in link at
+ * `<webUrl>/oauth/callback` and trusts incoming universal links from the same
+ * origin, and BOTH jobs need an origin —
+ *
+ *   - https except loopback, the rule the server applies to every redirect URI
+ *     (`src/auth/redirect-uri.ts`): an origin that cannot be allow-listed turns
+ *     every sign-in request into a 400, and a plain-http link would carry the
+ *     magic token in clear;
+ *   - no path, query or fragment: the web client serves its callback on its own
+ *     origin plus `/oauth/callback`, which is also the exact path the
+ *     `apple-app-site-association` component claims;
+ *   - no credentials, which have no business in a link that goes out by email.
+ *
+ * `primitive env add --web-url` and the project-config validation reject those
+ * shapes with a field-named error, but neither is on the path from a
+ * hand-edited `.primitive/config.json` to an Xcode build: the Swift template's
+ * pre-build script reads the file directly. So every reader that feeds
+ * `primitive.json` applies the contract, and a value that misses it is read as
+ * "this environment has no web counterpart" — code-only email, no trusted
+ * origin, nothing silently pointed at the wrong URL.
+ *
+ * The message-producing twin of this rule lives in `cli/src/lib/web-url.ts`;
+ * this file cannot import it (see COPYABILITY above), and a test pins that the
+ * two agree.
+ */
+export declare function normalizeWebOrigin(value: unknown): string | undefined;
+/**
+ * The one remedy for an environment that names no app (#3152), shared by every
+ * reader that can hit it: this core, the CLI's `validateProjectConfig`, the
+ * Swift template's pre-build script, and the Vue template's cf-deploy.
+ *
+ * Two constraints on the wording, both test-asserted:
+ *
+ *   - it never says `primitive env add <name>`, which REFUSES an environment
+ *     name that already exists — the shape this error is always about;
+ *   - it names no command the failure itself blocks. The CLI validates the
+ *     project config before any command parses, so every `primitive` command
+ *     run inside the broken project fails with this same error. The only
+ *     invocation it may offer is one it says out loud to run elsewhere.
+ */
+export declare function missingAppIdMessage(name: string, configPath?: string): string;
+export interface CoreProjectConfig {
+    version: number;
+    defaultEnvironment?: string;
+    environments: Record<string, CoreEnvironmentEntry>;
+}
+/** Which precedence step picked the environment. Printed in the build banner. */
+export type PrimitiveEnvSource = "explicit" | "env-var" | "local" | "default" | "sole";
+export interface ResolvedPrimitiveEnv {
+    name: string;
+    apiUrl: string;
+    /** Derived from apiUrl by scheme swap — never authored separately. */
+    wsUrl: string;
+    /** The app this environment names. Always present — see #3152. */
+    appId: string;
+    appName?: string;
+    /** The app's web counterpart for the SELECTED environment, if it has one. */
+    webUrl?: string;
+    description?: string;
+    source: PrimitiveEnvSource;
+    configPath: string;
+    localStatePath: string;
+    projectRoot: string;
+}
+export interface ResolveOptions {
+    /** Directory to start the upward walk from. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Environment variables to read. Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+    /** An explicit `--env` / `--primitive-env` value, if the caller has one. */
+    explicitEnvName?: string | null;
+    /** Use this config file instead of discovering one. */
+    configPath?: string;
+}
+/**
+ * Derives the WebSocket URL from the API URL. Every apiUrl/wsUrl pair in
+ * practice is the same host with the scheme swapped, so it is derived rather
+ * than authored — one less thing to get out of sync.
+ */
+export declare function deriveWsUrl(apiUrl: string): string;
+/**
+ * Finds `primitive/config.json` by walking up from `cwd`, or returns the
+ * PRIMITIVE_PROJECT_CONFIG override when it is set (and exists).
+ *
+ * The override is checked for provenance BEFORE the file is read (#3153, F2):
+ * it bypasses the walk, so without this an old-layout config could be handed
+ * straight to a reader and defeat the cutover.
+ *
+ * Every return is checked against the root it implies, not just the levels the
+ * walk passed through: this is the one function every reader goes through —
+ * `resolvePrimitiveEnv` and the CLI's own `loadProjectConfig`/`findProjectRoot`
+ * alike — so a half-migrated project must be refused HERE, or the commands that
+ * never call `resolvePrimitiveEnv` would read the new tree with the old one
+ * still beside it.
+ */
+export declare function findPrimitiveConfigPath(options?: {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+}): string | null;
+/**
+ * The project root for a config path: the parent of `primitive/`, or the
+ * containing directory when the config was pointed at directly (a fixture via
+ * PRIMITIVE_PROJECT_CONFIG, which is not inside a `primitive/` directory).
+ */
+export declare function projectRootForConfigPath(configPath: string): string;
+/**
+ * Machine-local state lives under the project root's `.primitive/`, not beside
+ * the config — the config is committed now, and the two must not share a
+ * directory. A fixture-pointed bare config still gets its own `.primitive/`
+ * in its own directory, so it never picks up a real project's selection.
+ */
+export declare function localStatePathForConfigPath(configPath: string): string;
+/**
+ * Reads and structurally validates `.primitive/config.json`. Throws rather
+ * than guessing: a config that cannot be understood is always louder than a
+ * silent fallback to the wrong backend.
+ */
+export declare function readCoreProjectConfig(configPath: string): CoreProjectConfig;
+/**
+ * Reads this machine's selection from `.primitive/local.json`. Returns null
+ * when there is no file or no selection in it; throws when the file exists but
+ * cannot be read as the shape `primitive env use` writes.
+ */
+export declare function readLocalSelection(configPath: string): string | null;
+/**
+ * Applies the precedence to an already-loaded config. Exposed separately so
+ * the CLI wrapper can run its own field-level validation first and still share
+ * one ordering with every other reader.
+ */
+export declare function selectEnvironmentName(config: CoreProjectConfig, options: {
+    explicitEnvName?: string | null;
+    envVarName?: string | null;
+    localSelection?: string | null;
+    configPath?: string;
+}): {
+    name: string;
+    source: PrimitiveEnvSource;
+};
+/**
+ * The whole algorithm end to end: discover the config, read the selection,
+ * apply the precedence, derive the WebSocket URL.
+ */
+export declare function resolvePrimitiveEnv(options?: ResolveOptions): ResolvedPrimitiveEnv;