feat(create-gen-app): add template caching with appstash

Add built-in template caching to avoid repeated git clones from GitHub.
Templates are cached locally using appstash, significantly speeding up
subsequent runs when using the same repository and branch.

Changes:
- Add cache.ts helper with getCachedRepo/cloneToCache/prepareTemplateDirectory
- Extend CreateGenOptions with optional cache configuration (toolName, baseDir, enabled)
- Update cloneRepo to support cache-aware cloning
- Integrate caching into createGen pipeline with cache-first logic
- Add cache.test.ts with isolated temp baseDir to avoid touching user's home
- Update README with caching documentation and usage examples
- Add appstash dependency to package.json

The cache is enabled by default and stores repositories under ~/.<toolName>/cache/repos.
Tests use temporary directories (via baseDir) to prevent pollution of the
developer's home directory, following the pattern from appstash tests.

Author: sdqede

packages/create-gen-app/README.md

@@ -25,6 +25,7 @@ A TypeScript-first library for cloning template repositories, asking the user fo
 - Merge auto-discovered variables with `.questions.{json,js}` (questions win, including `ignore` patterns)
 - 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
 
@@ -37,6 +38,9 @@ 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({
@@ -51,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:
@@ -107,6 +135,7 @@ No code changes are needed; the generator discovers templates at runtime and wil
 
 - `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

packages/create-gen-app/__tests__/cache.test.ts

@@ -0,0 +1,88 @@
+import * as childProcess from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import { createGen } from "../src";
+import {
+  TEST_BRANCH,
+  TEST_REPO,
+  TEST_TEMPLATE,
+  buildAnswers,
+  cleanupWorkspace,
+  createTempWorkspace,
+} from "../test-utils/integration-helpers";
+
+jest.setTimeout(180_000);
+
+describe("template caching (appstash)", () => {
+  let tempBaseDir: string;
+  const cacheTool = `pgpm-cache-${Date.now()}`;
+
+  beforeEach(() => {
+    tempBaseDir = fs.mkdtempSync(path.join(os.tmpdir(), "create-gen-cache-"));
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(tempBaseDir)) {
+      fs.rmSync(tempBaseDir, { recursive: true, force: true });
+    }
+  });
+
+  it("reuses cached repositories across runs when cache is enabled", async () => {
+    const cacheOptions = {
+      toolName: cacheTool,
+      baseDir: tempBaseDir,
+      enabled: true,
+    };
+
+    const firstWorkspace = createTempWorkspace("cache-first");
+    const firstAnswers = buildAnswers("cache-first");
+
+    try {
+      await createGen({
+        templateUrl: TEST_REPO,
+        fromBranch: TEST_BRANCH,
+        fromPath: TEST_TEMPLATE,
+        outputDir: firstWorkspace.outputDir,
+        argv: firstAnswers,
+        noTty: true,
+        cache: cacheOptions,
+      });
+    } finally {
+      cleanupWorkspace(firstWorkspace);
+    }
+
+    const repoCacheDir = path.join(tempBaseDir, `.${cacheTool}`, "cache", "repos");
+    expect(fs.existsSync(repoCacheDir)).toBe(true);
+    const cachedEntries = fs.readdirSync(repoCacheDir);
+    expect(cachedEntries.length).toBeGreaterThan(0);
+
+    const secondWorkspace = createTempWorkspace("cache-second");
+    const secondAnswers = buildAnswers("cache-second");
+    const execSpy = jest.spyOn(childProcess, "execSync");
+
+    try {
+      await createGen({
+        templateUrl: TEST_REPO,
+        fromBranch: TEST_BRANCH,
+        fromPath: TEST_TEMPLATE,
+        outputDir: secondWorkspace.outputDir,
+        argv: secondAnswers,
+        noTty: true,
+        cache: cacheOptions,
+      });
+
+      const cloneCalls = execSpy.mock.calls.filter(([command]) => {
+        return typeof command === "string" && command.includes("git clone");
+      });
+
+      expect(cloneCalls.length).toBe(0);
+    } finally {
+      execSpy.mockRestore();
+      cleanupWorkspace(secondWorkspace);
+    }
+  });
+});
+
+

packages/create-gen-app/package.json

@@ -28,6 +28,7 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
+    "appstash": "workspace:*",
     "inquirerer": "workspace:*"
   },
   "devDependencies": {

packages/create-gen-app/src/cache.ts

@@ -0,0 +1,130 @@
+import { execSync } from "child_process";
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+
+import { appstash, resolve as resolveAppstash } from "appstash";
+
+import { CacheOptions } from "./types";
+import { cloneRepo, normalizeGitUrl } from "./clone";
+
+const DEFAULT_TOOL = "pgpm";
+
+interface NormalizedCacheOptions {
+  enabled: boolean;
+  toolName: string;
+  baseDir?: string;
+}
+
+export interface TemplateSource {
+  templateDir: string;
+  cacheUsed: boolean;
+  cleanup: () => void;
+}
+
+interface PrepareTemplateArgs {
+  templateUrl: string;
+  branch?: string;
+  cache: NormalizedCacheOptions;
+}
+
+export function normalizeCacheOptions(cache?: CacheOptions | false): NormalizedCacheOptions {
+  if (cache === false) {
+    return {
+      enabled: false,
+      toolName: DEFAULT_TOOL,
+    };
+  }
+
+  const { enabled, toolName, baseDir } = cache ?? {};
+
+  return {
+    enabled: enabled !== false,
+    toolName: toolName ?? DEFAULT_TOOL,
+    baseDir,
+  };
+}
+
+export async function prepareTemplateDirectory(args: PrepareTemplateArgs): Promise<TemplateSource> {
+  const { templateUrl, branch, cache } = args;
+
+  if (!cache.enabled) {
+    const tempDir = await cloneRepo(templateUrl, { branch });
+    return {
+      templateDir: tempDir,
+      cacheUsed: false,
+      cleanup: () => cleanupDir(tempDir),
+    };
+  }
+
+  const { cachePath } = ensureCachePath(templateUrl, branch, cache);
+
+  if (fs.existsSync(cachePath)) {
+    return {
+      templateDir: cachePath,
+      cacheUsed: true,
+      cleanup: () => {},
+    };
+  }
+
+  cloneInto(templateUrl, cachePath, branch);
+
+  return {
+    templateDir: cachePath,
+    cacheUsed: false,
+    cleanup: () => {},
+  };
+}
+
+function ensureCachePath(
+  templateUrl: string,
+  branch: string | undefined,
+  cache: NormalizedCacheOptions
+): { cachePath: string } {
+  const dirs = appstash(cache.toolName, {
+    ensure: true,
+    baseDir: cache.baseDir,
+  });
+
+  const reposDir = resolveAppstash(dirs, "cache", "repos");
+  if (!fs.existsSync(reposDir)) {
+    fs.mkdirSync(reposDir, { recursive: true });
+  }
+
+  const key = createCacheKey(templateUrl, branch);
+  const cachePath = path.join(reposDir, key);
+
+  return { cachePath };
+}
+
+function createCacheKey(templateUrl: string, branch?: string): string {
+  const gitUrl = normalizeGitUrl(templateUrl);
+  return crypto.createHash("md5").update(`${gitUrl}#${branch ?? "default"}`).digest("hex");
+}
+
+function cloneInto(templateUrl: string, destination: string, branch?: string): void {
+  if (fs.existsSync(destination)) {
+    fs.rmSync(destination, { recursive: true, force: true });
+  }
+
+  const gitUrl = normalizeGitUrl(templateUrl);
+  const branchArgs = branch ? ` --branch ${branch} --single-branch` : "";
+  const depthArgs = " --depth 1";
+
+  execSync(`git clone${branchArgs}${depthArgs} ${gitUrl} ${destination}`, {
+    stdio: "inherit",
+  });
+
+  const gitDir = path.join(destination, ".git");
+  if (fs.existsSync(gitDir)) {
+    fs.rmSync(gitDir, { recursive: true, force: true });
+  }
+}
+
+function cleanupDir(dir: string): void {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+

packages/create-gen-app/src/clone.ts

@@ -48,7 +48,7 @@ export async function cloneRepo(
  * @param url - Input URL
  * @returns Normalized git URL
  */
-function normalizeGitUrl(url: string): string {
+export function normalizeGitUrl(url: string): string {
   if (
     url.startsWith("git@") ||
     url.startsWith("https://") ||