@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/extensions/manifests/postgres.manifest.json

@@ -0,0 +1,12 @@
+{
+  "id": "postgres",
+  "version": "1.0.0",
+  "kind": "queue",
+  "capabilities": ["enqueue", "claim", "lease", "reclaim"],
+  "secretEnvKeys": ["CONSTRUCT_DATABASE_URL"],
+  "operations": ["enqueue", "claim", "heartbeat", "complete", "skip", "reopen"],
+  "securityClassification": "trusted",
+  "owner": "construct-core",
+  "compatVersion": 1,
+  "installSource": "optional-dependency"
+}

package/lib/extensions/manifests/salesforce.manifest.json

@@ -0,0 +1,12 @@
+{
+  "id": "salesforce",
+  "version": "1.0.0",
+  "kind": "data-source",
+  "capabilities": ["read", "search"],
+  "secretEnvKeys": ["SALESFORCE_INSTANCE_URL", "SALESFORCE_ACCESS_TOKEN"],
+  "operations": ["read", "search"],
+  "securityClassification": "trusted",
+  "owner": "construct-core",
+  "compatVersion": 1,
+  "installSource": "builtin"
+}

package/lib/extensions/manifests/slack.manifest.json

@@ -0,0 +1,58 @@
+{
+  "id": "slack",
+  "version": "1.0.0",
+  "kind": "data-source",
+  "capabilities": ["read", "search"],
+  "secretEnvKeys": ["SLACK_BOT_TOKEN", "SLACK_USER_TOKEN"],
+  "operations": ["read", "search"],
+  "securityClassification": "trusted",
+  "owner": "construct-core",
+  "compatVersion": 1,
+  "installSource": "builtin",
+  "sourceTarget": {
+    "provider": "slack",
+    "selector": {
+      "field": "channel",
+      "pattern": null,
+      "patternTransform": "trim",
+      "hint": "required Slack channel name or ID",
+      "normalize": "trimHash"
+    },
+    "secondaryField": {
+      "field": "intent",
+      "enum": ["internal", "risk", "decision", "external", "how-to"],
+      "hint": "must be one of",
+      "default": "internal"
+    },
+    "signature": { "template": "slack:channel:{value}:intent:{intent}", "valueMode": "lowerOrEmpty" },
+    "legacyEnv": { "vars": ["SLACK_CHANNELS", "SLACK_CHANNEL"], "parse": "slackChannelColon" },
+    "aliases": { "strategy": "simple", "displayPrefix": "Slack", "catchAll": false },
+    "embed": {
+      "mode": "groupBy",
+      "groupField": "intent",
+      "groupDefault": "internal",
+      "valueField": "channels",
+      "valueKind": "array",
+      "refs": ["messages"],
+      "oldest": 86400,
+      "limit": 50
+    },
+    "embedFilters": {
+      "valueField": "channels",
+      "valueKind": "array",
+      "defaultRefs": ["messages"],
+      "extraFilterKeys": ["oldest"],
+      "defaultLimit": 50,
+      "includeSecondaryField": true
+    },
+    "demandFetch": {
+      "targetRefs": ["messages"],
+      "targetOptsField": "channels",
+      "targetOptsKind": "array",
+      "targetExtraFilterKeys": ["oldest"],
+      "targetOldestDefault": 86400,
+      "targetDefaultLimit": 50,
+      "querySupported": false
+    }
+  }
+}

package/lib/extensions/manifests/whisper.manifest.json

@@ -0,0 +1,36 @@
+{
+  "id": "whisper",
+  "version": "1.0.0",
+  "kind": "ingestion-provider",
+  "capabilities": ["audio-transcription"],
+  "docs": "Local audio/video transcription via whisper.cpp (Metal-accelerated on macOS). No npm dependency — the binary and model weights are provisioned outside npm and probed, not assumed.",
+  "owner": "construct-core",
+  "compatVersion": 1,
+  "installSource": "system-binary",
+  "installDependencies": [],
+  "installProbe": {
+    "kind": "binary-on-path",
+    "candidates": ["whisper-cli", "whisper-cpp", "main"],
+    "runtimeDirEnv": "CONSTRUCT_WHISPER_RUNTIME_DIR",
+    "defaultRuntimeDir": ".cx/runtime/whisper",
+    "cachedBinary": "bin/whisper-cli",
+    "description": "which(1) lookup for whisper-cli/whisper-cpp/main on PATH, falling back to a cached binary at <runtimeDir>/bin/whisper-cli."
+  },
+  "healthCheck": {
+    "kind": "subprocess-version",
+    "command": "<resolvedBinary>",
+    "args": ["--help"],
+    "timeoutMs": 10000,
+    "description": "whisper.cpp CLI has no --version flag; health runs the binary with --help and treats a clean exit (or the expected usage banner) as healthy. A missing binary or non-zero exit is unhealthy."
+  },
+  "degradation": {
+    "chain": [
+      { "id": "whisper", "mode": "sidecar", "description": "Local ASR transcription via whisper.cpp." },
+      { "id": "refuse", "mode": "error", "description": "No transcription backend available; audio/video ingest fails loud (ASR_REQUIRED) with an install hint (brew install whisper-cpp)." }
+    ],
+    "terminal": "refuse",
+    "resultMarking": "degraded"
+  },
+  "removalStatus": "active",
+  "securityClassification": "trusted"
+}

package/lib/extensions/validate.mjs

@@ -0,0 +1,175 @@
+/**
+ * lib/extensions/validate.mjs — extension manifest validator.
+ *
+ * Validates a plain-JS manifest object against the canonical schema defined in
+ * manifest-schema.mjs. All errors are returned in a structured result; this
+ * function never throws. Error messages are single-line, actionable, and
+ * prefixed with the filePath (when provided) so consumers can surface them
+ * directly to users.
+ */
+
+import {
+  MANIFEST_KINDS, REQUIRED_FIELDS, OPTIONAL_FIELDS, COMPAT_VERSION,
+  ALLOWED_SECRET_ENV_PREFIXES, ESCALATION_SENSITIVE_KINDS,
+  KNOWN_REQUESTABLE_TOOL_GRANTS, BUILTIN_SPECIALIST_IDS,
+} from './manifest-schema.mjs';
+
+/** Basic semver pattern: MAJOR.MINOR.PATCH with optional pre-release/build metadata. */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].+)?$/;
+
+/** Valid id characters: lowercase alphanumeric, hyphens, dots, forward slashes. */
+const ID_RE = /^[a-z0-9\-./]+$/;
+
+/**
+ * validateManifest(manifest, { filePath, strict } = {})
+ *
+ * Returns { valid: true } on success, or { valid: false, errors: string[] }
+ * on failure. Every error string is a self-contained, single-line description
+ * of the problem. The filePath prefix is included in every error so callers
+ * can surface messages without additional decoration.
+ *
+ * Checks performed (in order):
+ *   1. Required fields are present.
+ *   2. `kind` is one of the canonical MANIFEST_KINDS.
+ *   3. `version` matches the semver pattern.
+ *   4. `id` is a non-empty string matching [a-z0-9-./]+.
+ *   5. `compatVersion` (if present) does not exceed COMPAT_VERSION.
+ *
+ * When strict is true, additional hardening checks are applied:
+ *   6. No unknown fields (fields outside REQUIRED_FIELDS + OPTIONAL_FIELDS).
+ *   7. secretEnvKeys entries must start with an allowed prefix.
+ *   8. For escalation-sensitive kinds, toolGrantsRequested must be in
+ *      KNOWN_REQUESTABLE_TOOL_GRANTS.
+ *   9. Prompts targeting built-in specialists without override:true are
+ *      rejected (prompt shadowing prevention).
+ *  10. owner values starting with 'cx-' must be known built-in specialist ids.
+ *
+ * @param {unknown} manifest - The parsed manifest object to validate.
+ * @param {{ filePath?: string, strict?: boolean }} [opts]
+ * @returns {{ valid: true } | { valid: false, errors: string[] }}
+ */
+export function validateManifest(manifest, { filePath, strict = false } = {}) {
+  const prefix = filePath ? `${filePath}: ` : '';
+  const errors = [];
+
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return { valid: false, errors: [`${prefix}manifest must be a JSON object`] };
+  }
+
+  // Required fields
+  for (const field of REQUIRED_FIELDS) {
+    if (!(field in manifest) || manifest[field] === undefined || manifest[field] === null) {
+      errors.push(`${prefix}missing required field: ${field}`);
+    }
+  }
+
+  // If required fields are missing we may not have meaningful values for the
+  // semantic checks — collect what we can, but short-circuit gracefully.
+
+  // kind check (only if kind is present — otherwise already flagged above)
+  if ('kind' in manifest && manifest.kind !== undefined && manifest.kind !== null) {
+    if (!MANIFEST_KINDS.includes(manifest.kind)) {
+      errors.push(
+        `${prefix}unknown kind '${manifest.kind}'; expected one of: ${MANIFEST_KINDS.join(', ')}`
+      );
+    }
+  }
+
+  // version semver check
+  if ('version' in manifest && manifest.version !== undefined && manifest.version !== null) {
+    if (typeof manifest.version !== 'string' || !SEMVER_RE.test(manifest.version)) {
+      errors.push(`${prefix}version must be a semver string`);
+    }
+  }
+
+  // id format check
+  if ('id' in manifest && manifest.id !== undefined && manifest.id !== null) {
+    if (typeof manifest.id !== 'string' || manifest.id.length === 0) {
+      errors.push(`${prefix}id must be a non-empty string`);
+    } else if (!ID_RE.test(manifest.id)) {
+      errors.push(`${prefix}id must match [a-z0-9-./]+ (got '${manifest.id}')`);
+    }
+  }
+
+  // Forward-compat guard
+  if (
+    manifest.compatVersion !== undefined &&
+    manifest.compatVersion !== null
+  ) {
+    if (typeof manifest.compatVersion !== 'number' || !Number.isInteger(manifest.compatVersion)) {
+      errors.push(`${prefix}compatVersion must be an integer`);
+    } else if (manifest.compatVersion > COMPAT_VERSION) {
+      errors.push(
+        `${prefix}compatVersion ${manifest.compatVersion} exceeds supported version ${COMPAT_VERSION}; upgrade Construct to use this manifest`
+      );
+    }
+  }
+
+  // Strict-mode hardening checks
+  if (strict) {
+    const knownFields = new Set([...REQUIRED_FIELDS, ...OPTIONAL_FIELDS]);
+
+    // Unknown field rejection
+    for (const key of Object.keys(manifest)) {
+      if (key.startsWith('_')) continue;
+      if (!knownFields.has(key)) {
+        errors.push(`${prefix}unknown field '${key}' in strict mode`);
+      }
+    }
+
+    // Secret env key allowlist
+    if (manifest.secretEnvKeys && Array.isArray(manifest.secretEnvKeys)) {
+      for (const key of manifest.secretEnvKeys) {
+        const allowed = ALLOWED_SECRET_ENV_PREFIXES.some(p => key.startsWith(p));
+        if (!allowed) {
+          errors.push(`${prefix}secretEnvKey '${key}' is not allowed; must start with one of: ${ALLOWED_SECRET_ENV_PREFIXES.join(', ')}`);
+        }
+      }
+    }
+
+    // Capability escalation checks for sensitive kinds
+    if (manifest.kind && ESCALATION_SENSITIVE_KINDS.includes(manifest.kind)) {
+      if (manifest.toolGrantsRequested && Array.isArray(manifest.toolGrantsRequested)) {
+        for (const grant of manifest.toolGrantsRequested) {
+          if (!KNOWN_REQUESTABLE_TOOL_GRANTS.includes(grant)) {
+            errors.push(`${prefix}toolGrantsRequested '${grant}' is not a known tool grant`);
+          }
+        }
+      }
+    }
+
+    // Builtin prompt shadowing prevention
+    if (manifest.prompts && Array.isArray(manifest.prompts)) {
+      for (const [i, prompt] of manifest.prompts.entries()) {
+        if (
+          prompt &&
+          typeof prompt.specialist === 'string' &&
+          BUILTIN_SPECIALIST_IDS.includes(prompt.specialist) &&
+          !prompt.override
+        ) {
+          errors.push(
+            `${prefix}prompts[${i}]: specialist '${prompt.specialist}' is a built-in; set "override": true to shadow`
+          );
+        }
+      }
+    }
+
+    // Owner validation — cx- prefixed owners must be known builtins
+    if (
+      manifest.owner &&
+      typeof manifest.owner === 'string' &&
+      manifest.owner.startsWith('cx-')
+    ) {
+      if (!BUILTIN_SPECIALIST_IDS.includes(manifest.owner)) {
+        errors.push(
+          `${prefix}owner '${manifest.owner}' starts with 'cx-' but is not a known built-in specialist id`
+        );
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+  return { valid: true };
+}

package/lib/features.mjs

@@ -19,8 +19,12 @@ function getFeaturesFile(overrides = {}) {
   return overrides.featuresFile ?? join(configDir(getHomeDir(overrides)), 'features.json');
 }
 
-function getClaudeSettingsPath(overrides = {}) {
-  return overrides.claudeSettingsPath ?? join(getHomeDir(overrides), '.claude', 'settings.json');
+// Claude Code's user-scope MCP servers live in ~/.claude.json's top-level
+// `mcpServers`, not in settings.json (confirmed against
+// code.claude.com/docs/en/mcp and live `claude mcp list` repro, construct-ranh).
+
+function getClaudeUserConfigPath(overrides = {}) {
+  return overrides.claudeUserConfigPath ?? join(getHomeDir(overrides), '.claude.json');
 }
 
 function readEnabledFeatures(overrides = {}) {
@@ -39,11 +43,11 @@ function isFeatureEnabled(id, overrides = {}) {
   return (data.enabled ?? []).includes(id);
 }
 
-function readClaudeSettings(overrides = {}) {
-  const claudeSettings = getClaudeSettingsPath(overrides);
-  if (!existsSync(claudeSettings)) return null;
+function readClaudeUserConfig(overrides = {}) {
+  const claudeUserConfig = getClaudeUserConfigPath(overrides);
+  if (!existsSync(claudeUserConfig)) return null;
   try {
-    return JSON.parse(readFileSync(claudeSettings, 'utf8'));
+    return JSON.parse(readFileSync(claudeUserConfig, 'utf8'));
   } catch {
     return null;
   }
@@ -194,9 +198,9 @@ function getMcpPlatforms(mcp, overrides = {}) {
     platforms.push('Claude.ai');
   }
 
-  // --- Claude Code: user settings (~/.claude/settings.json) ---
-  const claudeSettings = readClaudeSettings(overrides);
-  if (getHostSupport(mcp, 'claude').mode === 'managed' && configHasAny(claudeSettings?.mcpServers, matchIds)) {
+  // --- Claude Code: user scope (~/.claude.json's top-level mcpServers) ---
+  const claudeUserConfig = readClaudeUserConfig(overrides);
+  if (getHostSupport(mcp, 'claude').mode === 'managed' && configHasAny(claudeUserConfig?.mcpServers, matchIds)) {
     platforms.push('Claude Code');
   }
 

package/lib/flows/checkpoint.mjs

@@ -0,0 +1,184 @@
+/**
+ * lib/flows/checkpoint.mjs — durable per-step checkpointing and resume for flow runs.
+ *
+ * Persists a Run after every completed step under the project's machine-scoped
+ * state root (ADR-0066) at `runtime/flows/runs/<runId>.json`, atomic write via
+ * temp-file-then-rename — the same pattern lib/orchestration/run-store.mjs uses
+ * for orchestration runs. A run's Set/Map fields (completed, joinProgress,
+ * usage) are serialized to plain arrays and reconstructed on load; the flow
+ * definition itself (its run/router functions) is never persisted — a
+ * resuming caller supplies the same flow object it would use to start a run,
+ * exactly like loadFlow's `handlers` pattern for JSON flows. A checkpoint
+ * records which flow id it was written under; resuming against a different
+ * flow id throws rather than silently replaying history against the wrong
+ * step graph.
+ *
+ * Idempotent re-entry: runCheckpointed() checkpoints strictly AFTER each
+ * advanceRun() call, so a step already reflected in a saved checkpoint's
+ * `completed` set is never in that checkpoint's `frontier` and will not
+ * re-run on resume — the frontier only ever holds not-yet-completed steps,
+ * which is a property of the Run shape itself, not something this module adds.
+ * The remaining window — a crash between a step's run() executing and the
+ * following checkpoint write landing — is closed by authoring convention, not
+ * an engine guarantee: a step's run() must be idempotent under at-least-once
+ * execution (pure computation, or a naturally idempotent side effect such as
+ * an upsert), the same constraint the engine already implies by recording
+ * delegation intent rather than performing it (engine.mjs's workerBackend
+ * handling). A step that must perform an exactly-once side effect belongs
+ * outside the engine, driven by its recorded delegation, not inside run().
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { resolveStateDir } from '../state-root.mjs';
+import { createRun, advanceRun } from './engine.mjs';
+import { RUN_STATUS } from './constants.mjs';
+
+export class FlowCheckpointError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'FlowCheckpointError';
+    this.code = 'FLOW_CHECKPOINT_MISMATCH';
+  }
+}
+
+let writeCounter = 0;
+
+export function runsDir(cwd = process.cwd()) {
+  return resolveStateDir(cwd, 'runtime', 'flows', 'runs', { ensureDir: false });
+}
+
+function checkpointPath(cwd, runId) {
+  return join(runsDir(cwd), `${runId}.json`);
+}
+
+function atomicWriteJson(filePath, value) {
+  writeCounter = (writeCounter + 1) % 100000;
+  const tmp = `${filePath}.${process.pid}.${writeCounter}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  renameSync(tmp, filePath);
+}
+
+function serializeRun(run) {
+  return {
+    state: run.state,
+    frontier: [...run.frontier],
+    completed: [...run.completed],
+    joinProgress: [...run.joinProgress.entries()].map(([step, satisfied]) => [step, [...satisfied]]),
+    usage: [...run.usage.entries()],
+    history: run.history,
+    status: run.status,
+    error: run.error,
+  };
+}
+
+function deserializeRun(flow, data) {
+  return {
+    flow,
+    state: data.state,
+    frontier: [...(data.frontier || [])],
+    completed: new Set(data.completed || []),
+    joinProgress: new Map((data.joinProgress || []).map(([step, satisfied]) => [step, new Set(satisfied)])),
+    usage: new Map(data.usage || []),
+    history: data.history || [],
+    status: data.status,
+    error: data.error || null,
+  };
+}
+
+/**
+ * Persist a run's current state to its checkpoint file. Overwrites any prior
+ * checkpoint for the same runId — a checkpoint is the run's latest snapshot,
+ * not a history of every tick (history already lives on the run itself).
+ */
+export function checkpointRun(cwd, runId, flow, run) {
+  const dir = runsDir(cwd);
+  mkdirSync(dir, { recursive: true });
+  atomicWriteJson(checkpointPath(cwd, runId), {
+    runId,
+    flowId: flow.id ?? null,
+    updatedAt: new Date().toISOString(),
+    run: serializeRun(run),
+  });
+}
+
+/**
+ * Read a checkpoint's raw persisted shape ({runId, flowId, updatedAt, run}),
+ * or null when no checkpoint exists or the file is corrupt.
+ */
+export function loadCheckpoint(cwd, runId) {
+  const file = checkpointPath(cwd, runId);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reconstruct a Run from its checkpoint against the given flow, or null when
+ * no checkpoint exists. Throws FlowCheckpointError when the checkpoint was
+ * recorded against a different flow id than the one supplied — resuming a
+ * run against the wrong step graph would silently reinterpret its history.
+ */
+export function resumeRun(cwd, runId, flow) {
+  const checkpoint = loadCheckpoint(cwd, runId);
+  if (!checkpoint) return null;
+  if (flow.id && checkpoint.flowId && flow.id !== checkpoint.flowId) {
+    throw new FlowCheckpointError(`checkpoint "${runId}" was recorded against flow "${checkpoint.flowId}", not "${flow.id}"`);
+  }
+  return deserializeRun(flow, checkpoint.run);
+}
+
+/**
+ * Start a new run and checkpoint it immediately, so a resume attempted before
+ * the first tick still finds a valid checkpoint rather than nothing.
+ */
+export function startRun(cwd, runId, flow, initialState = {}) {
+  const run = createRun(flow, initialState);
+  checkpointRun(cwd, runId, flow, run);
+  return run;
+}
+
+/**
+ * Advance a checkpointed run by exactly one tick: resume from the last
+ * checkpoint when one exists, otherwise start fresh from initialState, then
+ * run a single advanceRun() and checkpoint the result. Unlike
+ * runCheckpointed(), this never loops to completion — each call surfaces
+ * exactly the step that tick just completed, which is what a caller driving
+ * a run one delegation at a time (e.g. lib/orchestration/delegation-flow.mjs)
+ * needs: the current step, not the whole remaining chain. A run already at a
+ * terminal status is returned as-is, not re-driven.
+ */
+export async function tickCheckpointed(cwd, runId, flow, initialState = {}) {
+  let run = resumeRun(cwd, runId, flow) ?? startRun(cwd, runId, flow, initialState);
+  if (run.status === RUN_STATUS.RUNNING) {
+    run = await advanceRun(run);
+    checkpointRun(cwd, runId, flow, run);
+  }
+  return run;
+}
+
+/**
+ * Drive a flow to completion one checkpointed tick at a time: resume from the
+ * last checkpoint when one exists, otherwise start fresh from initialState.
+ * Every tick's result is checkpointed before the loop continues, so a crash
+ * at any point resumes from the most recently completed step, never earlier
+ * and never mid-step.
+ */
+export async function runCheckpointed(cwd, runId, flow, initialState = {}, { maxSteps = 10000 } = {}) {
+  let run = resumeRun(cwd, runId, flow) ?? startRun(cwd, runId, flow, initialState);
+  let steps = 0;
+  while (run.status === RUN_STATUS.RUNNING && steps < maxSteps) {
+    run = await advanceRun(run);
+    checkpointRun(cwd, runId, flow, run);
+    steps += 1;
+  }
+  if (run.status === RUN_STATUS.RUNNING && steps >= maxSteps) {
+    run = { ...run, status: RUN_STATUS.ERROR, error: { code: 'MAX_STEPS_EXCEEDED', message: `flow exceeded ${maxSteps} steps without reaching a terminal state` } };
+    checkpointRun(cwd, runId, flow, run);
+  }
+  return run;
+}

package/lib/flows/constants.mjs

@@ -0,0 +1,27 @@
+/**
+ * lib/flows/constants.mjs — shared sentinels and status enums for the flow engine.
+ *
+ * TERMINAL is a plain string sentinel (not a Symbol) so a router's return value
+ * survives JSON serialization unchanged, matching the future checkpoint/resume
+ * requirement that a run's next-step pointer be persistable as-is.
+ */
+
+export const TERMINAL = '@@flow/terminal';
+
+export const WORKER_BACKENDS = Object.freeze(['inline', 'provider', 'host']);
+
+export const STEP_STATUS = Object.freeze({
+  DONE: 'done',
+  ERROR: 'error',
+  BUDGET_EXHAUSTED: 'budget-exhausted',
+  INVALID_STATE: 'invalid-state',
+});
+
+export const RUN_STATUS = Object.freeze({
+  RUNNING: 'running',
+  COMPLETED: 'completed',
+  ERROR: 'error',
+  BUDGET_EXHAUSTED: 'budget-exhausted',
+});
+
+export const JOIN_MODES = Object.freeze(['all', 'any']);