@geraldmaron/construct 1.1.1 → 1.2.0

package/lib/graph/impact-cli.mjs

@@ -0,0 +1,89 @@
+/**
+ * lib/graph/impact-cli.mjs — `construct impact` command surface.
+ *
+ * Maps changed files to the tests that should run and the capabilities and
+ * workflows they touch, using the living dependency graph. Advisory by default;
+ * `--run` executes the selected tests via `node --test`. Files come from
+ * positional args, or — when none are given — from `git diff --name-only HEAD`.
+ *
+ *   construct impact lib/oracle/synthesize.mjs
+ *   construct impact --run
+ *   git diff --name-only origin/main | construct impact --stdin --json
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { computeImpact } from './impact.mjs';
+
+function readStdin() {
+  try { return readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+function gitChangedFiles(projectDir) {
+  const res = spawnSync('git', ['diff', '--name-only', 'HEAD'], { cwd: projectDir, encoding: 'utf8' });
+  if (res.status !== 0) return [];
+  return res.stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+}
+
+/**
+ * @param {string[]} args
+ * @param {{ rootDir: string, projectDir: string }} ctx
+ * @returns {Promise<number>} exit code
+ */
+export async function runImpactCli(args, { projectDir }) {
+  const json = args.includes('--json');
+  const run = args.includes('--run');
+  const useStdin = args.includes('--stdin');
+  let files = args.filter((a) => !a.startsWith('--'));
+
+  if (useStdin) files = readStdin().split('\n').map((l) => l.trim()).filter(Boolean);
+  if (files.length === 0) files = gitChangedFiles(projectDir);
+
+  if (files.length === 0) {
+    process.stderr.write('No changed files given (args, --stdin, or git diff). Nothing to analyze.\n');
+    return 1;
+  }
+
+  const result = computeImpact({ rootDir: projectDir, changedFiles: files });
+
+  if (!result.graphPresent) {
+    process.stderr.write('No dependency graph found. Run `construct matrix build` first.\n');
+    return 1;
+  }
+
+  if (json && !run) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return 0;
+  }
+
+  if (!json) {
+    process.stdout.write(`Changed: ${result.changed.length} file(s)\n`);
+    process.stdout.write(`Impacted capabilities (${result.impactedCapabilities.length}): ${result.impactedCapabilities.join(', ') || '(none)'}\n`);
+    process.stdout.write(`Stale capabilities (${result.staleCapabilities.length}): ${result.staleCapabilities.join(', ') || '(none)'}\n`);
+    process.stdout.write(`Impacted workflows (${result.impactedWorkflows.length}): ${result.impactedWorkflows.join(', ') || '(none)'}\n`);
+    process.stdout.write(`Affected tests (${result.affectedTests.length}):\n`);
+    for (const t of result.affectedTests) process.stdout.write(`  ${t}\n`);
+    if (result.coverageGaps.length) {
+      process.stdout.write(`\n⚠ Coverage gap — changed files realizing no capability (${result.coverageGaps.length}):\n`);
+      for (const f of result.coverageGaps) process.stdout.write(`  ${f}\n`);
+    }
+    if (result.unknown.length) {
+      process.stdout.write(`\nNot in graph (${result.unknown.length}): ${result.unknown.join(', ')}\n`);
+    }
+  }
+
+  if (run) {
+    const runnable = result.affectedTests.filter((t) => existsSync(path.join(projectDir, t)));
+    if (runnable.length === 0) {
+      process.stdout.write('\nNo runnable affected tests on disk.\n');
+      return 0;
+    }
+    process.stdout.write(`\n▶ Running ${runnable.length} affected test(s)…\n`);
+    const res = spawnSync(process.execPath, ['--test', ...runnable], { cwd: projectDir, stdio: 'inherit' });
+    return res.status ?? 1;
+  }
+
+  return 0;
+}

package/lib/graph/impact.mjs

@@ -0,0 +1,108 @@
+/**
+ * lib/graph/impact.mjs — forward change-impact over the dependency graph.
+ *
+ * Given a set of changed files, computes the tests that should run, the
+ * capabilities and workflows impacted, and any changed file that realizes no
+ * capability (a coverage gap). Test selection is Test Impact Analysis over the
+ * static import graph: a test is affected if it transitively imports a changed
+ * file, or if it validates a capability that a changed file realizes. The
+ * union is intentionally conservative — over-selection is safe, under-selection
+ * silently ships untested change.
+ */
+
+import { loadGraph, dependentsOf, dependenciesOf } from './store.mjs';
+import { rollupStaleImpact } from '../certification/stale-impact.mjs';
+
+function isTestRel(rel) {
+  return rel.endsWith('.test.mjs') || rel.endsWith('.test.js');
+}
+
+function toNodeId(rel) {
+  return isTestRel(rel) ? `test:${rel}` : `file:${rel}`;
+}
+
+function reverseImportClosure(graph, startId) {
+  const reached = new Set();
+  const stack = [startId];
+  while (stack.length) {
+    const id = stack.pop();
+    for (const importer of dependentsOf(graph, id, 'imports')) {
+      if (reached.has(importer)) continue;
+      reached.add(importer);
+      stack.push(importer);
+    }
+  }
+  return reached;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.rootDir — project root holding .cx/graph/.
+ * @param {string[]} opts.changedFiles — repo-relative paths.
+ * @returns {{ changed: string[], unknown: string[], affectedTests: string[], impactedCapabilities: string[], impactedWorkflows: string[], staleCapabilities: string[], coverageGaps: string[], graphPresent: boolean }}
+ */
+export function computeImpact({ rootDir, changedFiles }) {
+  const graph = loadGraph(rootDir);
+  const norm = [...new Set((changedFiles || []).map((f) => f.split('\\').join('/').replace(/^\.\//, '')))].filter(Boolean);
+  if (!graph.exists) {
+    return {
+      changed: norm,
+      unknown: norm,
+      affectedTests: [],
+      impactedCapabilities: [],
+      impactedWorkflows: [],
+      staleCapabilities: rollupStaleImpact({ rootDir, changedFiles: norm }),
+      coverageGaps: [],
+      graphPresent: false,
+    };
+  }
+
+  const tests = new Set();
+  const capabilities = new Set();
+  const unknown = [];
+  const coverageGaps = [];
+
+  for (const rel of norm) {
+    const id = toNodeId(rel);
+    if (!graph.nodes.has(id)) { unknown.push(rel); continue; }
+
+    if (id.startsWith('test:')) tests.add(id);
+
+    for (const importer of reverseImportClosure(graph, id)) {
+      if (importer.startsWith('test:')) tests.add(importer);
+    }
+
+    const caps = dependenciesOf(graph, id, 'realizes');
+    for (const c of caps) capabilities.add(c);
+    if (id.startsWith('file:') && caps.length === 0) coverageGaps.push(rel);
+  }
+
+  // Capabilities reached transitively also pull in their declared verification
+  // tests; their embedded workflows complete the requirement trace.
+
+  for (const cap of [...capabilities]) {
+    for (const t of dependentsOf(graph, cap, 'validates')) tests.add(t);
+  }
+  for (const t of tests) {
+    for (const cap of dependenciesOf(graph, t, 'validates')) capabilities.add(cap);
+  }
+
+  const workflows = new Set();
+  for (const cap of capabilities) {
+    for (const wf of dependenciesOf(graph, cap, 'embeds')) workflows.add(wf);
+  }
+
+  const strip = (set, prefix) => [...set].map((id) => id.slice(prefix.length)).sort();
+  const impactedCapabilityIds = strip(capabilities, 'capability:');
+  const staleCapabilities = rollupStaleImpact({ rootDir, changedFiles: norm });
+  return {
+    changed: norm,
+    unknown,
+    affectedTests: [...tests].map((id) => id.slice('test:'.length)).sort(),
+    impactedCapabilities: impactedCapabilityIds,
+    impactedWorkflows: strip(workflows, 'workflow:'),
+    staleCapabilities,
+    coverageGaps: coverageGaps.sort(),
+    graphPresent: true,
+  };
+}

package/lib/graph/staleness.mjs

@@ -0,0 +1,44 @@
+/**
+ * lib/graph/staleness.mjs — dependency graph seed-hash staleness checks.
+ *
+ * Compares the hash of registry/contracts/workflow seed files against the
+ * hash stored at last graph build (.cx/graph/meta.json). Shared by Oracle,
+ * the doctor graph-staleness watcher, and PostToolUse advisories.
+ */
+
+import { hashFiles } from './build-from-registry.mjs';
+import { loadGraph } from './store.mjs';
+
+export const GRAPH_SEED_FILES = [
+  'registry/capabilities.json',
+  'specialists/contracts.json',
+  'lib/embedded-contract/workflow-defs.mjs',
+];
+
+/**
+ * @param {string} rootDir — project root holding .cx/graph/.
+ * @returns {{ present: boolean, stale: boolean, staleReason: string|null, currentHash?: string, storedHash?: string|null }}
+ */
+export function checkGraphStaleness(rootDir) {
+  const graph = loadGraph(rootDir);
+  if (!graph.exists) {
+    return { present: false, stale: false, staleReason: null };
+  }
+
+  try {
+    const current = hashFiles(rootDir, GRAPH_SEED_FILES);
+    const stored = graph.meta?.sourceHash ?? null;
+    if (stored && current !== stored) {
+      return {
+        present: true,
+        stale: true,
+        staleReason: 'registry/contracts/workflow seeds changed since last build',
+        currentHash: current,
+        storedHash: stored,
+      };
+    }
+    return { present: true, stale: false, staleReason: null, currentHash: current, storedHash: stored };
+  } catch {
+    return { present: true, stale: false, staleReason: null };
+  }
+}

package/lib/graph/store.mjs

@@ -0,0 +1,172 @@
+/**
+ * lib/graph/store.mjs — typed, directed dependency-graph store.
+ *
+ * The substrate for Construct's living dependency matrix. Nodes are typed
+ * entities (file, module, workflow, capability, test, contract, surface,
+ * skill, rule) addressed by canonical ids of the form `type:key`. Edges are
+ * directed and carry a relation kind (imports, realizes, validates, covers,
+ * exposes, governed_by, uses, embeds, co_changes) and a provenance source
+ * (registry, import-graph, co-change, override).
+ *
+ * Persisted under `.cx/graph/` as deterministic JSONL so a graph round-trips
+ * losslessly and diffs cleanly: nodes.jsonl (sorted by id), edges.jsonl
+ * (sorted by from,rel,to), meta.json (generatedAt, sourceHash, counts).
+ * Dependency-free and pure-JS per ADR-0001.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import path from 'node:path';
+
+export const NODE_TYPES = new Set([
+  'file', 'module', 'workflow', 'capability', 'test', 'contract', 'surface', 'skill', 'rule',
+]);
+
+export const EDGE_RELS = new Set([
+  'imports', 'realizes', 'validates', 'covers', 'exposes', 'governed_by', 'uses', 'embeds', 'co_changes', 'contains',
+]);
+
+export const EDGE_SOURCES = new Set(['registry', 'import-graph', 'co-change', 'override']);
+
+const STORE_SUBDIR = path.join('.cx', 'graph');
+
+export function graphDir(rootDir) {
+  return path.join(rootDir, STORE_SUBDIR);
+}
+
+export function nodeId(type, key) {
+  return `${type}:${key}`;
+}
+
+function nodesPath(rootDir) { return path.join(graphDir(rootDir), 'nodes.jsonl'); }
+function edgesPath(rootDir) { return path.join(graphDir(rootDir), 'edges.jsonl'); }
+function metaPath(rootDir) { return path.join(graphDir(rootDir), 'meta.json'); }
+
+function readJsonl(filePath) {
+  if (!existsSync(filePath)) return [];
+  const out = [];
+  for (const line of readFileSync(filePath, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* skip malformed line */ }
+  }
+  return out;
+}
+
+function writeAtomic(filePath, contents) {
+  const tmp = `${filePath}.tmp`;
+  writeFileSync(tmp, contents, 'utf8');
+  renameSync(tmp, filePath);
+}
+
+// Canonical de-dup: nodes keyed by id (last write wins on attrs), edges keyed
+// by from|rel|to (weights summed so repeated co-change observations accumulate).
+
+function normalizeNodes(nodes) {
+  const byId = new Map();
+  for (const n of nodes) {
+    if (!n?.id || !n?.type) continue;
+    const prev = byId.get(n.id);
+    byId.set(n.id, prev ? { ...prev, ...n, attrs: { ...(prev.attrs || {}), ...(n.attrs || {}) } } : { id: n.id, type: n.type, name: n.name ?? n.id, attrs: n.attrs || {} });
+  }
+  return [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+function edgeKey(e) { return `${e.from}|${e.rel}|${e.to}`; }
+
+function normalizeEdges(edges) {
+  const byKey = new Map();
+  for (const e of edges) {
+    if (!e?.from || !e?.to || !e?.rel) continue;
+    const key = edgeKey(e);
+    const prev = byKey.get(key);
+    if (prev) {
+      prev.weight = (prev.weight || 1) + (e.weight || 1);
+      if (e.source && !prev.sources.includes(e.source)) prev.sources.push(e.source);
+    } else {
+      byKey.set(key, { from: e.from, to: e.to, rel: e.rel, weight: e.weight || 1, sources: e.source ? [e.source] : (e.sources || []) });
+    }
+  }
+  return [...byKey.values()].sort((a, b) => (edgeKey(a) < edgeKey(b) ? -1 : 1));
+}
+
+function countBy(items, key) {
+  const out = {};
+  for (const it of items) { const k = it[key]; out[k] = (out[k] || 0) + 1; }
+  return out;
+}
+
+/**
+ * Persist a full graph (regenerate semantics). Nodes and edges are normalized
+ * and sorted; meta records counts and the caller-supplied source hash.
+ *
+ * @param {string} rootDir
+ * @param {{ nodes: object[], edges: object[], generatedAt?: string, sourceHash?: string }} graph
+ * @returns {{ nodeCount: number, edgeCount: number, dir: string }}
+ */
+export function writeGraph(rootDir, { nodes = [], edges = [], generatedAt = null, sourceHash = null } = {}) {
+  const dir = graphDir(rootDir);
+  mkdirSync(dir, { recursive: true });
+  const normNodes = normalizeNodes(nodes);
+  const normEdges = normalizeEdges(edges);
+  writeAtomic(nodesPath(rootDir), normNodes.map((n) => JSON.stringify(n)).join('\n') + (normNodes.length ? '\n' : ''));
+  writeAtomic(edgesPath(rootDir), normEdges.map((e) => JSON.stringify(e)).join('\n') + (normEdges.length ? '\n' : ''));
+  const meta = {
+    generatedAt,
+    sourceHash,
+    nodeCount: normNodes.length,
+    edgeCount: normEdges.length,
+    nodesByType: countBy(normNodes, 'type'),
+    edgesByRel: countBy(normEdges, 'rel'),
+  };
+  writeAtomic(metaPath(rootDir), JSON.stringify(meta, null, 2) + '\n');
+  return { nodeCount: normNodes.length, edgeCount: normEdges.length, dir };
+}
+
+/**
+ * Load the graph into an indexed, queryable view. Out/in adjacency maps make
+ * forward (dependencies) and reverse (dependents) traversal O(degree).
+ *
+ * @param {string} rootDir
+ * @returns {{ nodes: Map<string,object>, edges: object[], out: Map<string,object[]>, in: Map<string,object[]>, meta: object|null, exists: boolean }}
+ */
+export function loadGraph(rootDir) {
+  const nodeList = readJsonl(nodesPath(rootDir));
+  const edgeList = readJsonl(edgesPath(rootDir));
+  let meta = null;
+  try { meta = JSON.parse(readFileSync(metaPath(rootDir), 'utf8')); } catch { /* no meta */ }
+
+  const nodes = new Map();
+  for (const n of nodeList) nodes.set(n.id, n);
+  const out = new Map();
+  const inc = new Map();
+  for (const e of edgeList) {
+    if (!out.has(e.from)) out.set(e.from, []);
+    if (!inc.has(e.to)) inc.set(e.to, []);
+    out.get(e.from).push(e);
+    inc.get(e.to).push(e);
+  }
+  return { nodes, edges: edgeList, out, in: inc, meta, exists: existsSync(nodesPath(rootDir)) };
+}
+
+function filterRel(edges, rel) {
+  if (!rel) return edges;
+  const rels = Array.isArray(rel) ? new Set(rel) : new Set([rel]);
+  return edges.filter((e) => rels.has(e.rel));
+}
+
+/**
+ * Nodes that `id` points to along `rel` (its dependencies).
+ */
+export function dependenciesOf(graph, id, rel = null) {
+  return filterRel(graph.out.get(id) || [], rel).map((e) => e.to);
+}
+
+/**
+ * Nodes that point to `id` along `rel` (its dependents).
+ */
+export function dependentsOf(graph, id, rel = null) {
+  return filterRel(graph.in.get(id) || [], rel).map((e) => e.from);
+}
+
+export function nodesByType(graph, type) {
+  return [...graph.nodes.values()].filter((n) => n.type === type);
+}

package/lib/health-check.mjs

@@ -10,6 +10,7 @@ import { spawnSync } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
+import { extractOpRef, hasAnySecret, hasSecret } from './providers/secret-resolver.mjs';
 
 const isWindows = os.platform() === 'win32';
 
@@ -165,37 +166,73 @@ export async function checkPrerequisites(options = {}) {
 }
 
 /**
- * Get a value from shell env by checking common sources.
- * Looks in process.env → project .env → ~/.env → ~/.construct/config.env
- * → shell rc files for op:// refs (resolved via 'op read').
+ * Read a credential raw value from dotenv files and shell rc without invoking
+ * `op read`. Returns op:// references as-is so callers can persist or report
+ * presence without biometric prompts (ADR-0042).
  */
-function getEnvFromShell(varName, homeDir) {
+function readCredentialRaw(varName, homeDir) {
   if (process.env[varName]) return process.env[varName];
 
-  const projectEnv = path.join(process.cwd(), '.env');
-  if (existsSync(projectEnv)) {
+  for (const envPath of [
+    path.join(process.cwd(), '.env'),
+    path.join(homeDir, '.env'),
+    path.join(homeDir, '.construct', 'config.env'),
+  ]) {
+    if (!existsSync(envPath)) continue;
     try {
-      const content = readFileSync(projectEnv, 'utf8');
+      const content = readFileSync(envPath, 'utf8');
       const m = content.match(new RegExp(`^${varName}=["']?(.+?)["']?$`, 'm'));
       if (m) return m[1].trim();
     } catch { /* skip */ }
   }
 
-  const homeEnv = path.join(homeDir, '.env');
-  if (existsSync(homeEnv)) {
+  const shellFiles = [
+    path.join(homeDir, '.zshrc'),
+    path.join(homeDir, '.bashrc'),
+    path.join(homeDir, '.bash_profile'),
+    path.join(homeDir, '.profile'),
+  ];
+  for (const rcPath of shellFiles) {
+    if (!existsSync(rcPath)) continue;
     try {
-      const content = readFileSync(homeEnv, 'utf8');
-      const m = content.match(new RegExp(`^${varName}=["']?(.+?)["']?$`, 'm'));
-      if (m) return m[1].trim();
+      const content = readFileSync(rcPath, 'utf8');
+      const opRe = new RegExp(`export\\s+${varName}=["']?\\$\\(op read '([^']+)'\\)["']?`, 'm');
+      const opMatch = content.match(opRe);
+      if (opMatch) return opMatch[1];
+      const directRe = new RegExp(`^\\s*export\\s+${varName}=(.+)$`, 'm');
+      const directMatch = content.match(directRe);
+      if (directMatch) return directMatch[1].trim().replace(/^["']|["']$/g, '');
     } catch { /* skip */ }
   }
 
-  const cfgPath = path.join(homeDir, '.construct', 'config.env');
-  if (existsSync(cfgPath)) {
+  return null;
+}
+
+/**
+ * Describe where a credential is configured without resolving op:// refs.
+ */
+export function describeCredentialPresence(varName, { homeDir = os.homedir(), cwd = process.cwd() } = {}) {
+  const sources = [];
+  const direct = process.env[varName];
+  if (direct) {
+    const ref = extractOpRef(direct);
+    sources.push(ref ? `process.env (op:// ref)` : `process.env (plain value)`);
+  }
+
+  for (const envPath of [
+    path.join(cwd, '.env'),
+    path.join(homeDir, '.env'),
+    path.join(homeDir, '.construct', 'config.env'),
+  ]) {
+    if (!existsSync(envPath)) continue;
     try {
-      const content = readFileSync(cfgPath, 'utf8');
-      const m = content.match(new RegExp(`^${varName}=(.+)$`, 'm'));
-      if (m) return m[1].trim();
+      const content = readFileSync(envPath, 'utf8');
+      const m = content.match(new RegExp(`^${varName}=["']?(.+?)["']?$`, 'm'));
+      if (m) {
+        const ref = extractOpRef(m[1]);
+        const label = envPath.replace(homeDir, '~');
+        sources.push(ref ? `${label} (op:// ref)` : `${label} (plain value)`);
+      }
     } catch { /* skip */ }
   }
 
@@ -209,47 +246,18 @@ function getEnvFromShell(varName, homeDir) {
     if (!existsSync(rcPath)) continue;
     try {
       const content = readFileSync(rcPath, 'utf8');
-      const re = new RegExp(`export\\s+${varName}=["']?\\$\\(op read '([^']+)'\\)["']?`, 'm');
-      const m = content.match(re);
-      if (m) {
-        const opRef = m[1];
-        try {
-          const result = spawnSync('op', ['read', opRef], {
-            encoding: 'utf8',
-            stdio: ['pipe', 'pipe', 'pipe'],
-            timeout: 5000,
-          });
-          if (result.status === 0) return result.stdout.trim();
-        } catch { /* op read failed */ }
+      const opRe = new RegExp(`export\\s+${varName}=["']?\\$\\(op read '([^']+)'\\)["']?`, 'm');
+      if (opRe.test(content)) {
+        sources.push(`${rcPath.replace(homeDir, '~')} (op read in rc — use op:// in config.env instead)`);
       }
-    } catch { /* skip unreadable files */ }
-  }
-
-  // If we found an op:// reference but couldn't read it, log the error
-  // for diagnostic purposes when DEBUG is on.
-  if (process.env.CONSTRUCT_DEBUG_CREDENTIALS === '1') {
-    for (const rcPath of shellFiles) {
-      if (!existsSync(rcPath)) continue;
-      try {
-        const content = readFileSync(rcPath, 'utf8');
-        const re = new RegExp(`export\\s+${varName}=["']?\\$\\(op read '([^']+)'\\)["']?`, 'm');
-        const m = content.match(re);
-        if (m) {
-          try {
-            const result = spawnSync('op', ['read', m[1]], { encoding: 'utf8', timeout: 5000 });
-            if (result.status !== 0) {
-              const errMsg = (result.stderr || '').trim().slice(0, 200);
-              process.stderr.write(`[credentials] ${varName}: op read '${m[1]}' failed: ${errMsg}\n`);
-            }
-          } catch (e) {
-            process.stderr.write(`[credentials] ${varName}: op CLI error: ${e.message}\n`);
-          }
-        }
-      } catch { /* skip */ }
-    }
+      const directRe = new RegExp(`^\\s*export\\s+${varName}=`, 'm');
+      if (directRe.test(content) && !sources.some((s) => s.includes(rcPath.replace(homeDir, '~')))) {
+        sources.push(`${rcPath.replace(homeDir, '~')} (export found)`);
+      }
+    } catch { /* skip */ }
   }
 
-  return null;
+  return { configured: hasSecret(varName, { env: process.env, cwd }), sources };
 }
 
 /**
@@ -287,30 +295,34 @@ const CREDENTIAL_VARS = [
 ];
 
 /**
- * Resolve all known credentials from env, .env files, and 1Password.
+ * Link discovered credential references into ~/.construct/config.env without
+ * invoking `op read`. Plain values and op:// refs are persisted as found.
  * @param {Object} options
  * @param {string} options.homeDir
- * @param {boolean} options.writeConfig - Write resolved keys to config.env (default: true)
- * @returns {Promise<Record<string, string>>} resolved key-value pairs
+ * @param {boolean} options.writeConfig - Write keys to config.env (default: false)
+ * @returns {Promise<Record<string, string>>} raw values linked (never plaintext from op)
  */
 export async function resolveCredentials(options = {}) {
-  const { homeDir = os.homedir(), writeConfig = true } = options;
-  const resolved = {};
+  const { homeDir = os.homedir(), writeConfig = false } = options;
+  const linked = {};
+  const { parseEnvFile, getUserEnvPath, writeEnvValues } = await import('./env-config.mjs');
+  const existing = parseEnvFile(getUserEnvPath(homeDir));
 
   for (const varName of CREDENTIAL_VARS) {
-    const value = getEnvFromShell(varName, homeDir);
-    if (value) resolved[varName] = value;
+    if (existing[varName]) continue;
+    const raw = readCredentialRaw(varName, homeDir);
+    if (!raw) continue;
+    const ref = extractOpRef(raw);
+    linked[varName] = ref || raw;
   }
 
-  // Write resolved keys to config.env so subprocesses and the dashboard find them
-  if (writeConfig && Object.keys(resolved).length > 0) {
+  if (writeConfig && Object.keys(linked).length > 0) {
     try {
-      const { writeEnvValues, getUserEnvPath } = await import('./env-config.mjs');
-      writeEnvValues(getUserEnvPath(homeDir), resolved);
+      writeEnvValues(getUserEnvPath(homeDir), linked);
     } catch { /* best effort */ }
   }
 
-  return resolved;
+  return linked;
 }
 
 /**
@@ -327,22 +339,24 @@ export function detectCredentials(options = {}) {
   const ghAuth = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
   found.github_cli = ghAuth.status === 0;
 
-  // GitHub Copilot (check VS Code extension state)
+  // GitHub Copilot: a device-flow credential (Construct's own store or the shared
+  // github-copilot store) is the usable signal; the VS Code extension and the
+  // copilot CLI are softer fallbacks.
+  const copilotAuthStore = existsSync(path.join(homeDir, '.construct', 'auth', 'github-copilot.json')) ||
+    existsSync(path.join(homeDir, '.config', 'github-copilot', 'apps.json')) ||
+    existsSync(path.join(homeDir, '.config', 'github-copilot', 'hosts.json'));
   const copilotDir = path.join(homeDir, '.vscode', 'extensions');
   const copilotExists = existsSync(copilotDir) && existsSync(path.join(homeDir, '.config', 'Code', 'User', 'globalStorage', 'github.copilot'));
-  found.copilot = copilotExists || commandExists('copilot');
+  found.copilot = copilotAuthStore || copilotExists || commandExists('copilot');
 
   // OpenRouter API key
-  found.openrouter_key = !!getEnvFromShell('OPENROUTER_API_KEY', homeDir);
+  found.openrouter_key = hasAnySecret(['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'], { env: process.env, cwd: process.cwd() });
 
-  // Anthropic API key
-  found.anthropic_key = !!getEnvFromShell('ANTHROPIC_API_KEY', homeDir);
+  found.anthropic_key = hasAnySecret(['ANTHROPIC_API_KEY'], { env: process.env, cwd: process.cwd() });
 
-  // OpenAI API key
-  found.openai_key = !!getEnvFromShell('OPENAI_API_KEY', homeDir);
+  found.openai_key = hasAnySecret(['OPENAI_API_KEY'], { env: process.env, cwd: process.cwd() });
 
-  // GitHub token
-  found.github_token = !!getEnvFromShell('GITHUB_TOKEN', homeDir) || !!getEnvFromShell('GH_TOKEN', homeDir);
+  found.github_token = hasAnySecret(['GITHUB_TOKEN', 'GH_TOKEN'], { env: process.env, cwd: process.cwd() });
 
   // VS Code installed
   found.vscode = commandExists('code');