iterate-plugin 3.5.7 → 3.7.0

package/dist/approval-gate.js

@@ -6,9 +6,19 @@
  * any I/O, so it is fully unit-testable:
  *
  *   - `{ kind: 'allow' }`        → run the call.
- *   - `{ kind: 'ask', reason }`  → prompt the human via the dsh approval service.
+ *   - `{ kind: 'ask', reason, displayReason }` → prompt the human via the dsh
+ *     approval service (`displayReason` carries the localized prompt text;
+ *     dsh 0.2.x renders it when present).
  *   - `{ kind: 'deny', reason }` → refuse; the caller surfaces the reason.
  *
+ * LANGUAGE RULE (project `config.language`, zh|en):
+ *   - Human-facing text (the `ask` prompt / `displayReason`) FOLLOWS the
+ *     configured language.
+ *   - Structured/durable text (the `deny` reason, `deny.info.reason`,
+ *     decision-log and console output) STAYS ENGLISH so logs, audits, and
+ *     machine matchers never depend on a locale. `ask.reason` is the audited
+ *     English summary; `displayReason` is the localized prompt.
+ *
  * Policy (config `observatory.approval`, default 'ask'):
  *   - `allow` → destructive iterate calls always run (debug/trusted).
  *   - `deny`  → destructive iterate calls are always refused (fail-closed).
@@ -16,36 +26,135 @@
  *
  * Destructive calls are exactly the ones that mutate the workspace:
  * `iterate_fix` (writes files), `iterate_rollback` (restores from backups),
- * and `iterate_prune` with `dryRun !== true` (deletes `.iterate/` artifacts).
+ * `iterate_prune` with `dryRun === false` (deletes `.iterate/` artifacts —
+ * prune is read-only by default, so only an explicit `dryRun: false` gates),
+ * and `iterate_config` with `operation === 'write'` (rewrites
+ * `iterate.config.yaml`). `iterate_config` writes matter because the config
+ * is policy: a silent `reviewer: {evidence_validation: false}` or a
+ * `validation.commands` addition changes what later rounds are allowed to do,
+ * so a write is consented to exactly like a file write — the read operation
+ * stays free.
  * Read-only calls are always allowed. Non-iterate calls are untouched — the
  * gate only ever inspects iterate tools so it cannot alter unrelated behavior.
  */
-/** Destructive iterate tools subject to the gate. */
-const DESTRUCTIVE_TOOLS = new Set(['iterate_fix', 'iterate_rollback', 'iterate_prune']);
-/** Human-readable reason rendered in the approval prompt. */
-function describe(toolName, arguments0) {
+/** Iterate tools subject to the gate (some only in specific operations). */
+const DESTRUCTIVE_TOOLS = new Set([
+    'iterate_fix',
+    'iterate_rollback',
+    'iterate_prune',
+    'iterate_config',
+]);
+/**
+ * True when this specific call MUTATES the workspace and therefore needs
+ * consent. Two of the four gated tools are operation-conditional:
+ *   - `iterate_prune` is read-only unless `dryRun === false`;
+ *   - `iterate_config` reads freely, but `operation === 'write'` rewrites
+ *     `iterate.config.yaml` — the file that carries the approval policy,
+ *     the reviewer gates, and the command allow-list.
+ */
+function mutatesWorkspace(toolName, args) {
+    if (toolName === 'iterate_prune')
+        return args.dryRun === false;
+    if (toolName === 'iterate_config')
+        return args.operation === 'write';
+    return DESTRUCTIVE_TOOLS.has(toolName);
+}
+/** Config updates the model supplied (empty when absent/malformed). */
+function readUpdates(args) {
+    const u = args.updates;
+    return u && typeof u === 'object' && !Array.isArray(u) ? u : {};
+}
+/**
+ * Config switches that DISABLE a safety gate, for the consent text. Writing
+ * `reviewer.evidence_validation: false` is legal config — but the human being
+ * asked must see that the call is about to turn a review gate off, not just
+ * "update a file".
+ */
+function disabledReviewGates(updates) {
+    const rv = updates.reviewer;
+    if (!rv || typeof rv !== 'object' || Array.isArray(rv))
+        return [];
+    const off = [];
+    for (const key of ['output_schema_validation', 'evidence_validation', 'coverage_validation']) {
+        if (rv[key] === false)
+            off.push(`reviewer.${key}`);
+    }
+    return off;
+}
+/**
+ * Human-readable reason rendered in the approval prompt.
+ *
+ * `language` selects the wording of the HUMAN-FACING text; call it with
+ * `'en'` for the structured, machine-readable string (deny reasons, audited
+ * ask summaries) and with the project's configured language for the prompt
+ * text (`displayReason`). The structured deny reason therefore never
+ * localizes, while the consent prompt follows `config.language`.
+ */
+export function describe(toolName, arguments0, language = 'en') {
+    const zh = language === 'zh';
     const file = arguments0 && typeof arguments0.file === 'string'
         ? `\`${arguments0.file}\``
-        : 'the workspace';
+        : zh
+            ? '工作区'
+            : 'the workspace';
     switch (toolName) {
         case 'iterate_fix':
-            return `Apply an atomic fix to ${file}`;
+            return zh
+                ? `对 ${file} 应用一次原子修复`
+                : `Apply an atomic fix to ${file}`;
         case 'iterate_rollback': {
-            const id = arguments0 && typeof arguments0.id === 'string' ? ` \`${arguments0.id}\`` : '';
-            return `Revert fix${id} (restore ${file} from backup)`;
+            // Rollback's parameters are `id` (required) + `path` (project root) —
+            // it has NO `file` param, so naming `arguments.file` could never
+            // identify the target ("restore the workspace from backup" every time).
+            // Name the fix id and, when present, the project scope instead.
+            const id = arguments0 && typeof arguments0.id === 'string' && arguments0.id
+                ? `\`${arguments0.id}\``
+                : null;
+            const scope = arguments0 && typeof arguments0.path === 'string' && arguments0.path
+                ? `\`${arguments0.path}\``
+                : null;
+            const target = id ?? scope ?? (zh ? '一次修复' : 'a fix');
+            const inScope = id && scope ? (zh ? `（位于 ${scope}）` : ` in ${scope}`) : '';
+            return zh
+                ? `回滚修复 ${target}${inScope}（从备份恢复其文件）`
+                : `Revert fix ${target}${inScope} (restore its file from backup)`;
         }
         case 'iterate_prune':
-            return 'Delete stale `.iterate/` runtime artifacts';
+            return zh
+                ? '删除过期的 `.iterate/` 运行时产物'
+                : 'Delete stale `.iterate/` runtime artifacts';
+        case 'iterate_config': {
+            // Name WHAT is being written and shout when the write disables a review
+            // gate — the consent prompt is the last human look before the model
+            // rewrites the policy file. The WARNING marker stays literal in both
+            // languages so the UI's highlight rule matches on it.
+            const updates = readUpdates(arguments0 ?? {});
+            const keys = Object.keys(updates);
+            const scope = keys.length > 0 ? keys.map((k) => `\`${k}\``).join(', ') : (zh ? '配置' : 'the configuration');
+            const base = zh
+                ? `更新 \`iterate.config.yaml\`（${scope}）`
+                : `Update \`iterate.config.yaml\` (${scope})`;
+            const off = disabledReviewGates(updates);
+            if (off.length === 0)
+                return base;
+            return zh
+                ? `${base} — WARNING：将关闭 ${off.join(', ')}`
+                : `${base} — WARNING: turns OFF ${off.join(', ')}`;
+        }
         default:
-            return `Run ${toolName}`;
+            return zh ? `运行 ${toolName}` : `Run ${toolName}`;
     }
 }
 /**
  * Decide whether a tool execution may proceed under the given policy.
- * Returns `allow` for read-only prune (`dryRun: true`), for `allow`-policy
+ * Returns `allow` for read-only prune (`dryRun: true`), for config READS
+ * (`iterate_config` without `operation: 'write'`), for `allow`-policy
  * deployments, and for any non-iterate tool.
+ *
+ * `language` only affects the HUMAN-FACING `ask.displayReason` text; the
+ * audited `ask.reason` and the `deny.reason` stay English (see header).
  */
-export function decideApproval(execution, policy) {
+export function decideApproval(execution, policy, language = 'en') {
     // Defensive reads: a hostile/proxied execution object must degrade to "not
     // our tool" (allow) rather than throw inside the gate.
     let name = '';
@@ -69,21 +178,32 @@ export function decideApproval(execution, policy) {
     const args = rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs)
         ? rawArgs
         : {};
-    // `iterate_prune` is read-only in its default dry-run mode — no gate needed.
-    if (name === 'iterate_prune' && args.dryRun === false) {
-        // falls through to the destructive path below
-    }
-    else if (name === 'iterate_prune') {
+    // Operation-conditional tools are read-only in their default operation —
+    // `iterate_prune` dry-runs and `iterate_config` reads need no consent.
+    if (!mutatesWorkspace(name, args))
         return { kind: 'allow' };
-    }
     if (policy === 'allow')
         return { kind: 'allow' };
-    const reason = describe(name, args);
+    // Structured text (deny reason / audited ask summary) is always English;
+    // only the human prompt (`displayReason`) follows the project language.
+    const reason = describe(name, args, 'en');
     if (policy === 'deny')
         return { kind: 'deny', reason };
-    return { kind: 'ask', reason };
+    const localized = describe(name, args, language);
+    return {
+        kind: 'ask',
+        reason,
+        displayReason: language === 'zh' ? { en: reason, zh: localized } : { en: reason },
+    };
 }
-/** True when any destructive iterate tool is listed in a name set. */
+/**
+ * True when a tool name is ROUTED through the approval gate.
+ *
+ * Name-level only (the caller has not parsed arguments yet), so the two
+ * operation-conditional tools are included for their whole name and
+ * {@link decideApproval} narrows per call: prune with a dry run and
+ * `iterate_config` reads both come back `allow`.
+ */
 export function isDestructiveIterateTool(name) {
     return typeof name === 'string' && DESTRUCTIVE_TOOLS.has(name);
 }

package/dist/atomic-fs.js

@@ -4,15 +4,24 @@
  * Every JSON/YAML artifact the plugin persists (.iterate/*.json,
  * iterate.config.yaml) is written through here: content goes to a
  * uniquely-named temp file in the SAME directory as the target (rename is
- * only atomic within one filesystem), then is `renameSync`ed over the
- * destination. A crash mid-write can therefore leave a stale temp file
- * behind, but never a truncated / half-written state file — readers
- * (which all tolerate missing/corrupt files) see either the previous or
- * the new content, never a mixture.
+ * only atomic within one filesystem), is fsynced to plating, then is
+ * `renameSync`ed over the destination, followed by a best-effort directory
+ * fsync so the rename itself is durable. A crash mid-write can therefore
+ * leave a stale temp file behind, but never a truncated / half-written state
+ * file — readers (which all tolerate missing/corrupt files) see either the
+ * previous or the new content, never a mixture.
+ *
+ * Two properties travel with the rename (which REPLACES the target inode):
+ *   - permissions: the temp is given the existing target's mode before the
+ *     swap, so rewriting a 0755 script stays 0755 and a 0600 secret never
+ *     widens to the umask default (0644).
+ *   - symlinks: when the target is a symlink, the atomic replace runs on the
+ *     link's REAL target instead — a fix written through a linked source file
+ *     must reach the real file, and the link must survive as a link.
  */
-import { dirname, join } from 'node:path';
-import { renameSync, rmSync, writeFileSync } from 'node:fs';
-import { rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { closeSync, fchmodSync, fsyncSync, lstatSync, openSync, realpathSync, renameSync, rmSync, statSync, writeSync, } from 'node:fs';
+import { lstat, open, realpath, rename, rm, stat } from 'node:fs/promises';
 /** Best-effort unlink of a leftover temp file (never throws). */
 function cleanupTemp(tmp) {
     try {
@@ -35,21 +44,128 @@ async function cleanupTempAsync(tmp) {
  * Unique temp file path for `filePath`, in the same directory, following the
  * prunable `.<basename>.tmp-<pid>-<random>` convention (see prune.ts
  * `isPrunableTemp`). The pid+random suffix makes concurrent writers safe.
+ * `basename` from node:path handles the platform separator (a hand-rolled
+ * `split('/')` breaks on Windows paths).
  */
 function tempPathFor(filePath) {
-    return join(dirname(filePath), `.${filePath.split('/').pop() ?? 'file'}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
+    return join(dirname(filePath), `.${basename(filePath)}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
+}
+/**
+ * Resolve the path the atomic replace must actually run on. A symlinked
+ * target is resolved to its real path: `renameSync(tmp, link)` would swap the
+ * LINK for a regular file and the linked-to file would silently keep its old
+ * content (a fix that never reaches the real source). When lstat/realpath
+ * cannot resolve (missing target, dangling or unreadable link), fall back to
+ * writing `filePath` itself — the pre-symlink-aware behavior.
+ */
+function resolveAtomicTarget(filePath) {
+    try {
+        if (lstatSync(filePath).isSymbolicLink())
+            return realpathSync(filePath);
+    }
+    catch {
+        // Missing target or unresolvable link — write `filePath` itself.
+    }
+    return filePath;
+}
+/** Async variant of {@link resolveAtomicTarget}. */
+async function resolveAtomicTargetAsync(filePath) {
+    try {
+        if ((await lstat(filePath)).isSymbolicLink())
+            return await realpath(filePath);
+    }
+    catch {
+        // Missing target or unresolvable link — write `filePath` itself.
+    }
+    return filePath;
+}
+/**
+ * The permission bits to give the temp file: the existing target's mode (so
+ * the rename-over swap preserves it), or `null` for a brand-new file — then
+ * the default open mode (0o666 & ~umask) applies, exactly like a plain
+ * `writeFileSync` of a new file.
+ */
+function existingMode(target) {
+    try {
+        return statSync(target).mode & 0o777;
+    }
+    catch {
+        return null;
+    }
+}
+/** Async variant of {@link existingMode}. */
+async function existingModeAsync(target) {
+    try {
+        return (await stat(target)).mode & 0o777;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best-effort fsync of the directory holding the final file, so the rename
+ * itself survives a crash. Unsupported on some platforms/filesystems — the
+ * data is already durable (fsynced on the temp), this only covers the
+ * directory entry, so failure is ignored by design.
+ */
+function fsyncDirBestEffort(dir) {
+    try {
+        const fd = openSync(dir, 'r');
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        // Directory fsync is unavailable (Windows, some FUSE mounts) — durability
+        // of the content does not depend on it.
+    }
+}
+/** Async variant of {@link fsyncDirBestEffort}. */
+async function fsyncDirBestEffortAsync(dir) {
+    let dh;
+    try {
+        dh = await open(dir, 'r');
+        await dh.sync();
+    }
+    catch {
+        // Directory fsync is unavailable — see fsyncDirBestEffort.
+    }
+    finally {
+        if (dh) {
+            await dh.close().catch(() => { });
+        }
+    }
 }
 /**
- * Write `data` to `filePath` atomically (temp file + rename, same dir).
+ * Write `data` to `filePath` atomically (temp file + fsync + rename, same dir).
  * Temp files follow the `<name>.tmp-<pid>-<random>` convention also used by
- * prune.ts / checkpoint.ts so they are recognizable and prunable.
+ * prune.ts / checkpoint.ts so they are recognizable and prunable. The existing
+ * target's mode is preserved across the swap and symlinked targets are
+ * resolved first (see the header).
  * Throws on failure (callers own error reporting — they map failures to
  * structured tool results).
  */
 export function writeTextAtomic(filePath, data) {
-    const tmp = tempPathFor(filePath);
+    const target = resolveAtomicTarget(filePath);
+    const tmp = tempPathFor(target);
+    const mode = existingMode(target);
     try {
-        writeFileSync(tmp, data, 'utf-8');
+        // fd-based write so the mode can be pinned and the CONTENT fsynced before
+        // the rename — a crash after rename but before the data hit the disk would
+        // otherwise leave a zero-length / torn state file.
+        const fd = openSync(tmp, 'w');
+        try {
+            writeSync(fd, data, null, 'utf-8');
+            if (mode !== null)
+                fchmodSync(fd, mode);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
     }
     catch (err) {
         // The write itself failed (disk full, permission, …): the temp file may
@@ -59,19 +175,33 @@ export function writeTextAtomic(filePath, data) {
         throw err;
     }
     try {
-        renameSync(tmp, filePath);
+        renameSync(tmp, target);
     }
     catch (err) {
         // Best-effort temp cleanup so a failed rename never litters the directory.
         cleanupTemp(tmp);
         throw err;
     }
+    fsyncDirBestEffort(dirname(target));
 }
 /** Async variant of {@link writeTextAtomic} (same temp naming convention). */
 export async function writeTextAtomicAsync(filePath, data) {
-    const tmp = tempPathFor(filePath);
+    const target = await resolveAtomicTargetAsync(filePath);
+    const tmp = tempPathFor(target);
+    const mode = await existingModeAsync(target);
     try {
-        await writeFile(tmp, data, 'utf-8');
+        // fd-based write: pin the target's mode and fsync the content before the
+        // rename (mirrors the sync variant — see writeTextAtomic).
+        const fh = await open(tmp, 'w');
+        try {
+            await fh.writeFile(data, 'utf-8');
+            if (mode !== null)
+                await fh.chmod(mode);
+            await fh.sync();
+        }
+        finally {
+            await fh.close();
+        }
     }
     catch (err) {
         // The write itself failed (disk full, permission, …): the temp file may
@@ -81,13 +211,14 @@ export async function writeTextAtomicAsync(filePath, data) {
         throw err;
     }
     try {
-        await rename(tmp, filePath);
+        await rename(tmp, target);
     }
     catch (err) {
         // Best-effort temp cleanup so a failed rename never litters the directory.
         await cleanupTempAsync(tmp);
         throw err;
     }
+    await fsyncDirBestEffortAsync(dirname(target));
 }
 /** JSON.stringify (2-space indent) + atomic write in one call. */
 export function writeJsonAtomic(filePath, value) {