@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/providers/contract/adapters/jira/governed-write.mjs

@@ -0,0 +1,182 @@
+/**
+ * lib/providers/contract/adapters/jira/governed-write.mjs — envelope-shaped
+ * Jira write adapter.
+ *
+ * Wraps a Jira REST transport in the provider shape lib/writes/envelope.mjs
+ * expects: write(config, payload), meta.id, search(). This is the only
+ * exposed entry point for Jira writes — specialists and CLI callers route
+ * through writeWithEnvelope(), never through a raw Jira client, so dedup,
+ * retry, dry-run, approval, and audit stay centralized in the envelope
+ * (LMCP-J2) rather than being reimplemented per-adapter.
+ *
+ * Adds the two behaviors createmeta + ADF require that a generic envelope
+ * cannot provide:
+ *
+ *   - createmeta validation before submit: fetches
+ *     `issue/createmeta?projectKeys=X&issuetypeNames=Y` (via the injected
+ *     `jiraTransport`) and checks required fields and ADF-vs-plain field
+ *     shape before making the create/comment call, so a bad project key,
+ *     unknown issue type, missing required field, or wrong field shape
+ *     surfaces as an actionable client-side error rather than a raw Jira
+ *     400.
+ *   - ADF body construction: `description` (issue create) and `body`
+ *     (comment) are converted from plain text to Atlassian Document Format
+ *     via lib/providers/contract/adapters/jira/adf.mjs before submit.
+ *
+ * Only `type: 'issue'` and `type: 'comment'` writes get createmeta + ADF
+ * treatment; other write types are rejected — this adapter does not
+ * support transitions or field updates (non-goal per LMCP-J3).
+ */
+
+import { AuthError } from '../../errors.mjs';
+import { buildAdfDocument, renderAdfPreview } from './adf.mjs';
+import { validateAgainstCreatemeta } from './createmeta.mjs';
+
+/**
+ * @param {object} opts
+ * @param {object} opts.jiraTransport - underlying Jira REST transport; must implement
+ *   `fetchCreatemeta(projectKey, issueTypeName)`, `createIssue(fields)`,
+ *   `createComment(issueKey, adfBody)`, and `searchIssues(jql)`.
+ */
+export function createGovernedJiraProvider({ jiraTransport } = {}) {
+  if (!jiraTransport) throw new Error('createGovernedJiraProvider: jiraTransport is required');
+
+  async function writeIssue(payload) {
+    const { project, issueType = 'Task', summary, description, labels, assignee } = payload;
+    if (!project) throw new Error('jira governed write: payload.project is required for type "issue"');
+    if (!summary) throw new Error('jira governed write: payload.summary is required for type "issue"');
+
+    const descriptionAdf = description !== undefined ? buildAdfDocument(description) : undefined;
+
+    const validation = await validateAgainstCreatemeta({
+      fetchCreatemeta: jiraTransport.fetchCreatemeta.bind(jiraTransport),
+      projectKey: project,
+      issueTypeName: issueType,
+      fieldValues: {
+        summary,
+        description: descriptionAdf,
+        labels,
+        assignee,
+      },
+    });
+
+    if (!validation.ok) {
+      const err = new Error(validation.errors.join(' '));
+      err.code = validation.reason;
+      err.jiraValidation = validation;
+      throw err;
+    }
+
+    try {
+      const result = await jiraTransport.createIssue({
+        project,
+        issueType,
+        summary,
+        description: descriptionAdf,
+        labels,
+        assignee,
+      });
+      return { type: 'issue-created', id: result.id, key: result.key, url: result.url };
+    } catch (err) {
+      throw mapWriteTransportError(err, { project });
+    }
+  }
+
+  async function writeComment(payload) {
+    const { issueKey, body } = payload;
+    if (!issueKey) throw new Error('jira governed write: payload.issueKey is required for type "comment"');
+    if (!body) throw new Error('jira governed write: payload.body is required for type "comment"');
+
+    const bodyAdf = buildAdfDocument(body);
+
+    try {
+      const result = await jiraTransport.createComment(issueKey, bodyAdf);
+      return { type: 'comment-created', id: result.id, issueKey, url: result.url };
+    } catch (err) {
+      throw mapWriteTransportError(err, { issueKey });
+    }
+  }
+
+  return {
+    meta: {
+      id: 'jira',
+      displayName: 'Jira (governed)',
+      capabilities: ['write', 'search'],
+      description: 'Envelope-routed Jira writes with createmeta pre-validation and ADF body construction.',
+    },
+
+    async write(config, payload) {
+      if (payload?.type === 'issue') return writeIssue(payload);
+      if (payload?.type === 'comment') return writeComment(payload);
+      throw new Error(`jira governed write: unsupported type "${payload?.type}" (only 'issue' and 'comment' are supported)`);
+    },
+
+    async search(config, query) {
+      return jiraTransport.searchIssues(query);
+    },
+
+    /**
+     * Render the ADF-shaped payload the envelope would submit, without
+     * calling createmeta or the transport. Feeds the envelope's dry-run
+     * path (lib/writes/envelope.mjs `dryRun: true`), giving a human
+     * reviewing a pending write both the raw ADF tree and a flattened
+     * preview string, not just the plain-text input.
+     *
+     * @param {object} payload
+     * @returns {{ type: string, fields: object, adfPreview: Record<string,string> }}
+     */
+    renderDryRun(payload) {
+      if (payload?.type === 'issue') {
+        const descriptionAdf = payload.description !== undefined ? buildAdfDocument(payload.description) : undefined;
+        return {
+          type: 'issue',
+          fields: {
+            project: { key: payload.project },
+            issuetype: { name: payload.issueType ?? 'Task' },
+            summary: payload.summary,
+            ...(descriptionAdf ? { description: descriptionAdf } : {}),
+            ...(payload.labels ? { labels: payload.labels } : {}),
+            ...(payload.assignee ? { assignee: payload.assignee } : {}),
+          },
+          adfPreview: descriptionAdf ? { description: renderAdfPreview(descriptionAdf) } : {},
+        };
+      }
+      if (payload?.type === 'comment') {
+        const bodyAdf = buildAdfDocument(payload.body);
+        return {
+          type: 'comment',
+          fields: { issueKey: payload.issueKey, body: bodyAdf },
+          adfPreview: { body: renderAdfPreview(bodyAdf) },
+        };
+      }
+      throw new Error(`jira governed write: cannot render dry-run for unsupported type "${payload?.type}"`);
+    },
+  };
+}
+
+/**
+ * Map a create/comment transport failure (401/403/404) to an actionable
+ * message. Distinct from mapCreatemetaTransportError since it covers the
+ * write call itself, not the pre-flight createmeta fetch.
+ *
+ * @param {Error & {status?: number}} err
+ * @param {{ project?: string, issueKey?: string }} ctx
+ * @returns {Error}
+ */
+function mapWriteTransportError(err, ctx) {
+  const status = err?.status;
+  if (status === 401) {
+    return new AuthError('Jira authentication failed. Check JIRA_EMAIL / JIRA_TOKEN.', { provider: 'jira' });
+  }
+  if (status === 403) {
+    const target = ctx.project ? `project "${ctx.project}"` : `issue "${ctx.issueKey}"`;
+    return new Error(`Forbidden: the authenticated account lacks permission to write to ${target}.`);
+  }
+  if (status === 404) {
+    const target = ctx.project ? `Project "${ctx.project}"` : `Issue "${ctx.issueKey}"`;
+    return new Error(`${target} was not found, or the authenticated account cannot access it.`);
+  }
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+export default createGovernedJiraProvider;

package/lib/providers/contract/adapters/jira/manifest.json

@@ -0,0 +1,17 @@
+{
+  "id": "jira-write",
+  "version": "1.0.0",
+  "kind": "data-source",
+  "capabilities": ["write", "search"],
+  "secretEnvKeys": ["JIRA_URL", "JIRA_EMAIL", "JIRA_TOKEN"],
+  "operations": ["write:issue", "write:comment", "search"],
+  "securityClassification": "trusted",
+  "owner": "construct-core",
+  "compatVersion": 1,
+  "installSource": "builtin",
+  "exposure": "envelope-only",
+  "envelopeModule": "lib/writes/envelope.mjs",
+  "adapterModule": "lib/providers/contract/adapters/jira/governed-write.mjs",
+  "transportModule": "lib/providers/contract/adapters/jira/transport.mjs",
+  "notes": "Colocated write-capability manifest for LMCP-J3. Follows the lib/extensions/manifests/*.manifest.json schema (see atlassian-jira.manifest.json, which declares read/search only). Wiring this into the shared lib/extensions/manifests/ discovery directory is out of scope for this bead; capabilities here are reachable only via writeWithEnvelope(), never a direct provider-registry lookup."
+}

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()) {