@webstew/bridge 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @webstew/bridge
+
+Run [Webstew](https://webstew.net) workspace chats against your **local Claude Code Pro/Max subscription** instead of paying separate Anthropic API rates.
+
+```
+npx @webstew/bridge connect <code>
+```
+
+Get the `<code>` from Webstew → **/integrations → Connect Local Bridge**.
+
+## Why
+
+Webstew's AI builder (`/workspace`) talks to Claude. By default, that goes through the Console API and bills against your API credits. If you already pay for **Claude Pro** or **Claude Max**, your subscription already covers Claude usage on your own machine via Claude Code — this bridge proxies your Webstew chats through that same path so your subscription handles the bill.
+
+## How it works
+
+```
+[your browser] ──► Webstew server ──► (you have a bridge?) ──► your local CLI
+                                                                    │
+                                                                    └─► Claude (your sub)
+```
+
+1. You click **Connect Local Bridge** in Webstew settings — get a pairing code.
+2. You paste the code into `webstew-bridge connect <code>` in your terminal.
+3. The bridge process stays running. It long-polls Webstew for any agent requests originating from your account.
+4. Each request runs through Claude Agent SDK on your machine, using your Pro/Max subscription. Output streams back to your browser chat.
+
+## Requirements
+
+- Node.js ≥ 18
+- An active Webstew account
+- An active **Claude Pro** or **Claude Max** subscription, authenticated locally (e.g. via Claude Code or the Anthropic CLI). The bridge uses whatever OAuth credentials Claude Code uses.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `webstew-bridge connect <code>` | Pair with a workspace and start the bridge |
+| `webstew-bridge status` | Print connection state |
+| `webstew-bridge logout` | Forget saved pairing token |
+| `webstew-bridge --version` | Print version + protocol version |
+
+## Where your auth lives
+
+The bridge stores its pairing token at `~/.webstew/bridge.json` with `0600` permissions on POSIX (owner-only). The Claude subscription token itself is owned by Claude Code; the bridge invokes Claude Code rather than re-implementing auth.
+
+## Protocol
+
+See [`src/protocol.ts`](./src/protocol.ts) for the wire contract. Versioned via `PROTOCOL_VERSION`; the server rejects bridges on an incompatible major version with an explicit upgrade hint.
+
+## Not for
+
+- **Production deployments** — the bridge is a developer tool. If you publish a site via Webstew, the deploy pipeline runs on Webstew's infra and doesn't touch your bridge.
+- **Multi-user teams** — each user runs their own bridge. There's no concept of a "team bridge" (yet).
+
+## Live E2E test (developer only)
+
+To validate the full flow against a local Webstew dev server:
+
+```bash
+# Terminal 1 — Webstew dev server
+cd /Users/homepc/ai-website-builder/apps/web
+env -u MONGODB_URI npx next dev -p 3000 -H 0.0.0.0
+```
+
+```
+# Browser
+http://localhost:3000/integrations
+# → Click "Connect Local Bridge" → copy the pairing code
+```
+
+```bash
+# Terminal 2 — bridge process pointing at local server
+cd /Users/homepc/ai-website-builder/packages/bridge
+WEBSTEW_SERVER_URL=http://localhost:3000 npx tsx src/cli.ts connect <code>
+# expect: "paired ✓  bridgeId=brg_…", then "bridge online — waiting for work"
+```
+
+```
+# Browser /integrations should auto-flip to "Connected ✓"
+# Browser /workspace → send any chat
+# Terminal 2 should log "▶ request …" → "✓ request … N.Ns"
+# Browser chat should show streaming text + file updates
+```
+
+## Troubleshooting
+
+- **`error: pairing failed (HTTP 400): Pairing code is invalid or expired`**
+  Pairing codes are single-use and expire in 10 minutes. Generate a fresh one in `/integrations`.
+
+- **`error: pairing failed (HTTP 426)`**
+  Your bridge version is on an incompatible protocol. `npm i -g @webstew/bridge@latest`.
+
+- **`claude exited with code 127` (in bridge logs)**
+  The bridge couldn't find the `claude` binary on `PATH`. Install Claude Code first ([claude.com/code](https://claude.com/code)), then restart the bridge.
+
+- **`Local bridge is offline. Start it with webstew-bridge connect …` (in /workspace chat)**
+  Bridge process isn't running, or hasn't checked in for 60s. Restart it in the terminal.
+
+## License
+
+MIT

package/bin/webstew-bridge

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+exec node "$(dirname "$0")/../dist/cli.js" "$@"

package/dist/auth.d.ts

@@ -0,0 +1,25 @@
+export interface BridgeAuth {
+    serverUrl: string;
+    bridgeId: string;
+    pairingToken: string;
+    pairedAt: string;
+}
+export declare function loadAuth(): BridgeAuth | null;
+export declare function saveAuth(a: BridgeAuth): void;
+export declare function clearAuth(): boolean;
+export declare function workspaceDirFor(projectId: string): string;
+/**
+ * Ensure ~/.webstew/mcp.json points at the @webstew/agent-tools MCP
+ * server so claude loads webstew_* tools (CMS, integrations, etc.).
+ * Returns the absolute config path that should be passed to claude as
+ * `--mcp-config <path>`.
+ *
+ * Behavior:
+ *   • If the config already exists, leave it alone (user may have
+ *     customized it).
+ *   • Otherwise, write a default config. In monorepo dev, point at the
+ *     local agent-tools tsx so we don't need a build/publish step.
+ *     In a production install (no local monorepo), point at npx so it
+ *     resolves the published package.
+ */
+export declare function ensureMcpConfig(): string;

package/dist/auth.js

@@ -0,0 +1,142 @@
+"use strict";
+// Local config — pairing token, bridgeId, serverUrl. Stored at
+// ~/.webstew/bridge.json with 0600 perms (owner-only read/write) on
+// POSIX so other local users can't read the token. Same model as
+// ~/.gitconfig + ~/.npmrc style configs.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAuth = loadAuth;
+exports.saveAuth = saveAuth;
+exports.clearAuth = clearAuth;
+exports.workspaceDirFor = workspaceDirFor;
+exports.ensureMcpConfig = ensureMcpConfig;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+function configDir() {
+    return node_path_1.default.join(node_os_1.default.homedir(), '.webstew');
+}
+function configPath() {
+    return node_path_1.default.join(configDir(), 'bridge.json');
+}
+function loadAuth() {
+    try {
+        const raw = node_fs_1.default.readFileSync(configPath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.serverUrl || !parsed.bridgeId || !parsed.pairingToken)
+            return null;
+        return {
+            serverUrl: parsed.serverUrl,
+            bridgeId: parsed.bridgeId,
+            pairingToken: parsed.pairingToken,
+            pairedAt: parsed.pairedAt || new Date().toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function saveAuth(a) {
+    const dir = configDir();
+    node_fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = configPath() + '.tmp';
+    node_fs_1.default.writeFileSync(tmp, JSON.stringify(a, null, 2), { mode: 0o600 });
+    node_fs_1.default.renameSync(tmp, configPath());
+    try {
+        // Belt + suspenders on POSIX — Windows ignores mode but the user
+        // gets owner-only by default anyway.
+        node_fs_1.default.chmodSync(configPath(), 0o600);
+    }
+    catch { }
+}
+function clearAuth() {
+    try {
+        node_fs_1.default.unlinkSync(configPath());
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Per-project workspace dirs. Each Webstew projectId gets its own dir
+// under ~/.webstew/workspaces/<projectId>/ so Claude Code's CLAUDE.md +
+// auto-memory namespace cleanly to that project — same as cd-ing into
+// different repos in regular Claude Code usage.
+function workspaceDirFor(projectId) {
+    const safe = projectId.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64) || 'unscoped';
+    const dir = node_path_1.default.join(configDir(), 'workspaces', safe);
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    // Opportunistically sweep workspaces older than 30 days. Cheap O(n)
+    // scan on entry; the workspace dir is tiny so this never blocks.
+    sweepStaleWorkspaces();
+    return dir;
+}
+function sweepStaleWorkspaces() {
+    const root = node_path_1.default.join(configDir(), 'workspaces');
+    if (!node_fs_1.default.existsSync(root))
+        return;
+    const THIRTY_DAYS = 30 * 24 * 60 * 60 * 1000;
+    const cutoff = Date.now() - THIRTY_DAYS;
+    try {
+        for (const entry of node_fs_1.default.readdirSync(root, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const full = node_path_1.default.join(root, entry.name);
+            try {
+                const { mtimeMs } = node_fs_1.default.statSync(full);
+                if (mtimeMs < cutoff)
+                    node_fs_1.default.rmSync(full, { recursive: true, force: true });
+            }
+            catch { /* non-fatal — skip this dir */ }
+        }
+    }
+    catch { /* non-fatal */ }
+}
+/**
+ * Ensure ~/.webstew/mcp.json points at the @webstew/agent-tools MCP
+ * server so claude loads webstew_* tools (CMS, integrations, etc.).
+ * Returns the absolute config path that should be passed to claude as
+ * `--mcp-config <path>`.
+ *
+ * Behavior:
+ *   • If the config already exists, leave it alone (user may have
+ *     customized it).
+ *   • Otherwise, write a default config. In monorepo dev, point at the
+ *     local agent-tools tsx so we don't need a build/publish step.
+ *     In a production install (no local monorepo), point at npx so it
+ *     resolves the published package.
+ */
+function ensureMcpConfig() {
+    const dir = configDir();
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    const cfgPath = node_path_1.default.join(dir, 'mcp.json');
+    if (node_fs_1.default.existsSync(cfgPath))
+        return cfgPath;
+    // Detect monorepo dev. __dirname of this module sits at
+    // packages/bridge/src/ during dev; sibling packages/agent-tools/src/index.ts
+    // tells us we're in the monorepo and can run tsx directly.
+    const dirname = __dirname;
+    const siblingTs = node_path_1.default.resolve(dirname, '..', '..', 'agent-tools', 'src', 'index.ts');
+    const isMonorepo = node_fs_1.default.existsSync(siblingTs);
+    const config = isMonorepo
+        ? {
+            mcpServers: {
+                webstew: {
+                    command: 'npx',
+                    args: ['--yes', 'tsx', siblingTs],
+                },
+            },
+        }
+        : {
+            mcpServers: {
+                webstew: {
+                    command: 'npx',
+                    args: ['--yes', '@webstew/agent-tools'],
+                },
+            },
+        };
+    node_fs_1.default.writeFileSync(cfgPath, JSON.stringify(config, null, 2));
+    return cfgPath;
+}

package/dist/claude-runner.d.ts

@@ -0,0 +1,10 @@
+import type { AgentRunRequest, BridgeResponse } from './protocol';
+interface RunOpts {
+    request: AgentRunRequest;
+    requestId: string;
+    onEvent: (chunk: BridgeResponse) => Promise<void>;
+    claudeBin?: string;
+    signal?: AbortSignal;
+}
+export declare function runClaudeOnce(opts: RunOpts): Promise<void>;
+export {};