cihai-cli 0.31.0__tar.gz → 0.32.0__tar.gz

{cihai_cli-0.31.0 → cihai_cli-0.32.0}/.github/workflows/docs.yml

@@ -5,14 +5,19 @@ on:
     branches:
       - master
 
+permissions:
+  contents: read
+  id-token: write
+
 jobs:
   build:
     runs-on: ubuntu-latest
+    environment: docs
     strategy:
       matrix:
         python-version: ['3.14']
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Filter changed file paths to outputs
         uses: dorny/paths-filter@v3.0.2
@@ -35,7 +40,7 @@ jobs:
         run: echo "PUBLISH=$(echo true)" >> $GITHUB_ENV
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
 
@@ -45,6 +50,9 @@ jobs:
       - name: Install dependencies
         run: uv sync --all-extras --dev
 
+      - name: Install just
+        uses: extractions/setup-just@v3
+
       - name: Print python versions
         if: env.PUBLISH == 'true'
         run: |
@@ -54,19 +62,27 @@ jobs:
       - name: Build documentation
         if: env.PUBLISH == 'true'
         run: |
-          pushd docs; make SPHINXBUILD='uv run sphinx-build' html; popd
+          cd docs && just html
 
-      - name: Push documentation to S3
+      - name: Configure AWS Credentials
         if: env.PUBLISH == 'true'
-        uses: jakejarvis/s3-sync-action@v0.5.1
+        uses: aws-actions/configure-aws-credentials@v5
         with:
-          args: --acl public-read --follow-symlinks --delete
-        env:
-          AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
-          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
-          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-          AWS_REGION: 'us-west-1' # optional: defaults to us-east-1
-          SOURCE_DIR: 'docs/_build/html' # optional: defaults to entire repository
+          role-to-assume: ${{ secrets.CIHAI_CLI_DOCS_ROLE_ARN }}
+          aws-region: us-east-1
+
+      - name: Push documentation to S3
+        if: env.PUBLISH == 'true'
+        run: |
+          aws s3 sync docs/_build/html "s3://${{ secrets.CIHAI_CLI_DOCS_BUCKET }}" \
+            --delete --follow-symlinks
+
+      - name: Invalidate CloudFront
+        if: env.PUBLISH == 'true'
+        run: |
+          aws cloudfront create-invalidation \
+            --distribution-id "${{ secrets.CIHAI_CLI_DOCS_DISTRIBUTION }}" \
+            --paths "/index.html" "/objects.inv" "/searchindex.js"
 
       - name: Purge cache on Cloudflare
         if: env.PUBLISH == 'true'

{cihai_cli-0.31.0 → cihai_cli-0.32.0}/.github/workflows/tests.yml

@@ -11,10 +11,10 @@ jobs:
       matrix:
         python-version: ['3.14']
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
 
@@ -49,16 +49,19 @@ jobs:
     runs-on: ubuntu-latest
     needs: build
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+    permissions:
+      id-token: write
+      attestations: write
 
     strategy:
       matrix:
         python-version: ['3.14']
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
 
@@ -74,6 +77,5 @@ jobs:
       - name: Publish package
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          user: __token__
-          password: ${{ secrets.PYPI_API_TOKEN }}
-          skip_existing: true
+          attestations: true
+          skip-existing: true

cihai_cli-0.32.0/.python-version

@@ -0,0 +1 @@
+3.14

{cihai_cli-0.31.0 → cihai_cli-0.32.0}/.tmuxp.yaml

@@ -9,8 +9,8 @@ windows:
   panes:
   - focus: true
   - pane 
-  - make watch_mypy
-  - make start
+  - just watch-mypy
+  - just start
 - window_name: docs
   layout: main-horizontal
   options:
@@ -20,4 +20,4 @@ windows:
   - focus: true
   - pane
   - pane
-  - make start
+  - just start

cihai_cli-0.32.0/.tool-versions

@@ -0,0 +1,3 @@
+just 1.46.0
+uv 0.9.26
+python 3.14 3.13.11 3.12.12 3.11.14 3.10.19

cihai_cli-0.32.0/AGENTS.md

@@ -0,0 +1,174 @@
+# AGENTS.md
+
+Guidance for AI agents (Cursor, Claude Code, Copilot, etc.) working in this repository.
+
+## CRITICAL REQUIREMENTS
+
+### Test Success
+- ALL tests must pass (unit, doctest, lint, type checks) before declaring work complete.
+- Do not describe code as "working" if any test fails.
+- Fix regressions rather than disabling or skipping tests unless explicitly approved.
+
+## Project Overview
+
+gp-libs is the shared tooling stack used across the git-pull ecosystem. This repository, `cihai-cli`, is a command-line interface built on top of the `cihai` library to explore the Unihan (CJK) character database. Key abilities:
+- Lookup CJK characters with `cihai info <char>` and YAML-formatted output.
+- Reverse search definitions with `cihai reverse <term>`.
+- Bootstraps and queries the Unihan dataset via `cihai` / `unihan-etl`.
+- Provides a small, typed argparse-based CLI (`src/cihai_cli/cli.py`) exposed as the `cihai` entry point.
+
+## Development Environment
+
+This project uses:
+- Python 3.10+
+- [uv](https://github.com/astral-sh/uv) for dependency and task execution
+- [ruff](https://github.com/astral-sh/ruff) for linting/formatting
+- [mypy](https://github.com/python/mypy) with strict settings
+- [pytest](https://docs.pytest.org/) (+ doctests) for testing
+- [gp-libs](https://github.com/gp-libs/gp-libs) for shared docs/testing helpers
+- Sphinx (Furo) for documentation
+
+## Common Commands
+
+### Setup
+```bash
+# Install dependencies (editable)
+uv pip install --editable .
+uv pip sync
+
+# Install with dev extras
+uv pip install --editable . -G dev
+```
+
+### Tests
+```bash
+just test           # or: uv run pytest
+uv run pytest tests/test_cli.py           # single file
+uv run pytest tests/test_cli.py::test_info_command  # single test
+
+just start          # run tests then watch with pytest-watcher
+uv run ptw .        # standalone watcher (doctests enabled by default)
+```
+
+### Linting & Types
+```bash
+just ruff           # uv run ruff check .
+just ruff-format    # uv run ruff format .
+uv run ruff check . --fix --show-fixes
+
+just mypy           # strict type checking
+```
+
+### Documentation
+```bash
+just build-docs     # build Sphinx HTML in docs/_build
+just start-docs     # autobuild + livereload
+just design-docs    # update CSS/JS assets
+```
+
+### Workflow (recommended)
+1) `uv run ruff format .`
+2) `uv run pytest`
+3) `uv run ruff check . --fix --show-fixes`
+4) `uv run mypy`
+5) `uv run pytest` (verify clean)
+
+## Code Architecture (quick map)
+- `src/cihai_cli/cli.py`: argparse entrypoint, implements `info` and `reverse` commands, logging setup.
+- `src/cihai_cli/__about__.py`: package metadata (`__version__`).
+- Tests: `tests/` (unit) plus doctests in `src/` and `docs/`.
+- Docs: `docs/` Sphinx project (Furo theme).
+
+## Testing Strategy
+- Pytest with doctests enabled (`addopts` in `pyproject.toml`).
+- Prefer real `cihai` / `unihan_etl` integration over heavy mocking; reuse fixtures where present.
+- Watch mode: `uv run ptw .` (used in `just start`).
+- Coverage via `pytest-cov`; configuration in `pyproject.toml`.
+- Prefer fixtures over mocks (`server`, `session`, etc. when available); use `tmp_path` over `tempfile`, `monkeypatch` over `unittest.mock`.
+
+## Coding Standards
+- `from __future__ import annotations` required; enforced by ruff.
+- Namespace imports for stdlib/typing (`import typing as t`); third-party packages may use `from X import Y`.
+- Docstrings follow NumPy style (see `tool.ruff.lint.pydocstyle`).
+- Python target version: 3.10 (`tool.ruff.target-version`).
+- Keep CLI output human-friendly YAML; avoid breaking existing flags/args.
+- Doctests: keep concise, narrative Examples blocks; move complex flows to `tests/examples/`.
+
+## Documentation Standards
+
+### Code Blocks in Documentation
+
+When writing documentation (README, CHANGES, docs/), follow these rules for code blocks:
+
+**One command per code block.** This makes commands individually copyable.
+
+**Put explanations outside the code block**, not as comments inside.
+
+Good:
+
+Run the tests:
+
+```console
+$ uv run pytest
+```
+
+Run with coverage:
+
+```console
+$ uv run pytest --cov
+```
+
+Bad:
+
+```console
+# Run the tests
+$ uv run pytest
+
+# Run with coverage
+$ uv run pytest --cov
+```
+
+## Debugging Tips
+- Lean on `pytest -k <pattern> -vv` for focused failures.
+- For CLI behavior, run `uv run cihai info 好` or `uv run cihai reverse library`.
+- If Unihan DB is missing, CLI bootstraps automatically; avoid altering that flow unless required.
+- Stuck in loops? Pause, minimize to a minimal repro, document exact errors, and restate the hypothesis before another attempt.
+
+## Git Commit Standards
+
+Commit subjects: `Component/File(commit-type[scope]): Concise description`
+
+Body template:
+```
+why: Reason or impact.
+what:
+- Key technical changes
+- Single topic only
+```
+
+Guidelines:
+- Subject ≤50 chars; body lines ≤72 chars; imperative mood.
+- One topic per commit; separate subject and body with a blank line.
+- Mark breaking changes with `BREAKING:` and include related issue refs when relevant.
+
+Common commit types:
+- **feat**: New features or enhancements
+- **fix**: Bug fixes
+- **refactor**: Code restructuring without functional change
+- **docs**: Documentation updates
+- **chore**: Maintenance (dependencies, tooling, config)
+- **test**: Test-related updates
+- **style**: Code style and formatting
+- **py(deps)**: Dependencies
+- **py(deps[dev])**: Dev dependencies
+- **ai(rules[LLM type])**: AI rule updates (e.g., `ai(rules[AGENTS])`)
+
+## Notes & Docs Authoring
+- For `notes/**/*.md`, keep content concise and well-structured (headings, bullets, code fences).
+- Use clear link text `[Title](mdc:URL)` and avoid redundancy; follow llms.txt style when possible.
+
+## References
+- Project docs: https://cihai-cli.git-pull.com
+- Library docs: https://cihai.git-pull.com
+- Unihan dataset: https://www.unicode.org/charts/unihan.html
+- Shared tooling: https://github.com/gp-libs/gp-libs

{cihai_cli-0.31.0 → cihai_cli-0.32.0}/CHANGES

@@ -28,11 +28,63 @@ $ uv add cihai-cli --prerelease allow
 $ uvx --from 'cihai-cli' --prerelease allow cihai
 ```
 
-## cihai-cli 0.32.x (unreleased)
+## cihai-cli 0.33.x (unreleased)
 
 <!-- Maintainers, insert changes / features for the next release here -->
 
-- _Changes for the upcoming release go here._
+_Add your latest changes from PRs here_
+
+## cihai-cli 0.32.0 (2026-01-24)
+
+### What's new
+
+#### Colored CLI help output (#337)
+
+- Add syntax highlighting for CLI help examples
+- New `_colors.py` module with ANSI color support respecting `NO_COLOR`/`FORCE_COLOR`
+- New `_formatter.py` with custom argparse HelpFormatter for colored examples
+
+#### Replace sphinx-argparse with sphinx_argparse_neo (#337)
+
+- Port `sphinx_argparse_neo` extension from vcspull, replacing external `sphinx-argparse` dependency
+- Add custom Pygments lexers for argparse and CLI usage syntax highlighting:
+  - `argparse_lexer.py` - Lexer for argparse help text
+  - `cli_usage_lexer.py` - Lexer for CLI usage patterns
+- Add `argparse_exemplar.py` extension for transforming argparse epilog examples into documentation
+- Add `argparse_roles.py` for custom Sphinx roles (`:opt:`, `:arg:`, `:prog:`)
+- Add CSS styling for syntax-highlighted argparse output
+- Add comprehensive test suite for all Sphinx extensions
+
+#### Dev dependencies
+
+- Add `types-docutils` and `types-Pygments` for type checking Sphinx extensions (#337)
+
+### Packaging
+
+- Add `py.typed` marker for [PEP 561] type checking support (#337)
+
+[PEP 561]: https://peps.python.org/pep-0561/
+
+## cihai-cli 0.31.1 (2026-01-24)
+
+### Breaking changes
+
+- Bump cihai 0.36.0 -> 0.36.1 (#338)
+
+### CI
+
+- Migrate to PyPI Trusted Publisher (#332)
+
+### Development
+
+#### Makefile -> Justfile (#333)
+
+- Migrate from `Makefile` to `justfile` for running development tasks
+- Update documentation to reference `just` commands
+
+### Documentation
+
+- Migrate docs deployment to AWS OIDC authentication and AWS CLI
 
 ## cihai-cli 0.31.0 (2025-11-01)
 

cihai_cli-0.32.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

{cihai_cli-0.31.0 → cihai_cli-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cihai-cli
-Version: 0.31.0
+Version: 0.32.0
 Summary: Command line frontend for the cihai CJK language library
 Project-URL: Bug Tracker, https://github.com/cihai/cihai-cli/issues
 Project-URL: Documentation, https://cihai-cli.git-pull.com
@@ -28,7 +28,7 @@ Classifier: Topic :: Software Development :: Localization
 Classifier: Topic :: System :: Shells
 Classifier: Topic :: Utilities
 Requires-Python: <4.0,>=3.10
-Requires-Dist: cihai~=0.36.0
+Requires-Dist: cihai~=0.36.1
 Requires-Dist: pyyaml
 Description-Content-Type: text/markdown
 

cihai_cli-0.32.0/docs/_ext/__init__.py

@@ -0,0 +1,3 @@
+"""Sphinx extensions for cihai-cli documentation."""
+
+from __future__ import annotations