@geraldmaron/construct 1.0.7 → 1.0.8

package/lib/scheduler/index.mjs

@@ -0,0 +1,112 @@
+/**
+ * lib/scheduler/index.mjs — deployment-topology-aware background job scheduler.
+ *
+ * Three modes:
+ *   solo        — native platform triggers (launchd/systemd/Task Scheduler) via lib/scheduler/solo.mjs
+ *   team/enterprise — Postgres advisory lock runner via lib/scheduler/postgres.mjs
+ *   one-shot    — run handler synchronously and exit (for CI)
+ *
+ * Jobs registered here: 'tag-candidate-mining', 'skill-usage-rollup', 'doc-hygiene-scan'
+ *
+ * Deployment mode is determined by getDeploymentMode(env), which inspects env vars.
+ * Registration is in-memory: no persistence across process restarts beyond the
+ * native trigger files written by solo.mjs or the DB rows in 009_scheduler.sql.
+ */
+
+// ---------------------------------------------------------------------------
+// In-memory job registry
+// ---------------------------------------------------------------------------
+
+const jobRegistry = new Map();
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Registers a job definition in memory. Overwrites any prior registration
+ * with the same id.
+ *
+ * @param {object} opts
+ *   id            {string}   - Unique job identifier
+ *   schedule      {string}   - Cron expression or interval string
+ *   mode          {string}   - 'solo' | 'team' | 'enterprise' | 'one-shot'
+ *   handler       {Function} - Async function ({ cwd, env }) => result
+ *   leaderLockKey {string}   - Postgres advisory lock key (team/enterprise only)
+ */
+export function registerJob({ id, schedule, mode, handler, leaderLockKey = null }) {
+  jobRegistry.set(id, { id, schedule, mode, handler, leaderLockKey, registeredAt: new Date().toISOString() });
+}
+
+/**
+ * Runs the handler for the given job id synchronously in the current process.
+ * Returns the handler's result. Throws if the job id is not registered.
+ */
+export async function runJobOnce(id, { cwd = process.cwd(), env = process.env } = {}) {
+  const job = jobRegistry.get(id);
+  if (!job) throw new Error(`job not registered: ${id}`);
+  return job.handler({ cwd, env });
+}
+
+/**
+ * Returns an array of all registered job definitions (handler excluded for safety).
+ */
+export function listJobs() {
+  return Array.from(jobRegistry.values()).map(({ id, schedule, mode, leaderLockKey, registeredAt }) => ({
+    id, schedule, mode, leaderLockKey, registeredAt,
+  }));
+}
+
+/**
+ * Derives the deployment mode from environment variables.
+ * Returns 'enterprise' | 'team' | 'solo'.
+ *
+ * CONSTRUCT_DEPLOYMENT=enterprise or CONSTRUCT_ENTERPRISE=1 => enterprise
+ * CONSTRUCT_DEPLOYMENT=team or CONSTRUCT_TEAM=1             => team
+ * Otherwise                                                  => solo
+ */
+export function getDeploymentMode(env = process.env) {
+  const explicit = env.CONSTRUCT_DEPLOYMENT;
+  if (explicit === 'enterprise' || env.CONSTRUCT_ENTERPRISE === '1') return 'enterprise';
+  if (explicit === 'team' || env.CONSTRUCT_TEAM === '1') return 'team';
+  if (explicit === 'solo') return 'solo';
+  return 'solo';
+}
+
+// ---------------------------------------------------------------------------
+// Built-in job registrations
+// ---------------------------------------------------------------------------
+
+registerJob({
+  id: 'tag-candidate-mining',
+  schedule: '0 3 * * *',
+  mode: 'solo',
+  handler: async ({ cwd, env }) => {
+    const { default: run } = await import('../../scripts/tag-candidate-mining.mjs');
+    return run({ cwd, env });
+  },
+});
+
+registerJob({
+  id: 'skill-usage-rollup',
+  schedule: '0 4 * * 1',
+  mode: 'solo',
+  handler: async () => ({ status: 'noop', reason: 'not yet implemented' }),
+});
+
+registerJob({
+  id: 'doc-hygiene-scan',
+  schedule: '0 2 * * *',
+  mode: 'solo',
+  handler: async ({ cwd, env }) => {
+    const { findHygieneCandidates } = await import('../hygiene/scan.mjs');
+    const mode = getDeploymentMode(env);
+    const limit = mode === 'solo' ? 25 : 50;
+    const candidates = findHygieneCandidates({ cwd, limit });
+    return {
+      status: 'ok',
+      candidates: candidates.length,
+      items: candidates.map((c) => ({ rel: c.rel, reason: c.reason, ageDays: c.ageDays })),
+    };
+  },
+});

package/lib/scheduler/solo.mjs

@@ -0,0 +1,183 @@
+/**
+ * lib/scheduler/solo.mjs — native platform trigger management for solo deployment mode.
+ *
+ * Detects the current platform (darwin/linux/win32) and writes the appropriate
+ * trigger file so the OS scheduler runs the job without a long-lived Construct
+ * daemon.
+ *
+ * darwin  — launchd plist at ~/Library/LaunchAgents/com.construct.job.<id>.plist
+ * linux   — systemd timer unit at ~/.config/systemd/user/construct-<id>.timer
+ *           (plus a matching .service unit at the same path)
+ * win32   — no-op with a descriptive message (Task Scheduler XML generation
+ *           is deferred; Windows support is tracked separately)
+ *
+ * The schedule parameter is a cron expression (5-field).
+ * launchd uses StartCalendarInterval derived from the cron fields.
+ * systemd uses OnCalendar= translated from the cron expression.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// ---------------------------------------------------------------------------
+// Cron parsing helpers — minimal support for standard 5-field cron
+// ---------------------------------------------------------------------------
+
+function parseCron(schedule) {
+  const parts = schedule.trim().split(/\s+/);
+  if (parts.length !== 5) throw new Error(`unsupported cron expression (need 5 fields): ${schedule}`);
+  const [minute, hour, dom, month, dow] = parts;
+  return { minute, hour, dom, month, dow };
+}
+
+function cronToLaunchdCalendar(schedule) {
+  const { minute, hour, dom, month, dow } = parseCron(schedule);
+  const items = [];
+  if (minute !== '*') items.push(`        <key>Minute</key><integer>${minute}</integer>`);
+  if (hour !== '*') items.push(`        <key>Hour</key><integer>${hour}</integer>`);
+  if (dom !== '*') items.push(`        <key>Day</key><integer>${dom}</integer>`);
+  if (month !== '*') items.push(`        <key>Month</key><integer>${month}</integer>`);
+  if (dow !== '*') items.push(`        <key>Weekday</key><integer>${dow}</integer>`);
+  return items.join('\n');
+}
+
+function cronToSystemdOnCalendar(schedule) {
+  const { minute, hour, dom, month, dow } = parseCron(schedule);
+  const dayOfWeek = dow === '*' ? '*' : dow;
+  const d = dom === '*' ? '*' : dom;
+  const m = month === '*' ? '*' : `*-${month}`;
+  const time = `${hour === '*' ? '*' : hour.padStart(2,'0')}:${minute === '*' ? '*' : minute.padStart(2,'0')}:00`;
+  return `${dayOfWeek} ${m}-${d} ${time}`;
+}
+
+// ---------------------------------------------------------------------------
+// Platform-specific trigger writers
+// ---------------------------------------------------------------------------
+
+function writeLaunchdPlist(id, schedule, cwd) {
+  const label = `com.construct.job.${id}`;
+  const plistDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+  const plistPath = path.join(plistDir, `${label}.plist`);
+  const constructBin = path.join(cwd, 'bin', 'construct');
+  const calendarEntries = cronToLaunchdCalendar(schedule);
+
+  const content = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${label}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${constructBin}</string>
+        <string>scheduler</string>
+        <string>run</string>
+        <string>${id}</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${cwd}</string>
+    <key>StartCalendarInterval</key>
+    <dict>
+${calendarEntries}
+    </dict>
+    <key>StandardOutPath</key>
+    <string>${path.join(os.homedir(), '.cx', 'scheduler', 'logs', `${id}.stdout.log`)}</string>
+    <key>StandardErrorPath</key>
+    <string>${path.join(os.homedir(), '.cx', 'scheduler', 'logs', `${id}.stderr.log`)}</string>
+    <key>RunAtLoad</key>
+    <false/>
+</dict>
+</plist>
+`;
+  fs.mkdirSync(plistDir, { recursive: true });
+  fs.writeFileSync(plistPath, content, 'utf8');
+  return plistPath;
+}
+
+function writeSystemdUnits(id, schedule, cwd) {
+  const unitDir = path.join(os.homedir(), '.config', 'systemd', 'user');
+  const timerPath = path.join(unitDir, `construct-${id}.timer`);
+  const servicePath = path.join(unitDir, `construct-${id}.service`);
+  const constructBin = path.join(cwd, 'bin', 'construct');
+  const onCalendar = cronToSystemdOnCalendar(schedule);
+
+  const timerContent = `[Unit]
+Description=Construct job scheduler: ${id}
+
+[Timer]
+OnCalendar=${onCalendar}
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+`;
+
+  const serviceContent = `[Unit]
+Description=Construct job: ${id}
+
+[Service]
+Type=oneshot
+WorkingDirectory=${cwd}
+ExecStart=${constructBin} scheduler run ${id}
+StandardOutput=append:${path.join(os.homedir(), '.cx', 'scheduler', 'logs', `${id}.stdout.log`)}
+StandardError=append:${path.join(os.homedir(), '.cx', 'scheduler', 'logs', `${id}.stderr.log`)}
+`;
+
+  fs.mkdirSync(unitDir, { recursive: true });
+  fs.writeFileSync(timerPath, timerContent, 'utf8');
+  fs.writeFileSync(servicePath, serviceContent, 'utf8');
+  return timerPath;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Detects the current platform and writes the appropriate native trigger file.
+ * Returns { platform, triggerPath, installed: boolean }.
+ *
+ * On win32, installed is false and triggerPath is null (deferred support).
+ */
+export function registerNativeTrigger({ id, schedule, cwd = process.cwd() }) {
+  const platform = process.platform;
+
+  if (platform === 'darwin') {
+    const triggerPath = writeLaunchdPlist(id, schedule, cwd);
+    return { platform, triggerPath, installed: true };
+  }
+
+  if (platform === 'linux') {
+    const triggerPath = writeSystemdUnits(id, schedule, cwd);
+    return { platform, triggerPath, installed: true };
+  }
+
+  return { platform, triggerPath: null, installed: false };
+}
+
+/**
+ * Removes the native trigger file(s) for the given job id.
+ * Silently ignores missing files.
+ */
+export function removeNativeTrigger({ id }) {
+  const platform = process.platform;
+
+  if (platform === 'darwin') {
+    const label = `com.construct.job.${id}`;
+    const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+    if (fs.existsSync(plistPath)) fs.unlinkSync(plistPath);
+    return { platform, removed: plistPath };
+  }
+
+  if (platform === 'linux') {
+    const unitDir = path.join(os.homedir(), '.config', 'systemd', 'user');
+    const timerPath = path.join(unitDir, `construct-${id}.timer`);
+    const servicePath = path.join(unitDir, `construct-${id}.service`);
+    if (fs.existsSync(timerPath)) fs.unlinkSync(timerPath);
+    if (fs.existsSync(servicePath)) fs.unlinkSync(servicePath);
+    return { platform, removed: timerPath };
+  }
+
+  return { platform, removed: null };
+}

package/lib/server/index.mjs

@@ -693,6 +693,12 @@ const server = createServer(async (req, res) => {
     return;
   }
 
+  if (url.pathname === '/api/services/langfuse/login' && req.method === 'GET') {
+    const { handleLangfuseLogin } = await import('./langfuse-login.mjs');
+    await handleLangfuseLogin(req, res);
+    return;
+  }
+
   if (url.pathname === '/api/status') {
     try {
       const status = await buildStatus();
@@ -2174,7 +2180,7 @@ watchFiles();
 // to keep the knowledge base current without manual intervention.
 // Override interval via CX_EMBED_INTERVAL_MS (default: 30 minutes).
 function runEmbedSync() {
-  const syncScript = join(ROOT_DIR, 'scripts', 'sync-agents.mjs');
+  const syncScript = join(ROOT_DIR, 'scripts', 'sync-specialists.mjs');
   if (!existsSync(syncScript)) return;
   try {
     spawnSync(process.execPath, [syncScript], {

package/lib/server/insights.mjs

@@ -47,9 +47,11 @@ async function fetchTelemetrySummary(env, { limit = 100 } = {}) {
       if (!res.ok) return { state: 'unreachable', message: `Telemetry HTTP ${res.status}` };
       const json = await res.json();
       const traces = Array.isArray(json.data) ? json.data : [];
-      let totalCost = 0; let observations = 0; const byModel = new Map(); let withError = 0; let withInput = 0; let withOutput = 0;
+      // Cost figures are intentionally absent from the user-facing summary.
+      // The underlying telemetry trace data still carries totalCost; that
+      // surfaces via the OTel + dashboard wiring planned in Workstream J.
+      let observations = 0; const byModel = new Map(); let withError = 0; let withInput = 0; let withOutput = 0;
       for (const trace of traces) {
-        totalCost += Number(trace?.totalCost) || 0;
         observations += Number(trace?.observationCount) || 0;
         if (trace?.input != null) withInput += 1;
         if (trace?.output != null) withOutput += 1;
@@ -59,16 +61,16 @@ async function fetchTelemetrySummary(env, { limit = 100 } = {}) {
           trace?.output?.model || trace?.output?.costModel || trace?.input?.metadata?.model ||
           (Array.isArray(trace?.observations) ? trace.observations.find((o) => o?.model)?.model : null) || null;
         if (!model) continue;
-        const prior = byModel.get(model) || { traces: 0, cost: 0 };
-        prior.traces += 1; prior.cost += Number(trace?.totalCost) || 0;
+        const prior = byModel.get(model) || { traces: 0 };
+        prior.traces += 1;
         byModel.set(model, prior);
       }
       return {
         state: traces.length === 0 ? 'empty' : 'ok',
         baseUrl, sampleSize: traces.length,
-        totalCostUsd: Number(totalCost.toFixed(4)), observations, withInput, withOutput, withError,
-        topModels: [...byModel.entries()].map(([model, v]) => ({ model, traces: v.traces, cost: Number(v.cost.toFixed(6)) }))
-          .sort((a, b) => b.cost - a.cost || b.traces - a.traces).slice(0, 5),
+        observations, withInput, withOutput, withError,
+        topModels: [...byModel.entries()].map(([model, v]) => ({ model, traces: v.traces }))
+          .sort((a, b) => b.traces - a.traces).slice(0, 5),
       };
     } catch (err) {
       clearTimeout(timer);
@@ -727,11 +729,13 @@ export async function buildInsights({ env = process.env, cwd = process.cwd(), ro
   } catch (err) {
     handoffs = { state: 'unreachable', message: err.message };
   }
-  const [telemetry, telemetryTrend, telemetryLatency, cost, intake, beads, recommendations, integrations] = await Promise.all([
+  // Cost-ledger and telemetry-cost-trend summaries are intentionally omitted
+  // from the dashboard payload. Underlying ledger writes + telemetry traces
+  // continue; the consumer surface lands with the OTel + dashboard wiring
+  // (plan Workstream J).
+  const [telemetry, telemetryLatency, intake, beads, recommendations, integrations] = await Promise.all([
     fetchTelemetrySummary(env),
-    summarizeTelemetryCostTrend(env),
     summarizeTelemetryLatency(env),
-    summarizeCostLedger(env),
     Promise.resolve(summarizeIntakeQueue(env, cwd)),
     Promise.resolve(summarizeBeads(rootDir)),
     summarizeRecommendations(),
@@ -747,9 +751,7 @@ export async function buildInsights({ env = process.env, cwd = process.cwd(), ro
   } catch { sessionUsage = null; }
   return {
     telemetry,
-    telemetryTrend,
     telemetryLatency,
-    cost,
     intake,
     recommendations,
     integrations,

package/lib/server/langfuse-login.mjs

@@ -0,0 +1,58 @@
+/**
+ * lib/server/langfuse-login.mjs — Magic-link bridge for local Langfuse.
+ *
+ * `construct up` seeds Langfuse with deterministic admin creds via the
+ * LANGFUSE_INIT_* env vars in langfuse/docker-compose.yml. This bridge turns
+ * the "Open Langfuse" link in the dashboard into a one-click sign-in: the
+ * server fetches a CSRF token from local Langfuse, then returns an HTML
+ * auto-submit form that POSTs the seeded credentials to NextAuth's callback.
+ * The browser receives Langfuse's session cookie on localhost:3000 directly,
+ * sidestepping cross-origin restrictions.
+ *
+ * The seeded creds are NOT secret — they are deterministic local defaults
+ * declared in the public compose file. Their only job is to make local
+ * Langfuse zero-touch.
+ */
+import { LANGFUSE_LOCAL } from '../service-manager.mjs';
+
+const HTML_HEADERS = { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' };
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (c) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  })[c]);
+}
+
+export async function handleLangfuseLogin(req, res, { baseUrl = LANGFUSE_LOCAL.baseUrl, email = LANGFUSE_LOCAL.email, pwd = LANGFUSE_LOCAL.pwd } = {}) {
+  try {
+    const csrfResponse = await fetch(`${baseUrl}/api/auth/csrf`, { headers: { Accept: 'application/json' } });
+    if (!csrfResponse.ok) {
+      res.writeHead(502, HTML_HEADERS);
+      res.end(`<!doctype html><meta charset="utf-8"><title>Langfuse unreachable</title><pre>Could not reach local Langfuse at ${escapeHtml(baseUrl)}. Status: ${csrfResponse.status}. Try \`construct up\` first.</pre>`);
+      return;
+    }
+    const { csrfToken } = await csrfResponse.json();
+
+    const callbackUrl = `${baseUrl}/api/auth/callback/credentials`;
+    const redirectAfter = `${baseUrl}/`;
+
+    res.writeHead(200, HTML_HEADERS);
+    res.end(`<!doctype html>
+<html><head><meta charset="utf-8"><title>Signing in to Langfuse…</title>
+<style>body{font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;color:#666;background:#fff}</style>
+</head><body>
+<p>Signing you in to Langfuse…</p>
+<form id="lf" method="POST" action="${escapeHtml(callbackUrl)}">
+<input type="hidden" name="csrfToken" value="${escapeHtml(csrfToken)}">
+<input type="hidden" name="email" value="${escapeHtml(email)}">
+<input type="hidden" name="password" value="${escapeHtml(pwd)}">
+<input type="hidden" name="callbackUrl" value="${escapeHtml(redirectAfter)}">
+<input type="hidden" name="json" value="false">
+</form>
+<script>document.getElementById('lf').submit();</script>
+</body></html>`);
+  } catch (err) {
+    res.writeHead(502, HTML_HEADERS);
+    res.end(`<!doctype html><meta charset="utf-8"><title>Langfuse unreachable</title><pre>Could not reach local Langfuse: ${escapeHtml(err?.message || 'unknown error')}. Try \`construct up\` first.</pre>`);
+  }
+}