create-quadrokit 0.2.0 → 0.2.2

package/README.md

@@ -16,16 +16,20 @@ bun create-quadrokit/src/index.ts --template dashboard --dir /path/to/my-app
 | `--template <name>` | `dashboard` \| `website` \| `ecommerce` \| `admin-shell` |
 | `--dir <path>` | Target directory (created; must be empty) |
 | `--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) |
 
-Interactive mode: run without `--template` / `--dir` to be prompted.
+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` to be prompted for those; you are then asked about **git** and **install** unless overridden with the flags above.
 
 ## What it does
 
-1. Copies the chosen template from `create-quadrokit/templates/<name>` when installed from npm, or `packages/templates/<name>` when you run the CLI from the monorepo (skips `node_modules`, `dist`).
-2. Copies `packages/sample-client/generated` → `<dir>/.quadrokit/generated`.
-3. Rewrites `src/lib/quadro-client.ts` to import from `../../.quadrokit/generated/client.gen.js`.
-4. Removes `@quadrokit/sample-client` and rewrites other `workspace:*` deps to `^0.2.0` (unless `--keep-workspace`).
-5. Writes `QUADROKIT.md` with proxy and `quadrokit-client generate` instructions.
+1. Copies the chosen template from `create-quadrokit/templates/<name>` when installed from npm, or `packages/templates/<name>` when you run the CLI from the monorepo (skips `node_modules`, `dist`, `.quadrokit`, lockfiles).
+2. Rewrites `src/lib/quadro-client.ts` to import from `../../.quadrokit/generated/client.gen.js`.
+3. 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`.
+4. Writes `QUADROKIT.md` with proxy and `quadrokit:generate` instructions. Does **not** copy `.quadrokit/generated` — run `bun run quadrokit:generate` after install.
+5. Optionally runs `git init` and installs dependencies (`bun` if available, otherwise `npm`).
 
 ## Published usage (future)
 

package/dist/{index.js → index.mjs}

@@ -1,8 +1,58 @@
 #!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { cp, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import prompts from 'prompts';
+const MIN_NODE_MAJOR = 18;
+function cmdVersion(cmd, args) {
+    const r = spawnSync(cmd, args, { encoding: 'utf8', shell: false });
+    if (r.error || r.status !== 0)
+        return null;
+    const line = r.stdout.trim().split('\n')[0];
+    return line || null;
+}
+function nodeMajor() {
+    const m = /^v?(\d+)/.exec(process.version);
+    return m ? Number(m[1]) : 0;
+}
+function checkPrereqs() {
+    const nodeVersion = process.version;
+    const nodeOk = nodeMajor() >= MIN_NODE_MAJOR;
+    const bunVersion = cmdVersion('bun', ['--version']);
+    const gitVersion = cmdVersion('git', ['--version']);
+    return {
+        nodeOk,
+        nodeVersion,
+        bunOk: bunVersion !== null,
+        bunVersion,
+        gitOk: gitVersion !== null,
+        gitVersion,
+    };
+}
+function printWelcome() {
+    console.log(`
+  ${'✨'.repeat(2)}  ${'\u001b[1mcreate-quadrokit\u001b[0m'}  ${'✨'.repeat(2)}
+  ${'🚀'.repeat(2)}  Scaffold a QuadroKit Vite + React app for 4D REST
+`);
+}
+function printPrereqReport(p) {
+    console.log('  Prerequisites');
+    const line = (ok, emoji, label, detail) => {
+        const mark = ok ? '✅' : '⚠️ ';
+        console.log(`    ${mark} ${emoji}  ${label}: ${detail}`);
+    };
+    line(p.nodeOk, '📗', 'Node.js', p.nodeOk ? p.nodeVersion : `${p.nodeVersion} (need >= ${MIN_NODE_MAJOR})`);
+    line(p.bunOk, '🥟', 'Bun', p.bunVersion ?? 'not found (you can use npm install instead)');
+    line(p.gitOk, '📌', 'Git', p.gitVersion ?? 'not found (needed only to init a repository)');
+    console.log('');
+}
+async function runInDir(cwd, cmd, args) {
+    const shell = process.platform === 'win32';
+    const r = spawnSync(cmd, args, { cwd, stdio: 'inherit', shell });
+    return r.status === 0;
+}
 const TEMPLATES = ['dashboard', 'website', 'ecommerce', 'admin-shell'];
 /** Directory of the create-quadrokit package (works when installed under node_modules). */
 function packageRoot() {
@@ -32,22 +82,13 @@ async function resolveBiomeJsonPath() {
     }
     return null;
 }
-async function resolveGeneratedClientDir() {
-    const pkg = packageRoot();
-    const bundled = path.join(pkg, 'vendor', 'generated');
-    if (await pathExists(bundled)) {
-        return bundled;
-    }
-    const monorepo = path.join(pkg, '..', 'packages', 'sample-client', 'generated');
-    if (await pathExists(monorepo)) {
-        return monorepo;
-    }
-    return null;
-}
 function parseArgs(argv) {
     let template;
     let dir;
     let keepWorkspace = false;
+    /** `undefined` = prompt later */
+    let initGit;
+    let installDeps;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--template' && argv[i + 1]) {
@@ -59,8 +100,20 @@ function parseArgs(argv) {
         else if (a === '--keep-workspace') {
             keepWorkspace = true;
         }
+        else if (a === '--git') {
+            initGit = true;
+        }
+        else if (a === '--no-git') {
+            initGit = false;
+        }
+        else if (a === '--install') {
+            installDeps = true;
+        }
+        else if (a === '--no-install') {
+            installDeps = false;
+        }
     }
-    return { template, dir, keepWorkspace };
+    return { template, dir, keepWorkspace, initGit, installDeps };
 }
 async function pathExists(p) {
     try {
@@ -71,11 +124,22 @@ async function pathExists(p) {
         return false;
     }
 }
+const SKIP_TEMPLATE_NAMES = new Set([
+    'node_modules',
+    'dist',
+    '.turbo',
+    '.quadrokit',
+    'bun.lock',
+    'bun.lockb',
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+]);
 async function copyTemplate(src, dest) {
     await mkdir(dest, { recursive: true });
     const entries = await readdir(src, { withFileTypes: true });
     for (const e of entries) {
-        if (e.name === 'node_modules' || e.name === 'dist' || e.name === '.turbo') {
+        if (SKIP_TEMPLATE_NAMES.has(e.name)) {
             continue;
         }
         const from = path.join(src, e.name);
@@ -88,15 +152,29 @@ async function copyTemplate(src, dest) {
         }
     }
 }
+/** Caret range for published @quadrokit/* deps (matches create-quadrokit release line). */
+function quadrokitPublishedSemverRange() {
+    try {
+        const raw = readFileSync(path.join(packageRoot(), 'package.json'), 'utf8');
+        const v = JSON.parse(raw).version;
+        if (v)
+            return `^${v}`;
+    }
+    catch {
+        /* ignore */
+    }
+    return '^0.0.0';
+}
 function rewriteWorkspaceDeps(pkg) {
+    const range = quadrokitPublishedSemverRange();
     for (const key of ['dependencies', 'devDependencies']) {
         const deps = pkg[key];
         if (!deps) {
             continue;
         }
         for (const name of Object.keys(deps)) {
-            if (deps[name] === 'workspace:*') {
-                deps[name] = '^0.2.0';
+            if (deps[name] === 'workspace:*' && name.startsWith('@quadrokit/')) {
+                deps[name] = range;
             }
         }
     }
@@ -141,23 +219,13 @@ async function writeStandaloneBiome(dest, keepWorkspace) {
 }
 async function writeQuadroClientImport(dest) {
     const p = path.join(dest, 'src', 'lib', 'quadro-client.ts');
-    const body = `import { createClient } from '../../.quadrokit/generated/client.gen.js';
+    const body = `import { createClient } from '../../.quadrokit/generated/client.gen.mjs';
 
 /** Same-origin \`/rest\` in dev (Vite proxy) and production (reverse proxy). */
 export const quadro = createClient({ baseURL: '/rest' });
 `;
     await writeFile(p, body, 'utf8');
 }
-async function seedGenerated(dest) {
-    const genSrc = await resolveGeneratedClientDir();
-    const genDest = path.join(dest, '.quadrokit', 'generated');
-    if (!genSrc) {
-        console.warn('Warning: sample generated client not found — run `quadrokit-client generate` after install.');
-        return;
-    }
-    await mkdir(path.join(dest, '.quadrokit'), { recursive: true });
-    await cp(genSrc, genDest, { recursive: true });
-}
 async function writeReadme(dest, template) {
     const text = `# ${path.basename(dest)}
 
@@ -165,14 +233,20 @@ Created with **create-quadrokit** (template: \`${template}\`).
 
 ## Next steps
 
-1. \`cd ${path.basename(dest)}\` and \`bun install\`
-2. Copy \`.env.example\` to \`.env\` and set \`VITE_4D_ORIGIN\` to your 4D web server.
-3. Regenerate the typed client when your REST catalog changes:
+1. \`cd ${path.basename(dest)}\` and install dependencies (\`bun install\` or \`npm install\`).
+2. Generate the typed REST client (required before \`dev\` / \`build\`):
+
+   \`\`\`bash
+   bun run quadrokit:generate
+   \`\`\`
+
+   This uses \`assets/catalog.placeholder.json\` by default (demo catalog from QuadroKit). Point at your live 4D catalog:
 
    \`\`\`bash
-   bunx quadrokit-client generate --url "http://localhost:7080/rest/\\$catalog" --token YOUR_TOKEN --out .quadrokit/generated
+   QUADROKIT_CATALOG_URL='http://localhost:7080/rest/\\$catalog' QUADROKIT_CATALOG_TOKEN='…' bun run quadrokit:generate
    \`\`\`
 
+3. Copy \`.env.example\` to \`.env\` and set \`VITE_4D_ORIGIN\` to your 4D web server.
 4. \`bun run dev\` — the dev server proxies \`/rest\` to \`VITE_4D_ORIGIN\` so **4DSID_** cookies stay same-origin.
 
 Production: serve the SPA and reverse-proxy \`/rest\` to 4D on the **same host** as the UI.
@@ -181,7 +255,14 @@ Production: serve the SPA and reverse-proxy \`/rest\` to 4D on the **same host**
 }
 async function main() {
     const argv = process.argv.slice(2);
-    const { template: tArg, dir: dirArg, keepWorkspace } = parseArgs(argv);
+    const { template: tArg, dir: dirArg, keepWorkspace, initGit: gitFlag, installDeps: installFlag, } = parseArgs(argv);
+    printWelcome();
+    const prereqs = checkPrereqs();
+    printPrereqReport(prereqs);
+    if (!prereqs.nodeOk) {
+        console.error(`  ❌ Node.js ${MIN_NODE_MAJOR}+ is required.`);
+        process.exit(1);
+    }
     const template = tArg && TEMPLATES.includes(tArg)
         ? tArg
         : (await prompts({
@@ -218,19 +299,75 @@ async function main() {
     }
     await copyTemplate(src, dest);
     await writeStandaloneBiome(dest, keepWorkspace);
-    await seedGenerated(dest);
     await patchPackageJson(dest, path
         .basename(dest)
         .replace(/[^a-z0-9-]/gi, '-')
         .toLowerCase() || 'quadro-app', keepWorkspace);
     await writeQuadroClientImport(dest);
     await writeReadme(dest, template);
-    console.log(`
-Created QuadroKit project at ${dest}
+    console.log(`\n  🎉  Project files are ready at ${'\u001b[1m'}${dest}${'\u001b[0m'}\n`);
+    let initGit = gitFlag;
+    if (initGit === undefined) {
+        const g = await prompts({
+            type: 'confirm',
+            name: 'v',
+            message: 'Initialize a git repository here?',
+            initial: true,
+        });
+        if (typeof g.v !== 'boolean') {
+            process.exit(1);
+        }
+        initGit = g.v;
+    }
+    if (initGit) {
+        if (!prereqs.gitOk) {
+            console.log('  ⚠️  Skipping git init — Git is not available on your PATH.\n');
+        }
+        else {
+            const ok = await runInDir(dest, 'git', ['init']);
+            if (ok) {
+                console.log('  ✅  Git repository initialized.\n');
+            }
+            else {
+                console.log('  ⚠️  `git init` failed — you can run it manually later.\n');
+            }
+        }
+    }
+    let installDeps = installFlag;
+    if (installDeps === undefined) {
+        const ins = await prompts({
+            type: 'confirm',
+            name: 'v',
+            message: 'Install dependencies now?',
+            initial: true,
+        });
+        if (typeof ins.v !== 'boolean') {
+            process.exit(1);
+        }
+        installDeps = ins.v;
+    }
+    if (installDeps) {
+        const useBun = prereqs.bunOk;
+        const cmd = useBun ? 'bun' : 'npm';
+        const args = useBun ? ['install'] : ['install'];
+        console.log(`  📦  Running ${cmd} ${args.join(' ')} …\n`);
+        const ok = await runInDir(dest, cmd, args);
+        if (ok) {
+            console.log(`  ✅  Dependencies installed with ${cmd}.\n`);
+        }
+        else {
+            console.log(`  ⚠️  Install failed — run \`${useBun ? 'bun install' : 'npm install'}\` inside the project.\n`);
+        }
+    }
+    const pm = prereqs.bunOk ? 'bun' : 'npm';
+    const runDev = prereqs.bunOk ? 'bun run dev' : 'npm run dev';
+    const installLine = installDeps ? `    →  ${runDev}` : `    →  ${pm} install\n    →  ${runDev}`;
+    console.log(`  🚀🚀  Next steps
+    →  cd ${path.basename(dest)}
+${installLine}
+    →  Copy .env.example → .env and set VITE_4D_ORIGIN
 
-  cd ${path.basename(dest)}
-  bun install
-  bun run dev
+  Happy building! ✨
 `);
 }
 main().catch((e) => {

package/package.json

@@ -1,17 +1,16 @@
 {
   "name": "create-quadrokit",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Scaffold a QuadroKit Vite + React app from a template",
   "type": "module",
-  "bin": "./dist/index.js",
+  "bin": "./dist/index.mjs",
   "files": [
     "dist",
     "templates",
-    "vendor",
     "biome.monorepo.json"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && bun ../scripts/rename-dist-js-to-mjs.ts dist",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepublishOnly": "bun run scripts/sync-for-publish.ts && bun run build"
   },

package/templates/README.md

@@ -34,4 +34,6 @@ Each template has a [`biome.json`](dashboard/biome.json) with `"root": false` an
 
 ## Scaffolding outside the monorepo
 
-Use [`create-quadrokit`](../../create-quadrokit/README.md); it copies a template, seeds `.quadrokit/generated`, and rewrites `workspace:*` to published semver.
+Use [`create-quadrokit`](../../create-quadrokit/README.md); it copies a template, rewrites `workspace:*` to published semver, and skips lockfiles and `.quadrokit/` (so new projects run `bun run quadrokit:generate` after install).
+
+For **monorepo** template packages, `.quadrokit/generated` is kept (regenerate with `bun run quadrokit:generate` in a template after changing `assets/catalog.placeholder.json`) so `tsc` can typecheck against the demo catalog.

package/templates/admin-shell/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "quadrokit:generate": "node scripts/quadrokit-generate.mjs",
     "dev": "vite",
     "build": "tsc -b && vite build",
     "preview": "vite preview",

package/templates/dashboard/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "quadrokit:generate": "node scripts/quadrokit-generate.mjs",
     "dev": "vite",
     "build": "tsc -b && vite build",
     "preview": "vite preview",

package/templates/ecommerce/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "quadrokit:generate": "node scripts/quadrokit-generate.mjs",
     "dev": "vite",
     "build": "tsc -b && vite build",
     "preview": "vite preview",

package/templates/website/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "quadrokit:generate": "node scripts/quadrokit-generate.mjs",
     "dev": "vite",
     "build": "tsc -b && vite build",
     "preview": "vite preview",