primitive-admin 1.1.0-alpha.9 → 1.1.0

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

@@ -0,0 +1,447 @@
+/**
+ * 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
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+/** Schema version of `primitive/config.json` this core understands. */
+export const PRIMITIVE_CONFIG_VERSION = 1;
+/** Schema version of `.primitive/local.json` this core writes and reads. */
+export 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 const PROJECT_TREE_DIR = "primitive";
+export const PROJECT_LOCAL_STATE_DIR = ".primitive";
+export const PROJECT_CONFIG_FILENAME = "config.json";
+export const LOCAL_STATE_FILENAME = "local.json";
+export const PROJECT_CONFIG_DISPLAY_NAME = "primitive/config.json";
+export const LOCAL_STATE_DISPLAY_NAME = ".primitive/local.json";
+/**
+ * The one refusal for a project that never migrated off the pre-#3153 layout:
+ * a `.primitive/config.json` with no `primitive/config.json` beside it.
+ *
+ * That shape is refused rather than walked past because the walk's next stop
+ * is the parent directory, and in a nested checkout the parent may be a
+ * DIFFERENT project — a command run in the unmigrated one would silently act
+ * on the other's app. Nothing else is refused (#3392): anything left under
+ * `.primitive/` beside a migrated tree is machine-local junk, not signal.
+ *
+ * One sentence, naming both halves — the file that was found and the file
+ * that is expected — and no document. The migration page this once pointed
+ * at was never published (#3155, won't-fix), and every reader that shares
+ * this refusal — this core, the generated Vite-plugin copy, the Swift
+ * pre-build script, the Vue template's deploy script — says the same thing.
+ */
+export function unmigratedProjectMessage(found, expected) {
+    return (`Found ${found} but no ${expected}: this project still uses the retired ` +
+        `layout under ${PROJECT_LOCAL_STATE_DIR}/, which is never read.`);
+}
+/**
+ * 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 function missingConfigMessage(where) {
+    return (`No ${PROJECT_CONFIG_DISPLAY_NAME} found in ${where} or any parent directory. ` +
+        `Primitive commands run inside a Primitive project: it is where the CLI reads ` +
+        `the environment, the app that environment names, and the configuration tree ` +
+        `from. Run 'primitive init' to create one.`);
+}
+export class PrimitiveEnvError extends Error {
+    kind;
+    path;
+    constructor(kind, message, path) {
+        super(message);
+        this.name = "PrimitiveEnvError";
+        this.kind = kind;
+        this.path = path;
+    }
+}
+/**
+ * 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 function normalizeWebOrigin(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return undefined;
+    if (url.protocol === "http:" &&
+        url.hostname !== "localhost" &&
+        url.hostname !== "127.0.0.1") {
+        return undefined;
+    }
+    if (url.username || url.password)
+        return undefined;
+    if (url.pathname !== "/" && url.pathname !== "")
+        return undefined;
+    if (url.search || url.hash)
+        return undefined;
+    return url.origin;
+}
+/**
+ * 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 function missingAppIdMessage(name, configPath) {
+    const where = configPath
+        ? `${PROJECT_CONFIG_DISPLAY_NAME} (${configPath})`
+        : PROJECT_CONFIG_DISPLAY_NAME;
+    return (`Environment "${name}" in ${where} has no "appId". ` +
+        `Every environment names exactly one app — add "appId": "<app-id>" to that environment in ${PROJECT_CONFIG_DISPLAY_NAME}. ` +
+        `Find the app id in the Primitive admin UI, with 'primitive apps list' run from another Primitive project, ` +
+        `or as the residual "currentAppId" in .primitive/credentials.json if this environment was ever pointed at an app by the retired per-machine app selection.`);
+}
+/**
+ * An environment's `appId` as a usable string, or undefined when the value
+ * cannot be one. Non-string and blank-after-trim are both "no app named": a
+ * numeric or whitespace appId reaches a consumer as an app id it cannot use,
+ * which is the silent version of the failure this field exists to prevent.
+ */
+function readAppId(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+/**
+ * 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 function deriveWsUrl(apiUrl) {
+    if (apiUrl.startsWith("https://"))
+        return "wss://" + apiUrl.slice("https://".length);
+    if (apiUrl.startsWith("http://"))
+        return "ws://" + apiUrl.slice("http://".length);
+    return apiUrl;
+}
+/**
+ * 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. An override that points inside
+ * a `.primitive/` directory IS the old layout, named explicitly.
+ *
+ * This is the one function every reader goes through — `resolvePrimitiveEnv`
+ * and the CLI's own `loadProjectConfig`/`findProjectRoot` alike — so the
+ * unmigrated-project refusal lives HERE, in the walk, or the commands that
+ * never call `resolvePrimitiveEnv` would walk past the old anchor into the
+ * parent directory's project.
+ */
+export function findPrimitiveConfigPath(options = {}) {
+    const env = options.env ?? process.env;
+    const override = env.PRIMITIVE_PROJECT_CONFIG;
+    if (override) {
+        const forced = resolve(override);
+        if (basename(dirname(forced)) === PROJECT_LOCAL_STATE_DIR) {
+            throw new PrimitiveEnvError("stale-layout", unmigratedProjectMessage(forced, join(dirname(dirname(forced)), PROJECT_TREE_DIR, PROJECT_CONFIG_FILENAME)), forced);
+        }
+        return existsSync(forced) ? forced : null;
+    }
+    let current = resolve(options.cwd ?? process.cwd());
+    while (true) {
+        const candidate = join(current, PROJECT_TREE_DIR, PROJECT_CONFIG_FILENAME);
+        if (existsSync(candidate))
+            return candidate;
+        // No anchor here. The old one means this directory IS a project — one
+        // that never migrated — and the walk stops rather than resolving whatever
+        // project the parent turns out to be (#3392). Checked only when the new
+        // anchor is absent: beside a migrated tree the old file is a leftover.
+        const unmigrated = join(current, PROJECT_LOCAL_STATE_DIR, PROJECT_CONFIG_FILENAME);
+        if (existsSync(unmigrated)) {
+            throw new PrimitiveEnvError("stale-layout", unmigratedProjectMessage(unmigrated, candidate), unmigrated);
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/**
+ * 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 function projectRootForConfigPath(configPath) {
+    const dir = dirname(configPath);
+    return basename(dir) === PROJECT_TREE_DIR ? dirname(dir) : dir;
+}
+/**
+ * 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 function localStatePathForConfigPath(configPath) {
+    return join(projectRootForConfigPath(configPath), PROJECT_LOCAL_STATE_DIR, LOCAL_STATE_FILENAME);
+}
+/**
+ * The message of a caught value. A catch binding is `unknown` under the
+ * strict config primitive-app compiles this copy with, so narrow first.
+ */
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * 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 function readCoreProjectConfig(configPath) {
+    if (!existsSync(configPath)) {
+        throw new PrimitiveEnvError("missing-config", missingConfigMessage(dirname(configPath)), configPath);
+    }
+    let raw;
+    try {
+        raw = readFileSync(configPath, "utf-8");
+    }
+    catch (err) {
+        throw new PrimitiveEnvError("malformed-config", `Failed to read ${PROJECT_CONFIG_DISPLAY_NAME} (${configPath}): ${errorMessage(err)}`, configPath);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new PrimitiveEnvError("malformed-config", `Failed to parse ${PROJECT_CONFIG_DISPLAY_NAME} (${configPath}): ${errorMessage(err)}`, configPath);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new PrimitiveEnvError("malformed-config", `${PROJECT_CONFIG_DISPLAY_NAME} (${configPath}) must contain a JSON object at the top level.`, configPath);
+    }
+    const obj = parsed;
+    if (typeof obj.version !== "number" || !Number.isInteger(obj.version)) {
+        throw new PrimitiveEnvError("malformed-config", `${PROJECT_CONFIG_DISPLAY_NAME} (${configPath}) is missing required integer field "version".`, configPath);
+    }
+    if (obj.version !== PRIMITIVE_CONFIG_VERSION) {
+        throw new PrimitiveEnvError("unsupported-version", `${PROJECT_CONFIG_DISPLAY_NAME} (${configPath}) has version ${obj.version}, but this tool understands version ${PRIMITIVE_CONFIG_VERSION}.`, configPath);
+    }
+    if (!obj.environments || typeof obj.environments !== "object" || Array.isArray(obj.environments)) {
+        throw new PrimitiveEnvError("malformed-config", `${PROJECT_CONFIG_DISPLAY_NAME} (${configPath}) is missing required "environments" object.`, configPath);
+    }
+    const environments = {};
+    for (const [name, entry] of Object.entries(obj.environments)) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new PrimitiveEnvError("malformed-config", `Environment "${name}" must be an object in ${PROJECT_CONFIG_DISPLAY_NAME} (${configPath}).`, configPath);
+        }
+        const e = entry;
+        if (typeof e.apiUrl !== "string" || !e.apiUrl) {
+            throw new PrimitiveEnvError("malformed-config", `Environment "${name}" must have a non-empty "apiUrl" string in ${PROJECT_CONFIG_DISPLAY_NAME} (${configPath}).`, configPath);
+        }
+        // Every environment names one app, checked here rather than after the
+        // selection: the criterion is about the FILE, and a second reader (the
+        // Vite plugin, cf-deploy, the Swift pre-build script) may land on a
+        // different environment than the CLI did.
+        const appId = readAppId(e.appId);
+        if (!appId) {
+            throw new PrimitiveEnvError("missing-app-id", missingAppIdMessage(name, configPath), configPath);
+        }
+        environments[name] = {
+            apiUrl: e.apiUrl.replace(/\/$/, ""),
+            appId,
+            appName: typeof e.appName === "string" ? e.appName : undefined,
+            webUrl: normalizeWebOrigin(e.webUrl),
+            description: typeof e.description === "string" ? e.description : undefined,
+        };
+    }
+    return {
+        version: obj.version,
+        defaultEnvironment: typeof obj.defaultEnvironment === "string" && obj.defaultEnvironment
+            ? obj.defaultEnvironment
+            : undefined,
+        environments,
+    };
+}
+/**
+ * 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 function readLocalSelection(configPath) {
+    const path = localStatePathForConfigPath(configPath);
+    if (!existsSync(path))
+        return null;
+    const corrupt = (detail) => {
+        throw new PrimitiveEnvError("corrupt-local-state", `${LOCAL_STATE_DISPLAY_NAME} (${path}) is unreadable: ${detail}. Delete the file or re-run 'primitive env use <name>'.`, path);
+    };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return corrupt(errorMessage(err));
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return corrupt("expected a JSON object");
+    }
+    const obj = parsed;
+    const selected = obj.selectedEnvironment;
+    if (selected === undefined || selected === null || selected === "")
+        return null;
+    if (typeof selected !== "string") {
+        return corrupt(`"selectedEnvironment" must be a string`);
+    }
+    return selected;
+}
+/**
+ * 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 function selectEnvironmentName(config, options) {
+    const available = Object.keys(config.environments);
+    const list = available.join(", ") || "(none)";
+    const where = options.configPath
+        ? `${PROJECT_CONFIG_DISPLAY_NAME} (${options.configPath})`
+        : PROJECT_CONFIG_DISPLAY_NAME;
+    const requireKnown = (name, source, origin) => {
+        if (!config.environments[name]) {
+            throw new PrimitiveEnvError("unknown-environment", `Environment "${name}" is not defined in ${where} (selected ${origin}). Available: ${list}`, options.configPath);
+        }
+        return { name, source };
+    };
+    if (options.explicitEnvName) {
+        return requireKnown(options.explicitEnvName, "explicit", "explicitly");
+    }
+    if (options.envVarName) {
+        return requireKnown(options.envVarName, "env-var", "via PRIMITIVE_ENV");
+    }
+    if (options.localSelection) {
+        return requireKnown(options.localSelection, "local", `in ${LOCAL_STATE_DISPLAY_NAME}`);
+    }
+    if (config.defaultEnvironment) {
+        return requireKnown(config.defaultEnvironment, "default", `as "defaultEnvironment"`);
+    }
+    if (available.length === 1) {
+        return { name: available[0], source: "sole" };
+    }
+    if (available.length === 0) {
+        throw new PrimitiveEnvError("no-selection", `${where} has no environments defined. Run 'primitive env add <name>' or 'primitive init'.`, options.configPath);
+    }
+    throw new PrimitiveEnvError("no-selection", `No environment selected. Run 'primitive env use <name>', set "defaultEnvironment" in ${where}, or export PRIMITIVE_ENV. Available: ${list}`, options.configPath);
+}
+/**
+ * The whole algorithm end to end: discover the config, read the selection,
+ * apply the precedence, derive the WebSocket URL.
+ */
+export function resolvePrimitiveEnv(options = {}) {
+    const env = options.env ?? process.env;
+    const configPath = options.configPath ?? findPrimitiveConfigPath({ cwd: options.cwd, env });
+    if (!configPath) {
+        throw new PrimitiveEnvError("missing-config", missingConfigMessage(options.cwd ?? process.cwd()));
+    }
+    const projectRoot = projectRootForConfigPath(configPath);
+    const config = readCoreProjectConfig(configPath);
+    const { name, source } = selectEnvironmentName(config, {
+        explicitEnvName: options.explicitEnvName || null,
+        envVarName: env.PRIMITIVE_ENV || null,
+        localSelection: readLocalSelection(configPath),
+        configPath,
+    });
+    const entry = config.environments[name];
+    return {
+        name,
+        apiUrl: entry.apiUrl,
+        wsUrl: deriveWsUrl(entry.apiUrl),
+        appId: entry.appId,
+        appName: entry.appName,
+        webUrl: entry.webUrl,
+        description: entry.description,
+        source,
+        configPath,
+        localStatePath: localStatePathForConfigPath(configPath),
+        projectRoot,
+    };
+}
+//# sourceMappingURL=env-resolver-core.js.map

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

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

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

@@ -0,0 +1,99 @@
+/**
+ * Environment resolution (CLI side).
+ *
+ * The algorithm itself lives in `env-resolver-core.ts` — the one copy the Vite
+ * plugin and the Swift pre-build script also run (#2873). This module is the
+ * CLI's thin wrapper around it: process-lifetime caching, the `--env` override
+ * commander sets, and — load-bearing — the CLI's own FULL field-level
+ * validation via `validateProjectConfig()`. The core carries only the version
+ * and structural checks the other readers need; running the CLI's validation
+ * first is what keeps `getProjectConfig()` and `getCurrentEnvironment()` from
+ * ever disagreeing about the same file.
+ *
+ * The resolution order is:
+ *
+ *   1. Explicit --env <name> flag (set via setCurrentEnvName from bin/primitive.ts)
+ *   2. PRIMITIVE_ENV environment variable
+ *   3. The per-machine selection in .primitive/local.json (`primitive env use`)
+ *   4. The project config's committed defaultEnvironment
+ *   5. If the project has exactly one environment, that one
+ *   6. 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";
+import { PrimitiveEnvError, type PrimitiveEnvSource } from "./env-resolver-core.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;
+    /** Which precedence step chose this environment. */
+    source: PrimitiveEnvSource;
+}
+/**
+ * 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;
+/**
+ * Reads this machine's environment selection (`primitive env use`), or null
+ * when nothing is selected. Throws PrimitiveEnvError on corrupt local state —
+ * `env list` / `env show` surface that distinctly instead of quietly falling
+ * back to the committed default.
+ */
+export declare function getLocalSelection(): string | null;
+/** Absolute path of the local-state file for the current project, if any. */
+export declare function getLocalStatePath(): string | 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;
+/**
+ * The resolved environment, or the one refusal (#3154, intent criterion 5).
+ *
+ * `getCurrentEnvironment()` answers `null` outside a project, which used to
+ * mean "legacy mode — fall back to `./config` and `~/.primitive/`". There is
+ * no such mode any more: the environment is the ONLY thing that names the
+ * configuration tree, the app and the server, so a caller that needs one asks
+ * here and gets an error naming what is missing instead of a second answer.
+ *
+ * Everything else propagates untouched. `no-selection`, `unknown-environment`,
+ * `corrupt-local-state` and `stale-layout` are real answers about a real
+ * project, and the old `safeEnv()` swallowing them is exactly how a typo in
+ * `--env` used to end up writing into `./config`.
+ */
+export declare function requireCurrentEnvironment(): ResolvedEnvironment;
+/**
+ * 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;
+export { PrimitiveEnvError };