feat(cli): --help now lists every template with a one-line description (#146)

Co-authored-by: H. Furkan Bozkurt <bozkurh@amazon.com>

Author: hfurkanbozkurt

.changeset/amplify-fresh-scaffold-guard.md

@@ -0,0 +1,19 @@
+---
+"@aws-blocks/create-blocks-app": patch
+---
+
+Fix + polish for `create-blocks-app`:
+
+- Reject `--template amplify` on a fresh directory up front with a
+  helpful message pointing at `--template default` (for a fresh app)
+  or the no-arg command (to integrate Blocks into an existing Amplify
+  Gen 2 project). The `amplify` template is an overlay auto-selected
+  when the CLI detects `amplify/backend.ts`, not a scaffoldable
+  starter. Previously the fresh-scaffold path with `--template amplify`
+  crashed mid-copy on missing template files.
+- Correct two template descriptions that misstated the frontend:
+  `auth-cognito` and `demo` were labeled "Vite + lit-html" but both
+  ship a Vite + vanilla-DOM frontend. Descriptions now read
+  "Vite + vanilla-DOM frontend with Cognito passwordless email-OTP
+  auth end-to-end" and "Fuller example — AuthBasic + KVStore +
+  DynamoDB priority-sorted todo (Vite, vanilla-DOM)" respectively.

.changeset/help-template-descriptions.md

@@ -0,0 +1,9 @@
+---
+"@aws-blocks/create-blocks-app": patch
+---
+
+Improve `--help` output for `create-blocks-app`:
+
+- Template discovery is now filesystem-driven — drop a folder under `templates/` with a `package.json` and it auto-registers.
+- `--help` now lists every template with a one-line description, sourced from each template's `blocksTemplateDescription` field.
+- Added `--yes --template nextjs` to the Examples section.

packages/create-blocks-app/README.md

@@ -20,15 +20,13 @@ npx @aws-blocks/create-blocks-app my-app
 npx @aws-blocks/create-blocks-app my-app --template react
 ```
 
-Available templates:
-- **default** - Real-time todo app with auth, data, and live sync
-- **bare** - Minimal Blocks setup
-- **react** - React frontend with Blocks backend
-- **backend** - Backend-only (no frontend)
-- **nextjs** - Next.js integration
-- **auth-cognito** - Cognito authentication example
-- **amplify** - Amplify Gen 2 integration
-- **demo** - Demo application
+For the full list of templates and one-line descriptions, run:
+
+```bash
+npx @aws-blocks/create-blocks-app --help
+```
+
+Template descriptions are sourced from each template's `package.json` (`blocksTemplateDescription`) so the CLI is always the source of truth.
 
 ### Add to Existing Project
 
@@ -135,33 +133,13 @@ export const blocksStack = await BlocksStack.create(app, stackName, {
 
 ## Templates
 
-### Default
-Real-time todo application with:
-- User authentication (AuthBasic)
-- Todo storage (DistributedTable / DynamoDB)
-- Optimistic locking
-- Real-time sync (Realtime / WebSocket)
-
-### Bare
-Minimal setup demonstrating core concepts.
-
-### React
-React frontend with Blocks backend.
+Available templates: `default`, `bare`, `react`, `backend`, `nextjs`, `auth-cognito`, `amplify`, `demo`.
 
-### Backend
-Backend-only template (no frontend bundling).
+Every folder under `templates/` is a self-registering template. Each `package.json` in that folder sets a `blocksTemplateDescription` field, which the CLI reads to build the `--help` catalog. To see the current list of templates and their one-line descriptions:
 
-### Next.js
-Next.js integration with Blocks backend.
-
-### Auth-Cognito
-Cognito authentication example.
-
-### Amplify
-Amplify Gen 2 integration template.
-
-### Demo
-Demo application showcasing Building Blocks.
+```bash
+npx @aws-blocks/create-blocks-app --help
+```
 
 ## Related Packages
 

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

@@ -45,6 +45,16 @@ describe('create-blocks-app CLI argument parsing', () => {
     assert.match(result.stdout, /Usage: create-blocks-app/);
   });
 
+  it('--help includes template descriptions', () => {
+    const result = run(['--help']);
+    assert.strictEqual(result.exitCode, 0);
+    assert.match(
+      result.stdout,
+      /default\s+Vite \+ lit-html frontend with auth/,
+      '--help should list the default template with its blocksTemplateDescription',
+    );
+  });
+
   it('unknown flag exits 1 with error message', () => {
     const result = run(['--foo']);
     assert.strictEqual(result.exitCode, 1);
@@ -80,6 +90,35 @@ describe('create-blocks-app CLI argument parsing', () => {
     assert.doesNotMatch(result.stderr, /ENOENT/);
   });
 
+  it('a template folder missing package.json is rejected as unknown, not crashed with ENOENT', () => {
+    // Latent-bug guard: a folder under templates/ with no package.json is shown
+    // in --help but excluded from validation, so selecting it fails cleanly
+    // instead of throwing ENOENT on the later template version read.
+    const brokenDir = join(__dirname, '../templates', '__broken_test_template__');
+    mkdirSync(brokenDir, { recursive: true });
+    try {
+      const result = run(['my-app', '--template', '__broken_test_template__', '--skip-install']);
+      assert.strictEqual(result.exitCode, 1);
+      assert.match(result.stderr, /Unknown template "__broken_test_template__"/);
+      assert.doesNotMatch(result.stderr, /ENOENT/);
+    } finally {
+      rmSync(brokenDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    }
+  });
+
+  it('--template amplify on a fresh dir exits 1 with a helpful message', () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'create-blocks-app-amplify-fresh-'));
+    try {
+      const result = run([tmpDir, '--template', 'amplify', '--skip-install', '-y']);
+      assert.strictEqual(result.exitCode, 1);
+      assert.match(result.stderr, /amplify.*auto-selected/i);
+      assert.match(result.stderr, /--template default/);
+      assert.doesNotMatch(result.stderr, /ENOENT/);
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
   it('multiple positional args exits 1 with error message', () => {
     const result = run(['my-app', 'extra-arg']);
     assert.strictEqual(result.exitCode, 1);

packages/create-blocks-app/src/index.ts

@@ -185,20 +185,123 @@ async function addBlocksWorkspace(targetDir: string, options: {
   }
 }
 
-const AVAILABLE_TEMPLATES = ['default', 'bare', 'react', 'backend', 'nextjs', 'auth-cognito', 'amplify', 'demo'];
+// ─── Template discovery ─────────────────────────────────────────────────────
+//
+// Templates are the ONLY source of truth for the template list. Each template
+// under `templates/<name>/` ships a `package.json` with:
+//   {
+//     "blocksTemplate": "<name>",
+//     "blocksTemplateDescription": "One-line description shown in --help"
+//   }
+//
+// Adding a new template = drop a folder with a package.json containing those
+// two fields. The CLI's --help, validation, and error messages all pick it up
+// automatically — no other code changes required.
+//
+// An optional `blocksTemplateOverlayOnly: true` marks a template as an overlay
+// that's auto-selected when the CLI detects a matching existing project (e.g.
+// `amplify`) rather than a scaffoldable fresh-app starter; `createFreshProject`
+// rejects it up front. A folder whose package.json can't be read is still shown
+// in --help (flagged) but excluded from `--template` validation.
+//
+// Display order below is preserved from the previous hardcoded list so that
+// `--help` reads in the intended progression (default → bare → richer variants
+// → framework variants → overlays → demos). New templates default to
+// alphabetical after known ones. Update this array to reorder.
+
+type TemplateInfo = {
+  name: string;
+  description: string;
+  valid: boolean;
+  overlayOnly: boolean;
+};
+
+const TEMPLATE_DISPLAY_ORDER = ['default', 'bare', 'react', 'backend', 'nextjs', 'auth-cognito', 'amplify', 'demo'];
+
+let templateCatalogCache: TemplateInfo[] | null = null;
+
+async function loadTemplateCatalog(): Promise<TemplateInfo[]> {
+  if (templateCatalogCache) return templateCatalogCache;
+
+  const templatesDir = join(__dirname, '../templates');
+  const entries = await readdir(templatesDir, { withFileTypes: true });
+  const discovered: TemplateInfo[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const pkgPath = join(templatesDir, entry.name, 'package.json');
+    try {
+      const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+      discovered.push({
+        name: entry.name,
+        description: typeof pkg.blocksTemplateDescription === 'string'
+          ? pkg.blocksTemplateDescription
+          : '(no description — add `blocksTemplateDescription` to this template\'s package.json)',
+        valid: true,
+        overlayOnly: pkg.blocksTemplateOverlayOnly === true,
+      });
+    } catch {
+      // Template folder without a readable package.json — surface it so it's
+      // discoverable, but flag that metadata is missing.
+      discovered.push({
+        name: entry.name,
+        description: '(no package.json — template metadata missing)',
+        valid: false,
+        overlayOnly: false,
+      });
+    }
+  }
+
+  // Sort by TEMPLATE_DISPLAY_ORDER, then any unknown templates alphabetically.
+  discovered.sort((a, b) => {
+    const aIdx = TEMPLATE_DISPLAY_ORDER.indexOf(a.name);
+    const bIdx = TEMPLATE_DISPLAY_ORDER.indexOf(b.name);
+    if (aIdx === -1 && bIdx === -1) return a.name.localeCompare(b.name);
+    if (aIdx === -1) return 1;
+    if (bIdx === -1) return -1;
+    return aIdx - bIdx;
+  });
+
+  templateCatalogCache = discovered;
+  return discovered;
+}
 
-function validateTemplateName(templateName: string): void {
-  if (!AVAILABLE_TEMPLATES.includes(templateName)) {
+async function validateTemplateName(templateName: string): Promise<void> {
+  const catalog = await loadTemplateCatalog();
+  const names = catalog.filter(t => t.valid).map(t => t.name);
+  if (!names.includes(templateName)) {
     console.error(`Error: Unknown template "${templateName}".`);
-    console.error(`Available templates: ${AVAILABLE_TEMPLATES.join(', ')}`);
+    console.error(`Available templates: ${names.join(', ')}`);
     process.exit(1);
   }
 }
 
 // ─── Fresh project creation ──────────────────────────────────────────────────
 
 async function createFreshProject(targetDir: string, templateName: string, skipInstall = false) {
-  validateTemplateName(templateName);
+  await validateTemplateName(templateName);
+
+  // Overlay templates (e.g. `amplify`, detected via `isAmplifyGen2Project()`)
+  // are auto-selected when the CLI finds a matching existing project and are
+  // flagged `blocksTemplateOverlayOnly` in their package.json. They ship only an
+  // overlay snippet — not a full standalone project (no `src/`, no `index.html`,
+  // no `gitignore`) — so a fresh scaffold would fail partway through the copy.
+  // Reject up front. Keying off the catalog flag (not a hardcoded name) means a
+  // new overlay template needs no change here — just the flag in its package.json.
+  const overlayEntry = (await loadTemplateCatalog()).find(t => t.name === templateName);
+  if (overlayEntry?.overlayOnly) {
+    console.error(`Error: The \`${templateName}\` template is an overlay that's auto-selected`);
+    console.error('when the CLI detects a compatible existing project. It cannot be');
+    console.error('scaffolded as a fresh app.');
+    console.error('');
+    console.error('To scaffold a fresh Blocks app, choose a different template:');
+    console.error('  npx @aws-blocks/create-blocks-app my-app --template default');
+    console.error('');
+    console.error('To integrate Blocks into an existing project, run this from');
+    console.error('the project root:');
+    console.error('  npx @aws-blocks/create-blocks-app');
+    process.exit(1);
+  }
 
   // Read template package.json to get template name
   const templateDir = join(__dirname, '../templates', templateName);
@@ -556,7 +659,14 @@ async function integrateWithExistingProject(targetDir: string, templateName = 'd
 
 // ─── Main ────────────────────────────────────────────────────────────────────
 
-function printUsage() {
+async function printUsage() {
+  const catalog = await loadTemplateCatalog();
+  const names = catalog.map(t => t.name);
+  const widest = catalog.length ? Math.max(...catalog.map(t => t.name.length)) : 0;
+  const templateList = catalog
+    .map(t => `    ${t.name.padEnd(widest)}   ${t.description}`)
+    .join('\n');
+
   console.log(`Usage: create-blocks-app [directory] [options]
 
 Create a new AWS Blocks app or add Blocks to an existing project.
@@ -581,15 +691,20 @@ Options:
                          starter app; when adding to an existing project it
                          selects which aws-blocks/ workspace to copy, e.g.
                          "nextjs" for a Next.js dev server (default: "default")
-                         Available templates: ${AVAILABLE_TEMPLATES.join(', ')}
+
+                         Available templates: ${names.join(', ')}
+
+${templateList}
+
   --skip-install         Skip installing dependencies
   -y, --yes              Skip confirmation prompts
   -h, --help             Show this help message
 
 Examples:
-  npx @aws-blocks/create-blocks-app            Add Blocks to current project
-  npx @aws-blocks/create-blocks-app .          Add Blocks to current project
-  npx @aws-blocks/create-blocks-app my-app     Create a standalone Blocks starter app
+  npx @aws-blocks/create-blocks-app                            Add Blocks to current project
+  npx @aws-blocks/create-blocks-app .                          Add Blocks to current project
+  npx @aws-blocks/create-blocks-app my-app                     Create a standalone Blocks starter app
+  npx @aws-blocks/create-blocks-app . --yes --template nextjs  Non-interactive scaffold with the Next.js template
 `);
 }
 
@@ -602,7 +717,7 @@ async function create() {
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--help' || args[i] === '-h') {
-      printUsage();
+      await printUsage();
       process.exit(0);
     } else if (args[i] === '--template') {
       const value = args[i + 1];
@@ -633,7 +748,7 @@ async function create() {
     }
   }
 
-  validateTemplateName(templateName);
+  await validateTemplateName(templateName);
 
   const templatePkgVersion: string = JSON.parse(
     await readFile(join(__dirname, '../templates', templateName, 'package.json'), 'utf-8'),

packages/create-blocks-app/templates/amplify/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "blocks-amplify-overlay",
+  "version": "0.1.0",
+  "private": true,
+  "blocksTemplate": "amplify",
+  "blocksTemplateDescription": "Overlay for an existing Amplify Gen 2 app (auto-selected when detected)",
+  "blocksTemplateOverlayOnly": true
+}

packages/create-blocks-app/templates/auth-cognito/package.json

@@ -3,10 +3,13 @@
   "version": "0.1.0",
   "type": "module",
   "blocksTemplate": "auth-cognito",
+  "blocksTemplateDescription": "Vite + vanilla-DOM frontend with Cognito passwordless email-OTP auth end-to-end",
   "engines": {
     "node": ">=22.0.0"
   },
-  "workspaces": ["aws-blocks"],
+  "workspaces": [
+    "aws-blocks"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit",
     "spec": "blocks-generate-spec",

packages/create-blocks-app/templates/backend/package.json

@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "type": "module",
   "blocksTemplate": "backend",
+  "blocksTemplateDescription": "Backend-only — Blocks API + CDK, no frontend (bring your own client)",
   "engines": {
     "node": ">=22.0.0"
   },

packages/create-blocks-app/templates/bare/package.json

@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "type": "module",
   "blocksTemplate": "bare",
+  "blocksTemplateDescription": "Vite + lit-html frontend with a single greet() API (smallest starter)",
   "engines": {
     "node": ">=22.0.0"
   },

packages/create-blocks-app/templates/default/package.json

@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "type": "module",
   "blocksTemplate": "default",
+  "blocksTemplateDescription": "Vite + lit-html frontend with auth, DynamoDB, and realtime (safe default)",
   "engines": {
     "node": ">=22.0.0"
   },