@lorekit/cli 1.19.0 → 1.20.0

package/bin/lorekit.mjs

@@ -18,6 +18,7 @@ import { lint } from '../src/lint.mjs';
 import { dedupe } from '../src/dedupe.mjs';
 import { hook } from '../src/hook.mjs';
 import { migrate } from '../src/migrate.mjs';
+import { bootstrap } from '../src/bootstrap.mjs';
 import { mcpServer } from '../src/mcp-server.mjs';
 import { traceCommand } from '../src/telemetry.mjs';
 import { loadDotEnv } from '../src/dotenv.mjs';
@@ -80,6 +81,9 @@ ${c.bold('Commands')}
   dedupe      Find likely-duplicate memories via a zero-dep word-overlap HEURISTIC
               (Jaccard >= threshold, not semantic), grouped into clusters per
               store. --json, --scope <s>, --threshold <0..1>.
+  bootstrap   Apply the BYOD schema to a user-supplied Supabase database.
+              Only needed when using LOREKIT_STORAGE_URL / LOREKIT_STORAGE_ANON_KEY.
+              See docs/byod.md for setup instructions.
   migrate     Relocate a LoreKit-format local store into the current layout.
               Dry-run by default; pass --yes to apply. Idempotent.
   hook        Hook engine for Claude Code / Cursor / Codex. Reads the host's
@@ -613,6 +617,8 @@ async function main() {
       return traceCommand('dedupe', args, VERSION, () => dedupe(args));
     case 'migrate':
       return traceCommand('migrate', args, VERSION, () => migrate(args));
+    case 'bootstrap':
+      return traceCommand('bootstrap', args, VERSION, () => bootstrap(args));
     case 'write':
       return traceCommand('write', args, VERSION, () => write(args));
     default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/bootstrap.mjs

@@ -0,0 +1,141 @@
+// `lorekit bootstrap` — apply the BYOD schema to a user-supplied Supabase database.
+//
+// Reads LOREKIT_STORAGE_URL and LOREKIT_STORAGE_SERVICE_KEY from the environment.
+// If neither is set, prints a helpful message and exits 0 — bootstrap is only
+// needed for BYOD (Bring Your Own Database) setups.
+//
+// Because Supabase's JS client does not expose a raw SQL execution method for DDL,
+// this command instructs the user to run the SQL file directly with psql when no
+// direct execution path is available. It validates connectivity using the anon key
+// and confirms the bootstrap.sql path for the user.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+import { log, err, heading, status, c } from './util.mjs';
+
+// The bootstrap.sql file is at <repo-root>/supabase/byod/bootstrap.sql.
+// This file lives at packages/cli/src/bootstrap.mjs, so the relative path
+// from here to the repo root is ../../../  (src → cli → packages → root).
+const BOOTSTRAP_SQL_PATH = fileURLToPath(
+  new URL('../../../supabase/byod/bootstrap.sql', import.meta.url),
+);
+
+export async function bootstrap(_args) {
+  heading('LoreKit bootstrap');
+
+  const storageUrl = process.env['LOREKIT_STORAGE_URL'];
+  const storageServiceKey = process.env['LOREKIT_STORAGE_SERVICE_KEY'];
+  const storageAnonKey = process.env['LOREKIT_STORAGE_ANON_KEY'];
+
+  // If no BYOD env vars are set, this command is a no-op — it's only for BYOD.
+  if (!storageUrl && !storageServiceKey) {
+    log('');
+    log(
+      `  ${c.cyan('•')} No BYOD storage configured — ${c.dim('bootstrap is only needed for custom databases.')}`,
+    );
+    log('');
+    log('  Set LOREKIT_STORAGE_URL and LOREKIT_STORAGE_SERVICE_KEY to use your own');
+    log('  Supabase project, then re-run this command.');
+    log('');
+    log('  See docs/byod.md for setup instructions.');
+    return 0;
+  }
+
+  if (!storageUrl) {
+    err(`${c.red('Error:')} LOREKIT_STORAGE_SERVICE_KEY is set but LOREKIT_STORAGE_URL is missing.`);
+    err('  Both variables are required. Set LOREKIT_STORAGE_URL and try again.');
+    return 1;
+  }
+
+  // Locate the bootstrap SQL file.
+  let sqlPath = BOOTSTRAP_SQL_PATH;
+
+  // When running from a published npm package, the SQL file is not bundled
+  // with the CLI. Fall back to looking for it relative to CWD (for dev use).
+  if (!fs.existsSync(sqlPath)) {
+    const cwdPath = path.resolve(process.cwd(), 'supabase/byod/bootstrap.sql');
+    if (fs.existsSync(cwdPath)) {
+      sqlPath = cwdPath;
+    } else {
+      err(`${c.red('Error:')} bootstrap.sql not found at expected path:`);
+      err(`  ${sqlPath}`);
+      err('');
+      err('  Apply the schema manually with psql:');
+      err('    psql "$DATABASE_URL" -f supabase/byod/bootstrap.sql');
+      err('');
+      err('  Or download it from the LoreKit repository:');
+      err('    https://github.com/mthines/lorekit/blob/main/supabase/byod/bootstrap.sql');
+      return 1;
+    }
+  }
+
+  status('pass', 'bootstrap.sql', sqlPath);
+  status('info', 'storage url', storageUrl);
+
+  // Test connectivity using the anon key if available (non-DDL path).
+  if (storageAnonKey) {
+    try {
+      const { createClient } = await import('@supabase/supabase-js');
+      const db = createClient(storageUrl, storageAnonKey, {
+        auth: { persistSession: false, autoRefreshToken: false },
+      });
+      // Simple ping: list memories (will return 0 rows or error if schema not applied yet).
+      const { error } = await db.from('memories').select('id').limit(1);
+      if (error && error.code === '42P01') {
+        // Table does not exist yet — that's expected before bootstrap.
+        status('info', 'connectivity', 'connected — schema not yet applied (run bootstrap)');
+      } else if (error) {
+        status('warn', 'connectivity', `connected but got: ${error.message}`);
+      } else {
+        status('pass', 'connectivity', 'connected and schema already present');
+      }
+    } catch (e) {
+      status('warn', 'connectivity', `could not verify: ${e && e.message ? e.message : String(e)}`);
+    }
+  } else {
+    status('info', 'connectivity', 'skipped — LOREKIT_STORAGE_ANON_KEY not set');
+  }
+
+  // Supabase JS client cannot execute raw DDL SQL directly.
+  // The correct path is psql or the Supabase dashboard SQL editor.
+  log('');
+  log(`  ${c.bold('To apply the schema, run:')}`);
+  log('');
+  log(`    ${c.cyan('psql "$DATABASE_URL" -f')} ${sqlPath}`);
+  log('');
+  log(`  Or paste the contents of ${c.dim(sqlPath)}`);
+  log('  into the Supabase dashboard → SQL Editor.');
+  log('');
+
+  if (storageServiceKey) {
+    status(
+      'info',
+      'service key',
+      'LOREKIT_STORAGE_SERVICE_KEY is set — use it as $DATABASE_URL password with psql',
+    );
+    log('');
+    log(`  ${c.dim('Example:')}`);
+    log(
+      `    ${c.cyan('DATABASE_URL')}="postgresql://postgres.${parseRef(storageUrl)}:${storageServiceKey}@aws-0-us-east-1.pooler.supabase.com:6543/postgres"`,
+    );
+    log(`    ${c.cyan('psql "$DATABASE_URL"')} -f ${sqlPath}`);
+    log('');
+    log(
+      `  ${c.dim('(Replace the host/port above with the exact connection string from your')}`,
+    );
+    log(`  ${c.dim('Supabase dashboard → Settings → Database → Connection string.)')}`);
+  }
+
+  return 0;
+}
+
+// Extract the project ref from a Supabase URL for display in the example.
+function parseRef(url) {
+  try {
+    const host = new URL(url).hostname; // e.g. abcdefgh.supabase.co
+    return host.split('.')[0];
+  } catch {
+    return '<project-ref>';
+  }
+}

package/src/doctor.mjs

@@ -98,6 +98,9 @@ export async function doctor(args) {
     await checkRemote(control, root, args, record);
   }
 
+  // 4b. BYOD storage connectivity check.
+  await checkBYODStorage(record);
+
   // 5. Scope.
   const scope = deriveScope(root);
   if (scope.hasRemote) {
@@ -351,6 +354,40 @@ function hooksForEvent(hooksObj, event) {
   return commands;
 }
 
+async function checkBYODStorage(record) {
+  const storageUrl = process.env['LOREKIT_STORAGE_URL'];
+  const storageAnonKey = process.env['LOREKIT_STORAGE_ANON_KEY'];
+
+  if (!storageUrl && !storageAnonKey) {
+    return; // No BYOD configured — skip silently.
+  }
+
+  if (storageUrl && !storageAnonKey) {
+    record('fail', 'byod storage', 'LOREKIT_STORAGE_URL is set but LOREKIT_STORAGE_ANON_KEY is missing');
+    return;
+  }
+
+  if (!storageUrl && storageAnonKey) {
+    record('fail', 'byod storage', 'LOREKIT_STORAGE_ANON_KEY is set but LOREKIT_STORAGE_URL is missing');
+    return;
+  }
+
+  try {
+    const { createClient } = await import('@supabase/supabase-js');
+    const db = createClient(storageUrl, storageAnonKey, {
+      auth: { persistSession: false, autoRefreshToken: false },
+    });
+    const { error } = await db.from('memories').select('id').limit(1);
+    if (error && error.code !== '42P01') {
+      record('fail', 'byod storage', `connectivity error: ${error.message}`);
+    } else {
+      record('pass', 'byod storage', `ok — ${storageUrl}`);
+    }
+  } catch (e) {
+    record('fail', 'byod storage', `could not connect: ${e && e.message ? e.message : String(e)}`);
+  }
+}
+
 function gitTracked(root, dir) {
   // Heuristic: is the store dir ignored by git? If `git check-ignore` names it,
   // it is private; otherwise it will be committed (team-shared).