create-gen-app 0.2.1 → 0.3.0

package/README.md

@@ -22,10 +22,10 @@ A TypeScript-first library for cloning template repositories, asking the user fo
 
 - 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)
+- Merge auto-discovered variables with `.questions.{json,js}` (questions win)
 - 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)
+- Built-in template caching powered by `appstash`, so repeat runs skip `git clone` (configurable via `cache` options; TTL is opt-in)
 
 ## Installation
 
@@ -37,51 +37,66 @@ npm install create-gen-app
 
 ## Library Usage
 
-```typescript
-import * as os from "os";
-import * as path from "path";
-
-import { createGen } from "create-gen-app";
-
-await createGen({
-  templateUrl: "https://github.com/user/template-repo",
-  fromBranch: "main",
-  fromPath: "templates/module",
-  outputDir: "./my-new-project",
-  argv: {
-    USERFULLNAME: "Jane Dev",
-    USEREMAIL: "jane@example.com",
-    MODULENAME: "awesome-module",
-    LICENSE: "MIT",
-  },
-  noTty: true,
-  cache: {
-    // optional: override tool/baseDir (defaults to pgpm + ~/.pgpm)
-    toolName: "pgpm",
-    baseDir: path.join(os.tmpdir(), "create-gen-cache"),
-  },
-});
-```
+`create-gen-app` provides a modular set of classes to handle template cloning, caching, and processing.
 
-### Template Caching
+### Core Components
 
-`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.
+- **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.
 
-- 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:
+### Example: Orchestration
 
-```ts
-const tempBase = fs.mkdtempSync(path.join(os.tmpdir(), "create-gen-cache-"));
+Here is how you can combine these components to create a full CLI pipeline (similar to `create-gen-app-test`):
 
-await createGen({
-  ...options,
-  cache: { baseDir: tempBase, toolName: "pgpm-test-suite" },
-});
+```typescript
+import * as path from "path";
+import { CacheManager, GitCloner, Templatizer } from "create-gen-app";
+
+async function main() {
+  const repoUrl = "https://github.com/user/template-repo";
+  const outputDir = "./my-new-project";
+
+  // 1. Initialize components
+  const cacheManager = new CacheManager({
+    toolName: "my-cli", // ~/.my-cli/cache
+    // ttl is optional; omit to keep cache forever, or set (e.g., 1 week) to enable expiration
+    // ttl: 604800000,
+  });
+  const gitCloner = new GitCloner();
+  const templatizer = new Templatizer();
+
+  // 2. Resolve template path (Cache or Clone)
+  const normalizedUrl = gitCloner.normalizeUrl(repoUrl);
+  const cacheKey = cacheManager.createKey(normalizedUrl);
+  
+  // Check cache
+  let templateDir = cacheManager.get(cacheKey);
+  const isExpired = cacheManager.checkExpiration(cacheKey);
+
+  if (!templateDir || isExpired) {
+    console.log("Cloning template...");
+    if (isExpired) cacheManager.clear(cacheKey);
+    
+    // Clone to a temporary location managed by CacheManager
+    const tempDest = path.join(cacheManager.getReposDir(), cacheKey);
+    await gitCloner.clone(normalizedUrl, tempDest, { depth: 1 });
+    
+    // Register and update cache
+    cacheManager.set(cacheKey, tempDest);
+    templateDir = tempDest;
+  }
+
+  // 3. Process Template
+  await templatizer.process(templateDir, outputDir, {
+    argv: {
+      PROJECT_NAME: "my-app",
+      LICENSE: "MIT"
+    }
+  });
+}
 ```
 
-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:
@@ -97,13 +112,12 @@ export const projectName = "____projectName____";
 export const author = "____fullName____";
 ```
 
-### Custom Questions & Ignore Rules
+### Custom Questions
 
 Create a `.questions.json`:
 
 ```json
 {
-  "ignore": ["__tests__", "docs/drafts"],
   "questions": [
     {
       "name": "____fullName____",
@@ -133,11 +147,21 @@ No code changes are needed; the generator discovers templates at runtime and wil
 
 ## 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 override alias deduping
-- `replaceVariables(templateDir, outputDir, extracted, answers)` – copy files, rename paths, render licenses
+### CacheManager
+- `new CacheManager(config)`: Initialize with `toolName` and optional `ttl`.
+- `get(key)`: Get path to cached repo if exists.
+- `set(key, path)`: Register a path in the cache.
+- `checkExpiration(key)`: Check if a cache entry is expired.
+- `clear(key)`: Remove a specific cache entry.
+- `clearAll()`: Clear all cached repos.
+- When `ttl` is `undefined`, cache entries never expire. Provide a TTL (ms) only when you want automatic invalidation.
+- Advanced: if you already own an appstash instance, pass `dirs` to reuse it instead of letting CacheManager create its own.
+
+### GitCloner
+- `clone(url, dest, options)`: Clone a repo to a destination.
+- `normalizeUrl(url)`: Normalize a git URL for consistency.
+
+### Templatizer
+- `process(templateDir, outputDir, options)`: Run the full template generation pipeline (extract -> prompt -> replace).
 
-See `packages/create-gen-app-test/dev/README.md` for the local development helper script (`pnpm --filter create-gen-app-test dev`).
+See `packages/create-gen-app-test` for a complete reference implementation.

package/cache/cache-manager.d.ts

@@ -0,0 +1,60 @@
+import { AppStashResult } from 'appstash';
+import { CacheManagerConfig, CacheMetadata, CacheEntryInfo } from './types';
+export declare class CacheManager {
+    private config;
+    private dirs;
+    private reposDir;
+    private metadataDir;
+    constructor(config: CacheManagerConfig);
+    /**
+     * Public accessor for the repos cache directory path.
+     */
+    getReposDir(): string;
+    /**
+     * Public accessor for the metadata cache directory path.
+     */
+    getMetadataDir(): string;
+    /**
+     * Public accessor for resolved appstash directories.
+     */
+    getAppstashDirs(): AppStashResult;
+    /**
+     * Get cached directory path if exists and not expired
+     * Returns null if not cached or expired
+     */
+    get(key: string): string | null;
+    /**
+     * Store directory in cache with metadata
+     * Does NOT perform cloning - just registers the directory
+     */
+    set(key: string, sourcePath: string): string;
+    /**
+     * Check if cache entry is expired based on TTL
+     * Returns null if no metadata or not expired, returns metadata if expired
+     */
+    checkExpiration(key: string): CacheMetadata | null;
+    /**
+     * Clear specific cache entry
+     */
+    clear(key: string): void;
+    /**
+     * Clear all cache entries
+     */
+    clearAll(): void;
+    /**
+     * List all cache entries with expiration status
+     */
+    listAll(): CacheEntryInfo[];
+    /**
+     * Get metadata for a cache entry
+     */
+    getMetadata(key: string): CacheMetadata | null;
+    /**
+     * Create a cache key from identifier (e.g., git URL + branch)
+     */
+    createKey(identifier: string, variant?: string): string;
+    private ensureDirectories;
+    private isExpired;
+    private getCachePath;
+    private getMetadataPath;
+}

package/cache/cache-manager.js

@@ -0,0 +1,228 @@
+"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.CacheManager = void 0;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const appstash_1 = require("appstash");
+class CacheManager {
+    config;
+    dirs;
+    reposDir;
+    metadataDir;
+    constructor(config) {
+        // Validate required toolName
+        if (!config.toolName) {
+            throw new Error('CacheManager requires toolName parameter');
+        }
+        this.config = {
+            toolName: config.toolName,
+            baseDir: config.baseDir,
+            ttl: config.ttl,
+            dirs: config.dirs,
+        };
+        this.dirs =
+            config.dirs ??
+                (0, appstash_1.appstash)(this.config.toolName, {
+                    ensure: true,
+                    baseDir: this.config.baseDir,
+                });
+        this.reposDir = (0, appstash_1.resolve)(this.dirs, 'cache', 'repos');
+        this.metadataDir = (0, appstash_1.resolve)(this.dirs, 'cache', 'metadata');
+        this.ensureDirectories();
+    }
+    /**
+     * Public accessor for the repos cache directory path.
+     */
+    getReposDir() {
+        return this.reposDir;
+    }
+    /**
+     * Public accessor for the metadata cache directory path.
+     */
+    getMetadataDir() {
+        return this.metadataDir;
+    }
+    /**
+     * Public accessor for resolved appstash directories.
+     */
+    getAppstashDirs() {
+        return this.dirs;
+    }
+    /**
+     * Get cached directory path if exists and not expired
+     * Returns null if not cached or expired
+     */
+    get(key) {
+        const cachePath = this.getCachePath(key);
+        if (!fs.existsSync(cachePath)) {
+            return null;
+        }
+        // Check expiration - if expired, return null
+        const expired = this.checkExpiration(key);
+        if (expired) {
+            return null;
+        }
+        return cachePath;
+    }
+    /**
+     * Store directory in cache with metadata
+     * Does NOT perform cloning - just registers the directory
+     */
+    set(key, sourcePath) {
+        const cachePath = this.getCachePath(key);
+        // Write metadata with current timestamp
+        const metadata = {
+            key,
+            identifier: sourcePath,
+            lastUpdated: Date.now(),
+        };
+        fs.writeFileSync(this.getMetadataPath(key), JSON.stringify(metadata, null, 2));
+        return cachePath;
+    }
+    /**
+     * Check if cache entry is expired based on TTL
+     * Returns null if no metadata or not expired, returns metadata if expired
+     */
+    checkExpiration(key) {
+        const metadata = this.getMetadata(key);
+        if (!metadata) {
+            return null;
+        }
+        if (this.isExpired(metadata)) {
+            return metadata;
+        }
+        return null;
+    }
+    /**
+     * Clear specific cache entry
+     */
+    clear(key) {
+        const cachePath = this.getCachePath(key);
+        const metadataPath = this.getMetadataPath(key);
+        if (fs.existsSync(cachePath)) {
+            fs.rmSync(cachePath, { recursive: true, force: true });
+        }
+        if (fs.existsSync(metadataPath)) {
+            fs.rmSync(metadataPath, { force: true });
+        }
+    }
+    /**
+     * Clear all cache entries
+     */
+    clearAll() {
+        if (fs.existsSync(this.reposDir)) {
+            fs.rmSync(this.reposDir, { recursive: true, force: true });
+            fs.mkdirSync(this.reposDir, { recursive: true });
+        }
+        if (fs.existsSync(this.metadataDir)) {
+            fs.rmSync(this.metadataDir, { recursive: true, force: true });
+            fs.mkdirSync(this.metadataDir, { recursive: true });
+        }
+    }
+    /**
+     * List all cache entries with expiration status
+     */
+    listAll() {
+        if (!fs.existsSync(this.metadataDir)) {
+            return [];
+        }
+        const results = [];
+        const files = fs.readdirSync(this.metadataDir);
+        for (const file of files) {
+            if (!file.endsWith('.json')) {
+                continue;
+            }
+            const metadataPath = path.join(this.metadataDir, file);
+            try {
+                const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+                results.push({
+                    ...metadata,
+                    path: this.getCachePath(metadata.key),
+                    expired: this.isExpired(metadata),
+                });
+            }
+            catch {
+                // Skip corrupted metadata
+            }
+        }
+        return results;
+    }
+    /**
+     * Get metadata for a cache entry
+     */
+    getMetadata(key) {
+        const metadataPath = this.getMetadataPath(key);
+        if (!fs.existsSync(metadataPath)) {
+            return null;
+        }
+        try {
+            return JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Create a cache key from identifier (e.g., git URL + branch)
+     */
+    createKey(identifier, variant) {
+        const input = variant ? `${identifier}#${variant}` : identifier;
+        return crypto.createHash('md5').update(input).digest('hex');
+    }
+    ensureDirectories() {
+        if (!fs.existsSync(this.reposDir)) {
+            fs.mkdirSync(this.reposDir, { recursive: true });
+        }
+        if (!fs.existsSync(this.metadataDir)) {
+            fs.mkdirSync(this.metadataDir, { recursive: true });
+        }
+    }
+    isExpired(metadata) {
+        if (!this.config.ttl) {
+            return false;
+        }
+        const age = Date.now() - metadata.lastUpdated;
+        return age > this.config.ttl;
+    }
+    getCachePath(key) {
+        return path.join(this.reposDir, key);
+    }
+    getMetadataPath(key) {
+        return path.join(this.metadataDir, `${key}.json`);
+    }
+}
+exports.CacheManager = CacheManager;

package/cache/types.d.ts

@@ -0,0 +1,22 @@
+import { AppStashResult } from 'appstash';
+export interface CacheManagerConfig {
+    toolName: string;
+    baseDir?: string;
+    ttl?: number;
+    /**
+     * Optional pre-resolved appstash directories owned by the caller.
+     * When provided, CacheManager will use these instead of creating its own.
+     */
+    dirs?: AppStashResult;
+}
+export interface CacheMetadata {
+    key: string;
+    identifier: string;
+    variant?: string;
+    lastUpdated: number;
+    source?: string;
+}
+export interface CacheEntryInfo extends CacheMetadata {
+    path: string;
+    expired: boolean;
+}

package/cache/types.js

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

package/esm/cache/cache-manager.js

@@ -0,0 +1,191 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { appstash, resolve as resolveAppstash } from 'appstash';
+export class CacheManager {
+    config;
+    dirs;
+    reposDir;
+    metadataDir;
+    constructor(config) {
+        // Validate required toolName
+        if (!config.toolName) {
+            throw new Error('CacheManager requires toolName parameter');
+        }
+        this.config = {
+            toolName: config.toolName,
+            baseDir: config.baseDir,
+            ttl: config.ttl,
+            dirs: config.dirs,
+        };
+        this.dirs =
+            config.dirs ??
+                appstash(this.config.toolName, {
+                    ensure: true,
+                    baseDir: this.config.baseDir,
+                });
+        this.reposDir = resolveAppstash(this.dirs, 'cache', 'repos');
+        this.metadataDir = resolveAppstash(this.dirs, 'cache', 'metadata');
+        this.ensureDirectories();
+    }
+    /**
+     * Public accessor for the repos cache directory path.
+     */
+    getReposDir() {
+        return this.reposDir;
+    }
+    /**
+     * Public accessor for the metadata cache directory path.
+     */
+    getMetadataDir() {
+        return this.metadataDir;
+    }
+    /**
+     * Public accessor for resolved appstash directories.
+     */
+    getAppstashDirs() {
+        return this.dirs;
+    }
+    /**
+     * Get cached directory path if exists and not expired
+     * Returns null if not cached or expired
+     */
+    get(key) {
+        const cachePath = this.getCachePath(key);
+        if (!fs.existsSync(cachePath)) {
+            return null;
+        }
+        // Check expiration - if expired, return null
+        const expired = this.checkExpiration(key);
+        if (expired) {
+            return null;
+        }
+        return cachePath;
+    }
+    /**
+     * Store directory in cache with metadata
+     * Does NOT perform cloning - just registers the directory
+     */
+    set(key, sourcePath) {
+        const cachePath = this.getCachePath(key);
+        // Write metadata with current timestamp
+        const metadata = {
+            key,
+            identifier: sourcePath,
+            lastUpdated: Date.now(),
+        };
+        fs.writeFileSync(this.getMetadataPath(key), JSON.stringify(metadata, null, 2));
+        return cachePath;
+    }
+    /**
+     * Check if cache entry is expired based on TTL
+     * Returns null if no metadata or not expired, returns metadata if expired
+     */
+    checkExpiration(key) {
+        const metadata = this.getMetadata(key);
+        if (!metadata) {
+            return null;
+        }
+        if (this.isExpired(metadata)) {
+            return metadata;
+        }
+        return null;
+    }
+    /**
+     * Clear specific cache entry
+     */
+    clear(key) {
+        const cachePath = this.getCachePath(key);
+        const metadataPath = this.getMetadataPath(key);
+        if (fs.existsSync(cachePath)) {
+            fs.rmSync(cachePath, { recursive: true, force: true });
+        }
+        if (fs.existsSync(metadataPath)) {
+            fs.rmSync(metadataPath, { force: true });
+        }
+    }
+    /**
+     * Clear all cache entries
+     */
+    clearAll() {
+        if (fs.existsSync(this.reposDir)) {
+            fs.rmSync(this.reposDir, { recursive: true, force: true });
+            fs.mkdirSync(this.reposDir, { recursive: true });
+        }
+        if (fs.existsSync(this.metadataDir)) {
+            fs.rmSync(this.metadataDir, { recursive: true, force: true });
+            fs.mkdirSync(this.metadataDir, { recursive: true });
+        }
+    }
+    /**
+     * List all cache entries with expiration status
+     */
+    listAll() {
+        if (!fs.existsSync(this.metadataDir)) {
+            return [];
+        }
+        const results = [];
+        const files = fs.readdirSync(this.metadataDir);
+        for (const file of files) {
+            if (!file.endsWith('.json')) {
+                continue;
+            }
+            const metadataPath = path.join(this.metadataDir, file);
+            try {
+                const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+                results.push({
+                    ...metadata,
+                    path: this.getCachePath(metadata.key),
+                    expired: this.isExpired(metadata),
+                });
+            }
+            catch {
+                // Skip corrupted metadata
+            }
+        }
+        return results;
+    }
+    /**
+     * Get metadata for a cache entry
+     */
+    getMetadata(key) {
+        const metadataPath = this.getMetadataPath(key);
+        if (!fs.existsSync(metadataPath)) {
+            return null;
+        }
+        try {
+            return JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Create a cache key from identifier (e.g., git URL + branch)
+     */
+    createKey(identifier, variant) {
+        const input = variant ? `${identifier}#${variant}` : identifier;
+        return crypto.createHash('md5').update(input).digest('hex');
+    }
+    ensureDirectories() {
+        if (!fs.existsSync(this.reposDir)) {
+            fs.mkdirSync(this.reposDir, { recursive: true });
+        }
+        if (!fs.existsSync(this.metadataDir)) {
+            fs.mkdirSync(this.metadataDir, { recursive: true });
+        }
+    }
+    isExpired(metadata) {
+        if (!this.config.ttl) {
+            return false;
+        }
+        const age = Date.now() - metadata.lastUpdated;
+        return age > this.config.ttl;
+    }
+    getCachePath(key) {
+        return path.join(this.reposDir, key);
+    }
+    getMetadataPath(key) {
+        return path.join(this.metadataDir, `${key}.json`);
+    }
+}

package/esm/cache/types.js

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