Scaffold kcolb CLI composing quoter, gas-oracle, depeg-monitor

[Pattermesh]

What

Scaffolds kcolb, a zero-framework (Python stdlib + argparse) convenience CLI that composes the existing on-disk kcolbchain DeFi toolkits. One subcommand per toolkit:

Subcommand	Wraps	Does
kcolb quote	quoter	constant-spread bid/ask around a mid price
kcolb gas	gas-oracle	predict L2 gas cost N blocks ahead
kcolb depeg	depeg-monitor	median-consensus stablecoin depeg severity

How it composes the toolkits

Each adapter (src/kcolb_cli/adapters/) imports the real toolkit when it is on PYTHONPATH and otherwise falls back to a clearly-labelled, pure-stdlib stub that mirrors the toolkit's core math — so kcolb always runs standalone. Every payload carries a source field ("quoter" / "gas-oracle" / "depeg-monitor", or "stub").

• quote -> src.strategies.constant_spread.compute_quotes (quoter)
• depeg -> depeg_monitor.consensus.compute_consensus (depeg-monitor)
• gas -> gas-oracle is TypeScript (no Python binding), so it always serves the documented stub; a _load_gas_oracle seam is kept for a future binding.

Verified end-to-end that with the real toolkits on PYTHONPATH the source flips to "quoter" / "depeg-monitor" and the numbers match the stub.

All commands support --json. Exit codes: 0 ok, 1 user error, 2 no subcommand (usage printed).

Included

• pyproject.toml with console_scripts entry point kcolb = kcolb_cli.cli:entrypoint
• README.md with usage + architecture, MIT LICENSE, .gitignore
• tests/ — pytest suite (31 tests): arg parsing + subcommand dispatch, each subcommand happy path, --json output, user-error exit codes, and the stub-fallback seam (monkeypatched ImportError)

Tests

$ pytest -q
...............................                                          [100%]
31 passed

Also verified pip install -e . exposes kcolb on PATH and the suite passes against the installed package.

Base main was seeded with LICENSE + README stub + .gitignore in a separate initial commit (the repo was empty).

🤖 Generated with Claude Code

[abhicris]

Welcome to kcolbchain, @Pattermesh — glad you're here. 🌱

Here's what happens from this PR:

1. Our automated review looks for obvious issues (tests, secrets, size) within a couple of hours.
2. If it's clean and CI passes, we merge without back-and-forth.
3. If we need changes, we'll leave a specific comment — not a generic nit. Push another commit and we re-review.

While you wait:

• Run the repo's tests locally (see the repo README.md).
• Keep the PR scoped to one concern — bigger PRs land slower.
• Don't commit tokens or .env contents.

What happens after your first merge

• You're listed on https://kcolbchain.com/contributors/ (opt-out anytime via data/contributors-optout.txt).
• At 2+ merged PRs you're a Regular; at 5+ you're a Fellow — Fellows are the pool we invite first for paid research, partner-org gigs, and grant-funded work. Details: https://kcolbchain.com/docs/org-contribution-policy.html
• Looking for what to pick up next? https://kcolbchain.com/invitations/ lists open help-wanted / good-first-issue across every kcolbchain repo.

Thanks for writing the code. We're building this to last.