@zhin.js/gateway 1.2.0 → 1.4.0

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/literal-secrets.d.ts

@@ -32,3 +32,6 @@ export interface LiteralSecretFixResult {
  * variables already written, so the operation is idempotent.
  */
 export declare function moveLiteralSecretsToEnv(projectRoot: string, configFile: string): Promise<LiteralSecretFixResult>;
+/** A `NAME=value` dotenv line that parses back to exactly `value`, or undefined when none does. */
+export declare function dotenvLine(name: string, value: string): string | undefined;
+export declare function readDocumentPath(document: unknown, path: readonly string[]): unknown;

package/lib/config/literal-secrets.js

@@ -100,7 +100,7 @@ export async function moveLiteralSecretsToEnv(projectRoot, configFile) {
     return Object.freeze({ moved: Object.freeze(moved), skipped: Object.freeze(skipped) });
 }
 /** A `NAME=value` dotenv line that parses back to exactly `value`, or undefined when none does. */
-function dotenvLine(name, value) {
+export function dotenvLine(name, value) {
     if (/[\r\n]/u.test(value))
         return undefined;
     for (const quote of ["'", '`', '"']) {
@@ -112,6 +112,9 @@ function dotenvLine(name, value) {
     }
     return undefined;
 }
+export function readDocumentPath(document, path) {
+    return readPath(document, path);
+}
 function readPath(document, path) {
     let current = document;
     for (const segment of path) {

package/lib/config/patch-path-messages.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Chinese explanations for project config patches that cannot apply (#1250): unknown top-level
+ * keys (with close candidates), declaration keys, and array indexes outside the array. Shown by
+ * `zhin config set|unset` and the Console; they never name RPCs or revisions.
+ */
+import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+/** Up to three known keys close to `key` (edit distance, prefix or substring). */
+export declare function closeConfigKeys(key: string, known: Iterable<string>): string[];
+export declare function unknownConfigKeyMessage(section: string, known: Iterable<string>): string;
+export declare function declarationKeyMessage(section: string): string;
+/**
+ * Why `path` cannot be written in `document` because of an array segment, or undefined. `set`
+ * cannot append: an index equal to the length is out of range too.
+ */
+export declare function describeArrayPathProblem(document: RuntimeConfigDocument, path: readonly string[], op: 'set' | 'remove'): string | undefined;

package/lib/config/patch-path-messages.js

@@ -0,0 +1,71 @@
+function displayPath(path) {
+    return path.join('.');
+}
+/** Damerau-free Levenshtein distance, enough for "did you mean" suggestions. */
+function distance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        let previous = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const current = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+            previous = current;
+        }
+    }
+    return row[b.length];
+}
+/** Up to three known keys close to `key` (edit distance, prefix or substring). */
+export function closeConfigKeys(key, known) {
+    const lower = key.toLowerCase();
+    return [...new Set(known)]
+        .map(candidate => ({ candidate, score: distance(lower, candidate.toLowerCase()) }))
+        .filter(({ candidate, score }) => score <= Math.max(2, Math.floor(key.length / 3))
+        || candidate.toLowerCase().startsWith(lower) || lower.startsWith(candidate.toLowerCase())
+        || (lower.length >= 3 && candidate.toLowerCase().includes(lower)))
+        .sort((left, right) => left.score - right.score || left.candidate.localeCompare(right.candidate))
+        .slice(0, 3)
+        .map(({ candidate }) => candidate);
+}
+export function unknownConfigKeyMessage(section, known) {
+    const close = closeConfigKeys(section, known);
+    return `没有这个配置项：${section}（不是 Host 配置，也不是已声明的插件实例）`
+        + (close.length > 0 ? `。你是不是想写：${close.join('、')}？` : '。')
+        + '要给新插件写配置，先在 Console「插件」页或用 zhin install <包名> 安装并声明它';
+}
+export function declarationKeyMessage(section) {
+    return `${section} 是插件声明，不能用配置补丁修改；请在 Console「插件」页管理插件，或直接编辑配置文件`;
+}
+/**
+ * Why `path` cannot be written in `document` because of an array segment, or undefined. `set`
+ * cannot append: an index equal to the length is out of range too.
+ */
+export function describeArrayPathProblem(document, path, op) {
+    let current = document;
+    for (let index = 0; index < path.length; index++) {
+        const segment = path[index];
+        const here = path.slice(0, index + 1);
+        if (Array.isArray(current)) {
+            const parent = displayPath(path.slice(0, index));
+            if (!/^(0|[1-9]\d*)$/u.test(segment)) {
+                return `${parent} 是数组，${displayPath(here)} 里的 "${segment}" 应为数组下标（0–${Math.max(current.length - 1, 0)}）`;
+            }
+            const position = Number(segment);
+            if (position >= current.length) {
+                const range = current.length === 0 ? '当前是空数组' : `当前有 ${current.length} 项，下标 0–${current.length - 1}`;
+                const append = op === 'set'
+                    ? `。要追加一项：先用 zhin config get ${parent} 读出整个数组，加上新项后用 zhin config set ${parent} '<JSON 数组>' 整体写回`
+                    : '';
+                return `${displayPath(here)} 超出数组范围（${range}）${append}`;
+            }
+            current = current[position];
+            continue;
+        }
+        if (!current || typeof current !== 'object')
+            return undefined;
+        current = Object.hasOwn(current, segment) ? current[segment] : undefined;
+        if (current === undefined)
+            return undefined;
+    }
+    return undefined;
+}

package/lib/config/secret-storage.d.ts

@@ -0,0 +1,42 @@
+import type { ConfigPatch, RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+/** How a patch stores secret values: `env` (default) or `plain` (explicit opt-out, e.g. `zhin config set --plain`). */
+export type ConfigSecretStorage = 'env' | 'plain';
+/** Result / error code when a write would store secret values in `.env` without `ops.env.write`. */
+export declare const SECRET_ENVIRONMENT_WRITE_REQUIRED = "env-write-required";
+/** Refusal message for {@link SECRET_ENVIRONMENT_WRITE_REQUIRED}; names the fields, never values. */
+export declare function secretEnvironmentWriteRequiredMessage(paths: readonly (readonly string[])[]): string;
+/** `setKey` refusal: the block holds secret literals but the caller may not write `.env`. */
+export declare class SecretEnvironmentWriteRequiredError extends Error {
+    readonly paths: readonly (readonly string[])[];
+    readonly code = "env-write-required";
+    constructor(paths: readonly (readonly string[])[]);
+}
+export interface SecretAssignment {
+    readonly path: readonly string[];
+    readonly variable: string;
+    /** Never serialized into results. */
+    readonly value: string;
+}
+export interface SecretExternalizationPlan {
+    /** `set path → ${VAR}` patches applied after the caller's patches. */
+    readonly patches: readonly ConfigPatch[];
+    readonly assignments: readonly SecretAssignment[];
+    /** Secret values `.env` cannot hold (line breaks): the write is refused for these paths. */
+    readonly errors: readonly {
+        readonly path: string;
+        readonly message: string;
+    }[];
+}
+/** `http.token` → `HTTP_TOKEN` (the `${…}` name the scaffold uses), `qq.endpoints.0.appSecret` → `QQ_ENDPOINTS_0_APP_SECRET`. */
+export declare function canonicalSecretVariable(path: readonly string[]): string;
+/**
+ * Plans moving the literal secrets that `candidate` newly holds under `touched` paths (values that
+ * differ from `current`) into `.env`.
+ */
+export declare function planSecretExternalization(projectRoot: string, environmentName: string, current: RuntimeConfigDocument, candidate: RuntimeConfigDocument, touched: readonly (readonly string[])[]): Promise<SecretExternalizationPlan>;
+/**
+ * Writes the assignments: into `.env.<environment>` when that file already defines the variable
+ * (it overrides `.env`), and into `.env` otherwise. Returns a function that restores the previous
+ * contents (used when the config write does not happen after all).
+ */
+export declare function writeSecretAssignments(projectRoot: string, environmentName: string, assignments: readonly SecretAssignment[]): Promise<() => Promise<void>>;

package/lib/config/secret-storage.js

@@ -0,0 +1,140 @@
+/**
+ * Secret values written through a config patch go to `.env`, not into the config file (#1250).
+ *
+ * A `set` that writes a literal into a schema-marked secret field (`x-zhin-secret`, `writeOnly`,
+ * `format: password`, `x-zhin-config.secret`, or the secret field-name fallback) is rewritten:
+ * the value is stored as a `.env` variable and the config keeps (or gets) the `${VAR}` reference.
+ * The variable is the field's canonical name derived from its path (`http.token` → `HTTP_TOKEN`,
+ * with a numeric suffix when another value already holds that name). A `${VAR}` the field merely
+ * references is never overwritten unless it is that canonical name: otherwise a config write could
+ * replace any `.env` variable (e.g. point `http.token` at `${OPENAI_API_KEY}`, then set a literal).
+ * Writing into `.env` at all needs the caller's `ops.env.write` ({@link SecretEnvironmentWriteRequiredError}).
+ * Values are never returned or logged.
+ */
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseDotenv } from 'dotenv';
+import { updateDotenvFile } from '@zhin.js/runtime';
+import { dotenvLine, findProjectLiteralSecrets, literalSecretEnvironmentName, readDocumentPath as readPath } from './literal-secrets.js';
+const WHOLE_REFERENCE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/u;
+/** Result / error code when a write would store secret values in `.env` without `ops.env.write`. */
+export const SECRET_ENVIRONMENT_WRITE_REQUIRED = 'env-write-required';
+/** Refusal message for {@link SECRET_ENVIRONMENT_WRITE_REQUIRED}; names the fields, never values. */
+export function secretEnvironmentWriteRequiredMessage(paths) {
+    return `敏感字段 ${paths.map(path => path.join('.')).join('、')} 的值要写入 .env，需要 ops.env.write 权限；未保存。`
+        + '请让有该权限的管理员设置，或在 .env 中设置变量后写入 ${VAR} 引用';
+}
+/** `setKey` refusal: the block holds secret literals but the caller may not write `.env`. */
+export class SecretEnvironmentWriteRequiredError extends Error {
+    paths;
+    code = SECRET_ENVIRONMENT_WRITE_REQUIRED;
+    constructor(paths) {
+        super(secretEnvironmentWriteRequiredMessage(paths));
+        this.paths = paths;
+        this.name = 'SecretEnvironmentWriteRequiredError';
+    }
+}
+/** `http.token` → `HTTP_TOKEN` (the `${…}` name the scaffold uses), `qq.endpoints.0.appSecret` → `QQ_ENDPOINTS_0_APP_SECRET`. */
+export function canonicalSecretVariable(path) {
+    return literalSecretEnvironmentName(path).replace(/^ZHIN_/u, '');
+}
+function startsWith(path, prefix) {
+    return prefix.length <= path.length && prefix.every((segment, index) => path[index] === segment);
+}
+async function readOptional(file) {
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Plans moving the literal secrets that `candidate` newly holds under `touched` paths (values that
+ * differ from `current`) into `.env`.
+ */
+export async function planSecretExternalization(projectRoot, environmentName, current, candidate, touched) {
+    const literals = (await findProjectLiteralSecrets(projectRoot, candidate))
+        .filter(secret => touched.some(path => startsWith(secret.path, path)));
+    if (literals.length === 0)
+        return { patches: [], assignments: [], errors: [] };
+    const layers = await Promise.all(['.env', `.env.${environmentName}`].map(async (name) => parseDotenv((await readOptional(join(projectRoot, name))) ?? '')));
+    const taken = new Map();
+    for (const layer of layers)
+        for (const [name, value] of Object.entries(layer))
+            taken.set(name, value);
+    const patches = [];
+    const assignments = [];
+    const errors = [];
+    for (const secret of literals) {
+        const value = readPath(candidate, secret.path);
+        if (typeof value !== 'string' || value === '' || value === readPath(current, secret.path))
+            continue;
+        const label = secret.path.join('.');
+        const canonical = canonicalSecretVariable(secret.path);
+        const reference = WHOLE_REFERENCE.exec(String(readPath(current, secret.path) ?? ''))?.[1];
+        // Only the field's own canonical variable is updated in place. Any other `${VAR}` the field
+        // references may belong to something else (#1250): a fresh name is written instead.
+        let variable = canonical;
+        if (reference !== canonical) {
+            for (let suffix = 2; (taken.has(variable) && taken.get(variable) !== value) || variable === reference; suffix += 1) {
+                variable = `${canonical}_${suffix}`;
+            }
+        }
+        if (!dotenvLine(variable, value)) {
+            errors.push({ path: `$.${label}`, message: `${label} 是敏感字段，值含换行等字符，无法写入 .env；请手动在 .env 设置后引用 \${${variable}}，或明确用明文保存（zhin config set --plain）` });
+            continue;
+        }
+        taken.set(variable, value);
+        assignments.push({ path: secret.path, variable, value });
+        patches.push({ op: 'set', path: secret.path, value: `\${${variable}}` });
+    }
+    return { patches, assignments, errors };
+}
+function assign(content, variable, line) {
+    const pattern = new RegExp(`^[ \\t]*(?:export[ \\t]+)?${variable}[ \\t]*=.*$`, 'mu');
+    if (pattern.test(content))
+        return content.replace(pattern, line);
+    const separator = content === '' || content.endsWith('\n') ? '' : '\n';
+    return `${content}${separator}${line}\n`;
+}
+/**
+ * Writes the assignments: into `.env.<environment>` when that file already defines the variable
+ * (it overrides `.env`), and into `.env` otherwise. Returns a function that restores the previous
+ * contents (used when the config write does not happen after all).
+ */
+export async function writeSecretAssignments(projectRoot, environmentName, assignments) {
+    if (assignments.length === 0)
+        return async () => { };
+    const files = ['.env', `.env.${environmentName}`].map(name => join(projectRoot, name));
+    const originals = await Promise.all(files.map(readOptional));
+    const overlay = parseDotenv(originals[1] ?? '');
+    const byFile = new Map();
+    for (const item of assignments) {
+        const file = Object.hasOwn(overlay, item.variable) ? files[1] : files[0];
+        byFile.set(file, [...(byFile.get(file) ?? []), item]);
+    }
+    const written = [];
+    try {
+        for (const [file, items] of byFile) {
+            await updateDotenvFile(file, content => items.reduce((text, item) => assign(text, item.variable, dotenvLine(item.variable, item.value)), content));
+            written.push(file);
+        }
+    }
+    catch (error) {
+        await restore(written);
+        throw error;
+    }
+    async function restore(targets) {
+        for (const file of targets) {
+            const original = originals[files.indexOf(file)];
+            if (original === undefined)
+                await rm(file, { force: true });
+            else
+                await updateDotenvFile(file, () => original);
+        }
+    }
+    return () => restore(written);
+}