catport 1.0.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "catport",
+  "version": "1.0.0",
+  "description": "A high-performance, minimalist, and dependency-free CLI tool for bundling file contents or extracting files from a bundle.",
+  "main": "src/index.js",
+  "bin": {
+    "catport": "bin/catport"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "ARCHITECTURE.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/**/*.test.js",
+    "test:watch": "node --test --watch tests/**/*.test.js",
+    "lint": "npx eslint src/ tests/ --max-warnings 0"
+  },
+  "keywords": [
+    "llm",
+    "context",
+    "bundle",
+    "devtools",
+    "serializer",
+    "ai",
+    "prompt-engineering",
+    "multipart",
+    "yaml",
+    "git",
+    "minifier",
+    "zero-dependency",
+    "cli"
+  ],
+  "author": "Reza Jelodar",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "type": "module",
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "globals": "^15.0.0"
+  }
+}

package/src/cli/args.js

@@ -0,0 +1,133 @@
+import { DEFAULTS, LOG, OPTIMIZE } from '../config/constants.js';
+import { OPTIONS } from '../config/options.js';
+import { Parser } from './parser.js';
+
+const parseSize = (input) => {
+  if (typeof input === 'number') {
+    return input;
+  }
+  if (!input) {
+    return 0;
+  }
+
+  const s = String(input).trim();
+  const match = s.match(/^(\d+(?:\.\d+)?)\s*([kmg]b?)?$/i);
+  
+  if (!match) {
+    return parseInt(s, 10) || 0;
+  }
+  
+  const val = parseFloat(match[1]);
+  const suffix = (match[2] || '').toLowerCase();
+  
+  if (suffix.startsWith('k')) {
+    return Math.floor(val * 1024);
+  }
+  if (suffix.startsWith('m')) {
+    return Math.floor(val * 1024 * 1024);
+  }
+  if (suffix.startsWith('g')) {
+    return Math.floor(val * 1024 * 1024 * 1024);
+  }
+  
+  return Math.floor(val);
+};
+
+const normalize = (config) => {
+  if (config.verbose) {
+    config.logLevel = LOG.INFO;
+  }
+
+  if (config.optimize !== undefined) {
+    const val = String(config.optimize).trim();
+    const lowerVal = val.toLowerCase();
+    const validModes = new Set(Object.values(OPTIMIZE));
+
+    if (validModes.has(lowerVal)) {
+      config.optimize = lowerVal;
+    } else {
+      config.optimizeCmd = val;
+    }
+  }
+
+  if (config.noInstruct) {
+    config.instruct = false;
+  }
+
+  if (config.noStructure) {
+    config.structure = false;
+  }
+
+  if (config.unsafe) {
+    config.safeMode = false;
+  }
+
+  if (config.extensions) {
+    config.extSet = new Set(
+      config.extensions.split(',').map(e => e.trim().replace(/^\./, '').toLowerCase())
+    );
+  }
+
+  // Merge Ignore Patterns
+  const baseIgnore = config.noIgnore ? [] : DEFAULTS.IGNORE;
+  const userIgnore = config.ignore || [];
+  config.ignore = [...baseIgnore, ...userIgnore];
+
+  if (config.priority) {
+    config.priorityRules = config.priority.map(p => {
+      if (typeof p === 'object') {
+        return p;
+      }
+      const idx = p.lastIndexOf(':');
+      if (idx > 0) {
+        const score = parseInt(p.slice(idx + 1), 10);
+        if (!Number.isNaN(score)) {
+          return {
+            pattern: p.slice(0, idx),
+            score
+          };
+        }
+      }
+      return null;
+    }).filter(Boolean);
+  }
+
+  if (config.gitDiff === true) {
+    config.gitDiff = 'HEAD';
+  }
+
+  if (config.maxSize !== undefined) {
+    config.maxSize = parseSize(config.maxSize);
+  }
+
+  return config;
+};
+
+export const ArgParser = {
+  process(argv, fileConfig = {}, schema = OPTIONS) {
+    const defaults = Parser.getDefaults(schema);
+    const explicit = Parser.parse(argv, schema);
+
+    const rawConfig = {
+      logLevel: LOG.WARN,
+      instruct: DEFAULTS.INSTRUCT,
+      structure: DEFAULTS.STRUCTURE,
+      listDirs: DEFAULTS.LIST_DIRS,
+      optimize: DEFAULTS.OPTIMIZE,
+      safeMode: DEFAULTS.SAFE_MODE,
+      charsPerToken: DEFAULTS.CHARS_PER_TOKEN,
+      maxSize: DEFAULTS.MAX_SIZE,
+      ...defaults,
+      ...fileConfig
+    };
+
+    Object.keys(explicit).forEach(k => {
+      if (k === 'paths' && explicit.paths.length === 0) {
+        return;
+      }
+      rawConfig[k] = explicit[k];
+    });
+
+    return normalize(rawConfig);
+  }
+};

package/src/cli/main.js

@@ -0,0 +1,78 @@
+import { ArgParser } from './args.js';
+import { UI } from './ui.js';
+import { Bundler } from '../core/bundler.js';
+import { Extractor } from '../core/extractor.js';
+import { NodeIO } from '../utils/io.js';
+import { Git } from '../utils/git.js';
+import { Logger } from '../utils/logger.js';
+import { EXIT, APP } from '../config/constants.js';
+import { OPTIONS } from '../config/options.js';
+import { Optimizer } from '../optimizers/index.js';
+import { Formatter } from '../formatters/index.js';
+import { Scanner } from '../core/scanner.js';
+import { Analyzer } from '../core/analyzer.js';
+import { Processor } from '../core/processor.js';
+import { ConfigLoader } from '../config/loader.js';
+
+export const CLI = {
+  async run(argv, io = NodeIO) {
+    const ui = UI(io);
+    try {
+      const fileConfig = await ConfigLoader.load(io);
+      const config = ArgParser.process(argv, fileConfig);
+
+      if (config.help) {
+        ui.printHeader(APP);
+        ui.printHelp(APP, OPTIONS);
+        return;
+      }
+
+      if (config.version) {
+        io.writeStdout(`${APP.NAME} v${APP.VERSION}\n`);
+        return;
+      }
+
+      const logger = Logger(config.logLevel, io);
+
+      if (config.extract) {
+        await Extractor.run(config, io, { 
+          formatter: Formatter,
+          logger: logger 
+        });
+      } else {
+        if (config.gitDiff) {
+          const changes = await Git.getChangedFiles(io, config.gitDiff, io.cwd());
+          if (!changes) {
+            ui.printError('Not a git repository or git command failed.');
+            io.exit(EXIT.ERROR);
+            return;
+          }
+          
+          if (changes.size === 0) {
+            ui.printError('No changes detected.');
+            io.exit(EXIT.SUCCESS);
+            return;
+          }
+          
+          config.gitFiles = changes;
+        }
+
+        const stats = await Bundler.run(config, io, {
+          scanner: Scanner,
+          analyzer: Analyzer,
+          processor: Processor,
+          optimizer: Optimizer,
+          formatter: Formatter,
+          logger: logger
+        });
+        
+        if (config.output && stats) {
+          ui.printUsageReport(stats, config.output);
+        }
+      }
+    } catch (e) {
+      ui.printError(e.message);
+      io.exit(EXIT.ERROR);
+    }
+  }
+};

package/src/cli/parser.js

@@ -0,0 +1,152 @@
+
+/**
+ * Map CLI flags to schema keys.
+ */
+const buildMaps = (schema) => {
+  const flags = new Map();
+  const shorts = new Map();
+
+  for (const [key, opt] of Object.entries(schema)) {
+    const long = '--' + key.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+    flags.set(long, key);
+    if (opt.short) {
+      shorts.set('-' + opt.short, key);
+    }
+  }
+  return { flags, shorts };
+};
+
+const parseNumber = (key, val) => {
+  const n = Number(val);
+  if (Number.isNaN(n)) {
+    throw new Error(`Expected number for --${key}, got "${val}"`);
+  }
+  return n;
+};
+
+export const Parser = {
+  getDefaults(schema) {
+    const defaults = { paths: [] };
+    for (const [key, opt] of Object.entries(schema)) {
+      if (opt.default !== undefined) {
+        defaults[key] = opt.default;
+      }
+    }
+    return defaults;
+  },
+
+  /**
+   * Parse argv into an explicit configuration object.
+   * Does NOT apply defaults. Returns only what is present in argv.
+   */
+  parse(argv, schema) {
+    const { flags, shorts } = buildMaps(schema);
+    const explicit = { paths: [] };
+    const args = argv.slice(2);
+
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+
+      if (arg === '--') {
+        explicit.paths.push(...args.slice(i + 1));
+        break;
+      }
+
+      if (!arg.startsWith('-') || arg === '-') {
+        explicit.paths.push(arg);
+        continue;
+      }
+
+      // Grouped Short Flags (e.g. -xvu)
+      if (!arg.startsWith('--') && arg.length > 2) {
+        const chars = arg.slice(1).split('');
+        for (const c of chars) {
+          const key = shorts.get('-' + c);
+          if (!key) {
+            throw new Error(`Unknown flag: -${c}`);
+          }
+          if (schema[key].type !== 'boolean') {
+            throw new Error(`Flag -${c} requires a value and cannot be grouped.`);
+          }
+          explicit[key] = true;
+        }
+        continue;
+      }
+
+      // Normal Flags
+      let key = null;
+      let explicitVal = null;
+
+      if (arg.startsWith('--')) {
+        if (arg.includes('=')) {
+          const parts = arg.split('=');
+          key = flags.get(parts[0]);
+          explicitVal = parts.slice(1).join('=');
+        } else {
+          key = flags.get(arg);
+        }
+      } else {
+        key = shorts.get(arg);
+      }
+
+      if (!key) {
+        throw new Error(`Unknown argument: ${arg}`);
+      }
+
+      const opt = schema[key];
+      const isBool = opt.type === 'boolean';
+
+      if (isBool) {
+        if (explicitVal) {
+          throw new Error(`Boolean flag ${key} does not accept a value.`);
+        }
+        explicit[key] = true;
+      } else {
+        let val = explicitVal;
+        
+        if (val === null) {
+          const next = args[i + 1];
+          
+          // Value detection logic
+          let isValidValue = false;
+          if (next !== undefined) {
+            const isFlag = next.startsWith('-');
+            const isStdin = next === '-';
+            const isNumberValue = isFlag && opt.type === 'number' && !Number.isNaN(Number(next));
+
+            if (!isFlag || isStdin || isNumberValue) {
+              isValidValue = true;
+            }
+          }
+
+          if (isValidValue) {
+            val = next;
+            i++;
+          } else {
+            if (opt.optional) {
+              val = true;
+            } else {
+              throw new Error(`Flag ${key} requires a value.`);
+            }
+          }
+        }
+
+        if (val === true && opt.optional) {
+          explicit[key] = true;
+        } else {
+          const parsed = opt.type === 'number' ? parseNumber(key, val) : val;
+          if (opt.type === 'array') {
+            if (!explicit[key]) {
+              explicit[key] = [];
+            }
+            explicit[key].push(parsed);
+          } else {
+            explicit[key] = parsed;
+          }
+        }
+      }
+    }
+
+    return explicit;
+  }
+};

package/src/cli/ui.js

@@ -0,0 +1,78 @@
+import { Style } from '../utils/style.js';
+
+export const UI = (io) => ({
+  printHeader: (app) => {
+    io.writeStdout(`\n${Style.bold(Style.cyan(app.NAME))} v${app.VERSION}\n`);
+    io.writeStdout(`${Style.dim(app.DESC)}\n`);
+  },
+
+  printHelp: (app, schema) => {
+    const pad = (str, len) => str.padEnd(len, ' ');
+    const row = (short, long, desc) => `  ${Style.yellow(short)}, ${Style.green(pad(long, 24))} ${desc}`;
+    const toKebab = (str) => '--' + str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+
+    io.writeStdout(`\n${Style.bold('USAGE')}\n  ${app.NAME} [options] [path...]\n`);
+
+    const categories = {};
+
+    Object.entries(schema).forEach(([key, opt]) => {
+      const cat = opt.category || 'General';
+      if (!categories[cat]) {
+        categories[cat] = [];
+      }
+
+      let flagStr = toKebab(key);
+      if (opt.type !== 'boolean') {
+        const mv = Style.italic(opt.metavar);
+        if (opt.optional) {
+          flagStr += ` [${mv}]`;
+        } else {
+          flagStr += ` <${mv}>`;
+        }
+      }
+
+      categories[cat].push(row(`-${opt.short}`, flagStr, opt.desc));
+    });
+
+    const order = [
+      'General',
+      'Bundling',
+      'Extraction'
+    ];
+
+    order.forEach(name => {
+      if (categories[name]) {
+        io.writeStdout(`\n${Style.bold(Style.underline(name.toUpperCase()))}\n${categories[name].join('\n')}\n`);
+      }
+    });
+
+    const cmt = (s) => Style.dim('# ' + s);
+
+    io.writeStdout(`\n${Style.bold('EXAMPLES')}
+  ${cmt('Bundle project with task')}
+  ${app.NAME} -T "Refactor this" -o bundle.md
+
+  ${cmt('Bundle git changes with optimized output (no comments)')}
+  ${app.NAME} -g HEAD -O comments
+
+  ${cmt('Extract code (safe by default)')}
+  ${app.NAME} -x bundle.md -d ./src
+
+  ${cmt('Extract code (unsafe/allow traversal)')}
+  ${app.NAME} -x bundle.md -d ./src -U
+`);
+  },
+
+  printError: (msg) => {
+    const badge = Style.bgRed(Style.white(' FATAL '));
+    io.writeStderr(`\n${badge} ${msg}\n`);
+  },
+
+  printUsageReport: (stats, path) => {
+    if (path) {
+      const files = stats.files !== undefined ? stats.files : stats;
+      const tokens = stats.tokens !== undefined ? ` (~${stats.tokens} tokens)` : '';
+      io.writeStdout(`\n${Style.green('✔ Success')} Bundled ${Style.bold(files)} files${tokens} to ${Style.cyan(path)}\n`);
+    }
+  }
+});

package/src/config/constants.js

@@ -0,0 +1,62 @@
+import { DEFAULT_IGNORES } from './ignores.js';
+
+export const APP = {
+  NAME: 'catport',
+  VERSION: '1.0.0',
+  DESC: 'Deterministic filesystem serializer for LLM contexts'
+};
+
+export const EXIT = {
+  SUCCESS: 0,
+  ERROR: 1
+};
+
+export const LOG = {
+  SILENT: 0,
+  ERROR: 1,
+  WARN: 2,
+  INFO: 3,
+  DEBUG: 4
+};
+
+export const FORMAT = {
+  MD: 'md',
+  XML: 'xml',
+  JSON: 'json',
+  YAML: 'yaml',
+  MULTIPART: 'multipart'
+};
+
+export const XML_MODE = {
+  AUTO: 'auto',
+  CDATA: 'cdata',
+  ESCAPE: 'escape'
+};
+
+export const OPTIMIZE = {
+  NONE: 'none',
+  WHITESPACE: 'whitespace',
+  COMMENTS: 'comments',
+  MINIFY: 'minify'
+};
+
+export const XML_TAGS = {
+  CDATA_OPEN: '<![' + 'CDATA[',
+  CDATA_CLOSE: ']]' + '>'
+};
+
+export const DEFAULTS = {
+  BUDGET: 0,
+  CHARS_PER_TOKEN: 4.2,
+  PRIORITY: 1,
+  EXTRACT_DIR: '.',
+  FORMAT: FORMAT.MD,
+  INSTRUCT: true,
+  STRUCTURE: true,
+  LIST_DIRS: false,
+  SAFE_MODE: true,
+  OPTIMIZE: OPTIMIZE.NONE,
+  CONCURRENCY: 32,
+  MAX_SIZE: 10 * 1024 * 1024,
+  IGNORE: DEFAULT_IGNORES
+};

package/src/config/ignores.js

@@ -0,0 +1,119 @@
+export const DEFAULT_IGNORES = [
+  // --- Version Control & Metadata ---
+  '.git/', '.svn/', '.hg/', '.bzr/', '.cvs/', '.gitattributes', '.gitmodules',
+
+  // --- OS & System Files ---
+  '.DS_Store', '.DS_Store?', '._*', '.Spotlight-V100', '.Trashes',
+  'Thumbs.db', 'ehthumbs.db', 'desktop.ini', '$RECYCLE.BIN/',
+  '.AppleDouble/', '.LSOverride/',
+  '.directory', '.fuse_hidden*', '.nfs*',
+
+  // --- Editors & IDEs ---
+  '.idea/', '.vscode/', '.vs/', '.settings/', '.classpath', '.project',
+  '*.sublime-workspace', '*.sublime-project',
+  '*.iml', '*.ipr', '*.iws', '*.suo', '*.ntvs*', '*.njsproj', '*.sln',
+  '.factorypath', '.checkstyle', '.metadata/',
+  'nbproject/', 'build.xml', // NetBeans / Ant
+  '.history/', '.ionide/',   // VS Code history / Ionide
+  'Session.vim', '.netrwhist', // Vim
+  '*~', '#*#', '.#*', // Emacs / Vim
+
+  // --- Logs, Temp, Backups ---
+  '*.log', 'logs/', 'log/', '*.log.*',
+  '*.backup', '*.bak', '*.tmp', '*.temp',
+  '*.swp', '*.swo', '*.swn',
+  '*.old', '*.orig', '*.rej',
+  '*.dump', '*.stackdump', 'core',
+  '*.pid', '*.seed',
+
+  // --- Secrets, Credentials, Local Config (Security) ---
+  '.env', '.env.*', '!.env.example', '!.env.sample', '!.env.template', '!.env.defaults',
+  '*.pem', '*.key', '*.crt', '*.pfx', '*.p12', '*.der', '*.cer',
+  'id_rsa', 'id_rsa.pub', 'known_hosts',
+  'config.secret.*', 'secrets.*', 'credentials.*',
+  '.npmrc', '.netrc', '.ssh/', '.aws/', '.gcloud/', '.azure/',
+
+  // --- Build Outputs & Artifacts (General) ---
+  'dist/', 'build/', 'out/', 'target/', 'obj/', 'bin/',
+  'release/', 'debug/',
+  '_build/', 'deps/',
+
+  // --- Archives & Binary Assets ---
+  '*.zip', '*.tar', '*.gz', '*.tgz', '*.rar', '*.7z', '*.iso', '*.dmg',
+  '*.exe', '*.dll', '*.so', '*.so.*', '*.dylib', '*.bin', '*.msi', '*.app',
+  '*.deb', '*.rpm', '*.apk', '*.jar', '*.war', '*.ear', '*.nar',
+  '*.png', '*.jpg', '*.jpeg', '*.gif', '*.ico', '*.svg', '*.webp', '*.bmp', '*.tiff',
+  '*.mp4', '*.mp3', '*.wav', '*.mov', '*.avi', '*.mkv', '*.webm', '*.flv',
+  '*.pdf', '*.doc', '*.docx', '*.xls', '*.xlsx', '*.ppt', '*.pptx',
+  '*.ttf', '*.otf', '*.woff', '*.woff2', '*.eot',
+  '*.psd', '*.ai', '*.hex', '*.out',
+
+  // --- Node.js / JS / TS ---
+  'node_modules/', 'bower_components/', 'jspm_packages/', 'web_modules/',
+  '.npm/', '.yarn/', '.pnp.*', '.pnpm-store/',
+  '.cache/', '.parcel-cache/', '.eslintcache/', '.stylelintcache/',
+  'coverage/', '.nyc_output/', 'lib-cov/',
+  '.grunt/', '.gulp/',
+  '.next/', '.nuxt/', '.output/', '.docusaurus/', '.svelte-kit/', '.astro/',
+  '*.min.js', '*.min.css', '*.map', 'report.[0-9]*.*', '*.tsbuildinfo',
+
+  // --- Python ---
+  '__pycache__/', '*.py[cod]', '*$py.class',
+  'venv/', '.venv/', 'env/', 'ENV/',
+  '.pytest_cache/', '.mypy_cache/', '.ruff_cache/', '.tox/', '.nox/', '.coverage',
+  'htmlcov/', 'pip-wheel-metadata/',
+  '*.egg-info/', '.eggs/', '*.egg', 'instance/',
+  'jupyter_cache/', '.ipynb_checkpoints/', 'celerybeat-schedule',
+
+  // --- Java / JVM / Kotlin ---
+  '*.class', '.gradle/', 'gradle-app.setting',
+  'hs_err_pid*',
+
+  // --- C / C++ / Obj-C ---
+  '*.o', '*.obj', '*.lo', '*.la', '*.lai', '*.slo', '*.sl',
+  '*.a', '*.lib',
+  '*.gch', '*.pch', '*.d',
+  '.make', 'cmake-build-*/', 'CMakeFiles/', 'CMakeCache.txt',
+  '*.profraw', '*.gcda', '*.gcno',
+  'DerivedData/', 'compile_commands.json',
+
+  // --- .NET / C# ---
+  '*.pdb', 'packages/', 'TestResult/',
+
+  // --- Go ---
+  'go.work', 'go.test', '_testmain.go',
+
+  // --- Rust ---
+  '*.rs.bk',
+
+  // --- Ruby ---
+  '.bundle/', 'lib/bundler/man/', '*.gem', '.ruby-version',
+
+  // --- PHP ---
+  'vendor/', 'composer.phar', '*.phar', '.phpunit.result.cache',
+
+  // --- Swift ---
+  '.swiftpm',
+
+  // --- Dart / Flutter ---
+  '.dart_tool/', '.pub-cache/', '.pub/',
+
+  // --- Terraform ---
+  '.terraform/', '*.tfstate', '.terraform.lock.hcl',
+
+  // --- Serverless ---
+  '.serverless/', '.aws-sam/', '.elasticbeanstalk/',
+
+  // --- Virtualization ---
+  '.vagrant/',
+
+  // --- Databases ---
+  '*.sqlite', '*.sqlite3', '*.db', '*.db3', '*.s3db',
+  '*.db-journal', '*.mdb', '*.accdb',
+  'dump.rdb',
+
+  // --- Lock Files (Noise reduction) ---
+  'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lockb',
+  'Cargo.lock', 'Gemfile.lock', 'composer.lock', 'poetry.lock', 'Pipfile.lock',
+  'go.sum', 'mix.lock', 'pubspec.lock', 'flake.lock'
+];

package/src/config/loader.js

@@ -0,0 +1,15 @@
+import { resolve } from 'node:path';
+
+export const ConfigLoader = {
+  load: async (io) => {
+    try {
+      const path = resolve(io.cwd(), '.catport.json');
+      const content = await io.readText(path);
+      return JSON.parse(content);
+    } catch {
+      // Fail silently if config file is missing or invalid, 
+      // relying on defaults handled by ArgParser.
+      return {};
+    }
+  }
+};