export type EnvironmentName = 'dev' | 'prod' | 'local';
export interface Environment {
    name: EnvironmentName;
    apiUrl: string;
    /**
     * Runtime AI for a game the CLI is serving — NPC chat, image and mesh generation,
     * speech-to-text. Not api-server: those live on game-server, which is a separate
     * deployment and needs no token.
     *
     * The engine can pick this host itself, but only from the page's own hostname
     * (`game/src/engine/environment.ts`), and localhost tells it nothing — it reads as
     * neither prod nor dev and so always resolves to the dev cluster. Here the project's
     * pinned environment is known, so `bitmagic dev` hands the answer to the engine
     * rather than letting it guess (see the LOAD_GAME `gameServerUrl` in editor/server.ts).
     */
    gameServerUrl: string;
    auth0Domain: string;
    auth0Audience: string;
    /** Empty until the Auth0 Native application exists; see resolveAuth0ClientId. */
    auth0ClientId: string;
}
export declare const ENVIRONMENTS: Record<EnvironmentName, Environment>;
export declare const ENVIRONMENT_NAMES: EnvironmentName[];
export declare function isEnvironmentName(value: string): value is EnvironmentName;
/** Which input decided the environment — what `whoami` prints and what `login` checks. */
export type EnvironmentSource = 'flag' | 'BITMAGIC_ENV' | 'project' | 'folder' | 'stored' | 'default';
export interface ResolveEnvironmentOptions {
    /** The --env flag, if given. */
    explicit?: string;
    /** The `environment` field of the nearest bitmagic.json, if the command found one. */
    projectDefault?: string;
    /** The `env` of the nearest .bitmagic-env, if the command found one. */
    folderDefault?: string;
    /** Where that marker was, so a bad value can name the file holding it. */
    folderMarkerPath?: string;
    /** Its optional `apiUrl` — applied only when the marker is also what chose the environment. */
    folderApiUrl?: string;
    /** The default recorded in the credentials file, if any. */
    storedDefault?: string;
    env?: Record<string, string | undefined>;
}
/**
 * The environment a CLI points at when nothing else says at all: prod, always.
 *
 * This used to ask the CLI about its own release line — `-dev.N` meant dev, a plain version meant
 * prod — so that a dev build needed no `--env` to reach the dev api-server. That answer is now
 * carried by `.bitmagic-env` instead, which states it per folder rather than inferring it from an
 * install, and states it for the release line too. Once the intent has somewhere honest to live,
 * inferring it is worse than not: the lane rule made the same command mean different things on two
 * machines, and the difference was a version string nobody was looking at.
 *
 * Prod because this is the bottom of the chain, and the bottom should be the environment a creator
 * who has expressed no preference actually wants: the one their games live on. Everything else is
 * reachable, and now has to be asked for — a marker, a project pin, BITMAGIC_ENV, or --env.
 *
 * The cost is real and worth naming: aiming at prod by accident is the more expensive mistake, as a
 * command that lands there can touch a published game, whereas one aimed at dev usually fails
 * visibly at the first authenticated call. That is the trade of making the default predictable
 * rather than inferred, and it is why every non-prod tree should carry a marker.
 */
export declare const DEFAULT_ENVIRONMENT: EnvironmentName;
export interface EnvironmentSelection {
    environment: Environment;
    source: EnvironmentSource;
}
/**
 * Resolve the environment AND report which input chose it.
 *
 * The source matters to more than diagnostics: `login` uses it to avoid turning a project's pin
 * into the machine-global default, and `upgrade` uses it to avoid stamping a one-off override into
 * a committed file.
 */
export declare function selectEnvironment(options?: ResolveEnvironmentOptions): EnvironmentSelection;
export declare function resolveEnvironment(options?: ResolveEnvironmentOptions): Environment;
/** Human phrasing for a source, for the one line commands print about where they are pointed. */
export declare function describeEnvironmentSource(source: EnvironmentSource): string;
export interface CommandEnvironmentOptions {
    /** The --env flag, for the commands that declare one. */
    explicit?: string;
    /**
     * Where to look for the project. Commands that already loaded one pass `context.root`; the rest
     * omit it and get process.cwd(). Standing outside a project is not an error — `login` and
     * friends legitimately do.
     */
    cwd?: string;
    /** Test-only credentials-directory override, matching the `baseDir` deps commands already thread. */
    baseDir?: string;
    env?: Record<string, string | undefined>;
}
export declare function selectEnvironmentForCommand(options?: CommandEnvironmentOptions): EnvironmentSelection;
/** The common case: the environment, without caring which input chose it. */
export declare function resolveEnvironmentForCommand(options?: CommandEnvironmentOptions): Environment;
/**
 * What the project itself says it belongs to — its committed pin, and nothing else.
 *
 * A different question from `selectEnvironmentForCommand`, which answers "where should THIS command
 * point" and therefore lets `--env`, `BITMAGIC_ENV` and the stored default in. Some answers are
 * properties of the project rather than of one invocation — which npm line its CLI comes from is
 * the first — and for those an override must not change the answer.
 *
 * Undefined for every "we do not know": no project, a project scaffolded before the field existed,
 * an unrecognised value, and an unreadable bitmagic.json. That is the opposite of `selectEnvironment`
 * on purpose — this feeds an advisory printed before any command runs, where a thrown CliError would
 * turn a malformed file into a CLI that cannot run at all.
 */
export declare function readPinnedEnvironment(cwd?: string): EnvironmentName | undefined;
export declare function resolveAuth0ClientId(environment: Environment, env?: Record<string, string | undefined>): string;