@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/providers/contract/adapters/jira/transport.mjs

@@ -0,0 +1,119 @@
+/**
+ * lib/providers/contract/adapters/jira/transport.mjs — real Jira Cloud REST
+ * v3 transport for the governed write adapter.
+ *
+ * Implements the `jiraTransport` shape governed-write.mjs depends on:
+ * `fetchCreatemeta`, `createIssue`, `createComment`, `searchIssues`. Kept
+ * separate from governed-write.mjs so tests can inject a fake transport
+ * (tests/fakes/fake-jira.mjs) without any network dependency, and separate
+ * from the read-oriented adapter in ./index.mjs so this write path never
+ * shares mutable state with the read path.
+ *
+ * Auth: API token via JIRA_URL + JIRA_EMAIL + JIRA_TOKEN env vars, or
+ * passed directly via config.
+ */
+
+import { AuthError, RateLimitError } from '../../errors.mjs';
+import { guardedFetch } from '../../../../net-guard.mjs';
+
+export function createJiraTransport(config = {}) {
+  const baseUrl = (config.baseUrl ?? process.env.JIRA_URL ?? '').replace(/\/$/, '');
+  const email = config.email ?? process.env.JIRA_EMAIL;
+  const token = config.token ?? process.env.JIRA_TOKEN;
+
+  if (!baseUrl || !email || !token) {
+    throw new AuthError(
+      'Jira transport requires JIRA_URL, JIRA_EMAIL, and JIRA_TOKEN (or config.baseUrl/email/token)',
+      { provider: 'jira' },
+    );
+  }
+
+  const auth = `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}`;
+
+  // Egress runs through the N7 guard (SSRF/rebinding). A self-hosted instance on
+  // a private address is the only legitimate private target, so it is an
+  // explicit, audited opt-in — never the default.
+  const allowPrivate = config.allowPrivateEgress ?? process.env.CONSTRUCT_NET_ALLOW_PRIVATE_EGRESS === '1';
+
+  async function request(path, { method = 'GET', body } = {}) {
+    const res = await guardedFetch(`${baseUrl}${path}`, {
+      method,
+      headers: {
+        Authorization: auth,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    }, { allowPrivate });
+
+    if (res.status === 429) {
+      const retryAfter = parseInt(res.headers.get('Retry-After') ?? '60', 10);
+      throw new RateLimitError('Jira rate limit hit', { provider: 'jira', retryAfter });
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      const err = new Error(`Jira API ${method} ${path} failed: ${res.status} ${text.slice(0, 300)}`);
+      err.status = res.status;
+      throw err;
+    }
+    if (res.status === 204) return null;
+    return res.json();
+  }
+
+  return {
+    async fetchCreatemeta(projectKey, issueTypeName) {
+      const params = new URLSearchParams({
+        projectKeys: projectKey,
+        issuetypeNames: issueTypeName,
+        expand: 'projects.issuetypes.fields',
+      });
+      return request(`/rest/api/3/issue/createmeta?${params.toString()}`);
+    },
+
+    async createIssue({ project, issueType, summary, description, labels, assignee }) {
+      const body = {
+        fields: {
+          project: { key: project },
+          issuetype: { name: issueType ?? 'Task' },
+          summary,
+          ...(description !== undefined ? { description } : {}),
+          ...(assignee ? { assignee: { accountId: assignee } } : {}),
+          ...(labels ? { labels } : {}),
+        },
+      };
+      const data = await request('/rest/api/3/issue', { method: 'POST', body });
+      return {
+        id: data.id,
+        key: data.key,
+        url: `${baseUrl}/browse/${data.key}`,
+      };
+    },
+
+    async createComment(issueKey, adfBody) {
+      const data = await request(`/rest/api/3/issue/${issueKey}/comment`, {
+        method: 'POST',
+        body: { body: adfBody },
+      });
+      return {
+        id: data.id,
+        url: `${baseUrl}/browse/${issueKey}?focusedCommentId=${data.id}`,
+      };
+    },
+
+    async searchIssues(jql) {
+      const query = typeof jql === 'string' ? jql : (jql?.jql ?? '');
+      const data = await request('/rest/api/3/search', {
+        method: 'POST',
+        body: { jql: query, maxResults: 50, fields: ['summary', 'status'] },
+      });
+      return (data.issues ?? []).map((issue) => ({
+        id: issue.id,
+        key: issue.key,
+        summary: issue.fields?.summary,
+        url: `${baseUrl}/browse/${issue.key}`,
+      }));
+    },
+  };
+}
+
+export default createJiraTransport;

package/lib/providers/contract.mjs

@@ -42,8 +42,23 @@
  *
  * Glob matching for `*Glob` fields follows minimatch-style single-segment
  * patterns where `*` matches any sequence of non-slash characters.
+ *
+ * ADR-0060 filter block (LMCP-B11): `validateFilterConfig(providerName,
+ * filter)` validates a `{ scope, predicates, nativeQuery }` block against
+ * `SCOPE_FIELDS_BY_PROVIDER` and the normalized predicate keys in
+ * `lib/providers/filter-schema.mjs`, throwing on any key the provider kind
+ * does not declare — fail closed at poll time, never a silent no-op.
+ * `matchesFilter(item, filter, providerName)` re-evaluates `scope` and
+ * `predicates` plane-side against a fetched item; this is the mandatory
+ * post-fetch backstop even when a provider pushed the same filter down
+ * server-side (Jira JQL, etc.). `filterHash(filter)` derives the stable
+ * digest recorded in the per-poll audit line.
  */
 
+import crypto from 'node:crypto';
+
+import { PREDICATE_KEYS, SCOPE_KEYS, STATUS_CATEGORIES, TOP_LEVEL_KEYS } from './filter-schema.mjs';
+
 export const ALLOWLIST_SCHEMA = Object.freeze({
   github:                 { fields: ['org', 'repoAllowlist', 'repoAllowGlob'] },
   'atlassian-jira':       { fields: ['instance', 'projectAllowlist'] },
@@ -98,6 +113,198 @@ export function validateAllowlist(providerName, target, config = {}) {
   };
 }
 
+// ─── ADR-0060 provider filter block (scope + predicates + nativeQuery) ──────
+
+// Which `scope` container keys and passthrough capability each provider kind
+// declares. Mirrors the dead *Allowlist fields ALLOWLIST_SCHEMA carried
+// per-provider, now under the one normalized `scope` container.
+
+export const SCOPE_FIELDS_BY_PROVIDER = Object.freeze({
+  github: { scope: ['repos', 'repoGlob'], nativeQuery: true },
+  'atlassian-jira': { scope: ['projects'], nativeQuery: true },
+  jira: { scope: ['projects'], nativeQuery: true },
+  'atlassian-confluence': { scope: ['spaces'], nativeQuery: false },
+  slack: { scope: ['channels'], nativeQuery: false },
+  salesforce: { scope: ['projects'], nativeQuery: true },
+});
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Validate an ADR-0060 filter block against the scope fields and predicate
+ * keys the given provider kind declares. Any unknown top-level key, unknown
+ * scope key, unknown predicate key, or `nativeQuery` on a provider that
+ * doesn't support passthrough throws — fail closed, never a silent no-op.
+ * Returns the block unchanged (for chaining) when it is valid.
+ */
+export function validateFilterConfig(providerName, filter) {
+  if (filter == null) return filter;
+  if (!isPlainObject(filter)) {
+    throw new Error(`provider filter (${providerName}): filter must be an object`);
+  }
+
+  for (const key of Object.keys(filter)) {
+    if (!TOP_LEVEL_KEYS.includes(key)) {
+      throw new Error(`provider filter (${providerName}): unknown filter key "${key}". Allowed: ${TOP_LEVEL_KEYS.join(', ')}`);
+    }
+  }
+
+  const allowed = SCOPE_FIELDS_BY_PROVIDER[providerName] ?? { scope: SCOPE_KEYS, nativeQuery: true };
+
+  if (filter.scope !== undefined) {
+    if (!isPlainObject(filter.scope)) {
+      throw new Error(`provider filter (${providerName}): scope must be an object`);
+    }
+    for (const key of Object.keys(filter.scope)) {
+      if (!SCOPE_KEYS.includes(key)) {
+        throw new Error(`provider filter (${providerName}): unknown scope key "${key}". Allowed: ${SCOPE_KEYS.join(', ')}`);
+      }
+      if (!allowed.scope.includes(key)) {
+        throw new Error(`provider filter (${providerName}): scope key "${key}" is not supported by this provider kind. Allowed: ${allowed.scope.join(', ') || '(none)'}`);
+      }
+      if (!Array.isArray(filter.scope[key])) {
+        throw new Error(`provider filter (${providerName}): scope.${key} must be an array`);
+      }
+    }
+  }
+
+  if (filter.predicates !== undefined) {
+    if (!isPlainObject(filter.predicates)) {
+      throw new Error(`provider filter (${providerName}): predicates must be an object`);
+    }
+    for (const key of Object.keys(filter.predicates)) {
+      if (!PREDICATE_KEYS.includes(key)) {
+        throw new Error(`provider filter (${providerName}): unknown predicate key "${key}". Allowed: ${PREDICATE_KEYS.join(', ')}`);
+      }
+      if (key === 'statusCategory') {
+        const values = filter.predicates[key];
+        if (!Array.isArray(values) || values.some((v) => !STATUS_CATEGORIES.includes(v))) {
+          throw new Error(`provider filter (${providerName}): predicates.statusCategory must be an array drawn from ${STATUS_CATEGORIES.join(', ')}`);
+        }
+      } else if (key === 'updatedSince') {
+        if (typeof filter.predicates[key] !== 'string' || !filter.predicates[key]) {
+          throw new Error(`provider filter (${providerName}): predicates.updatedSince must be a non-empty string`);
+        }
+      } else if (!Array.isArray(filter.predicates[key])) {
+        throw new Error(`provider filter (${providerName}): predicates.${key} must be an array`);
+      }
+    }
+  }
+
+  if (filter.nativeQuery !== undefined) {
+    if (typeof filter.nativeQuery !== 'string' || !filter.nativeQuery) {
+      throw new Error(`provider filter (${providerName}): nativeQuery must be a non-empty string`);
+    }
+    if (!allowed.nativeQuery) {
+      throw new Error(`provider filter (${providerName}): nativeQuery passthrough is not supported by this provider kind`);
+    }
+  }
+
+  return filter;
+}
+
+/**
+ * Stable content hash of an effective filter block, recorded in the per-poll
+ * audit line so operators can tell whether the enforced filter changed
+ * between polls without diffing the full block.
+ */
+export function filterHash(filter) {
+  const normalized = filter == null ? {} : filter;
+  return crypto.createHash('sha256').update(JSON.stringify(normalized, Object.keys(normalized).sort())).digest('hex').slice(0, 16);
+}
+
+function parseUpdatedSince(value) {
+  if (!value) return null;
+  const isoDuration = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?)?$/.exec(value);
+  if (isoDuration) {
+    const days = Number(isoDuration[1] ?? 0);
+    const hours = Number(isoDuration[2] ?? 0);
+    const minutes = Number(isoDuration[3] ?? 0);
+    const ms = ((days * 24 + hours) * 60 + minutes) * 60_000;
+    return Date.now() - ms;
+  }
+  const absolute = Date.parse(value);
+  return Number.isNaN(absolute) ? null : absolute;
+}
+
+function scopeContainerValue(item, key) {
+  if (key === 'projects') return item.project ?? null;
+  if (key === 'repos' || key === 'repoGlob') return item.repo ?? null;
+  if (key === 'channels') return item.channelId ?? item.channel ?? null;
+  if (key === 'spaces') return item.space ?? item.spaceKey ?? null;
+  return null;
+}
+
+function matchesScope(item, scope) {
+  if (!scope) return true;
+  for (const key of SCOPE_KEYS) {
+    const constraint = scope[key];
+    if (!Array.isArray(constraint) || constraint.length === 0) continue;
+    const value = scopeContainerValue(item, key);
+    if (value == null) return false;
+    if (key === 'repoGlob') {
+      if (!constraint.some((pattern) => globMatch(pattern, value))) return false;
+    } else if (!constraint.includes(value)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function matchesPredicates(item, predicates) {
+  if (!predicates) return true;
+
+  if (Array.isArray(predicates.assignee) && predicates.assignee.length > 0) {
+    if (!predicates.assignee.includes(item.assignee)) return false;
+  }
+  if (Array.isArray(predicates.statusCategory) && predicates.statusCategory.length > 0) {
+    const normalized = normalizeStatusCategory(item.statusCategory ?? item.status);
+    if (!predicates.statusCategory.includes(normalized)) return false;
+  }
+  if (Array.isArray(predicates.priority) && predicates.priority.length > 0) {
+    if (!predicates.priority.includes(item.priority)) return false;
+  }
+  if (Array.isArray(predicates.label) && predicates.label.length > 0) {
+    const itemLabels = Array.isArray(item.labels) ? item.labels : [];
+    if (!predicates.label.some((l) => itemLabels.includes(l))) return false;
+  }
+  if (typeof predicates.updatedSince === 'string' && predicates.updatedSince) {
+    const threshold = parseUpdatedSince(predicates.updatedSince);
+    const updatedAt = item.updatedAt ? Date.parse(item.updatedAt) : NaN;
+    if (threshold != null && (Number.isNaN(updatedAt) || updatedAt < threshold)) return false;
+  }
+  return true;
+}
+
+/**
+ * Normalize a provider-native status string to the ADR-0060 statusCategory
+ * enum (to-do | in-progress | done) so the same predicate expresses
+ * identically across Jira, GitHub, and Salesforce.
+ */
+export function normalizeStatusCategory(status) {
+  if (!status) return null;
+  const s = String(status).toLowerCase();
+  if (/done|closed|resolved|complete/.test(s)) return 'done';
+  if (/progress|review|doing|active/.test(s)) return 'in-progress';
+  if (/to.?do|open|backlog|new|triage/.test(s)) return 'to-do';
+  return null;
+}
+
+/**
+ * Plane-side re-evaluation of an ADR-0060 filter against a fetched item.
+ * Mandatory universal fallback: runs even when the provider already pushed
+ * the same filter down server-side, and is the sole enforcement point for
+ * providers with no server-side filtering. `nativeQuery` has no plane-side
+ * equivalent (opaque passthrough) — its effect is assumed already applied
+ * by the provider fetch; `scope` and `predicates` are conjoined here.
+ */
+export function matchesFilter(item, filter) {
+  if (filter == null) return true;
+  return matchesScope(item, filter.scope) && matchesPredicates(item, filter.predicates);
+}
+
 export const CAPABILITIES = Object.freeze([
   'read',
   'search',

package/lib/providers/credential-bootstrap.mjs

@@ -11,6 +11,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { hasAnySecret } from './secret-resolver.mjs';
+import { locateOpBinary } from './op-locate.mjs';
 import { API_KEY_CREDENTIALS, primaryEnvVar } from './credential-catalog.mjs';
 import {
   discoverAlternateRawForCredential,
@@ -36,7 +37,9 @@ export function commandExists(command) {
 }
 
 function defaultOpRun(args) {
-  return spawnSync('op', args, { encoding: 'utf8', timeout: 12_000 });
+  const opPath = locateOpBinary();
+  if (!opPath) return { status: 1, stdout: '', stderr: 'op not found' };
+  return spawnSync(opPath, args, { encoding: 'utf8', timeout: 12_000 });
 }
 
 export function listOpItems({ opRun = defaultOpRun } = {}) {
@@ -122,17 +125,17 @@ export function ensureConstructCredentials({
 
   const missing = missingCredentials({ env, cwd, home });
   if (missing.length === 0) {
-    lastBootstrapResult = { linked: [], opAvailable: commandExists('op') };
+    lastBootstrapResult = { linked: [], opAvailable: locateOpBinary() !== null };
     return lastBootstrapResult;
   }
 
   if (!autoLink) {
-    lastBootstrapResult = { linked: [], opAvailable: commandExists('op'), pending: missing.map((e) => e.id) };
+    lastBootstrapResult = { linked: [], opAvailable: locateOpBinary() !== null, pending: missing.map((e) => e.id) };
     return lastBootstrapResult;
   }
 
   const linked = [];
-  const opAvailable = opRun !== defaultOpRun || commandExists('op');
+  const opAvailable = opRun !== defaultOpRun || locateOpBinary() !== null;
   if (!opAvailable) {
     lastBootstrapResult = { linked, opAvailable: false };
     return lastBootstrapResult;

package/lib/providers/credential-sources.mjs

@@ -15,8 +15,20 @@ export function openCodeConfigPath(homeDir = os.homedir()) {
   return path.join(homeDir, '.config', 'opencode', 'opencode.json');
 }
 
-function isPlaceholder(value) {
-  return !value || String(value).includes('__OPENROUTER_API_KEY__');
+// Matches the literal reference forms Construct and OpenCode write into
+// config when no real credential is resolved yet, so presence checks don't
+// mistake an unresolved placeholder for a configured key.
+const PLACEHOLDER_PATTERNS = [
+  /^__[A-Z0-9_]+__$/,
+  /^\{env:[A-Z0-9_]+\}$/,
+  /^\$\{[A-Z0-9_]+\}$/,
+  /^\$\{env:[A-Z0-9_]+\}$/,
+];
+
+export function isPlaceholder(value) {
+  if (!value) return true;
+  const trimmed = String(value).trim();
+  return PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(trimmed));
 }
 
 export function readRawFromOpenCodeProvider(providerName, configPath = openCodeConfigPath()) {

package/lib/providers/directory/index.mjs

@@ -0,0 +1,261 @@
+/**
+ * lib/providers/directory/index.mjs — Local directory data-source provider.
+ *
+ * Provides read/search capabilities over a configured local directory with
+ * include/exclude glob patterns and file size limits. Security: all paths
+ * resolve and remain within the configured root; symlink escape and
+ * traversal (../) are rejected.
+ *
+ * Capabilities: read, search.
+ *
+ * Config (per call):
+ *   - root: absolute or relative path to the directory root (required)
+ *   - include: array of minimatch glob patterns (optional, defaults to ["**\/*"])
+ *   - exclude: array of minimatch glob patterns to filter out (optional)
+ *   - maxFileKB: integer max file size in KB (default 1024, max 10240)
+ */
+
+import { existsSync, statSync, readdirSync, readFileSync } from 'node:fs';
+import { resolve, relative, isAbsolute } from 'node:path';
+import { minimatch } from 'minimatch';
+
+/**
+ * Verify that path is within root and not a symlink escape.
+ * Returns { ok: true } or { ok: false, reason: '...' }.
+ */
+function validatePathSecurity(root, checkPath) {
+  try {
+    const realRoot = statSync(root).ino;
+    const stats = statSync(checkPath);
+
+    if (stats.isSymbolicLink()) {
+      return { ok: false, reason: 'symlink not allowed' };
+    }
+
+    const realPath = statSync(checkPath).ino;
+    if (realPath !== realRoot) {
+      const rel = relative(root, checkPath);
+      if (rel.startsWith('..')) {
+        return { ok: false, reason: 'path escape detected' };
+      }
+    }
+
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+}
+
+/**
+ * Resolve and validate a path within root. Returns { ok, path } or
+ * { ok: false, reason }.
+ */
+function resolvePath(root, candidate) {
+  const rootPath = isAbsolute(root) ? root : resolve(process.cwd(), root);
+
+  if (!existsSync(rootPath)) {
+    return { ok: false, reason: `root does not exist: ${rootPath}` };
+  }
+
+  const stat = statSync(rootPath);
+  if (!stat.isDirectory()) {
+    return { ok: false, reason: `root is not a directory: ${rootPath}` };
+  }
+
+  const resolved = isAbsolute(candidate)
+    ? candidate
+    : resolve(rootPath, candidate);
+
+  const validation = validatePathSecurity(rootPath, resolved);
+  if (!validation.ok) {
+    return { ok: false, reason: validation.reason };
+  }
+
+  return { ok: true, path: resolved, root: rootPath };
+}
+
+/**
+ * Walk directory recursively, matching include/exclude globs.
+ */
+function walkDir(dirPath, { include = ['**/*'], exclude = [] }) {
+  const results = [];
+  const stat = statSync(dirPath);
+  if (!stat.isDirectory()) return results;
+
+  function walk(dir, prefix = '') {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = resolve(dir, entry.name);
+      const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+      if (entry.isDirectory()) {
+        walk(fullPath, relativePath);
+      } else if (entry.isFile()) {
+        const matches = include.some((pat) => minimatch(relativePath, pat, { matchBase: true }));
+        const excludes = exclude.some((pat) => minimatch(relativePath, pat, { matchBase: true }));
+
+        if (matches && !excludes) {
+          results.push({ path: fullPath, relativePath, name: entry.name });
+        }
+      }
+    }
+  }
+
+  walk(dirPath);
+  return results;
+}
+
+/**
+ * Filter files by size constraint.
+ */
+function filterBySize(items, maxFileSizeKB) {
+  const maxBytes = maxFileSizeKB * 1024;
+  return items.filter((item) => {
+    try {
+      const stat = statSync(item.path);
+      return stat.size <= maxBytes;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * Read all matching files from the directory.
+ */
+async function readAllFiles(config) {
+  const root = config?.root;
+  if (!root) throw new Error('directory.read: config.root required');
+
+  const { ok, path, root: rootPath } = resolvePath(root, '.');
+  if (!ok) throw new Error(`directory.read: ${path}`);
+
+  const include = Array.isArray(config.include) ? config.include : ['**/*'];
+  const exclude = Array.isArray(config.exclude) ? config.exclude : [];
+  const maxKB = Math.min(config?.maxFileKB || 1024, 10240);
+
+  const items = walkDir(rootPath, { include, exclude });
+  const filtered = filterBySize(items, maxKB);
+
+  return filtered.map((item) => ({
+    path: item.relativePath,
+    name: item.name,
+    mtime: statSync(item.path).mtimeMs,
+    size: statSync(item.path).size,
+  }));
+}
+
+/**
+ * Search for a substring within matching files.
+ */
+async function searchFiles(config, query) {
+  if (!query || typeof query !== 'string') {
+    throw new Error('directory.search: query required (substring or glob pattern)');
+  }
+
+  const root = config?.root;
+  if (!root) throw new Error('directory.search: config.root required');
+
+  const { ok, path, root: rootPath } = resolvePath(root, '.');
+  if (!ok) throw new Error(`directory.search: ${path}`);
+
+  const include = Array.isArray(config.include) ? config.include : ['**/*'];
+  const exclude = Array.isArray(config.exclude) ? config.exclude : [];
+  const maxKB = Math.min(config?.maxFileKB || 1024, 10240);
+
+  const items = walkDir(rootPath, { include, exclude });
+  const filtered = filterBySize(items, maxKB);
+
+  const results = [];
+
+  for (const item of filtered) {
+    try {
+      const content = readFileSync(item.path, 'utf8');
+      if (content.includes(query)) {
+        results.push({
+          path: item.relativePath,
+          name: item.name,
+          mtime: statSync(item.path).mtimeMs,
+          size: statSync(item.path).size,
+          preview: content.slice(0, 200),
+        });
+      }
+    } catch {
+      // Skip files we cannot read
+    }
+  }
+
+  return results;
+}
+
+export function create({ env = process.env } = {}) {
+  return {
+    meta: {
+      id: 'directory',
+      displayName: 'Local Directory',
+      capabilities: ['read', 'search'],
+      description: 'Read and search files in a local directory.',
+    },
+
+    configSchema: {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      properties: {
+        root: {
+          type: 'string',
+          description: 'Path to the root directory (absolute or relative to cwd)',
+        },
+        include: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Glob patterns to include (default: ["**/*"])',
+          default: ['**/*'],
+        },
+        exclude: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Glob patterns to exclude (default: [])',
+          default: [],
+        },
+        maxFileKB: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 10240,
+          default: 1024,
+          description: 'Maximum file size in KB (default 1024)',
+        },
+      },
+      required: ['root'],
+    },
+
+    async health(config) {
+      const root = config?.root;
+      if (!root) {
+        return { ok: false, detail: 'config.root not set' };
+      }
+
+      const { ok, reason, root: rootPath } = resolvePath(root, '.');
+      if (!ok) {
+        return { ok: false, detail: reason };
+      }
+
+      try {
+        const entries = readdirSync(rootPath);
+        return { ok: true, detail: `directory readable (${entries.length} entries)` };
+      } catch (err) {
+        return { ok: false, detail: err.message };
+      }
+    },
+
+    read: readAllFiles,
+    search: searchFiles,
+  };
+}
+
+export default create;