@timeax/scaffold 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,439 @@
+/**
+ * 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.
+ */
+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.
+ */
+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).
+ */
+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.
+ */
+type StructureEntry = FileEntry | DirEntry;
+
+/**
+ * Lifecycle stages for non-stub (regular) hooks.
+ *
+ * These hooks are called around file operations (create/delete).
+ */
+type RegularHookKind = 'preCreateFile' | 'postCreateFile' | 'preDeleteFile' | 'postDeleteFile';
+/**
+ * Lifecycle stages for stub-related hooks.
+ *
+ * These hooks are called around stub resolution for file content.
+ */
+type StubHookKind = 'preStub' | 'postStub';
+/**
+ * Context object passed to all hooks (both regular and stub).
+ */
+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`.
+ */
+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.
+ */
+type RegularHookFn = (ctx: HookContext) => void | Promise<void>;
+/**
+ * Function signature for stub hooks.
+ */
+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.
+ */
+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.
+ */
+interface StubHookConfig extends HookFilter {
+    fn: StubHookFn;
+}
+/**
+ * Stub configuration, defining how file content is generated
+ * and which stub-specific hooks apply.
+ */
+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[];
+    };
+}
+
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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;
+}
+
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+interface LoggerOptions {
+    level?: LogLevel;
+    /**
+     * Optional prefix string (e.g. "[scaffold]" or "[group:app]").
+     */
+    prefix?: string;
+}
+/**
+ * Minimal logger for @timeax/scaffold with colored output.
+ */
+declare class Logger {
+    private level;
+    private prefix;
+    constructor(options?: LoggerOptions);
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+    /**
+     * Create a child logger with an additional prefix.
+     */
+    child(prefix: string): Logger;
+    private formatMessage;
+    private shouldLog;
+    error(msg: unknown, ...rest: unknown[]): void;
+    warn(msg: unknown, ...rest: unknown[]): void;
+    info(msg: unknown, ...rest: unknown[]): void;
+    debug(msg: unknown, ...rest: unknown[]): void;
+}
+
+interface InteractiveDeleteParams {
+    absolutePath: string;
+    relativePath: string;
+    size: number;
+    createdByStub?: string;
+    groupName?: string;
+}
+
+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.
+ */
+declare function runOnce(cwd: string, options?: RunOptions): Promise<void>;
+
+/**
+ * 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).
+ */
+declare function scanDirectoryToStructureText(rootDir: string, options?: ScanStructureOptions): string;
+/**
+ * Result of scanning based on the scaffold config.
+ *
+ * You can use `structureFilePath` + `text` to write out group structure files.
+ */
+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.
+ */
+declare function scanProjectFromConfig(cwd: string, options?: ScanFromConfigOptions): Promise<ScanFromConfigResult[]>;
+/**
+ * Convenience helper: write scan results to their structure files.
+ *
+ * This will ensure the scaffold directory exists and overwrite existing
+ * structure files.
+ */
+declare function writeScannedStructuresFromConfig(cwd: string, options?: ScanFromConfigOptions): Promise<void>;
+
+export { type BaseEntryOptions, type DirEntry, type FileEntry, type HookContext, type HookFilter, type RegularHookConfig, type RegularHookFn, type RegularHookKind, type RunOptions, type ScaffoldConfig, type ScanFromConfigOptions, type ScanFromConfigResult, type ScanStructureOptions, type StructureEntry, type StructureGroupConfig, type StubConfig, type StubHookConfig, type StubHookFn, type StubHookKind, runOnce, scanDirectoryToStructureText, scanProjectFromConfig, writeScannedStructuresFromConfig };