From d10cfee34e5e1f18fd92c424765f626f5113415c Mon Sep 17 00:00:00 2001 From: JRS1986 <1651269+JRS1986@users.noreply.github.com> Date: Wed, 20 May 2026 20:13:55 +0200 Subject: [PATCH] Document global CLI installation --- CHANGELOG.md | 7 +++++++ README.md | 29 +++++++++++++++++++++++++- docs/docs/wiki/Getting-Started.md | 34 +++++++++++++++++++++++++++++-- src/coding_scaffold/writers.py | 17 ++++++++-------- tests/test_writers.py | 18 ++++++++++++++++ 5 files changed, 93 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 269b7e3..e17ada7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +### Documentation + +- **Install docs now default to an isolated global CLI.** README, Getting Started, and generated + project onboarding recommend `uv tool install` or `pipx install` from the GitHub repo so users can + run `coding-scaffold` from any project without activating the source checkout's virtual + environment. The clone + editable install path remains documented for contributors. + ## [0.5.1] — 2026-05-19 ### Fixed diff --git a/README.md b/README.md index bad7b59..e26d394 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,34 @@ OpenRouter, GitHub Models, or another compatible provider. ## Install -Recommended with uv: +Recommended for using the CLI from any project: + +```bash +uv tool install git+https://github.com/JRS1986/CodingScaffold.git +``` + +Then open the repo you want to prepare and run: + +```bash +cd ~/dev/my-project +coding-scaffold doctor --target . +coding-scaffold pilot --target . --tool opencode +``` + +This installs `coding-scaffold` into an isolated tool environment and puts the command on your +`PATH`, so you do not have to activate a virtual environment from the CodingScaffold source checkout +before using it elsewhere. + +If you do not use `uv`, `pipx` gives the same global-command shape: + +```bash +pipx install git+https://github.com/JRS1986/CodingScaffold.git +``` + +If your shell cannot find `coding-scaffold` after either command, follow the PATH prompt printed by +`uv` or run `pipx ensurepath`, then restart the shell. + +For contributing to CodingScaffold itself, clone the repo and use the development environment: ```bash git clone https://github.com/JRS1986/CodingScaffold.git diff --git a/docs/docs/wiki/Getting-Started.md b/docs/docs/wiki/Getting-Started.md index 8a7e85a..4815bdd 100644 --- a/docs/docs/wiki/Getting-Started.md +++ b/docs/docs/wiki/Getting-Started.md @@ -50,7 +50,34 @@ runtime, an authenticated CLI, or a cloud/API provider. ## Install -Recommended with uv: +Recommended for using the CLI from any project: + +```bash +uv tool install git+https://github.com/JRS1986/CodingScaffold.git +``` + +Then open the repo you want to prepare and run: + +```bash +cd ~/dev/my-project +coding-scaffold doctor --target . +coding-scaffold pilot --target . --tool opencode +``` + +This installs `coding-scaffold` into an isolated tool environment and puts the command on your +`PATH`, so you do not have to activate a virtual environment from the CodingScaffold source checkout +before using it elsewhere. + +If you do not use `uv`, `pipx` gives the same global-command shape: + +```bash +pipx install git+https://github.com/JRS1986/CodingScaffold.git +``` + +If your shell cannot find `coding-scaffold` after either command, follow the PATH prompt printed by +`uv` or run `pipx ensurepath`, then restart the shell. + +For contributing to CodingScaffold itself, clone the repo and use the development environment: ```bash git clone https://github.com/JRS1986/CodingScaffold.git @@ -76,7 +103,10 @@ On Windows PowerShell outside WSL: .venv\Scripts\Activate.ps1 ``` -`uv.lock` is committed. Use `uv sync --extra dev` for reproducible development and CI parity. +Optional RouteLLM dependencies can be installed with `uv sync --extra dev --extra routellm` or +`python -m pip install -e ".[dev,routellm]"`. + +`uv.lock` is committed. Use `uv sync --extra dev` for reproducible local development and CI parity. ## Prepare A Project diff --git a/src/coding_scaffold/writers.py b/src/coding_scaffold/writers.py index 8071840..0ffc56e 100644 --- a/src/coding_scaffold/writers.py +++ b/src/coding_scaffold/writers.py @@ -751,8 +751,8 @@ def _getting_started_md(intake: IntakeAnswers, routing: RoutingPlan) -> str: ) return f"""# Getting Started -This scaffold is meant to be cloned, installed into a local venv, and run as guided setup inside -the project you want to prepare for AI-assisted coding. +CodingScaffold is meant to be installed once as a global command, then run inside whichever project +you want to prepare for AI-assisted coding. The goal is not just "better autocomplete." The goal is a controlled workflow where agents inspect, plan, edit, verify, review, and preserve the best team habits as reusable skills. @@ -760,16 +760,15 @@ def _getting_started_md(intake: IntakeAnswers, routing: RoutingPlan) -> str: ## Fast Path ```bash -git clone coding-scaffold -cd coding-scaffold -uv venv -source .venv/bin/activate -uv sync --extra dev +uv tool install git+https://github.com/JRS1986/CodingScaffold.git coding-scaffold setup run --target /path/to/your/project ``` -On WSL/Linux the flow is the same. On Windows PowerShell outside WSL, activate with -`.venv\\Scripts\\Activate.ps1`. +If you do not use `uv`, install the same isolated command with +`pipx install git+https://github.com/JRS1986/CodingScaffold.git`. + +After installation, run `coding-scaffold` from the project you are preparing. You should not need +to activate a virtual environment from the CodingScaffold source checkout. ## What Setup Did Here diff --git a/tests/test_writers.py b/tests/test_writers.py index 029c2f1..523cec0 100644 --- a/tests/test_writers.py +++ b/tests/test_writers.py @@ -39,6 +39,24 @@ def test_write_scaffold_creates_expected_files(tmp_path, scaffold_inputs) -> Non assert ".coding-scaffold/AGENTS.md" in version["files"] +def test_generated_getting_started_uses_global_cli_install(tmp_path, scaffold_inputs) -> None: + fixture = scaffold_inputs(tool=None) + write_scaffold( + tmp_path, + fixture.intake, + fixture.hardware, + fixture.providers, + fixture.routing, + ) + + text = (tmp_path / ".coding-scaffold" / "GETTING_STARTED.md").read_text(encoding="utf-8") + assert "uv tool install git+https://github.com/JRS1986/CodingScaffold.git" in text + assert "pipx install git+https://github.com/JRS1986/CodingScaffold.git" in text + assert "source .venv/bin/activate" not in text + assert "should not need" in text + assert "activate a virtual environment" in text + + def test_providers_json_redacts_azure_endpoint(tmp_path, monkeypatch, scaffold_inputs) -> None: from coding_scaffold.providers import detect_providers