@zhin.js/gateway 1.2.0 → 1.4.0

package/README.md

@@ -29,7 +29,7 @@ zhin console init           # 首次创建 Console 所有者；之后 http.token
 |---|---|
 | `@zhin.js/gateway/iam` | Console 账号、角色、会话、API 令牌、审计与初始化（ADR 0049）：`ConsoleIamService`、`ConsoleSetupService`、`installConsoleIam`、`registerConsoleAuthRoutes`、`dispatchIamRpc`、`importLegacyIamTables` / `revertLegacyIamImport` / `inspectLegacyIamImport`（旧版项目库账号表迁入 gateway.db 与回退，ADR 0059） |
 | `@zhin.js/gateway/terminal` | Console 终端（ADR 0051）：`TerminalService`、`installHostConsoleTerminal`、`parseTerminalConfig` |
-| `@zhin.js/gateway/config` | 原始配置文件与 `.env` 读写：`ConsoleConfigurationStore`、`readEnvFile` / `writeEnvFile`、配置路径与补丁、Console Schema |
+| `@zhin.js/gateway/config` | 原始配置文件与 `.env` 读写：`ConsoleConfigurationStore`、`readEnvFile` / `writeEnvFile`（Host 内部用）、Console 用的打码视图与逐键保存（`readEnvFileView` / `revealEnvVariable` / `updateEnvVariables` / `replaceEnvFileContent`）、配置路径与补丁、Console Schema |
 | `@zhin.js/gateway/plugin-management` | 项目级依赖事务：`PluginManagementWorkflow`、`PluginManagementActivity`、插件用例 |
 | `@zhin.js/gateway/project` | 项目文件工具：`findConfigFile`、`loadRuntimeEnvironmentLayers`、`createTsxModuleLoader`、实例声明迁移、旧配置检测、Node 版本要求 |
 | `@zhin.js/gateway/supervisor` | 实例进程监管 `InstanceSupervisor`：IPC 控制通道（`ready` / `shutdown` / `restart-request`）、崩溃重启与风暴保护、日志采集（环形缓冲 + `.zhin/logs/instance.log` 按大小轮转）；`runSupervisedInstance` 供 `zhin start` 使用 |

package/lib/config/configuration.d.ts

@@ -2,6 +2,7 @@ import { type ConsoleConfigApplication, type ConsoleConfigApplicationStatus, typ
 import type { PluginConfigValidation } from '@zhin.js/host-http';
 import { type RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 import { type ConfigFileDocument, type EnvStore } from '@zhin.js/runtime';
+import type { LiteralConfigSecret } from '@zhin.js/runtime';
 export interface ChatConfigurationField {
     readonly path: readonly string[];
     readonly type: readonly string[];
@@ -19,6 +20,14 @@ export declare class ConfigChatRequestRejectedError extends Error {
     constructor();
 }
 /** Owns one project's Console configuration projection over the Root config authority. */
+/**
+ * What the caller of a configuration write may do besides `ops.config.write`. Set by the Console
+ * RPC context from the principal's grants, and by trusted in-process / local-owner callers.
+ */
+export interface ConfigWriteAuthority {
+    /** The caller may write `.env` (`ops.env.write`): secret literals may be moved there. Default false. */
+    readonly environmentWrite?: boolean;
+}
 export declare class ConsoleConfigurationStore {
     #private;
     constructor(options: {
@@ -32,12 +41,22 @@ export declare class ConsoleConfigurationStore {
         readonly validateConfiguration?: (document: RuntimeConfigDocument) => Promise<void>;
     });
     readSource(): Promise<ConsoleConfigSource>;
+    /**
+     * Secret fields of the stored (unexpanded) configuration that hold literals instead of
+     * `${VAR}` references (ADR 0057). Paths only, never values.
+     */
+    readLiteralSecrets(): Promise<readonly LiteralConfigSecret[]>;
     readDocument(): Promise<Record<string, unknown>>;
     replaceSource(source: string, expectedRevision: string): Promise<{
         readonly revision: string;
         readonly restartRequired: boolean;
     } & ConsoleConfigApplicationStatus>;
-    setKey(pluginName: string, data: unknown): Promise<{
+    /**
+     * `options.environmentWrite`: the caller holds `ops.env.write` (or is a trusted in-process / local
+     * owner caller). Without it a block whose secret fields hold literals is refused
+     * ({@link SecretEnvironmentWriteRequiredError}): those values would be written into `.env`.
+     */
+    setKey(pluginName: string, data: unknown, options?: ConfigWriteAuthority): Promise<{
         restartRequired: boolean;
     } & ConsoleConfigApplicationStatus>;
     removeKey(pluginName: string): Promise<{
@@ -48,14 +67,14 @@ export declare class ConsoleConfigurationStore {
      * allowlist are rejected before reading values; a stale revision returns the latest
      * values instead of overwriting; every touched section is validated by its schema.
      */
-    patch(request: ConsoleConfigPatchRequest): Promise<ConsoleConfigPatchResult>;
+    patch(request: ConsoleConfigPatchRequest, options?: ConfigWriteAuthority): Promise<ConsoleConfigPatchResult>;
     /**
      * Trusted project administration (`config:patch-project`, full scope only). Same
      * single-CAS core as {@link patch}, without the page allowlist; it does not widen
      * `config:patch` / `HOST_CONFIG_PATCH_PATHS`. Declaration writes are rejected as
      * `invalid`, conflict values are masked, and a thrown commit is `unconfirmed`.
      */
-    patchProject(request: Omit<ConsoleConfigPatchRequest, 'instanceKey'>): Promise<ConsoleConfigProjectPatchResult>;
+    patchProject(request: Omit<ConsoleConfigPatchRequest, 'instanceKey'>, options?: ConfigWriteAuthority): Promise<ConsoleConfigProjectPatchResult>;
     /** Host-authenticated owner chat. Policy checks share the mutation's CAS boundary. */
     patchChat(request: Omit<ConsoleConfigPatchRequest, 'instanceKey'>): Promise<ConsoleConfigPatchResult>;
     /**
@@ -73,6 +92,16 @@ export declare class ConsoleConfigurationStore {
     apply(expectedRevision: string): Promise<ConsoleConfigApplyResult>;
     readEnvironmentFile(filename: string): Promise<string>;
     writeEnvironmentFile(filename: string, content: string): Promise<void>;
+    /** Masked view for the Console (`env:get`); never a value. */
+    readEnvironmentView(filename: string): Promise<import('@zhin.js/console-protocol').ConsoleEnvFileView>;
+    /** One variable as written (`env:reveal`); the caller authorizes and audits. */
+    revealEnvironmentVariable(filename: string, key: string): Promise<import('@zhin.js/console-protocol').ConsoleEnvRevealResult>;
+    /** Per-key save (`env:save { changes }`); keys not named keep their lines. */
+    updateEnvironmentVariables(filename: string, changes: unknown): Promise<{
+        readonly changed: readonly string[];
+    }>;
+    /** Whole-file save (`env:save { content, mode: 'replace' }`); refused when it holds mask placeholders. */
+    replaceEnvironmentFile(filename: string, content: string): Promise<void>;
     readSchema(pluginName?: string): Promise<unknown>;
     validatePluginConfig(pluginName: string, data: unknown, capturedDocument?: RuntimeConfigDocument): Promise<PluginConfigValidation>;
     readAllSchemas(): Promise<Record<string, unknown>>;

package/lib/config/configuration.js

@@ -5,11 +5,15 @@ import { ConfigDocumentConflictError, ConfigValidationError, ConfigurationSupers
 import { loadRuntimeEnvironmentLayers } from '../project/environment.js';
 import { readPluginPackageMap } from './plugin-package-map.js';
 import { assertUnambiguousConfigKey, configKeyPatch, configKeyRemovePatch, flattenConfigDocument } from './configuration-projection.js';
-import { readEnvFile, writeEnvFile } from './environment-files.js';
+import { readEnvFile, readEnvFileView, replaceEnvFileContent, revealEnvVariable, updateEnvVariables, writeEnvFile, } from './environment-files.js';
 import { PluginSchemaCatalog } from './plugin-schema-catalog.js';
+import { declarationKeyMessage, describeArrayPathProblem, unknownConfigKeyMessage } from './patch-path-messages.js';
+import { findProjectLiteralSecrets } from './literal-secrets.js';
+import { planSecretExternalization, SECRET_ENVIRONMENT_WRITE_REQUIRED, SecretEnvironmentWriteRequiredError, secretEnvironmentWriteRequiredMessage, writeSecretAssignments, } from './secret-storage.js';
 import { hostModelOwnerId } from '@zhin.js/plugin-runtime';
 import { assertChatConfigurationAccess, assertChatConfigurationScope, assertChatValueHasNoEnvironmentReference, assertChatOptionalLeaf, chatConfigurationLeaves, chatHostRoots, chatLeafTypes, ConfigChatAccessError, } from './configuration-chat-policy.js';
 import { isForbiddenConfigurationPathSegment } from './configuration-path.js';
+import { formatSchemaIssue } from './validation-messages.js';
 import { assertPatchesInScope, normalizeConfigPatchOperations, readDeclaredPatchPaths, readPath, resolvePatchScope, } from './configuration-patch.js';
 import { maskConfigValue, REDACTED_CONFIG_VALUE } from './configuration-redaction.js';
 /** A Host-classified rejection before this operation attempted any commit. */
@@ -47,7 +51,6 @@ function chatApplication(application) {
             dependsOn: Object.freeze([]),
         }))) });
 }
-/** Owns one project's Console configuration projection over the Root config authority. */
 export class ConsoleConfigurationStore {
     #projectRoot;
     #document;
@@ -93,6 +96,13 @@ export class ConsoleConfigurationStore {
             });
         });
     }
+    /**
+     * Secret fields of the stored (unexpanded) configuration that hold literals instead of
+     * `${VAR}` references (ADR 0057). Paths only, never values.
+     */
+    readLiteralSecrets() {
+        return this.#afterMutations(async () => findProjectLiteralSecrets(this.#projectRoot, (await this.#document.read()).document));
+    }
     readDocument() {
         return this.#afterMutations(async () => {
             const snapshot = await this.#document.read();
@@ -112,16 +122,36 @@ export class ConsoleConfigurationStore {
             });
         });
     }
-    setKey(pluginName, data) {
+    /**
+     * `options.environmentWrite`: the caller holds `ops.env.write` (or is a trusted in-process / local
+     * owner caller). Without it a block whose secret fields hold literals is refused
+     * ({@link SecretEnvironmentWriteRequiredError}): those values would be written into `.env`.
+     */
+    setKey(pluginName, data, options = {}) {
         return this.#serialize(async () => {
             const current = await this.#document.read();
             await this.#assertUnambiguousKey(current.document, pluginName);
-            const prepared = await this.#document.prepare(current, [
-                configKeyPatch(current.document, pluginName, data),
-            ]);
-            readApplicationPluginDeclaration(prepared.document);
-            await this.#validatePrepared(prepared);
-            const committed = await prepared.commit();
+            const patches = [configKeyPatch(current.document, pluginName, data)];
+            // Literal values of secret fields go to `.env`; the block keeps `${VAR}` references (#1250).
+            const plan = await planSecretExternalization(this.#projectRoot, this.#environmentName(), current.document, applyConfigPatches(current.document, patches), patches.map(patch => patch.path));
+            if (plan.assignments.length > 0 && options.environmentWrite !== true) {
+                throw new SecretEnvironmentWriteRequiredError(plan.assignments.map(item => item.path));
+            }
+            if (plan.errors.length > 0)
+                throw new Error(plan.errors.map(error => error.message).join('；'));
+            patches.push(...plan.patches);
+            const restoreEnvironment = await writeSecretAssignments(this.#projectRoot, this.#environmentName(), plan.assignments);
+            let committed;
+            try {
+                const prepared = await this.#document.prepare(current, patches);
+                readApplicationPluginDeclaration(prepared.document);
+                await this.#validatePrepared(prepared);
+                committed = await prepared.commit();
+            }
+            catch (error) {
+                await restoreEnvironment();
+                throw error;
+            }
             return this.#applySaved(HOST_CONFIG_KEYS.includes(pluginName), committed.revision);
         });
     }
@@ -143,8 +173,8 @@ export class ConsoleConfigurationStore {
      * allowlist are rejected before reading values; a stale revision returns the latest
      * values instead of overwriting; every touched section is validated by its schema.
      */
-    patch(request) {
-        return this.#serialize(() => this.#patchCore(request, 'scoped'));
+    patch(request, options = {}) {
+        return this.#serialize(() => this.#patchCore(request, 'scoped', options));
     }
     /**
      * Trusted project administration (`config:patch-project`, full scope only). Same
@@ -152,10 +182,11 @@ export class ConsoleConfigurationStore {
      * `config:patch` / `HOST_CONFIG_PATCH_PATHS`. Declaration writes are rejected as
      * `invalid`, conflict values are masked, and a thrown commit is `unconfirmed`.
      */
-    patchProject(request) {
+    patchProject(request, options = {}) {
         return this.#serialize(async () => {
             try {
-                return await this.#patchCore({ expectedRevision: request.expectedRevision, patches: request.patches }, 'project');
+                return await this.#patchCore({ expectedRevision: request.expectedRevision, patches: request.patches,
+                    ...(request.secretStorage === undefined ? {} : { secretStorage: request.secretStorage }) }, 'project', options);
             }
             catch (error) {
                 if (!(error instanceof ConfigCommitUnconfirmedError))
@@ -187,11 +218,13 @@ export class ConsoleConfigurationStore {
         });
     }
     /** Shared single-CAS write: `scoped` keeps the page allowlist; `project` is the trusted full path. */
-    async #patchCore(request, mode) {
+    async #patchCore(request, mode, authority = {}) {
         let phase = 'prepare';
+        // Restores `.env` when secrets were moved there but the config write does not happen.
+        let restoreEnvironment;
         try {
             const instanceKey = request.instanceKey;
-            const patches = normalizeConfigPatchOperations(request.patches);
+            let patches = normalizeConfigPatchOperations(request.patches);
             const current = await this.#document.read();
             if (mode === 'scoped') {
                 const declared = instanceKey === undefined
@@ -204,8 +237,9 @@ export class ConsoleConfigurationStore {
             if (mode !== 'scoped') {
                 const rejected = projectDeclarationErrors(current.document, paths);
                 if (rejected.length > 0) {
+                    const declarationWrite = paths.some(path => PROJECT_PATCH_DECLARATION_KEYS.has(path[0]));
                     return Object.freeze({ status: 'invalid', revision: current.revision, errors: Object.freeze(rejected),
-                        missingEnv: Object.freeze([]), message: '插件声明不能通过项目补丁修改，未保存' });
+                        missingEnv: Object.freeze([]), message: declarationWrite ? '插件声明不能通过项目补丁修改，未保存' : '没有这个配置项，未保存' });
                 }
             }
             const conflict = async (snapshot) => Object.freeze({
@@ -217,7 +251,44 @@ export class ConsoleConfigurationStore {
             });
             if (current.revision !== request.expectedRevision)
                 return await conflict(current);
-            const candidate = applyConfigPatches(current.document, patches);
+            // Array indexes outside the array (or a key where an index belongs) are a usage problem:
+            // answer with an explanation instead of the document layer's internal exception.
+            const arrayProblems = patches.flatMap(patch => {
+                const message = describeArrayPathProblem(current.document, patch.path, patch.op);
+                return message ? [{ path: `$.${patch.path.join('.')}`, message }] : [];
+            });
+            if (arrayProblems.length > 0) {
+                return Object.freeze({ status: 'invalid', revision: current.revision, errors: Object.freeze(arrayProblems),
+                    missingEnv: Object.freeze([]), message: '配置路径无效，未保存' });
+            }
+            let candidate = applyConfigPatches(current.document, patches);
+            // Secret fields keep `${VAR}` references: a literal written here goes to `.env` (#1250),
+            // unless the caller explicitly asked for plain storage. Chat writes never carry literals
+            // into secret fields (they are refused by the chat policy).
+            let envSecrets = [];
+            let secretAssignments = [];
+            if (mode !== 'chat' && request.secretStorage !== 'plain') {
+                const plan = await planSecretExternalization(this.#projectRoot, this.#environmentName(), current.document, candidate, patches.filter(patch => patch.op === 'set').map(patch => patch.path));
+                if (plan.errors.length > 0) {
+                    return Object.freeze({ status: 'invalid', revision: current.revision, errors: Object.freeze(plan.errors),
+                        missingEnv: Object.freeze([]), message: '配置校验失败，未保存' });
+                }
+                // Moving a value into `.env` is an `.env` write: it needs `ops.env.write` (#1250). Without
+                // it the write is refused, never stored as plain text behind the caller's back.
+                if (plan.assignments.length > 0 && authority.environmentWrite !== true) {
+                    const paths = plan.assignments.map(item => item.path);
+                    return Object.freeze({ status: 'invalid', revision: current.revision, code: SECRET_ENVIRONMENT_WRITE_REQUIRED,
+                        errors: Object.freeze(paths.map(path => Object.freeze({ path: `$.${path.join('.')}`,
+                            message: '敏感字段的值要写入 .env，需要 ops.env.write 权限' }))),
+                        missingEnv: Object.freeze([]), message: secretEnvironmentWriteRequiredMessage(paths) });
+                }
+                if (plan.patches.length > 0) {
+                    patches = Object.freeze([...patches, ...plan.patches]);
+                    candidate = applyConfigPatches(current.document, patches);
+                    secretAssignments = plan.assignments;
+                    envSecrets = Object.freeze(plan.assignments.map(item => Object.freeze({ path: item.path, variable: item.variable })));
+                }
+            }
             // Chat writes exactly one leaf (C1/C4); scope and leaf shape are proven before values.
             if (mode === 'chat' && patches.length !== 1)
                 throw new ConfigChatAccessError('leaf');
@@ -258,6 +329,8 @@ export class ConsoleConfigurationStore {
                 for (const name of validation.missingEnv)
                     missingEnv.add(name);
             }
+            for (const { variable } of envSecrets)
+                missingEnv.delete(variable);
             if (errors.length > 0) {
                 return Object.freeze({
                     status: 'invalid',
@@ -268,6 +341,7 @@ export class ConsoleConfigurationStore {
                 });
             }
             let committed;
+            restoreEnvironment = await writeSecretAssignments(this.#projectRoot, this.#environmentName(), secretAssignments);
             try {
                 const prepared = await this.#document.prepare(current, patches);
                 readApplicationPluginDeclaration(prepared.document);
@@ -280,6 +354,7 @@ export class ConsoleConfigurationStore {
                     // Runtime validation may report cross-field constraints without a
                     // structured path. Preserve the invalid contract at the document
                     // boundary; arbitrary issue strings can contain private values.
+                    await restoreEnvironment();
                     return Object.freeze({ status: 'invalid', revision: current.revision,
                         errors: Object.freeze([Object.freeze({ path: '$', message: '完整配置未通过运行校验' })]),
                         missingEnv: Object.freeze([...missingEnv].sort()), message: '配置校验失败，未保存' });
@@ -301,6 +376,8 @@ export class ConsoleConfigurationStore {
                 }
             }
             catch (error) {
+                if (phase === 'prepare')
+                    await restoreEnvironment();
                 if (error instanceof ConfigDocumentConflictError)
                     return await conflict(await this.#document.read());
                 throw error;
@@ -313,6 +390,7 @@ export class ConsoleConfigurationStore {
                 ...applied,
                 paths,
                 missingEnv: Object.freeze([...missingEnv].sort()),
+                ...(envSecrets.length > 0 ? { envSecrets } : {}),
                 message: applied.applicationError === 'superseded' ? '配置已保存，但该次生效申请已被替代'
                     : applied.applicationError === 'invalid' ? '配置已保存，但配置校验失败，未生效'
                         : applied.applicationError ? '配置已保存，生效结果未确认' : applied.restartRequired
@@ -551,6 +629,22 @@ export class ConsoleConfigurationStore {
     writeEnvironmentFile(filename, content) {
         return writeEnvFile(this.#projectRoot, filename, content);
     }
+    /** Masked view for the Console (`env:get`); never a value. */
+    readEnvironmentView(filename) {
+        return readEnvFileView(this.#projectRoot, filename);
+    }
+    /** One variable as written (`env:reveal`); the caller authorizes and audits. */
+    revealEnvironmentVariable(filename, key) {
+        return revealEnvVariable(this.#projectRoot, filename, key);
+    }
+    /** Per-key save (`env:save { changes }`); keys not named keep their lines. */
+    updateEnvironmentVariables(filename, changes) {
+        return updateEnvVariables(this.#projectRoot, filename, changes);
+    }
+    /** Whole-file save (`env:save { content, mode: 'replace' }`); refused when it holds mask placeholders. */
+    replaceEnvironmentFile(filename, content) {
+        return replaceEnvFileContent(this.#projectRoot, filename, content);
+    }
     async readSchema(pluginName) {
         const { document } = await this.#document.read();
         if (pluginName && !HOST_CONFIG_KEYS.includes(pluginName)
@@ -597,15 +691,15 @@ export class ConsoleConfigurationStore {
             for (const issue of candidate.errors) {
                 const location = issue.instancePath.replace(/^\/candidate/u, '').split('/').slice(1)
                     .map(key => key.replaceAll('~1', '/').replaceAll('~0', '~'));
+                // The message names the field relative to the block, in the project locale (`locale`).
+                const message = formatSchemaIssue(issue, location, document.locale);
                 if (issue.keyword === 'required' && typeof issue.params.missingProperty === 'string') {
                     location.push(issue.params.missingProperty);
                 }
-                errors.push({
-                    path: `$${location.map(key => `.${key}`).join('')}`,
-                    message: issue.keyword === 'type'
-                        ? `类型应为 ${issue.params.type === 'array' ? 'list' : String(issue.params.type)}`
-                        : issue.message ?? issue.keyword,
-                });
+                if (issue.keyword === 'additionalProperties' && typeof issue.params.additionalProperty === 'string') {
+                    location.push(issue.params.additionalProperty);
+                }
+                errors.push({ path: `$${location.map(key => `.${key}`).join('')}`, message });
             }
         }
         collectEnvironmentReferences(candidate.value, missingEnv, environment);
@@ -663,10 +757,11 @@ function projectDeclarationErrors(document, paths) {
     const errors = [];
     for (const section of new Set(paths.map(path => path[0]))) {
         if (PROJECT_PATCH_DECLARATION_KEYS.has(section)) {
-            errors.push({ path: `$.${section}`, message: '插件声明与根插件配置请用 gateway.plugins.declare、配置源码或插件管理修改' });
+            errors.push({ path: `$.${section}`, message: declarationKeyMessage(section) });
         }
         else if (!HOST_CONFIG_KEYS.includes(section) && !declared.has(section)) {
-            errors.push({ path: `$.${section}`, message: '未声明的插件实例；请先用 gateway.plugins.declare 声明' });
+            const known = [...HOST_CONFIG_KEYS, ...declared].filter(key => !PROJECT_PATCH_DECLARATION_KEYS.has(key));
+            errors.push({ path: `$.${section}`, message: unknownConfigKeyMessage(section, known) });
         }
     }
     return errors;

package/lib/config/environment-files.d.ts

@@ -1,3 +1,45 @@
+import { type ConsoleEnvChange, type ConsoleEnvFileView, type ConsoleEnvRevealResult } from '@zhin.js/console-protocol';
+/** The file as written. Only for the Host itself (setup, doctor); the Console reads {@link readEnvFileView}. */
 export declare function readEnvFile(projectRoot: string, filename: string): Promise<string>;
 /** Locked, atomic replacement that keeps the file mode (`0600` when new); ADR 0057 §4. */
 export declare function writeEnvFile(projectRoot: string, filename: string, content: string): Promise<void>;
+/**
+ * Masked view of `content` (`env:get`): exactly the variables dotenv reads, each masked; comments
+ * that carry a value are masked too. Never contains a value, its length, or a line's length.
+ */
+export declare function maskEnvFileContent(file: string, content: string): ConsoleEnvFileView;
+export declare function readEnvFileView(projectRoot: string, filename: string): Promise<ConsoleEnvFileView>;
+export declare class EnvVariableNotFoundError extends Error {
+    readonly code = "env_variable_not_found";
+    constructor(filename: string, key: string);
+}
+/**
+ * One variable (its effective, i.e. last, assignment) as written in the file: exactly the text
+ * dotenv reads as that variable's value, so it never carries another line of the file.
+ */
+export declare function revealEnvVariable(projectRoot: string, filename: string, key: string): Promise<ConsoleEnvRevealResult>;
+export declare class EnvChangeError extends Error {
+    readonly code = "invalid_env_change";
+    constructor(message: string);
+}
+/** Validated `env:save` changes; throws {@link EnvChangeError} (nothing is written). */
+export declare function validateEnvChanges(changes: unknown): readonly ConsoleEnvChange[];
+/**
+ * Applies validated changes to `content`; every line not naming a changed key keeps its bytes.
+ * Throws {@link EnvChangeError} when dotenv would read anything but the submitted changes.
+ */
+export declare function applyEnvChanges(content: string, changes: readonly ConsoleEnvChange[]): string;
+/**
+ * `env:save { changes }`: applies the changes to the file as it is on disk, inside the dotenv
+ * lock. Keys not named keep their lines byte for byte (they are never rebuilt from a masked view).
+ */
+export declare function updateEnvVariables(projectRoot: string, filename: string, changes: unknown): Promise<{
+    readonly changed: readonly string[];
+}>;
+/** Keys of `content` whose value (or commented value) is a mask placeholder. */
+export declare function maskedPlaceholderKeys(content: string): readonly string[];
+/**
+ * `env:save { content, mode: 'replace' }`: the whole-file form. Refused when any value is a mask
+ * placeholder, so a masked view can never be written back over the real values.
+ */
+export declare function replaceEnvFileContent(projectRoot: string, filename: string, content: string): Promise<void>;