unfairly 0.2.0 → 0.3.0

package/dist/auth/browser-flow.js

@@ -0,0 +1,73 @@
+import http from "node:http";
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+const SUCCESS_HTML = `<!doctype html><html><head><meta charset="utf-8"><title>Unfairly CLI authorized</title><style>body{margin:0;background:#FAF5EB;font-family:system-ui;color:#1a1612;display:flex;align-items:center;justify-content:center;min-height:100vh}.card{background:#fff;border:3px solid #1a1612;border-radius:20px;box-shadow:6px 6px 0 #1a1612;padding:36px;max-width:420px;text-align:center}h1{margin:0 0 8px;font-size:28px}p{margin:0;color:rgba(26,22,18,.7)}</style></head><body><div class="card"><h1>Authorized.</h1><p>You can close this window and return to your terminal.</p></div></body></html>`;
+function openBrowser(url) {
+    const opener = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "cmd"
+            : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        spawn(opener, args, { stdio: "ignore", detached: true }).unref();
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * OAuth handshake via loopback HTTP server. Used by `unfairly setup`,
+ * `unfairly login`, and `unfairly init`.
+ *
+ * Flow: pop a /cli-auth page in the user's browser with a one-time `state`
+ * and a `cb=http://localhost:<port>/done` callback. The page mints a
+ * `mcp_*` token and redirects the browser back to `cb`. Our local server
+ * verifies the state echo and resolves with the token.
+ */
+export async function browserAuthFlow(apiUrl, opts = {}) {
+    const tokenName = opts.tokenName ?? "unfairly cli";
+    const timeoutMs = opts.timeoutMs ?? 5 * 60_000;
+    const state = crypto.randomBytes(16).toString("base64url");
+    return new Promise((resolve) => {
+        let resolved = false;
+        const cleanup = (val) => {
+            if (resolved)
+                return;
+            resolved = true;
+            setTimeout(() => server.close(), 500);
+            resolve(val);
+        };
+        const server = http.createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            if (url.pathname !== "/done") {
+                res.writeHead(404).end();
+                return;
+            }
+            const echoState = url.searchParams.get("state") ?? "";
+            const token = url.searchParams.get("token") ?? "";
+            if (echoState !== state || !token.startsWith("mcp_")) {
+                res.writeHead(400).end("Auth failed");
+                cleanup(null);
+                return;
+            }
+            res
+                .writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
+                .end(SUCCESS_HTML);
+            cleanup(token);
+        });
+        const timeout = setTimeout(() => cleanup(null), timeoutMs);
+        server.on("close", () => clearTimeout(timeout));
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            const cb = `http://localhost:${port}/done`;
+            const authUrl = new URL("/cli-auth", apiUrl);
+            authUrl.searchParams.set("cb", cb);
+            authUrl.searchParams.set("state", state);
+            authUrl.searchParams.set("name", tokenName);
+            console.error(`\nOpening browser to authorize:\n  ${authUrl.toString()}\n(if it doesn't open, click the link above)\n`);
+            openBrowser(authUrl.toString());
+        });
+    });
+}

package/dist/cmd/init.js

@@ -2,102 +2,15 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
-import http from "node:http";
-import crypto from "node:crypto";
-import { spawn } from "node:child_process";
 import { SyncClient } from "../sync/api.js";
 import { emptyManifest, writeManifest } from "../sync/manifest.js";
 import { getToken, setToken } from "../sync/credentials.js";
+import { browserAuthFlow } from "../auth/browser-flow.js";
 import { runPull } from "./pull.js";
 const DEFAULT_API = "https://app.unfairly.ai";
 function isTty() {
     return Boolean(process.stdin.isTTY);
 }
-/**
- * Open a URL in the user's default browser. Best-effort, never throws.
- * Uses spawn (not exec) — URL passed as an arg, never interpolated into
- * a shell command, so no injection surface.
- */
-function openBrowser(url) {
-    const opener = process.platform === "darwin"
-        ? "open"
-        : process.platform === "win32"
-            ? "cmd"
-            : "xdg-open";
-    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
-    try {
-        spawn(opener, args, { stdio: "ignore", detached: true }).unref();
-    }
-    catch {
-        // best-effort
-    }
-}
-function successHtml() {
-    return `<!doctype html><html><head><meta charset="utf-8"><title>Unfairly CLI authorized</title><style>body{margin:0;background:#FAF5EB;font-family:system-ui;color:#1a1612;display:flex;align-items:center;justify-content:center;min-height:100vh}.card{background:#fff;border:3px solid #1a1612;border-radius:20px;box-shadow:6px 6px 0 #1a1612;padding:36px;max-width:420px;text-align:center}h1{margin:0 0 8px;font-size:28px}p{margin:0;color:rgba(26,22,18,.7)}</style></head><body><div class="card"><h1>Authorized.</h1><p>You can close this window and return to your terminal.</p></div></body></html>`;
-}
-function failHtml(msg) {
-    return `<!doctype html><html><head><meta charset="utf-8"><title>Unfairly CLI failed</title><style>body{margin:0;background:#FAF5EB;font-family:system-ui;color:#1a1612;display:flex;align-items:center;justify-content:center;min-height:100vh}.card{background:#fff;border:3px solid #1a1612;border-radius:20px;box-shadow:6px 6px 0 #1a1612;padding:36px;max-width:420px;text-align:center}h1{margin:0 0 8px;font-size:24px}p{margin:0;color:rgba(26,22,18,.7);font-size:14px}</style></head><body><div class="card"><h1>Authorization failed</h1><p>${msg}</p></div></body></html>`;
-}
-/**
- * Browser-based OAuth handoff. Spins up a loopback HTTP server, opens
- * the browser to /cli-auth, waits for the redirect callback. Returns
- * the mcp_* token, or null on timeout/cancel/error.
- */
-async function browserAuthFlow(apiUrl) {
-    const state = crypto.randomBytes(16).toString("base64url");
-    return new Promise((resolve) => {
-        let resolved = false;
-        const cleanup = (val) => {
-            if (resolved)
-                return;
-            resolved = true;
-            setTimeout(() => server.close(), 500);
-            resolve(val);
-        };
-        const server = http.createServer((req, res) => {
-            const url = new URL(req.url ?? "/", "http://localhost");
-            if (url.pathname !== "/done") {
-                res.writeHead(404).end("Not found");
-                return;
-            }
-            const echoState = url.searchParams.get("state") ?? "";
-            const token = url.searchParams.get("token") ?? "";
-            if (echoState !== state) {
-                res
-                    .writeHead(400, { "Content-Type": "text/html; charset=utf-8" })
-                    .end(failHtml("State mismatch — possible CSRF. Try `unfairly init` again."));
-                cleanup(null);
-                return;
-            }
-            if (!token.startsWith("mcp_")) {
-                res
-                    .writeHead(400, { "Content-Type": "text/html; charset=utf-8" })
-                    .end(failHtml("No token in callback."));
-                cleanup(null);
-                return;
-            }
-            res
-                .writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
-                .end(successHtml());
-            cleanup(token);
-        });
-        const timeout = setTimeout(() => cleanup(null), 5 * 60_000);
-        server.on("close", () => clearTimeout(timeout));
-        server.listen(0, "127.0.0.1", () => {
-            const addr = server.address();
-            const port = typeof addr === "object" && addr ? addr.port : 0;
-            const cb = `http://localhost:${port}/done`;
-            const authUrl = new URL("/cli-auth", apiUrl);
-            authUrl.searchParams.set("cb", cb);
-            authUrl.searchParams.set("state", state);
-            authUrl.searchParams.set("name", "unfairly cli");
-            console.log("Opening browser to authorize...");
-            console.log(`  ${authUrl.toString()}`);
-            console.log("(if it doesn't open, click the link above)");
-            openBrowser(authUrl.toString());
-        });
-    });
-}
 export async function runInit(opts = {}) {
     const cwd = process.cwd();
     const target = path.join(cwd, ".unfairly");

package/dist/cmd/login.js

@@ -1,78 +1,24 @@
-import http from "node:http";
-import crypto from "node:crypto";
-import { spawn } from "node:child_process";
+import { browserAuthFlow } from "../auth/browser-flow.js";
 import { setToken } from "../sync/credentials.js";
 const DEFAULT_API = "https://app.unfairly.ai";
-function openBrowser(url) {
-    const opener = process.platform === "darwin"
-        ? "open"
-        : process.platform === "win32"
-            ? "cmd"
-            : "xdg-open";
-    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
-    try {
-        spawn(opener, args, { stdio: "ignore", detached: true }).unref();
-    }
-    catch {
-        // best-effort
-    }
-}
-const SUCCESS_HTML = `<!doctype html><html><head><meta charset="utf-8"><title>Unfairly CLI authorized</title><style>body{margin:0;background:#FAF5EB;font-family:system-ui;color:#1a1612;display:flex;align-items:center;justify-content:center;min-height:100vh}.card{background:#fff;border:3px solid #1a1612;border-radius:20px;box-shadow:6px 6px 0 #1a1612;padding:36px;max-width:420px;text-align:center}h1{margin:0 0 8px;font-size:28px}p{margin:0;color:rgba(26,22,18,.7)}</style></head><body><div class="card"><h1>Authorized.</h1><p>You can close this window and return to your terminal.</p></div></body></html>`;
-async function browserAuthFlow(apiUrl) {
-    const state = crypto.randomBytes(16).toString("base64url");
-    return new Promise((resolve) => {
-        let resolved = false;
-        const cleanup = (val) => {
-            if (resolved)
-                return;
-            resolved = true;
-            setTimeout(() => server.close(), 500);
-            resolve(val);
-        };
-        const server = http.createServer((req, res) => {
-            const url = new URL(req.url ?? "/", "http://localhost");
-            if (url.pathname !== "/done") {
-                res.writeHead(404).end();
-                return;
-            }
-            const echoState = url.searchParams.get("state") ?? "";
-            const token = url.searchParams.get("token") ?? "";
-            if (echoState !== state || !token.startsWith("mcp_")) {
-                res.writeHead(400).end("Auth failed");
-                cleanup(null);
-                return;
-            }
-            res
-                .writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
-                .end(SUCCESS_HTML);
-            cleanup(token);
-        });
-        const timeout = setTimeout(() => cleanup(null), 5 * 60_000);
-        server.on("close", () => clearTimeout(timeout));
-        server.listen(0, "127.0.0.1", () => {
-            const addr = server.address();
-            const port = typeof addr === "object" && addr ? addr.port : 0;
-            const cb = `http://localhost:${port}/done`;
-            const authUrl = new URL("/cli-auth", apiUrl);
-            authUrl.searchParams.set("cb", cb);
-            authUrl.searchParams.set("state", state);
-            authUrl.searchParams.set("name", "unfairly cli");
-            console.error(`\nOpening browser to authorize:\n  ${authUrl.toString()}\n(if it doesn't open, click the link above)\n`);
-            openBrowser(authUrl.toString());
-        });
-    });
-}
 /**
  * `unfairly login` — runs the OAuth handoff and prints a shell snippet
  * the user can paste into their shell config. Useful for setting up
  * Codex CLI's UNFAIRLY_MCP_TOKEN env var without copy-pasting tokens.
  *
- * Stdout = the export line (only). Stderr = friendly hints. So users can
- * pipe: `unfairly login >> ~/.zshenv && source ~/.zshenv`.
+ * For most users `unfairly setup` is the better path — it handles env +
+ * agent host config in one shot. `login` is preserved for scripting use
+ * cases where you want just the export line on stdout.
+ *
+ * Stdout = the export line (only). Stderr = friendly hints.
+ *
+ * NOTE: do NOT pipe `unfairly login >> ~/.zshenv` via npx — npx's first-run
+ * "Ok to proceed?" confirmation goes to stdout and corrupts the file.
+ * Install globally first (`npm i -g unfairly`) or use `unfairly setup`.
  */
 export async function runLogin(opts = {}) {
     const apiUrl = process.env.UNFAIRLY_API_URL ?? DEFAULT_API;
-    const token = await browserAuthFlow(apiUrl);
+    const token = await browserAuthFlow(apiUrl, { tokenName: "unfairly login" });
     if (!token) {
         console.error("Login failed — browser flow timed out or was cancelled.");
         process.exit(1);
@@ -89,7 +35,6 @@ export async function runLogin(opts = {}) {
     process.stdout.write(`export UNFAIRLY_TOKEN=${token}\n`);
     if (!opts.quiet) {
         console.error("");
-        console.error("Or pipe directly:  npx unfairly@latest login >> ~/.zshenv && source ~/.zshenv");
-        console.error("Then restart any agent host (Codex, Claude Code) that needs the env.");
+        console.error("Tip: `unfairly setup` handles this AND patches your Codex / Claude Code config in one shot.");
     }
 }

package/dist/cmd/setup.js

@@ -0,0 +1,150 @@
+import { browserAuthFlow } from "../auth/browser-flow.js";
+import { setToken } from "../sync/credentials.js";
+import { writeShellEnv } from "../hosts/shell-env.js";
+import { configureCodex } from "../hosts/codex.js";
+import { configureClaudeCode, } from "../hosts/claude-code.js";
+const DEFAULT_API = "https://app.unfairly.ai";
+/**
+ * `unfairly setup` — one-shot agent host installer.
+ *
+ *  1. Browser OAuth → mint mcp_* token, cache in keychain.
+ *  2. Append/replace a sentinel-marked block in the user's shell rcfile
+ *     (~/.zshenv on zsh, ~/.bash_profile on bash) with UNFAIRLY_MCP_TOKEN
+ *     + UNFAIRLY_TOKEN exports.
+ *  3. Patch ~/.codex/config.toml with [mcp_servers.unfairly] including
+ *     bearer_token_env_var. Skips silently if Codex isn't installed.
+ *  4. Register with Claude Code via `claude mcp add` if the binary is
+ *     in PATH. Non-destructive — tolerates "already exists" as success.
+ *  5. Verify the new token works by calling /api/mcp with it. If the
+ *     handshake fails, print clear remediation instructions instead of
+ *     declaring victory.
+ *
+ * Idempotent — safe to re-run any time. Each write replaces in place
+ * rather than duplicating.
+ */
+export async function runSetup() {
+    const apiUrl = process.env.UNFAIRLY_API_URL ?? DEFAULT_API;
+    console.error("✦ unfairly setup");
+    console.error("");
+    // Step 1: browser auth
+    console.error("[1/4] Authorizing in browser...");
+    const token = await browserAuthFlow(apiUrl, { tokenName: "unfairly setup" });
+    if (!token) {
+        console.error("  ✗ Browser flow timed out or was cancelled. Run `unfairly setup` again.");
+        process.exit(1);
+    }
+    await setToken(token);
+    console.error("  ✓ Token minted and cached in keychain");
+    console.error("");
+    // Step 2: shell env
+    console.error("[2/4] Writing shell config...");
+    const env = await writeShellEnv(token);
+    if (env.shell === "unknown") {
+        console.error("  ⚠ Couldn't detect your shell ($SHELL is empty or non-zsh/bash).");
+        console.error("    Add this to your shell config manually:");
+        console.error(`    export UNFAIRLY_MCP_TOKEN=${token}`);
+    }
+    else {
+        console.error(`  ✓ ${env.path} (${env.action}) [${env.shell}]`);
+    }
+    console.error("");
+    // Step 3: hosts
+    console.error("[3/4] Configuring agent hosts...");
+    const codex = await configureCodex(apiUrl);
+    console.error(`  ${formatCodex(codex)}`);
+    const cc = await configureClaudeCode(apiUrl);
+    console.error(`  ${formatClaudeCode(cc)}`);
+    console.error("");
+    // Step 4: verify
+    console.error("[4/4] Verifying token works against /api/mcp...");
+    const verified = await verifyToken(apiUrl, token);
+    if (verified.ok) {
+        console.error("  ✓ MCP handshake succeeded");
+    }
+    else {
+        console.error(`  ✗ MCP handshake FAILED — ${verified.message}`);
+        console.error("    The token was saved, but something is wrong. Check that you signed in");
+        console.error("    as an internal-team member (anyone outside the allowlist gets denied).");
+        process.exit(2);
+    }
+    console.error("");
+    // Next steps
+    console.error("✓ Setup complete.");
+    console.error("");
+    console.error("Next:");
+    console.error("  1. Open a NEW terminal (existing shells don't have $UNFAIRLY_MCP_TOKEN yet).");
+    if (codex.status === "configured" || cc.status === "configured") {
+        console.error("  2. Restart any running agent host (Codex, Claude Code) so it reloads the MCP config.");
+        console.error("  3. Send any prompt — the agent will auto-fire `enter_org` and show your vaults.");
+    }
+    else {
+        console.error("  2. Install Codex or Claude Code, then re-run `unfairly setup` to wire them up.");
+    }
+    console.error("");
+    console.error("Optional — pull all vaults to local markdown for fast filesystem reads:");
+    console.error("  cd <your-workspace> && unfairly init");
+}
+function formatCodex(r) {
+    switch (r.status) {
+        case "configured":
+            return `✓ Codex (${r.path}) — ${r.action}`;
+        case "not-installed":
+            return `· Codex not detected at ${r.path} (skipped — install Codex and re-run if you want it)`;
+        case "error":
+            return `✗ Codex — ${r.message}`;
+    }
+}
+function formatClaudeCode(r) {
+    switch (r.status) {
+        case "configured":
+            return `✓ Claude Code — ${r.message}`;
+        case "already-registered":
+            return `· Claude Code — ${r.message}`;
+        case "not-installed":
+            return "· Claude Code CLI not detected (skipped)";
+        case "error":
+            return `✗ Claude Code — ${r.message}`;
+    }
+}
+/**
+ * Hit /api/mcp with the new token to confirm the full chain works:
+ * token row written, /api/mcp accepts it, handshake completes.
+ *
+ * We do an MCP `initialize` — that's the cheapest call that exercises
+ * the auth path end-to-end without touching DB-heavy tools.
+ */
+async function verifyToken(apiUrl, token) {
+    const url = `${apiUrl.replace(/\/$/, "")}/api/mcp`;
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "initialize",
+                params: {
+                    protocolVersion: "2024-11-05",
+                    capabilities: {},
+                    clientInfo: { name: "unfairly-setup", version: "0.3.0" },
+                },
+            }),
+        });
+        if (res.status !== 200) {
+            return { ok: false, message: `HTTP ${res.status}` };
+        }
+        const text = await res.text();
+        if (!text.includes('"result"') || !text.includes("protocolVersion")) {
+            return { ok: false, message: "unexpected response shape" };
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        const err = e;
+        return { ok: false, message: err.message };
+    }
+}

package/dist/hosts/claude-code.js

@@ -0,0 +1,43 @@
+import { spawnSync } from "node:child_process";
+/**
+ * Register Unfairly with Claude Code via `claude mcp add`. Non-destructive:
+ * if a server named `unfairly` already exists we don't remove it (the user
+ * may have a custom config). Instead we tolerate the "already exists" error
+ * and report `already-registered`.
+ *
+ * Skips silently if the `claude` binary is not in PATH (most CLI users have
+ * one host installed, not both).
+ */
+export async function configureClaudeCode(apiUrl) {
+    const url = `${apiUrl.replace(/\/$/, "")}/api/mcp`;
+    const result = spawnSync("claude", ["mcp", "add", "unfairly", "--transport", "http", url], { encoding: "utf-8" });
+    if (result.error) {
+        const e = result.error;
+        if (e.code === "ENOENT") {
+            return { status: "not-installed" };
+        }
+        return { status: "error", message: e.message };
+    }
+    const stderr = (result.stderr ?? "").toString();
+    const stdout = (result.stdout ?? "").toString();
+    const combined = `${stderr}\n${stdout}`.toLowerCase();
+    if (result.status === 0) {
+        return {
+            status: "configured",
+            message: "registered (Claude Code will pop OAuth on first call)",
+        };
+    }
+    // Claude CLI exits non-zero with a stderr message containing "already
+    // exists" (or similar) when the server name is taken. Don't destroy the
+    // user's existing config — surface as already-registered.
+    if (/already exists|already configured|duplicate/.test(combined)) {
+        return {
+            status: "already-registered",
+            message: "already registered (left as-is)",
+        };
+    }
+    return {
+        status: "error",
+        message: stderr.trim() || `claude mcp add exited ${result.status}`,
+    };
+}

package/dist/hosts/codex.js

@@ -0,0 +1,96 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const SECTION_HEADER = "[mcp_servers.unfairly]";
+/**
+ * Build the canonical [mcp_servers.unfairly] block. We own this whole
+ * section — anything inside it gets overwritten on re-runs.
+ */
+export function buildCodexBlock(apiUrl) {
+    const url = `${apiUrl.replace(/\/$/, "")}/api/mcp`;
+    return [
+        SECTION_HEADER,
+        `url = "${url}"`,
+        `bearer_token_env_var = "UNFAIRLY_MCP_TOKEN"`,
+    ].join("\n");
+}
+/**
+ * Strip ALL existing `[mcp_servers.unfairly]` blocks from a TOML string.
+ * "Block" = the section header through (but not including) the next
+ * top-level `[...]` table header at column 0, or end-of-file. This also
+ * removes any trailing blank lines we previously left.
+ *
+ * Robust against: duplicate blocks from prior bad runs, CRLF input,
+ * blocks at end-of-file with no trailing newline.
+ */
+export function stripUnfairlyBlocks(toml) {
+    // Normalize CRLF for matching; we'll use the same normalized form for
+    // output. (Codex writes LF on macOS / Linux anyway.)
+    const normalized = toml.replace(/\r\n/g, "\n");
+    // Match each block: header line, then everything up to next top-level
+    // [section] header or end-of-string. Multiline mode anchors `^[` to
+    // line start. Use `g` to clean up duplicates.
+    const blockRe = /^\[mcp_servers\.unfairly\]\s*\n[\s\S]*?(?=^\[|\Z)/gm;
+    // Note: `\Z` not supported in JS regex. Substitute with `(?=^\[|$(?![\s\S]))`.
+    const jsBlockRe = /^\[mcp_servers\.unfairly\]\s*\n[\s\S]*?(?=^\[|$(?![\s\S]))/gm;
+    void blockRe; // documentation only
+    let stripped = normalized.replace(jsBlockRe, "");
+    // Collapse runs of 3+ blank lines that the strip may have left behind.
+    stripped = stripped.replace(/\n{3,}/g, "\n\n");
+    return stripped;
+}
+/**
+ * Patch ~/.codex/config.toml to register the Unfairly MCP server with
+ * bearer-token wiring. Idempotent: removes any existing managed block(s)
+ * first, then appends one canonical block. Safe against duplicate sections
+ * left over from prior bad runs.
+ *
+ * If ~/.codex/config.toml does not exist, returns {status: "not-installed"}
+ * — don't create a Codex config out of thin air for a user who may not
+ * have Codex installed.
+ */
+export async function configureCodex(apiUrl) {
+    const home = os.homedir();
+    const filePath = path.join(home, ".codex", "config.toml");
+    let existing;
+    try {
+        existing = await fs.readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            return { status: "not-installed", path: filePath };
+        }
+        return {
+            status: "error",
+            path: filePath,
+            message: `Could not read ${filePath}: ${e.message}`,
+        };
+    }
+    const hadExistingBlock = /^\[mcp_servers\.unfairly\]/m.test(existing.replace(/\r\n/g, "\n"));
+    const stripped = stripUnfairlyBlocks(existing);
+    const block = buildCodexBlock(apiUrl);
+    // Append, ensuring exactly one blank line of separation if the file is
+    // non-empty.
+    const trimmedTail = stripped.replace(/\n+$/, "");
+    const next = trimmedTail.length === 0
+        ? `${block}\n`
+        : `${trimmedTail}\n\n${block}\n`;
+    try {
+        await fs.writeFile(filePath, next, "utf-8");
+    }
+    catch (err) {
+        const e = err;
+        return {
+            status: "error",
+            path: filePath,
+            message: `Could not write ${filePath}: ${e.message}`,
+        };
+    }
+    const action = hadExistingBlock
+        ? "replaced"
+        : existing.length === 0
+            ? "created"
+            : "appended";
+    return { status: "configured", path: filePath, action };
+}

package/dist/hosts/codex.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+import { stripUnfairlyBlocks, buildCodexBlock } from "./codex.js";
+const CANON = buildCodexBlock("https://app.unfairly.ai");
+describe("stripUnfairlyBlocks", () => {
+    it("returns input unchanged when no managed section is present", () => {
+        const input = `[mcp_servers.other]\nurl = "https://x"\n`;
+        expect(stripUnfairlyBlocks(input)).toBe(input);
+    });
+    it("removes a single managed section", () => {
+        const input = `[mcp_servers.other]\nurl = "https://x"\n\n` +
+            `[mcp_servers.unfairly]\nurl = "https://app.unfairly.ai/api/mcp"\nbearer_token_env_var = "UNFAIRLY_MCP_TOKEN"\n`;
+        const out = stripUnfairlyBlocks(input);
+        expect(out).not.toContain("[mcp_servers.unfairly]");
+        expect(out).toContain("[mcp_servers.other]");
+    });
+    it("removes ALL managed sections when there are duplicates", () => {
+        const input = `[mcp_servers.unfairly]\nurl = "https://stale-1"\n\n` +
+            `[mcp_servers.other]\nurl = "https://x"\n\n` +
+            `[mcp_servers.unfairly]\nurl = "https://stale-2"\nbearer_token_env_var = "UNFAIRLY_MCP_TOKEN"\n`;
+        const out = stripUnfairlyBlocks(input);
+        const occurrences = (out.match(/\[mcp_servers\.unfairly\]/g) ?? []).length;
+        expect(occurrences).toBe(0);
+        expect(out).toContain("[mcp_servers.other]");
+    });
+    it("survives CRLF line endings", () => {
+        const input = `[mcp_servers.other]\r\nurl = "https://x"\r\n\r\n` +
+            `[mcp_servers.unfairly]\r\nurl = "https://stale"\r\nbearer_token_env_var = "X"\r\n`;
+        const out = stripUnfairlyBlocks(input);
+        expect(out).not.toContain("[mcp_servers.unfairly]");
+        expect(out).toContain("[mcp_servers.other]");
+    });
+    it("removes a managed section that is the LAST table in the file", () => {
+        const input = `[mcp_servers.other]\nurl = "https://x"\n\n` +
+            `[mcp_servers.unfairly]\nurl = "https://stale"\nbearer_token_env_var = "UNFAIRLY_MCP_TOKEN"`;
+        const out = stripUnfairlyBlocks(input);
+        expect(out).not.toContain("[mcp_servers.unfairly]");
+    });
+    it("does not touch keys inside other tables that mention the word unfairly", () => {
+        const input = `[some.other.table]\ndescription = "this references unfairly somehow"\n` +
+            `url = "https://app.unfairly.ai/api/mcp"\n`;
+        const out = stripUnfairlyBlocks(input);
+        expect(out).toBe(input);
+    });
+    it("preserves sections that come AFTER our managed block", () => {
+        const input = `[mcp_servers.unfairly]\nurl = "https://stale"\nbearer_token_env_var = "X"\n\n` +
+            `[mcp_servers.zoo]\nurl = "https://zoo"\n`;
+        const out = stripUnfairlyBlocks(input);
+        expect(out).not.toContain("[mcp_servers.unfairly]");
+        expect(out).toContain("[mcp_servers.zoo]");
+        expect(out).toContain('url = "https://zoo"');
+    });
+});
+describe("buildCodexBlock", () => {
+    it("produces a TOML section with bearer_token_env_var wired", () => {
+        expect(CANON).toContain("[mcp_servers.unfairly]");
+        expect(CANON).toContain('url = "https://app.unfairly.ai/api/mcp"');
+        expect(CANON).toContain('bearer_token_env_var = "UNFAIRLY_MCP_TOKEN"');
+    });
+    it("trims trailing slash from apiUrl when constructing /api/mcp", () => {
+        const block = buildCodexBlock("https://app.unfairly.ai/");
+        expect(block).toContain('url = "https://app.unfairly.ai/api/mcp"');
+        expect(block).not.toContain("//api/mcp");
+    });
+});

package/dist/hosts/shell-env.js

@@ -0,0 +1,80 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export const ENV_BLOCK_START = "# === unfairly cli (auto-managed — do not edit) ===";
+export const ENV_BLOCK_END = "# === end unfairly cli ===";
+/**
+ * Detect the user's shell + the right rcfile to write env exports to.
+ * Returns null path for unknown shells so the caller can print a manual
+ * fallback instead of guessing.
+ */
+function detectShell() {
+    const shellEnv = process.env.SHELL ?? "";
+    const home = os.homedir();
+    if (shellEnv.endsWith("zsh")) {
+        return { shell: "zsh", rcPath: path.join(home, ".zshenv") };
+    }
+    if (shellEnv.endsWith("bash")) {
+        return { shell: "bash", rcPath: path.join(home, ".bash_profile") };
+    }
+    return { shell: "unknown", rcPath: null };
+}
+/**
+ * Build the canonical sentinel block. Used both for writing and matching.
+ */
+function buildBlock(token) {
+    return [
+        ENV_BLOCK_START,
+        `export UNFAIRLY_MCP_TOKEN=${token}`,
+        `export UNFAIRLY_TOKEN=${token}`,
+        ENV_BLOCK_END,
+    ].join("\n");
+}
+/**
+ * Idempotent shell-env writer. Replaces any existing managed block in
+ * place; appends one if none exists. Tolerates CRLF input by normalizing
+ * before matching, then preserves the host file's existing line ending
+ * convention on write.
+ */
+export async function writeShellEnvFile(rcPath, token) {
+    const block = buildBlock(token);
+    let existing = "";
+    let fileExists = true;
+    try {
+        existing = await fs.readFile(rcPath, "utf-8");
+    }
+    catch {
+        fileExists = false;
+    }
+    const normalized = existing.replace(/\r\n/g, "\n");
+    const blockRe = new RegExp(`${escapeRegex(ENV_BLOCK_START)}[\\s\\S]*?${escapeRegex(ENV_BLOCK_END)}\\n?`, "g");
+    let next;
+    let action;
+    if (blockRe.test(normalized)) {
+        blockRe.lastIndex = 0;
+        next = normalized.replace(blockRe, block + "\n");
+        action = "replaced";
+    }
+    else if (!fileExists || normalized.length === 0) {
+        next = block + "\n";
+        action = "created";
+    }
+    else {
+        const sep = normalized.endsWith("\n") ? "" : "\n";
+        next = `${normalized}${sep}\n${block}\n`;
+        action = "appended";
+    }
+    await fs.writeFile(rcPath, next, "utf-8");
+    return action;
+}
+export async function writeShellEnv(token) {
+    const { shell, rcPath } = detectShell();
+    if (!rcPath) {
+        return { path: "", shell, action: "created" };
+    }
+    const action = await writeShellEnvFile(rcPath, token);
+    return { path: rcPath, shell, action };
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/hosts/shell-env.test.js

@@ -0,0 +1,71 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { writeShellEnvFile, ENV_BLOCK_START, ENV_BLOCK_END, } from "./shell-env.js";
+const TOK_A = "mcp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+const TOK_B = "mcp_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+let tmpDir;
+let rcPath;
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "unfairly-shell-env-"));
+    rcPath = path.join(tmpDir, "rc");
+});
+afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+describe("writeShellEnvFile", () => {
+    it("creates the rcfile when missing", async () => {
+        const action = await writeShellEnvFile(rcPath, TOK_A);
+        expect(action).toBe("created");
+        const out = await fs.readFile(rcPath, "utf-8");
+        expect(out).toContain(ENV_BLOCK_START);
+        expect(out).toContain(`export UNFAIRLY_MCP_TOKEN=${TOK_A}`);
+        expect(out).toContain(`export UNFAIRLY_TOKEN=${TOK_A}`);
+        expect(out).toContain(ENV_BLOCK_END);
+    });
+    it("appends to a non-empty rcfile that has no managed block", async () => {
+        await fs.writeFile(rcPath, "export EXISTING=1\n", "utf-8");
+        const action = await writeShellEnvFile(rcPath, TOK_A);
+        expect(action).toBe("appended");
+        const out = await fs.readFile(rcPath, "utf-8");
+        expect(out.startsWith("export EXISTING=1")).toBe(true);
+        expect(out).toContain(`export UNFAIRLY_MCP_TOKEN=${TOK_A}`);
+    });
+    it("replaces a stale managed block on second run", async () => {
+        await writeShellEnvFile(rcPath, TOK_A);
+        const action = await writeShellEnvFile(rcPath, TOK_B);
+        expect(action).toBe("replaced");
+        const out = await fs.readFile(rcPath, "utf-8");
+        expect(out).toContain(TOK_B);
+        expect(out).not.toContain(TOK_A);
+        // Block should appear exactly once.
+        const occurrences = out.split(ENV_BLOCK_START).length - 1;
+        expect(occurrences).toBe(1);
+    });
+    it("preserves user content above and below the managed block on replace", async () => {
+        await fs.writeFile(rcPath, `export FOO=1\n${ENV_BLOCK_START}\nexport UNFAIRLY_MCP_TOKEN=stale\n${ENV_BLOCK_END}\nexport BAR=2\n`, "utf-8");
+        await writeShellEnvFile(rcPath, TOK_A);
+        const out = await fs.readFile(rcPath, "utf-8");
+        expect(out).toContain("export FOO=1");
+        expect(out).toContain("export BAR=2");
+        expect(out).toContain(TOK_A);
+        expect(out).not.toContain("stale");
+    });
+    it("normalizes CRLF input and writes LF output cleanly", async () => {
+        await fs.writeFile(rcPath, "export EXISTING=1\r\n", "utf-8");
+        const action = await writeShellEnvFile(rcPath, TOK_A);
+        expect(action).toBe("appended");
+        const out = await fs.readFile(rcPath, "utf-8");
+        expect(out).toContain("export EXISTING=1");
+        expect(out).toContain(`export UNFAIRLY_MCP_TOKEN=${TOK_A}`);
+    });
+    it("is idempotent across N runs with the same token", async () => {
+        for (let i = 0; i < 5; i++) {
+            await writeShellEnvFile(rcPath, TOK_A);
+        }
+        const out = await fs.readFile(rcPath, "utf-8");
+        const occurrences = out.split(ENV_BLOCK_START).length - 1;
+        expect(occurrences).toBe(1);
+    });
+});

package/dist/index.js

@@ -4,6 +4,10 @@ import { hideBin } from "yargs/helpers";
 await yargs(hideBin(process.argv))
     .scriptName("unfairly")
     .usage("$0 <cmd> [args]")
+    .command("setup", "One-shot: authorize, write shell env, configure Codex + Claude Code", () => { }, async () => {
+    const { runSetup } = await import("./cmd/setup.js");
+    await runSetup();
+})
     .command("login", "Authorize via browser; print export lines for ~/.zshenv (Codex / scripts)", (y) => y.option("quiet", {
     type: "boolean",
     alias: "q",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unfairly",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI + stdio MCP for syncing Unfairly vaults to local markdown — the multiplayer context layer for AI agents",
   "keywords": ["unfairly", "mcp", "ai", "context", "agents", "knowledge-base", "claude", "codex"],
   "homepage": "https://unfairly.ai",