content-grade 1.0.6 → 1.0.8

package/README.md

@@ -31,12 +31,40 @@ npx content-grade headline "Why Most Startups Fail at Month 18"
 
 **Free tier:** 50 analyses/day. No signup. `npx content-grade grade README.md` works immediately.
 
+**Install globally** (recommended — skips the `npx` download on every run):
+
+```bash
+npm install -g content-grade
+content-grade --help
+```
+
 ```bash
 # More commands
-npx content-grade https://yourblog.com/post    # analyze any URL
-npx content-grade analyze ./post.md --json     # raw JSON for CI pipelines
-npx content-grade analyze ./post.md --quiet    # score number only (for scripts)
-npx content-grade activate                     # unlock Pro: batch mode, 100/day
+content-grade https://yourblog.com/post    # analyze any URL
+content-grade analyze ./post.md --json     # raw JSON for CI pipelines
+content-grade analyze ./post.md --quiet    # score number only (for scripts)
+content-grade activate                     # unlock Pro: batch mode, 100/day
+```
+
+---
+
+## Usage Examples
+
+**Grade a single file:**
+```bash
+npx content-grade article.md
+```
+
+**Grade multiple files with a glob pattern:**
+```bash
+npx content-grade 'blog/**/*.md'
+```
+
+**JSON output for CI integration:**
+```bash
+npx content-grade README.md --format json
+# Returns structured JSON with score, grade, dimensions, and improvements
+# Exit code 1 if score < 50 — useful for blocking low-quality merges
 ```
 
 ---
@@ -107,6 +135,7 @@ npx content-grade activate                     # unlock Pro: batch mode, 100/day
 | `init` | First-run setup: verify Claude CLI, run smoke test |
 | `start` | Launch the full web dashboard (6 tools) |
 | `telemetry [on\|off]` | View or toggle anonymous usage tracking |
+| `check-updates` | Check if a newer version is available on npm |
 | `help` | Full usage and examples |
 
 **Flags:**
@@ -116,6 +145,7 @@ npx content-grade activate                     # unlock Pro: batch mode, 100/day
 | `--json` | Raw JSON output — pipe to `jq` for CI integration |
 | `--quiet` | Score number only — for shell scripts |
 | `--version` | Print version |
+| `--verbose` | Show debug info (model, timing, Claude response length) |
 | `--no-telemetry` | Skip usage tracking for this run |
 
 **Global flags:**
@@ -141,7 +171,20 @@ Launch with `content-grade start` — opens at [http://localhost:4000](http://lo
 | **EmailForge** | `/email-forge` | Subject line + body copy for click-through optimization |
 | **AudienceDecoder** | `/audience` | Twitter handle → audience archetypes and content patterns |
 
-Free tier: **50 analyses/day per tool**. Pro ($19/mo): **100 analyses/day** + all tools.
+Free tier: **50 analyses/day per tool**. Pro ($9/mo): **100 analyses/day** + all tools.
+
+---
+
+## Join the Discussion
+
+**[GitHub Discussions](https://github.com/Content-Grade/Content-Grade/discussions)** — ask questions, share setups, vote on what gets built next.
+
+Active threads:
+- [What content quality checks matter most to you?](https://github.com/Content-Grade/Content-Grade/discussions/1) — General
+- [Show your ContentGrade setup — configs, workflows, CI integrations](https://github.com/Content-Grade/Content-Grade/discussions/2) — Show & Tell
+- [Feature requests & roadmap input](https://github.com/Content-Grade/Content-Grade/discussions/3) — Ideas
+- [Content scoring in CI — who is actually doing this?](https://github.com/Content-Grade/Content-Grade/discussions/4) — General
+- [What integrations would make ContentGrade essential to your workflow?](https://github.com/Content-Grade/Content-Grade/discussions/5) — Ideas
 
 ---
 
@@ -160,6 +203,112 @@ If this fails, run `npx content-grade init` for step-by-step diagnostics.
 
 ---
 
+---
+
+## Troubleshooting
+
+### `Error: Claude CLI not found`
+
+ContentGrade requires Claude CLI. Install it:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+```
+
+Then verify it works:
+
+```bash
+claude -p "say hi"
+```
+
+If Claude is installed but not on your PATH, set `CLAUDE_PATH`:
+
+```bash
+CLAUDE_PATH=/path/to/claude content-grade analyze ./post.md
+```
+
+Or add it permanently to your shell profile:
+
+```bash
+export CLAUDE_PATH=/path/to/claude
+```
+
+---
+
+### Analysis times out or hangs
+
+Claude CLI calls can take 10–60 seconds on first run. If it hangs beyond 2 minutes:
+
+1. Test Claude directly: `claude -p "say hi"` — if this hangs too, Claude CLI is the issue
+2. Check your internet connection (Claude CLI phones home on first use)
+3. Run `content-grade init` for a guided diagnostic
+
+---
+
+### `Could not parse response as JSON`
+
+This means Claude returned a non-JSON response. Common causes:
+
+- Claude CLI rate-limited your account (try again in a few minutes)
+- The file content was too short or unrecognizable as text content
+- Claude returned an error message instead of scoring output
+
+Run with `--verbose` to see the raw response:
+
+```bash
+content-grade analyze ./post.md --verbose
+```
+
+---
+
+### Daily limit reached
+
+Free tier: 50 CLI analyses/day, resets at midnight UTC.
+
+```
+✗ Daily limit reached (50/50 free checks used today).
+```
+
+Options:
+- Wait until midnight UTC for the limit to reset
+- Unlock 100/day with Pro: `content-grade activate`
+
+---
+
+### `content-grade: command not found` after global install
+
+If `npm install -g content-grade` succeeded but the command isn't found:
+
+```bash
+# Find where npm puts global binaries
+npm bin -g
+
+# Add to PATH — for bash/zsh, add this to ~/.bashrc or ~/.zshrc:
+export PATH="$(npm bin -g):$PATH"
+```
+
+---
+
+### `activate` says "Could not reach server"
+
+The activation server may be temporarily unreachable. The key is stored locally without online verification — this is normal and your Pro access will still work for CLI tools. Re-run `content-grade activate` to re-verify once the server is back.
+
+---
+
+### Something else is broken
+
+Run the built-in diagnostic:
+
+```bash
+content-grade init
+```
+
+This checks: Claude CLI on PATH, live smoke test, production build status. It will tell you exactly what's wrong.
+
+Still stuck? Open an issue: [github.com/Content-Grade/Content-Grade/issues](https://github.com/Content-Grade/Content-Grade/issues)
+
+
 ## CLI reference
 
 ### `analyze` / `check`
@@ -291,6 +440,53 @@ Scans up to 2 directory levels deep for `.md`, `.txt`, and `.mdx` files. Picks t
 
 ---
 
+---
+
+### `check-updates`
+
+```bash
+content-grade check-updates
+```
+
+Checks npm for the latest published version of `content-grade` and compares it against the installed version. If an update is available, prints the upgrade command.
+
+```bash
+  ⚠  Update available: v1.0.4  →  v1.0.5
+  Update with:
+    npm install -g content-grade    (global install)
+    npm install content-grade@latest (local install)
+```
+
+---
+
+### `activate`
+
+```bash
+content-grade activate
+content-grade activate <your-license-key>
+```
+
+Unlocks Pro features by storing your license key locally. Can be run interactively (prompts for the key) or non-interactively by passing the key as an argument — useful for automated setups:
+
+```bash
+# Interactive
+content-grade activate
+
+# Non-interactive (CI/CD or scripted setup)
+CONTENT_GRADE_KEY=your-key-here content-grade analyze ./post.md
+```
+
+The key is validated against the server and saved to `~/.config/content-grade/config.json`. If the server is unreachable (corporate proxy, offline), the key is stored locally anyway with a warning.
+
+**Pro unlocks:**
+- 100 analyses/day (vs 50 free)
+- `content-grade batch <dir>` — analyze entire directories at once
+- A/B headline comparison (web dashboard)
+- Landing page URL audit, ad copy scoring, email optimizer
+
+Get a license: [content-grade.github.io/Content-Grade/](https://content-grade.github.io/Content-Grade/)
+
+
 ## Configuration
 
 All configuration is through environment variables — no config file needed.
@@ -716,7 +912,7 @@ echo "$DATE,$HEADLINE,$SCORE" >> headline-scores.csv
 
 | | Free | Pro |
 |-|------|-----|
-| Price | Free forever | $19/month |
+| Price | Free forever | $9/month |
 | Analyses/day (CLI) | Unlimited | Unlimited |
 | Analyses/day (web dashboard, per tool) | 3 | 100 |
 | HeadlineGrader (single grade) | ✓ | ✓ |
@@ -761,7 +957,7 @@ ContentGrade is built in public. The community is the roadmap.
 
 **[EARLY_ADOPTERS.md](EARLY_ADOPTERS.md)** — The first 50 users who install and share feedback get:
 
-- **Pro tier free for 12 months** ($19/mo value)
+- **Pro tier free for 12 months** ($9/mo value)
 - Direct feedback channel with the maintainer
 - Name in CONTRIBUTORS.md (permanent)
 - Roadmap preview + design input before features ship

package/bin/content-grade.js

@@ -90,6 +90,17 @@ const MG = '\x1b[35m';
 const BL = '\x1b[34m';
 const WH = '\x1b[97m';
 
+// ── Input sanitization ────────────────────────────────────────────────────────
+
+// Reject null bytes (path traversal vector) and trim surrounding whitespace.
+// Returns sanitized string, or null if the input is invalid.
+function sanitizeFilePath(p) {
+  if (typeof p !== 'string') return null;
+  if (p.includes('\0')) return null;
+  const trimmed = p.trim();
+  return trimmed || null;
+}
+
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
 function ok(msg)   { console.log(`  ${GN}✓${R} ${msg}`); }
@@ -257,6 +268,15 @@ async function cmdAnalyze(filePath) {
     process.exit(2);
   }
 
+  const safeFilePath = sanitizeFilePath(filePath);
+  if (!safeFilePath) {
+    blank();
+    fail(`Invalid file path.`);
+    blank();
+    process.exit(2);
+  }
+  filePath = safeFilePath;
+
   const absPath = resolve(process.cwd(), filePath);
   if (!existsSync(absPath)) {
     blank();
@@ -320,7 +340,7 @@ async function cmdAnalyze(filePath) {
     console.log(`  ${D}· Wait until tomorrow (limit resets at midnight)${R}`);
     console.log(`  ${D}· Unlock 100 checks/day: ${CY}content-grade activate${R}`);
     blank();
-    console.log(`  ${MG}Unlock unlimited analyses →${R}  ${CY}content-grade.github.io/Content-Grade/#pricing${R}`);
+    console.log(`  ${MG}Upgrade to Pro ($9/mo) for unlimited analyses →${R}  ${CY}https://content-grade.github.io/Content-Grade/${R}`);
     blank();
     process.exit(1);
   }
@@ -476,8 +496,7 @@ async function cmdAnalyze(filePath) {
     console.log(`  ${D}  · 100 checks/day (${remaining} remaining today on free tier)${R}`);
     console.log(`  ${D}  · Get a license at ${CY}content-grade.github.io/Content-Grade${R}`);
     blank();
-    console.log(`  ${MG}Unlock unlimited analyses →${R}  ${CY}content-grade.github.io/Content-Grade/#pricing${R}`);
-    console.log(`  ${D}⭐ Unlock deeper analysis →${R} ${CY}npm i content-grade && content-grade activate${R}  ${D}| content-grade.github.io/Content-Grade/${R}`);
+    console.log(`  ${MG}Upgrade to Pro ($9/mo) for unlimited analyses →${R}  ${CY}https://content-grade.github.io/Content-Grade/${R}`);
   }
   blank();
 }
@@ -545,7 +564,7 @@ async function cmdHeadline(text) {
     console.log(`  ${D}· Wait until tomorrow (limit resets at midnight)${R}`);
     console.log(`  ${D}· Unlock 100 checks/day: ${CY}content-grade activate${R}`);
     blank();
-    console.log(`  ${MG}Unlock unlimited analyses →${R}  ${CY}content-grade.github.io/Content-Grade/#pricing${R}`);
+    console.log(`  ${MG}Upgrade to Pro ($9/mo) for unlimited analyses →${R}  ${CY}https://content-grade.github.io/Content-Grade/${R}`);
     blank();
     process.exit(1);
   }
@@ -625,8 +644,7 @@ async function cmdHeadline(text) {
   console.log(`  ${D}Compare two headlines:  ${CY}content-grade start${R}  → HeadlineGrader compare${R}`);
   blank();
   if (!isProUser()) {
-    console.log(`  ${MG}Unlock unlimited analyses →${R}  ${CY}content-grade.github.io/Content-Grade/#pricing${R}`);
-    console.log(`  ${D}⭐ Unlock deeper analysis →${R} ${CY}npm i content-grade && content-grade activate${R}  ${D}| content-grade.github.io/Content-Grade/${R}`);
+    console.log(`  ${MG}Upgrade to Pro ($9/mo) for unlimited analyses →${R}  ${CY}https://content-grade.github.io/Content-Grade/${R}`);
     blank();
   }
 }
@@ -858,6 +876,15 @@ async function cmdBatch(dirPath) {
     process.exit(2);
   }
 
+  const safeDirPath = sanitizeFilePath(dirPath);
+  if (!safeDirPath) {
+    blank();
+    fail(`Invalid directory path.`);
+    blank();
+    process.exit(2);
+  }
+  dirPath = safeDirPath;
+
   const absDir = resolve(process.cwd(), dirPath);
   if (!existsSync(absDir)) {
     blank();
@@ -1084,6 +1111,45 @@ function cmdStart() {
   });
 }
 
+
+// ── Check-updates command ─────────────────────────────────────────────────────
+
+async function cmdCheckUpdates() {
+  blank();
+  console.log(`  ${B}Checking for updates...${R}`);
+  blank();
+  try {
+    const res = await new Promise((resolve, reject) => {
+      const req = httpsGet('https://registry.npmjs.org/content-grade/latest', {
+        headers: { 'User-Agent': 'content-grade-cli' },
+        timeout: 8000,
+      }, (r) => {
+        let data = '';
+        r.on('data', chunk => { data += chunk; });
+        r.on('end', () => resolve(data));
+      });
+      req.on('error', reject);
+      req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+    });
+    const { version: latest } = JSON.parse(res);
+    if (latest === _version) {
+      ok(`You're up to date — v${_version} is the latest.`);
+    } else {
+      warn(`Update available: ${RD}v${_version}${R}  →  ${GN}v${latest}${R}`);
+      blank();
+      console.log(`  ${B}Update with:${R}`);
+      console.log(`    ${CY}npm install -g content-grade${R}    ${D}(global install)${R}`);
+      console.log(`    ${CY}npm install content-grade@latest${R} ${D}(local install)${R}`);
+    }
+  } catch {
+    warn('Could not reach npm registry. Check your internet connection.');
+    blank();
+    console.log(`  ${D}Current version: v${_version}${R}`);
+    console.log(`  ${D}Check manually: ${CY}https://www.npmjs.com/package/content-grade${R}`);
+  }
+  blank();
+}
+
 // ── Help ──────────────────────────────────────────────────────────────────────
 
 function cmdHelp() {
@@ -1100,7 +1166,8 @@ function cmdHelp() {
 
   console.log(`  ${B}USAGE${R}`);
   blank();
-  console.log(`    ${CY}content-grade <command> [args]${R}`);
+  console.log(`    ${CY}npx content-grade <command> [args]${R}    ${D}# zero install${R}`);
+  console.log(`    ${CY}content-grade <command> [args]${R}        ${D}# after: npm install -g content-grade${R}`);
   blank();
 
   console.log(`  ${B}COMMANDS${R}`);
@@ -1122,10 +1189,12 @@ function cmdHelp() {
   console.log(`    ${CY}start${R}                   Launch the full web dashboard`);
   console.log(`    ${D}                         6 tools: headlines, pages, ads, threads, emails, audiences${R}`);
   blank();
-  console.log(`    ${CY}init${R}                    First-run setup and diagnostics`);
+  console.log(`    ${CY}init${R}                    Run if Claude CLI isn't detected or tools aren't working`);
   blank();
   console.log(`    ${CY}telemetry [on|off]${R}      View or toggle anonymous usage tracking`);
   blank();
+  console.log(`    ${CY}check-updates${R}           Check if a newer version is available on npm`);
+  blank();
   console.log(`    ${CY}help${R}                    Show this help`);
   blank();
   console.log(`  ${B}FLAGS${R}`);
@@ -1167,7 +1236,7 @@ function cmdHelp() {
   console.log(`    · Node.js 18+`);
   blank();
 
-  console.log(`  ${B}PRO TIER${R}  ${MG}$9/month${R}`);
+  console.log(`  ${B}PRO TIER${R}  ${MG}$9/mo${R}`);
   blank();
   console.log(`    · 100 analyses/day (vs 50 free)`);
   console.log(`    · Competitor headline A/B comparison`);
@@ -1176,7 +1245,8 @@ function cmdHelp() {
   console.log(`    · Email subject line optimizer`);
   console.log(`    · Audience archetype decoder`);
   blank();
-  console.log(`    ${CY}content-grade.github.io/Content-Grade${R}  → then: ${CY}content-grade activate${R}`);
+  console.log(`    Purchase at: ${CY}content-grade.github.io/Content-Grade${R}`);
+  console.log(`    Then unlock: ${CY}content-grade activate <your-license-key>${R}`);
   blank();
 }
 
@@ -1398,9 +1468,15 @@ function fetchUrl(url) {
   return new Promise((resolve, reject) => {
     const get = url.startsWith('https') ? httpsGet : httpGet;
     const req = get(url, { headers: { 'User-Agent': 'ContentGrade/1.0 (+https://github.com/content-grade/Content-Grade)' }, timeout: 15000 }, (res) => {
-      // Follow one redirect
+      // Follow one redirect — validate location is http/https before following
       if ((res.statusCode === 301 || res.statusCode === 302) && res.headers.location) {
-        fetchUrl(res.headers.location).then(resolve).catch(reject);
+        const loc = res.headers.location;
+        if (!/^https?:\/\//i.test(loc)) {
+          reject(new Error(`Redirect to non-HTTP location rejected: ${loc.slice(0, 80)}`));
+          res.resume();
+          return;
+        }
+        fetchUrl(loc).then(resolve).catch(reject);
         res.resume();
         return;
       }
@@ -1650,6 +1726,18 @@ switch (cmd) {
     cmdHelp();
     break;
 
+  case 'check-updates':
+  case 'update':
+  case 'upgrade-check':
+    recordEvent({ event: 'command', command: 'check-updates' });
+    cmdCheckUpdates().catch(err => {
+      blank();
+      fail(`Update check error: ${err.message}`);
+      blank();
+      process.exit(1);
+    });
+    break;
+
   case 'version':
   case '--version':
   case '-v':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "content-grade",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "AI-powered content analysis CLI. Score any blog post, landing page, or ad copy in under 30 seconds — runs on Claude CLI, no API key needed.",
   "type": "module",
   "bin": {