content-grade 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,198 @@
+# Contributing to ContentGrade
+
+Thanks for wanting to contribute. ContentGrade is a CLI + web dashboard for AI-powered content scoring. It runs entirely on local Claude CLI — no API keys, no external services (unless you add Stripe).
+
+---
+
+## Prerequisites
+
+- **Node.js 18+**
+- **pnpm** (`npm install -g pnpm`)
+- **Claude CLI** — installed and logged in ([claude.ai/code](https://claude.ai/code))
+- Verify: `claude -p "say hi"`
+
+---
+
+## Local development setup
+
+```bash
+git clone https://github.com/StanislavBG/Content-Grade
+cd Content-Grade
+pnpm install
+pnpm dev
+```
+
+This starts two processes concurrently:
+- **Client** (Vite) at [http://localhost:3000](http://localhost:3000) with hot reload
+- **Server** (tsx watch) at [http://localhost:4000](http://localhost:4000) with hot reload
+
+The client proxies API requests to the server automatically.
+
+---
+
+## Project structure
+
+```
+bin/
+  content-grade.js          CLI entry point — all CLI commands live here
+server/
+  app.ts                    Fastify app factory (used by server and tests)
+  index.ts                  Production server entry (binds port)
+  claude.ts                 Claude CLI wrapper (server-side)
+  db.ts                     SQLite setup — usage tracking, stripe subscriptions
+  routes/
+    demos.ts                API routes for all 6 web dashboard tools
+    stripe.ts               Stripe checkout, webhooks, subscription management
+  services/
+    claude.ts               askClaude() helper for route handlers
+    stripe.ts               Stripe helpers — subscription checks, customer management
+src/
+  App.tsx                   React app router
+  main.tsx                  React entry point
+  views/
+    HeadlineGraderView.tsx
+    PageRoastView.tsx
+    AdScorerView.tsx
+    ThreadGraderView.tsx
+    EmailForgeView.tsx
+    AudienceDecoderView.tsx
+    ContentGradeShared.tsx  Shared UI components
+  data/
+    api.ts                  API client for the web dashboard
+tests/
+  unit/                     Unit tests (no Claude required)
+  integration/              Integration tests (spins up Fastify)
+  helpers/
+    db.ts                   Test database helpers
+```
+
+---
+
+## Running tests
+
+```bash
+pnpm test               # run all tests once
+pnpm test:watch         # watch mode — reruns on file changes
+pnpm test:coverage      # full coverage report
+```
+
+Tests live in `tests/unit/` and `tests/integration/`. Integration tests spin up a real Fastify server but mock Claude responses — they don't require a live Claude CLI.
+
+Unit tests cover:
+- `tests/unit/validation.test.ts` — input validation
+- `tests/unit/cli-utils.test.ts` — CLI helper functions
+- `tests/unit/rate-limit.test.ts` — rate limit logic
+- `tests/unit/edge-cases.test.ts` — edge case handling
+- `tests/unit/quality-hardening.test.ts` — error path hardening
+
+---
+
+## TypeScript
+
+```bash
+pnpm typecheck    # run tsc --noEmit — check types without building
+```
+
+The project has two TypeScript configs:
+- `tsconfig.json` — client (Vite, React, ESNext)
+- `tsconfig.server.json` — server (Node.js ESM, outputs to `dist-server/`)
+
+Both must pass before merging.
+
+---
+
+## Building for production
+
+```bash
+pnpm build    # builds client (dist/) and server (dist-server/)
+pnpm start    # runs the production server
+```
+
+After building, test the full CLI flow:
+
+```bash
+node bin/content-grade.js init
+node bin/content-grade.js demo
+node bin/content-grade.js start
+```
+
+---
+
+## Making changes
+
+### Adding or modifying CLI commands
+
+All CLI logic lives in `bin/content-grade.js`. The router is the `switch (cmd)` block at the bottom.
+
+Pattern for a new command:
+1. Add a `cmdFoo(args)` async function
+2. Add a `case 'foo':` branch in the switch
+3. Follow the existing error handling pattern: `blank()`, `fail()`, `process.exit(1)`
+4. Use `checkClaude()` before any `askClaude()` call
+
+### Adding a new web dashboard tool
+
+1. Create `src/views/FooView.tsx` — follow the pattern of existing views
+2. Add a route in `App.tsx`
+3. Add an API endpoint in `server/routes/demos.ts`
+4. Add the endpoint name to `FREE_TIER_LIMIT` tracking in `demos.ts`
+5. Add to the tool list in `bin/content-grade.js` `cmdStart()` output
+
+### Modifying Claude prompts
+
+Prompts are inline in `bin/content-grade.js` (CLI) and `server/routes/demos.ts` (web). Both require JSON-only responses — the parser handles both clean JSON and JSON embedded in markdown fences.
+
+The scoring calibration note at the bottom of each prompt is load-bearing: without it, Claude uses a compressed range and most content scores 50-70. Keep it.
+
+---
+
+## Claude model selection
+
+| Use case | Model | Why |
+|----------|-------|-----|
+| `analyze` command | `claude-sonnet-4-6` | Richer analysis, better calibration |
+| `headline` command | `claude-haiku-4-5-20251001` | Fast, good enough for structured scoring |
+| `init` smoke test | `claude-haiku-4-5-20251001` | Just needs a JSON ping |
+| Web dashboard tools | `claude-haiku-4-5-20251001` | Server-side, latency-sensitive |
+
+---
+
+## Rate limiting
+
+The web dashboard uses SQLite-backed IP rate limiting:
+- Free tier: 3 analyses/day per tool per IP (IP is SHA-256 hashed, never stored raw)
+- Pro tier: 100 analyses/day — verified against Stripe API with a 5-minute cache
+- AudienceDecoder: one-time purchase model (different Stripe Price ID)
+
+The CLI (`analyze`, `headline`) has no rate limiting — it calls Claude directly from your machine.
+
+---
+
+## Stripe setup (optional)
+
+The app works without Stripe — upgrade prompts show "Coming Soon" instead of a checkout button.
+
+To enable payments:
+1. Copy `.env.example` to `.env`
+2. Add your Stripe keys
+3. Create products in Stripe dashboard — get the Price IDs
+4. Add `STRIPE_PRICE_CONTENTGRADE_PRO` and `STRIPE_PRICE_AUDIENCEDECODER`
+5. Set up a webhook pointing to `/api/stripe/webhook`
+
+---
+
+## Pull request checklist
+
+- [ ] `pnpm typecheck` passes (zero TypeScript errors)
+- [ ] `pnpm test` passes (all tests green)
+- [ ] CLI smoke test passes: `node bin/content-grade.js demo`
+- [ ] No hardcoded API keys or credentials
+- [ ] Error paths follow the existing pattern (`blank()`, `fail()`, `process.exit(1)`)
+- [ ] New Claude prompts include the scoring calibration note
+- [ ] PR description explains what changed and why
+
+---
+
+## Questions
+
+Open an issue or start a GitHub Discussion. Include your Node.js version, OS, and the output of `npx content-grade init` if it's a setup issue.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StanislavBG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# ContentGrade
+
+> AI-powered content quality scoring for developers and content teams. Score any blog post, landing page, ad copy, or email — in under 30 seconds. No API keys. No accounts. Runs on your local Claude CLI.
+
+[![npm](https://img.shields.io/npm/v/content-grade.svg)](https://www.npmjs.com/package/content-grade)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js 18+](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![Requires Claude CLI](https://img.shields.io/badge/requires-Claude%20CLI-orange)](https://claude.ai/code)
+
+---
+
+## 60-second quickstart
+
+```bash
+# 1. Verify Claude CLI is installed and logged in
+claude -p "say hi"
+
+# 2. Run an instant demo — no file needed
+npx content-grade
+
+# 3. Analyze your own content
+npx content-grade ./my-post.md
+
+# 4. Grade a single headline
+npx content-grade headline "Why Most Startups Fail at Month 18"
+```
+
+**One requirement:** [Claude CLI](https://claude.ai/code) must be installed and logged in. That's it — no API keys, no accounts, no data leaves your machine.
+
+---
+
+## What you get
+
+```
+  ╔═══════════════════════════════════════╗
+  ║   ContentGrade  ·  Content Analysis   ║
+  ╚═══════════════════════════════════════╝
+
+  OVERALL SCORE   72/100  B+   blog post
+  ████████████████████████░░░░░░░░░░░░░░░░
+
+  HEADLINE SCORE   ████████████░░░░░░░░ 61/100
+  "Why Most Startups Fail"
+  ↳ Too vague — the reader doesn't know if this applies to them.
+
+  ──────────────────────────────────────────────────────────
+  DIMENSION BREAKDOWN
+
+  Clarity           ████████████████████ 80/100
+    ↳ Well-organized with clear section breaks.
+
+  Engagement        ████████████░░░░░░░░ 60/100
+    ↳ Opens with a statistic but drops momentum in paragraph 3.
+
+  Structure         ████████████████░░░░ 72/100
+    ↳ Good use of subheadings but the conclusion is thin.
+
+  Value Delivery    █████████████░░░░░░░ 65/100
+    ↳ Core advice is solid but needs a concrete takeaway.
+
+  VERDICT
+  Strong structure undermined by a weak headline — fix that first.
+
+  TOP IMPROVEMENTS
+  ● Make the headline specific: who fails, why, and what the fix is
+    Fix: "Why 90% of SaaS Startups Fail at Month 18 (and How to Be the 10%)"
+
+  ● Add one data point to support claims in paragraph 2
+    Fix: Cite a specific study — "CB Insights found..." beats "many startups..."
+
+  HEADLINE REWRITES
+  1. Why 90% of SaaS Startups Fail at Month 18 (and How to Be the 10%)
+  2. The Month 18 Startup Trap: What Kills Growth-Stage Companies
+
+  Free analysis complete. Pro unlocks:
+    · Competitor headline comparison
+    · Landing page URL audit (full CRO analysis)
+    · Ad copy scoring (Google, Meta, LinkedIn)
+    · 100 analyses/day vs 3 free
+```
+
+---
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| *(no args)* | Instant demo on built-in sample content |
+| `<file>` | Analyze a file directly — `npx content-grade ./post.md` |
+| `.` or `<dir>` | Scan a directory, find and analyze the best content file |
+| `demo` | Same as no args |
+| `analyze <file>` | Full content audit: score, grade, dimensions, improvements |
+| `check <file>` | Alias for `analyze` |
+| `analyse <file>` | Alias for `analyze` (British spelling) |
+| `headline "<text>"` | Grade a headline on 4 copywriting frameworks |
+| `grade "<text>"` | Alias for `headline` |
+| `init` | First-run setup: verify Claude CLI, run smoke test |
+| `start` | Launch the full web dashboard (6 tools) |
+| `help` | Full usage and examples |
+
+---
+
+## The 6 web dashboard tools
+
+Launch with `content-grade start` — opens at [http://localhost:4000](http://localhost:4000):
+
+| Tool | Route | What it does |
+|------|-------|-------------|
+| **HeadlineGrader** | `/headline` | A/B comparison, scores across 4 frameworks, suggests rewrites |
+| **PageRoast** | `/page-roast` | Landing page URL audit: hero, social proof, clarity, CRO |
+| **AdScorer** | `/ad-scorer` | Google/Meta/LinkedIn ad copy scoring |
+| **ThreadGrader** | `/thread` | Twitter/X thread hook, structure, and shareability score |
+| **EmailForge** | `/email-forge` | Subject line + body copy for click-through optimization |
+| **AudienceDecoder** | `/audience` | Twitter handle → audience archetypes and content patterns |
+
+Free tier: **3 analyses/day per tool**. Pro ($9/mo): **100 analyses/day** + all tools.
+
+---
+
+## Requirements
+
+- **Node.js 18+**
+- **Claude CLI** — install from [claude.ai/code](https://claude.ai/code), then run `claude login`
+
+Verify Claude is working:
+
+```bash
+claude -p "say hi"
+```
+
+If this fails, run `npx content-grade init` for step-by-step diagnostics.
+
+---
+
+## CLI reference
+
+### `analyze` / `check`
+
+```bash
+content-grade analyze <file>
+content-grade check <file>
+```
+
+Analyzes written content from any plain-text file. Detects content type automatically (blog, landing page, email, ad copy, social thread) and calibrates scoring accordingly.
+
+**File limits:**
+- Maximum size: 500 KB
+- Minimum length: 20 characters
+- Binary files are rejected — use `.md`, `.txt`, `.mdx`, or any plain-text format
+- Files over 6,000 characters are truncated for analysis (the full file is still read)
+
+**Output sections:**
+1. Overall score (0–100) with letter grade (A+ to F)
+2. Headline score with 1-2 sentence feedback
+3. Dimension breakdown — Clarity, Engagement, Structure, Value Delivery
+4. One-line verdict
+5. Strengths list
+6. Top improvements with specific, actionable fixes
+7. 2 headline rewrite suggestions
+
+```bash
+# Examples
+content-grade analyze ./blog-post.md
+content-grade check ./email-draft.txt
+content-grade analyze ~/landing-page-copy.md
+```
+
+---
+
+### `headline` / `grade`
+
+```bash
+content-grade headline "<text>"
+content-grade grade "<text>"
+```
+
+Grades a single headline on 4 direct-response copywriting frameworks:
+
+| Framework | Max points | What it checks |
+|-----------|-----------|----------------|
+| Rule of One | 30 | Single focused idea, one reader, one promise |
+| Value Equation | 30 | Benefit clarity, specificity, reader desire |
+| Readability | 20 | Length, word choice, scan-ability |
+| Proof/Promise | 20 | Credibility signals, specificity, claims |
+
+Output: overall score, per-framework breakdown with notes, 2 stronger rewrites.
+
+```bash
+content-grade headline "How I 10x'd My Conversion Rate in 30 Days"
+content-grade headline "The $0 Marketing Strategy That Got Us 10,000 Users"
+```
+
+---
+
+### `init` / `setup`
+
+```bash
+content-grade init
+```
+
+Three-step diagnostic:
+1. Checks Claude CLI is on `PATH` (or `CLAUDE_PATH`)
+2. Runs a live smoke test against Claude
+3. Checks whether the production web dashboard build exists
+
+Use this when something isn't working — it tells you exactly what to fix.
+
+---
+
+### `start` / `serve`
+
+```bash
+content-grade start
+```
+
+Starts the production web server at [http://localhost:4000](http://localhost:4000) and opens your browser. Requires a production build (run `npm run build` first if self-hosting).
+
+**Port:** controlled by `PORT` environment variable (default: 4000).
+
+---
+
+### `demo`
+
+```bash
+content-grade demo
+# or just:
+npx content-grade
+```
+
+Runs a full analysis on built-in sample content so you see exactly what ContentGrade does before analyzing your own work.
+
+---
+
+### Directory scan
+
+```bash
+content-grade .
+content-grade ./posts
+content-grade /path/to/content
+```
+
+Scans up to 2 directory levels deep for `.md`, `.txt`, and `.mdx` files. Picks the best candidate (prefers files with names like `post`, `article`, `blog`, `draft`, `copy` over `README.md`; larger files score higher). Then runs `analyze` on it.
+
+---
+
+## Configuration
+
+All configuration is through environment variables — no config file needed.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `4000` | Web dashboard server port |
+| `PUBLIC_URL` | `http://localhost:4000` | Base URL for the server |
+| `CLAUDE_PATH` | `claude` | Path to Claude CLI binary if not on `PATH` |
+| `STRIPE_SECRET_KEY` | *(empty)* | Stripe secret key — leave empty to show "Coming Soon" on upgrade prompts |
+| `STRIPE_PRICE_CONTENTGRADE_PRO` | *(empty)* | Stripe Price ID for Pro subscription |
+| `STRIPE_PRICE_AUDIENCEDECODER` | *(empty)* | Stripe Price ID for AudienceDecoder one-time purchase |
+| `STRIPE_WEBHOOK_SECRET` | *(empty)* | Stripe webhook signing secret |
+| `VITE_API_URL` | `/api` | Vite dev server API proxy (development only) |
+
+Copy `.env.example` to `.env` and fill in what you need:
+
+```bash
+cp .env.example .env
+```
+
+Stripe variables are entirely optional — all tools work without them; upgrade prompts show "Coming Soon" instead of a checkout button.
+
+---
+
+## Self-hosting / Development
+
+```bash
+git clone https://github.com/StanislavBG/Content-Grade
+cd Content-Grade
+npm install
+npm run dev     # hot reload: server at :4000, client at :3000
+```
+
+To build for production:
+
+```bash
+npm run build   # builds client to dist/ and server to dist-server/
+npm start       # runs the production server
+```
+
+**Project layout:**
+
+```
+bin/               CLI entry point (content-grade.js)
+docs/              REST API reference (api.md)
+server/            Fastify API server
+  routes/          API route handlers (demos, stripe)
+  services/        Claude integration, Stripe helpers
+  db.ts            SQLite setup (usage tracking, subscriptions)
+src/               React web dashboard
+  views/           6 tool views (HeadlineGrader, PageRoast, etc.)
+tests/
+  unit/            Unit tests
+  integration/     Server integration tests
+```
+
+**REST API:** The web dashboard exposes a full REST API at `http://localhost:4000`. See [`docs/api.md`](./docs/api.md) for the complete reference — every endpoint, request shape, response schema, and cURL examples.
+
+**Run tests:**
+
+```bash
+npm test              # run all tests
+npm run test:watch    # watch mode
+npm run test:coverage # coverage report
+```
+
+---
+
+## Pricing
+
+| | Free | Pro |
+|-|------|-----|
+| Price | Free forever | $9/month |
+| Analyses/day (CLI) | Unlimited | Unlimited |
+| Analyses/day (web dashboard, per tool) | 3 | 100 |
+| HeadlineGrader (single grade) | ✓ | ✓ |
+| HeadlineGrader (A/B comparison) | — | ✓ |
+| PageRoast (URL audit) | — | ✓ |
+| AdScorer | — | ✓ |
+| ThreadGrader | — | ✓ |
+| EmailForge | — | ✓ |
+| AudienceDecoder | — | One-time purchase |
+
+---
+
+## How it works
+
+ContentGrade uses **your local Claude CLI** — the same binary you use for `claude -p` commands. When you run `analyze`, it:
+
+1. Reads your file and detects content type (blog, email, ad, landing page, social)
+2. Calls `claude -p --no-session-persistence --model claude-sonnet-4-6` with a structured scoring prompt
+3. Parses the JSON response and renders the scored output in your terminal
+
+No data is sent to any external service. No account required. Your content stays on your machine.
+
+The web dashboard works the same way — every tool call goes through `claude -p` running locally on your server.
+
+---
+
+## License
+
+MIT