snap-scaffold 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+# snap-scaffold
+
+A CLI to **snapshot** your directory structure into a plain-text file and **restore** it anywhere — including from pasted text.
+
+---
+
+## Install
+
+```bash
+npm install -g snap-scaffold
+```
+
+---
+
+## Commands
+
+### `snap export`
+
+Scans current directory and **appends** a snapshot block to `.snapshot`.  
+Never truncates or deletes previous snapshots.
+
+```bash
+snap export
+snap export -o my-project.snapshot
+snap export --ignore dist,build,coverage
+```
+
+### `snap restore`
+
+Recreates the directory/file structure. **Never overwrites** existing files.
+
+```bash
+snap restore
+snap restore -i my-project.snapshot -d ./new-folder
+snap restore --dry-run                        # preview only
+snap restore --text "d src f src/index.js"    # restore from pasted text
+```
+
+### `snap tree`
+
+Prints a pretty visual tree of your current directory (or a snapshot).
+
+```bash
+snap tree
+
+# Output:
+my-project/
+├── .env
+├── apps/
+│   └── web/
+├── infra/
+│   └── docker-compose.yml
+└── package.json
+```
+
+```bash
+snap tree -i my-project.snapshot   # tree from a saved snapshot
+```
+
+---
+
+## Snapshot format
+
+The `.snapshot` file is plain text:
+
+```
+# snap snapshot
+# created: 2025-04-01T10:00:00.000Z
+# root: /Users/you/my-project
+#
+# d = directory   f = file
+#
+d src
+d src/components
+f src/components/Button.js
+f src/index.js
+f package.json
+```
+
+Each `export` appends a new timestamped block — you keep a full history.
+
+---
+
+## Safety
+
+| Situation                      | Behaviour                    |
+| ------------------------------ | ---------------------------- |
+| Export on existing `.snapshot` | Appends — old data untouched |
+| Restore on existing file/dir   | Skips it — never overwrites  |
+| `node_modules`, `.git`         | Always excluded from export  |
+
+---
+
+## Options
+
+| Flag                  | Command      | Description                        |
+| --------------------- | ------------ | ---------------------------------- |
+| `-o, --output <file>` | export       | Output file (default: `.snapshot`) |
+| `--ignore <a,b>`      | export/tree  | Comma-separated names to skip      |
+| `-i, --input <file>`  | restore/tree | Snapshot file to read              |
+| `-d, --dest <dir>`    | restore      | Where to restore (default: cwd)    |
+| `-n, --dry-run`       | restore      | Preview without writing            |
+| `--text "<text>"`     | restore      | Restore from raw pasted text       |

package/bin/snap.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+"use strict";
+
+const minimist = require("minimist");
+const { exportSnap, restoreSnap, printTree } = require("../lib/index");
+
+const argv = minimist(process.argv.slice(2), {
+  string: ["output", "input", "dest", "ignore", "text"],
+  boolean: ["dry-run", "help", "version"],
+  alias: {
+    o: "output",
+    i: "input",
+    d: "dest",
+    n: "dry-run",
+    h: "help",
+    v: "version",
+  },
+});
+
+const command = argv._[0];
+
+// ── Version ──────────────────────────────────────────────────────────────────
+if (argv.version) {
+  const pkg = require("../package.json");
+  console.log(`snap-scaffold v${pkg.version}`);
+  process.exit(0);
+}
+
+// ── Help ─────────────────────────────────────────────────────────────────────
+const HELP = `
+snap — snapshot and scaffold directory structures
+
+COMMANDS
+  snap export              Scan current dir → write .snapshot file
+  snap restore             Read .snapshot  → recreate files & folders
+  snap tree                Print a visual ├── tree of current dir
+
+EXPORT
+  -o, --output <file>      Output file  (default: .snapshot)
+  --ignore <a,b,c>         Extra names to skip (comma-separated)
+
+RESTORE
+  -i, --input  <file>      Snapshot file (default: .snapshot)
+  -d, --dest   <dir>       Where to restore (default: cwd)
+  -n, --dry-run            Preview without writing anything
+  --text "<d f ...>"       Restore directly from pasted snapshot text
+
+TREE
+  -i, --input  <file>      Show tree from a snapshot file instead of live fs
+  --ignore <a,b,c>         Extra names to skip
+
+NOTES
+  • export  NEVER deletes or truncates — it always appends a new block
+  • restore NEVER overwrites — only creates what is missing
+  • node_modules, .git, .snapshot are always excluded from export
+
+EXAMPLES
+  snap export
+  snap export -o project.snapshot --ignore dist,build
+  snap restore
+  snap restore -i project.snapshot -d ./new-project --dry-run
+  snap restore --text "d src f src/index.js f README.md"
+  snap tree
+  snap tree -i project.snapshot
+`.trimStart();
+
+if (argv.help || !command) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+try {
+  if (command === "export") {
+    const extra = argv.ignore
+      ? String(argv.ignore)
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [];
+    exportSnap({ rootDir: process.cwd(), output: argv.output, ignore: extra });
+  } else if (command === "restore") {
+    if (argv.text) {
+      restoreSnap({
+        rawText: String(argv.text),
+        destDir: argv.dest,
+        dryRun: argv["dry-run"],
+      });
+    } else {
+      restoreSnap({
+        input: argv.input,
+        destDir: argv.dest,
+        dryRun: argv["dry-run"],
+      });
+    }
+  } else if (command === "tree") {
+    const extra = argv.ignore
+      ? String(argv.ignore)
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [];
+    printTree({ rootDir: process.cwd(), input: argv.input, ignore: extra });
+  } else {
+    console.error(`❌ Unknown command: "${command}"\nRun: snap --help`);
+    process.exit(1);
+  }
+} catch (err) {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+}

package/lib/index.js

@@ -0,0 +1,347 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+// ── Always-excluded names ────────────────────────────────────────────────────
+const DEFAULT_IGNORE = new Set([
+  "node_modules",
+  ".git",
+  ".DS_Store",
+  "Thumbs.db",
+  ".snapshot",
+]);
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function readDir(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+function sorted(entries) {
+  return [...entries].sort((a, b) => {
+    if (a.isDirectory() === b.isDirectory())
+      return a.name.localeCompare(b.name);
+    return a.isDirectory() ? -1 : 1; // dirs first
+  });
+}
+
+// ── WALK (shared by export + tree) ──────────────────────────────────────────
+
+/**
+ * Returns flat list: [{ type:'dir'|'file', rel:string, depth:number }]
+ */
+function walk(rootDir, ignoreSet) {
+  const results = [];
+
+  function recurse(current, depth) {
+    for (const entry of sorted(readDir(current))) {
+      if (ignoreSet.has(entry.name)) continue;
+
+      const abs = path.join(current, entry.name);
+      const rel = path.relative(rootDir, abs).replace(/\\/g, "/"); // normalise to forward slashes
+
+      if (entry.isDirectory()) {
+        results.push({ type: "dir", rel, depth });
+        recurse(abs, depth + 1);
+      } else {
+        results.push({ type: "file", rel, depth });
+      }
+    }
+  }
+
+  recurse(rootDir, 0);
+  return results;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// EXPORT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Snapshot the directory into a .snapshot file.
+ * ALWAYS appends — never truncates.
+ *
+ * File format:
+ *   # snap snapshot
+ *   # created: <ISO>
+ *   # root: <abs path>
+ *   #
+ *   d src/components
+ *   f src/components/Button.js
+ */
+function exportSnap(opts = {}) {
+  const rootDir = path.resolve(opts.rootDir || process.cwd());
+  const output = path.resolve(opts.output || path.join(rootDir, ".snapshot"));
+  const ignore = new Set([...DEFAULT_IGNORE, ...(opts.ignore || [])]);
+
+  console.log(`📂 Scanning  ${rootDir}`);
+  const entries = walk(rootDir, ignore);
+
+  const lines = [
+    "# snap snapshot",
+    `# created: ${new Date().toISOString()}`,
+    `# root: ${rootDir}`,
+    "#",
+    "# d = directory   f = file",
+    "#",
+    ...entries.map((e) => `${e.type === "dir" ? "d" : "f"} ${e.rel}`),
+    "",
+  ];
+
+  const block = lines.join("\n");
+  const sep = "\n# ──────────────────────────────────────────────\n\n";
+  const prev = fs.existsSync(output) ? fs.readFileSync(output, "utf8") : "";
+
+  // Flag "w" re-writes the file but we prepend ALL previous content — safe.
+  fs.writeFileSync(output, prev ? prev + sep + block : block, {
+    encoding: "utf8",
+  });
+
+  const dirs = entries.filter((e) => e.type === "dir").length;
+  const files = entries.filter((e) => e.type === "file").length;
+  console.log(`✅ Snapshot  → ${output}`);
+  console.log(`   ${dirs} dirs, ${files} files`);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// RESTORE
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Parse the LAST snapshot block in a file.
+ */
+function parseSnapshot(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  const blocks = raw.split(/\n#\s─{10,}.*\n/);
+  const last = blocks[blocks.length - 1];
+
+  let snapshotRoot = null;
+  const entries = [];
+
+  for (const line of last.split("\n")) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) {
+      const m = t.match(/^#\s*root:\s*(.+)$/);
+      if (m) snapshotRoot = m[1].trim();
+      continue;
+    }
+    const m = t.match(/^([df])\s+(.+)$/);
+    if (m) entries.push({ type: m[1] === "d" ? "dir" : "file", rel: m[2] });
+  }
+
+  return { entries, snapshotRoot };
+}
+
+/**
+ * Parse a RAW text (not a file) — used when user pastes the content directly.
+ * Handles both forward and back slashes.
+ */
+function parseRawText(text) {
+  const entries = [];
+
+  // Tokenise: split on whitespace but keep "d"/"f" markers + the path that follows.
+  // This handles both:
+  //   multi-line:  "d bin\nf bin/snap.js"
+  //   single-line: "d bin f bin/snap.js d lib f lib/index.js"
+  const tokens = text.trim().split(/\s+/);
+
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (tok === "d" || tok === "f") {
+      const relPath = tokens[i + 1];
+      if (relPath && relPath !== "d" && relPath !== "f") {
+        entries.push({
+          type: tok === "d" ? "dir" : "file",
+          rel: relPath.replace(/\\/g, "/"), // normalise backslashes
+        });
+        i++; // consume the path token
+      }
+    }
+  }
+
+  return { entries, snapshotRoot: null };
+}
+
+/**
+ * Restore from snapshot.
+ * NEVER overwrites existing files or directories.
+ */
+function restoreSnap(opts = {}) {
+  const destDir = path.resolve(opts.destDir || process.cwd());
+  const dryRun = !!opts.dryRun;
+
+  let entries, snapshotRoot;
+
+  if (opts.rawText) {
+    // ── restore from pasted text ──────────────────────────────────────────
+    ({ entries, snapshotRoot } = parseRawText(opts.rawText));
+    console.log("📋 Reading from provided text");
+  } else {
+    const input = path.resolve(
+      opts.input || path.join(process.cwd(), ".snapshot"),
+    );
+    if (!fs.existsSync(input))
+      throw new Error(`Snapshot file not found: ${input}`);
+    ({ entries, snapshotRoot } = parseSnapshot(input));
+    console.log(`📄 Reading   ${input}`);
+  }
+
+  if (snapshotRoot) console.log(`   Original root  ${snapshotRoot}`);
+  console.log(`   Restoring into ${destDir}`);
+  if (dryRun) console.log("   (dry-run — nothing written)\n");
+
+  let created = 0,
+    skipped = 0;
+
+  for (const e of entries) {
+    const target = path.join(destDir, e.rel);
+
+    if (fs.existsSync(target)) {
+      console.log(`  ⏭  exists   ${e.rel}${e.type === "dir" ? "/" : ""}`);
+      skipped++;
+      continue;
+    }
+
+    if (e.type === "dir") {
+      console.log(`  📁 mkdir    ${e.rel}/`);
+      if (!dryRun) fs.mkdirSync(target, { recursive: true });
+    } else {
+      console.log(`  📄 touch    ${e.rel}`);
+      if (!dryRun) {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, "", { encoding: "utf8", flag: "wx" });
+      }
+    }
+    created++;
+  }
+
+  console.log("");
+  console.log(
+    dryRun
+      ? `✅ Dry-run done.  Would create ${created}, skip ${skipped}.`
+      : `✅ Restore done.  Created ${created}, skipped ${skipped} (already existed).`,
+  );
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TREE  (pretty ├── display)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Print a visual tree, either from the live filesystem or from a snapshot file.
+ *
+ * jarvis/
+ * ├── .env
+ * ├── infra/
+ * │   └── docker-compose.yml
+ * └── apps/
+ */
+function printTree(opts = {}) {
+  let entries;
+  let label;
+
+  if (opts.input) {
+    // ── from snapshot file ────────────────────────────────────────────────
+    const input = path.resolve(opts.input);
+    if (!fs.existsSync(input))
+      throw new Error(`Snapshot file not found: ${input}`);
+    const parsed = parseSnapshot(input);
+    entries = parsed.entries.map((e) => ({
+      ...e,
+      depth: e.rel.split("/").length - 1,
+    }));
+    label = parsed.snapshotRoot
+      ? path.basename(parsed.snapshotRoot)
+      : "(snapshot)";
+  } else {
+    // ── from live filesystem ──────────────────────────────────────────────
+    const rootDir = path.resolve(opts.rootDir || process.cwd());
+    const ignore = new Set([...DEFAULT_IGNORE, ...(opts.ignore || [])]);
+    entries = walk(rootDir, ignore);
+    label = path.basename(rootDir);
+  }
+
+  // Build tree lines
+  // We need to know, for each depth, whether there are more siblings coming.
+  // Strategy: track the last-child status per depth level.
+
+  const lines = [`${label}/`];
+
+  // Convert flat list to a nested structure for proper └── vs ├── detection
+  // We'll do it by scanning ahead.
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    const depth = e.depth;
+    const name = path.basename(e.rel);
+
+    // Is this the last entry at this depth under the same parent?
+    const parentRel = e.rel.includes("/")
+      ? e.rel.slice(0, e.rel.lastIndexOf("/"))
+      : "";
+    let isLast = true;
+    for (let j = i + 1; j < entries.length; j++) {
+      const next = entries[j];
+      const nextParent = next.rel.includes("/")
+        ? next.rel.slice(0, next.rel.lastIndexOf("/"))
+        : "";
+      if (next.depth < depth) break; // went up — we were last
+      if (next.depth === depth && nextParent === parentRel) {
+        isLast = false;
+        break;
+      }
+    }
+
+    // Build the prefix: for each ancestor depth, check if that ancestor was last
+    let prefix = "";
+    for (let d = 0; d < depth; d++) {
+      // Find the ancestor at depth d that contains this entry
+      let ancestorIsLast = true;
+      // Look at what comes after the ancestor
+      // Find ancestor rel
+      const parts = e.rel.split("/");
+      const ancestorRel = parts.slice(0, d + 1).join("/");
+      const ancestorParent = d > 0 ? parts.slice(0, d).join("/") : "";
+
+      for (let j = 0; j < entries.length; j++) {
+        const candidate = entries[j];
+        const candidateParent = candidate.rel.includes("/")
+          ? candidate.rel.slice(0, candidate.rel.lastIndexOf("/"))
+          : "";
+        if (candidate.depth === d && candidateParent === ancestorParent) {
+          if (candidate.rel === ancestorRel) {
+            // Now scan forward to see if there are more siblings after this ancestor
+            ancestorIsLast = true;
+            for (let k = j + 1; k < entries.length; k++) {
+              const sib = entries[k];
+              const sibParent = sib.rel.includes("/")
+                ? sib.rel.slice(0, sib.rel.lastIndexOf("/"))
+                : "";
+              if (sib.depth < d) break;
+              if (sib.depth === d && sibParent === ancestorParent) {
+                ancestorIsLast = false;
+                break;
+              }
+            }
+            break;
+          }
+        }
+      }
+      prefix += ancestorIsLast ? "    " : "│   ";
+    }
+
+    const branch = isLast ? "└── " : "├── ";
+    const suffix = e.type === "dir" ? "/" : "";
+    lines.push(`${prefix}${branch}${name}${suffix}`);
+  }
+
+  const output = lines.join("\n");
+  console.log(output);
+  return output;
+}
+
+module.exports = { exportSnap, restoreSnap, printTree, parseRawText };

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "snap-scaffold",
+  "version": "1.0.0",
+  "description": "Snapshot your directory structure and restore it anywhere",
+  "main": "lib/index.js",
+  "bin": {
+    "snap": "bin/snap.js"
+  },
+  "keywords": [
+    "cli",
+    "scaffold",
+    "snapshot",
+    "directory",
+    "file-structure",
+    "tree"
+  ],
+  "author": "mrxgroot",
+  "license": "MIT",
+  "dependencies": {
+    "minimist": "^1.2.8"
+  }
+}