@geraldmaron/construct 1.1.0 → 1.1.1

package/lib/policy/unified-gates.mjs

@@ -1,96 +0,0 @@
-// lib/policy/unified-gates.mjs
-// Single policy declaration for all enforcement layers
-
-export const POLICIES = {
-  commentStyle: {
-    id: 'comment-style',
-    description: 'Comments must follow project standards',
-    layers: ['write', 'commit', 'ci'],
-    bypass: 'CONSTRUCT_SKIP_COMMENT_STYLE',
-    critical: false,
-  },
-  docCoupling: {
-    id: 'doc-coupling',
-    description: 'Code changes require documentation updates',
-    layers: ['commit', 'push'],
-    bypass: 'CONSTRUCT_SKIP_DOCS',
-    critical: false,
-  },
-  secretScan: {
-    id: 'secret-scan',
-    description: 'No secrets in committed code',
-    layers: ['commit', 'push', 'ci'],
-    bypass: 'CONSTRUCT_SKIP_SECRET_SCAN',
-    critical: true,
-  },
-  ciStatus: {
-    id: 'ci-status',
-    description: 'CI must be green before push',
-    layers: ['push', 'session-end'],
-    bypass: 'CONSTRUCT_SKIP_CI_CHECK',
-    critical: true,
-  },
-};
-
-export class UnifiedGateEngine {
-  constructor(options = {}) {
-    this.env = options.env || process.env;
-  }
-  
-  isBypassed(policyId) {
-    const policy = POLICIES[policyId];
-    if (!policy) return { bypassed: false };
-    
-    if (policy.bypass && this.env[policy.bypass] === '1') {
-      return { bypassed: true, envVar: policy.bypass };
-    }
-    
-    if (this.env.CONSTRUCT_SKIP_ALL_GATES === '1') {
-      return { bypassed: true, envVar: 'CONSTRUCT_SKIP_ALL_GATES' };
-    }
-    
-    return { bypassed: false };
-  }
-  
-  async evaluateLayer(layer, context = {}) {
-    const results = [];
-    
-    for (const [id, policy] of Object.entries(POLICIES)) {
-      if (policy.layers.includes(layer)) {
-        const bypass = this.isBypassed(id);
-        results.push({
-          policy: id,
-          passed: bypass.bypassed || true,
-          bypassed: bypass.bypassed,
-          bypassEnvVar: bypass.envVar,
-          critical: policy.critical,
-        });
-      }
-    }
-    
-    const failed = results.filter(r => !r.passed && r.critical);
-    
-    return {
-      layer,
-      passed: failed.length === 0,
-      canProceed: failed.length === 0,
-      results,
-      summary: `${results.filter(r => r.passed).length}/${results.length} passed`,
-    };
-  }
-}
-
-export async function checkGates(layer, context = {}, options = {}) {
-  const engine = new UnifiedGateEngine(options);
-  return await engine.evaluateLayer(layer, context);
-}
-
-export function listPolicies() {
-  return Object.entries(POLICIES).map(([id, policy]) => ({
-    id,
-    description: policy.description,
-    layers: policy.layers,
-    bypass: policy.bypass,
-    critical: policy.critical,
-  }));
-}

package/lib/profiles/validate-custom.mjs

@@ -1,114 +0,0 @@
-/**
- * lib/profiles/validate-custom.mjs — Schema validator for user-defined profiles.
- *
- * Custom profiles live at `<project>/.cx/profile.json` with `custom: true`.
- * They are validated on `construct sync` and via the pre-push gate. Rejected
- * profiles never get loaded; resolveActiveProfile falls back to the default
- * so a malformed escape-hatch file never breaks a project.
- *
- * Hard limits the validator enforces (kept in sync with schemas/profile.schema.json
- * and scripts/lint-profiles.mjs):
- *   - max 12 stages
- *   - max 24 intake types
- *   - max 80 roles per profile
- *   - max 12 departments per profile
- *   - max 20 roles per department
- *   - classificationTable path must stay inside .cx/ (no repo escapes)
- *
- * Rationale for each cap lives in docs/concepts/persona-research.md.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-
-const MAX_STAGES = 12;
-const MAX_INTAKE_TYPES = 24;
-const MAX_ROLES = 80;
-const MAX_DEPARTMENTS = 12;
-const MAX_ROLES_PER_DEPARTMENT = 20;
-
-/**
- * @returns {string[]} array of error strings; empty means valid.
- */
-export function validateCustomProfile(profile, { cwd } = {}) {
-  const errors = [];
-  if (!profile || typeof profile !== 'object') return ['profile is not an object'];
-  if (profile.custom !== true) errors.push('custom profiles must set custom: true');
-
-  if (!profile.id || !/^[a-z][a-z0-9-]{1,30}$/.test(profile.id)) {
-    errors.push('id must match ^[a-z][a-z0-9-]{1,30}$');
-  }
-  if (!profile.displayName || typeof profile.displayName !== 'string') {
-    errors.push('displayName is required');
-  }
-  if (!Array.isArray(profile.roles) || profile.roles.length === 0) {
-    errors.push('roles must be a non-empty array');
-  } else if (profile.roles.length > MAX_ROLES) {
-    errors.push(`roles exceeds max of ${MAX_ROLES}`);
-  }
-  if (!profile.intake || typeof profile.intake !== 'object') {
-    errors.push('intake is required');
-  } else {
-    if (!Array.isArray(profile.intake.types) || profile.intake.types.length === 0) {
-      errors.push('intake.types must be a non-empty array');
-    } else if (profile.intake.types.length > MAX_INTAKE_TYPES) {
-      errors.push(`intake.types exceeds max of ${MAX_INTAKE_TYPES}`);
-    }
-    if (!Array.isArray(profile.intake.stages) || profile.intake.stages.length === 0) {
-      errors.push('intake.stages must be a non-empty array');
-    } else if (profile.intake.stages.length > MAX_STAGES) {
-      errors.push(`intake.stages exceeds max of ${MAX_STAGES}`);
-    }
-    if (typeof profile.intake.classificationTable === 'string') {
-      const t = profile.intake.classificationTable;
-      if (path.isAbsolute(t)) {
-        errors.push('intake.classificationTable must be a relative path');
-      } else if (cwd && !t.startsWith('.cx/')) {
-        errors.push('intake.classificationTable must live under .cx/ for custom profiles');
-      }
-    }
-  }
-  if (profile.departments !== undefined) {
-    if (!Array.isArray(profile.departments)) {
-      errors.push('departments must be an array');
-    } else {
-      if (profile.departments.length > MAX_DEPARTMENTS) {
-        errors.push(`departments exceeds max of ${MAX_DEPARTMENTS}`);
-      }
-      for (const [i, dept] of profile.departments.entries()) {
-        if (!dept || typeof dept !== 'object') {
-          errors.push(`departments[${i}] must be an object`);
-          continue;
-        }
-        if (!dept.id || !/^[a-z][a-z0-9-]{1,40}$/.test(dept.id)) {
-          errors.push(`departments[${i}].id is missing or malformed`);
-        }
-        if (!dept.charter || dept.charter.length < 20) {
-          errors.push(`departments[${i}].charter must be at least 20 chars (mission statement, not a label)`);
-        }
-        if (!Array.isArray(dept.roles) || dept.roles.length === 0) {
-          errors.push(`departments[${i}].roles must be a non-empty array`);
-        } else if (dept.roles.length > MAX_ROLES_PER_DEPARTMENT) {
-          errors.push(`departments[${i}].roles exceeds max of ${MAX_ROLES_PER_DEPARTMENT}`);
-        }
-      }
-    }
-  }
-  return errors;
-}
-
-/**
- * Read and validate `<cwd>/.cx/profile.json`. Returns:
- *   { status: 'absent' }                 if the file does not exist
- *   { status: 'invalid', errors: [...] } if validation failed
- *   { status: 'ok', profile }            if the file is a valid custom profile
- */
-export function validateCustomProfileFile(cwd) {
-  const p = path.join(cwd, '.cx', 'profile.json');
-  if (!fs.existsSync(p)) return { status: 'absent' };
-  let raw;
-  try { raw = JSON.parse(fs.readFileSync(p, 'utf8')); }
-  catch (err) { return { status: 'invalid', errors: [`malformed JSON: ${err.message}`] }; }
-  const errors = validateCustomProfile(raw, { cwd });
-  if (errors.length > 0) return { status: 'invalid', errors };
-  return { status: 'ok', profile: raw };
-}

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));
-}