code-context-extractor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+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,227 @@
+# CodeContextExtractor
+
+CodeContextExtractor is a local-only CLI that captures a deterministic snapshot of a codebase and writes it to a single text or Markdown file. It exists for one purpose: safely sharing repository context with an AI assistant or teammate without uploading the repo itself or exposing sensitive files.
+
+## Why it exists
+- Developers need a clean, reliable way to send project context to AI tools
+- Repositories contain secrets, binaries, and noise that should be skipped by default
+
+## Who it is for
+- Engineers who want fast, offline context exports
+- Teams who need predictable, reproducible outputs
+- Anyone who shares code with AI systems and wants safe defaults
+
+## Quick start
+```bash
+npm install
+npm run build
+npx --no-install code-context-extractor extract . --verbose
+```
+
+The output is written to `.code-context/` with a timestamped filename like:
+```
+.code-context/<root>_context_YYYY-MM-DD_HHMMSS.txt
+```
+
+## Important: .gitignore your outputs
+> **Warning ⚠️**  
+> CodeContextExtractor writes files into a `.code-context/` folder inside your project root. If that folder is not ignored, you may accidentally commit and push your context exports.
+
+Add this line to your project's `.gitignore`:
+```
+.code-context/
+```
+
+## npm and npx (for beginners)
+- `npm` is the package manager that installs tools and libraries.
+- `npx` runs a tool. If it is not installed locally, it will try to download it.
+- `--no-install` tells `npx` to only use what is already installed and skip downloads.
+
+In this repo, `code-context-extractor` is not published to npm yet, so `npx` needs `--no-install` or a direct `node dist/cli.js` call.
+
+## User journey (example)
+You want to generate a context file for a project at `C:\projects\MyNewProject`.
+
+### Step 1: Install CodeContextExtractor (one time)
+```bash
+git clone https://github.com/Rwstrobe/CodeContextExtractor.git
+cd CodeContextExtractor
+npm install
+npm run build
+```
+
+### Step 2: Go to your project folder
+```bash
+cd C:\projects\MyNewProject
+```
+
+### Step 3: Generate the context file
+```bash
+npx --no-install code-context-extractor extract . --verbose
+```
+
+The output will be saved to:
+```
+.\.code-context\MyNewProject_context_YYYY-MM-DD_HHMMSS.txt
+```
+
+### macOS/Linux variant
+You can follow the same steps with a Unix-style path:
+```bash
+cd ~/projects/MyNewProject
+npx --no-install code-context-extractor extract . --verbose
+```
+The output will be saved to:
+```
+./.code-context/MyNewProject_context_YYYY-MM-DD_HHMMSS.txt
+```
+
+## Install from GitHub (beginner-friendly)
+1. Clone the repository:
+```bash
+git clone https://github.com/Rwstrobe/CodeContextExtractor.git
+```
+2. Enter the project folder:
+```bash
+cd CodeContextExtractor
+```
+3. Install dependencies:
+```bash
+npm install
+```
+4. Build the CLI:
+```bash
+npm run build
+```
+5. Run the extractor:
+```bash
+npx --no-install code-context-extractor extract . --verbose
+```
+
+If you prefer, you can run the built CLI directly:
+```bash
+node dist/cli.js extract . --verbose
+```
+
+## Features
+- Local-only operation (no network calls, telemetry, or analytics)
+- Cross-platform: Windows, macOS, Linux
+- Safe defaults with common sensitive excludes
+- Configurable include/exclude globs and max file size
+- Deterministic ordering and normalized paths/line endings
+- Streaming output (does not load large files into memory)
+- Conservative redaction enabled by default
+- Optional Markdown output
+- Automatic output folder `.code-context/`
+
+## Commands
+### Extract
+```bash
+npx --no-install code-context-extractor extract [path]
+```
+Example:
+```bash
+npx --no-install code-context-extractor extract ./project --format md --depth 3 --verbose
+```
+If you installed the CLI globally (for example via `npm link` or a future npm publish), you can run:
+```bash
+code-context-extractor extract [path]
+```
+
+## Options
+```bash
+--out <file>            Output file (default: .code-context/<root>_context_YYYY-MM-DD_HHMMSS.txt)
+--format <text|md>      Output format (default: text)
+--depth <n>             Tree depth (default: 4)
+--include <glob>        Include glob (repeatable)
+--exclude <glob>        Exclude glob (repeatable)
+--max-bytes <n>         Max file size in bytes (default: 500000)
+--redact                Enable redaction (default: true)
+--no-redact             Disable redaction
+--respect-gitignore     Honor .gitignore (default: true)
+--no-gitignore          Ignore .gitignore rules
+--config <file>         Optional JSON config file
+--verbose               Verbose logging
+```
+
+## Output format
+Each output file contains:
+- LLM context header (how to interpret the file)
+- Metadata header (root path, timestamp, tool version, command, config summary)
+- Folder tree (depth-limited)
+- Included files summary (count and total size)
+- Skipped files with reasons (excluded, too large, binary, unreadable)
+- For each included file: path, size, last modified, and contents in fenced blocks
+
+## Redaction
+Redaction is enabled by default to reduce accidental secret leakage. It targets:
+- Common key/value patterns (tokens, passwords, api keys)
+- Private key blocks
+- Common credential formats (JWTs, GitHub tokens, AWS keys, etc.)
+
+Disable redaction only when you are sure the output is safe:
+```bash
+code-context-extractor extract . --no-redact
+```
+
+## Default excludes
+The following are excluded by default:
+```
+node_modules
+dist
+build
+out
+.code-context
+.next
+.turbo
+.git
+.idea
+.vscode
+coverage
+*.lock
+*.log
+*.pem
+*.key
+*.p12
+*.env
+.env.*
+secrets.*
+id_rsa
+id_ed25519
+```
+
+## Configuration file
+Use an optional JSON file (example: `example-config.json`) to set defaults.
+```json
+{
+  "outFile": ".code-context/project_context_2026-01-19_145227.txt",
+  "format": "text",
+  "depth": 4,
+  "include": [],
+  "exclude": [],
+  "maxBytes": 500000,
+  "redact": true,
+  "respectGitignore": true
+}
+```
+
+Use it like this:
+```bash
+code-context-extractor extract . --config example-config.json
+```
+
+## Safety posture
+- No network access or external services
+- Does not execute or evaluate code from your repository
+- Skips common sensitive files by default
+- Redacts likely secrets unless `--no-redact` is specified
+
+## Development
+```bash
+npm run build
+npm test
+```
+
+## License
+MIT
+

package/dist/cli.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const config_1 = require("./config");
+const normalizePath_1 = require("./utils/normalizePath");
+const scanner_1 = require("./scanner");
+const text_1 = require("./exporters/text");
+const markdown_1 = require("./exporters/markdown");
+async function getVersion() {
+    try {
+        const packagePath = path_1.default.resolve(__dirname, '..', 'package.json');
+        const raw = await fs_1.promises.readFile(packagePath, 'utf8');
+        return JSON.parse(raw).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+async function main() {
+    const program = new commander_1.Command();
+    program
+        .name('code-context-extractor')
+        .description('Create a deterministic context file from a local codebase (folder tree + file contents).');
+    const version = await getVersion();
+    program.version(version);
+    program.addHelpText('after', `
+Examples:
+  code-context-extractor extract . --verbose
+  code-context-extractor extract . --format md --depth 3
+  code-context-extractor extract C:\\projects\\MyNewProject --max-bytes 200000
+`);
+    program
+        .command('extract')
+        .argument('[path]', 'Root path', '.')
+        .description('Generate a single context file from the target folder.')
+        .option('--out <file>', 'Output file path (defaults to .code-context/<root>_context_...)')
+        .option('--format <text|md>', 'Output format', 'text')
+        .option('--depth <n>', 'Folder tree depth', (value) => parseInt(value, 10), 4)
+        .option('--include <glob>', 'Include glob', collect, [])
+        .option('--exclude <glob>', 'Exclude glob', collect, [])
+        .option('--max-bytes <n>', 'Max file size in bytes', (value) => parseInt(value, 10), 500000)
+        .option('--redact', 'Enable redaction', true)
+        .option('--no-redact', 'Disable redaction')
+        .option('--respect-gitignore', 'Respect .gitignore', true)
+        .option('--no-gitignore', 'Ignore .gitignore')
+        .option('--config <file>', 'Optional JSON config file')
+        .option('--verbose', 'Verbose logging', false)
+        .action(async (rootArg, options) => {
+        const rootPath = path_1.default.resolve(process.cwd(), rootArg);
+        const config = await (0, config_1.resolveConfig)(rootPath, {
+            outFile: options.out,
+            format: options.format,
+            depth: options.depth,
+            include: options.include,
+            exclude: options.exclude,
+            maxBytes: options.maxBytes,
+            redact: options.redact,
+            respectGitignore: options.gitignore ?? options.respectGitignore,
+            verbose: options.verbose,
+            configPath: options.config
+        }, process.cwd());
+        const outputPath = path_1.default.resolve(process.cwd(), config.outFile);
+        const relativeOut = (0, normalizePath_1.normalizePath)(path_1.default.relative(rootPath, outputPath));
+        const shouldExcludeOut = relativeOut !== '' && !relativeOut.startsWith('..') && !path_1.default.isAbsolute(relativeOut);
+        const scanExcludes = shouldExcludeOut
+            ? [...config.exclude, relativeOut]
+            : config.exclude;
+        const result = await (0, scanner_1.scan)(rootPath, {
+            include: config.include,
+            exclude: scanExcludes,
+            maxBytes: config.maxBytes,
+            respectGitignore: config.respectGitignore
+        });
+        await fs_1.promises.mkdir(path_1.default.dirname(outputPath), { recursive: true });
+        const output = (0, fs_1.createWriteStream)(outputPath, { encoding: 'utf8' });
+        const metadata = {
+            version,
+            command: process.argv.slice(2).join(' ')
+        };
+        if (config.format === 'md') {
+            await (0, markdown_1.exportMarkdown)(result, config, output, metadata);
+        }
+        else {
+            await (0, text_1.exportText)(result, config, output, metadata);
+        }
+        await new Promise((resolve, reject) => {
+            output.on('finish', resolve);
+            output.on('error', reject);
+            output.end();
+        });
+        if (config.verbose) {
+            console.log(`Wrote ${result.files.length} files to ${outputPath}`);
+        }
+    });
+    await program.parseAsync(process.argv);
+}
+function collect(value, previous) {
+    return previous.concat([value]);
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = exports.DEFAULT_EXCLUDES = void 0;
+exports.loadConfigFile = loadConfigFile;
+exports.resolveConfig = resolveConfig;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+exports.DEFAULT_EXCLUDES = [
+    'node_modules/**',
+    'dist/**',
+    'build/**',
+    'out/**',
+    '.code-context/**',
+    '.next/**',
+    '.turbo/**',
+    '.git/**',
+    '.idea/**',
+    '.vscode/**',
+    'coverage/**',
+    '*.lock',
+    '*.log',
+    '*.pem',
+    '*.key',
+    '*.p12',
+    '*.env',
+    '.env.*',
+    'secrets.*',
+    'id_rsa',
+    'id_ed25519'
+];
+exports.DEFAULT_CONFIG = {
+    format: 'text',
+    depth: 4,
+    include: [],
+    exclude: [],
+    maxBytes: 500000,
+    redact: true,
+    respectGitignore: true
+};
+async function loadConfigFile(configPath, cwd) {
+    if (!configPath) {
+        return {};
+    }
+    const resolved = path_1.default.resolve(cwd, configPath);
+    const contents = await fs_1.promises.readFile(resolved, 'utf8');
+    return JSON.parse(contents);
+}
+function pickArray(primary, fallback) {
+    if (primary && primary.length > 0) {
+        return primary;
+    }
+    if (fallback && fallback.length > 0) {
+        return fallback;
+    }
+    return [];
+}
+async function resolveConfig(rootPath, cliOptions, cwd) {
+    const fileConfig = await loadConfigFile(cliOptions.configPath, cwd);
+    const format = normalizeFormat(cliOptions.format ?? fileConfig.format ?? exports.DEFAULT_CONFIG.format);
+    const explicitOutFile = cliOptions.outFile ?? fileConfig.outFile;
+    const outFile = explicitOutFile ?? buildAutoOutFile(rootPath, format);
+    return {
+        rootPath,
+        outFile,
+        format,
+        depth: cliOptions.depth ?? fileConfig.depth ?? exports.DEFAULT_CONFIG.depth,
+        include: pickArray(cliOptions.include, fileConfig.include),
+        exclude: pickArray(cliOptions.exclude, fileConfig.exclude),
+        maxBytes: cliOptions.maxBytes ?? fileConfig.maxBytes ?? exports.DEFAULT_CONFIG.maxBytes,
+        redact: cliOptions.redact ?? fileConfig.redact ?? exports.DEFAULT_CONFIG.redact,
+        respectGitignore: cliOptions.respectGitignore ??
+            fileConfig.respectGitignore ??
+            exports.DEFAULT_CONFIG.respectGitignore,
+        verbose: cliOptions.verbose ?? false
+    };
+}
+function buildAutoOutFile(rootPath, format) {
+    const rootName = path_1.default.basename(rootPath) || 'project';
+    const ext = format === 'md' ? 'md' : 'txt';
+    const now = new Date();
+    const stamp = [
+        now.getFullYear(),
+        pad(now.getMonth() + 1),
+        pad(now.getDate())
+    ].join('-');
+    const time = [pad(now.getHours()), pad(now.getMinutes()), pad(now.getSeconds())].join('');
+    return path_1.default.join('.code-context', `${rootName}_context_${stamp}_${time}.${ext}`);
+}
+function normalizeFormat(value) {
+    return value === 'md' ? 'md' : 'text';
+}
+function pad(value) {
+    return value.toString().padStart(2, '0');
+}

package/dist/exporters/markdown.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportMarkdown = exportMarkdown;
+const path_1 = __importDefault(require("path"));
+const tree_1 = require("./tree");
+const writer_1 = require("./writer");
+function formatBytes(size) {
+    return `${size} bytes`;
+}
+function formatDate(ms) {
+    return new Date(ms).toISOString();
+}
+function languageFromPath(filePath) {
+    const ext = path_1.default.extname(filePath).replace('.', '');
+    return ext || '';
+}
+async function writeFileSection(stream, file, redact) {
+    const language = languageFromPath(file.relativePath);
+    await (0, writer_1.writeText)(stream, `### ${file.relativePath}\n\n`);
+    await (0, writer_1.writeText)(stream, `- Size: ${formatBytes(file.size)}\n`);
+    await (0, writer_1.writeText)(stream, `- Modified: ${formatDate(file.mtimeMs)}\n\n`);
+    await (0, writer_1.writeText)(stream, `\`\`\`${language}\n`);
+    await (0, writer_1.streamFileContents)(stream, file.absolutePath, redact);
+    await (0, writer_1.writeText)(stream, '\n```\n\n');
+}
+async function exportMarkdown(result, config, output, metadata) {
+    await (0, writer_1.writeText)(output, '# LLM Context\n\n');
+    await (0, writer_1.writeText)(output, 'This file contains a deterministic snapshot of the repository: a folder tree and selected file contents.\n');
+    await (0, writer_1.writeText)(output, 'Use it for analysis, debugging, and planning changes.\n');
+    await (0, writer_1.writeText)(output, 'Treat redacted values as unavailable.\n\n');
+    const treeLines = (0, tree_1.buildTreeLines)(result.files.map((file) => file.relativePath), config.depth);
+    const totalBytes = result.files.reduce((sum, file) => sum + file.size, 0);
+    await (0, writer_1.writeText)(output, '# Code Context\n\n');
+    await (0, writer_1.writeText)(output, '## Metadata\n');
+    await (0, writer_1.writeText)(output, `- Root: ${result.rootPath}\n`);
+    await (0, writer_1.writeText)(output, `- Timestamp: ${new Date().toISOString()}\n`);
+    await (0, writer_1.writeText)(output, `- Version: ${metadata.version}\n`);
+    await (0, writer_1.writeText)(output, `- Command: ${metadata.command}\n`);
+    await (0, writer_1.writeText)(output, `- Config: format=${config.format} depth=${config.depth} maxBytes=${config.maxBytes} redact=${config.redact} respectGitignore=${config.respectGitignore}\n`);
+    await (0, writer_1.writeText)(output, `- Includes: ${config.include.length > 0 ? config.include.join(', ') : '(all)'}\n`);
+    await (0, writer_1.writeText)(output, `- Excludes: ${config.exclude.length > 0 ? config.exclude.join(', ') : '(defaults only)'}\n\n`);
+    await (0, writer_1.writeText)(output, '## Folder Tree\n\n');
+    await (0, writer_1.writeText)(output, '```\n');
+    for (const line of treeLines) {
+        await (0, writer_1.writeText)(output, `${line}\n`);
+    }
+    await (0, writer_1.writeText)(output, '```\n\n');
+    await (0, writer_1.writeText)(output, '## Included Files Summary\n');
+    await (0, writer_1.writeText)(output, `- Count: ${result.files.length}\n`);
+    await (0, writer_1.writeText)(output, `- Total Size: ${formatBytes(totalBytes)}\n\n`);
+    await (0, writer_1.writeText)(output, '## Skipped Files\n');
+    if (result.skipped.length === 0) {
+        await (0, writer_1.writeText)(output, '- (none)\n\n');
+    }
+    else {
+        for (const skipped of result.skipped) {
+            await (0, writer_1.writeText)(output, `- ${skipped.relativePath} (${skipped.reason})\n`);
+        }
+        await (0, writer_1.writeText)(output, '\n');
+    }
+    await (0, writer_1.writeText)(output, '## Files\n\n');
+    for (const file of result.files) {
+        await writeFileSection(output, file, config.redact);
+    }
+}

package/dist/exporters/text.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportText = exportText;
+const tree_1 = require("./tree");
+const writer_1 = require("./writer");
+function formatBytes(size) {
+    return `${size} bytes`;
+}
+function formatDate(ms) {
+    return new Date(ms).toISOString();
+}
+async function writeFileSection(stream, file, redact) {
+    await (0, writer_1.writeText)(stream, `---\n`);
+    await (0, writer_1.writeText)(stream, `File: ${file.relativePath}\n`);
+    await (0, writer_1.writeText)(stream, `Size: ${formatBytes(file.size)}\n`);
+    await (0, writer_1.writeText)(stream, `Modified: ${formatDate(file.mtimeMs)}\n`);
+    await (0, writer_1.writeText)(stream, '```\n');
+    await (0, writer_1.streamFileContents)(stream, file.absolutePath, redact);
+    await (0, writer_1.writeText)(stream, '\n```\n');
+}
+async function exportText(result, config, output, metadata) {
+    await (0, writer_1.writeText)(output, 'LLM Context\n');
+    await (0, writer_1.writeText)(output, 'This file contains a deterministic snapshot of the repository: a folder tree and selected file contents.\n');
+    await (0, writer_1.writeText)(output, 'Use it for analysis, debugging, and planning changes.\n');
+    await (0, writer_1.writeText)(output, 'Treat redacted values as unavailable.\n\n');
+    const treeLines = (0, tree_1.buildTreeLines)(result.files.map((file) => file.relativePath), config.depth);
+    const totalBytes = result.files.reduce((sum, file) => sum + file.size, 0);
+    await (0, writer_1.writeText)(output, 'Code Context\n');
+    await (0, writer_1.writeText)(output, `Root: ${result.rootPath}\n`);
+    await (0, writer_1.writeText)(output, `Timestamp: ${new Date().toISOString()}\n`);
+    await (0, writer_1.writeText)(output, `Version: ${metadata.version}\n`);
+    await (0, writer_1.writeText)(output, `Command: ${metadata.command}\n`);
+    await (0, writer_1.writeText)(output, `Config: format=${config.format} depth=${config.depth} maxBytes=${config.maxBytes} redact=${config.redact} respectGitignore=${config.respectGitignore}\n`);
+    await (0, writer_1.writeText)(output, `Includes: ${config.include.length > 0 ? config.include.join(', ') : '(all)'}\n`);
+    await (0, writer_1.writeText)(output, `Excludes: ${config.exclude.length > 0 ? config.exclude.join(', ') : '(defaults only)'}\n`);
+    await (0, writer_1.writeText)(output, '\nFolder Tree\n');
+    for (const line of treeLines) {
+        await (0, writer_1.writeText)(output, `${line}\n`);
+    }
+    await (0, writer_1.writeText)(output, '\nIncluded Files Summary\n');
+    await (0, writer_1.writeText)(output, `Count: ${result.files.length}\n`);
+    await (0, writer_1.writeText)(output, `Total Size: ${formatBytes(totalBytes)}\n`);
+    await (0, writer_1.writeText)(output, '\nSkipped Files\n');
+    if (result.skipped.length === 0) {
+        await (0, writer_1.writeText)(output, '(none)\n');
+    }
+    else {
+        for (const skipped of result.skipped) {
+            await (0, writer_1.writeText)(output, `${skipped.relativePath} - ${skipped.reason}\n`);
+        }
+    }
+    await (0, writer_1.writeText)(output, '\nFiles\n');
+    for (const file of result.files) {
+        await writeFileSection(output, file, config.redact);
+    }
+}

package/dist/exporters/tree.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTreeLines = buildTreeLines;
+const sort_1 = require("../utils/sort");
+function buildTreeLines(paths, depth) {
+    const root = { name: '.', isFile: false, children: new Map() };
+    for (const filePath of paths) {
+        const parts = filePath.split('/').filter(Boolean);
+        let node = root;
+        parts.forEach((part, index) => {
+            const isFile = index === parts.length - 1;
+            if (!node.children.has(part)) {
+                node.children.set(part, {
+                    name: part,
+                    isFile,
+                    children: new Map()
+                });
+            }
+            node = node.children.get(part);
+        });
+    }
+    const lines = [];
+    const maxDepth = depth;
+    function render(current, prefix, remainingDepth) {
+        if (remainingDepth <= 0) {
+            return;
+        }
+        const entries = Array.from(current.children.values()).sort((a, b) => (0, sort_1.compareEntries)({ name: a.name, isFile: a.isFile }, { name: b.name, isFile: b.isFile }));
+        for (const entry of entries) {
+            const suffix = entry.isFile ? '' : '/';
+            lines.push(`${prefix}${entry.name}${suffix}`);
+            if (!entry.isFile) {
+                render(entry, `${prefix}  `, remainingDepth - 1);
+            }
+        }
+    }
+    render(root, '', maxDepth);
+    return lines;
+}

package/dist/exporters/writer.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeText = writeText;
+exports.streamFileContents = streamFileContents;
+const events_1 = require("events");
+const fs_1 = require("fs");
+const stream_1 = require("stream");
+const redaction_1 = require("../redaction");
+class NormalizeTransform extends stream_1.Transform {
+    constructor(redact) {
+        super();
+        this.carry = '';
+        this.carrySize = 200;
+        this.redact = redact;
+    }
+    _transform(chunk, _encoding, callback) {
+        let text = this.carry + chunk.toString('utf8');
+        text = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+        if (this.redact) {
+            text = (0, redaction_1.redactText)(text);
+        }
+        const emitLength = Math.max(0, text.length - this.carrySize);
+        this.carry = text.slice(emitLength);
+        if (emitLength > 0) {
+            this.push(text.slice(0, emitLength));
+        }
+        callback();
+    }
+    _flush(callback) {
+        let text = this.carry;
+        if (this.redact) {
+            text = (0, redaction_1.redactText)(text);
+        }
+        if (text.length > 0) {
+            this.push(text);
+        }
+        callback();
+    }
+}
+async function writeText(stream, text) {
+    if (!stream.write(text)) {
+        await (0, events_1.once)(stream, 'drain');
+    }
+}
+async function streamFileContents(stream, filePath, redact) {
+    await new Promise((resolve, reject) => {
+        const reader = (0, fs_1.createReadStream)(filePath);
+        const transformer = new NormalizeTransform(redact);
+        reader.on('error', reject);
+        transformer.on('error', reject);
+        transformer.on('end', resolve);
+        reader.pipe(transformer).pipe(stream, { end: false });
+    });
+}

package/dist/redaction.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactText = redactText;
+const BLOCK_PATTERNS = [
+    /-----BEGIN [^-]+-----[\s\S]*?-----END [^-]+-----/g,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /\bASIA[0-9A-Z]{16}\b/g,
+    /\b(?:xox[baprs]-[A-Za-z0-9-]{10,})\b/g,
+    /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b/g,
+    /\b(?:sk_live|sk_test)_[A-Za-z0-9]{20,}\b/g,
+    /\beyJ[A-Za-z0-9_-]+?\.[A-Za-z0-9_-]+?\.[A-Za-z0-9_-]+?\b/g
+];
+const KEY_VALUE_PATTERN = /\b(api_key|apikey|token|secret|password|passphrase|key)\b(\s*[:=]\s*)['"]?([^'"\s]+)['"]?/gi;
+function redactText(input) {
+    let output = input;
+    output = output.replace(KEY_VALUE_PATTERN, (_match, key, separator) => {
+        return `${key}${separator}[REDACTED]`;
+    });
+    for (const pattern of BLOCK_PATTERNS) {
+        output = output.replace(pattern, '[REDACTED]');
+    }
+    return output;
+}

package/dist/scanner.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scan = scan;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const ignore_1 = __importDefault(require("ignore"));
+const config_1 = require("./config");
+const isBinary_1 = require("./utils/isBinary");
+const normalizePath_1 = require("./utils/normalizePath");
+async function loadGitignore(rootPath) {
+    const ig = (0, ignore_1.default)();
+    try {
+        const contents = await fs_1.promises.readFile(path_1.default.join(rootPath, '.gitignore'), 'utf8');
+        ig.add(contents);
+    }
+    catch {
+        return ig;
+    }
+    return ig;
+}
+async function scan(rootPath, options) {
+    const includeGlobs = options.include.length > 0 ? options.include : ['**/*'];
+    const excludeGlobs = [...config_1.DEFAULT_EXCLUDES, ...options.exclude];
+    const candidates = await (0, fast_glob_1.default)(includeGlobs, {
+        cwd: rootPath,
+        dot: true,
+        onlyFiles: true,
+        followSymbolicLinks: false,
+        unique: true,
+        absolute: true
+    });
+    const excludedSet = new Set();
+    if (excludeGlobs.length > 0) {
+        const excluded = await (0, fast_glob_1.default)(excludeGlobs, {
+            cwd: rootPath,
+            dot: true,
+            onlyFiles: true,
+            followSymbolicLinks: false,
+            unique: true,
+            absolute: false
+        });
+        for (const rel of excluded) {
+            excludedSet.add((0, normalizePath_1.normalizePath)(rel));
+        }
+    }
+    const ig = options.respectGitignore ? await loadGitignore(rootPath) : null;
+    const skipped = [];
+    const files = [];
+    for (const absPath of candidates) {
+        const relative = (0, normalizePath_1.normalizePath)(path_1.default.relative(rootPath, absPath));
+        if (excludedSet.has(relative)) {
+            skipped.push({ relativePath: relative, reason: 'excluded' });
+            continue;
+        }
+        if (ig && ig.ignores(relative)) {
+            skipped.push({ relativePath: relative, reason: 'excluded' });
+            continue;
+        }
+        let stats;
+        try {
+            stats = await fs_1.promises.stat(absPath);
+        }
+        catch (error) {
+            skipped.push({
+                relativePath: relative,
+                reason: 'unreadable',
+                detail: error.message
+            });
+            continue;
+        }
+        if (stats.size > options.maxBytes) {
+            skipped.push({ relativePath: relative, reason: 'too large' });
+            continue;
+        }
+        try {
+            if (await (0, isBinary_1.isBinaryFile)(absPath)) {
+                skipped.push({ relativePath: relative, reason: 'binary' });
+                continue;
+            }
+        }
+        catch (error) {
+            skipped.push({
+                relativePath: relative,
+                reason: 'unreadable',
+                detail: error.message
+            });
+            continue;
+        }
+        files.push({
+            relativePath: relative,
+            absolutePath: absPath,
+            size: stats.size,
+            mtimeMs: stats.mtimeMs
+        });
+    }
+    files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    skipped.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    return { rootPath, files, skipped };
+}

package/dist/utils/isBinary.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBinaryFile = isBinaryFile;
+const fs_1 = require("fs");
+async function isBinaryFile(filePath) {
+    const handle = await fs_1.promises.open(filePath, 'r');
+    try {
+        const buffer = Buffer.alloc(8000);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead === 0) {
+            return false;
+        }
+        let suspicious = 0;
+        for (let i = 0; i < bytesRead; i += 1) {
+            const byte = buffer[i];
+            if (byte === 0) {
+                return true;
+            }
+            if (byte < 7 || (byte > 14 && byte < 32)) {
+                suspicious += 1;
+            }
+        }
+        return suspicious / bytesRead > 0.3;
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/utils/normalizePath.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePath = normalizePath;
+function normalizePath(inputPath) {
+    return inputPath.replace(/\\/g, '/');
+}

package/dist/utils/sort.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareEntries = compareEntries;
+function compareEntries(a, b) {
+    if (a.isFile !== b.isFile) {
+        return a.isFile ? 1 : -1;
+    }
+    return a.name.localeCompare(b.name);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "code-context-extractor",
+  "version": "0.1.0",
+  "description": "Local-only CLI tool to extract codebase context into a single text or Markdown file.",
+  "license": "MIT",
+  "author": "Open Source Contributors",
+  "type": "commonjs",
+  "bin": {
+    "code-context-extractor": "dist/cli.js"
+  },
+  "main": "dist/cli.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  },
+  "dependencies": {
+    "commander": "^11.1.0",
+    "fast-glob": "^3.3.2",
+    "ignore": "^5.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.12",
+    "@typescript-eslint/eslint-plugin": "^7.11.0",
+    "@typescript-eslint/parser": "^7.11.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.2.5",
+    "tsx": "^4.11.0",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  }
+}