create-memory-soda 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# 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.
+
+```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.
+
+```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.
+
+## Requirements
+
+Node 20+, git, and a Postgres 14+ with the pgvector extension available.

package/index.js

@@ -0,0 +1,326 @@
+#!/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 { connect } from 'node:net';
+import { stdin, stdout, exit } from 'node:process';
+import { pathToFileURL } from 'node:url';
+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}`));
+
+function die(msg) {
+  console.error(`\n${chalk.red('✗')} ${msg}\n`);
+  exit(1);
+}
+
+function run(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, { stdio: 'inherit', ...opts });
+}
+
+/** 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 });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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,
+}) {
+  const lines = [
+    '# Generated by create-memory-soda.',
+    '# Full reference: https://github.com/alagappan17/memory-soda',
+    '',
+    '# PostgreSQL — must have the pgvector extension available.',
+    `DATABASE_URL=${databaseUrl}`,
+    '',
+    '# Google Gemini — 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.',
+    `PORT=${apiPort}`,
+    `DASHBOARD_PORT=${dashboardPort}`,
+    `CORS_ORIGIN=http://localhost:${dashboardPort}`,
+    `NEXT_PUBLIC_API_URL=http://localhost:${apiPort}`,
+    '',
+    '# Dashboard login, created once on first boot.',
+    `ADMIN_USERNAME=${adminUser}`,
+  ];
+  // An unset ADMIN_PASSWORD makes the API generate one and print it once. That
+  // is a better default than writing a weak chosen password to disk, so a blank
+  // answer omits the key entirely rather than writing an empty one.
+  if (adminPassword) lines.push(`ADMIN_PASSWORD=${adminPassword}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** True if the path is safe to scaffold into: missing, or an empty directory. */
+export function isUsableTarget(dir) {
+  if (!existsSync(dir)) return true;
+  return readdirSync(dir).filter((f) => f !== '.DS_Store').length === 0;
+}
+
+/**
+ * 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.
+ */
+export function parsePostgresUrl(url) {
+  try {
+    const u = new URL(url);
+    if (!u.protocol.startsWith('postgres')) return null;
+    return { host: u.hostname || 'localhost', port: Number(u.port) || 5432 };
+  } catch {
+    return null;
+  }
+}
+
+/** Is something accepting TCP connections there? Cheap pre-flight, 2s budget. */
+function isReachable({ host, port }, timeout = 2000) {
+  return new Promise((done) => {
+    const socket = connect({ host, port });
+    const finish = (result) => {
+      socket.destroy();
+      done(result);
+    };
+    socket.setTimeout(timeout);
+    socket.once('connect', () => finish(true));
+    socket.once('timeout', () => finish(false));
+    socket.once('error', () => finish(false));
+  });
+}
+
+/**
+ * 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;
+  try {
+    const require = createRequire(pathToFileURL(join(target, 'package.json')));
+    ({ Client } = require('pg'));
+  } catch {
+    return { skipped: 'could not load pg from the new project' };
+  }
+
+  const client = new 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) {
+      return {
+        problem: 'pgvector is not available on this server',
+        fix: 'Install it — brew install pgvector, or apt install postgresql-16-pgvector.',
+      };
+    }
+    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}`,
+      };
+    }
+    if (err.code === '28P01' || err.code === '28000') {
+      return { problem: 'authentication failed', fix: 'Check the user and password in the URL.' };
+    }
+    if (err.code === 'ECONNREFUSED') {
+      return {
+        problem: 'nothing is accepting connections at that host and port',
+        fix: 'Start Postgres — brew services start postgresql, or pg_ctl start.',
+      };
+    }
+    return { problem: err.message, fix: null };
+  } finally {
+    await client.end().catch(() => {});
+  }
+}
+
+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.`);
+    }
+  };
+
+  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.`);
+  }
+
+  const geminiKey = await ask('Gemini API key');
+  if (!geminiKey) note('No key given — set it in .env before starting.');
+
+  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.`);
+  }
+
+  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)')}`,
+  );
+
+  console.log();
+  step(`Cloning into ${chalk.bold(dirName)}`);
+  run('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,
+      }),
+    );
+  writeEnv();
+  step('Wrote .env');
+
+  step(`Installing dependencies ${chalk.dim('(this takes a minute)')}`);
+  run('npm', ['install'], { 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);
+    if (result === null) {
+      note('Connected, and pgvector is available.');
+      break;
+    }
+    if (result.skipped) {
+      note(`Skipped — ${result.skipped}.`);
+      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 (retry.toLowerCase() === 's') {
+      note('Skipped — the API will fail on boot until this is resolved.');
+      break;
+    }
+    if (retry) {
+      databaseUrl = retry;
+      writeEnv();
+    }
+  }
+
+  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}`)}`,
+  );
+  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();
+}
+
+/**
+ * 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.
+ */
+function isEntryPoint() {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+}
+
+// Importing this file (tests) must not start an interactive session.
+if (isEntryPoint()) {
+  main().catch((err) => die(err.message));
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "create-memory-soda",
+  "version": "0.1.0",
+  "description": "Scaffold a self-hosted memory-soda instance — API, dashboard, and Postgres",
+  "keywords": [
+    "ai",
+    "memory",
+    "agent",
+    "llm",
+    "create",
+    "scaffold"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-memory-soda": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "nx": {
+    "targets": {
+      "test": {
+        "executor": "nx:run-commands",
+        "options": {
+          "command": "node --test packages/create-memory-soda/*.test.js"
+        }
+      }
+    }
+  },
+  "dependencies": {
+    "chalk": "^5.6.2"
+  }
+}