tokenlean 0.1.0

package/bin/tl-prompt.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+/**
+ * tl-prompt - Output AI agent instructions for tokenlean tools
+ *
+ * Dynamically discovers all tl-* commands and generates instructions
+ * by calling each with --prompt flag.
+ *
+ * Usage:
+ *   tl-prompt                 # Full instructions (markdown)
+ *   tl-prompt --minimal       # Compact version
+ *   tl-prompt --list          # Simple list
+ */
+
+import { execSync } from 'child_process';
+import { readdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Prompt info for tl-prompt (meta!)
+if (process.argv.includes('--prompt')) {
+  process.exit(0);  // No output - this IS the prompt tool
+}
+
+/**
+ * Discover all tl-* tools and get their prompt info
+ */
+function discoverTools() {
+  const tools = [];
+  const binDir = __dirname;
+
+  const files = readdirSync(binDir)
+    .filter(f => f.startsWith('tl-') && f.endsWith('.mjs') && f !== 'tl-prompt.mjs');
+
+  for (const file of files) {
+    try {
+      const result = execSync(`node "${join(binDir, file)}" --prompt`, {
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+
+      if (result) {
+        const info = JSON.parse(result);
+        tools.push(info);
+      }
+    } catch (e) {
+      // Tool doesn't support --prompt or errored - skip it
+    }
+  }
+
+  return tools;
+}
+
+/**
+ * Group tools by their 'when' category
+ */
+function groupTools(tools) {
+  const groups = {
+    'before-read': { title: 'Before Reading Files', tools: [] },
+    'before-modify': { title: 'Before Modifying Files', tools: [] },
+    'search': { title: 'Searching', tools: [] }
+  };
+
+  for (const tool of tools) {
+    const group = groups[tool.when] || groups['search'];
+    group.tools.push(tool);
+  }
+
+  return groups;
+}
+
+function generateFull(tools) {
+  const groups = groupTools(tools);
+
+  let output = `## tokenlean CLI Tools
+
+Use these tools to explore the codebase efficiently and save context tokens.
+`;
+
+  for (const [key, group] of Object.entries(groups)) {
+    if (group.tools.length === 0) continue;
+
+    output += `
+### ${group.title}
+
+| Command | Purpose |
+|---------|---------|
+`;
+    for (const tool of group.tools) {
+      output += `| \`${tool.name}\` | ${tool.desc} |\n`;
+    }
+  }
+
+  output += `
+### Tips
+
+- Prefer \`tl-symbols\` over reading entire files when you only need signatures
+- Use \`tl-impact\` before refactoring to understand dependencies
+- Check \`tl-context\` to avoid reading unnecessarily large files
+- All tools support \`--help\` for more options
+`;
+
+  return output;
+}
+
+function generateMinimal(tools) {
+  const groups = groupTools(tools);
+
+  let lines = ['## tokenlean Tools', ''];
+
+  for (const [key, group] of Object.entries(groups)) {
+    if (group.tools.length === 0) continue;
+
+    const names = group.tools.map(t => `\`${t.name}\``).join(', ');
+    const label = group.title.replace(' Files', '').toLowerCase();
+    lines.push(`${label}: ${names}`);
+  }
+
+  lines.push('');
+  lines.push('Prefer `tl-symbols` over reading full files. Use `--help` on any command.');
+
+  return lines.join('\n');
+}
+
+function generateList(tools) {
+  return tools.map(t => `${t.name}: ${t.desc}`).join('\n');
+}
+
+// Parse args
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+tl-prompt - Output AI agent instructions for tokenlean tools
+
+Usage:
+  tl-prompt              Full markdown instructions
+  tl-prompt --minimal    Compact version (fewer tokens)
+  tl-prompt --list       Simple list of tools
+  tl-prompt --json       Raw JSON data
+  tl-prompt --help       Show this help
+
+Integration examples:
+  # Add to CLAUDE.md
+  tl-prompt >> CLAUDE.md
+
+  # Add to .cursorrules
+  tl-prompt --minimal >> .cursorrules
+
+  # Use in a hook (regenerate on session start)
+  tl-prompt > .ai-tools.md
+`);
+  process.exit(0);
+}
+
+// Discover tools dynamically
+const tools = discoverTools();
+
+if (tools.length === 0) {
+  console.error('No tools found. Make sure tl-* commands are in the same directory.');
+  process.exit(1);
+}
+
+if (args.includes('--json')) {
+  console.log(JSON.stringify(tools, null, 2));
+} else if (args.includes('--minimal') || args.includes('-m')) {
+  console.log(generateMinimal(tools));
+} else if (args.includes('--list') || args.includes('-l')) {
+  console.log(generateList(tools));
+} else {
+  console.log(generateFull(tools));
+}

package/bin/tl-related.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+/**
+ * tl-related - Find related files (tests, types, usages)
+ *
+ * Given a file, finds its tests, type definitions, and files that import it.
+ * Helps understand what to read before modifying a file.
+ *
+ * Usage: tl-related <file>
+ */
+
+// Prompt info for tl-prompt
+if (process.argv.includes('--prompt')) {
+  console.log(JSON.stringify({
+    name: 'tl-related',
+    desc: 'Find tests, types, and importers of a file',
+    when: 'before-modify',
+    example: 'tl-related src/Button.tsx'
+  }));
+  process.exit(0);
+}
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join, dirname, basename, relative, extname } from 'path';
+import { execSync } from 'child_process';
+import { shellEscape } from '../src/output.mjs';
+
+try { execSync('which rg', { stdio: 'ignore' }); } catch {
+  console.error('⚠️  ripgrep (rg) not found. Install: brew install ripgrep');
+  process.exit(1);
+}
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'android', 'ios', 'dist', 'build', '.expo', '.next'
+]);
+
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== '/') {
+    if (existsSync(join(dir, 'package.json'))) return dir;
+    dir = dirname(dir);
+  }
+  return process.cwd();
+}
+
+function estimateTokens(filePath) {
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    return Math.ceil(content.length / 4);
+  } catch {
+    return 0;
+  }
+}
+
+function formatTokens(tokens) {
+  if (tokens >= 1000) return `${(tokens / 1000).toFixed(1)}k`;
+  return String(tokens);
+}
+
+function findTestFiles(filePath, projectRoot) {
+  const dir = dirname(filePath);
+  const name = basename(filePath, extname(filePath));
+  const tests = [];
+
+  // Common test patterns
+  const patterns = [
+    join(dir, `${name}.test.ts`),
+    join(dir, `${name}.test.tsx`),
+    join(dir, `${name}.spec.ts`),
+    join(dir, `${name}.spec.tsx`),
+    join(dir, '__tests__', `${name}.test.ts`),
+    join(dir, '__tests__', `${name}.test.tsx`),
+    join(dir, '__tests__', `${name}.spec.ts`),
+    join(dir, '__tests__', `${name}.spec.tsx`),
+  ];
+
+  for (const p of patterns) {
+    if (existsSync(p)) {
+      tests.push(p);
+    }
+  }
+
+  return tests;
+}
+
+function findTypeFiles(filePath, projectRoot) {
+  const dir = dirname(filePath);
+  const name = basename(filePath, extname(filePath));
+  const types = [];
+
+  // Check for adjacent type file
+  const typePatterns = [
+    join(dir, `${name}.types.ts`),
+    join(dir, 'types.ts'),
+    join(dir, 'types', `${name}.ts`),
+  ];
+
+  for (const p of typePatterns) {
+    if (existsSync(p)) {
+      types.push(p);
+    }
+  }
+
+  // Check project-wide types directory
+  const globalTypes = join(projectRoot, 'src', 'types');
+  if (existsSync(globalTypes)) {
+    const typeFiles = readdirSync(globalTypes).filter(f => f.endsWith('.ts'));
+    for (const tf of typeFiles.slice(0, 5)) {
+      types.push(join(globalTypes, tf));
+    }
+  }
+
+  return types;
+}
+
+function findImporters(filePath, projectRoot) {
+  const name = basename(filePath, extname(filePath));
+
+  const importers = new Set();
+
+  // Search for files that might import this module
+  try {
+    const result = execSync(
+      `rg -l -g "*.{js,mjs,ts,tsx,jsx}" -e "${shellEscape(name)}" "${shellEscape(projectRoot)}" 2>/dev/null || true`,
+      { encoding: 'utf-8', maxBuffer: 5 * 1024 * 1024 }
+    );
+
+    for (const line of result.trim().split('\n')) {
+      if (!line) continue;
+      if (line === filePath) continue;
+      if (line.includes('.test.') || line.includes('.spec.')) continue;
+      if (line.includes('node_modules')) continue;
+
+      // Verify it's actually an import statement
+      try {
+        const content = readFileSync(line, 'utf-8');
+        // Match: from '...name' or from "...name" or require('...name')
+        const pattern = new RegExp(`(?:from|require)\\s*\\(?\\s*['"][^'"]*\\/${name}(?:\\.m?[jt]sx?)?['"]`);
+        if (pattern.test(content)) {
+          importers.add(line);
+        }
+      } catch { /* skip unreadable files */ }
+    }
+  } catch (e) { /* rg not found or no matches */ }
+
+  return Array.from(importers);
+}
+
+function findSiblings(filePath) {
+  const dir = dirname(filePath);
+  const siblings = [];
+
+  try {
+    const files = readdirSync(dir).filter(f => {
+      const fullPath = join(dir, f);
+      return statSync(fullPath).isFile() &&
+        f !== basename(filePath) &&
+        !f.includes('.test.') &&
+        !f.includes('.spec.') &&
+        (f.endsWith('.ts') || f.endsWith('.tsx'));
+    });
+
+    for (const f of files.slice(0, 5)) {
+      siblings.push(join(dir, f));
+    }
+  } catch (e) { /* permission error */ }
+
+  return siblings;
+}
+
+function printSection(title, files, projectRoot) {
+  if (files.length === 0) return;
+
+  console.log(`\n${title}`);
+  for (const f of files) {
+    const rel = relative(projectRoot, f);
+    const tokens = estimateTokens(f);
+    console.log(`  ${rel} (~${formatTokens(tokens)})`);
+  }
+}
+
+// Main
+const args = process.argv.slice(2);
+const targetFile = args[0];
+
+if (!targetFile) {
+  console.log('\nUsage: claude-related <file>\n');
+  console.log('Finds tests, types, and importers for a given file.');
+  process.exit(1);
+}
+
+const fullPath = join(process.cwd(), targetFile);
+if (!existsSync(fullPath)) {
+  console.error(`File not found: ${targetFile}`);
+  process.exit(1);
+}
+
+const projectRoot = findProjectRoot();
+const relPath = relative(projectRoot, fullPath);
+
+console.log(`\n📎 Related files for: ${relPath}`);
+
+const tests = findTestFiles(fullPath, projectRoot);
+const types = findTypeFiles(fullPath, projectRoot);
+const importers = findImporters(fullPath, projectRoot);
+const siblings = findSiblings(fullPath);
+
+printSection('🧪 Tests', tests, projectRoot);
+printSection('📝 Types', types, projectRoot);
+printSection('📥 Imported by', importers.slice(0, 10), projectRoot);
+printSection('👥 Siblings', siblings, projectRoot);
+
+const totalFiles = tests.length + types.length + Math.min(importers.length, 10) + siblings.length;
+if (totalFiles === 0) {
+  console.log('\n  No related files found.');
+}
+
+// Summary
+const totalTokens = [...tests, ...types, ...importers.slice(0, 10), ...siblings]
+  .reduce((sum, f) => sum + estimateTokens(f), 0);
+
+console.log(`\n📊 Total: ${totalFiles} related files, ~${formatTokens(totalTokens)} tokens`);
+
+if (importers.length > 10) {
+  console.log(`   (${importers.length - 10} more importers not shown)`);
+}
+console.log();