tree-fs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ghazi
+
+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,154 @@
+# tree-fs
+
+**tree-fs** is a tiny, zero-dependency Node.js utility that turns text-based directory trees into physical files and folders.
+
+It is designed to be the **standard "Paste & Go" receiver for AI-generated code**.
+
+[![npm version](https://img.shields.io/npm/v/tree-fs.svg)](https://www.npmjs.com/package/tree-fs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## ⚡ Why tree-fs?
+
+LLMs (ChatGPT, Claude, DeepSeek) are great at planning architectures but bad at executing them.
+They often output this:
+
+```text
+my-app
+├── src
+│   ├── index.js
+│   └── utils.js
+└── README.md
+```
+
+Copying that structure manually is tedious. **tree-fs** makes it instant.
+
+### Features
+*   **AI Compatible:** Strips comments (`# entry point`) and handles weird Markdown formatting.
+*   **Deterministic:** Same text input = same file structure. Always.
+*   **Safe:** Never overwrites existing files by default.
+*   **Smart:** Distinguishes `v1.0` (folder) from `v1.0.js` (file) automatically.
+*   **Zero Dependencies:** Installs in seconds.
+
+---
+
+## 🚀 Usage
+
+### 1. Interactive Mode (The "Paste" Workflow)
+
+Perfect for when ChatGPT gives you a project structure.
+
+```bash
+npx tree-fs
+```
+*(You don't even need to install it!)*
+
+1.  Paste your tree.
+2.  Press **Enter twice**.
+3.  Done.
+
+### 2. CLI with File Input
+
+Generate structure from a text file saved in your repo.
+
+```bash
+tree-fs structure.txt
+```
+
+### 3. Programmatic API (For Tool Builders)
+
+Embed `tree-fs` into your own CLIs, generators, or scripts.
+
+```bash
+npm install tree-fs
+```
+
+```javascript
+const { parseTree, generateFS } = require("tree-fs")
+const path = require("path")
+
+const treeInput = `
+backend-api
+├── src
+│   ├── controllers/
+│   └── models/
+└── .env
+`
+
+// 1. Parse text into JSON AST
+const tree = parseTree(treeInput)
+
+// 2. Generate files at the target directory
+generateFS(tree, path.resolve(__dirname, "./output"))
+
+console.log("Structure created!")
+```
+
+---
+
+## 💡 Syntax Guide & Robustness
+
+tree-fs is built to handle the "messy reality" of text inputs.
+
+### 1. Comments are ignored
+Great for annotated AI outputs.
+```text
+src
+├── auth.js  # Handles JWT tokens
+└── db.js    # Connection logic
+```
+*Result: Creates `auth.js` and `db.js`. Comments are stripped.*
+
+### 2. Explicit Folders
+If a name looks like a file but is actually a folder (e.g., version numbers), end it with a slash `/`.
+```text
+api
+├── v1.5/     <-- Created as a folder
+└── v2.0/     <-- Created as a folder
+```
+
+### 3. Smart Nesting
+If an item has children indented below it, it is **automatically treated as a folder**, even if it has a dot.
+```text
+app
+└── v2.5            <-- Treated as folder because it has a child
+    └── migrator.js
+```
+
+### 4. Markdown & Symbols
+We handle standard tree characters, ASCII art, and bullets.
+```text
+project
+- src
+  + components
+    > Header.jsx
+* public
+  - logo.png
+```
+
+### 5. Config Files
+Known files without extensions are correctly identified as files.
+*   `Dockerfile`, `Makefile`, `LICENSE`, `Procfile`, `.gitignore`, `Jenkinsfile`
+
+---
+
+## 📦 CI/CD Integration
+
+You can use `tree-fs` to scaffold environments in GitHub Actions or pipelines.
+
+```yaml
+- name: Scaffold Directory
+  run: npx tree-fs structure.txt
+```
+
+To test without writing files (Dry Run):
+```bash
+tree-fs structure.txt --dry-run
+```
+
+---
+
+## License
+
+MIT

package/bin/tree-fs.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+const fs = require("fs")
+const readline = require("readline")
+const { parseTree, generateFS } = require("../src")
+
+const args = process.argv.slice(2)
+const dryRun = args.includes("--dry-run")
+
+async function readInteractiveInput() {
+  console.log("Paste directory tree. Press Enter on an empty line to finish.\n")
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false // This helps handle raw paste streams better
+  })
+
+  const lines = []
+
+  for await (const line of rl) {
+    // If the line is empty (user hit Enter on a new line), we are done.
+    if (line.trim() === "") {
+      rl.close()
+      break
+    }
+    lines.push(line)
+  }
+
+  return lines.join("\n")
+}
+
+async function main() {
+  let input = ""
+
+  // Programmatic / CI / file input
+  if (args[0] && !args[0].startsWith("--")) {
+    try {
+      input = fs.readFileSync(args[0], "utf8")
+    } catch (err) {
+      console.error(`Error reading file: ${args[0]}`)
+      process.exit(1)
+    }
+  }
+  // Interactive mode
+  else {
+    input = await readInteractiveInput()
+  }
+
+  if (!input.trim()) {
+    console.error("No tree input provided.")
+    process.exit(1)
+  }
+
+  try {
+    const tree = parseTree(input)
+    generateFS(tree, process.cwd(), { dryRun })
+    
+    if (dryRun) {
+      console.log("Dry run complete. No files written.")
+    } else {
+      console.log("✅ Structure created successfully.")
+    }
+  } catch (error) {
+    console.error("Failed to generate structure:", error.message)
+    process.exit(1)
+  }
+}
+
+main()

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "tree-fs",
+  "version": "0.1.0",
+  "description": "Generate file system structures from text-based directory trees. The standard receiver for AI-generated project scaffolding.",
+  "bin": {
+    "tree-fs": "bin/tree-fs.js"
+  },
+  "main": "src/index.js",
+  "type": "commonjs",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node bin/tree-fs.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mgks/tree-fs.git"
+  },
+  "keywords": [
+    "filesystem",
+    "scaffold",
+    "tree",
+    "directory-structure",
+    "generator",
+    "llm",
+    "ai",
+    "automation",
+    "cli"
+  ],
+  "author": "Ghazi <hello@mgks.dev> (https://mgks.dev)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mgks/tree-fs/issues"
+  },
+  "homepage": "https://github.com/mgks/tree-fs"
+}

package/src/generator.js

@@ -0,0 +1,60 @@
+// src/generator.js
+const fs = require("fs")
+const path = require("path")
+
+function generateFS(tree, baseDir = process.cwd(), options = {}) {
+  const {
+    dryRun = false,
+    overwrite = false
+  } = options
+
+  if (!tree || tree.length === 0) return
+
+  let nodes = tree
+  let rootPath = baseDir
+
+  // Intelligent Root Detection:
+  // If there is exactly one top-level folder, we treat it as the project root.
+  if (nodes.length === 1 && nodes[0].type === "folder") {
+    rootPath = path.join(baseDir, nodes[0].name)
+    nodes = nodes[0].children
+    
+    // Create the root directory physically
+    if (!dryRun && !fs.existsSync(rootPath)) {
+      fs.mkdirSync(rootPath, { recursive: true })
+    }
+  }
+
+  function walk(nodes, currentPath) {
+    for (const node of nodes) {
+      // Robustness: normalize path separators for cross-platform safety
+      const target = path.join(currentPath, node.name)
+
+      if (node.type === "folder") {
+        if (!fs.existsSync(target)) {
+          if (!dryRun) fs.mkdirSync(target, { recursive: true })
+        }
+        if (node.children && node.children.length > 0) {
+          walk(node.children, target)
+        }
+      } else {
+        // File handling
+        if (fs.existsSync(target) && !overwrite) {
+          continue
+        }
+        
+        // Ensure parent directory exists (handles cases like "src/utils/helpers.js" as a single line)
+        const parentDir = path.dirname(target)
+        if (!dryRun && !fs.existsSync(parentDir)) {
+          fs.mkdirSync(parentDir, { recursive: true })
+        }
+
+        if (!dryRun) fs.writeFileSync(target, "")
+      }
+    }
+  }
+
+  walk(nodes, rootPath)
+}
+
+module.exports = { generateFS }

package/src/index.js

@@ -0,0 +1,7 @@
+const { parseTree } = require("./parser")
+const { generateFS } = require("./generator")
+
+module.exports = {
+  parseTree,
+  generateFS
+}

package/src/normaliser.js

@@ -0,0 +1,39 @@
+// src/normaliser.js
+
+// 1. Expanded Regex to catch +, >, and markdown bullets
+const STRIP_REGEX = /^[\s│├└─•*|\-+>]+/
+
+function normaliseLines(input) {
+  return input
+    .split("\n")
+    .map(line => line.replace(/\r/g, ""))
+    .filter(Boolean)
+    .map(raw => {
+      // 2. Detect indentation based on prefix length
+      const match = raw.match(STRIP_REGEX)
+      const prefixLength = match ? match[0].length : 0
+      
+      // 3. Strip comments (anything after ' #')
+      // We explicitly look for " #" so we don't break "page#1.js"
+      const commentIndex = raw.indexOf(" #")
+      let cleaned = commentIndex !== -1 ? raw.substring(0, commentIndex) : raw
+
+      // 4. Check for explicit trailing slash (User saying "This is a folder/")
+      const endsWithSlash = cleaned.trim().endsWith("/")
+
+      cleaned = cleaned
+        .replace(STRIP_REGEX, "") // Remove tree characters
+        .replace(/\/$/, "")       // Remove that trailing slash for the name
+        .trim()
+
+      return {
+        raw,
+        indent: prefixLength,
+        name: cleaned,
+        explicitFolder: endsWithSlash // Pass this signal to the parser
+      }
+    })
+    .filter(line => line.name.length > 0)
+}
+
+module.exports = { normaliseLines }

package/src/parser.js

@@ -0,0 +1,56 @@
+const { normaliseLines } = require("./normaliser")
+const { isFile } = require("./utils")
+
+function parseTree(input) {
+  const lines = normaliseLines(input)
+  const root = { name: "__root__", type: "folder", children: [] }
+  
+  // Stack keeps track of [ { node, indent } ]
+  const stack = [{ node: root, indent: -1 }]
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const nextLine = lines[i + 1]
+
+    // It is a folder IF:
+    // 1. It ends with '/' (Explicit)
+    // 2. The NEXT line exists AND has a deeper indent (Implicit Parent)
+    // 3. It does NOT pass the isFile check (Standard folder)
+    
+    let isFolder = false
+    
+    if (line.explicitFolder) {
+      isFolder = true
+    } else if (nextLine && nextLine.indent > line.indent) {
+      // If the next item is indented deeper, THIS item must be a folder to hold it.
+      isFolder = true
+    } else {
+      // Fallback to name-based checking
+      isFolder = !isFile(line.name)
+    }
+
+    const node = {
+      name: line.name,
+      type: isFolder ? "folder" : "file",
+      children: []
+    }
+
+    // Standard stack unwinding
+    while (stack.length && line.indent <= stack[stack.length - 1].indent) {
+      stack.pop()
+    }
+
+    // Add to parent
+    const parent = stack[stack.length - 1].node
+    parent.children.push(node)
+
+    // Push to stack if folder
+    if (isFolder) {
+      stack.push({ node, indent: line.indent })
+    }
+  }
+
+  return root.children
+}
+
+module.exports = { parseTree }

package/src/utils.js

@@ -0,0 +1,25 @@
+// src/utils.js
+
+// Common files that have no extension but should be treated as files
+const KNOWN_FILES = new Set([
+  "LICENSE", "licence",
+  "README", "readme",
+  "Dockerfile", "dockerfile",
+  "Makefile", "makefile",
+  "Jenkinsfile",
+  "Procfile",
+  "CNAME",
+  ".gitignore", ".env", ".npmrc", ".dockerignore", ".editorconfig"
+])
+
+function isFile(name) {
+  // Check exact matches (case-insensitive for safety if needed, but Sets are exact)
+  if (KNOWN_FILES.has(name)) return true
+  
+  // Standard extension check: dot followed by 1-5 chars (e.g., .js, .json, .java)
+  // We avoid detecting "v1.2" as a file by ensuring the extension is letters only
+  // OR if it ends in specific known formats like .tar.gz
+  return /\.[a-zA-Z0-9]{1,10}$/.test(name)
+}
+
+module.exports = { isFile }