@reporails/cli 0.4.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 -116
  2. package/bin/reporails.mjs +12 -15
  3. package/package.json +14 -6
package/README.md CHANGED
@@ -1,164 +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 install
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 (awaiting semantic) | 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
- | Command | Description |
98
- |---------|-------------|
99
- | `install [PATH]` | Install MCP server for detected agents |
100
- | `check [PATH]` | Validate instruction files |
101
- | `heal [PATH]` | Interactive auto-fix + semantic evaluation |
102
- | `explain RULE_ID` | Show rule details |
103
- | `map [PATH]` | Discover project structure |
104
- | `update` | Update rules framework + recommended |
105
- | `config set KEY VALUE` | Set a project config value |
106
- | `config set --global KEY VALUE` | Set a global default |
107
- | `config get KEY` | Show a config value |
108
- | `config list` | Show all config (project + global) |
109
- | `dismiss RULE_ID` | Dismiss a semantic finding |
110
- | `judge PATH VERDICTS` | Cache semantic verdicts |
111
- | `version` | Show version info |
112
-
113
- See the [main README](https://github.com/reporails/cli#commands) for full flag reference.
114
-
115
- ## Updating
116
-
117
- ```bash
118
- ails update # Update rules framework + recommended to latest
119
- ails update --check # Check for updates without installing
120
- ails update --recommended # Update recommended rules only
121
- ails update --force # Force reinstall even if current
122
- ails update --cli # Upgrade the CLI package itself
123
- ```
124
-
125
- Before each scan, the CLI prompts when updates are available. Use `--no-update-check` to skip.
126
-
127
- The **CLI itself** updates automatically — `npx @reporails/cli` always fetches the latest version.
128
- Persistent installs: `npm install -g @reporails/cli@latest`
129
-
130
- ## Recommended Rules
131
-
132
- [Recommended rules](https://github.com/reporails/recommended) (AILS_ namespace) are included by default and auto-downloaded on first run. To opt out:
133
-
134
- ```bash
135
- ails config set recommended false # This project only
136
- ails config set --global recommended false # All projects
137
- ```
138
-
139
- To update recommended rules independently:
140
-
141
- ```bash
142
- ails update --recommended
143
- ```
144
-
145
- ## Prerequisites
146
-
147
- - **Node.js >= 18**
148
- - **uv** — auto-installed if missing ([manual install](https://docs.astral.sh/uv/))
149
- - **No additional dependencies** — `install` writes config files directly
150
-
151
110
  ## How It Works
152
111
 
153
- 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.
154
-
155
- ## Rules
156
-
157
- Core rules are maintained at [reporails/rules](https://github.com/reporails/rules).
158
- Recommended rules at [reporails/recommended](https://github.com/reporails/recommended).
159
-
160
- 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.
161
113
 
162
114
  ## License
163
115
 
164
- BUSL 1.1 — converts to Apache 2.0 on 2029-02-20 or at 1.0, whichever comes first.
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 install [PATH] Install 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 install # Install 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.4.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
  }