ctxman 3.0.0 → 3.1.0

package/lib/utils/claude-token-counter.js

@@ -0,0 +1,151 @@
+/**
+ * Claude Token Counter
+ * Exact Claude token counts from Anthropic's count_tokens endpoint.
+ *
+ * tiktoken's encodings are OpenAI's. Claude models use their own tokenizer, which
+ * produces more tokens for the same text (especially for code), and Anthropic does not
+ * publish an offline tokenizer for current models: the API is the only exact source.
+ * Counting generates nothing and is free of charge, but it sends the text to Anthropic,
+ * so callers must only use it when the user asked for it.
+ */
+
+import TokenUtils from './token-utils.js';
+
+// Texts are grouped into requests of about this many cl100k_base tokens. Claude counts
+// a little more than that, which still leaves room in the smallest (200K) window.
+const DEFAULT_BATCH_TOKENS = 120000;
+
+/**
+ * Split a text that is larger than one request into line-aligned pieces
+ * @returns {{text: string, tokens: number}[]}
+ */
+function splitByLines(text, filePath, maxTokens) {
+  const tokens = TokenUtils.calculate(text, filePath);
+  if (tokens <= maxTokens) return [{ text, tokens }];
+
+  const pieces = [];
+  let lines = [];
+  let pieceTokens = 0;
+  for (const line of text.split('\n')) {
+    const lineTokens = TokenUtils.calculate(line + '\n', filePath);
+    if (lines.length > 0 && pieceTokens + lineTokens > maxTokens) {
+      pieces.push({ text: lines.join('\n'), tokens: pieceTokens });
+      lines = [];
+      pieceTokens = 0;
+    }
+    lines.push(line);
+    pieceTokens += lineTokens;
+  }
+  if (lines.length > 0) pieces.push({ text: lines.join('\n'), tokens: pieceTokens });
+  return pieces;
+}
+
+export class ClaudeTokenCounter {
+  /**
+   * @param {object} options
+   * @param {string} options.model - Claude model id, e.g. `claude-opus-5-5`
+   * @param {object} options.client - Anthropic SDK client (or a stand-in with
+   *   `messages.countTokens`)
+   */
+  constructor({ model, client }) {
+    if (!model) throw new Error('A Claude model id is required');
+    this.model = model;
+    this.client = client;
+    this.requests = 0;
+    this.framing = null;
+  }
+
+  /**
+   * Create a counter with the official SDK, which reads ANTHROPIC_API_KEY (or another
+   * configured credential) from the environment
+   * @param {object} options
+   * @param {string} options.model - Claude model id
+   * @param {object} [options.client] - Pre-built client (tests)
+   * @returns {Promise<ClaudeTokenCounter>}
+   */
+  static async create({ model, client } = {}) {
+    if (!client) {
+      let Anthropic;
+      try {
+        ({ default: Anthropic } = await import('@anthropic-ai/sdk'));
+      } catch (_error) {
+        throw new Error(
+          'Counting with the Anthropic API needs the official SDK: npm install @anthropic-ai/sdk'
+        );
+      }
+      client = new Anthropic();
+    }
+    return new ClaudeTokenCounter({ model, client });
+  }
+
+  /**
+   * Count one text as a single user message
+   * @param {string} text - Non-empty text
+   * @returns {Promise<number>} input_tokens reported by the API
+   */
+  async countMessage(text) {
+    this.requests++;
+    const response = await this.client.messages.countTokens({
+      model: this.model,
+      messages: [{ role: 'user', content: text }],
+    });
+    return response.input_tokens;
+  }
+
+  /**
+   * Tokens the API adds for the message framing, measured once with a one-token text
+   * @returns {Promise<number>}
+   */
+  async getFraming() {
+    this.framing ??= Math.max(0, (await this.countMessage('.')) - 1);
+    return this.framing;
+  }
+
+  /**
+   * Count a text, minus the message framing
+   * @param {string} text
+   * @returns {Promise<number>}
+   */
+  async countText(text) {
+    if (!text) return 0;
+    const framing = await this.getFraming();
+    return Math.max(0, (await this.countMessage(text)) - framing);
+  }
+
+  /**
+   * Count many documents in as few requests as the batch size allows
+   * @param {{path: string, content: string}[]} documents
+   * @param {object} [options]
+   * @param {number} [options.batchTokens] - cl100k_base tokens per request
+   * @param {(done: number, total: number) => void} [options.onProgress]
+   * @returns {Promise<{total: number, requests: number, batches: number}>}
+   */
+  async countDocuments(documents, { batchTokens = DEFAULT_BATCH_TOKENS, onProgress } = {}) {
+    const batches = [];
+    let current = [];
+    let currentTokens = 0;
+    for (const doc of documents) {
+      if (!doc.content) continue;
+      for (const piece of splitByLines(doc.content, doc.path, batchTokens)) {
+        if (current.length > 0 && currentTokens + piece.tokens > batchTokens) {
+          batches.push(current);
+          current = [];
+          currentTokens = 0;
+        }
+        current.push(piece.text);
+        currentTokens += piece.tokens;
+      }
+    }
+    if (current.length > 0) batches.push(current);
+
+    const before = this.requests;
+    let total = 0;
+    for (let i = 0; i < batches.length; i++) {
+      total += await this.countText(batches[i].join('\n'));
+      onProgress?.(i + 1, batches.length);
+    }
+    return { total, requests: this.requests - before, batches: batches.length };
+  }
+}
+
+export default ClaudeTokenCounter;

package/lib/utils/cli-output.js

@@ -0,0 +1,17 @@
+/**
+ * Command-line output helpers
+ */
+
+/**
+ * End the process quietly when the reader of stdout goes away (`ctxman pr | head`): the
+ * rest of the output has nowhere to go, and Node's default is an unhandled EPIPE error.
+ * @param {import('stream').Writable} [stream=process.stdout]
+ */
+export function exitOnBrokenPipe(stream = process.stdout) {
+  stream.on('error', (error) => {
+    if (error.code === 'EPIPE') process.exit(0);
+    throw error;
+  });
+}
+
+export default exitOnBrokenPipe;

package/lib/utils/clipboard-utils.js

@@ -6,61 +6,60 @@
 import { execSync } from 'child_process';
 
 class ClipboardUtils {
-    /**
-     * Copy text to system clipboard
-     * @param {string} text - Text to copy
-     * @returns {boolean} Success status
-     */
-    static copy(text) {
+  /**
+   * Copy text to system clipboard
+   * @param {string} text - Text to copy
+   * @returns {boolean} Success status
+   */
+  static copy(text) {
+    try {
+      if (process.platform === 'darwin') {
+        // macOS
+        execSync('pbcopy', { input: text, encoding: 'utf8' });
+      } else if (process.platform === 'linux') {
+        // Linux - try xclip first, then xsel
         try {
-            if (process.platform === 'darwin') {
-                // macOS
-                execSync('pbcopy', { input: text, encoding: 'utf8' });
-            } else if (process.platform === 'linux') {
-                // Linux - try xclip first, then xsel
-                try {
-                    execSync('xclip -selection clipboard', { input: text, encoding: 'utf8' });
-                } catch {
-                    execSync('xsel --clipboard --input', { input: text, encoding: 'utf8' });
-                }
-            } else if (process.platform === 'win32') {
-                // Windows
-                execSync('clip', { input: text, encoding: 'utf8' });
-            } else {
-                throw new Error('Unsupported platform for clipboard');
-            }
-
-            console.log('✅ Context copied to clipboard!');
-            console.log(`📋 ${text.length} characters copied`);
-            return true;
-
-        } catch (error) {
-            console.error('❌ Failed to copy to clipboard:', error.message);
-            return false;
+          execSync('xclip -selection clipboard', { input: text, encoding: 'utf8' });
+        } catch {
+          execSync('xsel --clipboard --input', { input: text, encoding: 'utf8' });
         }
-    }
+      } else if (process.platform === 'win32') {
+        // Windows
+        execSync('clip', { input: text, encoding: 'utf8' });
+      } else {
+        throw new Error('Unsupported platform for clipboard');
+      }
 
-    /**
-     * Check if clipboard is available on current platform
-     * @returns {boolean}
-     */
-    static isAvailable() {
-        const platform = process.platform;
-        return ['darwin', 'linux', 'win32'].includes(platform);
+      console.log('✅ Context copied to clipboard!');
+      console.log(`📋 ${text.length} characters copied`);
+      return true;
+    } catch (error) {
+      console.error('❌ Failed to copy to clipboard:', error.message);
+      return false;
     }
+  }
 
-    /**
-     * Get clipboard command for current platform
-     * @returns {string} Command name
-     */
-    static getCommand() {
-        const commands = {
-            darwin: 'pbcopy',
-            linux: 'xclip',
-            win32: 'clip'
-        };
-        return commands[process.platform] || 'unknown';
-    }
+  /**
+   * Check if clipboard is available on current platform
+   * @returns {boolean}
+   */
+  static isAvailable() {
+    const platform = process.platform;
+    return ['darwin', 'linux', 'win32'].includes(platform);
+  }
+
+  /**
+   * Get clipboard command for current platform
+   * @returns {string} Command name
+   */
+  static getCommand() {
+    const commands = {
+      darwin: 'pbcopy',
+      linux: 'xclip',
+      win32: 'clip',
+    };
+    return commands[process.platform] || 'unknown';
+  }
 }
 
 export default ClipboardUtils;

package/lib/utils/config-utils.js

@@ -14,81 +14,96 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 class ConfigUtils {
-    /**
-     * Find configuration file in standard locations
-     * @param {string} projectRoot - Project root directory
-     * @param {string} filename - Config filename
-     * @returns {string|undefined} Config file path or undefined
-     */
-    static findConfigFile(projectRoot, filename) {
-        const locations = [
-            path.join(__dirname, '..', '..', filename),  // Package root
-            path.join(projectRoot, filename)              // Project root
-        ];
-        return locations.find(loc => fs.existsSync(loc));
+  /**
+   * Find configuration file in standard locations
+   * @param {string} projectRoot - Project root directory
+   * @param {string} filename - Config filename
+   * @returns {string|undefined} Config file path or undefined
+   */
+  static findConfigFile(projectRoot, filename) {
+    const locations = [
+      path.join(__dirname, '..', '..', filename), // Package root
+      path.join(projectRoot, filename), // Project root
+    ];
+    return locations.find((loc) => fs.existsSync(loc));
+  }
+
+  /**
+   * Initialize method filter parser
+   * @param {string} projectRoot - Project root directory
+   * @returns {object|null} MethodFilterParser instance or null
+   */
+  static initMethodFilter(projectRoot) {
+    const paths = {
+      methodInclude: this.findConfigFile(projectRoot, '.methodinclude'),
+      methodIgnore: this.findConfigFile(projectRoot, '.methodignore'),
+    };
+
+    if (!paths.methodInclude && !paths.methodIgnore) {
+      return null;
     }
 
-    /**
-     * Initialize method filter parser
-     * @param {string} projectRoot - Project root directory
-     * @returns {object|null} MethodFilterParser instance or null
-     */
-    static initMethodFilter(projectRoot) {
-        const paths = {
-            methodInclude: this.findConfigFile(projectRoot, '.methodinclude'),
-            methodIgnore: this.findConfigFile(projectRoot, '.methodignore')
-        };
+    return new MethodFilterParser(paths.methodInclude, paths.methodIgnore);
+  }
 
-        if (!paths.methodInclude && !paths.methodIgnore) {
-            return null;
-        }
+  /**
+   * Detect if method filtering is enabled
+   * @param {string} projectRoot - Project root directory
+   * @returns {boolean}
+   */
+  static detectMethodFilters(projectRoot) {
+    const methodIncludePath = this.findConfigFile(projectRoot, '.methodinclude');
+    const methodIgnorePath = this.findConfigFile(projectRoot, '.methodignore');
+    return !!(methodIncludePath || methodIgnorePath);
+  }
 
-        return new MethodFilterParser(paths.methodInclude, paths.methodIgnore);
-    }
+  /**
+   * Initialize git ignore parser
+   * @param {string} projectRoot - Project root directory
+   * @returns {object} GitIgnoreParser instance
+   */
+  static initGitIgnore(projectRoot) {
+    const paths = {
+      contextIgnore: this.findConfigFile(projectRoot, '.contextignore'),
+      contextInclude: this.findConfigFile(projectRoot, '.contextinclude'),
+    };
 
-    /**
-     * Detect if method filtering is enabled
-     * @param {string} projectRoot - Project root directory
-     * @returns {boolean}
-     */
-    static detectMethodFilters(projectRoot) {
-        const methodIncludePath = this.findConfigFile(projectRoot, '.methodinclude');
-        const methodIgnorePath = this.findConfigFile(projectRoot, '.methodignore');
-        return !!(methodIncludePath || methodIgnorePath);
-    }
+    return new GitIgnoreParser(
+      path.join(projectRoot, '.gitignore'),
+      paths.contextIgnore,
+      paths.contextInclude
+    );
+  }
 
-    /**
-     * Initialize git ignore parser
-     * @param {string} projectRoot - Project root directory
-     * @returns {object} GitIgnoreParser instance
-     */
-    static initGitIgnore(projectRoot) {
-        const paths = {
-            contextIgnore: this.findConfigFile(projectRoot, '.contextignore'),
-            contextInclude: this.findConfigFile(projectRoot, '.contextinclude')
-        };
+  /**
+   * Get all config file paths
+   * @param {string} projectRoot - Project root directory
+   * @returns {object} Config paths
+   */
+  /**
+   * Load the user configuration (~/.ctxman/config.json, see docs/LOGGING-AND-UPDATES.md)
+   * @returns {object|null} Parsed config, or null when missing or invalid
+   */
+  static loadUserConfig() {
+    const home = process.env.HOME || process.env.USERPROFILE;
+    if (!home) return null;
 
-        return new GitIgnoreParser(
-            path.join(projectRoot, '.gitignore'),
-            paths.contextIgnore,
-            paths.contextInclude
-        );
+    try {
+      return JSON.parse(fs.readFileSync(path.join(home, '.ctxman', 'config.json'), 'utf8'));
+    } catch (_error) {
+      return null;
     }
+  }
 
-    /**
-     * Get all config file paths
-     * @param {string} projectRoot - Project root directory
-     * @returns {object} Config paths
-     */
-    static getConfigPaths(projectRoot) {
-        return {
-            gitignore: path.join(projectRoot, '.gitignore'),
-            contextIgnore: this.findConfigFile(projectRoot, '.contextignore'),
-            contextInclude: this.findConfigFile(projectRoot, '.contextinclude'),
-            methodInclude: this.findConfigFile(projectRoot, '.methodinclude'),
-            methodIgnore: this.findConfigFile(projectRoot, '.methodignore')
-        };
-    }
+  static getConfigPaths(projectRoot) {
+    return {
+      gitignore: path.join(projectRoot, '.gitignore'),
+      contextIgnore: this.findConfigFile(projectRoot, '.contextignore'),
+      contextInclude: this.findConfigFile(projectRoot, '.contextinclude'),
+      methodInclude: this.findConfigFile(projectRoot, '.methodinclude'),
+      methodIgnore: this.findConfigFile(projectRoot, '.methodignore'),
+    };
+  }
 }
 
 export default ConfigUtils;