draftgo-cli 1.0.4

package/src/fsx.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function exists(p) {
+  try { fs.accessSync(p); return true; } catch { return false; }
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function readText(p) {
+  return fs.readFileSync(p, 'utf8');
+}
+
+function writeText(p, content) {
+  ensureDir(path.dirname(p));
+  fs.writeFileSync(p, content, 'utf8');
+}
+
+function copyFile(src, dest) {
+  ensureDir(path.dirname(dest));
+  fs.copyFileSync(src, dest);
+}
+
+function copyDir(src, dest) {
+  if (!exists(src)) return;
+  ensureDir(dest);
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isSymbolicLink()) {
+      ensureDir(path.dirname(d));
+      const target = fs.readlinkSync(s);
+      try { fs.symlinkSync(target, d); }
+      catch (e) { if (e.code !== 'EEXIST') throw e; }
+    } else if (entry.isDirectory()) copyDir(s, d);
+    else if (entry.isFile()) copyFile(s, d);
+  }
+}
+
+function removePath(p) {
+  if (!exists(p)) return false;
+  fs.rmSync(p, { recursive: true, force: true });
+  return true;
+}
+
+function appendGitignoreLine(projectDir, line) {
+  const gi = path.join(projectDir, '.gitignore');
+  const content = exists(gi) ? readText(gi) : '';
+  if (content.split(/\r?\n/).some((l) => l.trim() === line)) return;
+  const sep = content && !content.endsWith('\n') ? '\n' : '';
+  fs.appendFileSync(gi, `${sep}${line}\n`);
+}
+
+module.exports = {
+  exists,
+  ensureDir,
+  readText,
+  writeText,
+  copyFile,
+  copyDir,
+  removePath,
+  appendGitignoreLine,
+};

package/src/index.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const path = require('path');
+const { parse } = require('./cli');
+const { resolveCommand } = require('./commandRegistry');
+const { configureConsoleUtf8 } = require('./consoleEncoding');
+const log = require('./logger');
+
+async function run(argv) {
+  configureConsoleUtf8();
+  const { command, positional, flags, errors } = parse(argv);
+
+  if (errors.length) {
+    for (const error of errors) log.err(error);
+    require('./commands/help')();
+    return 1;
+  }
+
+  // --version / --help shortcuts
+  if (flags.version || flags.v || command === 'version') {
+    console.log(require('./skill').getPackageVersion());
+    return 0;
+  }
+  if (!command || flags.help || flags.h || command === 'help') {
+    require('./commands/help')();
+    return 0;
+  }
+
+  const projectDir = flags.project
+    ? path.resolve(String(flags.project))
+    : process.cwd();
+
+  try {
+    const definition = resolveCommand(command);
+    if (definition) return await definition.run(projectDir, positional, flags);
+    log.err(`未知命令：${command}`);
+    require('./commands/help')();
+    return 1;
+  } catch (e) {
+    log.err(e.message || String(e));
+    if (process.env.DEBUG) console.error(e.stack);
+    return 1;
+  }
+}
+
+module.exports = { run };

package/src/localRuntime/compose.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const crypto = require('crypto');
+const path = require('path');
+const fs = require('fs');
+const { ensureDir, exists, readText, writeText } = require('../fsx');
+
+function stackDir(projectDir) { return path.join(projectDir, '.draftgo', 'docker'); }
+function composePath(projectDir) { return path.join(stackDir(projectDir), 'docker-compose.yaml'); }
+function envPath(projectDir) { return path.join(stackDir(projectDir), '.env'); }
+
+function randomHex(bytes) { return crypto.randomBytes(bytes).toString('hex'); }
+
+function readEnv(projectDir) {
+  if (!exists(envPath(projectDir))) return {};
+  const out = {};
+  for (const line of readText(envPath(projectDir)).split(/\r?\n/)) {
+    const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (match) out[match[1]] = match[2];
+  }
+  return out;
+}
+
+function writeEnv(projectDir, env) {
+  writeText(envPath(projectDir), `${Object.entries(env).map(([key, value]) => `${key}=${value}`).join('\n')}\n`);
+  fs.chmodSync(envPath(projectDir), 0o600);
+}
+
+function sanitizeProjectName(raw, fallback = 'draftgo') {
+  const value = String(raw || '').trim().toLowerCase().replace(/[^a-z0-9_-]/g, '-').replace(/^[-_]+/, '');
+  return value || fallback;
+}
+
+function dockerHost(host) {
+  return host === 'localhost' || host === '127.0.0.1' ? 'host.docker.internal' : host;
+}
+
+function generate(projectDir, opts) {
+  const root = stackDir(projectDir);
+  if (exists(composePath(projectDir)) && readText(composePath(projectDir)).includes('./data/storage:/app/data/storage')) {
+    throw new Error('Existing runtime uses legacy storage. Back up and migrate its data to the final DraftGo /app/data layout before regenerating Compose; existing files were preserved.');
+  }
+  ensureDir(root);
+  const env = readEnv(projectDir);
+  const projectName = sanitizeProjectName(opts.projectName, 'draftgo');
+  const database = opts.mysql.database;
+  const qdrant = opts.qdrant || { host: '127.0.0.1', port: 26333, apiKey: '' };
+
+  env.APP_PORT = String(opts.appPort || 7777);
+  env.SECRET_KEY = env.SECRET_KEY || randomHex(32);
+  env.SYSTEM_CONFIG_MASTER_KEY = env.SYSTEM_CONFIG_MASTER_KEY || randomHex(32);
+  env.DATABASE_URL = `mysql://${encodeURIComponent(opts.mysql.user)}:${encodeURIComponent(opts.mysql.password)}@${dockerHost(opts.mysql.host)}:${opts.mysql.port}/${encodeURIComponent(database)}`;
+  env.REDIS_URL = 'redis://redis:6379/0';
+  for (const key of ['REDIS_HOST', 'REDIS_PORT', 'REDIS_PASSWORD', 'REDIS_KEY_PREFIX']) delete env[key];
+  env.QDRANT_URL = qdrant ? `http://${dockerHost(qdrant.host)}:${qdrant.port}` : '';
+  env.QDRANT_API_KEY = qdrant ? (qdrant.apiKey || '') : '';
+  env.QDRANT_COLLECTION_PREFIX = database;
+
+  const yaml = [
+    '# Generated by draftgo-cli. MySQL and Qdrant are shared; Redis is project-isolated.',
+    `name: ${projectName}`,
+    'services:',
+    '  app:',
+    `    image: ${opts.image || 'cabinai/draftgo:latest'}`,
+    `    container_name: ${projectName}`,
+    '    restart: unless-stopped',
+    '    ports:',
+    '      - "${APP_PORT}:3000"',
+    '    environment:',
+    '      APP_ENV: production',
+    '      APP_HOST: 0.0.0.0',
+    '      APP_PORT: "3000"',
+    '      PUBLIC_BASE_URL: http://localhost:${APP_PORT}',
+    '      DATABASE_URL: ${DATABASE_URL}',
+    '      SECRET_KEY: ${SECRET_KEY}',
+    '      SYSTEM_CONFIG_MASTER_KEY: ${SYSTEM_CONFIG_MASTER_KEY}',
+    '      REDIS_URL: ${REDIS_URL}',
+    '      QDRANT_URL: ${QDRANT_URL}',
+    '      QDRANT_API_KEY: ${QDRANT_API_KEY}',
+    '      QDRANT_COLLECTION_PREFIX: ${QDRANT_COLLECTION_PREFIX}',
+    '      FILE_STORAGE_ROOT: /app/data/files',
+    '    volumes:',
+    '      - app_data:/app/data',
+    '    healthcheck:',
+    '      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:3000/api/system/health"]',
+    '      interval: 10s',
+    '      timeout: 5s',
+    '      start_period: 10s',
+    '      retries: 6',
+    '    depends_on:',
+    '      redis:',
+    '        condition: service_healthy',
+    '    extra_hosts:',
+    '      - "host.docker.internal:host-gateway"',
+    '  redis:',
+    '    image: redis:7.4-alpine',
+    '    restart: unless-stopped',
+    '    command: ["redis-server", "--appendonly", "yes"]',
+    '    volumes:',
+    '      - redis_data:/data',
+    '    healthcheck:',
+    '      test: ["CMD", "redis-cli", "ping"]',
+    '      interval: 5s',
+    '      timeout: 5s',
+    '      retries: 20',
+    'volumes:',
+    '  app_data:',
+    '  redis_data:',
+    '',
+  ].join('\n');
+  writeText(composePath(projectDir), yaml);
+  writeEnv(projectDir, env);
+  return { dir: root, composeFile: composePath(projectDir), envFile: envPath(projectDir), projectName, env };
+}
+
+module.exports = {
+  stackDir, composePath, envPath,
+  generate, sanitizeProjectName, randomHex,
+};

package/src/localRuntime/detect.js

@@ -0,0 +1,77 @@
+'use strict';
+
+// Environment detection helpers for the local stack setup wizard.
+//   - probePort:      TCP probe (used to find existing MySQL/Redis)
+//   - probeHttp:      HTTP GET probe with retry (used to wait for the app)
+//   - detectDocker:   Find a working `docker` + `docker compose` (or `docker-compose`)
+
+const net = require('net');
+const http = require('http');
+const { spawnSync } = require('child_process');
+
+function probePort(host, port, timeoutMs = 800) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let done = false;
+    const finish = (ok) => {
+      if (done) return;
+      done = true;
+      try { socket.destroy(); } catch {}
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => finish(true));
+    socket.once('timeout', () => finish(false));
+    socket.once('error', () => finish(false));
+    try { socket.connect(port, host); } catch { finish(false); }
+  });
+}
+
+function probeHttpOnce(url, timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    try {
+      const req = http.get(url, { timeout: timeoutMs }, (res) => {
+        res.resume();
+        resolve(res.statusCode >= 200 && res.statusCode < 300);
+      });
+      req.on('timeout', () => { req.destroy(); resolve(false); });
+      req.on('error', () => resolve(false));
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+async function probeHttp(url, { totalMs = 90000, intervalMs = 1500 } = {}) {
+  const start = Date.now();
+  while (Date.now() - start < totalMs) {
+    if (await probeHttpOnce(url)) return true;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
+function tryCmd(cmd, args) {
+  try {
+    const r = spawnSync(cmd, args, { encoding: 'utf8', shell: false });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function detectDocker() {
+  const hasDocker = tryCmd('docker', ['--version']);
+  if (!hasDocker) return { ok: false, reason: 'docker-missing' };
+  if (!tryCmd('docker', ['info', '--format', '{{.ServerVersion}}'])) return { ok: false, reason: 'docker-not-running' };
+  // Prefer `docker compose` (plugin); fall back to legacy `docker-compose`.
+  if (tryCmd('docker', ['compose', 'version'])) {
+    return { ok: true, composeCmd: 'docker', composeArgs: ['compose'] };
+  }
+  if (tryCmd('docker-compose', ['version'])) {
+    return { ok: true, composeCmd: 'docker-compose', composeArgs: [] };
+  }
+  return { ok: false, reason: 'compose-missing' };
+}
+
+module.exports = { probePort, probeHttp, probeHttpOnce, detectDocker };

package/src/localRuntime/index.js

@@ -0,0 +1,211 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const log = require('../logger');
+const { askRequired, askPassword, confirm } = require('../prompt');
+const { probePort, probeHttp, detectDocker } = require('./detect');
+const compose = require('./compose');
+const { ensureDatabase, testConnection, describeClient } = require('./mysqlClient');
+const { defaults, portOpen, probeQdrant, startService } = require('./services');
+const { writeProjectConfig } = require('../projectConfig');
+const { appendGitignoreLine, exists, readText } = require('../fsx');
+
+const DEFAULT_APP_PORT = 7777;
+
+async function promptMysqlConnection() {
+  while (true) {
+    const host = await askRequired('  MySQL host', { default: '127.0.0.1' });
+    const port = Number(await askRequired('  MySQL port', { default: '3306' }));
+    const user = await askRequired('  MySQL user', { default: 'draftgo' });
+    const password = await askPassword('  MySQL password', { default: 'draftgo' });
+    const conn = { host, port, user, password };
+    const result = testConnection(conn);
+    if (result.ok) return conn;
+    log.err(`  MySQL connection failed: ${(result.detail || result.reason || 'unknown error').split('\n')[0]}`);
+  }
+}
+
+async function ensureProjectDatabase(conn, database, interactive = true) {
+  while (true) {
+    const result = await ensureDatabase({ ...conn, database }, {
+      rootPromptFn: async () => {
+        if (!interactive) return null;
+        log.warn(`  ${conn.user} cannot create database ${database}.`);
+        if (!await confirm('  Create it with another MySQL account?', { default: true })) return null;
+        return {
+          user: await askRequired('  MySQL admin user', { default: 'root' }),
+          password: await askPassword('  MySQL admin password'),
+        };
+      },
+    });
+    if (result.ok) return { ...conn, database };
+    log.err(`  Database setup failed: ${(result.detail || result.reason || 'unknown error').split('\n')[0]}`);
+    if (!interactive) throw new Error('Database setup needs credentials. Run `draftgo local setup` in a terminal to continue.');
+    const retry = await confirm('  Re-enter MySQL connection settings?', { default: true });
+    if (!retry) throw new Error('MySQL database was not prepared.');
+    conn = await promptMysqlConnection();
+  }
+}
+
+async function planMysql(docker, defaultDatabase, interactive = true) {
+  log.step('Checking MySQL');
+  let conn = { ...defaults.mysql };
+  if (!await portOpen(conn.host, conn.port)) {
+    log.dim('  MySQL is not running locally; starting the shared local service.');
+    if (!startService(docker, 'mysql')) throw new Error('Unable to start shared MySQL.');
+  }
+  if (!testConnection(conn).ok) {
+    log.warn('  Default MySQL credentials were not accepted.');
+    if (!interactive) throw new Error('MySQL needs credentials. Run `draftgo local setup` in a terminal to continue.');
+    conn = await promptMysqlConnection();
+  }
+  const database = interactive ? await askRequired('  Project database name', { default: defaultDatabase }) : defaultDatabase;
+  const out = await ensureProjectDatabase(conn, database, interactive);
+  log.ok(`  MySQL ready: ${out.host}:${out.port}/${out.database} (${describeClient()})`);
+  return out;
+}
+
+async function promptQdrantConnection() {
+  while (true) {
+    const host = await askRequired('  Qdrant host', { default: '127.0.0.1' });
+    const port = Number(await askRequired('  Qdrant port', { default: '26333' }));
+    const apiKey = await askPassword('  Qdrant API key (empty for none)', { default: '' });
+    const conn = { host, port, apiKey };
+    if (await probeQdrant(conn)) return conn;
+    log.err('  Qdrant REST health check failed. Check the address and API key.');
+  }
+}
+
+async function planQdrant(docker, interactive = true) {
+  log.step('Checking Qdrant');
+  let conn = { ...defaults.qdrant };
+  if (!await portOpen(conn.host, conn.port)) {
+    log.dim('  Qdrant is not running locally; starting the shared local service.');
+    if (!startService(docker, 'qdrant')) throw new Error('Unable to start shared Qdrant.');
+  }
+  if (!await probeQdrant(conn)) {
+    log.warn('  Default unauthenticated Qdrant REST health check failed.');
+    if (!interactive) throw new Error('Qdrant needs credentials. Run `draftgo local setup` in a terminal to continue.');
+    conn = await promptQdrantConnection();
+  }
+  log.ok(`  Qdrant ready: ${conn.host}:${conn.port}`);
+  return conn;
+}
+
+async function pickAppPort(interactive = true) {
+  if (!interactive) {
+    for (let port = DEFAULT_APP_PORT; port < DEFAULT_APP_PORT + 100; port += 1) {
+      if (!await probePort('127.0.0.1', port)) return port;
+    }
+    throw new Error('No free local port found. Run `draftgo local setup` in a terminal to select a port.');
+  }
+  const taken = await probePort('127.0.0.1', DEFAULT_APP_PORT);
+  const suggested = String(taken ? DEFAULT_APP_PORT + 1 : DEFAULT_APP_PORT);
+  while (true) {
+    const port = Number(await askRequired('  DraftGo host port', { default: suggested }));
+    if (!Number.isInteger(port) || port < 1 || port > 65535) continue;
+    if (!await probePort('127.0.0.1', port)) return port;
+    if (await confirm(`  Port ${port} is in use. Use it anyway?`, { default: false })) return port;
+  }
+}
+
+async function pickProjectName() {
+  while (true) {
+    const raw = await askRequired('  Project container prefix', { default: 'draftgo' });
+    const clean = compose.sanitizeProjectName(raw, '');
+    if (clean) return clean;
+  }
+}
+
+function composeUp(docker, dir) {
+  const result = spawnSync(docker.composeCmd, [...docker.composeArgs, '-f', 'docker-compose.yaml', 'up', '-d'], {
+    cwd: dir, stdio: 'inherit', shell: false,
+  });
+  return result.status === 0;
+}
+
+async function waitForApp(appPort) {
+  const ok = await probeHttp(`http://127.0.0.1:${appPort}/api/system/health`, { totalMs: 120000, intervalMs: 2000 });
+  if (!ok) log.err('  Timed out waiting for DraftGo. Run `draftgo local logs` to inspect the app.');
+  return ok;
+}
+
+async function finishMcpSetup(projectDir, mcpCommands) {
+  const commands = mcpCommands || require('../commands/mcp');
+  const setupMcp = commands.setupMcp || commands.setup;
+  const testMcp = commands.testMcp || commands.test;
+  if (typeof setupMcp !== 'function' || typeof testMcp !== 'function') {
+    log.warn('  MCP setup helpers are unavailable. Run `draftgo mcp setup` after updating the CLI.');
+    return false;
+  }
+
+  let setupOk = false;
+  try {
+    setupOk = await setupMcp(projectDir, [], { yes: true }) === 0;
+  } catch {
+    log.warn('  MCP host setup failed. Retry with `draftgo mcp setup`.');
+  }
+
+  let testOk = false;
+  try {
+    testOk = await testMcp(projectDir, {}) === 0;
+  } catch {
+    log.warn('  MCP validation failed. Run `draftgo mcp test` for diagnostics.');
+  }
+  if (!testOk) {
+    log.dim('  The local stack and project config are ready; MCP may still be starting.');
+  }
+  return setupOk && testOk;
+}
+
+async function runWizard(projectDir, { yes = false, mcpCommands, interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !yes, params = {} } = {}) {
+  log.title('draftgo local setup');
+  if (!yes && !interactive) throw new Error('Run `draftgo local setup --yes` for unattended setup, or use a terminal for guided setup.');
+  if (!yes && !await confirm('Continue with local DraftGo setup?', { default: true })) return 0;
+
+  const docker = detectDocker();
+  if (!docker.ok) {
+    throw new Error(docker.reason === 'compose-missing'
+      ? 'Install Docker Compose: https://docs.docker.com/compose/install/ then retry `draftgo local setup`.'
+      : docker.reason === 'docker-not-running'
+        ? 'Start Docker Desktop or the Docker daemon, then retry `draftgo local setup`. Installed Skills are preserved.'
+        : 'Install Docker: https://docs.docker.com/get-started/get-docker/ then start it and retry `draftgo local setup`. Installed Skills are preserved.');
+  }
+
+  if (exists(compose.composePath(projectDir))) {
+    if (readText(compose.composePath(projectDir)).includes('./data/storage:/app/data/storage')) {
+      throw new Error('Existing runtime uses legacy storage. Back up and migrate it to final DraftGo before setup; Compose and data were preserved.');
+    }
+    log.dim('  Existing project runtime preserved. Use `draftgo local start` to resume it, then `draftgo connect` to bind your API Key.');
+    return 0;
+  }
+  const appPort = params.appPort || await pickAppPort(interactive);
+  const projectName = params.projectName || (interactive ? await pickProjectName() : compose.sanitizeProjectName(path.basename(projectDir)));
+  const mysql = params.mysql || await planMysql(docker, projectName, interactive);
+  const qdrant = params.qdrant === false ? null : (params.qdrant || await planQdrant(docker, interactive));
+
+  const out = compose.generate(projectDir, { projectName, appPort, mysql, qdrant, image: params.image });
+  appendGitignoreLine(projectDir, '.draftgo/docker/');
+  if (!composeUp(docker, out.dir) || !await waitForApp(appPort)) return 1;
+
+  const url = `http://localhost:${appPort}`;
+  log.ok(`DraftGo runtime is ready at ${url}`);
+  log.dim('  Open the site, register or sign in, and obtain your personal API Key.');
+  if (!interactive) {
+    log.dim(`  Connection pending. Run \`draftgo connect --server ${url}\` in a terminal to enter your API Key.`);
+    return 0;
+  }
+  let token = '';
+  while (token.length < 10) {
+    token = String(await askPassword('Paste a DraftGo user API Key')).trim();
+    if (token.length < 10) log.err('  API Key appears too short. Please try again.');
+  }
+  const cfgPath = writeProjectConfig(projectDir, url, token);
+  if (!await finishMcpSetup(projectDir, mcpCommands)) return 1;
+  log.ok(`DraftGo is ready at ${url}`);
+  log.dim(`Project config: ${cfgPath}`);
+  return 0;
+}
+
+module.exports = { finishMcpSetup, runWizard };

package/src/localRuntime/mysqlClient.js

@@ -0,0 +1,155 @@
+'use strict';
+
+// Lightweight MySQL helper used by the local stack wizard to validate
+// credentials and auto-create the project database when missing.
+//
+// We avoid taking a JS MySQL driver as a dependency. Instead we shell out
+// to one of:
+//   - a native `mysql` client on PATH (preferred — fast, no pull)
+//   - a dockerised `mysql:8.0` client (always available because the wizard
+//     already requires Docker; first call may have to pull the image)
+//
+// Passwords are passed via the `MYSQL_PWD` env var so they don't show up
+// in process listings.
+
+const { spawnSync } = require('child_process');
+const log = require('../logger');
+
+function hasNativeMysql() {
+  try {
+    const r = spawnSync('mysql', ['--version'], { encoding: 'utf8', shell: false });
+    return r.status === 0;
+  } catch { return false; }
+}
+
+function hasDocker() {
+  try {
+    const r = spawnSync('docker', ['version', '--format', '{{.Client.Version}}'], { encoding: 'utf8', shell: false });
+    return r.status === 0;
+  } catch { return false; }
+}
+
+function pickClient() {
+  if (hasNativeMysql()) return { kind: 'native' };
+  if (hasDocker()) return { kind: 'docker' };
+  return null;
+}
+
+// Rewrite localhost/127.0.0.1 to host.docker.internal when running inside
+// a container — the host MySQL is on the host network, not the bridge.
+function dockerHost(host) {
+  return (host === 'localhost' || host === '127.0.0.1') ? 'host.docker.internal' : host;
+}
+
+function runSQL(client, conn, sql) {
+  const env = { ...process.env, MYSQL_PWD: conn.password || '' };
+  if (client.kind === 'native') {
+    const args = [
+      '-h', conn.host,
+      '-P', String(conn.port),
+      '-u', conn.user,
+      '--protocol=TCP',
+      '--connect-timeout=5',
+      '-N', '-B',
+      '-e', sql,
+    ];
+    const r = spawnSync('mysql', args, { encoding: 'utf8', env, shell: false });
+    return { ok: r.status === 0, stdout: r.stdout || '', stderr: r.stderr || '', code: r.status };
+  }
+  // docker variant
+  const args = [
+    'run', '--rm', '-i',
+    '--add-host', 'host.docker.internal:host-gateway',
+    '-e', 'MYSQL_PWD',
+    'mysql:8.0',
+    'mysql',
+    '-h', dockerHost(conn.host),
+    '-P', String(conn.port),
+    '-u', conn.user,
+    '--protocol=TCP',
+    '--connect-timeout=5',
+    '-N', '-B',
+    '-e', sql,
+  ];
+  const r = spawnSync('docker', args, { encoding: 'utf8', env, shell: false });
+  return { ok: r.status === 0, stdout: r.stdout || '', stderr: r.stderr || '', code: r.status };
+}
+
+function testConnection(conn) {
+  const client = pickClient();
+  if (!client) return { ok: false, reason: 'no-client' };
+  const probe = runSQL(client, conn, 'SELECT 1');
+  if (probe.ok) return { ok: true };
+  const why = classifyError(probe.stderr);
+  return { ok: false, reason: why === 'auth' ? 'auth' : 'unreachable', detail: probe.stderr.trim() };
+}
+
+function classifyError(stderr) {
+  const s = (stderr || '').toLowerCase();
+  if (s.includes('access denied')) return 'auth';
+  if (s.includes("can't connect") || s.includes('connection refused') || s.includes('unknown server host') || s.includes('timed out')) return 'unreachable';
+  if (s.includes('access denied for user') && s.includes("to database")) return 'no-create-privilege';
+  return 'other';
+}
+
+// Escape a db identifier so it can be embedded in a backticked identifier.
+function escIdent(name) {
+  return String(name).replace(/`/g, '``');
+}
+
+// Public API ----------------------------------------------------------------
+//
+// ensureDatabase(conn, { rootPromptFn }) returns one of:
+//   { ok: true,  created: bool, mode: 'existed' | 'created' | 'created-as-root' }
+//   { ok: false, reason: 'no-client' | 'auth' | 'unreachable' | 'create-failed', detail }
+//
+// `rootPromptFn` (optional) is called when the user's account lacks CREATE
+// privilege; it should resolve to `{ user, password }` (or null to abort).
+async function ensureDatabase(conn, { rootPromptFn } = {}) {
+  const client = pickClient();
+  const connected = testConnection(conn);
+  if (!client || !connected.ok) return connected;
+
+  // 2) Does the database already exist?
+  const showSQL = `SHOW DATABASES LIKE '${String(conn.database).replace(/'/g, "''")}'`;
+  const show = runSQL(client, conn, showSQL);
+  if (show.ok && show.stdout.trim()) {
+    return { ok: true, created: false, mode: 'existed' };
+  }
+
+  // 3) Try to create as the supplied user.
+  const createSQL = `CREATE DATABASE IF NOT EXISTS \`${escIdent(conn.database)}\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`;
+  const create = runSQL(client, conn, createSQL);
+  if (create.ok) return { ok: true, created: true, mode: 'created' };
+
+  // 4) Fall back to root if available (privilege issue).
+  if (typeof rootPromptFn === 'function' && /denied/i.test(create.stderr || '')) {
+    const root = await rootPromptFn();
+    if (root && root.user && root.password !== undefined) {
+      const rootConn = { ...conn, user: root.user, password: root.password };
+      const probeRoot = runSQL(client, rootConn, 'SELECT 1');
+      if (!probeRoot.ok) {
+        return { ok: false, reason: 'auth', detail: probeRoot.stderr.trim() };
+      }
+      const createRoot = runSQL(client, rootConn, createSQL);
+      if (!createRoot.ok) {
+        return { ok: false, reason: 'create-failed', detail: createRoot.stderr.trim() };
+      }
+      // Grant privileges on the new DB to the project user so the app can use it.
+      const grantSQL =
+        `GRANT ALL PRIVILEGES ON \`${escIdent(conn.database)}\`.* TO '${conn.user.replace(/'/g, "''")}'@'%'; FLUSH PRIVILEGES;`;
+      runSQL(client, rootConn, grantSQL); // best-effort
+      return { ok: true, created: true, mode: 'created-as-root' };
+    }
+  }
+
+  return { ok: false, reason: 'create-failed', detail: create.stderr.trim() };
+}
+
+function describeClient() {
+  const c = pickClient();
+  if (!c) return 'none';
+  return c.kind === 'native' ? 'native mysql client' : 'docker mysql:8.0';
+}
+
+module.exports = { ensureDatabase, testConnection, describeClient };