@timeax/scaffold 0.0.1

package/src/cli/main.ts

@@ -0,0 +1,244 @@
+import readline from 'readline';
+import path from 'path';
+import fs from 'fs';
+import { Command } from 'commander';
+import { runOnce, RunOptions } from '../core/runner';
+import { watchScaffold } from '../core/watcher';
+import {
+  scanDirectoryToStructureText,
+  writeScannedStructuresFromConfig,
+} from '../core/scan-structure';
+import { initScaffold } from '../core/init-scaffold';
+import {
+  defaultLogger,
+  Logger,
+  type LogLevel,
+} from '../util/logger';
+import { ensureDirSync } from '../util/fs-utils';
+
+interface BaseCliOptions {
+  config?: string;
+  dir?: string;
+  watch?: boolean;
+  quiet?: boolean;
+  debug?: boolean;
+}
+
+interface ScanCliOptions {
+  root?: string;
+  out?: string;
+  ignore?: string[];
+  fromConfig?: boolean;
+  groups?: string[];
+}
+
+interface InitCliOptions {
+  force?: boolean;
+}
+
+/**
+ * Create a logger with the appropriate level from CLI flags.
+ */
+function createCliLogger(opts: { quiet?: boolean; debug?: boolean }): Logger {
+  if (opts.quiet) {
+    defaultLogger.setLevel('silent');
+  } else if (opts.debug) {
+    defaultLogger.setLevel('debug');
+  }
+  return defaultLogger.child('[cli]');
+}
+
+function askYesNo(question: string): Promise<'delete' | 'keep'> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close();
+      const val = answer.trim().toLowerCase();
+      if (val === 'y' || val === 'yes') {
+        resolve('delete');
+      } else {
+        resolve('keep');
+      }
+    });
+  });
+}
+
+async function handleRunCommand(cwd: string, baseOpts: BaseCliOptions) {
+  const logger = createCliLogger(baseOpts);
+
+  const configPath = baseOpts.config
+    ? path.resolve(cwd, baseOpts.config)
+    : undefined;
+  const scaffoldDir = baseOpts.dir
+    ? path.resolve(cwd, baseOpts.dir)
+    : undefined;
+
+  logger.debug(
+    `Starting scaffold (cwd=${cwd}, config=${configPath ?? 'auto'}, dir=${scaffoldDir ?? 'scaffold/'
+    }, watch=${baseOpts.watch ? 'yes' : 'no'})`,
+  );
+
+  const runnerOptions: RunOptions = {
+    configPath,
+    scaffoldDir,
+    logger,
+    interactiveDelete: async ({
+      relativePath,
+      size,
+      createdByStub,
+      groupName,
+    }) => {
+      const sizeKb = (size / 1024).toFixed(1);
+      const stubInfo = createdByStub ? ` (stub: ${createdByStub})` : '';
+      const groupInfo = groupName ? ` [group: ${groupName}]` : '';
+      const question =
+        `File "${relativePath}"${groupInfo} is ~${sizeKb}KB and no longer in structure${stubInfo}. Delete it?`;
+
+      return askYesNo(question);
+    },
+  };
+
+  if (baseOpts.watch) {
+    // Watch mode – this will not return
+    watchScaffold(cwd, runnerOptions);
+  } else {
+    await runOnce(cwd, runnerOptions);
+  }
+}
+
+async function handleScanCommand(
+  cwd: string,
+  scanOpts: ScanCliOptions,
+  baseOpts: BaseCliOptions,
+) {
+  const logger = createCliLogger(baseOpts);
+
+  const useConfigMode =
+    scanOpts.fromConfig || (!scanOpts.root && !scanOpts.out);
+
+  if (useConfigMode) {
+    logger.info('Scanning project using scaffold config/groups...');
+    await writeScannedStructuresFromConfig(cwd, {
+      ignore: scanOpts.ignore,
+      groups: scanOpts.groups,
+    });
+    return;
+  }
+
+  // Manual single-root mode
+  const rootDir = path.resolve(cwd, scanOpts.root ?? '.');
+  const ignore = scanOpts.ignore ?? [];
+
+  logger.info(`Scanning directory for structure: ${rootDir}`);
+  const text = scanDirectoryToStructureText(rootDir, {
+    ignore,
+  });
+
+  if (scanOpts.out) {
+    const outPath = path.resolve(cwd, scanOpts.out);
+    const dir = path.dirname(outPath);
+    ensureDirSync(dir);
+    fs.writeFileSync(outPath, text, 'utf8');
+    logger.info(`Wrote structure to ${outPath}`);
+  } else {
+    process.stdout.write(text + '\n');
+  }
+}
+
+async function handleInitCommand(
+  cwd: string,
+  initOpts: InitCliOptions,
+  baseOpts: BaseCliOptions,
+) {
+  const logger = createCliLogger(baseOpts);
+
+  const scaffoldDirRel = baseOpts.dir ?? 'scaffold';
+
+  logger.info(`Initializing scaffold directory at "${scaffoldDirRel}"...`);
+
+  const result = await initScaffold(cwd, {
+    scaffoldDir: scaffoldDirRel,
+    force: initOpts.force,
+  });
+
+  logger.info(
+    `Done. Config: ${result.configPath}, Structure: ${result.structurePath}`,
+  );
+}
+
+async function main() {
+  const cwd = process.cwd();
+
+  const program = new Command();
+
+  program
+    .name('scaffold')
+    .description('@timeax/scaffold – structure-based project scaffolding')
+    // global-ish options used by base + scan + init
+    .option('-c, --config <path>', 'Path to scaffold config file')
+    .option('-d, --dir <path>', 'Path to scaffold directory (default: ./scaffold)')
+    .option('-w, --watch', 'Watch scaffold directory for changes')
+    .option('--quiet', 'Silence logs')
+    .option('--debug', 'Enable debug logging');
+
+  // scan subcommand
+  program
+    .command('scan')
+    .description(
+      'Generate structure.txt-style output (config-aware by default, or manual root/out)',
+    )
+    .option(
+      '--from-config',
+      'Scan based on scaffold config/groups and write structure files into scaffold/ (default if no root/out specified)',
+    )
+    .option(
+      '-r, --root <path>',
+      'Root directory to scan (manual mode)',
+    )
+    .option(
+      '-o, --out <path>',
+      'Output file path (manual mode)',
+    )
+    .option(
+      '--ignore <patterns...>',
+      'Additional glob patterns to ignore (relative to root)',
+    )
+    .option(
+      '--groups <names...>',
+      'Limit config-based scanning to specific groups (by name)',
+    )
+    .action(async (scanOpts: ScanCliOptions, cmd: Command) => {
+      const baseOpts = cmd.parent?.opts<BaseCliOptions>() ?? {};
+      await handleScanCommand(cwd, scanOpts, baseOpts);
+    });
+
+  // init subcommand
+  program
+    .command('init')
+    .description('Initialize scaffold folder and config/structure files')
+    .option(
+      '--force',
+      'Overwrite existing config/structure files if they already exist',
+    )
+    .action(async (initOpts: InitCliOptions, cmd: Command) => {
+      const baseOpts = cmd.parent?.opts<BaseCliOptions>() ?? {};
+      await handleInitCommand(cwd, initOpts, baseOpts);
+    });
+
+  // Base command: run scaffold once or in watch mode
+  program.action(async (opts: BaseCliOptions) => {
+    await handleRunCommand(cwd, opts);
+  });
+
+  await program.parseAsync(process.argv);
+}
+
+// Run and handle errors
+main().catch((err) => {
+  defaultLogger.error(err);
+  process.exit(1);
+});

package/src/core/apply-structure.ts

@@ -0,0 +1,255 @@
+// src/core/apply-structure.ts
+
+import fs from 'fs';
+import path from 'path';
+import type {
+   ScaffoldConfig,
+   StructureEntry,
+   FileEntry,
+   DirEntry,
+   HookContext,
+} from '../schema';
+import { CacheManager } from './cache-manager';
+import { HookRunner } from './hook-runner';
+import {
+   ensureDirSync,
+   statSafeSync,
+   toProjectRelativePath,
+   toPosixPath,
+} from '../util/fs-utils';
+import type { Logger } from '../util/logger';
+import { defaultLogger } from '../util/logger';
+
+export interface InteractiveDeleteParams {
+   absolutePath: string;
+   relativePath: string; // project-root relative, POSIX
+   size: number;
+   createdByStub?: string;
+   groupName?: string;
+}
+
+export interface ApplyOptions {
+   config: ScaffoldConfig;
+
+   /**
+    * Global project root for this run.
+    */
+   projectRoot: string;
+
+   /**
+    * Absolute directory where this structure group should be applied.
+    * For grouped mode, this is projectRoot + group.root.
+    * For single mode, this will simply be projectRoot.
+    */
+   baseDir: string;
+
+   /**
+    * Which structure entries to apply (already resolved from txt or inline).
+    */
+   structure: StructureEntry[];
+
+   cache: CacheManager;
+   hooks: HookRunner;
+
+   /**
+    * Optional group metadata (only set for groups).
+    */
+   groupName?: string;
+   groupRoot?: string;
+
+   /**
+    * Optional override for deletion threshold.
+    * Falls back to config.sizePromptThreshold or internal default.
+    */
+   sizePromptThreshold?: number;
+
+   /**
+    * Optional interactive delete callback.
+    * Should ask the user and return 'delete' or 'keep'.
+    */
+   interactiveDelete?: (
+      params: InteractiveDeleteParams,
+   ) => Promise<'delete' | 'keep'>;
+
+   /**
+    * Optional logger; defaults to defaultLogger.child('[apply]').
+    */
+   logger?: Logger;
+}
+
+export async function applyStructure(opts: ApplyOptions): Promise<void> {
+   const {
+      config,
+      projectRoot,
+      baseDir,
+      structure,
+      cache,
+      hooks,
+      groupName,
+      groupRoot,
+      sizePromptThreshold,
+      interactiveDelete,
+   } = opts;
+
+   const logger =
+      opts.logger ?? defaultLogger.child(groupName ? `[apply:${groupName}]` : '[apply]');
+
+   const desiredPaths = new Set<string>(); // project-root relative, POSIX
+
+   const threshold = sizePromptThreshold ?? config.sizePromptThreshold ?? 128 * 1024;
+
+   async function walk(entry: StructureEntry, inheritedStub?: string): Promise<void> {
+      const effectiveStub = entry.stub ?? inheritedStub;
+      if (entry.type === 'dir') {
+         await handleDir(entry as DirEntry, effectiveStub);
+      } else {
+         await handleFile(entry as FileEntry, effectiveStub);
+      }
+   }
+
+   async function handleDir(entry: DirEntry, inheritedStub?: string): Promise<void> {
+      const relFromBase = entry.path.replace(/^[./]+/, '');
+      const absDir = path.resolve(baseDir, relFromBase);
+      const relFromRoot = toPosixPath(
+         toProjectRelativePath(projectRoot, absDir),
+      );
+
+      desiredPaths.add(relFromRoot);
+
+      ensureDirSync(absDir);
+
+      const nextStub = entry.stub ?? inheritedStub;
+
+      if (entry.children) {
+         for (const child of entry.children) {
+            // eslint-disable-next-line no-await-in-loop
+            await walk(child, nextStub);
+         }
+      }
+   }
+
+   async function handleFile(entry: FileEntry, inheritedStub?: string): Promise<void> {
+      const relFromBase = entry.path.replace(/^[./]+/, '');
+      const absFile = path.resolve(baseDir, relFromBase);
+      const relFromRoot = toPosixPath(
+         toProjectRelativePath(projectRoot, absFile),
+      );
+
+      desiredPaths.add(relFromRoot);
+
+      const stubName = entry.stub ?? inheritedStub;
+
+      const ctx: HookContext = {
+         projectRoot,
+         targetPath: relFromRoot,
+         absolutePath: absFile,
+         isDirectory: false,
+         stubName,
+      };
+
+      // If file already exists, do not overwrite; just ensure hooks
+      if (fs.existsSync(absFile)) {
+         return;
+      }
+
+      await hooks.runRegular('preCreateFile', ctx);
+
+      const dir = path.dirname(absFile);
+      ensureDirSync(dir);
+
+      if (stubName) {
+         await hooks.runStub('preStub', ctx);
+      }
+
+      let content = '';
+      const stubContent = await hooks.renderStubContent(ctx);
+      if (typeof stubContent === 'string') {
+         content = stubContent;
+      }
+
+      fs.writeFileSync(absFile, content, 'utf8');
+      const stats = fs.statSync(absFile);
+
+      cache.set({
+         path: relFromRoot,
+         createdAt: new Date().toISOString(),
+         sizeAtCreate: stats.size,
+         createdByStub: stubName,
+         groupName,
+         groupRoot,
+      });
+
+      logger.info(`created ${relFromRoot}`);
+
+      if (stubName) {
+         await hooks.runStub('postStub', ctx);
+      }
+
+      await hooks.runRegular('postCreateFile', ctx);
+   }
+
+   // 1) Create/update from structure
+   for (const entry of structure) {
+      // eslint-disable-next-line no-await-in-loop
+      await walk(entry);
+   }
+
+   // 2) Handle deletions: any cached path not in desiredPaths
+   for (const cachedPath of cache.allPaths()) {
+      if (desiredPaths.has(cachedPath)) continue;
+
+      const abs = path.resolve(projectRoot, cachedPath);
+      const stats = statSafeSync(abs);
+
+      if (!stats) {
+         cache.delete(cachedPath);
+         continue;
+      }
+
+      // Only handle files here; dirs are not tracked in cache.
+      if (!stats.isFile()) {
+         cache.delete(cachedPath);
+         continue;
+      }
+
+      const entry = cache.get(cachedPath);
+      const ctx: HookContext = {
+         projectRoot,
+         targetPath: cachedPath,
+         absolutePath: abs,
+         isDirectory: false,
+         stubName: entry?.createdByStub,
+      };
+
+      await hooks.runRegular('preDeleteFile', ctx);
+
+      let shouldDelete = true;
+      if (stats.size > threshold && interactiveDelete) {
+         const res = await interactiveDelete({
+            absolutePath: abs,
+            relativePath: cachedPath,
+            size: stats.size,
+            createdByStub: entry?.createdByStub,
+            groupName: entry?.groupName,
+         });
+
+         if (res === 'keep') {
+            shouldDelete = false;
+            cache.delete(cachedPath); // user takes ownership
+            logger.info(`keeping ${cachedPath} (removed from cache)`);
+         }
+      }
+
+      if (shouldDelete) {
+         try {
+            fs.unlinkSync(abs);
+            logger.info(`deleted ${cachedPath}`);
+         } catch (err) {
+            logger.warn(`failed to delete ${cachedPath}`, err);
+         }
+
+         cache.delete(cachedPath);
+         await hooks.runRegular('postDeleteFile', ctx);
+      }
+   }
+}

package/src/core/cache-manager.ts

@@ -0,0 +1,99 @@
+// src/core/cache-manager.ts
+
+import fs from 'fs';
+import path from 'path';
+import { ensureDirSync, toPosixPath } from '../util/fs-utils';
+import { defaultLogger } from '../util/logger';
+
+const logger = defaultLogger.child('[cache]');
+
+export interface CacheEntry {
+   /**
+    * Path relative to the *project root* (global root), POSIX style.
+    */
+   path: string;
+
+   createdAt: string;
+   sizeAtCreate: number;
+   createdByStub?: string;
+   groupName?: string;
+   groupRoot?: string;
+}
+
+export interface CacheFile {
+   version: 1;
+   entries: Record<string, CacheEntry>;
+}
+
+const DEFAULT_CACHE: CacheFile = {
+   version: 1,
+   entries: {},
+};
+
+export class CacheManager {
+   private cache: CacheFile = DEFAULT_CACHE;
+
+   constructor(
+      private readonly projectRoot: string,
+      private readonly cacheFileRelPath: string,
+   ) { }
+
+   private get cachePathAbs(): string {
+      return path.resolve(this.projectRoot, this.cacheFileRelPath);
+   }
+
+   load(): void {
+      const cachePath = this.cachePathAbs;
+      if (!fs.existsSync(cachePath)) {
+         this.cache = { ...DEFAULT_CACHE, entries: {} };
+         return;
+      }
+
+      try {
+         const raw = fs.readFileSync(cachePath, 'utf8');
+         const parsed = JSON.parse(raw) as CacheFile;
+         if (parsed.version === 1 && parsed.entries) {
+            this.cache = parsed;
+         } else {
+            logger.warn('Cache file version mismatch or invalid, resetting cache.');
+            this.cache = { ...DEFAULT_CACHE, entries: {} };
+         }
+      } catch (err) {
+         logger.warn('Failed to read cache file, resetting cache.', err);
+         this.cache = { ...DEFAULT_CACHE, entries: {} };
+      }
+   }
+
+   save(): void {
+      const cachePath = this.cachePathAbs;
+      const dir = path.dirname(cachePath);
+      ensureDirSync(dir);
+      fs.writeFileSync(cachePath, JSON.stringify(this.cache, null, 2), 'utf8');
+   }
+
+   get(relPath: string): CacheEntry | undefined {
+      const key = toPosixPath(relPath);
+      return this.cache.entries[key];
+   }
+
+   set(entry: CacheEntry): void {
+      const key = toPosixPath(entry.path);
+      this.cache.entries[key] = {
+         ...entry,
+         path: key,
+      };
+   }
+
+   delete(relPath: string): void {
+      const key = toPosixPath(relPath);
+      delete this.cache.entries[key];
+   }
+
+   allPaths(): string[] {
+      return Object.keys(this.cache.entries);
+   }
+
+   allEntries(): CacheEntry[] {
+      return Object.values(this.cache.entries);
+   }
+}