codetrellis 0.0.0-stage → 0.2.0

package/src/backend/mcp/tools/ui-tools.js

@@ -0,0 +1,356 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ui_tools_exports = {};
+__export(ui_tools_exports, {
+  register: () => register
+});
+module.exports = __toCommonJS(ui_tools_exports);
+var _lazy_______services_mdns_service = __toESM(require("../../services/mdns-service"));
+var import_node_fs = __toESM(require("node:fs"));
+var import_zod = require("zod");
+var import_grant_guard = require("../../services/grant-guard");
+function register(server, deps) {
+  server.registerTool(
+    "ui_ready",
+    {
+      description: "Is the CodeTrellis window actually usable right now? Reports whether the app shell is mounted, whether a blocking dialog covers it, whether a project is open, which workspace and side-panel tab are showing, which file or recorded file is on screen, and which acceptance criteria are visible and in what state. Call this before driving the UI: every other tool answers from the backend and will happily succeed while the window shows something else entirely.",
+      inputSchema: {}
+    },
+    async () => {
+      const nonce = `ur-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const p = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          deps.pendingResponses.delete(nonce);
+          reject(new Error("No answer from the window \u2014 is the CodeTrellis UI open?"));
+        }, 5e3);
+        deps.pendingResponses.set(nonce, { resolve, reject, timer });
+      });
+      deps.broadcast("ui-ready-request", { nonce });
+      try {
+        return { content: [{ type: "text", text: await p }] };
+      } catch (err) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              ready: false,
+              reason: err instanceof Error ? err.message : String(err)
+            })
+          }],
+          isError: true
+        };
+      }
+    }
+  );
+  server.registerTool(
+    "screenshot",
+    {
+      description: "Capture a screenshot of the CodeTrellis UI and return it as a base64-encoded PNG image. Use this to see the current state of the graph, plan workspace, terminal output, or any other part of the UI. The screenshot is taken from the connected browser/Electron window. Optionally target a specific panel to capture only that area.",
+      inputSchema: {
+        panel: import_zod.z.enum(["full", "graph", "plan", "terminal"]).optional().describe(
+          'Which panel to capture. "full" = entire window (default). "graph" = dependency graph canvas. "plan" = plan workspace. "terminal" = terminal panel.'
+        )
+      }
+    },
+    async ({ panel }) => {
+      if (deps.captureElectronScreenshot) {
+        try {
+          const base64 = await deps.captureElectronScreenshot();
+          return {
+            content: [{
+              type: "image",
+              data: base64,
+              mimeType: "image/png"
+            }]
+          };
+        } catch (err) {
+          return { content: [{ type: "text", text: `Electron screenshot failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        }
+      }
+      const nonce = `ss-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const target = panel ?? "full";
+      const p = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          deps.pendingResponses.delete(nonce);
+          reject(new Error("Screenshot timed out \u2014 is the CodeTrellis UI open in a browser?"));
+        }, 1e4);
+        deps.pendingResponses.set(nonce, { resolve, reject, timer });
+      });
+      deps.broadcast("ui-screenshot-request", { nonce, panel: target });
+      try {
+        const base64 = await p;
+        if (!base64) {
+          return { content: [{ type: "text", text: "Screenshot capture failed \u2014 the frontend returned empty data (html-to-image may have hit a canvas-tainting error)." }], isError: true };
+        }
+        return {
+          content: [{
+            type: "image",
+            data: base64,
+            mimeType: "image/png"
+          }]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }], isError: true };
+      }
+    }
+  );
+  server.registerTool(
+    "select_item",
+    {
+      description: "Navigate the plan workspace to a specific item by UID. The item will be selected in the sidebar tree and its body/properties will appear in the canvas. If the plan workspace is not open, it will be opened automatically.",
+      inputSchema: {
+        item_uid: import_zod.z.string().describe("UID of the plan item to select."),
+        plan_uid: import_zod.z.string().optional().describe("Plan UID (auto-detected from the item if omitted).")
+      }
+    },
+    async ({ item_uid, plan_uid }) => {
+      const item = deps.planItemService.getItem(item_uid);
+      if (!item) {
+        return { content: [{ type: "text", text: `Item ${item_uid} not found.` }], isError: true };
+      }
+      if (plan_uid && plan_uid !== item.planUid) {
+        return { content: [{ type: "text", text: `Item ${item_uid} is in plan ${item.planUid}, not ${plan_uid}.` }], isError: true };
+      }
+      const resolvedPlanUid = item.planUid;
+      deps.broadcast("ui-navigate", { target: "plan", planUid: resolvedPlanUid });
+      deps.broadcast("ui-select-item", { planUid: resolvedPlanUid, itemUid: item_uid });
+      return { content: [{ type: "text", text: `Selected item ${item_uid} in plan ${resolvedPlanUid}` }] };
+    }
+  );
+  server.registerTool(
+    "open_project",
+    {
+      description: "Open and scan a project directory in CodeTrellis. Parses the codebase, builds the dependency graph, and makes the project available to every tool that takes a project_path. Use this during onboarding to load a project for the first time.",
+      inputSchema: {
+        path: import_zod.z.string().describe("Absolute path to the project root directory.")
+      }
+    },
+    async ({ path: projectPath }) => {
+      try {
+        const stats = await deps.scanProject(projectPath);
+        deps.broadcast("ui-open-project", { path: projectPath });
+        return {
+          content: [{
+            type: "text",
+            text: `Opened ${projectPath} \u2014 ${stats.fileCount} files, ${stats.symbolCount} symbols, ${stats.importCount} imports (${stats.resolvedImports} resolved)`
+          }]
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: "text",
+            text: `Could not open ${projectPath}: ${err instanceof Error ? err.message : String(err)}`
+          }],
+          isError: true
+        };
+      }
+    }
+  );
+  server.registerTool(
+    "clipboard_write",
+    {
+      description: "Copy text to the user's clipboard. Use this to share code snippets, plan prompts, architecture summaries, or any text the user might want to paste elsewhere.",
+      inputSchema: {
+        text: import_zod.z.string().describe("The text to copy to the clipboard.")
+      }
+    },
+    async ({ text }) => {
+      deps.broadcast("ui-clipboard-write", { text });
+      return { content: [{ type: "text", text: `Copied ${text.length} chars to clipboard` }] };
+    }
+  );
+  server.registerTool(
+    "clipboard_read",
+    {
+      description: "Read the current contents of the user's clipboard. Useful for importing text the user has copied from another app (a GitHub issue, a Slack message, code from their editor, etc.).",
+      inputSchema: {}
+    },
+    async () => {
+      const nonce = `cb-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const p = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          deps.pendingResponses.delete(nonce);
+          reject(new Error("Clipboard read timed out \u2014 is the CodeTrellis UI open and focused?"));
+        }, 1e4);
+        deps.pendingResponses.set(nonce, { resolve, reject, timer });
+      });
+      deps.broadcast("ui-clipboard-read", { nonce });
+      try {
+        const text = await p;
+        return { content: [{ type: "text", text: text || "(clipboard is empty)" }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }], isError: true };
+      }
+    }
+  );
+  server.registerTool(
+    "get_settings",
+    {
+      description: "Read the current CodeTrellis settings \u2014 identity (display name, email), MCP server config (port, auto-detect), plan defaults (visibility, attachment location), and data directory.",
+      inputSchema: {}
+    },
+    async () => {
+      const settings = deps.getSettings();
+      return { content: [{ type: "text", text: JSON.stringify(settings, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "update_settings",
+    {
+      description: "Update CodeTrellis settings. Pass only the fields you want to change \u2014 unmentioned fields are preserved. Nested objects are deep-merged. Note: changing the MCP port requires a server restart to take effect.",
+      inputSchema: {
+        identity: import_zod.z.object({
+          displayName: import_zod.z.string().optional().describe("Display name shown in attributions."),
+          email: import_zod.z.string().optional().describe("Email used as canonical author key.")
+        }).optional().describe("Identity settings."),
+        mcp: import_zod.z.object({
+          port: import_zod.z.number().optional().describe("Preferred MCP port (default 19432)."),
+          autodetectOnCollision: import_zod.z.boolean().optional().describe("Try next ports if preferred is in use.")
+        }).optional().describe("MCP server settings."),
+        plans: import_zod.z.object({
+          defaultVisibility: import_zod.z.enum(["shared", "local"]).optional().describe('"shared" = export to .codetrellis/plans/, "local" = DB-only.'),
+          attachmentLocation: import_zod.z.enum(["project", "user"]).optional().describe('"project" = in repo, "user" = user data dir.')
+        }).optional().describe("Plan default settings."),
+        data: import_zod.z.object({
+          dataDirOverride: import_zod.z.string().optional().describe("Override for ~/.codetrellis/ data directory. Empty = default."),
+          personalSyncPath: import_zod.z.string().optional().describe("Path to personal sync folder (git repo, iCloud, Dropbox). Empty = no sync."),
+          personalSyncMode: import_zod.z.enum(["none", "selective", "full"]).optional().describe("What to sync: none, selective (settings+projects), or full (entire pantry).")
+        }).optional().describe("Data and sync settings."),
+        device: import_zod.z.object({
+          deviceName: import_zod.z.string().optional().describe("Human-readable name for this machine (shown to peers). Empty = hostname."),
+          advertise: import_zod.z.boolean().optional().describe("Whether to advertise via mDNS on the local network."),
+          shareAudio: import_zod.z.boolean().optional().describe("Whether to share audio capture with paired devices.")
+        }).optional().describe("Device discovery and pairing settings. Changes to advertise/deviceName take effect immediately (live mDNS restart)."),
+        firstRunComplete: import_zod.z.boolean().optional().describe("Set to true after the first-run wizard completes.")
+      }
+    },
+    async ({ identity, mcp, plans, data, device, firstRunComplete }) => {
+      const patch = {};
+      if (identity) patch.identity = identity;
+      if (mcp) patch.mcp = mcp;
+      if (plans) patch.plans = plans;
+      if (data) patch.data = data;
+      if (device) patch.device = device;
+      if (firstRunComplete !== void 0) patch.firstRunComplete = firstRunComplete;
+      const grant = (0, import_grant_guard.grantChange)(patch, deps.getSettings());
+      if (grant) {
+        return { content: [{ type: "text", text: (0, import_grant_guard.grantRefusal)(grant.field, grant.where) }], isError: true };
+      }
+      const updated = deps.updateSettings(patch);
+      if (device?.advertise !== void 0 || device?.deviceName !== void 0) {
+        try {
+          const mdns = _lazy_______services_mdns_service;
+          if (updated.device.advertise) {
+            mdns.startMdns(updated.device.deviceName || void 0);
+          } else {
+            mdns.stopMdns();
+          }
+        } catch {
+        }
+      }
+      deps.broadcast("settings-changed", { settings: updated });
+      const changes = [];
+      if (identity?.displayName !== void 0) changes.push(`display name \u2192 "${identity.displayName}"`);
+      if (identity?.email !== void 0) changes.push(`email \u2192 "${identity.email}"`);
+      if (mcp?.port !== void 0) changes.push(`MCP port \u2192 ${mcp.port} (restart needed)`);
+      if (mcp?.autodetectOnCollision !== void 0) changes.push(`auto-detect port \u2192 ${mcp.autodetectOnCollision}`);
+      if (plans?.defaultVisibility !== void 0) changes.push(`plan visibility \u2192 ${plans.defaultVisibility}`);
+      if (plans?.attachmentLocation !== void 0) changes.push(`attachment location \u2192 ${plans.attachmentLocation}`);
+      if (data?.personalSyncPath !== void 0) changes.push(`sync path \u2192 "${data.personalSyncPath}"`);
+      if (data?.personalSyncMode !== void 0) changes.push(`sync mode \u2192 ${data.personalSyncMode}`);
+      if (data?.dataDirOverride !== void 0) changes.push(`data dir \u2192 "${data.dataDirOverride || "(default)"}"`);
+      if (device?.deviceName !== void 0) changes.push(`device name \u2192 "${device.deviceName || "(hostname)"}"`);
+      if (device?.advertise !== void 0) changes.push(`mDNS advertise \u2192 ${device.advertise}`);
+      if (device?.shareAudio !== void 0) changes.push(`share audio with peers \u2192 ${device.shareAudio}`);
+      if (firstRunComplete !== void 0) changes.push(`first-run complete \u2192 ${firstRunComplete}`);
+      return { content: [{ type: "text", text: `Settings updated: ${changes.join(", ")}` }] };
+    }
+  );
+  server.registerTool(
+    "get_logs",
+    {
+      description: "Read the tail of the CodeTrellis application log. Returns the most recent log entries from the current day's log file. Useful for diagnosing errors, checking parse results, or understanding what happened during a scan or agent operation.",
+      inputSchema: {
+        lines: import_zod.z.number().optional().describe("Approximate number of lines to return (default ~500). Max constrained by 64KB."),
+        filter: import_zod.z.string().optional().describe("Optional grep-style filter \u2014 only return lines containing this string (case-insensitive).")
+      }
+    },
+    async ({ lines, filter }) => {
+      if (!import_node_fs.default.existsSync(deps.getCurrentLogPath())) {
+        return { content: [{ type: "text", text: "No log file: file logging runs in the CodeTrellis desktop app. This backend (web or dev build) logs to its console instead." }] };
+      }
+      const maxBytes = Math.min(Math.max(1, lines ?? 500) * 200, 64 * 1024);
+      let content = deps.tailLog(maxBytes);
+      if (filter) {
+        const lower = filter.toLowerCase();
+        content = content.split("\n").filter((line) => line.toLowerCase().includes(lower)).join("\n");
+      }
+      if (!content.trim()) {
+        return { content: [{ type: "text", text: "(no log entries found)" }] };
+      }
+      return { content: [{ type: "text", text: content }] };
+    }
+  );
+  server.registerTool(
+    "get_log_path",
+    {
+      description: "Get the path to the current log file and logs directory. Useful if the agent needs to tell the user where to find logs, or to read logs directly from disk.",
+      inputSchema: {}
+    },
+    async () => {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            currentLogFile: deps.getCurrentLogPath(),
+            logDirectory: deps.getLogDir()
+          }, null, 2)
+        }]
+      };
+    }
+  );
+  server.registerTool(
+    "get_app_guide",
+    {
+      description: 'Get instructions on how to use CodeTrellis. Returns a comprehensive markdown guide covering available MCP tools, workflows, and best practices. Seven flavors: "summary" = project-state-tailored overview with active plans and agents, "quickstart" = minimum viable agent workflow (register \u2192 find plan \u2192 claim \u2192 work \u2192 verify \u2192 done), "power-user" = deep features (phased plans, multi-agent, spec docs, drift, snapshots), "ui-nav" = focused UI navigation skill for sub-agents that drive the interface while the primary agent works, "diagnostics" = logs, settings, baseline, drift detection, architecture conformity, "multi-agent" = terminals, claiming, handoff patterns, session registration, approval gates, "parallel" = working alongside agents in other worktrees: get_awareness, declare_intent, check_footprint, acknowledge_signal.',
+      inputSchema: {
+        flavor: import_zod.z.enum(["summary", "quickstart", "power-user", "ui-nav", "diagnostics", "multi-agent", "parallel"]).optional().describe(
+          'Which guide to return. Default "summary". Use "quickstart" for first-time setup, "power-user" for advanced features, "ui-nav" for a sub-agent driving the UI, "diagnostics" for logs/settings/drift, "multi-agent" for terminal/claim/handoff workflows, "parallel" when other agents work in other worktrees of this repository.'
+        )
+      }
+    },
+    async ({ flavor }) => {
+      const guide = deps.buildSkillGuide(flavor ?? "summary");
+      return { content: [{ type: "text", text: guide }] };
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  register
+});

package/src/backend/mcp/types.js

@@ -0,0 +1,15 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/src/backend/middleware/local-auth.js

@@ -0,0 +1,116 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var local_auth_exports = {};
+__export(local_auth_exports, {
+  isUpgradeAuthorised: () => isUpgradeAuthorised,
+  localAuthMiddleware: () => localAuthMiddleware
+});
+module.exports = __toCommonJS(local_auth_exports);
+var import_capability_token = require("../services/capability-token");
+const ALLOWED_HOSTS = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
+function allowedOrigins() {
+  const set = /* @__PURE__ */ new Set();
+  if (process.env.NODE_ENV !== "production") {
+    const devPort = process.env.CODETRELLIS_DEV_ORIGIN_PORT || "5173";
+    set.add(`http://localhost:${devPort}`);
+    set.add(`http://127.0.0.1:${devPort}`);
+  }
+  const extra = process.env.CODETRELLIS_EXTRA_ORIGIN;
+  if (extra) set.add(extra);
+  return set;
+}
+function isPublicPath(pathname) {
+  return pathname === "/api/health";
+}
+function localAuthMiddleware(req, res, next) {
+  const origin = req.headers.origin;
+  const hostHeader = (req.headers.host || "").toString();
+  const hostname = hostHeader.replace(/:\d+$/, "").toLowerCase();
+  if (hostname && !ALLOWED_HOSTS.has(hostname)) {
+    res.status(403).json({ error: "Host not allowed" });
+    return;
+  }
+  if (origin) {
+    if (allowedOrigins().has(origin)) {
+      res.setHeader("Access-Control-Allow-Origin", origin);
+      res.setHeader("Access-Control-Allow-Credentials", "true");
+      res.setHeader("Vary", "Origin");
+    } else {
+      res.setHeader("Vary", "Origin");
+      if (!isPublicPath(req.path)) {
+        res.status(403).json({ error: "Origin not allowed" });
+        return;
+      }
+    }
+  }
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, PATCH, OPTIONS");
+  res.setHeader(
+    "Access-Control-Allow-Headers",
+    `Content-Type, Authorization, ${import_capability_token.TOKEN_HEADER}`
+  );
+  if (req.method === "OPTIONS") {
+    if (origin && !allowedOrigins().has(origin)) {
+      res.status(403).end();
+      return;
+    }
+    res.sendStatus(204);
+    return;
+  }
+  if (isPublicPath(req.path)) {
+    next();
+    return;
+  }
+  const token = (0, import_capability_token.extractToken)(
+    req.headers,
+    req.originalUrl || req.url
+  );
+  if (!(0, import_capability_token.verifyCapabilityToken)(token)) {
+    res.status(401).json({
+      error: "Missing or invalid capability token",
+      // Tell a legitimate local client how to authenticate. This leaks
+      // nothing to a browser: it is the PATH of the token file, not its
+      // contents, and anything that can read that path could have read the
+      // file without being told.
+      hint: `Send the token from <dataDir>/capability-token as the ${import_capability_token.TOKEN_HEADER} header, an Authorization: Bearer value, or the ${import_capability_token.TOKEN_QUERY_PARAM} query parameter.`
+    });
+    return;
+  }
+  next();
+}
+function isUpgradeAuthorised(headers, url) {
+  const hostHeader = (headers.host || "").toString();
+  const hostname = hostHeader.replace(/:\d+$/, "").toLowerCase();
+  if (hostname && !ALLOWED_HOSTS.has(hostname)) {
+    return { ok: false, reason: "Host not allowed" };
+  }
+  const originRaw = headers.origin;
+  const origin = Array.isArray(originRaw) ? originRaw[0] : originRaw;
+  if (origin && !allowedOrigins().has(origin)) {
+    return { ok: false, reason: "Origin not allowed" };
+  }
+  const token = (0, import_capability_token.extractToken)(headers, url);
+  if (!(0, import_capability_token.verifyCapabilityToken)(token)) {
+    return { ok: false, reason: "Missing or invalid capability token" };
+  }
+  return { ok: true };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isUpgradeAuthorised,
+  localAuthMiddleware
+});