@geraldmaron/construct 1.0.14 → 1.0.16

package/lib/mcp/server.mjs

@@ -116,7 +116,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'extract_document_text',
-      description: 'Extracts readable text from a local document path. Supports PDF on macOS plus common text and office document formats.',
+      description: 'Extracts readable text from a local document path. High-fidelity backend (docling Python sidecar via uv, whisper.cpp for audio/video) is wired into `construct ingest`; this MCP path returns the legacy regex extraction for backwards compatibility. Supports PDF, DOCX, XLSX, PPTX, HTML, plain text, email, and transcripts.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -903,6 +903,147 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: 'workflow_init',
+      description: 'Initialize a new workflow for the current project. Creates plan.md state if not already present and returns the initial workflow envelope.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          title: { type: 'string', description: 'Workflow title shown in the plan header (default: "Untitled workflow").' },
+          spec_ref: { type: 'string', description: 'Optional reference to a spec/PRD/ADR id this workflow implements.' },
+        },
+      },
+    },
+    {
+      name: 'workflow_add_task',
+      description: 'Add a task to the current workflow. Pass `request` for intent-based routing (the classifier picks track + specialist) or pass explicit task fields (`key`, `title`, etc.) for manual entry.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          request: { type: 'string', description: 'Natural-language task request; when present, intent-based routing is used and the explicit fields below act as overrides.' },
+          key: { type: 'string', description: 'Stable task key (e.g. T-001). Generated when omitted.' },
+          title: { type: 'string', description: 'Short task title.' },
+          phase: { type: 'string', description: 'Phase bucket (plan, build, validate, ship, etc.).' },
+          owner: { type: 'string', description: 'Specialist or persona that owns the task.' },
+          files: { type: 'array', items: { type: 'string' }, description: 'File paths this task touches.' },
+          readFirst: { type: 'array', items: { type: 'string' }, description: 'Files the owner should read before editing.' },
+          doNotChange: { type: 'array', items: { type: 'string' }, description: 'Files/regions the owner must not modify.' },
+          acceptanceCriteria: { type: 'array', items: { type: 'string' }, description: 'Acceptance criteria as a checklist.' },
+          verification: { type: 'string', description: 'Command(s) or description of how to verify the task is done.' },
+          dependsOn: { type: 'array', items: { type: 'string' }, description: 'Task keys this task depends on.' },
+          overlays: { type: 'array', items: { type: 'string' }, description: 'Role flavors that augment the owner persona for this task.' },
+          challengeRequired: { type: 'boolean', description: 'Force a cx-devil-advocate challenge before the task can complete.' },
+          challengeStatus: { type: 'string', description: 'Initial challenge status when seeded.' },
+          tokenBudget: { type: 'number', description: 'Per-task token budget for cost tracking.' },
+          status: { type: 'string', description: 'Initial status override.' },
+        },
+      },
+    },
+    {
+      name: 'workflow_update_task',
+      description: 'Update fields on an existing workflow task. Requires the task `key`. Only fields supplied are changed.',
+      inputSchema: {
+        type: 'object',
+        required: ['key'],
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          key: { type: 'string', description: 'Task key to update.' },
+          status: { type: 'string', description: 'New status (pending, in_progress, blocked_needs_user, blocked_by_dep, done, etc.).' },
+          owner: { type: 'string', description: 'New owner persona.' },
+          phase: { type: 'string', description: 'New phase bucket.' },
+          note: { type: 'string', description: 'Append-only progress note.' },
+          verification: { type: 'string', description: 'Updated verification description.' },
+          overlays: { type: 'array', items: { type: 'string' }, description: 'Replace the overlay list.' },
+          challengeRequired: { type: 'boolean', description: 'Toggle whether a challenge is required.' },
+          challengeStatus: { type: 'string', description: 'Update the challenge status (proposed, accepted, refused, etc.).' },
+        },
+      },
+    },
+    {
+      name: 'workflow_needs_main_input',
+      description: 'Mark a workflow task as blocked pending user input. Sets status to blocked_needs_user and writes a packet describing the blocker for the orchestrator to surface.',
+      inputSchema: {
+        type: 'object',
+        required: ['taskKey', 'blocker', 'question'],
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          taskKey: { type: 'string', description: 'Task key to mark blocked.' },
+          worker: { type: 'string', description: 'Specialist that needs input (default: current owner).' },
+          blocker: { type: 'string', description: 'One-line description of what is blocking progress.' },
+          question: { type: 'string', description: 'The specific question to put to the user.' },
+        },
+      },
+    },
+    {
+      name: 'workflow_validate',
+      description: 'Validate the current workflow state against the schema and run consistency checks (no orphan tasks, no circular dependencies, every owner resolves to a known persona).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+        },
+      },
+    },
+    {
+      name: 'workflow_status',
+      description: 'Return the full workflow snapshot for the current project: tasks, summary, alignment health, and the public-health surface used by the dashboard.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+        },
+      },
+    },
+    {
+      name: 'workflow_contract_validate',
+      description: 'Validate a producer→consumer handoff against specialists/contracts.json. Required when a specialist hands off to another role: enforces input.mustContain, output schema, disk-artifact postconditions, and binary postconditions per producer (rubber-stamp prevention, post-hoc threat-model prevention, etc.). Self-enforcing: a producer with binary rules MUST pass `packet`, or the call itself is a contract violation.',
+      inputSchema: {
+        type: 'object',
+        required: ['producer', 'consumer'],
+        properties: {
+          producer: { type: 'string', description: 'Producer agent or persona name (e.g. cx-reviewer, cx-security).' },
+          consumer: { type: 'string', description: 'Consumer agent or persona name receiving the handoff.' },
+          id: { type: 'string', description: 'Optional contract id; overrides producer/consumer lookup.' },
+          artifact: { type: 'object', description: 'The handoff payload to validate against the contract schema and disk-artifact postconditions.' },
+          packet: { type: 'object', description: 'The producer\'s in-memory output packet. REQUIRED when the producer has binary postconditions; omitting it is itself a contract violation.' },
+          enforcement: { type: 'string', enum: ['block', 'warn'], description: 'Enforcement mode (default: block). Use warn only when explicitly advisory.' },
+        },
+      },
+    },
+    {
+      name: 'workflow_import_plan',
+      description: 'Bulk-add tasks from a markdown plan to the current workflow. Parses headings and bullet structure to extract task titles, owners, and acceptance criteria.',
+      inputSchema: {
+        type: 'object',
+        required: ['markdown'],
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          markdown: { type: 'string', description: 'Plan markdown to parse.' },
+          phase: { type: 'string', description: 'Phase bucket applied to all imported tasks.' },
+          owner: { type: 'string', description: 'Default owner for tasks that do not specify one.' },
+          readFirst: { type: 'array', items: { type: 'string' }, description: 'Default readFirst files applied to all imported tasks.' },
+          doNotChange: { type: 'array', items: { type: 'string' }, description: 'Default doNotChange files applied to all imported tasks.' },
+          acceptanceCriteria: { type: 'array', items: { type: 'string' }, description: 'Default acceptance criteria applied to all imported tasks.' },
+          title: { type: 'string', description: 'Workflow title to set if the workflow is newly created.' },
+          spec_ref: { type: 'string', description: 'Spec reference to associate with the workflow.' },
+        },
+      },
+    },
+    {
+      name: 'cx_trace_telemetry',
+      description: 'Record a single CX telemetry trace for an agent invocation. Use to log start/end, model used, token cost, and outcome verdict for performance review.',
+      inputSchema: {
+        type: 'object',
+        required: ['agent', 'trace'],
+        properties: {
+          agent: { type: 'string', description: 'Agent or persona name being traced.' },
+          trace: { type: 'object', description: 'Trace record: start_ts, end_ts, model, tokens, verdict, notes, etc.' },
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+        },
+      },
+    },
   ],
 }));
 

package/lib/mcp/tools/skills.mjs

@@ -7,7 +7,7 @@
  */
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { routeRequest, routeRequestVerified, requiresExecutiveApproval, TERMINAL_STATES } from '../../orchestration-policy.mjs';
 import { buildTaskPacketFromIntent } from '../../workflow-state.mjs';
 import { logSkillCall } from '../../telemetry/skill-calls.mjs';
@@ -73,12 +73,15 @@ export function searchSkills(args, { ROOT_DIR }) {
   if (!pattern) return { error: 'Missing pattern argument' };
   const skillsDir = join(ROOT_DIR, 'skills');
 
+  // argv-array form: pattern is a discrete argument, never interpreted by a
+  // shell. MCP tool inputs are model-controlled and must not reach a shell.
+
   try {
-    const output = execSync(`rg -i "${pattern.replace(/"/g, '\\"')}" "${skillsDir}"`, { encoding: 'utf8' });
+    const output = execFileSync('rg', ['-i', pattern, skillsDir], { encoding: 'utf8' });
     return { results: output.split('\n').filter(Boolean) };
   } catch {
     try {
-      const output = execSync(`grep -ri "${pattern.replace(/"/g, '\\"')}" "${skillsDir}"`, { encoding: 'utf8' });
+      const output = execFileSync('grep', ['-ri', pattern, skillsDir], { encoding: 'utf8' });
       return { results: output.split('\n').filter(Boolean) };
     } catch {
       return { results: [], note: 'No matches found or grep error' };

package/lib/mcp/tools/telemetry.mjs

@@ -18,6 +18,7 @@ import { buildStatus } from '../../status.mjs';
 import { readEfficiencyLog, buildCompactEfficiencyDigest } from '../../efficiency.mjs';
 import { addObservation } from '../../observation-store.mjs';
 import { loadConstructEnv } from '../../env-config.mjs';
+import { createSqlClient, closeSqlClient } from '../../storage/backend.mjs';
 
 // Load config.env once at module init so config.env values win over shell env
 // (shell env may have stale/truncated credentials from earlier sessions)
@@ -243,6 +244,35 @@ export async function cxScore(args) {
       }
     }
 
+    // Postgres write-through (team/enterprise). Backs the
+    // construct_skill_quality_correlation view that `construct skills
+    // correlate-quality` reads — without this, the view stays empty and
+    // the CLI surface that promised correlation data delivered nothing.
+    // Best-effort: a missing DATABASE_URL or schema misalignment never
+    // blocks the score from reaching the remote telemetry or the local
+    // observation store above.
+
+    if (Number.isFinite(numericValue)) {
+      const sqlClient = createSqlClient(process.env);
+      if (sqlClient) {
+        try {
+          await sqlClient`
+            insert into construct_cx_scores (ts, trace_id, session_id, agent_id, name, value, comment)
+            values (
+              ${new Date().toISOString()},
+              ${traceId},
+              ${args.session_id ?? null},
+              ${args.agent_id ?? args.name ?? null},
+              ${args.name ?? 'quality'},
+              ${numericValue},
+              ${args.comment ?? null}
+            )
+          `;
+        } catch { /* best-effort write — never block on DB issues */ }
+        finally { await closeSqlClient(sqlClient).catch(() => {}); }
+      }
+    }
+
     return { ok: true, traceId, backend: client.backend, remoteStatus: client.remoteStatus };
   } catch (err) {
     return { ok: false, error: err.message };

package/lib/mcp/tools/workflow.mjs

@@ -104,7 +104,10 @@ export function workflowValidate(args) {
  *   consumer    — agent or persona name receiving it
  *   id          — optional contract id (overrides producer/consumer lookup)
  *   artifact    — the handoff payload to validate
- *   enforcement — 'warn' (default) or 'block'; 'block' returns ok:false on
+ *   packet      — the producer's in-memory output packet. Required when the
+ *                 producer has binary postconditions; omitting it is itself
+ *                 a contract violation.
+ *   enforcement — 'block' (default) or 'warn'; 'block' returns ok:false on
  *                 violation so the workflow can refuse to advance
  *
  * Returns { ok, status?, errors?, warnings?, contract } where status is set
@@ -117,7 +120,8 @@ export async function workflowContractValidate(args) {
     consumer: args.consumer,
     id: args.id,
     artifact: args.artifact,
-    enforcement: args.enforcement || process.env.CONSTRUCT_CONTRACT_ENFORCEMENT || 'warn',
+    packet: args.packet,
+    enforcement: args.enforcement || 'block',
   });
 }
 

package/lib/observation-store.mjs

@@ -112,10 +112,12 @@ function logCapDrop(rootDir, kind, dropped, total) {
 function writeIndex(rootDir, entries) {
   ensureDir(obsDir(rootDir), rootDir);
   const trimmed = entries.slice(0, MAX_INDEX);
-  if (entries.length > MAX_INDEX) {
-    logCapDrop(rootDir, 'observation-index', entries.length - MAX_INDEX, entries.length);
+  const dropped = Math.max(0, entries.length - MAX_INDEX);
+  if (dropped > 0) {
+    logCapDrop(rootDir, 'observation-index', dropped, entries.length);
   }
   fs.writeFileSync(indexPath(rootDir), JSON.stringify(trimmed, null, 2) + '\n');
+  return { dropped };
 }
 
 function readVectors(rootDir) {
@@ -130,10 +132,12 @@ function readVectors(rootDir) {
 
 function writeVectors(rootDir, records) {
   ensureDir(obsDir(rootDir), rootDir);
-  if (records.length > MAX_INDEX) {
-    logCapDrop(rootDir, 'observation-vectors', records.length - MAX_INDEX, records.length);
+  const dropped = Math.max(0, records.length - MAX_INDEX);
+  if (dropped > 0) {
+    logCapDrop(rootDir, 'observation-vectors', dropped, records.length);
   }
   fs.writeFileSync(vectorsPath(rootDir), JSON.stringify(records, null, 2) + '\n');
+  return { dropped };
 }
 
 /**
@@ -188,6 +192,7 @@ export async function addObservation(rootDir, {
     JSON.stringify(record, null, 2) + '\n',
   );
 
+  let indexDropped = 0;
   withFileLockSync(indexPath(rootDir), () => {
     const index = readIndex(rootDir);
     index.unshift({
@@ -198,8 +203,12 @@ export async function addObservation(rootDir, {
       project: record.project,
       createdAt: now,
     });
-    writeIndex(rootDir, index);
+    indexDropped = writeIndex(rootDir, index).dropped;
   });
+  if (indexDropped > 0) {
+    record.capDropped = indexDropped;
+    process.stderr.write(`[observation-store] observation cap reached: ${indexDropped} oldest entries evicted (cap=${MAX_INDEX})\n`);
+  }
 
   // Try SQL storage with neural embeddings
   try {

package/lib/ollama-manager.mjs

@@ -6,10 +6,26 @@
  * pulling new models, and configuring Ollama as a provider.
  */
 
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 
+// argv-array form for every shell-out: no shell interpolation, model names and
+// JSON bodies are passed as discrete arguments / stdin so user-supplied values
+// cannot break out of the command.
+
+function curlGet(url, { timeout } = {}) {
+  return execFileSync('curl', ['-s', url], { encoding: 'utf8', timeout });
+}
+
+function curlPost(url, body, { timeout } = {}) {
+  return execFileSync('curl', ['-s', url, '--data-binary', '@-'], {
+    encoding: 'utf8',
+    timeout,
+    input: typeof body === 'string' ? body : JSON.stringify(body),
+  });
+}
+
 const OLLAMA_BASE_URL = process.env.OLLAMA_BASE_URL || process.env.OLLAMA_HOST || 'http://localhost:11434';
 
 /**
@@ -17,14 +33,11 @@ const OLLAMA_BASE_URL = process.env.OLLAMA_BASE_URL || process.env.OLLAMA_HOST |
  */
 export function checkOllamaStatus() {
   try {
-    execSync('which ollama', { stdio: 'pipe' });
+    execFileSync('which', ['ollama'], { stdio: 'pipe' });
     const installed = true;
-    
+
     try {
-      const response = execSync(`curl -s ${OLLAMA_BASE_URL}/api/tags`, { 
-        encoding: 'utf8',
-        timeout: 3000
-      });
+      const response = curlGet(`${OLLAMA_BASE_URL}/api/tags`, { timeout: 3000 });
       const data = JSON.parse(response);
       return {
         installed,
@@ -54,10 +67,7 @@ export function checkOllamaStatus() {
  */
 export function listModels() {
   try {
-    const response = execSync(`curl -s ${OLLAMA_BASE_URL}/api/tags`, { 
-      encoding: 'utf8',
-      timeout: 5000
-    });
+    const response = curlGet(`${OLLAMA_BASE_URL}/api/tags`, { timeout: 5000 });
     const data = JSON.parse(response);
     return data.models || [];
   } catch (e) {
@@ -71,7 +81,7 @@ export function listModels() {
 export function pullModel(modelName, { verbose = false } = {}) {
   console.log(`Pulling ${modelName}...`);
   try {
-    const output = execSync(`ollama pull ${modelName}`, {
+    const output = execFileSync('ollama', ['pull', modelName], {
       encoding: 'utf8',
       stdio: verbose ? 'inherit' : 'pipe'
     });
@@ -86,7 +96,7 @@ export function pullModel(modelName, { verbose = false } = {}) {
  */
 export function removeModel(modelName) {
   try {
-    execSync(`ollama rm ${modelName}`, { encoding: 'utf8' });
+    execFileSync('ollama', ['rm', modelName], { encoding: 'utf8' });
     return { success: true };
   } catch (e) {
     return { success: false, error: e.message };
@@ -98,10 +108,7 @@ export function removeModel(modelName) {
  */
 export function showModel(modelName) {
   try {
-    const response = execSync(`curl -s ${OLLAMA_BASE_URL}/api/show -d '{"name":"${modelName}"}'`, {
-      encoding: 'utf8',
-      timeout: 5000
-    });
+    const response = curlPost(`${OLLAMA_BASE_URL}/api/show`, { name: modelName }, { timeout: 5000 });
     return JSON.parse(response);
   } catch (e) {
     throw new Error(`Failed to fetch model details: ${e.message}`);
@@ -113,14 +120,11 @@ export function showModel(modelName) {
  */
 export function testModel(modelName, prompt = 'Say hello in one sentence.') {
   try {
-    const response = execSync(`curl -s ${OLLAMA_BASE_URL}/api/generate -d '${JSON.stringify({
-      model: modelName,
-      prompt: prompt,
-      stream: false
-    })}'`, {
-      encoding: 'utf8',
-      timeout: 30000
-    });
+    const response = curlPost(
+      `${OLLAMA_BASE_URL}/api/generate`,
+      { model: modelName, prompt, stream: false },
+      { timeout: 30000 },
+    );
     const data = JSON.parse(response);
     return {
       success: true,
@@ -371,7 +375,7 @@ async function cmdOllamaSetup(args) {
     if (autoYes || process.platform === 'darwin') {
       console.log('Installing via Homebrew...');
       try {
-        execSync('brew install ollama', { stdio: 'inherit' });
+        execFileSync('brew', ['install', 'ollama'], { stdio: 'inherit' });
         console.log('✅ Ollama installed');
       } catch (e) {
         console.error('❌ Installation failed. Please install manually: https://ollama.com');
@@ -390,11 +394,11 @@ async function cmdOllamaSetup(args) {
     console.log('⚠️  Ollama is not running');
     console.log('Starting Ollama service...');
     try {
-      execSync('brew services start ollama', { stdio: 'pipe' });
+      execFileSync('brew', ['services', 'start', 'ollama'], { stdio: 'pipe' });
       console.log('✅ Ollama service started');
       // Wait for it to be ready
       console.log('Waiting for Ollama to be ready...');
-      execSync('sleep 3');
+      execFileSync('sleep', ['3']);
     } catch (e) {
       console.log('You can start it manually with: ollama serve');
     }

package/lib/orchestration-policy.mjs

@@ -352,6 +352,21 @@ export function classifyRoleFlavors(request = '') {
   };
 }
 
+// One line per non-null flavor: "cx-<role>: loaded <role>.<flavor>
+// overlay". Verbose chat surface + cx_trace span attribute; lets a
+// post-hoc reviewer see which overlays drove a given dispatch.
+
+export function formatOverlaySelection(roleFlavors) {
+  if (!roleFlavors || typeof roleFlavors !== 'object') return [];
+  const lines = [];
+  for (const [role, flavor] of Object.entries(roleFlavors)) {
+    if (!flavor) continue;
+    const specialist = `cx-${role.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
+    lines.push(`${specialist}: loaded ${role}.${flavor} overlay`);
+  }
+  return lines;
+}
+
 export function detectRiskFlags(request = '') {
   const text = String(request).toLowerCase();
   return {

package/lib/prompt-composer.js

@@ -94,7 +94,17 @@ function compactTokens(text, tokenLimit = 300, { modelId = 'default' } = {}) {
 function readPromptBody(promptFile, rootDir) {
   const filePath = path.join(rootDir, promptFile);
   if (!fs.existsSync(filePath)) return '';
-  return fs.readFileSync(filePath, 'utf8').trim();
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return stripLeadingYamlFrontmatter(raw).trim();
+}
+
+function stripLeadingYamlFrontmatter(content) {
+  if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) return content;
+  const closeIdx = content.indexOf('\n---', 4);
+  if (closeIdx === -1) return content;
+  const afterClose = content.indexOf('\n', closeIdx + 1);
+  if (afterClose === -1) return '';
+  return content.slice(afterClose + 1);
 }
 
 function buildLearnedPatternsBlock(agentName, {

package/lib/roles/gateway.mjs

@@ -11,7 +11,7 @@
  */
 
 import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { emit, _paths } from './event-bus.mjs';
@@ -54,7 +54,36 @@ function appendPending(entry) {
   appendFileSync(pendingPath(), JSON.stringify(entry) + '\n');
 }
 
+// Paths under the OS tmpdir are by definition test fixtures or sandbox
+// runs, not real project state. Escalating from them spawns persistent
+// beads for ephemeral files — pure tracker noise. macOS resolves
+// $TMPDIR through a /private/var/folders/... symlink; the raw tmpdir
+// and its /private prefix are both checked so either resolved form
+// matches.
+
+export function isTestFixturePath(p) {
+  if (!p || typeof p !== 'string') return false;
+  const tmp = tmpdir();
+  if (p.startsWith(tmp)) return true;
+  if (p.startsWith('/private' + tmp)) return true;
+  if (p.startsWith('/tmp/')) return true;
+  // macOS canonical user-tmp prefix when $TMPDIR is set elsewhere
+  if (/^\/private\/var\/folders\/[^/]+\/[^/]+\/T\//.test(p)) return true;
+  if (/^\/var\/folders\/[^/]+\/[^/]+\/T\//.test(p)) return true;
+  return false;
+}
+
+function eventIsFromTestFixture(event) {
+  if (isTestFixturePath(event?.cwd)) return true;
+  if (isTestFixturePath(event?.project)) return true;
+  if (isTestFixturePath(event?.context?.filePath)) return true;
+  return false;
+}
+
 export function shouldEscalate(event, manifest, now = Date.now()) {
+  if (eventIsFromTestFixture(event)) {
+    return { escalate: false, reason: 'test-fixture-path' };
+  }
   const fp = event.fingerprint;
   const pending = readPending();
 

package/lib/runtime/uv-bootstrap.mjs

@@ -0,0 +1,129 @@
+/**
+ * lib/runtime/uv-bootstrap.mjs — idempotent uv + docling venv provisioner.
+ *
+ * On first use: downloads uv via the official Astral installer, creates
+ * `<rootDir>/.cx/runtime/docling/.venv`, installs the pinned docling release.
+ * Subsequent calls are no-ops if the venv is already present.
+ *
+ * Best-practice notes (2026-06):
+ *   - uv (Astral) is the consensus Python tooling, ~10× faster than pip, single
+ *     binary, lockfile-based. OpenAI acquired Astral on 2026-03-19; the project
+ *     remains Apache-2.0 and actively maintained, but single-vendor governance
+ *     is a documented concern — flagged for re-evaluation if licensing shifts.
+ *   - docling (IBM, MIT, donated to LF AI & Data early 2026) is the consensus
+ *     multi-format doc parser for layout-aware MD/JSON output.
+ *
+ * Returns the path to the venv's python binary so callers can spawn the
+ * sidecar without relying on PATH state.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import os from 'node:os';
+
+const DOCLING_PIN = '2.45.0';
+const UV_INSTALL_URL = 'https://astral.sh/uv/install.sh';
+const UV_TIMEOUT_MS = 120_000;
+const VENV_TIMEOUT_MS = 240_000;
+const INSTALL_TIMEOUT_MS = 600_000;
+
+export function defaultRuntimeDir(cwd = process.cwd()) {
+  return path.join(cwd, '.cx', 'runtime', 'docling');
+}
+
+function which(bin) {
+  const result = spawnSync(process.platform === 'win32' ? 'where' : 'which', [bin], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return result.stdout.trim().split('\n')[0] || null;
+}
+
+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 });
+  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,
+    timeout: UV_TIMEOUT_MS,
+    encoding: 'utf8',
+  });
+  if (sh.status !== 0) {
+    throw new Error(`uv install failed (${sh.status}): ${sh.stderr || sh.stdout}`);
+  }
+  if (!existsSync(cachedUv)) {
+    throw new Error(`uv install reported success but binary not found at ${cachedUv}`);
+  }
+  return cachedUv;
+}
+
+function pythonBinFor(venvDir) {
+  const candidates = process.platform === 'win32'
+    ? [path.join(venvDir, 'Scripts', 'python.exe')]
+    : [path.join(venvDir, 'bin', 'python'), path.join(venvDir, 'bin', 'python3')];
+  return candidates.find((p) => existsSync(p));
+}
+
+function readMarker(markerPath) {
+  try { return JSON.parse(readFileSync(markerPath, 'utf8')); }
+  catch { return null; }
+}
+
+function writeMarker(markerPath, payload) {
+  mkdirSync(path.dirname(markerPath), { recursive: true });
+  writeFileSync(markerPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+}
+
+export function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), force = false } = {}) {
+  mkdirSync(runtimeDir, { recursive: true });
+  const venvDir = path.join(runtimeDir, '.venv');
+  const markerPath = path.join(runtimeDir, '.install-marker.json');
+  const existingMarker = readMarker(markerPath);
+  const existingPython = pythonBinFor(venvDir);
+
+  if (!force && existingPython && existingMarker?.doclingVersion === DOCLING_PIN) {
+    return { pythonBin: existingPython, venvDir, runtimeDir, fresh: false };
+  }
+
+  const uv = ensureUv(runtimeDir);
+
+  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}`);
+  }
+
+  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}`);
+  }
+
+  const pythonBin = pythonBinFor(venvDir);
+  writeMarker(markerPath, {
+    doclingVersion: DOCLING_PIN,
+    installedAt: new Date().toISOString(),
+    pythonBin,
+    uvVersion: spawnSync(uv, ['--version'], { encoding: 'utf8' }).stdout.trim() || null,
+    platform: `${process.platform}-${process.arch}`,
+    node: process.version,
+  });
+
+  return { pythonBin, venvDir, runtimeDir, fresh: true };
+}
+
+export function describeDoclingRuntime({ runtimeDir = defaultRuntimeDir() } = {}) {
+  const venvDir = path.join(runtimeDir, '.venv');
+  return {
+    runtimeDir,
+    venvDir,
+    pythonBin: pythonBinFor(venvDir),
+    marker: readMarker(path.join(runtimeDir, '.install-marker.json')),
+    available: !!pythonBinFor(venvDir),
+  };
+}