vexp-cli 3.2.5 → 3.3.0

package/dist/agent-consent.js

@@ -0,0 +1,244 @@
+import * as fs from "fs";
+import * as path from "path";
+import { TextDecoder } from "util";
+import { vexpHome } from "./state-home.js";
+import { canonicalWorkspaceRoot } from "./socket-path.js";
+export function agentConsentPath() {
+    return path.join(vexpHome(), ".vexp", "agent-consent.json");
+}
+/** The key a workspace's answers live under (see the header). */
+export function consentKey(root, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    if (platform !== "win32")
+        return path.resolve(root);
+    let canonical = root;
+    if (opts.realpath) {
+        try {
+            canonical = opts.realpath(root);
+        }
+        catch {
+            /* not resolvable: the spelling given, as canonicalWorkspaceRoot does */
+        }
+    }
+    else {
+        canonical = canonicalWorkspaceRoot(root);
+    }
+    return canonical.toLowerCase();
+}
+function isPlainObject(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+/** Anything that is not the schema reads as "no answers yet". */
+function normalize(raw) {
+    const obj = isPlainObject(raw) ? { ...raw } : {};
+    const workspaces = {};
+    const ws = obj.workspaces;
+    if (isPlainObject(ws)) {
+        for (const [key, agents] of Object.entries(ws)) {
+            if (!isPlainObject(agents))
+                continue;
+            const kept = {};
+            for (const [agent, decision] of Object.entries(agents)) {
+                if (typeof decision === "string")
+                    kept[agent] = decision;
+            }
+            workspaces[key] = kept;
+        }
+    }
+    const never = Array.isArray(obj.never)
+        ? obj.never.filter((a) => typeof a === "string")
+        : [];
+    return { ...obj, version: typeof obj.version === "number" ? obj.version : 1, workspaces, never };
+}
+/**
+ * The file's bytes as text, by the rules of the engine's decode_config_bytes
+ * (vexp-core config.rs): a UTF-8 BOM is dropped, a UTF-16 LE or BE BOM
+ * decodes the rest as UTF-16, anything else must be UTF-8. The same hands
+ * that edit vexp.toml edit this file, and Windows PowerShell 5.1's `>` and
+ * Out-File write UTF-16LE with a BOM (field report, 2026-09-24: the
+ * customer's vexp.toml). Read as UTF-8, such a file was "no answers", and
+ * the next answer overwrote every one saved in it (review, 2026-09-24).
+ * Throws with the problem, worded as the engine words it.
+ */
+export function decodeConsentBytes(bytes) {
+    const utf8 = (b, problem) => {
+        try {
+            return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(b);
+        }
+        catch {
+            throw new Error(problem);
+        }
+    };
+    const utf16 = (rest, littleEndian) => {
+        if (rest.length % 2 !== 0)
+            throw new Error("is UTF-16 with a truncated last character");
+        const le = Buffer.from(rest);
+        if (!littleEndian)
+            le.swap16();
+        const text = le.toString("utf16le");
+        // The engine's String::from_utf16 refuses an unpaired surrogate.
+        if (/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?:^|[^\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(text)) {
+            throw new Error("is not valid UTF-16 text");
+        }
+        return text;
+    };
+    if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)
+        return utf8(bytes.subarray(3), "is not valid UTF-8");
+    if (bytes[0] === 0xff && bytes[1] === 0xfe)
+        return utf16(bytes.subarray(2), true);
+    if (bytes[0] === 0xfe && bytes[1] === 0xff)
+        return utf16(bytes.subarray(2), false);
+    return utf8(bytes, "is not UTF-8 text");
+}
+export function loadAgentConsentFile(file = agentConsentPath()) {
+    let bytes;
+    try {
+        bytes = fs.readFileSync(file);
+    }
+    catch (e) {
+        const code = e.code;
+        // ENOTDIR: a file where the .vexp folder belongs. Nothing is saved
+        // there, and nothing can be.
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { state: "absent" };
+        return { state: "unreadable", problem: code ?? String(e) };
+    }
+    let text;
+    try {
+        text = decodeConsentBytes(bytes);
+    }
+    catch (e) {
+        return { state: "corrupt", problem: e.message };
+    }
+    // Empty: nothing to lose, nothing to keep aside.
+    if (text.trim() === "")
+        return { state: "answers", raw: {} };
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return { state: "corrupt", problem: "is not valid JSON" };
+    }
+    if (!isPlainObject(raw))
+        return { state: "corrupt", problem: "is not a JSON object" };
+    if (raw.workspaces !== undefined && !isPlainObject(raw.workspaces)) {
+        return { state: "corrupt", problem: 'has a "workspaces" that is not an object' };
+    }
+    if (raw.never !== undefined && !Array.isArray(raw.never)) {
+        return { state: "corrupt", problem: 'has a "never" that is not a list' };
+    }
+    return { state: "answers", raw };
+}
+/** The answers on this machine. A missing or unusable file is "none yet"; never throws. */
+export function readAgentConsent() {
+    try {
+        const found = loadAgentConsentFile();
+        return normalize(found.state === "answers" ? found.raw : undefined);
+    }
+    catch {
+        return normalize(undefined);
+    }
+}
+/** The answer for `agent` under an already computed key (see consentKey). */
+export function decisionForKey(consent, key, agent) {
+    const here = consent.workspaces[key]?.[agent];
+    // A "yes" given for this project outranks a "never" given elsewhere: both
+    // are explicit, and this one is the more specific.
+    if (here === "yes")
+        return "yes";
+    if (consent.never.includes(agent))
+        return "never";
+    if (here === "no")
+        return "no";
+    return undefined;
+}
+export function decisionFor(consent, root, agent, opts) {
+    return decisionForKey(consent, consentKey(root, opts), agent);
+}
+/** Temp file + rename, so a reader never sees half a file. */
+function writeAtomic(file, content) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        fs.writeFileSync(tmp, content, "utf-8");
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // A Windows rename refused because another process holds the target.
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            /* ignore */
+        }
+        fs.writeFileSync(file, content, "utf-8");
+    }
+}
+/** Rename a corrupt answers file out of the way; returns where it went. Throws when it cannot. */
+function keepAside(file) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    let aside = `${file}.corrupt-${stamp}`;
+    for (let n = 1; fs.existsSync(aside); n++)
+        aside = `${file}.corrupt-${stamp}-${n}`;
+    fs.renameSync(file, aside);
+    return aside;
+}
+/**
+ * Remember an answer. "never" applies to every project on this machine and
+ * clears this project's own answer for the agent. Never throws: an answer
+ * that cannot be saved is asked again next time, which is the lesser harm.
+ *
+ * Never writes over answers it cannot read. A file that cannot be read now
+ * is left alone and this answer is not saved; a corrupt one is renamed to
+ * agent-consent.json.corrupt-<time> first, so what it held can still be
+ * recovered. Everything else in the file, including entries this version
+ * does not understand, is written back as found.
+ */
+export function recordAgentConsent(root, agent, decision, opts) {
+    try {
+        const file = agentConsentPath();
+        const found = loadAgentConsentFile(file);
+        if (found.state === "unreadable") {
+            console.warn(`[vexp] ${file} could not be read (${found.problem}): the answer for ${agent} is not saved and will be asked again`);
+            return;
+        }
+        let raw = {};
+        if (found.state === "answers") {
+            raw = found.raw;
+        }
+        else if (found.state === "corrupt") {
+            let aside;
+            try {
+                aside = keepAside(file);
+            }
+            catch (e) {
+                console.warn(`[vexp] ${file} ${found.problem} and could not be moved aside (${e.message}): the answer for ${agent} is not saved and will be asked again`);
+                return;
+            }
+            console.warn(`[vexp] ${file} ${found.problem}: kept as ${path.basename(aside)} next to it, and a new file started`);
+        }
+        const key = consentKey(root, opts);
+        const workspaces = isPlainObject(raw.workspaces) ? { ...raw.workspaces } : {};
+        const current = workspaces[key];
+        const here = isPlainObject(current) ? { ...current } : {};
+        const never = Array.isArray(raw.never) ? [...raw.never] : [];
+        if (decision === "never") {
+            if (!never.includes(agent))
+                never.push(agent);
+            delete here[agent];
+        }
+        else {
+            here[agent] = decision;
+        }
+        if (Object.keys(here).length > 0)
+            workspaces[key] = here;
+        else
+            delete workspaces[key];
+        const out = { ...raw, version: typeof raw.version === "number" ? raw.version : 1, workspaces, never };
+        writeAtomic(file, JSON.stringify(out, null, 2) + "\n");
+    }
+    catch {
+        /* see above */
+    }
+}