wealthbox-cli 2.3.1__tar.gz → 2.4.1__tar.gz

wealthbox_cli-2.4.1/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+
+updates:
+  # Keep GitHub Actions up to date
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore(ci)"
+
+  # Keep Python dependencies up to date (pyproject.toml)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "chore(deps)"

wealthbox_cli-2.4.1/.github/workflows/ci.yml

@@ -0,0 +1,111 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run ruff check src/ tests/
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      - name: Run tests (ubuntu, with coverage gate)
+        if: matrix.os == 'ubuntu-latest'
+        run: uv run pytest --cov=src/wealthbox_tools --cov-report=term --cov-fail-under=91
+      - name: Run tests (windows, no coverage gate)
+        if: matrix.os == 'windows-latest'
+        run: uv run pytest
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run mypy src/
+
+  smoke:
+    # Install the built wheel in isolation WITHOUT dev dependencies and run the
+    # entrypoint, so a missing runtime dependency (e.g. a module-level import of
+    # a package typer no longer pulls in) is caught before publish. The normal
+    # test job always has dev deps present and cannot catch this.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.12"
+      - name: Build and smoke-test clean install
+        shell: bash
+        run: |
+          uv build
+          uv run --isolated --no-project --with "$(ls dist/*.whl)" wbox --version
+          uv run --isolated --no-project --with "$(ls dist/*.whl)" wbox notes --help
+
+  skill-ref-drift:
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run wbox internals regen-skill-refs
+      - run: git diff --exit-code -- src/wealthbox_tools/skills/wealthbox-crm/references/
+
+  publish:
+    needs: [lint, test, typecheck, smoke, skill-ref-drift]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.12"
+      - name: Check changelog matches version
+        run: |
+          python - <<'PY'
+          import re, pathlib, sys
+          ver = re.search(r'^version\s*=\s*"([^"]+)"', pathlib.Path("pyproject.toml").read_text(encoding="utf-8"), re.M).group(1)
+          m = re.search(r'^##\s*\[([0-9]+\.[0-9]+\.[0-9]+)\]', pathlib.Path("CHANGELOG.md").read_text(encoding="utf-8"), re.M)
+          top = m.group(1) if m else None
+          print(f"pyproject={ver} changelog={top}")
+          sys.exit(0 if top == ver else 1)
+          PY
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

{wealthbox_cli-2.3.1 → wealthbox_cli-2.4.1}/.github/workflows/release-binaries.yml

@@ -59,10 +59,10 @@ jobs:
             binary: wbox-windows-x64.exe
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 

wealthbox_cli-2.4.1/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      - id: ruff
+        files: ^(src|tests)/
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy (strict)
+        language: system
+        entry: uv run mypy src/
+        pass_filenames: false
+        types: [python]
+
+      - id: skill-ref-drift
+        name: skill-ref drift check
+        language: system
+        entry: bash -c 'uv run wbox internals regen-skill-refs && git diff --exit-code -- src/wealthbox_tools/skills/wealthbox-crm/references/'
+        pass_filenames: false
+        always_run: true

{wealthbox_cli-2.3.1 → wealthbox_cli-2.4.1}/CHANGELOG.md

@@ -4,6 +4,135 @@ All notable changes to `wealthbox-cli` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.1] - 2026-06-12
+
+Patch release fixing a startup crash in 2.4.0. The `cli/_factory.py` module
+(introduced in the 2.4.0 refactor) imported `click` at module level to
+annotate a `TyperGroup` subclass, but `click` is only referenced in type
+annotations. On installs where `typer` (>=0.26) does not pull in `click` as a
+transitive dependency, `wbox` crashed on launch with
+`ModuleNotFoundError: No module named 'click'` — the same failure class fixed
+for `skill_ref_gen` in 2.3.1. This was not caught by CI because the test
+environment always has `click` present via the dev dependencies.
+
+### Fixed
+- `wbox` startup crash (`ModuleNotFoundError: click`) on clean installs that
+  lack `click`. The `import click` in `cli/_factory.py` is now guarded by
+  `TYPE_CHECKING` (it is only used in annotations, which are not evaluated at
+  runtime under `from __future__ import annotations`).
+
+### Internal
+- CI gains a `smoke` job that installs the built wheel in isolation **without
+  dev dependencies** and runs `wbox --version`, so a missing-runtime-dependency
+  startup crash can no longer reach PyPI. The `publish` job now depends on it.
+
+## [2.4.0] - 2026-06-12
+
+The notable user-facing change in this release is **differentiated CLI exit
+codes** — scripts that branch on a specific non-zero code should read the note
+below. Beyond that, 2.4.0 is largely an internal hardening release: `src/` is
+now `mypy --strict` clean and gated in CI, the test matrix gained a Windows leg
+and a coverage floor, and the CLI command layer was refactored onto a shared
+resource-command factory. Command syntax, options, help text, and output are
+unchanged.
+
+### Changed
+- **Differentiated CLI exit codes (behavior change).** Previously every error
+  exited with code `1`. `wbox` now distinguishes failure classes: validation /
+  user errors and non-auth `4xx` responses (e.g. `404`, `422`) still exit `1`,
+  authentication errors (`401`/`403`) now exit **`2`**, and server errors
+  (`5xx`) now exit **`3`**. Scripts that branched on a specific non-zero code
+  for auth or server failures must be updated. (Click usage errors — unknown
+  flags, missing arguments — continue to exit `2` as before; that overlap is
+  pre-existing.)
+
+### Added
+- `WBOX_DEBUG` environment variable: set it to any non-empty value (e.g.
+  `WBOX_DEBUG=1`) to print the full Python traceback to stderr alongside the
+  friendly one-line error message. The mapped exit code is unchanged, so it is
+  safe to enable in scripts.
+- Documented the existing `WBOX_BRIEF` / `--brief` output mode (strips `*_html`
+  duplicate fields to cut response size) in the README and CLI reference.
+
+### Security
+- Token config file (`config.json`) and the rate-limit state file are now
+  written with `0600` permissions on POSIX so other local users cannot read a
+  stored token.
+- Malformed `Retry-After` response header values are truncated to 100
+  characters before being logged, bounding a hostile/oversized header.
+
+### Internal
+- **Typing:** `src/` is now `mypy --strict` clean (zero errors, zero
+  `type: ignore`). Client mixins share a typed request protocol and
+  `fetch_all_pages` returns a typed pagination envelope. A new `typecheck` CI
+  job runs `mypy src/` and gates publishing.
+- **CI:** added a `windows-latest` test leg (Python 3.12), a coverage floor
+  (`--cov-fail-under=91` on the Ubuntu leg), a publish-time check that the top
+  CHANGELOG version matches `pyproject.toml`, a weekly Dependabot config, and a
+  `.pre-commit-config.yaml` (ruff, mypy, skill-ref drift).
+- **Refactor:** `cli/_util.py` was split into `_client`, `_format`, `_resolve`,
+  and `_factory` modules (with `_util` kept as a re-export shim). The `notes`,
+  `projects`, `tasks`, `events`, `opportunities`, and `workflows` command
+  groups now generate their commands from a shared resource-command factory;
+  `contacts` remains hand-written. No change to the CLI surface.
+- **Tests:** added coverage for delete commands, project/workflow updates,
+  contacts list filters, HTTP base-client edge cases (missing/malformed
+  `Retry-After`, `5xx`, missing collection key), exit codes, and an
+  update-model contract meta-test (every `*UpdateInput` rejects an empty
+  payload).
+
+## [2.3.1] - 2026-06-01
+
+Patch release fixing a startup crash introduced in 2.3.0. `wbox` crashed on
+launch in clean environments because `skill_ref_gen.py` imported `click` at
+module level — and `typer` 0.26+ dropped `click` as a dependency, so it was
+no longer guaranteed to be present. The fix defers the import inside the
+hidden `regen-skill-refs` dev command so normal CLI invocations never touch
+it. CI also gains `skip_existing` on the PyPI publish step to survive
+re-pushed tags without a spurious 400 error.
+
+### Fixed
+- `wbox` startup crash (`ModuleNotFoundError: click`) in environments where
+  `click` is not installed. The `skill_ref_gen` import is now deferred to
+  the body of the hidden `regen-skill-refs` command, which is only ever
+  invoked during development.
+- PyPI publish job now uses `skip_existing: true` so re-pushing a tag
+  (e.g. to re-run a failed release workflow) does not fail with a 400 from
+  PyPI when the wheel was already uploaded on the first push.
+
+## [2.3.0] - 2026-06-01
+
+Feature release. Adds writable contact-role support (`--advisor-role`),
+fixing a long-standing gap where advisor assignments could not be set through
+the CLI at all — even the `--more-fields` / `--json` escape hatches rejected
+the payload because `ContactRoleAssignment` modeled the wrong write shape.
+Also improves the Windows bootstrap installer (idempotent re-runs,
+`-SkipSkills` opt-out, token re-use) and clarifies install/upgrade
+documentation for `uv tool` and `pipx` users.
+
+### Added
+- `--advisor-role ROLE:USER` flag on `contacts add person|household|org|trust`
+  and `contacts update`. Resolves role names and user substrings against the
+  workspace category list so human-readable values like
+  `"Associate Advisor:Jane Smith"` are accepted (#94).
+- `install.ps1` gains a `-SkipSkills` switch for CI and non-agent installs
+  that don't need the bundled agent skill.
+
+### Fixed
+- `ContactRoleAssignment` now uses `{id, value}` (the Wealthbox write shape)
+  instead of `{id, type}`, unblocking all contact-role write paths including
+  `--more-fields` (#94).
+- `install.ps1` re-runs are now idempotent: if the skill directory already
+  exists the installer runs `wbox skills upgrade` instead of erroring.
+- `install.ps1` no longer prompts for a token when one is already stored in
+  `%APPDATA%\wbox\config.json` or `WEALTHBOX_TOKEN`.
+
+### Changed
+- README and `docs/getting-started.md` now include a per-install-method
+  upgrading table and clarify that `wbox self upgrade` is for bundle installs
+  only; `uv tool upgrade` / `pipx upgrade` are the correct paths for
+  managed installs.
+
 ## [2.2.1] - 2026-05-13
 
 Bug-fix release. `wbox self upgrade` was silently no-op'ing for users who

{wealthbox_cli-2.3.1 → wealthbox_cli-2.4.1}/CONTRIBUTING.md

@@ -42,6 +42,30 @@ uv run wbox config set-token
 
 ---
 
+## Pre-commit hooks
+
+The repo ships a `.pre-commit-config.yaml` with three hooks: ruff lint, mypy strict, and a skill-ref drift check. Install them once after cloning:
+
+```bash
+# uv
+uv tool install pre-commit
+pre-commit install
+
+# or pip
+pip install pre-commit
+pre-commit install
+```
+
+Run all hooks manually at any time:
+
+```bash
+pre-commit run --all-files
+# or without a local install:
+uv tool run pre-commit run --all-files
+```
+
+---
+
 ## Running Tests
 
 ```bash
@@ -50,6 +74,14 @@ uv run pytest
 
 Tests use [respx](https://lundberg.github.io/respx/) to mock HTTP at the transport layer — no real API calls are made.
 
+### Coverage gate
+
+CI enforces `--cov-fail-under=91` on the ubuntu test leg. Run locally with:
+
+```bash
+uv run pytest --cov=src/wealthbox_tools --cov-report=term
+```
+
 ## Code Style
 
 ```bash
@@ -57,7 +89,7 @@ uv run ruff check src/ tests/
 ```
 
 - **ruff** for linting (E, F, I rules; 120-char line length)
-- **mypy** in strict mode
+- **mypy** in strict mode (`uv run mypy src/` must exit 0)
 
 ---
 
@@ -87,14 +119,58 @@ Three layers under `src/wealthbox_tools/`:
 
 ---
 
+## Skill reference files
+
+Any change to CLI command signatures or help text **must** regenerate the skill reference files before committing:
+
+```bash
+uv run wbox internals regen-skill-refs
+git add src/wealthbox_tools/skills/wealthbox-crm/references/
+```
+
+The generated files live under `src/wealthbox_tools/skills/wealthbox-crm/references/` and are checked in. The `skill-ref-drift` CI job and the pre-commit hook both fail on stale refs.
+
+---
+
+## Standing verification
+
+Run all of these before opening a PR (CI enforces each):
+
+```bash
+uv run ruff check src/ tests/
+uv run pytest
+uv run mypy src/
+uv run wbox internals regen-skill-refs && git diff --exit-code -- src/wealthbox_tools/skills/wealthbox-crm/references/
+```
+
+---
+
+## Releasing
+
+Releases follow semantic versioning. Bump patch for fixes, minor for features, major for breaking changes.
+
+1. Bump `version` in `pyproject.toml`.
+2. Add a `## [X.Y.Z]` entry at the top of `CHANGELOG.md` (CI enforces that the changelog version matches `pyproject.toml` before publishing to PyPI).
+3. Verify locally: `uv run ruff check src/ tests/ && uv run pytest && uv run mypy src/`
+4. Commit: `vX.Y.Z: <description>`
+5. Tag: `git tag vX.Y.Z`
+6. Push: `git push origin main --tags`
+
+CI builds and publishes to PyPI automatically on `v*` tags once lint, tests, typecheck, and skill-ref-drift all pass.
+
+---
+
 ## CI
 
 Pull requests and pushes to `main` run GitHub Actions CI:
 
 - **Lint:** `ruff check src/ tests/`
-- **Test:** `pytest` across Python 3.11, 3.12, 3.13
+- **Test:** `pytest` across Python 3.11, 3.12, 3.13 (ubuntu) + 3.12 (windows); coverage gate `--cov-fail-under=91` on ubuntu
+- **Typecheck:** `mypy src/` (strict)
+- **Smoke:** installs the built wheel in isolation (no dev deps) and runs `wbox --version` / `wbox notes --help`, catching missing-runtime-dependency startup crashes
+- **Skill-ref drift:** regenerates refs and asserts no git diff
 
-Both must pass before merging.
+All jobs must pass before merging; `publish` (on `v*` tags) additionally gates on lint, test, typecheck, and smoke.
 
 ---
 

{wealthbox_cli-2.3.1 → wealthbox_cli-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wealthbox-cli
-Version: 2.3.1
+Version: 2.4.1
 Summary: CLI and client library for the Wealthbox CRM API
 Project-URL: Homepage, https://github.com/massive-value/wealthbox-cli
 Project-URL: Documentation, https://massive-value.github.io/wealthbox-cli/
@@ -33,9 +33,11 @@ Requires-Dist: typer<1.0,>=0.12
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-tabulate>=0.9; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Wealthbox CLI
@@ -152,6 +154,29 @@ wbox notes add "Discussed retirement plan" --contact 12345
 ```
 
 Full command reference: [CLI Reference](https://massive-value.github.io/wealthbox-cli/cli-reference/). Output formats: `json` (default), `table`, `csv`, `tsv`. Date format: ISO 8601 (`2026-05-01T10:00:00-07:00`). See [Getting Started](https://massive-value.github.io/wealthbox-cli/getting-started/) for pipx, env-var auth, and project-scoped installs.
+
+**Exit codes** — `wbox` returns differentiated exit codes so scripts can branch on the failure class:
+
+| Code | Meaning |
+| ---- | ------- |
+| `0`  | Success |
+| `1`  | Validation / user error (bad input, a non-auth `4xx` from the API such as `404`/`422`) |
+| `2`  | Authentication error (API `401`/`403`) |
+| `3`  | Server error (API `5xx`) |
+
+Note: Click also exits `2` for usage errors (an unknown flag or a missing required argument); that overlap with the auth code is pre-existing and acceptable, since usage errors are caught by the parser before the command runs. Set `WBOX_DEBUG=1` to print the full Python traceback to stderr alongside the friendly message (the exit code is unchanged) — handy when reporting bugs.
+
+**Brief mode** — Wealthbox duplicates every text field as HTML markup (`content_html`, `description_html`, `body_html`, etc.), making responses 3–5x larger. Pass `--brief` or set `WBOX_BRIEF=1` to recursively strip all `*_html` keys from the JSON output before it is printed. Plain-text counterparts are kept; all other fields are unaffected. Any non-empty value is truthy (same convention as `WBOX_DEBUG`).
+
+```bash
+# One-off: flag form
+wbox --brief notes list
+
+# Persistent in a script or agent session
+export WBOX_BRIEF=1
+wbox notes list
+wbox tasks list
+```
 </details>
 
 <details>

{wealthbox_cli-2.3.1 → wealthbox_cli-2.4.1}/README.md

@@ -112,6 +112,29 @@ wbox notes add "Discussed retirement plan" --contact 12345
 ```
 
 Full command reference: [CLI Reference](https://massive-value.github.io/wealthbox-cli/cli-reference/). Output formats: `json` (default), `table`, `csv`, `tsv`. Date format: ISO 8601 (`2026-05-01T10:00:00-07:00`). See [Getting Started](https://massive-value.github.io/wealthbox-cli/getting-started/) for pipx, env-var auth, and project-scoped installs.
+
+**Exit codes** — `wbox` returns differentiated exit codes so scripts can branch on the failure class:
+
+| Code | Meaning |
+| ---- | ------- |
+| `0`  | Success |
+| `1`  | Validation / user error (bad input, a non-auth `4xx` from the API such as `404`/`422`) |
+| `2`  | Authentication error (API `401`/`403`) |
+| `3`  | Server error (API `5xx`) |
+
+Note: Click also exits `2` for usage errors (an unknown flag or a missing required argument); that overlap with the auth code is pre-existing and acceptable, since usage errors are caught by the parser before the command runs. Set `WBOX_DEBUG=1` to print the full Python traceback to stderr alongside the friendly message (the exit code is unchanged) — handy when reporting bugs.
+
+**Brief mode** — Wealthbox duplicates every text field as HTML markup (`content_html`, `description_html`, `body_html`, etc.), making responses 3–5x larger. Pass `--brief` or set `WBOX_BRIEF=1` to recursively strip all `*_html` keys from the JSON output before it is printed. Plain-text counterparts are kept; all other fields are unaffected. Any non-empty value is truthy (same convention as `WBOX_DEBUG`).
+
+```bash
+# One-off: flag form
+wbox --brief notes list
+
+# Persistent in a script or agent session
+export WBOX_BRIEF=1
+wbox notes list
+wbox tasks list
+```
 </details>
 
 <details>