@cliperhq/cliper 1.0.0

package/dist/scope/config.js

@@ -0,0 +1,71 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCliperDir = getCliperDir;
+exports.getScopeConfigPath = getScopeConfigPath;
+exports.loadScopeConfig = loadScopeConfig;
+exports.saveScopeConfig = saveScopeConfig;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const DEFAULT_CONFIG = {
+    active: [],
+    watched: [],
+    updatedAt: new Date().toISOString(),
+};
+function getCliperDir(projectRoot) {
+    return path.join(projectRoot, ".cliper");
+}
+function getScopeConfigPath(projectRoot) {
+    return path.join(getCliperDir(projectRoot), "scope.json");
+}
+function loadScopeConfig(projectRoot) {
+    const configPath = getScopeConfigPath(projectRoot);
+    if (!fs.existsSync(configPath))
+        return { ...DEFAULT_CONFIG };
+    try {
+        return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+}
+function saveScopeConfig(projectRoot, config) {
+    const dir = getCliperDir(projectRoot);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    config.updatedAt = new Date().toISOString();
+    fs.writeFileSync(getScopeConfigPath(projectRoot), JSON.stringify(config, null, 2));
+}
+//# sourceMappingURL=config.js.map

package/index.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+console.log("cliper v1.0.0");

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@cliperhq/cliper",
+  "version": "1.0.0",
+  "description": "Generate rich, AI-ready context documents from your codebase. Always fresh, always scoped — for Claude, ChatGPT, and beyond.",
+  "main": "dist/index.js",
+  "bin": {
+    "cliper": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js",
+    "lint": "eslint src/**/*.ts"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "cheerio": "^1.0.0",
+    "cli-table3": "^0.6.3",
+    "commander": "^12.0.0",
+    "glob": "^10.3.10",
+    "ignore": "^5.3.1",
+    "marked": "^12.0.0",
+    "node-fetch": "^3.3.2",
+    "ora": "^8.0.1",
+    "simple-git": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/cheerio": "^0.22.35",
+    "@types/node": "^20.12.7",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.4.5"
+  },
+  "license": "ISC",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/commands/analyze.ts

@@ -0,0 +1,201 @@
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+import ora from "ora";
+import { getCliperDir } from "../scope/config";
+
+type Model = "claude" | "chatgpt";
+
+interface AnalyzeOptions {
+    model: string;
+}
+
+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: string) => `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: string) => `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: string): Promise<string> {
+    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() as any;
+    return data.content?.[0]?.text ?? "";
+}
+
+async function callOpenAIAPI(contextDoc: string): Promise<string> {
+    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() as any;
+    return data.choices?.[0]?.message?.content ?? "";
+}
+
+export async function analyzeCommand(options: AnalyzeOptions): Promise<void> {
+    const projectRoot = process.cwd();
+    const cliperDir = getCliperDir(projectRoot);
+    const contextPath = path.join(cliperDir, "context.md");
+
+    // Check context doc exists
+    if (!fs.existsSync(contextPath)) {
+        console.error(chalk.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() as Model;
+
+    // Validate model choice
+    if (!["claude", "chatgpt"].includes(model)) {
+        console.error(chalk.red(`\n  Unknown model: ${options.model}`));
+        console.error(chalk.gray("  Usage: cliper analyze --model claude"));
+        console.error(chalk.gray("         cliper analyze --model chatgpt\n"));
+        process.exit(1);
+    }
+
+    // Check API key
+    if (model === "claude" && !process.env.ANTHROPIC_API_KEY) {
+        console.error(chalk.red("\n  ANTHROPIC_API_KEY not set."));
+        console.error(chalk.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.red("\n  OPENAI_API_KEY not set."));
+        console.error(chalk.gray("  Export it first: export OPENAI_API_KEY=your_key_here\n"));
+        process.exit(1);
+    }
+
+    console.log(chalk.bold.cyan(`\n  cliper analyze — ${model}\n`));
+
+    const spinner = ora(`Analyzing context doc with ${model === "claude" ? "Claude" : "ChatGPT"}...`).start();
+
+    try {
+        let prompt: string;
+
+        if (model === "claude") {
+            prompt = await callAnthropicAPI(contextDoc);
+            const outputPath = path.join(cliperDir, "prompt-claude.md");
+            fs.writeFileSync(outputPath, prompt, "utf-8");
+            spinner.succeed(chalk.green("Claude prompt generated"));
+            console.log(chalk.gray(`\n  Saved: ${outputPath}\n`));
+            console.log(chalk.cyan("  Copy to clipboard:"));
+            console.log(chalk.white("    cliper analyze --model claude | pbcopy\n"));
+            console.log(chalk.cyan("  Or open directly:"));
+            console.log(chalk.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.green("ChatGPT prompt generated"));
+            console.log(chalk.gray(`\n  Saved: ${outputPath}\n`));
+            console.log(chalk.cyan("  Copy to clipboard:"));
+            console.log(chalk.white(`    cat ${outputPath} | pbcopy\n`));
+        }
+
+    } catch (err: any) {
+        spinner.fail(chalk.red("Analysis failed"));
+        console.error(chalk.red(`\n  ${err.message}\n`));
+        process.exit(1);
+    }
+}

package/src/commands/export.ts

@@ -0,0 +1,33 @@
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+import { getCliperDir } from "../scope/config";
+
+interface ExportOptions {
+  format: string;
+}
+
+export async function exportCommand(options: ExportOptions): Promise<void> {
+  const projectRoot = process.cwd();
+  const contextPath = path.join(getCliperDir(projectRoot), "context.md");
+
+  if (!fs.existsSync(contextPath)) {
+    console.error(chalk.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);
+}

package/src/commands/init.ts

@@ -0,0 +1,174 @@
+import { buildDependencyMap, formatDependencyMap } from "../scanner/dependencies";
+import * as fs from "fs";
+import * as path from "path";
+import simpleGit from "simple-git";
+import chalk from "chalk";
+import ora from "ora";
+import { autoDetectScope } from "../scope/autoScope";
+import { loadScopeConfig, saveScopeConfig, getCliperDir } from "../scope/config";
+import { generateFileTree } from "../scanner/fileTree";
+import { extractFileContents } from "../scanner/fileContent";
+import { getGitContext } from "../scanner/gitContext";
+import { resolveBlockedReferences } from "../resolver/urlFetcher";
+import { detectGaps } from "../gaps/detector";
+import { buildContextDoc } from "../context/builder";
+
+
+
+interface InitOptions {
+  path: string;
+  maxFileSize?: number;
+}
+
+
+export async function initCommand(options: InitOptions): Promise<void> {
+  const projectRoot = path.resolve(options.path);
+
+  if (!fs.existsSync(projectRoot)) {
+    console.error(chalk.red(`Project path not found: ${projectRoot}`));
+    process.exit(1);
+  }
+
+  console.log(chalk.bold.cyan("\n  cliper init\n"));
+  console.log(chalk.gray(`  Project: ${projectRoot}\n`));
+
+  // Step 1: Load or create scope config
+  const spinner = ora("Detecting scope from git activity...").start();
+  let scopeConfig = loadScopeConfig(projectRoot);
+
+  // Always re-run auto-detection and merge with any manual additions
+  const autoScope = await autoDetectScope(projectRoot);
+  const manualAdditions = scopeConfig.active.filter((p) => !autoScope.includes(p));
+  scopeConfig.active = [...new Set([...autoScope, ...manualAdditions])];
+  saveScopeConfig(projectRoot, scopeConfig);
+  spinner.succeed(
+    chalk.green(`Scope detected: ${scopeConfig.active.length} paths active, ${scopeConfig.watched.length} watched`)
+  );
+
+  // Step 2: Generate file tree
+  const treeSpinner = ora("Building annotated file tree...").start();
+  const fileTree = generateFileTree(projectRoot, scopeConfig.active, scopeConfig.watched);
+  treeSpinner.succeed(chalk.green("File tree built"));
+
+  // Step 3: Extract file contents
+  const contentSpinner = ora("Extracting file contents within scope...").start();
+  const files = await extractFileContents(
+    projectRoot,
+    scopeConfig.active,
+    scopeConfig.watched,
+    options.maxFileSize ?? 50
+  );
+
+  contentSpinner.succeed(chalk.green(`Extracted ${files.length} files`));
+
+  // Step 4: Git context
+  const gitSpinner = ora("Reading git context...").start();
+  const gitContext = await getGitContext(projectRoot);
+  gitSpinner.succeed(
+    gitContext.isGitRepo
+      ? chalk.green(`Git: ${gitContext.branch} — ${gitContext.lastCommit?.message ?? "no commits"}`)
+      : chalk.yellow("Not a git repository")
+  );
+
+  // Step 5: Resolve blocked references
+  const refSpinner = ora("Fetching blocked external references...").start();
+  const references = await resolveBlockedReferences(projectRoot);
+  const fetched = references.filter((r) => r.status === "fetched").length;
+  const failed = references.filter((r) => r.status === "failed").length;
+  refSpinner.succeed(chalk.green(`References: ${fetched} fetched, ${failed} failed`));
+
+
+  // Step 6: Detect gaps
+
+
+
+  const gapSpinner = ora("Detecting gaps and undocumented patterns...").start();
+  const gaps = detectGaps(files, projectRoot);
+  gapSpinner.succeed(
+    gaps.length > 0
+      ? chalk.yellow(`Found ${gaps.length} gaps (${gaps.filter((g) => g.severity === "high").length} high priority)`)
+      : chalk.green("No significant gaps detected")
+  );
+  const depSpinner = ora("Mapping dependencies...").start();
+  const dependencyMap = buildDependencyMap(files);
+  depSpinner.succeed(chalk.green(`Dependency map: ${dependencyMap.edges.length} edges, ${dependencyMap.externalPackages.length} external packages`));
+
+  // Step 7: Build context doc
+  const buildSpinner = ora("Building context document...").start();
+  const projectName = path.basename(projectRoot);
+  const contextDoc = buildContextDoc({
+    projectRoot,
+    projectName,
+    activeScope: scopeConfig.active,
+    watchedScope: scopeConfig.watched,
+    fileTree,
+    files,
+    gitContext,
+    references,
+    gaps,
+    generatedAt: new Date().toISOString(),
+    dependencyMap: formatDependencyMap(dependencyMap),
+  });
+
+  // Step 8: Write to disk
+  const cliperDir = getCliperDir(projectRoot);
+  if (!fs.existsSync(cliperDir)) fs.mkdirSync(cliperDir, { recursive: true });
+  const contextPath = path.join(cliperDir, "context.md");
+  fs.writeFileSync(contextPath, contextDoc, "utf-8");
+  buildSpinner.succeed(chalk.green("Context document built"));
+
+  // Auto-manage .gitignore — add anything cliper introduces that shouldn't be committed
+  const gitignorePath = path.join(projectRoot, ".gitignore");
+
+  const entriesToEnsure: Array<{ check: string; line: string }> = [
+    { check: "node_modules", line: "node_modules/" },
+    { check: "package-lock.json", line: "package-lock.json" },
+    { check: ".cliper/cache", line: ".cliper/cache/" },
+    { check: ".cliper/prompt-", line: ".cliper/prompt-*.md" },
+  ];
+
+  let gitignoreContent = fs.existsSync(gitignorePath)
+    ? fs.readFileSync(gitignorePath, "utf-8")
+    : "";
+
+  const missingEntries = entriesToEnsure.filter((e) => !gitignoreContent.includes(e.check));
+
+  if (missingEntries.length > 0) {
+    const block = "\n# Cliper — auto-managed\n" + missingEntries.map((e) => e.line).join("\n") + "\n";
+    if (fs.existsSync(gitignorePath)) {
+      fs.appendFileSync(gitignorePath, block);
+    } else {
+      fs.writeFileSync(gitignorePath, block.trimStart());
+    }
+  }
+
+  // Remove node_modules from git tracking if accidentally staged
+  try {
+    const gitInstance = simpleGit(projectRoot);
+    const tracked = await gitInstance.raw(["ls-files", "node_modules"]);
+    if (tracked.trim().length > 0) {
+      await gitInstance.raw(["rm", "-r", "--cached", "node_modules/"]);
+      console.log(chalk.yellow("  ⚡ Removed node_modules from git tracking"));
+    }
+    const lockTracked = await gitInstance.raw(["ls-files", "package-lock.json"]);
+    if (lockTracked.trim().length > 0) {
+      await gitInstance.raw(["rm", "--cached", "package-lock.json"]);
+      console.log(chalk.yellow("  ⚡ Removed package-lock.json from git tracking"));
+    }
+  } catch {
+    // Not a git repo or already clean — skip silently
+  }
+
+  // Summary
+  const sizeKB = Math.round(Buffer.byteLength(contextDoc, "utf-8") / 1024);
+  const estimatedTokens = Math.round(contextDoc.length / 4);
+
+  console.log(chalk.bold.green("\n  ✓ Context document ready\n"));
+  console.log(chalk.gray(`  Location:  ${contextPath}`));
+  console.log(chalk.gray(`  Size:      ${sizeKB}KB (~${estimatedTokens.toLocaleString()} tokens)`));
+  console.log(chalk.gray(`  Files:     ${files.length} files in context`));
+  console.log(chalk.gray(`  Gaps:      ${gaps.length} detected\n`));
+  console.log(chalk.cyan("  Copy to clipboard:"));
+  console.log(chalk.white("    cliper export | pbcopy        # macOS"));
+  console.log(chalk.white("    cliper export | xclip         # Linux\n"));
+}

package/src/commands/scope.ts

@@ -0,0 +1,77 @@
+import * as path from "path";
+import chalk from "chalk";
+import { loadScopeConfig, saveScopeConfig } from "../scope/config";
+
+export async function scopeCommand(action: string, scopePath?: string): Promise<void> {
+  const projectRoot = process.cwd();
+  const config = loadScopeConfig(projectRoot);
+
+  switch (action) {
+    case "add": {
+      if (!scopePath) { console.error(chalk.red("  Please provide a path.")); process.exit(1); }
+      const normalized = path.normalize(scopePath);
+      if (!config.active.includes(normalized)) {
+        config.active.push(normalized);
+        saveScopeConfig(projectRoot, config);
+        console.log(chalk.green(`\n  ✓ Added to active scope: ${normalized}\n`));
+        console.log(chalk.gray("  Run cliper sync to update the context doc.\n"));
+      } else {
+        console.log(chalk.yellow(`\n  Already in scope: ${normalized}\n`));
+      }
+      break;
+    }
+
+    case "watch": {
+      if (!scopePath) { console.error(chalk.red("  Please provide a path.")); process.exit(1); }
+      const normalized = path.normalize(scopePath);
+      if (config.watched.length >= 15) {
+        console.log(chalk.yellow("\n  Watch list is capped at 15 files. Remove one first:\n"));
+        console.log(chalk.gray("  cliper scope remove <path>\n"));
+        process.exit(1);
+      }
+      if (!config.watched.includes(normalized)) {
+        config.watched.push(normalized);
+        saveScopeConfig(projectRoot, config);
+        console.log(chalk.green(`\n  ✓ Added to watch list: ${normalized}\n`));
+      } else {
+        console.log(chalk.yellow(`\n  Already watched: ${normalized}\n`));
+      }
+      break;
+    }
+
+    case "remove": {
+      if (!scopePath) { console.error(chalk.red("  Please provide a path.")); process.exit(1); }
+      const normalized = path.normalize(scopePath);
+      config.active = config.active.filter((p) => p !== normalized);
+      config.watched = config.watched.filter((p) => p !== normalized);
+      saveScopeConfig(projectRoot, config);
+      console.log(chalk.green(`\n  ✓ Removed from scope: ${normalized}\n`));
+      break;
+    }
+
+    case "list": {
+      console.log(chalk.bold.cyan("\n  Current Scope\n"));
+      if (config.active.length === 0 && config.watched.length === 0) {
+        console.log(chalk.gray("  No scope configured. Run cliper init to auto-detect.\n"));
+        break;
+      }
+      if (config.active.length > 0) {
+        console.log(chalk.bold("  Active scope:"));
+        for (const p of config.active) console.log(chalk.white(`    • ${p}`));
+      }
+      if (config.watched.length > 0) {
+        console.log(chalk.bold("\n  Watch list:"));
+        for (const p of config.watched) console.log(chalk.white(`    • ${p}`));
+        console.log(chalk.gray(`\n  (${config.watched.length}/15 watch slots used)`));
+      }
+      console.log();
+      break;
+    }
+
+    default: {
+      console.error(chalk.red(`\n  Unknown action: ${action}`));
+      console.log(chalk.gray("  Usage: cliper scope <add|remove|watch|list> [path]\n"));
+      process.exit(1);
+    }
+  }
+}

package/src/commands/status.ts

@@ -0,0 +1,67 @@
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+import { loadScopeConfig, getCliperDir } from "../scope/config";
+import { getGitContext } from "../scanner/gitContext";
+
+export async function statusCommand(): Promise<void> {
+  const projectRoot = process.cwd();
+  const cliperDir = getCliperDir(projectRoot);
+  const contextPath = path.join(cliperDir, "context.md");
+  const config = loadScopeConfig(projectRoot);
+
+  console.log(chalk.bold.cyan("\n  cliper status\n"));
+
+  // Context doc status
+  if (!fs.existsSync(contextPath)) {
+    console.log(chalk.red("  ✗ No context doc found"));
+    console.log(chalk.gray("    Run: cliper init\n"));
+    return;
+  }
+
+  const stat = fs.statSync(contextPath);
+  const ageMs = Date.now() - stat.mtime.getTime();
+  const ageHours = Math.floor(ageMs / 3600000);
+  const ageMins = Math.floor(ageMs / 60000);
+  const ageStr = ageHours > 0 ? `${ageHours}h ago` : `${ageMins}m ago`;
+  const sizeKB = Math.round(stat.size / 1024);
+  const isFresh = ageMs < 3600000; // < 1 hour
+
+  console.log(
+    isFresh
+      ? chalk.green(`  ✓ Context doc is fresh`)
+      : chalk.yellow(`  ⚡ Context doc may be stale`)
+  );
+  console.log(chalk.gray(`    Last updated: ${ageStr} | Size: ${sizeKB}KB`));
+  console.log(chalk.gray(`    Path: ${contextPath}`));
+
+  // Scope status
+  console.log(chalk.bold("\n  Scope:"));
+  if (config.active.length === 0) {
+    console.log(chalk.gray("    No active scope. Run cliper init to auto-detect."));
+  } else {
+    for (const p of config.active) console.log(chalk.white(`    • ${p}  `) + chalk.cyan("[active]"));
+    for (const p of config.watched) console.log(chalk.white(`    • ${p}  `) + chalk.blue("[watched]"));
+  }
+
+  // Git status
+  const git = await getGitContext(projectRoot);
+  if (git.isGitRepo) {
+    console.log(chalk.bold("\n  Git:"));
+    console.log(chalk.gray(`    Branch:  ${git.branch}`));
+    if (git.lastCommit) {
+      console.log(chalk.gray(`    Latest:  ${git.lastCommit.hash} — ${git.lastCommit.message} (${git.lastCommit.timeAgo})`));
+    }
+    if (git.uncommittedChanges.length > 0) {
+      console.log(chalk.yellow(`    Uncommitted: ${git.uncommittedChanges.length} files changed`));
+      if (ageMs > 600000) {
+        // Context is older than 10 mins and there are uncommitted changes
+        console.log(chalk.yellow("\n  ⚡ Changes detected since last context update."));
+        console.log(chalk.gray("    Run: cliper sync\n"));
+        return;
+      }
+    }
+  }
+
+  console.log();
+}