@reporails/cli 0.1.0 → 0.1.2

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 +93 -12
  2. package/bin/reporails.mjs +6 -1
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -2,45 +2,119 @@
2
2
 
3
3
  Score your CLAUDE.md files. See what's missing. Improve your AI coding setup.
4
4
 
5
- ## Install MCP Server (Claude Code)
5
+ ## Quick Start
6
6
 
7
7
  ```bash
8
8
  npx @reporails/cli install
9
9
  ```
10
10
 
11
- This registers the reporails MCP server with Claude Code. Then ask Claude:
11
+ This registers the MCP server with Claude Code. Then ask Claude:
12
12
 
13
13
  ```
14
14
  > What ails claude?
15
15
  ```
16
16
 
17
- ## CLI Usage
17
+ ### CLI path (only deterministic rules)
18
18
 
19
19
  ```bash
20
- # Score your setup
21
- npx @reporails/cli check .
20
+ npx @reporails/cli check
21
+ ```
22
+
23
+ That's it. You'll get a score, capability level, and actionable violations.
24
+ ```
25
+ ╔══════════════════════════════════════════════════════════════╗
26
+ ║ SCORE: 8.1 / 10 (partial) | CAPABILITY: Governed (L5) ║
27
+ ║ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░ ║
28
+ ╚══════════════════════════════════════════════════════════════╝
29
+
30
+ Violations:
31
+ CLAUDE.md (7 issues)
32
+ ○ MED C4.no-antipatterns :1 No NEVER or AVOID statements found
33
+ · LOW C12.no-version :1 No version or date marker found
34
+ ...
35
+ ```
22
36
 
23
- # JSON output (for CI)
24
- npx @reporails/cli check . -f json
37
+ Fix the issues, run again, watch your score and your experience improve.
25
38
 
26
- # Explain a rule
27
- npx @reporails/cli explain S1
39
+ ## Install
28
40
 
29
- # Show project structure
30
- npx @reporails/cli map .
41
+ ```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
31
47
  ```
32
48
 
49
+ Once installed, all commands use `ails` directly.
50
+
51
+ ## What It Checks
52
+
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
58
+
59
+ ## Capability Levels
60
+
61
+ | Level | Name | What it means |
62
+ |-------|------|---------------|
63
+ | L1 | Absent | No instruction file |
64
+ | L2 | Basic | Has CLAUDE.md |
65
+ | L3 | Structured | Sections, imports |
66
+ | L4 | Abstracted | .claude/rules/ directory |
67
+ | L5 | Governed | Shared files, 3+ components |
68
+ | L6 | Adaptive | Backbone + full governance |
69
+
33
70
  ## Commands
34
71
 
72
+ ```bash
73
+ ails check # Score your setup
74
+ ails check -f json # JSON output (for CI)
75
+ ails check --strict # Exit 1 if violations (for CI)
76
+ ails check --with-recommended # Include recommended rules
77
+ ails explain S1 # Explain a rule
78
+ ails map # Show project structure
79
+ ails map --save # Generate backbone.yml
80
+ ails update # Update rules framework
81
+ ails update --check # Check for rule updates
82
+ ails dismiss C6 # Dismiss a semantic finding
83
+ ails version # Show version info
84
+ ```
85
+
35
86
  | Command | Description |
36
87
  |---------|-------------|
37
88
  | `install [--scope user\|project]` | Register MCP server with Claude Code |
38
89
  | `uninstall [--scope user\|project]` | Remove MCP server from Claude Code |
39
90
  | `check [PATH]` | Validate instruction files |
40
- | `map [PATH]` | Discover project structure |
41
91
  | `explain RULE_ID` | Show rule details |
92
+ | `map [PATH]` | Discover project structure |
93
+ | `update` | Update rules framework |
94
+ | `dismiss RULE_ID` | Dismiss a semantic finding |
42
95
  | `version` | Show version info |
43
96
 
97
+ ## Updating
98
+
99
+ The **rules framework** updates separately from the CLI:
100
+
101
+ ```bash
102
+ ails update # Update rules to latest
103
+ ails update --check # Check without installing
104
+ ```
105
+
106
+ The **CLI itself** updates automatically — `npx @reporails/cli` always fetches the latest version.
107
+ Persistent installs: `npm install -g @reporails/cli@latest`
108
+
109
+ ## Recommended Rules
110
+
111
+ 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:
112
+
113
+ ```bash
114
+ ails check --with-recommended # Include recommended rules
115
+ ails update --recommended # Re-fetch latest recommended rules
116
+ ```
117
+
44
118
  ## Prerequisites
45
119
 
46
120
  - **Node.js >= 18**
@@ -51,6 +125,13 @@ npx @reporails/cli map .
51
125
 
52
126
  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.
53
127
 
128
+ ## Rules
129
+
130
+ Core rules are maintained at [reporails/rules](https://github.com/reporails/rules).
131
+ Recommended rules at [reporails/recommended](https://github.com/reporails/recommended).
132
+
133
+ 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).
134
+
54
135
  ## License
55
136
 
56
137
  Apache-2.0
package/bin/reporails.mjs CHANGED
@@ -15,12 +15,17 @@ Usage:
15
15
  reporails install [--scope user|project] Register MCP server with Claude Code
16
16
  reporails uninstall [--scope user|project] Remove MCP server from Claude Code
17
17
  reporails check [PATH] [OPTIONS] Validate instruction files
18
+ reporails explain RULE_ID Show rule details
19
+ reporails update Update rules framework
20
+ reporails dismiss RULE_ID Dismiss a semantic finding
21
+ reporails version Show version info
18
22
  reporails <command> [args...] Proxy any command to ails CLI
19
23
 
20
24
  Examples:
21
25
  npx @reporails/cli install # Add MCP server (user scope)
22
- npx @reporails/cli check . # Score your setup
26
+ npx @reporails/cli check # Score your setup
23
27
  npx @reporails/cli explain S1 # Explain a rule
28
+ npx @reporails/cli update # Update rules
24
29
 
25
30
  Prerequisites:
26
31
  Node.js >= 18 (uv is auto-installed if missing)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@reporails/cli",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Score your CLAUDE.md files. See what's missing. Improve your AI coding setup.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -17,7 +17,7 @@
17
17
  "claude",
18
18
  "claude-code",
19
19
  "mcp",
20
- "linter",
20
+ "validation",
21
21
  "ai-instructions",
22
22
  "claude-md"
23
23
  ],