@geraldmaron/construct 1.0.0

package/lib/service-manager.mjs

@@ -0,0 +1,225 @@
+/**
+ * lib/service-manager.mjs — start, stop, and describe Construct runtime services.
+ *
+ * Manages the dashboard process, local Langfuse (Docker), memory server (cm),
+ * and OpenCode. startServices() is the single entry point for `construct up`;
+ * it spawns whatever is available and returns a result per service.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { findAvailablePort } from './host-capabilities.mjs';
+import { getUserEnvPath, loadConstructEnv, writeEnvValues } from './env-config.mjs';
+import { detectDockerCompose } from './setup.mjs';
+
+const DASHBOARD_STATE_FILE = 'dashboard.json';
+
+const LANGFUSE_LOCAL_BASEURL = 'http://localhost:3000';
+const LANGFUSE_LOCAL_PUBLIC_KEY = 'pk-lf-construct-local';
+const LANGFUSE_LOCAL_SECRET_KEY = 'sk-lf-construct-local';
+
+function runtimeStateDir(homeDir = os.homedir()) {
+  return path.join(homeDir, '.construct', 'runtime');
+}
+
+function dashboardStatePath(homeDir = os.homedir()) {
+  return path.join(runtimeStateDir(homeDir), DASHBOARD_STATE_FILE);
+}
+
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function processExists(pid) {
+  if (!pid || Number(pid) <= 0) return false;
+  try {
+    process.kill(Number(pid), 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function spawnDetached(command, args, homeDir, logFile) {
+  const logPath = path.join(runtimeStateDir(homeDir), logFile);
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const fd = fs.openSync(logPath, 'a');
+  const child = spawn(command, args, { detached: true, stdio: ['ignore', fd, fd] });
+  child.unref();
+  return child;
+}
+
+export function readDashboardState(homeDir = os.homedir()) {
+  const state = readJson(dashboardStatePath(homeDir));
+  if (!state) return null;
+  if (!processExists(state.pid)) return null;
+  return state;
+}
+
+export function clearDashboardState(homeDir = os.homedir()) {
+  const filePath = dashboardStatePath(homeDir);
+  if (fs.existsSync(filePath)) fs.rmSync(filePath, { force: true });
+}
+
+export function stopDashboard(homeDir = os.homedir()) {
+  const state = readJson(dashboardStatePath(homeDir));
+  if (!state?.pid) {
+    clearDashboardState(homeDir);
+    return { stopped: false, reason: 'not-running' };
+  }
+
+  if (!processExists(state.pid)) {
+    clearDashboardState(homeDir);
+    return { stopped: false, reason: 'stale-state' };
+  }
+
+  process.kill(Number(state.pid), 'SIGTERM');
+  clearDashboardState(homeDir);
+  return { stopped: true, pid: Number(state.pid), port: state.port };
+}
+
+export async function startDashboard({ rootDir, homeDir = os.homedir(), preferredPort = 4242 } = {}) {
+  const existing = readDashboardState(homeDir);
+  if (existing) return { started: false, reused: true, pid: existing.pid, port: existing.port, url: existing.url };
+
+  const port = await findAvailablePort(preferredPort);
+  const outPath = path.join(runtimeStateDir(homeDir), 'dashboard.log');
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  const out = fs.openSync(outPath, 'a');
+  const err = fs.openSync(outPath, 'a');
+  const child = spawn(process.execPath, [path.join(rootDir, 'lib', 'server', 'index.mjs')], {
+    detached: true,
+    stdio: ['ignore', out, err],
+    env: { ...process.env, PORT: String(port) },
+  });
+  child.unref();
+
+  const state = {
+    pid: child.pid,
+    port,
+    url: `http://127.0.0.1:${port}`,
+    startedAt: new Date().toISOString(),
+    logPath: outPath,
+  };
+  writeJson(dashboardStatePath(homeDir), state);
+  return { started: true, reused: false, ...state };
+}
+
+export async function getRuntimePorts(homeDir = os.homedir()) {
+  const dashboard = readDashboardState(homeDir);
+  return {
+    dashboard: dashboard?.port ?? await findAvailablePort(4242),
+    memory: await findAvailablePort(8765),
+    bridge: await findAvailablePort(5173),
+  };
+}
+
+export async function describeRuntimeSupport() {
+  function commandExists(command) {
+    try {
+      const checker = process.platform === 'win32' ? 'where' : 'which';
+      return spawnSync(checker, [command], { stdio: 'ignore' }).status === 0;
+    } catch {
+      return false;
+    }
+  }
+  return {
+    tmux: commandExists('tmux'),
+    docker: commandExists('docker'),
+    cm: commandExists('cm'),
+    opencode: commandExists('opencode'),
+  };
+}
+
+export async function startServices({ rootDir, homeDir = os.homedir() } = {}) {
+  const support = await describeRuntimeSupport();
+  const ports = await getRuntimePorts(homeDir);
+  const envPath = getUserEnvPath(homeDir);
+
+  writeEnvValues(envPath, {
+    DASHBOARD_PORT: String(ports.dashboard),
+    MEMORY_PORT: String(ports.memory),
+    BRIDGE_PORT: String(ports.bridge),
+  });
+
+  const results = [];
+
+  // Dashboard
+  const dashboard = await startDashboard({ rootDir, homeDir, preferredPort: ports.dashboard });
+  results.push({
+    name: 'Dashboard',
+    url: dashboard.url,
+    status: dashboard.reused ? 'reused' : 'started',
+  });
+
+  // Langfuse — start local Docker unless a remote URL is explicitly configured
+  const liveEnv = loadConstructEnv({ rootDir, homeDir });
+  const langfuseUrl = liveEnv.LANGFUSE_BASEURL ?? '';
+  const isRemoteLangfuse = langfuseUrl && !langfuseUrl.includes('localhost') && !langfuseUrl.includes('127.0.0.1');
+
+  if (isRemoteLangfuse) {
+    results.push({ name: 'Langfuse', url: langfuseUrl, status: 'configured' });
+  } else {
+    const composeRunner = detectDockerCompose();
+    if (composeRunner) {
+      const composeFile = path.join(rootDir, 'langfuse', 'docker-compose.yml');
+      const r = spawnSync(
+        composeRunner.command,
+        [...composeRunner.argsPrefix, '-p', 'construct-langfuse', '-f', composeFile, 'up', '-d'],
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+      );
+      if (r.status === 0) {
+        writeEnvValues(envPath, {
+          LANGFUSE_BASEURL: LANGFUSE_LOCAL_BASEURL,
+          LANGFUSE_PUBLIC_KEY: LANGFUSE_LOCAL_PUBLIC_KEY,
+          LANGFUSE_SECRET_KEY: LANGFUSE_LOCAL_SECRET_KEY,
+        });
+        results.push({ name: 'Langfuse', url: LANGFUSE_LOCAL_BASEURL, status: 'started', note: 'containers starting — allow 30-60s' });
+      } else {
+        const msg = (r.stderr || r.stdout || 'docker compose failed').trim().split('\n')[0];
+        results.push({ name: 'Langfuse', status: 'failed', note: msg });
+      }
+    } else {
+      results.push({ name: 'Langfuse', status: 'unavailable', note: 'Docker not available' });
+    }
+  }
+
+  // Memory (cm)
+  if (support.cm) {
+    spawnDetached('cm', ['serve', '--port', String(ports.memory)], homeDir, 'cm.log');
+    results.push({ name: 'Memory (cm)', url: `http://127.0.0.1:${ports.memory}`, status: 'started' });
+  } else {
+    results.push({ name: 'Memory (cm)', status: 'unavailable', note: 'cm not installed — run: npm install -g @cass-ai/memory' });
+  }
+
+  // OpenCode (optional)
+  if (support.opencode) {
+    spawnDetached('opencode', ['serve', '--port', String(ports.bridge)], homeDir, 'opencode.log');
+    results.push({ name: 'OpenCode', url: `http://127.0.0.1:${ports.bridge}`, status: 'started' });
+  }
+
+  return { support, ports, results };
+}
+
+export async function stopServices({ homeDir = os.homedir() } = {}) {
+  const dashboard = stopDashboard(homeDir);
+  return {
+    stopped: dashboard.stopped ? ['dashboard'] : [],
+    guidance: dashboard.stopped
+      ? []
+      : ['Stop Construct-related services with their native commands or your process manager.'],
+    dashboard,
+  };
+}

package/lib/setup.mjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+/**
+ * lib/setup.mjs — <one-line purpose>
+ *
+ * <2–6 line summary.>
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { ensureUserConfigDir, getUserEnvPath, writeEnvValues } from './env-config.mjs';
+import { getCanonicalOpenCodeConfigPath, readOpenCodeConfig, writeOpenCodeConfig } from './opencode-config.mjs';
+import { syncFileStateToSql } from './storage/sync.mjs';
+import { createSqlClient, closeSqlClient } from './storage/backend.mjs';
+import { EMBEDDING_MODEL } from './storage/embeddings.mjs';
+
+const ROOT_DIR = path.resolve(import.meta.dirname, '..');
+const HOME = os.homedir();
+const LOCAL_POSTGRES_PORT = '54329';
+const LOCAL_POSTGRES_USER = 'construct';
+const LOCAL_POSTGRES_PASSWORD = 'construct';
+const LOCAL_POSTGRES_DB = 'construct';
+const LOCAL_DATABASE_URL = `postgresql://${LOCAL_POSTGRES_USER}:${LOCAL_POSTGRES_PASSWORD}@127.0.0.1:${LOCAL_POSTGRES_PORT}/${LOCAL_POSTGRES_DB}`;
+
+function printHelp() {
+  console.log(`Construct setup
+
+Usage:
+  construct setup [--yes] [--no-docker]
+
+What it does:
+  - creates ~/.construct/config.env
+  - ensures OpenCode config exists
+  - configures managed defaults for local vector retrieval
+  - starts local Postgres with Docker when available
+  - wires Memory, GitHub, and Langfuse configuration
+  - runs construct sync
+  - runs construct doctor
+
+Use --yes to run without prompts and accept detected environment defaults.`);
+}
+
+function runConstruct(argsList, { optional = false } = {}) {
+  const result = spawnSync(process.execPath, [path.join(ROOT_DIR, 'bin', 'construct'), ...argsList], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  if (result.status !== 0 && optional) {
+    console.log(`\nOptional setup step skipped: construct ${argsList.join(' ')}`);
+    return;
+  }
+  if (result.status !== 0) process.exit(result.status ?? 1);
+}
+
+function findCommand(command) {
+  const result = spawnSync('zsh', ['-lc', `command -v ${command}`], {
+    encoding: 'utf8',
+    env: process.env,
+  });
+  return result.status === 0 ? result.stdout.trim() : '';
+}
+
+export function defaultVectorIndexPath(homeDir = HOME) {
+  return path.join(homeDir, '.construct', 'vector', 'index.json');
+}
+
+export function buildManagedSetupValues({ homeDir = HOME, env = process.env, databaseUrl = '' } = {}) {
+  const values = {
+    CONSTRUCT_TRACE_BACKEND: env.CONSTRUCT_TRACE_BACKEND || 'langfuse',
+    LANGFUSE_BASEURL: env.LANGFUSE_BASEURL || 'https://cloud.langfuse.com',
+    CONSTRUCT_VECTOR_INDEX_PATH: env.CONSTRUCT_VECTOR_INDEX_PATH || defaultVectorIndexPath(homeDir),
+    CONSTRUCT_VECTOR_MODEL: env.CONSTRUCT_VECTOR_MODEL || EMBEDDING_MODEL,
+  };
+
+  const resolvedDatabaseUrl = databaseUrl || env.DATABASE_URL || '';
+  if (resolvedDatabaseUrl) values.DATABASE_URL = resolvedDatabaseUrl;
+  if (env.CONSTRUCT_VECTOR_URL) values.CONSTRUCT_VECTOR_URL = env.CONSTRUCT_VECTOR_URL;
+  if (env.LANGFUSE_PUBLIC_KEY) values.LANGFUSE_PUBLIC_KEY = env.LANGFUSE_PUBLIC_KEY;
+  if (env.LANGFUSE_SECRET_KEY) values.LANGFUSE_SECRET_KEY = env.LANGFUSE_SECRET_KEY;
+  if (env.LANGFUSE_PROJECT_ID) values.LANGFUSE_PROJECT_ID = env.LANGFUSE_PROJECT_ID;
+  return values;
+}
+
+export function localPostgresComposePath(homeDir = HOME) {
+  return path.join(homeDir, '.construct', 'services', 'postgres', 'docker-compose.yml');
+}
+
+export function writeLocalPostgresCompose(homeDir = HOME) {
+  const composePath = localPostgresComposePath(homeDir);
+  fs.mkdirSync(path.dirname(composePath), { recursive: true });
+  const content = `services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: construct-postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${LOCAL_POSTGRES_USER}
+      POSTGRES_PASSWORD: ${LOCAL_POSTGRES_PASSWORD}
+      POSTGRES_DB: ${LOCAL_POSTGRES_DB}
+    ports:
+      - "127.0.0.1:${LOCAL_POSTGRES_PORT}:5432"
+    volumes:
+      - construct-postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${LOCAL_POSTGRES_USER} -d ${LOCAL_POSTGRES_DB}"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+volumes:
+  construct-postgres-data:
+`;
+  fs.writeFileSync(composePath, content, 'utf8');
+  return composePath;
+}
+
+function runQuiet(command, args, { env = process.env, spawn = spawnSync } = {}) {
+  return spawn(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env,
+  });
+}
+
+export function detectDockerCompose({ env = process.env, spawn = spawnSync } = {}) {
+  const docker = runQuiet('docker', ['info'], { env, spawn });
+  if (docker.status !== 0) return null;
+  const compose = runQuiet('docker', ['compose', 'version'], { env, spawn });
+  if (compose.status === 0) return { command: 'docker', argsPrefix: ['compose'] };
+  const dockerCompose = runQuiet('docker-compose', ['version'], { env, spawn });
+  if (dockerCompose.status === 0) return { command: 'docker-compose', argsPrefix: [] };
+  return null;
+}
+
+export function startManagedPostgres({ homeDir = HOME, env = process.env, spawn = spawnSync } = {}) {
+  const composeRunner = detectDockerCompose({ env, spawn });
+  if (!composeRunner) {
+    return {
+      status: 'skipped',
+      databaseUrl: env.DATABASE_URL || '',
+      message: 'Docker is not available; using existing DATABASE_URL if configured.',
+    };
+  }
+
+  const composePath = writeLocalPostgresCompose(homeDir);
+  const result = runQuiet(
+    composeRunner.command,
+    [...composeRunner.argsPrefix, '-f', composePath, 'up', '-d', 'postgres'],
+    { env, spawn },
+  );
+
+  if (result.status !== 0) {
+    return {
+      status: 'degraded',
+      databaseUrl: env.DATABASE_URL || '',
+      composePath,
+      message: (result.stderr || result.stdout || 'Docker compose failed').trim(),
+    };
+  }
+
+  return {
+    status: 'ok',
+    databaseUrl: LOCAL_DATABASE_URL,
+    composePath,
+    message: 'Managed local Postgres is running.',
+  };
+}
+
+async function waitForSqlReady(env, { attempts = 20, delayMs = 500 } = {}) {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const client = createSqlClient(env);
+    try {
+      await client`select 1 as ok`;
+      await closeSqlClient(client);
+      return true;
+    } catch {
+      await closeSqlClient(client).catch(() => {});
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+  return false;
+}
+
+function warnIfGlobalCommandIsUnavailable() {
+  const globalConstruct = findCommand('construct');
+  if (!globalConstruct) {
+    console.log('\nInstall warning: `construct` is not on PATH yet.');
+    console.log('  From this checkout, run: npm install -g .');
+    console.log('  Without cloning, run: npm install -g github:geraldmaron/construct');
+    console.log('  Do not use `npm install -g construct`; that npm name belongs to another project.');
+    return;
+  }
+
+  const version = spawnSync(globalConstruct, ['version'], {
+    encoding: 'utf8',
+    env: process.env,
+  });
+  if (version.status !== 0 || !/^construct v\d+\./.test(version.stdout.trim())) {
+    console.log(`\nInstall warning: PATH resolves \`construct\` to ${globalConstruct}, but it does not look like this CLI.`);
+    console.log('  Reinstall from this checkout with: npm install -g .');
+    console.log('  Or install from GitHub with: npm install -g github:geraldmaron/construct');
+  }
+}
+
+function ensureOpenCodeConfig() {
+  const current = readOpenCodeConfig();
+  if (current.config) return current.file;
+  writeOpenCodeConfig({
+    $schema: 'https://opencode.ai/config.json',
+    mcp: {},
+    agent: {},
+  }, getCanonicalOpenCodeConfigPath());
+  return getCanonicalOpenCodeConfigPath();
+}
+
+export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME } = {}) {
+  const argSet = new Set(args);
+  const isYes = argSet.has('--yes');
+  const skipDocker = argSet.has('--no-docker');
+
+  if (argSet.has('--help') || argSet.has('-h')) {
+    printHelp();
+    return;
+  }
+
+  console.log('Construct setup');
+  console.log('────────────────');
+
+  const envPath = ensureUserConfig(homeDir);
+  const opencodePath = ensureOpenCodeConfig();
+
+  console.log(`User config: ${envPath}`);
+  console.log(`OpenCode config: ${opencodePath}`);
+  warnIfGlobalCommandIsUnavailable();
+
+  const serviceResult = isYes && !skipDocker && !process.env.DATABASE_URL
+    ? startManagedPostgres({ homeDir, env: process.env })
+    : { status: 'skipped', databaseUrl: process.env.DATABASE_URL || '', message: skipDocker ? 'Docker service setup skipped by flag.' : 'Using existing DATABASE_URL if configured.' };
+
+  fs.mkdirSync(path.dirname(defaultVectorIndexPath(homeDir)), { recursive: true });
+  const managedValues = buildManagedSetupValues({
+    homeDir,
+    env: process.env,
+    databaseUrl: serviceResult.databaseUrl,
+  });
+  writeEnvValues(envPath, managedValues);
+
+  if (isYes) {
+    console.log('\nManaged setup:');
+    console.log(`  Vector index: ${managedValues.CONSTRUCT_VECTOR_INDEX_PATH}`);
+    console.log(`  Vector model: ${managedValues.CONSTRUCT_VECTOR_MODEL}`);
+    console.log(`  Trace backend: ${managedValues.CONSTRUCT_TRACE_BACKEND}`);
+    console.log(`  Langfuse URL: ${managedValues.LANGFUSE_BASEURL}`);
+    if (serviceResult.status === 'ok') {
+      console.log(`  Postgres: ${serviceResult.databaseUrl}`);
+      console.log(`  Compose file: ${serviceResult.composePath}`);
+    } else {
+      console.log(`  Postgres: ${serviceResult.message}`);
+    }
+
+    const sqlClient = createSqlClient({ ...process.env, ...managedValues });
+    if (sqlClient) {
+      let readyClient = null;
+      let sqlClientClosed = false;
+      try {
+        if (serviceResult.status === 'ok') {
+          await closeSqlClient(sqlClient);
+          sqlClientClosed = true;
+          await waitForSqlReady({ ...process.env, ...managedValues });
+        }
+        readyClient = createSqlClient({ ...process.env, ...managedValues });
+        const migration = await import('node:fs/promises').then((fs) => fs.readFile(new URL('../db/migrations/001_init.sql', import.meta.url), 'utf8'));
+        await readyClient.unsafe(migration);
+        console.log('\nPostgres schema initialized.');
+        const syncResult = await syncFileStateToSql(rootDir, { env: { ...process.env, ...managedValues }, project: 'construct' });
+        console.log(`Hybrid storage sync: ${syncResult.status}`);
+        if (syncResult.embeddingModel) console.log(`Embedding model: ${syncResult.embeddingModel}`);
+      } catch (error) {
+        console.log(`Hybrid storage init failed: ${error?.message || 'unknown error'}`);
+      } finally {
+        await closeSqlClient(readyClient).catch(() => {});
+        if (!sqlClientClosed) await closeSqlClient(sqlClient);
+      }
+    }
+  }
+
+  if (isYes) {
+    runConstruct(['mcp', 'add', 'memory', '--auto'], { optional: true });
+    runConstruct(['mcp', 'add', 'github', '--auto'], { optional: true });
+    if (!managedValues.LANGFUSE_PUBLIC_KEY || !managedValues.LANGFUSE_SECRET_KEY) {
+      console.log('\nLangfuse is prewired but needs account credentials:');
+      console.log('  Set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY in ~/.construct/config.env');
+      console.log('  Set these in ~/.construct/config.env or run: cd langfuse && docker compose up -d');
+    }
+
+  } else {
+    console.log('\nManaged defaults written:');
+    console.log(`  Vector index: ${managedValues.CONSTRUCT_VECTOR_INDEX_PATH}`);
+    console.log(`  Trace backend: ${managedValues.CONSTRUCT_TRACE_BACKEND} (${managedValues.LANGFUSE_BASEURL})`);
+    console.log('\nFor unattended setup, including local Postgres when Docker is running:');
+    console.log('  construct setup --yes');
+  }
+
+  runConstruct(['sync']);
+  runConstruct(['doctor']);
+}
+
+function ensureUserConfig(homeDir = HOME) {
+  ensureUserConfigDir(homeDir);
+  const envPath = getUserEnvPath(homeDir);
+  if (!fs.existsSync(envPath)) writeEnvValues(envPath, {});
+  return envPath;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runSetup({ args: process.argv.slice(2) });
+}