pypet CLI Development Assistant

A specialized skill for working with pypet, a modern Python command-line snippet manager with Git synchronization, clipboard integration, and shell alias management.

What This Skill Does

This skill helps you work effectively with the pypet codebase by:

Architecture Overview

Core Components

1. **Models** (`pypet/models.py`): `Snippet` and `Parameter` dataclasses with TOML serialization

2. **Storage** (`pypet/storage.py`): TOML-based persistence at `~/.config/pypet/snippets.toml`

3. **CLI** (`pypet/cli/*.py`): Click-based interface with Rich formatting, organized into modules

4. **Sync** (`pypet/sync.py`): Git-based synchronization with automatic backups

5. **Alias Manager** (`pypet/alias_manager.py`): Shell alias management for bash/zsh

Key Features

Step-by-Step Instructions

1. Initial Setup and Context Gathering

When starting work:

2. Running Tests

**Use these commands in order of preference:**

```bash

Quick test (stops on first failure, for rapid iteration)

make test-quick

Full test suite

make test

Or: pytest

Verbose output

pytest -v

Specific test file

pytest tests/test_models.py

Specific test function

pytest tests/test_models.py::test_snippet_initialization

```

**Important:** All 130 tests must pass before any release.

3. Code Quality Checks

**Always run before committing:**

```bash

Auto-format and fix with ruff (REQUIRED before commit)

make format

Check linting

make lint

Run all checks (format + lint + test)

make all

```

**Note:** Ruff is used for both formatting and linting. Pre-push hooks enforce this automatically.

4. Development Workflow

```bash

Set up complete dev environment with hooks

make dev

Or step by step:

make install # Install package in dev mode

make hooks # Install pre-push git hooks

Run CLI locally

pypet --help

```

5. Adding New Commands

**Follow this pattern to avoid circular imports:**

1. Create command in appropriate module (e.g., `cli/snippet_commands.py`)

2. Import main from `.main`: `from .main import main`

3. Register with decorator: `@main.command()`

4. Import module in `cli/__init__.py` to trigger registration

5. Add tests in corresponding `tests/test_*_cli.py` file

**Example:**

```python

In cli/snippet_commands.py

from .main import main

@main.command()

def my_command():

"""Command description."""

pass

```

6. Working with Storage

7. Testing Patterns

Tests are organized by component:

**Use Click's `CliRunner` for CLI tests:**

```python

from click.testing import CliRunner

runner = CliRunner()

result = runner.invoke(command, args)

```

8. Code Conventions

**Follow these strictly:**

9. Git Workflow

**Important guidelines:**

10. Debugging and Troubleshooting

**Common issues:**

Important Constraints

1. **Never skip tests in production**: All 130 tests must pass

2. **Always format before commit**: Use `make format` or pre-push hooks will fail

3. **Respect module organization**: Don't bypass the CLI module structure

4. **Maintain backward compatibility**: TOML format changes must migrate existing data

5. **Use atomic operations**: Storage operations must be thread-safe

Example Usage

**Scenario: Adding a new snippet command**

1. Determine appropriate module (e.g., `cli/snippet_commands.py`)

2. Read existing commands in that module for patterns

3. Implement command following Click conventions

4. Add corresponding tests in `tests/test_cli.py`

5. Run `make format` to auto-format

6. Run `make test-quick` to verify

7. Run `make all` before committing

**Scenario: Fixing a test failure**

1. Run `pytest -v tests/test_failing.py` for detailed output

2. Fix the issue in the relevant module

3. Run `make format` to ensure formatting is correct

4. Run `pytest tests/test_failing.py` to verify fix

5. Run `make test` to ensure no regressions

**Scenario: Understanding sync feature**

1. Read `pypet/sync.py` for implementation

2. Review `tests/test_sync.py` for usage examples

3. Check `cli/sync_commands.py` for CLI interface

4. Understand backup/restore flow in Storage class

Notes