@synqa/cli 0.0.0-stage → 1.1.0

package/dist/theme.js

@@ -0,0 +1,106 @@
+// The Synqa palette and every colour escape the CLI emits. This file is the only place that builds
+// an escape sequence for colour; text from the model or from tools never reaches it as a code.
+// 24-bit colour when the terminal says it has it (COLORTERM=truecolor|24bit), otherwise the nearest
+// xterm-256 index. NO_COLOR, a non-TTY or TERM=dumb turn all of it off.
+
+                                                    
+
+export const TERRACOTTA      = [0xc8, 0x5a, 0x32]; // #c85a32 accent: the period, spinner, prompt, monogram
+export const BONE      = [0xf0, 0xea, 0xd8]; // #f0ead8 warm bone: name and active values
+export const STONE      = [0x9e, 0x95, 0x85]; // #9e9585 warm stone: borders, labels, footer
+export const SAGE      = [0x4a, 0x7c, 0x59]; // #4a7c59 sage: balance highlights and added diff lines
+
+                                
+
+// depth is optional so a bare { color: true } keeps meaning 24-bit.
+                                                           
+
+export function colorEnabled(env                                    , isTTY         )          {
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== "") return false;
+  if (env.TERM === "dumb") return false;
+  return isTTY;
+}
+
+export function colorDepth(env                                    )             {
+  const c = (env.COLORTERM ?? "").toLowerCase();
+  return c === "truecolor" || c === "24bit" ? 24 : 8;
+}
+
+const CUBE = [0, 95, 135, 175, 215, 255]         ;
+
+// Nearest xterm-256 colour: the best of the 6x6x6 cube (16..231) and the grey ramp (232..255).
+export function rgbTo256(rgb     )         {
+  const [r, g, b] = rgb;
+  const nearest = (v        ) => {
+    let best = 0;
+    for (let i = 1; i < CUBE.length; i++) {
+      if (Math.abs((CUBE[i]          ) - v) < Math.abs((CUBE[best]          ) - v)) best = i;
+    }
+    return best;
+  };
+  const ri = nearest(r);
+  const gi = nearest(g);
+  const bi = nearest(b);
+  const cubeIdx = 16 + 36 * ri + 6 * gi + bi;
+  const dist = (x     ) => (x[0] - r) ** 2 + (x[1] - g) ** 2 + (x[2] - b) ** 2;
+  const cubeDist = dist([CUBE[ri]          , CUBE[gi]          , CUBE[bi]          ]);
+  const grey = Math.min(23, Math.max(0, Math.round(((r + g + b) / 3 - 8) / 10)));
+  const level = 8 + 10 * grey;
+  const greyDist = dist([level, level, level]);
+  return greyDist < cubeDist ? 232 + grey : cubeIdx;
+}
+
+const RESET = "\x1b[0m";
+
+// The SGR parameters that select `rgb` as the foreground.
+export function fgParams(depth                        , rgb     )         {
+  return depth === 8 ? `38;5;${rgbTo256(rgb)}` : `38;2;${rgb[0]};${rgb[1]};${rgb[2]}`;
+}
+
+function paint(s       , params        , text        )         {
+  return s.color ? `\x1b[${params}m${text}${RESET}` : text;
+}
+
+export function terracotta(s       , text        )         {
+  return paint(s, fgParams(s.depth, TERRACOTTA), text);
+}
+
+export function boneBold(s       , text        )         {
+  return paint(s, `1;${fgParams(s.depth, BONE)}`, text);
+}
+
+export function stone(s       , text        )         {
+  return paint(s, fgParams(s.depth, STONE), text);
+}
+
+// Stone and bold together: labels stay readable on a light terminal background.
+export function stoneBold(s       , text        )         {
+  return paint(s, `1;${fgParams(s.depth, STONE)}`, text);
+}
+
+export function sage(s       , text        )         {
+  return paint(s, fgParams(s.depth, SAGE), text);
+}
+
+// Kept names: the accent is terracotta.
+export const accent = terracotta;
+
+export function dim(s       , text        )         {
+  return paint(s, "2", text);
+}
+
+export function bold(s       , text        )         {
+  return paint(s, "1", text);
+}
+
+export function green(s       , text        )         {
+  return paint(s, "32", text);
+}
+
+export function red(s       , text        )         {
+  return paint(s, "31", text);
+}
+
+export function cyan(s       , text        )         {
+  return paint(s, "36", text);
+}

package/dist/tiers.js

@@ -0,0 +1,53 @@
+                                                                
+
+export const TIERS                  = [
+  { key: "blink", id: "synqa-blink-5.5", display: "Blink 5.5" },
+  { key: "sonata", id: "synqa-sonata-6.0", display: "Sonata 6.0" },
+  { key: "aeon", id: "synqa-aeon-6.5", display: "Aeon 6.5" },
+];
+
+export const DEFAULT_TIER = "blink";
+
+// Reasoning effort the user can pick. "default" sends no reasoning_effort at all.
+export const EFFORTS = ["default", "low", "medium"]         ;
+                                              
+
+export function findEffort(name        )                     {
+  const n = name.trim().toLowerCase();
+  return EFFORTS.find((e) => e === n);
+}
+export const CONTEXT_TOKENS = 262144;
+export const MAX_OUTPUT_TOKENS = 16384;
+export const REQUEST_TIMEOUT_MS = 600_000;
+
+export function findTier(name        )                   {
+  const n = name.trim().toLowerCase();
+  return TIERS.find((t) => t.key === n || t.id === n);
+}
+
+// Map the x-synqa-routing header to what the status bar shows.
+// local and local-gated -> local, hybrid -> hybrid, fallback-* -> fallback, absent -> "?".
+export function routingLabel(header                           )         {
+  if (!header) return "?";
+  const v = header.trim().toLowerCase();
+  if (v === "local" || v === "local-gated") return "local";
+  if (v === "hybrid") return "hybrid";
+  if (v.startsWith("fallback")) return "fallback";
+  return "?";
+}
+
+                                                           
+
+export function usageFrom(raw         )                    {
+  if (!raw || typeof raw !== "object") return undefined;
+  const r = raw                           ;
+  const p = r.prompt_tokens;
+  const c = r.completion_tokens;
+  if (typeof p !== "number" && typeof c !== "number") return undefined;
+  return { prompt: typeof p === "number" ? p : 0, completion: typeof c === "number" ? c : 0 };
+}
+
+export function statusLine(tier      , routing        , usage       , total       )         {
+  const ctx = usage.prompt > 0 ? ` | ctx ${usage.prompt}/${CONTEXT_TOKENS}` : "";
+  return `${tier.display} | ${routing} | tokens ${total.prompt} in ${total.completion} out${ctx}`;
+}

package/dist/tools.js

@@ -0,0 +1,332 @@
+import { spawnSync } from "node:child_process";
+import { closeSync, mkdirSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { MAX_DIFF_LINES, renderDiff, unifiedDiff } from "./diff.js";
+import { snapshot } from "./journal.js";
+                                                
+import { commandTouchesSecrets, confine, fold, 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;
+}
+
+// Child processes get the parent environment minus every SYNQA_* variable (the API key).
+export function bashEnv(env                                    )                         {
+  const out                         = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (v !== undefined && !k.toUpperCase().startsWith("SYNQA_")) 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"]);
+
+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          )       {
+  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);
+    if (e.isDirectory()) walk(root, full, out);
+    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"]);
+
+// 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           = [];
+  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 is opened only after an explicit yes. With --yes, or with nobody to ask,
+// the answer is no: a prompt injection must not be able to read keys by running unattended. Every
+// tool that reads a file's bytes (read_file, edit_file) goes through this before opening it.
+async function sensitiveGate(ctx             , p        , verb        )                              {
+  if (!isSensitivePath(p)) return undefined;
+  if (ctx.yes) return "error: refused: this file may hold secrets and --yes never opens those";
+  if (!(await ctx.confirm(`${verb} ${visibleEscapes(p)}? It may hold secrets, and its text would be sent to the model.`))) return "denied by user";
+  return undefined;
+}
+
+async function toolRead(ctx             , a                         )                  {
+  const p = confine(ctx.cwd, str(a, "path"));
+  const refused = await sensitiveGate(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.
+  const risky = riskReasons(ctx.cwd, path).length > 0 || isSensitivePath(path);
+  const maxLines = risky ? Infinity : MAX_DIFF_LINES;
+  const detail = before === "too-large"
+    ? "  (the existing file is too large to preview)"
+    : renderDiff(unifiedDiff(rel, before === null ? null : before.toString("utf8"), after), { color: ctx.color ?? false }, 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) {
+    ctx.show?.(detail);
+    return true;
+  }
+  return ctx.confirm(question, detail);
+}
+
+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 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 = await sensitiveGate(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);
+  const hits = all.filter((f) => re.test(f) && !isSensitivePath(join(ctx.cwd, f))).sort().slice(0, MAX_RESULTS);
+  return hits.length ? hits.join("\n") : "no matches";
+}
+
+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";
+  const re = new RegExp(pat);
+  const base = confine(ctx.cwd, typeof a.path === "string" && a.path ? a.path : ".");
+  const files           = [];
+  if (statSync(base).isDirectory()) walk(base, base, files);
+  else files.push("");
+  const out           = [];
+  for (const f of files) {
+    if (out.length >= MAX_RESULTS) break;
+    const full = f ? join(base, f) : base;
+    if (isSensitivePath(full)) continue;
+    let text        ;
+    try {
+      if (statSync(full).size > MAX_FILE_BYTES) continue;
+      text = readCapped(full);
+    } catch {
+      continue;
+    }
+    if (text.includes("\u0000")) continue;
+    text.split("\n").forEach((line, i) => {
+      if (out.length < MAX_RESULTS && re.test(line.slice(0, 2000))) out.push(`${relative(ctx.cwd, full)}:${i + 1}:${line.slice(0, 300)}`);
+    });
+  }
+  return out.length ? out.join("\n") : "no matches";
+}
+
+async function toolBash(ctx             , a                         )                  {
+  const command = str(a, "command");
+  // Asks unless --yes. Even under --yes it asks when AGENTS.md is loaded, or when the command names
+  // a secrets file (or a glob that could): then, with nobody to ask, it is denied. Any other command
+  // under --yes runs unattended: use --yes only in repositories you trust.
+  const secret = commandTouchesSecrets(command);
+  if ((!ctx.yes || ctx.notesLoaded || secret) && !(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(ctx             , name        , args                         )                  {
+  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 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)}`;
+  }
+}