reporails-cli 0.0.2__tar.gz → 0.1.1__tar.gz

{reporails_cli-0.0.2 → reporails_cli-0.1.1}/.claude/rules/writing-rules.md

@@ -26,4 +26,3 @@ paths: ["src/**/*.py"]  # Optional: scope to specific files
 - Use descriptive filenames (`api-validation.md` not `rules1.md`)
 - Add `paths` frontmatter to reduce noise when not relevant
 - No paths = loads globally for all files
-- Content MUST be actionable, not explanatory

reporails_cli-0.1.1/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.file_path // .tool_input.filePath // empty' | grep -q 'src/reporails_cli/bundled/' && echo '{\"decision\": \"block\", \"reason\": \"Bundled config files (levels.yml, capability-patterns.yml) must not be modified without explicit human instruction. These are CLI-owned orchestration logic.\"}' && exit 2 || exit 0"
+          }
+        ]
+      }
+    ]
+  }
+}

reporails_cli-0.1.1/.claude/skills/add-changelog-entry/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: add-changelog-entry
+description: Add a changelog entry to UNRELEASED.md
+---
+
+# /add-changelog-entry
+
+Automatically add a changelog entry to PROJECT_ROOT/UNRELEASED.md.
+
+## Instructions
+
+1. Check git diff or recent file modifications
+2. Determine the area from the file path:
+   - interfaces/cli/ → [CLI]
+   - core/ → [CORE]
+   - bundled/ → [BUNDLED]
+   - formatters/ → [FORMATTERS]
+   - README.md → [DOCS]
+   - CLAUDE.md, backbone.yml, .claude/, .reporails/ → [META]
+3. Determine the category:
+   - New files/content → Added
+   - Modified existing → Changed
+   - Marked as deprecated/obsolete → Deprecated
+   - Removed content → Removed
+   - Bug fixes → Fixed
+   - Security-related changes → Security
+4. Write a concise description (3-7 words)
+5. Append to UNRELEASED.md under the correct category section
+6. Create the category section if it doesn't exist
+
+## Format
+
+```markdown
+### [Category]
+- [Area]: [Description]
+```
+
+## Categories
+
+Added, Changed, Deprecated, Removed, Fixed, Security
+
+## Areas
+
+- [CLI] – CLI interface (interfaces/cli/)
+- [CORE] – Core domain logic
+- [BUNDLED] – Bundled config (levels.yml, capability-patterns.yml)
+- [FORMATTERS] – Output formatters
+- [DOCS] – README, general documentation
+- [META] – CLAUDE.md, backbone.yml, repo structure
+
+## Example
+
+```markdown
+### Added
+- [CORE]: Semantic rule caching support
+
+### Changed
+- [FORMATTERS]: Updated compact output format
+```
+
+Do not ask for confirmation. Just do it.

reporails_cli-0.1.1/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: reporails

reporails_cli-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  npm:
+    name: Publish to npm
+    needs: pypi
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      id-token: write
+    defaults:
+      run:
+        working-directory: packages/npm
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Set version from release tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          npm version "$VERSION" --no-git-tag-version
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance

{reporails_cli-0.0.2 → reporails_cli-0.1.1}/.gitignore

@@ -15,6 +15,9 @@ docs/research
 
 .env
 
-# Claude Code MCP config (machine-specific paths)
+# Claude Code (machine-specific)
 .claude/mcp.json
+.claude/settings.local.json
+.claude/skills/*
+!.claude/skills/add-changelog-entry/
 .mcp.json

reporails_cli-0.1.1/.shared/knowledge/changelog.md

@@ -0,0 +1,103 @@
+# Changelog
+
+How to maintain the changelog and create releases.
+
+## Format
+
+[Keep a Changelog](https://keepachangelog.com/) with project-specific conventions.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `UNRELEASED.md` | Accumulates changes during development |
+| `CHANGELOG.md` | Released versions (moved from UNRELEASED) |
+
+## Adding Entries
+
+Add to `UNRELEASED.md` as you work:
+
+```markdown
+### Added
+- [AREA]: Brief description of what was added
+
+### Changed
+- [AREA]: Brief description of what changed
+
+### Fixed
+- [AREA]: Brief description of what was fixed
+
+### Removed
+- [AREA]: Brief description of what was removed
+```
+
+**Areas:** CLI, CORE, BUNDLED, FORMATTERS, DOCS, META
+
+## Writing Good Entries
+
+**Do:**
+- Group by theme, not by file
+- Lead with what matters to users
+- Be specific but concise
+
+**Don't:**
+- List every file changed
+- Use commit-message style entries
+- Bury important changes in lists
+
+**Good:**
+```markdown
+- [CORE]: Semantic rule caching support
+- [CLI]: Added --quiet-semantic flag to suppress messages
+```
+
+**Bad:**
+```markdown
+- Added cache.py
+- Changed main.py to add flag
+```
+
+## Creating a Release
+
+**Process:**
+1. Review `UNRELEASED.md`
+2. Group similar changes by theme
+3. Write release summary for `CHANGELOG.md`
+4. Clear `UNRELEASED.md` (keep header)
+5. Commit, tag, push
+
+**Release entry template:**
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+One-line summary of the release.
+
+### Added
+- **Theme**: Summary
+
+### Changed
+- **Theme**: Summary
+
+### Fixed
+- **Theme**: Summary
+```
+
+## Tagging
+
+```bash
+git tag X.Y.Z
+git push origin X.Y.Z
+```
+
+Tag format: [SemVer](https://semver.org/) (e.g., `0.2.0`)
+
+## Version Numbering
+
+| Change Type | Bump | Example |
+|-------------|------|---------|
+| Breaking changes | Major | 1.0.0 → 2.0.0 |
+| New features (backwards compatible) | Minor | 0.1.0 → 0.2.0 |
+| Bug fixes | Patch | 0.1.0 → 0.1.1 |
+
+Pre-1.0: Minor bumps for features, patch for fixes. Breaking changes OK.

{reporails_cli-0.0.2 → reporails_cli-0.1.1}/CLAUDE.md

@@ -1,8 +1,6 @@
-# Reporails CLI
+# Reporails CLI v0.1.1
 
-AI instruction linter. Validates instruction files against community-maintained rules.
-
-**repoRAILS** = **Repo** **R**ecursive **AI** **L**inting**S**
+AI instruction validator. Validates instruction files against community-maintained rules.
 
 ## Development Context
 
@@ -14,11 +12,17 @@ You are developing the reporails CLI, not an end user.
 
 Don't conflate these when discussing features, delivery, or documentation.
 
-## Session Start
+## File Reading Strategy
+
+- Read specs (`docs/specs/*.md`) before modifying core modules
+- Prefer reading specific files over broad glob patterns
+
+## Search Efficiency
 
-1. Read `.reporails/backbone.yml` for project structure
-2. Read `docs/specs/arch.md` for architecture decisions
-3. Read `docs/specs/modules.md` before modifying core modules
+- Use `Grep --type py` for Python-specific searches
+- Use `Glob "src/**/*.py"` to find Python files
+- Limit searches to `src/` or `tests/` directories when possible
+- Avoid grepping the entire repo; scope to relevant paths
 
 ## Quick Start
 ```bash
@@ -50,6 +54,8 @@ src/reporails_cli/
 └── formatters/     # Output adapters
 ```
 
+Path-scoped rules in `.claude/rules/` — see those files for context-specific constraints.
+
 See `docs/specs/arch.md` for full architecture.
 
 ## Framework vs CLI
@@ -62,28 +68,12 @@ See `docs/specs/arch.md` for full architecture.
 
 ## QA Commands
 
-| Command | Purpose |
-|---------|---------|
-| `uv run poe qa_fast` | Lint, type check, unit tests (pre-commit) |
-| `uv run poe qa` | Full QA including integration tests |
-| `uv run poe lint` | Ruff linter |
-| `uv run poe format` | Format code |
-| `uv run poe type` | Mypy type checking |
-| `uv run poe test_unit` | Unit tests only (fast, no OpenGrep) |
-| `uv run poe test_integration` | Integration tests (requires OpenGrep) |
-
-## Test Structure
-
-```
-tests/
-├── unit/           # Fast tests, no external dependencies
-└── integration/    # Requires OpenGrep binary
-```
+- `uv run poe qa_fast` — Lint, type check, unit tests (pre-commit)
+- `uv run poe qa` — Full QA including integration tests
 
 ## Architecture
 
-- **Agent-Agnostic**: Detects Claude, Cursor, Windsurf, Copilot, Aider
-- **Claude Rules v0.0.1**: Linting rules currently for Claude only
+@docs/specs/arch.md for full architecture details.
+
 - **OpenGrep-Powered**: Deterministic pattern matching
-- **Two-Phase Detection**: Filesystem + content analysis for capability scoring
 - **Framework Separation**: CLI orchestrates, framework defines rules

reporails_cli-0.1.1/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: reporails-cli
+Version: 0.1.1
+Summary: Validate and score CLAUDE.md files — MCP-first AI context governance
+Project-URL: Homepage, https://github.com/reporails/cli
+Project-URL: Documentation, https://reporails.dev/docs
+Project-URL: Repository, https://github.com/reporails/cli
+Project-URL: Issues, https://github.com/reporails/cli/issues
+Author: Reporails Team
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai,claude,claude-code,context,mcp,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: poethepoet>=0.25.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Reporails CLI
+
+Score your CLAUDE.md files. See what's missing. Improve your AI coding setup.
+[Why this exists](https://dev.to/cleverhoods/claudemd-lint-score-improve-repeat-2om5)
+
+## Quick Start
+
+### One-line install (npm)
+
+```bash
+npx @reporails/cli install
+```
+
+This registers the MCP server with Claude Code. Then ask Claude: `What ails claude?`
+
+### MCP Integration (manual)
+
+For full semantic analysis, add the MCP server:
+```bash
+# Add the MCP and restart Claude
+claude mcp add reporails -- uvx reporails-cli ails-mcp
+```
+
+Then ask Claude:
+```
+❯ What ails claude?
+```
+
+### CLI path (only deterministic rules)
+```bash
+# No install needed — run directly
+uvx reporails-cli check
+# or
+npx @reporails/cli check
+```
+
+That's it. You'll get a score, capability level, and actionable violations.
+```
+╔══════════════════════════════════════════════════════════════╗
+║   SCORE: 8.1 / 10 (partial)  |  CAPABILITY: Governed (L5)    ║
+║   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░         ║
+╚══════════════════════════════════════════════════════════════╝
+
+Violations:
+  CLAUDE.md (7 issues)
+    ○ MED C4.no-antipatterns :1    No NEVER or AVOID statements found
+    · LOW C12.no-version     :1    No version or date marker found
+    ...
+```
+
+Fix the issues, run again, watch your score and your experience improve.
+
+## Install
+
+```bash
+# Ephemeral (no install, always latest)
+uvx reporails-cli check
+npx @reporails/cli check
+
+# Persistent (adds `ails` to PATH)
+pip install reporails-cli
+# or
+npm install -g @reporails/cli
+```
+
+Once installed, all commands use `ails` directly.
+
+## What It Checks
+
+- **Structure** — File organization, size limits
+- **Content** — Clarity, completeness, anti-patterns
+- **Efficiency** — Token usage, context management
+- **Maintenance** — Versioning, review processes
+- **Governance** — Ownership, security policies
+
+## Capability Levels
+
+| Level | Name | What it means |
+|-------|------|---------------|
+| L1 | Absent | No instruction file |
+| L2 | Basic | Has CLAUDE.md |
+| L3 | Structured | Sections, imports |
+| L4 | Abstracted | .claude/rules/ directory |
+| L5 | Governed | Shared files, 3+ components |
+| L6 | Adaptive | Backbone + full governance |
+
+## Commands
+
+```bash
+ails check                      # Score your setup
+ails check -f json              # JSON output (for CI)
+ails check --strict             # Exit 1 if violations (for CI)
+ails check --with-recommended   # Include recommended rules
+ails explain S1                 # Explain a rule
+ails map                        # Show project structure
+ails map --save                 # Generate backbone.yml
+ails update                     # Update rules framework
+ails update --check             # Check for rule updates
+ails dismiss C6                 # Dismiss a semantic finding
+ails version                    # Show version info
+```
+
+## Updating
+
+The **rules framework** updates separately from the CLI:
+
+```bash
+ails update              # Update rules to latest
+ails update --check      # Check without installing
+```
+
+The **CLI itself** updates automatically with ephemeral runners (`uvx`, `npx`).
+Persistent installs: `pip install --upgrade reporails-cli` or `npm install -g @reporails/cli@latest`
+
+## Recommended Rules
+
+The `--with-recommended` flag adds community [recommended rules](https://github.com/reporails/recommended) on top of the core set. These are methodology-backed checks (AILS_ namespace) that are auto-downloaded on first use:
+
+```bash
+ails check --with-recommended       # Include recommended rules
+ails update --recommended              # Re-fetch latest recommended rules
+```
+
+## Prerequisites
+
+Depends on your install path:
+
+- **uvx/pip path**: [uv](https://docs.astral.sh/uv/) — no separate Python install needed
+- **npx/npm path**: Node.js >= 18 — uv is auto-installed if missing
+- **MCP install/uninstall**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+
+## Rules
+
+Core rules are maintained at [reporails/rules](https://github.com/reporails/rules).
+Recommended rules at [reporails/recommended](https://github.com/reporails/recommended).
+
+Want to add or improve rules? Please follow [Contribute](https://github.com/reporails/rules/blob/main/CONTRIBUTING.md) guide in the [Core repo](https://github.com/reporails/rules).
+
+## License
+
+Apache 2.0

reporails_cli-0.1.1/README.md

@@ -0,0 +1,141 @@
+# Reporails CLI
+
+Score your CLAUDE.md files. See what's missing. Improve your AI coding setup.
+[Why this exists](https://dev.to/cleverhoods/claudemd-lint-score-improve-repeat-2om5)
+
+## Quick Start
+
+### One-line install (npm)
+
+```bash
+npx @reporails/cli install
+```
+
+This registers the MCP server with Claude Code. Then ask Claude: `What ails claude?`
+
+### MCP Integration (manual)
+
+For full semantic analysis, add the MCP server:
+```bash
+# Add the MCP and restart Claude
+claude mcp add reporails -- uvx reporails-cli ails-mcp
+```
+
+Then ask Claude:
+```
+❯ What ails claude?
+```
+
+### CLI path (only deterministic rules)
+```bash
+# No install needed — run directly
+uvx reporails-cli check
+# or
+npx @reporails/cli check
+```
+
+That's it. You'll get a score, capability level, and actionable violations.
+```
+╔══════════════════════════════════════════════════════════════╗
+║   SCORE: 8.1 / 10 (partial)  |  CAPABILITY: Governed (L5)    ║
+║   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░         ║
+╚══════════════════════════════════════════════════════════════╝
+
+Violations:
+  CLAUDE.md (7 issues)
+    ○ MED C4.no-antipatterns :1    No NEVER or AVOID statements found
+    · LOW C12.no-version     :1    No version or date marker found
+    ...
+```
+
+Fix the issues, run again, watch your score and your experience improve.
+
+## Install
+
+```bash
+# Ephemeral (no install, always latest)
+uvx reporails-cli check
+npx @reporails/cli check
+
+# Persistent (adds `ails` to PATH)
+pip install reporails-cli
+# or
+npm install -g @reporails/cli
+```
+
+Once installed, all commands use `ails` directly.
+
+## What It Checks
+
+- **Structure** — File organization, size limits
+- **Content** — Clarity, completeness, anti-patterns
+- **Efficiency** — Token usage, context management
+- **Maintenance** — Versioning, review processes
+- **Governance** — Ownership, security policies
+
+## Capability Levels
+
+| Level | Name | What it means |
+|-------|------|---------------|
+| L1 | Absent | No instruction file |
+| L2 | Basic | Has CLAUDE.md |
+| L3 | Structured | Sections, imports |
+| L4 | Abstracted | .claude/rules/ directory |
+| L5 | Governed | Shared files, 3+ components |
+| L6 | Adaptive | Backbone + full governance |
+
+## Commands
+
+```bash
+ails check                      # Score your setup
+ails check -f json              # JSON output (for CI)
+ails check --strict             # Exit 1 if violations (for CI)
+ails check --with-recommended   # Include recommended rules
+ails explain S1                 # Explain a rule
+ails map                        # Show project structure
+ails map --save                 # Generate backbone.yml
+ails update                     # Update rules framework
+ails update --check             # Check for rule updates
+ails dismiss C6                 # Dismiss a semantic finding
+ails version                    # Show version info
+```
+
+## Updating
+
+The **rules framework** updates separately from the CLI:
+
+```bash
+ails update              # Update rules to latest
+ails update --check      # Check without installing
+```
+
+The **CLI itself** updates automatically with ephemeral runners (`uvx`, `npx`).
+Persistent installs: `pip install --upgrade reporails-cli` or `npm install -g @reporails/cli@latest`
+
+## Recommended Rules
+
+The `--with-recommended` flag adds community [recommended rules](https://github.com/reporails/recommended) on top of the core set. These are methodology-backed checks (AILS_ namespace) that are auto-downloaded on first use:
+
+```bash
+ails check --with-recommended       # Include recommended rules
+ails update --recommended              # Re-fetch latest recommended rules
+```
+
+## Prerequisites
+
+Depends on your install path:
+
+- **uvx/pip path**: [uv](https://docs.astral.sh/uv/) — no separate Python install needed
+- **npx/npm path**: Node.js >= 18 — uv is auto-installed if missing
+- **MCP install/uninstall**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+
+## Rules
+
+Core rules are maintained at [reporails/rules](https://github.com/reporails/rules).
+Recommended rules at [reporails/recommended](https://github.com/reporails/recommended).
+
+Want to add or improve rules? Please follow [Contribute](https://github.com/reporails/rules/blob/main/CONTRIBUTING.md) guide in the [Core repo](https://github.com/reporails/rules).
+
+## License
+
+Apache 2.0

reporails_cli-0.1.1/UNRELEASED.md

@@ -0,0 +1 @@
+# Unreleased

{reporails_cli-0.0.2 → reporails_cli-0.1.1}/docs/specs/arch.md

@@ -1,12 +1,10 @@
 # Architecture Overview
 
-> Version 0.1.0 | AI Instruction Linter
+> Version 0.1.1 | AI Instruction Validator
 
 ## Overview
 
-Reporails lints AI coding agent instruction files against community-maintained rules.
-
-**repoRAILS** = **Repo** **R**ecursive **AI** **L**inting**S**
+Reporails validates AI coding agent instruction files against community-maintained rules.
 
 | Purpose | Name |
 |---------|------|
@@ -288,7 +286,7 @@ Engine extracts content
 **Currently supported (v0.0.1):**
 - Claude: `CLAUDE.md`, `.claude/rules/*.md`
 
-**Discovery-ready (detection only, no linting rules yet):**
+**Discovery-ready (detection only, no validation rules yet):**
 
 | Agent | Instruction Files | Status |
 |-------|-------------------|--------|