@meshxdata/fops 0.0.5 → 0.0.7

package/src/plugins/bundled/coda/auth.js

@@ -0,0 +1,85 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { execSync } from "node:child_process";
+
+const CREDENTIALS_PATH = path.join(os.homedir(), ".fops", "plugins", "coda", ".credentials.json");
+const CODA_ACCOUNT_URL = "https://coda.io/account";
+
+/**
+ * Prompt for a single line of input from the terminal.
+ */
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Load saved credentials from disk.
+ */
+export function loadCredentials() {
+  try {
+    if (!fs.existsSync(CREDENTIALS_PATH)) return null;
+    const raw = JSON.parse(fs.readFileSync(CREDENTIALS_PATH, "utf8"));
+    if (!raw.access_token) return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save credentials to disk (mode 0o600).
+ */
+function saveCredentials(creds) {
+  const dir = path.dirname(CREDENTIALS_PATH);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  fs.writeFileSync(CREDENTIALS_PATH, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
+}
+
+/**
+ * Open a URL in the user's default browser.
+ */
+function openBrowser(url) {
+  try {
+    if (process.platform === "win32") {
+      execSync(`cmd /c start "" "${url}"`, { stdio: "ignore" });
+    } else {
+      const cmd = process.platform === "darwin" ? "open" : "xdg-open";
+      execSync(`${cmd} '${url}'`, { stdio: "ignore" });
+    }
+  } catch {}
+}
+
+/**
+ * Run the Coda login flow — prompt user for an API token.
+ * Returns true on success, false on failure.
+ */
+export async function runCodaLogin() {
+  console.log("\n  Coda API Token Setup");
+  console.log("  ────────────────────");
+  console.log(`  1. Go to ${CODA_ACCOUNT_URL}`);
+  console.log("  2. Scroll to \"API Settings\"");
+  console.log("  3. Click \"Generate API token\" and copy it\n");
+
+  openBrowser(CODA_ACCOUNT_URL);
+
+  const token = await ask("  API token: ");
+  if (!token) {
+    console.log("\n  Aborted.\n");
+    return false;
+  }
+
+  saveCredentials({ access_token: token });
+
+  console.log("\n  Saved to ~/.fops/plugins/coda/.credentials.json\n");
+  return true;
+}

package/src/plugins/bundled/coda/client.js

@@ -0,0 +1,187 @@
+import https from "node:https";
+import { URL, URLSearchParams } from "node:url";
+
+const BASE_URL = "https://coda.io/apis/v1";
+
+/**
+ * Simple sliding-window rate limiter.
+ * Tracks timestamps of recent requests and delays when the window is full.
+ */
+class RateLimiter {
+  constructor(maxRequests, windowMs) {
+    this.maxRequests = maxRequests;
+    this.windowMs = windowMs;
+    this.timestamps = [];
+  }
+
+  async wait() {
+    const now = Date.now();
+    this.timestamps = this.timestamps.filter((t) => now - t < this.windowMs);
+
+    if (this.timestamps.length >= this.maxRequests) {
+      const oldest = this.timestamps[0];
+      const delay = this.windowMs - (now - oldest) + 50; // 50ms buffer
+      await new Promise((r) => setTimeout(r, delay));
+    }
+
+    this.timestamps.push(Date.now());
+  }
+}
+
+// Conservative limits under Coda's hard caps (100 reads/6s, 4 doc listings/6s)
+const readLimiter = new RateLimiter(90, 6000);
+const docListLimiter = new RateLimiter(3, 6000);
+
+/**
+ * Make an HTTPS request to the Coda API.
+ */
+function request(method, path, token, body) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, BASE_URL + "/");
+    const options = {
+      hostname: url.hostname,
+      port: 443,
+      path: url.pathname + url.search,
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+    };
+
+    if (body) {
+      const encoded = JSON.stringify(body);
+      options.headers["Content-Length"] = Buffer.byteLength(encoded);
+    }
+
+    const req = https.request(options, (res) => {
+      let data = "";
+      res.on("data", (chunk) => { data += chunk; });
+      res.on("end", () => {
+        if (res.statusCode === 401 || res.statusCode === 403) {
+          reject(new Error(`Coda auth error (${res.statusCode}). Run: fops coda login`));
+          return;
+        }
+        if (res.statusCode === 429) {
+          reject(new Error("Coda rate limit exceeded. Wait a moment and retry."));
+          return;
+        }
+        if (res.statusCode >= 400) {
+          let msg = `Coda API error ${res.statusCode}`;
+          try { msg = JSON.parse(data).message || msg; } catch {}
+          reject(new Error(msg));
+          return;
+        }
+        try {
+          resolve(JSON.parse(data));
+        } catch {
+          reject(new Error(`Invalid JSON from Coda API: ${data.slice(0, 200)}`));
+        }
+      });
+    });
+
+    req.on("error", reject);
+    if (body) req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+/**
+ * Coda API client.
+ */
+export class CodaClient {
+  constructor(token) {
+    this.token = token;
+  }
+
+  /** GET /whoami — verify token and get user info */
+  async whoami() {
+    await readLimiter.wait();
+    return request("GET", `${BASE_URL}/whoami`, this.token);
+  }
+
+  /** GET /docs — list or search docs */
+  async listDocs(query) {
+    await docListLimiter.wait();
+    let url = `${BASE_URL}/docs`;
+    if (query) url += `?query=${encodeURIComponent(query)}`;
+    return request("GET", url, this.token);
+  }
+
+  /** GET /docs/{docId}/pages — list pages in a doc */
+  async listPages(docId) {
+    await readLimiter.wait();
+    return request("GET", `${BASE_URL}/docs/${docId}/pages`, this.token);
+  }
+
+  /**
+   * Export a page as markdown (or html).
+   * POST /docs/{docId}/pages/{pageId}/export → poll until ready → return content.
+   */
+  async exportPage(docId, pageId, format = "markdown") {
+    await readLimiter.wait();
+    const exportReq = await request(
+      "POST",
+      `${BASE_URL}/docs/${docId}/pages/${pageId}/export`,
+      this.token,
+      { outputFormat: format },
+    );
+
+    const requestId = exportReq.id;
+    const deadline = Date.now() + 30_000;
+
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 1000));
+      await readLimiter.wait();
+
+      const status = await request(
+        "GET",
+        `${BASE_URL}/docs/${docId}/pages/${pageId}/export/${requestId}`,
+        this.token,
+      );
+
+      if (status.status === "complete") {
+        return status.downloadLink
+          ? await this._fetchDownload(status.downloadLink)
+          : status;
+      }
+
+      if (status.status === "failed") {
+        throw new Error(`Page export failed: ${status.error || "unknown"}`);
+      }
+    }
+
+    throw new Error("Page export timed out after 30s");
+  }
+
+  /** GET /docs/{docId}/tables — list tables */
+  async listTables(docId) {
+    await readLimiter.wait();
+    return request("GET", `${BASE_URL}/docs/${docId}/tables`, this.token);
+  }
+
+  /** GET /docs/{docId}/tables/{tableId}/rows — list/query rows */
+  async listRows(docId, tableId, query) {
+    await readLimiter.wait();
+    let url = `${BASE_URL}/docs/${docId}/tables/${tableId}/rows`;
+    if (query) url += `?query=${encodeURIComponent(query)}`;
+    return request("GET", url, this.token);
+  }
+
+  /** Fetch raw content from a download link (returned by export). */
+  _fetchDownload(url) {
+    return new Promise((resolve, reject) => {
+      const parsed = new URL(url);
+      https.get(parsed, (res) => {
+        // Follow redirects
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          this._fetchDownload(res.headers.location).then(resolve, reject);
+          return;
+        }
+        let data = "";
+        res.on("data", (chunk) => { data += chunk; });
+        res.on("end", () => resolve(data));
+      }).on("error", reject);
+    });
+  }
+}

package/src/plugins/bundled/coda/fops.plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "coda",
+  "name": "Coda Knowledge Base",
+  "version": "0.1.0",
+  "description": "Interactive Coda knowledge base for the fops agent",
+  "skills": ["skills/coda"]
+}

package/src/plugins/bundled/coda/index.js

@@ -0,0 +1,284 @@
+import { CodaClient } from "./client.js";
+import { loadCredentials, runCodaLogin } from "./auth.js";
+
+function getClient() {
+  const creds = loadCredentials();
+  if (!creds) {
+    console.error("Not authenticated with Coda. Run: fops coda login");
+    process.exit(1);
+  }
+  return new CodaClient(creds.access_token);
+}
+
+export default {
+  async register(api) {
+    const config = api.config;
+
+    // ── Register "fops coda" command group ──────────────────────────────
+    api.registerCommand((program) => {
+      const coda = program
+        .command("coda")
+        .description("Coda knowledge base");
+
+      // fops coda login
+      coda
+        .command("login")
+        .description("Authenticate with Coda (API token)")
+        .action(async () => {
+          const ok = await runCodaLogin();
+          if (!ok) process.exit(1);
+        });
+
+      // fops coda whoami
+      coda
+        .command("whoami")
+        .description("Show current Coda user")
+        .action(async () => {
+          try {
+            const client = getClient();
+            const user = await client.whoami();
+            console.log(`Logged in as: ${user.name} (${user.loginId})`);
+          } catch (err) {
+            console.error(err.message);
+            process.exit(1);
+          }
+        });
+
+      // fops coda docs [-q <query>]
+      coda
+        .command("docs")
+        .description("List or search Coda docs")
+        .option("-q, --query <query>", "Filter docs by name")
+        .action(async (opts) => {
+          try {
+            const client = getClient();
+            const result = await client.listDocs(opts.query);
+            const docs = result.items || [];
+
+            if (docs.length === 0) {
+              console.log(opts.query ? `No docs matching "${opts.query}"` : "No docs found");
+              return;
+            }
+
+            for (const doc of docs) {
+              console.log(`${doc.id}  ${doc.name}`);
+            }
+            console.log(`\n${docs.length} doc(s) found`);
+          } catch (err) {
+            console.error(err.message);
+            process.exit(1);
+          }
+        });
+
+      // fops coda search <query>
+      coda
+        .command("search <query>")
+        .description("Search docs and pages by name")
+        .action(async (query) => {
+          try {
+            const client = getClient();
+            const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+            const matches = (text) => words.every((w) => text.toLowerCase().includes(w));
+
+            // Fetch all docs (no query filter — API only searches doc names)
+            const result = await client.listDocs();
+            const docs = result.items || [];
+
+            let found = false;
+
+            for (const doc of docs) {
+              const docMatches = matches(doc.name);
+
+              let pages = [];
+              try {
+                const pageResult = await client.listPages(doc.id);
+                pages = pageResult.items || [];
+              } catch {
+                // skip if pages can't be listed
+              }
+
+              const matchingPages = pages.filter((p) => matches(p.name));
+
+              if (!docMatches && matchingPages.length === 0) continue;
+
+              found = true;
+              console.log(`\n── ${doc.name} (${doc.id}) ──`);
+
+              if (docMatches) {
+                // Doc name matches → show all pages
+                for (const page of pages) {
+                  const marker = matches(page.name) ? " ◀" : "";
+                  console.log(`  ${page.id}  ${page.name}${marker}`);
+                }
+              } else {
+                // Only page names match → show matching pages
+                for (const page of matchingPages) {
+                  console.log(`  ${page.id}  ${page.name} ◀`);
+                }
+              }
+            }
+
+            if (!found) {
+              console.log(`No docs or pages matching "${query}"`);
+            }
+          } catch (err) {
+            console.error(err.message);
+            process.exit(1);
+          }
+        });
+
+      // fops coda read <docId> [pageId]
+      coda
+        .command("read <docId> [pageId]")
+        .description("List pages or read a page as markdown")
+        .action(async (docId, pageId) => {
+          try {
+            const client = getClient();
+
+            if (!pageId) {
+              // List pages
+              const result = await client.listPages(docId);
+              const pages = result.items || [];
+
+              if (pages.length === 0) {
+                console.log("No pages in this doc");
+                return;
+              }
+
+              for (const page of pages) {
+                console.log(`${page.id}  ${page.name}`);
+              }
+              console.log(`\n${pages.length} page(s). Read one with: fops coda read ${docId} <pageId>`);
+              return;
+            }
+
+            // Export page as markdown
+            const content = await client.exportPage(docId, pageId);
+            console.log(typeof content === "string" ? content : JSON.stringify(content, null, 2));
+          } catch (err) {
+            console.error(err.message);
+            process.exit(1);
+          }
+        });
+
+      // fops coda tables <docId> [-t <tableId>] [-q <query>]
+      coda
+        .command("tables <docId>")
+        .description("List tables or query rows")
+        .option("-t, --table <tableId>", "Table ID to query rows from")
+        .option("-q, --query <query>", "Query to filter rows")
+        .action(async (docId, opts) => {
+          try {
+            const client = getClient();
+
+            if (!opts.table) {
+              // List tables
+              const result = await client.listTables(docId);
+              const tables = result.items || [];
+
+              if (tables.length === 0) {
+                console.log("No tables in this doc");
+                return;
+              }
+
+              for (const t of tables) {
+                console.log(`${t.id}  ${t.name}`);
+              }
+              console.log(`\n${tables.length} table(s). Query rows with: fops coda tables ${docId} -t <tableId>`);
+              return;
+            }
+
+            // List/query rows
+            const result = await client.listRows(docId, opts.table, opts.query);
+            const rows = result.items || [];
+
+            if (rows.length === 0) {
+              console.log(opts.query ? `No rows matching "${opts.query}"` : "No rows found");
+              return;
+            }
+
+            for (const row of rows) {
+              const values = row.values || {};
+              const cells = Object.entries(values)
+                .map(([k, v]) => `${k}: ${typeof v === "object" ? JSON.stringify(v) : v}`)
+                .join(" | ");
+              console.log(`${row.id}  ${row.name || "(unnamed)"}  ${cells}`);
+            }
+            console.log(`\n${rows.length} row(s)`);
+          } catch (err) {
+            console.error(err.message);
+            process.exit(1);
+          }
+        });
+    });
+
+    // ── Register doctor check ───────────────────────────────────────────
+    api.registerDoctorCheck({
+      name: "coda",
+      fn: async (ok, warn) => {
+        const creds = loadCredentials();
+        if (!creds) {
+          warn("Coda", "Not authenticated. Run: fops coda login");
+          return;
+        }
+
+        try {
+          const client = new CodaClient(creds.access_token);
+          const user = await client.whoami();
+          ok("Coda", `connected as ${user.name}`);
+        } catch (err) {
+          warn("Coda", `Token may be expired: ${err.message}. Run: fops coda login`);
+        }
+      },
+    });
+
+    // ── Register RAG knowledge source ─────────────────────────────────
+    api.registerKnowledgeSource({
+      name: "Coda",
+      description: "Search Coda docs and pages by name",
+      async search(query) {
+        const creds = loadCredentials();
+        if (!creds) return [];
+
+        try {
+          const client = new CodaClient(creds.access_token);
+          const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+          const matches = (text) => words.every((w) => text.toLowerCase().includes(w));
+
+          const result = await client.listDocs();
+          const docs = result.items || [];
+          const results = [];
+
+          for (const doc of docs) {
+            const docMatches = matches(doc.name);
+
+            let pages = [];
+            try {
+              const pageResult = await client.listPages(doc.id);
+              pages = pageResult.items || [];
+            } catch {
+              continue;
+            }
+
+            for (const page of pages) {
+              const pageMatches = matches(page.name);
+              if (!docMatches && !pageMatches) continue;
+
+              const score = docMatches && pageMatches ? 1.0 : docMatches ? 0.7 : 0.5;
+              results.push({
+                title: `${doc.name} → ${page.name}`,
+                content: `Coda page "${page.name}" in doc "${doc.name}".\nRead with: fops coda read ${doc.id} ${page.id}`,
+                url: `https://coda.io/d/${doc.id}/_/${page.id}`,
+                score,
+              });
+            }
+          }
+
+          return results.sort((a, b) => b.score - a.score).slice(0, 10);
+        } catch {
+          return [];
+        }
+      },
+    });
+  },
+};

package/src/plugins/bundled/coda/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/src/plugins/bundled/coda/skills/coda/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: coda
+description: Search and read Coda knowledge base docs interactively
+---
+## Coda Knowledge Base
+
+Use `fops coda` commands to search and read internal documentation, runbooks, architecture decisions, and process docs stored in Coda.
+
+### When to Use
+
+- User asks about internal processes, onboarding, or "how we do X"
+- User needs a runbook, playbook, or architecture doc
+- User references a doc that might be in Coda
+- User asks "where is the doc for..." or "find the page about..."
+
+### Discovery Pattern
+
+Always follow: **search → list pages → read page**.
+
+1. Search for relevant docs by name:
+```bash
+fops coda docs -q "deployment"
+```
+
+2. Explore a doc's page structure:
+```bash
+fops coda read <docId>
+```
+
+3. Read a specific page as markdown:
+```bash
+fops coda read <docId> <pageId>
+```
+
+### Commands
+
+**List or search docs:**
+```bash
+fops coda docs
+fops coda docs -q "onboarding"
+```
+
+**Full-text search across docs (shows page structure):**
+```bash
+fops coda search "incident response"
+```
+
+**Read pages from a doc:**
+```bash
+fops coda read <docId>              # list all pages
+fops coda read <docId> <pageId>     # export page as markdown
+```
+
+**List tables or query rows:**
+```bash
+fops coda tables <docId>                          # list tables
+fops coda tables <docId> -t <tableId>             # list rows
+fops coda tables <docId> -t <tableId> -q "status:active"  # query rows
+```
+
+**Auth:**
+```bash
+fops coda login    # authenticate with Coda
+fops coda whoami   # check current auth
+```
+
+### Suggesting Commands
+
+Always suggest **2 commands** so the user can discover and then read:
+
+- Search + read: `fops coda docs -q "runbook"` + `fops coda read <docId>`
+- List + query: `fops coda tables <docId>` + `fops coda tables <docId> -t <tableId>`
+- Broad + narrow: `fops coda search "deploy"` + `fops coda read <docId> <pageId>`
+
+### Error Handling
+
+If a command returns an auth error, suggest:
+```bash
+fops coda login
+```
+
+Then retry the original command.

package/src/plugins/bundled/cursor/fops.plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "cursor",
+  "name": "Cursor IDE Integration",
+  "version": "0.1.0",
+  "description": "Bridge fops knowledge into Cursor AI via rules and edit commands",
+  "skills": ["skills/cursor"]
+}