feat: add clipboard copy support with -c/--copy and --copy-only flags

Author: nikolay-e

docs/Clipboard Copy.md

@@ -0,0 +1,244 @@
+## Plan: Improved Markdown (`md`) output format
+
+Add `md` as a first-class output format that produces a single, readable Markdown document with:
+
+* **dynamic `#` headings** based on directory depth
+* **directories distinguished with trailing `/`**
+* **file contents in fenced blocks** using inferred languages (for syntax highlighting)
+* **robust handling** of deep nesting, placeholder content, and backticks inside files
+
+---
+
+## Goals
+
+1. Generate a Markdown document that’s pleasant in GitHub/Markdown viewers *and* copy-pastable into LLMs.
+2. Preserve file content **byte-for-byte (as text)** (no transformations beyond ensuring it ends with `\n` already done in `tree.py`).
+3. Avoid broken Markdown in real-world repos (especially due to backticks in code).
+
+---
+
+## Output specification
+
+### 1) Headings & hierarchy
+
+* Root directory node:
+
+  * `# <root>/`
+* Each child directory/file:
+
+  * heading level = `depth + 1` (root depth = 0 → `#`)
+* Max heading level:
+
+  * Use headings only up to `######` (depth ≤ 5)
+  * Beyond that: switch to **indented bullet + bold name** to preserve structure
+
+Example deep nesting rendering (depth > 5):
+
+```md
+###### l5/
+  - **l6/**
+    - **l7/**
+```
+
+### 2) Directory vs file names
+
+* Directories: `name/`
+* Files: `name` (no slash)
+
+### 3) File content blocks
+
+* If a node has `"content"`:
+
+  * Emit fenced block with language: <code>`python</code>, <code>`toml</code>, etc.
+  * If language unknown → plain fence (no language)
+
+### 4) Placeholder content (binary / unreadable / too large)
+
+TreeMapper already emits placeholders like:
+
+* `<file too large: N bytes>`
+* `<binary file: N bytes>`
+* `<unreadable content: not utf-8>`
+* `<unreadable content>`
+
+For these, emit **italic inline** (no code fence), e.g.:
+
+```md
+_<binary file: 2048 bytes>_
+```
+
+### 5) Backticks inside content (critical robustness fix)
+
+If file content contains triple backticks, a normal fence breaks Markdown.
+
+Solution:
+
+* Choose a fence delimiter longer than any run of backticks in the content.
+* Example: if content contains `, use ` as fence.
+
+This guarantees the Markdown remains valid while keeping file content unchanged.
+
+---
+
+## Implementation
+
+### A) CLI: add `md` format
+
+File: `src/treemapper/cli.py`
+
+* Extend `--format` choices to `["yaml", "json", "text", "md"]`
+
+Optionally (nice usability):
+
+* support alias `"markdown"` too (mapped to `"md"` internally), but **not required** for v1.
+
+---
+
+### B) Writer: add Markdown serializer
+
+File: `src/treemapper/writer.py`
+
+Add:
+
+1. **Language mapping**
+
+* Use the richer mapping you provided (`EXTENSION_TO_LANG`, `FILENAME_TO_LANG`)
+* Keep `Path(filename).suffix.lower()` for extension lookup
+* Use `filename.lower()` for filename lookup
+
+2. **Fence length selection**
+
+* Find longest run of backticks in content and pick a longer fence
+* Always at least 3 backticks
+
+3. **Placeholder detection**
+   Avoid false positives (e.g., real HTML file that starts with `<tag>`).
+   Implement a strict check against known placeholder patterns TreeMapper produces.
+
+Recommended:
+
+* `content_stripped = content.strip()`
+* return `True` if:
+
+  * `content_stripped == "<unreadable content>"`
+  * `content_stripped == "<unreadable content: not utf-8>"`
+  * `content_stripped.startswith("<binary file:") and content_stripped.endswith(">")`
+  * `content_stripped.startswith("<file too large:") and content_stripped.endswith(">")`
+
+4. **Deep nesting formatting**
+
+* For depth ≤ 5: headings `#`…`######`
+* For depth ≥ 6: use indentation + bullet + bold, preserving hierarchy
+
+---
+
+### C) Writer dispatcher: route `md`
+
+File: `src/treemapper/writer.py`
+Update `write_tree_to_file()` dispatcher:
+
+* `elif output_format == "md": write_tree_markdown(f, tree)`
+
+---
+
+### D) Public API: `to_markdown`
+
+File: `src/treemapper/__init__.py`
+
+* Import `write_tree_markdown`
+* Add `to_markdown(tree) -> str`
+* Add to `__all__`
+
+Optional convenience (safe):
+
+* add `to_md = to_markdown` alias (doesn’t break anything, just adds a shorter name)
+
+---
+
+## Proposed function behavior (pseudocode structure)
+
+* `write_tree_markdown(file, tree)`:
+
+  * recursive `walk(node, depth)`
+  * if directory:
+
+    * emit heading (or bullet+bold if deep)
+    * recurse children
+  * else file:
+
+    * emit heading (or bullet+bold if deep)
+    * if content missing: just spacing
+    * else if placeholder: italic line
+    * else:
+
+      * fence = longest_backtick_run+1 (min 3)
+      * lang = inferred
+      * emit fence + lang + content + closing fence
+
+---
+
+## Documentation updates
+
+* `CLAUDE.md` (and/or README):
+
+  * add examples:
+
+    * `treemapper . --format md`
+    * `treemapper . --format md -o context.md`
+  * briefly explain headings + fenced code blocks
+
+---
+
+## Testing plan
+
+### Unit tests (add to existing test suite)
+
+1. **Basic structure**
+
+* root heading `# root/`
+* nested dir headings increment
+* file headings render at correct depth
+
+2. **Language detection**
+
+* `.py` → `python`
+* `Makefile` → `makefile`
+* `.yml` → `yaml`
+* unknown ext → empty language
+
+3. **Placeholder formatting**
+
+* `<binary file: ...>` results in italic and **no code fence** for that file
+
+4. **Deep nesting**
+
+* depth 5 uses `######`
+* depth 6 uses bullet+bold with indentation
+
+5. **Backtick safety**
+
+* file content contains ``` inside
+* output uses a longer fence (e.g. ````) and remains balanced
+
+---
+
+## Verification commands
+
+```bash
+treemapper . --format md --max-depth 2
+treemapper . --format md -o codebase.md
+treemapper . --format md --no-content
+```
+
+---
+
+## Notes on compatibility with your current codebase
+
+* Fits your existing architecture cleanly:
+
+  * CLI just adds a choice
+  * writer gains a new serializer and dispatcher branch
+  * public API mirrors existing `to_yaml/to_json/to_text`
+* No new dependencies, no changes to tree-building logic, and no changes required to ignore handling.
+
+If you want, I can also produce a patch-style diff for the exact files (`cli.py`, `writer.py`, `__init__.py`) that matches your current structure and naming conventions.

docs/MD Format.md

@@ -18,6 +18,8 @@ class ParsedArgs:
     max_depth: Optional[int]
     no_content: bool
     max_file_bytes: Optional[int]
+    copy: bool
+    copy_only: bool
 
 
 DEFAULT_IGNORES_HELP = """
@@ -56,6 +58,8 @@ def parse_args() -> ParsedArgs:
     parser.add_argument("--max-depth", type=int, default=None, metavar="N", help="Maximum traversal depth")
     parser.add_argument("--no-content", action="store_true", help="Skip file contents (structure only)")
     parser.add_argument("--max-file-bytes", type=int, default=None, metavar="N", help="Skip files larger than N bytes")
+    parser.add_argument("-c", "--copy", action="store_true", help="Copy output to clipboard")
+    parser.add_argument("--copy-only", action="store_true", help="Copy to clipboard only (no stdout/file output)")
     parser.add_argument(
         "-v",
         "--verbosity",
@@ -109,4 +113,6 @@ def parse_args() -> ParsedArgs:
         max_depth=args.max_depth,
         no_content=args.no_content,
         max_file_bytes=args.max_file_bytes,
+        copy=args.copy or args.copy_only,
+        copy_only=args.copy_only,
     )