@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/registry/surface-map.mjs

@@ -0,0 +1,76 @@
+/**
+ * lib/registry/surface-map.mjs — ADR-0039 primary interaction surface per command group.
+ *
+ * Declarative map from CLI command name to primary surface tier. The CLI registry
+ * remains the substrate; this file governs discovery posture without removing verbs.
+ *
+ * Surfaces:
+ *   agent-mcp — MCP tool canonical; CLI --json twin
+ *   thin-cli  — human types this at a prompt
+ *   tui       — interactive loop emphasized
+ *   dashboard — visual/telemetry emphasized
+ *   internal  — CI/harness only
+ */
+
+export const SURFACE_TIERS = ['agent-mcp', 'thin-cli', 'tui', 'dashboard', 'internal'];
+
+/** @type {Record<string, string>} */
+export const COMMAND_SURFACE = {
+  install: 'thin-cli',
+  init: 'thin-cli',
+  dev: 'thin-cli',
+  dashboard: 'thin-cli',
+  stop: 'thin-cli',
+  status: 'thin-cli',
+  doctor: 'thin-cli',
+  sync: 'thin-cli',
+  ingest: 'agent-mcp',
+  drop: 'agent-mcp',
+  distill: 'agent-mcp',
+  ask: 'agent-mcp',
+  search: 'agent-mcp',
+  knowledge: 'agent-mcp',
+  memory: 'agent-mcp',
+  reflect: 'agent-mcp',
+  intake: 'tui',
+  workflow: 'agent-mcp',
+  graph: 'agent-mcp',
+  capability: 'agent-mcp',
+  execution: 'agent-mcp',
+  orchestrate: 'agent-mcp',
+  models: 'agent-mcp',
+  profile: 'tui',
+  sandbox: 'tui',
+  review: 'dashboard',
+  telemetry: 'dashboard',
+  evals: 'dashboard',
+  improvement: 'dashboard',
+  ci: 'thin-cli',
+  docs: 'thin-cli',
+  export: 'agent-mcp',
+  diagram: 'agent-mcp',
+  demo: 'agent-mcp',
+  beads: 'thin-cli',
+  hook: 'internal',
+  'lint:comments': 'internal',
+  'lint:agents': 'internal',
+  'registry:status': 'internal',
+  'registry:validate': 'internal',
+  'registry:generate-docs': 'internal',
+  rules: 'thin-cli',
+};
+
+export function surfaceForCommand(name) {
+  if (COMMAND_SURFACE[name]) return COMMAND_SURFACE[name];
+  if (name.includes(':')) return 'internal';
+  return 'thin-cli';
+}
+
+export function commandsBySurface(commands) {
+  const grouped = Object.fromEntries(SURFACE_TIERS.map((t) => [t, []]));
+  for (const cmd of commands) {
+    const surface = cmd.surface ?? surfaceForCommand(cmd.name);
+    grouped[surface]?.push(cmd.name);
+  }
+  return grouped;
+}

package/lib/registry/validate.mjs

@@ -0,0 +1,135 @@
+/**
+ * lib/registry/validate.mjs — validate registry/capabilities.json against repo reality.
+ *
+ * Checks that declared skills, templates, workflow types, and verification paths
+ * resolve on disk; flags stale lastValidated entries; ensures every embedded
+ * workflow type has a registry row. Consumed by `construct registry validate`
+ * and `construct doctor`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { WORKFLOW_TYPES } from '../embedded-contract/workflow-defs.mjs';
+import { STRUCTURE_REQUIREMENTS } from '../templates/visual-requirements.mjs';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(MODULE_DIR, '..', '..');
+const REGISTRY_PATH = path.join(REPO_ROOT, 'registry', 'capabilities.json');
+const STALE_MS = 90 * 24 * 60 * 60 * 1000;
+
+function exists(rel) {
+  return fs.existsSync(path.join(REPO_ROOT, rel));
+}
+
+function resolveSkillPath(skillId) {
+  return path.join(REPO_ROOT, 'skills', `${skillId}.md`);
+}
+
+function resolveTemplate(name) {
+  const shipped = path.join(REPO_ROOT, 'templates', 'docs', `${name}.md`);
+  if (exists(path.relative(REPO_ROOT, shipped))) return true;
+  return false;
+}
+
+export function loadCapabilityRegistry({ rootDir = REPO_ROOT } = {}) {
+  const file = path.join(rootDir, 'registry', 'capabilities.json');
+  if (!fs.existsSync(file)) {
+    return { version: 0, capabilities: [], error: 'registry/capabilities.json missing' };
+  }
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    return { version: 0, capabilities: [], error: err?.message || String(err) };
+  }
+}
+
+export function validateCapabilityRegistry({ rootDir = REPO_ROOT, now = Date.now() } = {}) {
+  const raw = loadCapabilityRegistry({ rootDir });
+  const errors = [];
+  const warnings = [];
+  const ids = new Set();
+
+  if (raw.error) errors.push(raw.error);
+
+  for (const cap of raw.capabilities ?? []) {
+    if (!cap.id) {
+      errors.push('capability missing id');
+      continue;
+    }
+    if (ids.has(cap.id)) errors.push(`duplicate capability id: ${cap.id}`);
+    ids.add(cap.id);
+
+    if (cap.skill && !fs.existsSync(resolveSkillPath(cap.skill))) {
+      errors.push(`${cap.id}: skill file missing: skills/${cap.skill}.md`);
+    }
+
+    if (cap.embeddedWorkflow && !WORKFLOW_TYPES.includes(cap.embeddedWorkflow)) {
+      errors.push(`${cap.id}: unknown embeddedWorkflow "${cap.embeddedWorkflow}"`);
+    }
+
+    if (cap.template && !resolveTemplate(cap.template)) {
+      errors.push(`${cap.id}: template missing: templates/docs/${cap.template}.md`);
+    }
+
+    const ver = cap.verification ?? {};
+    if (ver.functional && !exists(ver.functional)) {
+      errors.push(`${cap.id}: verification.functional missing: ${ver.functional}`);
+    }
+    if (ver.hostEmulation && !exists(ver.hostEmulation)) {
+      errors.push(`${cap.id}: verification.hostEmulation missing: ${ver.hostEmulation}`);
+    }
+    if (ver.structureRequirements && !STRUCTURE_REQUIREMENTS[ver.structureRequirements]) {
+      errors.push(`${cap.id}: unknown structureRequirements "${ver.structureRequirements}"`);
+    }
+
+    const hasTest = ver.functional || ver.hostEmulation || ver.untestableRationale;
+    if (!hasTest && (cap.criticality === 'P0' || cap.criticality === 'P1')) {
+      warnings.push(`${cap.id}: P0/P1 capability has no functional test or untestableRationale`);
+    }
+
+    const surfaces = cap.surfaces ?? {};
+    for (const [surface, status] of Object.entries(surfaces)) {
+      if (!status?.supported) continue;
+      if (status.primary) {
+        const tierPath = path.join('tests', 'capabilities', cap.id, `${surface}.test.mjs`);
+        const hasSurfaceTest = exists(tierPath);
+        const hasFunctional = !!(ver.functional || ver.hostEmulation);
+        if (!hasSurfaceTest && !hasFunctional && !ver.untestableRationale) {
+          warnings.push(`${cap.id}: primary surface "${surface}" has no tests/capabilities/${cap.id}/${surface}.test.mjs`);
+        }
+      }
+    }
+
+    if (cap.lastValidated) {
+      const age = now - Date.parse(cap.lastValidated);
+      if (Number.isFinite(age) && age > STALE_MS) {
+        warnings.push(`${cap.id}: lastValidated older than 90 days (${cap.lastValidated})`);
+      }
+    } else if (cap.criticality === 'P0') {
+      warnings.push(`${cap.id}: P0 capability never validated (lastValidated null)`);
+    }
+
+    for (const dep of cap.dependencies?.skills ?? []) {
+      if (!fs.existsSync(resolveSkillPath(dep))) {
+        errors.push(`${cap.id}: dependency skill missing: skills/${dep}.md`);
+      }
+    }
+  }
+
+  for (const wf of WORKFLOW_TYPES) {
+    const covered = (raw.capabilities ?? []).some((c) => c.embeddedWorkflow === wf);
+    if (!covered) {
+      warnings.push(`embedded workflow "${wf}" has no registry entry yet`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    count: (raw.capabilities ?? []).length,
+    registryPath: path.join(rootDir, 'registry', 'capabilities.json'),
+  };
+}

package/lib/resources/budget.mjs

@@ -82,6 +82,16 @@ export function measureUsage(projectRoot, env = process.env) {
   return result;
 }
 
+let lastBudgetWarnAt = 0;
+
+export function warnBudgetOnce(message, env = process.env) {
+  if (env.NODE_ENV === 'test' && env.CONSTRUCT_BUDGET_WARN_IN_TEST !== '1') return;
+  const now = Date.now();
+  if (now - lastBudgetWarnAt < 60_000) return;
+  lastBudgetWarnAt = now;
+  process.stderr.write(`[construct:budget] ${message}\n`);
+}
+
 export function reserveOrReject(projectRoot, category, sizeBytes, env = process.env) {
   if (!CATEGORY_PATHS[category]) {
     return { ok: true, source: 'unknown-category' };
@@ -110,6 +120,78 @@ export function reserveOrReject(projectRoot, category, sizeBytes, env = process.
   return { ok: true };
 }
 
+function listHardRejectFiles(projectRoot) {
+  const files = [];
+  for (const cat of HARD_REJECT_CATEGORIES) {
+    const rel = CATEGORY_PATHS[cat];
+    if (!rel) continue;
+    const dir = path.join(projectRoot, rel);
+    if (!fs.existsSync(dir)) continue;
+    const walk = (current) => {
+      for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+        const full = path.join(current, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+          continue;
+        }
+        try {
+          const stat = fs.statSync(full);
+          files.push({
+            category: cat,
+            path: full,
+            mtimeMs: stat.mtimeMs,
+            bytes: stat.size,
+          });
+        } catch { /* race */ }
+      }
+    };
+    walk(dir);
+  }
+  files.sort((a, b) => a.mtimeMs - b.mtimeMs);
+  return files;
+}
+
+export function planEmergencyReclaim(projectRoot, bytesNeeded, env = process.env) {
+  const usage = measureUsage(projectRoot, env);
+  const bytesToFree = Math.max(0, usage.totalCxBytes + bytesNeeded - usage.totalCxCap);
+  if (bytesToFree <= 0) return [];
+
+  const actions = [];
+  let freed = 0;
+  for (const file of listHardRejectFiles(projectRoot)) {
+    if (freed >= bytesToFree) break;
+    actions.push({
+      category: file.category,
+      path: file.path,
+      reason: 'emergency-reclaim',
+      bytes: file.bytes,
+    });
+    freed += file.bytes;
+  }
+  return actions;
+}
+
+export function ensureDiskWrite(projectRoot, category, sizeBytes, env = process.env) {
+  let check = reserveOrReject(projectRoot, category, sizeBytes, env);
+  if (check.ok) return check;
+
+  if (!HARD_REJECT_CATEGORIES.has(category)) {
+    return check;
+  }
+
+  const actions = planEmergencyReclaim(projectRoot, sizeBytes, env);
+  let reclaimed = { removed: [], bytesFreed: 0 };
+  if (actions.length) {
+    reclaimed = executePrune(actions);
+    check = reserveOrReject(projectRoot, category, sizeBytes, env);
+    if (check.ok) {
+      return { ...check, reclaimed };
+    }
+  }
+
+  return { ...check, reclaimed };
+}
+
 export function planPrune(projectRoot, env = process.env, opts = {}) {
   const budgets = loadResourceBudgets(projectRoot, env);
   const disk = budgets?.disk ?? {};

package/lib/resources/process-budget.mjs

@@ -0,0 +1,45 @@
+/**
+ * lib/resources/process-budget.mjs — RSS caps from construct.config.json.
+ *
+ * Maps long-running Construct processes to `resources.process.*` limits so
+ * daemon runners and embed workers share one config surface with doctor.
+ */
+
+import { loadProjectConfig } from '../config/project-config.mjs';
+import { DEFAULT_MEMORY_CAP_MB } from '../daemons/contract.mjs';
+
+export function loadProcessBudgets(projectRoot, env = process.env) {
+  const { config } = loadProjectConfig(projectRoot, env);
+  const process = config?.resources?.process ?? {};
+  return {
+    embedDaemonMaxRssMb: process.embedDaemonMaxRssMb ?? 800,
+    mcpServerMaxRssMb: process.mcpServerMaxRssMb ?? 250,
+    workerReplicaMaxRssMb: process.workerReplicaMaxRssMb ?? DEFAULT_MEMORY_CAP_MB,
+  };
+}
+
+export function memoryCapMbFor(daemonName, projectRoot, env = process.env) {
+  const budgets = loadProcessBudgets(projectRoot, env);
+  switch (daemonName) {
+    case 'embed':
+    case 'embed-daemon':
+      return budgets.embedDaemonMaxRssMb;
+    case 'mcp':
+    case 'construct-mcp':
+      return budgets.mcpServerMaxRssMb;
+    case 'intake':
+    case 'oracle':
+    case 'worker':
+      return budgets.workerReplicaMaxRssMb;
+    default:
+      return DEFAULT_MEMORY_CAP_MB;
+  }
+}
+
+export function currentRssMb() {
+  return process.memoryUsage().rss / (1024 * 1024);
+}
+
+export function rssOverCap(capMb) {
+  return currentRssMb() > capMb;
+}

package/lib/rules-delivery.mjs

@@ -15,11 +15,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { logRuleCall } from './telemetry/rule-calls.mjs';
+
 const SKIP_DIRS = new Set(['node_modules', '.git', '.cx', 'dist', 'build', '.next', 'vendor', '.beads']);
 const MAX_FILES = 5000;
 
-function parseRule(absPath) {
+function parseRule(absPath, ruleRel) {
   const raw = fs.readFileSync(absPath, 'utf8');
+  logRuleCall({
+    rulePath: `rules/${ruleRel.replace(/\.md$/, '')}.md`,
+    source: 'sync',
+    callerContext: 'rules-delivery',
+  });
   const fm = raw.match(/^---\n([\s\S]*?)\n---\n?/);
   if (!fm) return null;
   const globs = [...fm[1].matchAll(/^\s*-\s+"([^"]+)"\s*$/gm)].map((m) => m[1]);
@@ -38,7 +45,7 @@ export function collectGlobScopedRules(rulesDir) {
       const childRel = rel ? `${rel}/${e.name}` : e.name;
       if (e.isDirectory()) walk(full, childRel);
       else if (e.name.endsWith('.md')) {
-        const parsed = parseRule(full);
+        const parsed = parseRule(full, childRel);
         if (parsed) out.push({ rule: childRel.replace(/\.md$/, ''), ...parsed });
       }
     }

package/lib/rules-read.mjs

@@ -0,0 +1,26 @@
+/**
+ * lib/rules-read.mjs — read rule files with reference telemetry.
+ *
+ * Central read path for enforcement and sync tooling so `construct rules usage`
+ * can roll up which rules are actually loaded at runtime.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { logRuleCall } from './telemetry/rule-calls.mjs';
+
+const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export function normalizeRulePath(rel) {
+  const trimmed = String(rel || '').replace(/^\.\//, '');
+  if (trimmed.startsWith('rules/')) return trimmed;
+  return `rules/${trimmed.replace(/\.md$/, '')}.md`;
+}
+
+export function readRuleFile(rel, { rootDir = REPO_ROOT, source = 'validation', callerContext, env } = {}) {
+  const rulePath = normalizeRulePath(rel);
+  logRuleCall({ rulePath, source, callerContext }, { env });
+  return fs.readFileSync(path.join(rootDir, rulePath), 'utf8');
+}

package/lib/runtime-env.mjs

@@ -0,0 +1,23 @@
+/**
+ * lib/runtime-env.mjs — Construct runtime environment with credential bootstrap.
+ *
+ * prepareConstructEnv merges ~/.construct/config.env into the process environment.
+ * Credential auto-link from 1Password runs only when autoLink:true (setup-credentials).
+ */
+
+import { loadConstructEnv } from './env-config.mjs';
+import { ensureConstructCredentials } from './providers/credential-bootstrap.mjs';
+
+export { loadConstructEnv } from './env-config.mjs';
+
+export function prepareConstructEnv({
+  rootDir, homeDir, env = process.env, warn = true, cwd, autoLink = false,
+} = {}) {
+  ensureConstructCredentials({
+    env,
+    cwd: cwd || rootDir || process.cwd(),
+    home: homeDir,
+    autoLink,
+  });
+  return loadConstructEnv({ rootDir, homeDir, env, warn });
+}

package/lib/runtime-pressure.mjs

@@ -91,6 +91,19 @@ function isHelperCommand(command) {
   return /(context7-mcp|playwright-mcp|mcp-server-sequential-thinking)/.test(command);
 }
 
+// VHS demo recorder spawns ttyd with a fixed flag set. Orphaned instances retain
+// resources after VHS exits without teardown.
+
+function isVhsTtydCommand(command) {
+  return /\bttyd\b/.test(command)
+    && /--once\b/.test(command)
+    && /rendererType canvas/.test(command);
+}
+
+function isVhsRecorderCommand(command) {
+  return /(?:^|\/)vhs(?:\s|$)/.test(command);
+}
+
 function isCassIndexCommand(command) {
   return /\bcass index\b/.test(command);
 }
@@ -166,6 +179,28 @@ export function buildCleanupPlan(processEntries = [], thresholds = {}) {
     }
   }
 
+  const leakedVhsTtyd = processEntries
+    .filter((entry) => isVhsTtydCommand(entry.command)
+      && (entry.ppid === 1 || entry.elapsedSeconds >= 3600))
+    .sort((a, b) => b.elapsedSeconds - a.elapsedSeconds);
+  for (const entry of leakedVhsTtyd) {
+    if (!seen.has(entry.pid)) {
+      seen.add(entry.pid);
+      terminate.push({ ...entry, reason: 'leaked-vhs-ttyd' });
+    }
+  }
+
+  const staleVhs = processEntries
+    .filter((entry) => isVhsRecorderCommand(entry.command)
+      && entry.elapsedSeconds >= maxHelperAgeSeconds)
+    .sort((a, b) => b.elapsedSeconds - a.elapsedSeconds);
+  for (const entry of staleVhs) {
+    if (!seen.has(entry.pid)) {
+      seen.add(entry.pid);
+      terminate.push({ ...entry, reason: 'stale-vhs-recorder' });
+    }
+  }
+
   const cassCandidates = processEntries
     .filter((entry) => isCassIndexCommand(entry.command) && entry.elapsedSeconds >= maxCassIndexAgeSeconds)
     .sort((a, b) => b.elapsedSeconds - a.elapsedSeconds)
@@ -179,18 +214,27 @@ export function buildCleanupPlan(processEntries = [], thresholds = {}) {
 }
 
 function parsePsLine(line) {
-  const match = line.match(/^\s*(\d+)\s+(\d+)\s+([0-9:-]+)\s+(.*)$/);
+  const match = line.match(/^\s*(\d+)\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],
+    ppid: Number(match[2]),
+    rssKb: Number(match[3]),
+    elapsedSeconds: parseElapsedSeconds(match[4]),
+    command: match[5],
   };
 }
 
+function isPressureManagedEntry(entry) {
+  return isOpencodeCommand(entry.command)
+    || isHelperCommand(entry.command)
+    || isCassIndexCommand(entry.command)
+    || isVhsTtydCommand(entry.command)
+    || isVhsRecorderCommand(entry.command);
+}
+
 export function listPressureProcesses({ spawnSyncFn = spawnSync } = {}) {
-  const result = spawnSyncFn('ps', ['-ax', '-o', 'pid=,rss=,etime=,command='], {
+  const result = spawnSyncFn('ps', ['-ax', '-o', 'pid=,ppid=,rss=,etime=,command='], {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],
   });
@@ -199,7 +243,7 @@ export function listPressureProcesses({ spawnSyncFn = spawnSync } = {}) {
     .split(/\r?\n/)
     .map(parsePsLine)
     .filter(Boolean)
-    .filter((entry) => isOpencodeCommand(entry.command) || isHelperCommand(entry.command) || isCassIndexCommand(entry.command));
+    .filter(isPressureManagedEntry);
 }
 
 export function readSwapUsage({ spawnSyncFn = spawnSync } = {}) {
@@ -270,7 +314,7 @@ export function runPressureRelease({
   for (const entry of targets) {
     try {
       killFn(entry.pid, 'SIGTERM');
-      killed.push({ pid: entry.pid, reason: entry.reason });
+      killed.push({ pid: entry.pid, reason: entry.reason, command: entry.command });
     } catch {
       // Process may already be gone or we lack permission — pressure relief
       // continues regardless; the loop is opportunistic per-pid, not transactional.

package/lib/schema-infer.mjs

@@ -21,7 +21,7 @@
  *   { name, type, description, required, pattern, example, enum, format, nested_fields }
  */
 
-import { extractDocumentText } from './document-extract.mjs';
+import { extractDocumentTextNodeNative, extractDocumentTextAsync } from './document-extract.mjs';
 import { readCurrentModels, readOpenRouterApiKeyFromOpenCodeConfig } from './model-router.mjs';
 import { getUserEnvPath } from './env-config.mjs';
 import { pollFreeModels, topForTier } from './model-free-selector.mjs';
@@ -348,6 +348,17 @@ function buildUserPrompt(extracted) {
   ].join('\n');
 }
 
+async function extractForSchemaInfer(filePath, { maxChars }) {
+  try {
+    return await extractDocumentTextNodeNative(filePath, { maxChars });
+  } catch (err) {
+    if (err.code === 'OFFICE_REQUIRES_DOCLING' || err.code === 'PDF_REQUIRES_DOCLING') {
+      return extractDocumentTextAsync(filePath, { maxChars });
+    }
+    throw err;
+  }
+}
+
 /**
  * Infer a structured schema from a document file.
  *
@@ -372,7 +383,7 @@ export async function inferDocumentSchema(filePath, { maxChars = 40_000 } = {})
     environment,
   });
 
-  const extracted = extractDocumentText(filePath, { maxChars });
+  const extracted = await extractForSchemaInfer(filePath, { maxChars });
   if (!extracted.text || extracted.text.trim().length === 0) {
     void lfUpdateTrace({ id: traceId, output: { error: 'no-text-extracted' }, metadata: { status: 'error' } });
     throw new Error(`No text could be extracted from: ${filePath}`);