fips-agents-cli 0.1.0__tar.gz → 0.1.2__tar.gz

fips_agents_cli-0.1.2/.claude/commands/create-release.md

@@ -0,0 +1,75 @@
+---
+description: Prepare and publish a new release version
+tags: [release, publish, version]
+---
+
+You are assisting with creating a new release for the fips-agents-cli project.
+
+## Your Task
+
+1. **Ask the user for release information:**
+   - New version number (format: x.y.z, e.g., 0.1.2)
+   - Release notes/description of changes
+
+2. **Update the README.md changelog:**
+   - Read the current README.md file
+   - Add a new version section under the `## Changelog` heading
+   - Format as:
+     ```markdown
+     ### Version X.Y.Z
+
+     - Feature/Fix: Description of change
+     - Feature/Fix: Description of change
+     ```
+   - Place the new version ABOVE older versions (newest first)
+   - Use the release notes provided by the user to populate the changelog
+
+3. **Run the release script:**
+   - After updating the changelog, run the release script:
+     ```bash
+     ./scripts/release.sh <version> "<commit-message>"
+     ```
+   - The commit message should be a concise summary of the release (e.g., "Add generator commands")
+
+## Important Notes
+
+- The release script will:
+  - Update version in `version.py` and `pyproject.toml`
+  - Commit all changes (including the changelog you updated)
+  - Create and push a git tag
+  - Trigger automated GitHub Actions for PyPI publishing
+
+- Version format must be x.y.z (three numbers separated by dots)
+- Follow semantic versioning:
+  - Major (1.0.0): Breaking changes
+  - Minor (0.1.0): New features, backward compatible
+  - Patch (0.1.1): Bug fixes, backward compatible
+
+- The changelog should be clear and user-focused
+- Group related changes together
+- Use consistent formatting
+
+## Example Interaction
+
+User: "I want to release version 0.1.2"
+
+You should:
+1. Ask: "What changes are included in version 0.1.2? Please describe the new features, fixes, or improvements."
+2. User provides: "Added support for middleware generation, fixed bug in tool validation, improved error messages"
+3. You update README.md changelog:
+   ```markdown
+   ### Version 0.1.2
+
+   - Feature: Added support for middleware generation
+   - Fix: Fixed bug in tool validation
+   - Improvement: Improved error messages
+   ```
+4. You run: `./scripts/release.sh 0.1.2 "Add middleware generation support"`
+5. Confirm success and provide links to monitor the release
+
+## Validation
+
+Before running the script, verify:
+- Version number is in correct format (x.y.z)
+- Changelog is properly formatted
+- User has confirmed the changes are ready to release

{fips_agents_cli-0.1.0 → fips_agents_cli-0.1.2}/.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v4

fips_agents_cli-0.1.2/.github/workflows/workflow.yaml

@@ -0,0 +1,113 @@
+name: Release and Publish
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+  id-token: write  # For PyPI trusted publishing
+
+jobs:
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Read version from version.py
+        id: read_version
+        run: |
+          VERSION_PY=$(grep -E '^__version__' src/fips_agents_cli/version.py | cut -d'"' -f2)
+          echo "version_py=$VERSION_PY" >> $GITHUB_OUTPUT
+
+      - name: Verify version match
+        run: |
+          if [ "${{ steps.version.outputs.version }}" != "${{ steps.read_version.outputs.version_py }}" ]; then
+            echo "Error: Tag version (${{ steps.version.outputs.version }}) does not match version.py (${{ steps.read_version.outputs.version_py }})"
+            exit 1
+          fi
+
+      - name: Extract changelog for this version
+        id: changelog
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+
+          # Extract changelog section for this version from README.md
+          CHANGELOG=$(awk "/### Version $VERSION/,/### Version [0-9]/ { if (/### Version [0-9]/ && !/### Version $VERSION/) exit; if (!/### Version $VERSION/) print }" README.md | sed '/^$/d')
+
+          if [ -z "$CHANGELOG" ]; then
+            CHANGELOG="Release version $VERSION"
+          fi
+
+          # Save to file to preserve formatting
+          echo "$CHANGELOG" > /tmp/changelog.txt
+
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          CHANGELOG=$(cat /tmp/changelog.txt)
+
+          gh release create "${{ steps.version.outputs.tag }}" \
+            --title "Release ${{ steps.version.outputs.tag }}" \
+            --notes "$CHANGELOG" \
+            --verify-tag
+
+  build:
+    name: Build distribution
+    needs: [create-release]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: [build]
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fips-agents-cli
+
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fips_agents_cli-0.1.2/CLAUDE.md

@@ -0,0 +1,328 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**fips-agents-cli** is a Python-based CLI tool for scaffolding FIPS-compliant AI agent projects, with initial focus on MCP (Model Context Protocol) server development. The tool clones template repositories, customizes them for new projects, and prepares them for immediate development use.
+
+**Current Status:** MVP implementation complete with `create mcp-server` command.
+
+## Development Commands
+
+### Environment Setup
+
+```bash
+# Create and activate virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in editable mode with dev dependencies
+pip install -e .[dev]
+```
+
+### Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage report
+pytest --cov=fips_agents_cli --cov-report=html --cov-report=term-missing
+
+# Run specific test file
+pytest tests/test_create.py
+
+# Run specific test
+pytest tests/test_create.py::TestCreateMcpServer::test_successful_creation
+```
+
+### Code Quality
+
+```bash
+# Format code with Black (line length: 100)
+black src tests
+
+# Lint with Ruff
+ruff check src tests
+
+# Run both linters before committing
+black src tests && ruff check src tests
+```
+
+### Building and Distribution
+
+```bash
+# Build distribution packages
+python -m build
+
+# Verify package integrity
+twine check dist/*
+
+# Test local installation
+pip install -e .
+fips-agents --version
+```
+
+### Creating a Release
+
+**Automated Method (Recommended):**
+
+Use the `/create-release` slash command in Claude Code:
+
+```
+/create-release
+```
+
+This command will:
+1. Ask for version number and release notes
+2. Update the changelog in README.md
+3. Run `scripts/release.sh` to:
+   - Update version in `version.py` and `pyproject.toml`
+   - Commit and push changes
+   - Create and push git tag
+   - Trigger GitHub Actions for automated PyPI publishing
+
+**Manual Method:**
+
+**IMPORTANT**: Version numbers must be updated in TWO places:
+1. `src/fips_agents_cli/version.py`
+2. `pyproject.toml`
+
+```bash
+# 1. Update version in both files manually or use the script:
+./scripts/release.sh <version> "<commit-message>"
+
+# Example:
+./scripts/release.sh 0.1.2 "Add new generator features"
+
+# The script handles:
+# - Updating version.py and pyproject.toml
+# - Committing changes (including README.md changelog)
+# - Creating and pushing tag
+# - Triggering GitHub Actions
+```
+
+**Note**: Always update the changelog in README.md before running the script.
+
+See `RELEASE_CHECKLIST.md` for detailed release procedures and troubleshooting.
+
+## Architecture
+
+### Module Structure
+
+The CLI follows a layered architecture:
+
+1. **CLI Layer** (`cli.py`): Click-based command interface with Rich output
+2. **Command Layer** (`commands/`): Command implementations (create, generate, etc.)
+3. **Tools Layer** (`tools/`): Reusable utilities for git, filesystem, and project operations
+4. **Entry Points**: `__main__.py` for `python -m fips_agents_cli`, `cli:main` for the `fips-agents` command
+
+### Key Design Patterns
+
+**Template Repository Pattern**: The CLI clones git repositories as templates rather than bundling templates internally. This allows:
+- Independent template versioning and updates
+- User customization via template forks
+- Minimal CLI package size
+
+**Project Customization Pipeline**: When creating projects, the tool follows this sequence:
+1. Clone template repository (shallow clone, depth=1)
+2. Remove template's `.git` directory
+3. Update `pyproject.toml` with new project name
+4. Rename source directory (`template_name` → `project_name` with underscores)
+5. Update entry point scripts in `pyproject.toml`
+6. Initialize fresh git repository with initial commit
+
+**Rich Console Output**: All user-facing output uses Rich library for:
+- Colored output (green checkmarks, red errors, yellow warnings)
+- Progress spinners for long operations
+- Formatted panels for success messages
+- Consistent visual style
+
+### Important Implementation Details
+
+**Project Name Handling**: Project names use hyphens (kebab-case) but module names use underscores (snake_case). The `to_module_name()` utility converts between these formats. This is critical for Python import compatibility.
+
+**TOML Manipulation**: Uses `tomlkit` (not `toml`) to preserve formatting and comments in `pyproject.toml` files during customization.
+
+**Git Operations**: Uses GitPython library for all git operations. Template clones are shallow (depth=1) for performance. The `.git` directory from templates is always removed before initializing a fresh repository.
+
+**Error Handling Strategy**: Commands use Rich console for user-friendly error messages, then call `sys.exit()` with appropriate exit codes. Validation failures provide hints for correction.
+
+## Testing Architecture
+
+### Test Structure
+
+Tests are organized by module:
+- `test_create.py`: Create command integration tests
+- `test_filesystem.py`: Filesystem utility unit tests
+- `test_project.py`: Project customization unit tests
+
+### Key Fixtures
+
+**`cli_runner`**: Provides Click's `CliRunner` for command testing. Use `invoke()` to run commands in isolated environment.
+
+**`temp_dir`**: Provides temporary directory that's automatically cleaned up. Use for file operations.
+
+**`mock_template_repo`**: Creates a complete mock MCP server template structure with:
+- `pyproject.toml` with placeholder project name
+- `src/mcp_server_template/` module directory
+- `prompts/` directory for YAML prompts
+- `.fips-agents-cli/generators/` for future generator templates
+
+### Testing Patterns
+
+When testing commands:
+```python
+result = runner.invoke(cli, ["create", "mcp-server", "test-server"])
+assert result.exit_code == 0
+assert "Success" in result.output
+```
+
+When testing with filesystem fixtures:
+```python
+def test_something(temp_dir):
+    project_path = temp_dir / "my-project"
+    # Test filesystem operations
+```
+
+## Configuration Files
+
+### pyproject.toml
+
+- **Build System**: Uses Hatchling (not Poetry or setuptools)
+- **Python Version**: Requires ≥3.10, supports 3.10-3.12 (dropped 3.9 in v0.1.1)
+- **Line Length**: Black and Ruff both configured for 100 characters
+- **Entry Point**: `fips-agents = "fips_agents_cli.cli:main"`
+- **Test Configuration**: pytest runs with coverage by default
+- **Version Management**: Version number must match `src/fips_agents_cli/version.py`
+
+### CI/CD Workflows
+
+**test.yml**: Runs on push/PR to main
+- Matrix testing across Python 3.10, 3.11, 3.12 (dropped 3.9 support in v0.1.1)
+- Runs pytest with coverage
+- Checks Black formatting
+- Runs Ruff linting
+- Builds distribution and validates with twine
+
+**workflow.yaml**: Automated release and PyPI publishing (triggered by version tags)
+- Triggers on `v*.*.*` tags (e.g., `v0.1.1`)
+- Verifies tag version matches both `version.py` and `pyproject.toml`
+- Extracts changelog from README.md
+- Creates GitHub Release automatically
+- Builds wheels and source distributions
+- Publishes to PyPI using trusted publishing (no API key needed)
+- **Important**: This single workflow handles the complete release process - DO NOT create separate release workflows
+
+## Common Development Patterns
+
+### Adding a New Command
+
+1. Create command file in `commands/` directory
+2. Define Click command group or command
+3. Register in `cli.py` with `cli.add_command()`
+4. Use Rich console for all output
+5. Add comprehensive tests in `tests/test_commandname.py`
+
+### Adding a New Tool/Utility
+
+1. Create utility module in `tools/` directory
+2. Import Rich console: `console = Console()`
+3. Provide clear docstrings with Args/Returns
+4. Return meaningful values (bool, tuple, etc.) not just console output
+5. Test in isolation with fixtures
+
+### File Operations Best Practices
+
+- Always use `pathlib.Path`, never string paths
+- Use `Path.resolve()` for absolute paths in user-facing messages
+- Check existence before operations: `path.exists()`
+- Use `parents=True, exist_ok=True` for `mkdir()` calls
+- Handle errors gracefully with try/except and user-friendly messages
+
+### Output Conventions
+
+- Success: `[green]✓[/green] Message`
+- Error: `[red]✗[/red] Message`
+- Warning: `[yellow]⚠[/yellow] Message`
+- Info: `[cyan]Message[/cyan]` or `[dim]Message[/dim]`
+- Use `console.print()` not `print()` or `click.echo()`
+
+## Known Patterns and Conventions
+
+### Template Repository Structure
+
+The CLI expects templates to have:
+- `pyproject.toml` with project name and entry points
+- `src/{module_name}/` source directory
+- `.fips-agents-cli/generators/` (optional, for Phase 2 generate commands)
+- Standard Python project structure
+
+### Project Name Validation
+
+Valid project names must:
+- Start with a lowercase letter
+- Contain only lowercase letters, numbers, hyphens, and underscores
+- Not be empty
+
+Examples:
+- ✅ `my-server`, `test_mcp`, `server123`
+- ❌ `MyServer` (uppercase), `123server` (starts with number), `my@server` (special chars)
+
+### Module vs Project Names
+
+- **Project name**: Uses hyphens (e.g., `my-mcp-server`)
+- **Module name**: Uses underscores (e.g., `my_mcp_server`)
+- Conversion: `project_name.replace("-", "_")`
+- This matters for imports and directory names
+
+## Future Roadmap Context
+
+### Phase 2 (Next): Generate Command
+
+The `generate` command will:
+- Load generator templates from `.fips-agents-cli/generators/` in projects
+- Use Jinja2 for template rendering
+- Support tool, prompt, and resource generation
+- Interactive prompts for parameters
+
+Template location strategy: Generators are copied into projects during creation (not kept in CLI), allowing per-project customization.
+
+### Why This Matters Now
+
+- Don't remove `.fips-agents-cli/` directories during template cloning
+- Test fixtures already include generator directory structure
+- Project customization must preserve these directories
+
+## Troubleshooting Common Issues
+
+### Git Clone Failures
+
+Check:
+1. Internet connectivity
+2. Template repository URL is accessible
+3. Git is installed: `git --version`
+4. Permissions on target directory
+
+### Module Not Found After Installation
+
+Ensure:
+1. Virtual environment is activated
+2. Package installed with `-e` flag: `pip install -e .`
+3. Using correct Python interpreter: `which python`
+
+### Test Failures
+
+Common causes:
+1. Forgot to activate venv
+2. Dependencies not installed: `pip install -e .[dev]`
+3. Git not configured globally: `git config --global user.email "test@example.com"`
+
+## Repository-Specific Notes
+
+- The main branch is `main` (not `master`)
+- Template URL is hardcoded to `https://github.com/rdwj/mcp-server-template`
+- Package name on PyPI: `fips-agents-cli`
+- Command name: `fips-agents` (no `-cli` suffix)
+- Recommended installation: `pipx install fips-agents-cli`