@tula-tech/cli 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,1898 @@
+import { Readable, Writable } from "node:stream";
+import { AdminFetch } from "@tula-tech/admin";
+/**
+* A mistake in how the CLI was called: an unknown option, a missing value, a missing setting.
+* Reported as `error: …` with exit code 1.
+*
+* @example
+* ```ts
+* throw new UsageError('Set TULA_API_URL, or pass --api-url.')
+* ```
+*/
+declare class UsageError extends Error {
+	/** @param message - What was wrong, and what to do instead. */
+	constructor(message: string);
+}
+/**
+* One option of a command.
+*
+* @example
+* ```ts
+* const yes: OptionSpec = { type: 'boolean', short: 'y', description: 'Do not ask.' }
+* ```
+*/
+interface OptionSpec {
+	/** `boolean` for a flag, `string` for an option that takes a value. */
+	type: "boolean" | "string";
+	/** A one-letter alias, e.g. `y` for `-y`. */
+	short?: string;
+	/** The value's name in the help text, e.g. `<name>`. */
+	value?: string;
+	/** One line for the help text. */
+	description: string;
+}
+/**
+* Parsed arguments.
+*
+* @example
+* ```ts
+* const { flags } = parseArgs(['--env', 'prod', '--yes'], options)
+* flags.env // 'prod'
+* ```
+*/
+interface ParsedArgs {
+	/** Options by name: `true` for a flag that was given, the value for an option. */
+	flags: Record<string, string | boolean | undefined>;
+	/** Everything that is not an option. */
+	positionals: string[];
+}
+/**
+* Parse a command's arguments: `--name`, `--name value`, `--name=value`, `-y`, and `--` to end
+* the options. No abbreviations and no grouped short flags, so what a script passes means one
+* thing.
+*
+* An error names the option and never repeats a value: what follows an option may be a secret
+* passed by mistake.
+*
+* @param argv - The arguments after the command's name.
+* @param options - The options the command takes, by name.
+* @returns The options that were given and the positional arguments.
+* @throws UsageError for an unknown option, a missing value, or a value given to a flag.
+*
+* @example
+* ```ts
+* parseArgs(['--env=prod', '-y'], { env: { type: 'string', description: '' }, yes: { type: 'boolean', short: 'y', description: '' } })
+* // { flags: { env: 'prod', yes: true }, positionals: [] }
+* ```
+*/
+declare function parseArgs(argv: readonly string[], options: Record<string, OptionSpec>): ParsedArgs;
+/**
+* One finished child process.
+*
+* @example
+* ```ts
+* const { code, stdout } = await host.run(['docker', 'compose', 'version'], { timeoutMs: 10_000 })
+* ```
+*/
+interface RunResult {
+	/** The exit code; `null` when the process was killed (a timeout, a signal). */
+	code: number | null;
+	/** What it wrote to standard output. Empty when the output was passed through. */
+	stdout: string;
+	/** What it wrote to standard error. Empty when the output was passed through. */
+	stderr: string;
+	/** Whether it was killed because it ran past its timeout. */
+	timedOut: boolean;
+}
+/**
+* How a child process is run.
+*
+* @example
+* ```ts
+* const options: RunOptions = { timeoutMs: 60_000, env: { COMPOSE_PROJECT_NAME: 'shop' } }
+* ```
+*/
+interface RunOptions {
+	/** The working directory. */
+	cwd?: string;
+	/** Variables added to the process's own environment. */
+	env?: Readonly<Record<string, string>>;
+	/** Kill the process after this long. Every spawn has one: a child that hangs must not hang the CLI. */
+	timeoutMs: number;
+	/**
+	* `capture` (the default) collects the output and shows none of it; `inherit` passes
+	* standard error through so a long step shows its progress. Standard output is always
+	* captured: a minted key is printed there.
+	*/
+	stderr?: "capture" | "inherit";
+	/**
+	* Run the command to its end whatever signal the CLI receives: it is not stopped by an
+	* interrupt, and is started outside the terminal's foreground group, so a Ctrl-C typed
+	* there does not reach it either. Its timeout still ends it. For the one command that
+	* must not be cut short by the interrupt it answers: closing a tunnel.
+	*/
+	shielded?: boolean;
+}
+/**
+* Everything `tula dev` does outside the API: running `docker compose` and reading and writing
+* the project's files. A test passes a fake, so no test needs Docker.
+*
+* @example
+* ```ts
+* const host: Host = createProcessHost()
+* await host.run(['docker', 'compose', 'up', '-d'], { timeoutMs: 300_000 })
+* ```
+*/
+interface Host {
+	/**
+	* Run a command to its end.
+	*
+	* @param command - The executable and its arguments. Never a shell line.
+	* @param options - Directory, environment, timeout.
+	* @returns The exit code and the captured output.
+	* @throws Error with `code: 'ENOENT'` when the executable does not exist.
+	*/
+	run(command: readonly string[], options: RunOptions): Promise<RunResult>;
+	/**
+	* Read a file as text.
+	*
+	* @param path - Absolute path.
+	* @returns The text, or `null` when the file does not exist.
+	* @throws UsageError when `path` is a symbolic link or anything else that is not a regular
+	*   file (a named pipe, a directory): refused before it is opened, so a read never waits.
+	*/
+	readFile(path: string): Promise<string | null>;
+	/**
+	* Write a file, replacing it atomically, readable by its owner only.
+	*
+	* @param path - Absolute path.
+	* @param text - The contents.
+	* @throws UsageError when `path` is a symbolic link: nothing is written through one.
+	*/
+	writeSecretFile(path: string, text: string): Promise<void>;
+	/**
+	* Create a file that must not exist yet, readable by its owner only (mode 0600). Asking and
+	* taking the name are one step, so nothing that appears at the path meanwhile is replaced.
+	*
+	* @param path - Absolute path.
+	* @param text - The contents.
+	* @throws UsageError when anything is at `path`: a file (whatever it holds), a directory, a
+	*   named pipe or a symbolic link. Nothing there is opened or changed.
+	*/
+	createSecretFile(path: string, text: string): Promise<void>;
+	/**
+	* Remove a file. A symbolic link at the path is removed itself, never what it points at.
+	*
+	* @param path - Absolute path.
+	* @returns Whether there was something to remove.
+	*/
+	removeFile(path: string): Promise<boolean>;
+	/**
+	* Make an existing file readable and writable by its owner only (mode 0600), leaving its
+	* contents alone.
+	*
+	* @param path - Absolute path.
+	* @returns Whether the file was open to anyone else and has been closed. `false` when it
+	*   already was owner-only, does not exist, or the platform has no such modes.
+	* @throws UsageError when `path` is a symbolic link: no mode is changed through one.
+	*/
+	restrictFile(path: string): Promise<boolean>;
+	/**
+	* Wait.
+	*
+	* @param ms - How long.
+	*/
+	sleep(ms: number): Promise<void>;
+	/**
+	* Be told every time the CLI is asked to stop (`SIGINT`, `SIGTERM`, `SIGHUP`), for as long
+	* as the returned function has not been called. While something listens the signal does
+	* not end the process: the listener's owner ends the run itself, after what it must not
+	* leave behind (an open tunnel) is taken down. A signal that cannot be caught (a kill, a
+	* crash, a power loss) tells nobody.
+	*
+	* @param listener - Called once for every signal received.
+	* @returns Stop listening.
+	*/
+	onInterrupt(listener: () => void): () => void;
+}
+/**
+* Where output goes: `process.stdout`, `process.stderr`, or a test's buffer.
+*
+* @example
+* ```ts
+* const lines: string[] = []
+* const sink: Sink = { write: (text) => lines.push(text) }
+* ```
+*/
+interface Sink {
+	/** Write text. */
+	write(text: string): unknown;
+	/** Whether the sink is a terminal. */
+	isTTY?: boolean;
+}
+/**
+* Text styles. Each returns its text unchanged when colour is off.
+*
+* @example
+* ```ts
+* output.line(output.style.green('+ added'))
+* ```
+*/
+interface Styles {
+	/** Something added. */
+	green(text: string): string;
+	/** Something removed, or an error. */
+	red(text: string): string;
+	/** Something changed, or a warning. */
+	yellow(text: string): string;
+	/** Secondary text. */
+	dim(text: string): string;
+	/** A heading. */
+	bold(text: string): string;
+}
+/**
+* The one place the CLI writes from. Commands never touch `console` or `process.stdout`: they
+* get an `Output`, so a test captures everything a run prints.
+*
+* @example
+* ```ts
+* const output = createOutput(process.stdout, process.stderr, process.env)
+* output.line('No changes.')
+* ```
+*/
+interface Output {
+	/** Write a line to standard output. */
+	line(text?: string): void;
+	/** Write a line to standard error. */
+	error(text: string): void;
+	/** Styles for standard output. */
+	readonly style: Styles;
+	/** Styles for standard error. */
+	readonly errorStyle: Styles;
+	/**
+	* Name a value that must never be printed (the secret key, a provider's secret). Every line
+	* written afterwards has it replaced by `[redacted]`. No code path prints one on purpose;
+	* this is the net under them (an error message that quotes a request, a future mistake).
+	*
+	* With `'errors'` the value is removed from standard error only. That is for a value that
+	* may be an ordinary word (the password `tula policy test` is given): results on standard
+	* output are fixed text that never includes it, and replacing the word there would garble
+	* them (`password.too_short` for the password `password`).
+	*/
+	redact(value: string, scope?: "all" | "errors"): void;
+}
+/**
+* Whether to colour a stream: only a terminal, and never when `NO_COLOR` is set to anything
+* but the empty string (https://no-color.org) or `TERM` is `dumb`.
+*
+* @param sink - The stream.
+* @param env - The environment.
+* @returns `true` to use ANSI colours.
+*
+* @example
+* ```ts
+* shouldUseColor(process.stdout, process.env)
+* ```
+*/
+declare function shouldUseColor(sink: Sink, env: Readonly<Record<string, string | undefined>>): boolean;
+/**
+* Build the CLI's output.
+*
+* @param stdout - Where results go.
+* @param stderr - Where errors and prompts go.
+* @param env - The environment (`NO_COLOR`, `TERM`).
+* @returns The output.
+*
+* @example
+* ```ts
+* const output = createOutput(process.stdout, process.stderr, process.env)
+* ```
+*/
+declare function createOutput(stdout: Sink, stderr: Sink, env: Readonly<Record<string, string | undefined>>): Output;
+/**
+* A run's exit code: `0` success (and, for `tula diff`, "no changes"), `1` an error, `2` "there
+* are changes to apply" (`tula diff`, so that CI can gate on it) and "the password would be
+* refused" (`tula policy test`): an answer, not a failure of the command.
+*
+* @example
+* ```ts
+* process.exit(plan.changes ? EXIT.changes : EXIT.ok)
+* ```
+*/
+declare const EXIT: {
+	readonly ok: 0;
+	readonly error: 1;
+	readonly changes: 2;
+	readonly refused: 2;
+};
+/**
+* Everything a run touches outside itself. `main` fills it from the process; a test passes its
+* own, which is how the real CLI entry runs in process against an API mounted in memory.
+*
+* @example
+* ```ts
+* const io: CliIo = { stdout, stderr, env: { TULA_API_URL, TULA_SECRET_KEY }, cwd, isTTY: false, fetch }
+* const code = await runCli(['diff', '--env', 'dev'], io)
+* ```
+*/
+interface CliIo {
+	/** Results. */
+	stdout: Sink;
+	/** Errors and prompts. */
+	stderr: Sink;
+	/** The environment: where the API URL, the secret key and provider secrets are read from. */
+	env: Readonly<Record<string, string | undefined>>;
+	/** The directory a relative `--config` is resolved against. */
+	cwd: string;
+	/**
+	* Whether a person can be asked a question: standard input and standard error are both a
+	* terminal (the question is written to standard error, so standard output may be a file).
+	*/
+	isTTY: boolean;
+	/**
+	* Whether standard input is a terminal. A secret key is never read from one
+	* (`--secret-key-file -`): it would be shown as it is typed.
+	*/
+	stdinIsTTY?: boolean;
+	/** The `fetch` the admin client uses. Defaults to the platform's. */
+	fetch?: AdminFetch;
+	/** Ask a question and read one line. Required only where a command prompts on a terminal. */
+	prompt?: (question: string) => Promise<string>;
+	/** Read all of standard input (`--secret-key-file -`). */
+	readStdin?: () => Promise<string>;
+	/** Read a file as text (`--secret-key-file <path>`). */
+	readFile?: (path: string) => Promise<string>;
+	/**
+	* Ask for a secret on the terminal without showing what is typed (`tula policy test`).
+	* Present only where standard input is a terminal.
+	*/
+	promptSecret?: (question: string) => Promise<string>;
+	/** This machine's clock (`tula doctor` compares it with the server's). Defaults to the system's. */
+	now?: () => Date;
+	/** How `tula dev` runs `docker compose` and touches the project's files. */
+	host?: Host;
+	/**
+	* The process's own standard input and output as streams, and its stop signals, for a
+	* command that serves a protocol on them (`tula mcp`). While it does, nothing else may be
+	* written to standard output: every other line goes to `stderr`.
+	*/
+	serve?: {
+		/** Standard input. */
+		input: Readable;
+		/** Standard output. */
+		output: Writable;
+		/** Call `stop` on SIGTERM or SIGINT. Returns how to stop listening. */
+		onTerminate?: (stop: () => void) => () => void;
+	};
+}
+/**
+* What a command's `run` receives.
+*
+* @example
+* ```ts
+* async function run({ output, flags }: CommandContext): Promise<number> {
+*   output.line(`env: ${String(flags.env)}`)
+*   return EXIT.ok
+* }
+* ```
+*/
+interface CommandContext extends ParsedArgs {
+	/** The run's surroundings. */
+	io: CliIo;
+	/** Where to write. */
+	output: Output;
+}
+/**
+* One command of the CLI. A new command (`tula dev`, `tula doctor`, …) is an object of this
+* shape added to the list `runCli` is given; nothing else changes.
+*
+* @example
+* ```ts
+* const hello: Command = {
+*   name: 'hello',
+*   summary: 'Say hello.',
+*   usage: 'tula hello [--name <name>]',
+*   options: { name: { type: 'string', value: '<name>', description: 'Who to greet.' } },
+*   run: async ({ output, flags }) => {
+*     output.line(`Hello, ${String(flags.name ?? 'world')}.`)
+*     return EXIT.ok
+*   },
+* }
+* ```
+*/
+interface Command {
+	/** The word after `tula`. */
+	name: string;
+	/** One line for `tula --help`. */
+	summary: string;
+	/** The usage line for `tula <name> --help`. */
+	usage: string;
+	/** More help: what the command does, its exit codes. */
+	description?: string;
+	/**
+	* How many arguments that are not options the command takes (default: none), e.g. the `test`
+	* of `tula policy test`. The command checks what they are.
+	*/
+	maxPositionals?: number;
+	/** The options it takes, by name. `--help` is added to every command. */
+	options: Record<string, OptionSpec>;
+	/** Run the command and answer its exit code. */
+	run(context: CommandContext): Promise<number>;
+}
+/**
+* Report a failure the way every command does, and answer the exit code for it.
+*
+* @param output - Where to write.
+* @param error - What was thrown.
+* @returns `EXIT.error`.
+*
+* @example
+* ```ts
+* try {
+*   await work()
+* } catch (error) {
+*   return reportError(output, error)
+* }
+* ```
+*/
+declare function reportError(output: Output, error: unknown): number;
+/**
+* Run the CLI: pick the command, parse its options, run it, and turn whatever it throws into a
+* message and an exit code. It never throws and never exits the process itself.
+*
+* @param argv - The arguments after `tula`.
+* @param io - The run's surroundings.
+* @param commands - The commands the CLI has.
+* @returns The exit code.
+*
+* @example
+* ```ts
+* const code = await runCli(['diff', '--env', 'prod'], io, COMMANDS)
+* ```
+*/
+declare function runCli(argv: readonly string[], io: CliIo, commands: readonly Command[]): Promise<number>;
+/**
+* `tula apply`: make an environment's settings, providers, webhook endpoints, hooks and native
+* apps what the config file says.
+*
+* It prints the same plan as `tula diff`, asks before changing anything (`--yes` skips the
+* question; without it a run that is not at a terminal refuses instead of hanging), and
+* refuses two plans unless told otherwise: one that would reset settings this version does not
+* know (`--allow-unknown`), and, under `--yes`, where nobody reads the warning, one that
+* weakens security (`--allow-weaker`: the settings' weakenings, the hooks' and the native
+* apps') or removes a
+* webhook endpoint (`--allow-webhook-removal`). A plan that creates a webhook endpoint or a
+* hook needs a word on its
+* signing secret, which the server shows once (`--secrets-file`, `--show-secrets`,
+* `--discard-secrets`); the secret is redacted from all output unless it was asked for. It
+* replaces the settings with `If-Match` on the revision the plan was made against, so a change
+* someone else made in between is never overwritten. If a write fails part-way, it says
+* exactly what was applied and what was not; running it again finishes the job.
+*
+* @example
+* ```sh
+* TULA_API_URL=https://auth.example.com TULA_SECRET_KEY=… tula apply --env prod --yes
+* ```
+*/
+declare const applyCommand: Command;
+/**
+* `tula approve <proposal id>`: a person's answer to a change an AI agent asked for
+* ([ADR 0053](../../../../docs/adr/0053-proposals.md)).
+*
+* An agent holds an agent key, which reads and proposes and, a sign-in test's throwaway user
+* aside (ADR 0058), can change nothing. Its proposal
+* waits, for minutes, until a person approves it with a credential the agent never has: the
+* environment's secret key, which this command reads from where every command reads it (the
+* environment or `--secret-key-file`, never an argument). The command shows what the
+* proposal would do and to whom, asks, and approves exactly what it showed: the approval
+* repeats the operation and the target, and the server refuses it for anything else.
+*
+* It runs at a terminal or not at all: where standard input and standard error are not both
+* a terminal it refuses before any request, and it has no option that answers the question
+* (no `--yes`), so a program that can run commands cannot approve by running this one. A
+* key on standard input (`--secret-key-file -`) is refused for the same reason: the answer
+* is typed there.
+*
+* @example
+* ```sh
+* TULA_API_URL=https://auth.example.com TULA_SECRET_KEY=… tula approve 0199c2f4-7a10-7c3e-9b1a-5d2e8f4a6c01
+* ```
+*/
+declare const approveCommand: Command;
+/**
+* `tula dev`: start the project's local stack with Docker Compose, migrate, seed, mint
+* development keys into `.env.local` and print the URLs. `tula dev down` stops it.
+* `--tunnel` also gives the stack a public https address (ADR 0049).
+*
+* @example
+* ```sh
+* tula dev            # start, or continue: running it again changes nothing
+* tula dev --tunnel   # the same, reachable from a phone at a stable https address
+* tula dev down       # stop; --volumes also deletes the database
+* ```
+*/
+declare const devCommand: Command;
+/**
+* `tula diff`: compare the config file with what the server has and print the plan. It writes
+* nothing. Exit code `0` when there is nothing to apply, `2` when there is, `1` on an error,
+* so a CI job can gate on it.
+*
+* @example
+* ```sh
+* tula diff --env prod || [ $? -eq 2 ]   # 2 = changes pending
+* ```
+*/
+declare const diffCommand: Command;
+/**
+* `tula doctor`: check what actually goes wrong in a deployment, each with its fix. The CLI
+* checks what it can see from this machine (the API answers, the versions match, the clocks
+* agree); the API checks itself (`GET /v1/instance/diagnostics`): the database and its
+* migrations, the master key against the stored secrets, the mail relay, Redis, `PUBLIC_URL`
+* and each enabled provider's redirect URI. The CLI never connects to the database.
+*
+* @example
+* ```sh
+* TULA_API_URL=https://auth.example.com TULA_ADMIN_TOKEN=… tula doctor --strict
+* ```
+*/
+declare const doctorCommand: Command;
+import { McpServer as McpServer_ymih5p } from "@modelcontextprotocol/server";
+/**
+* Build the MCP server `tula mcp` serves, from the same places every other command reads its
+* target: the API URL from `--api-url`, `TULA_API_URL_<NAME>` or `TULA_API_URL`; the secret
+* key from `--secret-key-file`, `TULA_SECRET_KEY_<NAME>` or `TULA_SECRET_KEY`; the instance
+* admin token (for `run_doctor`'s server-side checks only) from `--admin-token-file` or
+* `TULA_ADMIN_TOKEN`. Never from an argument, and never from a tool's input.
+*
+* **With an agent key the secret key is not read at all** (ADR 0053): `--agent-key-file`,
+* `TULA_AGENT_KEY_<NAME>` or `TULA_AGENT_KEY`. The read tools then read with the agent key
+* and the propose tools work; the process that an AI agent talks to holds no credential
+* that can approve a proposal, or change anything beyond running a sign-in test where the
+* environment allows one (ADR 0058). A secret key that is also set is left
+* unread, and that is said on standard error. Without an agent key the propose tools answer
+* "not configured": a secret key does not propose.
+*
+* Nothing is required: what is missing or refused (a plain-http URL that is not this machine)
+* becomes the "not configured" answer of the tools that needed it, and is said once on
+* standard error. The scaffold tools need none of it.
+*
+* This is where `@tula-tech/mcp` is loaded, on first use.
+*
+* @param context - The command's context.
+* @returns The server, not yet connected.
+*
+* @example
+* ```ts
+* const server = await buildMcpServer({ flags: {}, positionals: [], io, output })
+* await server.connect(transport)
+* ```
+*/
+declare function buildMcpServer(context: CommandContext): Promise<McpServer_ymih5p>;
+/**
+* `tula mcp`: serve Tula's Model Context Protocol server on standard input and output, for an
+* MCP client (Claude Code, Claude Desktop, an editor) to start as a child process. Read tools
+* over an environment's users, sessions, audit entries, settings and deployment checks, a
+* tool that drafts a settings change as an edit to the config file (for a person to apply
+* with `tula apply`), scaffold tools that return files for the client to write, and, with an agent key, tools
+* that propose a change for a person to approve with `tula approve`. One tool changes live
+* data, for the seconds it runs and only where the environment allows it: `test_signin`
+* signs a throwaway user up and in and deletes it (ADR 0058). No other tool does, and none
+* returns a secret.
+*
+* @example
+* ```sh
+* TULA_API_URL=https://auth.example.com TULA_AGENT_KEY=… tula mcp
+* ```
+*/
+declare const mcpCommand: Command;
+/**
+* `tula policy test`: show which rules of an environment's password policy a password passes.
+*
+* The policy is read from the API with the environment's secret key; the rules are evaluated
+* on this machine with the same code the server and the SDKs use (`@tula-tech/contract`). The
+* password is never sent anywhere, printed or logged. The breached-password check is the one
+* rule that is not run: the server makes it when a password is set.
+*
+* @example
+* ```sh
+* tula policy test                       # asks for the password without showing it
+* printf %s "$PW" | tula policy test --email maya@example.com
+* ```
+*/
+declare const policyCommand: Command;
+/**
+* One thing the tunnel answers: a path of the public address, and the local URL a request
+* for it is passed to. `/` is everything no other route names.
+*
+* @example
+* ```ts
+* const root: TunnelRoute = { path: '/', target: 'http://127.0.0.1:3003' }
+* ```
+*/
+interface TunnelRoute {
+	/** The path on the public address: `/`, or one exact path. */
+	path: string;
+	/** Where it goes: `http://127.0.0.1:<port>`, with a path for an exact route. */
+	target: string;
+}
+/**
+* What a tunnel tool says it serves on the tunnel's port.
+*
+* @example
+* ```ts
+* const nothing: TunnelStatus = { endpoints: [], taken: false }
+* ```
+*/
+interface TunnelStatus {
+	/** Each public name with something on the port, and where each of its paths goes. */
+	endpoints: {
+		/** The name, lower case, without a port. */
+		host: string;
+		/** Whether the internet reaches it (not only the tool's private network). */
+		public: boolean;
+		/** Path to local URL; `null` for a path that is served some other way (a file, a text). */
+		routes: Record<string, string | null>;
+	}[];
+	/** The port is in use by something that is no web endpoint (a TCP forward, a session in the foreground). */
+	taken: boolean;
+}
+/**
+* A tunnel service, as `tula dev --tunnel` needs it: how its tool is asked what it serves,
+* told to serve a route and told to stop, and what to say when the tool is missing. One
+* service is built (ADR 0049); another would be another value of this type.
+*
+* The tool's own login and configuration are the developer's: no command here carries a
+* credential, reads one or names a file that holds one. **No command makes the tool rewrite
+* the `Host` header**: the API's development-only routes answer a loopback `Host` only, and
+* that is one of the things that keeps them off a tunnel.
+*
+* @example
+* ```ts
+* tailscaleFunnel.openCommand({ path: '/', target: 'http://127.0.0.1:3003' })
+* // ['tailscale', 'funnel', '--bg', '--yes', '--https=443', 'http://127.0.0.1:3003']
+* ```
+*/
+interface TunnelService {
+	/** The service's name, for messages. */
+	readonly name: string;
+	/** The executable. */
+	readonly binary: string;
+	/** What is said when the executable is missing: its name and how to install it. Fixed text. */
+	readonly missing: string;
+	/** What is said when the tool starts and reports no address in time. Fixed text. */
+	readonly noAddress: string;
+	/** How to see, by hand, what the tool serves. */
+	readonly inspect: string;
+	/** How to close the tunnel by hand. */
+	readonly closeByHand: string;
+	/** The argument vector that prints what the tool serves. */
+	statusCommand(): readonly string[];
+	/** The argument vector that serves one route and returns. */
+	openCommand(route: TunnelRoute): readonly string[];
+	/** The argument vector that stops serving everything on the tunnel's port. */
+	closeCommand(): readonly string[];
+	/**
+	* Read what {@link TunnelService.statusCommand} printed.
+	*
+	* @param stdout - The tool's standard output.
+	* @returns What is served on the tunnel's port, or `null` when the output cannot be read.
+	*/
+	readStatus(stdout: string): TunnelStatus | null;
+}
+/** The file `tula dev` writes the keys to: read by Bun, Vite and Next.js, and ignored by git. */
+declare const DEV_ENV_FILE = ".env.local";
+/**
+* The variables in the block `tula dev` manages, or `null` when the file has no block.
+*
+* @param text - The file's contents.
+* @returns The block's variables.
+*
+* @example
+* ```ts
+* parseDevBlock(await Bun.file('.env.local').text())?.TULA_API_URL
+* ```
+*/
+declare function parseDevBlock(text: string): Record<string, string> | null;
+/**
+* A file's contents without the block `tula dev` manages. Every other line is kept as it is.
+*
+* @param text - The file's contents.
+* @returns The contents without the block.
+*
+* @example
+* ```ts
+* withoutDevBlock('A=1\n# tula:dev:start\nB=2\n# tula:dev:end\n') // 'A=1\n'
+* ```
+*/
+declare function withoutDevBlock(text: string): string;
+/**
+* A file's contents with the block `tula dev` manages set to `vars`: replaced where it is, or
+* added at the end. Lines outside the block are never changed.
+*
+* @param text - The file's contents (`''` for a new file).
+* @param vars - The block's variables.
+* @returns The new contents.
+*
+* @example
+* ```ts
+* withDevBlock('MINE=1\n', { TULA_API_URL: 'http://localhost:3003' })
+* ```
+*/
+declare function withDevBlock(text: string, vars: Readonly<Record<string, string>>): string;
+/**
+* What `tula dev` needs from its command: where it runs and how.
+*
+* @example
+* ```ts
+* await startDev({ io, output, host, projectName: 'shop', timeoutMs: 900_000, showKeys: false, rotateKeys: false })
+* ```
+*/
+interface DevOptions {
+	/** The run's surroundings. */
+	io: CliIo;
+	/** Where to write. */
+	output: Output;
+	/** How Docker is run and files are touched. */
+	host: Host;
+	/** The Compose project name (`-p`); Compose's own default when left out. */
+	projectName?: string;
+	/** How long a long step (pulling, building, migrating, becoming ready) may take. */
+	timeoutMs: number;
+	/** Print the secret key. */
+	showKeys: boolean;
+	/** Mint new keys even when the file has some. */
+	rotateKeys: boolean;
+	/** Give the stack a public https address through a tunnel (ADR 0049). */
+	tunnel?: boolean;
+	/** The tunnel service. Default: Tailscale Funnel, the one that is built. */
+	tunnelService?: TunnelService;
+}
+/**
+* `tula dev`: bring the project's local stack up and leave it ready to use.
+*
+* Starts the Compose services, runs the migrations and the seed through the commands the API
+* image ships (the one place the CLI reaches the database, and only through them), waits for
+* the API, mints a publishable and a secret development key unless `.env.local` already holds
+* keys the stack accepts, writes them to its own block of `.env.local` (owner-readable only;
+* lines outside the block are never changed, and a `TULA_SECRET_KEY` of the user's own is
+* used as it is) and prints the URLs. Running it again changes nothing.
+*
+* With `tunnel` (ADR 0049) the API is started under a public https address: the tunnel is
+* opened through `host` like every other command, the address goes into the block and into
+* the one `docker compose up` that starts the API, and nothing else of the project is
+* changed: no line outside the block, and no setting of the environment (the changes are
+* printed for the developer to make). Without `tunnel`, a tunnel an earlier run opened is
+* closed and the API goes back to its local address. A port that serves something else is
+* refused before anything is started. The API's container is stopped and the tunnel's
+* record (`TULA_TUNNEL_TARGET`) written before the tunnel is opened; a run that fails or
+* receives an interrupt after that closes the tunnel again before it throws, and the
+* record leaves the block only when the tunnel is closed. A process that is killed
+* outright closes nothing: the record is what `tula dev down` then closes by.
+*
+* @param options - Where and how to run.
+* @throws UsageError with the step that failed and what to do.
+*
+* @example
+* ```ts
+* await startDev({ io, output, host, timeoutMs: 900_000, showKeys: false, rotateKeys: false })
+* ```
+*/
+declare function startDev(options: DevOptions): Promise<void>;
+/**
+* `tula dev down`: stop the project's stack. With `volumes` the database is deleted too, and
+* the keys `tula dev` wrote (which that database no longer knows) are removed from
+* `.env.local`; every other line of the file stays. A tunnel `tula dev --tunnel` opened is
+* closed first, and its address is taken out of the block.
+*
+* @param options - Where and how to run, and whether to delete the data.
+* @throws UsageError when Docker fails.
+*
+* @example
+* ```ts
+* await stopDev({ io, output, host, projectName: 'shop', volumes: false })
+* ```
+*/
+declare function stopDev(options: Pick<DevOptions, "io" | "output" | "host" | "projectName" | "tunnelService"> & {
+	volumes: boolean;
+}): Promise<void>;
+import { AdminSchemas } from "@tula-tech/admin";
+import { EnvironmentConfig, NativeAppConfig } from "@tula-tech/config";
+import { EnvironmentSettings, EnvironmentSettingsInput, HookPoint, OAuthProvider, SettingsManagedBy } from "@tula-tech/contract";
+/**
+* The name `tula apply` records itself under as the manager of an environment's settings.
+*
+* @example
+* ```ts
+* headers['x-tula-managed-by'] = MANAGING_TOOL
+* ```
+*/
+declare const MANAGING_TOOL = "tula-apply";
+/**
+* Lists in the settings document that are **sets**: their order means nothing to the server
+* (an origin is allowed or it is not, a country is texted or it is not), so a reordering is
+* not a change, and a change is shown as the entries added and removed. Every other list is
+* compared in order.
+*
+* @example
+* ```ts
+* diffValues(current, desired, SET_PATHS)
+* ```
+*/
+declare const SET_PATHS: readonly string[];
+/**
+* One difference between what a server has and what a config says.
+*
+* @example
+* ```ts
+* const change: Change = { path: 'app.name', kind: 'changed', before: 'Tula', after: 'Northline' }
+* ```
+*/
+interface Change {
+	/** Where, dot-separated. */
+	path: string;
+	/** `added`: only the config has it. `removed`: only the server has it. `changed`: both do. */
+	kind: "added" | "changed" | "removed";
+	/** The server's value. */
+	before?: unknown;
+	/** The config's value. */
+	after?: unknown;
+	/** For a list that is a set: the entries the config adds. */
+	added?: unknown[];
+	/** For a list that is a set: the entries the config removes. */
+	removed?: unknown[];
+}
+/**
+* The structural difference between two values, by path.
+*
+* Objects are compared key by key at any depth; a key only one side has is `added` or
+* `removed` as a whole. A list on one of `setPaths` is compared as a set; any other list, and
+* every scalar, by value. A key set to `undefined` counts as absent. JWT templates are a set
+* by name and a template's claims a set by key (maps, so their order never counts); one claim
+* is compared as a whole value. An email template is compared by its subject and its body,
+* and a text message template by its text, also when only one side has it.
+*
+* @param before - What the server has.
+* @param after - What the config says.
+* @param setPaths - Paths of the lists that are sets.
+* @returns The changes, in the order of the config's keys; empty when there are none.
+*
+* @example
+* ```ts
+* diffValues({ app: { name: 'Tula' } }, { app: { name: 'Northline' } })
+* // [{ path: 'app.name', kind: 'changed', before: 'Tula', after: 'Northline' }]
+* ```
+*/
+declare function diffValues(before: unknown, after: unknown, setPaths?: readonly string[]): Change[];
+/**
+* A provider as the admin API lists it.
+*
+* @example
+* ```ts
+* const { data } = await admin.call('listOAuthProviders')
+* const providers: RemoteProvider[] = data.data
+* ```
+*/
+type RemoteProvider = AdminSchemas["OAuthProviderSettings"];
+/**
+* What a server has for one environment: its settings, their revision and manager, and its
+* providers.
+*
+* @example
+* ```ts
+* const state: RemoteState = { ...settingsResponse.data, providers: providersResponse.data.data }
+* ```
+*/
+interface RemoteState {
+	/** The settings' revision: what the replace is conditional on. */
+	revision: number;
+	/** The settings document in force. */
+	settings: EnvironmentSettings;
+	/** Who manages the settings; `null` for nobody; `undefined` from a server that does not say. */
+	managedBy?: SettingsManagedBy | null;
+	/** Every provider, configured or not. */
+	providers: readonly RemoteProvider[];
+	/**
+	* How many accounts depend on a provider, for the providers the run was asked about: the
+	* ones the plan switches off or removes ({@link providersGoingOff}). `null` for one whose
+	* count could not be read; a provider that was not asked about is left out.
+	*/
+	dependents?: RemoteDependents;
+	/**
+	* The webhook endpoints, oldest first. Left out when the config does not manage webhooks:
+	* they are then not even read.
+	*/
+	webhooks?: readonly RemoteWebhook[];
+	/**
+	* The hooks, oldest first. Left out when the config does not manage hooks: they are then
+	* not even read.
+	*/
+	hooks?: readonly RemoteHook[];
+	/**
+	* The native apps, oldest first. Left out when the config does not manage native apps: they
+	* are then not even read.
+	*/
+	nativeApps?: readonly RemoteNativeApp[];
+}
+/**
+* A native app as the admin API lists it.
+*
+* @example
+* ```ts
+* const { data } = await admin.call('listNativeApps')
+* const apps: RemoteNativeApp[] = data.data
+* ```
+*/
+type RemoteNativeApp = AdminSchemas["NativeApp"];
+/**
+* What a run does with one native app.
+*
+* @example
+* ```ts
+* const change: NativeAppChange = planNativeApps(remote.nativeApps, environment.nativeApps, {}).apps[0]
+* ```
+*/
+interface NativeAppChange {
+	/** The platform: `ios`, `android`, or whatever a later server sent. */
+	platform: string;
+	/**
+	* The bundle id or the package name. With the platform it is what names an app: the file's
+	* for an entry of the file, the server's otherwise.
+	*/
+	identifier: string;
+	/** The server's id of the app. Absent for one to create. */
+	id?: string;
+	/**
+	* `create`, `update`, `delete`; `none` when it already is as the config says; `unmanaged`
+	* when the server has it and the config does not list it (left alone without `--prune`);
+	* `unknown` when its platform is one this version of the CLI does not know, which no file
+	* can name and no run touches, `--prune` or not.
+	*/
+	action: "create" | "update" | "delete" | "none" | "unmanaged" | "unknown";
+	/**
+	* The differences: `teamId` of an iOS app; `sha256CertFingerprints` of an Android app, as a
+	* set (`added`, `removed`); `appLinkPaths` of either, as a set, and only where the entry
+	* writes the key. For an app to create, what it is registered with (its link paths only
+	* when it has some).
+	*/
+	fields: Change[];
+	/**
+	* Where the change widens who the platforms will believe is the environment's app, as the
+	* contract's `nativeAppWeakenings` judges it: `nativeApps.<platform>/<identifier>` for a
+	* registration, and that with `.teamId`, `.sha256CertFingerprints` or `.appLinkPaths` for a
+	* changed team, a gained fingerprint or a gained link path. Part of the plan's `weakened`.
+	*/
+	weakened: string[];
+	/** The config's entry, for an app the run creates or updates: what the write sends. */
+	entry?: NativeAppConfig;
+	/**
+	* How many link paths the server has for this app that the file does not manage, because
+	* its entry leaves `appLinkPaths` out. Present only when that is more than none. They are
+	* kept, and are no difference of the plan: this is for the one line that says so.
+	*/
+	unmanagedLinkPaths?: number;
+}
+/**
+* What a run does with an environment's native apps.
+*
+* @example
+* ```ts
+* if (plan.nativeApps.overLimit !== null) {
+*   // the environment would have more apps than it may
+* }
+* ```
+*/
+interface NativeAppPlan {
+	/** Whether the config has a `nativeApps` list at all. Without one nothing is read or changed. */
+	managed: boolean;
+	/** One entry per app of the file, in its order, then the server's other apps. */
+	apps: NativeAppChange[];
+	/**
+	* How many apps the environment would have once the plan is applied, when that is more than
+	* it may have (`MAX_NATIVE_APPS`); `null` otherwise.
+	*/
+	overLimit: number | null;
+	/**
+	* What the plan read of the server's apps ({@link nativeAppSnapshot}): `tula apply` reads
+	* them again before its first write to one and stops if this no longer matches.
+	*/
+	seen: string;
+}
+/**
+* A hook as the admin API lists it. Never with its signing secret: no read returns one.
+*
+* @example
+* ```ts
+* const { data } = await admin.call('listHooks')
+* const hooks: RemoteHook[] = data.data
+* ```
+*/
+type RemoteHook = AdminSchemas["Hook"];
+/**
+* What a run does with one hook.
+*
+* @example
+* ```ts
+* const change: HookChange = planHooks(remote.hooks, environment.hooks, {}).hooks[0]
+* ```
+*/
+interface HookChange {
+	/** The point, which is what names a hook: an environment has at most one per point. */
+	point: string;
+	/** The server's id of the hook. Absent for one to create. */
+	id?: string;
+	/** The hook's address: the file's for an entry of the file, the server's otherwise. */
+	url: string;
+	/**
+	* `create`, `update`, `delete`; `none` when it already is as the config says; `unmanaged`
+	* when the server has it and the config has no entry for its point (left alone without
+	* `--prune`); `unknown` when its point is one this version of the CLI does not know, which
+	* no file can name and no run touches, `--prune` or not.
+	*/
+	action: "create" | "update" | "delete" | "none" | "unmanaged" | "unknown";
+	/** The differences in `url`, `enabled`, `deadlineMs` and `failureMode`, in that order. */
+	fields: Change[];
+	/**
+	* Where the change lets through what the hook stops, as the contract's `hookWeakenings`
+	* judges it: `hooks.<point>.failureMode`, `hooks.<point>.enabled`, or `hooks.<point>` for
+	* the removal of a hook that is on. Part of the plan's `weakened`.
+	*/
+	weakened: string[];
+}
+/**
+* What a run does with an environment's hooks.
+*
+* @example
+* ```ts
+* if (plan.hooks.managed) {
+*   // the file has a `hooks` key: the server's hooks were read
+* }
+* ```
+*/
+interface HookPlan {
+	/** Whether the config has a `hooks` key at all. Without one nothing is read or changed. */
+	managed: boolean;
+	/** One entry per point the file or the server has a hook for, in the contract's order. */
+	hooks: HookChange[];
+	/**
+	* What the plan read of the server's hooks ({@link hookSnapshot}): `tula apply` reads them
+	* again before its first write to one and stops if this no longer matches.
+	*/
+	seen: string;
+}
+/**
+* A webhook endpoint as the admin API lists it. Never with its signing secret: no read
+* returns one.
+*
+* @example
+* ```ts
+* const { data } = await admin.call('listWebhookEndpoints')
+* const endpoints: RemoteWebhook[] = data.data
+* ```
+*/
+type RemoteWebhook = AdminSchemas["WebhookEndpoint"];
+/**
+* What a run does with one webhook endpoint.
+*
+* @example
+* ```ts
+* const change: WebhookChange = planWebhooks(remote.webhooks, environment.webhooks, {}).endpoints[0]
+* ```
+*/
+interface WebhookChange {
+	/**
+	* The endpoint's address, which is what identifies it: the file's for an entry of the file,
+	* the server's for an endpoint only the server has. Compared exactly, as the server stores
+	* and compares it.
+	*/
+	url: string;
+	/** The server's id of the endpoint. Absent for one to create and for one that is `ambiguous`. */
+	id?: string;
+	/**
+	* `create`, `update`, `delete`; `none` when it already is as the config says; `unmanaged`
+	* when the server has it and the config's list does not (left alone without `--prune`);
+	* `ambiguous` when the server has the address more than once, so the entry cannot be
+	* matched to one endpoint and nothing is done to any of them.
+	*/
+	action: "create" | "update" | "delete" | "none" | "unmanaged" | "ambiguous";
+	/**
+	* The differences in `eventTypes` (a set: the types added and removed, sorted) and, only
+	* when the file writes it, `enabled`.
+	*/
+	fields: Change[];
+	/**
+	* Set when the run switches on an endpoint the **server** switched off: the server's reason
+	* (`failing`, `gone`), so that a pipeline does not quietly undo it on every run.
+	*/
+	reenables?: string;
+	/** For `ambiguous`: the ids of the server's endpoints with this address. */
+	duplicates?: string[];
+}
+/**
+* What a run does with an environment's webhook endpoints.
+*
+* @example
+* ```ts
+* if (plan.webhooks.overLimit !== null) {
+*   // the run is refused before any write
+* }
+* ```
+*/
+interface WebhookPlan {
+	/** Whether the config has a `webhooks` list at all. Without one nothing is read or changed. */
+	managed: boolean;
+	/** One entry per entry of the file, in its order, then the endpoints only the server has. */
+	endpoints: WebhookChange[];
+	/**
+	* How many removals are made **before** the creations because the environment is too close
+	* to its limit to hold the new endpoints beside the ones being removed. Otherwise `0`:
+	* everything is created before anything is removed.
+	*/
+	removedFirst: number;
+	/**
+	* How many endpoints the environment would have after the run, when that is more than it
+	* may have (`MAX_WEBHOOK_ENDPOINTS`); `null` when the plan fits.
+	*/
+	overLimit: number | null;
+	/**
+	* What the plan read of the server's endpoints ({@link webhookSnapshot}): `tula apply` reads
+	* them again before its first webhook write and stops if this no longer matches.
+	*/
+	seen: string;
+}
+/**
+* The accounts that depend on a provider, as the server counted them
+* (`GET /v1/admin/oauth-providers/{provider}/dependents`, ADR 0059): how many of the
+* accounts it looked at can sign in only with that provider, and whether there were more
+* accounts than it looks at (the number is then a floor). Two values and nothing about who.
+*
+* @example
+* ```ts
+* const count: DependentCount = { accounts: 3, more: false }
+* ```
+*/
+interface DependentCount {
+	/** How many were found among the accounts looked at. */
+	accounts: number;
+	/** Whether not every account was looked at: read `accounts` as "at least". */
+	more: boolean;
+}
+/**
+* A count the server should have had and the run could not read: a request that failed or
+* got no answer, a refusal, an answer of another shape. Not known, never zero, and never
+* "not judged": the plan is flagged as if the server had not looked at every account,
+* because `tula apply --yes` must not get past a count for the reason that it failed.
+*
+* @example
+* ```ts
+* const dependents: RemoteDependents = { x: DEPENDENTS_UNREAD }
+* ```
+*/
+declare const DEPENDENTS_UNREAD = "unread";
+/**
+* What a run knows of one provider's dependent accounts: the count; {@link DEPENDENTS_UNREAD}
+* for one that could not be read; `null` for a server that has none to give (one from
+* before the route), the only case in which nothing is judged.
+*
+* @example
+* ```ts
+* const known: KnownDependents = { accounts: 3, more: false }
+* ```
+*/
+type KnownDependents = DependentCount | typeof DEPENDENTS_UNREAD | null;
+/**
+* What a run knows of the dependent accounts, by provider.
+*
+* @example
+* ```ts
+* const dependents: RemoteDependents = { x: { accounts: 3, more: false }, github: null }
+* ```
+*/
+type RemoteDependents = Partial<Record<OAuthProvider, KnownDependents>>;
+/**
+* Read a server's answer about a provider's dependent accounts. Only an answer of exactly
+* the expected shape is a count: the provider that was asked about, a whole number that is
+* not negative, a boolean. Anything else is "not read", never zero.
+*
+* @param provider - The provider that was asked about.
+* @param answer - What the server answered.
+* @returns The count, or `null` when the answer is not one.
+*
+* @example
+* ```ts
+* readDependentCount('x', { provider: 'x', accounts: 3, more: false }) // { accounts: 3, more: false }
+* readDependentCount('x', { provider: 'x', accounts: '3' }) // null
+* ```
+*/
+declare function readDependentCount(provider: OAuthProvider, answer: unknown): DependentCount | null;
+/**
+* What a run does with one provider.
+*
+* @example
+* ```ts
+* const change: ProviderChange = planProviders(remote.providers, environment.providers, {})[0]
+* ```
+*/
+interface ProviderChange {
+	/** The provider. */
+	provider: OAuthProvider;
+	/**
+	* `create`, `update`, `delete`; `none` when it already is as the config says; `unmanaged`
+	* when the server has it and the config does not (left alone without `--prune`).
+	*/
+	action: "create" | "update" | "delete" | "none" | "unmanaged";
+	/**
+	* The differences in its fields that are not secret: `clientId`, `teamId`, `keyId`,
+	* `tenant`, `additionalClientIds` (a set, with what is `added` and `removed`), `enabled`.
+	*/
+	fields: Change[];
+	/**
+	* What happens to its secret: `set` (written from the environment variable), `keep` (the
+	* stored one stays) or `none` (there is none to speak of). Never the value.
+	*/
+	secret: "set" | "keep" | "none";
+	/** The variable the secret is read from, when the config manages the provider. */
+	secretEnv?: string;
+	/** Whether sign-in offers it now. */
+	enabledBefore: boolean;
+	/** Whether sign-in offers it after the run. */
+	enabledAfter: boolean;
+	/**
+	* The paths at which the run makes the provider accept more than it does: a client id
+	* gained in Google's `additionalClientIds` (`providers.google.additionalClientIds`; the
+	* field's name, never an id); and, where accounts depend on it (ADR 0059),
+	* `providers.<provider>.enabled` for one the run switches off and `providers.<provider>`
+	* for one it removes. Part of the plan's `weakened`.
+	*/
+	weakened: string[];
+	/**
+	* Only for a provider the run switches off or removes, and only when the run asked the
+	* server: the accounts that depend on it; `'unread'` when the count could not be read
+	* (the plan is then flagged); `null` when the server has no count to give (then nothing
+	* is judged). The plan says which.
+	*/
+	dependents?: KnownDependents;
+}
+/** Options of a plan. */
+interface PlanOptions {
+	/** Delete providers the server has and the config does not. */
+	prune?: boolean;
+	/** Send every managed provider's secret again, changed or not. */
+	rotateSecrets?: boolean;
+}
+/**
+* Decide what to do with each provider.
+*
+* A secret cannot be compared: the API never returns one. So it is written when the provider
+* is created, when one of its identifying fields changes (a new client id comes with a new
+* secret) and when `rotateSecrets` asks; switching a provider on or off keeps the stored one,
+* and so does a change of Microsoft's `tenant` (which accounts may sign in: the app
+* registration, and so its secret, is the same) or of Google's `additionalClientIds`.
+* That is what makes a second run a no-op.
+*
+* Google's `additionalClientIds` (ADR 0045) are compared as a set, against none where the
+* file leaves them out or the server does not report the field; an id the file adds is the
+* entry's `weakened`.
+*
+* A provider the server has **on** that the run switches off or removes is a weakening where
+* accounts depend on it (ADR 0059: `providers.<provider>.enabled`, `providers.<provider>`).
+* The engine does not count: it is handed what the run read (`dependents`), judges
+* nothing for a provider whose count is missing or `null` (a server with none to give),
+* and flags one whose count could not be read.
+*
+* @param remote - The providers as the server lists them.
+* @param desired - The providers of the config's environment.
+* @param options - `prune`, `rotateSecrets`.
+* @param dependents - The dependent accounts the run counted, by provider.
+* @returns One entry per provider that the config or the server knows, by provider name.
+*
+* @example
+* ```ts
+* planProviders(remote.providers, environment.providers, { prune: true }, remote.dependents)
+* ```
+*/
+declare function planProviders(remote: readonly RemoteProvider[], desired: EnvironmentConfig["providers"], options: PlanOptions, dependents?: RemoteDependents): ProviderChange[];
+/**
+* The providers a run would take away from sign-in: on at the server, and switched off by
+* the file or removed (`--prune`). They are the only ones whose dependent accounts a run
+* asks the server to count, before the plan is made.
+*
+* @param remote - The providers as the server lists them.
+* @param desired - The providers of the config's environment.
+* @param options - `prune`.
+* @returns The providers, by name.
+*
+* @example
+* ```ts
+* providersGoingOff(remote.providers, environment.providers, { prune: true }) // ['x']
+* ```
+*/
+declare function providersGoingOff(remote: readonly RemoteProvider[], desired: EnvironmentConfig["providers"], options: Pick<PlanOptions, "prune">): OAuthProvider[];
+/**
+* Whether the server records this config as the manager of the settings, and why not.
+*
+* @example
+* ```ts
+* if (plan.marker.reason === 'drifted') {
+*   warn('changed outside the config file')
+* }
+* ```
+*/
+interface MarkerPlan {
+	/** Whether the server reports a manager at all (an older one does not). */
+	supported: boolean;
+	/** Whether a run would record this config as the manager. */
+	pending: boolean;
+	/**
+	* Why: `unmanaged` (nobody is on record), `other-tool`, `other-config` (another version of
+	* the file was applied), `drifted` (the settings were replaced around the file since), or
+	* `none` (it is on record, or the server does not record one).
+	*/
+	reason: "unmanaged" | "other-tool" | "other-config" | "drifted" | "none";
+	/** The manager on record. */
+	current: SettingsManagedBy | null;
+	/** This config's fingerprint. */
+	configHash: string;
+}
+/**
+* Everything a run would do to one environment.
+*
+* @example
+* ```ts
+* const plan: Plan = buildPlan(remote, environment, { configHash })
+* process.exitCode = plan.changes ? 2 : 0
+* ```
+*/
+interface Plan {
+	/** The settings revision the plan was made against. */
+	revision: number;
+	/** The differences in the settings document. */
+	settings: Change[];
+	/**
+	* Paths where the run weakens security: the settings' (the contract's
+	* `settingsWeakenings`), then the providers' (`oauthProviderWeakenings`, as
+	* `providers.<provider>…`), then the hooks' (`hookWeakenings`, as `hooks.<point>…`), then the
+	* native apps' (`nativeAppWeakenings`, as `nativeApps.<platform>/<identifier>…`).
+	*/
+	weakened: string[];
+	/** Settings the file leaves out whose default is the deployment's: kept as the server has them. */
+	kept: string[];
+	/** Settings the server has that this version of the CLI does not know. */
+	unknown: string[];
+	/** What happens to each provider. */
+	providers: ProviderChange[];
+	/** What happens to each webhook endpoint, when the config manages them. */
+	webhooks: WebhookPlan;
+	/** What happens to each hook, when the config manages them. */
+	hooks: HookPlan;
+	/** What happens to each native app, when the config manages them. */
+	nativeApps: NativeAppPlan;
+	/** Whether the server records this config as the settings' manager. */
+	marker: MarkerPlan;
+	/** The document a replace would send. */
+	body: EnvironmentSettingsInput;
+	/** Whether a run would change anything. */
+	changes: boolean;
+}
+/**
+* Compare a server's state with a config's environment.
+*
+* The file is the whole truth for what it can express: a setting it leaves out goes back to
+* its default. The exceptions are the two settings whose default is the **deployment's**
+* (`password`, `urls.allowedOrigins`), which only the server knows: left out, they are kept as
+* the server has them and listed in `kept`.
+*
+* @param remote - What the server has.
+* @param environment - The config's environment.
+* @param options - The config's fingerprint, `prune`, `rotateSecrets`.
+* @returns The plan.
+*
+* @example
+* ```ts
+* const plan = buildPlan(remote, selectEnvironment(config, 'prod'), { configHash })
+* ```
+*/
+declare function buildPlan(remote: RemoteState, environment: EnvironmentConfig, options: PlanOptions & {
+	configHash: string;
+}): Plan;
+/**
+* One write of a run.
+*
+* @example
+* ```ts
+* for (const operation of orderOperations(plan)) {
+*   await run(operation)
+* }
+* ```
+*/
+type Operation = {
+	kind: "settings";
+} | {
+	kind: "provider.set";
+	provider: OAuthProvider;
+	change: ProviderChange;
+} | {
+	kind: "provider.delete";
+	provider: OAuthProvider;
+	change: ProviderChange;
+} | {
+	kind: "webhook.create";
+	url: string;
+	change: WebhookChange;
+} | {
+	kind: "webhook.update";
+	url: string;
+	id: string;
+	change: WebhookChange;
+} | {
+	kind: "webhook.delete";
+	url: string;
+	id: string;
+	change: WebhookChange;
+} | {
+	kind: "hook.create";
+	point: HookPoint;
+	change: HookChange;
+} | {
+	kind: "hook.update";
+	point: HookPoint;
+	id: string;
+	change: HookChange;
+} | {
+	kind: "hook.delete";
+	point: HookPoint;
+	id: string;
+	change: HookChange;
+} | {
+	kind: "nativeApp.create";
+	entry: NativeAppConfig;
+	change: NativeAppChange;
+} | {
+	kind: "nativeApp.update";
+	id: string;
+	entry: NativeAppConfig;
+	change: NativeAppChange;
+} | {
+	kind: "nativeApp.delete";
+	id: string;
+	change: NativeAppChange;
+};
+/**
+* The writes of a plan, in an order in which every intermediate state is one the server
+* accepts.
+*
+* The server refuses to leave an environment with no way to sign in: its settings need a
+* native method (password, email code, passkey) or an enabled OAuth provider. So:
+*
+* 1. writes that add a way in or change none: creating a provider, enabling one, new
+*    credentials;
+* 2. writes that take one away: switching a provider off, then deleting providers.
+*
+* and the settings go **first** whenever the document they produce has a native method of its
+* own: nothing after them can then be refused for want of a way in, and a settings revision
+* that turned out stale stops the run before anything was written. Only when the file
+* switches every native method off do the settings wait for the providers they rely on.
+*
+* **Webhook endpoints come after the settings and every provider.** Nothing about
+* signing in depends on them, and a registration is the write most likely to be refused for
+* a reason outside the file (the server could not resolve the address, the environment is at
+* its limit): a failure there must find the settings and the providers already as the file
+* says, and a stale settings revision must stop the run before an endpoint is touched.
+* Among themselves: changes to existing endpoints, then new ones, then removals, so that an
+* address being replaced is never without an endpoint. The one exception is the limit
+* (`MAX_WEBHOOK_ENDPOINTS`): when the new endpoints do not fit beside the ones being removed,
+* exactly as many removals as it takes (`plan.webhooks.removedFirst`, oldest first) go before
+* the creations.
+*
+* **Hooks come after the webhook endpoints, and native apps last.** For hooks: an endpoint the same run registers is
+* then there to be told of what the run does to a hook (`hook.updated` with `weakened`),
+* since an event is owed only to endpoints registered before it happened. A hook's
+* registration can be refused for the same outside reasons as an endpoint's. Among
+* themselves, so that a run that stops half-way leaves the environment no laxer than it has
+* to: new hooks, then changes that loosen nothing, then changes that loosen one (switched
+* off, `allow`), then removals. Hooks at different points do not depend on each other and
+* each write is one request, so no intermediate state is laxer than both the start and the
+* end.
+*
+* Nothing else in a plan depends on a native app, and nothing about signing in on the web
+* does. Among themselves, for the same reason as the hooks' order and so that the limit
+* (`MAX_NATIVE_APPS`) is never met on the way to a state that fits: removals, then changes
+* that widen nothing (a fingerprint or a link path taken away), then changes that widen
+* (another team, a gained fingerprint, a gained link path), then registrations.
+*
+* @param plan - The plan.
+* @returns The writes, in order; empty when the plan changes nothing.
+*
+* @example
+* ```ts
+* orderOperations(plan).map((operation) => operation.kind) // ['settings', 'provider.set']
+* ```
+*/
+declare function orderOperations(plan: Plan): Operation[];
+import { InstanceClient } from "@tula-tech/admin";
+/**
+* How one check went.
+*
+* @example
+* ```ts
+* const status: CheckStatus = 'warn'
+* ```
+*/
+type CheckStatus = "ok" | "warn" | "fail" | "skipped";
+/**
+* One line of `tula doctor`'s report.
+*
+* @example
+* ```ts
+* const check: DoctorCheck = { id: 'api', source: 'cli', status: 'ok', summary: 'The API answers.' }
+* ```
+*/
+interface DoctorCheck {
+	/** Stable identifier, e.g. `database`. */
+	id: string;
+	/** Where it ran: on this machine, or inside the API. */
+	source: "cli" | "server";
+	/** How it went. */
+	status: CheckStatus;
+	/** One sentence saying what was found. */
+	summary: string;
+	/** What to do about it. */
+	fix?: string;
+	/** Values the operator needs, e.g. redirect URIs. */
+	values?: string[];
+}
+/**
+* What `tula doctor` found.
+*
+* @example
+* ```ts
+* const report = await examine({ apiUrl, instance, io })
+* process.exit(exitCode(report, false))
+* ```
+*/
+interface DoctorReport {
+	/** The API that was examined. */
+	apiUrl: string;
+	/** The API's version, when it answered. */
+	version?: string;
+	/** The deployment tier, when the server-side checks ran. */
+	environment?: string;
+	/** Every check, the CLI's own first. */
+	checks: DoctorCheck[];
+}
+/**
+* Text from a server, made safe for a terminal and bounded: no control characters (an escape
+* sequence could rewrite the screen or the window title), and nothing invisible that changes
+* how the rest reads (a right-to-left override would show `all good` for a failing check's
+* text; a zero-width space splits a word a reader would search for).
+*
+* @param value - What the server sent.
+* @param max - The longest text kept, in UTF-16 units; a character is never cut in half.
+* @returns Printable text.
+*
+* @example
+* ```ts
+* printable('ok\u001b[2J') // 'ok [2J'
+* printable('ok\u{202E}txt.exe') // 'oktxt.exe'
+* ```
+*/
+declare function printable(value: unknown, max?: number): string;
+/**
+* Examine a deployment: what this machine can see (the API answers, its version, the two
+* clocks, a loopback `PUBLIC_URL`) and what the API reports about itself through
+* `GET /v1/instance/diagnostics`.
+*
+* It never throws for something a check can say: an unreachable API is a failing check.
+*
+* @param input - The API's URL, the instance client (`null` without an admin token), the io,
+*   and optionally a signal: aborting it ends the request in flight, and the run answers with
+*   the failing check an unreachable API gets (`tula mcp` abandons a run that takes too long).
+* @returns The report.
+*
+* @example
+* ```ts
+* const report = await examine({ apiUrl: 'http://localhost:3003', instance, io })
+* ```
+*/
+declare function examine(input: {
+	apiUrl: string;
+	instance: InstanceClient | null;
+	io: CliIo;
+	signal?: AbortSignal;
+}): Promise<DoctorReport>;
+/**
+* The exit code of a report: `1` when a check failed, or warned under `--strict`.
+*
+* @param report - The report.
+* @param strict - Whether a warning fails too.
+* @returns `0` or `1`.
+*
+* @example
+* ```ts
+* exitCode(report, flags.strict === true)
+* ```
+*/
+declare function exitCode(report: DoctorReport, strict: boolean): number;
+/**
+* The report as data, for `--json`.
+*
+* @param report - The report.
+* @param strict - Whether a warning fails.
+* @returns A JSON-ready object.
+*
+* @example
+* ```ts
+* output.line(JSON.stringify(reportToJson(report, false), null, 2))
+* ```
+*/
+declare function reportToJson(report: DoctorReport, strict: boolean): {
+	/** The API that was examined. */
+	apiUrl: string;
+	/** The API's version, when it answered. */
+	version?: string;
+	/** The deployment tier, when the server-side checks ran. */
+	environment?: string;
+	/** Every check, the CLI's own first. */
+	checks: DoctorCheck[];
+	ok: boolean;
+};
+/**
+* Print the report as a table, with a fix line under each check that is not ok.
+*
+* @param output - Where to write.
+* @param report - The report.
+*
+* @example
+* ```ts
+* renderReport(output, report)
+* ```
+*/
+declare function renderReport(output: Output, report: DoctorReport): void;
+/**
+* The warnings of a plan, as sentences.
+*
+* @param plan - The plan.
+* @returns One line per warning; empty when there are none.
+*
+* @example
+* ```ts
+* planWarnings(plan) // ['weakens security: mfa.policy']
+* ```
+*/
+declare function planWarnings(plan: Plan): string[];
+/**
+* What `tula apply` will not do to a plan without being told to: reset settings this version
+* does not know (`--allow-unknown`); when nobody is asked (`--yes`), weaken security
+* (`--allow-weaker`) or remove a webhook endpoint with its delivery log
+* (`--allow-webhook-removal`); and create a webhook endpoint or a hook without a word on what
+* becomes of its signing secret (`--secrets-file`, `--show-secrets` or `--discard-secrets`).
+*
+* @param plan - The plan.
+* @returns Which of them the plan needs.
+*
+* @example
+* ```ts
+* applyRequirements(plan)
+* // { allowUnknown: false, allowWeaker: true, allowWebhookRemoval: false,
+* //   webhookSecrets: false, hookSecrets: false }
+* ```
+*/
+declare function applyRequirements(plan: Plan): {
+	allowUnknown: boolean;
+	allowWeaker: boolean;
+	allowWebhookRemoval: boolean;
+	webhookSecrets: boolean;
+	hookSecrets: boolean;
+};
+/**
+* One line that says what a write does.
+*
+* @param operation - The write.
+* @returns E.g. `settings: replace`, `provider google: create`, `webhook https://…: remove`,
+*   `hook before_sign_up: update`, `native app ios com.example.app: register`.
+*
+* @example
+* ```ts
+* describeOperation({ kind: 'settings' }) // 'settings: replace'
+* ```
+*/
+declare function describeOperation(operation: Operation): string;
+/**
+* Print a plan for a person: what would be added, changed and removed, by path, with warnings.
+* A provider's secret shows as "set from $NAME" or "kept", never as a value.
+*
+* @param output - Where to write.
+* @param target - The environment's name in the config and the API's URL.
+* @param plan - The plan.
+*
+* @example
+* ```ts
+* renderPlan(output, { environment: 'prod', apiUrl }, plan)
+* ```
+*/
+declare function renderPlan(output: Output, target: {
+	environment: string;
+	apiUrl: string;
+}, plan: Plan): void;
+/**
+* A plan for a machine: the same content as {@link renderPlan}, as plain data. A provider's
+* secret appears as `set` or `keep` and the name of its variable, never as a value; a webhook
+* endpoint's and a hook's secret do not appear at all (no read returns one).
+*
+* @param target - The environment's name in the config and the API's URL.
+* @param plan - The plan.
+* @returns A JSON-serialisable object.
+*
+* @example
+* ```ts
+* output.line(JSON.stringify(planToJson({ environment: 'prod', apiUrl }, plan), null, 2))
+* ```
+*/
+declare function planToJson(target: {
+	environment: string;
+	apiUrl: string;
+}, plan: Plan): Record<string, unknown>;
+import { AdminClient, InstanceClient as InstanceClient2 } from "@tula-tech/admin";
+import { EnvironmentConfig as EnvironmentConfig2 } from "@tula-tech/config";
+/**
+* The API a run talks to.
+*
+* @example
+* ```ts
+* const { admin, apiUrl } = await resolveTarget({ name: 'prod', environment, flags, io, output })
+* ```
+*/
+interface Target {
+	/** The API's URL, for display. */
+	apiUrl: string;
+	/** The admin client, holding the secret key. */
+	admin: AdminClient;
+}
+/**
+* Work out which API a run talks to and with which key.
+*
+* - **URL**: `--api-url`, else `TULA_API_URL_<NAME>`, else `TULA_API_URL`. It must be https,
+*   or this machine (`localhost`, `*.localhost`, `127.0.0.1`, `[::1]`): over plain http the
+*   secret key and provider secrets cross the network in clear text. `--insecure-http` allows
+*   it for a private network you trust.
+* - **Secret key**: `--secret-key-file <path>` (`-` reads standard input, which must then be
+*   a pipe: a terminal would show the key as it is typed), else `TULA_SECRET_KEY_<NAME>`, else
+*   `TULA_SECRET_KEY`.
+*
+* `<NAME>` is the environment's name in the config, upper-cased, so one CI job can hold the
+* keys of several environments. Neither is ever read from the config file (it is committed),
+* and there is deliberately no option that takes the key itself: a command line is recorded
+* in shell history and visible in process lists. The key is registered with the output's
+* redaction before anything else can print.
+*
+* The secret key decides the environment. When the config's entry says which `kind` it is
+* for, a key of the other kind (`tula_sk_dev_…` for `production`) is refused here, before any
+* request.
+*
+* @param input - The environment's name and entry, the command's flags, and the run's io.
+* @returns The API's URL and an admin client.
+* @throws UsageError when the URL or the key is missing, the key is of the wrong kind, the key
+*   would be typed at a terminal, or the URL is plain http for another machine.
+* @throws TulaAdminError when the key is not a secret key or the URL is not usable.
+*
+* @example
+* ```ts
+* const target = await resolveTarget({ name: 'prod', environment, flags, io, output })
+* ```
+*/
+declare function resolveTarget(input: {
+	name: string;
+	/** The config's entry; only its `kind` is read. A command without a config passes `{}`. */
+	environment: Pick<EnvironmentConfig2, "kind">;
+	flags: Record<string, string | boolean | undefined>;
+	io: CliIo;
+	output: Output;
+}): Promise<Target>;
+/**
+* The agent's client of a run of `tula mcp`: the environment's **agent key**
+* (`--agent-key-file`, else `TULA_AGENT_KEY_<NAME>`, else `TULA_AGENT_KEY`) for the API a
+* target would use. An agent key reads what a secret key reads and asks for changes as
+* proposals; it changes nothing and approves nothing (ADR 0053). There is deliberately no
+* option that takes the key itself, and it is registered with the output's redaction before
+* anything can print.
+*
+* @param input - The environment's name, the command's flags and the run's io and output.
+* @returns The API's URL and the client, or `null` when no agent key is configured here.
+* @throws UsageError when the key cannot be read, is not an agent key, the URL is missing,
+*   or the URL is plain http for another machine.
+*
+* @example
+* ```ts
+* const agent = await resolveAgent({ name: 'default', flags, io, output })
+* ```
+*/
+declare function resolveAgent(input: {
+	name: string;
+	flags: Record<string, string | boolean | undefined>;
+	io: CliIo;
+	output: Output;
+}): Promise<Target | null>;
+/**
+* The API URL of a command that needs no config file: `--api-url`, else `TULA_API_URL`.
+*
+* @param flags - The command's flags.
+* @param io - The run's surroundings.
+* @returns The URL, without a trailing slash.
+* @throws UsageError when there is none, or it is not an http(s) URL.
+*
+* @example
+* ```ts
+* const apiUrl = resolveApiUrl(flags, io)
+* ```
+*/
+declare function resolveApiUrl(flags: Record<string, string | boolean | undefined>, io: CliIo): string;
+/**
+* Read a secret from a file or standard input: the two ways a credential reaches the CLI
+* without being on the command line.
+*
+* @param path - The option's value: a path, or `-` for standard input.
+* @param option - The option's name, for the messages.
+* @param io - The run's surroundings.
+* @returns The secret, trimmed.
+* @throws UsageError when it cannot be read, or would be typed at a terminal.
+*
+* @example
+* ```ts
+* const token = await readSecretFile(String(flags['admin-token-file']), '--admin-token-file', io)
+* ```
+*/
+declare function readSecretFile(path: string, option: string, io: CliIo): Promise<string>;
+/**
+* The instance client of a run: the deployment's admin token (`--admin-token-file`, else
+* `TULA_ADMIN_TOKEN`) for the API at `apiUrl`. There is deliberately no option that takes the
+* token itself. The token is registered with the output's redaction before anything can print.
+*
+* @param input - The API URL, the command's flags and the run's io and output.
+* @returns The client, or `null` when no token is configured here.
+* @throws UsageError when the token cannot be read, is not usable, or the URL is plain http
+*   for another machine.
+*
+* @example
+* ```ts
+* const instance = await resolveInstance({ apiUrl, flags, io, output })
+* ```
+*/
+declare function resolveInstance(input: {
+	apiUrl: string;
+	flags: Record<string, string | boolean | undefined>;
+	io: CliIo;
+	output: Output;
+}): Promise<InstanceClient2 | null>;
+/**
+* The CLI's version: `tula --version`, and the `User-Agent` of its requests. A test holds it
+* equal to the package's `version`.
+*
+* @example
+* ```ts
+* `tula-cli/${VERSION}` // 'tula-cli/0.1.1'
+* ```
+*/
+declare const VERSION = "0.1.1";
+/**
+* The commands of `tula`. A new command is added here.
+*
+* @example
+* ```ts
+* await runCli(['diff'], io, COMMANDS)
+* ```
+*/
+declare const COMMANDS: readonly Command[];
+/**
+* Run `tula` with the process's own surroundings: its streams, environment and directory.
+*
+* @param argv - The arguments after `tula`.
+* @param overrides - Parts of the surroundings to replace (a test's streams, an in-process
+*   `fetch`).
+* @returns The exit code. The caller exits with it.
+*
+* @example
+* ```ts
+* process.exit(await main(process.argv.slice(2)))
+* ```
+*/
+declare function main(argv: readonly string[], overrides?: Partial<CliIo>): Promise<number>;
+export { COMMANDS, Change, CheckStatus, CliIo, Command, CommandContext, DEPENDENTS_UNREAD, DEV_ENV_FILE, DependentCount, DevOptions, DoctorCheck, DoctorReport, EXIT, Host, KnownDependents, MANAGING_TOOL, MarkerPlan, Operation, OptionSpec, Output, ParsedArgs, Plan, PlanOptions, ProviderChange, RemoteDependents, RemoteProvider, RemoteState, RunOptions, RunResult, SET_PATHS, Sink, Styles, Target, UsageError, VERSION, applyCommand, applyRequirements, approveCommand, buildMcpServer, buildPlan, createOutput, describeOperation, devCommand, diffCommand, diffValues, doctorCommand, examine, exitCode, main, mcpCommand, orderOperations, parseArgs, parseDevBlock, planProviders, planToJson, planWarnings, policyCommand, printable, providersGoingOff, readDependentCount, readSecretFile, renderPlan, renderReport, reportError, reportToJson, resolveAgent, resolveApiUrl, resolveInstance, resolveTarget, runCli, shouldUseColor, startDev, stopDev, withDevBlock, withoutDevBlock };