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

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.