create-memory-soda 0.1.1 → 0.3.0

package/README.md

@@ -1,41 +1,39 @@
 # create-memory-soda
 
 Scaffold a self-hosted [Memory Soda](https://github.com/alagappan17/memory-soda)
-instance — API, dashboard, SDK, and a Postgres to point them at.
+instance — API, dashboard, and a Postgres to point them at.
 
 ```bash
 npm create memory-soda@latest
 ```
 
-It asks for a folder name, a Gemini API key, your Postgres connection string,
-which ports to use, and the dashboard admin login. Then it clones the repo,
-writes `.env`, installs dependencies, and verifies the database.
+The installer checks each requirement before asking you to use it, creates
+what it can, and ends with a checklist of anything it could not do for you.
+
+1. **Preflight** — Node 20+ and git. Missing? Prints the install command for
+   your OS and stops. Nothing is written.
+2. **Folder** — `memory-soda` by default.
+3. **Postgres** — bring your own URL, let it start `pgvector/pgvector:pg16` in
+   Docker (offered when Docker is running), or skip.
+4. **Database check** — connects, offers to create a missing database,
+   confirms pgvector and enables the extension. Failures name the fix and let
+   you retry, paste another URL, or skip.
+5. **Gemini key** — checked live. Blank allowed; goes on the checklist.
+6. **Ports and admin login** — ports checked for use; blank password is
+   generated at first boot.
+7. **Clone, `.env`, `npm ci`, migrations** — migrations run now if the database
+   passed.
+
+Then:
 
 ```bash
 cd memory-soda
 npm run dev
 ```
 
-First boot applies migrations, creates your admin user, and prints an API key
-once. Dashboard on :3000, API on :3004.
-
-## Postgres
-
-You bring your own. The installer asks for a `DATABASE_URL`, probes the host and
-port while you are still at the prompt, and after `npm install` connects for real
-to confirm the database exists and pgvector is available.
-
-When that check fails it names the fix and lets you retry without starting over:
-
-```
-! database "memory_db" does not exist
-  createdb memory_db
-Fix it and press enter to retry, or type a new DATABASE_URL (s to skip):
-```
-
-The role in the URL needs permission to `CREATE EXTENSION vector` — the first
-migration creates the extension. On most installations that means a superuser.
+Sign in to the dashboard (:3000) to create an API key. `npm run update` pulls
+and reinstalls later. Pass `--verbose` to stream clone/install output.
 
 ## Requirements
 
-Node 20+, git, and a Postgres 14+ with the pgvector extension available.
+Node 20+, git. Postgres 14+ with pgvector, or Docker.

package/index.js

@@ -1,45 +1,83 @@
 #!/usr/bin/env node
-import { createInterface } from 'node:readline/promises';
-import { execFileSync } from 'node:child_process';
-import {
-  existsSync,
-  readdirSync,
-  writeFileSync,
-  rmSync,
-  realpathSync,
-} from 'node:fs';
-import { resolve, basename, join } from 'node:path';
-import { createRequire } from 'node:module';
+import { spawn, execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, writeFileSync, realpathSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
 import { connect } from 'node:net';
-import { stdin, stdout, exit } from 'node:process';
+import { exit, platform } from 'node:process';
 import { pathToFileURL } from 'node:url';
+import { randomBytes } from 'node:crypto';
+import * as p from '@clack/prompts';
 import chalk from 'chalk';
+import pg from 'pg';
 
 const REPO = 'https://github.com/alagappan17/memory-soda.git';
 const DEFAULT_DB = 'postgresql://localhost:5432/memory_db';
-
-const step = (msg) => console.log(`${chalk.cyan('→')} ${msg}`);
-const warn = (msg) => console.log(`${chalk.yellow('!')} ${msg}`);
-const note = (msg) => console.log(chalk.dim(`  ${msg}`));
+const DOCKER_IMAGE = 'pgvector/pgvector:pg16';
+const VERBOSE = process.argv.includes('--verbose');
 
 function die(msg) {
   console.error(`\n${chalk.red('✗')} ${msg}\n`);
   exit(1);
 }
 
-function run(cmd, args, opts = {}) {
-  return execFileSync(cmd, args, { stdio: 'inherit', ...opts });
+/** Bail if the user hit ctrl-c on a prompt. */
+function guard(value) {
+  if (p.isCancel(value)) die('Cancelled.');
+  return value;
 }
 
 /** Run a command quietly, returning stdout — or null if it failed or is missing. */
 function tryRun(cmd, args, opts = {}) {
   try {
-    return execFileSync(cmd, args, { encoding: 'utf8', stdio: 'pipe', ...opts });
+    return execFileSync(cmd, args, {
+      encoding: 'utf8',
+      stdio: 'pipe',
+      ...opts,
+    });
   } catch {
     return null;
   }
 }
 
+/**
+ * Run a long command behind a spinner. The spinner shows the command's last
+ * output line as it goes; the full log only appears if it fails (or with
+ * --verbose, where it streams straight through).
+ */
+function runWithSpinner(title, cmd, args, { cwd } = {}) {
+  if (VERBOSE) {
+    p.log.step(title);
+    return new Promise((done, fail) => {
+      spawn(cmd, args, { cwd, stdio: 'inherit' }).on('close', (code) =>
+        code === 0 ? done() : fail(new Error(`${cmd} exited with ${code}`)),
+      );
+    });
+  }
+  const s = p.spinner();
+  s.start(title);
+  return new Promise((done, fail) => {
+    let log = '';
+    const child = spawn(cmd, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    const onData = (chunk) => {
+      log += chunk;
+      const last = String(chunk).trim().split('\n').pop()?.trim();
+      if (last) s.message(`${title} ${chalk.dim(last.slice(0, 60))}`);
+    };
+    child.stdout.on('data', onData);
+    child.stderr.on('data', onData);
+    child.on('close', (code) => {
+      if (code === 0) return s.stop(title) ?? done();
+      s.stop(`${title} — failed`, 1);
+      p.log.error(log.trim().split('\n').slice(-20).join('\n'));
+      fail(
+        new Error(
+          `${cmd} ${args.join(' ')} exited with ${code}. Re-run with --verbose for the full log.`,
+        ),
+      );
+    });
+  });
+}
+
 /**
  * Render the .env file. Only the values the installer collects are written
  * explicitly — everything else stays on the defaults baked into config.ts, so
@@ -60,11 +98,11 @@ export function renderEnv({
     '# PostgreSQL — must have the pgvector extension available.',
     `DATABASE_URL=${databaseUrl}`,
     '',
-    '# Google Gemini — get a key at https://aistudio.google.com',
+    '# Google Gemini — REQUIRED for extraction and search. Get a key at https://aistudio.google.com',
     `GOOGLE_GENERATIVE_AI_API_KEY=${geminiKey}`,
     '',
     '# Ports. CORS_ORIGIN must match where the dashboard is served from, and',
-    '# VITE_API_URL is the browser\'s view of the API — not the server\'s.',
+    "# VITE_API_URL is the browser's view of the API — not the server's.",
     `PORT=${apiPort}`,
     `DASHBOARD_PORT=${dashboardPort}`,
     `CORS_ORIGIN=http://localhost:${dashboardPort}`,
@@ -89,8 +127,7 @@ export function isUsableTarget(dir) {
 
 /**
  * Pull the host and port out of a Postgres connection string, for the cheap
- * reachability probe. Returns null for anything unparseable — a malformed URL
- * is the database check's problem to report, not the probe's.
+ * reachability probe. Returns null for anything unparseable.
  */
 export function parsePostgresUrl(url) {
   try {
@@ -117,48 +154,82 @@ function isReachable({ host, port }, timeout = 2000) {
   });
 }
 
-/**
- * Connect for real and confirm pgvector is installable, using the `pg` copy
- * inside the freshly installed project so the installer needs no database
- * driver of its own. Returns null on success, or an operator-readable problem.
- */
-export async function checkDatabase(target, databaseUrl) {
-  let Client;
+const dbName = (databaseUrl) =>
+  decodeURIComponent(new URL(databaseUrl).pathname.slice(1));
+
+/** Create the database named in the URL by connecting to the maintenance db on the same server. */
+async function createDatabase(databaseUrl) {
+  const url = new URL(databaseUrl);
+  url.pathname = '/postgres';
+  const client = new pg.Client({ connectionString: url.href });
   try {
-    const require = createRequire(pathToFileURL(join(target, 'package.json')));
-    ({ Client } = require('pg'));
-  } catch {
-    return { skipped: 'could not load pg from the new project' };
+    await client.connect();
+    await client.query(
+      `CREATE DATABASE "${dbName(databaseUrl).replaceAll('"', '""')}"`,
+    );
+  } finally {
+    await client.end().catch(() => {});
   }
+}
+
+/** OS-specific hint for a pgvector install, matched to the server's major version. */
+function pgvectorHint(serverMajor) {
+  if (platform === 'darwin') return 'brew install pgvector';
+  if (platform === 'linux')
+    return `sudo apt install postgresql-${serverMajor}-pgvector`;
+  return 'see https://github.com/pgvector/pgvector#installation';
+}
 
-  const client = new Client({ connectionString: databaseUrl });
+/**
+ * Connect for real, confirm pgvector is installable, and enable it. Returns
+ * null on success, or an operator-readable { problem, fix, ...flags }.
+ */
+export async function checkDatabase(databaseUrl) {
+  const addr = parsePostgresUrl(databaseUrl) ?? { host: '?', port: '?' };
+  const client = new pg.Client({ connectionString: databaseUrl });
   try {
     await client.connect();
     const { rows } = await client.query(
       "SELECT 1 FROM pg_available_extensions WHERE name = 'vector'",
     );
     if (rows.length === 0) {
+      const major = (
+        await client.query('SHOW server_version')
+      ).rows[0].server_version.split('.')[0];
       return {
         problem: 'pgvector is not available on this server',
-        fix: 'Install it — brew install pgvector, or apt install postgresql-16-pgvector.',
+        fix: `${pgvectorHint(major)}, restart Postgres, then retry. Or let the installer start a Docker Postgres that has it.`,
       };
     }
+    try {
+      await client.query('CREATE EXTENSION IF NOT EXISTS vector');
+    } catch (err) {
+      // Not fatal: the first migration retries this. Surface it as a to-do
+      // rather than blocking, since it usually just needs a superuser once.
+      if (err.code === '42501') return { extensionTodo: dbName(databaseUrl) };
+      throw err;
+    }
     return null;
   } catch (err) {
     if (err.code === '3D000') {
-      const db = decodeURIComponent(new URL(databaseUrl).pathname.slice(1));
       return {
-        problem: `database "${db}" does not exist`,
-        fix: `createdb ${db}`,
+        problem: `database "${dbName(databaseUrl)}" does not exist`,
+        missingDb: dbName(databaseUrl),
       };
     }
     if (err.code === '28P01' || err.code === '28000') {
-      return { problem: 'authentication failed', fix: 'Check the user and password in the URL.' };
+      return {
+        problem: 'authentication failed',
+        fix: 'Check the user and password in the URL.',
+      };
     }
-    if (err.code === 'ECONNREFUSED') {
+    if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND') {
       return {
-        problem: 'nothing is accepting connections at that host and port',
-        fix: 'Start Postgres — brew services start postgresql, or pg_ctl start.',
+        problem: `nothing is accepting connections at ${addr.host}:${addr.port}`,
+        fix:
+          platform === 'darwin'
+            ? 'brew services start postgresql@16 (or start your Postgres however you installed it).'
+            : 'sudo systemctl start postgresql (or start your Postgres however you installed it).',
       };
     }
     return { problem: err.message, fix: null };
@@ -167,154 +238,384 @@ export async function checkDatabase(target, databaseUrl) {
   }
 }
 
-async function main() {
-  if (Number(process.versions.node.split('.')[0]) < 20) {
-    die(`Node 20 or newer is required — you are on ${process.versions.node}.`);
-  }
-  if (!tryRun('git', ['--version'])) die('git is required but was not found.');
-
-  console.log(
-    `\n${chalk.bold('Memory Soda')} ${chalk.dim('— self-hosted memory for AI agents')}\n`,
+/** Start a pgvector-enabled Postgres in Docker. Returns the DATABASE_URL, or throws. */
+async function startDockerPostgres() {
+  const password = randomBytes(12).toString('hex');
+  const name = 'memory-soda-pg';
+  // A stale container from a previous run would fail the `run` with a name
+  // clash; removing it is safe because it only ever held this installer's data.
+  tryRun('docker', ['rm', '-f', name]);
+  await runWithSpinner(
+    `Starting Postgres in Docker (${DOCKER_IMAGE})`,
+    'docker',
+    [
+      'run',
+      '-d',
+      '--name',
+      name,
+      '--restart',
+      'unless-stopped',
+      '-e',
+      `POSTGRES_PASSWORD=${password}`,
+      '-e',
+      'POSTGRES_DB=memory_db',
+      '-p',
+      '5432:5432',
+      DOCKER_IMAGE,
+    ],
   );
+  const addr = { host: 'localhost', port: 5432 };
+  // Postgres takes a moment to accept connections after the container is up.
+  for (let i = 0; i < 20 && !(await isReachable(addr, 500)); i++)
+    await new Promise((r) => setTimeout(r, 500));
+  return `postgresql://postgres:${password}@localhost:5432/memory_db`;
+}
 
-  // Read answers off the line iterator rather than rl.question(): with a piped
-  // stdin, question() consumes only the first line of a buffered chunk and
-  // drops the rest, so `printf 'a\nb\n' | npm create memory-soda` would stall.
-  const rl = createInterface({ input: stdin });
-  const lines = rl[Symbol.asyncIterator]();
-  const ask = async (q, fallback = '') => {
-    const hint = fallback ? chalk.dim(` (${fallback})`) : '';
-    stdout.write(`${q}${hint}: `);
-    const { value, done } = await lines.next();
-    // EOF (a script that piped fewer answers than there are questions) takes
-    // the default rather than hanging.
-    if (done) stdout.write('\n');
-    return (value ?? '').trim() || fallback;
-  };
-  const askPort = async (q, fallback) => {
-    for (;;) {
-      const raw = await ask(q, String(fallback));
-      const port = Number(raw);
-      if (Number.isInteger(port) && port > 0 && port < 65536) return port;
-      warn(`${raw} is not a port number.`);
-    }
-  };
-
-  const dirName = process.argv[2] || (await ask('Folder name', 'memory-soda'));
-  const target = resolve(process.cwd(), dirName);
-  if (!isUsableTarget(target)) {
-    rl.close();
-    die(`${target} already exists and is not empty.`);
+/** A cheap live check that the Gemini key is accepted. null = ok, string = why not. */
+export async function checkGeminiKey(key) {
+  try {
+    const res = await fetch(
+      'https://generativelanguage.googleapis.com/v1beta/models?pageSize=1',
+      {
+        headers: { 'x-goog-api-key': key },
+        signal: AbortSignal.timeout(8000),
+      },
+    );
+    if (res.ok) return null;
+    if (res.status === 400 || res.status === 403)
+      return 'Gemini rejected that key.';
+    return `Gemini answered ${res.status}.`;
+  } catch {
+    return 'could not reach Gemini (offline?)';
   }
+}
 
-  const geminiKey = await ask('Gemini API key');
-  if (!geminiKey) note('No key given — set it in .env before starting.');
+const validPort = (v) => {
+  if (!v) return; // blank takes the default
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 1 || n > 65535)
+    return 'Enter a port between 1 and 65535.';
+};
 
-  console.log(
-    `\n${chalk.bold('Postgres')} ${chalk.dim('— bring your own, with the pgvector extension available')}`,
-  );
-  let databaseUrl = await ask('DATABASE_URL', DEFAULT_DB);
-  const addr = parsePostgresUrl(databaseUrl);
-  if (!addr) {
-    warn('That does not parse as a postgres:// URL — it is written as given.');
-  } else if (!(await isReachable(addr))) {
-    // Only a warning: the server may legitimately be starting, or firewalled
-    // from here but reachable from wherever the app will actually run.
-    warn(`Nothing is listening on ${addr.host}:${addr.port} right now.`);
-    note('Continuing — the connection is checked again after install.');
-  } else {
-    note(`${addr.host}:${addr.port} is reachable.`);
+async function askPort(message, defaultValue) {
+  for (;;) {
+    const port = Number(
+      guard(
+        await p.text({
+          message,
+          placeholder: defaultValue,
+          defaultValue,
+          validate: validPort,
+        }),
+      ),
+    );
+    if (!(await isReachable({ host: '127.0.0.1', port }, 300))) return port;
+    p.log.warn(`Port ${port} is already in use.`);
   }
+}
 
-  console.log(`\n${chalk.bold('Ports')}`);
-  const apiPort = await askPort('API port', 3004);
-  const dashboardPort = await askPort('Dashboard port', 3000);
-
-  console.log(`\n${chalk.bold('Dashboard login')}`);
-  const adminUser = await ask('Admin username', 'admin');
-  const adminPassword = await ask(
-    `Admin password ${chalk.dim('(blank = generate one)')}`,
-  );
+async function main() {
+  // ── 0. Preflight: check and tell, never install. System packages are the
+  // user's call; we only ever run things inside the folder we create.
+  if (Number(process.versions.node.split('.')[0]) < 20) {
+    die(
+      `Node 20 or newer is required — you are on ${process.versions.node}.\n  ` +
+        (tryRun('nvm', ['--version'])
+          ? 'nvm install 22 && nvm use 22'
+          : 'https://nodejs.org or brew install node') +
+        '\n  then re-run: npm create memory-soda@latest',
+    );
+  }
+  if (!tryRun('git', ['--version'])) {
+    die(
+      'git is required but was not found.\n  ' +
+        (platform === 'darwin'
+          ? 'xcode-select --install'
+          : 'sudo apt install git') +
+        '\n  then re-run: npm create memory-soda@latest',
+    );
+  }
+  const hasDocker = Boolean(tryRun('docker', ['info']));
 
-  console.log();
-  step(`Cloning into ${chalk.bold(dirName)}`);
-  run('git', ['clone', '--depth', '1', REPO, target]);
-  rmSync(resolve(target, '.git'), { recursive: true, force: true });
+  p.intro(chalk.bold('create-memory-soda'));
+  const todo = []; // things the user must do themselves before the app runs
 
-  const writeEnv = () =>
-    writeFileSync(
-      resolve(target, '.env'),
-      renderEnv({
-        databaseUrl,
-        geminiKey,
-        adminUser,
-        adminPassword,
-        apiPort,
-        dashboardPort,
+  // ── 1. Folder
+  const dirName =
+    process.argv.slice(2).find((a) => !a.startsWith('-')) ??
+    guard(
+      await p.text({
+        message: 'Project folder',
+        placeholder: 'memory-soda',
+        defaultValue: 'memory-soda',
+        validate: (v) =>
+          isUsableTarget(resolve(process.cwd(), v || 'memory-soda'))
+            ? undefined
+            : 'That folder exists and is not empty.',
       }),
     );
-  writeEnv();
-  step('Wrote .env');
+  const target = resolve(process.cwd(), dirName);
+  if (!isUsableTarget(target))
+    die(`${target} already exists and is not empty.`);
 
-  step(`Installing dependencies ${chalk.dim('(this takes a minute)')}`);
-  run('npm', ['install'], { cwd: target });
+  // ── 2 + 3. Postgres: where is it, then verify it until it works or is skipped.
+  let databaseUrl = DEFAULT_DB;
+  let dbReady = false;
+  const where = guard(
+    await p.select({
+      message: 'Where is Postgres?',
+      options: [
+        {
+          value: 'own',
+          label: 'I have one',
+          hint: 'you give the URL; pgvector must be installed on it',
+        },
+        ...(hasDocker
+          ? [
+              {
+                value: 'docker',
+                label: 'Start one in Docker for me',
+                hint: DOCKER_IMAGE,
+              },
+            ]
+          : []),
+        {
+          value: 'skip',
+          label: 'Skip',
+          hint: 'set DATABASE_URL in .env yourself later',
+        },
+      ],
+    }),
+  );
+  if (where === 'docker') {
+    try {
+      databaseUrl = await startDockerPostgres();
+    } catch (err) {
+      p.log.error(err.message);
+    }
+  } else if (where === 'own') {
+    databaseUrl = guard(
+      await p.text({
+        message: 'Postgres URL',
+        placeholder: DEFAULT_DB,
+        defaultValue: DEFAULT_DB,
+        validate: (v) =>
+          v && !parsePostgresUrl(v) ? 'Expected a postgres:// URL.' : undefined,
+      }),
+    );
+  }
+  if (where !== 'skip') {
+    for (;;) {
+      const s = p.spinner();
+      s.start('Checking the database');
+      let result = await checkDatabase(databaseUrl);
+      if (result?.missingDb) {
+        s.stop(`Database "${result.missingDb}" does not exist`);
+        if (
+          guard(
+            await p.confirm({
+              message: `Create database "${result.missingDb}"?`,
+              initialValue: true,
+            }),
+          )
+        ) {
+          s.start(`Creating database ${result.missingDb}`);
+          try {
+            await createDatabase(databaseUrl);
+            result = await checkDatabase(databaseUrl);
+          } catch (err) {
+            result = {
+              problem: `could not create database "${result.missingDb}": ${err.message}`,
+              fix: `createdb ${result.missingDb}  (as a role with CREATEDB)`,
+            };
+          }
+        } else {
+          todo.push(`createdb ${result.missingDb}`);
+          break;
+        }
+        if (result?.missingDb)
+          result = {
+            problem: `database "${result.missingDb}" still does not exist`,
+            fix: null,
+          };
+        if (result === null || result?.extensionTodo)
+          s.start('Checking the database');
+      }
+      if (result === null) {
+        s.stop('Database ready — connected, pgvector enabled');
+        dbReady = true;
+        break;
+      }
+      if (result.extensionTodo) {
+        s.stop('Database connected, but this role cannot enable pgvector', 1);
+        todo.push(
+          `psql -d ${result.extensionTodo} -c "CREATE EXTENSION vector"   (run as a Postgres superuser)`,
+        );
+        break;
+      }
+      s.stop(`Database: ${result.problem}`, 1);
+      if (result.fix) p.log.info(result.fix);
+      const retry =
+        guard(
+          await p.text({
+            message:
+              'Fix it and press enter to retry, paste a new DATABASE_URL, or type s to skip',
+            placeholder: 'enter to retry',
+          }),
+        ) ?? '';
+      if (retry.toLowerCase() === 's') break;
+      if (retry) databaseUrl = retry;
+    }
+  }
+  if (!dbReady && todo.length === 0) {
+    todo.push(
+      `Point DATABASE_URL in .env at a Postgres with pgvector, and create the database (createdb ${dbName(databaseUrl)})`,
+    );
+  }
 
-  // Now that pg exists in the project, check the database for real. Looping
-  // here beats failing at first boot: the fix is usually one command away and
-  // the answer is still in front of the user.
+  // ── 4. Gemini
+  let geminiKey = '';
   for (;;) {
-    step('Checking the database');
-    const result = await checkDatabase(target, databaseUrl);
-    if (result === null) {
-      note('Connected, and pgvector is available.');
+    geminiKey =
+      guard(
+        await p.password({
+          message: `Gemini API key ${chalk.dim('(aistudio.google.com — leave blank to add later)')}`,
+          mask: '•',
+        }),
+      ) ?? '';
+    if (!geminiKey) break;
+    const s = p.spinner();
+    s.start('Checking the key');
+    const problem = await checkGeminiKey(geminiKey);
+    if (!problem) {
+      s.stop('Gemini key accepted');
       break;
     }
-    if (result.skipped) {
-      note(`Skipped — ${result.skipped}.`);
+    s.stop(problem, 1);
+    if (
+      guard(
+        await p.confirm({ message: 'Keep it anyway?', initialValue: false }),
+      )
+    )
       break;
-    }
-    warn(result.problem);
-    if (result.fix) note(result.fix);
-    const retry = await ask(
-      `Fix it and press enter to retry, or type a new DATABASE_URL ${chalk.dim('(s to skip)')}`,
+  }
+  if (!geminiKey)
+    todo.push(
+      'Set GOOGLE_GENERATIVE_AI_API_KEY in .env — the API refuses to start without it',
     );
-    if (retry.toLowerCase() === 's') {
-      note('Skipped — the API will fail on boot until this is resolved.');
-      break;
-    }
-    if (retry) {
-      databaseUrl = retry;
-      writeEnv();
+
+  // ── 5 + 6. Ports and login
+  const apiPort = await askPort('API port', '3004');
+  const dashboardPort = await askPort('Dashboard port', '3000');
+  const adminUser = guard(
+    await p.text({
+      message: 'Dashboard admin username',
+      placeholder: 'admin',
+      defaultValue: 'admin',
+    }),
+  );
+  const adminPassword =
+    guard(
+      await p.password({
+        message: `Dashboard admin password ${chalk.dim('(leave blank to generate one at first boot)')}`,
+        mask: '•',
+      }),
+    ) ?? '';
+
+  // ── 7. Install
+  await runWithSpinner(`Cloning into ${chalk.bold(dirName)}`, 'git', [
+    'clone',
+    '--depth',
+    '1',
+    REPO,
+    target,
+  ]);
+  writeFileSync(
+    resolve(target, '.env'),
+    renderEnv({
+      databaseUrl,
+      geminiKey,
+      adminUser,
+      adminPassword,
+      apiPort,
+      dashboardPort,
+    }),
+  );
+  p.log.success('Wrote .env');
+  await runWithSpinner(
+    'Installing dependencies',
+    'npm',
+    ['ci', '--no-audit', '--no-fund'],
+    { cwd: target },
+  );
+
+  let migrated = false;
+  if (dbReady) {
+    try {
+      await runWithSpinner(
+        'Applying migrations',
+        'npm',
+        ['run', 'db:migrate'],
+        { cwd: target },
+      );
+      migrated = true;
+    } catch {
+      todo.push(
+        'npm run db:migrate   (failed during install — see the log above)',
+      );
     }
+  } else {
+    todo.push('npm run db:migrate   (once the database is ready)');
   }
 
-  rl.close();
-  console.log(`\n${chalk.green('✓')} ${chalk.bold(basename(target))} is ready.\n`);
-  console.log(`  cd ${dirName}`);
-  console.log(`  npm run dev\n`);
-  note('First boot applies migrations and prints your API key once.');
-  note(
-    `Dashboard ${chalk.underline(`http://localhost:${dashboardPort}`)} · API ${chalk.underline(`http://localhost:${apiPort}`)}`,
+  // ── 8. Summary
+  const tick = (ok, text) =>
+    `${ok ? chalk.green('✓') : chalk.yellow('✗')} ${text}`;
+  p.note(
+    [
+      tick(
+        dbReady,
+        dbReady
+          ? `Postgres  ${databaseUrl.replace(/:[^:@/]+@/, ':•••@')}`
+          : 'Postgres  not verified',
+      ),
+      tick(
+        Boolean(geminiKey),
+        geminiKey ? 'Gemini key set' : 'Gemini key missing',
+      ),
+      tick(migrated, migrated ? 'Migrations applied' : 'Migrations pending'),
+    ].join('\n'),
+    'Status',
   );
-  note(
-    adminPassword
-      ? `Log in as ${adminUser} with the password you chose.`
-      : `Log in as ${adminUser} — the generated password is printed at first boot.`,
+  if (todo.length)
+    p.note(todo.map((t, i) => `${i + 1}. ${t}`).join('\n'), 'Before you run');
+  p.note(
+    [
+      `cd ${dirName}`,
+      'npm run dev',
+      '',
+      `Dashboard  ${chalk.underline(`http://localhost:${dashboardPort}`)}`,
+      `API        ${chalk.underline(`http://localhost:${apiPort}`)}`,
+      `Login      ${adminUser} / ${adminPassword ? 'the password you chose' : 'password printed at first boot'}`,
+      '',
+      'Then sign in, create an API key, and: npm install @memory-soda/sdk',
+    ].join('\n'),
+    'Run',
   );
-  console.log();
+  p.outro(`${chalk.bold(basename(target))} is ready.`);
 }
 
 /**
  * True when this file is the process entry point, false when it is imported.
- *
- * argv[1] must be resolved through realpath first: npm and npx invoke the bin
- * as a symlink in `node_modules/.bin`, while `import.meta.url` is already the
- * real path — comparing them raw makes every installed run a no-op.
+ * argv[1] is resolved through realpath: npm and npx invoke the bin as a
+ * symlink in node_modules/.bin, while import.meta.url is the real path.
  */
 function isEntryPoint() {
   if (!process.argv[1]) return false;
   try {
-    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+    return (
+      import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href
+    );
   } catch {
     return false;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-memory-soda",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Scaffold a self-hosted Memory Soda instance — API, dashboard, and Postgres",
   "keywords": [
     "ai",
@@ -36,6 +36,8 @@
     }
   },
   "dependencies": {
-    "chalk": "^5.6.2"
+    "@clack/prompts": "^1.7.0",
+    "chalk": "^5.6.2",
+    "pg": "^8.23.0"
   }
 }