cartotree 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lumina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# 🌲 cartotree
+
+> AI-friendly codebase mapping CLI — annotated directory trees that save tokens, not just space.
+
+[![npm version](https://img.shields.io/npm/v/cartotree)](https://www.npmjs.com/package/cartotree)
+[![license](https://img.shields.io/npm/l/cartotree)](./LICENSE)
+
+---
+
+## The Problem
+
+When you paste your project structure into an AI assistant, two things happen:
+
+1. **Token waste** — Raw `tree` output burns hundreds of tokens on ASCII box characters with zero semantic value.
+2. **Hallucination** — AI has no idea what each folder *does*, so it guesses wrong.
+
+## The Solution
+
+cartotree generates a compact, annotated map of your codebase — folder descriptions, exported functions, and an AI-optimized serialization format that fits your architecture into a fraction of the tokens.
+
+---
+
+## Quick Start
+
+```bash
+npx cartotree
+```
+
+No install required.
+
+---
+
+## Output Formats
+
+### Default — Annotated ASCII Tree
+```
+my-app/
+├── src/                    # Core application source
+│   ├── components/         # Reusable UI components
+│   │   ├── Button.tsx      <Button, ButtonProps>
+│   │   └── Modal.tsx       <Modal, useModal>
+│   ├── hooks/
+│   │   └── useAuth.ts      <useAuth, useUser>
+│   └── services/
+│       └── api.ts          <fetchUser, postData>
+└── package.json
+```
+
+### `--ai` — Token-Optimized Serialization
+```
+# cartotree fmt: name{desc}[children]<exports>
+my-app{Core application source}[src{Core application source}[components{Reusable UI components}[Button.tsx<Button,ButtonProps>,Modal.tsx<Modal,useModal>],hooks[useAuth.ts<useAuth,useUser>],services[api.ts<fetchUser,postData>]],package.json]
+```
+
+### `--json` — JSON Format
+```json
+{
+  "my-app": {
+    "src": {
+      "_desc": "Core application source",
+      "components": {
+        "Button.tsx": ["Button", "ButtonProps"],
+        "Modal.tsx": ["Modal", "useModal"]
+      }
+    }
+  }
+}
+```
+
+---
+
+## Usage
+
+```bash
+# Default annotated ASCII tree
+npx cartotree
+
+# AI-optimized single-line serialization
+npx cartotree --ai
+
+# JSON format
+npx cartotree --json
+
+# Copy to clipboard (paste directly into AI)
+npx cartotree --ai --copy
+
+# Sync into CLAUDE.md / AGENTS.md
+npx cartotree --ai --sync
+
+# Sync into custom file
+npx cartotree --sync .cursorrules
+
+# Limit depth
+npx cartotree --depth 2
+
+# No depth limit
+npx cartotree --full
+
+# Exclude patterns
+npx cartotree --exclude "tests,*.log"
+
+# Disable export parsing
+npx cartotree --no-exports
+```
+
+---
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--ai` | false | AI-optimized compact serialization |
+| `--json` | false | JSON format |
+| `--copy` | false | Copy output to clipboard |
+| `--sync [file]` | CLAUDE.md | Inject into AI config file |
+| `--depth <n>` | 3 | Max traversal depth |
+| `--full` | false | No depth limit |
+| `--exclude <patterns>` | — | Comma-separated exclude patterns |
+| `--no-exports` | false | Disable export parsing |
+
+---
+
+## Configuration
+
+Create `.cartotreerc` in your project root to set persistent defaults:
+
+```json
+{
+  "default": {
+    "ai": true,
+    "exports": false,
+    "depth": 3
+  }
+}
+```
+
+Now `npx cartotree` automatically runs with `--ai --no-exports`.
+
+---
+
+## Folder Annotations
+
+Add a `.folder.md` to any directory — the first line becomes the annotation:
+
+```
+# Reusable UI components
+Atomic design system built with Radix UI primitives.
+```
+
+cartotree also falls back to the first line of `README.md` if no `.folder.md` exists.
+
+---
+
+## Ignoring Files
+
+Create `.cartotreeignore` in your project root:
+
+```
+# .cartotreeignore
+*.log
+temp
+coverage
+.env*
+```
+
+`node_modules`, `.git`, `dist`, `build` are excluded by default.
+
+---
+
+## `--sync` Integration
+
+Running `cartotree --sync` injects the tree between marker tags:
+
+```html
+<!-- CARTOTREE-START -->
+(auto-updated on every sync)
+<!-- CARTOTREE-END -->
+```
+
+Works with `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, or any file.
+
+---
+
+## Export Parsing
+
+cartotree reads your source files and surfaces exported symbols directly in the tree:
+
+```
+hooks/
+└── useAuth.ts  <useAuth, useUser, AuthProvider>
+```
+
+Supports `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs`.
+
+---
+
+## License
+MIT
+
+---

package/bin/cartotree.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const { generateTree } = require('../src/tree');
+const { generateAI, generateJSON } = require('../src/ai');
+const { syncToFile } = require('../src/sync');
+const { copyToClipboard } = require('../src/clipboard');
+const { loadIgnorePatterns } = require('../src/ignore');
+const { loadConfig } = require('../src/config');
+
+program
+  .name('cartotree')
+  .description('AI-friendly annotated directory tree')
+  .version('0.1.0')
+  .option('-d, --depth <number>', 'max depth')
+  .option('-e, --exclude <patterns>', 'exclude patterns (comma-separated)')
+  .option('--ai', 'AI-optimized compact format')
+  .option('--json', 'JSON format')
+  .option('--no-exports', 'disable export parsing')
+  .option('--copy', 'copy to clipboard')
+  .option('--sync [file]', 'sync to CLAUDE.md or specified file')
+  .option('--full', 'no depth limit')
+  .parse(process.argv);
+
+const opts = program.opts();
+const config = loadConfig(process.cwd());
+
+const depth = opts.full ? Infinity : parseInt(opts.depth ?? config.depth);
+const useAI    = opts.ai   || config.ai;
+const useJSON  = opts.json || config.json;
+const useCopy  = opts.copy || config.copy;
+const useSync  = opts.sync || config.sync;
+const showExports = opts.exports ?? config.exports;
+
+const ignorePatterns = loadIgnorePatterns(process.cwd());
+const manualExclude = opts.exclude ? opts.exclude.split(',').map(s => s.trim()) : [];
+const exclude = [...new Set([...ignorePatterns, ...manualExclude])];
+const target = typeof useSync === 'string' ? useSync : 'CLAUDE.md';
+
+let output;
+if (useAI) {
+  output = generateAI(process.cwd(), { depth, exclude, showExports });
+} else if (useJSON) {
+  output = generateJSON(process.cwd(), { depth, exclude, showExports });
+} else {
+  output = generateTree(process.cwd(), { depth, exclude, showExports });
+}
+
+if (useCopy) {
+  copyToClipboard(output);
+} else if (useSync) {
+  syncToFile(output, target);
+} else {
+  console.log(output);
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "cartotree",
+  "version": "0.1.0",
+  "description": "AI-friendly codebase mapping CLI — annotated directory trees that save tokens",
+  "main": "src/tree.js",
+  "bin": {
+    "cartotree": "./bin/cartotree.js"
+  },
+  "keywords": ["cli", "ai", "developer-tools", "tree", "claude", "cursor", "tokens"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kingluminance/cartotree.git"
+  }
+}

package/src/ai.js

@@ -0,0 +1,113 @@
+const fs = require('fs');
+const path = require('path');
+const { shouldIgnore } = require('./ignore');
+const { parseExports } = require('./exports');
+
+const AI_FORMAT_HEADER = '# cartotree fmt: name{desc}[children]<exports>';
+
+function getFolderDescription(dirPath) {
+  const folderMd = path.join(dirPath, '.folder.md');
+  const readmeMd = path.join(dirPath, 'README.md');
+
+  if (fs.existsSync(folderMd)) {
+    return fs.readFileSync(folderMd, 'utf-8').trim().split('\n')[0].replace(/^#\s*/, '');
+  }
+  if (fs.existsSync(readmeMd)) {
+    const first = fs.readFileSync(readmeMd, 'utf-8').trim().split('\n')[0].replace(/^#\s*/, '');
+    if (first.length < 80) return first;
+  }
+  return null;
+}
+
+function buildAINode(entryPath, name, opts, isDir, currentDepth = 0) {
+  if (isDir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(entryPath, { withFileTypes: true });
+    } catch {
+      return `${name}[!]`;
+    }
+
+    const filtered = entries
+      .filter(e => !shouldIgnore(e.name, opts.exclude))
+      .sort((a, b) => {
+        if (a.isDirectory() && !b.isDirectory()) return -1;
+        if (!a.isDirectory() && b.isDirectory()) return 1;
+        return a.name.localeCompare(b.name);
+      });
+
+    const desc = getFolderDescription(entryPath);
+    const descPart = desc ? `{${desc}}` : '';
+
+    if (filtered.length === 0) return `${name}${descPart}[]`;
+
+    if (currentDepth >= opts.depth) {
+      const names = filtered.map(e => e.name + (e.isDirectory() ? '/' : '')).join(',');
+      return `${name}${descPart}[${names}]`;
+    }
+
+    const children = filtered.map(e => {
+      const fullPath = path.join(entryPath, e.name);
+      return buildAINode(fullPath, e.name, opts, e.isDirectory(), currentDepth + 1);
+    });
+
+    return `${name}${descPart}[${children.join(',')}]`;
+  } else {
+  const exports = opts.showExports ? parseExports(entryPath) : null;
+  const exportPart = exports && exports.length > 0
+    ? `<${exports.slice(0, 4).join(',')}${exports.length > 4 ? `+${exports.length - 4}` : ''}>`
+    : '';
+  return `${name}${exportPart}`;
+}
+}
+
+function buildJSONNode(entryPath, opts, currentDepth = 0) {
+  let entries;
+  try {
+    entries = fs.readdirSync(entryPath, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const filtered = entries
+    .filter(e => !shouldIgnore(e.name, opts.exclude))
+    .sort((a, b) => {
+      if (a.isDirectory() && !b.isDirectory()) return -1;
+      if (!a.isDirectory() && b.isDirectory()) return 1;
+      return a.name.localeCompare(b.name);
+    });
+
+  const result = {};
+
+  const desc = getFolderDescription(entryPath);
+  if (desc) result['_desc'] = desc;
+
+  filtered.forEach(entry => {
+    const fullPath = path.join(entryPath, entry.name);
+
+    if (entry.isDirectory()) {
+      result[entry.name] = currentDepth < opts.depth
+        ? buildJSONNode(fullPath, opts, currentDepth + 1)
+        : {};
+    } else {
+      const exports = parseExports(fullPath);
+      result[entry.name] = exports ?? null;
+    }
+  });
+
+  return result;
+}
+
+function generateAI(rootPath, opts) {
+  const rootName = path.basename(rootPath);
+  const node = buildAINode(rootPath, rootName, opts, true);
+  return `${AI_FORMAT_HEADER}\n${node}`;
+}
+
+function generateJSON(rootPath, opts) {
+  const rootName = path.basename(rootPath);
+  const tree = buildJSONNode(rootPath, opts);
+  return JSON.stringify({ [rootName]: tree }, null, 2);
+}
+
+module.exports = { generateAI, generateJSON };

package/src/clipboard.js

@@ -0,0 +1,11 @@
+const clipboardy = require('clipboardy');
+const chalk = require('chalk');
+
+function copyToClipboard(text) {
+    const plain = text.replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, '');
+    clipboardy.writeSync(plain);
+    console.log(chalk.green('✔ Copied to clipboard!'));
+    console.log(chalk.gray('(Color codes stripped for clean paste)'));
+}
+
+module.exports = { copyToClipboard };

package/src/config.js

@@ -0,0 +1,26 @@
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULTS = {
+  ai: false,
+  json: false,
+  exports: true,
+  depth: 3,
+  copy: false,
+  sync: false,
+};
+
+function loadConfig(rootPath) {
+  const configPath = path.join(rootPath, '.cartotreerc');
+  if (!fs.existsSync(configPath)) return DEFAULTS;
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    return { ...DEFAULTS, ...parsed.default };
+  } catch (err) {
+    console.warn('⚠ .cartotreerc parse error, using defaults');
+    return DEFAULTS;
+  }
+}
+
+module.exports = { loadConfig };

package/src/exports.js

@@ -0,0 +1,65 @@
+const fs = require('fs');
+
+const SUPPORTED_EXTENSIONS = ['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs'];
+
+function parseExports(filePath) {
+  const ext = SUPPORTED_EXTENSIONS.find(e => filePath.endsWith(e));
+  if (!ext) return null;
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  const names = new Set();
+
+  // export function foo / export async function foo / export class foo / export const foo
+  const namedPattern = /export\s+(?:async\s+)?(?:function|const|let|var|class)\s+(\w+)/g;
+  let match;
+  while ((match = namedPattern.exec(content)) !== null) {
+    if (match[1] !== 'default') names.add(match[1]);
+  }
+
+  // export { foo, bar as baz }
+  const bracketPattern = /export\s*\{([^}]+)\}/g;
+  while ((match = bracketPattern.exec(content)) !== null) {
+    match[1].split(',')
+      .map(s => s.trim().split(/\s+as\s+/).pop().trim())
+      .filter(Boolean)
+      .forEach(n => names.add(n));
+  }
+
+  // export default function foo / export default class foo
+  const defaultNamedPattern = /export\s+default\s+(?:function|class)\s+(\w+)/g;
+  while ((match = defaultNamedPattern.exec(content)) !== null) {
+    names.add(match[1]);
+  }
+
+  // module.exports = { foo, bar }
+  const cjsPattern = /module\.exports\s*=\s*\{([^}]+)\}/g;
+  while ((match = cjsPattern.exec(content)) !== null) {
+    match[1].split(',')
+      .map(s => s.trim().split(':')[0].trim())
+      .filter(s => /^\w+$/.test(s))
+      .forEach(n => names.add(n));
+  }
+
+  // module.exports.foo = ...
+  const cjsDotPattern = /module\.exports\.(\w+)\s*=/g;
+  while ((match = cjsDotPattern.exec(content)) !== null) {
+    names.add(match[1]);
+  }
+
+  return names.size > 0 ? [...names] : null;
+}
+
+function formatExports(names, max = 4) {
+  if (!names) return '';
+  const visible = names.slice(0, max);
+  const rest = names.length > max ? `, +${names.length - max}` : '';
+  return `<${visible.join(', ')}${rest}>`;
+}
+
+module.exports = { parseExports, formatExports };

package/src/ignore.js

@@ -0,0 +1,31 @@
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULTS = [
+  'node_modules', '.git', 'dist', 'build', '.next',
+  '.nuxt', 'coverage', '.cache', '.DS_Store', 'Thumbs.db'
+];
+
+function loadIgnorePatterns(rootPath) {
+  const ignorePath = path.join(rootPath, '.cartotreeignore');
+
+  if (!fs.existsSync(ignorePath)) return DEFAULTS;
+
+  const lines = fs.readFileSync(ignorePath, 'utf-8')
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => l && !l.startsWith('#'));
+
+  return [...new Set([...DEFAULTS, ...lines])];
+}
+
+function shouldIgnore(name, patterns) {
+  return patterns.some(pattern => {
+    if (pattern.startsWith('*.')) {
+      return name.endsWith(pattern.slice(1));
+    }
+    return name === pattern;
+  });
+}
+
+module.exports = { loadIgnorePatterns, shouldIgnore };

package/src/sync.js

@@ -0,0 +1,30 @@
+const fs = require('fs');
+const chalk = require('chalk');
+
+const START_MARKER = '<!-- CARTOTREE-START -->';
+const END_MARKER = '<!-- CARTOTREE-END -->';
+
+function syncToFile(tree, filePath) {
+  const plain = tree.replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, '');
+  const block = `${START_MARKER}\n\`\`\`\n${plain}\`\`\`\n${END_MARKER}`;
+
+  if (fs.existsSync(filePath)) {
+    let content = fs.readFileSync(filePath, 'utf-8');
+    const startIdx = content.indexOf(START_MARKER);
+    const endIdx = content.indexOf(END_MARKER);
+
+    if (startIdx !== -1 && endIdx !== -1) {
+      content = content.slice(0, startIdx) + block + content.slice(endIdx + END_MARKER.length);
+    } else {
+      content += `\n\n${block}\n`;
+    }
+
+    fs.writeFileSync(filePath, content, 'utf-8');
+    console.log(chalk.green(`✔ Synced to ${filePath}`));
+  } else {
+    fs.writeFileSync(filePath, `# Project Structure\n\n${block}\n`, 'utf-8');
+    console.log(chalk.green(`✔ Created ${filePath}`));
+  }
+}
+
+module.exports = { syncToFile };

package/src/tree.js

@@ -0,0 +1,97 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const { shouldIgnore } = require('./ignore');
+const { parseExports, formatExports } = require('./exports');
+
+
+function getFolderDescription(dirPath) {
+  const folderMd = path.join(dirPath, '.folder.md');
+  const readmeMd = path.join(dirPath, 'README.md');
+
+  if (fs.existsSync(folderMd)) {
+    const content = fs.readFileSync(folderMd, 'utf-8').trim();
+    return content.split('\n')[0].replace(/^#\s*/, '');
+  }
+
+  if (fs.existsSync(readmeMd)) {
+    const content = fs.readFileSync(readmeMd, 'utf-8').trim();
+    const firstLine = content.split('\n')[0].replace(/^#\s*/, '');
+    if (firstLine.length < 80) return firstLine;
+  }
+
+  return null;
+}
+
+function buildTree(dirPath, opts, prefix = '', currentDepth = 0) {
+  if (currentDepth > opts.depth) return '';
+
+  let entries;
+  try {
+    entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'EACCES') {
+      return `${prefix}${chalk.red('[permission denied]')}\n`;
+    }
+    return `${prefix}${chalk.red(`[error: ${err.code}]`)}\n`;
+  }
+
+  const filtered = entries
+    .filter(e => !shouldIgnore(e.name, opts.exclude))
+    .sort((a, b) => {
+      if (a.isDirectory() && !b.isDirectory()) return -1;
+      if (!a.isDirectory() && b.isDirectory()) return 1;
+      return a.name.localeCompare(b.name);
+    });
+
+  if (filtered.length === 0) {
+    return `${prefix}${chalk.gray('(empty)')}\n`;
+  }
+
+  let output = '';
+
+  filtered.forEach((entry, index) => {
+    const isLast = index === filtered.length - 1;
+    const connector = isLast ? '└── ' : '├── ';
+    const childPrefix = isLast ? '    ' : '│   ';
+    const fullPath = path.join(dirPath, entry.name);
+
+    if (entry.isSymbolicLink()) {
+      try {
+        const target = fs.readlinkSync(fullPath);
+        output += `${prefix}${connector}${chalk.magenta(entry.name)}${chalk.gray(` -> ${target}`)}\n`;
+      } catch {
+        output += `${prefix}${connector}${chalk.magenta(entry.name)}${chalk.red(' -> [broken link]')}\n`;
+      }
+      return;
+    }
+
+    if (entry.isDirectory()) {
+      const desc = getFolderDescription(fullPath);
+      const annotation = desc ? chalk.gray(`  # ${desc}`) : '';
+      output += `${prefix}${connector}${chalk.cyan(entry.name)}/${annotation}\n`;
+      if (currentDepth < opts.depth) {
+        output += buildTree(fullPath, opts, prefix + childPrefix, currentDepth + 1);
+      }
+    } else {
+        const exports = opts.showExports ? parseExports(fullPath) : null;
+        const exportTag = exports ? chalk.yellow(` ${formatExports(exports)}`) : '';
+        output += `${prefix}${connector}${entry.name}${exportTag}\n`;
+    }
+  });
+
+  return output;
+}
+
+function generateTree(rootPath, opts) {
+  const rootName = path.basename(rootPath);
+  const desc = getFolderDescription(rootPath);
+  const annotation = desc ? chalk.gray(`  # ${desc}`) : '';
+
+  let output = `${chalk.bold.cyan(rootName)}/${annotation}\n`;
+  output += buildTree(rootPath, opts);
+
+  return output;
+}
+
+module.exports = { generateTree };