create-gentiq-app 0.14.0 → 0.15.0-beta.2

package/index.js

@@ -4,107 +4,470 @@ import * as p from '@clack/prompts';
 import color from 'picocolors';
 import fs from 'fs-extra';
 import path from 'path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'url';
 
+import { shouldSkipEntry } from './skipped-entries.js';
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-async function main() {
-  console.clear();
+const PACKAGE_MANAGERS = ['pnpm', 'npm', 'yarn', 'bun'];
 
-  p.intro(`${color.bgBlue(color.black(' create-gentiq-app '))}`);
+const HELP = `
+${color.bold('create-gentiq-app')} — scaffold a full-stack Gentiq application.
 
-  // Determine target directory
-  let targetDir = process.argv[2];
+${color.bold('Usage')}
+  npx create-gentiq-app@latest [directory] [options]
 
-  if (!targetDir) {
-    const dirResponse = await p.text({
-      message: 'Where should we create your project?',
-      placeholder: './my-gentiq-app',
-      initialValue: './my-gentiq-app',
-      validate(value) {
-        if (value.length === 0) return 'Directory cannot be empty';
-      },
+${color.bold('Options')}
+  --pm <name>        Frontend package manager: pnpm | npm | yarn | bun
+  --install          Install backend and frontend dependencies (default)
+  --no-install       Scaffold only; skip \`uv sync\` and the frontend install
+  --openai-key <k>   Write this OPENAI_API_KEY into backend/.env
+  -y, --yes          Accept every default; never prompt (for CI)
+  -h, --help         Show this message
+`;
+
+// ---------------------------------------------------------------------------
+// Process helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a command, buffering its output so a spinner stays intact. Never rejects —
+ * a missing binary and a non-zero exit are both outcomes the caller reports on.
+ */
+function run(command, args, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd,
+      // Windows resolves `npm`/`pnpm` only through their .cmd shims.
+      shell: process.platform === 'win32',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, ADBLOCK: '1', DISABLE_OPENCOLLECTIVE: '1' },
     });
 
-    if (p.isCancel(dirResponse)) {
-      p.cancel('Operation cancelled');
-      process.exit(0);
+    let output = '';
+    const collect = (chunk) => {
+      output += chunk.toString();
+    };
+    child.stdout.on('data', collect);
+    child.stderr.on('data', collect);
+
+    child.on('error', (error) =>
+      resolve({ ok: false, missing: error.code === 'ENOENT', output: output + error.message }),
+    );
+    child.on('close', (code) => resolve({ ok: code === 0, missing: false, output, code }));
+  });
+}
+
+const hasCommand = async (command) => (await run(command, ['--version'])).ok;
+
+/** The package manager that invoked us, e.g. `pnpm create gentiq-app`. */
+function detectPackageManager() {
+  const agent = process.env.npm_config_user_agent || '';
+  return PACKAGE_MANAGERS.find((pm) => agent.startsWith(`${pm}/`)) || null;
+}
+
+// ---------------------------------------------------------------------------
+// Version pinning
+//
+// The three published packages (`gentiq` on PyPI, `gentiq` on npm and this CLI)
+// release in lockstep, so the CLI's own version names exactly the runtime this
+// template was written against. Pinning to it is what keeps a scaffold produced
+// by an older cached CLI from installing a newer, incompatible framework.
+// ---------------------------------------------------------------------------
+
+const VERSION_RE = /^(\d+)\.(\d+)\.(\d+)(?:-(alpha|beta|rc)\.?(\d+)?)?$/;
+
+function versionRanges(version) {
+  const match = String(version).match(VERSION_RE);
+  if (!match) return null;
+
+  const [, major, minor, patch, kind, num] = match;
+  // 0.x treats the minor as the breaking-change axis, exactly as npm's `^` does.
+  const upper = major === '0' ? `0.${Number(minor) + 1}.0` : `${Number(major) + 1}.0.0`;
+  // PEP 440 spells pre-releases `0.15.0b1`, semver `0.15.0-beta.1`. Naming one in
+  // the specifier is also what allows uv to resolve it at all.
+  const pep440 = kind
+    ? `${major}.${minor}.${patch}${kind === 'alpha' ? 'a' : kind === 'beta' ? 'b' : 'rc'}${num ?? 0}`
+    : `${major}.${minor}.${patch}`;
+
+  return { npm: `^${version}`, pypi: `>=${pep440},<${upper}` };
+}
+
+// ---------------------------------------------------------------------------
+// Scaffolding steps
+// ---------------------------------------------------------------------------
+
+function resolveTemplateDir() {
+  // Inside the repo the template lives at the root; the published tarball carries
+  // its own copy next to this file (see copy-template.js).
+  const candidates = [
+    path.join(__dirname, 'templates', 'starter'),
+    path.join(__dirname, '..', '..', 'templates', 'starter'),
+  ];
+  const found = candidates.find((dir) => fs.existsSync(dir));
+  if (!found) throw new Error('Could not locate the starter template.');
+  return found;
+}
+
+/**
+ * npm never ships a file named `.gitignore` inside a tarball, so the template
+ * carries them as `_gitignore` and they are renamed on the way out.
+ */
+async function restoreGitignores(dir) {
+  for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await restoreGitignores(full);
+    } else if (entry.name === '_gitignore') {
+      await fs.move(full, path.join(dir, '.gitignore'), { overwrite: true });
     }
-    
-    targetDir = dirResponse;
+  }
+}
+
+/** Replace `KEY=...` in place, whether the line is currently commented out or not. */
+function setEnvValue(content, key, value) {
+  const line = new RegExp(`^#?[ \\t]*${key}=.*$`, 'm');
+  return line.test(content)
+    ? content.replace(line, `${key}=${value}`)
+    : `${content.trimEnd()}\n${key}=${value}\n`;
+}
+
+/**
+ * Write `backend/.env` with real secrets. Without it the app fails closed: the
+ * JWT signing key has no default, and the server-to-server routes reject every
+ * request while BACKEND_API_KEY is unset. Generating them here is what makes the
+ * scaffold runnable before the developer has edited anything.
+ */
+async function writeEnvFile(backendDir, openaiKey) {
+  const examplePath = path.join(backendDir, '.env.example');
+  const envPath = path.join(backendDir, '.env');
+  if (!fs.existsSync(examplePath) || fs.existsSync(envPath)) return false;
+
+  const secret = () => crypto.randomBytes(32).toString('hex');
+  let content = await fs.readFile(examplePath, 'utf8');
+  content = setEnvValue(content, 'JWT_SECRET_KEY', secret());
+  content = setEnvValue(content, 'BACKEND_API_KEY', secret());
+  if (openaiKey) content = setEnvValue(content, 'OPENAI_API_KEY', openaiKey);
+
+  await fs.writeFile(envPath, content, 'utf8');
+  return true;
+}
+
+/** Point the template's workspace dependencies at the published packages. */
+async function pinDependencies(projectPath, ranges) {
+  const frontendPkgPath = path.join(projectPath, 'frontend', 'package.json');
+  if (fs.existsSync(frontendPkgPath)) {
+    const pkg = await fs.readJson(frontendPkgPath);
+    if (pkg.dependencies?.gentiq) {
+      pkg.dependencies.gentiq = ranges?.npm ?? 'latest';
+    }
+    await fs.writeJson(frontendPkgPath, pkg, { spaces: 2 });
+  }
+
+  const pyprojectPath = path.join(projectPath, 'backend', 'pyproject.toml');
+  if (ranges && fs.existsSync(pyprojectPath)) {
+    const toml = await fs.readFile(pyprojectPath, 'utf8');
+    await fs.writeFile(
+      pyprojectPath,
+      toml.replace(/"gentiq\[engines\][^"]*"/, `"gentiq[engines]${ranges.pypi}"`),
+      'utf8',
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Dependency installation
+// ---------------------------------------------------------------------------
+
+async function installBackend(projectPath, results) {
+  const backendDir = path.join(projectPath, 'backend');
+  if (!fs.existsSync(backendDir)) return;
+
+  if (!(await hasCommand('uv'))) {
+    results.push({
+      name: 'backend',
+      status: 'skipped',
+      hint: `${color.bold('uv')} is not installed — see ${color.underline('https://docs.astral.sh/uv/getting-started/installation/')}, then run ${color.cyan('uv sync')} in ${color.cyan('backend/')}.`,
+    });
+    return;
+  }
+
+  const result = await run('uv', ['sync'], backendDir);
+  results.push({
+    name: 'backend',
+    status: result.ok ? 'ok' : 'failed',
+    command: 'uv sync',
+    output: result.output,
+  });
+}
+
+async function installFrontend(projectPath, packageManager, results) {
+  const frontendDir = path.join(projectPath, 'frontend');
+  if (!fs.existsSync(frontendDir)) return;
+
+  // The requested manager may not exist on this machine (`--pm pnpm` on a plain
+  // npm box), so fall back rather than failing the whole scaffold.
+  let pm = packageManager;
+  if (!(await hasCommand(pm))) {
+    const fallback = [];
+    for (const candidate of PACKAGE_MANAGERS) {
+      if (candidate !== pm && (await hasCommand(candidate))) fallback.push(candidate);
+    }
+    if (fallback.length === 0) {
+      results.push({
+        name: 'frontend',
+        status: 'skipped',
+        hint: `No package manager found — install Node.js, then run ${color.cyan('npm install')} in ${color.cyan('frontend/')}.`,
+      });
+      return;
+    }
+    pm = fallback[0];
+  }
+
+  const result = await run(pm, ['install'], frontendDir);
+  results.push({
+    name: 'frontend',
+    status: result.ok ? 'ok' : 'failed',
+    command: `${pm} install`,
+    output: result.output,
+    packageManager: pm,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const options = { targetDir: null, install: null, packageManager: null, openaiKey: null, yes: false, help: false };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '-h' || arg === '--help') options.help = true;
+    else if (arg === '-y' || arg === '--yes') options.yes = true;
+    else if (arg === '--install') options.install = true;
+    else if (arg === '--no-install' || arg === '--skip-install') options.install = false;
+    else if (arg === '--pm' || arg === '--package-manager') options.packageManager = argv[++i];
+    else if (arg.startsWith('--pm=')) options.packageManager = arg.slice('--pm='.length);
+    else if (arg === '--openai-key') options.openaiKey = argv[++i];
+    else if (arg.startsWith('--openai-key=')) options.openaiKey = arg.slice('--openai-key='.length);
+    else if (!arg.startsWith('-') && !options.targetDir) options.targetDir = arg;
+  }
+
+  if (options.packageManager && !PACKAGE_MANAGERS.includes(options.packageManager)) {
+    console.error(`Unknown package manager "${options.packageManager}". Expected one of: ${PACKAGE_MANAGERS.join(', ')}.`);
+    process.exit(1);
+  }
+
+  return options;
+}
+
+const bail = (value) => {
+  if (p.isCancel(value)) {
+    p.cancel('Operation cancelled');
+    process.exit(0);
+  }
+  return value;
+};
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    console.log(HELP);
+    return;
+  }
+
+  // Prompting requires a TTY on both ends; CI gets the defaults instead.
+  const interactive = !options.yes && process.stdin.isTTY && process.stdout.isTTY;
+
+  console.clear();
+  p.intro(`${color.bgBlue(color.black(' create-gentiq-app '))}`);
+
+  let targetDir = options.targetDir;
+  if (!targetDir) {
+    targetDir = interactive
+      ? bail(
+          await p.text({
+            message: 'Where should we create your project?',
+            placeholder: './my-gentiq-app',
+            initialValue: './my-gentiq-app',
+            validate: (value) => (value.length === 0 ? 'Directory cannot be empty' : undefined),
+          }),
+        )
+      : './my-gentiq-app';
   }
 
   const projectPath = path.resolve(process.cwd(), targetDir);
 
   if (fs.existsSync(projectPath) && fs.readdirSync(projectPath).length > 0) {
-    const overwrite = await p.confirm({
-      message: `Directory ${targetDir} is not empty. Continue anyway?`,
-      initialValue: false,
-    });
+    const overwrite = interactive
+      ? bail(
+          await p.confirm({
+            message: `Directory ${targetDir} is not empty. Continue anyway?`,
+            initialValue: false,
+          }),
+        )
+      : false;
 
-    if (p.isCancel(overwrite) || !overwrite) {
+    if (!overwrite) {
       p.cancel('Operation cancelled');
       process.exit(0);
     }
   }
 
+  let packageManager = options.packageManager || detectPackageManager() || 'npm';
+  let install = options.install;
+  let openaiKey = options.openaiKey;
+
+  if (interactive) {
+    if (install === null) {
+      install = bail(
+        await p.confirm({
+          message: 'Install dependencies now?',
+          initialValue: true,
+        }),
+      );
+    }
+
+    if (install && !options.packageManager) {
+      packageManager = bail(
+        await p.select({
+          message: 'Which package manager should the frontend use?',
+          initialValue: packageManager,
+          options: PACKAGE_MANAGERS.map((pm) => ({ value: pm, label: pm })),
+        }),
+      );
+    }
+
+    if (!openaiKey) {
+      const answer = bail(
+        await p.text({
+          message: 'OpenAI API key? (optional — press Enter to add it to backend/.env later)',
+          placeholder: 'sk-proj-...',
+          defaultValue: '',
+        }),
+      );
+      openaiKey = answer.trim() || null;
+    }
+  }
+
+  if (install === null) install = true;
+
   const s = p.spinner();
   s.start('Scaffolding project...');
 
+  const installResults = [];
+  let envCreated = false;
+
   try {
-    // 1. Copy files from template
-    // In dev, the template is in ../../templates/starter
-    // In prod when published, it might be in different relative path, but assuming we pack it together
-    // Let's resolve the starter template path. Since this is in packages/cli, it's 2 levels up.
-    let templateDir = path.join(__dirname, '..', '..', 'templates', 'starter');
-    
-    // Fallback if packed differently on npm
-    if (!fs.existsSync(templateDir)) {
-       templateDir = path.join(__dirname, 'templates', 'starter');
-    }
+    const templateDir = resolveTemplateDir();
 
     await fs.copy(templateDir, projectPath, {
-      filter: (src) => {
-        const basename = path.basename(src);
-        return !['node_modules', '.venv', '__pycache__', '.ruff_cache', 'dist'].includes(basename);
-      }
+      filter: (src) => !shouldSkipEntry(path.basename(src)),
     });
 
-    // 2. Adjust frontend package.json
-    const frontendPkgPath = path.join(projectPath, 'frontend', 'package.json');
-    if (fs.existsSync(frontendPkgPath)) {
-      let pkgConfig = await fs.readJson(frontendPkgPath);
-      // Remove workspace dependency, replace with latest
-      pkgConfig.dependencies['gentiq'] = 'latest'; 
-      await fs.writeJson(frontendPkgPath, pkgConfig, { spaces: 2 });
-    }
+    await restoreGitignores(projectPath);
 
-    // 3. Adjust backend pyproject.toml
-    // Already removed tool.uv.sources in the template, so it relies on the 'gentiq' pip package by default.
-    // If there's any other workspace specific replace, we can do it here.
+    const { version } = await fs.readJson(path.join(__dirname, 'package.json'));
+    await pinDependencies(projectPath, versionRanges(version));
 
-    s.stop(`Project scaffolded successfully!`);
+    envCreated = await writeEnvFile(path.join(projectPath, 'backend'), openaiKey);
 
-    p.note(
-      `${color.cyan('cd')} ${targetDir}\n\n` +
-      `${color.bold('Frontend:')}\n` +
-      `${color.cyan('cd')} frontend\n` +
-      `${color.cyan('npm')} install\n` +
-      `${color.cyan('npm')} run dev\n\n` +
-      `${color.bold('Backend:')}\n` +
-      `${color.cyan('cd')} backend\n` +
-      `${color.cyan('uv')} sync\n` +
-      `${color.cyan('uv')} run uvicorn main:app.api --reload --port 8000`,
-      'Next Steps'
-    );
-
-    p.outro(`Good luck with your Gentiq app! Need help? Visit our docs.`);
+    s.stop('Project scaffolded successfully!');
   } catch (error) {
     s.stop('Failed to scaffold project');
     console.error(error);
     process.exit(1);
   }
+
+  if (install) {
+    s.start('Installing backend dependencies (uv sync)...');
+    await installBackend(projectPath, installResults);
+    const backend = installResults.find((r) => r.name === 'backend');
+    s.stop(
+      backend?.status === 'ok'
+        ? 'Backend dependencies installed'
+        : backend?.status === 'failed'
+          ? 'Backend dependencies failed to install'
+          : 'Backend dependencies skipped',
+    );
+
+    s.start(`Installing frontend dependencies (${packageManager} install)...`);
+    await installFrontend(projectPath, packageManager, installResults);
+    const frontend = installResults.find((r) => r.name === 'frontend');
+    if (frontend?.packageManager) packageManager = frontend.packageManager;
+    s.stop(
+      frontend?.status === 'ok'
+        ? 'Frontend dependencies installed'
+        : frontend?.status === 'failed'
+          ? 'Frontend dependencies failed to install'
+          : 'Frontend dependencies skipped',
+    );
+  }
+
+  // Surface why anything was skipped, and the tail of the log for anything that
+  // actually failed — a silent failure would leave a project that cannot start.
+  for (const result of installResults) {
+    if (result.status === 'skipped' && result.hint) {
+      p.note(result.hint, `${result.name}: skipped`);
+    } else if (result.status === 'failed') {
+      const tail = (result.output || '').trim().split('\n').slice(-12).join('\n');
+      p.note(
+        `${color.dim(`$ ${result.command}`)}\n\n${tail}\n\n${color.yellow(`Re-run ${color.cyan(result.command)} in ${color.cyan(`${result.name}/`)} once the cause is fixed.`)}`,
+        `${result.name}: install failed`,
+      );
+    }
+  }
+
+  const backendFailed = installResults.some((r) => r.name === 'backend' && r.status !== 'ok');
+  const frontendFailed = installResults.some((r) => r.name === 'frontend' && r.status !== 'ok');
+  const runFrontend = packageManager === 'npm' ? 'npm run dev' : `${packageManager} dev`;
+
+  if (envCreated) {
+    p.note(
+      `${color.cyan('backend/.env')} was created from ${color.cyan('.env.example')} with freshly generated\n` +
+        `${color.bold('JWT_SECRET_KEY')} and ${color.bold('BACKEND_API_KEY')} values. It is gitignored — keep it that way.`,
+      'Secrets',
+    );
+  }
+
+  // The one thing the scaffold cannot provision for you. pydantic-ai builds the
+  // provider client while `main.py` defines the agent, so an absent key is an
+  // import-time crash rather than a failed chat — worth saying plainly.
+  if (!openaiKey) {
+    p.note(
+      `Set ${color.bold('OPENAI_API_KEY')} in ${color.cyan('backend/.env')} before starting the backend —\n` +
+        `without it the agent definition in ${color.cyan('main.py')} raises on import.\n\n` +
+        `Using another provider? Change the model string in ${color.cyan('backend/main.py')}\n` +
+        `and set that provider's key instead.`,
+      color.yellow('Action required'),
+    );
+  }
+
+  const steps = [`${color.cyan('cd')} ${targetDir}`, ''];
+
+  steps.push(color.bold('Backend:'), `${color.cyan('cd')} backend`);
+  if (!envCreated) {
+    steps.push(`${color.cyan('cp')} .env.example .env    ${color.dim('# then fill in the required keys')}`);
+  }
+  if (!install || backendFailed) steps.push(`${color.cyan('uv')} sync`);
+  steps.push(`${color.cyan('uv')} run uvicorn main:app.api --reload --port 8000`, '');
+
+  steps.push(color.bold('Frontend (in a second terminal):'), `${color.cyan('cd')} frontend`);
+  if (!install || frontendFailed) steps.push(`${color.cyan(packageManager)} install`);
+  steps.push(color.cyan(runFrontend));
+
+  p.note(steps.join('\n'), 'Next Steps');
+
+  p.outro(`Good luck with your Gentiq app! Need help? Visit our docs.`);
 }
 
-main().catch(console.error);
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-gentiq-app",
-  "version": "0.14.0",
+  "version": "0.15.0-beta.2",
   "description": "CLI to scaffold a new Gentiq application",
   "type": "module",
   "bin": {
@@ -8,15 +8,18 @@
   },
   "files": [
     "index.js",
+    "skipped-entries.js",
     "copy-template.js",
     "templates"
   ],
+  "scripts": {
+    "start": "node index.js",
+    "prepublishOnly": "node copy-template.js",
+    "postpublish": "rm -rf templates"
+  },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
     "picocolors": "^1.0.0",
     "fs-extra": "^11.2.0"
-  },
-  "scripts": {
-    "start": "node index.js"
   }
-}
+}

package/skipped-entries.js

@@ -0,0 +1,42 @@
+// Entries that must never reach the published tarball or a scaffolded project.
+//
+// Shared deliberately. This list used to be duplicated in copy-template.js and
+// index.js, and the copies had already drifted: only copy-template.js knew about
+// lockfiles, so scaffolding from a clone copied a `uv.lock` resolved against
+// `workspace:*`. One definition, two consumers.
+
+// Build artefacts, virtualenvs and — critically — any `.env` a contributor left
+// in the template while working on it. None of these belong in a fresh project.
+const SKIPPED_NAMES = new Set([
+  'node_modules',
+  '.venv',
+  '__pycache__',
+  '.ruff_cache',
+  '.pytest_cache',
+  'dist',
+  '.vite',
+  '.storage',
+  '.env',
+  // The CLI rewrites the `gentiq` dependency to a published version range, so any
+  // lockfile resolved against `workspace:*` would be stale on arrival.
+  'uv.lock',
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+  'bun.lockb',
+]);
+
+// The sqlite database cannot be matched by name. `_create_sqlite` builds its
+// filename from the app, not the framework — `f"{app_name.lower()}.db"` — so the
+// starter's `app_name="My Gentiq App"` writes `my gentiq app.db`, and the exact
+// `gentiq.db` entry this replaces never once matched it. A contributor's local
+// database — real accounts, real chat history — was therefore eligible for
+// publishing, and `*.db` in .gitignore kept it out of `git status` where anyone
+// would have noticed. Match the extension, plus the sidecars SQLite writes next
+// to it under WAL or rollback journaling.
+const SKIPPED_PATTERN = /\.db(-wal|-shm|-journal)?$/i;
+
+/** @param {string} name A single path segment, not a full path. */
+export function shouldSkipEntry(name) {
+  return SKIPPED_NAMES.has(name) || SKIPPED_PATTERN.test(name);
+}