create-cwa 0.1.0 → 2.0.0-alpha.1

package/.gitignore

@@ -0,0 +1,2 @@
+dist/
+node_modules/

package/dist/index.js

@@ -3,22 +3,51 @@ import { downloadTemplate } from 'giget';
 import fse from 'fs-extra';
 import fg from 'fast-glob';
 import { readFile, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import { randomBytes } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
-const MANIFEST_URL = 'https://raw.githubusercontent.com/components-web-app/components-web-app/main/cwa-manifest.json';
-async function fetchManifest() {
+const REPO = 'components-web-app/components-web-app';
+// The CLI and the template share a version: create-cwa X downloads the template at
+// tag vX, so an install is reproducible. `--ref <branch|tag>` overrides it, for
+// example `--ref main` for the latest unreleased template.
+const CLI_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    let ref = `v${CLI_VERSION}`;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--ref' && args[i + 1])
+            ref = args[++i];
+        else if (arg.startsWith('--ref='))
+            ref = arg.slice('--ref='.length);
+        else
+            positional.push(arg);
+    }
+    return { projectName: positional[0], ref };
+}
+async function fetchManifest(ref) {
+    let res;
     try {
-        const res = await fetch(MANIFEST_URL);
-        if (!res.ok)
-            throw new Error(`HTTP ${res.status}`);
-        return (await res.json());
+        res = await fetch(`https://raw.githubusercontent.com/${REPO}/${ref}/cwa-manifest.json`);
     }
     catch {
         throw new Error('Could not fetch the CWA manifest. Check your internet connection and try again.');
     }
+    if (res.status === 404) {
+        throw new Error(`No CWA template found at "${ref}". Check the --ref value.`);
+    }
+    if (!res.ok) {
+        throw new Error(`Could not fetch the CWA manifest (HTTP ${res.status}). Try again shortly.`);
+    }
+    try {
+        return (await res.json());
+    }
+    catch {
+        throw new Error(`The CWA manifest at "${ref}" is not valid JSON.`);
+    }
 }
 function checkCancel(value) {
     if (isCancel(value)) {
@@ -37,8 +66,7 @@ function run(cmd, args, cwd) {
     const result = spawnSync(cmd, args, { stdio: 'inherit', cwd });
     return result.status === 0;
 }
-async function askQuestions(manifest, argv) {
-    const targetArg = argv[2];
+async function askQuestions(manifest, targetArg) {
     const projectName = checkCancel(await text({
         message: 'Project name?',
         placeholder: 'my-cwa-app',
@@ -79,11 +107,11 @@ async function askQuestions(manifest, argv) {
     }));
     return { projectName: projectName.trim(), ci, features: [...resolved], fixtures };
 }
-async function downloadRepo(manifest, tempDir) {
+async function downloadRepo(manifest, ref, tempDir) {
     const s = spinner();
-    s.start('Downloading template...');
+    s.start(`Downloading template (${ref})...`);
     try {
-        await downloadTemplate(`github:${manifest.repo}#${manifest.branch}`, {
+        await downloadTemplate(`github:${manifest.repo}#${ref}`, {
             dir: tempDir,
             force: true,
         });
@@ -151,7 +179,7 @@ async function generateReadme(tempDir, answers) {
 Sample content is bundled. Load it after the API container is healthy:
 
 \`\`\`bash
-docker compose exec php bin/console doctrine:fixtures:load
+docker compose exec php bin/console doctrine:fixtures:load --append
 \`\`\`
 `
         : '';
@@ -166,25 +194,27 @@ ${featureList}
 ## Getting started
 
 \`\`\`bash
-# 1. Start the stack
-#    composer install, database wait, and migrations all run automatically
+# Start the stack. The php container runs composer install, waits for the
+# database and migrates; the app container installs the Nuxt dependencies and
+# runs the dev server. There is nothing to start by hand.
 docker compose up -d
 
-# 2. Install Nuxt app dependencies (run locally, not inside Docker)
-cd app
-pnpm install
-
-# 3. Start the dev server
-pnpm dev
+# Follow the Nuxt dev server
+docker compose logs -f app
 \`\`\`
 
+\`app/\` is mounted into the app container, so its \`node_modules\` is shared. Run
+\`pnpm install\` in \`app/\` yourself only if your editor needs the types locally.
+
 | URL | Description |
 |---|---|
 | https://localhost | Nuxt app |
 | https://localhost/_api | API (JSON-LD / HAL) |
-| https://localhost/admin | CWA admin panel |
+| https://localhost/login | Sign in to the CWA admin |
 
-> **SSL:** The dev stack uses self-signed certs. Accept the browser warning or trust the CA at \`api/frankenphp/caddy/certs/\`.
+> **SSL:** Caddy issues local certificates from its own CA. Accept the browser warning, or trust the CA once:
+> \`docker compose cp php:/data/caddy/pki/authorities/local/root.crt caddy-local-root.crt\`,
+> then add \`caddy-local-root.crt\` to your system or browser trust store.
 
 ${fixturesSection}
 ${ciSection}## Learn more
@@ -206,21 +236,22 @@ async function moveToTarget(tempDir, targetDir) {
 }
 async function main() {
     intro('create-cwa — Components Web App scaffolder');
+    const args = parseArgs(process.argv);
     const s = spinner();
     s.start('Fetching manifest...');
     let manifest;
     try {
-        manifest = await fetchManifest();
+        manifest = await fetchManifest(args.ref);
         s.stop('Manifest loaded.');
     }
     catch (err) {
         s.stop(err.message);
         process.exit(1);
     }
-    const answers = await askQuestions(manifest, process.argv);
+    const answers = await askQuestions(manifest, args.projectName);
     const targetDir = resolve(process.cwd(), answers.projectName);
     const tempDir = join(tmpdir(), `cwa-${randomBytes(6).toString('hex')}`);
-    await downloadRepo(manifest, tempDir);
+    await downloadRepo(manifest, args.ref, tempDir);
     const s2 = spinner();
     s2.start('Configuring project...');
     try {
@@ -252,7 +283,8 @@ async function main() {
         '  • waits for PostgreSQL to be ready',
         '  • runs database migrations',
         '',
-        'You only need to run pnpm install and pnpm dev locally.',
+        'The app container installs the Nuxt dependencies and runs the dev server,',
+        'so there is nothing to start by hand.',
         answers.fixtures
             ? '\nFixtures are NOT loaded automatically — you will be reminded below.'
             : '',
@@ -267,7 +299,7 @@ async function main() {
             log.step('Running: docker compose up -d');
             const ok = run('docker', ['compose', 'up', '-d'], targetDir);
             if (!ok) {
-                log.warn('docker compose up -d failed. Start it manually before running pnpm dev.');
+                log.warn('docker compose up -d failed. Run it manually from the project directory.');
             }
         }
     }
@@ -278,8 +310,8 @@ async function main() {
     const hasPnpm = commandExists('pnpm');
     if (hasPnpm) {
         const installDeps = checkCancel(await confirm({
-            message: 'Install Nuxt app dependencies now? (pnpm install in app/)',
-            initialValue: true,
+            message: 'Also install app/ dependencies on this machine, for editor type support? (the app container installs them either way)',
+            initialValue: false,
         }));
         if (installDeps) {
             log.step('Running: pnpm install');
@@ -293,18 +325,18 @@ async function main() {
         log.warn('pnpm not found — run: npm i -g pnpm, then pnpm install inside app/');
     }
     const outroLines = [
-        `Start the dev server:`,
-        `  cd ${answers.projectName}/app && pnpm dev`,
+        `The dev server runs in the app container. Follow it with:`,
+        `  cd ${answers.projectName} && docker compose logs -f app`,
         '',
         'Then visit:',
         '  https://localhost        — app',
         '  https://localhost/_api   — API',
-        '  https://localhost/admin  — admin panel',
+        '  https://localhost/login  — sign in to the admin',
     ];
     if (answers.fixtures) {
         outroLines.push('');
         outroLines.push('Load sample content (once the API container is healthy):');
-        outroLines.push('  docker compose exec php bin/console doctrine:fixtures:load');
+        outroLines.push('  docker compose exec php bin/console doctrine:fixtures:load --append');
     }
     outro(outroLines.join('\n'));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cwa",
-  "version": "0.1.0",
+  "version": "2.0.0-alpha.1",
   "description": "Create a new CWA (Components Web App) project",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
     "directory": "packages/create-cwa"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.13.0"
   },
   "dependencies": {
     "@clack/prompts": "^0.9.0",

package/src/index.ts

@@ -15,26 +15,55 @@ import { downloadTemplate } from 'giget'
 import fse from 'fs-extra'
 import fg from 'fast-glob'
 import { readFile, writeFile } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import { randomBytes } from 'node:crypto'
 import { spawnSync } from 'node:child_process'
 import type { Manifest, Answers } from './types.js'
 
-const MANIFEST_URL =
-  'https://raw.githubusercontent.com/components-web-app/components-web-app/main/cwa-manifest.json'
+const REPO = 'components-web-app/components-web-app'
+
+// The CLI and the template share a version: create-cwa X downloads the template at
+// tag vX, so an install is reproducible. `--ref <branch|tag>` overrides it, for
+// example `--ref main` for the latest unreleased template.
+const CLI_VERSION: string = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+).version
+
+function parseArgs(argv: string[]): { projectName?: string; ref: string } {
+  const args = argv.slice(2)
+  let ref = `v${CLI_VERSION}`
+  const positional: string[] = []
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--ref' && args[i + 1]) ref = args[++i]
+    else if (arg.startsWith('--ref=')) ref = arg.slice('--ref='.length)
+    else positional.push(arg)
+  }
+  return { projectName: positional[0], ref }
+}
 
-async function fetchManifest(): Promise<Manifest> {
+async function fetchManifest(ref: string): Promise<Manifest> {
+  let res: Response
   try {
-    const res = await fetch(MANIFEST_URL)
-    if (!res.ok) throw new Error(`HTTP ${res.status}`)
-    return (await res.json()) as Manifest
+    res = await fetch(`https://raw.githubusercontent.com/${REPO}/${ref}/cwa-manifest.json`)
   } catch {
     throw new Error(
       'Could not fetch the CWA manifest. Check your internet connection and try again.'
     )
   }
+  if (res.status === 404) {
+    throw new Error(`No CWA template found at "${ref}". Check the --ref value.`)
+  }
+  if (!res.ok) {
+    throw new Error(`Could not fetch the CWA manifest (HTTP ${res.status}). Try again shortly.`)
+  }
+  try {
+    return (await res.json()) as Manifest
+  } catch {
+    throw new Error(`The CWA manifest at "${ref}" is not valid JSON.`)
+  }
 }
 
 function checkCancel<T>(value: T | symbol): T {
@@ -57,9 +86,7 @@ function run(cmd: string, args: string[], cwd: string): boolean {
   return result.status === 0
 }
 
-async function askQuestions(manifest: Manifest, argv: string[]): Promise<Answers> {
-  const targetArg = argv[2]
-
+async function askQuestions(manifest: Manifest, targetArg?: string): Promise<Answers> {
   const projectName = checkCancel(
     await text({
       message: 'Project name?',
@@ -118,11 +145,11 @@ async function askQuestions(manifest: Manifest, argv: string[]): Promise<Answers
   return { projectName: projectName.trim(), ci, features: [...resolved], fixtures }
 }
 
-async function downloadRepo(manifest: Manifest, tempDir: string): Promise<void> {
+async function downloadRepo(manifest: Manifest, ref: string, tempDir: string): Promise<void> {
   const s = spinner()
-  s.start('Downloading template...')
+  s.start(`Downloading template (${ref})...`)
   try {
-    await downloadTemplate(`github:${manifest.repo}#${manifest.branch}`, {
+    await downloadTemplate(`github:${manifest.repo}#${ref}`, {
       dir: tempDir,
       force: true,
     })
@@ -206,7 +233,7 @@ async function generateReadme(tempDir: string, answers: Answers): Promise<void>
 Sample content is bundled. Load it after the API container is healthy:
 
 \`\`\`bash
-docker compose exec php bin/console doctrine:fixtures:load
+docker compose exec php bin/console doctrine:fixtures:load --append
 \`\`\`
 `
     : ''
@@ -222,25 +249,27 @@ ${featureList}
 ## Getting started
 
 \`\`\`bash
-# 1. Start the stack
-#    composer install, database wait, and migrations all run automatically
+# Start the stack. The php container runs composer install, waits for the
+# database and migrates; the app container installs the Nuxt dependencies and
+# runs the dev server. There is nothing to start by hand.
 docker compose up -d
 
-# 2. Install Nuxt app dependencies (run locally, not inside Docker)
-cd app
-pnpm install
-
-# 3. Start the dev server
-pnpm dev
+# Follow the Nuxt dev server
+docker compose logs -f app
 \`\`\`
 
+\`app/\` is mounted into the app container, so its \`node_modules\` is shared. Run
+\`pnpm install\` in \`app/\` yourself only if your editor needs the types locally.
+
 | URL | Description |
 |---|---|
 | https://localhost | Nuxt app |
 | https://localhost/_api | API (JSON-LD / HAL) |
-| https://localhost/admin | CWA admin panel |
+| https://localhost/login | Sign in to the CWA admin |
 
-> **SSL:** The dev stack uses self-signed certs. Accept the browser warning or trust the CA at \`api/frankenphp/caddy/certs/\`.
+> **SSL:** Caddy issues local certificates from its own CA. Accept the browser warning, or trust the CA once:
+> \`docker compose cp php:/data/caddy/pki/authorities/local/root.crt caddy-local-root.crt\`,
+> then add \`caddy-local-root.crt\` to your system or browser trust store.
 
 ${fixturesSection}
 ${ciSection}## Learn more
@@ -266,22 +295,23 @@ async function moveToTarget(tempDir: string, targetDir: string): Promise<void> {
 async function main(): Promise<void> {
   intro('create-cwa — Components Web App scaffolder')
 
+  const args = parseArgs(process.argv)
   const s = spinner()
   s.start('Fetching manifest...')
   let manifest: Manifest
   try {
-    manifest = await fetchManifest()
+    manifest = await fetchManifest(args.ref)
     s.stop('Manifest loaded.')
   } catch (err) {
     s.stop((err as Error).message)
     process.exit(1)
   }
 
-  const answers = await askQuestions(manifest, process.argv)
+  const answers = await askQuestions(manifest, args.projectName)
   const targetDir = resolve(process.cwd(), answers.projectName)
   const tempDir = join(tmpdir(), `cwa-${randomBytes(6).toString('hex')}`)
 
-  await downloadRepo(manifest, tempDir)
+  await downloadRepo(manifest, args.ref, tempDir)
 
   const s2 = spinner()
   s2.start('Configuring project...')
@@ -321,7 +351,8 @@ async function main(): Promise<void> {
       '  • waits for PostgreSQL to be ready',
       '  • runs database migrations',
       '',
-      'You only need to run pnpm install and pnpm dev locally.',
+      'The app container installs the Nuxt dependencies and runs the dev server,',
+      'so there is nothing to start by hand.',
       answers.fixtures
         ? '\nFixtures are NOT loaded automatically — you will be reminded below.'
         : '',
@@ -342,7 +373,7 @@ async function main(): Promise<void> {
       log.step('Running: docker compose up -d')
       const ok = run('docker', ['compose', 'up', '-d'], targetDir)
       if (!ok) {
-        log.warn('docker compose up -d failed. Start it manually before running pnpm dev.')
+        log.warn('docker compose up -d failed. Run it manually from the project directory.')
       }
     }
   } else {
@@ -354,8 +385,8 @@ async function main(): Promise<void> {
   if (hasPnpm) {
     const installDeps = checkCancel(
       await confirm({
-        message: 'Install Nuxt app dependencies now? (pnpm install in app/)',
-        initialValue: true,
+        message: 'Also install app/ dependencies on this machine, for editor type support? (the app container installs them either way)',
+        initialValue: false,
       })
     ) as boolean
 
@@ -371,19 +402,19 @@ async function main(): Promise<void> {
   }
 
   const outroLines = [
-    `Start the dev server:`,
-    `  cd ${answers.projectName}/app && pnpm dev`,
+    `The dev server runs in the app container. Follow it with:`,
+    `  cd ${answers.projectName} && docker compose logs -f app`,
     '',
     'Then visit:',
     '  https://localhost        — app',
     '  https://localhost/_api   — API',
-    '  https://localhost/admin  — admin panel',
+    '  https://localhost/login  — sign in to the admin',
   ]
 
   if (answers.fixtures) {
     outroLines.push('')
     outroLines.push('Load sample content (once the API container is healthy):')
-    outroLines.push('  docker compose exec php bin/console doctrine:fixtures:load')
+    outroLines.push('  docker compose exec php bin/console doctrine:fixtures:load --append')
   }
 
   outro(outroLines.join('\n'))

package/src/types.ts

@@ -26,6 +26,8 @@ export interface ManifestCi {
 export interface Manifest {
   version: string
   repo: string
+  // Read only by create-cwa 0.x, which downloads this branch. Newer versions download
+  // the tag matching their own version, or --ref.
   branch: string
   alwaysExclude: string[]
   questions: ManifestQuestion[]

package/dist/index.d.ts

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

package/dist/types.d.ts

@@ -1,36 +0,0 @@
-export interface ManifestChoice {
-    value: string;
-    label: string;
-    requires?: string[];
-}
-export interface ManifestQuestion {
-    id: string;
-    type: 'text' | 'select' | 'multiselect' | 'confirm';
-    message: string;
-    placeholder?: string;
-    hint?: string;
-    default?: boolean;
-    choices?: ManifestChoice[];
-}
-export interface ManifestFeature {
-    requires?: string[];
-    exclude: string[];
-}
-export interface ManifestCi {
-    exclude: string[];
-}
-export interface Manifest {
-    version: string;
-    repo: string;
-    branch: string;
-    alwaysExclude: string[];
-    questions: ManifestQuestion[];
-    features: Record<string, ManifestFeature>;
-    ci: Record<string, ManifestCi>;
-}
-export interface Answers {
-    projectName: string;
-    ci: string;
-    features: string[];
-    fixtures: boolean;
-}

package/dist/types.js

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