dirforge-cli 0.1.0__tar.gz

dirforge_cli-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include example-structure.txt
+include pyproject.toml
+recursive-include tests *.py
+global-exclude __pycache__ *.py[cod]

dirforge_cli-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: dirforge-cli
+Version: 0.1.0
+Summary: Create project directory scaffolds from visual tree text files.
+Keywords: cli,scaffold,project-tree,directories,filesystem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+
+# DirForge
+
+DirForge is a dependency-free Python CLI that turns a visual project tree in a
+UTF-8 text file into real directories and empty files.
+
+> PyPI package name: `dirforge-cli`  
+> Installed command: `dirforge`
+
+The distribution uses `dirforge-cli` because `dirforge` is already registered
+to another project on PyPI.
+
+## Installation
+
+```bash
+python -m pip install dirforge-cli
+```
+
+DirForge requires Python 3.10 or newer and has no runtime dependencies.
+
+## Usage
+
+Create a text file such as `structure.txt`:
+
+```text
+project/
+├── src/
+│   └── app.py
+├── LICENSE
+├── Makefile
+└── .gitignore
+```
+
+Then create the scaffold:
+
+```bash
+dirforge structure.txt
+dirforge structure.txt --output ./projects
+dirforge structure.txt -o ./projects --dry-run --verbose
+```
+
+The repository script remains directly executable too:
+
+```bash
+python dirforge.py example-structure.txt --dry-run
+```
+
+## Tree Syntax
+
+Entries ending in `/` are directories. Every other entry is a file, including
+extensionless names such as `LICENSE` and `Makefile`. Blank lines and visual
+separator lines containing only `│` are ignored.
+
+## Options
+
+- `-o, --output`: Choose the directory that will contain the scaffold root.
+- `--dry-run`: Show planned changes without modifying the filesystem.
+- `--force`: Truncate existing files before recreating them.
+- `-v, --verbose`: Print every create, skip, or overwrite operation.
+- `--version`: Print the installed version.
+
+Existing directories are reused and existing files are preserved by default.
+DirForge rejects path traversal, absolute paths, separators inside node names,
+malformed indentation, children under files, and file/directory conflicts.
+
+## Development
+
+Run the test suite with only the standard library:
+
+```bash
+python -m unittest discover -v
+```
+
+Install the packaging tools and build both distribution formats:
+
+```bash
+python -m pip install -e '.[dev]'
+python -m build
+python -m twine check dist/*
+```
+
+Test the release on TestPyPI before publishing it publicly:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+python -m pip install --index-url https://test.pypi.org/simple/ dirforge-cli
+```
+
+After verifying the installed `dirforge` command, upload the same artifacts to
+PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+PyPI does not allow replacing an uploaded version. Increment `__version__` in
+`dirforge.py` before each new release; the build metadata reads it automatically.

dirforge_cli-0.1.0/README.md

@@ -0,0 +1,96 @@
+# DirForge
+
+DirForge is a dependency-free Python CLI that turns a visual project tree in a
+UTF-8 text file into real directories and empty files.
+
+> PyPI package name: `dirforge-cli`  
+> Installed command: `dirforge`
+
+The distribution uses `dirforge-cli` because `dirforge` is already registered
+to another project on PyPI.
+
+## Installation
+
+```bash
+python -m pip install dirforge-cli
+```
+
+DirForge requires Python 3.10 or newer and has no runtime dependencies.
+
+## Usage
+
+Create a text file such as `structure.txt`:
+
+```text
+project/
+├── src/
+│   └── app.py
+├── LICENSE
+├── Makefile
+└── .gitignore
+```
+
+Then create the scaffold:
+
+```bash
+dirforge structure.txt
+dirforge structure.txt --output ./projects
+dirforge structure.txt -o ./projects --dry-run --verbose
+```
+
+The repository script remains directly executable too:
+
+```bash
+python dirforge.py example-structure.txt --dry-run
+```
+
+## Tree Syntax
+
+Entries ending in `/` are directories. Every other entry is a file, including
+extensionless names such as `LICENSE` and `Makefile`. Blank lines and visual
+separator lines containing only `│` are ignored.
+
+## Options
+
+- `-o, --output`: Choose the directory that will contain the scaffold root.
+- `--dry-run`: Show planned changes without modifying the filesystem.
+- `--force`: Truncate existing files before recreating them.
+- `-v, --verbose`: Print every create, skip, or overwrite operation.
+- `--version`: Print the installed version.
+
+Existing directories are reused and existing files are preserved by default.
+DirForge rejects path traversal, absolute paths, separators inside node names,
+malformed indentation, children under files, and file/directory conflicts.
+
+## Development
+
+Run the test suite with only the standard library:
+
+```bash
+python -m unittest discover -v
+```
+
+Install the packaging tools and build both distribution formats:
+
+```bash
+python -m pip install -e '.[dev]'
+python -m build
+python -m twine check dist/*
+```
+
+Test the release on TestPyPI before publishing it publicly:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+python -m pip install --index-url https://test.pypi.org/simple/ dirforge-cli
+```
+
+After verifying the installed `dirforge` command, upload the same artifacts to
+PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+PyPI does not allow replacing an uploaded version. Increment `__version__` in
+`dirforge.py` before each new release; the build metadata reads it automatically.

dirforge_cli-0.1.0/dirforge.py

@@ -0,0 +1,397 @@
+#!/usr/bin/env python3
+"""Create a filesystem scaffold from a visual project tree."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+INVALID_INPUT = 2
+RUNTIME_FAILURE = 1
+
+BRANCH_RE = re.compile(r"^(?P<prefix>[ │]*)(?P<branch>[├└]──)\s*(?P<name>.+?)\s*$")
+WINDOWS_ABSOLUTE_RE = re.compile(r"^[A-Za-z]:[\\/]")
+
+__version__ = "0.1.0"
+
+
+class DirForgeError(Exception):
+    """Base class for expected, user-facing errors."""
+
+    exit_code = RUNTIME_FAILURE
+
+
+class InputError(DirForgeError):
+    """Raised when CLI input or tree syntax is invalid."""
+
+    exit_code = INVALID_INPUT
+
+
+@dataclass
+class TreeNode:
+    name: str
+    is_directory: bool
+    line_number: int
+    children: list["TreeNode"] = field(default_factory=list)
+
+
+@dataclass
+class ScaffoldStats:
+    dirs_created: int = 0
+    files_created: int = 0
+    entries_skipped: int = 0
+    dirs_to_create: int = 0
+    files_to_create: int = 0
+    existing_entries: int = 0
+    files_overwritten: int = 0
+
+
+def parse_arguments(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Create directories and empty files from a visual project tree stored in a .txt file.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""Examples:
+  dirforge structure.txt
+  dirforge structure.txt --output ./projects
+  python dirforge.py structure.txt
+  dirforge structure.txt -o ./projects --dry-run --verbose
+
+Tree syntax:
+  Names ending in / are directories. All other names are files.
+  Existing files are skipped by default so their contents are preserved.
+""",
+    )
+    parser.add_argument("tree_file", help="Path to a UTF-8 .txt file containing the project tree.")
+    parser.add_argument(
+        "-o",
+        "--output",
+        default=".",
+        help="Directory where the scaffold root should be created. Defaults to the current directory.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Parse and report planned changes without creating files or directories.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Truncate and recreate existing files. Warning: this can overwrite file contents.",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Print each create/skip operation.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser.parse_args(argv)
+
+
+def read_tree_file(path_text: str) -> list[str]:
+    path = Path(path_text)
+
+    if path.suffix.lower() != ".txt":
+        raise InputError("Input file must have a .txt extension.")
+    if not path.exists():
+        raise InputError(f"Input file does not exist: {path}")
+    if not path.is_file():
+        raise InputError(f"Input path is not a regular file: {path}")
+
+    try:
+        text = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        raise InputError(f"Input file is not valid UTF-8: {path}") from exc
+    except PermissionError as exc:
+        raise InputError(f"Input file cannot be read due to permissions: {path}") from exc
+    except OSError as exc:
+        raise InputError(f"Input file could not be read: {path}") from exc
+
+    if not text.strip():
+        raise InputError("Input file is empty.")
+
+    return text.splitlines()
+
+
+def is_visual_separator(line: str) -> bool:
+    stripped = line.strip()
+    return bool(stripped) and all(char in {"│", " "} for char in line)
+
+
+def normalize_node_name(raw_name: str, line_number: int) -> tuple[str, bool]:
+    name = raw_name.strip()
+    if not name:
+        raise InputError(f"Line {line_number}: entry name is empty.")
+
+    is_directory = name.endswith("/")
+    clean_name = name.rstrip("/") if is_directory else name
+    validate_node_name(clean_name, line_number)
+    return clean_name, is_directory
+
+
+def validate_node_name(name: str, line_number: int) -> None:
+    if not name:
+        raise InputError(f"Line {line_number}: entry name is empty.")
+    if name in {".", ".."}:
+        raise InputError(f"Line {line_number}: unsafe path name is not allowed: {name}")
+    if Path(name).is_absolute() or WINDOWS_ABSOLUTE_RE.match(name):
+        raise InputError(f"Line {line_number}: absolute paths are not allowed: {name}")
+    if "/" in name or "\\" in name:
+        raise InputError(f"Line {line_number}: path separators are not allowed inside an entry name: {name}")
+
+
+def indentation_depth(prefix: str, line_number: int) -> int:
+    if len(prefix) % 4 != 0:
+        raise InputError(
+            f"Invalid tree structure at line {line_number}. "
+            "Indentation must use four-character units."
+        )
+
+    for index in range(0, len(prefix), 4):
+        unit = prefix[index : index + 4]
+        if unit not in {"│   ", "    "}:
+            raise InputError(
+                f"Invalid tree structure at line {line_number}. "
+                "Indentation units must be either '│   ' or four spaces."
+            )
+
+    return len(prefix) // 4
+
+
+def parse_tree(lines: list[str]) -> TreeNode:
+    root: TreeNode | None = None
+    stack: list[tuple[int, TreeNode]] = []
+    previous_depth = 0
+
+    for line_number, raw_line in enumerate(lines, start=1):
+        line = raw_line.rstrip()
+        if not line.strip() or is_visual_separator(line):
+            continue
+
+        match = BRANCH_RE.match(line)
+
+        if root is None:
+            if match:
+                raise InputError("The first meaningful line must be the root directory without a branch marker.")
+
+            name, is_directory = normalize_node_name(line, line_number)
+            if not is_directory:
+                raise InputError(f"Line {line_number}: root entry must be a directory ending in '/'.")
+
+            root = TreeNode(name=name, is_directory=True, line_number=line_number)
+            stack = [(0, root)]
+            previous_depth = 0
+            continue
+
+        if not match:
+            raise InputError(f"Line {line_number}: invalid tree connector syntax.")
+
+        depth = indentation_depth(match.group("prefix"), line_number) + 1
+        name, is_directory = normalize_node_name(match.group("name"), line_number)
+
+        if depth > previous_depth + 1:
+            raise InputError(
+                f"Invalid tree structure at line {line_number}.\n"
+                f"Indentation jumped from level {previous_depth} to level {depth}."
+            )
+
+        while stack and stack[-1][0] >= depth:
+            stack.pop()
+
+        if not stack or stack[-1][0] != depth - 1:
+            raise InputError(f"Line {line_number}: entry cannot be attached to a valid parent.")
+
+        parent = stack[-1][1]
+        if not parent.is_directory:
+            raise InputError(
+                "A file cannot contain child entries.\n"
+                f"Line {line_number}: {name}"
+            )
+
+        node = TreeNode(name=name, is_directory=is_directory, line_number=line_number)
+        parent.children.append(node)
+        stack.append((depth, node))
+        previous_depth = depth
+
+    if root is None:
+        raise InputError("Tree contains no valid root entry.")
+
+    return root
+
+
+def iter_nodes(node: TreeNode, base: Path) -> list[tuple[TreeNode, Path]]:
+    current_path = base / node.name
+    entries = [(node, current_path)]
+    for child in node.children:
+        entries.extend(iter_nodes(child, current_path))
+    return entries
+
+
+def ensure_inside_output(path: Path, output_root: Path) -> None:
+    try:
+        path.resolve().relative_to(output_root.resolve())
+    except ValueError as exc:
+        raise InputError(f"Generated path escapes output directory: {path}") from exc
+
+
+def create_scaffold(
+    root: TreeNode,
+    output_dir: Path,
+    *,
+    dry_run: bool = False,
+    force: bool = False,
+    verbose: bool = False,
+) -> tuple[Path, ScaffoldStats]:
+    stats = ScaffoldStats()
+    output_root = output_dir.expanduser()
+    project_root = output_root / root.name
+
+    if force and not dry_run:
+        print("Warning: --force is enabled. Existing files may be truncated.", file=sys.stderr)
+
+    for node, target_path in iter_nodes(root, output_root):
+        ensure_inside_output(target_path, output_root)
+        exists = target_path.exists()
+
+        if node.is_directory:
+            handle_directory(target_path, exists, dry_run, verbose, stats)
+        else:
+            handle_file(target_path, exists, dry_run, force, verbose, stats)
+
+    return project_root, stats
+
+
+def handle_directory(
+    target_path: Path,
+    exists: bool,
+    dry_run: bool,
+    verbose: bool,
+    stats: ScaffoldStats,
+) -> None:
+    display_path = format_dir(target_path)
+
+    if exists:
+        if not target_path.is_dir():
+            raise DirForgeError(f"Cannot create directory '{target_path}' because a file exists at that path.")
+        stats.existing_entries += 1 if dry_run else 0
+        stats.entries_skipped += 0 if dry_run else 1
+        if verbose or dry_run:
+            print(("EXIST DIR    " if dry_run else "SKIP DIR    ") + display_path)
+        return
+
+    if dry_run:
+        stats.dirs_to_create += 1
+        print("[DIR]    " + display_path)
+        return
+
+    try:
+        target_path.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise DirForgeError(f"Cannot create directory '{target_path}': {exc}") from exc
+
+    stats.dirs_created += 1
+    if verbose:
+        print("CREATE DIR  " + display_path)
+
+
+def handle_file(
+    target_path: Path,
+    exists: bool,
+    dry_run: bool,
+    force: bool,
+    verbose: bool,
+    stats: ScaffoldStats,
+) -> None:
+    if exists:
+        if target_path.is_dir():
+            raise DirForgeError(f"Cannot create file '{target_path}' because a directory exists at that path.")
+        if dry_run:
+            stats.existing_entries += 1
+            print("EXIST FILE   " + str(target_path))
+            return
+        if force:
+            try:
+                target_path.write_text("", encoding="utf-8")
+            except OSError as exc:
+                raise DirForgeError(f"Cannot overwrite file '{target_path}': {exc}") from exc
+            stats.files_overwritten += 1
+            if verbose:
+                print("OVERWRITE FILE " + str(target_path))
+            return
+        stats.entries_skipped += 1
+        if verbose:
+            print("SKIP FILE   " + str(target_path))
+        return
+
+    if dry_run:
+        stats.files_to_create += 1
+        print("[FILE]   " + str(target_path))
+        return
+
+    try:
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        target_path.touch(exist_ok=False)
+    except OSError as exc:
+        raise DirForgeError(f"Cannot create file '{target_path}': {exc}") from exc
+
+    stats.files_created += 1
+    if verbose:
+        print("CREATE FILE " + str(target_path))
+
+
+def format_dir(path: Path) -> str:
+    return str(path) + "/"
+
+
+def print_summary(project_root: Path, stats: ScaffoldStats, *, dry_run: bool, force: bool) -> None:
+    if dry_run:
+        print("\nDry run completed successfully.\n")
+        print("Root:")
+        print(f"  {project_root.resolve()}")
+        print()
+        print(f"Directories to create: {stats.dirs_to_create}")
+        print(f"Files to create:       {stats.files_to_create}")
+        print(f"Existing entries:      {stats.existing_entries}")
+        print("\nNo filesystem changes were made.")
+        return
+
+    print("\nScaffold created successfully.\n")
+    print("Root:")
+    print(f"  {project_root.resolve()}")
+    print()
+    print(f"Directories created: {stats.dirs_created}")
+    print(f"Files created:       {stats.files_created}")
+    print(f"Entries skipped:     {stats.entries_skipped}")
+    if force:
+        print(f"Files overwritten:   {stats.files_overwritten}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        args = parse_arguments(argv)
+        lines = read_tree_file(args.tree_file)
+        tree = parse_tree(lines)
+        project_root, stats = create_scaffold(
+            tree,
+            Path(args.output),
+            dry_run=args.dry_run,
+            force=args.force,
+            verbose=args.verbose,
+        )
+        print_summary(project_root, stats, dry_run=args.dry_run, force=args.force)
+        return 0
+    except DirForgeError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return exc.exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dirforge_cli-0.1.0/dirforge_cli.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: dirforge-cli
+Version: 0.1.0
+Summary: Create project directory scaffolds from visual tree text files.
+Keywords: cli,scaffold,project-tree,directories,filesystem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+
+# DirForge
+
+DirForge is a dependency-free Python CLI that turns a visual project tree in a
+UTF-8 text file into real directories and empty files.
+
+> PyPI package name: `dirforge-cli`  
+> Installed command: `dirforge`
+
+The distribution uses `dirforge-cli` because `dirforge` is already registered
+to another project on PyPI.
+
+## Installation
+
+```bash
+python -m pip install dirforge-cli
+```
+
+DirForge requires Python 3.10 or newer and has no runtime dependencies.
+
+## Usage
+
+Create a text file such as `structure.txt`:
+
+```text
+project/
+├── src/
+│   └── app.py
+├── LICENSE
+├── Makefile
+└── .gitignore
+```
+
+Then create the scaffold:
+
+```bash
+dirforge structure.txt
+dirforge structure.txt --output ./projects
+dirforge structure.txt -o ./projects --dry-run --verbose
+```
+
+The repository script remains directly executable too:
+
+```bash
+python dirforge.py example-structure.txt --dry-run
+```
+
+## Tree Syntax
+
+Entries ending in `/` are directories. Every other entry is a file, including
+extensionless names such as `LICENSE` and `Makefile`. Blank lines and visual
+separator lines containing only `│` are ignored.
+
+## Options
+
+- `-o, --output`: Choose the directory that will contain the scaffold root.
+- `--dry-run`: Show planned changes without modifying the filesystem.
+- `--force`: Truncate existing files before recreating them.
+- `-v, --verbose`: Print every create, skip, or overwrite operation.
+- `--version`: Print the installed version.
+
+Existing directories are reused and existing files are preserved by default.
+DirForge rejects path traversal, absolute paths, separators inside node names,
+malformed indentation, children under files, and file/directory conflicts.
+
+## Development
+
+Run the test suite with only the standard library:
+
+```bash
+python -m unittest discover -v
+```
+
+Install the packaging tools and build both distribution formats:
+
+```bash
+python -m pip install -e '.[dev]'
+python -m build
+python -m twine check dist/*
+```
+
+Test the release on TestPyPI before publishing it publicly:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+python -m pip install --index-url https://test.pypi.org/simple/ dirforge-cli
+```
+
+After verifying the installed `dirforge` command, upload the same artifacts to
+PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+PyPI does not allow replacing an uploaded version. Increment `__version__` in
+`dirforge.py` before each new release; the build metadata reads it automatically.

dirforge_cli-0.1.0/dirforge_cli.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+MANIFEST.in
+README.md
+dirforge.py
+example-structure.txt
+pyproject.toml
+dirforge_cli.egg-info/PKG-INFO
+dirforge_cli.egg-info/SOURCES.txt
+dirforge_cli.egg-info/dependency_links.txt
+dirforge_cli.egg-info/entry_points.txt
+dirforge_cli.egg-info/requires.txt
+dirforge_cli.egg-info/top_level.txt
+tests/__init__.py
+tests/test_dirforge.py

dirforge_cli-0.1.0/dirforge_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dirforge_cli-0.1.0/dirforge_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dirforge = dirforge:main

dirforge_cli-0.1.0/dirforge_cli.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+build>=1.2
+twine>=5

dirforge_cli-0.1.0/dirforge_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+dirforge

dirforge_cli-0.1.0/example-structure.txt

@@ -0,0 +1,25 @@
+meta-ads-analytics/
+│
+├── composer.json
+├── README.md
+├── LICENSE
+├── .gitignore
+│
+├── src/
+│   ├── MetaAds.php
+│   │
+│   ├── Config/
+│   │   ├── MetaConfig.php
+│   │   └── ConfigurationValidator.php
+│   │
+│   └── Client/
+│       ├── MetaClient.php
+│       └── MetaClientInterface.php
+│
+├── tests/
+│   ├── Unit/
+│   └── bootstrap.php
+│
+└── docs/
+    ├── configuration.md
+    └── architecture.md

dirforge_cli-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dirforge-cli"
+dynamic = ["version"]
+description = "Create project directory scaffolds from visual tree text files."
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["cli", "scaffold", "project-tree", "directories", "filesystem"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: System :: Filesystems",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2",
+    "twine>=5",
+]
+
+[project.scripts]
+dirforge = "dirforge:main"
+
+[tool.setuptools]
+py-modules = ["dirforge"]
+
+[tool.setuptools.dynamic]
+version = {attr = "dirforge.__version__"}
+
+[tool.setuptools.data-files]
+"share/doc/dirforge-cli" = ["example-structure.txt"]

dirforge_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dirforge_cli-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+"""DirForge test suite."""

dirforge_cli-0.1.0/tests/test_dirforge.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+import dirforge
+
+
+VALID_TREE = """\
+sample-project/
+├── README.md
+├── src/
+│   └── main.py
+└── LICENSE
+"""
+
+
+class ParseTreeTests(unittest.TestCase):
+    def test_parses_directories_and_extensionless_files(self) -> None:
+        root = dirforge.parse_tree(VALID_TREE.splitlines())
+
+        self.assertEqual(root.name, "sample-project")
+        self.assertTrue(root.is_directory)
+        self.assertEqual([child.name for child in root.children], ["README.md", "src", "LICENSE"])
+        self.assertFalse(root.children[-1].is_directory)
+        self.assertEqual(root.children[1].children[0].name, "main.py")
+
+    def test_rejects_path_traversal(self) -> None:
+        with self.assertRaisesRegex(dirforge.InputError, "unsafe path name"):
+            dirforge.parse_tree(["project/", "└── ../"])
+
+    def test_rejects_children_beneath_files(self) -> None:
+        tree = ["project/", "└── README.md", "    └── child.txt"]
+
+        with self.assertRaisesRegex(dirforge.InputError, "file cannot contain"):
+            dirforge.parse_tree(tree)
+
+
+class ScaffoldTests(unittest.TestCase):
+    def test_creates_tree_and_preserves_existing_files(self) -> None:
+        root = dirforge.parse_tree(VALID_TREE.splitlines())
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            output = Path(temp_dir)
+            project_root, first_stats = dirforge.create_scaffold(root, output)
+            readme = project_root / "README.md"
+            readme.write_text("keep me", encoding="utf-8")
+
+            _, second_stats = dirforge.create_scaffold(root, output)
+
+            self.assertEqual(first_stats.dirs_created, 2)
+            self.assertEqual(first_stats.files_created, 3)
+            self.assertEqual(readme.read_text(encoding="utf-8"), "keep me")
+            self.assertEqual(second_stats.entries_skipped, 5)
+
+    def test_dry_run_does_not_write_to_disk(self) -> None:
+        root = dirforge.parse_tree(VALID_TREE.splitlines())
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            output = Path(temp_dir)
+            _, stats = dirforge.create_scaffold(root, output, dry_run=True)
+
+            self.assertFalse((output / "sample-project").exists())
+            self.assertEqual(stats.dirs_to_create, 2)
+            self.assertEqual(stats.files_to_create, 3)
+
+
+class CommandLineTests(unittest.TestCase):
+    def test_version_flag(self) -> None:
+        result = subprocess.run(
+            [sys.executable, str(Path(dirforge.__file__)), "--version"],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+
+        self.assertEqual(result.returncode, 0)
+        self.assertIn(dirforge.__version__, result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()