create-gen-app 0.6.4 → 0.8.0

package/README.md

@@ -37,15 +37,65 @@ npm install create-gen-app
 
 ## Library Usage
 
-`create-gen-app` provides a modular set of classes to handle template cloning, caching, and processing.
+`create-gen-app` provides both a high-level orchestrator and modular building blocks for template scaffolding.
 
-### Core Components
+### Quick Start with TemplateScaffolder
 
-- **CacheManager**: Handles local caching of git repositories with TTL (Time-To-Live) support.
-- **GitCloner**: Handles cloning git repositories.
-- **Templatizer**: Handles variable extraction, user prompting, and template generation.
+The easiest way to use `create-gen-app` is with the `TemplateScaffolder` class, which combines caching, cloning, and template processing into a single API:
 
-### Example: Orchestration
+```typescript
+import { TemplateScaffolder } from 'create-gen-app';
+
+const scaffolder = new TemplateScaffolder({
+  toolName: 'my-cli',                    // Cache directory: ~/.my-cli/cache
+  defaultRepo: 'org/my-templates',       // Default template repository
+  ttlMs: 7 * 24 * 60 * 60 * 1000,       // Cache TTL: 1 week
+});
+
+// Scaffold a project from the default repo
+await scaffolder.scaffold({
+  outputDir: './my-project',
+  fromPath: 'starter',                   // Use the "starter" template variant
+  answers: { projectName: 'my-app' },    // Pre-populate answers
+});
+
+// Or scaffold from a specific repo
+await scaffolder.scaffold({
+  template: 'https://github.com/other/templates.git',
+  outputDir: './another-project',
+  branch: 'v2',
+});
+```
+
+### Template Repository Conventions
+
+`TemplateScaffolder` supports the `.boilerplates.json` convention for organizing multiple templates in a single repository:
+
+```
+my-templates/
+├── .boilerplates.json    # { "dir": "templates" }
+└── templates/
+    ├── starter/
+    │   ├── .boilerplate.json
+    │   └── ...template files...
+    └── advanced/
+        ├── .boilerplate.json
+        └── ...template files...
+```
+
+When you call `scaffold({ fromPath: 'starter' })`, the scaffolder will:
+1. Check if `starter/` exists directly in the repo root
+2. If not, read `.boilerplates.json` and look for `templates/starter/`
+
+### Core Components (Building Blocks)
+
+For more control, you can use the individual components directly:
+
+- **CacheManager**: Handles local caching of git repositories with TTL support
+- **GitCloner**: Handles cloning git repositories
+- **Templatizer**: Handles variable extraction, user prompting, and template generation
+
+### Example: Manual Orchestration
 
 Here is how you can combine these components to create a full CLI pipeline (similar to `create-gen-app-test`):
 
@@ -150,6 +200,28 @@ No code changes are needed; the generator discovers templates at runtime and wil
 
 ## API Overview
 
+### TemplateScaffolder (Recommended)
+
+The high-level orchestrator that combines caching, cloning, and template processing:
+
+- `new TemplateScaffolder(config)`: Initialize with configuration:
+  - `toolName` (required): Name for cache directory (e.g., `'my-cli'` → `~/.my-cli/cache`)
+  - `defaultRepo`: Default template repository URL or `org/repo` shorthand
+  - `defaultBranch`: Default branch to clone
+  - `ttlMs`: Cache time-to-live in milliseconds
+  - `cacheBaseDir`: Override cache location (useful for tests)
+- `scaffold(options)`: Scaffold a project from a template:
+  - `template`: Repository URL, local path, or `org/repo` shorthand (uses `defaultRepo` if not provided)
+  - `outputDir` (required): Output directory for generated project
+  - `fromPath`: Subdirectory within template to use
+  - `branch`: Branch to clone
+  - `answers`: Pre-populated answers to skip prompting
+  - `noTty`: Disable interactive prompts
+  - `prompter`: Reuse an existing Inquirerer instance
+- `readBoilerplatesConfig(dir)`: Read `.boilerplates.json` from a template repo
+- `readBoilerplateConfig(dir)`: Read `.boilerplate.json` from a template directory
+- `getCacheManager()`, `getGitCloner()`, `getTemplatizer()`: Access underlying components
+
 ### CacheManager
 - `new CacheManager(config)`: Initialize with `toolName` and optional `ttl`.
 - `get(key)`: Get path to cached repo if exists.

package/esm/index.js

@@ -11,6 +11,8 @@ export * from './cache/cache-manager';
 export * from './cache/types';
 export * from './git/git-cloner';
 export * from './git/types';
+export * from './scaffolder/template-scaffolder';
+export * from './scaffolder/types';
 export * from './template/templatizer';
 export * from './template/types';
 export * from './utils/npm-version-check';

package/esm/scaffolder/index.js

@@ -0,0 +1,2 @@
+export * from './template-scaffolder';
+export * from './types';

package/esm/scaffolder/template-scaffolder.js

@@ -0,0 +1,302 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { CacheManager } from '../cache/cache-manager';
+import { GitCloner } from '../git/git-cloner';
+import { Templatizer } from '../template/templatizer';
+/**
+ * High-level orchestrator for template scaffolding operations.
+ * Combines CacheManager, GitCloner, and Templatizer into a single, easy-to-use API.
+ *
+ * @example
+ * ```typescript
+ * const scaffolder = new TemplateScaffolder({
+ *   toolName: 'my-cli',
+ *   defaultRepo: 'https://github.com/org/templates.git',
+ *   ttlMs: 7 * 24 * 60 * 60 * 1000, // 1 week
+ * });
+ *
+ * await scaffolder.scaffold({
+ *   outputDir: './my-project',
+ *   fromPath: 'starter',
+ *   answers: { name: 'my-project' },
+ * });
+ * ```
+ */
+export class TemplateScaffolder {
+    config;
+    cacheManager;
+    gitCloner;
+    templatizer;
+    constructor(config) {
+        if (!config.toolName) {
+            throw new Error('TemplateScaffolder requires toolName in config');
+        }
+        this.config = config;
+        this.cacheManager = new CacheManager({
+            toolName: config.toolName,
+            ttl: config.ttlMs,
+            baseDir: config.cacheBaseDir,
+        });
+        this.gitCloner = new GitCloner();
+        this.templatizer = new Templatizer();
+    }
+    /**
+     * Scaffold a new project from a template.
+     *
+     * Handles both local directories and remote git repositories.
+     * For remote repos, caching is used to avoid repeated cloning.
+     *
+     * @param options - Scaffold options
+     * @returns Scaffold result with output path and metadata
+     */
+    async scaffold(options) {
+        const template = options.template ?? this.config.defaultRepo;
+        if (!template) {
+            throw new Error('No template specified and no defaultRepo configured. ' +
+                'Either pass template in options or set defaultRepo in config.');
+        }
+        const branch = options.branch ?? this.config.defaultBranch;
+        const resolvedTemplate = this.resolveTemplatePath(template);
+        if (this.isLocalPath(resolvedTemplate) && fs.existsSync(resolvedTemplate)) {
+            return this.scaffoldFromLocal(resolvedTemplate, options);
+        }
+        return this.scaffoldFromRemote(resolvedTemplate, branch, options);
+    }
+    /**
+     * Inspect a template without scaffolding.
+     * Clones/caches the template and reads its .boilerplate.json configuration
+     * without copying any files to an output directory.
+     *
+     * This is useful for metadata-driven workflows where you need to know
+     * the template's type or other configuration before deciding how to handle it.
+     *
+     * @param options - Inspect options
+     * @returns Inspect result with template metadata
+     */
+    inspect(options) {
+        const template = options.template ?? this.config.defaultRepo;
+        if (!template) {
+            throw new Error('No template specified and no defaultRepo configured. ' +
+                'Either pass template in options or set defaultRepo in config.');
+        }
+        const branch = options.branch ?? this.config.defaultBranch;
+        const resolvedTemplate = this.resolveTemplatePath(template);
+        if (this.isLocalPath(resolvedTemplate) && fs.existsSync(resolvedTemplate)) {
+            return this.inspectLocal(resolvedTemplate, options.fromPath);
+        }
+        return this.inspectRemote(resolvedTemplate, branch, options.fromPath);
+    }
+    /**
+     * Read the .boilerplates.json configuration from a template repository root.
+     */
+    readBoilerplatesConfig(templateDir) {
+        const configPath = path.join(templateDir, '.boilerplates.json');
+        if (fs.existsSync(configPath)) {
+            try {
+                const content = fs.readFileSync(configPath, 'utf-8');
+                return JSON.parse(content);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Read the .boilerplate.json configuration from a boilerplate directory.
+     */
+    readBoilerplateConfig(boilerplatePath) {
+        const jsonPath = path.join(boilerplatePath, '.boilerplate.json');
+        if (fs.existsSync(jsonPath)) {
+            try {
+                const content = fs.readFileSync(jsonPath, 'utf-8');
+                return JSON.parse(content);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Get the underlying CacheManager instance for advanced cache operations.
+     */
+    getCacheManager() {
+        return this.cacheManager;
+    }
+    /**
+     * Get the underlying GitCloner instance for advanced git operations.
+     */
+    getGitCloner() {
+        return this.gitCloner;
+    }
+    /**
+     * Get the underlying Templatizer instance for advanced template operations.
+     */
+    getTemplatizer() {
+        return this.templatizer;
+    }
+    inspectLocal(templateDir, fromPath) {
+        const { fromPath: resolvedFromPath, resolvedTemplatePath } = this.resolveFromPath(templateDir, fromPath);
+        const config = this.readBoilerplateConfig(resolvedTemplatePath);
+        return {
+            templateDir,
+            resolvedFromPath,
+            resolvedTemplatePath,
+            cacheUsed: false,
+            cacheExpired: false,
+            config,
+        };
+    }
+    inspectRemote(templateUrl, branch, fromPath) {
+        const normalizedUrl = this.gitCloner.normalizeUrl(templateUrl);
+        const cacheKey = this.cacheManager.createKey(normalizedUrl, branch);
+        const expiredMetadata = this.cacheManager.checkExpiration(cacheKey);
+        if (expiredMetadata) {
+            this.cacheManager.clear(cacheKey);
+        }
+        let templateDir;
+        let cacheUsed = false;
+        const cachedPath = this.cacheManager.get(cacheKey);
+        if (cachedPath && !expiredMetadata) {
+            templateDir = cachedPath;
+            cacheUsed = true;
+        }
+        else {
+            const tempDest = path.join(this.cacheManager.getReposDir(), cacheKey);
+            this.gitCloner.clone(normalizedUrl, tempDest, {
+                branch,
+                depth: 1,
+                singleBranch: true,
+            });
+            this.cacheManager.set(cacheKey, tempDest);
+            templateDir = tempDest;
+        }
+        const { fromPath: resolvedFromPath, resolvedTemplatePath } = this.resolveFromPath(templateDir, fromPath);
+        const config = this.readBoilerplateConfig(resolvedTemplatePath);
+        return {
+            templateDir,
+            resolvedFromPath,
+            resolvedTemplatePath,
+            cacheUsed,
+            cacheExpired: Boolean(expiredMetadata),
+            config,
+        };
+    }
+    async scaffoldFromLocal(templateDir, options) {
+        const { fromPath, resolvedTemplatePath } = this.resolveFromPath(templateDir, options.fromPath);
+        const boilerplateConfig = this.readBoilerplateConfig(resolvedTemplatePath);
+        const result = await this.templatizer.process(templateDir, options.outputDir, {
+            argv: options.answers,
+            noTty: options.noTty,
+            fromPath,
+            prompter: options.prompter,
+        });
+        return {
+            outputDir: result.outputDir,
+            cacheUsed: false,
+            cacheExpired: false,
+            templateDir,
+            fromPath,
+            questions: boilerplateConfig?.questions,
+            answers: result.answers,
+        };
+    }
+    async scaffoldFromRemote(templateUrl, branch, options) {
+        const normalizedUrl = this.gitCloner.normalizeUrl(templateUrl);
+        const cacheKey = this.cacheManager.createKey(normalizedUrl, branch);
+        const expiredMetadata = this.cacheManager.checkExpiration(cacheKey);
+        if (expiredMetadata) {
+            this.cacheManager.clear(cacheKey);
+        }
+        let templateDir;
+        let cacheUsed = false;
+        const cachedPath = this.cacheManager.get(cacheKey);
+        if (cachedPath && !expiredMetadata) {
+            templateDir = cachedPath;
+            cacheUsed = true;
+        }
+        else {
+            const tempDest = path.join(this.cacheManager.getReposDir(), cacheKey);
+            this.gitCloner.clone(normalizedUrl, tempDest, {
+                branch,
+                depth: 1,
+                singleBranch: true,
+            });
+            this.cacheManager.set(cacheKey, tempDest);
+            templateDir = tempDest;
+        }
+        const { fromPath, resolvedTemplatePath } = this.resolveFromPath(templateDir, options.fromPath);
+        const boilerplateConfig = this.readBoilerplateConfig(resolvedTemplatePath);
+        const result = await this.templatizer.process(templateDir, options.outputDir, {
+            argv: options.answers,
+            noTty: options.noTty,
+            fromPath,
+            prompter: options.prompter,
+        });
+        return {
+            outputDir: result.outputDir,
+            cacheUsed,
+            cacheExpired: Boolean(expiredMetadata),
+            templateDir,
+            fromPath,
+            questions: boilerplateConfig?.questions,
+            answers: result.answers,
+        };
+    }
+    /**
+     * Resolve the fromPath using .boilerplates.json convention.
+     *
+     * Resolution order:
+     * 1. If explicit fromPath is provided and exists, use it directly
+     * 2. If .boilerplates.json exists with a dir field, prepend it to fromPath
+     * 3. Return the fromPath as-is
+     */
+    resolveFromPath(templateDir, fromPath) {
+        if (!fromPath) {
+            return {
+                fromPath: undefined,
+                resolvedTemplatePath: templateDir,
+            };
+        }
+        const directPath = path.isAbsolute(fromPath)
+            ? fromPath
+            : path.join(templateDir, fromPath);
+        if (fs.existsSync(directPath) && fs.statSync(directPath).isDirectory()) {
+            return {
+                fromPath: path.isAbsolute(fromPath) ? path.relative(templateDir, fromPath) : fromPath,
+                resolvedTemplatePath: directPath,
+            };
+        }
+        const rootConfig = this.readBoilerplatesConfig(templateDir);
+        if (rootConfig?.dir) {
+            const configBasedPath = path.join(templateDir, rootConfig.dir, fromPath);
+            if (fs.existsSync(configBasedPath) && fs.statSync(configBasedPath).isDirectory()) {
+                return {
+                    fromPath: path.join(rootConfig.dir, fromPath),
+                    resolvedTemplatePath: configBasedPath,
+                };
+            }
+        }
+        return {
+            fromPath,
+            resolvedTemplatePath: path.join(templateDir, fromPath),
+        };
+    }
+    isLocalPath(value) {
+        return (value.startsWith('.') ||
+            value.startsWith('/') ||
+            value.startsWith('~') ||
+            (process.platform === 'win32' && /^[a-zA-Z]:/.test(value)));
+    }
+    resolveTemplatePath(template) {
+        if (this.isLocalPath(template)) {
+            if (template.startsWith('~')) {
+                const home = process.env.HOME || process.env.USERPROFILE || '';
+                return path.join(home, template.slice(1));
+            }
+            return path.resolve(template);
+        }
+        return template;
+    }
+}

package/esm/scaffolder/types.js

@@ -0,0 +1 @@
+export {};

package/esm/template/prompt.js

@@ -54,18 +54,22 @@ function normalizeQuestionName(name) {
  * Prompt the user for variable values
  * @param extractedVariables - Variables extracted from the template
  * @param argv - Command-line arguments to pre-populate answers
- * @param noTty - Whether to disable TTY mode
+ * @param existingPrompter - Optional existing Inquirerer instance to reuse.
+ *   If provided, the caller retains ownership and must close it themselves.
+ *   If not provided, a new instance is created and closed automatically.
+ * @param noTty - Whether to disable TTY mode (only used when creating a new prompter)
  * @returns Answers from the user
  */
-export async function promptUser(extractedVariables, argv = {}, noTty = false) {
+export async function promptUser(extractedVariables, argv = {}, existingPrompter, noTty = false) {
     const questions = generateQuestions(extractedVariables);
     if (questions.length === 0) {
         return argv;
     }
     const preparedArgv = mapArgvToQuestions(argv, questions);
-    const prompter = new Inquirerer({
-        noTty
-    });
+    // If an existing prompter is provided, use it (caller owns lifecycle)
+    // Otherwise, create a new one and close it when done
+    const prompter = existingPrompter ?? new Inquirerer({ noTty });
+    const shouldClose = !existingPrompter;
     try {
         const promptAnswers = await prompter.prompt(preparedArgv, questions);
         return {
@@ -74,7 +78,9 @@ export async function promptUser(extractedVariables, argv = {}, noTty = false) {
         };
     }
     finally {
-        prompter.close();
+        if (shouldClose) {
+            prompter.close();
+        }
     }
 }
 function mapArgvToQuestions(argv, questions) {

package/esm/template/templatizer.js

@@ -11,7 +11,7 @@ export class Templatizer {
      * Process a local template directory (extract + prompt + replace)
      * @param templateDir - Local directory path (MUST be local, NOT git URL)
      * @param outputDir - Output directory for generated project
-     * @param options - Processing options (argv overrides, noTty)
+     * @param options - Processing options (argv overrides, noTty, prompter)
      * @returns Processing result
      */
     async process(templateDir, outputDir, options) {
@@ -23,8 +23,8 @@ export class Templatizer {
         this.validateTemplateDir(actualTemplateDir);
         // Extract variables
         const variables = await this.extract(actualTemplateDir);
-        // Prompt for values
-        const answers = await this.prompt(variables, options?.argv, options?.noTty);
+        // Prompt for values (pass through optional prompter)
+        const answers = await this.prompt(variables, options?.argv, options?.prompter, options?.noTty);
         // Replace variables
         await this.replace(actualTemplateDir, outputDir, variables, answers);
         return {
@@ -41,9 +41,13 @@ export class Templatizer {
     }
     /**
      * Prompt user for variables
+     * @param extracted - Extracted variables from template
+     * @param argv - Pre-populated answers
+     * @param prompter - Optional existing Inquirerer instance to reuse
+     * @param noTty - Whether to disable TTY mode (only used when creating a new prompter)
      */
-    async prompt(extracted, argv, noTty) {
-        return promptUser(extracted, argv ?? {}, noTty ?? false);
+    async prompt(extracted, argv, prompter, noTty) {
+        return promptUser(extracted, argv ?? {}, prompter, noTty ?? false);
     }
     /**
      * Replace variables in template

package/index.d.ts

@@ -6,6 +6,8 @@ export * from './cache/cache-manager';
 export * from './cache/types';
 export * from './git/git-cloner';
 export * from './git/types';
+export * from './scaffolder/template-scaffolder';
+export * from './scaffolder/types';
 export * from './template/templatizer';
 export * from './template/types';
 export * from './utils/npm-version-check';

package/index.js

@@ -32,6 +32,8 @@ __exportStar(require("./cache/cache-manager"), exports);
 __exportStar(require("./cache/types"), exports);
 __exportStar(require("./git/git-cloner"), exports);
 __exportStar(require("./git/types"), exports);
+__exportStar(require("./scaffolder/template-scaffolder"), exports);
+__exportStar(require("./scaffolder/types"), exports);
 __exportStar(require("./template/templatizer"), exports);
 __exportStar(require("./template/types"), exports);
 __exportStar(require("./utils/npm-version-check"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-gen-app",
-  "version": "0.6.4",
+  "version": "0.8.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Clone and customize template repositories with variable replacement",
   "main": "index.js",
@@ -36,5 +36,5 @@
     "makage": "0.1.8"
   },
   "keywords": [],
-  "gitHead": "acd6339f6890d5609a9d7b7ce2799d752b2a766e"
+  "gitHead": "9ab0a7a8b90ccedd5f9bbde7dcdaef424c7f5acd"
 }

package/scaffolder/index.d.ts

@@ -0,0 +1,2 @@
+export * from './template-scaffolder';
+export * from './types';

package/scaffolder/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./template-scaffolder"), exports);
+__exportStar(require("./types"), exports);

package/scaffolder/template-scaffolder.d.ts

@@ -0,0 +1,87 @@
+import { CacheManager } from '../cache/cache-manager';
+import { GitCloner } from '../git/git-cloner';
+import { Templatizer } from '../template/templatizer';
+import { TemplateScaffolderConfig, ScaffoldOptions, ScaffoldResult, BoilerplatesConfig, BoilerplateConfig, InspectOptions, InspectResult } from './types';
+/**
+ * High-level orchestrator for template scaffolding operations.
+ * Combines CacheManager, GitCloner, and Templatizer into a single, easy-to-use API.
+ *
+ * @example
+ * ```typescript
+ * const scaffolder = new TemplateScaffolder({
+ *   toolName: 'my-cli',
+ *   defaultRepo: 'https://github.com/org/templates.git',
+ *   ttlMs: 7 * 24 * 60 * 60 * 1000, // 1 week
+ * });
+ *
+ * await scaffolder.scaffold({
+ *   outputDir: './my-project',
+ *   fromPath: 'starter',
+ *   answers: { name: 'my-project' },
+ * });
+ * ```
+ */
+export declare class TemplateScaffolder {
+    private config;
+    private cacheManager;
+    private gitCloner;
+    private templatizer;
+    constructor(config: TemplateScaffolderConfig);
+    /**
+     * Scaffold a new project from a template.
+     *
+     * Handles both local directories and remote git repositories.
+     * For remote repos, caching is used to avoid repeated cloning.
+     *
+     * @param options - Scaffold options
+     * @returns Scaffold result with output path and metadata
+     */
+    scaffold(options: ScaffoldOptions): Promise<ScaffoldResult>;
+    /**
+     * Inspect a template without scaffolding.
+     * Clones/caches the template and reads its .boilerplate.json configuration
+     * without copying any files to an output directory.
+     *
+     * This is useful for metadata-driven workflows where you need to know
+     * the template's type or other configuration before deciding how to handle it.
+     *
+     * @param options - Inspect options
+     * @returns Inspect result with template metadata
+     */
+    inspect(options: InspectOptions): InspectResult;
+    /**
+     * Read the .boilerplates.json configuration from a template repository root.
+     */
+    readBoilerplatesConfig(templateDir: string): BoilerplatesConfig | null;
+    /**
+     * Read the .boilerplate.json configuration from a boilerplate directory.
+     */
+    readBoilerplateConfig(boilerplatePath: string): BoilerplateConfig | null;
+    /**
+     * Get the underlying CacheManager instance for advanced cache operations.
+     */
+    getCacheManager(): CacheManager;
+    /**
+     * Get the underlying GitCloner instance for advanced git operations.
+     */
+    getGitCloner(): GitCloner;
+    /**
+     * Get the underlying Templatizer instance for advanced template operations.
+     */
+    getTemplatizer(): Templatizer;
+    private inspectLocal;
+    private inspectRemote;
+    private scaffoldFromLocal;
+    private scaffoldFromRemote;
+    /**
+     * Resolve the fromPath using .boilerplates.json convention.
+     *
+     * Resolution order:
+     * 1. If explicit fromPath is provided and exists, use it directly
+     * 2. If .boilerplates.json exists with a dir field, prepend it to fromPath
+     * 3. Return the fromPath as-is
+     */
+    private resolveFromPath;
+    private isLocalPath;
+    private resolveTemplatePath;
+}

package/scaffolder/template-scaffolder.js

@@ -0,0 +1,339 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateScaffolder = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const cache_manager_1 = require("../cache/cache-manager");
+const git_cloner_1 = require("../git/git-cloner");
+const templatizer_1 = require("../template/templatizer");
+/**
+ * High-level orchestrator for template scaffolding operations.
+ * Combines CacheManager, GitCloner, and Templatizer into a single, easy-to-use API.
+ *
+ * @example
+ * ```typescript
+ * const scaffolder = new TemplateScaffolder({
+ *   toolName: 'my-cli',
+ *   defaultRepo: 'https://github.com/org/templates.git',
+ *   ttlMs: 7 * 24 * 60 * 60 * 1000, // 1 week
+ * });
+ *
+ * await scaffolder.scaffold({
+ *   outputDir: './my-project',
+ *   fromPath: 'starter',
+ *   answers: { name: 'my-project' },
+ * });
+ * ```
+ */
+class TemplateScaffolder {
+    config;
+    cacheManager;
+    gitCloner;
+    templatizer;
+    constructor(config) {
+        if (!config.toolName) {
+            throw new Error('TemplateScaffolder requires toolName in config');
+        }
+        this.config = config;
+        this.cacheManager = new cache_manager_1.CacheManager({
+            toolName: config.toolName,
+            ttl: config.ttlMs,
+            baseDir: config.cacheBaseDir,
+        });
+        this.gitCloner = new git_cloner_1.GitCloner();
+        this.templatizer = new templatizer_1.Templatizer();
+    }
+    /**
+     * Scaffold a new project from a template.
+     *
+     * Handles both local directories and remote git repositories.
+     * For remote repos, caching is used to avoid repeated cloning.
+     *
+     * @param options - Scaffold options
+     * @returns Scaffold result with output path and metadata
+     */
+    async scaffold(options) {
+        const template = options.template ?? this.config.defaultRepo;
+        if (!template) {
+            throw new Error('No template specified and no defaultRepo configured. ' +
+                'Either pass template in options or set defaultRepo in config.');
+        }
+        const branch = options.branch ?? this.config.defaultBranch;
+        const resolvedTemplate = this.resolveTemplatePath(template);
+        if (this.isLocalPath(resolvedTemplate) && fs.existsSync(resolvedTemplate)) {
+            return this.scaffoldFromLocal(resolvedTemplate, options);
+        }
+        return this.scaffoldFromRemote(resolvedTemplate, branch, options);
+    }
+    /**
+     * Inspect a template without scaffolding.
+     * Clones/caches the template and reads its .boilerplate.json configuration
+     * without copying any files to an output directory.
+     *
+     * This is useful for metadata-driven workflows where you need to know
+     * the template's type or other configuration before deciding how to handle it.
+     *
+     * @param options - Inspect options
+     * @returns Inspect result with template metadata
+     */
+    inspect(options) {
+        const template = options.template ?? this.config.defaultRepo;
+        if (!template) {
+            throw new Error('No template specified and no defaultRepo configured. ' +
+                'Either pass template in options or set defaultRepo in config.');
+        }
+        const branch = options.branch ?? this.config.defaultBranch;
+        const resolvedTemplate = this.resolveTemplatePath(template);
+        if (this.isLocalPath(resolvedTemplate) && fs.existsSync(resolvedTemplate)) {
+            return this.inspectLocal(resolvedTemplate, options.fromPath);
+        }
+        return this.inspectRemote(resolvedTemplate, branch, options.fromPath);
+    }
+    /**
+     * Read the .boilerplates.json configuration from a template repository root.
+     */
+    readBoilerplatesConfig(templateDir) {
+        const configPath = path.join(templateDir, '.boilerplates.json');
+        if (fs.existsSync(configPath)) {
+            try {
+                const content = fs.readFileSync(configPath, 'utf-8');
+                return JSON.parse(content);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Read the .boilerplate.json configuration from a boilerplate directory.
+     */
+    readBoilerplateConfig(boilerplatePath) {
+        const jsonPath = path.join(boilerplatePath, '.boilerplate.json');
+        if (fs.existsSync(jsonPath)) {
+            try {
+                const content = fs.readFileSync(jsonPath, 'utf-8');
+                return JSON.parse(content);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Get the underlying CacheManager instance for advanced cache operations.
+     */
+    getCacheManager() {
+        return this.cacheManager;
+    }
+    /**
+     * Get the underlying GitCloner instance for advanced git operations.
+     */
+    getGitCloner() {
+        return this.gitCloner;
+    }
+    /**
+     * Get the underlying Templatizer instance for advanced template operations.
+     */
+    getTemplatizer() {
+        return this.templatizer;
+    }
+    inspectLocal(templateDir, fromPath) {
+        const { fromPath: resolvedFromPath, resolvedTemplatePath } = this.resolveFromPath(templateDir, fromPath);
+        const config = this.readBoilerplateConfig(resolvedTemplatePath);
+        return {
+            templateDir,
+            resolvedFromPath,
+            resolvedTemplatePath,
+            cacheUsed: false,
+            cacheExpired: false,
+            config,
+        };
+    }
+    inspectRemote(templateUrl, branch, fromPath) {
+        const normalizedUrl = this.gitCloner.normalizeUrl(templateUrl);
+        const cacheKey = this.cacheManager.createKey(normalizedUrl, branch);
+        const expiredMetadata = this.cacheManager.checkExpiration(cacheKey);
+        if (expiredMetadata) {
+            this.cacheManager.clear(cacheKey);
+        }
+        let templateDir;
+        let cacheUsed = false;
+        const cachedPath = this.cacheManager.get(cacheKey);
+        if (cachedPath && !expiredMetadata) {
+            templateDir = cachedPath;
+            cacheUsed = true;
+        }
+        else {
+            const tempDest = path.join(this.cacheManager.getReposDir(), cacheKey);
+            this.gitCloner.clone(normalizedUrl, tempDest, {
+                branch,
+                depth: 1,
+                singleBranch: true,
+            });
+            this.cacheManager.set(cacheKey, tempDest);
+            templateDir = tempDest;
+        }
+        const { fromPath: resolvedFromPath, resolvedTemplatePath } = this.resolveFromPath(templateDir, fromPath);
+        const config = this.readBoilerplateConfig(resolvedTemplatePath);
+        return {
+            templateDir,
+            resolvedFromPath,
+            resolvedTemplatePath,
+            cacheUsed,
+            cacheExpired: Boolean(expiredMetadata),
+            config,
+        };
+    }
+    async scaffoldFromLocal(templateDir, options) {
+        const { fromPath, resolvedTemplatePath } = this.resolveFromPath(templateDir, options.fromPath);
+        const boilerplateConfig = this.readBoilerplateConfig(resolvedTemplatePath);
+        const result = await this.templatizer.process(templateDir, options.outputDir, {
+            argv: options.answers,
+            noTty: options.noTty,
+            fromPath,
+            prompter: options.prompter,
+        });
+        return {
+            outputDir: result.outputDir,
+            cacheUsed: false,
+            cacheExpired: false,
+            templateDir,
+            fromPath,
+            questions: boilerplateConfig?.questions,
+            answers: result.answers,
+        };
+    }
+    async scaffoldFromRemote(templateUrl, branch, options) {
+        const normalizedUrl = this.gitCloner.normalizeUrl(templateUrl);
+        const cacheKey = this.cacheManager.createKey(normalizedUrl, branch);
+        const expiredMetadata = this.cacheManager.checkExpiration(cacheKey);
+        if (expiredMetadata) {
+            this.cacheManager.clear(cacheKey);
+        }
+        let templateDir;
+        let cacheUsed = false;
+        const cachedPath = this.cacheManager.get(cacheKey);
+        if (cachedPath && !expiredMetadata) {
+            templateDir = cachedPath;
+            cacheUsed = true;
+        }
+        else {
+            const tempDest = path.join(this.cacheManager.getReposDir(), cacheKey);
+            this.gitCloner.clone(normalizedUrl, tempDest, {
+                branch,
+                depth: 1,
+                singleBranch: true,
+            });
+            this.cacheManager.set(cacheKey, tempDest);
+            templateDir = tempDest;
+        }
+        const { fromPath, resolvedTemplatePath } = this.resolveFromPath(templateDir, options.fromPath);
+        const boilerplateConfig = this.readBoilerplateConfig(resolvedTemplatePath);
+        const result = await this.templatizer.process(templateDir, options.outputDir, {
+            argv: options.answers,
+            noTty: options.noTty,
+            fromPath,
+            prompter: options.prompter,
+        });
+        return {
+            outputDir: result.outputDir,
+            cacheUsed,
+            cacheExpired: Boolean(expiredMetadata),
+            templateDir,
+            fromPath,
+            questions: boilerplateConfig?.questions,
+            answers: result.answers,
+        };
+    }
+    /**
+     * Resolve the fromPath using .boilerplates.json convention.
+     *
+     * Resolution order:
+     * 1. If explicit fromPath is provided and exists, use it directly
+     * 2. If .boilerplates.json exists with a dir field, prepend it to fromPath
+     * 3. Return the fromPath as-is
+     */
+    resolveFromPath(templateDir, fromPath) {
+        if (!fromPath) {
+            return {
+                fromPath: undefined,
+                resolvedTemplatePath: templateDir,
+            };
+        }
+        const directPath = path.isAbsolute(fromPath)
+            ? fromPath
+            : path.join(templateDir, fromPath);
+        if (fs.existsSync(directPath) && fs.statSync(directPath).isDirectory()) {
+            return {
+                fromPath: path.isAbsolute(fromPath) ? path.relative(templateDir, fromPath) : fromPath,
+                resolvedTemplatePath: directPath,
+            };
+        }
+        const rootConfig = this.readBoilerplatesConfig(templateDir);
+        if (rootConfig?.dir) {
+            const configBasedPath = path.join(templateDir, rootConfig.dir, fromPath);
+            if (fs.existsSync(configBasedPath) && fs.statSync(configBasedPath).isDirectory()) {
+                return {
+                    fromPath: path.join(rootConfig.dir, fromPath),
+                    resolvedTemplatePath: configBasedPath,
+                };
+            }
+        }
+        return {
+            fromPath,
+            resolvedTemplatePath: path.join(templateDir, fromPath),
+        };
+    }
+    isLocalPath(value) {
+        return (value.startsWith('.') ||
+            value.startsWith('/') ||
+            value.startsWith('~') ||
+            (process.platform === 'win32' && /^[a-zA-Z]:/.test(value)));
+    }
+    resolveTemplatePath(template) {
+        if (this.isLocalPath(template)) {
+            if (template.startsWith('~')) {
+                const home = process.env.HOME || process.env.USERPROFILE || '';
+                return path.join(home, template.slice(1));
+            }
+            return path.resolve(template);
+        }
+        return template;
+    }
+}
+exports.TemplateScaffolder = TemplateScaffolder;

package/scaffolder/types.d.ts

@@ -0,0 +1,175 @@
+import { Inquirerer } from 'inquirerer';
+import { Question } from 'inquirerer';
+/**
+ * Configuration for TemplateScaffolder instance
+ */
+export interface TemplateScaffolderConfig {
+    /**
+     * Tool name used for cache directory naming (e.g., 'my-cli' -> ~/.my-cli/cache)
+     */
+    toolName: string;
+    /**
+     * Default template repository URL or path.
+     * Used when scaffold() is called without specifying a template.
+     */
+    defaultRepo?: string;
+    /**
+     * Default branch to use when cloning repositories
+     */
+    defaultBranch?: string;
+    /**
+     * Cache time-to-live in milliseconds.
+     * Cached templates older than this will be re-cloned.
+     * Default: no expiration
+     */
+    ttlMs?: number;
+    /**
+     * Base directory for cache storage.
+     * Useful for tests to avoid touching the real home directory.
+     */
+    cacheBaseDir?: string;
+}
+/**
+ * Options for a single scaffold operation
+ */
+export interface ScaffoldOptions {
+    /**
+     * Template repository URL, local path, or org/repo shorthand.
+     * If not provided, uses the defaultRepo from config.
+     */
+    template?: string;
+    /**
+     * Branch to clone (for remote repositories)
+     */
+    branch?: string;
+    /**
+     * Subdirectory within the template repository to use as the template root.
+     * Can be a direct path or a variant name that gets resolved via .boilerplates.json
+     */
+    fromPath?: string;
+    /**
+     * Output directory for the generated project
+     */
+    outputDir: string;
+    /**
+     * Pre-populated answers to skip prompting for known values
+     */
+    answers?: Record<string, any>;
+    /**
+     * Disable TTY mode for non-interactive environments
+     */
+    noTty?: boolean;
+    /**
+     * Optional Inquirerer instance to reuse for prompting.
+     * If provided, the caller retains ownership and is responsible for closing it.
+     * If not provided, a new instance will be created and closed automatically.
+     */
+    prompter?: Inquirerer;
+}
+/**
+ * Result of a scaffold operation
+ */
+export interface ScaffoldResult {
+    /**
+     * Path to the generated output directory
+     */
+    outputDir: string;
+    /**
+     * Whether a cached template was used
+     */
+    cacheUsed: boolean;
+    /**
+     * Whether the cache was expired and refreshed
+     */
+    cacheExpired: boolean;
+    /**
+     * Path to the cached/cloned template directory
+     */
+    templateDir: string;
+    /**
+     * The resolved fromPath used for template processing
+     */
+    fromPath?: string;
+    /**
+     * Questions loaded from .boilerplate.json, if any
+     */
+    questions?: Question[];
+    /**
+     * Answers collected during prompting
+     */
+    answers: Record<string, any>;
+}
+/**
+ * Root configuration for a boilerplates repository.
+ * Stored in `.boilerplates.json` at the repository root.
+ */
+export interface BoilerplatesConfig {
+    /**
+     * Default directory containing boilerplate templates (e.g., "templates", "boilerplates")
+     */
+    dir?: string;
+}
+/**
+ * Configuration for a single boilerplate template.
+ * Stored in `.boilerplate.json` within each template directory.
+ */
+export interface BoilerplateConfig {
+    /**
+     * Optional type identifier for the boilerplate
+     */
+    type?: string;
+    /**
+     * Questions to prompt the user during scaffolding
+     */
+    questions?: Question[];
+}
+/**
+ * Options for inspecting a template without scaffolding.
+ * Used to read template metadata before deciding how to handle it.
+ */
+export interface InspectOptions {
+    /**
+     * Template repository URL, local path, or org/repo shorthand.
+     * If not provided, uses the defaultRepo from config.
+     */
+    template?: string;
+    /**
+     * Branch to clone (for remote repositories)
+     */
+    branch?: string;
+    /**
+     * Subdirectory within the template repository to inspect.
+     * Can be a direct path or a variant name that gets resolved via .boilerplates.json
+     */
+    fromPath?: string;
+}
+/**
+ * Result of inspecting a template.
+ * Contains metadata about the template without copying any files.
+ */
+export interface InspectResult {
+    /**
+     * Path to the cached/cloned template directory
+     */
+    templateDir: string;
+    /**
+     * The resolved fromPath after .boilerplates.json resolution
+     */
+    resolvedFromPath?: string;
+    /**
+     * Full path to the resolved template directory
+     */
+    resolvedTemplatePath: string;
+    /**
+     * Whether a cached template was used
+     */
+    cacheUsed: boolean;
+    /**
+     * Whether the cache was expired and refreshed
+     */
+    cacheExpired: boolean;
+    /**
+     * The .boilerplate.json configuration from the template, if present
+     */
+    config: BoilerplateConfig | null;
+}

package/scaffolder/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/template/prompt.d.ts

@@ -1,4 +1,4 @@
-import { Question } from 'inquirerer';
+import { Inquirerer, Question } from 'inquirerer';
 import { ExtractedVariables } from '../types';
 /**
  * Generate questions from extracted variables
@@ -10,7 +10,10 @@ export declare function generateQuestions(extractedVariables: ExtractedVariables
  * Prompt the user for variable values
  * @param extractedVariables - Variables extracted from the template
  * @param argv - Command-line arguments to pre-populate answers
- * @param noTty - Whether to disable TTY mode
+ * @param existingPrompter - Optional existing Inquirerer instance to reuse.
+ *   If provided, the caller retains ownership and must close it themselves.
+ *   If not provided, a new instance is created and closed automatically.
+ * @param noTty - Whether to disable TTY mode (only used when creating a new prompter)
  * @returns Answers from the user
  */
-export declare function promptUser(extractedVariables: ExtractedVariables, argv?: Record<string, any>, noTty?: boolean): Promise<Record<string, any>>;
+export declare function promptUser(extractedVariables: ExtractedVariables, argv?: Record<string, any>, existingPrompter?: Inquirerer, noTty?: boolean): Promise<Record<string, any>>;

package/template/prompt.js

@@ -58,18 +58,22 @@ function normalizeQuestionName(name) {
  * Prompt the user for variable values
  * @param extractedVariables - Variables extracted from the template
  * @param argv - Command-line arguments to pre-populate answers
- * @param noTty - Whether to disable TTY mode
+ * @param existingPrompter - Optional existing Inquirerer instance to reuse.
+ *   If provided, the caller retains ownership and must close it themselves.
+ *   If not provided, a new instance is created and closed automatically.
+ * @param noTty - Whether to disable TTY mode (only used when creating a new prompter)
  * @returns Answers from the user
  */
-async function promptUser(extractedVariables, argv = {}, noTty = false) {
+async function promptUser(extractedVariables, argv = {}, existingPrompter, noTty = false) {
     const questions = generateQuestions(extractedVariables);
     if (questions.length === 0) {
         return argv;
     }
     const preparedArgv = mapArgvToQuestions(argv, questions);
-    const prompter = new inquirerer_1.Inquirerer({
-        noTty
-    });
+    // If an existing prompter is provided, use it (caller owns lifecycle)
+    // Otherwise, create a new one and close it when done
+    const prompter = existingPrompter ?? new inquirerer_1.Inquirerer({ noTty });
+    const shouldClose = !existingPrompter;
     try {
         const promptAnswers = await prompter.prompt(preparedArgv, questions);
         return {
@@ -78,7 +82,9 @@ async function promptUser(extractedVariables, argv = {}, noTty = false) {
         };
     }
     finally {
-        prompter.close();
+        if (shouldClose) {
+            prompter.close();
+        }
     }
 }
 function mapArgvToQuestions(argv, questions) {

package/template/templatizer.d.ts

@@ -6,7 +6,7 @@ export declare class Templatizer {
      * Process a local template directory (extract + prompt + replace)
      * @param templateDir - Local directory path (MUST be local, NOT git URL)
      * @param outputDir - Output directory for generated project
-     * @param options - Processing options (argv overrides, noTty)
+     * @param options - Processing options (argv overrides, noTty, prompter)
      * @returns Processing result
      */
     process(templateDir: string, outputDir: string, options?: ProcessOptions): Promise<TemplatizerResult>;
@@ -16,8 +16,12 @@ export declare class Templatizer {
     extract(templateDir: string): Promise<ExtractedVariables>;
     /**
      * Prompt user for variables
+     * @param extracted - Extracted variables from template
+     * @param argv - Pre-populated answers
+     * @param prompter - Optional existing Inquirerer instance to reuse
+     * @param noTty - Whether to disable TTY mode (only used when creating a new prompter)
      */
-    prompt(extracted: ExtractedVariables, argv?: Record<string, any>, noTty?: boolean): Promise<Record<string, any>>;
+    prompt(extracted: ExtractedVariables, argv?: Record<string, any>, prompter?: import('inquirerer').Inquirerer, noTty?: boolean): Promise<Record<string, any>>;
     /**
      * Replace variables in template
      */

package/template/templatizer.js

@@ -47,7 +47,7 @@ class Templatizer {
      * Process a local template directory (extract + prompt + replace)
      * @param templateDir - Local directory path (MUST be local, NOT git URL)
      * @param outputDir - Output directory for generated project
-     * @param options - Processing options (argv overrides, noTty)
+     * @param options - Processing options (argv overrides, noTty, prompter)
      * @returns Processing result
      */
     async process(templateDir, outputDir, options) {
@@ -59,8 +59,8 @@ class Templatizer {
         this.validateTemplateDir(actualTemplateDir);
         // Extract variables
         const variables = await this.extract(actualTemplateDir);
-        // Prompt for values
-        const answers = await this.prompt(variables, options?.argv, options?.noTty);
+        // Prompt for values (pass through optional prompter)
+        const answers = await this.prompt(variables, options?.argv, options?.prompter, options?.noTty);
         // Replace variables
         await this.replace(actualTemplateDir, outputDir, variables, answers);
         return {
@@ -77,9 +77,13 @@ class Templatizer {
     }
     /**
      * Prompt user for variables
+     * @param extracted - Extracted variables from template
+     * @param argv - Pre-populated answers
+     * @param prompter - Optional existing Inquirerer instance to reuse
+     * @param noTty - Whether to disable TTY mode (only used when creating a new prompter)
      */
-    async prompt(extracted, argv, noTty) {
-        return (0, prompt_1.promptUser)(extracted, argv ?? {}, noTty ?? false);
+    async prompt(extracted, argv, prompter, noTty) {
+        return (0, prompt_1.promptUser)(extracted, argv ?? {}, prompter, noTty ?? false);
     }
     /**
      * Replace variables in template

package/template/types.d.ts

@@ -1,8 +1,15 @@
+import { Inquirerer } from 'inquirerer';
 import { ExtractedVariables } from '../types';
 export interface ProcessOptions {
     argv?: Record<string, any>;
     noTty?: boolean;
     fromPath?: string;
+    /**
+     * Optional Inquirerer instance to reuse for prompting.
+     * If provided, the caller retains ownership and is responsible for closing it.
+     * If not provided, a new instance will be created and closed automatically.
+     */
+    prompter?: Inquirerer;
 }
 export interface TemplatizerResult {
     outputDir: string;