@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/mcp/tools/skills.mjs

@@ -0,0 +1,409 @@
+/**
+ * lib/mcp/tools/skills.mjs — Skills, templates, agent contracts, orchestration policy, and team tools.
+ *
+ * Exposes listSkills, getSkill, searchSkills, getTemplate, listTemplates, agentContract,
+ * orchestrationPolicy, listTeams, and getTeam. All synchronous except agentContract (dynamic import).
+ * Requires ROOT_DIR injected via the opts argument on each call.
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { routeRequest, routeRequestVerified, requiresExecutiveApproval, TERMINAL_STATES } from '../../orchestration-policy.mjs';
+import { buildTaskPacketFromIntent } from '../../workflow-state.mjs';
+import { logSkillCall } from '../../telemetry/skill-calls.mjs';
+
+export function listSkills({ ROOT_DIR }) {
+  const skillsDir = join(ROOT_DIR, 'skills');
+  if (!existsSync(skillsDir)) return { error: 'Skills directory not found.' };
+
+  const listDirRecursive = (dir, prefix = '') => {
+    let results = [];
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        results = results.concat(listDirRecursive(join(dir, entry.name), `${prefix}${entry.name}/`));
+      } else if (entry.name.endsWith('.md') && entry.name !== 'SKILL.md') {
+        results.push(`${prefix}${entry.name.replace('.md', '')}`);
+      }
+    }
+    return results;
+  };
+
+  const skills = listDirRecursive(skillsDir).sort();
+  return { skills };
+}
+
+export function getSkill(args, { ROOT_DIR }) {
+  const { path: skillPath } = args;
+  if (!skillPath) return { error: 'Missing path argument' };
+
+  const fullPath = join(ROOT_DIR, 'skills', `${skillPath}.md`);
+
+  if (!existsSync(fullPath)) {
+    return { error: `Skill not found: ${skillPath}` };
+  }
+  const content = readFileSync(fullPath, 'utf8');
+  logSkillCall({ skillId: skillPath, source: 'mcp' });
+  return { content };
+}
+
+export function searchSkills(args, { ROOT_DIR }) {
+  const { pattern } = args;
+  if (!pattern) return { error: 'Missing pattern argument' };
+  const skillsDir = join(ROOT_DIR, 'skills');
+
+  try {
+    const output = execSync(`rg -i "${pattern.replace(/"/g, '\\"')}" "${skillsDir}"`, { encoding: 'utf8' });
+    return { results: output.split('\n').filter(Boolean) };
+  } catch {
+    try {
+      const output = execSync(`grep -ri "${pattern.replace(/"/g, '\\"')}" "${skillsDir}"`, { encoding: 'utf8' });
+      return { results: output.split('\n').filter(Boolean) };
+    } catch {
+      return { results: [], note: 'No matches found or grep error' };
+    }
+  }
+}
+
+function listTemplatesRaw({ ROOT_DIR }) {
+  const shipped = [];
+  const override = [];
+  const shippedDir = join(ROOT_DIR, 'templates', 'docs');
+  if (existsSync(shippedDir)) {
+    for (const f of readdirSync(shippedDir)) {
+      if (f.endsWith('.md')) shipped.push(f.replace(/\.md$/, ''));
+    }
+  }
+  const overrideDir = join(process.cwd(), '.cx', 'templates', 'docs');
+  if (existsSync(overrideDir)) {
+    for (const f of readdirSync(overrideDir)) {
+      if (f.endsWith('.md')) override.push(f.replace(/\.md$/, ''));
+    }
+  }
+  return { shipped: shipped.sort(), overridden: override.sort() };
+}
+
+export function getTemplate(args, { ROOT_DIR }) {
+  const { name } = args;
+  if (!name) return { error: 'Missing name argument' };
+  const safe = String(name).replace(/[^a-zA-Z0-9._-]/g, '');
+  if (!safe) return { error: 'Invalid template name' };
+
+  const cwd = process.cwd();
+  const candidates = [
+    { source: 'project-override', path: join(cwd, '.cx', 'templates', 'docs', `${safe}.md`) },
+    { source: 'shipped-default', path: join(ROOT_DIR, 'templates', 'docs', `${safe}.md`) },
+  ];
+  for (const { source, path: p } of candidates) {
+    if (existsSync(p)) {
+      return { source, path: p, content: readFileSync(p, 'utf8') };
+    }
+  }
+  return { error: `Template not found: ${safe}`, available: listTemplatesRaw({ ROOT_DIR }) };
+}
+
+export function listTemplates({ ROOT_DIR }) {
+  return listTemplatesRaw({ ROOT_DIR });
+}
+
+export async function agentContract(args = {}) {
+  const {
+    getAllContracts,
+    getContractById,
+    getContract,
+    getOutgoingContracts,
+    getIncomingContracts,
+    summarize,
+  } = await import('../../agent-contracts.mjs');
+  const { describePostconditions } = await import('../../agents/postconditions.mjs');
+  const { id, producer, consumer } = args;
+  // Attach binary postconditions to every returned contract so a specialist
+  // calling this tool at handoff time sees the hard checks their output
+  // packet must pass — not just the free-text postconditions field.
+  function attachPostconditions(c) {
+    if (!c?.producer) return c;
+    const binary = describePostconditions(c.producer);
+    return binary.length > 0 ? { ...c, binaryPostconditions: binary } : c;
+  }
+  if (id) {
+    const match = getContractById(String(id));
+    return match ? { contract: attachPostconditions(match) } : { error: `Contract not found: ${id}` };
+  }
+  if (producer && consumer) {
+    const match = getContract(String(producer), String(consumer));
+    return match ? { contract: attachPostconditions(match) } : { error: `No contract for ${producer} → ${consumer}` };
+  }
+  if (producer) return { producer: String(producer), contracts: getOutgoingContracts(String(producer)).map(attachPostconditions) };
+  if (consumer) return { consumer: String(consumer), contracts: getIncomingContracts(String(consumer)).map(attachPostconditions) };
+  return { summary: summarize(), contracts: getAllContracts().map(attachPostconditions) };
+}
+
+export async function orchestrationPolicy(args) {
+  // Use the LLM-verified router by default; it falls back to keyword-only
+  // when no model is configured or the verifier errors. Callers that need
+  // strictly synchronous behavior can import routeRequest directly.
+  const route = await routeRequestVerified(args || {});
+  const approvalRequired = requiresExecutiveApproval(args?.approval || {});
+  const draftTask = route.track !== 'immediate'
+    ? buildTaskPacketFromIntent(args?.request || '', { fileCount: args?.fileCount, moduleCount: args?.moduleCount })
+    : null;
+
+  // Per-specialist context packets: when the caller supplied a candidate
+  // artifact list, build the role-filtered bundle each specialist should
+  // receive. Each packet carries its own omitted-with-reason list so the
+  // caller can see exactly what was dropped per role. The router lookup
+  // strips the `cx-` prefix to match ROLE_POLICIES keys (which are
+  // unprefixed, e.g. `engineer`, `product-manager`).
+  let contextPackets = null;
+  const candidates = Array.isArray(args?.candidates) ? args.candidates : null;
+  if (candidates && route.specialists?.length > 0) {
+    const { buildContextPacket } = await import('../../context-router.mjs');
+    contextPackets = {};
+    for (const specialist of route.specialists) {
+      const role = specialist.replace(/^cx-/, '');
+      contextPackets[specialist] = buildContextPacket({
+        request: args?.request || '',
+        triage: args?.triage || null,
+        role,
+        budget: args?.budget || {},
+        candidates,
+      });
+    }
+  }
+
+  // Auto-generate a task graph when the caller names an intake packet.
+  // The graph mirrors the triage's recommendedChain one-to-one and is
+  // persisted to .cx/task-graphs/. Both intake.received and task_graph.created
+  // trace events share the same traceId so the lineage is queryable end-to-end.
+  let taskGraph = null;
+  let intakeError = null;
+  const intakeId = args?.intakeId;
+  if (intakeId) {
+    try {
+      const { createIntakeQueue } = await import('../../intake/queue.mjs');
+      const { generateTaskGraphFromTriage } = await import('../../task-graph/generate.mjs');
+      const { FilesystemTaskGraphStore } = await import('../../task-graph/store.mjs');
+      const { emitTraceEvent, newTraceId } = await import('../../worker/trace.mjs');
+      const cwd = process.cwd();
+      const queue = createIntakeQueue(cwd, process.env);
+      const intake = queue.read(intakeId);
+      if (!intake) {
+        intakeError = `intake packet not found: ${intakeId}`;
+      } else if (!intake.triage) {
+        intakeError = `intake packet ${intakeId} has no triage block`;
+      } else {
+        const traceId = args?.traceId || newTraceId();
+        const graph = generateTaskGraphFromTriage({
+          triage: intake.triage,
+          project: args?.project || (cwd.split('/').pop() || 'construct'),
+          request: args?.request || intake.excerpt || '',
+          intake: intake.intake,
+        });
+        new FilesystemTaskGraphStore(cwd).save(graph);
+        try {
+          emitTraceEvent({
+            rootDir: cwd,
+            eventType: 'task_graph.created',
+            traceId,
+            project: graph.project,
+            intakeId,
+            metadata: {
+              graphId: graph.id,
+              nodes: graph.nodes.length,
+              chain: graph.nodes.map((n) => n.owner),
+              intakeType: intake.triage.intakeType,
+              rdStage: intake.triage.rdStage,
+            },
+          });
+        } catch { /* observability never breaks the caller */ }
+        taskGraph = { ...graph, traceId };
+      }
+    } catch (err) {
+      intakeError = err?.message || String(err);
+    }
+  }
+
+  return {
+    ...route,
+    approvalRequired,
+    terminalStates: TERMINAL_STATES,
+    draftTask,
+    ...(contextPackets ? { contextPackets } : {}),
+    ...(taskGraph ? { taskGraph } : {}),
+    ...(intakeError ? { intakeError } : {}),
+  };
+}
+
+/**
+ * broker_check — query the MCP broker's policy decision for a pending action.
+ *
+ * Agents call this BEFORE attempting a high-risk action. Returns the same
+ * shape `Broker.invoke` would, minus the execute step: `{allowed, reason,
+ * approvalRequired, source, brokerActive}`. Solo mode returns
+ * `brokerActive: false` with `allowed: true` so agents skip the prompt
+ * overhead when no broker is configured. Always emits a `tool.called`
+ * trace event so the audit trail captures the consultation even when no
+ * underlying tool is invoked.
+ */
+export async function brokerCheck(args = {}) {
+  const { policyDecision } = await import('../../policy/engine.mjs');
+  const { isBrokered } = await import('../broker.mjs');
+  const { emitTraceEvent } = await import('../../worker/trace.mjs');
+  const brokerActive = isBrokered(process.env);
+
+  const baseEvent = {
+    rootDir: process.cwd(),
+    eventType: 'tool.called',
+    traceId: args?.traceId,
+    project: args?.project || null,
+    role: args?.role || null,
+  };
+
+  if (!brokerActive) {
+    try {
+      emitTraceEvent({
+        ...baseEvent,
+        metadata: {
+          tool: args?.tool || null,
+          action: args?.action || null,
+          risk: args?.risk || 'low',
+          allowed: true,
+          approvalRequired: false,
+          source: 'broker-off',
+          brokerActive: false,
+        },
+      });
+    } catch { /* observability never breaks the caller */ }
+    return {
+      allowed: true,
+      reason: 'broker inactive (solo mode default; set CONSTRUCT_MCP_BROKER=on to engage)',
+      approvalRequired: false,
+      source: 'broker-off',
+      brokerActive: false,
+    };
+  }
+
+  const decision = policyDecision({
+    role: args?.role,
+    project: args?.project,
+    tool: args?.tool,
+    action: args?.action,
+    risk: args?.risk,
+  });
+
+  try {
+    emitTraceEvent({
+      ...baseEvent,
+      metadata: {
+        tool: args?.tool || null,
+        action: args?.action || null,
+        risk: args?.risk || 'low',
+        allowed: decision.allowed,
+        approvalRequired: decision.approvalRequired,
+        source: decision.source,
+        brokerActive: true,
+      },
+    });
+  } catch { /* swallow */ }
+
+  return { ...decision, brokerActive: true };
+}
+
+/**
+ * worker_run — bounded command execution with optional task-graph evidence linkage.
+ *
+ * Wraps lib/worker/run.mjs `runJob`. Records evidence on the named task
+ * graph node when both `graphId` and `nodeId` are provided; otherwise
+ * returns the result without writing to a graph. Emits `worker.started`
+ * / `worker.completed` trace events from inside runJob, plus an
+ * `evidence.recorded` event when evidence is appended.
+ *
+ * Path policy: `allowedPaths` defaults to [cwd] so jobs can't reach
+ * outside the project. Set explicitly to broaden, e.g. when staging
+ * artifacts in a sibling worktree.
+ */
+export async function workerRun(args = {}) {
+  const { runJob } = await import('../../worker/run.mjs');
+  const { evidenceFromJobResult, recordEvidence } = await import('../../worker/evidence.mjs');
+  const { FilesystemTaskGraphStore } = await import('../../task-graph/store.mjs');
+
+  const cwd = process.cwd();
+  const jobId = args?.jobId || `worker-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const allowedPaths = Array.isArray(args?.allowedPaths) && args.allowedPaths.length > 0
+    ? args.allowedPaths
+    : [cwd];
+
+  let result;
+  try {
+    result = await runJob({
+      rootDir: cwd,
+      job: {
+        jobId,
+        taskId: args?.nodeId || args?.taskId || null,
+        project: args?.project || null,
+        workspaceRef: args?.workspaceRef || cwd,
+        command: args?.command,
+        args: Array.isArray(args?.args) ? args.args : [],
+        timeoutSeconds: args?.timeoutSeconds || 300,
+        envPolicy: args?.envPolicy || 'restricted',
+        allowedPaths,
+        allowedEnvKeys: Array.isArray(args?.allowedEnvKeys) ? args.allowedEnvKeys : [],
+        traceId: args?.traceId,
+      },
+    });
+  } catch (err) {
+    return { error: err?.message || String(err) };
+  }
+
+  // When the caller named a specific task graph node, append an evidence
+  // record. The result includes the evidence shape so the caller can show
+  // the user what was attached.
+  let evidence = null;
+  if (args?.graphId && args?.nodeId) {
+    try {
+      const store = new FilesystemTaskGraphStore(cwd);
+      evidence = evidenceFromJobResult(result, {
+        evidenceType: args?.evidenceType || 'test-result',
+        summary: args?.evidenceSummary,
+      });
+      recordEvidence({
+        store,
+        graphId: args.graphId,
+        nodeId: args.nodeId,
+        evidence,
+        rootDir: cwd,
+      });
+    } catch (err) {
+      return { ...result, evidence: null, evidenceError: err?.message || String(err) };
+    }
+  }
+
+  return { ...result, ...(evidence ? { evidence } : {}) };
+}
+
+export function listTeams({ ROOT_DIR }) {
+  const teamsPath = join(ROOT_DIR, 'agents', 'teams.json');
+  if (!existsSync(teamsPath)) return { error: 'agents/teams.json not found' };
+  const { templates } = JSON.parse(readFileSync(teamsPath, 'utf8'));
+  return {
+    teams: Object.entries(templates).map(([name, t]) => ({
+      name,
+      description: t.description,
+      members: t.members,
+      focus: t.focus,
+      skills: t.skills,
+      promotionGates: t.promotionGates,
+    })),
+  };
+}
+
+export function getTeam(args, { ROOT_DIR }) {
+  const { name } = args;
+  if (!name) return { error: 'Missing name argument' };
+  const teamsPath = join(ROOT_DIR, 'agents', 'teams.json');
+  if (!existsSync(teamsPath)) return { error: 'agents/teams.json not found' };
+  const { templates } = JSON.parse(readFileSync(teamsPath, 'utf8'));
+  const team = templates[name];
+  if (!team) return { error: `Team not found: ${name}`, available: Object.keys(templates) };
+  return { name, ...team };
+}

package/lib/mcp/tools/storage.mjs

@@ -0,0 +1,60 @@
+/**
+ * lib/mcp/tools/storage.mjs — Storage MCP tools: status, sync, reset, and artifact deletion.
+ *
+ * All functions are async. Wraps lib/storage/admin.mjs and lib/storage/sync.mjs.
+ * Requires confirm=true guards on destructive operations (reset, delete).
+ */
+import { resolve } from 'node:path';
+import { deleteIngestedArtifacts, getStorageStatus, inferProjectName, purgeExpiredData, resetStorage } from '../../storage/admin.mjs';
+import { syncFileStateToSql } from '../../storage/sync.mjs';
+
+export async function storageStatus(args) {
+  const cwd = args.cwd ? resolve(String(args.cwd)) : process.cwd();
+  const project = args.project ? String(args.project) : inferProjectName(cwd);
+  return getStorageStatus(cwd, { env: process.env, project });
+}
+
+export async function storageSync(args) {
+  const cwd = args.cwd ? resolve(String(args.cwd)) : process.cwd();
+  const project = args.project ? String(args.project) : inferProjectName(cwd);
+  const syncResult = await syncFileStateToSql(cwd, { env: process.env, project });
+
+  // Run retention purge on each sync so expired data is cleaned automatically.
+  let purge = null;
+  try {
+    purge = await purgeExpiredData(cwd, { env: process.env, project });
+  } catch { /* best effort */ }
+
+  return purge && purge.status !== 'skipped' ? { ...syncResult, retention: purge } : syncResult;
+}
+
+export async function storageReset(args) {
+  const cwd = args.cwd ? resolve(String(args.cwd)) : process.cwd();
+  const project = args.project ? String(args.project) : inferProjectName(cwd);
+  if (args.confirm !== true) {
+    return { error: 'storage_reset requires confirm=true' };
+  }
+  return resetStorage(cwd, {
+    env: process.env,
+    project,
+    resetSql: args.reset_sql !== false,
+    resetVector: args.reset_vector !== false,
+    resetIngested: args.reset_ingested === true,
+    confirm: true,
+  });
+}
+
+export function deleteIngestedArtifactsTool(args) {
+  const cwd = args.cwd ? resolve(String(args.cwd)) : process.cwd();
+  if (args.confirm !== true) {
+    return { error: 'delete_ingested_artifacts requires confirm=true' };
+  }
+  const files = Array.isArray(args.files)
+    ? args.files.map((value) => String(value))
+    : [];
+  try {
+    return deleteIngestedArtifacts(cwd, { files, confirm: true });
+  } catch (error) {
+    return { error: error.message ?? String(error) };
+  }
+}