@kontourai/flow-agents 3.2.0 → 3.4.0

package/scripts/install-merge.js

@@ -23,10 +23,13 @@
  *       flow-agents marker (the COLLISION_MARKER strings from init.ts).
  *   (c) APPEND the current managed hook groups from the bundle.
  *   (d) Preserve ALL other keys (permissions, statusLine, user hooks, auth).
+ *       Managed non-hook values are added only when absent or when replacing
+ *       an existing Flow Agents-owned value. Conflicting user-owned values win
+ *       and are reported to stderr.
  *   (e) Atomic write (write tmp + rename).
  *   (f) Write/update .flow-agents/install.json version stamp.
  *
- * Export: mergeSettings(existing, managed) — pure, testable.
+ * Export: mergeSettings(existing, managed, options) — pure, testable.
  * The managed ownership region is identified purely by statusMessage markers
  * (cross-runtime, no top-level key needed in settings.json).
  */
@@ -47,6 +50,33 @@ const FA_MARKERS = [
   "Capturing Flow Agents command evidence",
 ];
 
+const FA_OWNERSHIP_MARKERS = [
+  ...FA_MARKERS,
+  "flow-agents",
+  "Flow Agents",
+];
+
+function stableJson(value) {
+  if (value === undefined) return "undefined";
+  return JSON.stringify(value);
+}
+
+function valuesEqual(a, b) {
+  return stableJson(a) === stableJson(b);
+}
+
+function valueContainsManagedMarker(value) {
+  return FA_OWNERSHIP_MARKERS.some((marker) => stableJson(value).includes(marker));
+}
+
+function conflict(path, existingValue, managedValue) {
+  return { path, existingValue, managedValue };
+}
+
+function emitConflict(onConflict, item) {
+  if (typeof onConflict === "function") onConflict(item);
+}
+
 /**
  * Returns true if a hook-group entry is owned by flow-agents.
  * A hook-group in Claude Code settings looks like:
@@ -95,16 +125,28 @@ function mergeArrayUnion(a, b) {
  * @param {unknown} existingPerms @param {unknown} managedPerms
  * @returns {Record<string, unknown>}
  */
-function mergePermissions(existingPerms, managedPerms) {
+function mergePermissions(existingPerms, managedPerms, options = {}) {
   const e = existingPerms && typeof existingPerms === "object" ? existingPerms : {};
   const m = managedPerms && typeof managedPerms === "object" ? managedPerms : {};
-  const out = Object.assign({}, e, m);
+  const out = Object.assign({}, e);
   for (const listKey of ["allow", "deny", "ask"]) {
     if (Array.isArray(e[listKey]) || Array.isArray(m[listKey])) {
       out[listKey] = mergeArrayUnion(e[listKey], m[listKey]);
     }
   }
-  if (e.defaultMode !== undefined) out.defaultMode = e.defaultMode;
+  for (const [key, value] of Object.entries(m)) {
+    if (["allow", "deny", "ask"].includes(key)) continue;
+    if (!(key in e)) {
+      out[key] = value;
+      continue;
+    }
+    if (valuesEqual(e[key], value) || valueContainsManagedMarker(e[key])) {
+      out[key] = value;
+      continue;
+    }
+    out[key] = e[key];
+    emitConflict(options.onConflict, conflict(`permissions.${key}`, e[key], value));
+  }
   return out;
 }
 
@@ -117,14 +159,17 @@ function mergePermissions(existingPerms, managedPerms) {
  *
  * Returns a new object with:
  *   - All keys from `existing` preserved (permissions, statusLine, auth, etc.)
- *   - All keys from `managed` merged in (flow-agents owned keys like statusLine, hooks)
+ *   - Managed keys added when absent, or updated only when the existing value
+ *     is already Flow Agents-owned.
+ *   - User-owned managed-key conflicts preserved from `existing` and surfaced
+ *     through `options.onConflict`.
  *   - For the `hooks` key: user-owned hook groups (non-FA) survive; FA groups are
  *     replaced with the current managed set from `managed`.
  *
  * Strategy:
  *   1. Start with a shallow copy of `existing` (preserves all user keys).
- *   2. Overlay all scalar/non-hooks keys from `managed` (statusLine, permissions
- *      from the bundle, skipDangerousModePermissionPrompt, etc.).
+ *   2. Add or update Flow Agents-owned non-hooks keys from `managed`; preserve
+ *      user-owned conflicting values and report conflicts.
  *   3. For `hooks`: iterate each event key from both existing and managed;
  *      keep user (non-FA) groups from existing, append the current FA groups
  *      from managed.
@@ -133,19 +178,26 @@ function mergePermissions(existingPerms, managedPerms) {
  * @param {Record<string, unknown>} managed
  * @returns {Record<string, unknown>}
  */
-function mergeSettings(existing, managed) {
+function mergeSettings(existing, managed, options = {}) {
   // 1. Start with all existing keys (preserves user-owned data).
   const result = Object.assign({}, existing);
 
-  // 2. Overlay non-hooks keys from managed. `permissions` is DEEP-merged so the
-  //    user's allow/deny/ask lists + defaultMode survive — flow-agents only adds
-  //    its required entries (#117: never clobber user customizations).
+  // 2. Add non-hooks keys from managed without overwriting user-owned values.
+  //    If a key is absent, add the managed default. If the existing value is
+  //    already Flow Agents-owned (for example the generated statusLine command),
+  //    replace it with the current managed value. Otherwise preserve the user's
+  //    value and surface a conflict so the user can decide.
   for (const [key, value] of Object.entries(managed)) {
     if (key === "hooks") continue;
     if (key === "permissions") {
-      result.permissions = mergePermissions(existing.permissions, value);
-    } else {
+      result.permissions = mergePermissions(existing.permissions, value, options);
+    } else if (!(key in existing)) {
       result[key] = value;
+    } else if (valuesEqual(existing[key], value) || valueContainsManagedMarker(existing[key])) {
+      result[key] = value;
+    } else {
+      result[key] = existing[key];
+      emitConflict(options.onConflict, conflict(key, existing[key], value));
     }
   }
 
@@ -267,7 +319,13 @@ function runMerge({ configPath, managedHooksPath, version, installRecordPath, ru
   }
 
   // (b) + (c) + (d) Merge.
-  const merged = mergeSettings(existing, managed);
+  const conflicts = [];
+  const merged = mergeSettings(existing, managed, { onConflict: (item) => conflicts.push(item) });
+  for (const item of conflicts) {
+    process.stderr.write(
+      `install-merge: conflict: preserving existing setting '${item.path}' and not applying Flow Agents managed value\n`
+    );
+  }
 
   // (e) Atomic write.
   atomicWriteJson(configPath, merged);

package/scripts/install-owned-files.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// Install a prepared Flow Agents overlay without claiming or deleting unrelated files.
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function fail(message) {
+  process.stderr.write(`install-owned-files: ${message}\n`);
+  process.exit(1);
+}
+
+const [sourceArg, destArg, manifestArg] = process.argv.slice(2);
+if (!sourceArg || !destArg || !manifestArg) fail("usage: install-owned-files.js <overlay> <destination> <manifest-relative-path>");
+const source = fs.realpathSync(sourceArg);
+const dest = fs.realpathSync(destArg);
+const manifestPath = path.join(dest, manifestArg);
+
+function hashFile(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+function relativeFiles(root, current = root) {
+  const out = [];
+  for (const name of fs.readdirSync(current).sort()) {
+    const file = path.join(current, name);
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) fail(`refusing symlink in install overlay: ${file}`);
+    if (stat.isDirectory()) out.push(...relativeFiles(root, file));
+    else if (stat.isFile()) out.push(path.relative(root, file).split(path.sep).join("/"));
+    else fail(`unsupported install overlay entry: ${file}`);
+  }
+  return out;
+}
+
+function targetFor(rel) {
+  if (!rel || rel.split("/").some((part) => !part || part === "." || part === "..")) fail(`unsafe relative path: ${rel}`);
+  const target = path.resolve(dest, ...rel.split("/"));
+  const relative = path.relative(dest, target);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) fail(`path escapes destination: ${rel}`);
+  return target;
+}
+
+function ensureSafeParent(target, create) {
+  const relative = path.relative(dest, path.dirname(target));
+  let current = dest;
+  for (const part of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    if (fs.existsSync(current)) {
+      const stat = fs.lstatSync(current);
+      if (stat.isSymbolicLink()) fail(`refusing to write through symlink: ${current}`);
+      if (!stat.isDirectory()) fail(`destination component is not a directory: ${current}`);
+    } else if (create) {
+      fs.mkdirSync(current);
+    }
+  }
+}
+
+function readManifest() {
+  if (!fs.existsSync(manifestPath)) return new Map();
+  ensureSafeParent(manifestPath, false);
+  const stat = fs.lstatSync(manifestPath);
+  if (stat.isSymbolicLink() || !stat.isFile()) fail(`ownership manifest is not a regular file: ${manifestPath}`);
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8")); } catch (error) { fail(`invalid ownership manifest: ${error.message}`); }
+  if (parsed.schema_version !== "1.0" || !Array.isArray(parsed.files)) fail("unsupported ownership manifest; remove it only after manually auditing installed files");
+  return new Map(parsed.files.map((entry) => [String(entry.path), String(entry.sha256)]));
+}
+
+function legacyInstallCutoff() {
+  if (fs.existsSync(manifestPath)) return null;
+  const recordPath = path.join(dest, ".flow-agents", "install.json");
+  const hooksPath = path.join(dest, "hooks.json");
+  for (const file of [recordPath, hooksPath]) {
+    if (!fs.existsSync(file)) return null;
+    ensureSafeParent(file, false);
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) return null;
+  }
+  let record;
+  try { record = JSON.parse(fs.readFileSync(recordPath, "utf8")); } catch { return null; }
+  const installedAt = Date.parse(String(record.installedAt ?? ""));
+  if (record.runtime !== "codex" || !/^\d+\.\d+\.\d+(?:[-+].*)?$/.test(String(record.version ?? "")) || !Number.isFinite(installedAt)) return null;
+  const hooks = fs.readFileSync(hooksPath, "utf8");
+  if (!hooks.includes("Recording Flow Agents telemetry") && !hooks.includes("stop-goal-fit.js")) return null;
+  return installedAt + 2000;
+}
+
+// Exact path classes managed by the pre-manifest installer. These are an
+// auditable historical contract, intentionally narrower than "all incoming
+// files": root config/auth/hooks, kits/local, user-extensible skills/agents,
+// and arbitrary destination files are never bootstrapped from timestamps.
+function wasLegacyManagedPath(rel) {
+  const [top] = rel.split("/");
+  const managedTrees = new Set([
+    ".flow-agents", "agent-cards", "build", "context", "docs", "evals",
+    "integrations", "packaging", "powers", "prompts", "schemas", "scripts",
+  ]);
+  if (managedTrees.has(top)) return rel !== ".flow-agents/install.json";
+  if (top === "kits") return !rel.startsWith("kits/local/");
+  return new Set(["README.md", "console.telemetry.json", "install.sh"]).has(rel);
+}
+
+const previous = readManifest();
+const legacyCutoff = legacyInstallCutoff();
+const incoming = relativeFiles(source).map((rel) => ({ rel, source: path.join(source, ...rel.split("/")), hash: hashFile(path.join(source, ...rel.split("/"))) }));
+
+// Complete preflight before the first destination mutation.
+for (const entry of incoming) {
+  const target = targetFor(entry.rel);
+  ensureSafeParent(target, false);
+  if (!fs.existsSync(target)) continue;
+  const stat = fs.lstatSync(target);
+  if (stat.isSymbolicLink()) fail(`refusing to replace symlink: ${target}`);
+  if (!stat.isFile()) fail(`destination collision is not a regular file: ${target}`);
+  const oldHash = previous.get(entry.rel);
+  const currentHash = hashFile(target);
+  // Migration from the pre-manifest installer: byte-identical bundle files can
+  // be adopted without overwriting them. Any differing unowned file is a hard
+  // collision and remains untouched.
+  if (!oldHash) {
+    if (currentHash !== entry.hash) {
+      const recognizableLegacy = legacyCutoff !== null && wasLegacyManagedPath(entry.rel) && stat.mtimeMs <= legacyCutoff;
+      if (!recognizableLegacy) fail(`refusing to overwrite unowned or ambiguous file: ${target}`);
+    }
+  } else if (currentHash !== oldHash && currentHash !== entry.hash) {
+    fail(`refusing to overwrite modified Flow Agents file: ${target}`);
+  }
+}
+for (const [rel] of previous) {
+  const target = targetFor(rel);
+  ensureSafeParent(target, false);
+  if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) fail(`refusing to remove symlink replacing owned file: ${target}`);
+}
+
+for (const entry of incoming) {
+  const target = targetFor(entry.rel);
+  ensureSafeParent(target, true);
+  const temp = path.join(path.dirname(target), `.${path.basename(target)}.flow-agents-${process.pid}-${crypto.randomBytes(6).toString("hex")}.tmp`);
+  try {
+    fs.copyFileSync(entry.source, temp, fs.constants.COPYFILE_EXCL);
+    fs.chmodSync(temp, fs.statSync(entry.source).mode & 0o777);
+    fs.renameSync(temp, target);
+  } finally {
+    fs.rmSync(temp, { force: true });
+  }
+}
+
+const incomingPaths = new Set(incoming.map((entry) => entry.rel));
+const staleParents = new Set();
+for (const [rel, oldHash] of previous) {
+  if (incomingPaths.has(rel)) continue;
+  const target = targetFor(rel);
+  if (!fs.existsSync(target)) continue;
+  const stat = fs.lstatSync(target);
+  if (!stat.isFile() || hashFile(target) !== oldHash) {
+    process.stderr.write(`install-owned-files: preserving modified former Flow Agents file: ${target}\n`);
+    continue;
+  }
+  fs.rmSync(target);
+  staleParents.add(path.dirname(target));
+}
+for (const start of [...staleParents].sort((a, b) => b.length - a.length)) {
+  let current = start;
+  while (current !== dest) {
+    try { fs.rmdirSync(current); } catch { break; }
+    current = path.dirname(current);
+  }
+}
+
+ensureSafeParent(manifestPath, true);
+if (fs.existsSync(manifestPath) && fs.lstatSync(manifestPath).isSymbolicLink()) fail(`refusing to replace symlink: ${manifestPath}`);
+const manifestTemp = `${manifestPath}.tmp.${process.pid}.${crypto.randomBytes(6).toString("hex")}`;
+try {
+  fs.writeFileSync(manifestTemp, `${JSON.stringify({ schema_version: "1.0", files: incoming.map((entry) => ({ path: entry.rel, sha256: entry.hash })) }, null, 2)}\n`, { flag: "wx" });
+  fs.renameSync(manifestTemp, manifestPath);
+} finally {
+  fs.rmSync(manifestTemp, { force: true });
+}