stubborn-watch 0.10.0b1

Dev orchestration: file watch → SCIP indexer → stubborn index --merge

stubborn-watch

Debounced file watch → external SCIP indexer (scip-java) → stubborn index --merge.

Stubborn does not parse Java source. This package only orchestrates the dev loop described in ADR-009.

Install

pip install stubborn-watch

Requires scip-java on PATH for the default indexer command.

Usage

Watch mode (dev loop)

stubborn index --scip index.scip --out symbols.db   # initial full snapshot
stubborn-watch watch --root . --db symbols.db

On save (debounced, default 2s):

1. scip-java index
2. stubborn index --merge for changed relative_path values

One-shot merge (hooks / CI helpers)

stubborn-watch merge-once --root . --db symbols.db \
  --paths com/example/Foo.java,com/example/Bar.java

Use --skip-index when index.scip is already fresh.

Workspace watch (multi-repo)

For source-available internal repos, use a workspace manifest so each repo can index and merge independently into one shared workspace DB:

{
  "workspace": "acme",
  "db": "symbols.db",
  "repos": [
    { "repo_key": "orders-api", "root": "../orders-api", "scip": "index.scip" },
    { "repo_key": "orders-core", "root": "../orders-core", "scip": "index.scip" }
  ]
}

stubborn-watch workspace-watch --manifest stubborn-workspace.json
stubborn context symbols.db --workspace acme --target "<stable_id>"

Validation scope

This repo owns orchestration-focused validation:

• CLI smoke for merge-once
• debounce and path normalization
• subprocess invocation contracts around scip-java

The canonical ADR-009 runnable demo lives in stubborn-demo:

• stubborn-demo/demo-spring/scripts/run-merge-e2e.sh

That keeps stubborn-watch focused on watch behavior, while stubborn-demo owns runnable demo assets and black-box validation projects.

Options

Flag	Default	Purpose
--root	.	Project root
--db	(required)	SQLite symbol graph
--scip	index.scip	SCIP index path
--debounce	2.0	Seconds to coalesce events
--pattern	**/*.java	Watched file glob
--scip-cmd	scip-java index	External indexer command
--workspace	—	Workspace name for repo-scoped merges
--repo	—	Repo key for repo-scoped merges

Setup diagnostics

Read-only dev-loop prerequisites (ADR-015) — does not start watch or invoke scip-java:

stubborn-watch doctor --root . --db symbols.db
stubborn-watch doctor --json

Related

• stubborn — core compiler + --merge
• stubborn-mcp — MCP server over the same symbols.db
• stubborn-demo — runnable demos and validation projects
• stubborn-hub — program architecture

License

MIT — see LICENSE.