code-aide 1.15.0__tar.gz → 1.15.2__tar.gz

{code_aide-1.15.0 → code_aide-1.15.2}/AGENTS.md

@@ -5,28 +5,34 @@
 
 ## Key Design Decisions
 
-- Runtime dependencies are stdlib only (`dependencies` in pyproject.toml).
-  Dev tooling (pytest, black, ruff) lives in `dependency-groups` for tests
-  and linting.
+- Runtime dependencies are stdlib only (`dependencies` in pyproject.toml). Dev
+  tooling (pytest, black, ruff) lives in `dependency-groups` for tests and
+  linting.
 - Primary supported environments are macOS and Linux (see pyproject
-  classifiers); avoid assuming Windows-specific behavior unless explicitly
-  in scope.
-- For planned behavior or refactors, read matching notes under `specs/`
-  before inventing design.
-- Two-layer version data: bundled definitions (with SHA256 checksums),
-  user's local cache (~/.config/code-aide/versions.json)
+  classifiers); avoid assuming Windows-specific behavior unless explicitly in
+  scope.
+- For planned behavior or refactors, read matching notes under `specs/` before
+  inventing design.
+- Two-layer version data: bundled definitions (with SHA256 checksums), user's
+  local cache (~/.config/code-aide/versions.json)
+- Third-party install scripts are archived under `script-archive/` and their
+  SHA256 hashes are stored in `src/code_aide/data/tools.json`
+  (`install_sha256`). When an upgrade reports a SHA256 mismatch: (1) download
+  the new script to a temp file, (2) `diff script-archive/<tool>-install.sh
+  /tmp/new-script.sh` and review every change for anything suspicious, (3) if
+  safe, copy the new script over the archive copy and update `install_sha256` in
+  `tools.json`, (4) commit both files together. See `script-archive/README.md`
+  for the full procedure.
 - All tests should pass before committing
 - pre-commit runs black and ruff on commit; run `black` to format and then
   `pre-commit run --all-files` to check before committing
-- When changing pyproject.toml dependencies, run `uv lock` and commit
-  uv.lock
+- When changing pyproject.toml dependencies, run `uv lock` and commit uv.lock
 - Write useful commit messages: start subjects with past-tense action verbs
   (`Added`, `Changed`, `Fixed`, `Removed`), keep them user-facing, and keep
   commits focused.
 - Python 3.11+ compatible
 - Keep files under 300 lines where practical
-- Run `format-markdown` on markdown files before commits (if it is
-  available)
-- When pushing tags, always push them explicitly with `git push <remote>
-  <tag>` rather than relying on `--follow-tags`, which silently skips tags
-  when the branch commits are already on the remote
+- Run `format-markdown` on markdown files before commits (if it is available)
+- When pushing tags, always push them explicitly with `git push <remote> <tag>`
+  rather than relying on `--follow-tags`, which silently skips tags when the
+  branch commits are already on the remote

code_aide-1.15.2/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: code-aide
+Version: 1.15.2
+Summary: Manage AI coding CLI tools (Claude, Copilot, Cursor, Gemini, Amp, Codex)
+Project-URL: Homepage, https://github.com/dajobe/code-aide
+Project-URL: Repository, https://github.com/dajobe/code-aide
+Project-URL: Issues, https://github.com/dajobe/code-aide/issues
+Project-URL: Changelog, https://github.com/dajobe/code-aide/releases
+Author: Dave Beckett
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: BSD :: FreeBSD
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Installation/Setup
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# code-aide
+
+An aide for your AI coding tools.
+
+Manages installation, upgrade, removal, and version tracking of AI coding CLI
+tools: Claude Code, Copilot, Cursor, Gemini, Amp, Codex, OpenCode, and Kilo.
+
+## Installation
+
+```bash
+# Run without installing (requires uv)
+uvx code-aide status
+
+# Install persistently
+uv tool install code-aide
+
+# Or use pipx
+pipx install code-aide
+```
+
+## Usage
+
+```bash
+# List available tools and their status
+code-aide list
+
+# Show compact one-line-per-tool status
+code-aide status
+
+# Show detailed status for installed tools
+code-aide status -l
+
+# Install specific tools
+code-aide install claude gemini
+
+# Install all default tools
+code-aide install
+
+# Install with automatic prerequisite installation (Node.js, npm)
+code-aide install -p
+
+# Upgrade installed tools (no args = only out-of-date tools)
+code-aide upgrade [NAMES]
+
+# Remove tools
+code-aide remove [NAMES]
+
+# Check upstream for latest versions (dry-run)
+code-aide update-versions -n
+
+# Update version cache
+code-aide update-versions -y
+```
+
+## Supported Tools
+
+| Tool                     | Command    | Install Type    | Default |
+|:-------------------------|:-----------|:----------------|:--------|
+| Cursor CLI               | `agent`    | Direct download | Yes     |
+| Claude CLI (Claude Code) | `claude`   | Script          | Yes     |
+| Gemini CLI               | `gemini`   | npm             | Yes     |
+| OpenCode                 | `opencode` | npm             | No      |
+| Kilo CLI                 | `kilo`     | npm             | No      |
+| Amp (Sourcegraph)        | `amp`      | Script          | No      |
+| Codex CLI                | `codex`    | npm             | No      |
+| Copilot CLI              | `copilot`  | npm             | No      |
+
+## How Version Data Works
+
+code-aide uses a two-layer version data model:
+
+1. **Bundled tool definitions** (in `data/tools.json`): Install methods, URLs,
+   npm packages, version args, and SHA256 checksums. Updated by releasing new
+   versions of code-aide.
+
+2. **User's local version cache** (`~/.config/code-aide/versions.json`): Written
+   by `code-aide update-versions`. Provides latest versions, dates, and updated
+   SHA256 checksums.
+
+Run `code-aide update-versions` to get the latest version data without waiting
+for a new code-aide release.
+
+## Tool definition schema (`data/tools.json`)
+
+Each entry in `tools.json` describes one managed tool. Required fields are
+`name`, `command`, and `install_type`; the others are optional and only
+consulted when the relevant install method or platform applies.
+
+| Field                         | Required | Notes                                                                                        |
+|:------------------------------|:---------|:---------------------------------------------------------------------------------------------|
+| `name`                        | Yes      | Display name for status output                                                               |
+| `command`                     | Yes      | Binary name (looked up in `PATH`)                                                            |
+| `install_type`                | Yes      | One of `npm`, `script`, `direct_download`, `pkg`                                             |
+| `version_args`                | No       | List of arguments passed to the binary to print its version (default: `["--version"]`)       |
+| `version_url`                 | No       | URL queried by `update-versions` to discover the latest upstream version                     |
+| `latest_version`              | Cache    | Last known upstream version (filled by `update-versions`)                                    |
+| `latest_date`                 | Cache    | Release date for `latest_version`                                                            |
+| `prerequisites`               | No       | List of required external commands (e.g. `["npm"]`)                                          |
+| `min_node_version`            | No       | Minimum major Node.js version required                                                       |
+| `npm_package`                 | npm      | npm package name (e.g. `@anthropic-ai/claude-code`)                                          |
+| `install_url`                 | script   | URL of the install script that will be downloaded and piped to `bash`                        |
+| `install_sha256`              | script   | SHA-256 of the install script body — required for verified installs                          |
+| `install_script_path_prepend` | script   | Extra directories prepended to `PATH` when the install script runs (e.g. `["~/.local/bin"]`) |
+| `download_url_template`       | direct   | URL template with `{version}`, `{os}`, `{arch}` placeholders                                 |
+| `install_dir`                 | direct   | Directory to extract into; supports `{version}`                                              |
+| `bin_dir`                     | direct   | Directory where symlinks for `command` are created (e.g. `~/.local/bin`)                     |
+| `symlinks`                    | direct   | Map of `link_name` → relative path inside `install_dir` to symlink into `bin_dir`            |
+| `freebsd_port`                | FreeBSD  | FreeBSD ports/pkg name (used when running on FreeBSD)                                        |
+| `freebsd_pkg_repo`            | FreeBSD  | Optional non-default pkg repository name (passed via `pkg install -r <repo>`)                |
+| `next_steps`                  | No       | Free-form text printed after a successful install                                            |
+| `docs_url`                    | No       | Documentation URL printed after install                                                      |
+
+## Features
+
+- Zero external dependencies (Python stdlib only)
+- SHA256 verification for script-based installations
+- Automatic prerequisite detection and installation (Node.js, npm)
+- Detects install method (Homebrew, npm, system package, script, direct
+  download)
+- PATH configuration validation and warnings
+- Supports Linux and macOS
+
+## Requirements
+
+- Python 3.11+
+- No external Python dependencies
+
+## Development
+
+1. Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+2. Install dependencies: `uv sync`
+3. Install pre-commit hooks: `uv tool install pre-commit && pre-commit install`
+4. Run tests: `uv run pytest tests/ -v`
+
+```bash
+# Run from development checkout
+uv run python -m code_aide status
+uv run python -m code_aide install copilot
+
+# Run a specific test
+uv run pytest tests/test_install.py::TestDetectOsArch -v
+```
+
+## Release
+
+`publish.yml` publishes to PyPI when a Git tag matching `v*` is pushed.
+
+1. Update the version string in `src/code_aide/__init__.py` (`__version__`).
+   `pyproject.toml` reads it automatically via Hatchling.
+2. Run checks:
+   - `uv run pytest tests/ -v`
+   - `uv build`
+3. Commit the release version bump:
+   - `git add src/code_aide/__init__.py`
+   - `git commit -m "Bumped version to X.Y.Z"`
+4. Write useful commit messages before tagging:
+   - Start subject lines with an action verb in past tense (`Added`, `Changed`,
+     `Fixed`, `Removed`).
+   - Keep subjects user-facing so auto-generated release notes are meaningful.
+   - Group related changes into focused commits instead of one broad commit.
+   - Example: `Fixed timeout handling in status command`
+5. Tag and push:
+   - `git tag vX.Y.Z`
+   - `git push origin main`
+   - `git push origin vX.Y.Z`
+6. Confirm GitHub Actions:
+   - CI should pass.
+   - Publish workflow should upload to PyPI and create GitHub Release notes.
+   - Release notes should include generated notes plus a commit summary from the
+     previous tag to the current tag.
+
+## License
+
+Apache-2.0

code_aide-1.15.2/README.md

@@ -0,0 +1,174 @@
+# code-aide
+
+An aide for your AI coding tools.
+
+Manages installation, upgrade, removal, and version tracking of AI coding CLI
+tools: Claude Code, Copilot, Cursor, Gemini, Amp, Codex, OpenCode, and Kilo.
+
+## Installation
+
+```bash
+# Run without installing (requires uv)
+uvx code-aide status
+
+# Install persistently
+uv tool install code-aide
+
+# Or use pipx
+pipx install code-aide
+```
+
+## Usage
+
+```bash
+# List available tools and their status
+code-aide list
+
+# Show compact one-line-per-tool status
+code-aide status
+
+# Show detailed status for installed tools
+code-aide status -l
+
+# Install specific tools
+code-aide install claude gemini
+
+# Install all default tools
+code-aide install
+
+# Install with automatic prerequisite installation (Node.js, npm)
+code-aide install -p
+
+# Upgrade installed tools (no args = only out-of-date tools)
+code-aide upgrade [NAMES]
+
+# Remove tools
+code-aide remove [NAMES]
+
+# Check upstream for latest versions (dry-run)
+code-aide update-versions -n
+
+# Update version cache
+code-aide update-versions -y
+```
+
+## Supported Tools
+
+| Tool                     | Command    | Install Type    | Default |
+|:-------------------------|:-----------|:----------------|:--------|
+| Cursor CLI               | `agent`    | Direct download | Yes     |
+| Claude CLI (Claude Code) | `claude`   | Script          | Yes     |
+| Gemini CLI               | `gemini`   | npm             | Yes     |
+| OpenCode                 | `opencode` | npm             | No      |
+| Kilo CLI                 | `kilo`     | npm             | No      |
+| Amp (Sourcegraph)        | `amp`      | Script          | No      |
+| Codex CLI                | `codex`    | npm             | No      |
+| Copilot CLI              | `copilot`  | npm             | No      |
+
+## How Version Data Works
+
+code-aide uses a two-layer version data model:
+
+1. **Bundled tool definitions** (in `data/tools.json`): Install methods, URLs,
+   npm packages, version args, and SHA256 checksums. Updated by releasing new
+   versions of code-aide.
+
+2. **User's local version cache** (`~/.config/code-aide/versions.json`): Written
+   by `code-aide update-versions`. Provides latest versions, dates, and updated
+   SHA256 checksums.
+
+Run `code-aide update-versions` to get the latest version data without waiting
+for a new code-aide release.
+
+## Tool definition schema (`data/tools.json`)
+
+Each entry in `tools.json` describes one managed tool. Required fields are
+`name`, `command`, and `install_type`; the others are optional and only
+consulted when the relevant install method or platform applies.
+
+| Field                         | Required | Notes                                                                                        |
+|:------------------------------|:---------|:---------------------------------------------------------------------------------------------|
+| `name`                        | Yes      | Display name for status output                                                               |
+| `command`                     | Yes      | Binary name (looked up in `PATH`)                                                            |
+| `install_type`                | Yes      | One of `npm`, `script`, `direct_download`, `pkg`                                             |
+| `version_args`                | No       | List of arguments passed to the binary to print its version (default: `["--version"]`)       |
+| `version_url`                 | No       | URL queried by `update-versions` to discover the latest upstream version                     |
+| `latest_version`              | Cache    | Last known upstream version (filled by `update-versions`)                                    |
+| `latest_date`                 | Cache    | Release date for `latest_version`                                                            |
+| `prerequisites`               | No       | List of required external commands (e.g. `["npm"]`)                                          |
+| `min_node_version`            | No       | Minimum major Node.js version required                                                       |
+| `npm_package`                 | npm      | npm package name (e.g. `@anthropic-ai/claude-code`)                                          |
+| `install_url`                 | script   | URL of the install script that will be downloaded and piped to `bash`                        |
+| `install_sha256`              | script   | SHA-256 of the install script body — required for verified installs                          |
+| `install_script_path_prepend` | script   | Extra directories prepended to `PATH` when the install script runs (e.g. `["~/.local/bin"]`) |
+| `download_url_template`       | direct   | URL template with `{version}`, `{os}`, `{arch}` placeholders                                 |
+| `install_dir`                 | direct   | Directory to extract into; supports `{version}`                                              |
+| `bin_dir`                     | direct   | Directory where symlinks for `command` are created (e.g. `~/.local/bin`)                     |
+| `symlinks`                    | direct   | Map of `link_name` → relative path inside `install_dir` to symlink into `bin_dir`            |
+| `freebsd_port`                | FreeBSD  | FreeBSD ports/pkg name (used when running on FreeBSD)                                        |
+| `freebsd_pkg_repo`            | FreeBSD  | Optional non-default pkg repository name (passed via `pkg install -r <repo>`)                |
+| `next_steps`                  | No       | Free-form text printed after a successful install                                            |
+| `docs_url`                    | No       | Documentation URL printed after install                                                      |
+
+## Features
+
+- Zero external dependencies (Python stdlib only)
+- SHA256 verification for script-based installations
+- Automatic prerequisite detection and installation (Node.js, npm)
+- Detects install method (Homebrew, npm, system package, script, direct
+  download)
+- PATH configuration validation and warnings
+- Supports Linux and macOS
+
+## Requirements
+
+- Python 3.11+
+- No external Python dependencies
+
+## Development
+
+1. Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+2. Install dependencies: `uv sync`
+3. Install pre-commit hooks: `uv tool install pre-commit && pre-commit install`
+4. Run tests: `uv run pytest tests/ -v`
+
+```bash
+# Run from development checkout
+uv run python -m code_aide status
+uv run python -m code_aide install copilot
+
+# Run a specific test
+uv run pytest tests/test_install.py::TestDetectOsArch -v
+```
+
+## Release
+
+`publish.yml` publishes to PyPI when a Git tag matching `v*` is pushed.
+
+1. Update the version string in `src/code_aide/__init__.py` (`__version__`).
+   `pyproject.toml` reads it automatically via Hatchling.
+2. Run checks:
+   - `uv run pytest tests/ -v`
+   - `uv build`
+3. Commit the release version bump:
+   - `git add src/code_aide/__init__.py`
+   - `git commit -m "Bumped version to X.Y.Z"`
+4. Write useful commit messages before tagging:
+   - Start subject lines with an action verb in past tense (`Added`, `Changed`,
+     `Fixed`, `Removed`).
+   - Keep subjects user-facing so auto-generated release notes are meaningful.
+   - Group related changes into focused commits instead of one broad commit.
+   - Example: `Fixed timeout handling in status command`
+5. Tag and push:
+   - `git tag vX.Y.Z`
+   - `git push origin main`
+   - `git push origin vX.Y.Z`
+6. Confirm GitHub Actions:
+   - CI should pass.
+   - Publish workflow should upload to PyPI and create GitHub Release notes.
+   - Release notes should include generated notes plus a commit summary from the
+     previous tag to the current tag.
+
+## License
+
+Apache-2.0

{code_aide-1.15.0 → code_aide-1.15.2}/TODO.md

@@ -11,7 +11,7 @@ remove, status, and version metadata).
 | 2  | Read version from stdout+stderr        | Med      | Low     | Some tools write version to stderr; shown as not installed |
 | 3  | Atomic version cache writes            | Med-High | Low     | Process crash can corrupt `versions.json`                  |
 | 4  | Warn on invalid cache JSON             | Low      | Low     | Silent data loss; user sees empty versions                 |
-| 5  | Use `os.pathsep` not `":"`             | High     | Trivial | Breaks PATH checks on Windows entirely                     |
+| 5  | ~~Use `os.pathsep` not `":"`~~ (done)  | -        | -       | Fixed in `prereqs.py` `check_path_directories()`           |
 | 6  | Verify direct-download tarballs        | High     | Med     | No integrity check before extracting; MITM risk            |
 | 7  | Tarball checksum metadata fields       | High     | Low     | Prerequisite for item 6                                    |
 | 8  | `--json` output mode                   | Low      | Med     | Needed for CI/automation consumers                         |
@@ -30,21 +30,21 @@ remove, status, and version metadata).
 
 - [ ] Handle missing `node` cleanly during prerequisite checks
   (`FileNotFoundError` path in Node version probing).
-- [ ] Read tool version output from both stdout and stderr so status does
-  not miss installed versions.
+- [ ] Read tool version output from both stdout and stderr so status does not
+  miss installed versions.
 - [ ] Make version cache writes atomic (write temp file + rename) to avoid
   partial/corrupted `versions.json`.
-- [ ] Warn when `versions.json` cache contains invalid JSON instead of
-  silently returning empty data.
-- [ ] Use `os.pathsep` instead of hardcoded `":"` in `prereqs.py`
+- [ ] Warn when `versions.json` cache contains invalid JSON instead of silently
+  returning empty data.
+- [x] Use `os.pathsep` instead of hardcoded `":"` in `prereqs.py`
   `check_path_directories()`.
 
 ## Security and Integrity
 
-- [ ] Add integrity verification for direct-download tarballs (not only
-  install script SHA256).
-- [ ] Extend tool metadata to support tarball checksum/signature fields
-  where applicable.
+- [ ] Add integrity verification for direct-download tarballs (not only install
+  script SHA256).
+- [ ] Extend tool metadata to support tarball checksum/signature fields where
+  applicable.
 
 ## CLI and Automation UX
 
@@ -52,21 +52,19 @@ remove, status, and version metadata).
 - [ ] Add a focused `doctor` command for environment checks (PATH,
   prerequisites, command health).
 - [ ] Consider `install --force` for reinstall/repair flows.
-- [ ] Add cleanup support for stale direct-download versions no longer in
-  use.
+- [ ] Add cleanup support for stale direct-download versions no longer in use.
 
 ## Documentation
 
-- [ ] Document that running `code-aide` with no subcommand defaults to
-  `status`.
+- [ ] Document that running `code-aide` with no subcommand defaults to `status`.
 - [ ] Add `install --dryrun` to the README usage examples.
 - [ ] Document environment variables and config file paths
   (`~/.config/code-aide/versions.json`).
 
 ## Platform and Package Detection
 
-- [ ] Broaden system package metadata detection beyond Gentoo-specific
-  tooling where practical.
+- [ ] Broaden system package metadata detection beyond Gentoo-specific tooling
+  where practical.
 
 ## Maintainability and Tests
 

{code_aide-1.15.0 → code_aide-1.15.2}/pyproject.toml

@@ -43,6 +43,21 @@ path = "src/code_aide/__init__.py"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+filterwarnings = [
+    "error",
+    "ignore::DeprecationWarning:_pytest.*",
+]
+markers = [
+    "network: tests that make real network calls (deselect with '-m \"not network\"')",
+]
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src/code_aide"]
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unused_configs = true
+no_implicit_optional = true
 
 [dependency-groups]
 dev = [
@@ -50,4 +65,5 @@ dev = [
     "pytest-xdist>=3.0",
     "black>=25.1.0",
     "ruff>=0.9.0",
+    "mypy>=1.10",
 ]

{code_aide-1.15.0 → code_aide-1.15.2}/script-archive/amp-install.sh

@@ -240,18 +240,10 @@ install_amp_binary() {
 		log "Installing version: $version"
 	fi
 
-	# Use versioned URLs if available, fall back to root for backwards compatibility
 	local binary_url="$STORAGE_BASE/cli/${version}/amp-${platform}"
 	local checksum_url="$STORAGE_BASE/cli/${version}/${platform}-amp.sha256"
 	local minisign_signature_url="$binary_url.minisig"
 
-	# Check if versioned path exists, fall back to root path
-	if ! curl -fsSL --head "$checksum_url" >/dev/null 2>&1; then
-		binary_url="$STORAGE_BASE/cli/amp-${platform}"
-		checksum_url="$STORAGE_BASE/cli/${platform}-amp.sha256"
-		minisign_signature_url="$binary_url.minisig"
-	fi
-
 	# Add .exe for Windows downloads
 	if [[ "$platform" == *"windows"* ]]; then
 		binary_url="${binary_url}.exe"

{code_aide-1.15.0 → code_aide-1.15.2}/script-archive/claude-install.sh

@@ -107,6 +107,13 @@ mkdir -p "$DOWNLOAD_DIR"
 # Always download latest version (which has the most up-to-date installer)
 version=$(download_file "$DOWNLOAD_BASE_URL/latest")
 
+# Reject non-version content (e.g. an HTML error page) before it reaches the manifest URL
+if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+    echo "Failed to get a valid version from downloads.claude.ai (got unexpected content)." >&2
+    echo "This can happen if the download service is unreachable or not available in your region - see https://www.anthropic.com/supported-countries" >&2
+    exit 1
+fi
+
 # Download manifest and extract checksum
 manifest_json=$(download_file "$DOWNLOAD_BASE_URL/$version/manifest.json")