@hot-updater/cli-tools 1.1.4 → 1.2.0-rc.1

package/dist/index.d.mts

@@ -1,26 +1,78 @@
 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, SigningConfig, StorageAdapter, StorageAdapterWith, StoragePutResult, ToolingDatabase } from "@hot-updater/plugin-core";
+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 { Readable as Readable$1, Writable } from "node:stream";
 import { ManifestArchive } from "@hot-updater/protocol";
 //#region src/BuildLogger.d.ts
 type LinePattern = string | RegExp;
+/** The tool's output a failed build prints: its errors, else its last lines. */
+interface BuildFailureSummaryConfig {
+  /** Lines kept wherever they are, such as a compiler's `error:` lines. */
+  lines: LinePattern[];
+  /**
+   * Blocks kept whole: from a line matching `start` through one matching
+   * `end`, or up to it without `includeEnd`.
+   */
+  blocks: {
+    start: LinePattern;
+    end: LinePattern;
+    includeEnd: boolean;
+  }[];
+}
 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[][];
+  /** What a failure prints from the tool's raw output. */
+  failureSummary: BuildFailureSummaryConfig;
+}
+/**
+ * A native build that failed, after its logger printed the summary of the
+ * tool's output and the log file's path, so its message is one line.
+ */
+declare class BuildFailedError extends Error {
+  name: string;
+  /** The build log, relative to the project, or null without one. */
+  readonly logPath: string | null;
+  /** The lines of the tool's output the summary printed. */
+  readonly summary: string[];
+  constructor(message: string, { logPath, summary, cause }: {
+    logPath: string | null;
+    summary: string[];
+    cause?: unknown;
+  });
 }
 declare class BuildLogger {
   private readonly config;
   private state;
   private logWriter?;
+  private summaryLines;
+  private tailLines;
+  private openBlock?;
   private readonly promptProgress;
   private readonly stageCount;
   constructor(config: BuildLoggerConfig);
   start(): Promise<void>;
-  processStream(input: Readable): 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.
+   */
+  processStream(input: Readable, { display }?: {
+    display?: Readable;
+  }): Promise<void>;
+  /** The build log, relative to the project, or null without one. */
+  get logPath(): 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.
+   */
+  get failureSummary(): string[];
+  private consumeSummaryStream;
+  private processSummaryLine;
+  private keepSummaryLine;
   private consumeProgressStream;
   private processProgressLine;
   stop(message?: string, success?: boolean): void;
@@ -29,6 +81,11 @@ declare class BuildLogger {
   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
@@ -277,6 +334,165 @@ declare const createZip: ({ outfile, targetDir, excludeExts }: {
   excludeExts?: string[];
 }) => Promise<string>;
 //#endregion
+//#region src/credentialFiles.d.ts
+/**
+ * Temporary files holding credential values a tool reads from disk, such as
+ * an App Store Connect `.p8` key or an Android keystore.
+ */
+interface CredentialFiles {
+  /**
+   * Writes `contents` to a new file named `fileName`, readable only by the
+   * current user (0600), and returns its path. String contents are masked in
+   * logs.
+   */
+  write(fileName: string, contents: string | Uint8Array): Promise<string>;
+  /** Deletes every file written so far; nothing can be written after it. */
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/credentialEnvNames.d.ts
+/**
+ * The environment variables that override each kind, one entry per field.
+ * A field with two names takes a file path or the file's contents; the path
+ * wins when both are set.
+ */
+declare const CREDENTIAL_ENV_NAMES: {
+  readonly "asc-api-key": readonly [readonly ["HOT_UPDATER_ASC_KEY_PATH", "HOT_UPDATER_ASC_KEY"], readonly ["HOT_UPDATER_ASC_KEY_ID"], readonly ["HOT_UPDATER_ASC_ISSUER_ID"]];
+  readonly "android-keystore": readonly [readonly ["HOT_UPDATER_ANDROID_KEYSTORE_PATH", "HOT_UPDATER_ANDROID_KEYSTORE_BASE64"], readonly ["HOT_UPDATER_ANDROID_KEYSTORE_PASSWORD"], readonly ["HOT_UPDATER_ANDROID_KEY_ALIAS"], readonly ["HOT_UPDATER_ANDROID_KEY_PASSWORD"]];
+  readonly "play-service-account": readonly [readonly ["HOT_UPDATER_PLAY_SERVICE_ACCOUNT_PATH", "HOT_UPDATER_PLAY_SERVICE_ACCOUNT_JSON"]];
+};
+//#endregion
+//#region src/credentialResolver.d.ts
+/**
+ * The build credentials the CLI resolves by name. Deploy credentials reach
+ * the config's adapters through `secretEnv`.
+ */
+interface Credentials {
+  /** App Store Connect API key, for automatic signing and uploads. */
+  "asc-api-key": {
+    /** A 0600 temporary file or the path the user set. */
+    readonly keyPath: string;
+    readonly keyId: string;
+    readonly issuerId: string;
+  };
+  /** Android release keystore, for Gradle signing. */
+  "android-keystore": {
+    /** A 0600 temporary file or the path the user set. */
+    readonly storeFile: string;
+    readonly storePassword: string;
+    readonly keyAlias: string;
+    readonly keyPassword: string;
+  };
+  /** Google Play service account, kept in memory. */
+  "play-service-account": {
+    readonly json: string;
+  };
+}
+type CredentialKind = keyof Credentials;
+interface CredentialRequest<TKind extends CredentialKind> {
+  readonly kind: TKind;
+  /**
+   * The item's name, for a project with several items of one kind (such as
+   * `widget-keystore`). Defaults to the kind. Environment overrides apply to
+   * every item of a kind.
+   */
+  readonly name?: string;
+}
+/**
+ * Resolves the credentials a command needs. Commands call `dispose` in a
+ * `finally` (or use `withCredentialResolver`); temporary files are also
+ * deleted when the process exits.
+ */
+interface CredentialResolver {
+  resolve<TKind extends CredentialKind>(request: CredentialRequest<TKind>): Promise<Credentials[TKind]>;
+  /**
+   * Waits for resolutions in flight, then deletes every temporary file this
+   * resolver wrote. The resolver resolves nothing after it.
+   */
+  dispose(): Promise<void>;
+}
+/**
+ * The sentence every "credential unavailable" message ends with: the
+ * environment variables that provide `kind` whatever the secrets adapter.
+ */
+declare const credentialOverrideHint: (kind: CredentialKind) => string;
+/**
+ * The command that stores a credential of `kind` you have as `name` through
+ * the config's `secrets` adapter, from its files.
+ */
+declare const credentialPutCommand: (kind: CredentialKind, name?: string) => string;
+/** The credentials Hot Updater issues itself after a sign-in. */
+type IssuedCredentialKind = Exclude<CredentialKind, "android-keystore">;
+/**
+ * The command that signs in once, at a terminal, and 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.
+ */
+declare const credentialIssueCommand: (kind: IssuedCredentialKind, 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`.
+ */
+declare const credentialLoginCommand: (kind: IssuedCredentialKind, name?: string) => string;
+/**
+ * The command that stores a missing credential of `kind` as `name`: the
+ * keystore you have, or the key Hot Updater issues after a sign-in.
+ */
+declare const credentialStoreCommand: (kind: CredentialKind, name?: string) => string;
+declare class CredentialUnavailableError extends Error {
+  readonly kind: CredentialKind;
+  /** The environment variables that can provide this credential. */
+  readonly envNames: readonly string[];
+  constructor(kind: CredentialKind, message: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Masks a credential's JSON value in the CLI's output: the whole value, and
+ * each field but those that identify it, such as `keyId` and `keyAlias`,
+ * so a password or a key a log prints alone stays masked. A value that is
+ * no JSON object is masked whole.
+ */
+declare const registerCredentialValue: (value: string) => void;
+interface CreateCredentialResolverOptions {
+  /**
+   * Environment values read after `process.env`, the same lookup as
+   * `getHotUpdaterEnvValue`.
+   */
+  readonly env?: Readonly<Record<string, string>>;
+  /**
+   * Where to find an item no environment override sets, or a function that
+   * returns it when an item resolves, for a command whose config loads
+   * after the resolver is created. Defaults to the config `loadConfig` last
+   * loaded, the default store when it sets none.
+   */
+  readonly secrets?: SecretsAdapter | (() => SecretsAdapter);
+  /** The project directory the adapter is given. Defaults to `getCwd()`. */
+  readonly cwd?: string;
+}
+/**
+ * Resolves each item from its environment overrides when any is set, and
+ * otherwise from the config's `secrets` adapter as one value named by the
+ * item, so overrides never reach the store. When the adapter fails or holds
+ * no such value, the error names the environment variables that can
+ * provide the item instead. Nothing is cached, values are never written to
+ * disk except as 0600 temporary files, are never set in `process.env`, and
+ * every secret is masked in logs.
+ */
+declare const createCredentialResolver: ({ env, secrets, cwd }?: CreateCredentialResolverOptions) => CredentialResolver;
+/**
+ * Runs `run` with a credential resolver and deletes its temporary files
+ * when `run` settles.
+ */
+declare const withCredentialResolver: <T>(run: (resolver: CredentialResolver) => Promise<T>, options?: CreateCredentialResolverOptions) => Promise<T>;
+//#endregion
 //#region src/crypto.d.ts
 declare const encryptJson: (jsonData: Record<string, any>, secretKey: string) => string;
 declare const decryptJson: <T>(encryptedData: string, secretKey: string) => T;
@@ -386,8 +602,15 @@ type HotUpdaterInitEnv = {
 };
 declare const getHotUpdaterInitInputEnv: ({ env, managedEnv }: HotUpdaterInitEnv, nonInteractive: boolean) => Readonly<Record<string, string>>;
 declare const readHotUpdaterInitEnv: (cwd: string, envFile?: string) => Promise<HotUpdaterInitEnv>;
-declare const readHotUpdaterEnv: (cwd: string) => Promise<Readonly<Record<string, string>>>;
 declare const getHotUpdaterEnvValue: (env: Readonly<Record<string, string>>, key: string) => string | undefined;
+/**
+ * An env file's variables as `process.loadEnvFile` sets them, the way
+ * `hot-updater.config.ts` loads `.env.hotupdater`: inline comments, quotes,
+ * and `export` prefixes included.
+ */
+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>>>;
 //#endregion
 //#region src/HotUpdateDirUtil.d.ts
 declare const HotUpdateDirUtil: {
@@ -510,6 +733,25 @@ declare const assertInitInputs: ({ inputs, strict }: {
 }) => void;
 declare const getMissingInitInputs: (inputs: Readonly<Record<string, string | undefined>>) => readonly string[];
 //#endregion
+//#region src/interactive.d.ts
+/**
+ * Whether the environment is a CI run: `CI` is set to anything but empty,
+ * `0`, or `false`. GitHub Actions, GitLab CI, CircleCI, Buildkite, Bitrise,
+ * and Codemagic set it.
+ */
+declare const isCI: (env?: Readonly<Record<string, string | undefined>>) => boolean;
+/**
+ * Why the CLI can't ask anything here, or undefined when it can: in CI,
+ * where a runner may give the job a terminal nobody answers in, and without
+ * a terminal on stdin. Prompts and sign-ins both check it.
+ */
+declare const nonInteractiveReason: ({ env, input }?: {
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly input?: {
+    readonly isTTY?: boolean;
+  };
+}) => string | undefined;
+//#endregion
 //#region src/interfaceFingerprint.d.ts
 /**
  * The engine fingerprint.json records for the interface fingerprint. Change
@@ -549,7 +791,37 @@ interface NativeInterface {
    * engine, read from the files the framework itself reads.
    */
   settings?: Record<string, string>;
+  /**
+   * What autolinking printed, as parsed: the React Native config, and
+   * expo-modules-autolinking's `resolve` when the app links Expo modules.
+   */
+  autolinking?: {
+    reactNative: unknown;
+    expoModules: unknown;
+  };
 }
+/**
+ * The command, run with Node.js, that lists the React Native packages a
+ * build links, chosen as Expo and @expo/fingerprint choose it: Expo's
+ * autolinking from expo-modules-autolinking 1.12 (SDK 52), else React Native
+ * CLI, as for an app without Expo. The native templates also fall back to
+ * React Native CLI when `EXPO_USE_COMMUNITY_AUTOLINKING=1`, as Expo
+ * documents.
+ */
+declare const reactNativeConfigCommand: (cwd: string, platform: Platform, env?: NodeJS.ProcessEnv) => string[];
+/**
+ * The command that lists the React Native packages the native project of a
+ * build adapter links, as the adapter's own fingerprint runs it: `rock config`
+ * for Rock, React Native CLI's `config` for the bare adapter, and
+ * {@link reactNativeConfigCommand} for Expo and any other adapter.
+ */
+declare const autolinkingConfigCommand: (cwd: string, platform: Platform, { buildAdapter, env }?: {
+  buildAdapter?: string;
+  env?: NodeJS.ProcessEnv;
+}) => {
+  command: string;
+  args: string[];
+};
 /**
  * The expo-modules-autolinking an Expo app builds with, resolved from its
  * `expo` package as the native templates resolve it.
@@ -617,16 +889,22 @@ declare const createLogWriter: ({ prefix, logFilePath }: {
 }) => Promise<HotUpdaterLogWriter>;
 //#endregion
 //#region src/localBundleSigning.d.ts
-declare const normalizeSigningConfig: (signing: SigningConfig | undefined) => BundleSigningAdapter | Extract<LocalSigningConfig, {
+/** 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;
-}> | undefined;
+}>;
+declare const normalizeSigningConfig: (signing: SigningConfig | undefined, { secrets }?: {
+  readonly secrets?: SecretsAdapter;
+}) => BundleSigningAdapter | EnabledLocalSigningConfig | undefined;
 //#endregion
 //#region src/loadConfig.d.ts
 type HotUpdaterConfigOptions = {
   platform: Platform;
   channel: string;
 } | null;
-type ConfigResponse = RequiredDeep<Omit<ConfigInput, "database" | "storage" | "plugins" | "signing">> & {
+type ConfigResponse = RequiredDeep<Omit<ConfigInput, "database" | "storage" | "plugins" | "signing" | "secrets">> & {
   /** The server's database, or `standaloneRepository(...)`; absent when the config names none. */
   database?: ConfiguredDatabase;
   /** Where the CLI uploads bundles; absent when the config names none. */
@@ -634,6 +912,12 @@ type ConfigResponse = RequiredDeep<Omit<ConfigInput, "database" | "storage" | "p
   /** 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
+   * config's adapter with `localSecrets()`'s store after it (`withLocalKeyStore`),
+   * or `localSecrets()` when it sets none.
+   */
+  secrets: SecretsAdapter;
 };
 declare const loadConfig: (options: HotUpdaterConfigOptions) => Promise<ConfigResponse>;
 /**
@@ -745,13 +1029,14 @@ declare const createMigrator: ({ database, plugins }: ToolingSource) => Migrator
 declare const generateSchema: ({ database, plugins }: ToolingSource, version: Parameters<SchemaGenerator>[0], name?: Parameters<SchemaGenerator>[1]) => ReturnType<SchemaGenerator>;
 //#endregion
 //#region src/log.d.ts
+type LogMessage = string | number | null | undefined;
 declare const log: {
-  normal: (message: string | number | null | undefined) => void;
-  success: (message: string | number | null | undefined) => void;
-  info: (message: string | number | null | undefined) => void;
-  error: (message: string | number | null | undefined) => void;
-  warn: (message: string | number | null | undefined) => void;
-  debug: (message: string | number | null | undefined) => void;
+  normal: (message: LogMessage) => void;
+  success: (message: LogMessage) => void;
+  info: (message: LogMessage) => void;
+  error: (message: LogMessage) => void;
+  warn: (message: LogMessage) => void;
+  debug: (message: LogMessage) => void;
 };
 //#endregion
 //#region src/makeEnv.d.ts
@@ -762,8 +1047,24 @@ type EnvVarValue = string | {
 declare const makeEnv: (newEnvVars: Record<string, EnvVarValue>, filePath?: string, options?: {
   readonly preserveKeys?: readonly string[];
   readonly removeKeys?: readonly string[];
+  /** Rewrites only a file that holds exactly this, else throws. */
+  readonly expectedContent?: string;
 }) => Promise<string>;
 //#endregion
+//#region src/minBundleId.d.ts
+/**
+ * The MIN_BUNDLE_ID a native build compiles in, which is also the ID of its
+ * built-in bundle: a UUIDv7 of the build's millisecond whose random bits are
+ * all zero, `<ts>-<ts>-7000-8000-000000000000`, as the SDK's podspec script
+ * phase and Gradle task generate it. The bundles `hot-updater deploy` issued
+ * before the build sort before it, and the ones it issues afterwards sort
+ * after it. Bundle IDs share one space across platforms, so two builds that
+ * start in the same millisecond get the same one: `native-build ios|android`
+ * steps past an ID the registry holds before it builds, and the registry
+ * refuses a second registration of one.
+ */
+declare const createMinBundleId: (nowMs?: number) => string;
+//#endregion
 //#region src/moduleSpecifiers.d.ts
 /**
  * The modules `source` imports or re-exports, statically or with an
@@ -1063,10 +1364,10 @@ declare class AutocompletePrompt<T extends OptionLike$1> extends Prompt<T['value
 type DateFormat = 'YMD' | 'MDY' | 'DMY';
 declare function isCancel(value: unknown): value is symbol;
 declare namespace index_d_exports {
-  export { AutocompleteMultiSelectOptions, AutocompleteOptions, BoxAlignment, BoxOptions, ClackSettings, CommonOptions, ConfirmOptions, DateFormat, DateOptions, GroupMultiSelectOptions, LimitOptionsParams, LogMessageOptions, MULTISELECT_INSTRUCTIONS, MultiLineOptions, MultiSelectOptions, NoteOptions, Option, PasswordOptions, PathOptions, ProgressOptions, ProgressResult, PromptGroup, PromptGroupAwaitedReturn, PromptGroupOptions, SELECT_INSTRUCTIONS, S_BAR, S_BAR_END, S_BAR_END_RIGHT, S_BAR_H, S_BAR_START, S_BAR_START_RIGHT, S_CHECKBOX_ACTIVE, S_CHECKBOX_INACTIVE, S_CHECKBOX_SELECTED, S_CONNECT_LEFT, S_CORNER_BOTTOM_LEFT, S_CORNER_BOTTOM_RIGHT, S_CORNER_TOP_LEFT, S_CORNER_TOP_RIGHT, S_ERROR, S_INFO, S_PASSWORD_MASK, S_RADIO_ACTIVE, S_RADIO_INACTIVE, S_STEP_ACTIVE, S_STEP_CANCEL, S_STEP_ERROR, S_STEP_SUBMIT, S_SUCCESS, S_WARN, SelectKeyOptions, SelectOptions, SpinnerOptions, SpinnerResult, Task, TaskLogCompletionOptions, TaskLogMessageOptions, TaskLogOptions, TextOptions, autocomplete, autocompleteMultiselect, box, cancel, confirm, date, formatInstructionFooter, group, groupMultiselect, intro, isCI, isCancel, isTTY, limitOptions, log$1 as log, multiline, multiselect, note, outro, password, path, progress, select, selectKey, settings$1 as settings, spinner, stream, symbol, symbolBar, taskLog, tasks, text, unicode, unicodeOr, updateSettings };
+  export { AutocompleteMultiSelectOptions, AutocompleteOptions, BoxAlignment, BoxOptions, ClackSettings, CommonOptions, ConfirmOptions, DateFormat, DateOptions, GroupMultiSelectOptions, LimitOptionsParams, LogMessageOptions, MULTISELECT_INSTRUCTIONS, MultiLineOptions, MultiSelectOptions, NoteOptions, Option, PasswordOptions, PathOptions, ProgressOptions, ProgressResult, PromptGroup, PromptGroupAwaitedReturn, PromptGroupOptions, SELECT_INSTRUCTIONS, S_BAR, S_BAR_END, S_BAR_END_RIGHT, S_BAR_H, S_BAR_START, S_BAR_START_RIGHT, S_CHECKBOX_ACTIVE, S_CHECKBOX_INACTIVE, S_CHECKBOX_SELECTED, S_CONNECT_LEFT, S_CORNER_BOTTOM_LEFT, S_CORNER_BOTTOM_RIGHT, S_CORNER_TOP_LEFT, S_CORNER_TOP_RIGHT, S_ERROR, S_INFO, S_PASSWORD_MASK, S_RADIO_ACTIVE, S_RADIO_INACTIVE, S_STEP_ACTIVE, S_STEP_CANCEL, S_STEP_ERROR, S_STEP_SUBMIT, S_SUCCESS, S_WARN, SelectKeyOptions, SelectOptions, SpinnerOptions, SpinnerResult, Task, TaskLogCompletionOptions, TaskLogMessageOptions, TaskLogOptions, TextOptions, autocomplete, autocompleteMultiselect, box, cancel, confirm, date, formatInstructionFooter, group, groupMultiselect, intro, isCI$1 as isCI, isCancel, isTTY, limitOptions, log$1 as log, multiline, multiselect, note, outro, password, path, progress, select, selectKey, settings$1 as settings, spinner, stream, symbol, symbolBar, taskLog, tasks, text, unicode, unicodeOr, updateSettings };
 }
 declare const unicode: boolean;
-declare const isCI: () => boolean;
+declare const isCI$1: () => boolean;
 declare const isTTY: (output: Writable) => boolean;
 declare const unicodeOr: (c: string, fallback: string) => string;
 declare const S_STEP_ACTIVE: string;
@@ -1975,6 +2276,11 @@ declare const taskLog: (opts: TaskLogOptions) => {
 };
 //#endregion
 //#region src/prompts.d.ts
+/**
+ * `@clack/prompts` with CI-safe spinners, with every message a registered
+ * credential value appears in masked (`registerSecretValue`), and with
+ * prompts that refuse to ask without a terminal.
+ */
 declare const p: typeof index_d_exports;
 type PromptProgress = ReturnType<typeof p.progress>;
 type PromptSpinner = ReturnType<typeof p.spinner>;
@@ -1986,6 +2292,23 @@ interface ReadPackageUpResult<T = unknown> {
 }
 declare const readPackageUp: <T = unknown>(cwd: string) => Promise<ReadPackageUpResult<T> | undefined>;
 //#endregion
+//#region src/reservedVariables.d.ts
+/**
+ * Whether `name` is a variable no secret may set: one a loader or
+ * 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
+ * CLI gives a child process from resolved secrets.
+ */
+declare const isReservedVariableName: (name: string) => boolean;
+/**
+ * Throws when `env`, an environment the CLI gives a child process from
+ * resolved secrets, sets a reserved variable, naming it and `what` sets it.
+ * Returns `env`.
+ */
+declare const assertUnreservedEnv: <T extends Readonly<Record<string, string>>>(env: T, what: string) => T;
+//#endregion
 //#region src/resolvePackageVersion.d.ts
 declare const HOT_UPDATER_SERVER_PACKAGE_VERSION_ENV = "HOT_UPDATER_SERVER_PACKAGE_VERSION";
 declare const resolvePackageVersion: (packageName: string, options?: {
@@ -1995,6 +2318,207 @@ declare const resolveHotUpdaterServerVersion: (currentPackageName: string, optio
   searchFrom?: string;
 }) => string;
 //#endregion
+//#region src/secretMasking.d.ts
+/**
+ * Registers a credential value so every CLI log sink (`p`, `log`, and the
+ * build log files) prints it masked, however short it is. A multi-line value
+ * is also registered line by line, so a PEM printed one line at a time stays
+ * masked.
+ */
+declare const registerSecretValue: (value: string) => void;
+/** Replaces every registered credential value in `text` with a mask. */
+declare const maskSecretValues: (text: string) => string;
+//#endregion
+//#region src/localKeyStore.d.ts
+/**
+ * Relocates Hot Updater's per-user directory, `~/.hot-updater` by default,
+ * such as for CI caches or tests.
+ */
+declare const HOT_UPDATER_HOME_ENV = "HOT_UPDATER_HOME";
+/** Hot Updater's per-user directory: `$HOT_UPDATER_HOME`, else `~/.hot-updater`. */
+declare const getHotUpdaterHome: () => string;
+/**
+ * The project's directory name in the store: the project directory's name
+ * and the first 12 hex digits of the SHA-256 of its real path, such as
+ * `my-app-3f2a9c1d04be`. Each checkout of an app has its own.
+ */
+declare const getProjectKey: (cwd: string) => string;
+/**
+ * The directory `localSecrets()` keeps a project's secrets in without a
+ * `path`: `<home>/secrets/<project-key>` (`getHotUpdaterHome`,
+ * `getProjectKey`).
+ */
+declare const getLocalKeyStoreDir: (cwd: string) => string;
+/**
+ * `localSecrets({ path })`'s directory: `~` is the home directory, and a
+ * relative path is the project's (`cwd`).
+ */
+declare const resolveLocalSecretsPath: (value: string, cwd: string) => string;
+/** Where `localSecrets()` keeps a project's secrets, one file per name. */
+interface LocalSecretsStore {
+  /** The project's directory. */
+  readonly directory: (cwd: string) => string;
+  /**
+   * The file `name` is kept in, `<name>.json`. A secret's name has no path
+   * separator and does not start with a dot.
+   */
+  readonly file: (name: string, cwd: string) => string;
+  /** `name`'s value, or undefined. */
+  readonly read: (name: string, cwd: string) => Promise<string | undefined>;
+  /**
+   * Stores `value` as `name`: the directory is 0700 and the file 0600,
+   * readable by this user alone, and a write replaces the file whole or
+   * not at all. Returns the file.
+   */
+  readonly write: (name: string, value: string, cwd: string) => Promise<string>;
+}
+/**
+ * The store `localSecrets({ path })` reads and writes: `path`, or
+ * `getLocalKeyStoreDir` without one. Its first use refuses a directory
+ * secrets must not go in (`assertPrivateDirectory`).
+ */
+declare const createLocalSecretsStore: ({ path: configured }?: {
+  readonly path?: string;
+}) => LocalSecretsStore;
+/** The file `localSecrets()` without a `path` keeps `name` in. */
+declare const getLocalKeyFile: (name: string, cwd: string) => string;
+/** `name`'s value in `localSecrets()`'s default store, or undefined. */
+declare const readLocalKey: (name: string, cwd: string) => Promise<string | undefined>;
+/** Stores `value` as `name` in `localSecrets()`'s default store. */
+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. */
+declare const isSecretName: (name: string) => boolean;
+/**
+ * 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.
+ */
+declare const parseSecretReference: (reference: string, 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
+ * is, and any other, such as `asc-api-key`, upper-cased with `HOT_UPDATER_`
+ * before it and every character but letters and digits as `_`
+ * (`HOT_UPDATER_ASC_API_KEY`).
+ */
+declare const secretVariableName: (name: string) => string;
+/** `name` from its variable in `process.env` or the project's `.env.hotupdater`. */
+declare const readSecretVariables: (names: readonly string[], cwd: string) => Promise<Record<string, string | undefined>>;
+/** `localSecrets()`'s name, the `secrets` adapter when the config sets none. */
+declare const LOCAL_SECRETS_NAME = "localSecrets";
+/**
+ * Secrets in JSON files on this machine, the `secrets` adapter when the
+ * config sets none: `get` reads each name from its environment variable
+ * (`secretVariableName`, in `process.env` or `.env.hotupdater`), then from
+ * `~/.hot-updater/secrets/<project-key>/<name>.json`; `set` writes that
+ * file, 0600 in a 0700 directory, outside the project, so it survives
+ * `node_modules` and is never committed. `HOT_UPDATER_HOME` moves
+ * `~/.hot-updater`. The project key is the same for every clone of one app
+ * on a machine (its `origin` remote and its directory in the repository),
+ * so another machine signs in and issues a key of its own.
+ *
+ * @example
+ * export default defineConfig({ secrets: localSecrets(), ... });
+ */
+declare const localSecrets: (options?: LocalSecretsOptions) => SecretsAdapter;
+interface LocalSecretsOptions {
+  /**
+   * The directory that holds this project's secrets, one `<name>.json`
+   * each, such as `~/.hot-updater/secrets/my-app`: `~` is the home
+   * directory, and a relative path is the project's. A directory in a git
+   * work tree must be one git ignores. Defaults to
+   * `~/.hot-updater/secrets/<project-key>`, whose key is the same for every
+   * clone of the app on a machine (`getProjectKey`).
+   */
+  readonly path?: string;
+}
+/**
+ * The config's `secrets` adapter with `localSecrets()`'s store after it:
+ * `get` reads each name the adapter does not hold from
+ * `~/.hot-updater/secrets/<project-key>/<name>.json`, and `set` stores there
+ * when the adapter stores nothing. Without an adapter, it is
+ * `localSecrets()` itself. Keys Hot Updater issues, and credentials
+ * `secrets put` imports, are reused by the next build on this machine with
+ * no step in between.
+ */
+declare const withLocalKeyStore: (configured?: SecretsAdapter) => SecretsAdapter;
+/**
+ * The `localSecrets()` store `secrets` reads after its adapter, and stores
+ * in when the adapter stores nothing: `localSecrets({ path })`'s, else the
+ * default one.
+ */
+declare const getLocalSecretsStore: (secrets: SecretsAdapter) => LocalSecretsStore;
+/**
+ * The config's own `secrets` adapter, without `localSecrets()`'s store
+ * after it: undefined for `localSecrets()`, and when the config sets none.
+ * `secretEnv` reads deploy credentials from it.
+ */
+declare const getConfiguredAdapter: (secrets: SecretsAdapter) => SecretsAdapter | undefined;
+/**
+ * Where `secrets.set` stores `name`, for messages: the config's adapter
+ * when it stores values, else `localSecrets()`'s file.
+ */
+declare const describeStoredSecret: (secrets: SecretsAdapter, name: string) => string;
+/**
+ * Whether a key `secrets` stores stays on this machine: it is `localSecrets()`,
+ * whose files no other machine reads.
+ */
+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.
+ */
+interface SecretsScope {
+  secrets?: SecretsAdapter;
+}
+/**
+ * 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
+ * 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
+ * with the config's. It is kept on `globalThis`: the config file loads Hot
+ * Updater's modules again, as its own copies.
+ */
+declare const setConfiguredSecrets: (secrets: SecretsAdapter) => void;
+/**
+ * The config's `secrets` adapter with `localSecrets()`'s store after it
+ * (`withLocalKeyStore`), `localSecrets()` until a config loads.
+ */
+declare const getConfiguredSecrets: () => SecretsAdapter;
+/** 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.
+ *
+ * @example
+ * const deploy = secretEnv(["S3_ACCESS_KEY_ID", "S3_SECRET_ACCESS_KEY"]);
+ * s3Storage({
+ *   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,
+ *     };
+ *   },
+ * });
+ */
+declare const secretEnv: <const TName extends string>(names: readonly TName[]) => (() => Promise<Readonly<Record<TName, string>>>);
+//#endregion
 //#region src/storageFiles.d.ts
 declare const getStorageFileByteSize: (filePath: string) => Promise<number>;
 declare const putStorageFile: (storage: StorageAdapterWith<"put">, key: string, filePath: string) => Promise<StoragePutResult & {
@@ -2018,4 +2542,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, BuildLogger, BuildLoggerConfig, BuildType, BundleSigningSession, ClientAuthSpec, ClientCredentialSpec, ConfigBuilder, ConfigBuilderScaffold, ConfigResponse, CreateHotUpdaterConfigScaffoldFromBuilderOptions, CreateHotUpdaterConfigScaffoldOptions, HOT_UPDATER_SERVER_PACKAGE_VERSION_ENV, HotUpdateDirUtil, HotUpdaterConfigOptions, HotUpdaterConfigScaffold, HotUpdaterInitEnv, HotUpdaterLogWriter, INTERFACE_FINGERPRINT_ENGINE, ImportInfo, InitEnvFileError, InitError, InitProviderDefinition, InitProviderInputDefinition, InitProviderInputPersistence, LegacyInfrastructureError, ManagedHelperStatement, ManagedHelperStrategy, MissingInitInputsError, NativeDependency, NativeInterface, PromptProgress, PromptSpinner, ProviderConfig, ProvisionedClientCredential, ReactNativeMetadata, ReadPackageUpResult, RunInitOptions, ServerClientEndpoint, ServerDefinition, ServerDefinitionError, WriteHotUpdaterConfigResult, assembleServer, assertInfrastructureGenerationAtUrl, assertInfrastructureGenerationPayload, assertInitInputs, assertInitProviderInputs, banner, clientAuthOf, typedColors as colors, confirmInitInputPersistence, copyDirToTmp, createHotUpdaterConfigScaffold, createHotUpdaterConfigScaffoldFromBuilder, createInterfaceFingerprint, createLogWriter, createMigrator, createTarBrTargetFiles, createZip, decryptJson, defineInitProvider, encryptJson, ensureInstallPackages, generateClientCredential, generateSchema, generatesSchema, getAndroidSdkPath, getBundleSigningPublicKey, getCwd, getHotUpdaterEnvValue, getHotUpdaterInitInputEnv, getInitProviderEnvVars, getInitProviderTextPromptValues, getMissingInitInputs, getMissingInitProviderInputs, getPackageManager, getReactNativeMetadatas, getStorageFileByteSize, isCodegenSpecFile, isServerDefinition, link, loadConfig, loadPlatformConfigs, log, makeEnv, moduleSpecifiersOf, p, prepareBundleSigning, printAppSetup, printBanner, provisionClientCredential, putStorageFile, reactNativeCliFingerprint, readBundleSigningPublicKeyFile, readHotUpdaterEnv, readHotUpdaterInitEnv, readPackageUp, readReactNativeInterface, renderAppImports, renderAppSetup, renderImportStatements, resolveExpoAutolinking, resolveHotUpdaterServerVersion, resolveInitProviderInput, resolveInitProviderInputs, resolvePackageVersion, serverDefinitionOf, shouldAutoSelectOnlyInitResource, stripAnsi, transformEnv, transformTemplate, writeHotUpdaterConfig, writeHotUpdaterFiles };
+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, 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, credentialOverrideHint, credentialPutCommand, 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, getStorageFileByteSize, isCI, isCodegenSpecFile, isReservedVariableName, isSecretName, isServerDefinition, keepsKeysOnThisMachine, link, loadConfig, loadPlatformConfigs, localSecrets, log, makeEnv, maskSecretValues, moduleSpecifiersOf, nonInteractiveReason, p, parseLoadedEnv, parseSecretReference, prepareBundleSigning, printAppSetup, printBanner, provisionClientCredential, putStorageFile, reactNativeCliFingerprint, reactNativeConfigCommand, readBundleSigningPublicKeyFile, readHotUpdaterInitEnv, readLoadedHotUpdaterEnv, readLocalKey, readPackageUp, readReactNativeInterface, readSecretVariables, registerCredentialValue, registerSecretValue, renderAppImports, renderAppSetup, renderImportStatements, resolveExpoAutolinking, resolveHotUpdaterServerVersion, resolveInitProviderInput, resolveInitProviderInputs, resolveLocalSecretsPath, resolvePackageVersion, secretEnv, secretVariableName, serverDefinitionOf, setConfiguredSecrets, shouldAutoSelectOnlyInitResource, stripAnsi, transformEnv, transformTemplate, withCredentialResolver, withLocalKeyStore, withSecretsScope, writeHotUpdaterConfig, writeHotUpdaterFiles, writeLocalKey };