create-quadrokit 0.2.6 → 0.2.8

package/README.md

@@ -16,17 +16,18 @@ bun create-quadrokit/src/index.ts --template dashboard --dir /path/to/my-app
 | `--template <name>` | `dashboard` \| `website` \| `ecommerce` \| `admin-shell` |
 | `--dir <path>` | Target directory relative to cwd (created; must be empty if it already exists) |
 | `--name <name>` | Same as `--dir` (project folder name); ignored if `--dir` is set |
-| `-y` / `--yes` | Non-interactive: requires `--template`; uses `quadro-<template>` as the directory unless `--dir` / `--name` is set; runs git init and install without prompting (override with `--no-git` / `--no-install`) |
+| `-y` / `--yes` | Non-interactive: requires `--template`; uses `quadro-<template>` as the directory unless `--dir` / `--name` is set; copies `.env.example` → `.env`, runs git init and install without prompting (override with `--no-copy-env` / `--no-git` / `--no-install`) |
 | `-h` / `--help` | Print usage and exit |
 | `--keep-workspace` | Keep `workspace:*` in `package.json` (for development inside the QuadroKit monorepo only) |
 | `--git` / `--no-git` | Initialize a git repo after scaffolding (skip the prompt) |
 | `--install` / `--no-install` | Run `bun install` or `npm install` after scaffolding (skip the prompt) |
+| `--copy-env` / `--no-copy-env` | Copy `.env.example` to `.env` after scaffolding (skip the prompt) |
 
 The banner shows **create-quadrokit**’s package version (e.g. `v0.2.2`).
 
 On start, the CLI prints a short **prerequisites** check (Node.js, Bun, Git). Node 18+ is required; Bun is optional (falls back to npm for installs). Git is only needed if you choose to init a repository.
 
-Interactive mode: run without `--template` / `--dir` / `--name` to be prompted. If the project directory already exists and is **not empty**, you are asked again for a different name. You are then asked about **git** and **install** unless `-y` or the explicit flags above apply.
+Interactive mode: run without `--template` / `--dir` / `--name` to be prompted. If the project directory already exists and is **not empty**, you are asked again for a different name. You are then asked whether to copy **`.env.example` → `.env`**, then about **git** and **install**, unless `-y` or the explicit flags above apply.
 
 ## What it does
 
@@ -36,7 +37,8 @@ Interactive mode: run without `--template` / `--dir` / `--name` to be prompted.
 4. Removes `@quadrokit/sample-client` and rewrites `workspace:*` on `@quadrokit/*` deps to `^<version>` matching **create-quadrokit**’s own `package.json` `version` (run `bun run version:set` at repo root to bump public packages) unless `--keep-workspace`.
 5. Writes `QUADROKIT.md` with proxy and `quadrokit:generate` instructions. Does **not** copy `.quadrokit/generated` — run `bun run quadrokit:generate` after install.
 6. Adds a root `.gitignore` (unless the template already shipped one).
-7. Optionally runs `git init` and installs dependencies (`bun` if available, otherwise `npm`).
+7. Optionally copies `.env.example` to `.env` (prompt, or defaults with `-y`; use `--no-copy-env` to skip).
+8. Optionally runs `git init` and installs dependencies (`bun` if available, otherwise `npm`).
 
 ## Published usage (future)
 

package/dist/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { copyFile, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import prompts from 'prompts';
@@ -63,11 +63,14 @@ Options:
   --dir <path>          Project directory (relative to cwd; must not exist or be empty)
   --name <name>         Same as --dir when --dir is omitted
   -y, --yes             Non-interactive: requires --template; uses quadro-<template> as directory
-                        unless --dir / --name; runs git init + install (override with --no-git / --no-install)
+                        unless --dir / --name; copies .env.example → .env, runs git init + install
+                        (override with --no-copy-env / --no-git / --no-install)
   --git                 Initialize a git repository (skips prompt)
   --no-git              Do not run git init
   --install             Install dependencies after scaffold (skips prompt)
   --no-install          Do not install dependencies
+  --copy-env            Copy .env.example to .env (skips prompt)
+  --no-copy-env         Do not copy .env.example to .env
   --keep-workspace      Keep workspace:* @quadrokit deps (monorepo development only)
   -h, --help            Show this help
 
@@ -130,6 +133,7 @@ function parseArgs(argv) {
     /** `undefined` = prompt later (unless yes) */
     let initGit;
     let installDeps;
+    let copyEnvFile;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--template' && argv[i + 1]) {
@@ -159,11 +163,17 @@ function parseArgs(argv) {
         else if (a === '--no-install') {
             installDeps = false;
         }
+        else if (a === '--copy-env') {
+            copyEnvFile = true;
+        }
+        else if (a === '--no-copy-env') {
+            copyEnvFile = false;
+        }
     }
     if (!dir && name) {
         dir = name;
     }
-    return { template, dir, keepWorkspace, yes, initGit, installDeps };
+    return { template, dir, keepWorkspace, yes, initGit, installDeps, copyEnvFile };
 }
 async function pathExists(p) {
     try {
@@ -334,7 +344,7 @@ Created with **create-quadrokit** (template: \`${template}\`).
 ## Next steps
 
 1. \`cd ${path.basename(dest)}\` and install dependencies (\`bun install\` or \`npm install\`).
-2. Copy \`.env.example\` to \`.env\` and set \`VITE_4D_ORIGIN\` to your 4D web server (used for the dev proxy and as the default catalog origin for generate).
+2. If \`.env\` is missing, copy \`.env.example\` to \`.env\`. Set \`VITE_4D_ORIGIN\` to your 4D web server (used for the dev proxy and as the default catalog origin for generate). The scaffold CLI can copy this file for you when asked.
 
 3. Generate the typed REST client (required before \`dev\` / \`build\`). The CLI is \`quadrokit-client\` from \`@quadrokit/client\` (reads \`.env\` in the project cwd for defaults):
 
@@ -344,7 +354,7 @@ Created with **create-quadrokit** (template: \`${template}\`).
 
    Same as \`quadrokit-client generate\`. One-off (no local install): \`bunx -p @quadrokit/client quadrokit-client generate\` (or \`bunx quadrokit-client generate\`).
 
-   Default catalog URL: \`\${VITE_4D_ORIGIN}/rest/\\$catalog\`, or \`http://127.0.0.1:7080/rest/\\$catalog\` if unset. Generator-only \`.env\` keys (not used by the browser):
+   Default catalog URL: \`\${VITE_4D_ORIGIN}/rest/\\$catalog/\\$all\`, or \`http://127.0.0.1:7080/rest/\\$catalog/\\$all\` if unset (plain \`/rest/\\$catalog\` omits attributes — use \`/\\$all\`). Generator-only \`.env\` keys (not used by the browser):
 
    - \`QUADROKIT_ACCESS_KEY\` — multipart \`accessKey\` to \`/api/login\`; then \`4DAdminSID\` for the catalog request.
    - \`QUADROKIT_LOGIN_URL\` — full login URL if not \`\${catalog origin}/api/login\`.
@@ -358,6 +368,22 @@ Production: serve the SPA and reverse-proxy \`/rest\` to 4D on the **same host**
 `;
     await writeFile(path.join(dest, 'QUADROKIT.md'), text, 'utf8');
 }
+/** Copy `.env.example` → `.env` when the latter does not exist. */
+async function copyEnvExampleToEnv(dest) {
+    const from = path.join(dest, '.env.example');
+    const to = path.join(dest, '.env');
+    if (!(await pathExists(from))) {
+        console.warn('  ⚠️  .env.example missing — skipped env copy.\n');
+        return false;
+    }
+    if (await pathExists(to)) {
+        console.log('  ⚠️  .env already exists — skipped copying .env.example.\n');
+        return false;
+    }
+    await copyFile(from, to);
+    console.log('  ✅  Copied .env.example → .env\n');
+    return true;
+}
 async function writeGitignore(dest) {
     const p = path.join(dest, '.gitignore');
     if (await pathExists(p)) {
@@ -385,7 +411,7 @@ async function main() {
         printHelp(readPackageVersion());
         process.exit(0);
     }
-    const { template: tArg, dir: dirArg, keepWorkspace, yes: yesFlag, initGit: gitFlag, installDeps: installFlag, } = parseArgs(argv);
+    const { template: tArg, dir: dirArg, keepWorkspace, yes: yesFlag, initGit: gitFlag, installDeps: installFlag, copyEnvFile: copyEnvFlag, } = parseArgs(argv);
     printWelcome(readPackageVersion());
     const prereqs = checkPrereqs();
     printPrereqReport(prereqs);
@@ -427,6 +453,28 @@ async function main() {
     await writeReadme(dest, template);
     await writeGitignore(dest);
     console.log(`\n  🎉  Project files are ready at ${'\u001b[1m'}${dest}${'\u001b[0m'}\n`);
+    let copyEnv = copyEnvFlag;
+    if (copyEnv === undefined) {
+        if (yesFlag) {
+            copyEnv = true;
+        }
+        else {
+            const envPrompt = await prompts({
+                type: 'confirm',
+                name: 'v',
+                message: 'Copy .env.example to .env?',
+                initial: true,
+            });
+            if (typeof envPrompt.v !== 'boolean') {
+                process.exit(1);
+            }
+            copyEnv = envPrompt.v;
+        }
+    }
+    let envCopiedOk = false;
+    if (copyEnv) {
+        envCopiedOk = await copyEnvExampleToEnv(dest);
+    }
     let initGit = gitFlag;
     if (initGit === undefined) {
         if (yesFlag) {
@@ -493,10 +541,21 @@ async function main() {
     const pm = prereqs.bunOk ? 'bun' : 'npm';
     const runDev = prereqs.bunOk ? 'bun run dev' : 'npm run dev';
     const installLine = installDeps ? `    →  ${runDev}` : `    →  ${pm} install\n    →  ${runDev}`;
+    const hasEnvFile = await pathExists(path.join(dest, '.env'));
+    let envHint;
+    if (envCopiedOk || hasEnvFile) {
+        envHint = `    →  Set VITE_4D_ORIGIN in .env (if needed)`;
+    }
+    else if (!copyEnv) {
+        envHint = `    →  Copy .env.example → .env and set VITE_4D_ORIGIN`;
+    }
+    else {
+        envHint = `    →  Create .env from .env.example and set VITE_4D_ORIGIN`;
+    }
     console.log(`  🚀🚀  Next steps
     →  cd ${path.basename(dest)}
 ${installLine}
-    →  Copy .env.example → .env and set VITE_4D_ORIGIN
+${envHint}
 
   Happy building! ✨
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quadrokit",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Scaffold a QuadroKit Vite + React app from a template",
   "type": "module",
   "bin": "./dist/index.mjs",

package/template-common/.env.example

@@ -1,7 +1,7 @@
 # Origin of your 4D web server (REST). The Vite dev server proxies /rest here.
 VITE_4D_ORIGIN=http://127.0.0.1:7080
 
-# Generator only (quadrokit:generate): multipart accessKey → 4DAdminSID cookie for fetching /rest/$catalog.
+# Generator only (quadrokit:generate): multipart accessKey → 4DAdminSID cookie for fetching /rest/$catalog/$all.
 # Not used by the browser runtime.
 # QUADROKIT_ACCESS_KEY=
 # QUADROKIT_LOGIN_URL=https://127.0.0.1:7443/api/login