ctxshot 0.1.0 → 0.2.0

package/README.md

@@ -14,6 +14,25 @@ npx ctxshot --compact -o .ai/context.md
 npx ctxshot --diff
 ```
 
+### MCP（Claude Code / Cursor）
+
+```bash
+npx ctxshot-mcp   # stdio MCP server
+```
+
+```json
+{
+  "mcpServers": {
+    "ctxshot": {
+      "command": "npx",
+      "args": ["-y", "ctxshot-mcp@latest"]
+    }
+  }
+}
+```
+
+Tools: `session_brief`（每日写 `.ai/context.md`）· `pack_context` · `context_stats`
+
 每次新开 Claude Code / Cursor 会话都要重新解释项目？复制整份 README 又费 token。`ctxshot` 把「项目全貌」压成一份 **AI-ready brief**，成为你每天的固定起手式。
 
 ---

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -3,10 +3,8 @@ import { parseArgs } from "node:util";
 import { writeFileSync, mkdirSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import pc from "picocolors";
-import { buildTree, readManifests, readContextSnippets } from "./scan.js";
-import { gitSummary } from "./git.js";
-import { formatBrief } from "./format.js";
-const VERSION = "0.1.0";
+import { packContext } from "./core/pack.js";
+const VERSION = "0.2.0";
 function help() {
     console.log(`
 ${pc.bold("ctxshot")} — 开 AI 编程会话前，3 秒打包项目上下文（结构 / 脚本 / 最近改动）。
@@ -29,7 +27,7 @@ ${pc.bold("ctxshot")} — 开 AI 编程会话前，3 秒打包项目上下文（
   npx ctxshot --compact -o .ai/context.md
   npx ctxshot --diff
 
-Part of AI Ship Kit → evaldrift + mcp-quickstart + ctxshot
+MCP: npx ctxshot-mcp — pack_context / session_brief tools for Claude Code & Cursor
 `);
 }
 async function main() {
@@ -55,19 +53,21 @@ async function main() {
     }
     const root = resolve(process.cwd());
     const compact = values.compact ?? false;
-    const depth = values.depth ? parseInt(values.depth, 10) : compact ? 2 : 3;
-    const maxEntries = values.max ? parseInt(values.max, 10) : compact ? 50 : 80;
-    const tree = buildTree({ root, maxDepth: depth, maxEntries });
-    const manifests = readManifests(root);
-    const snippets = readContextSnippets(root, compact);
-    const git = gitSummary(root, values.diff ?? false);
-    const text = formatBrief({ root, tree, manifests, snippets, git, compact });
+    const depth = values.depth ? parseInt(values.depth, 10) : undefined;
+    const maxEntries = values.max ? parseInt(values.max, 10) : undefined;
+    const { markdown: text, stats } = packContext({
+        root,
+        compact,
+        diff: values.diff ?? false,
+        depth,
+        maxEntries,
+    });
     if (values.out) {
         const outPath = resolve(root, values.out);
         mkdirSync(dirname(outPath), { recursive: true });
         writeFileSync(outPath, text, "utf8");
         console.error(pc.green(`已写入 ${values.out}`));
-        console.error(pc.dim(`${text.split("\n").length} 行，约 ${Math.round(text.length / 4)} tokens（粗估）`));
+        console.error(pc.dim(`${stats.lineCount} 行，约 ${stats.estimatedTokens} tokens（粗估）`));
     }
     else {
         console.log(text);

package/dist/core/format.d.ts

@@ -0,0 +1,12 @@
+import type { ManifestSummary } from "./scan.js";
+import type { GitSummary } from "./git.js";
+export interface FormatOptions {
+    root: string;
+    tree: string[];
+    manifests: ManifestSummary[];
+    snippets: string[];
+    git: GitSummary | null;
+    compact: boolean;
+}
+export declare function estimateTokens(text: string): number;
+export declare function formatBrief(opts: FormatOptions): string;

package/dist/core/format.js

@@ -0,0 +1,75 @@
+export function estimateTokens(text) {
+    return Math.round(text.length / 4);
+}
+export function formatBrief(opts) {
+    const lines = [];
+    lines.push("# Project context (ctxshot)");
+    lines.push("");
+    lines.push(`Root: \`${opts.root}\``);
+    const bodyPreview = [
+        ...opts.tree,
+        ...opts.snippets,
+        JSON.stringify(opts.manifests),
+    ].join("\n");
+    const estTokens = estimateTokens(bodyPreview);
+    lines.push(`Mode: ${opts.compact ? "compact · daily session brief" : "full"} · ~${estTokens} tokens (estimate)`);
+    lines.push(`Note: lightweight overview only — for full file contents use [Repomix](https://repomix.com).`);
+    lines.push("");
+    if (opts.git) {
+        lines.push("## Git");
+        if (opts.git.branch)
+            lines.push(`- Branch: \`${opts.git.branch}\``);
+        if (opts.git.recentCommits.length) {
+            lines.push("- Recent commits:");
+            for (const c of opts.git.recentCommits)
+                lines.push(`  - ${c}`);
+        }
+        if (opts.git.diffStat) {
+            lines.push("- Uncommitted diff stat:");
+            lines.push("```");
+            lines.push(opts.git.diffStat);
+            lines.push("```");
+        }
+        if (opts.git.changedFiles.length) {
+            lines.push("- Changed / untracked files:");
+            for (const f of opts.git.changedFiles)
+                lines.push(`  - ${f}`);
+        }
+        lines.push("");
+    }
+    if (opts.manifests.length) {
+        lines.push("## Scripts & stack");
+        for (const m of opts.manifests) {
+            lines.push(`### ${m.kind}`);
+            if (m.extra?.length) {
+                for (const e of m.extra)
+                    lines.push(`- ${e}`);
+            }
+            if (m.scripts && Object.keys(m.scripts).length) {
+                const keys = opts.compact
+                    ? ["dev", "build", "test", "start", "lint"].filter((k) => m.scripts[k])
+                    : Object.keys(m.scripts);
+                for (const k of keys) {
+                    lines.push(`- \`${k}\`: ${m.scripts[k]}`);
+                }
+            }
+            if (m.deps?.length) {
+                lines.push(`- Key deps: ${m.deps.join(", ")}`);
+            }
+            lines.push("");
+        }
+    }
+    if (opts.snippets.length) {
+        lines.push("## Existing instructions");
+        lines.push(...opts.snippets);
+        lines.push("");
+    }
+    lines.push("## Project tree");
+    lines.push("```");
+    lines.push(...opts.tree);
+    lines.push("```");
+    lines.push("");
+    lines.push("---");
+    lines.push("Tip: re-run `pack_context` / `npx ctxshot` after major refactors.");
+    return lines.join("\n");
+}

package/dist/core/git.d.ts

@@ -0,0 +1,8 @@
+export declare function isGitRepo(root: string): boolean;
+export interface GitSummary {
+    branch: string | null;
+    recentCommits: string[];
+    diffStat: string | null;
+    changedFiles: string[];
+}
+export declare function gitSummary(root: string, withDiff: boolean): GitSummary | null;

package/dist/core/git.js

@@ -0,0 +1,35 @@
+import { execSync } from "node:child_process";
+function run(cmd, cwd) {
+    try {
+        return execSync(cmd, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function isGitRepo(root) {
+    return run("git rev-parse --is-inside-work-tree", root) === "true";
+}
+export function gitSummary(root, withDiff) {
+    if (!isGitRepo(root))
+        return null;
+    const branch = run("git branch --show-current", root);
+    const log = run("git log -5 --oneline", root);
+    const recentCommits = log ? log.split("\n").filter(Boolean) : [];
+    let diffStat = null;
+    let changedFiles = [];
+    if (withDiff) {
+        diffStat = run("git diff --stat", root);
+        const names = run("git diff --name-only", root);
+        changedFiles = names ? names.split("\n").filter(Boolean).slice(0, 30) : [];
+        const untracked = run("git ls-files --others --exclude-standard", root);
+        if (untracked) {
+            changedFiles.push(...untracked.split("\n").filter(Boolean).slice(0, 10));
+        }
+    }
+    return { branch, recentCommits, diffStat, changedFiles };
+}

package/dist/core/ignore.d.ts

@@ -0,0 +1,4 @@
+declare const DEFAULT_IGNORE: Set<string>;
+export declare function loadGitignore(root: string): Set<string>;
+export declare function shouldIgnore(relPath: string, name: string, gitignore: Set<string>, extra?: Set<string>): boolean;
+export { DEFAULT_IGNORE };

package/dist/core/ignore.js

@@ -0,0 +1,62 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+const DEFAULT_IGNORE = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    "coverage",
+    ".turbo",
+    ".cache",
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".idea",
+    ".vscode",
+    "target",
+    "vendor",
+    ".ai",
+]);
+export function loadGitignore(root) {
+    const patterns = new Set();
+    const file = join(root, ".gitignore");
+    if (!existsSync(file))
+        return patterns;
+    const lines = readFileSync(file, "utf8").split(/\r?\n/);
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        patterns.add(line.replace(/\/$/, ""));
+    }
+    return patterns;
+}
+function matchPattern(name, pattern) {
+    if (pattern.startsWith("*.")) {
+        return name.endsWith(pattern.slice(1));
+    }
+    if (pattern.includes("*")) {
+        const re = new RegExp("^" + pattern.replace(/\./g, "\\.").replace(/\*/g, ".*") + "$");
+        return re.test(name);
+    }
+    return (name === pattern ||
+        name.endsWith("/" + pattern) ||
+        name.startsWith(pattern + "/"));
+}
+export function shouldIgnore(relPath, name, gitignore, extra = DEFAULT_IGNORE) {
+    if (extra.has(name))
+        return true;
+    const parts = relPath.split(/[/\\]/);
+    for (const part of parts) {
+        if (extra.has(part))
+            return true;
+        for (const p of gitignore) {
+            if (matchPattern(part, p) || matchPattern(relPath, p))
+                return true;
+        }
+    }
+    return false;
+}
+export { DEFAULT_IGNORE };

package/dist/core/index.d.ts

@@ -0,0 +1,5 @@
+export { packContext, type PackOptions, type PackResult, type ContextStats } from "./pack.js";
+export { formatBrief, estimateTokens, type FormatOptions } from "./format.js";
+export { buildTree, readManifests, readContextSnippets, type TreeOptions, type ManifestSummary } from "./scan.js";
+export { gitSummary, isGitRepo, type GitSummary } from "./git.js";
+export { loadGitignore, shouldIgnore, DEFAULT_IGNORE } from "./ignore.js";

package/dist/core/index.js

@@ -0,0 +1,5 @@
+export { packContext } from "./pack.js";
+export { formatBrief, estimateTokens } from "./format.js";
+export { buildTree, readManifests, readContextSnippets } from "./scan.js";
+export { gitSummary, isGitRepo } from "./git.js";
+export { loadGitignore, shouldIgnore, DEFAULT_IGNORE } from "./ignore.js";

package/dist/core/pack.d.ts

@@ -0,0 +1,22 @@
+export interface PackOptions {
+    /** Project root (default: process.cwd()) */
+    root?: string;
+    compact?: boolean;
+    diff?: boolean;
+    depth?: number;
+    maxEntries?: number;
+}
+export interface ContextStats {
+    estimatedTokens: number;
+    lineCount: number;
+    treeLineCount: number;
+    compact: boolean;
+    hasGit: boolean;
+    manifestCount: number;
+}
+export interface PackResult {
+    markdown: string;
+    stats: ContextStats;
+    root: string;
+}
+export declare function packContext(opts?: PackOptions): PackResult;

package/dist/core/pack.js

@@ -0,0 +1,35 @@
+import { resolve } from "node:path";
+import { buildTree, readManifests, readContextSnippets } from "./scan.js";
+import { gitSummary } from "./git.js";
+import { formatBrief, estimateTokens } from "./format.js";
+export function packContext(opts = {}) {
+    const root = resolve(opts.root ?? process.cwd());
+    const compact = opts.compact ?? false;
+    const diff = opts.diff ?? false;
+    const depth = opts.depth ?? (compact ? 2 : 3);
+    const maxEntries = opts.maxEntries ?? (compact ? 50 : 80);
+    const tree = buildTree({ root, maxDepth: depth, maxEntries });
+    const manifests = readManifests(root);
+    const snippets = readContextSnippets(root, compact);
+    const git = gitSummary(root, diff);
+    const markdown = formatBrief({
+        root,
+        tree,
+        manifests,
+        snippets,
+        git,
+        compact,
+    });
+    return {
+        markdown,
+        root,
+        stats: {
+            estimatedTokens: estimateTokens(markdown),
+            lineCount: markdown.split("\n").length,
+            treeLineCount: tree.length,
+            compact,
+            hasGit: git !== null,
+            manifestCount: manifests.length,
+        },
+    };
+}

package/dist/core/scan.d.ts

@@ -0,0 +1,14 @@
+export interface TreeOptions {
+    root: string;
+    maxDepth: number;
+    maxEntries: number;
+}
+export declare function buildTree(opts: TreeOptions): string[];
+export interface ManifestSummary {
+    kind: string;
+    scripts?: Record<string, string>;
+    deps?: string[];
+    extra?: string[];
+}
+export declare function readManifests(root: string): ManifestSummary[];
+export declare function readContextSnippets(root: string, compact: boolean): string[];

package/dist/core/scan.js

@@ -0,0 +1,122 @@
+import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { shouldIgnore, loadGitignore } from "./ignore.js";
+export function buildTree(opts) {
+    const gitignore = loadGitignore(opts.root);
+    const lines = [];
+    let count = 0;
+    function walk(dir, depth, prefix) {
+        if (depth > opts.maxDepth || count >= opts.maxEntries)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir).sort((a, b) => a.localeCompare(b));
+        }
+        catch {
+            return;
+        }
+        const visible = entries.filter((name) => {
+            const rel = relative(opts.root, join(dir, name)).replace(/\\/g, "/");
+            return !shouldIgnore(rel, name, gitignore);
+        });
+        for (let i = 0; i < visible.length; i++) {
+            if (count >= opts.maxEntries) {
+                lines.push(`${prefix}… (${opts.maxEntries} entries max)`);
+                return;
+            }
+            const name = visible[i];
+            const full = join(dir, name);
+            const last = i === visible.length - 1;
+            const branch = last ? "└── " : "├── ";
+            const childPrefix = prefix + (last ? "    " : "│   ");
+            let label = name;
+            try {
+                if (statSync(full).isDirectory()) {
+                    label += "/";
+                    lines.push(prefix + branch + label);
+                    count++;
+                    walk(full, depth + 1, childPrefix);
+                }
+                else {
+                    lines.push(prefix + branch + label);
+                    count++;
+                }
+            }
+            catch {
+                lines.push(prefix + branch + label);
+                count++;
+            }
+        }
+    }
+    lines.push(".");
+    walk(opts.root, 1, "");
+    return lines;
+}
+export function readManifests(root) {
+    const out = [];
+    const pkg = join(root, "package.json");
+    if (existsSync(pkg)) {
+        try {
+            const j = JSON.parse(readFileSync(pkg, "utf8"));
+            const deps = [
+                ...Object.keys(j.dependencies ?? {}),
+                ...Object.keys(j.devDependencies ?? {}),
+            ].slice(0, 12);
+            out.push({
+                kind: `package.json${j.name ? ` (${j.name})` : ""}`,
+                scripts: j.scripts,
+                deps,
+            });
+        }
+        catch {
+            out.push({ kind: "package.json (parse error)" });
+        }
+    }
+    const py = join(root, "pyproject.toml");
+    if (existsSync(py)) {
+        const text = readFileSync(py, "utf8");
+        const scripts = {};
+        const match = text.match(/\[project\.scripts\]([\s\S]*?)(?:\[|$)/);
+        if (match) {
+            for (const line of match[1].split("\n")) {
+                const m = line.match(/^(\w[\w-]*)\s*=\s*"(.+)"\s*$/);
+                if (m)
+                    scripts[m[1]] = m[2];
+            }
+        }
+        out.push({
+            kind: "pyproject.toml",
+            scripts: Object.keys(scripts).length ? scripts : undefined,
+        });
+    }
+    const go = join(root, "go.mod");
+    if (existsSync(go)) {
+        const first = readFileSync(go, "utf8").split("\n")[0];
+        out.push({ kind: "go.mod", extra: [first.trim()] });
+    }
+    return out;
+}
+const CONTEXT_FILES = ["AGENTS.md", "CLAUDE.md", ".cursor/rules", "README.md"];
+export function readContextSnippets(root, compact) {
+    const snippets = [];
+    const limit = compact ? 400 : 1200;
+    for (const rel of CONTEXT_FILES) {
+        const full = join(root, rel);
+        if (!existsSync(full))
+            continue;
+        try {
+            const st = statSync(full);
+            if (st.isDirectory())
+                continue;
+            const text = readFileSync(full, "utf8").trim();
+            if (!text)
+                continue;
+            const body = text.length > limit ? text.slice(0, limit) + "\n…(truncated)" : text;
+            snippets.push(`### ${rel}\n\n${body}`);
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return snippets;
+}

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "ctxshot",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pack your repo into a compact AI-ready context brief in 3 seconds — before every Claude / Cursor session.",
   "type": "module",
   "bin": {
     "ctxshot": "dist/cli.js"
   },
+  "exports": {
+    ".": "./dist/cli.js",
+    "./core": "./dist/core/index.js"
+  },
   "files": [
     "dist",
     "README.md",
@@ -17,7 +21,8 @@
     "dev": "tsx src/cli.ts",
     "prepublishOnly": "npm run build && npm run test:smoke",
     "test": "node --test",
-    "test:smoke": "node scripts/ci-smoke.mjs"
+    "test:smoke": "node scripts/ci-smoke.mjs",
+    "benchmark": "node scripts/benchmark.mjs"
   },
   "keywords": [
     "ai",
@@ -26,7 +31,8 @@
     "context",
     "developer-tools",
     "llm",
-    "productivity"
+    "productivity",
+    "mcp"
   ],
   "license": "MIT",
   "engines": {