@geraldmaron/construct 1.0.20 → 1.0.23

package/lib/runtime/uv-bootstrap.mjs

@@ -37,12 +37,32 @@ function which(bin) {
   return result.stdout.trim().split('\n')[0] || null;
 }
 
+// First-run docling provisioning blocks for minutes (uv install, venv, then a
+// large `uv pip install docling` that pulls ML deps). Without a heartbeat it
+// reads as a hang. Progress goes to stderr only, so JSON consumers on stdout are
+// unaffected; it is the long-operation's own channel, not a suppressible notice.
+
+function progress(message) {
+  try { process.stderr.write(`[docling setup] ${message}\n`); } catch { /* stderr closed */ }
+}
+
+// spawnSync sets status=null and error.code=ETIMEDOUT on timeout; distinguish a
+// timeout from a real non-zero exit so the message tells the user what to do.
+
+function describeStepFailure(label, result, timeoutMs) {
+  if (result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') {
+    return `${label} timed out after ${Math.round(timeoutMs / 1000)}s — docling's one-time download did not complete. Check network/proxy and re-run; or set ingest.fallback to "adapter" to skip docling.`;
+  }
+  return `${label} failed (${result.status}): ${result.stderr || result.stdout || result.error?.message || 'unknown error'}`;
+}
+
 function ensureUv(installDir) {
   const fromPath = which('uv');
   if (fromPath) return fromPath;
   const cachedUv = path.join(installDir, 'bin', 'uv');
   if (existsSync(cachedUv)) return cachedUv;
   mkdirSync(installDir, { recursive: true });
+  progress('Installing uv (Python toolchain) — first run only…');
   const env = { ...process.env, UV_INSTALL_DIR: path.join(installDir, 'bin'), UV_NO_MODIFY_PATH: '1' };
   const sh = spawnSync('sh', ['-c', `curl -LsSf ${UV_INSTALL_URL} | sh`], {
     env,
@@ -50,7 +70,7 @@ function ensureUv(installDir) {
     encoding: 'utf8',
   });
   if (sh.status !== 0) {
-    throw new Error(`uv install failed (${sh.status}): ${sh.stderr || sh.stdout}`);
+    throw new Error(describeStepFailure('uv install', sh, UV_TIMEOUT_MS));
   }
   if (!existsSync(cachedUv)) {
     throw new Error(`uv install reported success but binary not found at ${cachedUv}`);
@@ -86,23 +106,27 @@ export function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), force = fa
     return { pythonBin: existingPython, venvDir, runtimeDir, fresh: false };
   }
 
+  progress('Provisioning the docling document extractor (first run). This downloads a Python runtime and ML dependencies and can take several minutes; later runs are instant.');
   const uv = ensureUv(runtimeDir);
 
+  progress('Creating Python 3.11 virtualenv…');
   const venvResult = spawnSync(uv, ['venv', venvDir, '--python', '3.11'], {
     timeout: VENV_TIMEOUT_MS,
     encoding: 'utf8',
   });
   if (venvResult.status !== 0) {
-    throw new Error(`uv venv failed (${venvResult.status}): ${venvResult.stderr}`);
+    throw new Error(describeStepFailure('uv venv', venvResult, VENV_TIMEOUT_MS));
   }
 
+  progress(`Installing docling ${DOCLING_PIN} and its dependencies — the slow step (large download)…`);
   const installResult = spawnSync(uv, ['pip', 'install', '--python', pythonBinFor(venvDir), `docling==${DOCLING_PIN}`], {
     timeout: INSTALL_TIMEOUT_MS,
     encoding: 'utf8',
   });
   if (installResult.status !== 0) {
-    throw new Error(`docling install failed (${installResult.status}): ${installResult.stderr}`);
+    throw new Error(describeStepFailure('docling install', installResult, INSTALL_TIMEOUT_MS));
   }
+  progress('docling extractor ready.');
 
   const pythonBin = pythonBinFor(venvDir);
   writeMarker(markerPath, {

package/lib/schema-infer.mjs

@@ -210,9 +210,23 @@ async function callModel(userContent, { traceId } = {}) {
   }
 
   // If only Anthropic key available, use configured fast tier directly.
+  // Construct ships with no implicit model defaults (ADR-0027,
+  // tests/model-router-no-defaults.test.mjs), so an unconfigured fast tier
+  // resolves to null. Surface a clear configuration error instead of letting
+  // null leak into the candidate loop where /^anthropic\//.test(null) throws.
+
   if (candidates.length === 0 && anthropicKey) {
     const envPath = getUserEnvPath();
-    candidates = [readCurrentModels(envPath, {}).fast];
+    const fast = readCurrentModels(envPath, {}).fast;
+    if (!fast) {
+      throw new Error(
+        "Schema inference requires a fast-tier model. " +
+        "Either set OPENROUTER_API_KEY (to use free model fallbacks) or " +
+        "configure a fast tier with 'construct models --apply' or " +
+        "'export CX_MODEL_FAST=<model-id>'."
+      );
+    }
+    candidates = [fast];
   }
 
   let lastError;
@@ -261,7 +275,7 @@ async function callModel(userContent, { traceId } = {}) {
           headers: {
             Authorization: `Bearer ${orKey}`,
             'content-type': 'application/json',
-            'HTTP-Referer': 'https://github.com/construct',
+            'HTTP-Referer': 'https://github.com/geraldmaron/construct',
           },
           body: JSON.stringify({
             model: openRouterModelId,

package/lib/server/csrf.mjs

@@ -66,6 +66,11 @@ export function ensureCsrfCookie(req, res) {
  */
 export function verifyCsrf(req, { skip } = {}) {
   if (SAFE_METHODS.has(req.method)) return true;
+  // A request authenticated by an Authorization header (bearer token) is not
+  // cookie-driven, so it cannot be forged cross-origin — CSRF defends ambient
+  // cookie auth, not header tokens. This is what lets programmatic API clients
+  // (editor adapters, CLI, CI) POST without the browser CSRF dance.
+  if (req.headers && req.headers.authorization) return true;
   if (typeof skip === 'function' && skip(req.url || '')) return true;
   const headerVal = req.headers[HEADER_NAME];
   const cookieVal = parseCookies(req)[COOKIE_NAME];
@@ -78,13 +83,20 @@ export function verifyCsrf(req, { skip } = {}) {
 }
 
 /**
- * Default skip predicate — webhooks and auth/login may legitimately accept
- * cross-origin POSTs without the CSRF dance.
+ * Default skip predicate — webhooks, auth/login, and the orchestration API
+ * legitimately accept POSTs without the CSRF dance. CSRF defends a browser
+ * cookie session; the `/api/orchestration/*` endpoints are consumed only by
+ * programmatic clients (the `--remote` CLI, the MCP tool, editor adapters) that
+ * carry a bearer token (or nothing in no-token mode), never the dashboard
+ * cookie — so CSRF is the wrong control there, and the auth gate still protects
+ * them in token mode. Without this, a no-token daemon rejects every orchestration
+ * run with a 403.
  */
 export function defaultSkip(url) {
   if (!url) return false;
   return (
     url.startsWith('/api/webhooks/') ||
+    url.startsWith('/api/orchestration/') ||
     url === '/api/auth/login' ||
     url === '/api/slack/commands'
   );

package/lib/server/index.mjs

@@ -32,6 +32,14 @@ import { onEmbedNotification } from '../embed/notifications.mjs';
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const ROOT_DIR = join(__dirname, '..', '..');
 const HOME = homedir();
+
+// The daemon is a long-lived, detached service not bound to one project, so its
+// orchestration runs persist under the user data root (HOME → ~/.cx/runtime/
+// orchestration via the run store's relative path) rather than the install
+// directory. A global install dir can be shared or read-only and would mix
+// every project's runs together; HOME is always writable and survives reinstalls.
+
+const ORCHESTRATION_RUN_ROOT = HOME;
 const PORT = parseInt(process.env.PORT ?? '4242', 10);
 
 // Default bind is loopback regardless of NODE_ENV. Exposing the dashboard to
@@ -464,6 +472,88 @@ async function handleApprovals(req, res) {
   res.end('Method Not Allowed');
 }
 
+// Orchestration daemon surface: start a run (background execution), inspect runs,
+// and stream a single run's lifecycle over SSE. Construct's runtime owns the
+// orchestration; this lets any thin client (editor, TUI, CI) reach the outcome.
+// Responses are wrapped in the versioned, secret-free embedded-contract envelope.
+
+async function handleOrchestration(req, res) {
+  const url = new URL(req.url, `http://${BIND_HOST}:${PORT}`);
+  const { startRun, getRun, getRuns } = await import('../orchestration/runtime.mjs');
+  const { onRunEvent, requestCancel } = await import('../orchestration/events.mjs');
+  const { wrapResponse } = await import('../embedded-contract/envelope.mjs');
+
+  const send = (code, data) => {
+    res.writeHead(code, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(wrapResponse({ data, surface: 'sdk' })));
+  };
+  const fail = (code, message) => {
+    res.writeHead(code, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: message }));
+  };
+
+  if (url.pathname === '/api/orchestration/runs' && req.method === 'POST') {
+    let body = '';
+    req.on('data', (c) => { body += c; });
+    req.on('end', async () => {
+      try {
+        const d = JSON.parse(body || '{}');
+        if (!d.request || typeof d.request !== 'string') throw new Error('Missing "request" string');
+        const run = await startRun(
+          { request: d.request, workflowType: d.workflowType, requestedStrategy: d.requestedStrategy, host: d.host, hostModel: d.hostModel, hostProvider: d.hostProvider, fileCount: d.fileCount, moduleCount: d.moduleCount },
+          { cwd: ORCHESTRATION_RUN_ROOT, workerBackend: d.workerBackend || null },
+        );
+        send(202, run);
+      } catch (err) {
+        fail(400, err.message);
+      }
+    });
+    return;
+  }
+
+  if (url.pathname === '/api/orchestration/runs' && req.method === 'GET') {
+    const limit = Number(url.searchParams.get('limit') || 20);
+    send(200, { runs: await getRuns(ORCHESTRATION_RUN_ROOT, { limit }) });
+    return;
+  }
+
+  const match = url.pathname.match(/^\/api\/orchestration\/runs\/([^/]+)(\/events|\/cancel)?$/);
+  if (match) {
+    const runId = decodeURIComponent(match[1]);
+    const sub = match[2];
+
+    if (!sub && req.method === 'GET') {
+      const run = await getRun(ORCHESTRATION_RUN_ROOT, runId);
+      if (!run) { fail(404, `Run not found: ${runId}`); return; }
+      send(200, run);
+      return;
+    }
+
+    if (sub === '/cancel' && req.method === 'POST') {
+      requestCancel(runId);
+      send(202, { runId, cancelRequested: true });
+      return;
+    }
+
+    if (sub === '/events' && req.method === 'GET') {
+      const run = await getRun(ORCHESTRATION_RUN_ROOT, runId);
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive', 'Access-Control-Allow-Origin': '*' });
+      res.write(': connected\n\n');
+      if (run) {
+        const snapshot = { type: 'snapshot', runId, status: run.status, chainOfThought: run.chainOfThought ?? null, tasks: (run.tasks || []).map((t) => ({ id: t.id, role: t.role, status: t.status, executor: t.executor, reasoning: t.reasoning ?? null })) };
+        res.write(`data: ${JSON.stringify(snapshot)}\n\n`);
+      }
+      const off = onRunEvent(runId, (event) => {
+        try { res.write(`data: ${JSON.stringify(event)}\n\n`); } catch { off(); }
+      });
+      req.on('close', off);
+      return;
+    }
+  }
+
+  fail(404, 'Not found');
+}
+
 // ── Config handler ────────────────────────────────────────────────────────
 
 function handleConfig(req, res) {
@@ -701,6 +791,11 @@ const server = createServer(async (req, res) => {
     return;
   }
 
+  if (url.pathname.startsWith('/api/orchestration/')) {
+    await handleOrchestration(req, res);
+    return;
+  }
+
   if (url.pathname === '/api/registry' && req.method === 'GET') {
     try {
       const registry = JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));

package/lib/service-manager.mjs

@@ -10,6 +10,7 @@ import fs from 'node:fs';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { findAvailablePort } from './host-capabilities.mjs';
 import { getUserEnvPath, loadConstructEnv, parseEnvFile, writeEnvValues } from './env-config.mjs';
@@ -22,15 +23,24 @@ import {
   isRemoteTelemetry,
 } from './services/local-postgres.mjs';
 import { resolveTraceBackend, telemetryProviderLabel } from './telemetry/client.mjs';
+import { postgresPort, postgresContainerName, memoryPort as derivedMemoryPort } from './home-namespace.mjs';
 
 const CONSTRUCT_PG_COMPOSE_DIR = 'services/postgres';
-const CONSTRUCT_PG_CONTAINER = 'construct-postgres';
-const CONSTRUCT_PG_PORT = 54329;
+const CONSTRUCT_PG_CONTAINER = postgresContainerName();
+const CONSTRUCT_PG_PORT = postgresPort();
 const CONSTRUCT_PG_HEALTH_RETRIES = 12;
 const CONSTRUCT_PG_HEALTH_INTERVAL_MS = 2000;
 
 const DASHBOARD_STATE_FILE = 'dashboard.json';
 
+// The caller's `rootDir` is the project (for compose/context/traces), but the
+// dashboard and doctor entrypoints ship with the install, not the project. They
+// must resolve against the install root — derived from this module's own
+// location — or `construct init` spawns `<project>/lib/server/index.mjs` and the
+// process dies with MODULE_NOT_FOUND while still advertising the URL.
+
+const INSTALL_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+
 // pruneStashDir and verifyTelemetryKeys now live in lib/services/telemetry-backend.mjs.
 // Re-exported below at module bottom for tests that already import from here.
 
@@ -260,7 +270,7 @@ export function startDoctor({ rootDir, homeDir = os.homedir() } = {}) {
   }
   const existing = readDoctorState(homeDir);
   if (existing) return { started: false, reused: true, pid: existing.pid };
-  const indexPath = path.join(rootDir, 'lib', 'doctor', 'index.mjs');
+  const indexPath = path.join(INSTALL_ROOT, 'lib', 'doctor', 'index.mjs');
   if (!fs.existsSync(indexPath)) return { started: false, reason: 'missing-binary' };
   const { logPath } = spawnDetached('node', [indexPath], homeDir, 'doctor.log', { cwd: rootDir, env: { ...process.env } });
   return { started: true, logPath };
@@ -279,13 +289,30 @@ export async function startDashboard({ rootDir, homeDir = os.homedir(), preferre
   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')], {
+  const child = spawn(process.execPath, [path.join(INSTALL_ROOT, 'lib', 'server', 'index.mjs')], {
     detached: true,
     stdio: ['ignore', out, err],
     env: { ...process.env, PORT: String(port) },
   });
   child.unref();
 
+  // Confirm the process actually bound the port before persisting state or
+  // advertising the URL. Without this the caller reports a dead PID/URL when the
+  // server crashes on boot — the readiness gate turns a silent failure into an
+  // honest, actionable one (the log tail names the cause).
+
+  let ready = false;
+  for (let i = 0; i < 30; i += 1) {
+    if (await probeRuntimePort(port)) { ready = true; break; }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+
+  if (!ready) {
+    let logTail = '';
+    try { logTail = fs.readFileSync(outPath, 'utf8').split('\n').slice(-12).join('\n'); } catch { /* log unreadable */ }
+    return { started: false, failed: true, port, logPath: outPath, error: `dashboard did not bind 127.0.0.1:${port} within 6s`, logTail };
+  }
+
   const state = {
     pid: child.pid,
     port,
@@ -320,7 +347,7 @@ export async function getRuntimePorts(homeDir = os.homedir(), {
 
   return {
     dashboard: dashboard?.port ?? await resolvePort('DASHBOARD_PORT', 4242, dashboardProbeFn),
-    memory: await resolvePort('MEMORY_PORT', 8765, memoryProbeFn),
+    memory: await resolvePort('MEMORY_PORT', derivedMemoryPort(), memoryProbeFn),
     bridge: await resolvePort('BRIDGE_PORT', 5173, openCodeProbeFn),
   };
 }
@@ -375,13 +402,13 @@ async function waitForConstructPostgresHealthy({
 }
 
 function startConstructPostgres({ rootDir, homeDir = os.homedir(), spawnSyncFn = spawnSync, detectDockerComposeFn = detectDockerCompose } = {}) {
-  const composeRunner = detectDockerComposeFn();
+  const composeRunner = detectDockerComposeFn({ autoStart: true });
   if (!composeRunner) return { status: 'unavailable', note: 'Docker not available' };
 
   const composeFile = constructPgComposePath(rootDir);
   if (!fs.existsSync(composeFile)) return { status: 'unavailable', note: 'Postgres compose file not found — run construct init first' };
 
-  const args = [...composeRunner.argsPrefix, '-p', 'construct-postgres', '-f', composeFile, 'up', '-d'];
+  const args = [...composeRunner.argsPrefix, '-p', CONSTRUCT_PG_CONTAINER, '-f', composeFile, 'up', '-d'];
   const r = spawnSyncFn(composeRunner.command, args, { stdio: 'pipe', encoding: 'utf8' });
   if (r.status === 0) return { status: 'started' };
   return { status: 'error', note: (r.stderr || '').trim().split('\n')[0] || 'compose up failed' };
@@ -394,7 +421,7 @@ function stopConstructPostgres({ rootDir, homeDir = os.homedir(), spawnSyncFn =
   const composeFile = constructPgComposePath(rootDir);
   if (!fs.existsSync(composeFile)) return { status: 'skipped', note: 'no compose file' };
 
-  const args = [...composeRunner.argsPrefix, '-p', 'construct-postgres', '-f', composeFile, 'down'];
+  const args = [...composeRunner.argsPrefix, '-p', CONSTRUCT_PG_CONTAINER, '-f', composeFile, 'down'];
   const r = spawnSyncFn(composeRunner.command, args, { stdio: 'pipe', encoding: 'utf8' });
   if (r.status === 0) return { status: 'stopped' };
   return { status: 'error', note: (r.stderr || '').trim().split('\n')[0] || 'compose down failed' };
@@ -540,11 +567,9 @@ export async function startServices({
   // Dashboard
   if (wants('dashboard')) {
     const dashboard = await startDashboardFn({ rootDir, homeDir, preferredPort: ports.dashboard });
-    results.push({
-      name: 'Dashboard',
-      url: dashboard.url,
-      status: dashboard.reused ? 'reused' : 'started',
-    });
+    results.push(dashboard.failed
+      ? { name: 'Dashboard', status: 'failed', note: `${dashboard.error} — see ${dashboard.logPath}` }
+      : { name: 'Dashboard', url: dashboard.url, status: dashboard.reused ? 'reused' : 'started' });
   }
 
   const telemetryUrl = liveEnv.CONSTRUCT_TELEMETRY_URL ?? '';
@@ -705,7 +730,7 @@ export async function stopServices({
   // Memory (cm) — find port from config.env or fall back to default
   const envPath = getUserEnvPath(homeDir);
   const envValues = parseEnvFile(envPath);
-  const memoryPort = Number(envValues.MEMORY_PORT) || 8765;
+  const memoryPort = Number(envValues.MEMORY_PORT) || derivedMemoryPort();
   const cmKilled = killPortOwners(memoryPort, spawnSyncFn);
   results.push({ name: 'Memory (cm)', status: cmKilled ? 'stopped' : 'not-running' });
 

package/lib/setup-prompts.mjs

@@ -29,6 +29,7 @@ export async function consentToInstall({
   alreadyConfigured = false,
   alreadyConfiguredNote = '',
   envPath,
+  question = '',
   defaultYes = true,
   readlineModule = readline,
   stdin = process.stdin,
@@ -64,7 +65,7 @@ export async function consentToInstall({
   }
 
   const answer = await promptYesNo({
-    question: `Install local ${name} via Docker?`,
+    question: question || `Install local ${name} via Docker?`,
     defaultYes,
     readlineModule,
     stdin,