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

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

@@ -0,0 +1,459 @@
+/**
+ * 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 docs-site slug of the migration procedure (#3155 publishes the page). */
+export 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 function staleLayoutMessage(detail) {
+    return (`${detail} The Primitive configuration tree moved out of the hidden ` +
+        `directory: the config is now ${PROJECT_CONFIG_DISPLAY_NAME} and each ` +
+        `environment's TOML is at primitive/<env>/, while .primitive/ keeps only ` +
+        `machine-local state. Nothing is read from either tree until the project ` +
+        `is migrated — follow ${MIGRATION_GUIDE_SLUG}.`);
+}
+/**
+ * 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;
+}
+/**
+ * Refuses a project still holding the pre-#3153 layout, wherever it is found.
+ *
+ * Two shapes, one error. During the walk: a directory that has
+ * `.primitive/config.json` and no `primitive/config.json` never migrated. After
+ * a root is known: `<root>/.primitive/sync/` or a leftover
+ * `<root>/.primitive/config.json` means the migration stopped halfway, which is
+ * the state a fallback read would hide.
+ */
+function assertNoStaleLayout(root) {
+    const oldConfig = join(root, PROJECT_LOCAL_STATE_DIR, PROJECT_CONFIG_FILENAME);
+    if (existsSync(oldConfig)) {
+        throw new PrimitiveEnvError("stale-layout", staleLayoutMessage(`${oldConfig} still exists.`), oldConfig);
+    }
+    const oldTree = join(root, PROJECT_LOCAL_STATE_DIR, "sync");
+    if (existsSync(oldTree)) {
+        throw new PrimitiveEnvError("stale-layout", staleLayoutMessage(`${oldTree} still exists.`), oldTree);
+    }
+}
+/**
+ * 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 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", staleLayoutMessage(`PRIMITIVE_PROJECT_CONFIG points at ${forced}, inside a ${PROJECT_LOCAL_STATE_DIR}/ directory.`), forced);
+        }
+        if (!existsSync(forced))
+            return null;
+        assertNoStaleLayout(projectRootForConfigPath(forced));
+        return forced;
+    }
+    let current = resolve(options.cwd ?? process.cwd());
+    while (true) {
+        const candidate = join(current, PROJECT_TREE_DIR, PROJECT_CONFIG_FILENAME);
+        // Runs whether or not the new anchor is here: without it, a directory that
+        // has both anchors resolves (half-migrated), and one that has only the old
+        // one is not a project at all.
+        assertNoStaleLayout(current);
+        if (existsSync(candidate))
+            return candidate;
+        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);
+}
+/**
+ * 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}): ${err.message}`, configPath);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new PrimitiveEnvError("malformed-config", `Failed to parse ${PROJECT_CONFIG_DISPLAY_NAME} (${configPath}): ${err.message}`, 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(err.message);
+    }
+    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()));
+    }
+    // The root is known now (by the walk OR by an override), so the
+    // half-migrated shapes can be ruled out before anything is read.
+    const projectRoot = projectRootForConfigPath(configPath);
+    assertNoStaleLayout(projectRoot);
+    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 };