@zhin.js/gateway 1.1.2 → 1.3.0

package/README.md

@@ -3,7 +3,7 @@
 Zhin.js 管理网关（[ADR 0054](../../../docs/adr/0054-management-gateway.md)）。网关负责宿主层面的事：Console 账号与权限、终端、
 项目配置与 `.env`、依赖事务、实例监管。它**不依赖 `zhin.js` 与 IM 层**，不加载插件代码（`pnpm check:architecture` 强制）。
 
-网关进程（`zhin start`；前台运行用 `zhin start --foreground`）自己打开项目数据库并持有 `console_*` 表：登录、初始化、`iam.*`、`onboarding.update`、终端与审计
+网关进程（`zhin start`；前台运行用 `zhin start --foreground`）把 `console_*` 账号表放在自己的 `.zhin/gateway.db`（ADR 0059，与项目数据库方言无关；升级时自动从项目数据库迁入）：登录、初始化、`iam.*`、`onboarding.update`、终端与审计
 都在网关里，没有实例时 Console 照样可用；受管实例只按转发的主体做授权。`--standalone`（开发 / 测试，无网关）的实例仍在进程内
 装配 `installConsoleIam` / `installHostConsoleTerminal`。
 
@@ -27,17 +27,17 @@ zhin console init           # 首次创建 Console 所有者；之后 http.token
 
 | 子路径 | 内容 |
 |---|---|
-| `@zhin.js/gateway/iam` | Console 账号、角色、会话、API 令牌、审计与初始化（ADR 0049）：`ConsoleIamService`、`ConsoleSetupService`、`installConsoleIam`、`registerConsoleAuthRoutes`、`dispatchIamRpc` |
+| `@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` 使用 |
 | `@zhin.js/gateway/usage` | 用量统计聚合 |
 | `@zhin.js/gateway/onboarding` | Console 引导（ADR 0053）：`.zhin/onboarding.json` 状态（`OnboardingStateStore`、自动识别已配置步骤）、`OnboardingService`、安装白名单与 `authorizeInstall`、流式 `installPackages` |
 | `@zhin.js/gateway/http` | HTML / SSE 响应工具（实例也导入，不加载 Node HTTP 栈） |
-| `@zhin.js/gateway/server` | 网关 HTTP 服务器（`GatewayHttpServer`：自有路由、`{base}` 认证后转发、其他路由原样转发、实例离线 503 / 超时 504 / 其他 502；`useConsoleRpc` 登记更多网关 RPC）、`gateway.*` Console RPC 路由、`startGatewayConsole`（项目数据库、本地认证、`/auth/*`、`iam.*`、`onboarding.update`、初始化向导、终端、审计）、`registerGatewayEventRoutes`（合并 `{base}/events`、`{base}/gateway/packages/progress`）、`startGateway`（服务器 + Console + 实例监管 + `@zhin.js/host-http/bridge` 实例传输）、`runGateway`（`zhin start` 的监管 + 网关入口） |
-| `@zhin.js/gateway/database` | 网关自己的项目数据库连接（ADR 0054 §7）：`loadProjectDatabaseConfig` / `resolveProjectDatabaseConfig`（与实例 `resolveDatabaseConfig` 同一规则）、`ProjectDatabase`（SQLite WAL；不用同步的 `busy_timeout`，`SQLITE_BUSY` 以异步退避重试，默认 5 秒预算，超时返回 `503 database_busy` 与 `Retry-After`） |
+| `@zhin.js/gateway/server` | 网关 HTTP 服务器（`GatewayHttpServer`：自有路由、`{base}` 认证后转发、其他路由原样转发、实例离线 503 / 超时 504 / 其他 502；`useConsoleRpc` 登记更多网关 RPC）、`gateway.*` Console RPC 路由、`startGatewayConsole`（gateway.db、旧表迁移、本地认证、`/auth/*`、`iam.*`、`onboarding.update`、初始化向导、终端、审计）、`registerGatewayEventRoutes`（合并 `{base}/events`、`{base}/gateway/packages/progress`）、`startGateway`（服务器 + Console + 实例监管 + `@zhin.js/host-http/bridge` 实例传输）、`runGateway`（`zhin start` 的监管 + 网关入口） |
+| `@zhin.js/gateway/database` | 网关自己的存储与临时项目库连接（ADR 0054 §7、ADR 0059）：`openGatewayStore`（`.zhin/gateway.db`，`0600`，`gateway_meta`）、`loadProjectDatabaseConfig` / `resolveProjectDatabaseConfig`（与实例 `resolveDatabaseConfig` 同一规则，含 `database.console`）、`ProjectDatabase`（SQLite WAL；不用同步的 `busy_timeout`，`SQLITE_BUSY` 以异步退避重试，默认 5 秒预算，超时返回 `503 database_busy` 与 `Retry-After`；`tableExists` / `readSnapshot` / `dropTables` 供迁移使用）、`setupConsoleRole`（`zhin db console-role`：PostgreSQL / MySQL 的 Console SQL 受限账号） |
 | `@zhin.js/gateway` | 以上全部 |
 
 ```ts

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[];
@@ -32,6 +33,11 @@ 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;
@@ -73,6 +79,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,13 @@ 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 { findProjectLiteralSecrets } from './literal-secrets.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. */
@@ -93,6 +95,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();
@@ -551,6 +560,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 +622,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);

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>;

package/lib/config/environment-files.js

@@ -1,14 +1,354 @@
 import { join } from 'node:path';
-import { readDotenvFile, writeDotenvFile } from '@zhin.js/runtime';
-const ENV_FILES = new Set(['.env', '.env.development', '.env.production']);
-export async function readEnvFile(projectRoot, filename) {
+import { parse } from 'dotenv';
+import { ENV_FILE_NAMES, ENV_MASK_CHAR, ENV_MASK_RUN, ENV_KEY_PATTERN, ENV_SAVE_LIMITS, isConsoleEnvMaskPlaceholder, maskConsoleEnvValue, } from '@zhin.js/console-protocol';
+import { readDotenvFile, updateDotenvFile, writeDotenvFile } from '@zhin.js/runtime';
+const ENV_FILES = new Set(ENV_FILE_NAMES);
+function envPath(projectRoot, filename) {
     if (!ENV_FILES.has(filename))
         throw new Error(`Invalid env file: ${filename}`);
-    return readDotenvFile(join(projectRoot, filename));
+    return join(projectRoot, filename);
+}
+/** The file as written. Only for the Host itself (setup, doctor); the Console reads {@link readEnvFileView}. */
+export async function readEnvFile(projectRoot, filename) {
+    return readDotenvFile(envPath(projectRoot, filename));
 }
 /** Locked, atomic replacement that keeps the file mode (`0600` when new); ADR 0057 §4. */
 export async function writeEnvFile(projectRoot, filename, content) {
-    if (!ENV_FILES.has(filename))
-        throw new Error(`Invalid env file: ${filename}`);
-    await writeDotenvFile(join(projectRoot, filename), content);
+    await writeDotenvFile(envPath(projectRoot, filename), content);
+}
+// ---------------------------------------------------------------------------------------------
+// Parsing. The process reads `.env` with dotenv's `parse`, so the Console's view of the file must be
+// exactly dotenv's: the same assignments, with the same values. `DOTENV_LINE` is dotenv's own line
+// pattern (dotenv 17, `lib/main.js` `LINE`) with two extra capture groups (the separator and the
+// value) and match indices; `scanEnv` runs it the way `parse` does (`\r\n` / `\r` read as `\n`) and
+// maps every match back to the bytes of the file. Anything dotenv does not read as an assignment is
+// text (comments, blank and stray lines). The tests compare this scan with `parse` itself.
+// No `u` flag: the pattern is kept exactly as dotenv has it.
+const DOTENV_LINE = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/dgm;
+const REFERENCE = /^\$\{[^}]+\}$/u;
+/** dotenv's value rules, applied to the captured value (see `parse` in dotenv's `lib/main.js`). */
+function dotenvValue(captured) {
+    let value = captured.trim();
+    const maybeQuote = value[0];
+    value = value.replace(/^(['"`])([\s\S]*)\1$/mg, '$2');
+    if (maybeQuote === '"')
+        value = value.replace(/\\n/gu, '\n').replace(/\\r/gu, '\r');
+    return value;
+}
+function scanEnv(content) {
+    // dotenv reads `\r\n` and `\r` as `\n`; `toOriginal[i]` is the offset in `content` of normalised offset `i`.
+    let normalized = '';
+    const toOriginal = [];
+    for (let index = 0; index < content.length; index += 1) {
+        toOriginal.push(index);
+        if (content[index] === '\r') {
+            normalized += '\n';
+            if (content[index + 1] === '\n')
+                index += 1;
+        }
+        else
+            normalized += content[index];
+    }
+    toOriginal.push(content.length);
+    const entries = [];
+    const texts = [];
+    let cursor = 0;
+    const pattern = new RegExp(DOTENV_LINE.source, DOTENV_LINE.flags);
+    let match;
+    while ((match = pattern.exec(normalized)) !== null) {
+        const indices = match.indices;
+        const first = match.index + match[0].search(/\S/u);
+        const lineStart = normalized.lastIndexOf('\n', first - 1) + 1;
+        const separatorEnd = indices[2][1];
+        let valueStart = separatorEnd;
+        let valueEnd = separatorEnd;
+        if (match[3] !== undefined) {
+            const [groupStart, groupEnd] = indices[3];
+            const leading = /^\s*/u.exec(match[3])[0];
+            // A value on a line of its own (`KEY=` then `"value"`): replacing it replaces that line break too.
+            valueStart = leading.includes('\n') ? groupStart : groupStart + leading.length;
+            valueEnd = groupStart + match[3].trimEnd().length;
+            if (valueEnd < valueStart)
+                valueEnd = valueStart;
+        }
+        const last = Math.max(valueEnd, separatorEnd) - 1;
+        const lineBreak = normalized.indexOf('\n', last);
+        const lineEnd = lineBreak < 0 ? normalized.length : lineBreak + 1;
+        if (lineStart > cursor)
+            texts.push({ start: toOriginal[cursor], end: toOriginal[lineStart] });
+        const rawStart = groupValueStart(match[3], indices[3]);
+        entries.push(Object.freeze({
+            key: match[1],
+            exported: /^export\s/u.test(normalized.slice(first, indices[1][0])),
+            start: toOriginal[lineStart],
+            end: toOriginal[lineEnd],
+            valueStart: toOriginal[valueStart],
+            valueEnd: toOriginal[valueEnd],
+            raw: content.slice(toOriginal[rawStart ?? valueStart], toOriginal[valueEnd]),
+            value: dotenvValue(match[3] ?? ''),
+        }));
+        cursor = lineEnd;
+    }
+    if (cursor < normalized.length)
+        texts.push({ start: toOriginal[cursor], end: content.length });
+    return { entries, texts };
+}
+/** Where the captured value starts once its leading whitespace is left out. */
+function groupValueStart(captured, span) {
+    if (captured === undefined || !span)
+        return undefined;
+    return span[0] + /^\s*/u.exec(captured)[0].length;
+}
+/** What the process reads from `content`: dotenv's own `parse` (the last assignment of a key wins). */
+function dotenvValues(content) {
+    return new Map(Object.entries(parse(content)));
+}
+/** The value as the process reads it (dotenv's own rules on that one assignment). */
+function effectiveValue(key, rawValue) {
+    return parse(`${key}=${rawValue}`)[key] ?? '';
+}
+function maskedVariable(entry) {
+    return Object.freeze({
+        key: entry.key,
+        masked: maskConsoleEnvValue(entry.value),
+        hasValue: entry.value.length > 0,
+        ...(REFERENCE.test(entry.value) ? { isReference: true } : {}),
+    });
+}
+/** A comment that names a key: `# KEY=value`, `## KEY=value`, `#- KEY: value`, `# export KEY=value`. */
+const COMMENTED_ASSIGNMENT = /^\s*#[^\w\r\n]*?(?:export\s+)?([\w.-]+)\s*[=:](.*\S.*)$/u;
+/** Any other sign of a value in a comment: `=` or `:` followed by text (`# old token is: sk-…`). */
+const COMMENTED_VALUE = /[=:](?=\s*\S)/u;
+const unquote = (text) => text.trim().replace(/^(["'`])([\s\S]*)\1$/u, '$2');
+function textLines(raw) {
+    return raw.split(/\r\n|\n|\r/u).slice(0, raw.match(/\r\n|\n|\r/u) ? -1 : undefined).map((line) => {
+        if (!line.trim())
+            return Object.freeze({ kind: 'blank' });
+        if (!/^\s*#/u.test(line))
+            return Object.freeze({ kind: 'other' });
+        const commented = COMMENTED_ASSIGNMENT.exec(line);
+        if (commented)
+            return Object.freeze({ kind: 'comment', key: commented[1], masked: maskConsoleEnvValue(unquote(commented[2])) });
+        const separator = COMMENTED_VALUE.exec(line);
+        if (separator) {
+            const head = line.slice(0, separator.index + 1);
+            return Object.freeze({ kind: 'comment', text: `${head} ${maskConsoleEnvValue(unquote(line.slice(separator.index + 1))) || ENV_MASK_CHAR.repeat(ENV_MASK_RUN)}` });
+        }
+        return Object.freeze({ kind: 'comment', text: line });
+    });
+}
+/**
+ * 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 function maskEnvFileContent(file, content) {
+    const { entries, texts } = scanEnv(content);
+    const lines = [];
+    const variables = new Map();
+    let text = 0;
+    for (const entry of entries) {
+        while (text < texts.length && texts[text].start < entry.start)
+            lines.push(...textLines(content.slice(texts[text].start, texts[text++].end)));
+        lines.push(Object.freeze({ kind: 'entry', key: entry.key, ...(entry.exported ? { export: true } : {}) }));
+        // A key assigned twice: the last assignment is the one the process reads; keep first position.
+        variables.set(entry.key, maskedVariable(entry));
+    }
+    while (text < texts.length)
+        lines.push(...textLines(content.slice(texts[text].start, texts[text++].end)));
+    const order = [...new Set(entries.map(entry => entry.key))];
+    const masked = lines.map((line) => {
+        switch (line.kind) {
+            case 'blank': return '';
+            case 'comment': return 'text' in line ? line.text : `# ${line.key}=${line.masked}`;
+            case 'entry': return `${line.export ? 'export ' : ''}${line.key}=${variables.get(line.key).masked}`;
+            case 'other': return ENV_MASK_CHAR.repeat(ENV_MASK_RUN);
+        }
+    });
+    return Object.freeze({
+        format: 'masked',
+        file,
+        variables: Object.freeze(order.map(key => variables.get(key))),
+        lines: Object.freeze(lines),
+        content: masked.length ? `${masked.join('\n')}\n` : '',
+    });
+}
+export async function readEnvFileView(projectRoot, filename) {
+    return maskEnvFileContent(filename, await readDotenvFile(envPath(projectRoot, filename)));
+}
+export class EnvVariableNotFoundError extends Error {
+    code = 'env_variable_not_found';
+    constructor(filename, key) {
+        super(`${filename} 中没有变量 ${key}`);
+        this.name = 'EnvVariableNotFoundError';
+    }
+}
+/**
+ * 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 async function revealEnvVariable(projectRoot, filename, key) {
+    if (typeof key !== 'string' || !ENV_KEY_PATTERN.test(key) || key.length > ENV_SAVE_LIMITS.maxKeyLength) {
+        throw new EnvChangeError('变量名无效');
+    }
+    const content = await readDotenvFile(envPath(projectRoot, filename));
+    const entry = scanEnv(content).entries.filter(item => item.key === key).at(-1);
+    if (!entry)
+        throw new EnvVariableNotFoundError(filename, key);
+    return Object.freeze({ file: filename, key, value: entry.raw });
+}
+export class EnvChangeError extends Error {
+    code = 'invalid_env_change';
+    constructor(message) {
+        super(message);
+        this.name = 'EnvChangeError';
+    }
+}
+/**
+ * Whether a raw value (as written after `KEY=`) is read back by dotenv as one assignment of `KEY`
+ * and nothing else: a value spanning lines must be quoted; after a closing quote only spaces or an
+ * inline comment (`# …`) may follow, on the same line. dotenv reads `"x"zz` as the unquoted `"x`
+ * and the next line as a new assignment, so such a value is refused.
+ */
+function assignmentProblem(value) {
+    const written = `K=${value}`;
+    const { entries, texts } = scanEnv(written);
+    const quoted = /^\s*["'`]/u.test(value);
+    if (/[\r\n]/u.test(value) && !/^[ \t]*["'`]/u.test(value))
+        return '多行值必须用引号包裹';
+    const entry = entries[0];
+    if (entries.length !== 1 || texts.length !== 0 || entry.key !== 'K' || entry.end !== written.length) {
+        return quoted ? '引号没有闭合，或闭合引号之后还有注释以外的内容' : '值会被读成多行或多个变量';
+    }
+    const tail = written.slice(entry.valueEnd);
+    if (/[\r\n]/u.test(tail))
+        return '闭合引号之后还有换行';
+    if (quoted) {
+        const quote = value.trimStart()[0];
+        const raw = entry.raw;
+        if (raw.length < 2 || raw[0] !== quote || raw.at(-1) !== quote || !/^\s*(?:#.*)?$/u.test(tail)) {
+            return '引号没有闭合，或闭合引号之后还有注释以外的内容';
+        }
+    }
+    return null;
+}
+/** Validated `env:save` changes; throws {@link EnvChangeError} (nothing is written). */
+export function validateEnvChanges(changes) {
+    if (!Array.isArray(changes) || changes.length === 0)
+        throw new EnvChangeError('changes 必须是非空数组');
+    if (changes.length > ENV_SAVE_LIMITS.maxChanges)
+        throw new EnvChangeError(`一次最多修改 ${ENV_SAVE_LIMITS.maxChanges} 个变量`);
+    const seen = new Set();
+    return Object.freeze(changes.map((item, index) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            throw new EnvChangeError(`changes[${index}] 必须是对象`);
+        const { key, value } = item;
+        const remove = item.delete === true;
+        if (typeof key !== 'string' || !ENV_KEY_PATTERN.test(key) || key.length > ENV_SAVE_LIMITS.maxKeyLength) {
+            throw new EnvChangeError(`changes[${index}].key 不是合法变量名`);
+        }
+        if (seen.has(key))
+            throw new EnvChangeError(`变量 ${key} 在 changes 中出现了多次`);
+        seen.add(key);
+        if (remove) {
+            if (value !== undefined)
+                throw new EnvChangeError(`changes[${index}] 不能同时删除并设置值`);
+            return Object.freeze({ key, delete: true });
+        }
+        if (typeof value !== 'string')
+            throw new EnvChangeError(`changes[${index}].value 必须是字符串`);
+        if (value.length > ENV_SAVE_LIMITS.maxValueLength)
+            throw new EnvChangeError(`变量 ${key} 的值过长`);
+        if (isConsoleEnvMaskPlaceholder(value)) {
+            throw new EnvChangeError(`变量 ${key} 的值是打码占位（●），不能保存；请填写真实值，或不修改这个变量`);
+        }
+        const problem = assignmentProblem(value);
+        if (problem)
+            throw new EnvChangeError(`变量 ${key}：${problem}`);
+        return Object.freeze({ key, value });
+    }));
+}
+/** `content` with one change applied; every line not naming `change.key` keeps its bytes. */
+function applyEnvChange(content, change) {
+    const entries = scanEnv(content).entries.filter(entry => entry.key === change.key);
+    let text = content;
+    // From the last assignment backwards, so earlier offsets stay valid.
+    for (const entry of [...entries].reverse()) {
+        text = 'delete' in change
+            ? text.slice(0, entry.start) + text.slice(entry.end)
+            : text.slice(0, entry.valueStart) + change.value + text.slice(entry.valueEnd);
+    }
+    if ('delete' in change || entries.length)
+        return text;
+    const eol = text.match(/\r\n|\n|\r/u)?.[0] ?? '\n';
+    const separator = text && !/[\r\n]$/u.test(text) ? eol : '';
+    return `${text}${separator}${change.key}=${change.value}${eol}`;
+}
+/**
+ * Checks what dotenv reads after the changes: every key not submitted keeps its value (none appears
+ * or disappears), every set key reads as its submitted value and every deleted key is gone.
+ * Throws {@link EnvChangeError} otherwise (the file is not written).
+ */
+function assertOnlySubmittedKeysChanged(before, after, changes) {
+    const old = dotenvValues(before);
+    const next = dotenvValues(after);
+    const submitted = new Map(changes.map(change => [change.key, change]));
+    const problems = [];
+    for (const key of new Set([...old.keys(), ...next.keys()])) {
+        const change = submitted.get(key);
+        if (!change) {
+            if (old.get(key) !== next.get(key) || old.has(key) !== next.has(key))
+                problems.push(key);
+        }
+        else if ('delete' in change ? next.has(key) : next.get(key) !== effectiveValue(key, change.value)) {
+            problems.push(key);
+        }
+    }
+    for (const change of changes) {
+        if (!('delete' in change) && !next.has(change.key))
+            problems.push(change.key);
+    }
+    if (problems.length) {
+        throw new EnvChangeError(`保存会改变未提交的变量或读不回提交的值：${[...new Set(problems)].slice(0, 8).join('、')}；文件没有修改`);
+    }
+}
+/**
+ * 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 function applyEnvChanges(content, changes) {
+    const next = changes.reduce(applyEnvChange, content);
+    assertOnlySubmittedKeysChanged(content, next, changes);
+    return next;
+}
+/**
+ * `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 async function updateEnvVariables(projectRoot, filename, changes) {
+    const valid = validateEnvChanges(changes);
+    await updateDotenvFile(envPath(projectRoot, filename), current => applyEnvChanges(current, valid));
+    return Object.freeze({ changed: Object.freeze(valid.map(change => change.key)) });
+}
+/** Keys of `content` whose value (or commented value) is a mask placeholder. */
+export function maskedPlaceholderKeys(content) {
+    const keys = new Set();
+    const { entries, texts } = scanEnv(content);
+    for (const entry of entries)
+        if (isConsoleEnvMaskPlaceholder(entry.raw))
+            keys.add(entry.key);
+    for (const text of texts)
+        if (isConsoleEnvMaskPlaceholder(content.slice(text.start, text.end)))
+            keys.add('(非变量行)');
+    return [...keys];
+}
+/**
+ * `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 async function replaceEnvFileContent(projectRoot, filename, content) {
+    const masked = maskedPlaceholderKeys(content);
+    if (masked.length) {
+        throw new EnvChangeError(`内容里有打码占位（●），不能整文件保存：${masked.slice(0, 8).join('、')}。请改用逐键保存`);
+    }
+    await writeEnvFile(projectRoot, filename, content);
 }

package/lib/config/validation-messages.d.ts

@@ -0,0 +1,13 @@
+import { type Locale } from '@zhin.js/plugin-runtime';
+/** The parts of an Ajv `ErrorObject` a configuration message needs. */
+export interface SchemaIssue {
+    readonly keyword: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly message?: string;
+}
+/**
+ * Localized text for one Ajv issue of a Plugin configuration, in the project `locale`
+ * (`zh-CN` by default). `location` is the field path inside the configuration block; it is named in
+ * the message so a reader sees which field is wrong without matching it to the separate path.
+ */
+export declare function formatSchemaIssue(issue: SchemaIssue, location: readonly string[], locale: Locale | unknown): string;

package/lib/config/validation-messages.js

@@ -0,0 +1,59 @@
+import { createMessages, resolveLocale } from '@zhin.js/plugin-runtime';
+const messages = createMessages({
+    type: { 'zh-CN': '{field}类型应为 {type}', en: '{field}must be of type {type}' },
+    maximum: { 'zh-CN': '{field}不能大于 {limit}', en: '{field}must be at most {limit}' },
+    minimum: { 'zh-CN': '{field}不能小于 {limit}', en: '{field}must be at least {limit}' },
+    exclusiveMaximum: { 'zh-CN': '{field}必须小于 {limit}', en: '{field}must be less than {limit}' },
+    exclusiveMinimum: { 'zh-CN': '{field}必须大于 {limit}', en: '{field}must be greater than {limit}' },
+    minLength: { 'zh-CN': '{field}长度不能少于 {limit} 个字符', en: '{field}must be at least {limit} characters long' },
+    maxLength: { 'zh-CN': '{field}长度不能超过 {limit} 个字符', en: '{field}must be at most {limit} characters long' },
+    enum: { 'zh-CN': '{field}必须是以下值之一：{values}', en: '{field}must be one of: {values}' },
+    const: { 'zh-CN': '{field}必须等于 {value}', en: '{field}must equal {value}' },
+    pattern: { 'zh-CN': '{field}格式不符合 {pattern}', en: '{field}must match the pattern {pattern}' },
+    required: { 'zh-CN': '缺少必填字段 {property}', en: 'missing required field {property}' },
+    additionalProperties: { 'zh-CN': '不支持的字段 {property}', en: 'unknown field {property}' },
+    format: { 'zh-CN': '{field}应为有效的 {format}', en: '{field}must be a valid {format}' },
+    minItems: { 'zh-CN': '{field}至少需要 {limit} 项', en: '{field}must have at least {limit} items' },
+    maxItems: { 'zh-CN': '{field}最多只能有 {limit} 项', en: '{field}must have at most {limit} items' },
+    fallback: { 'zh-CN': '{field}不满足 {keyword} 约束（{detail}）', en: '{field}does not satisfy {keyword} ({detail})' },
+    field: { 'zh-CN': '字段 {path} ', en: 'Field {path} ' },
+});
+const NUMERIC_LIMITS = new Set(['maximum', 'minimum', 'exclusiveMaximum', 'exclusiveMinimum', 'minLength', 'maxLength', 'minItems', 'maxItems']);
+function display(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+/**
+ * Localized text for one Ajv issue of a Plugin configuration, in the project `locale`
+ * (`zh-CN` by default). `location` is the field path inside the configuration block; it is named in
+ * the message so a reader sees which field is wrong without matching it to the separate path.
+ */
+export function formatSchemaIssue(issue, location, locale) {
+    const lang = resolveLocale(locale);
+    const field = location.length > 0 ? messages(lang, 'field', { path: location.join('.') }) : '';
+    const params = issue.params;
+    switch (issue.keyword) {
+        case 'type': {
+            const type = Array.isArray(params.type) ? params.type.join(' | ') : String(params.type);
+            return messages(lang, 'type', { field, type: type === 'array' ? 'list' : type });
+        }
+        case 'enum': {
+            const allowed = Array.isArray(params.allowedValues) ? params.allowedValues.map(display).join(', ') : display(params.allowedValues);
+            return messages(lang, 'enum', { field, values: allowed });
+        }
+        case 'const':
+            return messages(lang, 'const', { field, value: display(params.allowedValue) });
+        case 'pattern':
+            return messages(lang, 'pattern', { field, pattern: String(params.pattern) });
+        case 'format':
+            return messages(lang, 'format', { field, format: String(params.format) });
+        case 'required':
+            return messages(lang, 'required', { property: [...location, String(params.missingProperty)].join('.') });
+        case 'additionalProperties':
+            return messages(lang, 'additionalProperties', { property: [...location, String(params.additionalProperty)].join('.') });
+        default:
+            if (NUMERIC_LIMITS.has(issue.keyword) && (typeof params.limit === 'number' || typeof params.limit === 'string')) {
+                return messages(lang, issue.keyword, { field, limit: params.limit });
+            }
+            return messages(lang, 'fallback', { field, keyword: issue.keyword, detail: issue.message ?? issue.keyword });
+    }
+}