@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/services/telemetry-backend.mjs

@@ -1,177 +0,0 @@
-/**
- * lib/services/telemetry-backend.mjs — local services stack management.
- *
- * Manages the local Postgres service (services/docker-compose.yml).
- * In solo mode, Postgres runs as a Docker container with pgvector enabled.
- *
- * Remote telemetry backends (for trace ingestion) are configured via
- * CONSTRUCT_TELEMETRY_URL / CONSTRUCT_TELEMETRY_PUBLIC_KEY /
- * CONSTRUCT_TELEMETRY_SECRET_KEY env vars. This module handles local
- * infrastructure only — it does not manage telemetry dashboard services.
- */
-
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-
-import { getUserEnvPath, writeEnvValues } from '../env-config.mjs';
-
-/** Local Postgres port (within Construct's 54329-54339 reserved block). */
-export const POSTGRES_LOCAL_PORT = 54329;
-
-export function isRemoteTelemetry(url = '') {
-  if (!url) return false;
-  return !url.includes('localhost') && !url.includes('127.0.0.1');
-}
-
-export function servicesComposePath(rootDir) {
-  return path.join(rootDir, 'services', 'docker-compose.yml');
-}
-
-// Keep only the N most recent stash pairs (.dump + .json) in the stash dir.
-export function pruneStashDir(dir, keep = 3) {
-  try {
-    const dumps = fs.readdirSync(dir)
-      .filter((f) => f.endsWith('.dump'))
-      .sort()
-      .reverse();
-    for (const dump of dumps.slice(keep)) {
-      fs.rmSync(path.join(dir, dump), { force: true });
-      fs.rmSync(path.join(dir, dump.replace('.dump', '.json')), { force: true });
-    }
-  } catch { /* non-critical */ }
-}
-
-/**
- * Verify that the Postgres service is reachable. Returns a status object.
- * Verifies the Postgres service is up and ready.
- */
-export async function verifyPostgresHealth({
-  port = POSTGRES_LOCAL_PORT,
-  fetchFn = globalThis.fetch,
-  maxRetries = 5,
-  intervalMs = 2000,
-} = {}) {
-  // Postgres is not HTTP — health is checked via pg_isready in docker instead
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      const result = spawnSync('docker', [
-        'exec', 'construct-postgres',
-        'pg_isready', '-U', 'construct', '-d', 'construct',
-      ], { stdio: 'pipe', timeout: 3000 });
-      if (result.status === 0) return { status: 'verified' };
-    } catch { /* not ready yet */ }
-    if (attempt < maxRetries - 1) await new Promise((r) => setTimeout(r, intervalMs));
-  }
-  return { status: 'unreachable' };
-}
-
-/**
- * Verify telemetry backend keys (remote HTTP).
- * 
- */
-export async function verifyTelemetryKeys({
-  baseUrl,
-  publicKey,
-  secretKey,
-  composeRunner,
-  composeFile,
-  homeDir = os.homedir(),
-  maxRetries = 5,
-  intervalMs = 2000,
-  spawnSyncFn = spawnSync,
-  fetchFn = globalThis.fetch,
-  overallTimeoutMs = 0,
-} = {}) {
-  const resolvedBaseUrl =
-    baseUrl ??
-    process.env.CONSTRUCT_TELEMETRY_URL ??
-    '';
-  const resolvedPublicKey =
-    publicKey ??
-    process.env.CONSTRUCT_TELEMETRY_PUBLIC_KEY ??
-    '';
-  const resolvedSecretKey =
-    secretKey ??
-    process.env.CONSTRUCT_TELEMETRY_SECRET_KEY ??
-    '';
-
-  if (!resolvedPublicKey || !resolvedSecretKey || !resolvedBaseUrl) {
-    return { status: 'unconfigured' };
-  }
-
-  async function doVerify() {
-    const auth = `Basic ${Buffer.from(`${resolvedPublicKey}:${resolvedSecretKey}`).toString('base64')}`;
-    for (let attempt = 0; attempt < maxRetries; attempt++) {
-      try {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), 3000);
-        const res = await fetchFn(`${resolvedBaseUrl}/api/public/health`, {
-          signal: controller.signal,
-        }).finally(() => clearTimeout(timer));
-        if (res.ok) break;
-      } catch { /* not ready yet */ }
-      if (attempt < maxRetries - 1) await new Promise((r) => setTimeout(r, intervalMs));
-    }
-
-    try {
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), 5000);
-      const res = await fetchFn(`${resolvedBaseUrl}/api/public/traces?limit=1`, {
-        headers: { Authorization: auth },
-        signal: controller.signal,
-      }).finally(() => clearTimeout(timer));
-      if (res.ok) return { status: 'verified' };
-    } catch {
-      return { status: 'unreachable' };
-    }
-    return { status: 'auth-failed', reseeded: false };
-  }
-
-  if (overallTimeoutMs > 0) {
-    return Promise.race([
-      doVerify(),
-      new Promise((_, reject) =>
-        setTimeout(() => reject(new Error('verifyTelemetryKeys timeout')), overallTimeoutMs),
-      ),
-    ]);
-  }
-  return doVerify();
-}
-
-/**
- * Bring up the local Postgres service via services/docker-compose.yml.
- * Starts the local Postgres service via services/docker-compose.yml.
- */
-export async function startManagedServices({
-  rootDir,
-  homeDir = os.homedir(),
-  env = process.env,
-  composeRunner,
-  spawnDetached,
-} = {}) {
-  if (!rootDir) throw new Error('startManagedServices: rootDir is required');
-  if (!composeRunner) throw new Error('startManagedServices: composeRunner is required');
-  if (!spawnDetached) throw new Error('startManagedServices: spawnDetached is required');
-
-  const composeFile = servicesComposePath(rootDir);
-  if (!fs.existsSync(composeFile)) {
-    return { status: 'unavailable', note: `services compose file missing at ${composeFile}` };
-  }
-
-  const { logPath } = spawnDetached(
-    composeRunner.command,
-    [...composeRunner.argsPrefix, '-p', 'construct-services', '-f', composeFile, 'up', '-d'],
-    homeDir,
-    'services.log',
-  );
-
-  return {
-    status: 'started',
-    note: `Postgres started — connect at localhost:${POSTGRES_LOCAL_PORT}`,
-    composeFile,
-    logPath,
-  };
-}
-

package/lib/storage/fusion.mjs

@@ -1,95 +0,0 @@
-/**
- * lib/storage/fusion.mjs — score fusion for hybrid retrieval.
- *
- * Exposes two fusion strategies for combining ranked results from
- * multiple retrieval signals (lexical, vector, metadata, recency):
- *
- *   fuseScores({ vector, lexical, metadata, recency }, weights)
- *     — weighted linear combination, returns the final score and
- *       component scores so callers can debug retrieval drift.
- *
- *   reciprocalRankFusion(rankedLists, { k })
- *     — RRF: finalScore = Σ 1 / (k + rank_i) for each list a doc appears in.
- *       Order-insensitive across lists; robust to score-scale mismatch
- *       between lexical (BM25) and vector (cosine) backends.
- *
- * Default weights match the source plan: vector 0.45, lexical 0.35,
- * metadata 0.15, recency 0.05. Callers override per-query when needed
- * (e.g. weight metadata higher for filter-driven queries).
- */
-
-export const DEFAULT_WEIGHTS = Object.freeze({
-  vector: 0.45,
-  lexical: 0.35,
-  metadata: 0.15,
-  recency: 0.05,
-});
-
-function clamp01(value) {
-  if (!Number.isFinite(value)) return 0;
-  if (value < 0) return 0;
-  if (value > 1) return 1;
-  return value;
-}
-
-/**
- * Compute a fused score from component signals.
- *
- * @param {object} components
- * @param {number} [components.vector]    cosine similarity in [0, 1]
- * @param {number} [components.lexical]   normalized lexical score in [0, 1]
- * @param {number} [components.metadata]  metadata-match score in [0, 1]
- * @param {number} [components.recency]   freshness score in [0, 1]
- * @param {object} [weights]
- * @returns {{ vector, lexical, metadata, recency, finalScore, weights }}
- */
-export function fuseScores(components = {}, weights = DEFAULT_WEIGHTS) {
-  const v = clamp01(components.vector);
-  const l = clamp01(components.lexical);
-  const m = clamp01(components.metadata);
-  const r = clamp01(components.recency);
-  const w = { ...DEFAULT_WEIGHTS, ...weights };
-  const finalScore = clamp01(v * w.vector + l * w.lexical + m * w.metadata + r * w.recency);
-  return { vector: v, lexical: l, metadata: m, recency: r, finalScore, weights: w };
-}
-
-/**
- * Reciprocal Rank Fusion across N ranked lists. Each list is an array
- * of `{ id, ... }` objects ordered by descending relevance.
- *
- * @param {Array<Array<object>>} rankedLists
- * @param {object} [opts]
- * @param {number} [opts.k=60]
- * @returns {Array<{ id, rrfScore, appearsIn: number }>}
- */
-export function reciprocalRankFusion(rankedLists, { k = 60 } = {}) {
-  if (!Array.isArray(rankedLists) || rankedLists.length === 0) return [];
-  const scores = new Map();
-  for (const list of rankedLists) {
-    if (!Array.isArray(list)) continue;
-    list.forEach((item, idx) => {
-      if (!item?.id) return;
-      const rrf = 1 / (k + idx + 1);
-      const prev = scores.get(item.id) || { id: item.id, rrfScore: 0, appearsIn: 0 };
-      prev.rrfScore += rrf;
-      prev.appearsIn += 1;
-      scores.set(item.id, prev);
-    });
-  }
-  return [...scores.values()].sort((a, b) => b.rrfScore - a.rrfScore);
-}
-
-/**
- * Compute a normalized recency score in [0, 1] given a timestamp and
- * a half-life in days. A doc updated today scores ~1, a doc older than
- * 4× the half-life scores near 0.
- */
-export function recencyScore(updatedAt, { halfLifeDays = 30, now = Date.now() } = {}) {
-  if (!updatedAt) return 0;
-  const ts = updatedAt instanceof Date ? updatedAt.getTime() : Date.parse(updatedAt);
-  if (!Number.isFinite(ts)) return 0;
-  const ageMs = Math.max(0, now - ts);
-  const halfLifeMs = halfLifeDays * 24 * 60 * 60 * 1000;
-  if (halfLifeMs <= 0) return 0;
-  return clamp01(Math.pow(0.5, ageMs / halfLifeMs));
-}