pgpm 0.2.17 → 0.3.0

package/LICENSE

@@ -1,7 +1,7 @@
 The MIT License (MIT)
 
 Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
-Copyright (c) 2025 Hyperweb <developers@hyperweb.io>
+Copyright (c) 2025 Constructive <developers@constructive.io>
 Copyright (c) 2020-present, Interweb, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

package/README.md

@@ -34,7 +34,7 @@ eval "$(pgpm env)"
 
 ```bash
 # 1. Create a workspace
-pgpm init --workspace
+pgpm init workspace
 cd my-app
 
 # 2. Create your first module
@@ -55,7 +55,7 @@ psql -d mydb1 -c "SELECT faker.city('MI');"
 ### Getting Started
 
 - `pgpm init` - Initialize a new module
-- `pgpm init --workspace` - Initialize a new workspace
+- `pgpm init workspace` - Initialize a new workspace
 
 ### Development Setup
 
@@ -98,6 +98,8 @@ psql -d mydb1 -c "SELECT faker.city('MI');"
 - `pgpm analyze` - Analyze database structure
 - `pgpm rename` - Rename database changes
 - `pgpm admin-users` - Manage admin users
+- `pgpm cache clean` - Clear cached template repos used by `pgpm init`
+- `pgpm update` - Install the latest pgpm version from npm
 
 ## 💡 Common Workflows
 
@@ -105,7 +107,7 @@ psql -d mydb1 -c "SELECT faker.city('MI');"
 
 ```bash
 # 1. Create workspace
-pgpm init --workspace
+pgpm init workspace
 cd my-app
 
 # 2. Create your first module
@@ -119,6 +121,12 @@ pgpm add some_change
 pgpm deploy --createdb
 ```
 
+## 🧰 Templates, Caching, and Updates
+
+- `pgpm init` now scaffolds workspaces/modules from `https://github.com/launchql/pgpm-boilerplates.git` using `create-gen-app` with a one-week cache (stored under `~/.pgpm/cache/repos`). Override with `--repo`, `--from-branch`, and `--template-path`, or use a local template path.
+- Run `pgpm cache clean` to wipe the cached boilerplates if you need a fresh pull.
+- The CLI performs a lightweight npm version check at most once per week (skipped in CI or when `PGPM_SKIP_UPDATE_CHECK` is set). Use `pgpm update` to upgrade to the latest release.
+
 ### Working with Existing Projects
 
 ```bash
@@ -342,71 +350,71 @@ Most commands support these global options:
 
 ## Education and Tutorials
 
- 1. 🚀 [Quickstart: Getting Up and Running](https://launchql.com/learn/quickstart)
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
 Get started with modular databases in minutes. Install prerequisites and deploy your first module.
 
- 2. 📦 [Modular PostgreSQL Development with Database Packages](https://launchql.com/learn/modular-postgres)
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
 Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
 
- 3. ✏️ [Authoring Database Changes](https://launchql.com/learn/authoring-database-changes)
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
 Master the workflow for adding, organizing, and managing database changes with pgpm.
 
- 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://launchql.com/learn/e2e-postgres-testing)
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
 Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
 
- 5. ⚡ [Supabase Testing](https://launchql.com/learn/supabase)
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
 Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
 
- 6. 💧 [Drizzle ORM Testing](https://launchql.com/learn/drizzle-testing)
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
 Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
 
- 7. 🔧 [Troubleshooting](https://launchql.com/learn/troubleshooting)
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
 Common issues and solutions for pgpm, PostgreSQL, and testing.
 
-## Related LaunchQL Tooling
+## Related Constructive Tooling
 
 ### 🧪 Testing
 
-* [launchql/pgsql-test](https://github.com/launchql/launchql/tree/main/packages/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
-* [launchql/supabase-test](https://github.com/launchql/launchql/tree/main/packages/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
-* [launchql/graphile-test](https://github.com/launchql/launchql/tree/main/packages/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
-* [launchql/pg-query-context](https://github.com/launchql/launchql/tree/main/packages/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/packages/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/packages/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/packages/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/packages/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
 
 ### 🧠 Parsing & AST
 
-* [launchql/pgsql-parser](https://github.com/launchql/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
-* [launchql/libpg-query-node](https://github.com/launchql/libpg-query-node): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
-* [launchql/pg-proto-parser](https://github.com/launchql/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
-* [@pgsql/enums](https://github.com/launchql/pgsql-parser/tree/main/packages/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
-* [@pgsql/types](https://github.com/launchql/pgsql-parser/tree/main/packages/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
-* [@pgsql/utils](https://github.com/launchql/pgsql-parser/tree/main/packages/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
-* [launchql/pg-ast](https://github.com/launchql/launchql/tree/main/packages/pg-ast): **🔍 Low-level AST tools** and transformations for Postgres query structures.
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+* [pg-ast](https://www.npmjs.com/package/pg-ast): **🔍 Low-level AST tools** and transformations for Postgres query structures.
 
 ### 🚀 API & Dev Tools
 
-* [launchql/server](https://github.com/launchql/launchql/tree/main/packages/server): **⚡ Express-based API server** powered by PostGraphile to expose a secure, scalable GraphQL API over your Postgres database.
-* [launchql/explorer](https://github.com/launchql/launchql/tree/main/packages/explorer): **🔎 Visual API explorer** with GraphiQL for browsing across all databases and schemas—useful for debugging, documentation, and API prototyping.
+* [launchql/server](https://github.com/constructive-io/constructive/tree/main/packages/server): **⚡ Express-based API server** powered by PostGraphile to expose a secure, scalable GraphQL API over your Postgres database.
+* [launchql/explorer](https://github.com/constructive-io/constructive/tree/main/packages/explorer): **🔎 Visual API explorer** with GraphiQL for browsing across all databases and schemas—useful for debugging, documentation, and API prototyping.
 
 ### 🔁 Streaming & Uploads
 
-* [launchql/s3-streamer](https://github.com/launchql/launchql/tree/main/packages/s3-streamer): **📤 Direct S3 streaming** for large files with support for metadata injection and content validation.
-* [launchql/etag-hash](https://github.com/launchql/launchql/tree/main/packages/etag-hash): **🏷️ S3-compatible ETags** created by streaming and hashing file uploads in chunks.
-* [launchql/etag-stream](https://github.com/launchql/launchql/tree/main/packages/etag-stream): **🔄 ETag computation** via Node stream transformer during upload or transfer.
-* [launchql/uuid-hash](https://github.com/launchql/launchql/tree/main/packages/uuid-hash): **🆔 Deterministic UUIDs** generated from hashed content, great for deduplication and asset referencing.
-* [launchql/uuid-stream](https://github.com/launchql/launchql/tree/main/packages/uuid-stream): **🌊 Streaming UUID generation** based on piped file content—ideal for upload pipelines.
-* [launchql/upload-names](https://github.com/launchql/launchql/tree/main/packages/upload-names): **📂 Collision-resistant filenames** utility for structured and unique file names for uploads.
+* [launchql/s3-streamer](https://github.com/constructive-io/constructive/tree/main/packages/s3-streamer): **📤 Direct S3 streaming** for large files with support for metadata injection and content validation.
+* [launchql/etag-hash](https://github.com/constructive-io/constructive/tree/main/packages/etag-hash): **🏷️ S3-compatible ETags** created by streaming and hashing file uploads in chunks.
+* [launchql/etag-stream](https://github.com/constructive-io/constructive/tree/main/packages/etag-stream): **🔄 ETag computation** via Node stream transformer during upload or transfer.
+* [launchql/uuid-hash](https://github.com/constructive-io/constructive/tree/main/packages/uuid-hash): **🆔 Deterministic UUIDs** generated from hashed content, great for deduplication and asset referencing.
+* [launchql/uuid-stream](https://github.com/constructive-io/constructive/tree/main/packages/uuid-stream): **🌊 Streaming UUID generation** based on piped file content—ideal for upload pipelines.
+* [launchql/upload-names](https://github.com/constructive-io/constructive/tree/main/packages/upload-names): **📂 Collision-resistant filenames** utility for structured and unique file names for uploads.
 
 ### 🧰 CLI & Codegen
 
-* [pgpm](https://github.com/launchql/launchql/tree/main/packages/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
-* [@launchql/cli](https://github.com/launchql/launchql/tree/main/packages/cli): **🖥️ Command-line toolkit** for managing LaunchQL projects—supports database scaffolding, migrations, seeding, code generation, and automation.
-* [launchql/launchql-gen](https://github.com/launchql/launchql/tree/main/packages/launchql-gen): **✨ Auto-generated GraphQL** mutations and queries dynamically built from introspected schema data.
-* [@launchql/query-builder](https://github.com/launchql/launchql/tree/main/packages/query-builder): **🏗️ SQL constructor** providing a robust TypeScript-based query builder for dynamic generation of `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and stored procedure calls—supports advanced SQL features like `JOIN`, `GROUP BY`, and schema-qualified queries.
-* [@launchql/query](https://github.com/launchql/launchql/tree/main/packages/query): **🧩 Fluent GraphQL builder** for PostGraphile schemas. ⚡ Schema-aware via introspection, 🧩 composable and ergonomic for building deeply nested queries.
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/packages/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+* [@launchql/cli](https://github.com/constructive-io/constructive/tree/main/packages/cli): **🖥️ Command-line toolkit** for managing LaunchQL projects—supports database scaffolding, migrations, seeding, code generation, and automation.
+* [constructive-io/constructive-gen](https://github.com/constructive-io/constructive/tree/main/packages/launchql-gen): **✨ Auto-generated GraphQL** mutations and queries dynamically built from introspected schema data.
+* [@launchql/query-builder](https://github.com/constructive-io/constructive/tree/main/packages/query-builder): **🏗️ SQL constructor** providing a robust TypeScript-based query builder for dynamic generation of `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and stored procedure calls—supports advanced SQL features like `JOIN`, `GROUP BY`, and schema-qualified queries.
+* [@launchql/query](https://github.com/constructive-io/constructive/tree/main/packages/query): **🧩 Fluent GraphQL builder** for PostGraphile schemas. ⚡ Schema-aware via introspection, 🧩 composable and ergonomic for building deeply nested queries.
 
 ## Credits
 
-🛠 Built by LaunchQL — if you like our tools, please checkout and contribute to [our github ⚛️](https://github.com/launchql)
+🛠 Built by Constructive — if you like our tools, please checkout and contribute to [our github ⚛️](https://github.com/constructive-io)
 
 
 ## Disclaimer

package/commands/cache.d.ts

@@ -0,0 +1,3 @@
+import { CLIOptions, Inquirerer } from 'inquirerer';
+declare const _default: (argv: Partial<Record<string, any>>, _prompter: Inquirerer, _options: CLIOptions) => Promise<Partial<Record<string, any>>>;
+export default _default;

package/commands/cache.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const logger_1 = require("@launchql/logger");
+const create_gen_app_1 = require("create-gen-app");
+const cli_error_1 = require("../utils/cli-error");
+const log = new logger_1.Logger('cache');
+const cacheUsageText = `
+Cache Command:
+
+  pgpm cache clean [OPTIONS]
+
+Options:
+  --help, -h          Show this help message
+  --tool <name>       Cache namespace to clear (default: pgpm)
+`;
+exports.default = async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(cacheUsageText);
+        process.exit(0);
+    }
+    const action = argv._?.[0] || 'clean';
+    if (action !== 'clean') {
+        console.log(cacheUsageText);
+        await (0, cli_error_1.cliExitWithError)(`Unknown cache action: ${action}`);
+    }
+    const toolName = argv.tool || 'pgpm';
+    const cacheManager = new create_gen_app_1.CacheManager({ toolName });
+    cacheManager.clearAll();
+    log.success(`Cleared template cache for "${toolName}".`);
+    log.debug(`Cache location: ${cacheManager.getReposDir()}`);
+    return argv;
+};

package/commands/init/index.d.ts

@@ -1,4 +1,5 @@
 import { CLIOptions, Inquirerer } from 'inquirerer';
+export declare const createInitUsageText: (binaryName: string, productLabel?: string) => string;
 declare const _default: (argv: Partial<Record<string, any>>, prompter: Inquirerer, _options: CLIOptions) => Promise<{
     [x: string]: any;
 } | {

package/commands/init/index.js

@@ -3,45 +3,50 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInitUsageText = void 0;
 const module_1 = __importDefault(require("./module"));
 const workspace_1 = __importDefault(require("./workspace"));
-const initUsageText = `
+const createInitUsageText = (binaryName, productLabel) => {
+    const displayName = productLabel ?? binaryName;
+    return `
 Init Command:
 
-  pgpm init [OPTIONS]
+  ${binaryName} init [OPTIONS] [workspace]
 
-  Initialize pgpm workspace or module.
+  Initialize ${displayName} workspace or module.
 
 Options:
   --help, -h              Show this help message
-  --workspace             Initialize workspace instead of module
   --cwd <directory>       Working directory (default: current directory)
-  --repo <repo>           Use templates from GitHub repository (e.g., owner/repo)
-  --template-path <path>   Use templates from local path
-  --from-branch <branch>   Specify branch when using --repo (default: main)
+  --repo <repo>           Template repo (default: https://github.com/launchql/pgpm-boilerplates.git)
+  --template-path <path>  Template sub-path (default: workspace/module) or local path override
+  --from-branch <branch>  Branch/tag to use when cloning repo
 
 Examples:
-  pgpm init                                  Initialize new module in existing workspace
-  pgpm init --workspace                       Initialize new workspace
-  pgpm init --repo owner/repo                Use templates from GitHub repository
-  pgpm init --template-path ./custom-templates Use templates from local path
-  pgpm init --repo owner/repo --from-branch develop  Use specific branch
+  ${binaryName} init                                   Initialize new module in existing workspace
+  ${binaryName} init workspace                         Initialize new workspace
+  ${binaryName} init --repo owner/repo                 Use templates from GitHub repository
+  ${binaryName} init --template-path ./custom-templates Use templates from local path
+  ${binaryName} init --repo owner/repo --from-branch develop  Use specific branch
 `;
+};
+exports.createInitUsageText = createInitUsageText;
 exports.default = async (argv, prompter, _options) => {
     // Show usage if explicitly requested
     if (argv.help || argv.h) {
-        console.log(initUsageText);
+        console.log((0, exports.createInitUsageText)('pgpm'));
         process.exit(0);
     }
     return handlePromptFlow(argv, prompter);
 };
 async function handlePromptFlow(argv, prompter) {
-    const { workspace } = argv;
-    switch (workspace) {
-        case true:
-            return (0, workspace_1.default)(argv, prompter);
-        case false:
-        default:
-            return (0, module_1.default)(argv, prompter);
+    const firstArg = argv._?.[0] || undefined;
+    if (firstArg === 'workspace') {
+        const nextArgv = {
+            ...argv,
+            _: (argv._ ?? []).slice(1)
+        };
+        return (0, workspace_1.default)(nextArgv, prompter);
     }
+    return (0, module_1.default)(argv, prompter);
 }

package/commands/init/module.js

@@ -6,7 +6,6 @@ const logger_1 = require("@launchql/logger");
 const types_1 = require("@launchql/types");
 const log = new logger_1.Logger('module-init');
 async function runModuleSetup(argv, prompter) {
-    const { email, username } = (0, types_1.getGitConfigInfo)();
     const { cwd = process.cwd() } = argv;
     const project = new core_1.LaunchQLPackage(cwd);
     if (!project.workspacePath) {
@@ -20,7 +19,7 @@ async function runModuleSetup(argv, prompter) {
     const availExtensions = project.getAvailableModules();
     const moduleQuestions = [
         {
-            name: 'MODULENAME',
+            name: 'moduleName',
             message: 'Enter the module name',
             required: true,
             type: 'text',
@@ -35,36 +34,31 @@ async function runModuleSetup(argv, prompter) {
         },
     ];
     const answers = await prompter.prompt(argv, moduleQuestions);
-    const modName = (0, core_1.sluggify)(answers.MODULENAME);
+    const modName = (0, core_1.sluggify)(answers.moduleName);
+    // Avoid overlapping readline listeners with create-gen-app's prompts.
+    prompter.close();
     const extensions = answers.extensions
         .filter((opt) => opt.selected)
         .map((opt) => opt.name);
-    // Determine template source
-    let templateSource;
-    if (argv.repo) {
-        templateSource = {
-            type: 'github',
-            path: argv.repo,
-            branch: argv.fromBranch
-        };
-        log.info(`Loading templates from GitHub repository: ${argv.repo}`);
-    }
-    else if (argv.templatePath) {
-        templateSource = {
-            type: 'local',
-            path: argv.templatePath
-        };
-        log.info(`Loading templates from local path: ${argv.templatePath}`);
-    }
-    project.initModule({
+    const templateRepo = argv.repo ?? core_1.DEFAULT_TEMPLATE_REPO;
+    const templatePath = argv.templatePath;
+    const templateAnswers = {
         ...argv,
         ...answers,
+        moduleName: modName,
+        packageIdentifier: argv.packageIdentifier || modName
+    };
+    await project.initModule({
         name: modName,
-        // @ts-ignore
-        USERFULLNAME: username,
-        USEREMAIL: email,
+        description: answers.description || modName,
+        author: answers.author || modName,
         extensions,
-        templateSource
+        templateRepo,
+        templatePath,
+        branch: argv.fromBranch,
+        toolName: core_1.DEFAULT_TEMPLATE_TOOL_NAME,
+        answers: templateAnswers,
+        noTty: Boolean(argv.noTty || argv['no-tty'] || process.env.CI === 'true')
     });
     log.success(`Initialized module: ${modName}`);
     return { ...argv, ...answers };

package/commands/init/workspace.js

@@ -6,9 +6,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = runWorkspaceSetup;
 const core_1 = require("@launchql/core");
 const logger_1 = require("@launchql/logger");
-// @ts-ignore - TypeScript module resolution issue with @launchql/templatizer
-const templatizer_1 = require("@launchql/templatizer");
-const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
 const log = new logger_1.Logger('workspace-init');
 async function runWorkspaceSetup(argv, prompter) {
@@ -17,36 +14,35 @@ async function runWorkspaceSetup(argv, prompter) {
             name: 'name',
             message: 'Enter workspace name',
             required: true,
-            type: 'text',
+            type: 'text'
         }
     ];
     const answers = await prompter.prompt(argv, workspaceQuestions);
-    const { cwd } = argv;
+    const { cwd = process.cwd() } = argv;
     const targetPath = path_1.default.join(cwd, (0, core_1.sluggify)(answers.name));
-    (0, fs_1.mkdirSync)(targetPath, { recursive: true });
-    log.success(`Created workspace directory: ${targetPath}`);
-    // Determine template source
-    let templates = templatizer_1.workspaceTemplate;
-    if (argv.repo) {
-        const source = {
-            type: 'github',
-            path: argv.repo,
-            branch: argv.fromBranch
-        };
-        log.info(`Loading templates from GitHub repository: ${argv.repo}`);
-        const compiledTemplates = (0, templatizer_1.loadTemplates)(source, 'workspace');
-        templates = compiledTemplates.map((t) => t.render);
-    }
-    else if (argv.templatePath) {
-        const source = {
-            type: 'local',
-            path: argv.templatePath
-        };
-        log.info(`Loading templates from local path: ${argv.templatePath}`);
-        const compiledTemplates = (0, templatizer_1.loadTemplates)(source, 'workspace');
-        templates = compiledTemplates.map((t) => t.render);
-    }
-    (0, templatizer_1.writeRenderedTemplates)(templates, targetPath, { ...argv, ...answers });
+    // Prevent double-echoed keystrokes by closing our prompter before template prompts.
+    prompter.close();
+    const templateRepo = argv.repo ?? core_1.DEFAULT_TEMPLATE_REPO;
+    const templatePath = argv.templatePath ?? 'workspace';
+    const scaffoldResult = await (0, core_1.scaffoldTemplate)({
+        type: 'workspace',
+        outputDir: targetPath,
+        templateRepo,
+        branch: argv.fromBranch,
+        templatePath,
+        answers: {
+            ...argv,
+            ...answers,
+            workspaceName: answers.name
+        },
+        toolName: core_1.DEFAULT_TEMPLATE_TOOL_NAME,
+        noTty: Boolean(argv.noTty || argv['no-tty'] || process.env.CI === 'true'),
+        cwd
+    });
+    const cacheMessage = scaffoldResult.cacheUsed
+        ? `Using cached templates from ${scaffoldResult.templateDir}`
+        : `Fetched templates into ${scaffoldResult.templateDir}`;
+    log.success(cacheMessage);
     log.success('Workspace templates rendered.');
     return { ...argv, ...answers, cwd: targetPath };
 }

package/commands/update.d.ts

@@ -0,0 +1,3 @@
+import { CLIOptions, Inquirerer } from 'inquirerer';
+declare const _default: (argv: Partial<Record<string, any>>, _prompter: Inquirerer, _options: CLIOptions) => Promise<Partial<Record<string, any>>>;
+export default _default;

package/commands/update.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const logger_1 = require("@launchql/logger");
+const child_process_1 = require("child_process");
+const package_1 = require("../package");
+const npm_version_1 = require("../utils/npm-version");
+const cli_error_1 = require("../utils/cli-error");
+const log = new logger_1.Logger('update');
+const updateUsageText = `
+Update Command:
+
+  pgpm update [OPTIONS]
+
+  Install the latest version of pgpm from npm.
+
+Options:
+  --help, -h          Show this help message
+  --package <name>    Override the package name (default: package.json name)
+  --registry <url>    Use a custom npm registry
+  --dry-run           Print the npm command without executing it
+`;
+const runNpmInstall = (pkgName, registry) => {
+    return new Promise((resolve, reject) => {
+        const args = ['install', '-g', pkgName];
+        if (registry) {
+            args.push('--registry', registry);
+        }
+        const child = (0, child_process_1.spawn)('npm', args, { stdio: 'inherit' });
+        child.on('error', reject);
+        child.on('exit', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`npm install exited with code ${code}`));
+            }
+        });
+    });
+};
+exports.default = async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(updateUsageText);
+        process.exit(0);
+    }
+    const pkgJson = (0, package_1.readAndParsePackageJson)();
+    const pkgName = argv.package || pkgJson.name || 'pgpm';
+    const registry = argv.registry;
+    const dryRun = Boolean(argv['dry-run']);
+    const npmCommand = `npm install -g ${pkgName}${registry ? ` --registry ${registry}` : ''}`;
+    if (dryRun) {
+        log.info(`[dry-run] ${npmCommand}`);
+        return argv;
+    }
+    log.info(`Running: ${npmCommand}`);
+    try {
+        await runNpmInstall(pkgName, registry);
+        const latest = await (0, npm_version_1.fetchLatestVersion)(pkgName);
+        if (latest) {
+            log.success(`Successfully updated ${pkgName} to version ${latest}.`);
+        }
+        else {
+            log.success(`npm install completed for ${pkgName}.`);
+        }
+    }
+    catch (error) {
+        await (0, cli_error_1.cliExitWithError)(error instanceof Error ? error.message : String(error), { package: pkgName, registry });
+    }
+    return argv;
+};

package/commands.js

@@ -8,6 +8,7 @@ const pg_cache_1 = require("pg-cache");
 const add_1 = __importDefault(require("./commands/add"));
 const admin_users_1 = __importDefault(require("./commands/admin-users"));
 const analyze_1 = __importDefault(require("./commands/analyze"));
+const cache_1 = __importDefault(require("./commands/cache"));
 const clear_1 = __importDefault(require("./commands/clear"));
 const deploy_1 = __importDefault(require("./commands/deploy"));
 const docker_1 = __importDefault(require("./commands/docker"));
@@ -20,6 +21,7 @@ const kill_1 = __importDefault(require("./commands/kill"));
 const migrate_1 = __importDefault(require("./commands/migrate"));
 const package_1 = __importDefault(require("./commands/package"));
 const plan_1 = __importDefault(require("./commands/plan"));
+const update_1 = __importDefault(require("./commands/update"));
 const remove_1 = __importDefault(require("./commands/remove"));
 const rename_1 = __importDefault(require("./commands/rename"));
 const revert_1 = __importDefault(require("./commands/revert"));
@@ -28,6 +30,7 @@ const verify_1 = __importDefault(require("./commands/verify"));
 const package_2 = require("./package");
 const utils_1 = require("./utils");
 const cli_error_1 = require("./utils/cli-error");
+const update_check_1 = require("./utils/update-check");
 const withPgTeardown = (fn, skipTeardown = false) => async (...args) => {
     try {
         await fn(...args);
@@ -60,7 +63,9 @@ const createPgpmCommandMap = (skipPgTeardown = false) => {
         install: pgt(install_1.default),
         migrate: pgt(migrate_1.default),
         analyze: pgt(analyze_1.default),
-        rename: pgt(rename_1.default)
+        rename: pgt(rename_1.default),
+        cache: cache_1.default,
+        update: update_1.default
     };
 };
 exports.createPgpmCommandMap = createPgpmCommandMap;
@@ -91,6 +96,15 @@ const commands = async (argv, prompter, options) => {
         ]);
         command = answer.command;
     }
+    try {
+        await (0, update_check_1.checkForUpdates)({
+            command,
+            pkgVersion: (0, package_2.readAndParsePackageJson)().version
+        });
+    }
+    catch {
+        // ignore update check failures
+    }
     newArgv = await prompter.prompt(newArgv, [
         {
             type: 'text',

package/esm/commands/cache.js

@@ -0,0 +1,30 @@
+import { Logger } from '@launchql/logger';
+import { CacheManager } from 'create-gen-app';
+import { cliExitWithError } from '../utils/cli-error';
+const log = new Logger('cache');
+const cacheUsageText = `
+Cache Command:
+
+  pgpm cache clean [OPTIONS]
+
+Options:
+  --help, -h          Show this help message
+  --tool <name>       Cache namespace to clear (default: pgpm)
+`;
+export default async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(cacheUsageText);
+        process.exit(0);
+    }
+    const action = argv._?.[0] || 'clean';
+    if (action !== 'clean') {
+        console.log(cacheUsageText);
+        await cliExitWithError(`Unknown cache action: ${action}`);
+    }
+    const toolName = argv.tool || 'pgpm';
+    const cacheManager = new CacheManager({ toolName });
+    cacheManager.clearAll();
+    log.success(`Cleared template cache for "${toolName}".`);
+    log.debug(`Cache location: ${cacheManager.getReposDir()}`);
+    return argv;
+};