@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/runtime-pressure.mjs

@@ -0,0 +1,360 @@
+/**
+ * lib/runtime-pressure.mjs — Manage local memory-pressure guard defaults.
+ *
+ * Defines configurable thresholds for helper cleanup, emits environment
+ * values consumed by setup flows, and runs local diagnostics that back the
+ * guard verification tests.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const DEFAULTS = Object.freeze({
+  enabled: '1',
+  intervalSeconds: '300',
+  swapGb: '6',
+  maxOpencode: '6',
+  maxOpencodeAgeHours: '24',
+  opencodeWarnGraceMinutes: '15',
+  maxHelperAgeHours: '2',
+  maxCassIndexAgeHours: '8',
+});
+
+function parsePositiveInt(value, fallback) {
+  const parsed = Number.parseInt(String(value ?? ''), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function thresholdConfig(env = process.env) {
+  return {
+    enabled: String(env.CONSTRUCT_PRESSURE_GUARD_ENABLED ?? DEFAULTS.enabled) !== '0',
+    intervalSeconds: parsePositiveInt(env.CONSTRUCT_PRESSURE_GUARD_INTERVAL_SECONDS, Number(DEFAULTS.intervalSeconds)),
+    swapGb: parsePositiveInt(env.CONSTRUCT_PRESSURE_GUARD_SWAP_GB, Number(DEFAULTS.swapGb)),
+    maxOpencodeProcesses: parsePositiveInt(env.CONSTRUCT_PRESSURE_GUARD_MAX_OPENCODE, Number(DEFAULTS.maxOpencode)),
+    maxOpencodeAgeHours: parsePositiveInt(env.CONSTRUCT_PRESSURE_GUARD_MAX_OPENCODE_AGE_HOURS, Number(DEFAULTS.maxOpencodeAgeHours)),
+    opencodeWarnGraceMinutes: parsePositiveInt(
+      env.CONSTRUCT_PRESSURE_GUARD_OPENCODE_WARN_GRACE_MINUTES,
+      Number(DEFAULTS.opencodeWarnGraceMinutes),
+    ),
+    maxHelperAgeHours: parsePositiveInt(env.CONSTRUCT_PRESSURE_GUARD_MAX_HELPER_AGE_HOURS, Number(DEFAULTS.maxHelperAgeHours)),
+    maxCassIndexAgeHours: parsePositiveInt(env.CONSTRUCT_PRESSURE_GUARD_MAX_CASS_INDEX_AGE_HOURS, Number(DEFAULTS.maxCassIndexAgeHours)),
+  };
+}
+
+export function buildPressureGuardValues({ env = process.env } = {}) {
+  const config = thresholdConfig(env);
+  return {
+    CONSTRUCT_PRESSURE_GUARD_ENABLED: config.enabled ? '1' : '0',
+    CONSTRUCT_PRESSURE_GUARD_INTERVAL_SECONDS: String(config.intervalSeconds),
+    CONSTRUCT_PRESSURE_GUARD_SWAP_GB: String(config.swapGb),
+    CONSTRUCT_PRESSURE_GUARD_MAX_OPENCODE: String(config.maxOpencodeProcesses),
+    CONSTRUCT_PRESSURE_GUARD_MAX_OPENCODE_AGE_HOURS: String(config.maxOpencodeAgeHours),
+    CONSTRUCT_PRESSURE_GUARD_OPENCODE_WARN_GRACE_MINUTES: String(config.opencodeWarnGraceMinutes),
+    CONSTRUCT_PRESSURE_GUARD_MAX_HELPER_AGE_HOURS: String(config.maxHelperAgeHours),
+    CONSTRUCT_PRESSURE_GUARD_MAX_CASS_INDEX_AGE_HOURS: String(config.maxCassIndexAgeHours),
+  };
+}
+
+export function parseElapsedSeconds(input) {
+  const raw = String(input ?? '').trim();
+  if (!raw) return 0;
+  if (/^\d+$/.test(raw)) return Number(raw);
+  const daySplit = raw.split('-');
+  const clock = daySplit.pop();
+  const days = daySplit.length ? Number.parseInt(daySplit[0], 10) || 0 : 0;
+  const parts = clock.split(':').map((part) => Number.parseInt(part, 10) || 0);
+  if (parts.length === 2) return (days * 86400) + (parts[0] * 60) + parts[1];
+  if (parts.length === 3) return (days * 86400) + (parts[0] * 3600) + (parts[1] * 60) + parts[2];
+  return 0;
+}
+
+export function parseSwapUsage(output) {
+  const text = String(output ?? '');
+  const total = text.match(/total = ([0-9.]+)M/);
+  const used = text.match(/used = ([0-9.]+)M/);
+  const free = text.match(/free = ([0-9.]+)M/);
+  if (!total || !used || !free) return null;
+  const toBytes = (value) => Math.round(Number.parseFloat(value) * 1024 * 1024);
+  return {
+    totalBytes: toBytes(total[1]),
+    usedBytes: toBytes(used[1]),
+    freeBytes: toBytes(free[1]),
+  };
+}
+
+function isOpencodeCommand(command) {
+  return /^opencode(?:\s|$)/.test(command);
+}
+
+function isHelperCommand(command) {
+  return /(context7-mcp|playwright-mcp|mcp-server-sequential-thinking)/.test(command);
+}
+
+function isCassIndexCommand(command) {
+  return /\bcass index\b/.test(command);
+}
+
+function summarizeTermination(entries) {
+  if (!entries.length) return 'No stale dev-agent processes matched the current policy.';
+  return `Pressure guard selected ${entries.length} processes for cleanup.`;
+}
+
+function warningStatePath(env = process.env) {
+  const homeDir = env.HOME || os.homedir();
+  return path.join(homeDir, '.construct', 'runtime', 'process-pressure-warnings.json');
+}
+
+function readWarningState(env = process.env) {
+  const statePath = warningStatePath(env);
+  try {
+    const raw = fs.readFileSync(statePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeWarningState(entries, env = process.env) {
+  const statePath = warningStatePath(env);
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(statePath, `${JSON.stringify(entries, null, 2)}\n`);
+}
+
+function warningKey(entry) {
+  return `${entry.reason}:${entry.pid}`;
+}
+
+export function buildCleanupPlan(processEntries = [], thresholds = {}) {
+  const maxOpencodeProcesses = thresholds.maxOpencodeProcesses ?? 2;
+  const maxOpencodeAgeSeconds = (thresholds.maxOpencodeAgeHours ?? 24) * 3600;
+  const maxHelperAgeSeconds = (thresholds.maxHelperAgeHours ?? 2) * 3600;
+  const maxCassIndexAgeSeconds = (thresholds.maxCassIndexAgeHours ?? 8) * 3600;
+
+  const terminate = [];
+  const seen = new Set();
+
+  const opencode = processEntries.filter((entry) => isOpencodeCommand(entry.command));
+  const staleOpencode = opencode
+    .filter((entry) => entry.elapsedSeconds >= maxOpencodeAgeSeconds)
+    .sort((a, b) => b.elapsedSeconds - a.elapsedSeconds);
+  for (const entry of staleOpencode) {
+    if (!seen.has(entry.pid)) {
+      seen.add(entry.pid);
+      terminate.push({ ...entry, reason: 'stale-opencode', warnFirst: true });
+    }
+  }
+  const duplicateOpencode = opencode
+    .slice()
+    .sort((a, b) => b.elapsedSeconds - a.elapsedSeconds)
+    .slice(Math.max(0, maxOpencodeProcesses));
+  for (const entry of duplicateOpencode) {
+    if (!seen.has(entry.pid)) {
+      seen.add(entry.pid);
+      terminate.push({ ...entry, reason: 'duplicate-opencode', warnFirst: true });
+    }
+  }
+
+  const helpers = processEntries
+    .filter((entry) => isHelperCommand(entry.command) && entry.elapsedSeconds >= maxHelperAgeSeconds)
+    .sort((a, b) => b.elapsedSeconds - a.elapsedSeconds);
+  for (const entry of helpers) {
+    if (!seen.has(entry.pid)) {
+      seen.add(entry.pid);
+      terminate.push({ ...entry, reason: 'stale-helper' });
+    }
+  }
+
+  const cassCandidates = processEntries
+    .filter((entry) => isCassIndexCommand(entry.command) && entry.elapsedSeconds >= maxCassIndexAgeSeconds)
+    .sort((a, b) => b.elapsedSeconds - a.elapsedSeconds)
+    .map((entry) => ({ ...entry, reason: 'stale-cass-index' }));
+
+  return {
+    terminate,
+    cassCandidates,
+    summary: summarizeTermination(terminate),
+  };
+}
+
+function parsePsLine(line) {
+  const match = line.match(/^\s*(\d+)\s+(\d+)\s+([0-9:-]+)\s+(.*)$/);
+  if (!match) return null;
+  return {
+    pid: Number(match[1]),
+    rssKb: Number(match[2]),
+    elapsedSeconds: parseElapsedSeconds(match[3]),
+    command: match[4],
+  };
+}
+
+export function listPressureProcesses({ spawnSyncFn = spawnSync } = {}) {
+  const result = spawnSyncFn('ps', ['-ax', '-o', 'pid=,rss=,etime=,command='], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  if (result.status !== 0) return [];
+  return String(result.stdout || '')
+    .split(/\r?\n/)
+    .map(parsePsLine)
+    .filter(Boolean)
+    .filter((entry) => isOpencodeCommand(entry.command) || isHelperCommand(entry.command) || isCassIndexCommand(entry.command));
+}
+
+export function readSwapUsage({ spawnSyncFn = spawnSync } = {}) {
+  const result = spawnSyncFn('sysctl', ['vm.swapusage'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  if (result.status !== 0) return null;
+  return parseSwapUsage(result.stdout);
+}
+
+function thresholdBytes(gb) {
+  return gb * 1024 * 1024 * 1024;
+}
+
+export function runPressureRelease({
+  env = process.env,
+  processEntries,
+  swapUsage,
+  spawnSyncFn = spawnSync,
+  killFn = process.kill.bind(process),
+  force = false,
+} = {}) {
+  const config = thresholdConfig(env);
+  const entries = processEntries ?? listPressureProcesses({ spawnSyncFn });
+  const swap = swapUsage ?? readSwapUsage({ spawnSyncFn });
+  const plan = buildCleanupPlan(entries, config);
+  const pressureTriggered = force || Boolean(swap && swap.usedBytes >= thresholdBytes(config.swapGb));
+  const warningState = readWarningState(env);
+  const warningGraceSeconds = config.opencodeWarnGraceMinutes * 60;
+  const targets = [];
+  const warnings = [];
+  const nextWarningState = {};
+
+  for (const entry of plan.terminate) {
+    if (!entry.warnFirst) {
+      targets.push(entry);
+      continue;
+    }
+
+    const key = warningKey(entry);
+    const previous = warningState[key];
+    const warnedAt = typeof previous?.warnedAt === 'number' ? previous.warnedAt : null;
+    const now = Date.now();
+
+    if (warnedAt && ((now - warnedAt) / 1000) >= warningGraceSeconds) {
+      targets.push(entry);
+      continue;
+    }
+
+    const record = {
+      pid: entry.pid,
+      command: entry.command,
+      reason: entry.reason,
+      warnedAt: warnedAt ?? now,
+    };
+    nextWarningState[key] = record;
+    warnings.push({
+      ...entry,
+      warningIssued: !warnedAt,
+      graceMinutes: config.opencodeWarnGraceMinutes,
+    });
+  }
+
+  if (pressureTriggered) targets.push(...plan.cassCandidates);
+
+  const killed = [];
+  for (const entry of targets) {
+    try {
+      killFn(entry.pid, 'SIGTERM');
+      killed.push({ pid: entry.pid, reason: entry.reason });
+    } catch {
+      // Process may already be gone or we lack permission — pressure relief
+      // continues regardless; the loop is opportunistic per-pid, not transactional.
+    }
+  }
+
+  for (const entry of targets) {
+    if (!entry.warnFirst) continue;
+    delete nextWarningState[warningKey(entry)];
+  }
+  writeWarningState(nextWarningState, env);
+
+  return {
+    pressureTriggered,
+    swapUsage: swap,
+    config,
+    plan,
+    warnings,
+    killed,
+  };
+}
+
+function plistEscape(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+export function installPressureGuardLaunchAgent({
+  homeDir = os.homedir(),
+  rootDir,
+  intervalSeconds = Number(DEFAULTS.intervalSeconds),
+  nodePath = process.execPath,
+} = {}) {
+  const launchAgentsDir = path.join(homeDir, 'Library', 'LaunchAgents');
+  fs.mkdirSync(launchAgentsDir, { recursive: true });
+  const plistPath = path.join(launchAgentsDir, 'dev.construct.pressure-release.plist');
+  const programArgs = [
+    nodePath,
+    path.join(rootDir, 'bin', 'construct'),
+    'cleanup',
+    '--pressure-release',
+  ];
+  const plist = `<?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>dev.construct.pressure-release</string>
+    <key>ProgramArguments</key>
+    <array>
+${programArgs.map((arg) => `      <string>${plistEscape(arg)}</string>`).join('\n')}
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StartInterval</key>
+    <integer>${intervalSeconds}</integer>
+    <key>StandardOutPath</key>
+    <string>${plistEscape(path.join(homeDir, '.construct', 'runtime', 'pressure-release.log'))}</string>
+    <key>StandardErrorPath</key>
+    <string>${plistEscape(path.join(homeDir, '.construct', 'runtime', 'pressure-release.log'))}</string>
+  </dict>
+</plist>
+`;
+  fs.writeFileSync(plistPath, plist, 'utf8');
+  return { installed: true, plistPath };
+}
+
+export function loadPressureGuardLaunchAgent({
+  plistPath,
+  spawnSyncFn = spawnSync,
+} = {}) {
+  if (!plistPath || !fs.existsSync(plistPath)) return { loaded: false, reason: 'missing-plist' };
+  spawnSyncFn('launchctl', ['unload', plistPath], {
+    stdio: ['ignore', 'ignore', 'ignore'],
+  });
+  const result = spawnSyncFn('launchctl', ['load', '-w', plistPath], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status === 0) return { loaded: true };
+  return {
+    loaded: false,
+    reason: (result.stderr || result.stdout || 'launchctl load failed').trim().split('\n')[0],
+  };
+}

package/lib/schema-artifact.mjs

@@ -0,0 +1,134 @@
+/**
+ * lib/schema-artifact.mjs — persist and read inferred schema results.
+ *
+ * Writes SchemaInferenceResult and UnifiedSchemaResult objects as JSON artifacts
+ * under .cx/knowledge/reference/schemas/. File names are derived from the source document
+ * basename so results are easy to find and diff.
+ *
+ * Schema artifacts are intentionally separate from ingested markdown so they
+ * can be consumed programmatically without parsing markdown.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve } from 'node:path';
+
+const DEFAULT_SCHEMA_DIR = '.cx/knowledge/reference/schemas';
+
+function slugify(value) {
+  return String(value)
+    .normalize('NFKD')
+    .replace(/[^\w.-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .toLowerCase();
+}
+
+function ensureDir(dirPath) {
+  mkdirSync(dirPath, { recursive: true });
+}
+
+function nextAvailablePath(targetPath) {
+  if (!existsSync(targetPath)) return targetPath;
+  const parsed = parse(targetPath);
+  let index = 2;
+  while (true) {
+    const candidate = join(parsed.dir, `${parsed.name}-${index}${parsed.ext}`);
+    if (!existsSync(candidate)) return candidate;
+    index += 1;
+  }
+}
+
+/**
+ * Write a schema inference result to disk.
+ *
+ * @param {object} schema   SchemaInferenceResult or UnifiedSchemaResult
+ * @param {object} opts
+ * @param {string} [opts.cwd]        Project root for resolving default output dir.
+ * @param {string} [opts.outputPath] Explicit output path (overrides outputDir).
+ * @param {string} [opts.outputDir]  Directory to write into (default: .cx/knowledge/reference/schemas).
+ * @param {string} [opts.label]      Optional label that derives the filename.
+ * @returns {{ outputPath: string, relativePath: string }}
+ */
+export function writeSchemaArtifact(schema, { cwd = process.cwd(), outputPath = null, outputDir = null, label = null } = {}) {
+  const resolvedCwd = resolve(cwd);
+  const resolvedDir = outputDir
+    ? (isAbsolute(outputDir) ? outputDir : resolve(resolvedCwd, outputDir))
+    : resolve(resolvedCwd, DEFAULT_SCHEMA_DIR);
+
+  let targetPath;
+  if (outputPath) {
+    targetPath = isAbsolute(outputPath) ? outputPath : resolve(resolvedCwd, outputPath);
+  } else {
+    // Derive filename from source_path (single) or label (unified).
+    const nameBase = label
+      ? slugify(label)
+      : schema.source_path
+        ? slugify(basename(schema.source_path))
+        : 'schema';
+    targetPath = join(resolvedDir, `${nameBase}.schema.json`);
+  }
+
+  ensureDir(dirname(targetPath));
+  const finalPath = nextAvailablePath(targetPath);
+
+  writeFileSync(finalPath, JSON.stringify(schema, null, 2) + '\n', 'utf8');
+
+  return {
+    outputPath: finalPath,
+    relativePath: relative(resolvedCwd, finalPath),
+  };
+}
+
+/**
+ * Read a schema artifact from disk.
+ *
+ * @param {string} schemaPath  Absolute or relative path to a .schema.json file.
+ * @param {string} [cwd]
+ * @returns {object}
+ */
+export function readSchemaArtifact(schemaPath, cwd = process.cwd()) {
+  const resolved = isAbsolute(schemaPath) ? schemaPath : resolve(cwd, schemaPath);
+  if (!existsSync(resolved)) throw new Error(`Schema artifact not found: ${resolved}`);
+  return JSON.parse(readFileSync(resolved, 'utf8'));
+}
+
+/**
+ * List all schema artifacts in a directory.
+ *
+ * @param {object} opts
+ * @param {string} [opts.cwd]
+ * @param {string} [opts.schemaDir]
+ * @returns {Array<{ path: string, relativePath: string, stat: object }>}
+ */
+export function listSchemaArtifacts({ cwd = process.cwd(), schemaDir = null } = {}) {
+  const resolvedCwd = resolve(cwd);
+  const dir = schemaDir
+    ? (isAbsolute(schemaDir) ? schemaDir : resolve(resolvedCwd, schemaDir))
+    : resolve(resolvedCwd, DEFAULT_SCHEMA_DIR);
+
+  if (!existsSync(dir)) return [];
+
+  const entries = [];
+  const stack = [dir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile() && entry.name.endsWith('.schema.json')) {
+        entries.push({
+          path: full,
+          relativePath: relative(resolvedCwd, full),
+          stat: statSync(full),
+        });
+      }
+    }
+  }
+  return entries.sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs);
+}
+
+/**
+ * Default schema output dir relative to project root.
+ */
+export const SCHEMA_DIR = DEFAULT_SCHEMA_DIR;