Metadata-Version: 2.4
Name: synapse-context-cli
Version: 0.1.0
Summary: CLI for Synapse — push uncommitted code to the WIP cache so MCP-aware AI tools see your live editor state.
Project-URL: Homepage, https://synapse.abhinavaditya.com
Project-URL: Repository, https://github.com/abhinav162/synapse
Project-URL: Documentation, https://github.com/abhinav162/synapse/blob/main/synapse-cli/README.md
Project-URL: Issues, https://github.com/abhinav162/synapse/issues
Author-email: Abhinav Aditya <abhinav.aditya@hirequotient.com>
License: MIT
Keywords: ai,claude,codex,context,cursor,mcp,synapse,wip
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.12
Requires-Dist: gitpython>=3.1
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Requires-Dist: synapse-context-sdk>=0.1.0
Requires-Dist: typer>=0.12
Requires-Dist: watchdog>=4.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Description-Content-Type: text/markdown

# synapse-cli

`synapse` is the developer CLI for the Synapse Universal Memory Layer. It pushes
your uncommitted, work-in-progress code into the Synapse WIP cache so MCP-aware
AI tools (Claude Code, Cursor, etc.) get the *current* state of your editor —
not just whatever was on `main` last night.

## Install

```bash
pip install synapse-context-cli
# or, from a clone:    pip install -e .
```

The distribution name on PyPI is `synapse-context-cli`. The console-script
it installs is still `synapse` — type `synapse sync`, not `synapse-context-cli sync`.

## Authenticate

Two options. **Use device-flow login on developer machines, tokens on CI/headless.**

### Device-flow login (recommended)

```bash
synapse login
```

Walks the GitHub device-authorization flow against the Synapse GitHub App,
exchanges the resulting access token for a Synapse `syn_live_*` API token,
and saves it to `~/.synapse/credentials.json`. One-time setup per machine.

> Make sure you've installed the [Synapse GitHub App](https://github.com/apps/synapse-context)
> on your org first — the device-flow exchange checks org membership.

To log out: `synapse logout`.

### Token mode (CI/headless)

```bash
export SYNAPSE_TOKEN=syn_live_...
export SYNAPSE_API_ENDPOINT=https://synapse.abhinavaditya.com   # optional, default
```

Generate the token from the dashboard at **Settings → API Tokens**.

### Verify

```bash
synapse status        # ping /health, show auth state
synapse status -v     # also list live WIP entries with TTL countdown
```

You should see **API Status: Connected**.

## Usage

### One-shot diff sync

```bash
synapse sync
```

Walks `git diff` (staged + unstaged + untracked, deletes excluded), secret-
scans every file, and POSTs the clean ones to `/wip/sync`. WIP entries live
for 4 hours unless re-synced.

### Full repo sync (first-time index from CLI)

```bash
synapse sync --full
```

Walks the entire working tree (respecting `.gitignore`) and syncs every
tracked / untracked-not-ignored file. Mirrors the initial-install index that
the GitHub App webhook would do — useful for a fresh clone before the
webhook fires.

### Watch mode (daily driver)

```bash
synapse sync --watch
```

Runs an initial sync, then watches the repo. Saves are debounced 1.5s and
filtered against `.gitignore` and `_IGNORED_DIRS` (`.git`, `node_modules`,
build outputs, IDE caches). Stop with `Ctrl-C`. Tune the debounce window
with `--debounce 0.8`.

Want it to survive reboots? `synapse install-service` (see below).

### Dry-run

```bash
synapse sync --dry-run
```

Shows what *would* sync (including secret-scan rejections) without
uploading. Useful for sanity-checking before wiring up an automated hook.

### Pre-commit hook

```bash
synapse sync --pre-commit
```

Scan-only mode: walks staged files, exits non-zero if any contain secrets.
Doesn't upload anything (commits go through the GitHub-webhook → Temporal
pipeline anyway). Wire into `.pre-commit-config.yaml`:

```yaml
- repo: local
  hooks:
    - id: synapse-secret-scan
      name: synapse secret scan
      entry: synapse sync --pre-commit
      language: system
      pass_filenames: false
```

### Background service

```bash
synapse install-service          # current dir, default label "dev.synapse.watch"
synapse install-service --repo ~/code/my-project --label dev.synapse.api
synapse uninstall-service --label dev.synapse.api
```

macOS → drops a launchd plist in `~/Library/LaunchAgents/` and `launchctl load`.
Linux → drops a systemd user unit in `~/.config/systemd/user/` and
`systemctl --user enable --now`. Logs land in `/tmp/<label>.log`.

### Status

```bash
synapse status     # auth + /health
synapse status -v  # also list live WIP entries (file, TTL, repo, branch)
```

## How it interacts with MCP

When an MCP client (Claude Code, etc.) queries Synapse, the server merges
results from three tiers in priority order:

1. **WIP** — Redis, scoped to `(org, user, repo, file_path)`, 4h TTL. This
   is what `synapse sync` writes. Multiple repos at once is supported —
   entries don't collide on overlapping paths.
2. **Feature** — Qdrant, scoped to `feature/{branch}`, 7-day TTL.
3. **Global** — Qdrant, scoped to `global` (= `main`), no TTL.

Higher tiers win on `file_path` collisions, so your in-flight edits
override whatever's in main.

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| `Not logged in.` | Run `synapse login`, or export `SYNAPSE_TOKEN`. |
| `API Status: Unreachable` | Wrong endpoint, or token revoked. Check `synapse status`. |
| `⚠ Secret detected … skipped` | Secret scanner found a credential. Remove it; file syncs next time. |
| `Pre-commit failed: N file(s) contain secrets.` | Same — but blocking your commit by design. |
| MCP tool returns stale code | Run `synapse sync` manually to confirm upload succeeds. Then check `synapse status -v` to see TTL. |
| Watcher fires constantly during builds | Build dirs (`dist/`, `target/`, `.next/`) are already skipped, but if your tool writes to a custom output dir, add it to `.gitignore` — the watcher honours it. |

## Development

```bash
make test               # unit tests (no infra)
make test-integration   # requires SYNAPSE_INTEGRATION=1 + live stack
make benchmark          # KPI: 10-file diff sync < 2s
make lint typecheck     # ruff + mypy --strict
make check              # lint + typecheck + unit
```
