@meshxdata/fops 0.0.4 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshxdata/fops",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "CLI to install and manage Foundation data mesh platforms",
   "keywords": [
     "foundation",
@@ -26,6 +26,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-code": "^1.0.0",
+    "@meshxdata/fops": "^0.0.4",
     "boxen": "^8.0.1",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",

package/src/commands/index.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import https from "node:https";
 import chalk from "chalk";
 import { Command } from "commander";
 import { PKG } from "../config.js";
@@ -273,6 +274,24 @@ export function registerCommands(program, registry) {
     .command("plugin")
     .description("Manage fops plugins");
 
+  // Helper: read/write plugin enabled state in ~/.fops.json
+  const fopsConfigPath = path.join(os.homedir(), ".fops.json");
+  const readFopsConfig = () => {
+    try { return fs.existsSync(fopsConfigPath) ? JSON.parse(fs.readFileSync(fopsConfigPath, "utf8")) : {}; } catch { return {}; }
+  };
+  const setPluginEnabled = (id, enabled) => {
+    const cfg = readFopsConfig();
+    if (!cfg.plugins) cfg.plugins = {};
+    if (!cfg.plugins.entries) cfg.plugins.entries = {};
+    if (!cfg.plugins.entries[id]) cfg.plugins.entries[id] = {};
+    cfg.plugins.entries[id].enabled = enabled;
+    fs.writeFileSync(fopsConfigPath, JSON.stringify(cfg, null, 2) + "\n");
+  };
+  const isPluginEnabled = (id) => {
+    const cfg = readFopsConfig();
+    return cfg?.plugins?.entries?.[id]?.enabled !== false;
+  };
+
   pluginCmd
     .command("list")
     .description("List installed plugins with status")
@@ -284,8 +303,11 @@ export function registerCommands(program, registry) {
       }
       console.log(chalk.bold.cyan("\n  Installed Plugins\n"));
       for (const p of registry.plugins) {
+        const enabled = isPluginEnabled(p.id);
+        const dot = enabled ? chalk.green("●") : chalk.red("○");
+        const status = enabled ? "" : chalk.red(" (disabled)");
         const source = chalk.dim(`(${p.source})`);
-        console.log(`  ${chalk.green("●")} ${chalk.bold(p.name)} ${chalk.dim("v" + p.version)} ${source}`);
+        console.log(`  ${dot} ${chalk.bold(p.name)} ${chalk.dim("v" + p.version)} ${source}${status}`);
         console.log(chalk.dim(`    id: ${p.id}  path: ${p.path}`));
       }
       console.log("");
@@ -338,4 +360,144 @@ export function registerCommands(program, registry) {
       fs.rmSync(pluginDir, { recursive: true, force: true });
       console.log(chalk.green(`  ✓ Removed plugin "${id}"`));
     });
+
+  pluginCmd
+    .command("enable <id>")
+    .description("Enable a plugin")
+    .action(async (id) => {
+      const found = registry.plugins.find((p) => p.id === id);
+      if (!found) {
+        console.error(chalk.red(`Plugin "${id}" not found. Run: fops plugin list`));
+        process.exit(1);
+      }
+      setPluginEnabled(id, true);
+      console.log(chalk.green(`  ✓ Enabled plugin "${id}". Restart fops to apply.`));
+    });
+
+  pluginCmd
+    .command("disable <id>")
+    .description("Disable a plugin without removing it")
+    .action(async (id) => {
+      const found = registry.plugins.find((p) => p.id === id);
+      if (!found) {
+        console.error(chalk.red(`Plugin "${id}" not found. Run: fops plugin list`));
+        process.exit(1);
+      }
+      setPluginEnabled(id, false);
+      console.log(chalk.yellow(`  ○ Disabled plugin "${id}". Restart fops to apply.`));
+    });
+
+  // ── Plugin marketplace ──────────────────────────────
+  const marketplaceCmd = pluginCmd
+    .command("marketplace")
+    .description("Browse and install plugins from GitHub");
+
+  marketplaceCmd
+    .command("add <repo>")
+    .description("Install a plugin from GitHub (owner/repo)")
+    .action(async (repo) => {
+      const parts = repo.split("/");
+      if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        console.error(chalk.red('  Usage: fops plugin marketplace add <owner/repo>'));
+        process.exit(1);
+      }
+      const [owner, repoName] = parts;
+
+      // Download tarball from GitHub
+      const tarballUrl = `https://api.github.com/repos/${owner}/${repoName}/tarball/main`;
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fops-marketplace-"));
+      const tarPath = path.join(tmpDir, "plugin.tar.gz");
+
+      console.log(chalk.blue(`  Downloading ${owner}/${repoName}...`));
+
+      try {
+        await new Promise((resolve, reject) => {
+          const follow = (url) => {
+            https.get(url, { headers: { "User-Agent": "fops-cli", Accept: "application/vnd.github+json" } }, (res) => {
+              if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                follow(res.headers.location);
+                return;
+              }
+              if (res.statusCode !== 200) {
+                reject(new Error(`GitHub returned ${res.statusCode}. Check that ${owner}/${repoName} exists and is public.`));
+                res.resume();
+                return;
+              }
+              const ws = fs.createWriteStream(tarPath);
+              res.pipe(ws);
+              ws.on("finish", resolve);
+              ws.on("error", reject);
+            }).on("error", reject);
+          };
+          follow(tarballUrl);
+        });
+      } catch (err) {
+        console.error(chalk.red(`  Download failed: ${err.message}`));
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        process.exit(1);
+      }
+
+      // Extract tarball
+      const extractDir = path.join(tmpDir, "extracted");
+      fs.mkdirSync(extractDir, { recursive: true });
+      try {
+        await execa("tar", ["xzf", tarPath, "-C", extractDir]);
+      } catch (err) {
+        console.error(chalk.red(`  Failed to extract archive: ${err.message}`));
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        process.exit(1);
+      }
+
+      // GitHub tarballs extract into a single directory like owner-repo-sha/
+      const extracted = fs.readdirSync(extractDir);
+      if (extracted.length === 0) {
+        console.error(chalk.red("  Archive was empty."));
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        process.exit(1);
+      }
+      const pluginSrc = path.join(extractDir, extracted[0]);
+
+      // Validate manifest
+      const manifestPath = path.join(pluginSrc, "fops.plugin.json");
+      if (!fs.existsSync(manifestPath)) {
+        console.error(chalk.red(`  No fops.plugin.json found in ${owner}/${repoName}. Not a valid fops plugin.`));
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        process.exit(1);
+      }
+
+      let manifest;
+      try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+      } catch {
+        console.error(chalk.red("  Invalid fops.plugin.json"));
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        process.exit(1);
+      }
+
+      if (!manifest.id) {
+        console.error(chalk.red('  fops.plugin.json missing required "id" field.'));
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        process.exit(1);
+      }
+
+      // Copy to ~/.fops/plugins/<id>/
+      const dest = path.join(os.homedir(), ".fops", "plugins", manifest.id);
+      fs.mkdirSync(dest, { recursive: true });
+
+      const entries = fs.readdirSync(pluginSrc, { withFileTypes: true });
+      for (const entry of entries) {
+        const srcFile = path.join(pluginSrc, entry.name);
+        const destFile = path.join(dest, entry.name);
+        if (entry.isFile()) {
+          fs.copyFileSync(srcFile, destFile);
+        } else if (entry.isDirectory()) {
+          fs.cpSync(srcFile, destFile, { recursive: true });
+        }
+      }
+
+      // Cleanup temp dir
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+
+      console.log(chalk.green(`  ✓ Installed plugin "${manifest.id}" from ${owner}/${repoName} to ${dest}`));
+    });
 }

package/src/doctor.js

@@ -6,8 +6,8 @@ import path from "node:path";
 import chalk from "chalk";
 import { execa } from "execa";
 import { rootDir } from "./project.js";
+import inquirer from "inquirer";
 import { detectEcrRegistry, detectAwsSsoProfiles, fixAwsSso, fixEcr } from "./setup/aws.js";
-import { confirm } from "./ui/index.js";
 
 const KEY_PORTS = {
   5432: "Postgres",
@@ -34,6 +34,25 @@ async function checkPort(port) {
   });
 }
 
+/**
+ * Ensure Homebrew is available (macOS). Installs if missing.
+ * Returns true if brew is usable after the call.
+ */
+async function ensureBrew() {
+  try { await execa("brew", ["--version"]); return true; } catch {}
+  console.log(chalk.cyan("  ▶ Installing Homebrew…"));
+  try {
+    await execa("bash", ["-c", 'NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'], {
+      stdio: "inherit", timeout: 300_000,
+    });
+    const brewPaths = ["/opt/homebrew/bin/brew", "/usr/local/bin/brew"];
+    for (const bp of brewPaths) {
+      if (fs.existsSync(bp)) { process.env.PATH = path.dirname(bp) + ":" + process.env.PATH; break; }
+    }
+    return true;
+  } catch { return false; }
+}
+
 async function cmdVersion(cmd, args = ["--version"]) {
   try {
     const { stdout } = await execa(cmd, args, { reject: false, timeout: 5000 });
@@ -98,19 +117,21 @@ export async function runDoctor(opts = {}, registry = null) {
   let failed = 0;
 
   const fixes = []; // collect fix actions to run at the end
+  const fixFns = new Set(); // deduplicate by function reference
 
   const ok = (name, detail) => {
     console.log(chalk.green("  ✓ ") + name + (detail ? chalk.dim(` — ${detail}`) : ""));
     passed++;
   };
-  const warn = (name, detail) => {
+  const warn = (name, detail, fixFn) => {
     console.log(chalk.yellow("  ⚠ ") + name + (detail ? chalk.dim(` — ${detail}`) : ""));
     warned++;
+    if (fixFn && !fixFns.has(fixFn)) { fixes.push({ name, fn: fixFn }); fixFns.add(fixFn); }
   };
   const fail = (name, detail, fixFn) => {
     console.log(chalk.red("  ✗ ") + name + (detail ? chalk.dim(` — ${detail}`) : ""));
     failed++;
-    if (fixFn) fixes.push({ name, fn: fixFn });
+    if (fixFn && !fixFns.has(fixFn)) { fixes.push({ name, fn: fixFn }); fixFns.add(fixFn); }
   };
 
   // ── Prerequisites ──────────────────────────────────
@@ -235,7 +256,20 @@ export async function runDoctor(opts = {}, registry = null) {
   // Git
   const gitVer = await cmdVersion("git");
   if (gitVer) ok("Git available", gitVer);
-  else fail("Git not found", "install git");
+  else fail("Git not found", "install git", async () => {
+    if (process.platform === "darwin") {
+      if (!(await ensureBrew())) throw new Error("Homebrew required");
+      console.log(chalk.cyan("  ▶ brew install git"));
+      await execa("brew", ["install", "git"], { stdio: "inherit", timeout: 300_000 });
+    } else if (process.platform === "win32") {
+      if (!hasWinget) throw new Error("winget required");
+      console.log(chalk.cyan("  ▶ winget install Git.Git"));
+      await execa("winget", ["install", "Git.Git", "--accept-source-agreements", "--accept-package-agreements"], { stdio: "inherit", timeout: 300_000 });
+    } else {
+      console.log(chalk.cyan("  ▶ sudo apt-get install -y git"));
+      await execa("sudo", ["apt-get", "install", "-y", "git"], { stdio: "inherit", timeout: 300_000 });
+    }
+  });
 
   // Node.js version
   const nodeVer = process.versions.node;
@@ -246,28 +280,121 @@ export async function runDoctor(opts = {}, registry = null) {
   // Claude CLI (bundled as a dependency)
   const claudeVer = await cmdVersion("claude");
   if (claudeVer) ok("Claude CLI", claudeVer);
-  else fail("Claude CLI not found", "run: npm install (included as a dependency)");
+  else fail("Claude CLI not found", "included as a dependency", async () => {
+    console.log(chalk.cyan("  ▶ npm install"));
+    await execa("npm", ["install"], { stdio: "inherit", timeout: 300_000 });
+  });
 
   // AWS CLI (optional)
   const awsVer = await cmdVersion("aws");
   if (awsVer) ok("AWS CLI", awsVer);
-  else warn("AWS CLI not found", "optional — needed for ECR login");
+  else warn("AWS CLI not found", "needed for ECR login", async () => {
+    if (process.platform === "darwin") {
+      if (!(await ensureBrew())) throw new Error("Homebrew required");
+      console.log(chalk.cyan("  ▶ brew install awscli"));
+      await execa("brew", ["install", "awscli"], { stdio: "inherit", timeout: 300_000 });
+    } else if (process.platform === "win32") {
+      if (!hasWinget) throw new Error("winget required");
+      console.log(chalk.cyan("  ▶ winget install Amazon.AWSCLI"));
+      await execa("winget", ["install", "Amazon.AWSCLI", "--accept-source-agreements", "--accept-package-agreements"], { stdio: "inherit", timeout: 300_000 });
+    } else {
+      console.log(chalk.cyan("  ▶ curl + unzip install"));
+      await execa("sh", ["-c", 'curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o /tmp/awscliv2.zip && unzip -qo /tmp/awscliv2.zip -d /tmp && sudo /tmp/aws/install'], {
+        stdio: "inherit", timeout: 300_000,
+      });
+    }
+  });
+
+  // 1Password CLI (optional — needed for secret sync)
+  const opVer = await cmdVersion("op");
+  if (opVer) ok("1Password CLI (op)", opVer);
+  else warn("1Password CLI (op) not installed", "needed for secret sync", async () => {
+    if (process.platform === "darwin") {
+      if (!(await ensureBrew())) throw new Error("Homebrew required");
+      console.log(chalk.cyan("  ▶ brew install --cask 1password-cli"));
+      await execa("brew", ["install", "--cask", "1password-cli"], { stdio: "inherit", timeout: 300_000 });
+    } else if (process.platform === "win32") {
+      if (!hasWinget) throw new Error("winget required");
+      console.log(chalk.cyan("  ▶ winget install AgileBits.1Password.CLI"));
+      await execa("winget", ["install", "AgileBits.1Password.CLI", "--accept-source-agreements", "--accept-package-agreements"], { stdio: "inherit", timeout: 300_000 });
+    } else {
+      console.log(chalk.dim("  Install manually: https://developer.1password.com/docs/cli/get-started/#install"));
+    }
+  });
 
-  // ~/.netrc GitHub credentials (optional — validate against API + repo access)
+  // GitHub CLI
+  const ghVer = await cmdVersion("gh");
+  if (ghVer) ok("GitHub CLI (gh)", ghVer);
+  else warn("GitHub CLI (gh) not installed", "needed for auth", async () => {
+    if (process.platform === "darwin") {
+      if (!(await ensureBrew())) throw new Error("Homebrew required");
+      console.log(chalk.cyan("  ▶ brew install gh"));
+      await execa("brew", ["install", "gh"], { stdio: "inherit", timeout: 300_000 });
+    } else if (process.platform === "win32") {
+      if (!hasWinget) throw new Error("winget required");
+      console.log(chalk.cyan("  ▶ winget install GitHub.cli"));
+      await execa("winget", ["install", "GitHub.cli", "--accept-source-agreements", "--accept-package-agreements"], { stdio: "inherit", timeout: 300_000 });
+    } else {
+      console.log(chalk.dim("  Install: https://cli.github.com/"));
+    }
+  });
+
+  // ~/.netrc GitHub credentials (required for private repo access)
   const netrcPath = path.join(os.homedir(), ".netrc");
+  const netrcFixFn = async () => {
+    // Install gh if missing
+    let hasGh = false;
+    try { await execa("gh", ["--version"]); hasGh = true; } catch {}
+    if (!hasGh) {
+      if (process.platform === "darwin") {
+        if (!(await ensureBrew())) throw new Error("Homebrew required to install gh");
+        console.log(chalk.cyan("  ▶ brew install gh"));
+        await execa("brew", ["install", "gh"], { stdio: "inherit", timeout: 300_000 });
+        hasGh = true;
+      } else if (process.platform === "win32") {
+        console.log(chalk.cyan("  ▶ winget install GitHub.cli"));
+        await execa("winget", ["install", "GitHub.cli", "--accept-source-agreements", "--accept-package-agreements"], { stdio: "inherit", timeout: 300_000 });
+        hasGh = true;
+      }
+    }
+    // Authenticate via gh
+    console.log(chalk.cyan("\n  ▶ gh auth login -p https -h github.com -w"));
+    await execa("gh", ["auth", "login", "-p", "https", "-h", "github.com", "-w"], {
+      stdio: "inherit", timeout: 120_000,
+    });
+    console.log(chalk.cyan("  ▶ gh auth setup-git"));
+    await execa("gh", ["auth", "setup-git"], { stdio: "inherit", timeout: 10_000 }).catch(() => {});
+    // Extract token and write to .netrc for tools that need it directly
+    try {
+      const { stdout: ghToken } = await execa("gh", ["auth", "token"], { timeout: 5000 });
+      const { stdout: ghUser } = await execa("gh", ["api", "/user", "--jq", ".login"], { timeout: 10000 });
+      if (ghToken?.trim() && ghUser?.trim()) {
+        const entry = `machine github.com\nlogin ${ghUser.trim()}\npassword ${ghToken.trim()}\n`;
+        if (fs.existsSync(netrcPath)) {
+          const content = fs.readFileSync(netrcPath, "utf8");
+          if (!content.includes("github.com")) {
+            fs.appendFileSync(netrcPath, "\n" + entry);
+          }
+        } else {
+          fs.writeFileSync(netrcPath, entry, { mode: 0o600 });
+        }
+        console.log(chalk.green("  ✓ ~/.netrc updated with GitHub credentials"));
+      }
+    } catch {}
+  };
   if (fs.existsSync(netrcPath)) {
     try {
       const content = fs.readFileSync(netrcPath, "utf8");
       if (!content.includes("github.com")) {
-        warn("~/.netrc exists but no github.com entry");
+        fail("~/.netrc exists but no github.com entry", "needed for private repos", netrcFixFn);
       } else {
         const token = readNetrcToken(content, "github.com");
         if (!token) {
-          warn("~/.netrc has github.com but no password/token");
+          fail("~/.netrc has github.com but no password/token", "add token", netrcFixFn);
         } else {
           const userRes = await ghApiGet("/user", token);
           if (userRes.status !== 200) {
-            fail("~/.netrc GitHub token invalid or expired", "regenerate at github.com/settings/tokens");
+            fail("~/.netrc GitHub token invalid or expired", "regenerate at github.com/settings/tokens", netrcFixFn);
           } else {
             const login = userRes.body.login || "authenticated";
             ok("~/.netrc GitHub credentials", `authenticated as ${login}`);
@@ -283,10 +410,10 @@ export async function runDoctor(opts = {}, registry = null) {
         }
       }
     } catch {
-      warn("~/.netrc not readable");
+      fail("~/.netrc not readable", "check file permissions", netrcFixFn);
     }
   } else {
-    warn("~/.netrc not found", "optional — used for private repo access");
+    fail("~/.netrc not found", "needed for private repo access", netrcFixFn);
   }
 
   // ~/.fops.json config (optional)
@@ -324,7 +451,7 @@ export async function runDoctor(opts = {}, registry = null) {
       }
     }
   } else {
-    warn("~/.aws/config not found", "optional — needed for ECR");
+    warn("~/.aws/config not found", "needed for ECR", fixAwsSso);
   }
 
   // Validate ECR access if project references ECR images
@@ -332,7 +459,7 @@ export async function runDoctor(opts = {}, registry = null) {
   if (ecrInfo) {
     const ecrUrl = `${ecrInfo.accountId}.dkr.ecr.${ecrInfo.region}.amazonaws.com`;
     if (!awsSessionValid) {
-      fail(`ECR registry ${ecrUrl}`, "fix AWS session first", () => fixEcr(ecrInfo));
+      fail(`ECR registry ${ecrUrl}`, "fix AWS session first");
     } else {
       // Check we can get an ECR login password (same call the actual login uses)
       const ssoProfiles = detectAwsSsoProfiles();
@@ -528,6 +655,10 @@ export async function runDoctor(opts = {}, registry = null) {
         const ERROR_RE = /\b(ERROR|FATAL|PANIC|CRITICAL)\b/;
         const CRASH_RE = /\b(OOM|OutOfMemory|out of memory|segmentation fault|segfault)\b/i;
         const CONN_RE = /\b(ECONNREFUSED|ETIMEDOUT|connection refused)\b/i;
+        // Telemetry/analytics hosts whose failures are harmless noise
+        const TELEMETRY_RE = /heapanalytics\.com|segment\.io|sentry\.io|amplitude\.com|mixpanel\.com|telemetry/i;
+        // Harmless startup noise — idempotent init scripts & transient Kafka topic races
+        const BENIGN_RE = /already exists|UNKNOWN_TOPIC_OR_PART/;
 
         for (const line of logOut.split("\n")) {
           const sep = line.indexOf(" | ");
@@ -535,6 +666,9 @@ export async function runDoctor(opts = {}, registry = null) {
           const service = line.slice(0, sep).trim();
           const msg = line.slice(sep + 3);
 
+          if (TELEMETRY_RE.test(msg)) continue;
+          if (BENIGN_RE.test(msg)) continue;
+
           let level = null;
           if (CRASH_RE.test(msg)) level = "crash";
           else if (ERROR_RE.test(msg)) level = "error";
@@ -644,8 +778,12 @@ export async function runDoctor(opts = {}, registry = null) {
   if (failed) parts.push(chalk.red(`${failed} failed`));
   console.log("  " + parts.join(chalk.dim(" · ")));
 
-  if (failed > 0 && fixes.length > 0) {
-    const shouldFix = opts.fix || await confirm(`\n  Fix ${fixes.length} issue(s) automatically?`, true);
+  if (fixes.length > 0) {
+    let shouldFix = opts.fix;
+    if (!shouldFix) {
+      const { ans } = await inquirer.prompt([{ type: "confirm", name: "ans", message: `Fix ${fixes.length} issue(s) automatically?`, default: true }]);
+      shouldFix = ans;
+    }
     if (shouldFix) {
       console.log("");
       for (const fix of fixes) {
@@ -658,7 +796,7 @@ export async function runDoctor(opts = {}, registry = null) {
         }
       }
       console.log(chalk.dim("  Run fops doctor again to verify.\n"));
-    } else {
+    } else if (failed > 0) {
       console.log("");
       process.exit(1);
     }

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

@@ -0,0 +1,79 @@
+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) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try { 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;
+}