@timeax/scaffold 0.0.1

package/src/schema/hooks.ts

@@ -0,0 +1,139 @@
+// src/schema/hooks.ts
+
+/**
+ * Lifecycle stages for non-stub (regular) hooks.
+ *
+ * These hooks are called around file operations (create/delete).
+ */
+export type RegularHookKind =
+   | 'preCreateFile'
+   | 'postCreateFile'
+   | 'preDeleteFile'
+   | 'postDeleteFile';
+
+/**
+ * Lifecycle stages for stub-related hooks.
+ *
+ * These hooks are called around stub resolution for file content.
+ */
+export type StubHookKind = 'preStub' | 'postStub';
+
+/**
+ * Context object passed to all hooks (both regular and stub).
+ */
+export interface HookContext {
+   /**
+    * Absolute path to the group root / project root that this
+    * scaffold run is targeting.
+    */
+   projectRoot: string;
+
+   /**
+    * Path of the file or directory relative to the project root
+    * used for this run (or group root, if grouped).
+    *
+    * Example: "src/index.ts", "Http/Controllers/Controller.php".
+    */
+   targetPath: string;
+
+   /**
+    * Absolute path to the file or directory on disk.
+    */
+   absolutePath: string;
+
+   /**
+    * Whether the target is a directory.
+    * (For now, most hooks will be for files, but this is future-proofing.)
+    */
+   isDirectory: boolean;
+
+   /**
+    * The stub name associated with the file (if any).
+    *
+    * For regular hooks, this can be used to detect which stub
+    * produced a given file.
+    */
+   stubName?: string;
+}
+
+/**
+ * Common filter options used by both regular and stub hooks.
+ *
+ * Filters are evaluated against the `targetPath`.
+ */
+export interface HookFilter {
+   /**
+    * Glob patterns which must match for the hook to run.
+    * If provided, at least one pattern must match.
+    */
+   include?: string[];
+
+   /**
+    * Glob patterns which, if any match, will prevent the hook
+    * from running.
+    */
+   exclude?: string[];
+
+   /**
+    * Additional patterns or explicit file paths, treated similarly
+    * to `include` — mainly a convenience alias.
+    */
+   files?: string[];
+}
+
+/**
+ * Function signature for regular hooks.
+ */
+export type RegularHookFn = (ctx: HookContext) => void | Promise<void>;
+
+/**
+ * Function signature for stub hooks.
+ */
+export type StubHookFn = (ctx: HookContext) => void | Promise<void>;
+
+/**
+ * Configuration for a regular hook instance.
+ *
+ * Each hook category (e.g. `preCreateFile`) can have an array
+ * of these, each with its own filter.
+ */
+export interface RegularHookConfig extends HookFilter {
+   fn: RegularHookFn;
+}
+
+/**
+ * Configuration for a stub hook instance.
+ *
+ * Each stub can have its own `preStub` / `postStub` hook arrays,
+ * each with independent filters.
+ */
+export interface StubHookConfig extends HookFilter {
+   fn: StubHookFn;
+}
+
+/**
+ * Stub configuration, defining how file content is generated
+ * and which stub-specific hooks apply.
+ */
+export interface StubConfig {
+   /**
+    * Unique name of this stub within the config.
+    * This is referenced from structure entries via `stub: name`.
+    */
+   name: string;
+
+   /**
+    * Content generator for files that use this stub.
+    *
+    * If omitted, the scaffold engine may default to an empty file.
+    */
+   getContent?: (ctx: HookContext) => string | Promise<string>;
+
+   /**
+    * Stub-specific hooks called for files that reference this stub.
+    */
+   hooks?: {
+      preStub?: StubHookConfig[];
+      postStub?: StubHookConfig[];
+   };
+}

package/src/schema/index.ts

@@ -0,0 +1,4 @@
+// src/schema/index.ts
+export * from './structure';
+export * from './hooks';
+export * from './config';

package/src/schema/structure.ts

@@ -0,0 +1,77 @@
+// src/schema/structure.ts
+
+/**
+ * Common options that can be applied to both files and directories
+ * in the scaffold structure.
+ *
+ * These options are *declarative* — they do not enforce behavior by
+ * themselves; they are consumed by the core engine.
+ */
+export interface BaseEntryOptions {
+   /**
+    * Glob patterns relative to the group root or project root
+    * (depending on how the engine is called).
+    *
+    * If provided, at least one pattern must match the entry path
+    * for the entry to be considered.
+    */
+   include?: string[];
+
+   /**
+    * Glob patterns relative to the group root or project root.
+    *
+    * If any pattern matches the entry path, the entry will be ignored.
+    */
+   exclude?: string[];
+
+   /**
+    * Name of the stub to use when creating this file or directory’s
+    * content. For directories, this can act as an “inherited” stub
+    * for child files if the engine chooses to support that behavior.
+    */
+   stub?: string;
+}
+
+/**
+ * A single file entry in the structure tree.
+ *
+ * Paths are always stored as POSIX-style forward-slash paths
+ * relative to the group root / project root.
+ */
+export interface FileEntry extends BaseEntryOptions {
+   type: 'file';
+
+   /**
+    * File path (e.g. "src/index.ts", "Models/User.php").
+    * Paths should never end with a trailing slash.
+    */
+   path: string;
+}
+
+/**
+ * A directory entry in the structure tree.
+ *
+ * Paths should *logically* represent directories and may end
+ * with a trailing slash for readability (the engine can normalize).
+ */
+export interface DirEntry extends BaseEntryOptions {
+   type: 'dir';
+
+   /**
+    * Directory path (e.g. "src/", "src/schema/", "Models/").
+    * It is recommended (but not strictly required) that directory
+    * paths end with a trailing slash.
+    */
+   path: string;
+
+   /**
+    * Nested structure entries for files and subdirectories.
+    */
+   children?: StructureEntry[];
+}
+
+/**
+ * A single node in the structure tree:
+ * either a file or a directory.
+ */
+export type StructureEntry = FileEntry | DirEntry;

package/src/util/fs-utils.ts

@@ -0,0 +1,126 @@
+// src/util/fs-utils.ts
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Convert any path to a POSIX-style path with forward slashes.
+ */
+export function toPosixPath(p: string): string {
+   return p.replace(/\\/g, '/');
+}
+
+/**
+ * Ensure a directory exists (like mkdir -p).
+ * Returns the absolute path of the directory.
+ */
+export function ensureDirSync(dirPath: string): string {
+   if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+   }
+   return dirPath;
+}
+
+/**
+ * Synchronous check for file or directory existence.
+ */
+export function existsSync(targetPath: string): boolean {
+   return fs.existsSync(targetPath);
+}
+
+/**
+ * Read a file as UTF-8, returning null if it doesn't exist
+ * or if an error occurs (no exceptions thrown).
+ */
+export function readFileSafeSync(filePath: string): string | null {
+   try {
+      return fs.readFileSync(filePath, 'utf8');
+   } catch {
+      return null;
+   }
+}
+
+/**
+ * Write a UTF-8 file, creating parent directories if needed.
+ */
+export function writeFileSafeSync(filePath: string, contents: string): void {
+   const dir = path.dirname(filePath);
+   ensureDirSync(dir);
+   fs.writeFileSync(filePath, contents, 'utf8');
+}
+
+/**
+ * Remove a file if it exists. Does nothing on error.
+ */
+export function removeFileSafeSync(filePath: string): void {
+   try {
+      if (fs.existsSync(filePath)) {
+         fs.unlinkSync(filePath);
+      }
+   } catch {
+      // ignore
+   }
+}
+
+/**
+ * Get file stats if they exist, otherwise null.
+ */
+export function statSafeSync(targetPath: string): fs.Stats | null {
+   try {
+      return fs.statSync(targetPath);
+   } catch {
+      return null;
+   }
+}
+
+/**
+ * Resolve an absolute path from projectRoot + relative path,
+ * and assert it stays within the project root.
+ *
+ * Throws if the resolved path escapes the project root.
+ */
+export function resolveProjectPath(projectRoot: string, relPath: string): string {
+   const absRoot = path.resolve(projectRoot);
+   const absTarget = path.resolve(absRoot, relPath);
+
+   // Normalise for safety check
+   const rootWithSep = absRoot.endsWith(path.sep) ? absRoot : absRoot + path.sep;
+   if (!absTarget.startsWith(rootWithSep) && absTarget !== absRoot) {
+      throw new Error(
+         `Attempted to resolve path outside project root: ` +
+         `root="${absRoot}", target="${absTarget}"`,
+      );
+   }
+
+   return absTarget;
+}
+
+/**
+ * Convert an absolute path back to a project-relative path.
+ * Throws if the path is not under projectRoot.
+ */
+export function toProjectRelativePath(projectRoot: string, absolutePath: string): string {
+   const absRoot = path.resolve(projectRoot);
+   const absTarget = path.resolve(absolutePath);
+
+   const rootWithSep = absRoot.endsWith(path.sep) ? absRoot : absRoot + path.sep;
+   if (!absTarget.startsWith(rootWithSep) && absTarget !== absRoot) {
+      throw new Error(
+         `Path "${absTarget}" is not inside project root "${absRoot}".`,
+      );
+   }
+
+   const rel = path.relative(absRoot, absTarget);
+   return toPosixPath(rel);
+}
+
+/**
+ * Check if `target` is inside (or equal to) `base` directory.
+ */
+export function isSubPath(base: string, target: string): boolean {
+   const absBase = path.resolve(base);
+   const absTarget = path.resolve(target);
+
+   const baseWithSep = absBase.endsWith(path.sep) ? absBase : absBase + path.sep;
+   return absTarget === absBase || absTarget.startsWith(baseWithSep);
+}

package/src/util/logger.ts

@@ -0,0 +1,144 @@
+// src/util/logger.ts
+
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+
+export interface LoggerOptions {
+   level?: LogLevel;
+   /**
+    * Optional prefix string (e.g. "[scaffold]" or "[group:app]").
+    */
+   prefix?: string;
+}
+
+/**
+ * Minimal ANSI color helpers (no external deps).
+ */
+const supportsColor =
+   typeof process !== 'undefined' &&
+   process.stdout &&
+   process.stdout.isTTY &&
+   process.env.NO_COLOR !== '1';
+
+type ColorFn = (text: string) => string;
+
+function wrap(code: number): ColorFn {
+   const open = `\u001b[${code}m`;
+   const close = `\u001b[0m`;
+   return (text: string) => (supportsColor ? `${open}${text}${close}` : text);
+}
+
+const color = {
+   red: wrap(31),
+   yellow: wrap(33),
+   green: wrap(32),
+   cyan: wrap(36),
+   magenta: wrap(35),
+   dim: wrap(2),
+   bold: wrap(1),
+   gray: wrap(90),
+};
+
+function colorForLevel(level: LogLevel): ColorFn {
+   switch (level) {
+      case 'error':
+         return color.red;
+      case 'warn':
+         return color.yellow;
+      case 'info':
+         return color.cyan;
+      case 'debug':
+         return color.gray;
+      default:
+         return (s) => s;
+   }
+}
+
+/**
+ * Minimal logger for @timeax/scaffold with colored output.
+ */
+export class Logger {
+   private level: LogLevel;
+   private prefix: string | undefined;
+
+   constructor(options: LoggerOptions = {}) {
+      this.level = options.level ?? 'info';
+      this.prefix = options.prefix;
+   }
+
+   setLevel(level: LogLevel) {
+      this.level = level;
+   }
+
+   getLevel(): LogLevel {
+      return this.level;
+   }
+
+   /**
+    * Create a child logger with an additional prefix.
+    */
+   child(prefix: string): Logger {
+      const combined = this.prefix ? `${this.prefix}${prefix}` : prefix;
+      return new Logger({ level: this.level, prefix: combined });
+   }
+
+   private formatMessage(msg: unknown, lvl: LogLevel): string {
+      const text =
+         typeof msg === 'string'
+            ? msg
+            : msg instanceof Error
+               ? msg.message
+               : String(msg);
+
+      const levelColor = colorForLevel(lvl);
+      const prefixColored = this.prefix
+         ? color.magenta(this.prefix)
+         : undefined;
+
+      const textColored =
+         lvl === 'debug' ? color.dim(text) : levelColor(text);
+
+      if (prefixColored) {
+         return `${prefixColored} ${textColored}`;
+      }
+
+      return textColored;
+   }
+
+   private shouldLog(targetLevel: LogLevel): boolean {
+      const order: LogLevel[] = ['silent', 'error', 'warn', 'info', 'debug'];
+      const currentIdx = order.indexOf(this.level);
+      const targetIdx = order.indexOf(targetLevel);
+      if (currentIdx === -1 || targetIdx === -1) return true;
+      if (this.level === 'silent') return false;
+      return targetIdx <= currentIdx || targetLevel === 'error';
+   }
+
+   error(msg: unknown, ...rest: unknown[]) {
+      if (!this.shouldLog('error')) return;
+      console.error(this.formatMessage(msg, 'error'), ...rest);
+   }
+
+   warn(msg: unknown, ...rest: unknown[]) {
+      if (!this.shouldLog('warn')) return;
+      console.warn(this.formatMessage(msg, 'warn'), ...rest);
+   }
+
+   info(msg: unknown, ...rest: unknown[]) {
+      if (!this.shouldLog('info')) return;
+      console.log(this.formatMessage(msg, 'info'), ...rest);
+   }
+
+   debug(msg: unknown, ...rest: unknown[]) {
+      if (!this.shouldLog('debug')) return;
+      console.debug(this.formatMessage(msg, 'debug'), ...rest);
+   }
+}
+
+/**
+ * Default process-wide logger used by CLI and core.
+ * Level can be controlled via SCAFFOLD_LOG_LEVEL env.
+ */
+export const defaultLogger = new Logger({
+   level: (process.env.SCAFFOLD_LOG_LEVEL as LogLevel | undefined) ?? 'info',
+   prefix: '[scaffold]',
+});

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+   "compilerOptions": {
+      "target": "ESNext",
+      "module": "ESNext",
+      "moduleResolution": "bundler",
+      "esModuleInterop": true,
+      "allowSyntheticDefaultImports": true,
+      "strict": true,
+      "forceConsistentCasingInFileNames": true,
+      "skipLibCheck": true,
+      "resolveJsonModule": true,
+      "rootDir": "src",
+      "outDir": "dist",
+      "declaration": true,
+      "declarationMap": true,
+      "sourceMap": true,
+      "types": [
+         "node"
+      ]
+   },
+   "include": [
+      "src"
+   ]
+}

package/tsup.config.ts

@@ -0,0 +1,48 @@
+// tsup.config.ts
+import { defineConfig } from 'tsup';
+
+export default defineConfig([
+   // Library build (@timeax/scaffold import)
+   {
+      entry: ['src/index.ts'],
+      outDir: 'dist',
+      format: ['esm', 'cjs'],
+      dts: true,
+      sourcemap: true,
+      clean: true,
+      target: 'node18',
+      platform: 'node',
+      treeshake: true,
+      splitting: false, // small lib, keep it simple
+      outExtension({ format }) {
+         return {
+            // ESM → .mjs, CJS → .cjs
+            js: format === 'esm' ? '.mjs' : '.cjs',
+         };
+      },
+   },
+
+   // CLI build (scaffold command)
+   {
+      entry: {
+         cli: 'src/cli/main.ts',
+      },
+      outDir: 'dist',
+      format: ['esm', 'cjs'],
+      dts: false,
+      sourcemap: true,
+      clean: false, // don't blow away the lib build
+      target: 'node18',
+      platform: 'node',
+      treeshake: true,
+      splitting: false,
+      outExtension({ format }) {
+         return {
+            js: format === 'esm' ? '.mjs' : '.cjs',
+         };
+      },
+      banner: {
+         js: '#!/usr/bin/env node',
+      },
+   },
+]);