@cliperhq/cliper 1.0.0

package/README.md

@@ -0,0 +1,266 @@
+# Cliper
+
+> Generate rich, AI-ready context documents from your codebase — always fresh, always scoped, always honest about what it doesn't know.
+
+**npm:** `@cliperhq/cliper` | **CLI:** `cliper` | **Version:** 1.0.0
+
+---
+
+## What is Cliper?
+
+Every time you start an AI coding session, you waste time re-explaining your project — pasting file contents, describing structure, warning the AI about legacy decisions, and hoping it doesn't miss something critical.
+
+Cliper eliminates that tax entirely.
+
+One command. Your AI has full, accurate, scoped context. You go straight to building.
+
+---
+
+## Installation
+
+### Option A — npx (recommended, no install needed)
+
+```bash
+npx @cliperhq/cliper init
+```
+
+npx always pulls the latest version and leaves zero footprint in your project.
+
+### Option B — Global install
+
+Install once, use in any project:
+
+```bash
+npm install -g @cliperhq/cliper
+```
+
+### Option C — Shell alias (best of both worlds)
+
+Add to your `~/.zshrc` or `~/.bashrc`:
+
+```bash
+alias cliper="npx @cliperhq/cliper"
+```
+
+Then reload:
+```bash
+source ~/.zshrc
+```
+
+> **Never run `npm install @cliperhq/cliper` inside your project directory.** This installs Cliper as a project dependency and pollutes your `node_modules`. Always use npx or a global install.
+
+---
+
+## Quick Start
+
+```bash
+# Go into any project
+cd your-project
+
+# Generate your first context document
+cliper init
+
+# Copy to clipboard and paste into Claude or ChatGPT
+cliper export | pbcopy        # macOS
+cliper export | xclip         # Linux
+
+# Generate an AI-optimized prompt (requires API key)
+export ANTHROPIC_API_KEY=your_key
+cliper analyze --model claude
+
+# Or for ChatGPT
+export OPENAI_API_KEY=your_key
+cliper analyze --model chatgpt
+```
+
+---
+
+## What Gets Generated
+
+Cliper scans your project and produces `.cliper/context.md` containing:
+
+### Annotated Folder Structure
+Not a raw `tree` dump — an annotated, scoped view showing what's active, what's watched, and when files were last modified.
+
+```
+your-project/
+├── src/
+│   ├── payments/              ← ACTIVE SCOPE
+│   │   ├── refund.ts          ← modified 2h ago
+│   │   └── processor.ts       ← modified 3d ago
+│   └── auth/                  ← out of scope (3 files, last touched 3 weeks ago)
+├── config/                    ← WATCHED
+└── [14 other directories — out of scope]
+```
+
+### Git Context
+Branch, recent commits, uncommitted changes — so the AI knows exactly where you are in the development timeline.
+
+### Dependency Map
+What imports what across your scoped files, entry points, and all external packages used. Supports TypeScript, JavaScript, Rust, and Python.
+
+### Key File Contents
+Full source of scoped files, prioritized by language and recency, with a configurable size limit.
+
+### Blocked Reference Resolution
+READMEs often link to external docs the AI can't access (robots.txt blocks, private pages). Cliper fetches them locally and inlines the content directly into the context doc. No broken links, no missing context.
+
+### Gap Detection
+What you forgot to tell the AI — undocumented functions, missing `.env` vars, TODO/FIXME comments, implicit dependencies. Surfaced before your session starts.
+
+### AI-Optimized Prompts
+`cliper analyze` takes the raw context doc and uses AI to reformat it into a model-specific prompt — tuned for how Claude reasons vs how ChatGPT processes structured input.
+
+---
+
+## CLI Reference
+
+```bash
+# Initialize — scan project and generate context document
+cliper init
+cliper init --max-file-size 200    # increase file size limit (default: 50KB)
+
+# Sync — refresh stale sections after changes
+cliper sync
+cliper sync --watch                # auto-refresh on every git commit
+
+# Scope — control what gets included
+cliper scope add src/payments/     # add directory to active scope
+cliper scope watch config/db.ts    # add file to persistent watch list
+cliper scope remove src/payments/  # remove from scope
+cliper scope list                  # show current scope
+
+# Status — check freshness and current state
+cliper status
+
+# Export — print context doc to stdout
+cliper export                      # markdown format
+cliper export --format txt         # plain text
+
+# Analyze — generate AI-optimized prompt from context doc
+cliper analyze --model claude      # optimized for Claude
+cliper analyze --model chatgpt     # optimized for ChatGPT
+```
+
+---
+
+## Language Support
+
+Cliper auto-detects your project type and scopes intelligently:
+
+| Language | Auto-detected from | Source dirs included |
+|---|---|---|
+| **Rust** | `Cargo.toml` | All workspace member `src/` dirs |
+| **TypeScript / JavaScript** | `package.json` | `src/`, `packages/`, `apps/`, `libs/` |
+| **Python** | `pyproject.toml` / `requirements.txt` | `src/`, dirs with `__init__.py` |
+| **Go** | `go.mod` | `internal/`, `pkg/`, `cmd/` |
+
+---
+
+## How to Use with AI Models
+
+After running `cliper init`:
+
+**Option 1 — Copy and paste**
+```bash
+cliper export | pbcopy     # macOS — then paste as first message
+cliper export | xclip      # Linux
+```
+
+**Option 2 — Use the optimized prompt**
+```bash
+cliper analyze --model claude
+cat .cliper/prompt-claude.md | pbcopy
+```
+
+**Option 3 — Reference the file directly**
+Some tools (Cursor, Claude Projects) can reference files directly. Point them at `.cliper/context.md`.
+
+---
+
+## Project Architecture
+
+```
+src/
+├── commands/
+│   ├── init.ts          # cliper init — full project scan
+│   ├── sync.ts          # cliper sync — incremental refresh
+│   ├── scope.ts         # cliper scope — manage active scope
+│   ├── status.ts        # cliper status — freshness report
+│   ├── export.ts        # cliper export — output context doc
+│   └── analyze.ts       # cliper analyze — AI-optimized prompt generation
+├── scanner/
+│   ├── fileTree.ts      # annotated folder structure
+│   ├── fileContent.ts   # scoped file extraction with token cap
+│   ├── gitContext.ts    # branch, commits, uncommitted changes
+│   └── dependencies.ts  # import/dependency map (TS, JS, Rust, Python)
+├── resolver/
+│   └── urlFetcher.ts    # fetch and inline blocked external references
+├── gaps/
+│   └── detector.ts      # undocumented patterns, missing env vars, TODOs
+├── context/
+│   └── builder.ts       # assembles the final context.md
+└── scope/
+    ├── config.ts         # persists scope config in .cliper/
+    └── autoScope.ts      # language-aware auto-scoping from git activity
+```
+
+---
+
+## What Cliper Creates in Your Project
+
+Running `cliper init` adds the following to your project:
+
+```
+.cliper/
+├── context.md          # the context document — commit this
+├── scope.json          # your scope config — commit this
+├── prompt-claude.md    # generated prompt (cliper analyze) — gitignored
+├── prompt-gpt.md       # generated prompt (cliper analyze) — gitignored
+└── cache/              # locally fetched URL content — gitignored
+```
+
+Cliper also automatically adds `node_modules/`, `package-lock.json`, and `.cliper/cache/` to your `.gitignore` — and removes them from git tracking if they were accidentally staged.
+
+---
+
+## Roadmap
+
+**Shipped**
+- ✅ Language-aware auto-scoping (Rust, Node, Python, Go)
+- ✅ Annotated folder structure with freshness timestamps
+- ✅ Git-aware context (branch, commits, uncommitted changes)
+- ✅ Dependency map (TS/JS/Rust/Python)
+- ✅ Blocked URL resolution and inlining
+- ✅ Gap detection (TODOs, missing env vars, undocumented functions)
+- ✅ AI-optimized prompt generation (Claude + ChatGPT)
+- ✅ `--max-file-size` flag for large files
+- ✅ Auto-managed `.gitignore`
+
+**Coming Soon**
+- ⬜ `cliper push` — sync context to the Cliper web dashboard
+- ⬜ Web dashboard — visual representation of your codebase context
+- ⬜ Project history — track how your codebase evolves over time
+- ⬜ Team sharing — shared context annotations committed to git
+- ⬜ VS Code extension — one-click context copy from the editor
+
+---
+
+## Contributing
+
+Cliper is early and actively developed. If you're a developer who feels the pain of re-explaining your project to AI every session, contributions are very welcome.
+
+```bash
+git clone https://github.com/bristinwild/cliper
+cd cliper
+npm install
+npm run dev
+```
+
+Open an issue before submitting large PRs so we can align on direction.
+
+---
+
+## License
+
+ISC © bristinwild

package/dist/commands/analyze.d.ts

@@ -0,0 +1,6 @@
+interface AnalyzeOptions {
+    model: string;
+}
+export declare function analyzeCommand(options: AnalyzeOptions): Promise<void>;
+export {};
+//# sourceMappingURL=analyze.d.ts.map

package/dist/commands/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/commands/analyze.ts"],"names":[],"mappings":"AAQA,UAAU,cAAc;IACpB,KAAK,EAAE,MAAM,CAAC;CACjB;AA2HD,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAmE3E"}

package/dist/commands/analyze.js

@@ -0,0 +1,216 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeCommand = analyzeCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const config_1 = require("../scope/config");
+const CLAUDE_SYSTEM = `You are an expert software architect analyzing a codebase context document.
+Your job is to transform raw codebase data into a highly optimized prompt for a Claude AI coding session.
+
+Claude thinks best when given:
+- Clear project narrative (what it is, why it exists)
+- Explicit constraints and existing decisions to respect
+- The specific area of focus with surrounding context
+- What NOT to change or break
+- Open questions or uncertainties the developer has
+
+Your output must be a ready-to-paste prompt. No preamble. No explanation. Just the prompt itself.`;
+const CHATGPT_SYSTEM = `You are an expert software architect analyzing a codebase context document.
+Your job is to transform raw codebase data into a highly optimized prompt for a ChatGPT coding session.
+
+ChatGPT works best when given:
+- Numbered, structured context sections
+- Explicit file paths and code blocks
+- Clear task definition separated from context
+- Constraints listed as bullet points
+- A direct question or task at the end
+
+Your output must be a ready-to-paste prompt. No preamble. No explanation. Just the prompt itself.`;
+const CLAUDE_USER = (contextDoc) => `Here is the raw codebase context document generated by Cliper:
+
+<context>
+${contextDoc}
+</context>
+
+Transform this into an optimized Claude prompt following these rules:
+
+CRITICAL ACCURACY RULES:
+- Never expand acronyms unless the context doc explicitly defines them. If you see "SPEL" and the doc doesn't say what it stands for, write "SPEL" — do not invent an expansion.
+- Never infer what a framework "is based on" from inspiration references. "Inspired by Anchor for Solana" does NOT mean the project runs on Solana.
+- Include ALL macros and annotations found in the source code, not just the most common ones. If you see #[require_admin], include it.
+- If a file was truncated, note that there may be additional macros or patterns not visible.
+
+FORMAT RULES:
+1. Opens with a concise project narrative (2-3 sentences max) — only state facts explicitly in the context doc
+2. Summarizes the current branch focus and recent work
+3. Lists key architectural decisions already made that must be respected
+4. Highlights the most important files and their roles
+5. Lists ALL macros/annotations found across all files
+6. Surfaces any detected gaps the developer should be aware of
+7. Ends with: "## What I need help with today:"
+
+Make it feel like a natural briefing. Never invent details not present in the context doc.`;
+const CHATGPT_USER = (contextDoc) => `Here is the raw codebase context document generated by Cliper:
+
+${contextDoc}
+
+Transform this into an optimized chatgpt prompt following these rules:
+
+CRITICAL ACCURACY RULES:
+- Never expand acronyms unless the context doc explicitly defines them. If you see "SPEL" and the doc doesn't say what it stands for, write "SPEL" — do not invent an expansion.
+- Never infer what a framework "is based on" from inspiration references. "Inspired by Anchor for Solana" does NOT mean the project runs on Solana.
+- Include ALL macros and annotations found in the source code, not just the most common ones. If you see #[require_admin], include it.
+- If a file was truncated, note that there may be additional macros or patterns not visible.
+
+FORMAT RULES:
+1. Starts with "## Project Context" as a header
+2. Uses numbered sections for: Project Overview, Tech Stack, Current Branch & Focus, Key Files, Constraints & Decisions, Known Gaps
+3. Uses bullet points and code blocks for file paths and snippets
+4. Keeps each section concise — no more than 5 bullet points per section
+5. Ends with "## Task:" followed by a blank line for the developer to fill in
+
+Format it for maximum clarity and scannability. ChatGPT responds best to structured, explicitly labeled context.`;
+async function callAnthropicAPI(contextDoc) {
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "x-api-key": process.env.ANTHROPIC_API_KEY ?? "",
+            "anthropic-version": "2023-06-01",
+        },
+        body: JSON.stringify({
+            model: "claude-sonnet-4-20250514",
+            max_tokens: 2000,
+            system: CLAUDE_SYSTEM,
+            messages: [{ role: "user", content: CLAUDE_USER(contextDoc) }],
+        }),
+    });
+    if (!response.ok) {
+        const err = await response.text();
+        throw new Error(`Anthropic API error: ${response.status} — ${err}`);
+    }
+    const data = await response.json();
+    return data.content?.[0]?.text ?? "";
+}
+async function callOpenAIAPI(contextDoc) {
+    const response = await fetch("https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${process.env.OPENAI_API_KEY ?? ""}`,
+        },
+        body: JSON.stringify({
+            model: "gpt-4o",
+            max_tokens: 2000,
+            messages: [
+                { role: "system", content: CHATGPT_SYSTEM },
+                { role: "user", content: CHATGPT_USER(contextDoc) },
+            ],
+        }),
+    });
+    if (!response.ok) {
+        const err = await response.text();
+        throw new Error(`OpenAI API error: ${response.status} — ${err}`);
+    }
+    const data = await response.json();
+    return data.choices?.[0]?.message?.content ?? "";
+}
+async function analyzeCommand(options) {
+    const projectRoot = process.cwd();
+    const cliperDir = (0, config_1.getCliperDir)(projectRoot);
+    const contextPath = path.join(cliperDir, "context.md");
+    // Check context doc exists
+    if (!fs.existsSync(contextPath)) {
+        console.error(chalk_1.default.red("\n  No context doc found. Run cliper init first.\n"));
+        process.exit(1);
+    }
+    const contextDoc = fs.readFileSync(contextPath, "utf-8");
+    const model = options.model.toLowerCase();
+    // Validate model choice
+    if (!["claude", "chatgpt"].includes(model)) {
+        console.error(chalk_1.default.red(`\n  Unknown model: ${options.model}`));
+        console.error(chalk_1.default.gray("  Usage: cliper analyze --model claude"));
+        console.error(chalk_1.default.gray("         cliper analyze --model chatgpt\n"));
+        process.exit(1);
+    }
+    // Check API key
+    if (model === "claude" && !process.env.ANTHROPIC_API_KEY) {
+        console.error(chalk_1.default.red("\n  ANTHROPIC_API_KEY not set."));
+        console.error(chalk_1.default.gray("  Export it first: export ANTHROPIC_API_KEY=your_key_here\n"));
+        process.exit(1);
+    }
+    if (model === "chatgpt" && !process.env.OPENAI_API_KEY) {
+        console.error(chalk_1.default.red("\n  OPENAI_API_KEY not set."));
+        console.error(chalk_1.default.gray("  Export it first: export OPENAI_API_KEY=your_key_here\n"));
+        process.exit(1);
+    }
+    console.log(chalk_1.default.bold.cyan(`\n  cliper analyze — ${model}\n`));
+    const spinner = (0, ora_1.default)(`Analyzing context doc with ${model === "claude" ? "Claude" : "ChatGPT"}...`).start();
+    try {
+        let prompt;
+        if (model === "claude") {
+            prompt = await callAnthropicAPI(contextDoc);
+            const outputPath = path.join(cliperDir, "prompt-claude.md");
+            fs.writeFileSync(outputPath, prompt, "utf-8");
+            spinner.succeed(chalk_1.default.green("Claude prompt generated"));
+            console.log(chalk_1.default.gray(`\n  Saved: ${outputPath}\n`));
+            console.log(chalk_1.default.cyan("  Copy to clipboard:"));
+            console.log(chalk_1.default.white("    cliper analyze --model claude | pbcopy\n"));
+            console.log(chalk_1.default.cyan("  Or open directly:"));
+            console.log(chalk_1.default.white(`    cat ${outputPath} | pbcopy\n`));
+        }
+        else {
+            prompt = await callOpenAIAPI(contextDoc);
+            const outputPath = path.join(cliperDir, "prompt-gpt.md");
+            fs.writeFileSync(outputPath, prompt, "utf-8");
+            spinner.succeed(chalk_1.default.green("ChatGPT prompt generated"));
+            console.log(chalk_1.default.gray(`\n  Saved: ${outputPath}\n`));
+            console.log(chalk_1.default.cyan("  Copy to clipboard:"));
+            console.log(chalk_1.default.white(`    cat ${outputPath} | pbcopy\n`));
+        }
+    }
+    catch (err) {
+        spinner.fail(chalk_1.default.red("Analysis failed"));
+        console.error(chalk_1.default.red(`\n  ${err.message}\n`));
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=analyze.js.map

package/dist/commands/export.d.ts

@@ -0,0 +1,6 @@
+interface ExportOptions {
+    format: string;
+}
+export declare function exportCommand(options: ExportOptions): Promise<void>;
+export {};
+//# sourceMappingURL=export.d.ts.map

package/dist/commands/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/commands/export.ts"],"names":[],"mappings":"AAKA,UAAU,aAAa;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBzE"}

package/dist/commands/export.js

@@ -0,0 +1,64 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportCommand = exportCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const config_1 = require("../scope/config");
+async function exportCommand(options) {
+    const projectRoot = process.cwd();
+    const contextPath = path.join((0, config_1.getCliperDir)(projectRoot), "context.md");
+    if (!fs.existsSync(contextPath)) {
+        console.error(chalk_1.default.red("\n  No context doc found. Run cliper init first.\n"));
+        process.exit(1);
+    }
+    let content = fs.readFileSync(contextPath, "utf-8");
+    if (options.format === "txt") {
+        // Strip markdown formatting for plain text output
+        content = content
+            .replace(/```[\w]*\n/g, "")
+            .replace(/```/g, "")
+            .replace(/#{1,6}\s/g, "")
+            .replace(/\*\*/g, "")
+            .replace(/`/g, "");
+    }
+    // Write to stdout — designed to be piped
+    process.stdout.write(content);
+}
+//# sourceMappingURL=export.js.map

package/dist/commands/init.d.ts

@@ -0,0 +1,7 @@
+interface InitOptions {
+    path: string;
+    maxFileSize?: number;
+}
+export declare function initCommand(options: InitOptions): Promise<void>;
+export {};
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAiBA,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAGD,wBAAsB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAsJrE"}