@timeax/scaffold 0.0.1

package/src/core/scan-structure.ts

@@ -0,0 +1,214 @@
+// src/core/scan-structure.ts
+
+import fs from 'fs';
+import path from 'path';
+import { minimatch } from 'minimatch';
+
+import {
+   ScanStructureOptions,
+   ScanFromConfigOptions,
+   StructureGroupConfig,
+   ScaffoldConfig,
+} from '../schema';
+import { toPosixPath, ensureDirSync } from '../util/fs-utils';
+import { loadScaffoldConfig } from './config-loader';
+import { defaultLogger } from '../util/logger';
+
+const logger = defaultLogger.child('[scan]');
+
+const DEFAULT_IGNORE: string[] = [
+   'node_modules/**',
+   '.git/**',
+   'dist/**',
+   'build/**',
+   '.turbo/**',
+   '.next/**',
+   'coverage/**',
+];
+
+/**
+ * Generate a structure.txt-style tree from an existing directory.
+ *
+ * Indenting:
+ * - 2 spaces per level.
+ * - Directories suffixed with "/".
+ * - No stub/include/exclude annotations are guessed (plain tree).
+ */
+export function scanDirectoryToStructureText(
+   rootDir: string,
+   options: ScanStructureOptions = {},
+): string {
+   const absRoot = path.resolve(rootDir);
+   const lines: string[] = [];
+
+   const ignorePatterns = options.ignore ?? DEFAULT_IGNORE;
+   const maxDepth = options.maxDepth ?? Infinity;
+
+   function isIgnored(absPath: string): boolean {
+      const rel = toPosixPath(path.relative(absRoot, absPath));
+      if (!rel || rel === '.') return false;
+      return ignorePatterns.some((pattern) =>
+         minimatch(rel, pattern, { dot: true }),
+      );
+   }
+
+   function walk(currentAbs: string, depth: number) {
+      if (depth > maxDepth) return;
+
+      let dirents: fs.Dirent[];
+      try {
+         dirents = fs.readdirSync(currentAbs, { withFileTypes: true });
+      } catch {
+         return;
+      }
+
+      // Sort: directories first, then files, both alphabetically
+      dirents.sort((a, b) => {
+         if (a.isDirectory() && !b.isDirectory()) return -1;
+         if (!a.isDirectory() && b.isDirectory()) return 1;
+         return a.name.localeCompare(b.name);
+      });
+
+      for (const dirent of dirents) {
+         const name = dirent.name;
+         const absPath = path.join(currentAbs, name);
+
+         if (isIgnored(absPath)) continue;
+
+         const indent = '  '.repeat(depth);
+         if (dirent.isDirectory()) {
+            lines.push(`${indent}${name}/`);
+            walk(absPath, depth + 1);
+         } else if (dirent.isFile()) {
+            lines.push(`${indent}${name}`);
+         }
+         // symlinks etc. are skipped for now
+      }
+   }
+
+   walk(absRoot, 0);
+   return lines.join('\n');
+}
+
+/**
+ * Result of scanning based on the scaffold config.
+ *
+ * You can use `structureFilePath` + `text` to write out group structure files.
+ */
+export interface ScanFromConfigResult {
+   groupName: string;
+   groupRoot: string;
+   structureFileName: string;
+   structureFilePath: string;
+   text: string;
+}
+
+/**
+ * Scan the project using the scaffold config and its groups.
+ *
+ * - If `config.groups` exists and is non-empty:
+ *   - scans each group's `root` (relative to projectRoot)
+ *   - produces text suitable for that group's structure file
+ * - Otherwise:
+ *   - scans the single `projectRoot` and produces text for a single structure file.
+ *
+ * NOTE: This function does NOT write files; it just returns what should be written.
+ * The CLI (or caller) decides whether/where to save.
+ */
+export async function scanProjectFromConfig(
+   cwd: string,
+   options: ScanFromConfigOptions = {},
+): Promise<ScanFromConfigResult[]> {
+   const { config, scaffoldDir, projectRoot } = await loadScaffoldConfig(cwd, {
+      scaffoldDir: options.scaffoldDir,
+   });
+
+   const ignorePatterns = options.ignore ?? DEFAULT_IGNORE;
+   const maxDepth = options.maxDepth ?? Infinity;
+   const onlyGroups = options.groups;
+
+   const results: ScanFromConfigResult[] = [];
+
+   function scanGroup(
+      cfg: ScaffoldConfig,
+      group: StructureGroupConfig,
+   ): ScanFromConfigResult {
+      const rootAbs = path.resolve(projectRoot, group.root);
+      const text = scanDirectoryToStructureText(rootAbs, {
+         ignore: ignorePatterns,
+         maxDepth,
+      });
+
+      const structureFileName = group.structureFile ?? `${group.name}.txt`;
+      const structureFilePath = path.join(scaffoldDir, structureFileName);
+
+      return {
+         groupName: group.name,
+         groupRoot: group.root,
+         structureFileName,
+         structureFilePath,
+         text,
+      };
+   }
+
+   if (config.groups && config.groups.length > 0) {
+      logger.debug(
+         `Scanning project from config with ${config.groups.length} group(s).`,
+      );
+
+      for (const group of config.groups) {
+         if (onlyGroups && !onlyGroups.includes(group.name)) {
+            continue;
+         }
+         const result = scanGroup(config, group);
+         results.push(result);
+      }
+   } else {
+      // Single-root mode: scan the whole projectRoot
+      logger.debug('Scanning project in single-root mode (no groups).');
+
+      const text = scanDirectoryToStructureText(projectRoot, {
+         ignore: ignorePatterns,
+         maxDepth,
+      });
+
+      const structureFileName = config.structureFile ?? 'structure.txt';
+      const structureFilePath = path.join(scaffoldDir, structureFileName);
+
+      results.push({
+         groupName: 'default',
+         groupRoot: '.',
+         structureFileName,
+         structureFilePath,
+         text,
+      });
+   }
+
+   return results;
+}
+
+/**
+ * Convenience helper: write scan results to their structure files.
+ *
+ * This will ensure the scaffold directory exists and overwrite existing
+ * structure files.
+ */
+export async function writeScannedStructuresFromConfig(
+   cwd: string,
+   options: ScanFromConfigOptions = {},
+): Promise<void> {
+   const { scaffoldDir } = await loadScaffoldConfig(cwd, {
+      scaffoldDir: options.scaffoldDir,
+   });
+
+   ensureDirSync(scaffoldDir);
+
+   const results = await scanProjectFromConfig(cwd, options);
+
+   for (const result of results) {
+      fs.writeFileSync(result.structureFilePath, result.text, 'utf8');
+      logger.info(
+         `Wrote structure for group "${result.groupName}" to ${result.structureFilePath}`,
+      );
+   }
+}

package/src/core/structure-txt.ts

@@ -0,0 +1,203 @@
+// src/core/structure-txt.ts
+
+import type { StructureEntry, DirEntry, FileEntry } from '../schema';
+import { toPosixPath } from '../util/fs-utils';
+
+interface ParsedLine {
+   lineNo: number;
+   indentSpaces: number;
+   rawPath: string;
+   stub?: string;
+   include?: string[];
+   exclude?: string[];
+}
+
+/**
+ * Parse a single non-empty, non-comment line into a ParsedLine.
+ * Supports inline annotations:
+ * - @stub:name
+ * - @include:pattern,pattern2
+ * - @exclude:pattern,pattern2
+ */
+function parseLine(line: string, lineNo: number): ParsedLine | null {
+   const match = line.match(/^(\s*)(.+)$/);
+   if (!match) return null;
+
+   const indentSpaces = match[1].length;
+   const rest = match[2].trim();
+   if (!rest || rest.startsWith('#')) return null;
+
+   const parts = rest.split(/\s+/);
+   const pathToken = parts[0];
+
+   let stub: string | undefined;
+   const include: string[] = [];
+   const exclude: string[] = [];
+
+   for (const token of parts.slice(1)) {
+      if (token.startsWith('@stub:')) {
+         stub = token.slice('@stub:'.length);
+      } else if (token.startsWith('@include:')) {
+         const val = token.slice('@include:'.length);
+         if (val) {
+            include.push(
+               ...val
+                  .split(',')
+                  .map((s) => s.trim())
+                  .filter(Boolean),
+            );
+         }
+      } else if (token.startsWith('@exclude:')) {
+         const val = token.slice('@exclude:'.length);
+         if (val) {
+            exclude.push(
+               ...val
+                  .split(',')
+                  .map((s) => s.trim())
+                  .filter(Boolean),
+            );
+         }
+      }
+   }
+
+   return {
+      lineNo,
+      indentSpaces,
+      rawPath: pathToken,
+      stub,
+      include: include.length ? include : undefined,
+      exclude: exclude.length ? exclude : undefined,
+   };
+}
+
+/**
+ * Convert a structure.txt content into a nested StructureEntry[].
+ *
+ * Rules:
+ * - Indentation is **2 spaces per level** (strict).
+ * - Indent must be a multiple of 2.
+ * - You cannot "skip" levels (no jumping from level 0 to 2 directly).
+ * - **Only directories can have children**:
+ *   - If you indent under a file, an error is thrown.
+ * - Folders must end with "/" in the txt; paths are normalized to POSIX.
+ */
+export function parseStructureText(text: string): StructureEntry[] {
+   const lines = text.split(/\r?\n/);
+   const parsed: ParsedLine[] = [];
+
+   for (let i = 0; i < lines.length; i++) {
+      const lineNo = i + 1;
+      const p = parseLine(lines[i], lineNo);
+      if (p) parsed.push(p);
+   }
+
+   const rootEntries: StructureEntry[] = [];
+
+   type StackItem = {
+      level: number;
+      entry: DirEntry | FileEntry;
+      isDir: boolean;
+   };
+
+   const stack: StackItem[] = [];
+   const INDENT_STEP = 2;
+
+   for (const p of parsed) {
+      const { indentSpaces, lineNo } = p;
+
+      if (indentSpaces % INDENT_STEP !== 0) {
+         throw new Error(
+            `structure.txt: Invalid indent on line ${lineNo}. ` +
+            `Indent must be multiples of ${INDENT_STEP} spaces.`,
+         );
+      }
+
+      const level = indentSpaces / INDENT_STEP;
+
+      // Determine parent level and enforce no skipping
+      if (level > stack.length) {
+         // e.g. current stack depth 1, but line level=2+ is invalid
+         if (level !== stack.length + 1) {
+            throw new Error(
+               `structure.txt: Invalid indentation on line ${lineNo}. ` +
+               `You cannot jump more than one level at a time. ` +
+               `Previous depth: ${stack.length}, this line depth: ${level}.`,
+            );
+         }
+      }
+
+      // If this line is indented (level > 0), parent must exist and must be dir
+      if (level > 0) {
+         const parent = stack[level - 1]; // parent level is (level - 1)
+         if (!parent) {
+            throw new Error(
+               `structure.txt: Indented entry without a parent on line ${lineNo}.`,
+            );
+         }
+         if (!parent.isDir) {
+            throw new Error(
+               `structure.txt: Cannot indent under a file on line ${lineNo}. ` +
+               `Files cannot have children. Parent: "${parent.entry.path}".`,
+            );
+         }
+      }
+
+      const isDir = p.rawPath.endsWith('/');
+      const clean = p.rawPath.replace(/\/$/, '');
+      const basePath = toPosixPath(clean);
+
+      // Determine parent based on level
+      // Pop stack until we are at the correct depth
+      while (stack.length > level) {
+         stack.pop();
+      }
+
+      const parent = stack[stack.length - 1]?.entry as DirEntry | undefined;
+      const parentPath = parent ? parent.path.replace(/\/$/, '') : '';
+
+      const fullPath = parentPath
+         ? `${parentPath}/${basePath}${isDir ? '/' : ''}`
+         : `${basePath}${isDir ? '/' : ''}`;
+
+      if (isDir) {
+         const dirEntry: DirEntry = {
+            type: 'dir',
+            path: fullPath,
+            children: [],
+            ...(p.stub ? { stub: p.stub } : {}),
+            ...(p.include ? { include: p.include } : {}),
+            ...(p.exclude ? { exclude: p.exclude } : {}),
+         };
+
+         if (parent && parent.type === 'dir') {
+            parent.children = parent.children ?? [];
+            parent.children.push(dirEntry);
+         } else if (!parent) {
+            rootEntries.push(dirEntry);
+         }
+
+         stack.push({ level, entry: dirEntry, isDir: true });
+      } else {
+         const fileEntry: FileEntry = {
+            type: 'file',
+            path: fullPath,
+            ...(p.stub ? { stub: p.stub } : {}),
+            ...(p.include ? { include: p.include } : {}),
+            ...(p.exclude ? { exclude: p.exclude } : {}),
+         };
+
+         if (parent && parent.type === 'dir') {
+            parent.children = parent.children ?? [];
+            parent.children.push(fileEntry);
+         } else if (!parent) {
+            rootEntries.push(fileEntry);
+         }
+
+         // files are not added to the stack; they cannot have children
+         stack.push({ level, entry: fileEntry, isDir: false });
+         // but next lines at same or lower level will pop correctly
+      }
+   }
+
+   return rootEntries;
+}

package/src/core/watcher.ts

@@ -0,0 +1,106 @@
+// src/core/watcher.ts
+
+import path from 'path';
+import chokidar from 'chokidar';
+import { runOnce, type RunOptions } from './runner';
+import { defaultLogger, type Logger } from '../util/logger';
+
+export interface WatchOptions extends RunOptions {
+   /**
+    * Debounce delay in milliseconds between detected changes
+    * and a scaffold re-run.
+    *
+    * Default: 150 ms
+    */
+   debounceMs?: number;
+
+   /**
+    * Optional logger; falls back to defaultLogger.child('[watch]').
+    */
+   logger?: Logger;
+}
+
+/**
+ * Watch the scaffold directory and re-run scaffold on changes.
+ *
+ * This watches:
+ * - scaffold/config.* files
+ * - scaffold/*.txt files (structures)
+ *
+ * CLI can call this when `--watch` is enabled.
+ */
+export function watchScaffold(cwd: string, options: WatchOptions = {}): void {
+   const logger = options.logger ?? defaultLogger.child('[watch]');
+
+   const scaffoldDir = options.scaffoldDir
+      ? path.resolve(cwd, options.scaffoldDir)
+      : path.resolve(cwd, 'scaffold');
+
+   const debounceMs = options.debounceMs ?? 150;
+
+   logger.info(`Watching scaffold directory: ${scaffoldDir}`);
+
+   let timer: NodeJS.Timeout | undefined;
+   let running = false;
+   let pending = false;
+
+   async function run() {
+      if (running) {
+         pending = true;
+         return;
+      }
+      running = true;
+      try {
+         logger.info('Change detected → running scaffold...');
+         await runOnce(cwd, {
+            ...options,
+            // we already resolved scaffoldDir for watcher; pass it down
+            scaffoldDir,
+         });
+         logger.info('Scaffold run completed.');
+      } catch (err) {
+         logger.error('Scaffold run failed:', err);
+      } finally {
+         running = false;
+         if (pending) {
+            pending = false;
+            timer = setTimeout(run, debounceMs);
+         }
+      }
+   }
+
+   function scheduleRun() {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(run, debounceMs);
+   }
+
+   const watcher = chokidar.watch(
+      [
+         path.join(scaffoldDir, 'config.*'),
+         path.join(scaffoldDir, '*.txt'),
+      ],
+      {
+         ignoreInitial: false,
+      },
+   );
+
+   watcher
+      .on('add', (filePath) => {
+         logger.debug(`File added: ${filePath}`);
+         scheduleRun();
+      })
+      .on('change', (filePath) => {
+         logger.debug(`File changed: ${filePath}`);
+         scheduleRun();
+      })
+      .on('unlink', (filePath) => {
+         logger.debug(`File removed: ${filePath}`);
+         scheduleRun();
+      })
+      .on('error', (error) => {
+         logger.error('Watcher error:', error);
+      });
+
+   // Initial run
+   scheduleRun();
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+// src/index.ts
+
+export * from './schema';
+export * from './core/runner';
+export * from './core/scan-structure';

package/src/schema/config.ts

@@ -0,0 +1,180 @@
+// src/schema/config.ts
+
+import type {
+   RegularHookConfig,
+   RegularHookKind,
+   StubConfig,
+} from './hooks';
+import type { StructureEntry } from './structure';
+
+
+
+/**
+ * Configuration for a single structure group.
+ *
+ * Groups allow you to clearly separate different roots in a project,
+ * such as "app", "routes", "resources/js", etc., each with its own
+ * structure definition.
+ */
+export interface StructureGroupConfig {
+   /**
+    * Human-readable identifier for the group (e.g. "app", "routes", "frontend").
+    * Used mainly for logging and, optionally, cache metadata.
+    */
+   name: string;
+
+   /**
+    * Root directory for this group, relative to the overall project root.
+    *
+    * Example: "app", "routes", "resources/js".
+    *
+    * All paths produced from this group's structure are resolved
+    * relative to this directory.
+    */
+   root: string;
+
+   /**
+    * Optional inline structure entries for this group.
+    * If present and non-empty, these take precedence over `structureFile`.
+    */
+   structure?: StructureEntry[];
+
+   /**
+    * Name of the structure file inside the scaffold directory for this group.
+    *
+    * Example: "app.txt", "routes.txt".
+    *
+    * If omitted, the default is `<name>.txt` within the scaffold directory.
+    */
+   structureFile?: string;
+}
+
+/**
+ * Root configuration object for @timeax/scaffold.
+ *
+ * This is what you export from `scaffold/config.ts` in a consuming
+ * project, or from any programmatic usage of the library.
+ */
+export interface ScaffoldConfig {
+   /**
+    * Absolute or relative project root (where files are created).
+    *
+    * If omitted, the engine will treat `process.cwd()` as the root.
+    */
+   root?: string;
+
+   /**
+   * Base directory where structures are applied and files/folders
+   * are actually created.
+   *
+   * This is resolved relative to `root` (not CWD).
+   *
+   * Default: same as `root`.
+   *
+   * Examples:
+   * - base: '.'       with root: '.'       → apply to <cwd>
+   * - base: 'src'     with root: '.'       → apply to <cwd>/src
+   * - base: '..'      with root: 'tools'   → apply to <cwd>/tools/..
+   */
+   base?: string;
+
+   /**
+    * Path to the scaffold cache file, relative to `root`.
+    *
+    * Default: ".scaffold-cache.json"
+    */
+   cacheFile?: string;
+
+   /**
+    * File size threshold (in bytes) above which deletions become
+    * interactive (e.g. ask "are you sure?").
+    *
+    * Default is determined by the core engine (e.g. 128 KB).
+    */
+   sizePromptThreshold?: number;
+
+   /**
+    * Optional single-root structure (legacy or simple mode).
+    *
+    * If `groups` is defined and non-empty, this is ignored.
+    * Paths are relative to `root` in this mode.
+    */
+   structure?: StructureEntry[];
+
+   /**
+    * Name of the single structure file in the scaffold directory
+    * for legacy mode.
+    *
+    * If `groups` is empty and `structure` is not provided, this
+    * file name is used (default: "structure.txt").
+    */
+   structureFile?: string;
+
+   /**
+    * Multiple structure groups (recommended).
+    *
+    * When provided and non-empty, the engine will iterate over each
+    * group and apply its structure relative to each group's `root`.
+    */
+   groups?: StructureGroupConfig[];
+
+   /**
+    * Hook configuration for file lifecycle events.
+    *
+    * Each category (e.g. "preCreateFile") is an array of hook configs,
+    * each with its own `include` / `exclude` / `files` filters.
+    */
+   hooks?: {
+      [K in RegularHookKind]?: RegularHookConfig[];
+   };
+
+   /**
+    * Stub definitions keyed by stub name.
+    *
+    * These are referenced from structure entries by `stub: name`.
+    */
+   stubs?: Record<string, StubConfig>;
+
+   /**
+    * When true, the CLI or consuming code may choose to start scaffold
+    * in watch mode by default (implementation-specific).
+    *
+    * This flag itself does not start watch mode; it is a hint to the
+    * runner / CLI.
+    */
+   watch?: boolean;
+}
+
+
+/**
+ * Options when scanning an existing directory into a structure.txt tree.
+ */
+export interface ScanStructureOptions {
+   /**
+    * Glob patterns (relative to the scanned root) to ignore.
+    */
+   ignore?: string[];
+
+   /**
+    * Maximum depth to traverse (0 = only that dir).
+    * Default: Infinity (no limit).
+    */
+   maxDepth?: number;
+}
+
+/**
+ * Options when scanning based on the scaffold config/groups.
+ */
+export interface ScanFromConfigOptions extends ScanStructureOptions {
+   /**
+    * If provided, only scan these group names (by `StructureGroupConfig.name`).
+    * If omitted, all groups are scanned (or single-root mode).
+    */
+   groups?: string[];
+
+   /**
+    * Optional override for scaffold directory; normally you can let
+    * loadScaffoldConfig resolve this from "<cwd>/scaffold".
+    */
+   scaffoldDir?: string;
+}