@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/intake/session-prelude.mjs

@@ -14,6 +14,11 @@ import { createIntakeQueue } from './queue.mjs';
 import { formatTriageLine } from './classify.mjs';
 import { isBrokered } from '../mcp/broker.mjs';
 import { getRebrand } from '../profiles/rebrand.mjs';
+import { homedir as osHomedir } from 'node:os';
+import { readLastTick } from '../oracle/index.mjs';
+import { listPending } from '../oracle/actions.mjs';
+import { readLatestVerdict } from '../oracle/verdicts.mjs';
+import { isVerdictOnlyGap } from '../oracle/policy.mjs';
 
 export function buildIntakePrelude({ cwd, env = process.env } = {}) {
   if (!cwd) return '';
@@ -48,9 +53,93 @@ export function buildBrokerStatusLine({ env = process.env } = {}) {
 export function buildSessionPrelude({ cwd, env = process.env } = {}) {
   const intake = buildIntakePrelude({ cwd, env });
   const broker = buildBrokerStatusLine({ env });
-  if (!intake && !broker) return '';
+  const oracle = buildOraclePrelude({ cwd, env });
+  if (!intake && !broker && !oracle) return '';
   const parts = [];
   if (intake) parts.push(intake.trim());
+  if (oracle) parts.push(oracle.trim());
   if (broker) parts.push(broker);
   return parts.join('\n\n');
 }
+
+/**
+ * Oracle verdict + pending queue for session-start (mirror doctor warnings).
+ */
+export function buildOraclePrelude({ cwd, env = process.env, homeDir } = {}) {
+  if (!cwd) return '';
+  if (env.CONSTRUCT_ORACLE === 'off' || env.CONSTRUCT_ORACLE === '0') return '';
+  try {
+    const home = homeDir ?? osHomedir();
+    const last = readLastTick(home);
+    const verdict = readLatestVerdict(cwd);
+    const pending = listPending(cwd).filter((p) => p.status === 'pending');
+    const v = verdict?.verdict ?? last?.verdict ?? 'unknown';
+    if (v === 'healthy' && pending.length === 0) return '';
+    const lines = [`\n## Oracle overseer · verdict: **${v}**`];
+    const gapSource = verdict?.gaps ?? last?.gaps ?? [];
+    const top = gapSource.filter((g) => g.severity === 'high').slice(0, 3);
+    for (const g of top) {
+      if (isVerdictOnlyGap(g)) {
+        const hint = g.id === 'beads-hygiene'
+          ? 'run `construct beads drift`'
+          : g.id === 'workflow-misaligned'
+            ? 'run `construct workflow init` or `construct init`'
+            : 'see `construct oracle gaps`';
+        lines.push(`- [${g.severity}] ${g.id} (verdict-only): ${g.detail} — ${hint}`);
+      } else {
+        lines.push(`- [${g.severity}] ${g.id}: ${g.detail}`);
+      }
+    }
+    if (pending.length) {
+      lines.push(`Pending approvals (${pending.length}): \`construct oracle pending\``);
+    }
+    lines.push('Review: `construct oracle review` · Gaps: `construct oracle gaps` · Approve: `construct oracle approve <id>`\n');
+    return lines.join('\n');
+  } catch {
+    return '';
+  }
+}
+
+export function readOracleDockState({ cwd, env = process.env, homeDir } = {}) {
+  if (!cwd || env.CONSTRUCT_ORACLE === 'off' || env.CONSTRUCT_ORACLE === '0') {
+    return { visible: false, verdict: null, pendingCount: 0, topGaps: [], summary: '' };
+  }
+  try {
+    const home = homeDir ?? osHomedir();
+    const last = readLastTick(home);
+    const verdictDoc = readLatestVerdict(cwd);
+    const pending = listPending(cwd).filter((p) => p.status === 'pending');
+    const verdict = verdictDoc?.verdict ?? last?.verdict ?? 'unknown';
+    const gapSource = verdictDoc?.gaps ?? last?.gaps ?? [];
+    const topGaps = gapSource.filter((g) => g.severity === 'high').slice(0, 3);
+    const visible = verdict !== 'healthy' || pending.length > 0;
+    const parts = [`verdict ${verdict}`];
+    if (pending.length) parts.push(`${pending.length} pending`);
+    return {
+      visible,
+      verdict,
+      pendingCount: pending.length,
+      topGaps,
+      summary: parts.join(' · '),
+    };
+  } catch {
+    return { visible: false, verdict: null, pendingCount: 0, topGaps: [], summary: '' };
+  }
+}
+
+export function formatOracleDockDetail(state) {
+  if (!state?.visible) return 'Oracle: healthy — no pending approvals.';
+  const lines = [`Oracle overseer · ${state.summary}`];
+  for (const g of state.topGaps || []) {
+    if (isVerdictOnlyGap(g)) {
+      lines.push(`  [${g.severity}] ${g.id} (verdict-only): ${g.detail}`);
+    } else {
+      lines.push(`  [${g.severity}] ${g.id}: ${g.detail}`);
+    }
+  }
+  if (state.pendingCount > 0) {
+    lines.push('  Pending: construct oracle pending');
+  }
+  lines.push('  Review: construct oracle review · Gaps: construct oracle gaps');
+  return lines.join('\n');
+}

package/lib/libreoffice-export.mjs

@@ -0,0 +1,97 @@
+/**
+ * lib/libreoffice-export.mjs — LibreOffice headless conversion for legacy .doc export.
+ *
+ * Pandoc has no `.doc` writer; Construct exports DOCX first, then down-converts via
+ * `soffice --headless --convert-to doc`. Binary is optional (ADR-0024).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const SOFFICE_CANDIDATES = [
+  'soffice',
+  'libreoffice',
+  '/Applications/LibreOffice.app/Contents/MacOS/soffice',
+];
+
+function whichBin(name) {
+  const cmd = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(cmd, [name], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return (result.stdout || '').trim().split('\n')[0] || null;
+}
+
+export function resolveLibreOfficeBin(env = process.env) {
+  const fromEnv = (env.CONSTRUCT_LIBREOFFICE_BIN || env.SOFFICE_BIN || '').trim();
+  if (fromEnv && fs.existsSync(fromEnv)) return fromEnv;
+  for (const candidate of SOFFICE_CANDIDATES) {
+    if (candidate.includes('/') && fs.existsSync(candidate)) return candidate;
+    const found = whichBin(candidate);
+    if (found) return found;
+  }
+  return null;
+}
+
+export function libreOfficePresent(env = process.env) {
+  return Boolean(resolveLibreOfficeBin(env));
+}
+
+export function libreOfficeInstallHint() {
+  return 'Install LibreOffice to enable legacy .doc export (e.g. `brew install --cask libreoffice` on macOS, `apt install libreoffice` on Debian/Ubuntu, or https://www.libreoffice.org/download/). Override with CONSTRUCT_LIBREOFFICE_BIN.';
+}
+
+export function convertDocxToDoc({
+  docxPath,
+  outputPath,
+  env = process.env,
+  spawnFn = spawnSync,
+} = {}) {
+  const soffice = resolveLibreOfficeBin(env);
+  if (!soffice) {
+    return {
+      ok: false,
+      message: libreOfficeInstallHint(),
+      missing: ['libreoffice'],
+    };
+  }
+  if (!fs.existsSync(docxPath)) {
+    return { ok: false, message: `DOCX intermediate missing: ${docxPath}` };
+  }
+
+  const outDir = path.dirname(outputPath);
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const result = spawnFn(soffice, [
+    '--headless',
+    '--convert-to', 'doc',
+    '--outdir', outDir,
+    path.resolve(docxPath),
+  ], { encoding: 'utf8', env });
+
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      message: `LibreOffice conversion failed (exit ${result.status}): ${(result.stderr || result.stdout || '').trim().slice(0, 400)}`,
+    };
+  }
+
+  const expected = path.join(outDir, `${path.parse(docxPath).name}.doc`);
+  if (!fs.existsSync(expected)) {
+    return {
+      ok: false,
+      message: `LibreOffice did not produce expected output: ${expected}`,
+    };
+  }
+
+  if (path.resolve(expected) !== path.resolve(outputPath)) {
+    fs.renameSync(expected, outputPath);
+  }
+
+  return {
+    ok: true,
+    outputPath,
+    engine: 'libreoffice',
+    message: `Wrote ${path.relative(process.cwd(), outputPath)}`,
+  };
+}

package/lib/logging/rotate.mjs

@@ -231,6 +231,15 @@ export const LIMITS = {
     envOverride: 'CONSTRUCT_HOOK_CALLS_MAX_MB',
   },
 
+  // Rule path reference telemetry. ~/.cx/rule-calls.jsonl.
+
+  'rule-calls': {
+    maxBytes: 10 * 1024 * 1024,
+    maxSegments: 2,
+    gzip: true,
+    envOverride: 'CONSTRUCT_RULE_CALLS_MAX_MB',
+  },
+
   // Legacy-lock fallback firings on the beads write path. ~/.cx/beads-fallback.jsonl.
 
   'beads-fallback': {

package/lib/maintenance/docker-reclaim.mjs

@@ -0,0 +1,206 @@
+/**
+ * lib/maintenance/docker-reclaim.mjs — reclaim abandoned per-home Postgres
+ * containers and data volumes that outlived the HOME that created them.
+ *
+ * Construct derives a Postgres container/volume namespace from a sha256 slice
+ * of the resolved home directory (lib/home-namespace.mjs) so isolated HOMEs —
+ * test sandboxes, ephemeral /tmp footprint runs, deleted accounts — never
+ * collide on one machine. Each container carries a `restart: unless-stopped`
+ * policy. When the owning HOME or its compose project directory is deleted,
+ * Docker keeps the container alive with nothing left to reap it: an orphan that
+ * pins memory and leaks disk through its named volume.
+ *
+ * The reclaim runs from the upgrade flows (lib/update.mjs, lib/upgrade.mjs)
+ * once per upgrade and from `construct cleanup`, never from `construct sync`,
+ * which fires constantly and must not mutate machine-global Docker state.
+ *
+ * An orphan is removed only when every signal agrees it is abandoned:
+ *   - the name carries a Construct per-home suffix (construct-postgres-<8 hex>),
+ *     so hand-named and third-party containers stay untouched;
+ *   - the suffix differs from the current HOME's suffix, sparing the live install;
+ *   - the name differs from an operator-pinned CONSTRUCT_PG_CONTAINER;
+ *   - a container's compose working_dir label points at a path that is gone;
+ *   - a volume has no surviving container for its suffix.
+ * The legacy singular `construct-postgres` (no suffix) is out of scope.
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+
+import { homeNamespaceSuffix } from '../home-namespace.mjs';
+
+const CONTAINER_RE = /^construct-postgres-([0-9a-f]{8})$/;
+const VOLUME_RE = /construct-postgres-([0-9a-f]{8})/;
+const CONTAINER_FORMAT = '{{.Names}}\t{{.Label "com.docker.compose.project.working_dir"}}';
+const DEFAULT_MAX = 25;
+
+export function defaultRunDocker(args) {
+  const r = spawnSync('docker', args, { encoding: 'utf8' });
+  return {
+    status: r.status ?? 1,
+    stdout: r.stdout || '',
+    stderr: r.stderr || '',
+    error: r.error || null,
+  };
+}
+
+// `docker ps -a` lists every container with its compose working_dir label on a
+// tab. Anything that does not match the per-home naming scheme is dropped, so
+// the parser only surfaces Construct-managed candidates.
+
+export function parseContainers(stdout) {
+  const out = [];
+  for (const raw of String(stdout || '').split('\n')) {
+    const line = raw.replace(/\s+$/, '');
+    if (!line) continue;
+    const tab = line.indexOf('\t');
+    const name = (tab === -1 ? line : line.slice(0, tab)).trim();
+    const workingDir = tab === -1 ? '' : line.slice(tab + 1).trim();
+    const match = CONTAINER_RE.exec(name);
+    if (!match) continue;
+    out.push({ name, suffix: match[1], workingDir });
+  }
+  return out;
+}
+
+export function parseVolumes(stdout) {
+  const out = [];
+  for (const raw of String(stdout || '').split('\n')) {
+    const name = raw.trim();
+    if (!name) continue;
+    const match = VOLUME_RE.exec(name);
+    if (!match) continue;
+    out.push({ name, suffix: match[1] });
+  }
+  return out;
+}
+
+// A container is an orphan when it belongs to a foreign home namespace, is not
+// the operator-pinned container, and its compose project directory is gone. A
+// volume is an orphan when its suffix is foreign and no surviving container —
+// including containers spared this pass — still claims it.
+
+export function selectOrphans({
+  containers,
+  volumes,
+  currentSuffix,
+  pinnedName = null,
+  pathExists = (p) => fs.existsSync(p),
+}) {
+  const orphanContainers = containers.filter((c) =>
+    c.suffix !== currentSuffix &&
+    c.name !== pinnedName &&
+    c.workingDir &&
+    !pathExists(c.workingDir));
+
+  const orphanSuffixes = new Set(orphanContainers.map((c) => c.suffix));
+  const liveSuffixes = new Set(
+    containers.filter((c) => !orphanSuffixes.has(c.suffix)).map((c) => c.suffix),
+  );
+
+  const orphanVolumes = volumes.filter((v) =>
+    v.suffix &&
+    v.suffix !== currentSuffix &&
+    !liveSuffixes.has(v.suffix));
+
+  return { orphanContainers, orphanVolumes };
+}
+
+export function reclaimOrphanedDockerResources({
+  runDocker = defaultRunDocker,
+  homeDir = os.homedir(),
+  env = process.env,
+  dryRun = false,
+  max = DEFAULT_MAX,
+  pathExists = (p) => fs.existsSync(p),
+} = {}) {
+  const summary = {
+    available: false,
+    reason: null,
+    scanned: { containers: 0, volumes: 0 },
+    removedContainers: [],
+    removedVolumes: [],
+    skipped: [],
+    errors: [],
+    dryRun,
+  };
+
+  // A non-zero `docker ps` means the daemon is down or Docker is absent; the
+  // machine then holds no reclaimable state and the pass is a clean no-op.
+
+  const psResult = runDocker(['ps', '-a', '--format', CONTAINER_FORMAT]);
+  if (!psResult || psResult.status !== 0) {
+    summary.reason = 'docker-unavailable';
+    return summary;
+  }
+  summary.available = true;
+
+  const containers = parseContainers(psResult.stdout);
+  summary.scanned.containers = containers.length;
+
+  const volResult = runDocker(['volume', 'ls', '--format', '{{.Name}}']);
+  const volumes = volResult && volResult.status === 0 ? parseVolumes(volResult.stdout) : [];
+  summary.scanned.volumes = volumes.length;
+
+  const currentSuffix = homeNamespaceSuffix(homeDir);
+  const pinnedName = (env.CONSTRUCT_PG_CONTAINER || '').trim() || null;
+
+  const { orphanContainers, orphanVolumes } = selectOrphans({
+    containers,
+    volumes,
+    currentSuffix,
+    pinnedName,
+    pathExists,
+  });
+
+  let budget = Number.isFinite(max) && max > 0 ? max : DEFAULT_MAX;
+
+  for (const c of orphanContainers) {
+    if (budget <= 0) {
+      summary.skipped.push({ name: c.name, reason: 'reclaim-budget-exhausted' });
+      continue;
+    }
+    budget -= 1;
+    if (dryRun) {
+      summary.removedContainers.push(c.name);
+      continue;
+    }
+    const r = runDocker(['rm', '-f', '-v', c.name]);
+    if (r && r.status === 0) summary.removedContainers.push(c.name);
+    else summary.errors.push({ name: c.name, error: (r?.stderr || '').trim() || `docker rm exited ${r?.status}` });
+  }
+
+  // A named data volume only drops once nothing references it. `docker volume
+  // rm` exits non-zero for an in-use or already-gone volume, so a failure here
+  // is recorded as skipped rather than a hard error.
+
+  for (const v of orphanVolumes) {
+    if (budget <= 0) {
+      summary.skipped.push({ name: v.name, reason: 'reclaim-budget-exhausted' });
+      continue;
+    }
+    budget -= 1;
+    if (dryRun) {
+      summary.removedVolumes.push(v.name);
+      continue;
+    }
+    const r = runDocker(['volume', 'rm', v.name]);
+    if (r && r.status === 0) summary.removedVolumes.push(v.name);
+    else summary.skipped.push({ name: v.name, reason: 'in-use-or-missing' });
+  }
+
+  return summary;
+}
+
+export function formatReclaim(summary) {
+  if (!summary || !summary.available) return null;
+  const containers = summary.removedContainers.length;
+  const volumes = summary.removedVolumes.length;
+  if (!containers && !volumes) return null;
+  const parts = [];
+  if (containers) parts.push(`${containers} orphaned Postgres container${containers === 1 ? '' : 's'}`);
+  if (volumes) parts.push(`${volumes} abandoned data volume${volumes === 1 ? '' : 's'}`);
+  const verb = summary.dryRun ? 'Would reclaim' : 'Reclaimed';
+  return `${verb} ${parts.join(' and ')} from deleted home namespaces.`;
+}

package/lib/mcp/external-schema-cost.mjs

@@ -0,0 +1,74 @@
+/**
+ * lib/mcp/external-schema-cost.mjs — measured token cost for heavy external MCP servers.
+ *
+ * Committed fixtures under tests/fixtures/mcp-tool-schemas/ hold captured tools/list
+ * payloads per server. Regenerate with scripts/measure-external-mcp-schemas.mjs.
+ * Sums schemaTokens via estimateToolTokens (JSON length × 0.25) for sync-time trim
+ * comments and ADR-0032 footnotes.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HEAVY_EXTERNAL_MCP_IDS, estimateToolTokens } from './tool-budget.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, '..', '..');
+export const EXTERNAL_MCP_SCHEMA_FIXTURE_DIR = join(REPO_ROOT, 'tests', 'fixtures', 'mcp-tool-schemas');
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+// Load one server's committed fixture; missing files throw so CI fails loudly.
+
+export function loadExternalMcpSchemaFixture(serverId) {
+  const path = join(EXTERNAL_MCP_SCHEMA_FIXTURE_DIR, `${serverId}.json`);
+  if (!existsSync(path)) {
+    throw new Error(`Missing external MCP schema fixture: ${path}`);
+  }
+  const doc = readJson(path);
+  const tools = Array.isArray(doc.tools) ? doc.tools : [];
+  const schemaTokens = Number.isFinite(doc.schemaTokens)
+    ? doc.schemaTokens
+    : estimateToolTokens(tools);
+  return {
+    serverId,
+    capturedAt: doc.capturedAt || null,
+    toolCount: tools.length,
+    schemaTokens,
+    tools,
+  };
+}
+
+// Per-server breakdown plus total for HEAVY_EXTERNAL_MCP_IDS.
+
+export function measuredHeavyExternalMcpCosts() {
+  const servers = {};
+  let totalSchemaTokens = 0;
+  for (const id of HEAVY_EXTERNAL_MCP_IDS) {
+    const row = loadExternalMcpSchemaFixture(id);
+    servers[id] = {
+      toolCount: row.toolCount,
+      schemaTokens: row.schemaTokens,
+      capturedAt: row.capturedAt,
+    };
+    totalSchemaTokens += row.schemaTokens;
+  }
+  return { servers, totalSchemaTokens };
+}
+
+export function measuredHeavyExternalMcpTokenCost() {
+  return measuredHeavyExternalMcpCosts().totalSchemaTokens;
+}
+
+// Lazy constant — fixtures may be absent while scripts/measure-external-mcp-schemas.mjs runs.
+
+let cachedMeasuredTotal = null;
+
+export function getMeasuredHeavyExternalMcpTokenCost() {
+  if (cachedMeasuredTotal === null) {
+    cachedMeasuredTotal = measuredHeavyExternalMcpTokenCost();
+  }
+  return cachedMeasuredTotal;
+}