@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/doctor/watchers/handoffs.mjs

@@ -0,0 +1,33 @@
+/**
+ * lib/doctor/watchers/handoffs.mjs — periodic handoff cleanup tick.
+ *
+ * Runs `autoCleanHandoffs` against the project root on a 30-min schedule.
+ * Resolved handoffs older than `handoffsMaxDays` move to .cx/handoffs/archive/;
+ * archived handoffs older than 2× retention get deleted. Live handoffs are
+ * never touched — open work is sacred. Each tick records a one-line audit
+ * entry so the doctor log shows what was done and why.
+ */
+
+import { record } from '../audit.mjs';
+import { autoCleanHandoffs } from '../../handoffs/cleanup.mjs';
+
+export const name = 'handoffs';
+export const intervalMs = 30 * 60 * 1000;
+
+export async function tick() {
+  try {
+    const { result } = autoCleanHandoffs(process.cwd(), process.env);
+    if (result.moved.length === 0 && result.deleted.length === 0 && (result.warnings || []).length === 0) {
+      return;
+    }
+    record({
+      watcher: name,
+      event: 'cleanup',
+      moved: result.moved.map((a) => ({ from: a.from, to: a.to, bytes: a.bytes, reason: a.reason })),
+      deleted: result.deleted.map((a) => ({ path: a.path, bytes: a.bytes, reason: a.reason })),
+      warnings: result.warnings || [],
+    });
+  } catch (err) {
+    record({ watcher: name, event: 'error', message: err?.message || 'unknown' });
+  }
+}

package/lib/doctor/watchers/process-pressure.mjs

@@ -0,0 +1,60 @@
+/**
+ * lib/doctor/watchers/process-pressure.mjs — continuous process pressure guard.
+ *
+ * Runs the runtime-pressure cleanup on a recurring tick so stale Construct
+ * helpers don't accumulate between `construct up` invocations. Any killed
+ * process is recorded; if the same service-class has been killed >=2 times
+ * in the last hour, escalates so cx-sre can investigate the underlying churn.
+ *
+ * Tick: 60s.
+ */
+
+import { record, recent } from '../audit.mjs';
+import { escalate } from '../escalate.mjs';
+import { runPressureRelease } from '../../runtime-pressure.mjs';
+
+export const name = 'process-pressure';
+export const intervalMs = 60 * 1000;
+
+export async function tick() {
+  const actions = [];
+  const escalations = [];
+
+  const report = runPressureRelease({ env: process.env });
+
+  if (Array.isArray(report?.killed) && report.killed.length > 0) {
+    for (const proc of report.killed) {
+      record({
+        kind: 'action',
+        watcher: name,
+        action: 'kill',
+        target: proc.command || proc.pid || 'unknown',
+        summary: `killed stale process ${proc.command || ''} (pid ${proc.pid || '?'}, ${proc.reason || 'pressure rule'})`,
+        context: proc,
+      });
+      actions.push({ type: 'kill', target: proc.command || proc.pid });
+    }
+
+    const hourAgo = Date.now() - 60 * 60 * 1000;
+    const recentKills = recent({ watcher: name, kind: 'action', since: hourAgo, limit: 50 })
+      .filter((e) => e.action === 'kill');
+    const byClass = {};
+    for (const k of recentKills) {
+      const cls = String(k.target || '').split(/[\s/]/)[0] || 'unknown';
+      byClass[cls] = (byClass[cls] || 0) + 1;
+    }
+    for (const [cls, count] of Object.entries(byClass)) {
+      if (count >= 2) {
+        const r = await escalate({
+          watcher: name,
+          eventType: 'service.down',
+          summary: `${cls} killed ${count} times in last hour — repeated pressure churn`,
+          context: { class: cls, killCount: count, report },
+        });
+        escalations.push({ eventType: 'service.down', class: cls, result: r });
+      }
+    }
+  }
+
+  return { actions, escalations, notes: [{ pressureTriggered: !!report?.pressureTriggered, killed: report?.killed?.length || 0 }] };
+}

package/lib/doctor/watchers/service-health.mjs

@@ -0,0 +1,188 @@
+/**
+ * lib/doctor/watchers/service-health.mjs — continuous service probes.
+ *
+ * Probes the services `construct up` starts (postgres, dashboard,
+ * cm, opencode). On 2 consecutive probe failures, attempts a restart of
+ * docker-backed services (postgres). On 2 consecutive failed
+ * restarts, escalates `service.down` for cx-sre. Non-docker services log +
+ * escalate after 3 consecutive failures — auto-restart needs original spawn
+ * args and is deferred to a follow-up.
+ *
+ * Tick: 60s.
+ */
+
+import { spawnSync, spawn } from 'node:child_process';
+import { existsSync, readFileSync, openSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { record } from '../audit.mjs';
+import { escalate } from '../escalate.mjs';
+
+export const name = 'service-health';
+export const intervalMs = 60 * 1000;
+
+const failureCounts = {};
+const restartAttempts = {};
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, '..', '..', '..');
+
+const services = [
+  {
+    id: 'postgres',
+    probe: () => probeTcp('127.0.0.1', 54329),
+    restart: () => dockerRestart('construct-postgres'),
+    restartable: true,
+  },
+  {
+    id: 'dashboard',
+    probe: () => probeDashboardPort(),
+    restart: () => respawnViaConstructUp('dashboard'),
+    restartable: true,
+  },
+  {
+    id: 'cm',
+    probe: () => probeMemoryHealth(),
+    restart: () => respawnCm(),
+    restartable: true,
+  },
+];
+
+function probeTcp(host, port, timeoutMs = 1500) {
+  const r = spawnSync('bash', ['-c', `(echo > /dev/tcp/${host}/${port}) 2>/dev/null`], { timeout: timeoutMs });
+  return r.status === 0;
+}
+
+function probeDashboardPort() {
+  const statePath = join(homedir(), '.construct', 'dashboard.json');
+  if (!existsSync(statePath)) return true;
+  try {
+    const state = JSON.parse(readFileSync(statePath, 'utf8'));
+    if (!state.port) return true;
+    return probeTcp('127.0.0.1', state.port);
+  } catch {
+    return true;
+  }
+}
+
+function probeMemoryHealth() {
+  const envPath = join(homedir(), '.construct', 'config.env');
+  if (!existsSync(envPath)) return true;
+  try {
+    const env = readFileSync(envPath, 'utf8');
+    const match = env.match(/MEMORY_PORT=(\d+)/);
+    if (!match) return true;
+    return probeTcp('127.0.0.1', parseInt(match[1], 10));
+  } catch {
+    return true;
+  }
+}
+
+function dockerRestart(container) {
+  const r = spawnSync('docker', ['restart', container], { encoding: 'utf8', timeout: 15000 });
+  return { ok: r.status === 0, stderr: r.stderr };
+}
+
+function detachSpawn(command, args, logName) {
+  try {
+    const runtimeDir = join(homedir(), '.construct', '.runtime');
+    if (!existsSync(runtimeDir)) mkdirSync(runtimeDir, { recursive: true });
+    const logPath = join(runtimeDir, logName);
+    const fd = openSync(logPath, 'a');
+    const child = spawn(command, args, { detached: true, stdio: ['ignore', fd, fd] });
+    child.unref();
+    return { ok: true, logPath };
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+}
+
+function respawnViaConstructUp() {
+  const bin = join(REPO_ROOT, 'bin', 'construct');
+  if (!existsSync(bin)) return { ok: false, error: 'bin/construct not found' };
+  return detachSpawn('node', [bin, 'up'], 'doctor-respawn-up.log');
+}
+
+function respawnCm() {
+  const envPath = join(homedir(), '.construct', 'config.env');
+  let port = '4231';
+  try {
+    if (existsSync(envPath)) {
+      const m = readFileSync(envPath, 'utf8').match(/MEMORY_PORT=(\d+)/);
+      if (m) port = m[1];
+    }
+  } catch { /* fall through */ }
+  return detachSpawn('cm', ['serve', '--port', port], 'cm-respawn.log');
+}
+
+export async function tick() {
+  const actions = [];
+  const escalations = [];
+  const samples = [];
+
+  for (const svc of services) {
+    let healthy = true;
+    try { healthy = await svc.probe(); } catch { healthy = false; }
+    samples.push({ id: svc.id, healthy });
+
+    if (healthy) {
+      if (failureCounts[svc.id]) {
+        record({
+          kind: 'recovery',
+          watcher: name,
+          target: svc.id,
+          summary: `${svc.id} recovered after ${failureCounts[svc.id]} consecutive probe failure(s)`,
+          context: { previousFailures: failureCounts[svc.id] },
+        });
+      }
+      failureCounts[svc.id] = 0;
+      restartAttempts[svc.id] = 0;
+      continue;
+    }
+
+    failureCounts[svc.id] = (failureCounts[svc.id] || 0) + 1;
+    record({
+      kind: 'sample',
+      watcher: name,
+      target: svc.id,
+      result: 'down',
+      summary: `${svc.id} probe failed (${failureCounts[svc.id]} consecutive)`,
+      context: { failureCount: failureCounts[svc.id] },
+    });
+
+    if (svc.restartable && failureCounts[svc.id] >= 2 && (restartAttempts[svc.id] || 0) < 2) {
+      const restart = svc.restart();
+      restartAttempts[svc.id] = (restartAttempts[svc.id] || 0) + 1;
+      record({
+        kind: 'action',
+        watcher: name,
+        action: 'restart',
+        target: svc.id,
+        result: restart.ok ? 'ok' : 'failed',
+        summary: `${svc.id} restart attempt ${restartAttempts[svc.id]} — ${restart.ok ? 'succeeded' : 'failed'}`,
+        context: restart,
+      });
+      actions.push({ type: 'restart', target: svc.id, ok: restart.ok });
+      if (restart.ok) failureCounts[svc.id] = 0;
+    }
+
+    const escalateThreshold = svc.restartable ? 2 : 3;
+    const restartFailures = restartAttempts[svc.id] || 0;
+    const shouldEscalate = svc.restartable
+      ? restartFailures >= 2 && failureCounts[svc.id] >= 2
+      : failureCounts[svc.id] >= escalateThreshold;
+    if (shouldEscalate) {
+      const r = await escalate({
+        watcher: name,
+        eventType: 'service.down',
+        summary: `${svc.id} down (${failureCounts[svc.id]} consecutive probes, ${restartFailures} restart attempt(s) failed)`,
+        context: { service: svc.id, failureCount: failureCounts[svc.id], restartAttempts: restartFailures },
+      });
+      escalations.push({ eventType: 'service.down', service: svc.id, result: r });
+    }
+  }
+
+  return { actions, escalations, notes: samples };
+}

package/lib/document-extract.mjs

@@ -0,0 +1,288 @@
+/**
+ * lib/document-extract.mjs — shared local document extraction for retrieval and MCP reads.
+ *
+ * Handles plain-text formats directly, XML/HTML via lightweight tag stripping,
+ * Office zip containers via unzip, and PDFs via pdftotext or macOS-native fallbacks.
+ * Also provides extractDocumentMetadata() for structured metadata (title, authors,
+ * dates, links) from source document frontmatter and content.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const UTF8_TEXT_EXTS = new Set([
+  '.md', '.txt', '.rst', '.adoc', '.json', '.yaml', '.yml', '.toml',
+  '.js', '.mjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.sh', '.bash',
+  '.html', '.css', '.csv', '.tsv', '.xml', '.env', '.env.example', '.conf', '.ini', '.tf', '.hcl',
+  '.sql', '.log',
+  '.vtt', '.srt', '.lrc', '.transcript',
+]);
+
+export const ZIP_DOCUMENT_EXTS = new Set(['.docx', '.xlsx', '.pptx', '.odt', '.ods']);
+export const RICH_TEXT_EXTS = new Set(['.doc', '.rtf']);
+export const MDLS_DOCUMENT_EXTS = new Set(['.xls', '.ppt', '.pages', '.numbers', '.key']);
+export const EXTRACTABLE_DOCUMENT_EXTS = new Set([
+  ...UTF8_TEXT_EXTS,
+  ...ZIP_DOCUMENT_EXTS,
+  ...RICH_TEXT_EXTS,
+  ...MDLS_DOCUMENT_EXTS,
+  '.pdf',
+]);
+
+function normalizeText(value) {
+  return String(value)
+    .replace(/\r\n/g, '\n')
+    .replace(/\u0000/g, '')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function decodeXmlEntities(value) {
+  return value
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, code) => String.fromCharCode(parseInt(code, 16)));
+}
+
+function stripMarkup(value) {
+  return normalizeText(
+    decodeXmlEntities(String(value))
+      .replace(/<w:tab\/>/g, '\t')
+      .replace(/<w:br\/>/g, '\n')
+      .replace(/<\/(?:w:p|text:p|table:table-row|tr|p|div|h\d)>/g, '\n')
+      .replace(/<\/(?:w:tc|table:table-cell|td)>/g, '\t')
+      .replace(/<[^>]+>/g, ' ')
+  );
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || `${command} failed`).trim());
+  }
+  return result.stdout;
+}
+
+function commandExists(command) {
+  const checker = process.platform === 'win32' ? 'where' : 'which';
+  return spawnSync(checker, [command], { stdio: 'ignore' }).status === 0;
+}
+
+function extractUtf8(filePath, extension) {
+  const raw = readFileSync(filePath, 'utf8');
+  const text = extension === '.html' || extension === '.xml'
+    ? stripMarkup(raw)
+    : normalizeText(raw);
+  return { text, method: 'utf8' };
+}
+
+function zipEntries(filePath) {
+  return run('unzip', ['-Z1', filePath]).split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+function unzipEntry(filePath, entryPath) {
+  return run('unzip', ['-p', filePath, entryPath]);
+}
+
+function extractZipDocument(filePath, extension) {
+  const entries = zipEntries(filePath);
+  let targets = [];
+
+  if (extension === '.docx') {
+    targets = entries.filter((entry) => entry === 'word/document.xml' || entry.startsWith('word/header') || entry.startsWith('word/footer'));
+  } else if (extension === '.xlsx') {
+    targets = entries.filter((entry) => entry === 'xl/sharedStrings.xml' || /^xl\/worksheets\/sheet\d+\.xml$/.test(entry));
+  } else if (extension === '.pptx') {
+    targets = entries.filter((entry) => /^ppt\/slides\/slide\d+\.xml$/.test(entry));
+  } else if (extension === '.odt' || extension === '.ods') {
+    targets = entries.filter((entry) => entry === 'content.xml');
+  }
+
+  if (targets.length === 0) throw new Error(`No readable document entries found for ${extension}`);
+
+  const text = normalizeText(targets.map((entry) => stripMarkup(unzipEntry(filePath, entry))).join('\n\n'));
+  return { text, method: 'zip-xml' };
+}
+
+function extractRichText(filePath) {
+  if (!commandExists('textutil')) {
+    throw new Error('textutil not available for rich-text extraction');
+  }
+  return {
+    text: normalizeText(run('textutil', ['-convert', 'txt', '-stdout', filePath])),
+    method: 'textutil',
+  };
+}
+
+function extractPdfWithPdftotext(filePath) {
+  return {
+    text: normalizeText(run('pdftotext', ['-layout', '-nopgbrk', filePath, '-'])),
+    method: 'pdftotext',
+  };
+}
+
+function extractPdfWithSwift(filePath) {
+  const script = `
+import Foundation
+import PDFKit
+
+let path = CommandLine.arguments[1]
+let url = URL(fileURLWithPath: path)
+guard let document = PDFDocument(url: url) else {
+  fputs("Unable to open PDF\\n", stderr)
+  exit(1)
+}
+print(document.string ?? "")
+`;
+  return {
+    text: normalizeText(run('swift', ['-e', script, filePath])),
+    method: 'swift-pdfkit',
+  };
+}
+
+function extractPdfWithMdls(filePath) {
+  const text = extractWithMdls(filePath);
+  return { text, method: 'mdls' };
+}
+
+function extractWithMdls(filePath) {
+  const text = normalizeText(run('mdls', ['-raw', '-name', 'kMDItemTextContent', filePath]));
+  if (!text || text === '(null)') throw new Error('Spotlight text extraction unavailable');
+  return text;
+}
+
+function extractPdf(filePath) {
+  if (commandExists('pdftotext')) return extractPdfWithPdftotext(filePath);
+  if (process.platform === 'darwin' && commandExists('swift')) {
+    try {
+      return extractPdfWithSwift(filePath);
+    } catch {
+      return extractPdfWithMdls(filePath);
+    }
+  }
+  if (process.platform === 'darwin' && commandExists('mdls')) return extractPdfWithMdls(filePath);
+  throw new Error('No PDF extraction backend available');
+}
+
+export function isExtractableDocumentPath(filePath) {
+  return EXTRACTABLE_DOCUMENT_EXTS.has(extname(filePath).toLowerCase());
+}
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+const URL_RE = /https?:\/\/[^\s)>\]"'`]+/g;
+const DATE_KEYS = ['date', 'created', 'created_at', 'updated', 'updated_at', 'published', 'last_modified'];
+const AUTHOR_KEYS = ['author', 'authors', 'by', 'contributor', 'contributors'];
+
+function parseFrontmatter(text) {
+  const match = text.match(FRONTMATTER_RE);
+  if (!match) return { fields: {}, body: text };
+  const fields = {};
+  for (const line of match[1].split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim().toLowerCase();
+    const val = line.slice(idx + 1).trim();
+    if (!key) continue;
+    if (val.startsWith('[') && val.endsWith(']')) {
+      fields[key] = val.slice(1, -1).split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    } else {
+      fields[key] = val.replace(/^["']|["']$/g, '');
+    }
+  }
+  return { fields, body: text.slice(match[0].length) };
+}
+
+function extractTitleFromBody(body, extension) {
+  if (['.md', '.mdx', '.rst', '.adoc'].includes(extension)) {
+    const h1 = body.match(/^#\s+(.+)/m);
+    if (h1) return h1[1].trim();
+  }
+  if (['.html', '.xml'].includes(extension)) {
+    const title = body.match(/<title[^>]*>([^<]+)<\/title>/i);
+    if (title) return normalizeText(title[1]);
+  }
+  return null;
+}
+
+export function extractDocumentMetadata(filePath) {
+  const resolvedPath = resolve(filePath);
+  if (!existsSync(resolvedPath)) return { error: 'file not found' };
+
+  const extension = extname(resolvedPath).toLowerCase();
+  const stat = statSync(resolvedPath);
+  const result = { filePath: resolvedPath, extension, title: null, frontmatter: {}, authors: [], dates: {}, links: [] };
+
+  if (!UTF8_TEXT_EXTS.has(extension)) {
+    result.title = basename(resolvedPath).replace(/\.[^.]+$/, '').replace(/[-_]+/g, ' ').trim();
+    result.dates.modified = new Date(stat.mtimeMs).toISOString();
+    result.dates.created = new Date(stat.birthtimeMs || stat.mtimeMs).toISOString();
+    return result;
+  }
+
+  const raw = readFileSync(resolvedPath, 'utf8');
+  const { fields, body } = parseFrontmatter(raw);
+  result.frontmatter = fields;
+
+  result.title = fields.title || extractTitleFromBody(body, extension) || basename(resolvedPath).replace(/\.[^.]+$/, '').replace(/[-_]+/g, ' ').trim();
+
+  for (const key of AUTHOR_KEYS) {
+    if (fields[key]) {
+      result.authors = Array.isArray(fields[key]) ? fields[key] : [fields[key]];
+      break;
+    }
+  }
+
+  for (const key of DATE_KEYS) {
+    if (fields[key]) result.dates[key] = fields[key];
+  }
+  if (!Object.keys(result.dates).length) {
+    result.dates.modified = new Date(stat.mtimeMs).toISOString();
+    result.dates.created = new Date(stat.birthtimeMs || stat.mtimeMs).toISOString();
+  }
+
+  const urls = body.match(URL_RE) || [];
+  result.links = [...new Set(urls)].slice(0, 100);
+
+  return result;
+}
+
+export function extractDocumentText(filePath, { maxChars = null } = {}) {
+  const resolvedPath = resolve(filePath);
+  if (!existsSync(resolvedPath)) throw new Error(`File not found: ${resolvedPath}`);
+
+  const extension = extname(resolvedPath).toLowerCase();
+  if (!EXTRACTABLE_DOCUMENT_EXTS.has(extension)) {
+    throw new Error(`Unsupported document type: ${extension || 'unknown'}`);
+  }
+
+  let extracted;
+  if (UTF8_TEXT_EXTS.has(extension)) extracted = extractUtf8(resolvedPath, extension);
+  else if (ZIP_DOCUMENT_EXTS.has(extension)) extracted = extractZipDocument(resolvedPath, extension);
+  else if (RICH_TEXT_EXTS.has(extension)) extracted = extractRichText(resolvedPath);
+  else if (MDLS_DOCUMENT_EXTS.has(extension) && process.platform === 'darwin' && commandExists('mdls')) extracted = { text: extractWithMdls(resolvedPath), method: 'mdls' };
+  else if (extension === '.pdf') extracted = extractPdf(resolvedPath);
+  else throw new Error(`Unsupported document type: ${extension || 'unknown'}`);
+
+  const text = extracted.text;
+  const limit = Number.isFinite(Number(maxChars)) && Number(maxChars) > 0
+    ? Math.min(Number(maxChars), 200_000)
+    : null;
+  const truncated = limit !== null && text.length > limit;
+
+  return {
+    filePath: resolvedPath,
+    extension,
+    extractionMethod: extracted.method,
+    text: truncated ? `${text.slice(0, limit)}\n` : text,
+    truncated,
+    characters: text.length,
+  };
+}