Allow optional TTL, expose cache dirs, and read CLI package name dynamically

- add TTL opt-out flow to create-gen-app-test (new --ttl/--no-ttl flags) and avoid forcing 1-week default
- read package name from package.json (fallback @launchql/cli) for version checks instead of hard-coding create-gen-app
- expose CacheManager appstash dirs via getters and allow caller-provided dirs to own appstash lifecycle
- update callers/tests to use getReposDir() and refresh README to document optional TTL and dirs injection

Author: sdqede

packages/create-gen-app-test/src/__tests__/cached-template.test.ts

@@ -58,7 +58,7 @@ describe('cached template integration tests', () => {
       const cacheKey = cacheManager.createKey(normalizedUrl);
 
       // Clone to cache directory
-      const cachePath = path.join(cacheManager['reposDir'], cacheKey);
+      const cachePath = path.join(cacheManager.getReposDir(), cacheKey);
       gitCloner.clone(normalizedUrl, cachePath, { depth: 1 });
 
       // Register in cache manager

packages/create-gen-app-test/src/cli.ts

@@ -14,9 +14,11 @@ const DEFAULT_PATH = ".";
 const DEFAULT_OUTPUT_FALLBACK = "create-gen-app-output";
 const DEFAULT_TOOL_NAME = "create-gen-app-test";
 const DEFAULT_TTL = 604800000; // 1 week
+const DEFAULT_TTL_DAYS = DEFAULT_TTL / (24 * 60 * 60 * 1000);
 
 // Import package.json for version
 import * as createGenPackageJson from "create-gen-app/package.json";
+const PACKAGE_NAME = createGenPackageJson.name ?? "@launchql/cli";
 const PACKAGE_VERSION = createGenPackageJson.version ?? "0.0.0";
 
 const RESERVED_ARG_KEYS = new Set([
@@ -41,6 +43,8 @@ const RESERVED_ARG_KEYS = new Set([
   "n",
   "clear-cache",
   "c",
+  "ttl",
+  "no-ttl",
 ]);
 
 export interface CliResult {
@@ -63,9 +67,10 @@ export async function runCli(
       v: "version",
       n: "no-tty",
       c: "clear-cache",
+      // no alias for ttl to keep it explicit
     },
-    string: ["repo", "branch", "path", "template", "output"],
-    boolean: ["force", "help", "version", "no-tty", "clear-cache"],
+    string: ["repo", "branch", "path", "template", "output", "ttl"],
+    boolean: ["force", "help", "version", "no-tty", "clear-cache", "no-ttl"],
     default: {
       repo: DEFAULT_REPO,
       path: DEFAULT_PATH,
@@ -84,21 +89,23 @@ export async function runCli(
 
   // Check for updates
   try {
-    const versionCheck = await checkNpmVersion("create-gen-app", PACKAGE_VERSION);
+    const versionCheck = await checkNpmVersion(PACKAGE_NAME, PACKAGE_VERSION);
     if (versionCheck.isOutdated && versionCheck.latestVersion) {
       console.warn(
         `\n⚠️  New version available: ${versionCheck.currentVersion} → ${versionCheck.latestVersion}`
       );
-      console.warn(`   Run: npm install -g create-gen-app@latest\n`);
+      console.warn(`   Run: npm install -g ${PACKAGE_NAME}@latest\n`);
     }
   } catch {
     // Silently ignore version check failures
   }
 
+  const ttl = resolveTtlOption(args);
+
   // Initialize modules
   const cacheManager = new CacheManager({
     toolName: DEFAULT_TOOL_NAME,
-    ttl: DEFAULT_TTL,
+    ttl,
   });
 
   // Handle --clear-cache
@@ -139,7 +146,7 @@ export async function runCli(
     if (args.branch) {
       console.log(`Using branch ${args.branch}`);
     }
-    const tempDest = path.join(cacheManager['reposDir'], cacheKey);
+    const tempDest = path.join(cacheManager.getReposDir(), cacheKey);
     gitCloner.clone(normalizedUrl, tempDest, { branch: args.branch, depth: 1 });
     cacheManager.set(cacheKey, tempDest);
     templateDir = tempDest;
@@ -213,7 +220,7 @@ export async function runCli(
       answers: answerOverrides,
       noTty,
       toolName: DEFAULT_TOOL_NAME,
-      ttl: DEFAULT_TTL,
+      ttl,
     });
 
     console.log(`\n✨ Done! Project ready at ${outputDir}`);
@@ -238,6 +245,8 @@ Options:
   -o, --output <dir>       Output directory (defaults to ./<template>)
   -f, --force              Overwrite the output directory if it exists
   -c, --clear-cache        Clear the template cache and exit
+      --ttl <ms>           Set cache TTL in milliseconds (flag alone uses 1 week)
+      --no-ttl             Disable TTL (cache never expires)
   -v, --version            Show CLI version
   -n, --no-tty             Disable TTY mode for prompts
   -h, --help               Show this help message
@@ -246,7 +255,7 @@ You can also pass variable overrides, e.g.:
   node cli --template module --PROJECT_NAME my-app
 
 Cache is stored at: ~/.${DEFAULT_TOOL_NAME}/cache/repos
-TTL: ${DEFAULT_TTL / (24 * 60 * 60 * 1000)} days
+TTL: none by default; use --ttl to enable (default ${DEFAULT_TTL_DAYS} days when flag provided)
 `);
 }
 
@@ -317,3 +326,26 @@ if (require.main === module) {
     process.exitCode = 1;
   });
 }
+
+function resolveTtlOption(args: ParsedArgs): number | undefined {
+  const disableTtl = Boolean(args["no-ttl"] ?? (args as Record<string, unknown>).noTtl);
+  if (disableTtl) {
+    return undefined;
+  }
+
+  if (args.ttl === undefined) {
+    return undefined;
+  }
+
+  // Support --ttl with no value to use the default 1-week TTL
+  if (args.ttl === true) {
+    return DEFAULT_TTL;
+  }
+
+  const ttlMs = Number(args.ttl);
+  if (Number.isNaN(ttlMs) || ttlMs < 0) {
+    throw new Error("TTL must be a non-negative number of milliseconds");
+  }
+
+  return ttlMs === 0 ? undefined : ttlMs;
+}

packages/create-gen-app-test/src/index.ts

@@ -4,7 +4,6 @@ import { GitCloner } from 'create-gen-app';
 import { Templatizer } from 'create-gen-app';
 
 // Configuration constants (top-most layer owns defaults)
-const DEFAULT_TTL = 604800000; // 1 week in milliseconds
 const DEFAULT_TOOL_NAME = 'pgpm';
 
 export interface CreateFromTemplateOptions {
@@ -39,7 +38,7 @@ export async function createFromTemplate(
     answers = {},
     toolName = DEFAULT_TOOL_NAME,
     branch,
-    ttl = DEFAULT_TTL,
+    ttl,
     baseDir,
     fromPath,
     noTty = false,
@@ -79,7 +78,7 @@ export async function createFromTemplate(
   } else {
     // 4. Clone to cache
     console.log(`Cloning ${normalizedUrl}...`);
-    const tempDest = path.join(cacheManager['reposDir'], cacheKey);
+    const tempDest = path.join(cacheManager.getReposDir(), cacheKey);
 
     gitCloner.clone(normalizedUrl, tempDest, { branch, depth: 1 });
     cacheManager.set(cacheKey, tempDest);

packages/create-gen-app/README.md

@@ -25,7 +25,7 @@ A TypeScript-first library for cloning template repositories, asking the user fo
 - 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
 
@@ -60,7 +60,8 @@ async function main() {
   // 1. Initialize components
   const cacheManager = new CacheManager({
     toolName: "my-cli", // ~/.my-cli/cache
-    ttl: 604800000,     // 1 week
+    // 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();
@@ -78,7 +79,7 @@ async function main() {
     if (isExpired) cacheManager.clear(cacheKey);
 
     // Clone to a temporary location managed by CacheManager
-    const tempDest = path.join(cacheManager.reposDir, cacheKey);
+    const tempDest = path.join(cacheManager.getReposDir(), cacheKey);
     await gitCloner.clone(normalizedUrl, tempDest, { depth: 1 });
 
     // Register and update cache
@@ -147,12 +148,14 @@ No code changes are needed; the generator discovers templates at runtime and wil
 ## API Overview
 
 ### CacheManager
-- `new CacheManager(config)`: Initialize with `toolName` and `ttl`.
+- `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.

packages/create-gen-app/__tests__/ttl-expiration.test.ts

@@ -19,7 +19,7 @@ describe('TTL expiration', () => {
     try {
       // First clone - cache miss
       const cacheKey = cacheManager.createKey(testRepo);
-      const tempDest = path.join(cacheManager['reposDir'], cacheKey);
+      const tempDest = path.join(cacheManager.getReposDir(), cacheKey);
 
       console.log(`Cloning test repository to ${tempDest}...`);
       gitCloner.clone(testRepo, tempDest, { depth: 1 });

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

@@ -20,19 +20,43 @@ export class CacheManager {
       toolName: config.toolName,
       baseDir: config.baseDir,
       ttl: config.ttl,
+      dirs: config.dirs,
     };
 
-    this.dirs = appstash(this.config.toolName, {
-      ensure: true,
-      baseDir: this.config.baseDir,
-    });
+    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(): string {
+    return this.reposDir;
+  }
+
+  /**
+   * Public accessor for the metadata cache directory path.
+   */
+  getMetadataDir(): string {
+    return this.metadataDir;
+  }
+
+  /**
+   * Public accessor for resolved appstash directories.
+   */
+  getAppstashDirs(): AppStashResult {
+    return this.dirs;
+  }
+
   /**
    * Get cached directory path if exists and not expired
    * Returns null if not cached or expired

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

@@ -1,7 +1,14 @@
+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 {