fast-context-skill 0.1.0

package/src/extract-key.mjs

@@ -0,0 +1,93 @@
+/**
+ * Windsurf API Key extraction from local installation.
+ *
+ * Cross-platform: macOS / Windows / Linux.
+ * Uses sql.js (pure JS/WASM) to read state.vscdb — no native compilation needed.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir, platform } from "node:os";
+import initSqlJs from "sql.js";
+
+/**
+ * Get the platform-specific path to Windsurf's state.vscdb.
+ * @returns {string}
+ */
+export function getDbPath() {
+  const plat = platform();
+  const home = homedir();
+
+  if (plat === "darwin") {
+    return join(home, "Library", "Application Support", "Windsurf", "User", "globalStorage", "state.vscdb");
+  } else if (plat === "win32") {
+    const appdata = process.env.APPDATA || "";
+    if (!appdata) throw new Error("Cannot determine APPDATA path");
+    return join(appdata, "Windsurf", "User", "globalStorage", "state.vscdb");
+  } else {
+    // Linux
+    const config = process.env.XDG_CONFIG_HOME || join(home, ".config");
+    return join(config, "Windsurf", "User", "globalStorage", "state.vscdb");
+  }
+}
+
+/**
+ * Extract API Key from Windsurf state.vscdb.
+ * @param {string} [dbPath]
+ * @returns {Promise<{ api_key?: string, db_path: string, error?: string, hint?: string }>}
+ */
+export async function extractKey(dbPath) {
+  if (!dbPath) {
+    dbPath = getDbPath();
+  }
+
+  if (!existsSync(dbPath)) {
+    return {
+      error: `Windsurf database not found: ${dbPath}`,
+      hint: "Ensure Windsurf is installed and logged in.",
+      db_path: dbPath,
+    };
+  }
+
+  let db;
+  try {
+    const SQL = await initSqlJs();
+    const buf = readFileSync(dbPath);
+    db = new SQL.Database(buf);
+  } catch (e) {
+    return { error: `Failed to open database: ${e.message}`, db_path: dbPath };
+  }
+
+  try {
+    const stmt = db.prepare("SELECT value FROM ItemTable WHERE key = 'windsurfAuthStatus'");
+    if (!stmt.step()) {
+      stmt.free();
+      return {
+        error: "windsurfAuthStatus record not found",
+        hint: "Ensure Windsurf is logged in.",
+        db_path: dbPath,
+      };
+    }
+
+    const row = stmt.getAsObject();
+    stmt.free();
+
+    let data;
+    try {
+      data = JSON.parse(row.value);
+    } catch {
+      return { error: "windsurfAuthStatus data parse failed", db_path: dbPath };
+    }
+
+    const apiKey = data.apiKey || "";
+    if (!apiKey) {
+      return { error: "apiKey field is empty", db_path: dbPath };
+    }
+
+    return { api_key: apiKey, db_path: dbPath };
+  } catch (e) {
+    return { error: `Extraction failed: ${e.message}`, db_path: dbPath };
+  } finally {
+    db.close();
+  }
+}

package/src/project-path.mjs

@@ -0,0 +1,47 @@
+import { statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+
+export const PROJECT_PATH_REQUIRED_MESSAGE =
+  "project_path is required. Pass the absolute path to the project root directory.";
+
+export const projectPathSchema = z
+  .string()
+  .trim()
+  .min(1, PROJECT_PATH_REQUIRED_MESSAGE);
+
+/**
+ * Validate the project root path provided to fast_context_search.
+ * Returns null when valid, otherwise an MCP-friendly error string.
+ *
+ * @param {string} projectPath
+ * @param {(path: string) => import("node:fs").Stats} [statFn]
+ * @returns {string|null}
+ */
+export function validateProjectPath(projectPath, statFn = statSync) {
+  if (!projectPath) {
+    return `Error: ${PROJECT_PATH_REQUIRED_MESSAGE}`;
+  }
+
+  if (!isAbsolute(projectPath)) {
+    return `Error: project_path must be an absolute path, got: ${projectPath}`;
+  }
+
+  try {
+    const st = statFn(projectPath);
+    if (!st.isDirectory()) {
+      return `Error: project_path is not a directory: ${projectPath}`;
+    }
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return `Error: project_path does not exist: ${projectPath}`;
+    }
+    if (error?.code === "EACCES" || error?.code === "EPERM") {
+      return `Error: cannot access project_path (${error.code}): ${projectPath}`;
+    }
+    const reason = error?.message ? `${error.code || "UNKNOWN"}: ${error.message}` : String(error);
+    return `Error: failed to validate project_path: ${reason}`;
+  }
+
+  return null;
+}

package/src/protobuf.mjs

@@ -0,0 +1,235 @@
+/**
+ * Hand-written Protobuf encoder/decoder + Connect-RPC frame handling.
+ *
+ * Matches the Windsurf wire format exactly.
+ * Python bytearray → Node.js Buffer
+ * struct.pack(">I", len) → buf.writeUInt32BE
+ * gzip.compress/decompress → zlib.gzipSync/gunzipSync
+ */
+
+import { gzipSync, gunzipSync } from "node:zlib";
+
+// ─── Protobuf Encoder ──────────────────────────────────────
+
+export class ProtobufEncoder {
+  constructor() {
+    /** @type {Buffer[]} */
+    this._chunks = [];
+  }
+
+  /**
+   * Encode an unsigned varint into a Buffer.
+   * @param {number} value
+   * @returns {Buffer}
+   */
+  _varint(value) {
+    const bytes = [];
+    while (value > 0x7f) {
+      bytes.push((value & 0x7f) | 0x80);
+      value >>>= 7;
+    }
+    bytes.push(value & 0x7f);
+    return Buffer.from(bytes);
+  }
+
+  /**
+   * Encode a field tag.
+   * @param {number} field
+   * @param {number} wire
+   * @returns {Buffer}
+   */
+  _tag(field, wire) {
+    return this._varint((field << 3) | wire);
+  }
+
+  /**
+   * Write a varint field.
+   * @param {number} field
+   * @param {number} value
+   * @returns {ProtobufEncoder}
+   */
+  writeVarint(field, value) {
+    this._chunks.push(this._tag(field, 0), this._varint(value));
+    return this;
+  }
+
+  /**
+   * Write a length-delimited string field.
+   * @param {number} field
+   * @param {string} value
+   * @returns {ProtobufEncoder}
+   */
+  writeString(field, value) {
+    const data = Buffer.from(value, "utf-8");
+    this._chunks.push(this._tag(field, 2), this._varint(data.length), data);
+    return this;
+  }
+
+  /**
+   * Write a length-delimited bytes field.
+   * @param {number} field
+   * @param {Buffer|Uint8Array} value
+   * @returns {ProtobufEncoder}
+   */
+  writeBytes(field, value) {
+    const buf = Buffer.isBuffer(value) ? value : Buffer.from(value);
+    this._chunks.push(this._tag(field, 2), this._varint(buf.length), buf);
+    return this;
+  }
+
+  /**
+   * Write a nested message field.
+   * @param {number} field
+   * @param {ProtobufEncoder} sub
+   * @returns {ProtobufEncoder}
+   */
+  writeMessage(field, sub) {
+    const data = sub.toBuffer();
+    this._chunks.push(this._tag(field, 2), this._varint(data.length), data);
+    return this;
+  }
+
+  /**
+   * Return the encoded bytes as a Buffer.
+   * @returns {Buffer}
+   */
+  toBuffer() {
+    return Buffer.concat(this._chunks);
+  }
+}
+
+// ─── Varint Decode ─────────────────────────────────────────
+
+/**
+ * Decode a varint from a buffer at the given offset.
+ * @param {Buffer} buf
+ * @param {number} offset
+ * @returns {[number, number]} [value, newOffset]
+ */
+export function decodeVarint(buf, offset) {
+  let value = 0;
+  let shift = 0;
+  while (offset < buf.length) {
+    const b = buf[offset++];
+    value |= (b & 0x7f) << shift;
+    shift += 7;
+    if (!(b & 0x80)) break;
+  }
+  return [value, offset];
+}
+
+// ─── Protobuf String Extraction ────────────────────────────
+
+/**
+ * Extract all UTF-8 strings (length > 5) from raw protobuf data
+ * by parsing wire types. Matches Python proto_extract_strings().
+ * @param {Buffer} data
+ * @returns {string[]}
+ */
+export function extractStrings(data) {
+  const strings = [];
+  let i = 0;
+  while (i < data.length) {
+    // Read tag varint
+    let tag = 0;
+    let shift = 0;
+    while (i < data.length) {
+      const b = data[i++];
+      tag |= (b & 0x7f) << shift;
+      shift += 7;
+      if (!(b & 0x80)) break;
+    }
+    const wire = tag & 0x7;
+    if (wire === 0) {
+      // Varint — skip
+      while (i < data.length) {
+        const b = data[i++];
+        if (!(b & 0x80)) break;
+      }
+    } else if (wire === 1) {
+      // 64-bit fixed
+      i += 8;
+    } else if (wire === 2) {
+      // Length-delimited
+      let length = 0;
+      shift = 0;
+      while (i < data.length) {
+        const b = data[i++];
+        length |= (b & 0x7f) << shift;
+        shift += 7;
+        if (!(b & 0x80)) break;
+      }
+      if (i + length <= data.length) {
+        const raw = data.subarray(i, i + length);
+        try {
+          const text = raw.toString("utf-8");
+          if (text.length > 5) {
+            strings.push(text);
+          }
+        } catch {
+          // Not valid UTF-8, skip
+        }
+      }
+      i += length;
+    } else if (wire === 5) {
+      // 32-bit fixed
+      i += 4;
+    } else {
+      // Unknown wire type — stop
+      break;
+    }
+  }
+  return strings;
+}
+
+// ─── Connect-RPC Frame Encode/Decode ───────────────────────
+
+/**
+ * Encode protobuf bytes into a gzip-compressed Connect-RPC frame.
+ * Frame format: 1-byte flags + 4-byte big-endian length + payload
+ * @param {Buffer} protoBytes
+ * @param {boolean} [compress=true]
+ * @returns {Buffer}
+ */
+export function connectFrameEncode(protoBytes, compress = true) {
+  let payload;
+  let flags;
+  if (compress) {
+    payload = gzipSync(protoBytes);
+    flags = 1; // gzip compressed
+  } else {
+    payload = protoBytes;
+    flags = 0;
+  }
+  const header = Buffer.alloc(5);
+  header[0] = flags;
+  header.writeUInt32BE(payload.length, 1);
+  return Buffer.concat([header, payload]);
+}
+
+/**
+ * Decode Connect-RPC frames from raw response data.
+ * Handles gzip-compressed frames (flags 1 or 3).
+ * @param {Buffer} data
+ * @returns {Buffer[]}
+ */
+export function connectFrameDecode(data) {
+  const frames = [];
+  let i = 0;
+  while (i + 5 <= data.length) {
+    const flags = data[i];
+    const length = data.readUInt32BE(i + 1);
+    i += 5;
+    let payload = data.subarray(i, i + length);
+    i += length;
+    if (flags === 1 || flags === 3) {
+      try {
+        payload = gunzipSync(payload);
+      } catch {
+        // Decompression failed — use raw payload
+      }
+    }
+    frames.push(Buffer.from(payload));
+  }
+  return frames;
+}