genomic 5.0.3 → 5.2.0

package/esm/git/git-cloner.js

@@ -2,6 +2,7 @@ import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { createSpinner } from 'inquirerer';
 export class GitCloner {
     /**
      * Clone a git repository to a destination
@@ -73,14 +74,28 @@ export class GitCloner {
         const branch = options?.branch;
         const depth = options?.depth ?? 1;
         const singleBranch = options?.singleBranch ?? true;
+        const silent = options?.silent ?? true;
         const branchArgs = branch ? ` --branch ${branch}` : '';
         const singleBranchArgs = singleBranch ? ' --single-branch' : '';
         const depthArgs = ` --depth ${depth}`;
         const command = `git clone${branchArgs}${singleBranchArgs}${depthArgs} ${url} ${destination}`;
+        const spinner = silent ? createSpinner(`Cloning ${url}...`) : null;
         try {
-            execSync(command, { stdio: 'inherit' });
+            if (spinner) {
+                spinner.start();
+            }
+            execSync(command, {
+                stdio: silent ? 'pipe' : 'inherit',
+                encoding: 'utf-8'
+            });
+            if (spinner) {
+                spinner.succeed('Repository cloned');
+            }
         }
         catch (error) {
+            if (spinner) {
+                spinner.fail('Failed to clone repository');
+            }
             // Clean up on failure
             if (fs.existsSync(destination)) {
                 fs.rmSync(destination, { recursive: true, force: true });

package/esm/scaffolder/index.js

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

package/esm/scaffolder/scan-boilerplates.js

@@ -0,0 +1,187 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Directories to skip during recursive scanning.
+ * These are common directories that should never contain boilerplates.
+ */
+const SKIP_DIRECTORIES = new Set([
+    '.git',
+    'node_modules',
+    '.pnpm',
+    'dist',
+    'build',
+    'coverage',
+    '.next',
+    '.nuxt',
+    '.cache',
+    '__pycache__',
+    '.venv',
+    'venv',
+]);
+/**
+ * Read the .boilerplate.json configuration from a directory.
+ *
+ * @param dirPath - The directory path to check
+ * @returns The boilerplate config or null if not found
+ */
+export function readBoilerplateConfig(dirPath) {
+    const configPath = path.join(dirPath, '.boilerplate.json');
+    if (fs.existsSync(configPath)) {
+        try {
+            const content = fs.readFileSync(configPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Recursively scan a directory for boilerplate templates.
+ *
+ * A boilerplate is any directory containing a `.boilerplate.json` file.
+ * This function recursively searches the entire directory tree (with sensible
+ * pruning of common non-template directories like node_modules, .git, etc.)
+ * and returns all discovered boilerplates with their relative paths.
+ *
+ * This is useful when:
+ * - The user specifies `--dir .` to bypass `.boilerplates.json`
+ * - You want to discover all available boilerplates regardless of nesting
+ * - You need to match a `fromPath` against available boilerplates
+ *
+ * @param baseDir - The root directory to start scanning from
+ * @param options - Scanning options
+ * @returns Array of discovered boilerplates with relative paths
+ *
+ * @example
+ * ```typescript
+ * // Given structure:
+ * // repo/
+ * //   default/
+ * //     module/.boilerplate.json
+ * //     workspace/.boilerplate.json
+ * //   scripts/  (no .boilerplate.json)
+ *
+ * const boilerplates = scanBoilerplatesRecursive('/path/to/repo');
+ * // Returns:
+ * // [
+ * //   { relativePath: 'default/module', absolutePath: '...', config: {...} },
+ * //   { relativePath: 'default/workspace', absolutePath: '...', config: {...} }
+ * // ]
+ * // Note: 'scripts' is not included because it has no .boilerplate.json
+ * ```
+ */
+export function scanBoilerplatesRecursive(baseDir, options = {}) {
+    const { maxDepth = 10, skipDirectories = [] } = options;
+    const boilerplates = [];
+    const skipSet = new Set([...SKIP_DIRECTORIES, ...skipDirectories]);
+    function scan(currentDir, relativePath, depth) {
+        if (depth > maxDepth) {
+            return;
+        }
+        if (!fs.existsSync(currentDir)) {
+            return;
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            if (skipSet.has(entry.name)) {
+                continue;
+            }
+            const entryPath = path.join(currentDir, entry.name);
+            const entryRelativePath = relativePath ? path.join(relativePath, entry.name) : entry.name;
+            const config = readBoilerplateConfig(entryPath);
+            if (config) {
+                boilerplates.push({
+                    relativePath: entryRelativePath,
+                    absolutePath: entryPath,
+                    config,
+                });
+            }
+            // Continue scanning subdirectories even if this directory is a boilerplate
+            // (in case there are nested boilerplates, though uncommon)
+            scan(entryPath, entryRelativePath, depth + 1);
+        }
+    }
+    scan(baseDir, '', 0);
+    // Sort by relative path for consistent ordering
+    boilerplates.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    return boilerplates;
+}
+/**
+ * Find a boilerplate by matching against a fromPath.
+ *
+ * This function attempts to match a user-provided `fromPath` against
+ * discovered boilerplates. It supports:
+ * 1. Exact match: `fromPath` matches a relative path exactly
+ * 2. Basename match: `fromPath` matches the last segment of a relative path
+ *    (only if unambiguous - i.e., exactly one match)
+ *
+ * @param boilerplates - Array of scanned boilerplates
+ * @param fromPath - The path to match against
+ * @returns The matching boilerplate, or null if no match or ambiguous
+ *
+ * @example
+ * ```typescript
+ * const boilerplates = scanBoilerplatesRecursive('/path/to/repo');
+ *
+ * // Exact match
+ * findBoilerplateByPath(boilerplates, 'default/module');
+ * // Returns the 'default/module' boilerplate
+ *
+ * // Basename match (unambiguous)
+ * findBoilerplateByPath(boilerplates, 'module');
+ * // Returns the 'default/module' boilerplate if it's the only one ending in 'module'
+ *
+ * // Ambiguous basename match
+ * // If both 'default/module' and 'supabase/module' exist:
+ * findBoilerplateByPath(boilerplates, 'module');
+ * // Returns null (ambiguous)
+ * ```
+ */
+export function findBoilerplateByPath(boilerplates, fromPath) {
+    // Normalize the fromPath (remove leading/trailing slashes)
+    const normalizedPath = fromPath.replace(/^\/+|\/+$/g, '');
+    // Try exact match first
+    const exactMatch = boilerplates.find((bp) => bp.relativePath === normalizedPath);
+    if (exactMatch) {
+        return exactMatch;
+    }
+    // Try basename match (last segment of path)
+    const basename = path.basename(normalizedPath);
+    const basenameMatches = boilerplates.filter((bp) => path.basename(bp.relativePath) === basename);
+    // Only return if unambiguous (exactly one match)
+    if (basenameMatches.length === 1) {
+        return basenameMatches[0];
+    }
+    return null;
+}
+/**
+ * Find a boilerplate by type within a scanned list.
+ *
+ * @param boilerplates - Array of scanned boilerplates
+ * @param type - The type to find (e.g., 'workspace', 'module')
+ * @returns The matching boilerplate or undefined
+ */
+export function findBoilerplateByType(boilerplates, type) {
+    return boilerplates.find((bp) => bp.config.type === type);
+}
+/**
+ * Get all boilerplates of a specific type.
+ *
+ * @param boilerplates - Array of scanned boilerplates
+ * @param type - The type to filter by
+ * @returns Array of matching boilerplates
+ */
+export function filterBoilerplatesByType(boilerplates, type) {
+    return boilerplates.filter((bp) => bp.config.type === type);
+}

package/esm/scaffolder/template-scaffolder.js

@@ -3,6 +3,7 @@ import * as path from 'path';
 import { CacheManager } from '../cache/cache-manager';
 import { GitCloner } from '../git/git-cloner';
 import { Templatizer } from '../template/templatizer';
+import { scanBoilerplatesRecursive, findBoilerplateByPath, } from './scan-boilerplates';
 /**
  * High-level orchestrator for template scaffolding operations.
  * Combines CacheManager, GitCloner, and Templatizer into a single, easy-to-use API.
@@ -137,6 +138,33 @@ export class TemplateScaffolder {
     getTemplatizer() {
         return this.templatizer;
     }
+    /**
+     * Scan a template directory recursively for all boilerplates.
+     *
+     * A boilerplate is any directory containing a `.boilerplate.json` file.
+     * This method recursively searches the entire directory tree and returns
+     * all discovered boilerplates with their relative paths.
+     *
+     * This is useful when:
+     * - The user specifies `--dir .` to bypass `.boilerplates.json`
+     * - You want to discover all available boilerplates regardless of nesting
+     * - You need to present a list of available boilerplates to the user
+     *
+     * @param templateDir - The root directory to scan
+     * @param options - Scanning options (maxDepth, skipDirectories)
+     * @returns Array of discovered boilerplates with relative paths
+     *
+     * @example
+     * ```typescript
+     * const scaffolder = new TemplateScaffolder({ toolName: 'my-cli' });
+     * const inspection = scaffolder.inspect({ template: 'org/repo' });
+     * const boilerplates = scaffolder.scanBoilerplates(inspection.templateDir);
+     * // Returns: [{ relativePath: 'default/module', ... }, { relativePath: 'default/workspace', ... }]
+     * ```
+     */
+    scanBoilerplates(templateDir, options) {
+        return scanBoilerplatesRecursive(templateDir, options);
+    }
     inspectLocal(templateDir, fromPath, useBoilerplatesConfig = true) {
         const { fromPath: resolvedFromPath, resolvedTemplatePath } = this.resolveFromPath(templateDir, fromPath, useBoilerplatesConfig);
         const config = this.readBoilerplateConfig(resolvedTemplatePath);
@@ -246,12 +274,13 @@ export class TemplateScaffolder {
         };
     }
     /**
-     * Resolve the fromPath using .boilerplates.json convention.
+     * Resolve the fromPath using .boilerplates.json convention and recursive scanning.
      *
      * Resolution order:
      * 1. If explicit fromPath is provided and exists, use it directly
      * 2. If useBoilerplatesConfig is true and .boilerplates.json exists with a dir field, prepend it to fromPath
-     * 3. Return the fromPath as-is
+     * 3. Recursively scan for boilerplates and try to match fromPath (exact match, then basename match if unambiguous)
+     * 4. Return the fromPath as-is (will likely fail later if path doesn't exist)
      *
      * @param templateDir - The template repository root directory
      * @param fromPath - The subdirectory path to resolve
@@ -286,6 +315,17 @@ export class TemplateScaffolder {
                 }
             }
         }
+        // Try recursive scan to find a matching boilerplate
+        // This handles cases like `--dir .` where the user wants to match against
+        // discovered boilerplates (e.g., "module" matching "default/module")
+        const boilerplates = scanBoilerplatesRecursive(templateDir);
+        const match = findBoilerplateByPath(boilerplates, fromPath);
+        if (match) {
+            return {
+                fromPath: match.relativePath,
+                resolvedTemplatePath: match.absolutePath,
+            };
+        }
         return {
             fromPath,
             resolvedTemplatePath: path.join(templateDir, fromPath),

package/git/git-cloner.js

@@ -38,6 +38,7 @@ const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
+const inquirerer_1 = require("inquirerer");
 class GitCloner {
     /**
      * Clone a git repository to a destination
@@ -109,14 +110,28 @@ class GitCloner {
         const branch = options?.branch;
         const depth = options?.depth ?? 1;
         const singleBranch = options?.singleBranch ?? true;
+        const silent = options?.silent ?? true;
         const branchArgs = branch ? ` --branch ${branch}` : '';
         const singleBranchArgs = singleBranch ? ' --single-branch' : '';
         const depthArgs = ` --depth ${depth}`;
         const command = `git clone${branchArgs}${singleBranchArgs}${depthArgs} ${url} ${destination}`;
+        const spinner = silent ? (0, inquirerer_1.createSpinner)(`Cloning ${url}...`) : null;
         try {
-            (0, child_process_1.execSync)(command, { stdio: 'inherit' });
+            if (spinner) {
+                spinner.start();
+            }
+            (0, child_process_1.execSync)(command, {
+                stdio: silent ? 'pipe' : 'inherit',
+                encoding: 'utf-8'
+            });
+            if (spinner) {
+                spinner.succeed('Repository cloned');
+            }
         }
         catch (error) {
+            if (spinner) {
+                spinner.fail('Failed to clone repository');
+            }
             // Clean up on failure
             if (fs.existsSync(destination)) {
                 fs.rmSync(destination, { recursive: true, force: true });

package/git/types.d.ts

@@ -2,6 +2,8 @@ export interface GitCloneOptions {
     branch?: string;
     depth?: number;
     singleBranch?: boolean;
+    /** If true (default), show spinner and silence git output. If false, show raw git output. */
+    silent?: boolean;
 }
 export interface GitCloneResult {
     destination: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genomic",
-  "version": "5.0.3",
+  "version": "5.2.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Clone and customize template repositories with variable replacement",
   "main": "index.js",
@@ -29,12 +29,12 @@
   },
   "dependencies": {
     "appstash": "0.2.7",
-    "inquirerer": "4.1.2"
+    "inquirerer": "4.2.0"
   },
   "devDependencies": {
     "copyfiles": "^2.4.1",
     "makage": "0.1.8"
   },
   "keywords": [],
-  "gitHead": "8f2e433e1feb28d23095ce761388a61a0e827bd0"
+  "gitHead": "89afff9da8425e38d1c8b75b2021833581a90307"
 }

package/scaffolder/index.d.ts

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

package/scaffolder/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./template-scaffolder"), exports);
 __exportStar(require("./types"), exports);
+__exportStar(require("./scan-boilerplates"), exports);

package/scaffolder/scan-boilerplates.d.ts

@@ -0,0 +1,124 @@
+import { BoilerplateConfig } from './types';
+/**
+ * Result of scanning for boilerplates.
+ */
+export interface ScannedBoilerplate {
+    /**
+     * The relative path from the scan root to the boilerplate directory.
+     * For example: "default/module", "default/workspace"
+     */
+    relativePath: string;
+    /**
+     * The absolute path to the boilerplate directory.
+     */
+    absolutePath: string;
+    /**
+     * The boilerplate configuration from .boilerplate.json
+     */
+    config: BoilerplateConfig;
+}
+/**
+ * Options for scanning boilerplates.
+ */
+export interface ScanBoilerplatesOptions {
+    /**
+     * Maximum depth to recurse into directories.
+     * Default: 10 (should be enough for any reasonable structure)
+     */
+    maxDepth?: number;
+    /**
+     * Additional directory names to skip during scanning.
+     */
+    skipDirectories?: string[];
+}
+/**
+ * Read the .boilerplate.json configuration from a directory.
+ *
+ * @param dirPath - The directory path to check
+ * @returns The boilerplate config or null if not found
+ */
+export declare function readBoilerplateConfig(dirPath: string): BoilerplateConfig | null;
+/**
+ * Recursively scan a directory for boilerplate templates.
+ *
+ * A boilerplate is any directory containing a `.boilerplate.json` file.
+ * This function recursively searches the entire directory tree (with sensible
+ * pruning of common non-template directories like node_modules, .git, etc.)
+ * and returns all discovered boilerplates with their relative paths.
+ *
+ * This is useful when:
+ * - The user specifies `--dir .` to bypass `.boilerplates.json`
+ * - You want to discover all available boilerplates regardless of nesting
+ * - You need to match a `fromPath` against available boilerplates
+ *
+ * @param baseDir - The root directory to start scanning from
+ * @param options - Scanning options
+ * @returns Array of discovered boilerplates with relative paths
+ *
+ * @example
+ * ```typescript
+ * // Given structure:
+ * // repo/
+ * //   default/
+ * //     module/.boilerplate.json
+ * //     workspace/.boilerplate.json
+ * //   scripts/  (no .boilerplate.json)
+ *
+ * const boilerplates = scanBoilerplatesRecursive('/path/to/repo');
+ * // Returns:
+ * // [
+ * //   { relativePath: 'default/module', absolutePath: '...', config: {...} },
+ * //   { relativePath: 'default/workspace', absolutePath: '...', config: {...} }
+ * // ]
+ * // Note: 'scripts' is not included because it has no .boilerplate.json
+ * ```
+ */
+export declare function scanBoilerplatesRecursive(baseDir: string, options?: ScanBoilerplatesOptions): ScannedBoilerplate[];
+/**
+ * Find a boilerplate by matching against a fromPath.
+ *
+ * This function attempts to match a user-provided `fromPath` against
+ * discovered boilerplates. It supports:
+ * 1. Exact match: `fromPath` matches a relative path exactly
+ * 2. Basename match: `fromPath` matches the last segment of a relative path
+ *    (only if unambiguous - i.e., exactly one match)
+ *
+ * @param boilerplates - Array of scanned boilerplates
+ * @param fromPath - The path to match against
+ * @returns The matching boilerplate, or null if no match or ambiguous
+ *
+ * @example
+ * ```typescript
+ * const boilerplates = scanBoilerplatesRecursive('/path/to/repo');
+ *
+ * // Exact match
+ * findBoilerplateByPath(boilerplates, 'default/module');
+ * // Returns the 'default/module' boilerplate
+ *
+ * // Basename match (unambiguous)
+ * findBoilerplateByPath(boilerplates, 'module');
+ * // Returns the 'default/module' boilerplate if it's the only one ending in 'module'
+ *
+ * // Ambiguous basename match
+ * // If both 'default/module' and 'supabase/module' exist:
+ * findBoilerplateByPath(boilerplates, 'module');
+ * // Returns null (ambiguous)
+ * ```
+ */
+export declare function findBoilerplateByPath(boilerplates: ScannedBoilerplate[], fromPath: string): ScannedBoilerplate | null;
+/**
+ * Find a boilerplate by type within a scanned list.
+ *
+ * @param boilerplates - Array of scanned boilerplates
+ * @param type - The type to find (e.g., 'workspace', 'module')
+ * @returns The matching boilerplate or undefined
+ */
+export declare function findBoilerplateByType(boilerplates: ScannedBoilerplate[], type: string): ScannedBoilerplate | undefined;
+/**
+ * Get all boilerplates of a specific type.
+ *
+ * @param boilerplates - Array of scanned boilerplates
+ * @param type - The type to filter by
+ * @returns Array of matching boilerplates
+ */
+export declare function filterBoilerplatesByType(boilerplates: ScannedBoilerplate[], type: string): ScannedBoilerplate[];

package/scaffolder/scan-boilerplates.js

@@ -0,0 +1,227 @@
+"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.readBoilerplateConfig = readBoilerplateConfig;
+exports.scanBoilerplatesRecursive = scanBoilerplatesRecursive;
+exports.findBoilerplateByPath = findBoilerplateByPath;
+exports.findBoilerplateByType = findBoilerplateByType;
+exports.filterBoilerplatesByType = filterBoilerplatesByType;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Directories to skip during recursive scanning.
+ * These are common directories that should never contain boilerplates.
+ */
+const SKIP_DIRECTORIES = new Set([
+    '.git',
+    'node_modules',
+    '.pnpm',
+    'dist',
+    'build',
+    'coverage',
+    '.next',
+    '.nuxt',
+    '.cache',
+    '__pycache__',
+    '.venv',
+    'venv',
+]);
+/**
+ * Read the .boilerplate.json configuration from a directory.
+ *
+ * @param dirPath - The directory path to check
+ * @returns The boilerplate config or null if not found
+ */
+function readBoilerplateConfig(dirPath) {
+    const configPath = path.join(dirPath, '.boilerplate.json');
+    if (fs.existsSync(configPath)) {
+        try {
+            const content = fs.readFileSync(configPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Recursively scan a directory for boilerplate templates.
+ *
+ * A boilerplate is any directory containing a `.boilerplate.json` file.
+ * This function recursively searches the entire directory tree (with sensible
+ * pruning of common non-template directories like node_modules, .git, etc.)
+ * and returns all discovered boilerplates with their relative paths.
+ *
+ * This is useful when:
+ * - The user specifies `--dir .` to bypass `.boilerplates.json`
+ * - You want to discover all available boilerplates regardless of nesting
+ * - You need to match a `fromPath` against available boilerplates
+ *
+ * @param baseDir - The root directory to start scanning from
+ * @param options - Scanning options
+ * @returns Array of discovered boilerplates with relative paths
+ *
+ * @example
+ * ```typescript
+ * // Given structure:
+ * // repo/
+ * //   default/
+ * //     module/.boilerplate.json
+ * //     workspace/.boilerplate.json
+ * //   scripts/  (no .boilerplate.json)
+ *
+ * const boilerplates = scanBoilerplatesRecursive('/path/to/repo');
+ * // Returns:
+ * // [
+ * //   { relativePath: 'default/module', absolutePath: '...', config: {...} },
+ * //   { relativePath: 'default/workspace', absolutePath: '...', config: {...} }
+ * // ]
+ * // Note: 'scripts' is not included because it has no .boilerplate.json
+ * ```
+ */
+function scanBoilerplatesRecursive(baseDir, options = {}) {
+    const { maxDepth = 10, skipDirectories = [] } = options;
+    const boilerplates = [];
+    const skipSet = new Set([...SKIP_DIRECTORIES, ...skipDirectories]);
+    function scan(currentDir, relativePath, depth) {
+        if (depth > maxDepth) {
+            return;
+        }
+        if (!fs.existsSync(currentDir)) {
+            return;
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            if (skipSet.has(entry.name)) {
+                continue;
+            }
+            const entryPath = path.join(currentDir, entry.name);
+            const entryRelativePath = relativePath ? path.join(relativePath, entry.name) : entry.name;
+            const config = readBoilerplateConfig(entryPath);
+            if (config) {
+                boilerplates.push({
+                    relativePath: entryRelativePath,
+                    absolutePath: entryPath,
+                    config,
+                });
+            }
+            // Continue scanning subdirectories even if this directory is a boilerplate
+            // (in case there are nested boilerplates, though uncommon)
+            scan(entryPath, entryRelativePath, depth + 1);
+        }
+    }
+    scan(baseDir, '', 0);
+    // Sort by relative path for consistent ordering
+    boilerplates.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    return boilerplates;
+}
+/**
+ * Find a boilerplate by matching against a fromPath.
+ *
+ * This function attempts to match a user-provided `fromPath` against
+ * discovered boilerplates. It supports:
+ * 1. Exact match: `fromPath` matches a relative path exactly
+ * 2. Basename match: `fromPath` matches the last segment of a relative path
+ *    (only if unambiguous - i.e., exactly one match)
+ *
+ * @param boilerplates - Array of scanned boilerplates
+ * @param fromPath - The path to match against
+ * @returns The matching boilerplate, or null if no match or ambiguous
+ *
+ * @example
+ * ```typescript
+ * const boilerplates = scanBoilerplatesRecursive('/path/to/repo');
+ *
+ * // Exact match
+ * findBoilerplateByPath(boilerplates, 'default/module');
+ * // Returns the 'default/module' boilerplate
+ *
+ * // Basename match (unambiguous)
+ * findBoilerplateByPath(boilerplates, 'module');
+ * // Returns the 'default/module' boilerplate if it's the only one ending in 'module'
+ *
+ * // Ambiguous basename match
+ * // If both 'default/module' and 'supabase/module' exist:
+ * findBoilerplateByPath(boilerplates, 'module');
+ * // Returns null (ambiguous)
+ * ```
+ */
+function findBoilerplateByPath(boilerplates, fromPath) {
+    // Normalize the fromPath (remove leading/trailing slashes)
+    const normalizedPath = fromPath.replace(/^\/+|\/+$/g, '');
+    // Try exact match first
+    const exactMatch = boilerplates.find((bp) => bp.relativePath === normalizedPath);
+    if (exactMatch) {
+        return exactMatch;
+    }
+    // Try basename match (last segment of path)
+    const basename = path.basename(normalizedPath);
+    const basenameMatches = boilerplates.filter((bp) => path.basename(bp.relativePath) === basename);
+    // Only return if unambiguous (exactly one match)
+    if (basenameMatches.length === 1) {
+        return basenameMatches[0];
+    }
+    return null;
+}
+/**
+ * Find a boilerplate by type within a scanned list.
+ *
+ * @param boilerplates - Array of scanned boilerplates
+ * @param type - The type to find (e.g., 'workspace', 'module')
+ * @returns The matching boilerplate or undefined
+ */
+function findBoilerplateByType(boilerplates, type) {
+    return boilerplates.find((bp) => bp.config.type === type);
+}
+/**
+ * Get all boilerplates of a specific type.
+ *
+ * @param boilerplates - Array of scanned boilerplates
+ * @param type - The type to filter by
+ * @returns Array of matching boilerplates
+ */
+function filterBoilerplatesByType(boilerplates, type) {
+    return boilerplates.filter((bp) => bp.config.type === type);
+}

package/scaffolder/template-scaffolder.d.ts

@@ -2,6 +2,7 @@ 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';
+import { ScannedBoilerplate, ScanBoilerplatesOptions } from './scan-boilerplates';
 /**
  * High-level orchestrator for template scaffolding operations.
  * Combines CacheManager, GitCloner, and Templatizer into a single, easy-to-use API.
@@ -69,17 +70,43 @@ export declare class TemplateScaffolder {
      * Get the underlying Templatizer instance for advanced template operations.
      */
     getTemplatizer(): Templatizer;
+    /**
+     * Scan a template directory recursively for all boilerplates.
+     *
+     * A boilerplate is any directory containing a `.boilerplate.json` file.
+     * This method recursively searches the entire directory tree and returns
+     * all discovered boilerplates with their relative paths.
+     *
+     * This is useful when:
+     * - The user specifies `--dir .` to bypass `.boilerplates.json`
+     * - You want to discover all available boilerplates regardless of nesting
+     * - You need to present a list of available boilerplates to the user
+     *
+     * @param templateDir - The root directory to scan
+     * @param options - Scanning options (maxDepth, skipDirectories)
+     * @returns Array of discovered boilerplates with relative paths
+     *
+     * @example
+     * ```typescript
+     * const scaffolder = new TemplateScaffolder({ toolName: 'my-cli' });
+     * const inspection = scaffolder.inspect({ template: 'org/repo' });
+     * const boilerplates = scaffolder.scanBoilerplates(inspection.templateDir);
+     * // Returns: [{ relativePath: 'default/module', ... }, { relativePath: 'default/workspace', ... }]
+     * ```
+     */
+    scanBoilerplates(templateDir: string, options?: ScanBoilerplatesOptions): ScannedBoilerplate[];
     private inspectLocal;
     private inspectRemote;
     private scaffoldFromLocal;
     private scaffoldFromRemote;
     /**
-     * Resolve the fromPath using .boilerplates.json convention.
+     * Resolve the fromPath using .boilerplates.json convention and recursive scanning.
      *
      * Resolution order:
      * 1. If explicit fromPath is provided and exists, use it directly
      * 2. If useBoilerplatesConfig is true and .boilerplates.json exists with a dir field, prepend it to fromPath
-     * 3. Return the fromPath as-is
+     * 3. Recursively scan for boilerplates and try to match fromPath (exact match, then basename match if unambiguous)
+     * 4. Return the fromPath as-is (will likely fail later if path doesn't exist)
      *
      * @param templateDir - The template repository root directory
      * @param fromPath - The subdirectory path to resolve

package/scaffolder/template-scaffolder.js

@@ -39,6 +39,7 @@ 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");
+const scan_boilerplates_1 = require("./scan-boilerplates");
 /**
  * High-level orchestrator for template scaffolding operations.
  * Combines CacheManager, GitCloner, and Templatizer into a single, easy-to-use API.
@@ -173,6 +174,33 @@ class TemplateScaffolder {
     getTemplatizer() {
         return this.templatizer;
     }
+    /**
+     * Scan a template directory recursively for all boilerplates.
+     *
+     * A boilerplate is any directory containing a `.boilerplate.json` file.
+     * This method recursively searches the entire directory tree and returns
+     * all discovered boilerplates with their relative paths.
+     *
+     * This is useful when:
+     * - The user specifies `--dir .` to bypass `.boilerplates.json`
+     * - You want to discover all available boilerplates regardless of nesting
+     * - You need to present a list of available boilerplates to the user
+     *
+     * @param templateDir - The root directory to scan
+     * @param options - Scanning options (maxDepth, skipDirectories)
+     * @returns Array of discovered boilerplates with relative paths
+     *
+     * @example
+     * ```typescript
+     * const scaffolder = new TemplateScaffolder({ toolName: 'my-cli' });
+     * const inspection = scaffolder.inspect({ template: 'org/repo' });
+     * const boilerplates = scaffolder.scanBoilerplates(inspection.templateDir);
+     * // Returns: [{ relativePath: 'default/module', ... }, { relativePath: 'default/workspace', ... }]
+     * ```
+     */
+    scanBoilerplates(templateDir, options) {
+        return (0, scan_boilerplates_1.scanBoilerplatesRecursive)(templateDir, options);
+    }
     inspectLocal(templateDir, fromPath, useBoilerplatesConfig = true) {
         const { fromPath: resolvedFromPath, resolvedTemplatePath } = this.resolveFromPath(templateDir, fromPath, useBoilerplatesConfig);
         const config = this.readBoilerplateConfig(resolvedTemplatePath);
@@ -282,12 +310,13 @@ class TemplateScaffolder {
         };
     }
     /**
-     * Resolve the fromPath using .boilerplates.json convention.
+     * Resolve the fromPath using .boilerplates.json convention and recursive scanning.
      *
      * Resolution order:
      * 1. If explicit fromPath is provided and exists, use it directly
      * 2. If useBoilerplatesConfig is true and .boilerplates.json exists with a dir field, prepend it to fromPath
-     * 3. Return the fromPath as-is
+     * 3. Recursively scan for boilerplates and try to match fromPath (exact match, then basename match if unambiguous)
+     * 4. Return the fromPath as-is (will likely fail later if path doesn't exist)
      *
      * @param templateDir - The template repository root directory
      * @param fromPath - The subdirectory path to resolve
@@ -322,6 +351,17 @@ class TemplateScaffolder {
                 }
             }
         }
+        // Try recursive scan to find a matching boilerplate
+        // This handles cases like `--dir .` where the user wants to match against
+        // discovered boilerplates (e.g., "module" matching "default/module")
+        const boilerplates = (0, scan_boilerplates_1.scanBoilerplatesRecursive)(templateDir);
+        const match = (0, scan_boilerplates_1.findBoilerplateByPath)(boilerplates, fromPath);
+        if (match) {
+            return {
+                fromPath: match.relativePath,
+                resolvedTemplatePath: match.absolutePath,
+            };
+        }
         return {
             fromPath,
             resolvedTemplatePath: path.join(templateDir, fromPath),