flatten-tool 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+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,127 @@
+# flatten-tool
+
+[![npm version](https://img.shields.io/npm/v/flatten-tool)](https://www.npmjs.com/package/flatten-tool)
+
+A CLI utility to flatten directory structures.
+
+## Installation
+
+Requires [Bun](https://bun.sh) runtime (v1.1+).
+
+```bash
+npm install -g flatten-tool
+```
+
+## Usage
+
+By default, the tool merges all file contents into a single Markdown file, with each file's content placed under a header with its relative path, followed by a code block with appropriate language highlighting based on the file extension. Ignores and filters are applied as usual.
+
+The `<source>` argument is optional and defaults to the current directory (`.`). The `<target>` argument is also optional and defaults to `flattened.md` (or `flattened/` when using `--directory`).
+
+### Options
+
+- `--directory`, `-d`: Flatten to individual files in a directory instead of merging to Markdown.
+- `--move`, `-m`: Move files instead of copying (original files will be deleted).
+- `--overwrite`, `-o`: Overwrite existing target files.
+- `--gitignore`, `-g`: Respect `.gitignore` files (default: true). Use `--no-gitignore` to disable.
+- `--help`, `-h`: Show help.
+- `--version`, `-v`: Show version.
+
+### Examples
+
+Flatten current directory to `flattened.md`:
+
+```bash
+flatten-tool
+```
+
+Flatten a specific directory to `flattened.md`:
+
+```bash
+flatten-tool /path/to/source
+```
+
+Flatten current directory to a custom Markdown file:
+
+```bash
+flatten-tool output.md
+```
+
+Flatten a specific directory to a custom Markdown file:
+
+```bash
+flatten-tool /path/to/source output.md
+```
+
+Flatten to individual files in a directory:
+
+```bash
+flatten-tool --directory
+```
+
+This creates a `flattened/` directory with flattened files.
+
+Flatten a specific directory to a custom output directory:
+
+```bash
+flatten-tool /path/to/source output-dir --directory
+```
+
+Move files instead of copying:
+
+```bash
+flatten-tool --move
+```
+
+Overwrite existing files:
+
+```bash
+flatten-tool --overwrite
+```
+
+Combine options:
+
+```bash
+flatten-tool /path/to/source output.md --move --overwrite
+```
+
+## Testing
+
+Run all tests:
+
+```bash
+bun test
+```
+
+Run tests in watch mode:
+
+```bash
+bun test --watch
+```
+
+Run a specific test:
+
+```bash
+bun test -t "flattens a simple nested directory"
+```
+
+## Development
+
+This project uses Bun for runtime, TypeScript for type safety, and follows the guidelines in `AGENTS.md` for coding standards.
+
+## Changelog
+
+### v1.2.0
+- Implemented streaming for Markdown merging to improve memory efficiency for large files/directories.
+- Updated documentation and coding guidelines.
+
+### v1.1.0
+- Made source argument optional (defaults to current directory).
+- Improved CLI defaults and options.
+
+### v1.0.0
+- Initial release with Markdown merging and directory flattening capabilities.
+
+## License
+
+This project was created using `bun init` in bun v1.3.8. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/index.ts

@@ -0,0 +1,216 @@
+#!/usr/bin/env bun
+import { copyFile, rename, rm, stat, mkdir, readdir, rmdir, readFile, writeFile } from 'node:fs/promises';
+import { join, relative, sep, resolve, extname } from 'node:path';
+import { createReadStream, createWriteStream } from 'node:fs';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { globby } from 'globby';
+import pkg from './package.json' assert { type: 'json' };
+
+function escapePathComponent(component: string): string {
+  return component.replace(/_/g, '__');
+}
+
+async function removeEmptyDirs(dir: string, root?: string): Promise<void> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      await removeEmptyDirs(join(dir, entry.name), root);
+    }
+  }
+  if (dir !== root) {
+    try {
+      await rmdir(dir);
+    } catch {
+      // Not empty, skip
+    }
+  }
+}
+
+export async function flattenDirectory(
+  source: string,
+  target: string,
+  move: boolean = false,
+  overwrite: boolean = false,
+  ignorePatterns: string[] = [],
+  respectGitignore: boolean = true,
+  flattenToDirectory: boolean = false
+): Promise<void> {
+  const absSource = resolve(source);
+  const absTarget = resolve(target);
+
+  if (absSource === absTarget) {
+    console.log('Source and target are the same; skipping.');
+    return;
+  }
+
+  const negativeIgnores = ignorePatterns.map(pattern => `!${pattern}`);
+
+  const files = await globby(['**', ...negativeIgnores], {
+    cwd: absSource,
+    gitignore: respectGitignore,
+    absolute: true,
+    dot: true,
+    onlyFiles: true,
+    ignore: ['.git'],
+  });
+
+  if (!flattenToDirectory) {
+    // Check if target exists
+    try {
+      await stat(absTarget);
+      if (!overwrite) {
+        throw new Error(`Target file "${absTarget}" already exists. Use --overwrite to force.`);
+      }
+      console.warn(`Overwriting existing file: ${absTarget}`);
+    } catch (err: any) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+
+    const writeStream = createWriteStream(absTarget);
+
+    for (const srcPath of files) {
+      const relPath = relative(absSource, srcPath).replace(/\\/g, '/');
+      let ext = extname(srcPath).slice(1) || 'text';
+      const isMd = ['md', 'markdown'].includes(ext.toLowerCase());
+      const ticks = isMd ? '````' : '```';
+
+      // Header + opening fence
+      writeStream.write(`# ${relPath}\n\n${ticks}${ext}\n`);
+
+      // Stream file content as UTF-8 text (matches previous readFile(..., 'utf8') behavior)
+      const readStream = createReadStream(srcPath, { encoding: 'utf8' });
+
+      await new Promise<void>((resolve, reject) => {
+        readStream.pipe(writeStream, { end: false });
+
+        readStream.on('end', () => {
+          // Closing fence + trailing newlines
+          writeStream.write(`\n${ticks}\n\n`);
+          resolve();
+        });
+
+        readStream.on('error', reject);
+        writeStream.on('error', reject);
+      });
+    }
+
+    // Finalise the output file
+    await new Promise<void>((resolve, reject) => {
+      writeStream.end();
+      writeStream.on('close', resolve);
+      writeStream.on('error', reject);
+    });
+
+    if (move) {
+      for (const srcPath of files) {
+        await rm(srcPath);
+      }
+      await removeEmptyDirs(absSource, absSource);
+    }
+  } else {
+    await mkdir(absTarget, { recursive: true });
+
+    for (const srcPath of files) {
+      const relPath = relative(absSource, srcPath);
+      const components = relPath.split(sep);
+      const escapedComponents = components.map(escapePathComponent);
+      const newName = escapedComponents.join('_');
+      const tgtPath = join(absTarget, newName);
+
+      try {
+        await stat(tgtPath);
+        if (!overwrite) {
+          throw new Error(`Target file "${tgtPath}" already exists. Use --overwrite to force.`);
+        }
+        console.warn(`Overwriting existing file: ${tgtPath}`);
+      } catch (err: any) {
+        if (err.code !== 'ENOENT') throw err;
+      }
+
+      if (move) {
+        await rename(srcPath, tgtPath);
+      } else {
+        await copyFile(srcPath, tgtPath);
+      }
+    }
+
+    if (move) {
+      await removeEmptyDirs(absSource, absSource);
+    }
+  }
+}
+
+// Main CLI logic
+if (import.meta.url === `file://${process.argv[1]}`) {
+  yargs(hideBin(process.argv))
+    .command('$0 [source] [target]', 'Flatten or merge a directory structure (default source: current directory)', (yargs) => {
+      yargs
+        .positional('source', {
+          describe: 'Directory to flatten (default: current directory ".")',
+          type: 'string',
+          default: '.',
+        })
+        .positional('target', {
+          describe: 'Target file or directory. Default: flattened.md or flattened/ depending on --directory',
+          type: 'string',
+        })
+        .option('move', {
+          alias: 'm',
+          describe: 'Move files instead of copying (original files will be deleted)',
+          type: 'boolean',
+          default: false,
+        })
+        .option('overwrite', {
+          alias: 'o',
+          describe: 'Overwrite existing files in target if conflicts occur',
+          type: 'boolean',
+          default: false,
+        })
+        .option('gitignore', {
+          alias: 'g',
+          describe: 'Respect .gitignore files (default: true). Use --no-gitignore to include everything',
+          type: 'boolean',
+          default: true,
+        })
+        .option('directory', {
+          alias: 'd',
+          describe: 'Flatten files into a directory structure (escaped filenames). When not set, merges everything into a single Markdown file (default behavior).',
+          type: 'boolean',
+          default: false,
+        })
+    }, async (argv) => {
+      let source = argv.source as string;           // now always defined (default '.')
+      let target = argv.target as string;           // may be undefined
+
+      const move: boolean = argv.move as boolean;
+      const overwrite: boolean = argv.overwrite as boolean;
+      const ignorePatterns: string[] = argv.ignore as string[] || [];
+      const respectGitignore: boolean = argv.gitignore as boolean;
+      const flattenToDirectory: boolean = argv.directory as boolean;
+
+      // If user didn't provide explicit target, choose sensible default
+      if (!target) {
+        target = flattenToDirectory
+          ? join(process.cwd(), 'flattened')
+          : join(process.cwd(), 'flattened.md');
+      }
+
+      try {
+        await stat(source);
+      } catch {
+        console.error(`Source directory "${source}" does not exist.`);
+        process.exit(1);
+      }
+
+      const action = move ? 'moved' : 'copied';
+      const mode = flattenToDirectory ? 'directory' : 'Markdown file';
+      await flattenDirectory(source, target, move, overwrite, ignorePatterns, respectGitignore, flattenToDirectory);
+      console.log(`Directory flattened successfully (${action}) into ${target} (${mode}).`);
+    })
+    .help('h')
+    .alias('h', 'help')
+    .version(pkg.version ?? '0.0.0')
+    .alias('v', 'version')
+    .parse();
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "flatten-tool",
+  "version": "1.2.0",
+  "description": "CLI tool to flatten directory structures: merge files into a single Markdown file (default) or copy/move to a flat directory with escaped filenames. Respects .gitignore, supports move/overwrite, and more.",
+  "module": "index.ts",
+  "type": "module",
+  "bin": {
+    "flatten-tool": "index.ts"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "keywords": [
+    "flatten",
+    "directory",
+    "cli",
+    "markdown",
+    "merge",
+    "filesystem",
+    "bun",
+    "gitignore"
+  ],
+  "author": "Your Name <your.email@example.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourusername/flatten-tool.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/flatten-tool/issues"
+  },
+  "homepage": "https://github.com/yourusername/flatten-tool#readme",
+  "files": [
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/yargs": "^17.0.35"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "globby": "^16.1.0",
+    "ignore": "^7.0.5",
+    "minimatch": "^10.1.1",
+    "yargs": "^18.0.0"
+  }
+}