open-index/open-npm huggingface dataset:
npm package: @gluecharm-lab/bridge
Description: Local bridge between Gluecharm web app and Cursor/VS Code extension
Latest version: 0.1.7

# @gluecharm-lab/bridge

Local daemon that connects the Gluecharm web app (gluecharm.com) with the Gluecharm Cursor/VS Code extension. It runs on your machine and is only reachable on localhost.

## Install and run

**Install from npm (published package):** `npm install -g @gluecharm-lab/bridge` or use `npx @gluecharm-lab/bridge start`. See [User manual: Install and run from npm](.gluecharm/docs/USER-MANUAL/user-manual-srs-24.md) for details.

### Install (local development)

```bash
npm install
npm run build
npm link
```

### Start the bridge

```bash
gluecharm-bridge start
```

Or without linking (e.g. from another machine or via npx):

```bash
npx gluecharm-bridge start
```

The bridge picks a free port (typically 7891, then 7892 if 7891 is in use) and writes it to **`~/.gluecharm/bridge.lock`** along with an ephemeral secret. The Gluecharm extension reads this file to connect. You should see something like:

```
Gluecharm Bridge running on http://localhost:7891
```

(The port in the message is the one actually in use; check `~/.gluecharm/bridge.lock` for the exact `port` and `secret`.)

- **Credentials (SRS-17):** The Technical Connect view in the web app can send GlueCharm API credentials to the bridge via `POST /gluecharm/credentials` (with `X-Bridge-Secret`). They are stored in **`~/.gluecharm/credentials.json`** (mode 0600). The bridge refreshes the access token when expired (same policy as the frontend: 120 s before expiry) and uses the stored token for outbound GlueCharm API calls. The extension does not call the API directly; it goes through the bridge. To use a different auth API for refresh, set `GLUECHARM_AUTH_API_URL` (default: `https://system-manager-api.staging.gluecharm.info:8092`).

- **Single instance:** Only one Gluecharm Bridge runs per machine. If you start a second one while the first is still running, it exits with: `Another Gluecharm Bridge is already running (PID …). Exiting.`
- **Idle shutdown:** If no extension is connected for 5 minutes, the bridge exits and removes the lock file.

### Test the bridge

With the bridge running in another terminal, from the repo root:

```bash
./scripts/test-bridge.sh
```

This reads `~/.gluecharm/bridge.lock` for port and secret, then checks `/ping` and `/bridge/register`. If both succeed, the bridge is ready for the extension.

Or test manually (use the port from the console or from `~/.gluecharm/bridge.lock`):

```bash
curl http://localhost:7891/ping
# → { "status": "pong", "version": "0.1.0" }
```

### Run without linking (from repo)

```bash
npm run build
node bin/gluecharm-bridge.js start
```

### Run acceptance criteria tests

From the repo root:

```bash
./scripts/run-ac-tests.sh
```

### Teardown

```bash
npm unlink -g @gluecharm-lab/bridge
```