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

cihai_cli-0.31.0/.cursor/rules/avoid-debug-loops.mdc

@@ -0,0 +1,57 @@
+---
+description: When stuck in debugging loops, break the cycle by minimizing to an MVP, removing debugging cruft, and documenting the issue completely for a fresh approach
+globs: *.py
+alwaysApply: true
+---
+# Avoid Debug Loops
+
+When debugging becomes circular and unproductive, follow these steps:
+
+## Detection
+- You have made multiple unsuccessful attempts to fix the same issue
+- You are adding increasingly complex code to address errors
+- Each fix creates new errors in a cascading pattern
+- You are uncertain about the root cause after 2-3 iterations
+
+## Action Plan
+
+1. **Pause and acknowledge the loop**
+   - Explicitly state that you are in a potential debug loop
+   - Review what approaches have been tried and failed
+
+2. **Minimize to MVP**
+   - Remove all debugging cruft and experimental code
+   - Revert to the simplest version that demonstrates the issue
+   - Focus on isolating the core problem without added complexity
+
+3. **Comprehensive Documentation**
+   - Provide a clear summary of the issue
+   - Include minimal but complete code examples that reproduce the problem
+   - Document exact error messages and unexpected behaviors
+   - Explain your current understanding of potential causes
+
+4. **Format for Portability**
+   - Present the problem in quadruple backticks for easy copying:
+
+````
+# Problem Summary
+[Concise explanation of the issue]
+
+## Minimal Reproduction Code
+```python
+# Minimal code example that reproduces the issue
+```
+
+## Error/Unexpected Output
+```
+[Exact error messages or unexpected output]
+```
+
+## Failed Approaches
+[Brief summary of approaches already tried]
+
+## Suspected Cause
+[Your current hypothesis about what might be causing the issue]
+````
+
+This format enables the user to easily copy the entire problem statement into a fresh conversation for a clean-slate approach.

cihai_cli-0.31.0/.cursor/rules/dev-loop.mdc

@@ -0,0 +1,187 @@
+---
+description: QA every edit
+globs: *.py
+alwaysApply: true
+---
+
+# Development Process
+
+## Project Stack
+
+The project uses the following tools and technologies:
+
+- **uv** - Python package management and virtual environments
+- **ruff** - Fast Python linter and formatter
+- **py.test** - Testing framework
+  - **pytest-watcher** - Continuous test runner
+- **mypy** - Static type checking
+- **doctest** - Testing code examples in documentation
+
+## 1. Start with Formatting
+
+Format your code first:
+
+```
+uv run ruff format .
+```
+
+## 2. Run Tests
+
+Verify that your changes pass the tests:
+
+```
+uv run py.test
+```
+
+For continuous testing during development, use pytest-watcher:
+
+```
+# Watch all tests
+uv run ptw .
+
+# Watch and run tests immediately, including doctests
+uv run ptw . --now --doctest-modules
+
+# Watch specific files or directories
+uv run ptw . --now --doctest-modules src/libtmux/_internal/
+```
+
+## 3. Commit Initial Changes
+
+Make an atomic commit for your changes using conventional commits.
+Use `@git-commits.mdc` for assistance with commit message standards.
+
+## 4. Run Linting and Type Checking
+
+Check and fix linting issues:
+
+```
+uv run ruff check . --fix --show-fixes
+```
+
+Check typings:
+
+```
+uv run mypy
+```
+
+## 5. Verify Tests Again
+
+Ensure tests still pass after linting and type fixes:
+
+```
+uv run py.test
+```
+
+## 6. Final Commit
+
+Make a final commit with any linting/typing fixes.
+Use `@git-commits.mdc` for assistance with commit message standards.
+
+## Development Loop Guidelines
+
+If there are any failures at any step due to your edits, fix them before proceeding to the next step.
+
+## Python Code Standards
+
+### Docstring Guidelines
+
+For `src/**/*.py` files, follow these docstring guidelines:
+
+1. **Use reStructuredText format** for all docstrings.
+   ```python
+   """Short description of the function or class.
+
+   Detailed description using reStructuredText format.
+
+   Parameters
+   ----------
+   param1 : type
+       Description of param1
+   param2 : type
+       Description of param2
+
+   Returns
+   -------
+   type
+       Description of return value
+   """
+   ```
+
+2. **Keep the main description on the first line** after the opening `"""`.
+
+3. **Use NumPy docstyle** for parameter and return value documentation.
+
+### Doctest Guidelines
+
+For doctests in `src/**/*.py` files:
+
+1. **Use narrative descriptions** for test sections rather than inline comments:
+   ```python
+   """Example function.
+
+   Examples
+   --------
+   Create an instance:
+
+   >>> obj = ExampleClass()
+   
+   Verify a property:
+   
+   >>> obj.property
+   'expected value'
+   """
+   ```
+
+2. **Move complex examples** to dedicated test files at `tests/examples/<path_to_module>/test_<example>.py` if they require elaborate setup or multiple steps.
+
+3. **Utilize pytest fixtures** via `doctest_namespace` for more complex test scenarios:
+   ```python
+   """Example with fixture.
+
+   Examples
+   --------
+   >>> # doctest_namespace contains all pytest fixtures from conftest.py
+   >>> example_fixture = getfixture('example_fixture')
+   >>> example_fixture.method()
+   'expected result'
+   """
+   ```
+
+4. **Keep doctests simple and focused** on demonstrating usage rather than comprehensive testing.
+
+5. **Add blank lines between test sections** for improved readability.
+
+6. **Test your doctests continuously** using pytest-watcher during development:
+   ```
+   # Watch specific modules for doctest changes
+   uv run ptw . --now --doctest-modules src/path/to/module.py
+   ```
+
+### Pytest Testing Guidelines
+
+1. **Use existing fixtures over mocks**:
+   - Use fixtures from conftest.py instead of `monkeypatch` and `MagicMock` when available
+   - For instance, if using libtmux, use provided fixtures: `server`, `session`, `window`, and `pane`
+   - Document in test docstrings why standard fixtures weren't used for exceptional cases
+
+2. **Preferred pytest patterns**:
+   - Use `tmp_path` (pathlib.Path) fixture over Python's `tempfile`
+   - Use `monkeypatch` fixture over `unittest.mock`
+
+### Import Guidelines
+
+1. **Prefer namespace imports**:
+   - Import modules and access attributes through the namespace instead of importing specific symbols
+   - Example: Use `import enum` and access `enum.Enum` instead of `from enum import Enum`
+   - This applies to standard library modules like `pathlib`, `os`, and similar cases
+
+2. **Standard aliases**:
+   - For `typing` module, use `import typing as t`
+   - Access typing elements via the namespace: `t.NamedTuple`, `t.TypedDict`, etc.
+   - Note primitive types like unions can be done via `|` pipes and primitive types like list and dict can be done via `list` and `dict` directly.
+
+3. **Benefits of namespace imports**:
+   - Improves code readability by making the source of symbols clear
+   - Reduces potential naming conflicts
+   - Makes import statements more maintainable

cihai_cli-0.31.0/.cursor/rules/git-commits.mdc

@@ -0,0 +1,95 @@
+---
+description: git-commits: Git commit message standards and AI assistance
+globs: git-commits: Git commit message standards and AI assistance | *.git/* .gitignore .github/* CHANGELOG.md CHANGES.md
+alwaysApply: true
+---
+# Optimized Git Commit Standards
+
+## Commit Message Format
+```
+Component/File(commit-type[Subcomponent/method]): Concise description
+
+why: Explanation of necessity or impact.
+what:
+- Specific technical changes made
+- Focused on a single topic
+
+refs: #issue-number, breaking changes, or relevant links
+```
+
+## Component Patterns
+### General Code Changes
+```
+Component/File(feat[method]): Add feature
+Component/File(fix[method]): Fix bug
+Component/File(refactor[method]): Code restructure
+```
+
+### Packages and Dependencies
+| Language   | Standard Packages                  | Dev Packages                  | Extras / Sub-packages                          |
+|------------|------------------------------------|-------------------------------|-----------------------------------------------|
+| General    | `lang(deps):`                      | `lang(deps[dev]):`            |                                               |
+| Python     | `py(deps):`                        | `py(deps[dev]):`              | `py(deps[extra]):`                            |
+| JavaScript | `js(deps):`                        | `js(deps[dev]):`              | `js(deps[subpackage]):`, `js(deps[dev{subpackage}]):` |
+
+#### Examples
+- `py(deps[dev]): Update pytest to v8.1`
+- `js(deps[ui-components]): Upgrade Button component package`
+- `js(deps[dev{linting}]): Add ESLint plugin`
+
+### Documentation Changes
+Prefix with `docs:`
+```
+docs(Component/File[Subcomponent/method]): Update API usage guide
+```
+
+### Test Changes
+Prefix with `tests:`
+```
+tests(Component/File[Subcomponent/method]): Add edge case tests
+```
+
+## Commit Types Summary
+- **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
+
+## General Guidelines
+- Subject line: Maximum 50 characters
+- Body lines: Maximum 72 characters
+- Use imperative mood (e.g., "Add", "Fix", not "Added", "Fixed")
+- Limit to one topic per commit
+- Separate subject from body with a blank line
+- Mark breaking changes clearly: `BREAKING:`
+- Use `See also:` to provide external references
+
+## AI Assistance Workflow in Cursor
+- Stage changes with `git add`
+- Use `@commit` to generate initial commit message
+- Review and refine generated message
+- Ensure adherence to these standards
+
+## Good Commit Example
+```
+Pane(feat[capture_pane]): Add screenshot capture support
+
+why: Provide visual debugging capability
+what:
+- Implement capturePane method with image export
+- Integrate with existing Pane component logic
+- Document usage in Pane README
+
+refs: #485
+See also: https://example.com/docs/pane-capture
+```
+
+## Bad Commit Example
+```
+fixed stuff and improved some functions
+```
+
+These guidelines ensure clear, consistent commit histories, facilitating easier code review and maintenance.

cihai_cli-0.31.0/.cursor/rules/notes-llms-txt.mdc

@@ -0,0 +1,42 @@
+---
+description: LLM-friendly markdown format for notes directories
+globs: notes/**/*.md,**/notes/**/*.md
+alwaysApply: true
+---
+
+# Instructions for Generating LLM-Optimized Markdown Content
+
+When creating or editing markdown files within the specified directories, adhere to the following guidelines to ensure the content is optimized for LLM understanding and efficient token usage:
+
+1. **Conciseness and Clarity**:
+   - **Be Brief**: Present information succinctly, avoiding unnecessary elaboration.
+   - **Use Clear Language**: Employ straightforward language to convey ideas effectively.
+
+2. **Structured Formatting**:
+   - **Headings**: Utilize markdown headings (`#`, `##`, `###`, etc.) to organize content hierarchically.
+   - **Lists**: Use bullet points (`-`) or numbered lists (`1.`, `2.`, etc.) to enumerate items clearly.
+   - **Code Blocks**: Enclose code snippets within triple backticks (```) to distinguish them from regular text.
+
+3. **Semantic Elements**:
+   - **Emphasis**: Use asterisks (`*`) or underscores (`_`) for italicizing text to denote emphasis.
+   - **Strong Emphasis**: Use double asterisks (`**`) or double underscores (`__`) for bold text to highlight critical points.
+   - **Inline Code**: Use single backticks (`) for inline code references.
+
+4. **Linking and References**:
+   - **Hyperlinks**: Format links using `[Link Text](mdc:URL)` to provide direct access to external resources.
+   - **References**: When citing sources, use footnotes or inline citations to maintain readability.
+
+5. **Avoid Redundancy**:
+   - **Eliminate Repetition**: Ensure that information is not unnecessarily repeated within the document.
+   - **Use Summaries**: Provide brief summaries where detailed explanations are not essential.
+
+6. **Standard Compliance**:
+   - **llms.txt Conformance**: Structure the document in alignment with the `llms.txt` standard, which includes:
+     - An H1 heading with the project or site name.
+     - A blockquote summarizing the project's purpose.
+     - Additional markdown sections providing detailed information.
+     - H2-delimited sections containing lists of URLs for further details.
+
+By following these guidelines, the markdown files will be tailored for optimal LLM processing, ensuring that the content is both accessible and efficiently tokenized for AI applications.
+
+For more information on the `llms.txt` standard, refer to the official documentation: https://llmstxt.org/

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

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.13']
+        python-version: ['3.14']
     steps:
       - uses: actions/checkout@v4
 

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

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.9', '3.13']
+        python-version: ['3.14']
     steps:
       - uses: actions/checkout@v4
 
@@ -52,7 +52,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ['3.13']
+        python-version: ['3.14']
 
     steps:
       - uses: actions/checkout@v4

cihai_cli-0.31.0/.tool-versions

@@ -0,0 +1,2 @@
+uv 0.9.7
+python 3.14.0 3.13.8 3.12.12 3.11.14 3.10.19

cihai_cli-0.31.0/.windsurfrules

@@ -0,0 +1,136 @@
+# libtmux Python Project Rules
+
+<project_stack>
+- uv - Python package management and virtual environments
+- ruff - Fast Python linter and formatter
+- py.test - Testing framework
+  - pytest-watcher - Continuous test runner
+- mypy - Static type checking
+- doctest - Testing code examples in documentation
+</project_stack>
+
+<coding_style>
+- Use a consistent coding style throughout the project
+- Format code with ruff before committing
+- Run linting and type checking before finalizing changes
+- Verify tests pass after each significant change
+</coding_style>
+
+<python_docstrings>
+- Use reStructuredText format for all docstrings in src/**/*.py files
+- Keep the main description on the first line after the opening `"""`
+- Use NumPy docstyle for parameter and return value documentation
+- Format docstrings as follows:
+  ```python
+  """Short description of the function or class.
+
+  Detailed description using reStructuredText format.
+
+  Parameters
+  ----------
+  param1 : type
+      Description of param1
+  param2 : type
+      Description of param2
+
+  Returns
+  -------
+  type
+      Description of return value
+  """
+  ```
+</python_docstrings>
+
+<python_doctests>
+- Use narrative descriptions for test sections rather than inline comments
+- Format doctests as follows:
+  ```python
+  """
+  Examples
+  --------
+  Create an instance:
+
+  >>> obj = ExampleClass()
+  
+  Verify a property:
+  
+  >>> obj.property
+  'expected value'
+  """
+  ```
+- Add blank lines between test sections for improved readability
+- Keep doctests simple and focused on demonstrating usage
+- Move complex examples to dedicated test files at tests/examples/<path_to_module>/test_<example>.py
+- Utilize pytest fixtures via doctest_namespace for complex scenarios
+</python_doctests>
+
+<testing_practices>
+- Run tests with `uv run py.test` before committing changes
+- Use pytest-watcher for continuous testing: `uv run ptw . --now --doctest-modules`
+- Fix any test failures before proceeding with additional changes
+</testing_practices>
+
+<git_workflow>
+- Make atomic commits with conventional commit messages
+- Start with an initial commit of functional changes
+- Follow with separate commits for formatting, linting, and type checking fixes
+</git_workflow>
+
+<git_commit_standards>
+- Use the following commit message format:
+  ```
+  Component/File(commit-type[Subcomponent/method]): Concise description
+
+  why: Explanation of necessity or impact.
+  what:
+  - Specific technical changes made
+  - Focused on a single topic
+
+  refs: #issue-number, breaking changes, or relevant links
+  ```
+
+- 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
+
+- Prefix Python package changes with:
+  - `py(deps):` for standard packages
+  - `py(deps[dev]):` for development packages
+  - `py(deps[extra]):` for extras/sub-packages
+
+- General guidelines:
+  - Subject line: Maximum 50 characters
+  - Body lines: Maximum 72 characters
+  - Use imperative mood (e.g., "Add", "Fix", not "Added", "Fixed")
+  - Limit to one topic per commit
+  - Separate subject from body with a blank line
+  - Mark breaking changes clearly: `BREAKING:`
+</git_commit_standards>
+
+<pytest_testing_guidelines>
+- Use fixtures from conftest.py instead of monkeypatch and MagicMock when available
+- For instance, if using libtmux, use provided fixtures: server, session, window, and pane
+- Document in test docstrings why standard fixtures weren't used for exceptional cases
+- Use tmp_path (pathlib.Path) fixture over Python's tempfile
+- Use monkeypatch fixture over unittest.mock
+</pytest_testing_guidelines>
+
+<import_guidelines>
+- Prefer namespace imports over importing specific symbols
+- Import modules and access attributes through the namespace:
+  - Use `import enum` and access `enum.Enum` instead of `from enum import Enum`
+  - This applies to standard library modules like pathlib, os, and similar cases
+- For typing, use `import typing as t` and access via the namespace:
+  - Access typing elements as `t.NamedTuple`, `t.TypedDict`, etc.
+  - Note primitive types like unions can be done via `|` pipes
+  - Primitive types like list and dict can be done via `list` and `dict` directly
+- Benefits of namespace imports:
+  - Improves code readability by making the source of symbols clear
+  - Reduces potential naming conflicts
+  - Makes import statements more maintainable
+</import_guidelines>

{cihai_cli-0.30.0 → cihai_cli-0.31.0}/CHANGES

@@ -3,24 +3,61 @@
 You can test the unpublished version of cihai-cli before its released, see
 [developmental releases](https://cihai-cli.git-pull.com/quickstart.html#developmental-releases).
 
-- [pip](https://pip.pypa.io/en/stable/):
+[pip](https://pip.pypa.io/en/stable/):
 
-  ```console
-  $ pip install --user --upgrade --pre cihai-cli
-  ```
+```console
+$ pip install --user --upgrade --pre cihai-cli
+```
 
-- [pipx](https://pypa.github.io/pipx/docs/):
+[pipx](https://pypa.github.io/pipx/docs/):
 
-  ```console
-  $ pipx install --suffix=@next cihai-cli --pip-args '\--pre' --include-deps --force
-  ```
+```console
+$ pipx install --suffix=@next 'cihai-cli' --pip-args '\--pre' --force
+// Usage: cihai@next info 好
+```
 
-  Then use `cihai@next info 好`.
+[uv](https://docs.astral.sh/uv/getting-started/features/#python-versions):
 
-## cihai-cli 0.31.x (unreleased)
+```console
+$ uv add cihai-cli --prerelease allow
+```
+
+[uvx](https://docs.astral.sh/uv/guides/tools/):
+
+```console
+$ uvx --from 'cihai-cli' --prerelease allow cihai
+```
+
+## cihai-cli 0.32.x (unreleased)
 
 <!-- Maintainers, insert changes / features for the next release here -->
 
+- _Changes for the upcoming release go here._
+
+## cihai-cli 0.31.0 (2025-11-01)
+
+### Breaking changes
+
+- Bump cihai 0.35.0 -> 0.36.0
+- Drop support for Python 3.9; the new minimum is Python 3.10 (#330).
+
+  See also:
+  - [Python 3.9 EOL timeline](https://devguide.python.org/versions/#:~:text=Release%20manager-,3.9,-PEP%20596)
+  - [PEP 596](https://peps.python.org/pep-0596/)
+
+### Development
+
+- Add Python 3.14 to test matrix (#329)
+
+#### chore: Implement PEP 563 deferred annotation resolution (#324)
+
+- Add `from __future__ import annotations` to defer annotation resolution and reduce unnecessary runtime computations during type checking.
+- Enable Ruff checks for PEP-compliant annotations:
+  - [non-pep585-annotation (UP006)](https://docs.astral.sh/ruff/rules/non-pep585-annotation/)
+  - [non-pep604-annotation (UP007)](https://docs.astral.sh/ruff/rules/non-pep604-annotation/)
+
+For more details on PEP 563, see: https://peps.python.org/pep-0563/
+
 ## cihai-cli 0.30.0 (2024-12-21)
 
 _Maintenance only, no bug fixes, or new features_
@@ -455,6 +492,24 @@ After (cihai 0.15+, cihai-cli 0.11+):
 $ pip install cihai-cli
 ```
 
+Modern uv-based workflows can either add the CLI to a project:
+
+```console
+$ uv add cihai-cli
+```
+
+Install it as a user-wide tool:
+
+```console
+$ uv tool install cihai-cli
+```
+
+Or run it on-demand:
+
+```console
+$ uvx --from cihai-cli cihai --version
+```
+
 This made deploying cihai + cihai-cli and pinning packages extremely laborious.
 
 We can reinvestigate this model in the future.