@reporails/cli 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +68 -133
  2. package/bin/reporails.mjs +12 -15
  3. package/package.json +14 -6
package/README.md CHANGED
@@ -1,181 +1,116 @@
1
1
  # @reporails/cli
2
2
 
3
- Score your CLAUDE.md files. See what's missing. Improve your AI coding setup.
3
+ AI instruction diagnostics for coding agents. Validates instruction files for Claude, Codex, Copilot, Gemini, and Cursor against 90+ deterministic rules.
4
+
5
+ ### Beta — limited 100 spots, free until GA.
4
6
 
5
7
  ## Quick Start
6
8
 
7
9
  ```bash
8
- npx @reporails/cli setup
10
+ npx @reporails/cli check
9
11
  ```
10
12
 
11
- This detects agents in your project and writes the MCP config. Then ask Claude:
13
+ That's it. Score and actionable findings — no install, no account.
12
14
 
13
15
  ```
14
- > What ails claude?
15
- ```
16
+ Reporails — Diagnostics
16
17
 
17
- ### CLI path (only deterministic rules)
18
+ ┌─ Main (1)
19
+ │ CLAUDE.md 12 dir / 5 con · 60% prose
20
+ │ ⚠ L1 No NEVER or AVOID statements found CORE:C:0003
21
+ │ ○ L1 No version or date marker found CORE:C:0012
22
+ │
23
+ └─ 3 findings
18
24
 
19
- ```bash
20
- npx @reporails/cli check
21
- ```
25
+ ── Summary ──────────────────────────────────────────────
22
26
 
23
- That's it. You'll get a score, capability level, and actionable violations.
24
- ```
25
- ╔══════════════════════════════════════════════════════════════╗
26
- ║ SCORE: 8.1 / 10 (partial) | CAPABILITY: Maintained (L5) ║
27
- ║ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░ ║
28
- ╚══════════════════════════════════════════════════════════════╝
29
-
30
- Violations:
31
- CLAUDE.md (7 issues)
32
- ○ :1 No NEVER or AVOID statements found RRAILS:C:0003
33
- · :1 No version or date marker found CORE:C:0012
34
- ...
35
- ```
27
+ Score: 7.2 / 10 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░ (0.3s)
28
+ Agent: Claude
36
29
 
37
- Fix the issues, run again, watch your score and your experience improve.
30
+ 3 findings · 0 errors · 2 warnings · 1 info
31
+ ```
38
32
 
39
33
  ## Install
40
34
 
41
35
  ```bash
42
- # Ephemeral (no install, always latest)
36
+ # Zero install — always latest
43
37
  npx @reporails/cli check
44
38
 
45
- # Persistent (adds `ails` to PATH)
39
+ # Or install globally
46
40
  npm install -g @reporails/cli
47
41
  ```
48
42
 
49
- Once installed, all commands use `ails` directly.
43
+ Once installed globally, use `ails` directly:
44
+
45
+ ```bash
46
+ ails check
47
+ ails auth login # Unlock Pro diagnostics (GitHub sign-in)
48
+ ails check # Now with cross-file analysis + compliance scoring
49
+ ```
50
+
51
+ ## Supported Agents
52
+
53
+ | Agent | Instruction files |
54
+ |-------|-------------------|
55
+ | Claude | `CLAUDE.md`, `.claude/rules/*.md`, `.claude/skills/*/SKILL.md` |
56
+ | Codex | `AGENTS.md`, `CODEX.md`, `agents/*.md` |
57
+ | Copilot | `copilot-instructions.md`, `.github/copilot-instructions.md` |
58
+ | Gemini | `GEMINI.md`, `.gemini/rules/*.md` |
59
+ | Cursor | `.cursorrules`, `.cursor/rules/*.md` |
60
+
61
+ ## Commands
62
+
63
+ | Command | Description |
64
+ |---------|-------------|
65
+ | `check [PATH]` | Validate instruction files (90+ rules) |
66
+ | `explain RULE_ID` | Show rule details and fix guidance |
67
+ | `heal` | Interactive auto-fix for violations |
68
+ | `auth login` | Sign in with GitHub (Pro enrollment) |
69
+ | `auth status` | Check auth state |
70
+ | `auth logout` | Remove stored credentials |
71
+ | `install [PATH]` | Install MCP server for detected agents |
72
+ | `version` | Show version info |
50
73
 
51
74
  ## What It Checks
52
75
 
53
- - **Structure** — File organization, size limits
54
- - **Content** — Clarity, completeness, anti-patterns
55
- - **Efficiency** — Token usage, context management
56
- - **Maintenance** — Versioning, review processes
57
- - **Governance** — Ownership, security policies
76
+ 90+ rules across six categories:
58
77
 
59
- ## Capability Levels
78
+ - **Structure** — File organization, size limits, modularity, imports
79
+ - **Content** — Specificity, reinforcement, topic clustering, anti-patterns
80
+ - **Context Quality** — Tech stack, project description, domain terminology
81
+ - **Efficiency** — Token usage, import depth, elaboration
82
+ - **Maintenance** — Versioning, review processes
83
+ - **Governance** — Security policies, credential protection
60
84
 
61
- Capability levels describe what your AI instruction setup enables — not how "mature" it is. Different projects need different capabilities.
85
+ ## Unauthenticated vs Authenticated
62
86
 
63
- | Level | Name | What It Enables |
64
- |-------|------|-----------------|
65
- | L0 | Absent | No instruction file — nothing to evaluate |
66
- | L1 | Basic | Reviewed, tracked instruction file |
67
- | L2 | Scoped | Project-specific constraints, size control |
68
- | L3 | Structured | External references, multiple files |
69
- | L4 | Abstracted | Path-scoped rules, context-aware loading |
70
- | L5 | Maintained | Structural integrity, governance, navigation |
71
- | L6 | Adaptive | Dynamic context, extensibility, persistence |
87
+ | Feature | Unauthenticated | Authenticated |
88
+ |---------|-----------------|---------------|
89
+ | Mechanical rules | 70+ | 70+ |
90
+ | Deterministic rules | 20+ | 20+ |
91
+ | Cross-file analysis | — | Conflicts, repetition |
92
+ | Reinforcement detection | — | Orphan instructions, topic clustering |
93
+ | Compliance scoring | — | Per-instruction strength |
72
94
 
73
95
  ## GitHub Actions
74
96
 
75
- Add `ails check` as a CI gate with inline PR annotations:
76
-
77
97
  ```yaml
78
- # .github/workflows/reporails.yml
79
98
  name: Reporails
80
99
  on:
81
100
  pull_request:
82
- paths: ['CLAUDE.md', '.claude/**']
101
+ paths: ['CLAUDE.md', '.claude/**', 'AGENTS.md', '.cursorrules']
83
102
  jobs:
84
103
  check:
85
104
  runs-on: ubuntu-latest
86
105
  steps:
87
106
  - uses: actions/checkout@v4
88
- - uses: reporails/cli/action@v1
89
- with:
90
- min-score: '6.0'
107
+ - run: npx @reporails/cli check --format github --strict
91
108
  ```
92
109
 
93
- See the [main README](https://github.com/reporails/cli#github-actions) for full action inputs/outputs.
94
-
95
- ## Commands
96
-
97
- ```bash
98
- ails setup # Set up MCP server for detected agents
99
- ails check # Score your setup
100
- ails check -f json # JSON output (for CI)
101
- ails check -f github # GitHub Actions annotations
102
- ails check --strict # Exit 1 if violations (for CI)
103
- ails check --no-update-check # Skip pre-run update prompt
104
- ails check --exclude-dir vendor # Exclude directory from scanning
105
- ails check -v # Verbose: per-file PASS/FAIL with rule titles
106
- ails heal # Interactive auto-fix + semantic evaluation
107
- ails heal --non-interactive # JSON output for agents and scripts
108
- ails explain CORE:S:0001 # Explain a rule
109
- ails map # Show project structure
110
- ails map --save # Generate backbone.yml
111
- ails update # Update rules framework + recommended
112
- ails update --check # Check for updates without installing
113
- ails update --recommended # Update recommended rules only
114
- ails update --force # Force reinstall even if current
115
- ails update --cli # Upgrade the CLI package itself
116
- ails dismiss CORE:C:0001 # Dismiss a semantic finding
117
- ails judge . "RULE:FILE:pass:reason" # Cache semantic verdicts
118
- ails version # Show version info
119
- ```
120
-
121
- | Command | Description |
122
- |---------|-------------|
123
- | `setup [PATH]` | Set up MCP server for detected agents |
124
- | `check [PATH]` | Validate instruction files |
125
- | `heal [PATH]` | Interactive auto-fix + semantic evaluation |
126
- | `explain RULE_ID` | Show rule details |
127
- | `map [PATH]` | Discover project structure |
128
- | `update` | Update rules framework + recommended |
129
- | `dismiss RULE_ID` | Dismiss a semantic finding |
130
- | `judge PATH VERDICTS` | Cache semantic verdicts |
131
- | `version` | Show version info |
132
-
133
- ## Updating
134
-
135
- ```bash
136
- ails update # Update rules framework + recommended to latest
137
- ails update --check # Check for updates without installing
138
- ails update --recommended # Update recommended rules only
139
- ails update --force # Force reinstall even if current
140
- ails update --cli # Upgrade the CLI package itself
141
- ```
142
-
143
- Before each scan, the CLI prompts when updates are available. Use `--no-update-check` to skip.
144
-
145
- The **CLI itself** updates automatically — `npx @reporails/cli` always fetches the latest version.
146
- Persistent installs: `npm install -g @reporails/cli@latest`
147
-
148
- ## Recommended Rules
149
-
150
- [Recommended rules](https://github.com/reporails/recommended) (AILS_ namespace) are included by default and auto-downloaded on first run. To opt out, add to your `.reporails/config.yml`:
151
-
152
- ```yaml
153
- recommended: false
154
- ```
155
-
156
- To update recommended rules independently:
157
-
158
- ```bash
159
- ails update --recommended
160
- ```
161
-
162
- ## Prerequisites
163
-
164
- - **Node.js >= 18**
165
- - **uv** — auto-installed if missing ([manual install](https://docs.astral.sh/uv/))
166
- - **No additional dependencies** — `setup` writes config files directly
167
-
168
110
  ## How It Works
169
111
 
170
- This is a thin Node.js wrapper around the [reporails-cli](https://pypi.org/project/reporails-cli/) Python package. Commands are proxied via `uvx` — no Python installation required.
171
-
172
- ## Rules
173
-
174
- Core rules are maintained at [reporails/rules](https://github.com/reporails/rules).
175
- Recommended rules at [reporails/recommended](https://github.com/reporails/recommended).
176
-
177
- 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).
112
+ Thin Node.js wrapper around the [reporails-cli](https://pypi.org/project/reporails-cli/) Python package. Commands are proxied via `uvx` — no Python install required. Node.js >= 18 needed. `uv` is auto-installed if missing.
178
113
 
179
114
  ## License
180
115
 
181
- BUSL 1.1
116
+ [BUSL 1.1](https://github.com/reporails/cli/blob/main/LICENSE) — converts to Apache 2.0 three years after each release.
package/bin/reporails.mjs CHANGED
@@ -8,26 +8,23 @@ const PYPI_PACKAGE = "reporails-cli";
8
8
  const CLI_COMMAND = "ails";
9
9
 
10
10
  const HELP = `
11
- reporails — Score your CLAUDE.md files
11
+ ails — Validate and score AI instruction files
12
12
 
13
13
  Usage:
14
- reporails setup [PATH] Set up MCP server for detected agents
15
- reporails check [PATH] [OPTIONS] Validate instruction files
16
- reporails explain RULE_ID Show rule details
17
- reporails map [PATH] [--save] Discover project structure
18
- reporails update Update rules framework + recommended
19
- reporails update --check Check for updates without installing
20
- reporails update --recommended Update recommended rules only
21
- reporails update --cli Upgrade CLI package itself
22
- reporails dismiss RULE_ID Dismiss a semantic finding
23
- reporails version Show version info
24
- reporails <command> [args...] Proxy any command to ails CLI
14
+ ails check [PATH] [OPTIONS] Validate instruction files
15
+ ails explain RULE_ID Show rule details
16
+ ails install [PATH] Install MCP server for detected agents
17
+ ails update Update rules framework
18
+ ails update --cli Upgrade CLI package itself
19
+ ails version Show version info
25
20
 
26
21
  Examples:
27
- npx @reporails/cli setup # Set up MCP server
28
- npx @reporails/cli check # Score your setup
22
+ npx @reporails/cli check # Validate your setup
23
+ npx @reporails/cli install # Install MCP server
29
24
  npx @reporails/cli explain CORE:S:0001 # Explain a rule
30
- npx @reporails/cli update # Update rules + recommended
25
+
26
+ Aliases:
27
+ ails, reporails — both work after global install
31
28
 
32
29
  Prerequisites:
33
30
  Node.js >= 18 (uv is auto-installed if missing)
package/package.json CHANGED
@@ -1,9 +1,10 @@
1
1
  {
2
2
  "name": "@reporails/cli",
3
- "version": "0.3.0",
4
- "description": "Score your CLAUDE.md files. See what's missing. Improve your AI coding setup.",
3
+ "version": "0.5.0",
4
+ "description": "AI instruction diagnostics for coding agents",
5
5
  "type": "module",
6
6
  "bin": {
7
+ "ails": "bin/reporails.mjs",
7
8
  "reporails": "bin/reporails.mjs"
8
9
  },
9
10
  "engines": {
@@ -14,17 +15,24 @@
14
15
  "README.md"
15
16
  ],
16
17
  "keywords": [
18
+ "ai-instructions",
17
19
  "claude",
18
- "claude-code",
19
- "mcp",
20
+ "codex",
21
+ "copilot",
22
+ "cursor",
23
+ "gemini",
24
+ "diagnostics",
20
25
  "validation",
21
- "ai-instructions",
22
- "claude-md"
26
+ "mcp"
23
27
  ],
24
28
  "repository": {
25
29
  "type": "git",
26
30
  "url": "https://github.com/reporails/cli"
27
31
  },
32
+ "homepage": "https://reporails.com",
33
+ "bugs": {
34
+ "url": "https://github.com/reporails/cli/issues"
35
+ },
28
36
  "license": "BUSL-1.1",
29
37
  "author": "Reporails"
30
38
  }