z0gcode 0.2.0

package/src/mcp.mjs

@@ -0,0 +1,91 @@
+// MCP client: connect to configured MCP servers (.z0g/mcp.json) and expose their
+// tools to the agent, so z0gcode becomes a hub for 0G and third-party MCP tools.
+// The SDK is an optional dependency: if it or the config is missing, MCP is skipped.
+import { readFileSync, existsSync } from "node:fs";
+import path from "node:path";
+
+const CONFIG = (cwd) => path.join(cwd, ".z0g", "mcp.json");
+const PREFIX = "mcp_";
+
+const sanitize = (s) => String(s).replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 48);
+
+// Returns null (MCP disabled) or { tools, isMcp, call, close, count }.
+export async function loadMcp(cwd) {
+  const cfgPath = CONFIG(cwd);
+  if (!existsSync(cfgPath)) return null;
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+  } catch {
+    return null;
+  }
+  const servers = cfg.servers || cfg.mcpServers || {};
+  if (!Object.keys(servers).length) return null;
+
+  let Client, StdioClientTransport;
+  try {
+    ({ Client } = await import("@modelcontextprotocol/sdk/client/index.js"));
+    ({ StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js"));
+  } catch {
+    return null; // SDK not installed
+  }
+
+  const routes = {}; // agentToolName -> { client, remote }
+  const tools = [];
+  const conns = [];
+
+  for (const [name, spec] of Object.entries(servers)) {
+    if (!spec || !spec.command) continue;
+    try {
+      const transport = new StdioClientTransport({
+        command: spec.command,
+        args: spec.args || [],
+        env: { ...process.env, ...(spec.env || {}) },
+      });
+      const client = new Client({ name: "z0gcode", version: "0.2.0" }, { capabilities: {} });
+      await client.connect(transport);
+      conns.push(client);
+      const res = await client.listTools();
+      for (const t of res.tools || []) {
+        const toolName = `${PREFIX}${sanitize(name)}__${sanitize(t.name)}`;
+        routes[toolName] = { client, remote: t.name };
+        tools.push({
+          type: "function",
+          function: {
+            name: toolName,
+            description: `[MCP:${name}] ${t.description || t.name}`,
+            parameters: t.inputSchema && t.inputSchema.type ? t.inputSchema : { type: "object", properties: {} },
+          },
+        });
+      }
+    } catch {
+      // skip a server that fails to start/connect
+    }
+  }
+
+  return {
+    tools,
+    count: tools.length,
+    isMcp: (name) => !!routes[name],
+    async call(name, args) {
+      const r = routes[name];
+      if (!r) return { ok: false, summary: `mcp ${name} not found`, content: "unknown MCP tool" };
+      try {
+        const out = await r.client.callTool({ name: r.remote, arguments: args || {} });
+        const text = (out.content || [])
+          .map((x) => (x.type === "text" ? x.text : JSON.stringify(x)))
+          .join("\n");
+        return { ok: !out.isError, summary: `mcp ${name}`, content: text || "OK" };
+      } catch (e) {
+        return { ok: false, summary: `mcp ${name} error`, content: `ERROR: ${e.message}` };
+      }
+    },
+    async close() {
+      for (const c of conns) {
+        try {
+          await c.close();
+        } catch {}
+      }
+    },
+  };
+}

package/src/media.mjs

@@ -0,0 +1,52 @@
+// Media on the 0G Router: image generation (z-image-turbo, priced per image)
+// and speech-to-text (whisper-large-v3, priced per second). Same OpenAI-
+// compatible endpoints and 0G API key. Each call also returns its cost.
+import { createReadStream } from "node:fs";
+import { CONFIG } from "./config.mjs";
+
+async function pricingOf(client, modelId) {
+  try {
+    const res = await client.models.list();
+    return (res.data || []).find((m) => m.id === modelId)?.pricing_usd || null;
+  } catch {
+    return null;
+  }
+}
+
+// Generate images. Returns { images: base64 PNG[], cost }. n clamped to 1..2.
+export async function generateImage(client, { prompt, n = 1 }) {
+  const count = Math.max(1, Math.min(2, Number(n) || 1));
+  const res = await client.images.generate({ model: CONFIG.imageModel, prompt, n: count });
+  const images = (res?.data || []).map((d) => d.b64_json).filter(Boolean);
+  if (!images.length) throw new Error("no image data returned (expected base64)");
+  const pu = await pricingOf(client, CONFIG.imageModel);
+  const per = Number(pu?.image ?? pu?.prompt ?? 0);
+  const cost = per > 0 ? per * images.length : null;
+  return { images, cost };
+}
+
+// Transcribe an audio file. Returns { text, duration, cost }.
+export async function transcribeAudio(client, filePath) {
+  let res;
+  try {
+    res = await client.audio.transcriptions.create({
+      file: createReadStream(filePath),
+      model: CONFIG.transcribeModel,
+      response_format: "verbose_json",
+    });
+  } catch {
+    res = await client.audio.transcriptions.create({
+      file: createReadStream(filePath),
+      model: CONFIG.transcribeModel,
+    });
+  }
+  const text = (typeof res === "string" ? res : res?.text ?? "").trim();
+  const duration = Number(res?.duration) || null;
+  let cost = null;
+  if (duration) {
+    const pu = await pricingOf(client, CONFIG.transcribeModel);
+    const per = Number(pu?.prompt ?? 0);
+    if (per > 0) cost = per * duration;
+  }
+  return { text, duration, cost };
+}

package/src/models-info.mjs

@@ -0,0 +1,97 @@
+// Model catalog: fetch + normalize the 0G Router's GET /v1/models into the
+// fields the CLI renders (price, context, capabilities, TEE, discount).
+// All display data comes from the API; only the "vs official" discount is a
+// bundled reference (the Router API does not expose it).
+
+// "vs official API price" savings, from the 0G pricing page. Reference only:
+// the live price column always comes from the API, so if these drift the
+// numbers a user actually pays stay correct.
+export const DISCOUNTS = {
+  "minimax-m3": 55,
+  "0gm-1.0-35b-a3b": 50,
+  "qwen3.7-max": 60,
+  "qwen3.6-plus": 50,
+  "qwen3.7-plus": 45,
+  "glm-5": 40,
+  "glm-5.1": 35,
+  "glm-5.2": 30,
+  "kimi-k2.7-code": 18,
+  "deepseek-v4-pro": 15,
+  "deepseek-v4-flash": 12,
+  "claude-fable-5": 10,
+  "claude-opus-4-8": 10,
+};
+
+// Binary K, decimal M: 262144 -> "256K", 32768 -> "32K", 131072 -> "128K",
+// 1000000 -> "1M", 1048576 -> "1.0M" (the values developers recognize).
+export function fmtCtx(n) {
+  if (!n || n <= 0) return "?";
+  if (n >= 1_000_000) {
+    const v = n / 1_000_000;
+    return (Math.abs(v - 1) < 1e-9 ? "1" : v.toFixed(1)) + "M";
+  }
+  return Math.round(n / 1024) + "K";
+}
+
+// $/1M tokens, adaptive precision so tiny prices keep meaning.
+export function fmtPrice(perM) {
+  if (perM == null) return "-";
+  if (perM >= 100) return "$" + perM.toFixed(0);
+  if (perM >= 1) return "$" + perM.toFixed(2);
+  return "$" + perM.toFixed(perM < 0.1 ? 4 : 3);
+}
+
+function normalize(m) {
+  const im = m.architecture?.input_modalities || [];
+  const sp = m.supported_parameters || [];
+  const inUsd = Number(m.pricing_usd?.prompt);
+  const outUsd = Number(m.pricing_usd?.completion);
+  return {
+    id: m.id,
+    name: m.name || m.id,
+    description: m.description || "",
+    type: m.type || "chatbot",
+    ctx: m.context_length || null,
+    maxOut: m.max_completion_tokens || null,
+    inPerM: Number.isFinite(inUsd) && inUsd > 0 ? inUsd * 1e6 : null,
+    outPerM: Number.isFinite(outUsd) && outUsd > 0 ? outUsd * 1e6 : null,
+    tools: sp.includes("tools"),
+    vision: im.includes("image"),
+    verifiable: !!m.tee_attested && !!m.verifiability && m.verifiability !== "None",
+    private: m.verifiability === "TeeML",
+    tee: m.tee_type || null,
+    discount: DISCOUNTS[m.id] ?? null,
+    raw: m,
+  };
+}
+
+// Fetch and normalize. Returns [] on failure is NOT desired; let caller catch.
+export async function fetchModels(client) {
+  const res = await client.models.list();
+  return (res.data || []).map(normalize);
+}
+
+// Chat/coding models, ordered: default first, then verifiable+tools by input
+// price ascending, then the rest, then non-verifiable (e.g. proxied Claude).
+export function orderChatModels(models, defaultId) {
+  const chat = models.filter((m) => m.type === "chatbot");
+  const rank = (m) => {
+    if (m.id === defaultId) return 0;
+    if (m.verifiable && m.tools) return 1;
+    if (m.verifiable) return 2;
+    return 3;
+  };
+  return chat.sort((a, b) => {
+    const ra = rank(a);
+    const rb = rank(b);
+    if (ra !== rb) return ra - rb;
+    const pa = a.inPerM ?? Infinity;
+    const pb = b.inPerM ?? Infinity;
+    return pa - pb;
+  });
+}
+
+// Non-chat models (speech, image) for a separate compact section.
+export function mediaModels(models) {
+  return models.filter((m) => m.type !== "chatbot");
+}

package/src/plan.mjs

@@ -0,0 +1,21 @@
+// Plan/checklist: the agent maintains a visible todo list for multi-step tasks.
+// `dir` is the session directory (.z0g/sessions/<id>) so the plan is per-chat.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+const FILE = (dir) => path.join(dir, "plan.json");
+
+export async function savePlan(dir, plan) {
+  const f = FILE(dir);
+  await fs.mkdir(path.dirname(f), { recursive: true });
+  await fs.writeFile(f, JSON.stringify({ tool: "z0gcode", ts: new Date().toISOString(), plan }, null, 2), "utf8");
+}
+
+export async function loadPlan(dir) {
+  try {
+    const d = JSON.parse(await fs.readFile(FILE(dir), "utf8"));
+    return Array.isArray(d.plan) ? d.plan : null;
+  } catch {
+    return null;
+  }
+}

package/src/prompt.mjs

@@ -0,0 +1,149 @@
+// Dependency-free interactive prompts (raw ANSI). Currently: a single-select
+// list navigable with the arrow keys, decoupled from its look via renderFrame.
+import readline from "node:readline";
+
+// arrowSelect: navigate a list with the arrow keys, Enter to choose, Esc/Ctrl-C
+// to cancel. Resolves to the chosen item, or undefined if cancelled, or
+// { __action, item } when an action key fires. Resolves undefined immediately
+// when stdin/stdout is not a TTY so the caller can fall back (e.g. a number
+// prompt).
+//
+// Options:
+// - renderFrame(items, index, ctx) returns the ENTIRE multi-line frame; each
+//   logical line must fit the terminal width (caller truncates), or wrapping
+//   breaks the in-place redraw. ctx = { filter, filtering }.
+// - filterable: enable type-to-filter. While on, letters/digits build a filter
+//   (only the arrow keys navigate; j/k/q/1-9 become filter input); Esc clears
+//   the filter, or cancels when it is already empty.
+// - filterText(item): the text a filter matches against; return null to always
+//   keep the item visible (e.g. a "New chat" entry).
+// - onActionKey(key, str): return an action name for a key combo (e.g. ctrl-r);
+//   the promise resolves { __action: name, item: highlighted }.
+export function arrowSelect({ items, initialIndex = 0, renderFrame, clearOnExit = false, filterable = false, filterText, onActionKey }) {
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    if (!stdin.isTTY || !stdout.isTTY || !items || items.length === 0) {
+      resolve(undefined);
+      return;
+    }
+
+    let index = Math.min(Math.max(initialIndex | 0, 0), items.length - 1);
+    let filter = "";
+    let prevLines = 0;
+
+    const matches = (it) => {
+      if (!filterable || !filter) return true;
+      const t = filterText ? filterText(it) : String(it);
+      return t == null ? true : String(t).toLowerCase().includes(filter.toLowerCase());
+    };
+    const visible = () => (filterable ? items.filter(matches) : items);
+
+    readline.emitKeypressEvents(stdin);
+    const saved = stdin.listeners("keypress").slice();
+    for (const l of saved) stdin.removeListener("keypress", l);
+
+    const wasRaw = !!stdin.isRaw;
+    if (stdin.setRawMode) stdin.setRawMode(true);
+    stdin.resume();
+    stdout.write("\x1b[?25l"); // hide cursor
+
+    const clear = () => {
+      if (prevLines > 0) {
+        readline.moveCursor(stdout, 0, -prevLines);
+        readline.cursorTo(stdout, 0);
+        readline.clearScreenDown(stdout);
+      }
+    };
+    const draw = () => {
+      clear();
+      const vis = visible();
+      if (index >= vis.length) index = Math.max(0, vis.length - 1);
+      const frame = renderFrame(vis, index, { filter, filtering: filterable });
+      const body = frame.endsWith("\n") ? frame : frame + "\n";
+      stdout.write(body);
+      prevLines = (body.match(/\n/g) || []).length;
+    };
+    const cleanup = () => {
+      stdin.removeListener("keypress", onKey);
+      if (clearOnExit && prevLines > 0) {
+        readline.moveCursor(stdout, 0, -prevLines);
+        readline.cursorTo(stdout, 0);
+        readline.clearScreenDown(stdout);
+      }
+      stdout.write("\x1b[?25h"); // show cursor
+      try {
+        if (stdin.setRawMode) stdin.setRawMode(wasRaw);
+      } catch {}
+      for (const l of saved) stdin.on("keypress", l); // restore outer listeners
+    };
+    const finish = (val) => {
+      cleanup();
+      resolve(val);
+    };
+
+    const onKey = (str, key) => {
+      try {
+        key = key || {};
+        const vis = visible();
+        const len = vis.length;
+        if (onActionKey) {
+          const a = onActionKey(key, str);
+          if (a) {
+            finish({ __action: a, item: len ? vis[index] : null });
+            return;
+          }
+        }
+        if (key.name === "up" || (!filterable && key.name === "k")) {
+          if (len) index = (index - 1 + len) % len;
+          draw();
+        } else if (key.name === "down" || (!filterable && key.name === "j")) {
+          if (len) index = (index + 1) % len;
+          draw();
+        } else if (key.name === "return" || key.name === "enter") {
+          if (len) finish(vis[index]);
+        } else if ((key.ctrl && key.name === "c") || (key.ctrl && key.name === "d")) {
+          finish(undefined);
+        } else if (key.name === "escape") {
+          if (filterable && filter) {
+            filter = "";
+            index = 0;
+            draw();
+          } else finish(undefined);
+        } else if (!filterable && key.name === "q") {
+          finish(undefined);
+        } else if (key.name === "home" || (key.ctrl && key.name === "a")) {
+          index = 0;
+          draw();
+        } else if (key.name === "end" || (key.ctrl && key.name === "e")) {
+          index = Math.max(0, len - 1);
+          draw();
+        } else if (filterable && key.name === "backspace") {
+          filter = filter.slice(0, -1);
+          index = 0;
+          draw();
+        } else if (filterable && str && str.length === 1 && str >= " " && !key.ctrl) {
+          filter += str;
+          index = 0;
+          draw();
+        } else if (!filterable && str && /^[1-9]$/.test(str)) {
+          const n = Number(str) - 1;
+          if (n < items.length) {
+            index = n;
+            draw();
+          }
+        }
+      } catch {
+        finish(undefined); // never leave the terminal in raw mode on a render error
+      }
+    };
+
+    try {
+      draw();
+    } catch {
+      finish(undefined);
+      return;
+    }
+    stdin.on("keypress", onKey);
+  });
+}

package/src/provenance.mjs

@@ -0,0 +1,46 @@
+// Provenance manifest: binds every file change to the 0G model that produced it.
+// This is the verifiable-provenance differentiator: a closed-provider CLI cannot
+// prove which model wrote which code. We capture the model id and response id
+// reported by 0G plus the before/after hashes. Full TEE-quote verification is roadmap.
+import { promises as fs } from "node:fs";
+import crypto from "node:crypto";
+import path from "node:path";
+
+const sha256 = (s) => crypto.createHash("sha256").update(s ?? "", "utf8").digest("hex");
+
+// `dir` is the session directory (.z0g/sessions/<id>) so provenance is per-chat.
+const MANIFEST = (dir) => path.join(dir, "provenance.json");
+
+export function makeProvenance(dir) {
+  const file = MANIFEST(dir);
+  const entries = [];
+  return {
+    async record({ pathRel, before, after, model, responseId, trace }) {
+      // 0G returns an x_0g_trace with the on-chain provider node that served the
+      // request and a 0G request id: honest, verifiable TEE evidence.
+      const tee = trace ? { provider: trace.provider || null, request_id: trace.request_id || null } : null;
+      entries.push({
+        path: pathRel,
+        sha256_before: sha256(before),
+        sha256_after: sha256(after),
+        model: model || "unknown",
+        response_id: responseId || null,
+        tee_trace: tee,
+        ts: new Date().toISOString(),
+      });
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      await fs.writeFile(file, JSON.stringify({ tool: "z0gcode", provider: "0g-compute", entries }, null, 2), "utf8");
+    },
+    count() {
+      return entries.length;
+    },
+  };
+}
+
+export async function loadProvenance(dir) {
+  try {
+    return JSON.parse(await fs.readFile(MANIFEST(dir), "utf8"));
+  } catch {
+    return null;
+  }
+}

package/src/sessions.mjs

@@ -0,0 +1,168 @@
+// Multi-chat sessions per project. Each session lives in its own directory
+// under .z0g/sessions/<id>/ and isolates its conversation (session.json),
+// plan (plan.json), and provenance (provenance.json). File changes on disk are
+// shared across sessions; the recorded history/plan/provenance are not.
+import { promises as fs } from "node:fs";
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import path from "node:path";
+
+const root = (cwd) => path.join(cwd, ".z0g", "sessions");
+export const sessionDir = (cwd, id) => path.join(root(cwd), id);
+const sessionFile = (cwd, id) => path.join(sessionDir(cwd, id), "session.json");
+
+function genId() {
+  // Sortable: base36 timestamp + a short random suffix (unique per run).
+  const t = Date.now().toString(36);
+  const r = Math.floor(Math.random() * 1e7).toString(36);
+  return `${t}-${r}`;
+}
+
+// Auto-title from the first user message (single line, truncated).
+export function autoTitle(messages) {
+  const first = (messages || []).find(
+    (m) => m.role === "user" && typeof m.content === "string" && m.content.trim()
+  );
+  if (!first) return "New chat";
+  const t = first.content.trim().replace(/\s+/g, " ");
+  return t.length > 48 ? t.slice(0, 47) + "…" : t;
+}
+
+function countTurns(messages) {
+  return Array.isArray(messages) ? messages.filter((m) => m.role === "user" || m.role === "assistant").length : 0;
+}
+
+async function readSession(cwd, id) {
+  try {
+    return JSON.parse(await fs.readFile(sessionFile(cwd, id), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function createSession(cwd, { title = "" } = {}) {
+  const id = genId();
+  const now = new Date().toISOString();
+  const data = { tool: "z0gcode", id, title, created: now, updated: now, messages: [] };
+  await fs.mkdir(sessionDir(cwd, id), { recursive: true });
+  await fs.writeFile(sessionFile(cwd, id), JSON.stringify(data, null, 2), "utf8");
+  return { id, dir: sessionDir(cwd, id), title, history: [] };
+}
+
+export async function readMessages(cwd, id) {
+  const d = await readSession(cwd, id);
+  return d && Array.isArray(d.messages) && d.messages.length ? d.messages : null;
+}
+
+export async function saveMessages(cwd, id, messages) {
+  const d = (await readSession(cwd, id)) || { tool: "z0gcode", id, title: "", created: new Date().toISOString() };
+  d.messages = messages;
+  d.updated = new Date().toISOString();
+  if (!d.title) d.title = autoTitle(messages);
+  await fs.mkdir(sessionDir(cwd, id), { recursive: true });
+  await fs.writeFile(sessionFile(cwd, id), JSON.stringify(d, null, 2), "utf8");
+}
+
+// Sync listing (used before async flows and by the picker). Newest first.
+export function listSessions(cwd) {
+  const dir = root(cwd);
+  if (!existsSync(dir)) return [];
+  const out = [];
+  let ids = [];
+  try {
+    ids = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  for (const id of ids) {
+    const f = sessionFile(cwd, id);
+    if (!existsSync(f)) continue;
+    try {
+      const d = JSON.parse(readFileSync(f, "utf8"));
+      out.push({
+        id,
+        title: (d.title && d.title.trim()) || autoTitle(d.messages),
+        updated: d.updated || d.created || "",
+        messageCount: countTurns(d.messages),
+      });
+    } catch {}
+  }
+  out.sort((a, b) => String(b.updated).localeCompare(String(a.updated)));
+  return out;
+}
+
+export function hasSessions(cwd) {
+  return listSessions(cwd).length > 0;
+}
+
+export function mostRecent(cwd) {
+  const s = listSessions(cwd);
+  return s.length ? s[0].id : null;
+}
+
+export async function renameSession(cwd, id, title) {
+  const d = await readSession(cwd, id);
+  if (!d) return false;
+  const t = String(title || "").trim();
+  if (!t) return false;
+  d.title = t;
+  await fs.writeFile(sessionFile(cwd, id), JSON.stringify(d, null, 2), "utf8");
+  return true;
+}
+
+export async function deleteSession(cwd, id) {
+  await fs.rm(sessionDir(cwd, id), { recursive: true, force: true });
+}
+
+// Synchronous prune of a session that persisted no messages. Safe to call from
+// a SIGINT handler, where async cleanup would not run before the process exits.
+export function pruneEmptySync(cwd, id) {
+  try {
+    const s = listSessions(cwd).find((x) => x.id === id);
+    if (s && s.messageCount === 0) rmSync(sessionDir(cwd, id), { recursive: true, force: true });
+  } catch {}
+}
+
+// Import a legacy single .z0g/session.json (+ plan/provenance) as one session,
+// exactly once, so upgrading loses no history.
+export async function migrateLegacy(cwd) {
+  const legacy = path.join(cwd, ".z0g", "session.json");
+  if (!existsSync(legacy) || hasSessions(cwd)) return;
+  let messages = [];
+  try {
+    const d = JSON.parse(readFileSync(legacy, "utf8"));
+    messages = Array.isArray(d.messages) ? d.messages : [];
+  } catch {
+    messages = [];
+  }
+  if (messages.length) {
+    const { id } = await createSession(cwd, { title: autoTitle(messages) });
+    await saveMessages(cwd, id, messages);
+    for (const name of ["plan.json", "provenance.json"]) {
+      const src = path.join(cwd, ".z0g", name);
+      if (existsSync(src)) {
+        try {
+          await fs.copyFile(src, path.join(sessionDir(cwd, id), name));
+        } catch {}
+      }
+    }
+  }
+  try {
+    await fs.rename(legacy, legacy + ".migrated");
+  } catch {}
+}
+
+// Add .z0g/ to the project .gitignore (only in a git repo, only once) so
+// sessions and provenance are not committed by accident.
+export async function ensureGitignore(cwd) {
+  if (!existsSync(path.join(cwd, ".git"))) return;
+  const gi = path.join(cwd, ".gitignore");
+  let content = "";
+  try {
+    content = readFileSync(gi, "utf8");
+  } catch {}
+  if (/^\s*\.z0g\/?\s*$/m.test(content)) return; // already ignored
+  const prefix = content && !content.endsWith("\n") ? "\n" : "";
+  try {
+    await fs.appendFile(gi, prefix + ".z0g/\n");
+  } catch {}
+}

package/src/settings.mjs

@@ -0,0 +1,37 @@
+// User settings, persisted like Claude Code's settings.json.
+// Global: ~/.z0gcode/settings.json. Project overrides: <cwd>/.z0g/settings.json.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const GLOBAL_DIR = path.join(os.homedir(), ".z0gcode");
+const GLOBAL_FILE = path.join(GLOBAL_DIR, "settings.json");
+const projectFile = (cwd) => path.join(cwd, ".z0g", "settings.json");
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+// Merge global then project (project wins).
+export function loadSettings(cwd) {
+  const g = readJson(GLOBAL_FILE);
+  const p = cwd ? readJson(projectFile(cwd)) : {};
+  return { ...g, ...p };
+}
+
+// Save a key to the global settings file.
+export function saveSetting(key, value) {
+  const s = readJson(GLOBAL_FILE);
+  s[key] = value;
+  try {
+    mkdirSync(GLOBAL_DIR, { recursive: true });
+    writeFileSync(GLOBAL_FILE, JSON.stringify(s, null, 2) + "\n");
+  } catch {}
+  return s;
+}
+
+export const settingsPath = GLOBAL_FILE;