create-memory-soda 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # create-memory-soda
 
-Scaffold a self-hosted [memory-soda](https://github.com/alagappan17/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.
 
 ```bash
@@ -9,7 +9,9 @@ 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.
+writes `.env`, installs dependencies, creates the database if it is missing,
+and verifies pgvector is available. Clone and install run behind a spinner;
+pass `--verbose` to stream their full output instead.
 
 ```bash
 cd memory-soda
@@ -21,17 +23,11 @@ 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):
-```
+You bring the server; the installer creates the database. It asks for a
+`DATABASE_URL`, probes the host and port while you are still at the prompt, and
+after install connects for real. A missing database is created for you (the
+role in the URL needs `CREATEDB`). Anything else — server down, bad password,
+no pgvector — names the fix and lets you retry without starting over.
 
 The role in the URL needs permission to `CREATE EXTENSION vector` — the first
 migration creates the extension. On most installations that means a superuser.

package/index.js

@@ -1,34 +1,27 @@
 #!/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 { spawn, 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 { connect } from 'node:net';
-import { stdin, stdout, exit } from 'node:process';
+import { exit } from 'node:process';
 import { pathToFileURL } from 'node:url';
+import * as p from '@clack/prompts';
 import chalk from 'chalk';
 
 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 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. */
@@ -40,19 +33,47 @@ function tryRun(cmd, args, opts = {}) {
   }
 }
 
+/**
+ * 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
  * this file does not drift every time a new option is added there.
  */
-export function renderEnv({
-  databaseUrl,
-  geminiKey,
-  adminUser,
-  adminPassword,
-  apiPort,
-  dashboardPort,
-}) {
+export function renderEnv({ databaseUrl, geminiKey, adminUser, adminPassword, apiPort, dashboardPort }) {
   const lines = [
     '# Generated by create-memory-soda.',
     '# Full reference: https://github.com/alagappan17/memory-soda',
@@ -60,15 +81,15 @@ 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',
-    '# NEXT_PUBLIC_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}`,
-    `NEXT_PUBLIC_API_URL=http://localhost:${apiPort}`,
+    `VITE_API_URL=http://localhost:${apiPort}`,
     '',
     '# Dashboard login, created once on first boot.',
     `ADMIN_USERNAME=${adminUser}`,
@@ -89,8 +110,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,6 +137,26 @@ function isReachable({ host, port }, timeout = 2000) {
   });
 }
 
+function loadPg(target) {
+  const require = createRequire(pathToFileURL(join(target, 'package.json')));
+  return require('pg').Client;
+}
+
+/** Create the database named in the URL by connecting to the maintenance db on the same server. */
+async function createDatabase(target, databaseUrl) {
+  const Client = loadPg(target);
+  const url = new URL(databaseUrl);
+  const db = decodeURIComponent(url.pathname.slice(1));
+  url.pathname = '/postgres';
+  const client = new Client({ connectionString: url.href });
+  try {
+    await client.connect();
+    await client.query(`CREATE DATABASE "${db.replaceAll('"', '""')}"`);
+  } finally {
+    await client.end().catch(() => {});
+  }
+}
+
 /**
  * Connect for real and confirm pgvector is installable, using the `pg` copy
  * inside the freshly installed project so the installer needs no database
@@ -125,8 +165,7 @@ function isReachable({ host, port }, timeout = 2000) {
 export async function checkDatabase(target, databaseUrl) {
   let Client;
   try {
-    const require = createRequire(pathToFileURL(join(target, 'package.json')));
-    ({ Client } = require('pg'));
+    Client = loadPg(target);
   } catch {
     return { skipped: 'could not load pg from the new project' };
   }
@@ -134,23 +173,18 @@ export async function checkDatabase(target, databaseUrl) {
   const client = new Client({ connectionString: databaseUrl });
   try {
     await client.connect();
-    const { rows } = await client.query(
-      "SELECT 1 FROM pg_available_extensions WHERE name = 'vector'",
-    );
+    const { rows } = await client.query("SELECT 1 FROM pg_available_extensions WHERE name = 'vector'");
     if (rows.length === 0) {
       return {
         problem: 'pgvector is not available on this server',
-        fix: 'Install it — brew install pgvector, or apt install postgresql-16-pgvector.',
+        fix: 'Install it — brew install pgvector, or apt install postgresql-16-pgvector — then retry.',
       };
     }
     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}`,
-      };
+      return { problem: `database "${db}" does not exist`, fix: `createdb ${db}`, missingDb: db };
     }
     if (err.code === '28P01' || err.code === '28000') {
       return { problem: 'authentication failed', fix: 'Check the user and password in the URL.' };
@@ -167,119 +201,111 @@ export async function checkDatabase(target, databaseUrl) {
   }
 }
 
+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.';
+};
+
 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`,
-  );
-
-  // 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.`);
-    }
-  };
+  console.log();
+  p.intro(`${chalk.bgCyan.black(' Memory Soda ')} ${chalk.dim('self-hosted memory for AI agents')}`);
 
-  const dirName = process.argv[2] || (await ask('Folder name', 'memory-soda'));
+  const dirArg = process.argv.slice(2).find((a) => !a.startsWith('-'));
+  const dirName =
+    dirArg ||
+    guard(
+      await p.text({
+        message: 'Where should we create your project?',
+        placeholder: 'memory-soda',
+        defaultValue: 'memory-soda',
+        validate: (v) =>
+          isUsableTarget(resolve(process.cwd(), v || 'memory-soda')) ? undefined : 'That folder exists and is not empty.',
+      }),
+    );
   const target = resolve(process.cwd(), dirName);
-  if (!isUsableTarget(target)) {
-    rl.close();
-    die(`${target} already exists and is not empty.`);
-  }
+  if (!isUsableTarget(target)) die(`${target} already exists and is not empty.`);
 
-  const geminiKey = await ask('Gemini API key');
-  if (!geminiKey) note('No key given — set it in .env before starting.');
+  const geminiKey = guard(
+    await p.password({
+      message: `Gemini API key ${chalk.dim('(aistudio.google.com — required for the memory layer, leave blank to add to .env later)')}`,
+      mask: '•',
+    }),
+  ) ?? '';
+  if (!geminiKey) p.log.warn('No key given. Memory extraction and search will not work until GOOGLE_GENERATIVE_AI_API_KEY is set in .env.');
 
-  console.log(
-    `\n${chalk.bold('Postgres')} ${chalk.dim('— bring your own, with the pgvector extension available')}`,
+  let databaseUrl = guard(
+    await p.text({
+      message: `Postgres URL ${chalk.dim('(bring your own — pgvector must be installed; the database itself is created for you)')}`,
+      placeholder: DEFAULT_DB,
+      defaultValue: DEFAULT_DB,
+      validate: (v) => (v && !parsePostgresUrl(v) ? 'Expected a postgres:// URL.' : undefined),
+    }),
   );
-  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))) {
+  if (addr && !(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.`);
+    p.log.warn(`Nothing is listening on ${addr.host}:${addr.port} right now — checked again after install.`);
   }
 
-  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)')}`,
+  const apiPort = Number(guard(await p.text({ message: 'API port', placeholder: '3004', defaultValue: '3004', validate: validPort })));
+  const dashboardPort = Number(
+    guard(await p.text({ message: 'Dashboard port', placeholder: '3000', defaultValue: '3000', validate: validPort })),
   );
+  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: '•' })) ?? '';
 
-  console.log();
-  step(`Cloning into ${chalk.bold(dirName)}`);
-  run('git', ['clone', '--depth', '1', REPO, target]);
+  await runWithSpinner(`Cloning into ${chalk.bold(dirName)}`, 'git', ['clone', '--depth', '1', REPO, target]);
   rmSync(resolve(target, '.git'), { recursive: true, force: true });
 
   const writeEnv = () =>
-    writeFileSync(
-      resolve(target, '.env'),
-      renderEnv({
-        databaseUrl,
-        geminiKey,
-        adminUser,
-        adminPassword,
-        apiPort,
-        dashboardPort,
-      }),
-    );
+    writeFileSync(resolve(target, '.env'), renderEnv({ databaseUrl, geminiKey, adminUser, adminPassword, apiPort, dashboardPort }));
   writeEnv();
-  step('Wrote .env');
+  p.log.success('Wrote .env');
 
-  step(`Installing dependencies ${chalk.dim('(this takes a minute)')}`);
-  run('npm', ['install'], { cwd: target });
+  await runWithSpinner('Installing dependencies', 'npm', ['ci', '--no-audit', '--no-fund'], { cwd: target });
 
   // 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.
   for (;;) {
-    step('Checking the database');
-    const result = await checkDatabase(target, databaseUrl);
+    const s = p.spinner();
+    s.start('Checking the database');
+    let result = await checkDatabase(target, databaseUrl);
+    if (result?.missingDb) {
+      s.message(`Creating database ${result.missingDb}`);
+      try {
+        await createDatabase(target, databaseUrl);
+        result = await checkDatabase(target, databaseUrl);
+      } catch (err) {
+        result = { problem: `could not create database "${result.missingDb}": ${err.message}`, fix: result.fix };
+      }
+    }
     if (result === null) {
-      note('Connected, and pgvector is available.');
+      s.stop('Database ready — connected, pgvector available');
       break;
     }
     if (result.skipped) {
-      note(`Skipped — ${result.skipped}.`);
+      s.stop(`Database check skipped — ${result.skipped}`, 1);
       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)')}`,
-    );
+    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') {
-      note('Skipped — the API will fail on boot until this is resolved.');
+      p.log.warn('Skipped — the API will fail on boot until this is resolved.');
       break;
     }
     if (retry) {
@@ -288,28 +314,27 @@ async function main() {
     }
   }
 
-  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}`)}`,
+  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'}`,
+      '',
+      'First boot applies migrations and prints your API key once.',
+      ...(geminiKey ? [] : ['Set GOOGLE_GENERATIVE_AI_API_KEY in .env before starting.']),
+    ].join('\n'),
+    'Next steps',
   );
-  note(
-    adminPassword
-      ? `Log in as ${adminUser} with the password you chose.`
-      : `Log in as ${adminUser} — the generated password is printed at first boot.`,
-  );
-  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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-memory-soda",
-  "version": "0.1.0",
-  "description": "Scaffold a self-hosted memory-soda instance — API, dashboard, and Postgres",
+  "version": "0.2.0",
+  "description": "Scaffold a self-hosted Memory Soda instance — API, dashboard, and Postgres",
   "keywords": [
     "ai",
     "memory",
@@ -13,7 +13,7 @@
   "license": "MIT",
   "type": "module",
   "bin": {
-    "create-memory-soda": "./index.js"
+    "create-memory-soda": "index.js"
   },
   "files": [
     "index.js",
@@ -36,6 +36,7 @@
     }
   },
   "dependencies": {
+    "@clack/prompts": "^1.7.0",
     "chalk": "^5.6.2"
   }
 }