create-gen-app 0.1.7 → 0.2.1

package/README.md

@@ -16,52 +16,31 @@
   <a href="https://www.npmjs.com/package/create-gen-app"><img height="20" src="https://img.shields.io/github/package-json/v/hyperweb-io/dev-utils?filename=packages%2Fcreate-gen-app%2Fpackage.json"></a>
 </p>
 
-A TypeScript-first CLI/library for cloning template repositories, asking the user for variables, and generating a new project with sensible defaults.
+A TypeScript-first library for cloning template repositories, asking the user for variables, and generating a new project with sensible defaults.
 
 ## Features
 
 - Clone any Git repo (or GitHub `org/repo` shorthand) and optionally select a branch + subdirectory
 - Extract template variables from filenames and file contents using the safer `____variable____` convention
 - Merge auto-discovered variables with `.questions.{json,js}` (questions win, including `ignore` patterns)
-- Interactive prompts powered by `inquirerer`, with CLI flag overrides (`--VAR value`) and non-TTY mode for CI
-- Built-in CLI (`create-gen-app` / `cga`) that discovers templates, prompts once, and writes output safely
+- Interactive prompts powered by `inquirerer`, with flexible override mapping (`argv` support) and non-TTY mode for CI
 - License scaffolding: choose from MIT, Apache-2.0, ISC, GPL-3.0, BSD-3-Clause, Unlicense, or MPL-2.0 and generate a populated `LICENSE`
+- Built-in template caching powered by `appstash`, so repeat runs skip `git clone` (configurable via `cache` options)
 
 ## Installation
 
 ```bash
 npm install create-gen-app
-# or for CLI only
-npm install -g create-gen-app
 ```
 
-## CLI Usage
-
-```bash
-# interactively pick a template from launchql/pgpm-boilerplates
-create-gen-app --output ./workspace
-
-# short alias
-cga --template module --branch main --output ./module \
-    --USERFULLNAME "Jane Dev" --USEREMAIL jane@example.com
-
-# point to a different repo/branch/path
-cga --repo github:my-org/my-templates --branch release \
-    --path ./templates --template api --output ./api
-```
-
-Key flags:
-
-- `--repo`, `--branch`, `--path` – choose the Git repo, branch/tag, and subdirectory that contains templates
-- `--template` – folder inside `--path` (auto-prompted if omitted)
-- `--output` – destination directory (defaults to `./<template>`); use `--force` to overwrite
-- `--no-tty` – disable interactive prompts (ideal for CI)
-- `--version`, `--help` – standard metadata
-- Any extra `--VAR value` pairs become variable overrides
+> **Note:** The published package is API-only. An internal CLI harness used for integration testing now lives in `packages/create-gen-app-test/`.
 
 ## Library Usage
 
 ```typescript
+import * as os from "os";
+import * as path from "path";
+
 import { createGen } from "create-gen-app";
 
 await createGen({
@@ -76,9 +55,33 @@ await createGen({
     LICENSE: "MIT",
   },
   noTty: true,
+  cache: {
+    // optional: override tool/baseDir (defaults to pgpm + ~/.pgpm)
+    toolName: "pgpm",
+    baseDir: path.join(os.tmpdir(), "create-gen-cache"),
+  },
 });
 ```
 
+### Template Caching
+
+`create-gen-app` caches repositories under `~/.pgpm/cache/repos/<hash>` by default (using [`appstash`](https://github.com/hyperweb-io/dev-utils/tree/main/packages/appstash)). The first run clones & stores the repo, subsequent runs re-use the cached directory.
+
+- Disable caching with `cache: false` or `cache: { enabled: false }`
+- Override the tool name or base directory with `cache: { toolName, baseDir }`
+- For tests/CI, point `baseDir` to a temporary folder so the suite does not touch the developer’s real home directory:
+
+```ts
+const tempBase = fs.mkdtempSync(path.join(os.tmpdir(), "create-gen-cache-"));
+
+await createGen({
+  ...options,
+  cache: { baseDir: tempBase, toolName: "pgpm-test-suite" },
+});
+```
+
+The cache directory never mutates the template, so reusing the same cached repo across many runs is safe.
+
 ### Template Variables
 
 Variables should be wrapped in four underscores on each side:
@@ -126,14 +129,15 @@ Or `.questions.js` for dynamic logic. Question names can use `____var____` or pl
 
 - `{{YEAR}}`, `{{AUTHOR}}`, `{{EMAIL_LINE}}`
 
-No code changes are needed; the CLI discovers templates at runtime and will warn if a `.questions` option doesn’t have a matching template.
+No code changes are needed; the generator discovers templates at runtime and will warn if a `.questions` option doesn’t have a matching template.
 
 ## API Overview
 
 - `createGen(options)` – full pipeline (clone → extract → prompt → replace)
 - `cloneRepo(url, { branch })` – clone to a temp dir
+- `normalizeCacheOptions(cache)` / `prepareTemplateDirectory(...)` – inspect or reuse cached template repos
 - `extractVariables(dir)` – parse file/folder names + content for variables, load `.questions`
-- `promptUser(extracted, argv, noTty)` – run interactive questions with CLI overrides and alias deduping
+- `promptUser(extracted, argv, noTty)` – run interactive questions with override alias deduping
 - `replaceVariables(templateDir, outputDir, extracted, answers)` – copy files, rename paths, render licenses
 
-See `dev/README.md` for the local development helper script (`pnpm dev`).
+See `packages/create-gen-app-test/dev/README.md` for the local development helper script (`pnpm --filter create-gen-app-test dev`).

package/cache.d.ts

@@ -0,0 +1,13 @@
+import { CacheOptions } from "./types";
+export interface TemplateSource {
+    templateDir: string;
+    cacheUsed: boolean;
+    cleanup: () => void;
+}
+interface PrepareTemplateArgs {
+    templateUrl: string;
+    branch?: string;
+    cache: CacheOptions | false;
+}
+export declare function prepareTemplateDirectory(args: PrepareTemplateArgs): Promise<TemplateSource>;
+export { TemplateCache } from "./template-cache";

package/cache.js

@@ -0,0 +1,76 @@
+"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.TemplateCache = void 0;
+exports.prepareTemplateDirectory = prepareTemplateDirectory;
+const fs = __importStar(require("fs"));
+const clone_1 = require("./clone");
+const template_cache_1 = require("./template-cache");
+async function prepareTemplateDirectory(args) {
+    const { templateUrl, branch, cache } = args;
+    const templateCache = new template_cache_1.TemplateCache(cache);
+    if (!templateCache.isEnabled()) {
+        const tempDir = await (0, clone_1.cloneRepo)(templateUrl, { branch });
+        return {
+            templateDir: tempDir,
+            cacheUsed: false,
+            cleanup: () => cleanupDir(tempDir),
+        };
+    }
+    // Try to get from cache
+    const cachedPath = templateCache.get(templateUrl, branch);
+    if (cachedPath) {
+        return {
+            templateDir: cachedPath,
+            cacheUsed: true,
+            cleanup: () => { },
+        };
+    }
+    // Cache miss or expired - clone and cache
+    const cachePath = templateCache.set(templateUrl, branch);
+    return {
+        templateDir: cachePath,
+        cacheUsed: false,
+        cleanup: () => { },
+    };
+}
+function cleanupDir(dir) {
+    if (fs.existsSync(dir)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+// Re-export TemplateCache for external use
+var template_cache_2 = require("./template-cache");
+Object.defineProperty(exports, "TemplateCache", { enumerable: true, get: function () { return template_cache_2.TemplateCache; } });

package/clone.d.ts

@@ -7,3 +7,9 @@ export interface CloneOptions {
  * @returns Path to the cloned repository
  */
 export declare function cloneRepo(url: string, options?: CloneOptions): Promise<string>;
+/**
+ * Normalize a URL to a git-cloneable format
+ * @param url - Input URL
+ * @returns Normalized git URL
+ */
+export declare function normalizeGitUrl(url: string): string;

package/clone.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cloneRepo = cloneRepo;
+exports.normalizeGitUrl = normalizeGitUrl;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
@@ -44,15 +45,16 @@ const path = __importStar(require("path"));
  * @returns Path to the cloned repository
  */
 async function cloneRepo(url, options = {}) {
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'create-gen-'));
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "create-gen-"));
     const { branch } = options;
     try {
         const gitUrl = normalizeGitUrl(url);
-        const branchArgs = branch ? ` --branch ${branch} --single-branch` : '';
-        (0, child_process_1.execSync)(`git clone${branchArgs} ${gitUrl} ${tempDir}`, {
-            stdio: 'inherit'
+        const branchArgs = branch ? ` --branch ${branch} --single-branch` : "";
+        const depthArgs = " --depth 1"; // use shallow clone for speed; remove if future features need full history
+        (0, child_process_1.execSync)(`git clone${branchArgs}${depthArgs} ${gitUrl} ${tempDir}`, {
+            stdio: "inherit",
         });
-        const gitDir = path.join(tempDir, '.git');
+        const gitDir = path.join(tempDir, ".git");
         if (fs.existsSync(gitDir)) {
             fs.rmSync(gitDir, { recursive: true, force: true });
         }
@@ -72,7 +74,9 @@ async function cloneRepo(url, options = {}) {
  * @returns Normalized git URL
  */
 function normalizeGitUrl(url) {
-    if (url.startsWith('git@') || url.startsWith('https://') || url.startsWith('http://')) {
+    if (url.startsWith("git@") ||
+        url.startsWith("https://") ||
+        url.startsWith("http://")) {
         return url;
     }
     if (/^[\w-]+\/[\w-]+$/.test(url)) {

package/esm/cache.js

@@ -0,0 +1,38 @@
+import * as fs from "fs";
+import { cloneRepo } from "./clone";
+import { TemplateCache } from "./template-cache";
+export async function prepareTemplateDirectory(args) {
+    const { templateUrl, branch, cache } = args;
+    const templateCache = new TemplateCache(cache);
+    if (!templateCache.isEnabled()) {
+        const tempDir = await cloneRepo(templateUrl, { branch });
+        return {
+            templateDir: tempDir,
+            cacheUsed: false,
+            cleanup: () => cleanupDir(tempDir),
+        };
+    }
+    // Try to get from cache
+    const cachedPath = templateCache.get(templateUrl, branch);
+    if (cachedPath) {
+        return {
+            templateDir: cachedPath,
+            cacheUsed: true,
+            cleanup: () => { },
+        };
+    }
+    // Cache miss or expired - clone and cache
+    const cachePath = templateCache.set(templateUrl, branch);
+    return {
+        templateDir: cachePath,
+        cacheUsed: false,
+        cleanup: () => { },
+    };
+}
+function cleanupDir(dir) {
+    if (fs.existsSync(dir)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+// Re-export TemplateCache for external use
+export { TemplateCache } from "./template-cache";

package/esm/clone.js

@@ -1,22 +1,23 @@
-import { execSync } from 'child_process';
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
+import { execSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
 /**
  * Clone a repository to a temporary directory
  * @param url - Repository URL (GitHub or any git URL)
  * @returns Path to the cloned repository
  */
 export async function cloneRepo(url, options = {}) {
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'create-gen-'));
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "create-gen-"));
     const { branch } = options;
     try {
         const gitUrl = normalizeGitUrl(url);
-        const branchArgs = branch ? ` --branch ${branch} --single-branch` : '';
-        execSync(`git clone${branchArgs} ${gitUrl} ${tempDir}`, {
-            stdio: 'inherit'
+        const branchArgs = branch ? ` --branch ${branch} --single-branch` : "";
+        const depthArgs = " --depth 1"; // use shallow clone for speed; remove if future features need full history
+        execSync(`git clone${branchArgs}${depthArgs} ${gitUrl} ${tempDir}`, {
+            stdio: "inherit",
         });
-        const gitDir = path.join(tempDir, '.git');
+        const gitDir = path.join(tempDir, ".git");
         if (fs.existsSync(gitDir)) {
             fs.rmSync(gitDir, { recursive: true, force: true });
         }
@@ -35,8 +36,10 @@ export async function cloneRepo(url, options = {}) {
  * @param url - Input URL
  * @returns Normalized git URL
  */
-function normalizeGitUrl(url) {
-    if (url.startsWith('git@') || url.startsWith('https://') || url.startsWith('http://')) {
+export function normalizeGitUrl(url) {
+    if (url.startsWith("git@") ||
+        url.startsWith("https://") ||
+        url.startsWith("http://")) {
         return url;
     }
     if (/^[\w-]+\/[\w-]+$/.test(url)) {

package/esm/index.js

@@ -1,48 +1,61 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import { cloneRepo } from './clone';
-import { extractVariables } from './extract';
-import { promptUser } from './prompt';
-import { replaceVariables } from './replace';
-export * from './clone';
-export * from './extract';
-export * from './prompt';
-export * from './replace';
-export * from './types';
+import * as fs from "fs";
+import * as path from "path";
+import { prepareTemplateDirectory } from "./cache";
+import { extractVariables } from "./extract";
+import { promptUser } from "./prompt";
+import { replaceVariables } from "./replace";
+export * from "./cache";
+export * from "./clone";
+export * from "./extract";
+export * from "./prompt";
+export * from "./replace";
+export * from "./types";
+export * from "./template-cache";
 /**
  * Create a new project from a template repository
  * @param options - Options for creating the project
  * @returns Path to the generated project
  */
 export async function createGen(options) {
-    const { templateUrl, outputDir, argv = {}, noTty = false, fromBranch, fromPath } = options;
-    console.log(`Cloning template from ${templateUrl}...`);
-    const tempDir = await cloneRepo(templateUrl, { branch: fromBranch });
-    const normalizedPath = fromPath ? path.normalize(fromPath) : '.';
-    const templateRoot = normalizedPath && normalizedPath !== '.'
-        ? path.join(tempDir, normalizedPath)
-        : tempDir;
+    const { templateUrl, outputDir, argv = {}, noTty = false, fromBranch, fromPath, cache, } = options;
+    console.log(`Preparing template from ${templateUrl}...`);
+    const templateSource = await prepareTemplateDirectory({
+        templateUrl,
+        branch: fromBranch,
+        cache,
+    });
+    const cacheEnabled = cache !== false && (cache?.enabled !== false);
+    if (cacheEnabled) {
+        console.log(templateSource.cacheUsed
+            ? "Using cached repository"
+            : "Caching repository for future runs...");
+    }
+    else {
+        console.log("Cloning repository without cache...");
+    }
+    const normalizedPath = fromPath ? path.normalize(fromPath) : ".";
+    const templateRoot = normalizedPath && normalizedPath !== "."
+        ? path.join(templateSource.templateDir, normalizedPath)
+        : templateSource.templateDir;
     try {
         if (!fs.existsSync(templateRoot)) {
             throw new Error(`Template path "${fromPath}" does not exist in repository ${templateUrl}.`);
         }
-        console.log('Extracting template variables...');
+        console.log("Extracting template variables...");
         const extractedVariables = await extractVariables(templateRoot);
         console.log(`Found ${extractedVariables.fileReplacers.length} file replacers`);
         console.log(`Found ${extractedVariables.contentReplacers.length} content replacers`);
         if (extractedVariables.projectQuestions) {
             console.log(`Found ${extractedVariables.projectQuestions.questions.length} project questions`);
         }
-        console.log('Prompting for variable values...');
+        console.log("Prompting for variable values...");
         const answers = await promptUser(extractedVariables, argv, noTty);
         console.log(`Generating project in ${outputDir}...`);
         await replaceVariables(templateRoot, outputDir, extractedVariables, answers);
-        console.log('Project created successfully!');
+        console.log("Project created successfully!");
         return outputDir;
     }
     finally {
-        if (fs.existsSync(tempDir)) {
-            fs.rmSync(tempDir, { recursive: true, force: true });
-        }
+        templateSource.cleanup();
     }
 }

package/esm/replace.js

@@ -53,7 +53,7 @@ async function walkAndReplace(sourceDir, destDir, extractedVariables, answers, s
     }
 }
 async function ensureLicenseFile(outputDir, answers) {
-    const licenseValue = answers?.LICENSE;
+    const licenseValue = getAnswer(answers, ["LICENSE", "license"]);
     if (typeof licenseValue !== 'string' || licenseValue.trim() === '') {
         return;
     }
@@ -62,12 +62,17 @@ async function ensureLicenseFile(outputDir, answers) {
         console.warn(`[create-gen-app] License "${selectedLicense}" is not supported by the built-in templates. Leaving template LICENSE file as-is.`);
         return;
     }
-    const author = answers?.USERFULLNAME ??
-        answers?.AUTHOR ??
-        answers?.AUTHORFULLNAME ??
-        answers?.USERNAME ??
-        'Unknown Author';
-    const email = answers?.USEREMAIL ?? answers?.EMAIL ?? '';
+    const author = getAnswer(answers, [
+        "USERFULLNAME",
+        "AUTHOR",
+        "AUTHORFULLNAME",
+        "USERNAME",
+        "fullName",
+        "author",
+        "authorFullName",
+        "userName",
+    ]) ?? "Unknown Author";
+    const email = getAnswer(answers, ["USEREMAIL", "EMAIL", "email", "userEmail"]) ?? "";
     const content = renderLicense(selectedLicense, {
         author: String(author),
         email: String(email || ''),
@@ -80,6 +85,15 @@ async function ensureLicenseFile(outputDir, answers) {
     fs.writeFileSync(licensePath, content.trimEnd() + '\n', 'utf8');
     console.log(`[create-gen-app] LICENSE updated with ${selectedLicense} template.`);
 }
+function getAnswer(answers, keys) {
+    for (const key of keys) {
+        const value = answers?.[key];
+        if (typeof value === "string" && value.trim() !== "") {
+            return value;
+        }
+    }
+    return undefined;
+}
 /**
  * Replace variables in a file using streams
  * @param sourcePath - Source file path