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

Related MCP server: Primitiv

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

corepack prepare pnpm@10.13.1 --activate
corepack pnpm install

Build and test

corepack pnpm build
corepack pnpm test

VS Code extension smoke test

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

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

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

corepack pnpm package:extension

This produces artifacts/snapback-vscode.vsix.

Install and try the VS Code extension

1. Package the extension:

corepack pnpm package:extension

2. Install the local artifact:

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

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

code examples/express-api-demo

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

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, CODE_OF_CONDUCT.md, and SECURITY.md.