@reporails/cli 0.4.0 → 0.5.1

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 +65 -117
  2. package/bin/reporails.mjs +12 -15
  3. package/package.json +14 -6
package/README.md CHANGED
@@ -1,164 +1,112 @@
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 the entire agentic instruction system against 90+ rules.
4
+
5
+ ### Beta — first 100 users free.
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
+ No install, no account. Actionable findings in seconds:
12
14
 
13
15
  ```
14
- > What ails claude?
16
+ Reporails — Diagnostics
17
+
18
+ ┌─ Main (1)
19
+ │ CLAUDE.md 4 dir / 3 con · 73% prose
20
+ │ ⚠ Missing tech stack declaration CORE:C:0034
21
+ │ ⚠ Missing testing documentation CORE:C:0005
22
+ │ 2 brief · 2 orphan
23
+ │
24
+ └─ 10 findings
25
+
26
+ Score: 7.4 / 10 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░ (1.2s)
27
+ 10 findings · 8 warnings · 2 info
28
+ Compliance: HIGH
15
29
  ```
16
30
 
17
- ### CLI path (only deterministic rules)
31
+ ## Install
18
32
 
19
33
  ```bash
34
+ # Zero install — always latest
20
35
  npx @reporails/cli check
21
- ```
22
36
 
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
- ...
37
+ # Or install globally
38
+ npm install -g @reporails/cli
35
39
  ```
36
40
 
37
- Fix the issues, run again, watch your score and your experience improve.
38
-
39
- ## Install
41
+ Once installed globally, use `ails` directly:
40
42
 
41
43
  ```bash
42
- # Ephemeral (no install, always latest)
43
- npx @reporails/cli check
44
-
45
- # Persistent (adds `ails` to PATH)
46
- npm install -g @reporails/cli
44
+ ails check
45
+ ails auth login # Unlock full diagnostics (GitHub sign-in)
46
+ ails check # Now with cross-file analysis + compliance scoring
47
47
  ```
48
48
 
49
- Once installed, all commands use `ails` directly.
49
+ ## Supported Agents
50
+
51
+ | Agent | Instruction files |
52
+ |---------|-----------------------------------------------------------|
53
+ | Claude | `CLAUDE.md`, `.claude/rules/*.md`, `.claude/skills/*/SKILL.md` |
54
+ | Codex | `AGENTS.md`, `CODEX.md`, `agents/*.md` |
55
+ | Copilot | `.github/copilot-instructions.md` |
56
+ | Gemini | `GEMINI.md`, `.gemini/rules/*.md` |
57
+ | Cursor | `.cursorrules`, `.cursor/rules/*.md` |
58
+
59
+ ## Commands
60
+
61
+ | Command | Description |
62
+ |----------------------|--------------------------------------------|
63
+ | `check [PATH]` | Validate instruction files (90+ rules) |
64
+ | `explain RULE_ID` | Show rule details and fix guidance |
65
+ | `heal` | Auto-fix common violations |
66
+ | `auth login` | Sign in with GitHub |
67
+ | `auth status` | Check auth state |
68
+ | `auth logout` | Remove stored credentials |
69
+ | `install [PATH]` | Install MCP server for detected agents |
70
+ | `version` | Show version info |
50
71
 
51
72
  ## What It Checks
52
73
 
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
74
+ 90+ rules across five categories:
58
75
 
59
- ## Capability Levels
76
+ - **Structure** — File organization, size limits, modularity
77
+ - **Content** — Specificity, reinforcement, tech stack, domain terminology
78
+ - **Efficiency** — Token usage, elaboration, formatting
79
+ - **Maintenance** — Versioning, review processes
80
+ - **Governance** — Security policies, credential protection
60
81
 
61
- Capability levels describe what your AI instruction setup enables — not how "mature" it is. Different projects need different capabilities.
82
+ ## Offline vs Authenticated
62
83
 
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 |
84
+ | Feature | Offline | Authenticated |
85
+ |----------------------|-------------|------------------------------|
86
+ | Mechanical checks | 70+ rules | 70+ rules |
87
+ | Content checks | 25+ rules | 25+ rules |
88
+ | Cross-file analysis | — | Conflicts, repetition |
89
+ | Compliance scoring | — | Per-instruction strength |
72
90
 
73
91
  ## GitHub Actions
74
92
 
75
- Add `ails check` as a CI gate with inline PR annotations:
76
-
77
93
  ```yaml
78
- # .github/workflows/reporails.yml
79
94
  name: Reporails
80
95
  on:
81
96
  pull_request:
82
- paths: ['CLAUDE.md', '.claude/**']
97
+ paths: ['CLAUDE.md', '.claude/**', 'AGENTS.md', '.cursorrules']
83
98
  jobs:
84
99
  check:
85
100
  runs-on: ubuntu-latest
86
101
  steps:
87
102
  - uses: actions/checkout@v4
88
- - uses: reporails/cli/action@v1
89
- with:
90
- min-score: '6.0'
103
+ - run: npx @reporails/cli check --format github --strict
91
104
  ```
92
105
 
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
106
  ## How It Works
152
107
 
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).
108
+ Thin Node.js wrapper around [reporails-cli](https://pypi.org/project/reporails-cli/). Commands proxied via `uvx` — no Python install required. Node.js >= 18 needed. `uv` auto-installed if missing.
161
109
 
162
110
  ## License
163
111
 
164
- BUSL 1.1 — converts to Apache 2.0 on 2029-02-20 or at 1.0, whichever comes first.
112
+ [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.1",
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
  }