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

{cihai_cli-0.31.0 → cihai_cli-0.31.1}/.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.31.1}/.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.31.1/.python-version

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

{cihai_cli-0.31.0 → cihai_cli-0.31.1}/.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.31.1/.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.31.1/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.31.1}/CHANGES

@@ -32,7 +32,28 @@ $ uvx --from 'cihai-cli' --prerelease allow cihai
 
 <!-- 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.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.31.1/CLAUDE.md

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cihai-cli
-Version: 0.31.0
+Version: 0.31.1
 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.31.0 → cihai_cli-0.31.1}/docs/_templates/sidebar/projects.html

@@ -49,7 +49,7 @@
   <p class="indented-block">
     <span class="project-name">web</span>
     <span class="indent">
-      <a class="internal" href="https://social-embed.git-pull.com" class="current">social-embed</a>
+      <a class="internal" href="https://social-embed.org" class="current">social-embed</a>
     </span>
   </p>
 </div>

cihai_cli-0.31.1/docs/justfile

@@ -0,0 +1,206 @@
+# justfile for cihai-cli documentation
+# https://just.systems/
+
+set shell := ["bash", "-uc"]
+
+# Configuration
+http_port := "8037"
+builddir := "_build"
+sphinxopts := ""
+sphinxbuild := "uv run sphinx-build"
+sourcedir := "."
+
+# File patterns for watching
+watch_files := "find .. -type f -not -path '*/\\.*' | grep -i '.*[.]\\(rst\\|md\\)$\\|.*[.]py$\\|CHANGES\\|TODO\\|.*conf\\.py' 2> /dev/null"
+
+# Sphinx options
+allsphinxopts := "-d " + builddir + "/doctrees " + sphinxopts + " ."
+
+# List all available commands
+default:
+    @just --list
+
+# Build HTML documentation
+[group: 'build']
+html:
+    {{ sphinxbuild }} -b html {{ allsphinxopts }} {{ builddir }}/html
+    @echo ""
+    @echo "Build finished. The HTML pages are in {{ builddir }}/html."
+
+# Build directory HTML files
+[group: 'build']
+dirhtml:
+    {{ sphinxbuild }} -b dirhtml {{ allsphinxopts }} {{ builddir }}/dirhtml
+    @echo ""
+    @echo "Build finished. The HTML pages are in {{ builddir }}/dirhtml."
+
+# Build single HTML file
+[group: 'build']
+singlehtml:
+    {{ sphinxbuild }} -b singlehtml {{ allsphinxopts }} {{ builddir }}/singlehtml
+    @echo ""
+    @echo "Build finished. The HTML page is in {{ builddir }}/singlehtml."
+
+# Build EPUB
+[group: 'build']
+epub:
+    {{ sphinxbuild }} -b epub {{ allsphinxopts }} {{ builddir }}/epub
+    @echo ""
+    @echo "Build finished. The epub file is in {{ builddir }}/epub."
+
+# Build LaTeX files
+[group: 'build']
+latex:
+    {{ sphinxbuild }} -b latex {{ allsphinxopts }} {{ builddir }}/latex
+    @echo ""
+    @echo "Build finished; the LaTeX files are in {{ builddir }}/latex."
+
+# Build PDF via LaTeX
+[group: 'build']
+latexpdf:
+    {{ sphinxbuild }} -b latex {{ allsphinxopts }} {{ builddir }}/latex
+    @echo "Running LaTeX files through pdflatex..."
+    make -C {{ builddir }}/latex all-pdf
+    @echo "pdflatex finished; the PDF files are in {{ builddir }}/latex."
+
+# Build plain text files
+[group: 'build']
+text:
+    {{ sphinxbuild }} -b text {{ allsphinxopts }} {{ builddir }}/text
+    @echo ""
+    @echo "Build finished. The text files are in {{ builddir }}/text."
+
+# Build man pages
+[group: 'build']
+man:
+    {{ sphinxbuild }} -b man {{ allsphinxopts }} {{ builddir }}/man
+    @echo ""
+    @echo "Build finished. The manual pages are in {{ builddir }}/man."
+
+# Build JSON output
+[group: 'build']
+json:
+    {{ sphinxbuild }} -b json {{ allsphinxopts }} {{ builddir }}/json
+    @echo ""
+    @echo "Build finished; now you can process the JSON files."
+
+# Clean build directory
+[group: 'misc']
+[confirm]
+clean:
+    rm -rf {{ builddir }}/*
+
+# Build HTML help files
+[group: 'misc']
+htmlhelp:
+    {{ sphinxbuild }} -b htmlhelp {{ allsphinxopts }} {{ builddir }}/htmlhelp
+    @echo ""
+    @echo "Build finished; now you can run HTML Help Workshop with the .hhp project file in {{ builddir }}/htmlhelp."
+
+# Build Qt help files
+[group: 'misc']
+qthelp:
+    {{ sphinxbuild }} -b qthelp {{ allsphinxopts }} {{ builddir }}/qthelp
+    @echo ""
+    @echo "Build finished; now you can run 'qcollectiongenerator' with the .qhcp project file in {{ builddir }}/qthelp."
+
+# Build Devhelp files
+[group: 'misc']
+devhelp:
+    {{ sphinxbuild }} -b devhelp {{ allsphinxopts }} {{ builddir }}/devhelp
+    @echo ""
+    @echo "Build finished."
+
+# Build Texinfo files
+[group: 'misc']
+texinfo:
+    {{ sphinxbuild }} -b texinfo {{ allsphinxopts }} {{ builddir }}/texinfo
+    @echo ""
+    @echo "Build finished. The Texinfo files are in {{ builddir }}/texinfo."
+
+# Build Info files from Texinfo
+[group: 'misc']
+info:
+    {{ sphinxbuild }} -b texinfo {{ allsphinxopts }} {{ builddir }}/texinfo
+    @echo "Running Texinfo files through makeinfo..."
+    make -C {{ builddir }}/texinfo info
+    @echo "makeinfo finished; the Info files are in {{ builddir }}/texinfo."
+
+# Build gettext catalogs
+[group: 'misc']
+gettext:
+    {{ sphinxbuild }} -b gettext {{ sphinxopts }} . {{ builddir }}/locale
+    @echo ""
+    @echo "Build finished. The message catalogs are in {{ builddir }}/locale."
+
+# Check all external links
+[group: 'validate']
+linkcheck:
+    {{ sphinxbuild }} -b linkcheck {{ allsphinxopts }} {{ builddir }}/linkcheck
+    @echo ""
+    @echo "Link check complete; look for any errors in the above output or in {{ builddir }}/linkcheck/output.txt."
+
+# Run doctests embedded in documentation
+[group: 'validate']
+doctest:
+    {{ sphinxbuild }} -b doctest {{ allsphinxopts }} {{ builddir }}/doctest
+    @echo "Testing of doctests in the sources finished, look at the results in {{ builddir }}/doctest/output.txt."
+
+# Check build from scratch
+[group: 'validate']
+checkbuild:
+    rm -rf {{ builddir }}
+    {{ sphinxbuild }} -n -q ./ {{ builddir }}
+
+# Build redirects configuration
+[group: 'misc']
+redirects:
+    {{ sphinxbuild }} -b rediraffewritediff {{ allsphinxopts }} {{ builddir }}/redirects
+    @echo ""
+    @echo "Build finished. The redirects are in rediraffe_redirects."
+
+# Show changes overview
+[group: 'misc']
+changes:
+    {{ sphinxbuild }} -b changes {{ allsphinxopts }} {{ builddir }}/changes
+    @echo ""
+    @echo "The overview file is in {{ builddir }}/changes."
+
+# Watch files and rebuild on change
+[group: 'dev']
+watch:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if command -v entr > /dev/null; then
+        ${{ watch_files }} | entr -c just html
+    else
+        just html
+    fi
+
+# Serve documentation via Python http.server
+[group: 'dev']
+serve:
+    @echo '=============================================================='
+    @echo ''
+    @echo 'docs server running at http://localhost:{{ http_port }}/'
+    @echo ''
+    @echo '=============================================================='
+    python -m http.server {{ http_port }} --directory {{ builddir }}/html
+
+# Watch and serve simultaneously
+[group: 'dev']
+dev:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    just watch &
+    just serve
+
+# Start sphinx-autobuild server
+[group: 'dev']
+start:
+    uv run sphinx-autobuild "{{ sourcedir }}" "{{ builddir }}" {{ sphinxopts }} --port {{ http_port }}
+
+# Design mode: watch static files and disable incremental builds
+[group: 'dev']
+design:
+    uv run sphinx-autobuild "{{ sourcedir }}" "{{ builddir }}" {{ sphinxopts }} --port {{ http_port }} --watch "." -a