@synqa/cli 0.0.0-stage → 1.1.1

package/dist/tools.js

@@ -0,0 +1,413 @@
+import { spawnSync } from "node:child_process";
+import { Worker } from "node:worker_threads";
+import { closeSync, mkdirSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { MAX_DIFF_LINES, renderDiff, unifiedDiff } from "./diff.js";
+import { snapshot } from "./journal.js";
+                                                
+import { commandTouchesSecrets, confine, fold, isHomeDir, isSecretStemSource, isSensitivePath, writeConfined } from "./paths.js";
+import { visibleEscapes } from "./sanitize.js";
+                                        
+
+const MAX_FILE_BYTES = 1_000_000;
+const MAX_PATTERN = 200;
+
+// Reads at most MAX_FILE_BYTES of a regular file; stats first so a huge file is never loaded.
+function readCapped(p        )         {
+  const st = statSync(p);
+  if (!st.isFile()) throw new Error("not a regular file");
+  const len = Math.min(st.size, MAX_FILE_BYTES);
+  const buf = Buffer.alloc(len);
+  const fd = openSync(p, "r");
+  try {
+    readSync(fd, buf, 0, len, 0);
+  } finally {
+    closeSync(fd);
+  }
+  const text = buf.toString("utf8");
+  return st.size > MAX_FILE_BYTES ? text + `\n[file truncated at ${MAX_FILE_BYTES} bytes]` : text;
+}
+
+// Environment variables that commonly hold credentials, by name: the API key (SYNQA_*), tokens,
+// secrets, keys and passwords (TOKENIZERS_PARALLELISM, AWS_REGION, AWS_DEFAULT_REGION and
+// AWS_PROFILE stay), connection strings, the cloud, code host and package registry families
+// (NPM_* includes npm_config_*), git credential helpers and the SSH agent. Model provider keys are
+// caught by the KEY and TOKEN rules. Narrowing this list must keep the regression list in
+// test/hardening.test.ts passing.
+const SECRET_ENV = [
+  /^SYNQA_/, /TOKEN(?!IZER)/, /AUTHTOKEN/, /SECRET/, /(^|_)KEYS?(_|$)/, /APIKEY/, /PASSWORD/, /PASSWD/, /(^|_)PASS$/, /_PWD$/,
+  /CREDENTIAL/, /CONNECTION_?STRING/, /(^|_)AUTH$/, /^AUTH_/, /ASKPASS/, /^VSCODE_GIT_/, /^SSH_AUTH_SOCK$/,
+  /^SLACK_WEBHOOK_URL$/, /^SENTRY_DSN$/, /^DATABASE_URL$/,
+  /^AWS_(?!REGION$|DEFAULT_REGION$|PROFILE$)/, /^GH_/, /^GITHUB_/, /^GITLAB_/, /^NPM_/, /^HF_/, /^HUGGING_?FACE/, /^AZURE_/,
+  /^GOOGLE_APPLICATION_CREDENTIALS$/,
+];
+// A URL, URI or DSN value with a user and password in it (postgres://user:pass@host) is a secret;
+// a plain URL is kept.
+const URL_NAME = /(^|_)(URL|URI|DSN)$/;
+const USERINFO = /^[a-z][a-z0-9+.-]*:\/\/[^/\s@:]*:[^/\s@]*@/i;
+
+// Child processes get the parent environment minus every variable that looks like a credential.
+// SSH_AUTH_SOCK is one of them, so git over SSH that needs the agent runs in the user's own terminal.
+export function bashEnv(env                                    )                         {
+  const out                         = {};
+  for (const [k, v] of Object.entries(env)) {
+    const up = k.toUpperCase();
+    if (v === undefined || SECRET_ENV.some((re) => re.test(up))) continue;
+    if (URL_NAME.test(up) && USERINFO.test(v.trim())) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+// `detail` is text this module built (a coloured diff); the caller prints it as is, while the
+// question is model-influenced and must be sanitized by the caller.
+                                                                              
+                           
+              
+                   
+               
+                                             
+                                                                                 
+                                                    
+                                                                                     
+                                                                            
+                                                                      
+                                                                                                            
+  
+
+const MAX_OUT = 20_000;
+const MAX_RESULTS = 500;
+const SKIP_DIRS = new Set([".git", "node_modules", ".ssh", ".aws", ".gnupg", ".kube", ".trash"]);
+
+export const TOOL_DEFS = [
+  def("read_file", "Read a text file inside the working directory.", {
+    path: { type: "string", description: "File path relative to the working directory" },
+  }, ["path"]),
+  def("write_file", "Create or overwrite a file (asks the user first).", {
+    path: { type: "string" },
+    content: { type: "string" },
+  }, ["path", "content"]),
+  def("edit_file", "Replace one exact occurrence of old_string with new_string (asks the user first).", {
+    path: { type: "string" },
+    old_string: { type: "string" },
+    new_string: { type: "string" },
+  }, ["path", "old_string", "new_string"]),
+  def("glob", "List files matching a glob pattern such as src/**/*.ts.", {
+    pattern: { type: "string" },
+  }, ["pattern"]),
+  def("grep", "Search file contents with a regular expression.", {
+    pattern: { type: "string" },
+    path: { type: "string", description: "Optional directory or file to search" },
+  }, ["pattern"]),
+  def("bash", "Run a shell command in the working directory (asks the user first).", {
+    command: { type: "string" },
+  }, ["command"]),
+];
+
+function def(name        , description        , properties                         , required          ) {
+  return { type: "function", function: { name, description, parameters: { type: "object", properties, required } } };
+}
+
+function truncate(s        )         {
+  return s.length > MAX_OUT ? s.slice(0, MAX_OUT) + `\n[truncated ${s.length - MAX_OUT} chars]` : s;
+}
+
+export function globToRegExp(pattern        )         {
+  let re = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i]          ;
+    if (c === "*") {
+      if (pattern[i + 1] === "*") {
+        i++;
+        if (pattern[i + 1] === "/") {
+          i++;
+          re += "(?:.*/)?";
+        } else re += ".*";
+      } else re += "[^/]*";
+    } else if (c === "?") re += "[^/]";
+    else if (c === "{") {
+      const end = pattern.indexOf("}", i);
+      if (end > i) {
+        re += "(?:" + pattern.slice(i + 1, end).split(",").map(escapeRe).join("|") + ")";
+        i = end;
+      } else re += "\\{";
+    } else re += escapeRe(c);
+  }
+  return new RegExp("^" + re + "$");
+}
+
+function escapeRe(s        )         {
+  return s.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+}
+
+function walk(root        , dir        , out          , secret                        )       {
+  if (out.length >= MAX_RESULTS * 20) return;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (SKIP_DIRS.has(fold(e.name))) continue;
+    const full = join(dir, e.name);
+    // A folder of credentials or a browser profile is never walked into (it can be huge, too).
+    if (e.isDirectory()) { if (!secret(full)) walk(root, full, out, secret); }
+    else if (e.isFile()) out.push(relative(root, full).split(sep).join("/"));
+  }
+}
+
+const RC_FILES = new Set([".bashrc", ".zshrc", ".profile", ".bash_profile", ".zprofile", ".zshenv", ".bash_login", ".zlogin", ".zlogout", ".bash_logout", ".kshrc", ".cshrc", ".tcshrc", ".login", "config.fish"]);
+
+// Why an approved write to this target can run code later (hooks, build files, shell startup files,
+// CI, editor tasks, executables). Compared folded, so ".GIT/hooks" counts as ".git/hooks".
+export function riskReasons(root        , abs        )           {
+  const rel = fold(relative(root, abs).split(sep).join("/"));
+  const parts = rel.split("/");
+  const base = parts[parts.length - 1] ?? "";
+  const dirs = parts.slice(0, -1);
+  const reasons           = [];
+  const full = "/" + fold(abs.split(sep).join("/")).replace(/^\/+/, "");
+  if (rel === ".." || rel.startsWith("../") || isAbsolute(rel)) reasons.push("outside the workspace");
+  if (/\/library\/(launchagents|launchdaemons)\//.test(full)) reasons.push("a launchd job (runs at login or boot)");
+  if (full.includes("/.config/autostart/")) reasons.push("an autostart entry (runs at login)");
+  if (/\/(\.config|\.local\/share)\/systemd\//.test(full)) reasons.push("a systemd unit (runs as a service)");
+  if (full.includes("/.config/fish/")) reasons.push("a fish startup file (runs in every new shell)");
+  if (full.includes("/.local/bin/")) reasons.push("a program on your PATH");
+  if (rel.startsWith(".git/hooks/") || rel.includes("/.git/hooks/")) reasons.push("a git hook (runs on git actions)");
+  else if (dirs.includes(".git")) reasons.push("inside .git");
+  if (base === "package.json") reasons.push("package.json (scripts can run on install or test)");
+  if (base === "makefile" || base === "gnumakefile") reasons.push("a Makefile (make runs it)");
+  if (base === ".envrc") reasons.push(".envrc (direnv runs it when you enter the folder)");
+  if (dirs.includes(".vscode") && base.endsWith(".json")) reasons.push("VS Code settings (can define tasks that run)");
+  if (rel.startsWith(".github/workflows/") || rel.includes("/.github/workflows/")) reasons.push("a CI workflow");
+  if (dirs.includes(".devcontainer") && base.endsWith(".json")) reasons.push("a dev container config (runs commands when the container is built)");
+  if (base === "conftest.py") reasons.push("conftest.py (pytest runs it)");
+  if (base === "setup.py") reasons.push("setup.py (runs on install)");
+  if (base === "pyproject.toml") reasons.push("pyproject.toml (build backends and scripts run from it)");
+  if (dirs.includes(".cargo") && base.startsWith("config")) reasons.push("a Cargo config (can set the compiler or a runner)");
+  if (base === "build.rs") reasons.push("build.rs (cargo runs it)");
+  if (base === "justfile" || base === ".justfile") reasons.push("a justfile (just runs it)");
+  if (base === "rakefile" || base === "rakefile.rb") reasons.push("a Rakefile (rake runs it)");
+  if (dirs.includes(".husky")) reasons.push("a husky hook (runs on git actions)");
+  if (RC_FILES.has(base)) reasons.push("a shell startup file (runs in every new shell)");
+  else if (base.startsWith(".")) reasons.push("a dotfile");
+  try {
+    const st = statSync(abs);
+    if (st.isFile() && (st.mode & 0o111) !== 0) reasons.push("an executable file");
+  } catch {
+    // The file does not exist yet: nothing to check.
+  }
+  return reasons;
+}
+
+export function riskNote(root        , abs        )         {
+  const reasons = riskReasons(root, abs);
+  return reasons.length ? `\n  WARNING: this is ${reasons.join(", ")}; an approved write can run code later.` : "";
+}
+
+const NESTED_QUANTIFIER = /\((?:[^()\\]|\\.)*[+*}](?:[^()\\]|\\.)*\)[+*{]/;
+
+// Heuristic ReDoS guard: refuse a quantified group that itself contains a quantifier, e.g. (a+)+.
+// It does not catch every pathological pattern (see SPEC); lines are also cut to 2000 characters.
+export function hasNestedQuantifier(pattern        )          {
+  return NESTED_QUANTIFIER.test(pattern);
+}
+
+// A file that holds secrets (see isSensitivePath) is never opened, written or edited by a tool:
+// not with --yes, not with a yes to a question. The answer names no content, so it is not an
+// oracle either. The person can open the file themselves; the model never gets its text.
+export const SECRET_REFUSAL = "error: refused: this file may hold secrets (keys, tokens or credentials), so Synqa never reads, writes or edits it. Open it yourself if you need to.";
+
+const secretIn = (ctx             ) => (p        ) => isSensitivePath(p, undefined, ctx.home);
+
+function sensitiveGate(ctx             , p        )                     {
+  return secretIn(ctx)(p) ? SECRET_REFUSAL : undefined;
+}
+
+// grep and glob also skip source files named like a secret store (secrets.py): see isSecretStemSource.
+const skipIn = (ctx             ) => (p        ) => secretIn(ctx)(p) || isSecretStemSource(p);
+
+// secrets.py, credentials.js and the like are opened only after an explicit yes, --yes or not;
+// with nobody to ask the answer is no.
+async function stemGate(ctx             , p        , verb        )                              {
+  if (!isSecretStemSource(p)) return undefined;
+  const ok = await ctx.confirm(`${verb} ${visibleEscapes(p)}? Its name says it may hold secrets, and its text would be sent to the model.`);
+  return ok ? undefined : "denied by user";
+}
+
+async function toolRead(ctx             , a                         )                  {
+  const p = confine(ctx.cwd, str(a, "path"));
+  const refused = sensitiveGate(ctx, p) ?? (await stemGate(ctx, p, "Read"));
+  if (refused) return refused;
+  return truncate(readCapped(p));
+}
+
+                                          
+
+// Shows the change (the question gets the diff as `detail`; with --yes the diff is only shown).
+async function approve(ctx             , question        , path        , before        , after        )                   {
+  const rel = relative(ctx.cwd, path) || path;
+  // A file that can run code later (hook, package.json, shell startup file, dotfile) is shown in
+  // full: a payload on line 60 must not hide behind a cut.
+  // A write to a secrets-named source file (secrets.py) asks too, like reading it does.
+  const risky = riskReasons(ctx.cwd, path).length > 0 || isSecretStemSource(path);
+  const diff = (maxLines        ) => before === "too-large"
+    ? "  (the existing file is too large to preview)"
+    : renderDiff(unifiedDiff(rel, before === null ? null : before.toString("utf8"), after), ctx.style ?? { color: ctx.color ?? false, depth: 8 }, maxLines);
+  // --yes skips the question only for an ordinary file with no AGENTS.md loaded. A write that can
+  // run code later, a secrets file, or any write while repository text steers the model always asks
+  // (and is denied when nobody can answer): a shell prompt is no boundary if another tool can plant
+  // a hook, a Makefile or a workflow that runs without one.
+  if (ctx.yes && !risky && !ctx.notesLoaded) {
+    // Already approved by --yes: the shown diff may be cut for length.
+    ctx.show?.(diff(MAX_DIFF_LINES));
+    return true;
+  }
+  // A question always shows the whole change: nothing can hide below a cut while you decide.
+  return ctx.confirm(question, diff(Infinity));
+}
+
+function journalWrite(ctx             , written        , before        , after        )         {
+  if (before === "too-large") return " (not undoable: the old file was too large to keep)";
+  ctx.journal?.record({ path: written, before, after: Buffer.from(after) });
+  return "";
+}
+
+async function toolWrite(ctx             , a                         )                  {
+  const p = confine(ctx.cwd, str(a, "path"));
+  const content = str(a, "content");
+  const refused = sensitiveGate(ctx, p);
+  if (refused) return refused;
+  const before = snapshot(p);
+  const q = `Write ${content.length} chars to ${visibleEscapes(p)}?${riskNote(ctx.cwd, p)}`;
+  if (!(await approve(ctx, q, p, before, content))) return "denied by user";
+  mkdirSync(dirname(confine(ctx.cwd, p)), { recursive: true });
+  const written = writeConfined(ctx.cwd, p, content);
+  return `wrote ${relative(ctx.cwd, written)}${journalWrite(ctx, written, before, content)}`;
+}
+
+async function toolEdit(ctx             , a                         )                  {
+  const p = confine(ctx.cwd, str(a, "path"));
+  const oldS = str(a, "old_string");
+  const newS = str(a, "new_string");
+  const refused = sensitiveGate(ctx, p) ?? (await stemGate(ctx, p, "Edit"));
+  if (refused) return refused;
+  const text = readCapped(p);
+  if (text.endsWith(`[file truncated at ${MAX_FILE_BYTES} bytes]`)) return "error: file too large to edit";
+  if (oldS === "") return "error: old_string is empty";
+  const first = text.indexOf(oldS);
+  if (first < 0) return "error: old_string not found";
+  if (text.indexOf(oldS, first + oldS.length) >= 0) return "error: old_string matches more than once; add context";
+  const next = text.slice(0, first) + newS + text.slice(first + oldS.length);
+  const before = snapshot(p);
+  const q = `Edit ${visibleEscapes(p)}?${riskNote(ctx.cwd, p)}`;
+  if (!(await approve(ctx, q, p, before, next))) return "denied by user";
+  const written = writeConfined(ctx.cwd, p, next);
+  return `edited ${relative(ctx.cwd, p)}${journalWrite(ctx, written, before, next)}`;
+}
+
+function toolGlob(ctx             , a                         )         {
+  const re = globToRegExp(str(a, "pattern"));
+  const all           = [];
+  walk(ctx.cwd, ctx.cwd, all, secretIn(ctx));
+  const hits = all.filter((f) => re.test(f) && !skipIn(ctx)(join(ctx.cwd, f))).sort().slice(0, MAX_RESULTS);
+  return hits.length ? hits.join("\n") : "no matches";
+}
+
+// The matching loop runs in a worker thread, so a pattern that backtracks badly ((a|a)*$ and the
+// like, which no static check catches) is stopped after GREP_BUDGET_MS instead of hanging the session.
+const GREP_BUDGET_MS = 10_000;
+const GREP_WORKER = `
+const { parentPort, workerData } = require("node:worker_threads");
+const re = new RegExp(workerData.pattern);
+const out = [];
+for (const f of workerData.files) {
+  if (out.length >= workerData.max) break;
+  f.text.split("\\n").forEach((line, i) => {
+    if (out.length < workerData.max && re.test(line.slice(0, 2000))) out.push(f.rel + ":" + (i + 1) + ":" + line.slice(0, 300));
+  });
+}
+parentPort.postMessage(out);
+`;
+
+function grepInWorker(pattern        , files                                      , budgetMs        )                                {
+  return new Promise((resolve, reject) => {
+    const w = new Worker(GREP_WORKER, { eval: true, workerData: { pattern, files, max: MAX_RESULTS } });
+    const timer = setTimeout(() => { void w.terminate(); resolve("timeout"); }, budgetMs);
+    w.once("message", (m          ) => { clearTimeout(timer); void w.terminate(); resolve(m); });
+    w.once("error", (e) => { clearTimeout(timer); reject(e); });
+  });
+}
+
+async function toolGrep(ctx             , a                         )                  {
+  const pat = str(a, "pattern");
+  if (pat.length > MAX_PATTERN) return `error: pattern longer than ${MAX_PATTERN} characters`;
+  if (hasNestedQuantifier(pat)) return "error: pattern has a quantified group containing a quantifier (nested quantifier); rewrite it";
+  new RegExp(pat); // a syntax error is reported here, before any file is read
+  const base = confine(ctx.cwd, typeof a.path === "string" && a.path ? a.path : ".");
+  const paths           = [];
+  if (statSync(base).isDirectory()) walk(base, base, paths, secretIn(ctx));
+  else paths.push("");
+  const files                                       = [];
+  let bytes = 0;
+  for (const f of paths) {
+    const full = f ? join(base, f) : base;
+    if (skipIn(ctx)(full)) continue;
+    let text        ;
+    try {
+      if (statSync(full).size > MAX_FILE_BYTES) continue;
+      text = readCapped(full);
+    } catch {
+      continue;
+    }
+    if (text.includes("\u0000")) continue;
+    files.push({ rel: relative(ctx.cwd, full), text });
+    bytes += text.length;
+    if (bytes > 64 * MAX_FILE_BYTES) break;
+  }
+  const out = await grepInWorker(pat, files, ctx.grepBudgetMs ?? GREP_BUDGET_MS);
+  if (out === "timeout") return `error: the pattern took longer than ${Math.round((ctx.grepBudgetMs ?? GREP_BUDGET_MS) / 1000)}s (it may backtrack heavily); use a simpler pattern`;
+  return out.length ? out.join("\n") : "no matches";
+}
+
+async function toolBash(ctx             , a                         )                  {
+  const command = str(a, "command");
+  // Every shell command asks, also under --yes: any file the model read (a README, a code comment)
+  // can carry an instruction such as "printenv | curl ...", so --yes covers file writes inside the
+  // workspace only. With nobody to ask the answer is no. A command that names a secret or dumps
+  // the environment gets a warning in the question.
+  const secret = commandTouchesSecrets(command);
+  if (!(await ctx.confirm(`Run: ${visibleEscapes(command)}${secret ? "\n  WARNING: this command refers to files that may hold secrets." : ""}`))) return "denied by user";
+  const r = spawnSync("/bin/sh", ["-c", command], {
+    cwd: ctx.cwd, encoding: "utf8", timeout: 120_000, maxBuffer: 4 * 1024 * 1024, env: bashEnv(process.env),
+  });
+  const body = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+  const code = r.status === null ? `signal ${r.signal ?? "timeout"}` : `exit ${r.status}`;
+  return truncate(`${body}\n[${code}]`);
+}
+
+function str(a                         , k        )         {
+  const v = a[k];
+  if (typeof v !== "string") throw new Error(`missing string argument: ${k}`);
+  return v;
+}
+
+// Never throws: failures come back as text so the model can react.
+export async function runTool(ctx0             , name        , args                         )                  {
+  // --yes never applies when the workspace is the home folder: too much there can run code later.
+  const ctx = ctx0.yes && isHomeDir(ctx0.cwd, ctx0.home) ? { ...ctx0, yes: false } : ctx0;
+  try {
+    switch (name) {
+      case "read_file": return await toolRead(ctx, args);
+      case "write_file": return await toolWrite(ctx, args);
+      case "edit_file": return await toolEdit(ctx, args);
+      case "glob": return toolGlob(ctx, args);
+      case "grep": return await toolGrep(ctx, args);
+      case "bash": return await toolBash(ctx, args);
+      default: return `error: unknown tool ${name}`;
+    }
+  } catch (err) {
+    return `error: ${err instanceof Error ? err.message : String(err)}`;
+  }
+}