genomic 4.0.2 → 5.0.0

package/scaffolder/template-scaffolder.js

@@ -0,0 +1,347 @@
+"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);
+        const useBoilerplatesConfig = options.useBoilerplatesConfig ?? true;
+        if (this.isLocalPath(resolvedTemplate) && fs.existsSync(resolvedTemplate)) {
+            return this.inspectLocal(resolvedTemplate, options.fromPath, useBoilerplatesConfig);
+        }
+        return this.inspectRemote(resolvedTemplate, branch, options.fromPath, useBoilerplatesConfig);
+    }
+    /**
+     * 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, useBoilerplatesConfig = true) {
+        const { fromPath: resolvedFromPath, resolvedTemplatePath } = this.resolveFromPath(templateDir, fromPath, useBoilerplatesConfig);
+        const config = this.readBoilerplateConfig(resolvedTemplatePath);
+        return {
+            templateDir,
+            resolvedFromPath,
+            resolvedTemplatePath,
+            cacheUsed: false,
+            cacheExpired: false,
+            config,
+        };
+    }
+    inspectRemote(templateUrl, branch, fromPath, useBoilerplatesConfig = true) {
+        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, useBoilerplatesConfig);
+        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, options.useBoilerplatesConfig ?? true);
+        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, options.useBoilerplatesConfig ?? true);
+        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 useBoilerplatesConfig is true and .boilerplates.json exists with a dir field, prepend it to fromPath
+     * 3. Return the fromPath as-is
+     *
+     * @param templateDir - The template repository root directory
+     * @param fromPath - The subdirectory path to resolve
+     * @param useBoilerplatesConfig - Whether to use .boilerplates.json for fallback resolution (default: true)
+     */
+    resolveFromPath(templateDir, fromPath, useBoilerplatesConfig = true) {
+        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,
+            };
+        }
+        // Only check .boilerplates.json if useBoilerplatesConfig is true
+        if (useBoilerplatesConfig) {
+            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,191 @@
+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;
+    /**
+     * Whether to use .boilerplates.json for path resolution fallback.
+     * When true (default), if fromPath doesn't exist directly, the resolver
+     * will check .boilerplates.json for a base directory to prepend.
+     * When false, .boilerplates.json is ignored and fromPath is used as-is.
+     * @default true
+     */
+    useBoilerplatesConfig?: boolean;
+    /**
+     * 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 Prompter 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;
+    /**
+     * Whether to use .boilerplates.json for path resolution fallback.
+     * When true (default), if fromPath doesn't exist directly, the resolver
+     * will check .boilerplates.json for a base directory to prepend.
+     * When false, .boilerplates.json is ignored and fromPath is used as-is.
+     * @default true
+     */
+    useBoilerplatesConfig?: boolean;
+}
+/**
+ * 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/extract.d.ts

@@ -0,0 +1,7 @@
+import { ExtractedVariables } from '../types';
+/**
+ * Extract all variables from a template directory
+ * @param templateDir - Path to the template directory
+ * @returns Extracted variables including file replacers, content replacers, and project questions
+ */
+export declare function extractVariables(templateDir: string): Promise<ExtractedVariables>;