@timeax/scaffold 0.0.1

package/src/core/config-loader.ts

@@ -0,0 +1,184 @@
+// src/core/config-loader.ts
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import { pathToFileURL } from 'url';
+import { transform } from 'esbuild';
+
+import type { ScaffoldConfig } from '../schema';
+import { defaultLogger } from '../util/logger';
+import { ensureDirSync } from '../util/fs-utils';
+
+const logger = defaultLogger.child('[config]');
+
+export interface LoadScaffoldConfigOptions {
+   /**
+    * Optional explicit scaffold directory path (absolute or relative to cwd).
+    * If provided, this overrides config.root for locating the scaffold folder.
+    */
+   scaffoldDir?: string;
+
+   /**
+    * Optional explicit config file path (absolute or relative to cwd).
+    * If not provided, we look for config.* inside the scaffoldDir.
+    */
+   configPath?: string;
+}
+
+export interface LoadScaffoldConfigResult {
+   /**
+    * Parsed scaffold configuration.
+    */
+   config: ScaffoldConfig;
+
+   /**
+    * Absolute path to the scaffold directory (where config & *.txt live).
+    */
+   scaffoldDir: string;
+
+   /**
+    * Effective project root BASE where structures are applied.
+    * This is derived from config.root + config.base.
+    */
+   projectRoot: string;
+}
+
+/**
+ * Load scaffold configuration based on CWD + optional overrides + config.root/base.
+ *
+ * Resolution rules:
+ * - configRoot:
+ *   - Start from cwd.
+ *   - Apply config.root (if defined) as a path relative to cwd.
+ * - scaffoldDir:
+ *   - If options.scaffoldDir is provided → use it as-is (resolved from cwd).
+ *   - Else → <configRoot>/scaffold.
+ * - projectRoot (base):
+ *   - If config.base is defined → resolve relative to configRoot.
+ *   - Else → configRoot.
+ */
+export async function loadScaffoldConfig(
+   cwd: string,
+   options: LoadScaffoldConfigOptions = {},
+): Promise<LoadScaffoldConfigResult> {
+   const absCwd = path.resolve(cwd);
+
+   // First pass: figure out an initial scaffold dir just to locate config.*
+   const initialScaffoldDir = options.scaffoldDir
+      ? path.resolve(absCwd, options.scaffoldDir)
+      : path.join(absCwd, 'scaffold');
+
+   const configPath =
+      options.configPath ?? resolveConfigPath(initialScaffoldDir);
+
+   // Import config (supports .ts/.tsx via esbuild)
+   const config = await importConfig(configPath);
+
+   // Now compute configRoot (where scaffold/ lives by default)
+   let configRoot = absCwd;
+   if (config.root) {
+      configRoot = path.resolve(absCwd, config.root);
+   }
+
+   // Final scaffoldDir (can still be overridden by CLI)
+   const scaffoldDir = options.scaffoldDir
+      ? path.resolve(absCwd, options.scaffoldDir)
+      : path.join(configRoot, 'scaffold');
+
+   // projectRoot (base) is relative to configRoot
+   const baseRoot = config.base
+      ? path.resolve(configRoot, config.base)
+      : configRoot;
+
+   logger.debug(
+      `Loaded config: configRoot=${configRoot}, baseRoot=${baseRoot}, scaffoldDir=${scaffoldDir}`,
+   );
+
+   return {
+      config,
+      scaffoldDir,
+      projectRoot: baseRoot,
+   };
+}
+
+function resolveConfigPath(scaffoldDir: string): string {
+   const candidates = [
+      'config.ts',
+      'config.mts',
+      'config.mjs',
+      'config.js',
+      'config.cjs',
+   ];
+
+   for (const file of candidates) {
+      const full = path.join(scaffoldDir, file);
+      if (fs.existsSync(full)) {
+         return full;
+      }
+   }
+
+   throw new Error(
+      `Could not find scaffold config in ${scaffoldDir}. Looked for: ${candidates.join(
+         ', ',
+      )}`,
+   );
+}
+
+/**
+ * Import a ScaffoldConfig from the given path.
+ * - For .ts/.tsx we transpile with esbuild to ESM and load from a temp file.
+ * - For .js/.mjs/.cjs we import directly.
+ */
+async function importConfig(configPath: string): Promise<ScaffoldConfig> {
+   const ext = path.extname(configPath).toLowerCase();
+
+   if (ext === '.ts' || ext === '.tsx') {
+      return importTsConfig(configPath);
+   }
+
+   const url = pathToFileURL(configPath).href;
+   const mod = await import(url);
+   return (mod.default ?? mod) as ScaffoldConfig;
+}
+
+/**
+ * Transpile a TS config file to ESM with esbuild and import the compiled file.
+ * We cache based on (path + mtime) so changes invalidate the temp.
+ */
+async function importTsConfig(configPath: string): Promise<ScaffoldConfig> {
+   const source = fs.readFileSync(configPath, 'utf8');
+   const stat = fs.statSync(configPath);
+
+   const hash = crypto
+      .createHash('sha1')
+      .update(configPath)
+      .update(String(stat.mtimeMs))
+      .digest('hex');
+
+   const tmpDir = path.join(os.tmpdir(), 'timeax-scaffold-config');
+   ensureDirSync(tmpDir);
+
+   const tmpFile = path.join(tmpDir, `${hash}.mjs`);
+
+   if (!fs.existsSync(tmpFile)) {
+      const result = await transform(source, {
+         loader: 'ts',
+         format: 'esm',
+         sourcemap: 'inline',
+         target: 'ESNext',
+         tsconfigRaw: {
+            compilerOptions: {
+
+            },
+         },
+      });
+
+      fs.writeFileSync(tmpFile, result.code, 'utf8');
+   }
+
+   const url = pathToFileURL(tmpFile).href;
+   const mod = await import(url);
+   return (mod.default ?? mod) as ScaffoldConfig;
+}

package/src/core/hook-runner.ts

@@ -0,0 +1,73 @@
+// src/core/hook-runner.ts
+
+import { minimatch } from 'minimatch';
+import type {
+   ScaffoldConfig,
+   HookContext,
+   RegularHookKind,
+   StubHookKind,
+   StubConfig,
+   RegularHookConfig,
+   StubHookConfig,
+} from '../schema';
+
+function matchesFilter(
+   pathRel: string,
+   cfg: { include?: string[]; exclude?: string[]; files?: string[] },
+): boolean {
+   const { include, exclude, files } = cfg;
+
+   const patterns: string[] = [];
+   if (include?.length) patterns.push(...include);
+   if (files?.length) patterns.push(...files);
+
+   if (patterns.length) {
+      const ok = patterns.some((p) => minimatch(pathRel, p));
+      if (!ok) return false;
+   }
+
+   if (exclude?.length) {
+      const blocked = exclude.some((p) => minimatch(pathRel, p));
+      if (blocked) return false;
+   }
+
+   return true;
+}
+
+export class HookRunner {
+   constructor(private readonly config: ScaffoldConfig) { }
+
+   async runRegular(kind: RegularHookKind, ctx: HookContext): Promise<void> {
+      const configs: RegularHookConfig[] = this.config.hooks?.[kind] ?? [];
+      for (const cfg of configs) {
+         if (!matchesFilter(ctx.targetPath, cfg)) continue;
+         await cfg.fn(ctx);
+      }
+   }
+
+   private getStubConfig(stubName?: string): StubConfig | undefined {
+      if (!stubName) return undefined;
+      return this.config.stubs?.[stubName];
+   }
+
+   async runStub(kind: StubHookKind, ctx: HookContext): Promise<void> {
+      const stub = this.getStubConfig(ctx.stubName);
+      if (!stub?.hooks) return;
+
+      const configs: StubHookConfig[] =
+         kind === 'preStub'
+            ? stub.hooks.preStub ?? []
+            : stub.hooks.postStub ?? [];
+
+      for (const cfg of configs) {
+         if (!matchesFilter(ctx.targetPath, cfg)) continue;
+         await cfg.fn(ctx);
+      }
+   }
+
+   async renderStubContent(ctx: HookContext): Promise<string | undefined> {
+      const stub = this.getStubConfig(ctx.stubName);
+      if (!stub?.getContent) return undefined;
+      return stub.getContent(ctx);
+   }
+}

package/src/core/init-scaffold.ts

@@ -0,0 +1,162 @@
+// src/core/init-scaffold.ts
+
+import fs from 'fs';
+import path from 'path';
+import { ensureDirSync } from '../util/fs-utils';
+import { defaultLogger } from '../util/logger';
+
+const logger = defaultLogger.child('[init]');
+
+export interface InitScaffoldOptions {
+   /**
+    * Path to the scaffold directory (relative to cwd).
+    * Default: "scaffold"
+    */
+   scaffoldDir?: string;
+
+   /**
+    * Overwrite existing config/structure files if they already exist.
+    */
+   force?: boolean;
+
+   /**
+    * Name of the config file inside the scaffold directory.
+    * Default: "config.ts"
+    */
+   configFileName?: string;
+
+   /**
+    * Name of the default structure file inside the scaffold directory
+    * for single-root mode.
+    * Default: "structure.txt"
+    */
+   structureFileName?: string;
+}
+
+// src/core/init-scaffold.ts
+
+const DEFAULT_CONFIG_TS = `import type { ScaffoldConfig } from '@timeax/scaffold';
+
+const config: ScaffoldConfig = {
+  // Root for resolving the scaffold/ folder & this config file.
+  // By default, this is the directory where you run \`scaffold\`.
+  // Example:
+  //   root: '.',          // scaffold/ at <cwd>/scaffold
+  //   root: 'tools',      // scaffold/ at <cwd>/tools/scaffold
+  // root: '.',
+
+  // Base directory where structures are applied and files/folders are created.
+  // This is resolved relative to \`root\` above. Defaults to the same as root.
+  // Example:
+  //   base: '.',          // apply to <root>
+  //   base: 'src',        // apply to <root>/src
+  //   base: '..',         // apply to parent of <root>
+  // base: '.',
+
+  // Cache file path, relative to base.
+  // cacheFile: '.scaffold-cache.json',
+
+  // --- Single-structure mode (simple) ---
+  // structureFile: 'structure.txt',
+
+  // --- Grouped mode (uncomment and adjust) ---
+  // groups: [
+  //   { name: 'app', root: 'app', structureFile: 'app.txt' },
+  //   { name: 'frontend', root: 'resources/js', structureFile: 'frontend.txt' },
+  // ],
+
+  hooks: {
+    // preCreateFile: [],
+    // postCreateFile: [],
+    // preDeleteFile: [],
+    // postDeleteFile: [],
+  },
+
+  stubs: {
+    // Example:
+    // page: {
+    //   name: 'page',
+    //   getContent: (ctx) =>
+    //     \`export default function Page() { return <div>\${ctx.targetPath}</div>; }\`,
+    // },
+  },
+};
+
+export default config;
+`;
+
+const DEFAULT_STRUCTURE_TXT = `# scaffold/structure.txt
+# Example structure definition.
+# - Indent with 2 spaces per level
+# - Directories must end with "/"
+# - Files do not
+# - Lines starting with "#" are comments and ignored by parser
+
+# Example:
+# src/
+#   index.ts
+`;
+
+/**
+ * Initialize the scaffold directory and basic config/structure files.
+ *
+ * - Creates the scaffold directory if it doesn't exist.
+ * - Writes a default config.ts if missing (or if force = true).
+ * - Writes a default structure.txt if missing (or if force = true).
+ */
+export async function initScaffold(
+   cwd: string,
+   options: InitScaffoldOptions = {},
+): Promise<{
+   scaffoldDir: string;
+   configPath: string;
+   structurePath: string;
+   created: { config: boolean; structure: boolean };
+}> {
+   const scaffoldDirRel = options.scaffoldDir ?? 'scaffold';
+   const scaffoldDirAbs = path.resolve(cwd, scaffoldDirRel);
+   const configFileName = options.configFileName ?? 'config.ts';
+   const structureFileName = options.structureFileName ?? 'structure.txt';
+
+   ensureDirSync(scaffoldDirAbs);
+
+   const configPath = path.join(scaffoldDirAbs, configFileName);
+   const structurePath = path.join(scaffoldDirAbs, structureFileName);
+
+   let createdConfig = false;
+   let createdStructure = false;
+
+   // config.ts
+   if (fs.existsSync(configPath) && !options.force) {
+      logger.info(`Config already exists at ${configPath} (use --force to overwrite).`);
+   } else {
+      fs.writeFileSync(configPath, DEFAULT_CONFIG_TS, 'utf8');
+      createdConfig = true;
+      logger.info(
+         `${fs.existsSync(configPath) ? 'Overwrote' : 'Created'} config at ${configPath}`,
+      );
+   }
+
+   // structure.txt
+   if (fs.existsSync(structurePath) && !options.force) {
+      logger.info(
+         `Structure file already exists at ${structurePath} (use --force to overwrite).`,
+      );
+   } else {
+      fs.writeFileSync(structurePath, DEFAULT_STRUCTURE_TXT, 'utf8');
+      createdStructure = true;
+      logger.info(
+         `${fs.existsSync(structurePath) ? 'Overwrote' : 'Created'} structure file at ${structurePath}`,
+      );
+   }
+
+   return {
+      scaffoldDir: scaffoldDirAbs,
+      configPath,
+      structurePath,
+      created: {
+         config: createdConfig,
+         structure: createdStructure,
+      },
+   };
+}

package/src/core/resolve-structure.ts

@@ -0,0 +1,64 @@
+// src/core/resolve-structure.ts
+
+import fs from 'fs';
+import path from 'path';
+import type {
+   ScaffoldConfig,
+   StructureEntry,
+   StructureGroupConfig,
+} from '../schema';
+import { parseStructureText } from './structure-txt';
+import { defaultLogger } from '../util/logger';
+
+const logger = defaultLogger.child('[structure]');
+
+export function resolveGroupStructure(
+   scaffoldDir: string,
+   group: StructureGroupConfig,
+): StructureEntry[] {
+   if (group.structure && group.structure.length) {
+      logger.debug(`Using inline structure for group "${group.name}"`);
+      return group.structure;
+   }
+
+   const fileName = group.structureFile ?? `${group.name}.txt`;
+   const filePath = path.join(scaffoldDir, fileName);
+
+   if (!fs.existsSync(filePath)) {
+      throw new Error(
+         `@timeax/scaffold: Group "${group.name}" has no structure. ` +
+         `Expected file "${fileName}" in "${scaffoldDir}".`,
+      );
+   }
+
+   logger.debug(`Reading structure for group "${group.name}" from ${filePath}`);
+   const raw = fs.readFileSync(filePath, 'utf8');
+   return parseStructureText(raw);
+}
+
+/**
+ * Legacy single-structure mode (no groups defined).
+ */
+export function resolveSingleStructure(
+   scaffoldDir: string,
+   config: ScaffoldConfig,
+): StructureEntry[] {
+   if (config.structure && config.structure.length) {
+      logger.debug('Using inline single structure (no groups)');
+      return config.structure;
+   }
+
+   const fileName = config.structureFile ?? 'structure.txt';
+   const filePath = path.join(scaffoldDir, fileName);
+
+   if (!fs.existsSync(filePath)) {
+      throw new Error(
+         `@timeax/scaffold: No structure defined. ` +
+         `Expected "${fileName}" in "${scaffoldDir}".`,
+      );
+   }
+
+   logger.debug(`Reading single structure from ${filePath}`);
+   const raw = fs.readFileSync(filePath, 'utf8');
+   return parseStructureText(raw);
+}

package/src/core/runner.ts

@@ -0,0 +1,94 @@
+// src/core/runner.ts
+
+import path from 'path';
+import { loadScaffoldConfig } from './config-loader';
+import {
+   resolveGroupStructure,
+   resolveSingleStructure,
+} from './resolve-structure';
+import { CacheManager } from './cache-manager';
+import { HookRunner } from './hook-runner';
+import { applyStructure, type InteractiveDeleteParams } from './apply-structure';
+import type { Logger } from '../util/logger';
+import { defaultLogger } from '../util/logger';
+
+export interface RunOptions {
+   /**
+    * Optional interactive delete callback; if omitted, deletions
+    * above the size threshold will be skipped (kept + removed from cache).
+    */
+   interactiveDelete?: (
+      params: InteractiveDeleteParams,
+   ) => Promise<'delete' | 'keep'>;
+
+   /**
+    * Optional logger override.
+    */
+   logger?: Logger;
+
+   /**
+    * Optional overrides (e.g. allow CLI to point at a different scaffold dir).
+    */
+   scaffoldDir?: string;
+   configPath?: string;
+}
+
+/**
+ * Run scaffold once for the current working directory.
+ */
+export async function runOnce(cwd: string, options: RunOptions = {}): Promise<void> {
+   const logger = options.logger ?? defaultLogger.child('[runner]');
+   const { config, scaffoldDir, projectRoot } = await loadScaffoldConfig(cwd, {
+      scaffoldDir: options.scaffoldDir,
+      configPath: options.configPath,
+   });
+
+   const cachePath = config.cacheFile ?? '.scaffold-cache.json';
+   const cache = new CacheManager(projectRoot, cachePath);
+   cache.load();
+
+   const hooks = new HookRunner(config);
+
+   // Grouped mode
+   if (config.groups && config.groups.length > 0) {
+      for (const group of config.groups) {
+         const groupRootAbs = path.resolve(projectRoot, group.root);
+         const structure = resolveGroupStructure(scaffoldDir, group);
+
+         const groupLogger = logger.child(`[group:${group.name}]`);
+
+         // eslint-disable-next-line no-await-in-loop
+         await applyStructure({
+            config,
+            projectRoot,
+            baseDir: groupRootAbs,
+            structure,
+            cache,
+            hooks,
+            groupName: group.name,
+            groupRoot: group.root,
+            interactiveDelete: options.interactiveDelete,
+            logger: groupLogger,
+         });
+      }
+   } else {
+      // Single-root mode
+      const structure = resolveSingleStructure(scaffoldDir, config);
+      const baseLogger = logger.child('[group:default]');
+
+      await applyStructure({
+         config,
+         projectRoot,
+         baseDir: projectRoot,
+         structure,
+         cache,
+         hooks,
+         groupName: 'default',
+         groupRoot: '.',
+         interactiveDelete: options.interactiveDelete,
+         logger: baseLogger,
+      });
+   }
+
+   cache.save();
+}