causly-server 0.0.0-stage → 1.5.1

package/tools/discordOps.js

@@ -0,0 +1,133 @@
+// Discord tools over the REST API (v10). No new dependencies; a bot token is all that is needed.
+//
+//   discord_get_me         check the bot token, show the bot
+//   discord_list_guilds    servers the bot is in
+//   discord_list_channels  channels of one server, grouped by category
+//   discord_read_messages  recent messages in a channel
+//   discord_send_message   post a message (HIGH risk, needs confirm: true)
+//
+// Credentials: DISCORD_BOT_TOKEN (Discord Developer Portal > your app > Bot > Reset Token).
+// Invite the bot with the permissions View Channels, Read Message History, Send Messages.
+// To read what OTHER people wrote, turn on "Message Content Intent" for the bot in the portal;
+// without it Discord returns empty text for most messages.
+import { UNTRUSTED_NOTICE } from "./webOps.js";
+
+const API = "https://discord.com/api/v10";
+const clamp = (n, lo, hi) => Math.min(Math.max(n, lo), hi);
+const SNOWFLAKE = /^\d{15,25}$/;
+const MAX_TEXT = 2000;
+const CHANNEL_KINDS = { 0: "text", 5: "announcement", 15: "forum" };
+
+function snowflake(value, label) {
+  const s = String(value ?? "").trim();
+  if (!SNOWFLAKE.test(s)) throw new Error(`${label} must be a Discord id (a long number). In Discord, turn on Developer Mode and right-click > Copy ID, or use discord_list_guilds / discord_list_channels.`);
+  return s;
+}
+
+async function call(method, path, { query, body } = {}, deps = {}) {
+  const fetchFn = deps.fetch ?? globalThis.fetch;
+  const token = process.env.DISCORD_BOT_TOKEN;
+  if (!token) throw new Error("Discord is not set up. Missing: DISCORD_BOT_TOKEN (create a bot in the Discord Developer Portal and add its token to .env).");
+  const scrub = (text) => String(text).split(token).join("[REDACTED]");
+  const pairs = Object.entries(query ?? {}).filter(([, v]) => v !== undefined && v !== null && v !== "");
+  const qs = pairs.length ? `?${new URLSearchParams(pairs.map(([k, v]) => [k, String(v)]))}` : "";
+
+  let res;
+  try {
+    res = await fetchFn(`${API}${path}${qs}`, {
+      method,
+      headers: {
+        authorization: `Bot ${token}`,
+        "user-agent": "DiscordBot (https://github.com/KNIHAL/causly-server, 1.0)",
+        ...(body ? { "content-type": "application/json" } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(20_000),
+    });
+  } catch (err) {
+    throw new Error(`Could not reach Discord: ${scrub(err.message)}`);
+  }
+  const data = await res.json().catch(() => ({}));
+  if (res.ok) return data;
+
+  const why = scrub(data.message || `HTTP ${res.status}`);
+  if (res.status === 401) throw new Error("Discord rejected the bot token. Check DISCORD_BOT_TOKEN.");
+  if (res.status === 403) throw new Error(`Discord refused: ${why}. The bot is missing access or a permission there: check its role and the channel's permissions (View Channel, Read Message History, Send Messages).`);
+  if (res.status === 404) throw new Error(`Discord could not find that: ${why}. Check the id, and that the bot is in that server.`);
+  if (res.status === 429) throw new Error(`Discord rate limit hit${data.retry_after ? `; retry in ${Math.ceil(data.retry_after)}s` : ""}.`);
+  throw new Error(`Discord error: ${why}`);
+}
+
+// ---------------------------------------------------------------- tools
+
+export async function getMe(_input = {}, deps = {}) {
+  const me = await call("GET", "/users/@me", {}, deps);
+  const guilds = await call("GET", "/users/@me/guilds", { query: { limit: 200 } }, deps);
+  return { id: me.id, username: me.username, servers: guilds.length };
+}
+
+export async function listGuilds(_input = {}, deps = {}) {
+  const data = await call("GET", "/users/@me/guilds", { query: { limit: 200 } }, deps);
+  return { count: data.length, servers: data.map((g) => ({ id: g.id, name: g.name, ...(g.owner ? { owner: true } : {}) })) };
+}
+
+export async function listChannels({ guild_id } = {}, deps = {}) {
+  const id = snowflake(guild_id, "guild_id");
+  const data = await call("GET", `/guilds/${id}/channels`, {}, deps);
+  const categories = new Map(data.filter((c) => c.type === 4).map((c) => [c.id, c.name]));
+  const channels = data
+    .filter((c) => c.type in CHANNEL_KINDS)
+    .sort((a, b) => (a.position ?? 0) - (b.position ?? 0))
+    .map((c) => ({
+      id: c.id,
+      name: c.name,
+      type: CHANNEL_KINDS[c.type],
+      ...(c.parent_id && categories.has(c.parent_id) ? { category: categories.get(c.parent_id) } : {}),
+      ...(c.topic ? { topic: String(c.topic).slice(0, 200) } : {}),
+    }));
+  return { guild_id: id, count: channels.length, channels, notice: UNTRUSTED_NOTICE };
+}
+
+export async function readMessages({ channel_id, limit = 20, before, after } = {}, deps = {}) {
+  const id = snowflake(channel_id, "channel_id");
+  const query = {
+    limit: clamp(Math.trunc(Number(limit)) || 20, 1, 100),
+    ...(before ? { before: snowflake(before, "before") } : {}),
+    ...(after ? { after: snowflake(after, "after") } : {}),
+  };
+  const raw = await call("GET", `/channels/${id}/messages`, { query }, deps);
+  const messages = [...raw].reverse().map((m) => ({
+    id: m.id,
+    author: m.author?.username ?? "unknown",
+    author_id: m.author?.id,
+    ...(m.author?.bot ? { bot: true } : {}),
+    time: m.timestamp,
+    text: m.content ?? "",
+    ...(m.message_reference?.message_id ? { reply_to: m.message_reference.message_id } : {}),
+    ...(m.attachments?.length ? { attachments: m.attachments.length } : {}),
+    ...(m.embeds?.length ? { embeds: m.embeds.length } : {}),
+  }));
+  const blank = messages.length > 0 && messages.every((m) => !m.text && !m.attachments && !m.embeds);
+  return {
+    channel_id: id,
+    count: messages.length,
+    messages,
+    ...(blank ? { note: "Every message came back with empty text. Turn on 'Message Content Intent' for the bot in the Discord Developer Portal (Bot page), then try again." } : {}),
+    notice: UNTRUSTED_NOTICE,
+  };
+}
+
+/** HIGH risk: posts as the bot where other people read it. The wrapper requires confirm: true. */
+export async function sendMessage({ channel_id, text, reply_to_message_id, confirm } = {}, deps = {}) {
+  const id = snowflake(channel_id, "channel_id");
+  const content = String(text ?? "");
+  if (!content.trim()) throw new Error("text is required.");
+  if (content.length > MAX_TEXT) throw new Error(`text is ${content.length} characters; Discord allows ${MAX_TEXT}. Shorten it or send it in parts.`);
+  const body = {
+    content,
+    allowed_mentions: { parse: [] }, // never ping @everyone, @here, roles or people by accident
+    ...(reply_to_message_id ? { message_reference: { message_id: snowflake(reply_to_message_id, "reply_to_message_id"), fail_if_not_exists: false } } : {}),
+  };
+  const m = await call("POST", `/channels/${id}/messages`, { body }, deps);
+  return { sent: true, id: m.id, channel_id: m.channel_id, time: m.timestamp };
+}

package/tools/dockerOps.js

@@ -0,0 +1,259 @@
+const { execFile } = await import("child_process");
+const { promisify } = await import("util");
+const execFileAsync = promisify(execFile);
+
+/** Converts a Windows path (D:\foo\bar) to its WSL equivalent (/mnt/d/foo/bar). Leaves non-Windows-style paths untouched. */
+function toWslPath(p) {
+  if (typeof p !== "string" || !/^[a-zA-Z]:\\/.test(p)) return p;
+  const drive = p[0].toLowerCase();
+  const rest = p.slice(2).replace(/\\/g, "/");
+  return `/mnt/${drive}${rest}`;
+}
+
+/** Applies toWslPath to a "HOST:CONTAINER" volume string's host side only. */
+function toWslVolume(v) {
+  if (typeof v !== "string") return v;
+  const idx = v.indexOf(":", 2); // skip past "D:" drive-letter colon
+  if (v.length > 1 && v[1] === ":" ) {
+    const rest = v.slice(2);
+    const sep = rest.indexOf(":");
+    if (sep === -1) return v;
+    const hostPart = v.slice(0, 2) + rest.slice(0, sep);
+    const containerPart = rest.slice(sep);
+    return toWslPath(hostPart) + containerPart;
+  }
+  return v;
+}
+
+/**
+ * Cross-platform Docker runner. Tries `docker` directly first — this covers
+ * macOS, Linux, and Windows with Docker Desktop (which puts docker.exe on PATH).
+ * If that fails with a "command not found" style error AND we're on Windows,
+ * falls back to `wsl docker ...` — this covers Windows setups where Docker
+ * only exists inside WSL (no Docker Desktop installed). When falling back,
+ * pass `wslArgs`/`wslCwd` (WSL-path versions) if the direct args contain
+ * Windows-style paths that WSL's docker can't resolve.
+ */
+async function runDocker(args, { timeout_ms = 60000, cwd, wslArgs, wslCwd } = {}) {
+  const attempt = async (cmd, cmdArgs, cmdCwd) => {
+    try {
+      const { stdout, stderr } = await execFileAsync(cmd, cmdArgs, {
+        cwd: cmdCwd,
+        timeout: timeout_ms,
+        maxBuffer: 1024 * 1024 * 20,
+      });
+      return { stdout, stderr, exit_code: 0 };
+    } catch (err) {
+      return {
+        stdout: err.stdout || "",
+        stderr: err.stderr || err.message,
+        exit_code: err.code ?? 1,
+        notFound: err.code === "ENOENT" || /is not recognized|command not found/i.test(err.message || ""),
+      };
+    }
+  };
+
+  const direct = await attempt("docker", args, cwd);
+  if (direct.exit_code === 0 || !direct.notFound) return direct;
+
+  if (process.platform === "win32") {
+    return attempt("wsl", ["docker", ...(wslArgs || args)], wslCwd || cwd);
+  }
+  return direct;
+}
+
+/** Get Docker client/server version info — connectivity check. */
+export async function dockerVersion() {
+  return runDocker(["version"]);
+}
+
+/** List containers. Set all=true to include stopped ones (defaults to running only). */
+export async function dockerPs({ all = false }) {
+  const args = ["ps", "--format", "{{json .}}"];
+  if (all) args.push("-a");
+  const result = await runDocker(args);
+  if (result.exit_code !== 0) return result;
+  const containers = result.stdout
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+  return { containers };
+}
+
+/** List images. */
+export async function dockerImages() {
+  const result = await runDocker(["images", "--format", "{{json .}}"]);
+  if (result.exit_code !== 0) return result;
+  const images = result.stdout
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+  return { images };
+}
+
+/** Build an image from a Dockerfile. HIGH risk — requires confirm: true. */
+export async function dockerBuild({ context_dir, tag, dockerfile, build_args, confirm }) {
+  const buildArgsFlags = [];
+  if (build_args) {
+    for (const [k, v] of Object.entries(build_args)) {
+      buildArgsFlags.push("--build-arg", `${k}=${v}`);
+    }
+  }
+
+  const args = ["build", "-t", tag, ...(dockerfile ? ["-f", dockerfile] : []), ...buildArgsFlags, context_dir];
+  const wslArgs = [
+    "build",
+    "-t",
+    tag,
+    ...(dockerfile ? ["-f", toWslPath(dockerfile)] : []),
+    ...buildArgsFlags,
+    toWslPath(context_dir),
+  ];
+
+  return runDocker(args, { timeout_ms: 600000, wslArgs });
+}
+
+/** Run a new container from an image. HIGH risk — requires confirm: true. */
+export async function dockerRun({ image, name, ports, env, volumes, detach = true, command, confirm }) {
+  const base = [];
+  if (detach) base.push("-d");
+  if (name) base.push("--name", name);
+  if (ports) for (const p of ports) base.push("-p", p);
+  if (env) for (const [k, v] of Object.entries(env)) base.push("-e", `${k}=${v}`);
+
+  const args = ["run", ...base];
+  const wslArgs = ["run", ...base];
+  if (volumes) {
+    for (const v of volumes) {
+      args.push("-v", v);
+      wslArgs.push("-v", toWslVolume(v));
+    }
+  }
+  args.push(image);
+  wslArgs.push(image);
+  if (command) {
+    const cmdParts = command.split(" ");
+    args.push(...cmdParts);
+    wslArgs.push(...cmdParts);
+  }
+
+  return runDocker(args, { timeout_ms: 120000, wslArgs });
+}
+
+/** Stop a running container. HIGH risk — requires confirm: true. */
+export async function dockerStop({ container, confirm }) {
+  return runDocker(["stop", container]);
+}
+
+/** Start a stopped container. */
+export async function dockerStart({ container }) {
+  return runDocker(["start", container]);
+}
+
+/** Restart a container. HIGH risk — requires confirm: true. */
+export async function dockerRestart({ container, confirm }) {
+  return runDocker(["restart", container]);
+}
+
+/** Remove a container. DESTRUCTIVE — requires confirm: true. */
+export async function dockerRemove({ container, force = false, confirm }) {
+  const args = ["rm"];
+  if (force) args.push("-f");
+  args.push(container);
+  return runDocker(args);
+}
+
+/** Remove an image. DESTRUCTIVE — requires confirm: true. */
+export async function dockerRemoveImage({ image, force = false, confirm }) {
+  const args = ["rmi"];
+  if (force) args.push("-f");
+  args.push(image);
+  return runDocker(args);
+}
+
+/** Get logs from a container. */
+export async function dockerLogs({ container, tail = 100, since }) {
+  const args = ["logs", "--tail", String(tail)];
+  if (since) args.push("--since", since);
+  args.push(container);
+  return runDocker(args);
+}
+
+/** Inspect a container or image — full JSON metadata. */
+export async function dockerInspect({ target }) {
+  const result = await runDocker(["inspect", target]);
+  if (result.exit_code !== 0) return result;
+  try {
+    return { data: JSON.parse(result.stdout) };
+  } catch {
+    return result;
+  }
+}
+
+/** Execute a command inside a running container. */
+export async function dockerExec({ container, command }) {
+  const args = ["exec", container, ...command.split(" ")];
+  return runDocker(args);
+}
+
+/** Show live resource usage stats (CPU, memory) for running containers — one-shot snapshot, not streaming. */
+export async function dockerStats() {
+  const result = await runDocker(["stats", "--no-stream", "--format", "{{json .}}"]);
+  if (result.exit_code !== 0) return result;
+  const stats = result.stdout
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+  return { stats };
+}
+
+/** Push an image to a registry. HIGH risk — requires confirm: true. */
+export async function dockerPush({ image, confirm }) {
+  return runDocker(["push", image], { timeout_ms: 300000 });
+}
+
+/** Pull an image from a registry. */
+export async function dockerPull({ image }) {
+  return runDocker(["pull", image], { timeout_ms: 300000 });
+}
+
+/** Run docker compose up for a project directory. HIGH risk — requires confirm: true. */
+export async function dockerComposeUp({ project_dir, detach = true, confirm }) {
+  const args = ["compose", "up"];
+  if (detach) args.push("-d");
+  const direct = await runDocker(args, { cwd: project_dir, timeout_ms: 300000 });
+  if (direct.exit_code === 0 || !direct.notFound || process.platform !== "win32") return direct;
+
+  const wslDir = toWslPath(project_dir);
+  const composeCmd = `cd '${wslDir}' && docker compose up${detach ? " -d" : ""}`;
+  try {
+    const { stdout, stderr } = await execFileAsync("wsl", ["bash", "-lc", composeCmd], {
+      timeout: 300000,
+      maxBuffer: 1024 * 1024 * 20,
+    });
+    return { stdout, stderr, exit_code: 0 };
+  } catch (err) {
+    return { stdout: err.stdout || "", stderr: err.stderr || err.message, exit_code: err.code ?? 1 };
+  }
+}
+
+/** Run docker compose down for a project directory. HIGH risk — requires confirm: true. */
+export async function dockerComposeDown({ project_dir, confirm }) {
+  const direct = await runDocker(["compose", "down"], { cwd: project_dir, timeout_ms: 120000 });
+  if (direct.exit_code === 0 || !direct.notFound || process.platform !== "win32") return direct;
+
+  const wslDir = toWslPath(project_dir);
+  const composeCmd = `cd '${wslDir}' && docker compose down`;
+  try {
+    const { stdout, stderr } = await execFileAsync("wsl", ["bash", "-lc", composeCmd], {
+      timeout: 120000,
+      maxBuffer: 1024 * 1024 * 20,
+    });
+    return { stdout, stderr, exit_code: 0 };
+  } catch (err) {
+    return { stdout: err.stdout || "", stderr: err.stderr || err.message, exit_code: err.code ?? 1 };
+  }
+}

package/tools/envFile.js

@@ -0,0 +1,89 @@
+// Reading and editing the settings (.env) file without disturbing anything else in it.
+// Used by `causly-server keys` and `causly-server setup`. Values are never logged here.
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+const NAME = /^[A-Z][A-Z0-9_]{1,63}$/;
+export const isValidName = (n) => NAME.test(String(n));
+
+const stripQuotes = (v) => ((v.startsWith('"') && v.endsWith('"') && v.length > 1) || (v.startsWith("'") && v.endsWith("'") && v.length > 1) ? v.slice(1, -1) : v);
+
+/** { NAME: value } from the active (uncommented) lines of a .env file. Missing file gives {}. */
+export function readEnvValues(file) {
+  if (!fs.existsSync(file)) return {};
+  const out = {};
+  for (const raw of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    if (key) out[key] = stripQuotes(line.slice(eq + 1).trim());
+  }
+  return out;
+}
+
+/** Trim and validate a pasted value. Throws a plain message if it cannot be stored safely. */
+export function checkValue(value) {
+  const v = String(value ?? "").trim();
+  if (!v) throw new Error("The value is empty.");
+  if (/[\r\n]/.test(v)) throw new Error("The value has a line break in it. Paste just the key.");
+  if (v.length > 4096) throw new Error("The value is too long (4096 characters at most).");
+  if (/^["']|["']$/.test(v)) throw new Error("The value starts or ends with a quote mark. Paste it without quotes.");
+  return v;
+}
+
+function writeAtomic(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, text, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  if (os.platform() !== "win32") fs.chmodSync(file, 0o600); // keys are for the owner only
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Set NAME=value: replace the active line, else fill in a "# NAME=" placeholder, else append. */
+export function setEnvValue(file, name, value) {
+  if (!isValidName(name)) throw new Error(`"${name}" is not a valid setting name (capital letters, digits and underscores).`);
+  const v = checkValue(value);
+  const existed = fs.existsSync(file);
+  const text = existed ? fs.readFileSync(file, "utf8") : "";
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const lines = text === "" ? [] : text.split(/\r?\n/);
+  if (lines.length && lines[lines.length - 1] === "") lines.pop(); // the split leaves one empty item after a final newline
+  const active = new RegExp(`^\\s*${escapeRe(name)}\\s*=`);
+  const placeholder = new RegExp(`^\\s*#\\s*${escapeRe(name)}\\s*=`);
+  let at = lines.findIndex((l) => active.test(l));
+  const replaced = at !== -1;
+  if (at === -1) at = lines.findIndex((l) => placeholder.test(l));
+  const line = `${name}=${v}`;
+  if (at !== -1) lines[at] = line;
+  else {
+    if (lines.length && lines[lines.length - 1] === "") lines.pop();
+    lines.push(line);
+  }
+  writeAtomic(file, `${lines.join(eol)}${eol}`);
+  return { created: !existed, replaced };
+}
+
+/** Remove NAME from the file (every active line for it). Returns whether anything was removed. */
+export function unsetEnvValue(file, name) {
+  if (!fs.existsSync(file)) return false;
+  const text = fs.readFileSync(file, "utf8");
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const active = new RegExp(`^\\s*${escapeRe(name)}\\s*=`);
+  const lines = text.split(/\r?\n/);
+  const kept = lines.filter((l) => !active.test(l));
+  if (kept.length === lines.length) return false;
+  writeAtomic(file, kept.join(eol));
+  return true;
+}
+
+/** "set (…ab12)" for a secret long enough to hint at, "set" otherwise. Never the whole value. */
+export function describeSecret(value) {
+  const v = String(value ?? "");
+  if (!v) return "missing";
+  return v.length >= 12 ? `set (…${v.slice(-4)})` : "set";
+}

package/tools/envLoader.js

@@ -0,0 +1,85 @@
+import fs from "fs";
+import { envFiles } from "./paths.js";
+
+/**
+ * Minimal, dependency-free .env loader.
+ * Written by hand instead of using the `dotenv` package because dotenv
+ * prints a banner to stdout on load, which corrupts the MCP stdio
+ * JSON-RPC stream (stdout must contain ONLY protocol messages).
+ *
+ * Files are read in order: CAUSLY_ENV_FILE, ~/.causly/.env, then the .env next to the
+ * code (a git checkout). A variable that is already set is never overwritten, so the
+ * client's own "env" block and earlier files win.
+ */
+
+let launchKeys = null; // variables the process started with: files never override these
+let fromFiles = new Set(); // variables we set from files, so a reload can update or drop them
+let seen = new Map(); // file -> "mtimeMs:size" at last load
+
+function applyFiles() {
+  for (const file of envFiles()) {
+    if (!fs.existsSync(file)) continue;
+    let content;
+    try {
+      content = fs.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    for (const rawLine of content.split("\n")) {
+      const line = rawLine.trim();
+      if (!line || line.startsWith("#")) continue;
+
+      const eqIndex = line.indexOf("=");
+      if (eqIndex === -1) continue;
+
+      const key = line.slice(0, eqIndex).trim();
+      let value = line.slice(eqIndex + 1).trim();
+
+      // Strip surrounding quotes if present.
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      if (key && !(key in process.env)) {
+        process.env[key] = value;
+        fromFiles.add(key);
+      }
+    }
+  }
+}
+
+export function loadEnv() {
+  if (launchKeys === null) launchKeys = new Set(Object.keys(process.env));
+  applyFiles();
+  snapshot();
+}
+
+function stamp(file) {
+  try {
+    const s = fs.statSync(file);
+    return `${s.mtimeMs}:${s.size}`;
+  } catch {
+    return "";
+  }
+}
+
+function snapshot() {
+  seen = new Map(envFiles().map((f) => [f, stamp(f)]));
+}
+
+/**
+ * Pick up changes made to the settings files while the server is running (for example by
+ * `causly-server setup`), so a new key works on the next tool call without a restart.
+ * Variables the process started with keep winning. Cheap: a stat per file per call.
+ */
+export function reloadEnvIfChanged() {
+  if (launchKeys === null) return false;
+  const files = envFiles();
+  const changed = files.length !== seen.size || files.some((f) => seen.get(f) !== stamp(f));
+  if (!changed) return false;
+  for (const key of fromFiles) if (!launchKeys.has(key)) delete process.env[key];
+  fromFiles = new Set();
+  applyFiles();
+  snapshot();
+  return true;
+}

package/tools/fileOps.js

@@ -0,0 +1,125 @@
+import fs from "fs/promises";
+import path from "path";
+import { isPathDenied } from "./security.js";
+
+function assertPathAllowed(targetPath) {
+  const check = isPathDenied(targetPath);
+  if (check.denied) throw new Error(check.reason);
+}
+
+/**
+ * mkdir(recursive: true) that tolerates Windows quirks where the target
+ * directory is a drive root (e.g. "D:\") — Node throws EPERM there even
+ * though the directory already exists.
+ */
+async function safeMkdir(dirPath) {
+  try {
+    await fs.mkdir(dirPath, { recursive: true });
+  } catch (err) {
+    if (err.code !== "EPERM" && err.code !== "EEXIST") throw err;
+  }
+}
+
+/** Read a single file's full text content. */
+export async function readFile({ path: filePath, encoding = "utf8" }) {
+  const content = await fs.readFile(filePath, encoding);
+  return { path: filePath, content };
+}
+
+/** Read multiple files in one call — avoids repeated round trips. */
+export async function readMultipleFiles({ paths, encoding = "utf8" }) {
+  const results = await Promise.all(
+    paths.map(async (p) => {
+      try {
+        const content = await fs.readFile(p, encoding);
+        return { path: p, content, success: true };
+      } catch (err) {
+        return { path: p, error: err.message, success: false };
+      }
+    })
+  );
+  return { results };
+}
+
+/** Create a brand-new file. Fails if the file already exists (safety). */
+export async function createFile({ path: filePath, content = "" }) {
+  assertPathAllowed(filePath);
+  await safeMkdir(path.dirname(filePath));
+  await fs.writeFile(filePath, content, { flag: "wx" });
+  return { path: filePath, created: true };
+}
+
+/** Write/overwrite a file completely. Creates parent dirs if needed. */
+export async function writeFile({ path: filePath, content }) {
+  assertPathAllowed(filePath);
+  await safeMkdir(path.dirname(filePath));
+  await fs.writeFile(filePath, content, "utf8");
+  return { path: filePath, written: true };
+}
+
+/**
+ * Edit a file via exact string replacement (find & replace) without
+ * rewriting the whole file manually. `old_str` must be unique unless
+ * replace_all is true.
+ */
+export async function editFile({ path: filePath, old_str, new_str, replace_all = false }) {
+  assertPathAllowed(filePath);
+  const original = await fs.readFile(filePath, "utf8");
+
+  if (!original.includes(old_str)) {
+    throw new Error("old_str not found in file — no changes made.");
+  }
+
+  let updated;
+  if (replace_all) {
+    updated = original.split(old_str).join(new_str);
+  } else {
+    const firstIndex = original.indexOf(old_str);
+    const lastIndex = original.lastIndexOf(old_str);
+    if (firstIndex !== lastIndex) {
+      throw new Error(
+        "old_str appears multiple times. Pass replace_all: true, or make old_str more specific/unique."
+      );
+    }
+    updated = original.slice(0, firstIndex) + new_str + original.slice(firstIndex + old_str.length);
+  }
+
+  await fs.writeFile(filePath, updated, "utf8");
+  return { path: filePath, edited: true };
+}
+
+/** Delete a single file. */
+export async function deleteFile({ path: filePath }) {
+  assertPathAllowed(filePath);
+  await fs.unlink(filePath);
+  return { path: filePath, deleted: true };
+}
+
+/** Move or rename a file/directory. */
+export async function moveFile({ source, destination }) {
+  assertPathAllowed(source);
+  assertPathAllowed(destination);
+  await safeMkdir(path.dirname(destination));
+  await fs.rename(source, destination);
+  return { source, destination, moved: true };
+}
+
+/** Copy a file (not recursive — for directories use copyDirectory). */
+export async function copyFile({ source, destination }) {
+  await safeMkdir(path.dirname(destination));
+  await fs.copyFile(source, destination);
+  return { source, destination, copied: true };
+}
+
+/** Get metadata about a file or directory. */
+export async function getFileInfo({ path: targetPath }) {
+  const stats = await fs.stat(targetPath);
+  return {
+    path: targetPath,
+    type: stats.isDirectory() ? "directory" : "file",
+    size_bytes: stats.size,
+    created: stats.birthtime,
+    modified: stats.mtime,
+    accessed: stats.atime,
+  };
+}