@hot-updater/cli-tools 1.2.0-rc.6 → 1.2.0-rc.8

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { Readable } from "stream";
 import { Key as Key$1 } from "node:readline";
-import { AnyHotUpdaterPlugin, BundleSigningAdapter, ConfigInput, ConfiguredDatabase, EngineDatabase, HotUpdaterCoreApi, LocalSigningConfig, Migrator, NativeFingerprint, NativeFingerprintOptions, Platform, PluginClientPlugin, RequiredDeep, SchemaGenerator, SecretsAdapter, SigningConfig, StorageAdapter, StorageAdapterWith, StoragePutResult, ToolingDatabase } from "@hot-updater/plugin-core";
+import { AnyHotUpdaterPlugin, ConfigInput, ConfiguredDatabase, EngineDatabase, HotUpdaterCoreApi, Migrator, NativeFingerprint, NativeFingerprintOptions, Platform, PluginClientPlugin, RequiredDeep, SchemaGenerator, SecretRef, SecretsAdapter, SigningConfig, StorageAdapter, StorageAdapterWith, StoragePutResult, ToolingDatabase } from "@hot-updater/plugin-core";
 import { Readable as Readable$1, Writable } from "node:stream";
 import { ManifestArchive } from "@hot-updater/protocol";
 //#region src/BuildLogger.d.ts
@@ -19,12 +19,21 @@ interface BuildFailureSummaryConfig {
     includeEnd: boolean;
   }[];
 }
+/**
+ * Reads the short phase a live build line shows, such as `Compiling
+ * React-Core · 412 files`, from each line of the tool's raw output, or
+ * undefined for a line that starts no phase. One reader reads one run.
+ */
+type BuildPhaseReader = (line: string) => string | undefined;
 interface BuildLoggerConfig {
   logPrefix: string;
-  /** Lines that should be surfaced in prompt output as important events. */
-  importantLogPatterns: LinePattern[];
-  /** Progress stages: stage index advances when corresponding output patterns are observed. */
-  progressStages: LinePattern[][];
+  /**
+   * The log file to append to, such as an archive's for its export, instead
+   * of a new one.
+   */
+  logFilePath?: string;
+  /** A phase reader for each run. */
+  createPhaseReader: () => BuildPhaseReader;
   /** What a failure prints from the tool's raw output. */
   failureSummary: BuildFailureSummaryConfig;
 }
@@ -38,33 +47,48 @@ declare class BuildFailedError extends Error {
   readonly logPath: string | null;
   /** The lines of the tool's output the summary printed. */
   readonly summary: string[];
-  constructor(message: string, { logPath, summary, cause }: {
+  /**
+   * What to do about it, such as accepting an agreement, which the summary
+   * doesn't say: the one line a command prints after it, or null.
+   */
+  readonly hint: string | null;
+  constructor(message: string, { logPath, summary, hint, cause }: {
     logPath: string | null;
     summary: string[];
+    hint?: string | null;
     cause?: unknown;
   });
 }
+/**
+ * Runs a native build tool's output through a step: the step's live line
+ * shows the phase its reader finds, the log file keeps the raw output, and a
+ * failure prints the summary of it on stderr.
+ */
 declare class BuildLogger {
   private readonly config;
-  private state;
   private logWriter?;
+  private step?;
   private summaryLines;
   private tailLines;
   private openBlock?;
-  private readonly promptProgress;
-  private readonly stageCount;
   constructor(config: BuildLoggerConfig);
-  start(): Promise<void>;
   /**
-   * Writes the tool's raw output to the log file and reads its failure
-   * summary from it, and shows progress from `display`, a formatter's
-   * output of it such as xcbeautify's, or from the raw output without one.
+   * Opens the log, writes `header` to it, such as the tool's command line,
+   * which the terminal doesn't show, and starts the step titled `title`.
    */
-  processStream(input: Readable, { display }?: {
-    display?: Readable;
+  start({ title, header }: {
+    title: string;
+    header?: string[];
   }): Promise<void>;
+  /**
+   * Writes the tool's raw output to the log file, reads its failure summary
+   * from it, and shows its phases on the step's line.
+   */
+  processStream(input: Readable): Promise<void>;
   /** The build log, relative to the project, or null without one. */
   get logPath(): string | null;
+  /** The build log's absolute path, or null without one. */
+  get logFilePath(): string | null;
   /**
    * The lines of the raw output a failure prints: the ones the config's
    * `failureSummary` keeps, deduplicated, or the last lines without any.
@@ -74,19 +98,18 @@ declare class BuildLogger {
   private processSummaryLine;
   private keepSummaryLine;
   private consumeProgressStream;
-  private processProgressLine;
+  /**
+   * Ends the step with `message` and its duration, or, for a failure, as
+   * failed, then prints the failure summary and the log's path.
+   */
   stop(message?: string, success?: boolean): void;
   writeError(error: unknown): void;
   close(): Promise<void>;
-  private updateProgress;
-  private finishRemainingProgress;
-  private shouldLogLine;
   /**
    * Prints the failure summary and the log's path to stderr, so a `--json`
    * command's stdout stays its JSON.
    */
   private showFailureSummary;
-  private showLogFileLocation;
 }
 //#endregion
 //#region src/appSetup.d.ts
@@ -196,21 +219,77 @@ declare const banner: (version?: string) => string;
 declare const printBanner: (version?: string) => void;
 //#endregion
 //#region src/bundleSigning.d.ts
+/** The secret `signing: secret("bundle-signing-key")` names, which `secrets issue` creates. */
+declare const BUNDLE_SIGNING_KEY_SECRET = "bundle-signing-key";
+/** The command that creates and stores a bundle signing key. */
+declare const ISSUE_SIGNING_KEY_COMMAND = "npx hot-updater secrets issue bundle-signing-key";
+/** The command that stores a bundle signing key you have. */
+declare const PUT_SIGNING_KEY_COMMAND = "npx hot-updater secrets put bundle-signing-key <key.pem>";
+/** What deploy and doctor say when the config sets no `signing`. */
+declare const UNSIGNED_BUNDLES_WARNING = "Bundles are unsigned.";
+/** The next step after `UNSIGNED_BUNDLES_WARNING`. */
+declare const UNSIGNED_BUNDLES_NEXT_STEP = "To sign them, run:";
+/** What deploy and doctor say when `signing` is no shape it takes. */
+declare const INVALID_SIGNING_MESSAGE = "signing takes secret(\"bundle-signing-key\").";
+/** The next step after `INVALID_SIGNING_MESSAGE`. */
+declare const INVALID_SIGNING_NEXT_STEP = "Store your key:";
+/**
+ * The config's `signing`, read without reading any key:
+ * - `on`: signs, with the private key from a secret or a file. The
+ *   shorthand `secret("<name>")` is `{ enabled: true, privateKey }`;
+ * - `off`: `{ enabled: false }`, which turns signing off on purpose;
+ * - `unsigned`: no `signing`, which deploy and doctor warn about;
+ * - `invalid`: any other value, such as a signing adapter of earlier
+ *   releases, which deploy refuses rather than deploy unsigned.
+ */
+type BundleSigningState = {
+  readonly status: "on";
+  readonly key: {
+    readonly secret: string;
+  } | {
+    readonly privateKeyPath: string;
+  };
+} | {
+  readonly status: "off";
+} | {
+  readonly status: "unsigned";
+} | {
+  readonly status: "invalid";
+  readonly message: string;
+};
+declare const readBundleSigningState: (signing: unknown) => BundleSigningState;
+/** The `secret()` the config's `signing` reads its private key from, if any. */
+declare const bundleSigningSecretRef: (signing: unknown) => SecretRef | undefined;
+/**
+ * A bundle signing failure whose message the CLI prints as it is: it names
+ * the secret and the next step, and quotes no key material.
+ */
+declare class BundleSigningKeyError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
 interface BundleSigningSession {
-  readonly name: string;
   readonly publicKey: string;
   readonly signFileHash: (fileHash: string) => Promise<string>;
 }
 declare const readBundleSigningPublicKeyFile: (publicKeyPath: string, options?: {
   readonly cwd?: string;
 }) => Promise<string>;
-declare const prepareBundleSigning: (signing: SigningConfig | undefined, options?: {
+interface BundleSigningOptions {
   readonly cwd?: string;
-}) => Promise<BundleSigningSession | null>;
-/** Resolves the public identity of the configured bundle signer. */
-declare const getBundleSigningPublicKey: (signing: SigningConfig | undefined, options?: {
-  readonly cwd?: string;
-}) => Promise<string | null>;
+  /** The config's `secrets` adapter; the configured one by default. */
+  readonly secrets?: SecretsAdapter;
+}
+/**
+ * Prepares the run's bundle signing: the public key the app must embed, and
+ * a signer of SHA-256 file hashes that signs each hash once. Null when
+ * `signing` is omitted or `{ enabled: false }`.
+ */
+declare const prepareBundleSigning: (signing: unknown, options?: BundleSigningOptions) => Promise<BundleSigningSession | null>;
+/**
+ * The public key of the configured bundle signing key, in SPKI PEM; null
+ * when `signing` signs nothing.
+ */
+declare const getBundleSigningPublicKey: (signing: unknown, options?: BundleSigningOptions) => Promise<string | null>;
 //#endregion
 //#region src/ConfigBuilder.d.ts
 type BuildType = "bare" | "rock" | "expo";
@@ -364,8 +443,8 @@ declare const CREDENTIAL_ENV_NAMES: {
 //#endregion
 //#region src/credentialResolver.d.ts
 /**
- * The build credentials the CLI resolves by name. Deploy credentials reach
- * the config's adapters through `secretEnv`.
+ * The build credentials the CLI resolves by name. Adapter credentials are
+ * `secret()`s the adapters call.
  */
 interface Credentials {
   /** App Store Connect API key, for automatic signing and uploads. */
@@ -412,29 +491,34 @@ interface CredentialResolver {
   dispose(): Promise<void>;
 }
 /** The credentials Hot Updater issues itself after a sign-in. */
-type IssuedCredentialKind = Exclude<CredentialKind, "android-keystore">;
+type IssuedCredentialKind = "asc-api-key";
+/** The credentials `secrets put <name> <file>` stores from one file. */
+type FileCredentialKind = Exclude<CredentialKind, IssuedCredentialKind>;
+/**
+ * The command that stores the file you have as `name`: the service
+ * account's JSON key, or the app's upload keystore. `--kind` is named only
+ * for a name that is not the kind.
+ */
+declare const credentialPutCommand: (kind: FileCredentialKind, name?: string) => string;
 /**
  * The command that stores the key Hot Updater issues as `name`: an App
- * Store Connect API key after an Apple Account sign-in, a Play service
- * account after a Google one, and an upload keystore it creates.
+ * Store Connect API key after an Apple Account sign-in, and an upload
+ * keystore it creates.
  */
 declare const credentialIssueCommand: (kind: CredentialKind, name?: string) => string;
 /** The command group of each issued kind's shortcut, `<group> login`. */
 declare const CREDENTIAL_LOGIN_GROUPS: {
   readonly "asc-api-key": "apple";
-  readonly "play-service-account": "google-play";
 };
 /**
  * The command people meet first that issues `kind` as `name`: its shortcut,
- * `apple login` for an App Store Connect API key or `google-play login`
- * for a Play service account, which takes nothing and stores the kind's
- * own name; for another name, `credentialIssueCommand`.
+ * `apple login` for an App Store Connect API key, which takes nothing and
+ * stores the kind's own name; for another name, `credentialIssueCommand`.
  */
 declare const credentialLoginCommand: (kind: IssuedCredentialKind, name?: string) => string;
 /**
  * The command that stores a missing credential of `kind` as `name`: the
- * upload keystore Hot Updater creates, or the key it issues after a
- * sign-in.
+ * key Hot Updater issues after an Apple sign-in, or the file you have.
  */
 declare const credentialStoreCommand: (kind: CredentialKind, name?: string) => string;
 declare class CredentialUnavailableError extends Error {
@@ -565,15 +649,6 @@ type WriteHotUpdaterConfigResult = {
   path: string;
   reason?: string;
 };
-/**
- * `const <name> = secretEnv([...names])`, a helper a managed config reads
- * credentials with: from the environment and `.env.hotupdater` first, then
- * from the config's `secrets` adapter. `storageSecrets` and
- * `databaseSecrets` read each adapter's own, so a command that reaches only
- * one needs only its credentials; `deploySecrets` reads what both share.
- * Its builder imports `secretEnv` from `hot-updater`.
- */
-declare const secretEnvHelper: (name: "databaseSecrets" | "deploySecrets" | "storageSecrets", names: readonly string[]) => ManagedHelperStatement;
 declare const createHotUpdaterConfigScaffold: ({ build, storage, database, plugins, extraImports, helperStatements, updateStrategy }: CreateHotUpdaterConfigScaffoldOptions) => HotUpdaterConfigScaffold;
 declare const createHotUpdaterConfigScaffoldFromBuilder: (builder: ConfigBuilder, { helperStatements, updateStrategy }?: CreateHotUpdaterConfigScaffoldFromBuilderOptions) => HotUpdaterConfigScaffold;
 /**
@@ -581,6 +656,14 @@ declare const createHotUpdaterConfigScaffoldFromBuilder: (builder: ConfigBuilder
  * existing config with the scaffold's build, storage, database, plugins, and
  * helpers merged in, keeping the project's own settings.
  */
+/**
+ * Whether `hot-updater.config.ts` in `cwd` sets a team `secrets` adapter,
+ * read from its text: a `secrets` property other than `localSecrets(...)`,
+ * or a config whose shape init can't read. False without the file. Init
+ * reads the store through the loaded config, so one that sets a store but
+ * doesn't load must be fixed first.
+ */
+declare const configSetsTeamSecrets: (cwd: string) => Promise<boolean>;
 declare const writeHotUpdaterConfig: (scaffold: HotUpdaterConfigScaffold, filePath?: string) => Promise<WriteHotUpdaterConfigResult>;
 /**
  * Writes hot-updater.config.ts and says what it did. `settings` names the
@@ -593,6 +676,30 @@ declare const writeHotUpdaterFiles: (scaffold: HotUpdaterConfigScaffold, { cwd,
 }) => Promise<{
   readonly config: WriteHotUpdaterConfigResult;
 }>;
+/** What `addSigningSecretToConfigText` did. */
+type AddSigningSecretResult = {
+  readonly status: "added";
+  readonly text: string;
+} |
+/** The config already sets `signing`, which stays as it is. */
+{
+  readonly status: "kept";
+} |
+/** The file is no `export default defineConfig({ ... })` it can edit. */
+{
+  readonly status: "unsupported";
+};
+/**
+ * The config text with `signing: secret("<name>")` added, and `secret` in
+ * its `hot-updater` import, once. A config that sets `signing` in any form,
+ * such as 1.1's `{ enabled: true, privateKeyPath }`, is kept.
+ */
+declare const addSigningSecretToConfigText: (text: string, name: string) => AddSigningSecretResult;
+/**
+ * Adds `signing: secret("<name>")` to `hot-updater.config.ts` in `cwd`, as
+ * `addSigningSecretToConfigText` does. Without the file, nothing is written.
+ */
+declare const addSigningSecretToConfig: (cwd: string, name: string) => Promise<AddSigningSecretResult["status"] | "missing">;
 //#endregion
 //#region src/hotUpdaterEnv.d.ts
 type HotUpdaterInitEnv = {
@@ -616,6 +723,11 @@ declare const getHotUpdaterEnvValue: (env: Readonly<Record<string, string>>, key
 declare const parseLoadedEnv: (content: string) => Readonly<Record<string, string>>;
 /** `cwd`'s `.env.hotupdater` as the config loads it; empty when there is none. */
 declare const readLoadedHotUpdaterEnv: (cwd: string) => Promise<Readonly<Record<string, string>>>;
+/**
+ * `file`, an env file a command was given, relative to `cwd`, as
+ * `parseLoadedEnv` reads it; a file that can't be read is refused by name.
+ */
+declare const readLoadedEnvFile: (file: string, cwd: string) => Promise<Readonly<Record<string, string>>>;
 //#endregion
 //#region src/HotUpdateDirUtil.d.ts
 declare const HotUpdateDirUtil: {
@@ -680,7 +792,7 @@ type InitProviderDefinition<TInputs extends InitProviderInputsDefinition = InitP
   readonly label: string;
   /**
    * The variables of the credentials the config init writes reads with
-   * `secretEnv`, such as an API token. With a team `secrets` adapter, init
+   * `secret()`, such as an API token. With a team `secrets` adapter, init
    * stores them there with the app's API key, and reads one the
    * environment and the env file lack from it.
    */
@@ -897,6 +1009,8 @@ declare const reactNativeCliFingerprint: (cwd: string, options: NativeFingerprin
 type HotUpdaterLogWriter = {
   logFilePath: string | null;
   writeStream: (input: Readable) => Promise<void>;
+  /** Writes lines of its own, such as the command a build runs. */
+  writeLines: (lines: readonly string[]) => void;
   writeError: (error: unknown) => void;
   close: () => Promise<void>;
 };
@@ -906,17 +1020,6 @@ declare const createLogWriter: ({ prefix, logFilePath }: {
   logFilePath?: string;
 }) => Promise<HotUpdaterLogWriter>;
 //#endregion
-//#region src/localBundleSigning.d.ts
-/** The secret `keys generate --secret` stores the private key as by default. */
-declare const DEFAULT_SIGNING_KEY_SECRET = "bundle-signing-key";
-/** Local signing enabled, with its private key from a file or a secret. */
-type EnabledLocalSigningConfig = Extract<LocalSigningConfig, {
-  enabled: true;
-}>;
-declare const normalizeSigningConfig: (signing: SigningConfig | undefined, { secrets }?: {
-  readonly secrets?: SecretsAdapter;
-}) => BundleSigningAdapter | EnabledLocalSigningConfig | undefined;
-//#endregion
 //#region src/loadConfig.d.ts
 type HotUpdaterConfigOptions = {
   platform: Platform;
@@ -929,9 +1032,14 @@ type ConfigResponse = RequiredDeep<Omit<ConfigInput, "database" | "storage" | "p
   storage?: StorageAdapter;
   /** The plugins the server runs; none when the config lists none. */
   plugins: readonly AnyHotUpdaterPlugin[];
-  signing?: ReturnType<typeof normalizeSigningConfig>;
   /**
-   * Where `secret:` references and issued keys are read and stored: the
+   * As the config sets it, read only when a command signs: deploy refuses a
+   * value it doesn't take (`readBundleSigningState`), and other commands,
+   * such as the `secrets put` that fixes it, still load the config.
+   */
+  signing?: SigningConfig;
+  /**
+   * Where `secret()` references and issued keys are read and stored: the
    * config's adapter alone, or `localSecrets()` when it sets none
    * (`resolveSecretsAdapter`).
    */
@@ -951,10 +1059,12 @@ declare const loadPlatformConfigs: <TPlatform extends Platform>(platforms: reado
   readonly config: ConfigResponse;
 }[]>;
 /**
- * The names every `secretEnv` the config created while it loaded reads,
- * such as `HOT_UPDATER_CLOUDFLARE_API_TOKEN`, in the order it created them.
+ * The names the config's `secret()`s reference for its adapters, such as
+ * `HOT_UPDATER_CLOUDFLARE_API_TOKEN`, in the order the config created
+ * them: every name but those of build credentials, which `doctor` lists
+ * by field.
  */
-declare const getSecretEnvNames: (config: ConfigResponse) => readonly string[];
+declare const getDeploySecretNames: (config: ConfigResponse) => readonly string[];
 //#endregion
 //#region src/serverDefinition.d.ts
 /** A plugin's endpoint on a server's `handlers.client`. */
@@ -2321,7 +2431,7 @@ declare const readPackageUp: <T = unknown>(cwd: string) => Promise<ReadPackageUp
  * interpreter reads (`NODE_*` but `NODE_ENV`, `PATH`, `LD_*`, `DYLD_*`,
  * `BASH_ENV`, `ENV`, `GIT_*`, `npm_config_*`, the JVM's, Gradle's, Ruby's,
  * Python's, and Perl's options), or one Hot Updater reads its credentials
- * from. `secretEnv` refuses these names, and so does every environment the
+ * from. `secret()` refuses these names, and so does every environment the
  * CLI gives a child process from resolved secrets.
  */
 declare const isReservedVariableName: (name: string) => boolean;
@@ -2411,14 +2521,16 @@ declare const readLocalKey: (name: string, cwd: string) => Promise<string | unde
 declare const writeLocalKey: (name: string, value: string, cwd: string) => Promise<string>;
 //#endregion
 //#region src/secrets.d.ts
-/** Whether `name` is a secret's name, as `secret:<name>` takes one. */
+/** Whether `name` is a secret's name, as `secret("<name>")` takes one. */
 declare const isSecretName: (name: string) => boolean;
+/** Whether `value` is a `secret("<name>")` reference. */
+declare const isSecretRef: (value: unknown) => value is SecretRef;
 /**
- * The secret name a config's `secret:<name>` reference names, such as
- * `release-keystore` for `"secret:release-keystore"`. `field` is the config
- * field the reference is in, which the error names.
+ * The secret name a config's `secret("<name>")` names, such as
+ * `release-keystore` for `secret("release-keystore")`. `field` is the
+ * config field it is in, which the error names.
  */
-declare const parseSecretReference: (reference: string, field: string) => string;
+declare const parseSecretReference: (reference: unknown, field: string) => string;
 /**
  * The environment variable the default store reads a secret from: a name
  * that is a variable name already, such as `CLOUDFLARE_API_TOKEN`, as it
@@ -2470,8 +2582,8 @@ declare const resolveSecretsAdapter: (configured?: SecretsAdapter) => SecretsAda
 declare const getLocalSecretsStore: (secrets: SecretsAdapter) => LocalSecretsStore | undefined;
 /**
  * The config's own `secrets` adapter: undefined for `localSecrets()`,
- * which is the adapter when the config sets none. `secretEnv` reads deploy
- * credentials from it.
+ * which is the adapter when the config sets none. A called `secret()` reads
+ * from it.
  */
 declare const getConfiguredAdapter: (secrets: SecretsAdapter) => SecretsAdapter | undefined;
 /**
@@ -2496,23 +2608,30 @@ declare const readSecretWithSource: (secrets: SecretsAdapter, name: string, cwd:
 declare const keepsKeysOnThisMachine: (secrets: SecretsAdapter) => boolean;
 /**
  * The `secrets` adapter of one config load, filled once the config it
- * evaluates resolves: each `secretEnv` the evaluation creates reads from it,
- * and adds the names it reads to `names`.
+ * evaluates resolves: each `secret()` the evaluation creates reads from it,
+ * and adds its name to `names`.
  */
 interface SecretsScope {
   secrets?: SecretsAdapter;
   names?: Set<string>;
+  /**
+   * The names build credentials reference, such as `signing.keystore`'s,
+   * which the CLI reads for their kind: the batched read leaves them out.
+   */
+  buildNames?: Set<string>;
+  /** The one read of the scope's other names, once a `secret()` is called. */
+  read?: Promise<Readonly<Record<string, string | undefined>>>;
 }
 /**
  * Evaluates a config, the file or a config function, with `scope` as the
- * scope of every `secretEnv` it creates, so each reads the `secrets` of the
+ * scope of every `secret()` it creates, so each reads the `secrets` of the
  * config that created it, whatever config loads after. It is kept on
  * `globalThis`: the config file loads its own copy of Hot Updater's modules.
  */
 declare const withSecretsScope: <T>(scope: SecretsScope, evaluate: () => Promise<T> | T) => Promise<T>;
 /**
  * Makes `secrets` the adapter a credential resolver reads from by default,
- * and a `secretEnv` created outside any config load, as `loadConfig` does
+ * and a `secret()` created outside any config load, as `loadConfig` does
  * with the config's. It is kept on `globalThis`: the config file loads Hot
  * Updater's modules again, as its own copies.
  */
@@ -2522,32 +2641,105 @@ declare const setConfiguredSecrets: (secrets: SecretsAdapter) => void;
  * until a config loads.
  */
 declare const getConfiguredSecrets: () => SecretsAdapter;
+/**
+ * `names` from `secrets` in one `get`. A read that fails names the secrets
+ * and the adapter, with the adapter's own error on the next line, such as
+ * `EACCES: permission denied, open '<file>'`.
+ */
+declare const readSecrets: (secrets: SecretsAdapter, names: readonly string[], cwd: string) => Promise<Readonly<Record<string, string | undefined>>>;
 /** Where an adapter keeps `name`, for messages. */
 declare const describeSecret: (secrets: SecretsAdapter, name: string) => string;
 /**
- * Environment variables from the `secrets` adapter of the config that
- * creates it, as a function a config calls when an adapter needs them, so loading
- * `hot-updater.config.ts` reads no secret. Each name set in the environment
- * or `.env.hotupdater` wins; the others are read from the config's
- * `secrets` adapter in one call, and without one they must be set. The values go only to the caller: they are never set in
- * `process.env`, and are masked in the CLI's logs. Names a loader or
- * interpreter reads, such as `NODE_OPTIONS`, are refused.
+ * `secret("<name>")`: the secret `name` in `hot-updater.config.ts`, for a
+ * build credential, such as `signing.keystore`, or any adapter credential,
+ * which calls it on first use, so loading the config reads no secret.
+ * Called, it reads `name`'s variable (`secretVariableName`) in the
+ * environment or `.env.hotupdater`, else the config's `secrets` adapter:
+ * the first call reads every name the config's `secret()`s reference and
+ * the environment doesn't set, in one `get`. With `localSecrets()`, the
+ * variable must be set: its files hold only the keys Hot Updater stores.
+ * Values are masked in the CLI's logs and never set in `process.env`.
+ * Names a loader or interpreter reads, such as `NODE_OPTIONS`, are refused.
+ * A server passes its own environment's values instead.
  *
  * @example
- * const deploy = secretEnv(["S3_ACCESS_KEY_ID", "S3_SECRET_ACCESS_KEY"]);
- * s3Storage({
+ * r2Storage({
  *   bucketName: "bundles",
- *   region: "us-east-1",
- *   credentials: async () => {
- *     const env = await deploy();
- *     return {
- *       accessKeyId: env.S3_ACCESS_KEY_ID,
- *       secretAccessKey: env.S3_SECRET_ACCESS_KEY,
- *     };
+ *   accountId: "<account-id>",
+ *   credentials: {
+ *     accessKeyId: secret("HOT_UPDATER_CLOUDFLARE_R2_ACCESS_KEY_ID"),
+ *     secretAccessKey: secret("HOT_UPDATER_CLOUDFLARE_R2_SECRET_ACCESS_KEY"),
  *   },
  * });
  */
-declare const secretEnv: <const TName extends string>(names: readonly TName[]) => (() => Promise<Readonly<Record<TName, string>>>);
+declare const secret: (name: string) => SecretRef;
+//#endregion
+//#region src/step.d.ts
+type Output = Writable & {
+  isTTY?: boolean;
+  columns?: number;
+};
+/** `4.2s`, `38s`, `6m41s`, `1h02m`. */
+declare const formatDuration: (ms: number) => string;
+/**
+ * `message` with `duration` at the right edge of a step's line, the message
+ * cut with `…` when the line would be wider.
+ */
+declare const withDuration: (message: string, ms: number, width?: number) => string;
+/** `text` cut to `width` visible columns, with `…` for the rest. */
+declare const truncateLine: (text: string, width: number) => string;
+/** How a finished step's line is marked. */
+type StepLevel = "step" | "info" | "warn";
+/**
+ * A step of a command that takes a while, shown as one line: at a terminal,
+ * a spinner whose line shows the step's current detail and its elapsed
+ * time, which ends as the step's line with its duration; elsewhere, such as
+ * in CI, only that last line.
+ *
+ * While it runs, what other code prints through `p` is held: a spinner's
+ * messages become the step's detail, and logs print after the step's line,
+ * but an error ends the step as failed first and prints at once, since the
+ * process may exit right after it.
+ */
+interface Step {
+  /** Starts the step, once: nothing shows before. */
+  start(): Step;
+  /** Shows `detail` after the title on the live line, or the title alone. */
+  update(detail?: string): void;
+  /**
+   * Ends the step with `message`, the title by default, and its duration,
+   * marked as a finished step or with `level`.
+   */
+  succeed(message?: string, options?: {
+    level?: StepLevel;
+  }): void;
+  /** Ends the step as failed, with `message` or `<title> failed`. */
+  fail(message?: string): void;
+  /** Milliseconds since it started, or 0 before. */
+  readonly elapsedMs: number;
+  /** Whether it started and has not ended. */
+  readonly active: boolean;
+}
+interface StepOptions {
+  output?: Output;
+}
+/**
+ * A step that shows nothing until `start()`. A step created while another
+ * runs is part of it: its title and detail become the running step's detail.
+ */
+declare const createStep: (title: string, { output }?: StepOptions) => Step;
+/**
+ * Ends the running step as failed, if one runs, before a command prints
+ * its error.
+ */
+declare const failActiveStep: () => void;
+/** A step, started. */
+declare const startStep: (title: string, options?: StepOptions) => Step;
+/**
+ * Runs `run` as a step titled `title`, which ends with `done(result)`, or as
+ * failed when `run` throws.
+ */
+declare const withStep: <T>(title: string, run: (step: Step) => Promise<T>, done?: (result: T) => string, options?: StepOptions) => Promise<T>;
 //#endregion
 //#region src/teamSecrets.d.ts
 /**
@@ -2574,12 +2766,15 @@ declare const readMissingFromTeamSecrets: (secrets: SecretsAdapter, names: reado
   readonly cwd: string;
 }) => Promise<Readonly<Record<string, string>>>;
 /**
- * Stores each of `names` that `.env.hotupdater` holds through `secrets`,
- * then reads them back in one call. The file is left as it is. Returns the
+ * Stores each of `names` that `envFile`, `.env.hotupdater` by default,
+ * holds through `secrets`, then reads them back in one call. Only the file
+ * is read, never the environment. The file is left as it is. Returns the
  * names stored, in the order of `names`; throws when the adapter reads
  * back another value.
  */
-declare const storeEnvFileSecrets: (secrets: SecretsAdapter, names: readonly string[], cwd: string) => Promise<readonly string[]>;
+declare const storeEnvFileSecrets: (secrets: SecretsAdapter, names: readonly string[], cwd: string,
+/** An env file to read instead of `.env.hotupdater`, relative to `cwd`. */
+envFile?: string) => Promise<readonly string[]>;
 //#endregion
 //#region src/storageFiles.d.ts
 declare const getStorageFileByteSize: (filePath: string) => Promise<number>;
@@ -2604,4 +2799,4 @@ type TransformTemplateArgs<T extends string> = { [Key in ExtractPlaceholders<T>]
  */
 declare function transformTemplate<T extends string>(templateString: T, values: TransformTemplateArgs<T>): string;
 //#endregion
-export { AppClientCredential, AppClientPlugin, AssembleServerOptions, AssembledServer, BuildFailedError, BuildFailureSummaryConfig, BuildLogger, BuildLoggerConfig, BuildType, BundleSigningSession, CREDENTIAL_ENV_NAMES, CREDENTIAL_LOGIN_GROUPS, ClientAuthSpec, ClientCredentialSpec, ConfigBuilder, ConfigBuilderScaffold, ConfigResponse, CreateCredentialResolverOptions, CreateHotUpdaterConfigScaffoldFromBuilderOptions, CreateHotUpdaterConfigScaffoldOptions, type CredentialFiles, CredentialKind, CredentialRequest, CredentialResolver, CredentialUnavailableError, Credentials, DEFAULT_SIGNING_KEY_SECRET, HOT_UPDATER_HOME_ENV, HOT_UPDATER_SERVER_PACKAGE_VERSION_ENV, HotUpdateDirUtil, HotUpdaterConfigOptions, HotUpdaterConfigScaffold, HotUpdaterInitEnv, HotUpdaterLogWriter, INTERFACE_FINGERPRINT_ENGINE, ImportInfo, InitEnvFileError, InitError, InitProviderDefinition, InitProviderInputDefinition, InitProviderInputPersistence, IssuedCredentialKind, LOCAL_SECRETS_NAME, LegacyInfrastructureError, LocalSecretsOptions, LocalSecretsStore, MANAGED_CLIENT_CREDENTIAL_ENV, ManagedHelperStatement, ManagedHelperStrategy, MissingInitInputsError, NativeDependency, NativeInterface, PromptProgress, PromptSpinner, ProviderConfig, ProvisionedClientCredential, ReactNativeMetadata, ReadPackageUpResult, RunInitOptions, SecretsScope, ServerClientEndpoint, ServerDefinition, ServerDefinitionError, WriteHotUpdaterConfigResult, assembleServer, assertInfrastructureGenerationAtUrl, assertInfrastructureGenerationPayload, assertInitInputs, assertInitProviderInputs, assertUnreservedEnv, autolinkingConfigCommand, banner, clientAuthOf, typedColors as colors, confirmInitInputPersistence, copyDirToTmp, createCredentialResolver, createHotUpdaterConfigScaffold, createHotUpdaterConfigScaffoldFromBuilder, createInterfaceFingerprint, createLocalSecretsStore, createLogWriter, createMigrator, createMinBundleId, createTarBrTargetFiles, createZip, credentialIssueCommand, credentialLoginCommand, credentialStoreCommand, decryptJson, defineInitProvider, describeSecret, describeStoredSecret, encryptJson, ensureInstallPackages, generateClientCredential, generateSchema, generatesSchema, getAndroidSdkPath, getBundleSigningPublicKey, getConfiguredAdapter, getConfiguredSecrets, getCwd, getHotUpdaterEnvValue, getHotUpdaterHome, getHotUpdaterInitInputEnv, getInitProviderEnvVars, getInitProviderTextPromptValues, getLocalKeyFile, getLocalKeyStoreDir, getLocalSecretsStore, getMissingInitInputs, getMissingInitProviderInputs, getPackageManager, getProjectKey, getReactNativeMetadatas, getSecretEnvNames, getStorageFileByteSize, isCI, isCodegenSpecFile, isReservedVariableName, isSecretName, isServerDefinition, keepsKeysOnThisMachine, link, loadConfig, loadPlatformConfigs, loadTeamSecrets, localSecrets, log, makeEnv, maskSecretValues, moduleSpecifiersOf, nonInteractiveReason, p, parseLoadedEnv, parseSecretReference, prepareBundleSigning, printAppSetup, printBanner, provisionClientCredential, putStorageFile, reactNativeCliFingerprint, reactNativeConfigCommand, readBundleSigningPublicKeyFile, readHotUpdaterInitEnv, readLoadedHotUpdaterEnv, readLocalKey, readMissingFromTeamSecrets, readPackageUp, readReactNativeInterface, readSecretVariables, readSecretWithSource, registerCredentialValue, registerSecretValue, renderAppImports, renderAppSetup, renderImportStatements, resolveExpoAutolinking, resolveHotUpdaterServerVersion, resolveInitProviderInput, resolveInitProviderInputs, resolveLocalSecretsPath, resolvePackageVersion, resolveSecretsAdapter, secretEnv, secretEnvHelper, secretVariableName, serverDefinitionOf, setConfiguredSecrets, shouldAutoSelectOnlyInitResource, storeEnvFileSecrets, stripAnsi, transformEnv, transformTemplate, withCredentialResolver, withSecretsScope, writeHotUpdaterConfig, writeHotUpdaterFiles, writeLocalKey };
+export { AddSigningSecretResult, AppClientCredential, AppClientPlugin, AssembleServerOptions, AssembledServer, BUNDLE_SIGNING_KEY_SECRET, BuildFailedError, BuildFailureSummaryConfig, BuildLogger, BuildLoggerConfig, BuildPhaseReader, BuildType, BundleSigningKeyError, BundleSigningOptions, BundleSigningSession, BundleSigningState, CREDENTIAL_ENV_NAMES, CREDENTIAL_LOGIN_GROUPS, ClientAuthSpec, ClientCredentialSpec, ConfigBuilder, ConfigBuilderScaffold, ConfigResponse, CreateCredentialResolverOptions, CreateHotUpdaterConfigScaffoldFromBuilderOptions, CreateHotUpdaterConfigScaffoldOptions, type CredentialFiles, CredentialKind, CredentialRequest, CredentialResolver, CredentialUnavailableError, Credentials, FileCredentialKind, HOT_UPDATER_HOME_ENV, HOT_UPDATER_SERVER_PACKAGE_VERSION_ENV, HotUpdateDirUtil, HotUpdaterConfigOptions, HotUpdaterConfigScaffold, HotUpdaterInitEnv, HotUpdaterLogWriter, INTERFACE_FINGERPRINT_ENGINE, INVALID_SIGNING_MESSAGE, INVALID_SIGNING_NEXT_STEP, ISSUE_SIGNING_KEY_COMMAND, ImportInfo, InitEnvFileError, InitError, InitProviderDefinition, InitProviderInputDefinition, InitProviderInputPersistence, IssuedCredentialKind, LOCAL_SECRETS_NAME, LegacyInfrastructureError, LocalSecretsOptions, LocalSecretsStore, MANAGED_CLIENT_CREDENTIAL_ENV, ManagedHelperStatement, ManagedHelperStrategy, MissingInitInputsError, NativeDependency, NativeInterface, PUT_SIGNING_KEY_COMMAND, PromptProgress, PromptSpinner, ProviderConfig, ProvisionedClientCredential, ReactNativeMetadata, ReadPackageUpResult, RunInitOptions, SecretsScope, ServerClientEndpoint, ServerDefinition, ServerDefinitionError, Step, StepLevel, UNSIGNED_BUNDLES_NEXT_STEP, UNSIGNED_BUNDLES_WARNING, WriteHotUpdaterConfigResult, addSigningSecretToConfig, addSigningSecretToConfigText, assembleServer, assertInfrastructureGenerationAtUrl, assertInfrastructureGenerationPayload, assertInitInputs, assertInitProviderInputs, assertUnreservedEnv, autolinkingConfigCommand, banner, bundleSigningSecretRef, clientAuthOf, typedColors as colors, configSetsTeamSecrets, confirmInitInputPersistence, copyDirToTmp, createCredentialResolver, createHotUpdaterConfigScaffold, createHotUpdaterConfigScaffoldFromBuilder, createInterfaceFingerprint, createLocalSecretsStore, createLogWriter, createMigrator, createMinBundleId, createStep, createTarBrTargetFiles, createZip, credentialIssueCommand, credentialLoginCommand, credentialPutCommand, credentialStoreCommand, decryptJson, defineInitProvider, describeSecret, describeStoredSecret, encryptJson, ensureInstallPackages, failActiveStep, formatDuration, generateClientCredential, generateSchema, generatesSchema, getAndroidSdkPath, getBundleSigningPublicKey, getConfiguredAdapter, getConfiguredSecrets, getCwd, getDeploySecretNames, getHotUpdaterEnvValue, getHotUpdaterHome, getHotUpdaterInitInputEnv, getInitProviderEnvVars, getInitProviderTextPromptValues, getLocalKeyFile, getLocalKeyStoreDir, getLocalSecretsStore, getMissingInitInputs, getMissingInitProviderInputs, getPackageManager, getProjectKey, getReactNativeMetadatas, getStorageFileByteSize, isCI, isCodegenSpecFile, isReservedVariableName, isSecretName, isSecretRef, isServerDefinition, keepsKeysOnThisMachine, link, loadConfig, loadPlatformConfigs, loadTeamSecrets, localSecrets, log, makeEnv, maskSecretValues, moduleSpecifiersOf, nonInteractiveReason, p, parseLoadedEnv, parseSecretReference, prepareBundleSigning, printAppSetup, printBanner, provisionClientCredential, putStorageFile, reactNativeCliFingerprint, reactNativeConfigCommand, readBundleSigningPublicKeyFile, readBundleSigningState, readHotUpdaterInitEnv, readLoadedEnvFile, readLoadedHotUpdaterEnv, readLocalKey, readMissingFromTeamSecrets, readPackageUp, readReactNativeInterface, readSecretVariables, readSecretWithSource, readSecrets, registerCredentialValue, registerSecretValue, renderAppImports, renderAppSetup, renderImportStatements, resolveExpoAutolinking, resolveHotUpdaterServerVersion, resolveInitProviderInput, resolveInitProviderInputs, resolveLocalSecretsPath, resolvePackageVersion, resolveSecretsAdapter, secret, secretVariableName, serverDefinitionOf, setConfiguredSecrets, shouldAutoSelectOnlyInitResource, startStep, storeEnvFileSecrets, stripAnsi, transformEnv, transformTemplate, truncateLine, withCredentialResolver, withDuration, withSecretsScope, withStep, writeHotUpdaterConfig, writeHotUpdaterFiles, writeLocalKey };