# SnapBack

SnapBack is a local-first VS Code extension + CLI + MCP-capable core that turns vague coding requests into a `TaskContract`, then runs drift/sludge guard checks against the active task.

This repository is the public TypeScript monorepo for the deterministic-first `v0.2.1` MVP.

This repository now contains a runnable first-stage MVP centered on the public `v0.2.1` contract schema and implementation.

## Status

Current maturity:

- Public MVP / early open-source baseline
- Deterministic contract generation, no LLM dependency required
- Generic + JS/TS + Python analyzer coverage at MVP depth
- CLI, runnable MCP stdio server, and installable VS Code extension with proactive reminders, diagnostics, and review-plan flows

Not yet complete:

- Fully stable VS Code host smoke execution across restricted/headless environments
- Production-grade release/versioning automation
- Broader real-world project fixtures and performance tuning


## Supported MVP flows

- `snapback init`
- `snapback task "..."` with `needs_user_input` / `provisional` / `ready`
- `snapback answer --task ... --question ... --value ...`
- `snapback explain`
- `snapback guard --json`
- `snapback audit --json`
- `snapback patch --plan`
- `snapback handoff --close`

## Current analyzer coverage

- Long file detection
- JS/TS long function and branching detection
- Python long function and all-in-one script detection
- Missing verification detection
- Frontend UI responsibility leak heuristic
- Backend route DB-write leak heuristic
- Agent prompt/tool/memory/fallback co-occurrence leak heuristic
- Contract drift detection against the active task scope
- Patch churn detection based on task snapshot history
- Fallback smell detection for repeated fallback/default logic

## Config runtime

`snapback.config.json` is now read at runtime by the generic analyzer.

Supported MVP behavior:

- `config > preset > generic` rule precedence
- `thresholds.generic_file_max_lines`
- `thresholds.patch_churn_count`
- `accepted_patterns`
- `analyzers.generic / analyzers.js_ts / analyzers.python`

## Install

```bash
corepack prepare pnpm@10.13.1 --activate
corepack pnpm install
```

## Build and test

```bash
corepack pnpm build
corepack pnpm test
```

## VS Code extension smoke test

```bash
corepack pnpm build
corepack pnpm test:extension-host
```

Note:

- This test launches a real VS Code desktop host.
- In restricted GUI/sandbox environments it may time out even when `build`, `test`, and `.vsix` packaging succeed.

## Start the MCP server

```bash
corepack pnpm build
corepack pnpm mcp:start
```

## Repository conventions

- Generated artifacts like `dist/`, `node_modules/`, `.snapback/`, and `tmp/` are ignored by git.
- Package build output excludes test source files.
- CI runs build and test on every push and pull request.
- Product/source-of-truth docs remain in the repository while the implementation catches up.

## CLI examples

```bash
node packages/cli/dist/index.js init
node packages/cli/dist/index.js task "add oauth login"
node packages/cli/dist/index.js explain
node packages/cli/dist/index.js guard --json
node packages/cli/dist/index.js patch --plan
```

## Package the extension

```bash
corepack pnpm package:extension
```

This produces `artifacts/snapback-vscode.vsix`.

## Install and try the VS Code extension

1. Package the extension:

```bash
corepack pnpm package:extension
```

2. Install the local artifact:

```bash
code --install-extension artifacts/snapback-vscode.vsix --force
```

3. Reload VS Code and open one of the example workspaces:

```bash
code examples/express-api-demo
```

4. Run `SnapBack: Start Task` from the Command Palette and enter a real requirement such as:

```text
add order cancel endpoint with refund
```

5. Save a related or out-of-scope file to trigger proactive guard behavior.

Expected extension behavior:

- Status bar shows `SnapBack: On Track / Drift / Sludge Risk`
- Active task creation can ask blocking questions before continuing
- Saving files can trigger a proactive reminder with only `Review Plan` and `Later`
- `Review Plan` opens the detailed panel with findings, patch plan, and task-scoped actions
- Findings appear in VS Code diagnostics / Problems

## Notes

- The MVP is deterministic-first and does not require an LLM provider.
- `provisional` is a real contract status in the schema and runtime flow.
- `.snapback/tasks/<task_id>/contract.json` is the durable task record; `.snapback/active-task.json` is only the pointer.
- v0.2.1 preserves the v0.2 contract field names; it does not adopt v0.3/v0.4 naming changes.
- Static fixtures for `contract drift`, `fallback smell`, and `patch churn` live under `tests/fixtures/`.
- The extension is currently distributed as a local `.vsix` artifact, not through the Visual Studio Marketplace or Open VSX.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md), [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md), and [SECURITY.md](./SECURITY.md).