ironprose 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # ironprose-cli
 
+## 0.4.0
+
+### Minor Changes
+
+- 7377bad: Add --genre and --locale flags to analyze subcommand
+- 9f038b4: feat: add insights subcommand (closes #28)
+
+### Patch Changes
+
+- af5822e: Added `insights` and `export` to the CLI's schema mapping so agents can introspect the endpoints.
+- 0d1e061: Deduplicate diagnostics in compare introduced/fixed arrays
+- d12ecf7: Add --output flag to list-rules subcommand
+- ca5abbd: Document --output text stream split and fix 0-indexed line numbers
+- 99fd4c0: Remove non-existent export endpoint from schema error message
+
+## 0.3.1
+
+### Patch Changes
+
+- d947aa0: docs: wrap long CLI command examples in README and SKILL.md to prevent horizontal overflow on npmjs.com
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -56,38 +56,112 @@ npx ironprose analyze "The dark night was very dark and she felt scared."
 npx ironprose --help
 
 # macOS/Linux
-curl --proto '=https' --tlsv1.2 -LsSf https://github.com/benchcutlogic/ironprose-cli/releases/latest/download/ironprose-cli-installer.sh | sh
+curl --proto '=https' --tlsv1.2 -LsSf \
+  https://github.com/benchcutlogic/ironprose-cli/releases/latest/download/ironprose-cli-installer.sh | sh
+
+# Agent skills (for AI coding agents)
+npx skills install benchcutlogic/ironprose-cli
 ```
 
 ## Usage
 
 ```bash
-# Analyze a file
-ironprose analyze --file chapter-01.md
+# Analyze text (JSON output — agents should always use this)
+ironprose analyze --file chapter-01.md --output json
+cat draft.md | ironprose analyze --output json
 
-# Pipe from stdin
-cat draft.md | ironprose analyze
+# Scores only — minimizes output tokens
+ironprose analyze --file draft.md --output json --score-only
 
-# Human-readable output
-ironprose analyze --file draft.md --output text
+# Raw JSON passthrough — zero translation loss
+ironprose analyze \
+  --json '{"text":"The dark night was very dark."}' \
+  --output json
+
+# Schema introspection — discover endpoints at runtime
+ironprose schema analyze
+ironprose schema rate
 
-# Filter by rule or severity
-ironprose analyze --file draft.md --rules passive_voice,repetition
-ironprose analyze --file draft.md --severity-min warning
+# Rate diagnostics — closes the feedback loop
+ironprose rate \
+  --json '{"rule":"repetition","rating":"false_positive","diagnostic_id":"d-001"}'
 
 # Compare revisions
-ironprose compare --original-file v1.md --revised-file v2.md
+ironprose compare --original-file v1.md --revised-file v2.md --output json
 
 # List all rules
-ironprose list-rules
+ironprose list-rules --output json
 
-# Inspect API schema
-ironprose schema analyze
+# Human-readable output
+ironprose analyze --file draft.md --output text
+ironprose rate --rule repetition --rating helpful --diagnostic-id d-001
+
+# Aggregate feedback insights (requires API key)
+ironprose insights
+ironprose insights --since 2024-01-01 --until 2024-12-31
+ironprose insights --genre fiction
+ironprose insights --work-id my-novel --since 2024-06-01
+```
+
+## Insights
+
+The `insights` subcommand returns aggregate feedback data per analyzer rule — counts of `helpful`, `not_helpful`, and `false_positive` ratings plus a precision proxy. Requires an API key.
+
+```bash
+# All-time insights
+ironprose insights
+
+# Filter by date range
+ironprose insights --since 2024-01-01 --until 2024-12-31
+
+# Filter by genre (prefix match)
+ironprose insights --genre fiction
+
+# Filter by work identifier
+ironprose insights --work-id my-novel
+```
+
+```json
+{
+  "rules": [
+    {
+      "rule": "repetition",
+      "helpful": 42,
+      "not_helpful": 3,
+      "false_positive": 1,
+      "precision_proxy": 0.91
+    }
+  ]
+}
+```
+
+### `--output text` stream split
+
+When `--output text` is used, the two output streams are **intentionally separate**:
 
-# Rate a diagnostic (closes the feedback loop)
-ironprose rate --rule repetition --rating false_positive --diagnostic-id d-001
+| Stream   | Content                               |
+| -------- | ------------------------------------- |
+| `stderr` | Diagnostics (one per line)            |
+| `stdout` | Score JSON                            |
+
+To capture **both** in a single file or variable, merge stderr into stdout:
+
+```bash
+ironprose analyze --file draft.md --output text 2>&1
 ```
 
+To capture them separately:
+
+```bash
+ironprose analyze --file draft.md --output text \
+  > score.json \
+  2> diagnostics.txt
+```
+
+### Line numbers
+
+Diagnostics include `start_line` / `end_line` fields that come from the API in **0-indexed** form (line 1 of the file = `0`). The `--output text` renderer converts these to **1-indexed** line numbers for human display (`L1`, `L2`, …). Raw `--output json` output preserves the 0-indexed values as returned by the API.
+
 ## Configuration
 
 | Variable            | Description                      | Default                     |

package/npm-shrinkwrap.json

@@ -23,7 +23,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "ironprose",
-      "version": "0.3.0"
+      "version": "0.4.0"
     },
     "node_modules/@isaacs/cliui": {
       "engines": {
@@ -542,5 +542,5 @@
     }
   },
   "requires": true,
-  "version": "0.3.0"
+  "version": "0.4.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/benchcutlogic/ironprose-cli/releases/download/v0.3.0"
+    "https://github.com/benchcutlogic/ironprose-cli/releases/download/v0.4.0"
   ],
   "bin": {
     "ironprose": "run-ironprose.js"
@@ -112,7 +112,7 @@
       "zipExt": ".tar.gz"
     }
   },
-  "version": "0.3.0",
+  "version": "0.4.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"