@geraldmaron/construct 1.5.2 → 1.5.3

package/README.md

@@ -22,6 +22,9 @@ Install the CLI (once per machine):
 npm install -g @geraldmaron/construct
 ```
 
+> [!NOTE]
+> npm may print deprecation warnings for `boolean` and `node-domexception` during install. Both are transitive dependencies of upstream packages (`@huggingface/transformers` → `onnxruntime-node` → `global-agent` → `boolean`; `@lancedb/lancedb` → `openai@4.29.2` → `formdata-node` → `node-domexception`) and are harmless. They cannot be silenced from this package — `@lancedb/lancedb` pins `openai@4.29.2` exactly, and npm ignores a package's own `overrides` on end-user installs.
+
 Bootstrap local services (once per machine, opt-in to machine-scope writes):
 
 ```bash
@@ -243,7 +246,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 | `construct improvement` | Governed improvement loop — review, approve, and record apply/rollback for proposals |
 | `construct llm-judge` | Run LLM-as-a-judge evaluations on unscored traces for continuous quality feedback |
 | `construct optimize` | Prompt optimization using telemetry trace quality scores |
-| `construct review` | Generate agent performance review from the configured telemetry trace backend |
+| `construct review` | Agent performance review from telemetry (run\|legacy), or a deterministic PR-diff review for CI (pr) |
 | `construct telemetry` | Query telemetry traces and latency data |
 | `construct telemetry-backfill` | Backfill sparse traces with observations (trace backend) |
 | `construct telemetry-setup` | Configure telemetry backend credentials and trace export (OTLP or Langfuse-compatible) |

package/bin/construct

@@ -1886,10 +1886,10 @@ async function cmdMigrate(args) {
 }
 
 async function cmdReview(args) {
-  fs.mkdirSync(path.join(doctorRoot(), 'performance-reviews'), { recursive: true });
   const sub = args[0];
 
   if (!sub || sub === 'run') {
+    fs.mkdirSync(path.join(doctorRoot(), 'performance-reviews'), { recursive: true });
     const { runGenerator } = await import('../lib/performance/generate.mjs');
     const result = await runGenerator({ env: process.env });
     info(`Wrote ${result.filename} · ${result.agentCount} agent${result.agentCount === 1 ? '' : 's'}`);
@@ -1898,6 +1898,7 @@ async function cmdReview(args) {
   }
 
   if (sub === 'legacy') {
+    fs.mkdirSync(path.join(doctorRoot(), 'performance-reviews'), { recursive: true });
     if (!ENV.CONSTRUCT_TELEMETRY_PUBLIC_KEY || !ENV.CONSTRUCT_TELEMETRY_SECRET_KEY) {
       errorln('Error: CONSTRUCT_TELEMETRY_PUBLIC_KEY and CONSTRUCT_TELEMETRY_SECRET_KEY must be set.');
       errorln('Configure telemetry credentials in ~/.construct/config.env or .env.');
@@ -1907,7 +1908,22 @@ async function cmdReview(args) {
     return;
   }
 
-  errorln('Usage: construct review [run|legacy]');
+  if (sub === 'pr') {
+    const { runReviewPrCli } = await import('../lib/review-pr.mjs');
+    const { exitCode, error, result, json, outputPath } = runReviewPrCli(args.slice(1));
+    if (error) {
+      errorln(error);
+      process.exit(exitCode);
+    }
+    if (outputPath) {
+      info(`Wrote ${outputPath} · ${result.findings.length} finding${result.findings.length === 1 ? '' : 's'}`);
+    } else {
+      println(json);
+    }
+    return;
+  }
+
+  errorln('Usage: construct review [run|legacy|pr --base=<ref> [--output=<file>]]');
   process.exit(1);
 }
 

package/lib/adapters-sync.mjs

@@ -27,7 +27,7 @@ const HOST_ID_MAP = {
 };
 
 export function resolveAdapterHosts({ forceAll = false, extra = [] } = {}) {
-  if (forceAll) return ['claude', 'opencode', 'codex', 'vscode', 'cursor'];
+  if (forceAll) return ['claude', 'opencode', 'codex', 'vscode', 'cursor', 'copilot'];
   const hosts = new Set(extra);
   for (const entry of detectHostCapabilities()) {
     if (entry.availability !== 'installed') continue;

package/lib/auto-docs.mjs

@@ -114,9 +114,13 @@ const DIR_DESCRIPTIONS = {
 };
 
 function buildStructureSection(rootDir) {
+  // git stderr must be discarded: from the published package rootDir is not a
+  // repository, and execSync's default stdio prints "fatal: not a git repository"
+  // to the user's terminal before the catch fires (doctor and sync both hit this).
+
   let trackedDirs;
   try {
-    const out = execSync('git ls-tree --name-only HEAD', { cwd: rootDir, encoding: 'utf8' });
+    const out = execSync('git ls-tree --name-only HEAD', { cwd: rootDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
     trackedDirs = new Set(out.trim().split('\n').filter(Boolean));
   } catch {
     trackedDirs = null;

package/lib/cli-commands.mjs

@@ -602,8 +602,13 @@ export const CLI_COMMANDS = [
     emoji: '📈',
     category: 'Observability',
     core: false,
-    description: 'Generate agent performance review from the configured telemetry trace backend',
-    usage: 'construct review [--agent=<id>] [--days=N]',
+    description: 'Agent performance review from telemetry (run|legacy), or a deterministic PR-diff review for CI (pr)',
+    usage: 'construct review [run|legacy|pr --base=<ref> [--output=<file>]]',
+    subcommands: [
+      { name: 'run', desc: 'Generate the per-agent performance review from local session costs + telemetry' },
+      { name: 'legacy', desc: 'Telemetry pipeline report (requires CONSTRUCT_TELEMETRY_* credentials)' },
+      { name: 'pr', desc: 'Deterministic diff review vs a base ref — secret/quality heuristics, no model, no credentials (backs the CI review gate, ADR-0069)' },
+    ],
   },
   {
     name: 'optimize',

package/lib/decisions/golden.mjs

@@ -12,7 +12,7 @@ import { loadRegistry } from '../registry/loader.mjs';
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
@@ -25,19 +25,18 @@ function hookName(command) {
   return 'cmd';
 }
 
-export function buildSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
+export async function buildSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
   const snapshot = { commands: [], agents: [], hooks: {} };
 
-  const cli = readFileSync(join(repoRoot, 'lib', 'cli-commands.mjs'), 'utf8');
-  const nameRe = /name:\s*'([^']+)'[\s\S]*?core:\s*(true|false)/g;
-  let m;
-  const seen = new Set();
-  while ((m = nameRe.exec(cli)) !== null) {
-    if (seen.has(m[1])) continue;
-    seen.add(m[1]);
-    snapshot.commands.push({ name: m[1], core: m[2] === 'true' });
-  }
-  snapshot.commands.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  // The command surface comes from the CLI_COMMANDS registry module, not a
+  // text scan of its source: the earlier regex scan paired `subcommands:` item
+  // names with the NEXT command's `core:` field, minting phantom commands and
+  // swallowing real ones, so the pinned set never matched the true surface.
+
+  const { CLI_COMMANDS } = await import(pathToFileURL(join(repoRoot, 'lib', 'cli-commands.mjs')).href);
+  snapshot.commands = CLI_COMMANDS
+    .map((c) => ({ name: c.name, core: c.core === true }))
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
   const registry = loadRegistry({ rootDir: repoRoot });
   snapshot.agents = Object.values(registry.specialists || {}).map((s) => s.name).sort();
@@ -59,26 +58,26 @@ function snapshotPath(repoRoot) {
   return join(repoRoot, 'tests', 'fixtures', 'golden', 'surface.json');
 }
 
-export function compareSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
+export async function compareSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
   const file = snapshotPath(repoRoot);
   if (!existsSync(file)) return { ok: false, diffs: ['no committed snapshot — run: construct decisions golden --write'] };
   const expected = JSON.stringify(JSON.parse(readFileSync(file, 'utf8')));
-  const actual = JSON.stringify(buildSurfaceSnapshot({ repoRoot }));
+  const actual = JSON.stringify(await buildSurfaceSnapshot({ repoRoot }));
   if (expected === actual) return { ok: true, diffs: [] };
   return { ok: false, diffs: ['surface snapshot drift — review the change, then regenerate with: construct decisions golden --write'] };
 }
 
-export function writeSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
-  writeFileSync(snapshotPath(repoRoot), JSON.stringify(buildSurfaceSnapshot({ repoRoot }), null, 2) + '\n');
+export async function writeSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
+  writeFileSync(snapshotPath(repoRoot), JSON.stringify(await buildSurfaceSnapshot({ repoRoot }), null, 2) + '\n');
 }
 
 export async function runGoldenCli(args = []) {
   if (args.includes('--write')) {
-    writeSurfaceSnapshot();
+    await writeSurfaceSnapshot();
     process.stdout.write('✓ wrote surface golden snapshot\n');
     return;
   }
-  const { ok, diffs } = compareSurfaceSnapshot();
+  const { ok, diffs } = await compareSurfaceSnapshot();
   if (ok) {
     process.stdout.write('✓ surface matches the golden snapshot\n');
     return;

package/lib/review-pr.mjs

@@ -0,0 +1,102 @@
+/**
+ * lib/review-pr.mjs — deterministic PR-diff review backing `construct review pr`
+ * and the CI `review` gate (.github/workflows/pr-review.yml).
+ *
+ * Reviews HEAD against a base ref under the constraint set of a fork-PR
+ * runner: zero repo secrets and zero model access. Diff shape comes from
+ * summarizeDiff; per-file findings come from scanFile's secret and quality
+ * heuristics over the added and modified files. Findings are advisory — the
+ * command exits non-zero only when the review itself cannot run (bad ref,
+ * not a repository), never on findings, because blocking enforcement belongs
+ * to the dedicated gates (secret scanning, lint suite). ADR-0069 records the
+ * decision that replaced the never-implemented cx-reviewer persona invocation
+ * with this backend.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { scanFile, summarizeDiff } from './mcp/tools/project.mjs';
+
+const MAX_SCANNED_FILES = 200;
+
+export function reviewPrDiff({ baseRef, cwd = process.cwd() } = {}) {
+  if (typeof baseRef !== 'string' || !baseRef.trim()) {
+    return { error: 'baseRef is required' };
+  }
+
+  // Three-dot semantics (merge-base..HEAD) so the review sees only the PR's
+  // own changes, never the base branch's drift since the fork point.
+
+  const base = baseRef.trim();
+  const diff = summarizeDiff({ base_ref: `${base}...HEAD`, cwd });
+  if (diff.error) return { error: diff.error };
+
+  const reviewable = diff.changes.filter((c) => c.status === 'A' || c.status === 'M');
+  const scanned = reviewable.slice(0, MAX_SCANNED_FILES);
+  const skipped = reviewable.length - scanned.length;
+
+  const findings = [];
+  for (const change of scanned) {
+    const scan = scanFile({ cwd, file_path: change.file });
+    if (scan.error) {
+      findings.push({ severity: 'info', file: change.file, message: `${change.file}: not scanned (${scan.error})` });
+      continue;
+    }
+    for (const secret of scan.secrets ?? []) {
+      findings.push({
+        severity: 'high',
+        file: change.file,
+        line: secret.line,
+        message: `possible secret (${secret.pattern}) at ${change.file}:${secret.line}`,
+      });
+    }
+    for (const issue of scan.quality_issues ?? []) {
+      findings.push({
+        severity: 'info',
+        file: change.file,
+        ...(issue.line ? { line: issue.line } : {}),
+        message: `${issue.type} in ${change.file}: ${issue.detail}`,
+      });
+    }
+  }
+
+  const high = findings.filter((f) => f.severity === 'high').length;
+  const counts = `${findings.length} finding${findings.length === 1 ? '' : 's'} (${high} high) across ${scanned.length} scanned file${scanned.length === 1 ? '' : 's'}.`;
+  const cap = skipped > 0 ? ` ${skipped} additional changed file${skipped === 1 ? '' : 's'} not scanned (cap: ${MAX_SCANNED_FILES}).` : '';
+
+  return {
+    generated_by: 'construct review pr',
+    base_ref: base,
+    diff: { files_changed: diff.files_changed, insertions: diff.insertions, deletions: diff.deletions },
+    scanned_files: scanned.length,
+    skipped_files: skipped,
+    summary: `Deterministic diff review — ${diff.summary} ${counts}${cap}`,
+    findings,
+  };
+}
+
+export function runReviewPrCli(argv, { cwd = process.cwd() } = {}) {
+  let baseRef = null;
+  let output = null;
+  for (const arg of argv) {
+    if (arg.startsWith('--base=')) baseRef = arg.slice('--base='.length);
+    else if (arg.startsWith('--output=')) output = arg.slice('--output='.length);
+    else return { exitCode: 1, error: `Unknown argument: ${arg}\nUsage: construct review pr --base=<ref> [--output=<file>]` };
+  }
+  if (!baseRef) {
+    return { exitCode: 1, error: 'Usage: construct review pr --base=<ref> [--output=<file>]' };
+  }
+
+  const result = reviewPrDiff({ baseRef, cwd });
+  if (result.error) return { exitCode: 1, error: result.error };
+
+  const json = JSON.stringify(result, null, 2);
+  let outputPath = null;
+  if (output) {
+    outputPath = path.resolve(cwd, output);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, `${json}\n`);
+  }
+  return { exitCode: 0, result, json, outputPath };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -123,10 +123,6 @@
     "unpdf": "^1.6.2",
     "zod": "^4.4.3"
   },
-  "overrides": {
-    "express-rate-limit": "8.5.1",
-    "undici": "6.27.0"
-  },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
     "c8": "^11.0.0",

package/scripts/sync-specialists.mjs

@@ -1459,12 +1459,21 @@ ${buildPrompt(entry, allEntries, "copilot")}
 }
 
 function syncCopilot(entries, targetDir = null, wants = true) {
+  // Deselected host: leave prior Copilot outputs untouched. Adapter pruning is
+  // explicit-consent-only and `.github` is out of adapter-prune's scope
+  // (lib/reconcile/adapter-prune.mjs), so a sync that did not select copilot
+  // must never delete or degrade another run's files — the old empty-writeEntries
+  // fall-through pruned .github/prompts and .github/agents and blanked the
+  // instructions block on every copilot-less sync (construct-lqp4c).
+
+  if (!wants) return;
+
   const promptsDir = targetDir
     ? path.join(targetDir, ".github", "prompts")
     : path.join(home, ".github", "prompts");
-  if (!DRY_RUN && wants) mkdirp(promptsDir);
+  if (!DRY_RUN) mkdirp(promptsDir);
 
-  const writeEntries = wants ? globalEntries(entries) : [];
+  const writeEntries = globalEntries(entries);
 
   for (const entry of writeEntries) {
     writeFile(path.join(promptsDir, `${adapterName(entry)}.prompt.md`), copilotPrompt(entry, entries), { stamp: false });
@@ -1483,7 +1492,7 @@ function syncCopilot(entries, targetDir = null, wants = true) {
   const agentsDir = targetDir
     ? path.join(targetDir, ".github", "agents")
     : path.join(home, ".github", "agents");
-  if (!DRY_RUN && wants) mkdirp(agentsDir);
+  if (!DRY_RUN) mkdirp(agentsDir);
   for (const entry of writeEntries) {
     writeFile(path.join(agentsDir, `${adapterName(entry)}.agent.md`), copilotAgentFile(entry, entries), { stamp: false });
   }