portolan-cli 0.1.1__tar.gz

portolan_cli-0.1.1/.claude/hooks/post-bash-remind.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Distill - PostToolUse Hook for Bash
+# Reminds to use MCP tools for large outputs
+
+INPUT=$(cat)
+TOOL_RESPONSE=$(echo "$INPUT" | jq -r '.tool_response // empty')
+RESPONSE_SIZE=${#TOOL_RESPONSE}
+
+# Threshold: 5000 chars ~ 1250 tokens
+THRESHOLD=5000
+
+# Skip if output is small
+if [ "$RESPONSE_SIZE" -lt "$THRESHOLD" ]; then
+  exit 0
+fi
+
+# Detect content type and suggest appropriate tool
+if echo "$TOOL_RESPONSE" | grep -qiE "(error TS|warning TS|error\[E|npm ERR|ERROR in|failed|FAILED)"; then
+  echo '{"systemMessage": "TIP: Large build output detected. Use mcp__distill__auto_optimize to compress errors (95%+ reduction)."}'
+  exit 0
+fi
+
+if echo "$TOOL_RESPONSE" | grep -qiE "(\[INFO\]|\[ERROR\]|\[WARN\]|\[DEBUG\]|[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2})"; then
+  echo '{"systemMessage": "TIP: Large log output detected. Use mcp__distill__summarize_logs to compress (80-90% reduction)."}'
+  exit 0
+fi
+
+# Generic large output
+echo '{"systemMessage": "TIP: Large output ('$RESPONSE_SIZE' chars). Consider using mcp__distill__auto_optimize for compression (40-60% reduction)."}'
+exit 0

portolan_cli-0.1.1/.claude/hooks/pre-read-check.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Distill - PreToolUse Hook for Read
+# Suggests smart_file_read for code files (non-blocking to allow Edit to work)
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+BASENAME=$(basename "$FILE_PATH")
+
+# Skip suggestion for configuration files
+if echo "$BASENAME" | grep -qiE "^(CLAUDE|README|CHANGELOG|LICENSE)"; then
+  exit 0
+fi
+if echo "$BASENAME" | grep -qiE "\.(md|json|yaml|yml|toml|ini|config)$"; then
+  exit 0
+fi
+if echo "$BASENAME" | grep -qiE "^(Dockerfile|Makefile|\.gitignore|\.env|\.prettierrc|\.eslintrc)"; then
+  exit 0
+fi
+
+# Suggest smart_file_read for source code files (non-blocking)
+if echo "$FILE_PATH" | grep -qE "\.(ts|tsx|js|jsx|py|go|rs|java|cpp|c|h|hpp)$"; then
+  # Use systemMessage to suggest without blocking (allows Edit to work)
+  cat << EOF
+{"systemMessage": "TIP: Consider using mcp__distill__smart_file_read for '$BASENAME' to save 50-70% tokens. Example: mcp__distill__smart_file_read filePath=\"$FILE_PATH\" target={\"type\":\"function\",\"name\":\"myFunc\"}"}
+EOF
+  exit 0
+fi
+
+# Allow everything else
+exit 0

portolan_cli-0.1.1/.claude/hooks/prompt-inject.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# Distill - UserPromptSubmit Hook
+# Injects MCP tool reminders at the start of each prompt
+
+cat << 'EOF'
+<user-prompt-submit-hook>
+DISTILL REMINDER: Use MCP tools for token optimization:
+- Code files: mcp__distill__smart_file_read (50-70% savings vs Read)
+- Build/test output: mcp__distill__auto_optimize
+- Session stats: mcp__distill__session_stats
+</user-prompt-submit-hook>
+EOF
+exit 0

portolan_cli-0.1.1/.coderabbit.yaml

@@ -0,0 +1,38 @@
+language: en-US
+
+tone_instructions: |
+  Be extremely concise. Only flag major bugs, security issues, or critical
+  performance problems. Skip style nits, minor suggestions, and anything
+  that doesn't meaningfully impact correctness or maintainability.
+
+reviews:
+  profile: chill
+  high_level_summary: true
+  high_level_summary_in_walkthrough: false
+  poem: false
+  sequence_diagrams: false
+  collapse_walkthrough: true
+  changed_files_summary: false
+  estimate_code_review_effort: false
+  related_issues: false
+  related_prs: false
+  suggested_labels: false
+  suggested_reviewers: false
+  in_progress_fortune: false
+  review_details: false
+
+  auto_review:
+    enabled: true
+    drafts: false
+
+  tools:
+    ruff:
+      enabled: false
+    flake8:
+      enabled: false
+    pylint:
+      enabled: false
+
+chat:
+  art: false
+  auto_reply: true

portolan_cli-0.1.1/.github/CODEOWNERS

@@ -0,0 +1 @@
+@cholmes @nlebovits

portolan_cli-0.1.1/.github/dependabot.yml

@@ -0,0 +1,33 @@
+version: 2
+updates:
+  # GitHub Actions dependencies
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    open-pull-requests-limit: 5
+
+  # Python dependencies
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "python"
+    open-pull-requests-limit: 10
+    # Group minor and patch updates together
+    groups:
+      development-dependencies:
+        dependency-type: "development"
+        update-types:
+          - "minor"
+          - "patch"
+      production-dependencies:
+        dependency-type: "production"
+        update-types:
+          - "minor"
+          - "patch"

portolan_cli-0.1.1/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## PR Title
+Write a clear, action-oriented title. This will be used for changelog and release notes.
+
+## Description
+<!-- Concise summary of what changed and why. This may be used in release notes. -->
+
+## Technical Details
+<!-- Implementation notes, breaking changes, migration steps. For reviewers. -->
+
+## Related Issue(s)
+- #
+
+## Checklist
+- [ ] Code is formatted
+- [ ] Tests pass

portolan_cli-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,156 @@
+# Tier 2 CI - Runs on every PR and push to main
+# See context/shared/documentation/ci.md for the full CI strategy
+#
+# Philosophy: Starting from zero, all quality gates are STRICT.
+# Nothing passes with warnings - fix issues or they block the PR.
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Check code formatting
+        run: uv run ruff format --check .
+
+      - name: Run linter
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run mypy portolan_cli
+
+      - name: Spell check
+        run: uv run codespell --skip "*.parquet,*.tif,.git,*.lock" portolan_cli tests docs
+
+  security:
+    name: Security Scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run bandit security scan
+        run: uv run bandit -r portolan_cli -c pyproject.toml
+
+      - name: Audit dependencies
+        run: uv run pip-audit
+
+  test:
+    name: Test (Python ${{ matrix.python-version }} / ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+        exclude:
+          # Reduce matrix size - test older Python only on Linux
+          - os: macos-latest
+            python-version: '3.10'
+          - os: windows-latest
+            python-version: '3.10'
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests (unit + integration, no network)
+        run: uv run pytest tests/ -v --tb=short -m "not network and not slow and not benchmark" --cov=portolan_cli --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v5
+        with:
+          file: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+
+  dead-code:
+    name: Dead Code & Complexity
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Check for dead code
+        run: uv run vulture portolan_cli tests --min-confidence 80
+
+      - name: Check code complexity
+        run: uv run xenon --max-absolute=C --max-modules=B --max-average=A portolan_cli tests
+
+  docs:
+    name: Documentation Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Build package
+        run: uv build
+
+      - name: Check package contents
+        run: |
+          uv run python -c "import tarfile; t = tarfile.open(list(__import__('pathlib').Path('dist').glob('*.tar.gz'))[0]); print('\n'.join(t.getnames()))"

portolan_cli-0.1.1/.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv pip install --system mkdocs mkdocs-material mkdocstrings[python]
+
+      - name: Build documentation
+        run: mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: ./site
+
+  deploy:
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

portolan_cli-0.1.1/.github/workflows/nightly.yml

@@ -0,0 +1,169 @@
+# Tier 3 CI - Scheduled nightly checks
+# See context/shared/documentation/ci.md for the full CI strategy
+#
+# Philosophy: These are the "expensive" checks that would slow down PRs.
+# They still fail the build - we track trends but don't accept regressions.
+name: Nightly
+on:
+  schedule:
+    - cron: '0 4 * * *'  # 4 AM UTC daily
+  workflow_dispatch:  # Allow manual triggering
+
+jobs:
+  mutation:
+    name: Mutation Testing
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run mutation testing
+        run: |
+          uv run mutmut run \
+            --paths-to-mutate=portolan_cli/ \
+            --tests-dir=tests/ \
+            --no-progress
+
+      - name: Check mutation score
+        run: |
+          # Get mutation results as JSON and check score
+          uv run mutmut results --json > mutation-results.json
+
+          # Calculate survival rate (lower is better)
+          SURVIVED=$(jq '.survived // 0' mutation-results.json)
+          KILLED=$(jq '.killed // 0' mutation-results.json)
+          TOTAL=$((SURVIVED + KILLED))
+
+          if [ "$TOTAL" -eq 0 ]; then
+            echo "No mutations generated - check if source code is testable"
+            exit 0
+          fi
+
+          # Calculate kill rate (higher is better)
+          KILL_RATE=$(echo "scale=2; $KILLED * 100 / $TOTAL" | bc)
+          echo "Mutation kill rate: $KILL_RATE% ($KILLED killed, $SURVIVED survived)"
+
+          # Fail if kill rate drops below 60%
+          # This threshold should increase as the codebase matures
+          MIN_KILL_RATE=60
+          if [ $(echo "$KILL_RATE < $MIN_KILL_RATE" | bc) -eq 1 ]; then
+            echo "::error::Mutation kill rate ($KILL_RATE%) is below threshold ($MIN_KILL_RATE%)"
+            echo "Tests are not catching enough bugs. Review survived mutants."
+            exit 1
+          fi
+
+      - name: Generate mutation report
+        if: always()
+        run: uv run mutmut html || true
+
+      - name: Upload mutation report
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-report
+          path: html/
+          retention-days: 30
+        if: always()
+
+  benchmark:
+    name: Performance Benchmarks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # Full history to compare with previous runs
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run benchmarks
+        run: |
+          # Run benchmarks and save results
+          uv run pytest tests/ \
+            -m benchmark \
+            --benchmark-json=benchmark-results.json \
+            --benchmark-autosave \
+            -v
+
+      - name: Check for performance regression
+        run: |
+          # If baseline exists, compare and fail on >20% regression
+          if [ -f .benchmarks/baseline.json ]; then
+            uv run pytest-benchmark compare \
+              benchmark-results.json \
+              .benchmarks/baseline.json \
+              --fail-on=20
+          else
+            echo "No baseline found. This run will establish the baseline."
+            mkdir -p .benchmarks
+            cp benchmark-results.json .benchmarks/baseline.json
+          fi
+
+      - name: Upload benchmark results
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: benchmark-results.json
+          retention-days: 90
+        if: always()
+
+  network-live:
+    name: Live Network Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run network tests against live services
+        run: |
+          uv run pytest tests/ \
+            -m network \
+            --timeout=120 \
+            -v
+
+  dependency-check:
+    name: Dependency Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Full security audit
+        run: |
+          echo "=== Dependency security audit ==="
+          uv run pip-audit --strict
+
+      - name: Check for outdated dependencies
+        run: |
+          echo "=== Outdated dependencies ==="
+          uv pip list --outdated
+          # Note: This is informational, not a failure condition

portolan_cli-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,102 @@
+# Automated release workflow using commitizen
+# See context/shared/documentation/ci.md for the full CI strategy
+#
+# This workflow:
+# 1. Analyzes commits since last release
+# 2. Bumps version based on conventional commits
+# 3. Generates changelog entry
+# 4. Creates git tag
+# 5. Publishes to PyPI
+#
+# Triggered on push to main (after PR merge)
+name: Release
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:  # Allow manual triggering
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    # Only run if the commit message doesn't start with "bump:" (avoid infinite loop)
+    if: "!startsWith(github.event.head_commit.message, 'bump:')"
+    permissions:
+      contents: write  # Required for creating tags and pushing
+      id-token: write  # Required for trusted PyPI publishing
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # Full history for commitizen
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Configure git
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+
+      - name: Check if release needed
+        id: check
+        run: |
+          # Check if there are any commits that would trigger a version bump
+          # Exit code 21 = NO_COMMITS_TO_BUMP (commits exist but none are feat/fix/breaking)
+          # Exit code 3 = NO_COMMITS_FOUND (no commits at all since last tag)
+          # --yes flag auto-confirms "is this the first tag?" prompt in CI
+          set +e
+          output=$(uv run cz bump --dry-run --yes 2>&1)
+          exit_code=$?
+          set -e
+
+          echo "$output"
+
+          if [ $exit_code -eq 0 ]; then
+            echo "release_needed=true" >> $GITHUB_OUTPUT
+            echo "✓ Release-worthy commits found"
+          elif [ $exit_code -eq 21 ]; then
+            echo "release_needed=false" >> $GITHUB_OUTPUT
+            echo "✓ No release needed (commits are docs/refactor/test/chore only)"
+          elif [ $exit_code -eq 3 ]; then
+            echo "release_needed=false" >> $GITHUB_OUTPUT
+            echo "✓ No commits found since last release"
+          else
+            echo "✗ Unexpected error from commitizen (exit code: $exit_code)"
+            exit $exit_code
+          fi
+
+      - name: Bump version and update changelog
+        if: steps.check.outputs.release_needed == 'true'
+        run: |
+          uv run cz bump --changelog --yes
+          git push --follow-tags
+
+      - name: Build package
+        if: steps.check.outputs.release_needed == 'true'
+        run: uv build
+
+      - name: Publish to PyPI
+        if: steps.check.outputs.release_needed == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          print-hash: true
+
+      - name: Create GitHub Release
+        if: steps.check.outputs.release_needed == 'true'
+        run: |
+          # Get the latest tag
+          TAG=$(git describe --tags --abbrev=0)
+          # Create a GitHub release from the tag
+          gh release create "$TAG" \
+            --title "$TAG" \
+            --notes "See [CHANGELOG](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details." \
+            dist/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}