@adula/create-app 0.2.0-alpha.1 → 0.2.0-alpha.2

package/README.md

@@ -2,7 +2,8 @@
 
 Creates a complete, project-owned AdonisJS 7 application with adula, React/Inertia,
 shadcn/ui, authentication, administration and the managed business-design skill.
-Version 0.2.0-alpha.1 is **unreleased**; registry commands become available after publication.
+Version 0.2.0-alpha.2 is **experimental**, intended for the alpha channel.
+The owner-authorized latest alias remains on 0.2.0-alpha.1; next is absent.
 
 ```sh
 npm create @adula/app@alpha my-app
@@ -13,6 +14,28 @@ through an existing Docker installation with Compose. pnpm is bootstrapped throu
 npm and installed as a project-local development dependency; neither a global
 pnpm installation nor a pre-existing AdonisJS application is required.
 
+Use a lowercase directory such as `dental-gate`; the company display name can be
+`Dental-Gate`. The creator checks a supplied directory and Docker before asking
+for company details or creating project files.
+
+On Windows, setup checks native Docker, the standard Docker Desktop location,
+then Docker in the default WSL distribution. When WSL Docker is selected, Node.js
+and application files remain on Windows; Compose runs through `wsl.exe --exec`.
+The generated README records the matching service start/stop command.
+
+If Docker is absent, the interactive wizard asks for explicit permission before
+installing Docker Desktop using `winget`. Pressing Enter or answering no never
+installs software: you can supply an existing-services profile or cancel. Windows
+may request administrator approval or a restart; complete Docker Desktop setup
+and rerun the same command if needed. No application files/databases are created
+before the service preflight succeeds. `--yes` never authorizes host installation.
+On other operating systems, setup provides installation guidance and the existing
+services alternative. A stopped engine is detected separately and can be retried.
+Existing PostgreSQL 17 **and Redis** are supported via the connection profile below.
+
+Host installation references: [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/)
+and [WinGet install options](https://learn.microsoft.com/windows/package-manager/winget/install).
+
 The wizard requests the company name, administrator email and company identity.
 An optional identity JSON file contains `primaryColor` (six-digit hex), `logo`
 (local PNG/JPEG/WebP path relative to the JSON), `fontFamily` and `guidelines`.
@@ -58,6 +81,6 @@ runtime processes documented in the application README. SMTP, OAuth, S3, product
 hosting and off-site backups need real configuration; no external accounts are
 created. Node.js and Docker themselves are host prerequisites.
 
-Before publication, run the packed CLI with npm exec and `--packages` pointing
+For local archive verification, run the packed CLI with npm exec and `--packages` pointing
 to the directory containing matching `adula-kit-VERSION.tgz` and
 `adula-ui-VERSION.tgz`. `pnpm test:create` exercises this path from an empty folder.

package/build/cli.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Progress } from './progress.mjs'
+import { prepareDocker } from './prerequisites.mjs'
 import { parseArgs } from 'node:util'
 import { createInterface } from 'node:readline/promises'
 import { randomBytes } from 'node:crypto'
@@ -117,6 +118,15 @@ export async function main(argv = process.argv.slice(2)) {
   let email = values['admin-email']
   let identityFile = values.identity
   const interactive = process.stdin.isTTY && !values.yes
+  // Reject a supplied destination before collecting company details.
+  if (directory) {
+    projectName(resolve(directory))
+    await assertEmpty(resolve(directory))
+  }
+  if (!interactive && (!directory || !company || !email))
+    throw new Error('Provide a directory, --company and --admin-email, or run interactively.')
+  // Host prerequisites must pass before prompts, package setup or project writes.
+  let docker
   if (interactive) {
     const prompt = createInterface({
       input: process.stdin,
@@ -124,6 +134,28 @@ export async function main(argv = process.argv.slice(2)) {
     })
     try {
       directory ||= await prompt.question('Application directory: ')
+      projectName(resolve(directory))
+      await assertEmpty(resolve(directory))
+      if (values.services === 'docker') {
+        const services = await prepareDocker({
+          question: (message) => prompt.question(message),
+          execute: async (command, args) => {
+            prompt.pause()
+            try {
+              await run(command, args)
+            } finally {
+              prompt.resume()
+            }
+          },
+        })
+        if (services.connection) {
+          values.services = 'existing'
+          values.connection = services.connection
+        } else {
+          docker = services.docker
+          console.log(`Docker is ready (${docker.display}). Continuing setup.`)
+        }
+      }
       company ||= await prompt.question('Company name as it should appear in the application: ')
       email ||= await prompt.question('Administrator email: ')
       identityFile ||= await prompt.question(
@@ -132,6 +164,8 @@ export async function main(argv = process.argv.slice(2)) {
     } finally {
       prompt.close()
     }
+  } else if (values.services === 'docker') {
+    docker = (await prepareDocker()).docker
   }
   if (!directory || !company || !email)
     throw new Error('Provide a directory, --company and --admin-email, or run interactively.')
@@ -166,8 +200,6 @@ export async function main(argv = process.argv.slice(2)) {
   try {
     progress.start('Check services and prepare configuration')
     if (values.services === 'docker') {
-      await run('docker', ['compose', 'version'], { env, quiet: true })
-      await run('docker', ['info'], { env, quiet: true })
       profile = {
         postgres: {
           host: '127.0.0.1',
@@ -255,7 +287,7 @@ export async function main(argv = process.argv.slice(2)) {
     await writeNew(
       target,
       'README.md',
-      `# ${name}\n\nCreated with @adula/create-app ${template.version}. Node.js 24+ is required.\n\n## Local development\n\n\`\`\`sh\nnpm run dev\n\`\`\`\n\nOpen ${appEnv.APP_URL}. Administrator credentials are in ignored tmp/dev-admin.txt. After signing in, open /admin/setup and follow docs/initial-setup.md to review identity and verify service readiness.\nRun workers separately with node ace adula:worker, the outbox dispatcher with node ace adula:outbox, and the scheduler with node ace scheduler:run.\n\n${values.services === 'docker' ? 'PostgreSQL 17 and Redis 7 run in Docker. Start them with docker compose up -d --wait; stop with docker compose stop. Named volumes retain data; never use down -v unless deliberately deleting the local databases.' : 'PostgreSQL 17 and Redis use your existing services. Installation created fresh databases; keep .env and .env.test private.'}\n\n## Verification\n\nRun npm run typecheck, npm test, npm run lint and npm run build. Tests use the separate *_test database and a distinct Redis namespace.\n\n## Company identity\n\nRead docs/design-identity.md and the managed design skill before changing UI. Source files and shadcn components belong to this application.\n\n## External services and production\n\nLocal file storage is enabled. SMTP (including a local relay), OAuth provider credentials, S3, off-site backups, and production deployment need actual destination configuration. The creator does not enable unconfigured external services. Production requires backup variables validated in start/env.ts.\n\n## Incomplete installation\n\nReview the reported failing step; files and databases are retained. After resolving it, use npm exec --yes --package=pnpm@11.19.0 -- pnpm install, node ace migration:run, and node ace adula:setup. Setup reads tmp/dev-admin.txt; it refuses to promote an existing account with a different password. Then run node ace adula:doctor and npm run build. Never recreate over a nonempty directory.\n`
+      `# ${name}\n\nCreated with @adula/create-app ${template.version}. Node.js 24+ is required.\n\n## Local development\n\n\`\`\`sh\nnpm run dev\n\`\`\`\n\nOpen ${appEnv.APP_URL}. Administrator credentials are in ignored tmp/dev-admin.txt. After signing in, open /admin/setup and follow docs/initial-setup.md to review identity and verify service readiness.\nRun workers separately with node ace adula:worker, the outbox dispatcher with node ace adula:outbox, and the scheduler with node ace scheduler:run.\n\n${values.services === 'docker' ? `PostgreSQL 17 and Redis 7 run in Docker. Start them with ${docker.display} compose up -d --wait; stop with ${docker.display} compose stop. Named volumes retain data; never use down -v unless deliberately deleting the local databases.` : 'PostgreSQL 17 and Redis use your existing services. Installation created fresh databases; keep .env and .env.test private.'}\n\n## Verification\n\nRun npm run typecheck, npm test, npm run lint and npm run build. Tests use the separate *_test database and a distinct Redis namespace.\n\n## Company identity\n\nRead docs/design-identity.md and the managed design skill before changing UI. Source files and shadcn components belong to this application.\n\n## External services and production\n\nLocal file storage is enabled. SMTP (including a local relay), OAuth provider credentials, S3, off-site backups, and production deployment need actual destination configuration. The creator does not enable unconfigured external services. Production requires backup variables validated in start/env.ts.\n\n## Incomplete installation\n\nReview the reported failing step; files and databases are retained. After resolving it, use npm exec --yes --package=pnpm@11.19.0 -- pnpm install, node ace migration:run, and node ace adula:setup. Setup reads tmp/dev-admin.txt; it refuses to promote an existing account with a different password. Then run node ace adula:doctor and npm run build. Never recreate over a nonempty directory.\n`
     )
     await writeNew(target, 'tmp/install.log', '', true)
     const options = {
@@ -269,8 +301,18 @@ export async function main(argv = process.argv.slice(2)) {
     if (values.services === 'docker') {
       await writeNew(target, 'compose.yaml', composeFile())
       await run(
-        'docker',
-        ['compose', '--env-file', '.env', 'up', '-d', '--wait', '--wait-timeout', '120'],
+        docker.command,
+        [
+          ...docker.prefix,
+          'compose',
+          '--env-file',
+          '.env',
+          'up',
+          '-d',
+          '--wait',
+          '--wait-timeout',
+          '120',
+        ],
         options
       )
       await pingRedis(profile.redis)
@@ -324,7 +366,7 @@ export async function main(argv = process.argv.slice(2)) {
 if (process.argv[1] && import.meta.url === pathToFileURL(await realpath(process.argv[1])).href)
   main().catch((error) => {
     console.error(
-      `\nSetup did not complete: ${error.message}\nCreated files and databases are retained so you can inspect and resume setup.`
+      `\nSetup did not complete: ${error.message}\nIf setup created files or databases, they have been retained for inspection. See the generated README for recovery steps.`
     )
     process.exitCode = 1
   })

package/build/prerequisites.mjs

@@ -0,0 +1,71 @@
+import { checkDocker, run } from './system.mjs'
+
+/** Never install host software in unattended mode or without explicit consent. */
+export async function prepareDocker({
+  question = undefined,
+  detect = checkDocker,
+  execute = run,
+  platform = process.platform,
+} = {}) {
+  try {
+    return { docker: await detect() }
+  } catch (error) {
+    if (!question) throw error
+    if (error.code === 'DOCKER_STOPPED') {
+      const answer = await question(
+        `${error.message}\nStart the engine, then press Enter to retry (or type cancel): `
+      )
+      if (answer.trim().toLowerCase() === 'cancel')
+        throw new Error('Setup cancelled before project creation.')
+      return { docker: await detect() }
+    }
+    if (error.code !== 'DOCKER_MISSING') throw error
+    if (platform === 'win32') {
+      const consent = await question(
+        'Docker was not found. Install Docker Desktop using winget? Windows may request administrator approval or a restart. Docker license terms remain in the installer. [y/N]: '
+      )
+      if (/^(y|yes)$/i.test(consent.trim())) {
+        try {
+          await execute('winget', [
+            'install',
+            '--id',
+            'Docker.DockerDesktop',
+            '--exact',
+            '--source',
+            'winget',
+            '--interactive',
+          ])
+        } catch {
+          throw new Error(
+            'Docker Desktop installation did not complete. Review the installer output. If Windows requests a restart, restart and rerun the same npm create command. If winget is unavailable, install Docker Desktop from https://docs.docker.com/desktop/setup/install/windows-install/ . No application files or databases have been created.'
+          )
+        }
+        const answer = await question(
+          'Open Docker Desktop, complete its setup and wait for the engine. Press Enter when ready, or type restart to exit and rerun this command after restarting Windows: '
+        )
+        if (answer.trim().toLowerCase() === 'restart')
+          throw new Error(
+            'Restart Windows, start Docker Desktop, then rerun the same npm create command. No application files or databases have been created.'
+          )
+        try {
+          return { docker: await detect() }
+        } catch {
+          throw new Error(
+            'Docker is not ready yet. Complete Docker Desktop setup, restart Windows if requested, then rerun the same npm create command. No application files or databases have been created.'
+          )
+        }
+      }
+    } else {
+      // Host installation differs by OS/distro; do not guess a privileged script.
+      console.log(error.message)
+    }
+    const connection = (
+      await question(
+        'Use existing PostgreSQL 17 and Redis instead? Enter the connection JSON path, or press Enter to cancel: '
+      )
+    ).trim()
+    if (!connection)
+      throw new Error('Setup cancelled before project creation. No software was installed.')
+    return { connection }
+  }
+}

package/build/project.mjs

@@ -5,7 +5,7 @@ export function projectName(target) {
   const name = basename(resolve(target))
   if (!/^[a-z][a-z0-9-]{0,49}$/.test(name))
     throw new Error(
-      'Project directory name must start with a lowercase letter and use lowercase letters, digits or hyphens (up to 50 characters).'
+      'Project directory name must start with a lowercase letter and use lowercase letters, digits or hyphens (up to 50 characters). For example, use dental-gate for the directory; the company display name can still be Dental-Gate.'
     )
   return name
 }

package/build/system.mjs

@@ -41,6 +41,65 @@ export async function run(
   }
 }
 
+export async function checkDocker(execute = run, platform = process.platform) {
+  const alternative =
+    'Alternatively, use --services existing --connection ./local.json with PostgreSQL 17 and Redis (see the creator README).'
+  let command = 'docker'
+  let prefix = []
+  try {
+    await execute('docker', ['compose', 'version'], { quiet: true })
+  } catch {
+    if (platform === 'win32') {
+      try {
+        // A newly installed Docker Desktop may not be in this process's PATH yet.
+        command = join(
+          process.env.ProgramFiles ?? 'C:\\Program Files',
+          'Docker/Docker/resources/bin/docker.exe'
+        )
+        await execute(command, ['compose', 'version'], { quiet: true })
+      } catch {
+        try {
+          command = 'wsl.exe'
+          prefix = ['--exec', 'docker']
+          await execute(command, [...prefix, 'compose', 'version'], { quiet: true })
+        } catch {
+          throw Object.assign(
+            new Error(
+              'Docker with Compose was not found in PowerShell or the default WSL distribution. Install and start Docker Desktop, or provide Docker with Compose in your default WSL distribution. ' +
+                alternative
+            ),
+            { code: 'DOCKER_MISSING' }
+          )
+        }
+      }
+    } else {
+      throw Object.assign(
+        new Error(
+          'Docker with Compose is required. Install Docker and Compose, then verify docker compose version. ' +
+            alternative
+        ),
+        { code: 'DOCKER_MISSING' }
+      )
+    }
+  }
+  try {
+    await execute(command, [...prefix, 'info'], { quiet: true })
+  } catch {
+    throw Object.assign(
+      new Error(
+        `Docker Compose is available, but the Docker engine is not reachable. Start Docker Desktop or your Docker service and verify ${[command, ...prefix, 'info'].join(' ')} in this terminal. ` +
+          alternative
+      ),
+      { code: 'DOCKER_STOPPED' }
+    )
+  }
+  return {
+    command,
+    prefix,
+    display: [command.includes(' ') ? `& "${command}"` : command, ...prefix].join(' '),
+  }
+}
+
 export async function packageManager() {
   // Keep the installer outside the project whose dependency tree it updates.
   // Direct JavaScript entries also avoid shell interpretation on Windows.