portal-agent-cli 1.0.1 → 3.0.0

package/lib/sessions.mjs

@@ -0,0 +1,75 @@
+import { mkdir, readFile, readdir, writeFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+function dir() {
+  return join(homedir(), ".portal-agent", "sessions");
+}
+
+export function newSessionId() {
+  const d = new Date();
+  const p = function (n, w) { return String(n).padStart(w || 2, "0"); };
+  return [
+    d.getFullYear(),
+    p(d.getMonth() + 1),
+    p(d.getDate()),
+    "-",
+    p(d.getHours()),
+    p(d.getMinutes()),
+    p(d.getSeconds())
+  ].join("");
+}
+
+export async function saveSession(id, data) {
+  const d = dir();
+  await mkdir(d, { recursive: true });
+  const path = join(d, id + ".json");
+  await writeFile(path, JSON.stringify(data, null, 2), "utf8");
+}
+
+export async function loadSession(id) {
+  const path = join(dir(), id + ".json");
+  try {
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw);
+  } catch (e) {
+    return null;
+  }
+}
+
+export async function listSessions() {
+  const d = dir();
+  let names;
+  try {
+    names = await readdir(d);
+  } catch (e) {
+    return [];
+  }
+
+  const metas = [];
+  for (const n of names) {
+    if (!n.endsWith(".json")) continue;
+    const id = n.slice(0, -5);
+    const s = await loadSession(id);
+    if (!s) continue;
+    metas.push({
+      id: id,
+      ws: s.ws || "",
+      provider: s.provider || "",
+      turns: (s.turns || []).length,
+      updatedAt: s.updatedAt || 0
+    });
+  }
+  metas.sort(function (a, b) { return b.updatedAt - a.updatedAt; });
+  return metas;
+}
+
+export async function deleteSession(id) {
+  const path = join(dir(), id + ".json");
+  try {
+    await unlink(path);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}

package/lib/system.mjs

@@ -1,24 +1,38 @@
-import { CATALOG } from "./tools.mjs";
+import { CATALOG } from "./tools/index.mjs";
 
-export function buildSystem(ws) {
+export function buildSystem(ws, instructions) {
   const shown = ws.split("\\").join("/");
-  return [
+  const parts = [];
+
+  parts.push([
     "You are a coding agent working in a terminal.",
     "Workspace: " + shown,
-    "Use forward slashes in every path, even on Windows.",
+    "",
+    "Rules:",
+    "1. Use forward slashes in every path, even on Windows.",
+    "2. Do not call the same tool with the same arguments twice.",
+    "3. Do not explore. Act. Only call tools you actually need.",
+    "4. Read a file before editing it. Never guess contents.",
+    "5. When a task is done, stop. Reply with plain prose, no tool calls.",
+    "6. If the request is ambiguous, ask one short question. Do not guess.",
+    "7. Keep replies short. One sentence is fine. No filler.",
+    "8. Prefer edit_file over write_file for changes to existing files."
+  ].join("\n"));
+
+  if (instructions) parts.push(instructions);
+
+  parts.push([
+    "Tool call format:",
     "",
     "To call a tool, write on its own line:",
     "portal-tool: {\"tool\":\"name\",\"args\":{\"key\":\"value\"}}",
     "",
-    "The JSON must use double quotes around keys and values.",
-    "Plain text only. Do not wrap the call in a code block.",
-    "One call per action. Never repeat a call with the same arguments.",
-    "",
-    "If a tool returns an empty result, that is final. Report it.",
-    "If unsure what to do, reply with plain prose and ask.",
-    "When done, reply with plain prose and no tool calls.",
-    "",
-    "Available tools:",
-    CATALOG
-  ].join("\n");
+    "The JSON must use double quotes. Plain text only, no backticks.",
+    "One call per action. Never combine calls inside a code block.",
+    "Multiple calls in one reply are allowed, one per line."
+  ].join("\n"));
+
+  parts.push("Available tools:\n" + CATALOG);
+
+  return parts.join("\n\n");
 }

package/lib/theme.mjs

@@ -0,0 +1,56 @@
+const E = String.fromCharCode(27);
+
+const MODE = process.env.NO_COLOR ? "plain" : "color";
+const FORCE = process.env.PORTAL_THEME || "auto";
+
+function c(code) {
+  if (MODE === "plain") return "";
+  return E + "[" + code + "m";
+}
+
+const R = c(0);
+const B = c(1);
+const D = c(90);
+const RED = c(31);
+const GRN = c(32);
+const YEL = c(33);
+const BLU = c(34);
+const MAG = c(35);
+const CYN = c(36);
+const BGRN = c(92);
+const BRED = c(91);
+const BCYN = c(96);
+
+function wrap(prefix, s) {
+  return prefix + String(s) + R;
+}
+
+export const theme = {
+  reset: R,
+  bold: function (s) { return wrap(B, s); },
+  dim: function (s) { return wrap(D, s); },
+  red: function (s) { return wrap(RED, s); },
+  error: function (s) { return wrap(BRED, s); },
+  green: function (s) { return wrap(GRN, s); },
+  ok: function (s) { return wrap(BGRN, s); },
+  yellow: function (s) { return wrap(YEL, s); },
+  warn: function (s) { return wrap(YEL, s); },
+  blue: function (s) { return wrap(BLU, s); },
+  magenta: function (s) { return wrap(MAG, s); },
+  cyan: function (s) { return wrap(BCYN, s); },
+  accent: function (s) { return wrap(CYN, s); },
+  user: function (s) { return wrap(BLU, s); },
+  tool: function (s) { return wrap(MAG, s); },
+  italic: function (s) { return c(3) + String(s) + R; },
+  underline: function (s) { return c(4) + String(s) + R; }
+};
+
+export function isDark() {
+  if (FORCE === "dark") return true;
+  if (FORCE === "light") return false;
+  return true;
+}
+
+export function colorEnabled() {
+  return MODE === "color";
+}

package/lib/tools/delete.mjs

@@ -0,0 +1,30 @@
+import { unlink, stat, rename } from "node:fs/promises";
+import { safePath } from "./path.mjs";
+
+// Move a file to a trash directory instead of unlinking. Safer default.
+export async function delete_file(args) {
+  const abs = safePath(args.path);
+  try {
+    const st = await stat(abs);
+    if (st.isDirectory()) {
+      return "delete_file cannot remove directories: " + args.path;
+    }
+    // Instead of deleting, rename to .portal-trash
+    const trash = abs + ".portal-trash";
+    await rename(abs, trash);
+    return "moved " + args.path + " to " + args.path + ".portal-trash";
+  } catch (e) {
+    return "delete_file failed: " + (e.message || e);
+  }
+}
+
+export async function move_file(args) {
+  const from = safePath(args.from);
+  const to = safePath(args.to);
+  try {
+    await rename(from, to);
+    return "moved " + args.from + " to " + args.to;
+  } catch (e) {
+    return "move_file failed: " + (e.message || e);
+  }
+}

package/lib/tools/edit.mjs

@@ -0,0 +1,51 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { safePath } from "./path.mjs";
+
+// Exact string replace. Refuses ambiguous edits, so the model cannot
+// accidentally replace the wrong occurrence.
+export async function edit_file(args) {
+  const abs = safePath(args.path);
+  const oldStr = String(args.old_string || "");
+  const newStr = String(args.new_string || "");
+
+  if (!oldStr) return "edit_file requires old_string";
+  if (oldStr === newStr) return "old_string and new_string are identical";
+
+  const orig = await readFile(abs, "utf8");
+  const count = orig.split(oldStr).length - 1;
+
+  if (count === 0) {
+    return "old_string not found in " + args.path + "\n" +
+      "Read the file first with read_file to see exact contents.";
+  }
+
+  if (count > 1 && !args.replace_all) {
+    return "old_string appears " + count + " times in " + args.path + "\n" +
+      "Add more surrounding context to make it unique, or set replace_all:true.";
+  }
+
+  const next = args.replace_all
+    ? orig.split(oldStr).join(newStr)
+    : orig.replace(oldStr, newStr);
+
+  await writeFile(abs + ".portal-bak", orig, "utf8");
+  await writeFile(abs, next, "utf8");
+
+  const delta = next.length - orig.length;
+  const noun = args.replace_all ? count + " occurrences" : "1 occurrence";
+  return "edited " + args.path + ": replaced " + noun +
+    " (" + (delta >= 0 ? "+" : "") + delta + " bytes)";
+}
+
+// Restore the last backup for a file, if one exists.
+export async function undo_file(args) {
+  const abs = safePath(args.path);
+  const backup = abs + ".portal-bak";
+  try {
+    const content = await readFile(backup, "utf8");
+    await writeFile(abs, content, "utf8");
+    return "restored " + args.path + " from backup";
+  } catch (e) {
+    return "no backup found for " + args.path;
+  }
+}

package/lib/tools/find.mjs

@@ -0,0 +1,42 @@
+import { relative, sep } from "node:path";
+import { walk } from "./walk.mjs";
+import { safePath, toPosix, getWorkspace } from "./path.mjs";
+
+function globToRegex(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") { re += ".*"; i++; }
+      else re += "[^/\\\\]*";
+    } else if (c === "?") {
+      re += ".";
+    } else if (".+^$(){}[]|\\".indexOf(c) >= 0) {
+      re += "\\" + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp("^" + re + "$", "i");
+}
+
+export async function find_files(args) {
+  const pattern = args.pattern || "*";
+  const re = globToRegex(pattern);
+  const ws = getWorkspace();
+  const hits = [];
+  const MAX = 200;
+
+  for await (const f of walk(ws)) {
+    if (hits.length >= MAX) break;
+    const rel = toPosix(relative(ws, f));
+    const base = f.split(sep).pop();
+    if (re.test(rel) || re.test(base)) {
+      hits.push(rel);
+    }
+  }
+
+  if (!hits.length) return "no files matched: " + pattern;
+  hits.sort();
+  return hits.length + " file(s):\n" + hits.join("\n");
+}

package/lib/tools/git.mjs

@@ -0,0 +1,52 @@
+import { spawn } from "node:child_process";
+import { getWorkspace } from "./path.mjs";
+
+function run(args) {
+  return new Promise(function (done) {
+    const child = spawn("git", args, {
+      cwd: getWorkspace(),
+      shell: false,
+      windowsHide: true
+    });
+    let out = "";
+    let err = "";
+    if (child.stdout) child.stdout.on("data", function (d) { out += String(d); });
+    if (child.stderr) child.stderr.on("data", function (d) { err += String(d); });
+    const timer = setTimeout(function () {
+      child.kill();
+      done({ code: -1, out: out, err: "timed out" });
+    }, 15000);
+    child.on("error", function (e) {
+      clearTimeout(timer);
+      done({ code: -1, out: "", err: e.message });
+    });
+    child.on("close", function (code) {
+      clearTimeout(timer);
+      done({ code: code, out: out, err: err });
+    });
+  });
+}
+
+export async function git_status() {
+  const r = await run(["status", "--short", "--branch"]);
+  if (r.code !== 0) return "not a git repository, or git is not installed";
+  return r.out.trim() || "working tree clean";
+}
+
+export async function git_diff(args) {
+  const cmd = ["diff"];
+  if (args && args.staged) cmd.push("--cached");
+  if (args && args.path) cmd.push("--", args.path);
+  const r = await run(cmd);
+  if (r.code !== 0) return r.err || "git diff failed";
+  const out = r.out.trim();
+  if (!out) return "no changes";
+  return out.length > 30000 ? out.slice(0, 30000) + "\n[truncated]" : out;
+}
+
+export async function git_log(args) {
+  const n = (args && args.count) || 10;
+  const r = await run(["log", "--oneline", "-" + n]);
+  if (r.code !== 0) return "not a git repository";
+  return r.out.trim() || "no commits";
+}

package/lib/tools/grep.mjs

@@ -0,0 +1,44 @@
+import { readFile, stat } from "node:fs/promises";
+import { relative, sep } from "node:path";
+import { walk } from "./walk.mjs";
+import { safePath, toPosix, getWorkspace } from "./path.mjs";
+
+const MAX_RESULTS = 80;
+const MAX_FILE_BYTES = 512000;
+
+export async function grep_search(args) {
+  const pattern = String(args.pattern || "");
+  if (!pattern) return "grep_search requires a pattern";
+
+  let re;
+  try {
+    re = new RegExp(pattern, args.case_sensitive ? "" : "i");
+  } catch (e) {
+    return "bad regex: " + e.message;
+  }
+
+  const ws = getWorkspace();
+  const startPath = args.path ? safePath(args.path) : ws;
+  const hits = [];
+
+  for await (const f of walk(startPath)) {
+    if (hits.length >= MAX_RESULTS) break;
+    let info;
+    try { info = await stat(f); } catch (e) { continue; }
+    if (info.size > MAX_FILE_BYTES) continue;
+
+    let text;
+    try { text = await readFile(f, "utf8"); } catch (e) { continue; }
+    const lines = text.split("\n");
+
+    for (let i = 0; i < lines.length && hits.length < MAX_RESULTS; i++) {
+      if (re.test(lines[i])) {
+        const rel = toPosix(relative(ws, f));
+        hits.push(rel + ":" + (i + 1) + ":" + lines[i].trim().slice(0, 200));
+      }
+    }
+  }
+
+  if (!hits.length) return "no matches for: " + pattern;
+  return hits.length + " matches:\n" + hits.join("\n");
+}

package/lib/tools/index.mjs

@@ -0,0 +1,53 @@
+import { read_file } from "./read.mjs";
+import { write_file, append_file } from "./write.mjs";
+import { edit_file, undo_file } from "./edit.mjs";
+import { list_files } from "./list.mjs";
+import { find_files } from "./find.mjs";
+import { grep_search } from "./grep.mjs";
+import { delete_file, move_file } from "./delete.mjs";
+import { shell } from "./shell.mjs";
+import { git_status, git_diff, git_log } from "./git.mjs";
+
+export const TOOLS = {
+  read_file: read_file,
+  write_file: write_file,
+  edit_file: edit_file,
+  append_file: append_file,
+  undo_file: undo_file,
+  list_files: list_files,
+  find_files: find_files,
+  grep_search: grep_search,
+  delete_file: delete_file,
+  move_file: move_file,
+  shell: shell,
+  git_status: git_status,
+  git_diff: git_diff,
+  git_log: git_log
+};
+
+export const SAFE_TOOLS = new Set([
+  "read_file",
+  "list_files",
+  "find_files",
+  "grep_search",
+  "git_status",
+  "git_diff",
+  "git_log"
+]);
+
+export const CATALOG = [
+  "- read_file(path, start_line?, end_line?)             read file with line numbers",
+  "- write_file(path, content)                            write or overwrite a whole file",
+  "- edit_file(path, old_string, new_string, replace_all?)  exact find and replace",
+  "- append_file(path, content)                           add text to the end of a file",
+  "- undo_file(path)                                      restore the last backup",
+  "- list_files(path?)                                    list a directory with sizes",
+  "- find_files(pattern)                                  glob search, e.g. **/*.ts",
+  "- grep_search(pattern, path?, case_sensitive?)         regex inside files",
+  "- delete_file(path)                                    move a file to .portal-trash",
+  "- move_file(from, to)                                  rename or relocate a file",
+  "- shell(command)                                       run a shell command",
+  "- git_status()                                         show git status",
+  "- git_diff(path?, staged?)                             show uncommitted changes",
+  "- git_log(count?)                                      recent commits"
+].join("\n");

package/lib/tools/list.mjs

@@ -0,0 +1,38 @@
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { safePath } from "./path.mjs";
+
+export async function list_files(args) {
+  const abs = safePath(args.path || ".");
+  const entries = await readdir(abs, { withFileTypes: true });
+
+  if (!entries.length) {
+    return "EMPTY. This directory has no files or subdirectories. " +
+      "Do not call list_files again on this path.";
+  }
+
+  const rows = [];
+  for (const e of entries) {
+    const full = join(abs, e.name);
+    let size = "";
+    if (e.isFile()) {
+      try {
+        const st = await stat(full);
+        size = formatSize(st.size);
+      } catch (err) {
+        size = "";
+      }
+    }
+    const tag = e.isDirectory() ? "[dir] " : "      ";
+    rows.push(tag + e.name.padEnd(40) + " " + size);
+  }
+
+  rows.sort();
+  return rows.join("\n");
+}
+
+function formatSize(bytes) {
+  if (bytes < 1024) return bytes + " B";
+  if (bytes < 1024 * 1024) return Math.round(bytes / 1024) + " KB";
+  return (bytes / 1024 / 1024).toFixed(1) + " MB";
+}

package/lib/tools/path.mjs

@@ -0,0 +1,22 @@
+import { resolve, relative, sep } from "node:path";
+
+let ws = process.cwd();
+
+export function setWorkspace(p) { ws = resolve(p); }
+export function getWorkspace() { return ws; }
+
+export function safePath(p) {
+  if (!p || typeof p !== "string") {
+    throw new Error("path must be a non-empty string");
+  }
+  const abs = resolve(ws, p);
+  const rel = relative(ws, abs);
+  if (rel === ".." || rel.slice(0, 3) === "..\\" || rel.slice(0, 3) === "../") {
+    throw new Error("path escapes workspace: " + p);
+  }
+  return abs;
+}
+
+export function toPosix(p) {
+  return p.split(sep).join("/");
+}

package/lib/tools/read.mjs

@@ -0,0 +1,33 @@
+import { readFile } from "node:fs/promises";
+import { safePath } from "./path.mjs";
+
+const MAX_BYTES = 500000;
+
+export async function read_file(args) {
+  const abs = safePath(args.path);
+  const text = await readFile(abs, "utf8");
+
+  if (text.length > MAX_BYTES) {
+    return text.slice(0, MAX_BYTES) + "\n[truncated at " + MAX_BYTES + " bytes]";
+  }
+
+  const lines = text.split("\n");
+  const start = Math.max(1, Number(args.start_line) || 1);
+  const end = Math.min(lines.length, Number(args.end_line) || lines.length);
+
+  if (start > end) {
+    return "invalid range: start_line " + start + " is after end_line " + end;
+  }
+
+  const width = String(end).length;
+  const out = [];
+  for (let i = start - 1; i < end; i++) {
+    out.push(String(i + 1).padStart(width) + "| " + lines[i]);
+  }
+
+  const header = start === 1 && end === lines.length
+    ? lines.length + " lines total"
+    : "lines " + start + "-" + end + " of " + lines.length;
+
+  return "[" + header + "]\n" + out.join("\n");
+}

package/lib/tools/shell.mjs

@@ -0,0 +1,45 @@
+import { spawn } from "node:child_process";
+import { getWorkspace } from "./path.mjs";
+
+const MAX_OUTPUT = 65000;
+const TIMEOUT_MS = 60000;
+
+export function shell(args) {
+  const cmd = String(args.command || "");
+  if (!cmd) return Promise.resolve("shell requires a command");
+
+  return new Promise(function (done) {
+    const ws = getWorkspace();
+    const isWin = process.platform === "win32";
+
+    const child = spawn(cmd, {
+      cwd: ws,
+      shell: isWin ? true : "/bin/sh",
+      windowsHide: true
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    if (child.stdout) child.stdout.on("data", function (d) { stdout += String(d); });
+    if (child.stderr) child.stderr.on("data", function (d) { stderr += String(d); });
+
+    const timer = setTimeout(function () {
+      child.kill();
+      done("timed out after " + (TIMEOUT_MS / 1000) + "s\n" + stderr);
+    }, TIMEOUT_MS);
+
+    child.on("error", function (err) {
+      clearTimeout(timer);
+      done("spawn error: " + err.message);
+    });
+
+    child.on("close", function (code) {
+      clearTimeout(timer);
+      const both = [stdout.trimEnd(), stderr.trimEnd()].filter(Boolean).join("\n");
+      let s = "exit " + (code === null ? "null" : code) + "\n" + (both || "(no output)");
+      if (s.length > MAX_OUTPUT) s = s.slice(0, MAX_OUTPUT) + "\n[truncated]";
+      done(s);
+    });
+  });
+}

package/lib/tools/walk.mjs

@@ -0,0 +1,32 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+const DEFAULT_IGNORE = new Set([
+  "node_modules", ".git", ".hg", ".svn", "dist", "build", "out",
+  ".next", ".nuxt", ".turbo", ".cache", "target", "__pycache__",
+  ".venv", "venv", "env", "coverage", ".idea", ".vscode", ".DS_Store"
+]);
+
+let ignore = DEFAULT_IGNORE;
+
+export function setIgnore(names) {
+  ignore = new Set(names || []);
+}
+
+// Depth-first file walker. Yields full absolute paths. Skips ignored dirs
+// and hidden files (except .env.example which is often relevant).
+export async function* walk(dir) {
+  let items;
+  try {
+    items = await readdir(dir, { withFileTypes: true });
+  } catch (e) {
+    return;
+  }
+  for (const it of items) {
+    if (ignore.has(it.name)) continue;
+    if (it.name.startsWith(".") && it.name !== ".env.example") continue;
+    const full = join(dir, it.name);
+    if (it.isDirectory()) yield* walk(full);
+    else if (it.isFile()) yield full;
+  }
+}

package/lib/tools/write.mjs

@@ -0,0 +1,46 @@
+import { writeFile, mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { safePath } from "./path.mjs";
+
+// Write a whole file. Creates parent directories. If the file already
+// exists, saves a backup first.
+export async function write_file(args) {
+  const abs = safePath(args.path);
+  const content = args.content || "";
+  await mkdir(dirname(abs), { recursive: true });
+
+  // Backup existing file
+  try {
+    const existing = await readFile(abs, "utf8");
+    if (existing !== content) {
+      const backup = abs + ".portal-bak";
+      await writeFile(backup, existing, "utf8");
+    }
+  } catch (e) {
+    // new file, no backup needed
+  }
+
+  await writeFile(abs, content, "utf8");
+  const lines = content.length === 0 ? 0 : content.split("\n").length;
+  return "wrote " + content.length + " bytes (" + lines + " lines) to " + args.path;
+}
+
+// Append to end of a file, creating it if missing.
+export async function append_file(args) {
+  const abs = safePath(args.path);
+  await mkdir(dirname(abs), { recursive: true });
+
+  let existing = "";
+  try {
+    existing = await readFile(abs, "utf8");
+  } catch (e) {
+    existing = "";
+  }
+
+  const content = args.content || "";
+  const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  const add = content.endsWith("\n") ? content : content + "\n";
+
+  await writeFile(abs, existing + sep + add, "utf8");
+  return "appended " + content.length + " bytes to " + args.path;
+}