turntax 0.1.0 → 0.3.0

package/dist/node/discover.js

@@ -1,6 +1,8 @@
 import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { MAX_DEPTH, addImports, isInstructionFile, isSkippedDir } from '../core/files.js';
+import { MCP_CONFIGS, USER_MCP_PATHS } from '../core/mcp.js';
+import { USER_ROOTS, isUserInstructionFile } from '../core/user.js';
 const MAX_BYTES = 2 * 1024 * 1024;
 function readText(abs) {
     try {
@@ -61,3 +63,46 @@ export function packageScripts(root) {
         return undefined;
     }
 }
+/** Project MCP config files (for example .mcp.json, .cursor/mcp.json). Read-only. */
+export function discoverMcpConfigs(root) {
+    const paths = [...new Set(MCP_CONFIGS.filter((c) => c.scope === 'project').map((c) => c.path))];
+    return paths.flatMap((path) => {
+        const text = readText(join(root, path));
+        return text === null ? [] : [{ path, text }];
+    });
+}
+/**
+ * User-level instruction files and MCP configs in the home directory, with `~/` paths.
+ * Only the folders listed in USER_ROOTS are searched. Read-only.
+ */
+export function discoverUser(home) {
+    const files = new Map();
+    const walk = (rel, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(join(home, rel), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const path = `${rel}/${e.name}`;
+            if (e.isDirectory()) {
+                if (depth > 0 && !isSkippedDir(path))
+                    walk(path, depth - 1);
+            }
+            else if ((e.isFile() || e.isSymbolicLink()) && isUserInstructionFile(path)) {
+                const text = readText(join(home, path));
+                if (text !== null)
+                    files.set(path, { path: `~/${path}`, text });
+            }
+        }
+    };
+    for (const r of USER_ROOTS)
+        walk(r.dir, r.depth);
+    const mcpConfigs = USER_MCP_PATHS.flatMap((path) => {
+        const text = readText(join(home, path));
+        return text === null ? [] : [{ path: `~/${path}`, text }];
+    });
+    return { files: [...files.values()].sort((a, b) => a.path.localeCompare(b.path)), mcpConfigs };
+}

package/dist/node/git.js

@@ -0,0 +1,46 @@
+import { execFileSync } from 'node:child_process';
+import { addImports, isInstructionFile, isSkippedDir } from '../core/files.js';
+import { isMcpConfigFile } from '../core/mcp.js';
+/**
+ * Reads the instruction files and project MCP configs of `root` as they were at a git ref,
+ * without touching the working tree. Paths are relative to `root`, like discover().
+ */
+export async function filesAtRef(root, ref) {
+    const git = (...args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    try {
+        git('rev-parse', '--verify', '--quiet', `${ref}^{commit}`);
+    }
+    catch {
+        throw new Error(`git ref "${ref}" was not found in ${root}`);
+    }
+    // ls-tree prints paths relative to the current directory, so a subfolder of a repository works too.
+    const paths = git('ls-tree', '-r', '--name-only', '-z', ref, '--', '.').split('\0').filter(Boolean);
+    const kept = paths.filter((p) => {
+        const parts = p.split('/');
+        for (let i = 1; i < parts.length; i++)
+            if (isSkippedDir(parts.slice(0, i).join('/')))
+                return false;
+        return true;
+    });
+    const read = (p) => {
+        try {
+            return git('show', `${ref}:./${p}`);
+        }
+        catch {
+            return null;
+        }
+    };
+    const found = new Map();
+    for (const p of kept.filter(isInstructionFile)) {
+        const text = read(p);
+        if (text !== null)
+            found.set(p, { path: p, text });
+    }
+    const all = new Set(kept);
+    await addImports(found, (p) => (all.has(p) ? read(p) : null));
+    const mcpConfigs = kept.filter(isMcpConfigFile).flatMap((p) => {
+        const text = read(p);
+        return text === null ? [] : [{ path: p, text }];
+    });
+    return { files: [...found.values()].sort((a, b) => a.path.localeCompare(b.path)), mcpConfigs, paths: all };
+}

package/dist/node/mcp.js

@@ -0,0 +1,212 @@
+import { spawn } from 'node:child_process';
+import { isAbsolute, resolve } from 'node:path';
+/**
+ * Starts MCP servers and asks them for their tool definitions (initialize + tools/list).
+ * Runs only with --mcp: stdio servers execute the command from the config file.
+ */
+const PROTOCOL_VERSION = '2025-06-18';
+const CLIENT_INFO = { name: 'turntax', version: '0' };
+/** Expands `${VAR}`, `${VAR:-default}` and `${env:VAR}`; returns null when a VS Code `${input:...}` is needed. */
+export function expandVars(value, env) {
+    if (/\$\{input:[^}]+\}/.test(value))
+        return null;
+    return value.replace(/\$\{(?:env:)?([A-Za-z_][\w]*)(?::-([^}]*))?\}/g, (_, name, fallback) => env[name] ?? fallback ?? '');
+}
+function expandAll(server, env) {
+    const one = (v) => (v === undefined ? undefined : expandVars(v, env));
+    const many = (vs) => vs?.map((v) => expandVars(v, env));
+    const map = (m) => m ? Object.fromEntries(Object.entries(m).map(([k, v]) => [k, expandVars(v, env)])) : undefined;
+    const out = { ...server, command: one(server.command), args: many(server.args), env: map(server.env), url: one(server.url), headers: map(server.headers) };
+    const values = [out.command, ...(out.args ?? []), ...Object.values(out.env ?? {}), out.url, ...Object.values(out.headers ?? {})];
+    if (values.some((v) => v === null))
+        return 'needs a value VS Code prompts for (${input:...}); not measured';
+    return out;
+}
+export async function measureServer(server, opts) {
+    const expanded = expandAll(server, opts.env ?? process.env);
+    if (typeof expanded === 'string')
+        return { error: expanded };
+    try {
+        if (expanded.transport === 'stdio')
+            return { tools: await viaStdio(expanded, opts.root, opts.timeoutMs, opts.env ?? process.env) };
+        if (expanded.transport === 'http')
+            return { tools: await viaHttp(expanded, opts.timeoutMs, opts.fetchFn ?? fetch) };
+        return { error: 'legacy SSE transport is not supported; not measured' };
+    }
+    catch (e) {
+        return { error: e.message };
+    }
+}
+async function listTools(rpc, notify) {
+    await rpc('initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: CLIENT_INFO });
+    await notify('notifications/initialized');
+    const tools = [];
+    let cursor;
+    for (let page = 0; page < 50; page++) {
+        const r = await rpc('tools/list', cursor ? { cursor } : {});
+        for (const t of r?.tools ?? [])
+            tools.push({ name: String(t.name), description: t.description, inputSchema: t.inputSchema });
+        cursor = r?.nextCursor;
+        if (!cursor)
+            break;
+    }
+    return tools;
+}
+function viaStdio(server, root, timeoutMs, env) {
+    if (!server.command)
+        return Promise.reject(new Error('no command in the config'));
+    const cwd = server.cwd ? (isAbsolute(server.cwd) ? server.cwd : resolve(root, server.cwd)) : root;
+    // npx and similar launchers are .cmd shims on Windows, which only start through the shell.
+    const windows = process.platform === 'win32';
+    const child = windows
+        ? spawn([server.command, ...(server.args ?? [])].map(cmdQuote).join(' '), { cwd, env: { ...env, ...server.env }, shell: true, windowsHide: true })
+        : spawn(server.command, server.args ?? [], { cwd, env: { ...env, ...server.env }, stdio: ['pipe', 'pipe', 'pipe'] });
+    const pending = new Map();
+    let nextId = 1;
+    let buffer = '';
+    let stderr = '';
+    let failed = null;
+    const failAll = (e) => {
+        failed ??= e;
+        for (const p of pending.values())
+            p.reject(e);
+        pending.clear();
+    };
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+        buffer += chunk;
+        let nl;
+        while ((nl = buffer.indexOf('\n')) >= 0) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!line)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue; // Servers sometimes log to stdout; skip non-JSON lines.
+            }
+            const p = typeof msg?.id === 'number' ? pending.get(msg.id) : undefined;
+            if (!p)
+                continue;
+            pending.delete(msg.id);
+            if (msg.error)
+                p.reject(new Error(`server error: ${msg.error.message ?? 'unknown'}`));
+            else
+                p.resolve(msg.result);
+        }
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (s) => (stderr = (stderr + s).slice(-500)));
+    child.on('error', (e) => failAll(new Error(`could not start "${server.command}": ${e.message}`)));
+    child.on('exit', (code) => failAll(new Error(`exited with code ${code} before answering${stderr.trim() ? `: ${lastLine(stderr)}` : ''}`)));
+    const send = (msg) => child.stdin.write(JSON.stringify(msg) + '\n');
+    const rpc = (method, params) => failed
+        ? Promise.reject(failed)
+        : new Promise((res, rej) => {
+            const id = nextId++;
+            pending.set(id, { resolve: res, reject: rej });
+            send({ jsonrpc: '2.0', id, method, params });
+        });
+    const notify = async (method) => void send({ jsonrpc: '2.0', method });
+    let timer;
+    const timeout = new Promise((_, rej) => {
+        timer = setTimeout(() => rej(new Error(`no answer within ${Math.round(timeoutMs / 1000)}s`)), timeoutMs);
+    });
+    return Promise.race([listTools(rpc, notify), timeout]).finally(() => {
+        clearTimeout(timer);
+        child.removeAllListeners('exit');
+        child.removeAllListeners('error');
+        child.on('error', () => { });
+        // On Windows the server runs under cmd.exe; end the whole process tree, not just the shell.
+        if (windows && child.pid)
+            spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }).on('error', () => { }).unref();
+        else
+            child.kill();
+        child.stdin.destroy();
+        child.stdout.destroy();
+        child.stderr.destroy();
+    });
+}
+/** Quotes one argument for cmd.exe so spaces, quotes and characters such as > & ( ) reach the program unchanged. */
+export function cmdQuote(arg) {
+    if (arg !== '' && !/[\s"&|<>^()%!,;=]/.test(arg))
+        return arg;
+    return '"' + arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1') + '"';
+}
+/** The most useful stderr line: the first that names an error, else the last. */
+function lastLine(s) {
+    const lines = s.trim().split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    return (lines.find((l) => /error|not found|cannot|denied/i.test(l)) ?? lines.at(-1) ?? '').slice(0, 200);
+}
+async function viaHttp(server, timeoutMs, fetchFn) {
+    const url = server.url;
+    let session;
+    let nextId = 1;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const post = async (body) => {
+        const res = await fetchFn(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream',
+                'mcp-protocol-version': PROTOCOL_VERSION,
+                ...(session ? { 'mcp-session-id': session } : {}),
+                ...server.headers,
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}${res.status === 401 || res.status === 403 ? ' (needs authorization)' : ''}`);
+        session = res.headers.get('mcp-session-id') ?? session;
+        return res;
+    };
+    const rpc = async (method, params) => {
+        const id = nextId++;
+        const res = await post({ jsonrpc: '2.0', id, method, params });
+        const type = res.headers.get('content-type') ?? '';
+        const messages = type.includes('text/event-stream') ? sseMessages(await res.text()) : [await res.json()];
+        const msg = messages.find((m) => m?.id === id);
+        if (!msg)
+            throw new Error(`no response to ${method}`);
+        if (msg.error)
+            throw new Error(`server error: ${msg.error.message ?? 'unknown'}`);
+        return msg.result;
+    };
+    const notify = async (method) => void (await post({ jsonrpc: '2.0', method }));
+    try {
+        return await listTools(rpc, notify);
+    }
+    catch (e) {
+        if (controller.signal.aborted)
+            throw new Error(`no answer within ${Math.round(timeoutMs / 1000)}s`);
+        throw e;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** JSON-RPC messages from the `data:` lines of a server-sent event stream. */
+export function sseMessages(text) {
+    const out = [];
+    for (const event of text.split(/\r?\n\r?\n/)) {
+        const data = event
+            .split(/\r?\n/)
+            .filter((l) => l.startsWith('data:'))
+            .map((l) => l.slice(5).trimStart())
+            .join('\n');
+        if (!data)
+            continue;
+        try {
+            out.push(JSON.parse(data));
+        }
+        catch {
+            // Ignore keep-alive and non-JSON events.
+        }
+    }
+    return out;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "turntax",
-  "version": "0.1.0",
-  "description": "Measure the per-turn token tax your AI coding-agent instruction files (CLAUDE.md, AGENTS.md, Cursor/Copilot/Windsurf rules) add to every agent turn.",
+  "version": "0.3.0",
+  "description": "Measure the per-turn token cost of AI coding-agent instruction files (AGENTS.md, CLAUDE.md, Cursor, Copilot, Cline, Roo, Kiro, Windsurf and more) for every agent that reads them.",
   "license": "MIT",
   "author": "TORUT LTD",
   "homepage": "https://github.com/TorutDev/turntax#readme",
@@ -30,13 +30,24 @@
     "prepack": "npm run build"
   },
   "keywords": [
-    "claude-code",
+    "mcp",
     "agents-md",
+    "claude-code",
     "codex",
     "cursor",
     "copilot",
     "gemini-cli",
     "windsurf",
+    "cline",
+    "roo-code",
+    "kiro",
+    "junie",
+    "zed",
+    "continue",
+    "aider",
+    "goose",
+    "amp",
+    "opencode",
     "tokens",
     "context",
     "cli"