weld-cli 0.6.0__tar.gz

weld_cli-0.6.0/.claude/docs/DOCS_BEST_PRACTICES.md

@@ -0,0 +1,209 @@
+## Best practices for user docs for a Python CLI tool (OSS-grade)
+
+### 1) Define your doc set (minimum viable, then scale)
+
+**Minimum**
+
+* **README.md**: fast onboarding + core commands.
+* **`mycli --help`**: authoritative CLI reference for flags/args.
+* **Command reference** (docs site or `/docs`): one page per command + examples.
+
+**Common additions**
+
+* **Installation**: pipx / uv tool install / pip / brew (if you ship it).
+* **Configuration**: file format, env vars, precedence, locations.
+* **Tutorials**: 2–3 end-to-end workflows users actually do.
+* **How-to**: targeted tasks (“use dry-run”, “debug logging”, “CI integration”).
+* **Troubleshooting**: known errors, exit codes, common gotchas.
+* **FAQ**: concise answers, links to deeper docs.
+* **Changelog** + **Upgrade notes**: breaking changes and migration steps.
+
+---
+
+### 2) Optimize for “first success in 2 minutes”
+
+Your README should contain, in this order:
+
+1. **One-sentence value** (what it does, who for).
+2. **Install** (one preferred method, others collapsed).
+3. **Quick start**: 3–5 commands that produce a visible result.
+4. **Common workflows**: 2–4 examples.
+5. **Configuration**: where config lives + minimal example.
+6. **Support**: how to file issues, debug info to include.
+
+Pattern for quick start:
+
+```bash
+uv tool install mycli
+mycli init
+mycli run plan.md
+mycli status
+```
+
+---
+
+### 3) Make the CLI self-documenting
+
+**`--help` quality is part of docs quality.**
+
+Best practices:
+
+* Every command has:
+
+  * short summary
+  * longer help text
+  * examples (even 1 is enough)
+* Flags:
+
+  * consistent naming (`--dry-run`, `--debug`, `--json`, `--config`, `--version`)
+  * clear defaults shown in help output
+* Subcommands are discoverable:
+
+  * `mycli help`
+  * `mycli <cmd> --help`
+
+If using Typer/Click, invest in:
+
+* good parameter names
+* `help=` strings everywhere
+* sane defaults
+
+---
+
+### 4) Document output contracts (users build automation)
+
+If people will script your tool, document:
+
+* **Exit codes** (table)
+* **stdout vs stderr** behavior
+* **JSON output schemas** (`--json`), stability guarantees:
+
+  * “stable fields” vs “best-effort fields”
+* **Determinism** expectations (ordering, timestamps, concurrency)
+
+Example exit code contract:
+
+* `0` success
+* `1` runtime error
+* `2` usage error (bad args/config)
+* `3` partial success / some checks failed (if relevant)
+
+---
+
+### 5) Configuration docs: be explicit and testable
+
+Users fail most often on config.
+
+Include:
+
+* **Search path** (e.g. current dir → XDG → home)
+* **Precedence**: flags > env > config file > defaults
+* **Full config reference** (generated if possible)
+* A “minimal config” and a “full config” example
+* Validation behavior: what happens on unknown keys / wrong types
+
+If you support env vars, document them in a dedicated table:
+
+* name, type, default, example, related flags.
+
+---
+
+### 6) Examples that match real user intent
+
+Prefer “task-based” pages over exhaustive prose.
+
+* “Run in dry-run mode to preview changes”
+* “Enable debug logs and collect diagnostics for an issue”
+* “Integrate with CI (GitHub Actions)”
+* “Use JSON output with jq”
+* “Handle non-zero exit codes in bash”
+
+Each example should show:
+
+* command
+* expected output snippet (short)
+* what to do next
+
+---
+
+### 7) Keep docs versioned and tied to releases
+
+Best practice for OSS:
+
+* Host docs per version (or at least “latest” + “stable”).
+* At minimum: docs in repo; release tags preserve exact docs state.
+* For breaking changes, add a dedicated **Upgrade Guide** section and link it from release notes.
+
+---
+
+### 8) Choose a docs toolchain that fits CLI repos
+
+Recommended:
+
+* **MkDocs + mkdocs-material**: simple, fast, great UX.
+* Keep docs in `docs/`, build on CI, deploy to GitHub Pages.
+
+Doc site structure that scales:
+
+```
+docs/
+  index.md
+  install.md
+  quickstart.md
+  commands/
+    init.md
+    run.md
+    status.md
+    checks.md
+  config.md
+  tutorials/
+    workflow-basic.md
+    ci-github-actions.md
+  troubleshooting.md
+  faq.md
+```
+
+---
+
+### 9) Troubleshooting: include a diagnostics checklist
+
+Have a “copy/paste for issues” section:
+
+* `mycli --version`
+* `python --version`
+* OS info
+* config file used
+* command invoked
+* `--debug` logs (redaction guidance)
+* relevant output files/artifacts paths
+
+Also document:
+
+* common permission errors
+* path issues
+* lockfile/state issues (if your tool uses locks)
+* proxy/network behavior (if applicable)
+
+---
+
+### 10) Doc quality gates (enterprise habit)
+
+Add CI that fails if docs break:
+
+* Build docs on PRs (MkDocs build)
+* Check links (optional)
+* Spellcheck (optional, but useful at scale)
+* Ensure `--help` output is updated if you snapshot it
+
+---
+
+## Recommended “minimum bar” for your CLI (given your features like `--dry-run`, `--debug`, checks)
+
+* README with install + quick start + “how it works” paragraph
+* Command docs: `init`, `plan`, `implement`, `review`, `checks`, `status`, `commit`
+* Config docs including new checks categories and defaults
+* “CI integration” how-to
+* Troubleshooting page covering locks, stale locks, debug logs, non-zero exit codes
+* Output contract page (`--json`, exit codes)
+
+If you share your command list (or `mycli --help` output), I can propose an exact docs IA (page tree) and draft the README + 2–3 core docs pages in your style.

weld_cli-0.6.0/.claude/docs/PYTHON_BEST_PRACTICES.md

@@ -0,0 +1,215 @@
+## Enterprise-grade best practices for a `uv`-managed Python CLI tool
+
+### Project layout (CLI-first, testable, packageable)
+
+Use `src/` layout and keep CLI thin.
+
+```
+mycli/
+  pyproject.toml
+  uv.lock
+  src/mycli/
+    __init__.py
+    __main__.py
+    cli.py
+    commands/
+      __init__.py
+      foo.py
+    core/
+      __init__.py
+      logic.py
+    services/
+      __init__.py
+      fs.py
+      net.py
+  tests/
+    test_cli.py
+    test_logic.py
+  README.md
+```
+
+Principles
+
+* **`cli.py`**: argument parsing + command dispatch only.
+* **`core/`**: pure logic, easy unit tests.
+* **`services/`**: side effects (filesystem/network/subprocess), injectable/mocked.
+
+---
+
+## `uv` workflow standard (local + CI)
+
+### Commands developers run
+
+* Install/sync: `uv sync`
+* Run CLI: `uv run mycli ...`
+* Run tests: `uv run pytest`
+* Lint: `uv run ruff check .`
+* Format: `uv run ruff format .` (or `uv run black .`)
+* Typecheck: `uv run pyright`
+
+### CI should run (no autofix)
+
+* `uv sync --frozen`
+* `uv run ruff format --check .`
+* `uv run ruff check .`
+* `uv run pyright`
+* `uv run pytest -q --maxfail=1`
+* `uv run pip-audit` (or `uv run pip-audit -r <exported requirements>` if needed)
+
+---
+
+## `pyproject.toml` baseline (uv + CLI + quality gates)
+
+```toml
+[project]
+name = "mycli"
+version = "0.1.0"
+description = "My CLI tool"
+requires-python = ">=3.11"
+dependencies = [
+  "typer>=0.12",
+  "rich>=13.7",
+]
+
+[project.scripts]
+mycli = "mycli.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E","F","I","UP","B","SIM","C4","RUF"]
+ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pyright]
+typeCheckingMode = "standard"
+pythonVersion = "3.11"
+include = ["src"]
+```
+
+Notes
+
+* `project.scripts` makes a proper entry point (`mycli`).
+* `hatchling` is a clean default build backend for CLIs.
+* Ruff rule-set chosen for CLI repos: correctness + modernization + import hygiene.
+
+---
+
+## CLI implementation best practices (enterprise-grade)
+
+### Use a real CLI framework
+
+* Prefer **Typer** (excellent UX, type-hints map well to args/options).
+* Alternate: Click (mature), argparse (stdlib, minimal deps).
+
+### Make failures predictable
+
+* Exit codes: `0` success, `1` generic error, `2` usage error, etc.
+* Print user-facing errors to **stderr**, and keep them concise.
+* Provide `--json` for machine-readable output if automation matters.
+
+### Logging strategy
+
+* Default: quiet user output; add `--verbose/-v` for logs.
+* For CI / automation: `--log-level` and `--no-color`.
+* If you emit logs, separate them from primary output (stderr vs stdout).
+
+### Configuration
+
+* Support precedence:
+
+  1. CLI flags
+  2. environment variables
+  3. config file (e.g., `~/.config/mycli/config.toml`)
+  4. defaults
+* Use `platformdirs` to locate config directories.
+
+---
+
+## Testing strategy for a CLI tool
+
+### Unit tests
+
+* Pure logic in `core/` with straightforward tests.
+
+### CLI tests
+
+* For Typer: `typer.testing.CliRunner()`
+* Assert:
+
+  * exit code
+  * stdout/stderr
+  * behavior under invalid args
+  * behavior with env vars / config
+
+### Integration tests (optional but common)
+
+* Use `tmp_path` for filesystem scenarios.
+* Mock network/subprocess calls unless you explicitly test them behind a marker.
+
+---
+
+## Security + supply chain for CLIs
+
+* Dependency scanning: `pip-audit` in CI.
+* Secret scanning: `detect-secrets` or `gitleaks` pre-commit + CI.
+* If invoking subprocesses:
+
+  * avoid `shell=True`
+  * sanitize args
+  * timeouts everywhere
+* If handling files:
+
+  * avoid unsafe path joins (validate inputs; use `pathlib`)
+
+---
+
+## Pre-commit (works perfectly with `uv run`)
+
+`.pre-commit-config.yaml` recommended hooks:
+
+* ruff (lint)
+* ruff (format)
+* pyright (optional; can be slow but doable)
+* detect-secrets
+
+Run hooks via:
+
+* `uv run pre-commit install`
+* `uv run pre-commit run -a`
+
+---
+
+## Release and packaging (CLI distribution)
+
+* Build: `uv run python -m build`
+* Publish: `uv run twine upload dist/*`
+* Add `--version` and `mycli version` command (handy for support).
+* Consider shipping a single-file binary (optional):
+
+  * `pyinstaller` / `shiv` / `pex` depending on target environment.
+
+---
+
+## CI (GitHub Actions skeleton for `uv`)
+
+Core pattern:
+
+* checkout
+* install uv
+* `uv sync --frozen`
+* run quality gates listed above
+
+---
+
+If you want, I can output a complete ready-to-drop-in repo scaffold: `pyproject.toml`, `ruff/pyright` settings, `pre-commit` config, and a GitHub Actions workflow using `uv sync --frozen`, plus a minimal Typer-based CLI with one command and tests.

weld_cli-0.6.0/.claude/docs/RELEASE_WORKFLOW.md

@@ -0,0 +1,272 @@
+## Best practices spec: OSS `uv` package releases via GitHub tag → CI → GitHub Release (+ PyPI)
+
+### Goals
+
+* Release is **triggered by pushing a git tag** `vX.Y.Z`.
+* CI **creates a GitHub Release** and **publishes to PyPI**.
+* GitHub Release notes are **pulled automatically from `CHANGELOG.md`**.
+* Release is **reproducible** and **fails early** on versioning/changelog mistakes.
+* Prefer **PyPI Trusted Publishing (OIDC)** over long-lived API tokens.
+
+---
+
+## Repository requirements
+
+### 1) Version source of truth
+
+* `pyproject.toml` contains `project.version = "X.Y.Z"`.
+* The git tag is `vX.Y.Z`.
+* CI must assert: `tag_version == pyproject_version`.
+
+### 2) Changelog format (Keep a Changelog compatible)
+
+`CHANGELOG.md` must have:
+
+* An `## [Unreleased]` section at the top.
+* Released sections like: `## [0.1.0] - 2026-01-04`
+* Content under headings (`###`, `####`, etc.) is allowed.
+
+Example:
+
+```md
+## [Unreleased]
+### Added
+- ...
+
+## [0.1.0] - 2026-01-04
+Initial release...
+```
+
+---
+
+## Release process (human + automation)
+
+### Human steps (per release)
+
+1. Move entries from `## [Unreleased]` into a new version section `## [X.Y.Z] - YYYY-MM-DD`.
+2. Ensure `pyproject.toml` version is set to `X.Y.Z`.
+3. Commit to `main`.
+4. Create annotated tag: `git tag -a vX.Y.Z -m "vX.Y.Z"`.
+5. Push tag: `git push origin vX.Y.Z`.
+
+### CI responsibilities (on tag push)
+
+1. Checkout with full history.
+2. Install `uv`, sync dependencies with lockfile (`--frozen`).
+3. Run quality gates (format, lint, typecheck, tests).
+4. Extract version from tag.
+5. Verify `pyproject.toml` version matches tag.
+6. Verify `CHANGELOG.md`:
+
+   * `[X.Y.Z]` section exists.
+   * `## [Unreleased]` is **empty** (recommended gate).
+7. Extract release notes from the `[X.Y.Z]` section and write `RELEASE_NOTES.md`.
+8. Build sdist + wheel once.
+9. Publish to PyPI (Trusted Publishing preferred).
+10. Create GitHub Release using extracted notes and attach artifacts.
+
+---
+
+## Changelog extraction spec (tailored to your structure)
+
+### A) Extract release notes for version `X.Y.Z`
+
+Rules:
+
+* Find section header matching `^## \[X.Y.Z\]` (date suffix optional).
+* Capture everything until the next `^## \[` section header or EOF.
+* Exclude the header line itself.
+* Preserve all markdown below (including nested headings).
+
+Reference implementation (`scripts/extract_release_notes.py`):
+
+```python
+import re, sys, pathlib
+
+version = sys.argv[1]
+text = pathlib.Path("CHANGELOG.md").read_text(encoding="utf-8")
+
+pattern = rf"""
+^##\s+\[{re.escape(version)}\][^\n]*\n
+(.*?)
+(?=^##\s+\[|\Z)
+"""
+
+m = re.search(pattern, text, re.S | re.M | re.X)
+if not m:
+    raise SystemExit(f"CHANGELOG.md missing section for [{version}]")
+
+notes = m.group(1).strip()
+pathlib.Path("RELEASE_NOTES.md").write_text(notes + "\n", encoding="utf-8")
+```
+
+### B) Enforce “Unreleased is empty” on tag builds (recommended)
+
+Rule:
+
+* Extract the body of `## [Unreleased]`.
+* If it contains non-whitespace content, fail the release.
+
+Reference implementation (`scripts/assert_unreleased_empty.py`):
+
+```python
+import re, pathlib
+
+text = pathlib.Path("CHANGELOG.md").read_text(encoding="utf-8")
+m = re.search(r"^##\s+\[Unreleased\]\n(.*?)(?=^##\s+\[|\Z)", text, re.S | re.M)
+
+if m and m.group(1).strip():
+    raise SystemExit("Unreleased section is not empty — move entries into the release section before tagging.")
+```
+
+Policy note:
+
+* This is a “hard gate” that prevents accidental partial releases.
+* If you want a softer policy, change it to warn-only (not recommended for clean OSS releases).
+
+---
+
+## GitHub Actions workflow (tag push trigger)
+
+Create: `.github/workflows/release.yml`
+
+```yaml
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Sync deps (locked)
+        run: uv sync --frozen
+
+      - name: Quality gates
+        run: |
+          uv run ruff format --check .
+          uv run ruff check .
+          uv run pyright
+          uv run pytest -q
+
+      - name: Extract version from tag
+        id: tag
+        run: echo "version=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
+
+      - name: Verify pyproject version matches tag
+        run: |
+          uv run python - <<'PY'
+          import tomllib
+          v=tomllib.load(open("pyproject.toml","rb"))["project"]["version"]
+          tv="${{ steps.tag.outputs.version }}"
+          assert v==tv, f"pyproject version {v} != tag {tv}"
+          PY
+
+      - name: Ensure Unreleased is empty
+        run: uv run python scripts/assert_unreleased_empty.py
+
+      - name: Extract release notes from CHANGELOG.md
+        run: uv run python scripts/extract_release_notes.py "${{ steps.tag.outputs.version }}"
+
+      - name: Build (sdist + wheel)
+        run: uv run python -m build
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+      - name: Create GitHub Release + upload artifacts
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" \
+            --title "${GITHUB_REF_NAME}" \
+            --notes-file RELEASE_NOTES.md \
+            dist/*
+```
+
+---
+
+## PyPI publishing (recommended: Trusted Publishing)
+
+### Setup (one-time)
+
+1. Create the project on PyPI (or publish once manually).
+2. In PyPI project settings, add a **Trusted Publisher**:
+
+   * Provider: GitHub
+   * Repo: your org/repo
+   * Workflow: `.github/workflows/release.yml`
+3. Ensure GitHub Actions has:
+
+   * `permissions: id-token: write`
+
+### Fallback (token-based)
+
+If Trusted Publishing is not possible:
+
+* Store `PYPI_API_TOKEN` as a GitHub secret.
+* Replace publish step:
+
+```yaml
+- uses: pypa/gh-action-pypi-publish@release/v1
+  with:
+    password: ${{ secrets.PYPI_API_TOKEN }}
+```
+
+---
+
+## Hardening checklist (recommended for serious OSS)
+
+### Reproducibility
+
+* Commit `uv.lock`.
+* Use `uv sync --frozen` in CI.
+* Build artifacts only after tests pass.
+
+### Security
+
+* Add dependency audit on tag builds (or every PR):
+
+  * `uv run pip-audit`
+* Add secret scanning:
+
+  * `gitleaks` or `detect-secrets` in pre-commit + CI
+
+### Release integrity
+
+* Fail if:
+
+  * tag version != pyproject version
+  * changelog section missing
+  * Unreleased is non-empty
+  * tests/lint/typecheck fail
+  * build fails
+
+---
+
+## Expected conventions
+
+* Tags are `vX.Y.Z`.
+* Changelog headers are `## [X.Y.Z] - YYYY-MM-DD`.
+* `CHANGELOG.md` is authoritative release notes source.
+* CI is authoritative publisher and release creator.