@vetterjulius/cagg 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julius Vetter
+
+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,74 @@
+# cagg — Code Aggregator
+
+Bundles every relevant text/code file of a repository into a single output
+file, each preceded by a clear header showing which file follows:
+
+```
+-------------- src/index.js -----------------
+1: 'use strict';
+2:
+...
+```
+
+Built for feeding a codebase to an LLM or for a quick, readable overview of
+a project — the output is kept as small as possible (no unnecessary blank
+lines, no binaries, no build artifacts).
+
+## Example
+An example aggregation of the source code for the tool is included. See [agg.txt](agg.txt).
+
+## Install
+
+```bash
+npm install -g cagg
+```
+
+## Usage
+
+```bash
+cagg                       # aggregate CWD into ./agg.txt
+cagg -i path/to/project     # aggregate a different folder
+cagg -o context.md          # change output name/extension
+cagg -a                     # use absolute paths in headers instead of CWD-relative
+cagg --no-line-numbers      # don't prefix lines with numbers
+cagg --max-size 1           # skip files larger than 1 MB
+cagg --max-lines 2000       # skip files with more than 2000 lines
+```
+
+## Ignoring files
+
+By default, `cagg` ignores an extensive built-in list of common clutter:
+`.git`, `node_modules`, build/dist output, caches, lockfiles, IDE folders,
+OS files, and common binary/media file types (images, fonts, archives,
+documents, ...). Files that don't look like text (checked by content, not
+just extension) are always skipped and reported.
+
+- `--no-ignore` — disable all ignoring; every file is included. Prints a
+  warning since this will likely pull in dependencies and binaries.
+- `--ignore-patterns "pattern1,pattern2"` — supply your own
+  `.gitignore`-style patterns. This **replaces** the built-in default list.
+  Can be repeated / combined with commas.
+- `--ignore-file <path>` — same idea, but patterns come from a file (e.g.
+  point it at your real `.gitignore`). Also **replaces** the default list.
+- If the current directory has a `.gitignore`, its entries are
+  automatically merged into whichever ignore list is active (default or
+  custom). Disable this with `--no-merge-gitignore`.
+
+The output file itself is always excluded from its own aggregation.
+
+## All options
+
+```
+-i, --input <path>            input directory to scan (relative to CWD or absolute) (default: ".")
+-o, --output <path>           output file name/path (default: "agg.txt")
+-a, --absolute-paths          use absolute paths in file headers instead of CWD-relative paths
+    --no-ignore                disable all ignoring; include every file (prints a warning)
+    --ignore-patterns <patterns>  comma-separated gitignore-style patterns, replaces default ignore list
+    --ignore-file <path>       file with gitignore-style patterns, replaces default ignore list
+    --no-merge-gitignore       don't merge a CWD .gitignore into the active ignore list
+    --no-line-numbers          do not prefix each line with its line number
+    --max-size <mb>            skip files larger than this size in MB
+    --max-lines <n>            skip files with more lines than this
+-h, --help                     display help
+-V, --version                  output the version number
+```

package/bin/cagg.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../src/cli').run(process.argv);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@vetterjulius/cagg",
+  "version": "1.0.0",
+  "description": "Code Aggregator - bundles all text/code files of a repository into a single .txt file, with gitignore-aware filtering",
+  "keywords": ["cli", "aggregator", "code", "llm", "context", "gitignore"],
+  "license": "MIT",
+  "bin": {
+    "cagg": "./bin/cagg.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "ignore": "^5.3.2",
+    "isbinaryfile": "^5.0.2"
+  }
+}

package/src/cli.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const { Command } = require('commander');
+const path = require('path');
+const { aggregate } = require('./index');
+const pkg = require('../package.json');
+
+function splitList(value, previous) {
+  const items = value.split(',').map((s) => s.trim()).filter(Boolean);
+  return (previous || []).concat(items);
+}
+
+function parseFloatOpt(value) {
+  const n = parseFloat(value);
+  if (Number.isNaN(n) || n <= 0) {
+    throw new Error(`Invalid numeric value: ${value}`);
+  }
+  return n;
+}
+
+function parseIntOpt(value) {
+  const n = parseInt(value, 10);
+  if (Number.isNaN(n) || n <= 0) {
+    throw new Error(`Invalid integer value: ${value}`);
+  }
+  return n;
+}
+
+function run(argv) {
+  const program = new Command();
+
+  program
+    .name('cagg')
+    .description(
+      'Code Aggregator: bundles all text/code files of a repository into a single ' +
+        'output file, separated by clear file-path headers.'
+    )
+    .version(pkg.version)
+    .option('-i, --input <path>', 'input directory to scan (relative to CWD or absolute)', '.')
+    .option('-o, --output <path>', 'output file name/path (extension can be changed)', 'agg.txt')
+    .option('-a, --absolute-paths', 'use absolute paths in file headers instead of CWD-relative paths', false)
+    .option('--no-ignore', 'disable all ignoring; include every file (prints a warning)')
+    .option(
+      '--ignore-patterns <patterns>',
+      'comma-separated .gitignore-style patterns; REPLACES the built-in default ignore list ' +
+        '(repeatable)',
+      splitList,
+      []
+    )
+    .option(
+      '--ignore-file <path>',
+      'path to a file with .gitignore-style patterns (e.g. your real .gitignore); ' +
+        'REPLACES the built-in default ignore list'
+    )
+    .option(
+      '--no-merge-gitignore',
+      "don't additionally merge a .gitignore found in the CWD into the active ignore list"
+    )
+    .option('--no-line-numbers', 'do not prefix each line with its line number')
+    .option('--max-size <mb>', 'skip files larger than this size in MB', parseFloatOpt)
+    .option('--max-lines <n>', 'skip files with more lines than this', parseIntOpt);
+
+  let opts;
+  try {
+    program.parse(argv);
+    opts = program.opts();
+
+    const result = aggregate({
+      input: opts.input,
+      output: opts.output,
+      absolutePaths: Boolean(opts.absolutePaths),
+      noIgnore: opts.ignore === false,
+      ignorePatterns: opts.ignorePatterns,
+      ignoreFile: opts.ignoreFile,
+      mergeGitignore: opts.mergeGitignore !== false,
+      lineNumbers: opts.lineNumbers !== false,
+      maxSizeMb: opts.maxSize,
+      maxLines: opts.maxLines,
+    });
+
+    const relOut = path.relative(process.cwd(), result.outputPath) || result.outputPath;
+    console.log(`Aggregated ${result.includedCount} file(s) into ${relOut}`);
+    if (result.skipped.length) {
+      console.log(`Skipped ${result.skipped.length} file(s):`);
+      for (const { file, reason } of result.skipped) {
+        console.log(`  - ${path.relative(process.cwd(), file)} (${reason})`);
+      }
+    }
+  } catch (err) {
+    console.error(`cagg: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { run };

package/src/defaultIgnore.js

@@ -0,0 +1,131 @@
+'use strict';
+
+// Extensive built-in default ignore list, gitignore-pattern-style.
+// Covers common VCS/IDE/OS clutter, build artifacts for several ecosystems,
+// dependency directories, lockfiles and binary/media file types that add
+// bulk without helping a reader understand the source code.
+module.exports = `
+# --- version control ---
+.git/
+.svn/
+.hg/
+
+# --- OS clutter ---
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# --- editors / IDEs ---
+.vscode/
+.idea/
+*.iml
+*.swp
+*.swo
+
+# --- node ---
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+dist/
+build/
+out/
+coverage/
+.next/
+.nuxt/
+.cache/
+
+# --- python ---
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+env/
+.mypy_cache/
+.pytest_cache/
+.tox/
+poetry.lock
+Pipfile.lock
+*.egg-info/
+
+# --- java / jvm ---
+target/
+*.class
+*.jar
+.gradle/
+
+# --- go ---
+vendor/
+
+# --- rust ---
+Cargo.lock
+/target/
+
+# --- ruby ---
+.bundle/
+Gemfile.lock
+
+# --- dotnet ---
+# scoped (not a bare "bin/") since Node CLI tools legitimately use a bin/ dir
+[Bb]in/Debug/
+[Bb]in/Release/
+obj/
+
+# --- logs / env ---
+*.log
+.env
+.env.*
+
+# --- archives ---
+*.zip
+*.tar
+*.tar.gz
+*.tgz
+*.rar
+*.7z
+
+# --- compiled / binaries ---
+*.exe
+*.dll
+*.so
+*.dylib
+*.o
+*.a
+
+# --- images / media / fonts ---
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.bmp
+*.ico
+*.webp
+*.svg
+*.mp3
+*.mp4
+*.mov
+*.avi
+*.woff
+*.woff2
+*.ttf
+*.eot
+
+# --- documents ---
+*.pdf
+*.doc
+*.docx
+*.xls
+*.xlsx
+*.ppt
+*.pptx
+
+# --- generated / minified ---
+*.min.js
+*.min.css
+*.map
+`;

package/src/index.js

@@ -0,0 +1,189 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const ignore = require('ignore');
+const { isBinaryFileSync } = require('isbinaryfile');
+
+const DEFAULT_IGNORE = require('./defaultIgnore');
+
+/**
+ * Reads a gitignore-pattern-style file and returns its non-empty lines.
+ * Missing files simply yield no extra patterns.
+ */
+function readPatternFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+}
+
+/**
+ * Builds the `ignore` matcher according to the resolved options.
+ * Returns { ig, warnings } where warnings is a list of strings to print.
+ */
+function buildIgnoreMatcher(opts) {
+  const warnings = [];
+
+  if (opts.noIgnore) {
+    warnings.push(
+      'WARNING: ignoring is disabled (--no-ignore). Every file will be included, ' +
+        'including build artifacts, dependencies and binaries.'
+    );
+    return { ig: ignore(), warnings };
+  }
+
+  const ig = ignore();
+  const hasCustomPatterns = opts.ignorePatterns.length > 0 || Boolean(opts.ignoreFile);
+
+  if (hasCustomPatterns) {
+    // Custom patterns replace the built-in default list ("Alternativ ...").
+    if (opts.ignoreFile) {
+      ig.add(readPatternFile(path.resolve(opts.ignoreFile)));
+    }
+    if (opts.ignorePatterns.length > 0) {
+      ig.add(opts.ignorePatterns);
+    }
+  } else {
+    ig.add(DEFAULT_IGNORE);
+  }
+
+  if (opts.mergeGitignore) {
+    const projectGitignore = path.join(process.cwd(), '.gitignore');
+    const lines = readPatternFile(projectGitignore);
+    if (lines.some((l) => l.trim() && !l.trim().startsWith('#'))) {
+      ig.add(lines);
+    }
+  }
+
+  return { ig, warnings };
+}
+
+/** Normalizes a path to forward slashes, as expected by the `ignore` package. */
+function toPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+/**
+ * Recursively walks `dir`, collecting absolute file paths.
+ * Paths are checked against `ig` relative to `root` so whole directories
+ * (e.g. node_modules/) can be pruned without descending into them.
+ */
+function walk(dir, root, ig, results) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    return; // unreadable directory (permissions, broken symlink, ...): skip
+  }
+
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    const rel = toPosix(path.relative(root, abs));
+
+    // ignore() expects directory patterns to be testable without a trailing
+    // slash mismatch; passing the relative dir path is enough for pruning.
+    if (rel && ig.ignores(entry.isDirectory() ? `${rel}/` : rel)) continue;
+
+    if (entry.isDirectory()) {
+      walk(abs, root, ig, results);
+    } else if (entry.isFile()) {
+      results.push(abs);
+    }
+  }
+}
+
+/** Formats a byte count as a human-readable MB string for messages. */
+function toMb(bytes) {
+  return (bytes / (1024 * 1024)).toFixed(2);
+}
+
+/**
+ * Runs the aggregation with resolved options and writes the output file.
+ * `opts` fields:
+ *   input, output, absolutePaths, noIgnore, ignorePatterns, ignoreFile,
+ *   mergeGitignore, lineNumbers, maxSizeMb, maxLines
+ */
+function aggregate(opts) {
+  const cwd = process.cwd();
+  const inputRoot = path.resolve(opts.input);
+  const outputPath = path.resolve(opts.output);
+
+  const { ig, warnings } = buildIgnoreMatcher(opts);
+  warnings.forEach((w) => console.warn(w));
+
+  const allFiles = [];
+  walk(inputRoot, inputRoot, ig, allFiles);
+
+  // Never re-ingest our own output file, even across repeated runs.
+  const filtered = allFiles.filter((f) => path.resolve(f) !== outputPath);
+
+  const included = [];
+  const skipped = [];
+  const maxBytes = opts.maxSizeMb ? opts.maxSizeMb * 1024 * 1024 : null;
+
+  for (const file of filtered) {
+    let stat;
+    try {
+      stat = fs.statSync(file);
+    } catch (err) {
+      skipped.push({ file, reason: 'unreadable' });
+      continue;
+    }
+
+    if (maxBytes && stat.size > maxBytes) {
+      skipped.push({ file, reason: `exceeds max size (${toMb(stat.size)} MB)` });
+      continue;
+    }
+
+    let buffer;
+    try {
+      buffer = fs.readFileSync(file);
+    } catch (err) {
+      skipped.push({ file, reason: 'unreadable' });
+      continue;
+    }
+
+    if (isBinaryFileSync(buffer, buffer.length)) {
+      skipped.push({ file, reason: 'binary file' });
+      continue;
+    }
+
+    const content = buffer.toString('utf8');
+    const lines = content.length === 0 ? [] : content.split(/\r?\n/);
+
+    if (opts.maxLines && lines.length > opts.maxLines) {
+      skipped.push({ file, reason: `exceeds max lines (${lines.length})` });
+      continue;
+    }
+
+    included.push({ file, lines });
+  }
+
+  // Sort for deterministic, readable output.
+  included.sort((a, b) => a.file.localeCompare(b.file));
+
+  const parts = [];
+  for (const { file, lines } of included) {
+    const displayPath = toPosix(
+      opts.absolutePaths ? file : path.relative(cwd, file)
+    );
+    const header = `-------------- ${displayPath} -----------------`;
+
+    let body = lines
+      .map((line, i) => (opts.lineNumbers ? `${i + 1}: ${line}` : line))
+      .join('\n');
+    body = body.replace(/\n+$/, ''); // drop trailing blank lines, keep file small
+
+    parts.push(`${header}\n${body}`);
+  }
+
+  const output = parts.join('\n\n') + (parts.length ? '\n' : '');
+  fs.writeFileSync(outputPath, output, 'utf8');
+
+  return { outputPath, includedCount: included.length, skipped };
+}
+
+module.exports = { aggregate, buildIgnoreMatcher, walk };