@gakim-digital/dexter-bridge 0.5.0

package/LICENSE

@@ -0,0 +1,16 @@
+Dexter Bridge License
+
+Copyright (c) 2026 InstaWeb AI. All rights reserved.
+
+Permission is granted to download, install, and run this software solely to
+connect your local machine to the Dexter / InstaWeb AI service. You may not
+modify, redistribute, sublicense, or sell this software or use it to build a
+competing service.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# Dexter Bridge
+
+Local Companion CLI for Dexter's Framer plugin.
+
+## Claude Code on macOS
+
+Dexter's Claude setup wizard uses Homebrew so the bridge starts automatically
+at login and the user can close Terminal after setup. The wizard fills in the
+pairing code, API URL, agent, and model:
+
+```bash
+brew install gakim-digital/tap/dexter-bridge \
+  && dexter-bridge pair 123456 --api https://api.example.com/iwm-api/0.0.1 --agent claude-code --model claude-code:sonnet \
+  && brew services restart gakim-digital/tap/dexter-bridge
+```
+
+Claude Code must already be installed and signed in on the same Mac. Pairing
+records the resolved Claude executable path in `~/.dexter-bridge/config.json`
+so the background service can find installations managed by NVM or another
+shell-specific tool.
+
+Useful service commands:
+
+```bash
+brew services info gakim-digital/tap/dexter-bridge
+brew services restart gakim-digital/tap/dexter-bridge
+brew services stop gakim-digital/tap/dexter-bridge
+dexter-bridge status
+dexter-bridge doctor
+```
+
+Users without Homebrew can select the temporary command in the wizard. That
+uses `npx` and must remain open while Dexter is using Claude Code.
+
+## Temporary CLI connection
+
+One command pairs and goes online — the Dexter plugin's Connect wizard prints it
+with your pairing code and API URL filled in:
+
+```bash
+npx --yes @gakim-digital/dexter-bridge@latest connect 123456 --api https://api.example.com/iwm-api/0.0.1 --agent codex
+```
+
+Run `connect` with no code to reuse a saved pairing. Lower-level commands remain
+for support and automation:
+
+```bash
+npx @gakim-digital/dexter-bridge pair 123456 --api http://localhost:3800/iwm-api/0.0.1
+npx @gakim-digital/dexter-bridge start --agent claude-code
+npx @gakim-digital/dexter-bridge start --agent codex
+npx @gakim-digital/dexter-bridge status
+npx @gakim-digital/dexter-bridge doctor
+npx @gakim-digital/dexter-bridge logout
+```
+
+`dry-run` verifies pairing, run polling, and event delivery without editing the
+canvas. `claude-code` executes through its local CLI. Codex uses one persistent
+`codex app-server` process for authentication, threads, usage, and cancellation:
+
+```bash
+DEXTER_BRIDGE_AGENT=claude-code npx @gakim-digital/dexter-bridge start
+DEXTER_BRIDGE_AGENT=codex npx @gakim-digital/dexter-bridge start
+```
+
+Codex App Server threads run with a read-only sandbox and approvals disabled.
+The CLI and desktop bridge keep one app-server process alive across model turns.
+Set `DEXTER_BRIDGE_CODEX_APP_SERVER=false` to temporarily use the legacy
+`codex exec --sandbox read-only --skip-git-repo-check` path.
+The bridge retains at most 32 recent Codex threads by default; override this
+with `DEXTER_BRIDGE_CODEX_MAX_THREADS`.
+
+The CLI stores the device token in `~/.dexter-bridge/config.json` with mode
+`0600` where supported. The macOS desktop app stores the token through Electron
+`safeStorage`, backed by the user’s macOS credential encryption. Dexter platform
+credits are not charged for companion runs; the backend records reported usage
+for visibility.
+
+Claude Code runs use `--output-format json` and Codex runs use `--json` so the
+bridge can report input, output, cache, and reasoning tokens when the local CLI
+provides them. Claude's reported `total_cost_usd` is displayed as an estimated
+API-equivalent cost, not an amount Dexter charged. If an older or customized
+CLI does not support structured output, set `DEXTER_BRIDGE_STRUCTURED_USAGE=false`;
+the run will continue, but its token usage will be marked unavailable rather
+than estimated from text.
+
+## Debugging
+
+The Dexter Bridge terminal is the shell where `dexter-bridge start` is running.
+For each companion run, the bridge also writes a redacted JSONL trace:
+
+```bash
+~/.dexter-bridge/logs/run-<runId>.jsonl
+```
+
+Set `DEXTER_BRIDGE_LOG_DIR=/path/to/logs` to override the location. The desktop
+app writes the same run traces next to its app log; use **Reveal log** in the
+desktop window to open that folder.
+
+Useful events in a stuck run:
+
+- `model_turn` / `agent_process_spawn` — Claude Code or Codex was invoked.
+- `agent_process_timeout` — the local agent did not return before the timeout.
+- `event_post_done` — the bridge returned a model completion to the shared server loop.
+- `run_done` — the local model turn completed.
+
+## Desktop release
+
+From `framer-plugin`:
+
+```bash
+npm run bridge:desktop:dev
+npm run bridge:desktop:build:mac
+npm run bridge:desktop:build:win
+npm run bridge:desktop:dist
+npm --prefix packages/dexter-bridge-desktop run verify:mac
+npm --prefix packages/dexter-bridge-desktop run verify:win
+```
+
+The Mac build emits `.dmg` and `.zip` artifacts from
+`packages/dexter-bridge-desktop/release`.
+
+The Windows x64 build emits an NSIS `.exe` installer and a `.zip` artifact from
+the same release directory. Build it on Windows directly or through
+`.github/workflows/dexter-bridge-windows.yml`; Windows packaging must not depend
+on a developer’s macOS environment.
+
+Release builds automatically sign when a Developer ID identity is available to
+electron-builder. Notarization runs from `afterSign` when either App Store
+Connect API credentials (`APPLE_API_KEY`, `APPLE_API_KEY_ID`,
+`APPLE_API_ISSUER`) or Apple ID credentials (`APPLE_ID`,
+`APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`) are configured. Set
+`DEXTER_REQUIRE_NOTARIZATION=true` in release CI so missing credentials fail the
+build instead of producing an unnotarized artifact.
+
+Windows signing is configured through electron-builder’s standard certificate
+environment variables, such as `CSC_LINK` and `CSC_KEY_PASSWORD`. Set
+`DEXTER_REQUIRE_WINDOWS_SIGNING=true` when running `verify:win` for a public
+release. Unsigned installers are only suitable for internal testing.
+
+The unsigned desktop app is not the public Claude setup path. Until a notarized
+build is available, macOS Claude users should receive the Homebrew service flow
+above.
+
+Recommended release env:
+
+```bash
+FRAMER_COMPANION_DOWNLOAD_URL=https://instawebai.com/dexter-bridge
+NEXT_PUBLIC_DEXTER_BRIDGE_VERSION=0.2.0
+NEXT_PUBLIC_DEXTER_BRIDGE_DOWNLOAD_BASE_URL=https://instawebai.com/downloads/dexter-bridge
+NEXT_PUBLIC_DEXTER_BRIDGE_MAC_ARM64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.2.0-mac-arm64.dmg
+NEXT_PUBLIC_DEXTER_BRIDGE_MAC_X64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.2.0-mac-x64.dmg
+NEXT_PUBLIC_DEXTER_BRIDGE_MAC_ZIP_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.2.0-mac-universal.zip
+NEXT_PUBLIC_DEXTER_BRIDGE_WIN_X64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.2.0-win-x64.exe
+```

package/bin/dexter-bridge.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.js';
+
+runCli(process.argv.slice(2)).catch((error) => {
+  const message = error && typeof error === 'object' && 'message' in error
+    ? error.message
+    : String(error);
+  console.error(`Dexter Bridge failed: ${message}`);
+  process.exitCode = typeof error?.exitCode === 'number' ? error.exitCode : 1;
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@gakim-digital/dexter-bridge",
+  "version": "0.5.0",
+  "description": "Local Companion bridge for the Dexter Framer plugin — runs Codex or Claude Code on your machine.",
+  "type": "module",
+  "bin": {
+    "dexter-bridge": "./bin/dexter-bridge.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "dexter",
+    "framer",
+    "instawebai",
+    "codex",
+    "claude-code"
+  ],
+  "homepage": "https://instawebai.com/dexter-bridge",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "SEE LICENSE IN LICENSE"
+}