@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/providers/instance-config.mjs

@@ -0,0 +1,215 @@
+/**
+ * lib/providers/instance-config.mjs — provider instance config persistence + validation.
+ *
+ * Backs `construct provider add|configure` (LMCP-B12). An "instance config"
+ * is the per-project, per-provider-id settings block (Jira project keys,
+ * GitHub repo, Slack channel, plus the ADR-0060 `filter` block) — distinct
+ * from `lib/providers/registry.mjs`'s `.cx/providers.json`, which registers
+ * *which provider module* answers for an id, not its call-time config.
+ *
+ * Storage: one JSON file per provider id at `<rootDir>/.cx/providers/<id>.json`,
+ * `{ providerId, config, updatedAt }`. Human-reviewable, git-trackable, and
+ * namespaced per id so concurrent `configure` calls on different providers
+ * never collide on one shared file.
+ *
+ * Validation walks the provider's `configSchema` (a JSON-Schema draft
+ * 2020-12 subset: `type`, `properties`, `required`, `enum`, `pattern`,
+ * `minimum`/`maximum`, `additionalProperties`) by hand — no schema engine
+ * dependency, mirroring the hand-rolled approach `contract.mjs` already
+ * takes for the ADR-0060 filter block. `config.filter`, when present, is
+ * delegated to `validateFilterConfig()` from `contract.mjs` (LMCP-B11) so
+ * the two validators can never drift on filter-block semantics. Every
+ * rejection carries a JSON-Pointer-style path (`config.<field>` or
+ * `config.filter.<...>`) so the caller can name the offending key.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { validateFilterConfig } from './contract.mjs';
+import { SCOPE_KEYS, PREDICATE_KEYS } from './filter-schema.mjs';
+
+// `filter.scope.*` and most `filter.predicates.*` leaves are always arrays
+// per the ADR-0060 grammar (filter-schema.mjs); `updatedSince` is the one
+// scalar-string predicate. A single `--filter.scope.projects ABC` must
+// therefore land as `["ABC"]`, not the bare string, even on first occurrence.
+const ALWAYS_ARRAY_FILTER_LEAVES = new Set([
+  ...SCOPE_KEYS.map((k) => `filter.scope.${k}`),
+  ...PREDICATE_KEYS.filter((k) => k !== 'updatedSince').map((k) => `filter.predicates.${k}`),
+]);
+
+export function instanceConfigPath(rootDir, providerId) {
+  return join(rootDir, '.cx', 'providers', `${providerId}.json`);
+}
+
+export function readInstanceConfig(rootDir, providerId) {
+  const filePath = instanceConfigPath(rootDir, providerId);
+  if (!existsSync(filePath)) return null;
+  return JSON.parse(readFileSync(filePath, 'utf8'));
+}
+
+export function writeInstanceConfig(rootDir, providerId, config) {
+  const filePath = instanceConfigPath(rootDir, providerId);
+  mkdirSync(dirname(filePath), { recursive: true });
+  const record = { providerId, config, updatedAt: new Date().toISOString() };
+  writeFileSync(filePath, JSON.stringify(record, null, 2) + '\n');
+  return record;
+}
+
+/**
+ * Build the default config object from a JSON-Schema `properties` map:
+ * every property that declares a `default` is seeded with it. Properties
+ * without a default are omitted — `provider add` scaffolds only what the
+ * schema actually commits to, not placeholder nulls.
+ */
+export function defaultsFromSchema(configSchema) {
+  const defaults = {};
+  const properties = configSchema?.properties || {};
+  for (const [key, propSchema] of Object.entries(properties)) {
+    if (propSchema && Object.prototype.hasOwnProperty.call(propSchema, 'default')) {
+      defaults[key] = propSchema.default;
+    }
+  }
+  return defaults;
+}
+
+function typeMatches(value, type) {
+  switch (type) {
+    case 'string': return typeof value === 'string';
+    case 'number': return typeof value === 'number' && Number.isFinite(value);
+    case 'integer': return typeof value === 'number' && Number.isInteger(value);
+    case 'boolean': return typeof value === 'boolean';
+    case 'array': return Array.isArray(value);
+    case 'object': return value !== null && typeof value === 'object' && !Array.isArray(value);
+    default: return true;
+  }
+}
+
+/**
+ * Validate one property value against its JSON-Schema property descriptor.
+ * Returns an array of error strings (empty when valid); each string is
+ * prefixed with `path` so nested callers can build a JSON-Pointer trail.
+ */
+function validateProperty(path, value, propSchema) {
+  const errors = [];
+  if (!propSchema) return errors;
+
+  if (propSchema.enum && !propSchema.enum.includes(value)) {
+    errors.push(`${path}: must be one of [${propSchema.enum.join(', ')}], got ${JSON.stringify(value)}`);
+    return errors;
+  }
+
+  if (propSchema.type && !typeMatches(value, propSchema.type)) {
+    errors.push(`${path}: must be of type ${propSchema.type}, got ${JSON.stringify(value)}`);
+    return errors;
+  }
+
+  if (propSchema.pattern && typeof value === 'string' && !new RegExp(propSchema.pattern).test(value)) {
+    errors.push(`${path}: does not match pattern ${propSchema.pattern}`);
+  }
+
+  if (typeof value === 'number') {
+    if (propSchema.minimum !== undefined && value < propSchema.minimum) {
+      errors.push(`${path}: must be >= ${propSchema.minimum}, got ${value}`);
+    }
+    if (propSchema.maximum !== undefined && value > propSchema.maximum) {
+      errors.push(`${path}: must be <= ${propSchema.maximum}, got ${value}`);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate a merged instance config against a provider's declared
+ * `configSchema`, plus (when the config carries a `filter` key) the
+ * ADR-0060 filter block via `validateFilterConfig()`. Returns
+ * `{ valid: true }` or `{ valid: false, errors: string[] }` — never throws,
+ * so callers (CLI + tests) get a uniform result shape to report from.
+ *
+ * `filter` is accepted on every provider config regardless of whether the
+ * schema's `properties` declares it: the ADR-0060 block is a cross-cutting
+ * concern layered on top of the provider-specific schema, not a provider-
+ * specific property.
+ */
+export function validateInstanceConfig(providerId, configSchema, config = {}) {
+  const errors = [];
+  const schema = configSchema || {};
+  const properties = schema.properties || {};
+  const { filter, ...rest } = config || {};
+
+  for (const required of schema.required || []) {
+    if (!(required in rest)) {
+      errors.push(`config.${required}: required property missing`);
+    }
+  }
+
+  for (const [key, value] of Object.entries(rest)) {
+    const path = `config.${key}`;
+    if (!(key in properties)) {
+      if (schema.additionalProperties === false) {
+        errors.push(`${path}: unknown property (not declared in configSchema)`);
+      }
+      continue;
+    }
+    errors.push(...validateProperty(path, value, properties[key]));
+  }
+
+  if (filter !== undefined) {
+    try {
+      validateFilterConfig(providerId, filter);
+    } catch (err) {
+      errors.push(`config.filter: ${err.message}`);
+    }
+  }
+
+  if (errors.length > 0) return { valid: false, errors };
+  return { valid: true };
+}
+
+/**
+ * Apply `--key value` CLI overrides onto a base config object. Dotted keys
+ * (`scope.projects`) address nested objects; repeated flags for an array
+ * leaf (`filter.scope.projects`) accumulate rather than overwrite, so
+ * `--filter.scope.projects ABC --filter.scope.projects DEF` yields
+ * `["ABC", "DEF"]` in one `configure` call.
+ */
+export function applyOverrides(base, overrides) {
+  const result = JSON.parse(JSON.stringify(base || {}));
+
+  // Accumulation only fires for a keyPath repeated within *this* override
+  // batch — a pre-existing base value (a schema default or a prior
+  // `configure` call) is a plain overwrite, never folded into an array.
+  const touched = new Set();
+
+  for (const { keyPath, value } of overrides) {
+    const segments = keyPath.split('.');
+    let cursor = result;
+    for (let i = 0; i < segments.length - 1; i++) {
+      const segment = segments[i];
+      if (typeof cursor[segment] !== 'object' || cursor[segment] === null || Array.isArray(cursor[segment])) {
+        cursor[segment] = {};
+      }
+      cursor = cursor[segment];
+    }
+    const leaf = segments[segments.length - 1];
+    const parsed = parseFlagValue(value);
+    if (touched.has(keyPath)) {
+      cursor[leaf] = Array.isArray(cursor[leaf]) ? [...cursor[leaf], parsed] : [cursor[leaf], parsed];
+    } else if (ALWAYS_ARRAY_FILTER_LEAVES.has(keyPath)) {
+      cursor[leaf] = [parsed];
+      touched.add(keyPath);
+    } else {
+      cursor[leaf] = parsed;
+      touched.add(keyPath);
+    }
+  }
+  return result;
+}
+
+function parseFlagValue(raw) {
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (raw !== '' && !Number.isNaN(Number(raw))) return Number(raw);
+  return raw;
+}

package/lib/providers/op-locate.mjs

@@ -0,0 +1,96 @@
+/**
+ * lib/providers/op-locate.mjs — resolve the 1Password `op` CLI binary once.
+ *
+ * A GUI-launched MCP host (OpenCode, Claude Desktop, Cursor) spawns
+ * `node lib/mcp/server.mjs` with a minimal PATH that omits Homebrew, so a bare
+ * `spawnSync('op', …)` ENOENTs and `op` is misreported as not installed despite
+ * being present at a well-known path like /opt/homebrew/bin/op. Resolution walks three
+ * tiers — the process PATH (cheap, no shell), then a login-shell probe that re-runs
+ * the user's rc/profile (macOS path_helper included, the way credential-bootstrap
+ * recovers PATH), then well-known install dirs — and caches the absolute path for
+ * the process lifetime. Every op-invocation site (secret-resolver, op-run,
+ * credential-bootstrap) resolves through here so PATH semantics stay consistent
+ * across call sites. env/runShell/wellKnown are injectable so tests exercise each
+ * tier without a real 1Password install.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const WELL_KNOWN_POSIX = ['/opt/homebrew/bin/op', '/usr/local/bin/op', '/usr/bin/op'];
+
+function wellKnownWin32() {
+  const local = process.env.LOCALAPPDATA;
+  return [
+    local ? path.join(local, 'Microsoft', 'WinGet', 'Links', 'op.exe') : null,
+    'C:\\ProgramData\\chocolatey\\bin\\op.exe',
+  ].filter(Boolean);
+}
+
+function defaultWellKnown() {
+  return process.platform === 'win32' ? wellKnownWin32() : WELL_KNOWN_POSIX;
+}
+
+let cached;
+
+function isFile(candidate) {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// Scan the process PATH for `op` without spawning a shell — the common case where
+// PATH is already correct resolves here at no cost.
+
+function scanProcessPath(env) {
+  const dirs = String(env?.PATH || '').split(path.delimiter).filter(Boolean);
+  const names = process.platform === 'win32' ? ['op.exe', 'op.cmd', 'op.bat'] : ['op'];
+  for (const dir of dirs) {
+    for (const name of names) {
+      const candidate = path.join(dir, name);
+      if (isFile(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+// Login-shell probe: `sh -lc 'command -v op'` re-runs the user's shell init, which
+// on macOS is where path_helper adds Homebrew — recovering the PATH a GUI-launched
+// child never inherited. `where op` is the Windows analogue.
+
+function defaultRunShell() {
+  if (process.platform === 'win32') {
+    const r = spawnSync('where', ['op'], { encoding: 'utf8', timeout: 3000 });
+    return r.status === 0 ? String(r.stdout || '').split(/\r?\n/)[0].trim() : '';
+  }
+  const r = spawnSync('sh', ['-lc', 'command -v op'], { encoding: 'utf8', timeout: 3000 });
+  return r.status === 0 ? String(r.stdout || '').trim() : '';
+}
+
+/**
+ * Resolve the `op` binary (process PATH → login-shell PATH → well-known dirs),
+ * returning an absolute path or null. Cached for the process lifetime; pass
+ * fresh:true to bypass the cache. env/runShell/wellKnown are injectable for tests.
+ */
+export function locateOpBinary({ env = process.env, runShell = defaultRunShell, wellKnown = defaultWellKnown(), fresh = false } = {}) {
+  if (!fresh && cached !== undefined) return cached;
+
+  const onPath = scanProcessPath(env);
+  if (onPath) return (cached = onPath);
+
+  const viaShell = runShell();
+  if (viaShell && isFile(viaShell)) return (cached = viaShell);
+
+  for (const candidate of wellKnown) {
+    if (candidate && isFile(candidate)) return (cached = candidate);
+  }
+
+  return (cached = null);
+}
+
+export function __resetOpLocateCache() {
+  cached = undefined;
+}

package/lib/providers/op-run.mjs

@@ -1,13 +1,21 @@
 /**
- * lib/providers/op-run.mjs — optionally launch a child under 1Password `op run`.
+ * lib/providers/op-run.mjs — optionally launch Construct under 1Password `op run`.
  *
- * When CONSTRUCT_OP_ENV_FILE points to an `op run` env-file (KEY=op://… lines)
- * and the `op` CLI is installed, long-lived Construct services are spawned through
- * `op run --env-file <file> -- <cmd>`, so op:// references resolve once at startup
- * into the process env. lib/service-manager.mjs calls wrapWithOpRun at each service
- * spawn, so the memory server, OpenCode, the copilot bridge, the doctor daemon, and
- * the oracle daemon all inherit resolved provider keys without a per-invocation
- * shell wrapper. Masking stays on so resolved secrets are not echoed to service logs.
+ * When CONSTRUCT_OP_ENV_FILE points to an `op run` env-file (KEY=op://… lines) and
+ * the `op` CLI is installed, `construct dev` re-execs itself once under
+ * `op run --env-file <file> -- …` (maybeReExecUnderOpRun). Every op:// reference then
+ * resolves a single time at that stable parent — one biometric unlock — and the
+ * detached daemons the re-exec'd process spawns inherit the resolved keys through the
+ * parent env. A CONSTRUCT_OP_RUN_ACTIVE sentinel marks the wrapped process so nested
+ * launches inside it do not re-wrap and re-prompt.
+ *
+ * wrapWithOpRun stays the per-service fallback for daemons started outside the
+ * re-exec'd parent (a doctor or oracle restart from a hook), where no parent
+ * resolution has run; under the parent (sentinel set) it returns the command
+ * unchanged. The trade-off of resolving once at the parent: `op run` masks the
+ * parent's own stdout but not the separate log files of the daemons it detaches, so a
+ * daemon that echoes a key logs it unmasked (ADR-0049). The per-service fallback still
+ * masks the daemons it wraps directly.
  *
  * Strictly opt-in: with the var unset, the file missing, or `op` absent, the
  * command is returned unchanged and 1Password is never invoked. No other setup
@@ -17,6 +25,13 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
+import { locateOpBinary } from './op-locate.mjs';
+
+// Set on the process env when Construct has already re-exec'd under a parent `op run`.
+// Both the parent re-exec and the per-service wrap check it so a single resolution at
+// the top of the tree is never nested (which would re-prompt and double-resolve).
+
+export const OP_RUN_ACTIVE_ENV = 'CONSTRUCT_OP_RUN_ACTIVE';
 
 function expandHome(file, homeDir) {
   if (file === '~') return homeDir;
@@ -36,8 +51,10 @@ export function resolveOpEnvFile(env = process.env, homeDir = os.homedir()) {
 }
 
 export function opCliAvailable() {
+  const opPath = locateOpBinary();
+  if (!opPath) return false;
   try {
-    return spawnSync('op', ['--version'], { stdio: 'ignore', timeout: 3000 }).status === 0;
+    return spawnSync(opPath, ['--version'], { stdio: 'ignore', timeout: 3000 }).status === 0;
   } catch {
     return false;
   }
@@ -48,6 +65,10 @@ export function opCliAvailable() {
  * to the original command unchanged otherwise. `hasOp` is injectable for tests.
  */
 export function wrapWithOpRun(command, args = [], { env = process.env, homeDir = os.homedir(), hasOp = opCliAvailable } = {}) {
+  // A parent `op run` already resolved every reference into this env; wrapping again
+  // would spawn a nested op run that re-prompts, so hand back the command untouched.
+  if (env[OP_RUN_ACTIVE_ENV]) return { command, args, wrapped: false, envFile: null };
+
   const file = resolveOpEnvFile(env, homeDir);
   if (!file || !hasOp()) return { command, args, wrapped: false, envFile: null };
   return {
@@ -57,3 +78,37 @@ export function wrapWithOpRun(command, args = [], { env = process.env, homeDir =
     envFile: file,
   };
 }
+
+/**
+ * Re-exec the current process once under `op run` so every op:// reference in the
+ * env-file resolves a single time into the process env; the detached daemons the
+ * re-exec'd process then spawns inherit the resolved keys without their own op run.
+ * The blocking spawnSync makes the outer process a thin wrapper that exits with the
+ * inner status. Returns { reExecuted: false, reason } on every opt-out path — sentinel
+ * already set, no resolvable env-file, `op` absent, or a spawn error — so the caller
+ * falls through to the normal (per-service-wrap) launch unchanged. `spawnFn` and the
+ * process descriptors are injectable for tests.
+ */
+export function maybeReExecUnderOpRun({
+  argv = process.argv,
+  execPath = process.execPath,
+  env = process.env,
+  homeDir = os.homedir(),
+  hasOp = opCliAvailable,
+  spawnFn = spawnSync,
+} = {}) {
+  if (env[OP_RUN_ACTIVE_ENV]) return { reExecuted: false, reason: 'already-active' };
+  const file = resolveOpEnvFile(env, homeDir);
+  if (!file) return { reExecuted: false, reason: 'not-opted-in' };
+  if (!hasOp()) return { reExecuted: false, reason: 'op-missing' };
+
+  const scriptArgs = argv.slice(1);
+  const childEnv = { ...env, [OP_RUN_ACTIVE_ENV]: '1' };
+  const result = spawnFn('op', ['run', `--env-file=${file}`, '--', execPath, ...scriptArgs], {
+    stdio: 'inherit',
+    env: childEnv,
+  });
+  if (result?.error) return { reExecuted: false, reason: 'spawn-failed', error: result.error };
+  const code = typeof result?.status === 'number' ? result.status : 1;
+  return { reExecuted: true, code, envFile: file };
+}

package/lib/providers/registry.mjs

@@ -26,10 +26,20 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { assertProviderContract } from './contract.mjs';
 import { getBreaker } from './circuit-breaker.mjs';
 import { configDir } from '../config/xdg.mjs';
+import { loadManifestsFromDir, resolveManifestDirs } from '../extensions/loader.mjs';
+import { describeModelProviders } from '../models/catalog.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
-export const BUILT_INS = ['github', 'atlassian-jira', 'atlassian-confluence', 'slack', 'salesforce'];
+/**
+ * @deprecated Use manifest-driven provider discovery via resolveProviders() instead.
+ * Will be removed in a future version.
+ */
+export const BUILT_INS = (() => {
+  const { builtin: dir } = resolveManifestDirs();
+  const { manifests } = loadManifestsFromDir(dir);
+  return manifests.filter((m) => m.kind === 'data-source').map((m) => m.id);
+})();
 
 function readJsonIfExists(path) {
   try {
@@ -109,7 +119,13 @@ export async function resolveProviders({ rootDir = process.cwd(), env = process.
   const sources = {};
   const errors = [];
 
-  for (const id of BUILT_INS) {
+  const { builtin: builtinManifestDir } = resolveManifestDirs();
+  const { manifests: allManifests } = loadManifestsFromDir(builtinManifestDir);
+  const builtInIds = allManifests
+    .filter((m) => m.kind === 'data-source')
+    .map((m) => m.id);
+
+  for (const id of builtInIds) {
     try {
       const mod = await loadBuiltIn(id);
       if (!mod) continue;
@@ -145,6 +161,12 @@ export async function resolveProviders({ rootDir = process.cwd(), env = process.
   return { providers, sources, errors };
 }
 
+// kind='model' manifests (LMCP-B4) enumerate through this same registry but
+// are never instantiated as data-source contract instances — model provider
+// families keep their cache/poll/visibility logic in lib/models/catalog.mjs
+// and lib/model-router.mjs. This appends their manifest-derived summary rows
+// so `construct provider list` shows one merged surface across both kinds.
+
 export async function describeProviders({ rootDir = process.cwd(), env = process.env } = {}) {
   const { providers, sources, errors } = await resolveProviders({ rootDir, env });
   const summary = await Promise.all(
@@ -161,7 +183,8 @@ export async function describeProviders({ rootDir = process.cwd(), env = process
       };
     })
   );
-  return { summary, errors };
+  const modelSummary = describeModelProviders({ rootDir, env });
+  return { summary: [...summary, ...modelSummary], errors };
 }
 
 // Standalone validation for a candidate override entry: imports the package

package/lib/providers/secret-audit-wiring.mjs

@@ -20,6 +20,12 @@ export function enableSecretAuditTrail({ file } = {}) {
   setSecretAuditSink((event) => {
     if (event.event === 'secret.op_read') {
       if (event.cacheHit) return;
+
+      // Persisting the op:// ref (vault/item/field — not the value) into
+      // Construct's own audit JSONL is a recorded design decision (remediation
+      // plan Epic 6, construct-trxz.6), distinct from the mcp-platform-config.mjs
+      // prohibition on writing op:// refs into host-readable MCP config files.
+
       appendAuditRecord(
         {
           ts: new Date().toISOString(),