@geraldmaron/construct 1.0.3 → 1.0.5

package/lib/status.mjs

@@ -24,6 +24,7 @@ import { describeSqlStore, sqlStoreHealth } from './storage/sql-store.mjs';
 import { describeVectorStore } from './storage/vector-store.mjs';
 import { describeSqlStoreHealth } from './storage/sql-store.mjs';
 import { triggerAutoBackfillIfSparse } from './telemetry/backfill.mjs';
+import { resolveTraceBackend, telemetryProviderLabel } from './telemetry/client.mjs';
 const TOTAL_BYTES_WARNING_THRESHOLD = 750_000;
 
 function readJSON(path) {
@@ -317,18 +318,27 @@ async function defaultProbeService(service) {
 }
 
 async function fetchTelemetryStatus(env, { timeout = 2500 } = {}) {
+  const backend = resolveTraceBackend(env);
+  if (backend === 'local') return { status: 'healthy', summary: 'Local JSONL tracing enabled · remote export not configured', backend, provider: telemetryProviderLabel(env) };
+  if (backend === 'none') return { status: 'disabled', summary: 'Remote telemetry disabled · local JSONL tracing preserved', backend, provider: telemetryProviderLabel(env) };
+  if (backend === 'otel') {
+    const endpoint = (env.CONSTRUCT_OTEL_EXPORTER_OTLP_ENDPOINT ?? '').replace(/\/$/, '');
+    if (!endpoint) return { status: 'unavailable', summary: 'OTLP endpoint not configured', backend, provider: telemetryProviderLabel(env) };
+    return { status: 'configured', summary: `OTLP export configured · ${endpoint}`, backend, provider: telemetryProviderLabel(env) };
+  }
   const baseUrl = (env.CONSTRUCT_TELEMETRY_URL ?? '').replace(/\/$/, '');
   const key = env.CONSTRUCT_TELEMETRY_PUBLIC_KEY;
   const secret = env.CONSTRUCT_TELEMETRY_SECRET_KEY;
-  if (!key || !secret) return { status: 'unavailable', summary: 'Telemetry credentials not configured' };
+  if (backend === 'langfuse' && (!key || !secret)) return { status: 'unavailable', summary: 'Langfuse credentials not configured', backend, provider: telemetryProviderLabel(env) };
   if (!baseUrl) return { status: 'unavailable', summary: 'CONSTRUCT_TELEMETRY_URL not set' };
   const headers = {
-    Authorization: `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}`,
+    ...(key && secret ? { Authorization: `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}` } : {}),
   };
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeout);
   try {
-    const res = await fetch(`${baseUrl}/api/public/traces?limit=25`, { headers, signal: controller.signal });
+    const tracesPath = backend === 'http' ? '/traces?limit=25' : '/api/public/traces?limit=25';
+    const res = await fetch(`${baseUrl}${tracesPath}`, { headers, signal: controller.signal });
     if (res.status === 401 || res.status === 403) {
       return { status: 'credentials-invalid', summary: `Telemetry credentials rejected (HTTP ${res.status}) — run: construct init` };
     }
@@ -359,6 +369,8 @@ async function fetchTelemetryStatus(env, { timeout = 2500 } = {}) {
 
     return {
       status,
+      backend,
+      provider: telemetryProviderLabel(env),
       total,
       rich: counts.rich,
       partial: counts.partial,
@@ -478,6 +490,40 @@ export function buildPublicHealthSurface({
 }
 
 function traceBackendDefinition(env) {
+  const backend = resolveTraceBackend(env);
+  const provider = telemetryProviderLabel(env);
+  if (backend === 'local' || backend === 'none') {
+    return {
+      id: 'telemetry',
+      name: 'Telemetry',
+      url: 'local://.cx/traces',
+      runtime: 'local',
+      note: backend === 'none' ? 'Remote disabled; local JSONL preserved' : 'Local JSONL traces',
+      healthyMessage: 'Local trace capture enabled',
+      impactsOverall: false,
+      selfCheck: {
+        status: backend === 'none' ? 'disabled' : 'healthy',
+        message: backend === 'none' ? 'Remote telemetry disabled' : 'Writing .cx/traces/*.jsonl',
+      },
+    };
+  }
+  if (backend === 'otel') {
+    const endpoint = (env.CONSTRUCT_OTEL_EXPORTER_OTLP_ENDPOINT ?? '').replace(/\/$/, '');
+    return {
+      id: 'telemetry',
+      name: 'Telemetry',
+      url: endpoint || '(not configured)',
+      probeUrl: '',
+      runtime: 'remote',
+      note: `${provider} trace export`,
+      healthyMessage: 'Configured',
+      impactsOverall: false,
+      selfCheck: {
+        status: endpoint ? 'configured' : 'unavailable',
+        message: endpoint ? `OTLP export configured: ${endpoint}` : 'CONSTRUCT_OTEL_EXPORTER_OTLP_ENDPOINT not set',
+      },
+    };
+  }
   const url = (env.CONSTRUCT_TELEMETRY_URL ?? '').replace(/\/$/, '');
   const pubKey = env.CONSTRUCT_TELEMETRY_PUBLIC_KEY || '';
   const secKey = env.CONSTRUCT_TELEMETRY_SECRET_KEY || '';
@@ -486,10 +532,10 @@ function traceBackendDefinition(env) {
     id: 'telemetry',
     name: 'Telemetry',
     url: url || '(not configured)',
-    probeUrl: url ? `${url}/api/public/traces?limit=1` : '',
+    probeUrl: url ? `${url}${backend === 'http' ? '/traces?limit=1' : '/api/public/traces?limit=1'}` : '',
     probeHeaders: auth ? { Authorization: auth } : undefined,
     runtime: 'live',
-    note: 'Trace backend',
+    note: `${provider} trace export`,
     healthyMessage: 'Reachable',
     impactsOverall: false,
   };

package/lib/storage/backend.mjs

@@ -1,17 +1,27 @@
 #!/usr/bin/env node
 /**
  * lib/storage/backend.mjs — shared storage backend helpers for SQL/vector wiring.
+ *
+ * postgres is an optional peer dep. Top-level await catches the case where it is not
+ * installed (fresh installs, test temp dirs) so the module loads cleanly everywhere.
  */
-import postgres from 'postgres';
 import { resolveDatabaseUrl } from '../env-config.mjs';
 
+let postgres = null;
+try {
+  const mod = await import('postgres');
+  postgres = mod.default ?? mod;
+} catch {
+  // postgres not installed — SQL features unavailable; createSqlClient returns null
+}
+
 function cleanUrl(url) {
   return String(url || '').trim();
 }
 
 export function createSqlClient(env = process.env) {
   const databaseUrl = cleanUrl(resolveDatabaseUrl(env));
-  if (!databaseUrl) return null;
+  if (!databaseUrl || !postgres) return null;
   return postgres(databaseUrl, {
     max: Number.parseInt(env.CONSTRUCT_DB_POOL_SIZE || '5', 10),
     idle_timeout: Number.parseInt(env.CONSTRUCT_DB_IDLE_TIMEOUT_MS || '30000', 10),

package/lib/strategy-store.mjs

@@ -0,0 +1,371 @@
+/**
+ * lib/strategy-store.mjs — Multi-scope product strategy store.
+ *
+ * Strategy is organised by scope: product, technical, gtm, platform.
+ * Each scope lives in its own file under .cx/knowledge/decisions/strategy/{scope}.md.
+ * Strategy documents are NEVER auto-updated from ingested documents — they require
+ * an explicit writeStrategy() call from a privileged caller.
+ *
+ * In team/enterprise mode Postgres is the secondary store (best-effort). Each scope
+ * is stored as a separate row whose content is prefixed with `scope:{name}\n` so we
+ * can store and retrieve scopes without adding a new column to the existing schema.
+ *
+ * getStrategyDigest() / getStrategyDigestSync() return a compact block (≤ 500 tokens)
+ * suitable for injection into agent prompts. getStrategyDigestSync() is the file-only
+ * synchronous path required where await is not available (e.g. prompt assembly).
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { cxDir } from './paths.mjs';
+import { hasSqlStore } from './storage/sql-store.mjs';
+import { createSqlClient } from './storage/backend.mjs';
+
+const VALID_SCOPES = ['product', 'technical', 'gtm', 'platform'];
+const SCOPE_PREFIX = 'scope:';
+
+// ── Path helpers ──────────────────────────────────────────────────────────────
+
+export function strategyDir(env = process.env) {
+  return join(cxDir(), 'knowledge', 'decisions', 'strategy');
+}
+
+export function strategyFilePath(scope = 'product', env = process.env) {
+  return join(strategyDir(env), `${scope}.md`);
+}
+
+// ── Scope discovery ───────────────────────────────────────────────────────────
+
+/**
+ * Return scope names that have corresponding files in the strategy directory.
+ *
+ * @param {object} [env]
+ * @returns {string[]}
+ */
+export function listStrategyScopes(env = process.env) {
+  const dir = strategyDir(env);
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith('.md'))
+      .map((f) => basename(f, '.md'));
+  } catch {
+    return [];
+  }
+}
+
+// ── Read helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Read one strategy scope from Postgres (primary) or file (fallback).
+ *
+ * @param {string} [scope]
+ * @param {object} [env]
+ * @returns {Promise<{ content: string, version: number, updatedAt: string, source: 'postgres'|'file'|'none', scope: string }>}
+ */
+export async function readStrategy(scope = 'product', env = process.env) {
+  if (hasSqlStore(env)) {
+    const client = createSqlClient(env);
+    try {
+      const project = env.CX_PROJECT || 'default';
+      const prefix = `${SCOPE_PREFIX}${scope}\n`;
+
+      // Rows stored with the scope prefix — match on content prefix
+      const rows = await client`
+        select content, version, updated_at
+        from construct_strategy
+        where project = ${project}
+          and content like ${prefix + '%'}
+        order by version desc
+        limit 1
+      `;
+
+      if (rows.length > 0) {
+        const row = rows[0];
+        return {
+          content: row.content.startsWith(prefix) ? row.content.slice(prefix.length) : row.content,
+          version: row.version,
+          updatedAt: row.updated_at instanceof Date ? row.updated_at.toISOString() : String(row.updated_at),
+          source: 'postgres',
+          scope,
+        };
+      }
+    } catch {
+      // Postgres unavailable — fall through to file
+    } finally {
+      if (client) await client.end({ timeout: 5 }).catch(() => {});
+    }
+  }
+
+  const filePath = strategyFilePath(scope, env);
+  if (existsSync(filePath)) {
+    const content = readFileSync(filePath, 'utf8');
+    return { content, version: 1, updatedAt: new Date().toISOString(), source: 'file', scope };
+  }
+
+  return { content: '', version: 0, updatedAt: new Date().toISOString(), source: 'none', scope };
+}
+
+/**
+ * Read all present strategy scopes.
+ *
+ * When Postgres is available it reads all rows for the project and parses scope
+ * from the prefix. Files are used as the fallback or supplement for scopes that
+ * have no Postgres row.
+ *
+ * @param {object} [env]
+ * @returns {Promise<Map<string, { content: string, version: number, updatedAt: string, source: string }>>}
+ */
+export async function readAllStrategies(env = process.env) {
+  const result = new Map();
+
+  if (hasSqlStore(env)) {
+    const client = createSqlClient(env);
+    try {
+      const project = env.CX_PROJECT || 'default';
+
+      // Fetch all rows — latest version per scope
+      const rows = await client`
+        select distinct on (
+          substring(content from 1 for position(E'\n' in content))
+        ) content, version, updated_at
+        from construct_strategy
+        where project = ${project}
+          and content like ${SCOPE_PREFIX + '%'}
+        order by
+          substring(content from 1 for position(E'\n' in content)),
+          version desc
+      `;
+
+      for (const row of rows) {
+        const firstNewline = row.content.indexOf('\n');
+        if (firstNewline === -1) continue;
+        const header = row.content.slice(0, firstNewline);
+        if (!header.startsWith(SCOPE_PREFIX)) continue;
+        const rowScope = header.slice(SCOPE_PREFIX.length);
+        const content = row.content.slice(firstNewline + 1);
+        result.set(rowScope, {
+          content,
+          version: row.version,
+          updatedAt: row.updated_at instanceof Date ? row.updated_at.toISOString() : String(row.updated_at),
+          source: 'postgres',
+        });
+      }
+    } catch {
+      // Fall through to file-based reads
+    } finally {
+      if (client) await client.end({ timeout: 5 }).catch(() => {});
+    }
+  }
+
+  // Supplement / replace with file-based reads for any scope present on disk
+  const fileScopes = listStrategyScopes(env);
+  for (const fileScope of fileScopes) {
+    if (result.has(fileScope)) continue;
+    const filePath = strategyFilePath(fileScope, env);
+    try {
+      const content = readFileSync(filePath, 'utf8');
+      result.set(fileScope, {
+        content,
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        source: 'file',
+      });
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  return result;
+}
+
+// ── Digest helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Parse markdown into sections split on ## headers.
+ *
+ * @param {string} content
+ * @returns {Array<{ header: string, body: string }>}
+ */
+function parseSections(content) {
+  const lines = content.split('\n');
+  const sections = [];
+  let current = null;
+
+  for (const line of lines) {
+    if (line.startsWith('## ')) {
+      if (current) sections.push(current);
+      current = { header: line.slice(3).trim(), body: '' };
+    } else if (current) {
+      current.body += line + '\n';
+    }
+  }
+  if (current) sections.push(current);
+  return sections;
+}
+
+/**
+ * Truncate a body to the first N sentences.
+ *
+ * @param {string} body
+ * @param {number} maxSentences
+ * @returns {string}
+ */
+function firstSentences(body, maxSentences = 2) {
+  const trimmed = body.trim();
+  if (!trimmed) return '';
+  const sentences = trimmed.match(/[^.!?\n]+[.!?\n]+/g) || [trimmed];
+  return sentences.slice(0, maxSentences).join(' ').trim();
+}
+
+/**
+ * Build a compact markdown block from a single scope's content.
+ *
+ * @param {string} scopeName
+ * @param {string} content
+ * @param {number} charBudget — remaining character budget; mutated by reference via returned delta
+ * @returns {{ text: string, charsUsed: number }}
+ */
+function buildScopeBlock(scopeName, content, charBudget) {
+  const sections = parseSections(content);
+  if (!sections.length) return { text: '', charsUsed: 0 };
+
+  const lines = [`### ${scopeName}`];
+  let used = scopeName.length + 5;
+
+  for (const { header, body } of sections) {
+    if (used >= charBudget) break;
+    const excerpt = firstSentences(body, 2);
+    const line = excerpt ? `**${header}:** ${excerpt}` : `**${header}**`;
+    lines.push(line);
+    used += line.length + 1;
+  }
+
+  const text = lines.join('\n');
+  return { text, charsUsed: used };
+}
+
+/**
+ * Return a compact strategy digest (≤ 500 tokens) for agent prompt injection.
+ *
+ * Reads all present scopes asynchronously. Returns empty string when no scopes exist.
+ *
+ * @param {object} [env]
+ * @returns {Promise<string>}
+ */
+export async function getStrategyDigest(env = process.env) {
+  try {
+    const all = await readAllStrategies(env);
+    if (!all.size) return '';
+
+    const TOKEN_LIMIT = 500;
+    let charBudget = TOKEN_LIMIT * 4;
+    const parts = ['## Active strategy'];
+
+    for (const [scopeName, { content }] of all) {
+      if (!content) continue;
+      const { text, charsUsed } = buildScopeBlock(scopeName, content, charBudget);
+      if (text) {
+        parts.push(text);
+        charBudget -= charsUsed;
+      }
+      if (charBudget <= 0) break;
+    }
+
+    return parts.length > 1 ? parts.join('\n') : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Synchronous file-only strategy digest for prompt-composer.js.
+ *
+ * Reads all .md files present in the strategy directory directly. Never reads
+ * Postgres. Returns empty string when the directory is absent or empty.
+ *
+ * @param {object} [env]
+ * @returns {string}
+ */
+export function getStrategyDigestSync(env = process.env) {
+  try {
+    const dir = strategyDir(env);
+    if (!existsSync(dir)) return '';
+
+    const files = readdirSync(dir).filter((f) => f.endsWith('.md'));
+    if (!files.length) return '';
+
+    const TOKEN_LIMIT = 500;
+    let charBudget = TOKEN_LIMIT * 4;
+    const parts = ['## Active strategy'];
+
+    for (const file of files) {
+      if (charBudget <= 0) break;
+      const scopeName = basename(file, '.md');
+      let content;
+      try {
+        content = readFileSync(join(dir, file), 'utf8');
+      } catch {
+        continue;
+      }
+      if (!content) continue;
+      const { text, charsUsed } = buildScopeBlock(scopeName, content, charBudget);
+      if (text) {
+        parts.push(text);
+        charBudget -= charsUsed;
+      }
+    }
+
+    return parts.length > 1 ? parts.join('\n') : '';
+  } catch {
+    return '';
+  }
+}
+
+// ── Write ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Write a strategy scope to file (always) and Postgres (best-effort if available).
+ *
+ * The scope parameter defaults to 'product'. When writing to Postgres the content
+ * is prefixed with `scope:{name}\n` to allow per-scope storage without a schema change.
+ *
+ * @param {string} content
+ * @param {string} [scope]
+ * @param {object} [opts]
+ * @param {string} [opts.updatedBy]
+ * @param {object} [opts.env]
+ */
+export async function writeStrategy(content, scope = 'product', { updatedBy, env = process.env } = {}) {
+  const filePath = strategyFilePath(scope, env);
+  const dir = strategyDir(env);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(filePath, content, 'utf8');
+
+  if (!hasSqlStore(env)) return;
+
+  const client = createSqlClient(env);
+  try {
+    const project = env.CX_PROJECT || 'default';
+    const scopedContent = `${SCOPE_PREFIX}${scope}\n${content}`;
+    const prefix = `${SCOPE_PREFIX}${scope}\n`;
+
+    const existing = await client`
+      select version from construct_strategy
+      where project = ${project}
+        and content like ${prefix + '%'}
+      order by version desc
+      limit 1
+    `;
+    const nextVersion = existing.length > 0 ? existing[0].version + 1 : 1;
+
+    await client`
+      insert into construct_strategy (project, content, version, updated_by)
+      values (${project}, ${scopedContent}, ${nextVersion}, ${updatedBy ?? null})
+    `;
+  } catch {
+    // Best-effort Postgres write — file write already succeeded
+  } finally {
+    if (client) await client.end({ timeout: 5 }).catch(() => {});
+  }
+}

package/lib/telemetry/backends/local.mjs

@@ -7,11 +7,12 @@
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 
 export const name = 'local';
 
-const TRACES_DIR = join(homedir(), '.cx', 'traces');
+function tracesDir(env = process.env) {
+  return join(env.CX_TOOLKIT_DIR || process.cwd(), '.cx', 'traces');
+}
 
 export async function isAvailable() {
   return true;
@@ -25,7 +26,8 @@ export async function isAvailable() {
  * @returns {Promise<object[]>}
  */
 export async function listTraces(teamId, windowMs) {
-  if (!existsSync(TRACES_DIR)) return [];
+  const dir = tracesDir();
+  if (!existsSync(dir)) return [];
 
   const since = Date.now() - windowMs;
   const files = readdirSync(TRACES_DIR)
@@ -36,7 +38,7 @@ export async function listTraces(teamId, windowMs) {
 
   const traces = [];
   for (const file of files) {
-    const lines = readFileSync(join(TRACES_DIR, file), 'utf8')
+      const lines = readFileSync(join(dir, file), 'utf8')
       .split('\n')
       .filter(Boolean);
     for (const line of lines) {