connections-architect 0.2.0

package/src/core/runner.mjs

@@ -0,0 +1,140 @@
+// The runner — distilled from arkitect's: per-check gating, crash≠drift, gating-vs-advisory, and the
+// agent-facing FIX_QUEUE.md + manifest.json with `pass.nextAction`. Splits checks by domain: `code`
+// checks always run; `hosted` checks run only when a vault handle is present (so plain `npx architect`
+// runs the code half with no cloud creds).
+// Phase 2: also writes tmp/architect/findings.sarif (SARIF 2.1.0) and tmp/architect/DECISION_BRIEF.json.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { countSeverities } from "./finding.mjs";
+import { checkAppliesToProject } from "./project-detect.mjs";
+import { toSarif } from "./sarif.mjs";
+
+export async function runAudits(audits, ctxBase, { outDir }) {
+  mkdirSync(outDir, { recursive: true });
+  const results = [];
+  for (const audit of audits) {
+    if (!checkAppliesToProject(audit.requires, ctxBase.project)) {
+      results.push({ id: audit.id, audit, status: "skipped", reason: "requires-not-met" });
+      continue;
+    }
+    if (audit.domain === "hosted" && !ctxBase.vault) {
+      results.push({ id: audit.id, audit, status: "skipped", reason: "no-vault: run via the Connections MCP to enable hosted checks" });
+      continue;
+    }
+    const checkConfig = { ...(audit.defaultConfig || {}), ...((ctxBase.config?.checks || {})[audit.id] || {}) };
+    const ctx = { ...ctxBase, checkConfig };
+    let out;
+    try {
+      out = await audit.run(ctx);
+    } catch (e) {
+      // A check that THROWS always fails the run, separately from findings — never a silent pass.
+      results.push({
+        id: audit.id,
+        audit,
+        status: "crashed",
+        error: String(e?.stack || e?.message || e).split("\n").slice(0, 3).join("\n"),
+        findings: [],
+        failed: true,
+      });
+      continue;
+    }
+    const findings = out?.findings || [];
+    const counts = countSeverities(findings);
+    const failed = out?.failed ?? counts.errors > 0;
+    if (out?.report && (failed || counts.warnings > 0)) {
+      const path = out.outputPath || join(outDir, `${audit.id}.md`);
+      try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, out.report);
+      } catch {
+        /* best-effort report write */
+      }
+    }
+    results.push({ id: audit.id, audit, status: failed ? "failed" : counts.warnings ? "warned" : "clean", findings, counts, failed });
+  }
+  return summarize(results, outDir);
+}
+
+function rank(r) {
+  if (r.status === "crashed") return 0;
+  if (r.status === "failed") return 1;
+  return 2;
+}
+
+const SEV_ORDER = { error: 0, warning: 1, info: 2 };
+
+function summarize(results, outDir) {
+  let totalErrors = 0,
+    gatingErrors = 0,
+    warnings = 0,
+    crashed = 0;
+  for (const r of results) {
+    if (r.status === "crashed") {
+      crashed++;
+      gatingErrors++;
+      continue;
+    }
+    const c = r.counts || { errors: 0, warnings: 0 };
+    totalErrors += c.errors;
+    warnings += c.warnings;
+    // `gating !== false` ⇒ a check gates the run; advisory checks (gating:false) surface but never block.
+    if (r.audit.gating !== false && r.failed) gatingErrors += c.errors || 1;
+  }
+  const clean = gatingErrors === 0;
+  const nextAction = gatingErrors > 0 ? "fix-errors" : warnings > 0 ? "review-warnings" : "done";
+
+  const offenders = results
+    .filter((r) => r.status === "failed" || r.status === "crashed" || r.status === "warned")
+    .sort((a, b) => rank(a) - rank(b));
+  const queue = offenders.map((r) => {
+    const tag = r.status === "crashed" ? "CRASH" : r.audit.gating === false ? "ADVISORY" : r.status === "warned" ? "WARN" : "ERROR";
+    const detail = r.status === "crashed" ? `  ${r.error?.split("\n")[0] || ""}` : `  (${r.counts?.errors || 0}e/${r.counts?.warnings || 0}w)`;
+    return `- [${tag}] ${r.id} — ${r.audit.title}${detail}`;
+  });
+  writeFileSync(join(outDir, "FIX_QUEUE.md"), `# Architect — Fix Queue\n\nnextAction: ${nextAction}\n\n${queue.join("\n") || "✅ all clean"}\n`);
+
+  const manifest = {
+    totalErrors,
+    gatingErrors,
+    warnings,
+    crashed,
+    checks: results.map((r) => ({
+      id: r.id,
+      group: r.audit.__group ?? null,
+      status: r.status,
+      errors: r.counts?.errors || 0,
+      warnings: r.counts?.warnings || 0,
+      ...(r.reason ? { reason: r.reason } : {}),
+    })),
+    pass: { clean, nextAction },
+  };
+  writeFileSync(join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+
+  // Phase 2: SARIF 2.1.0 output.
+  try {
+    writeFileSync(join(outDir, "findings.sarif"), JSON.stringify(toSarif(results), null, 2));
+  } catch {
+    /* best-effort */
+  }
+
+  // Phase 2: DECISION_BRIEF — flat, sorted array of all findings enriched with check metadata.
+  try {
+    const brief = [];
+    for (const r of results) {
+      for (const f of r.findings || []) {
+        brief.push({ ...f, checkId: r.id, checkTitle: r.audit?.title ?? r.id });
+      }
+    }
+    brief.sort((a, b) => {
+      const sa = SEV_ORDER[a.severity] ?? 99;
+      const sb = SEV_ORDER[b.severity] ?? 99;
+      if (sa !== sb) return sa - sb;
+      return (a.checkId ?? "").localeCompare(b.checkId ?? "");
+    });
+    writeFileSync(join(outDir, "DECISION_BRIEF.json"), JSON.stringify(brief, null, 2));
+  } catch {
+    /* best-effort */
+  }
+
+  return { results, manifest, outDir };
+}

package/src/core/sarif.mjs

@@ -0,0 +1,81 @@
+// SARIF 2.1.0 emitter — converts architect run results into the Static Analysis Results Interchange Format
+// understood by GitHub Code Scanning, VS Code, and CI toolchains. Zero external dependencies.
+// Spec: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+
+/**
+ * Map an architect finding severity to a SARIF level.
+ * SARIF levels: "error" | "warning" | "note" | "none"
+ */
+function toSarifLevel(severity) {
+  if (severity === "error") return "error";
+  if (severity === "warning") return "warning";
+  return "note"; // info → note
+}
+
+/**
+ * Convert a flat array of per-check run results (as returned by runner.runAudits) into a SARIF 2.1.0 object.
+ *
+ * @param {Array<{id:string, audit:{id:string,title:string}, findings?:Array, status:string}>} results
+ * @returns {object}  SARIF 2.1.0 document
+ */
+export function toSarif(results) {
+  // Collect unique rule definitions (one per unique check id that produced findings).
+  const rulesById = new Map();
+  const sarifResults = [];
+
+  for (const r of results) {
+    const findings = r.findings || [];
+    if (!findings.length) continue;
+
+    const ruleId = r.id;
+    if (!rulesById.has(ruleId)) {
+      rulesById.set(ruleId, {
+        id: ruleId,
+        name: r.audit?.title ?? ruleId,
+        shortDescription: { text: r.audit?.title ?? ruleId },
+      });
+    }
+
+    for (const f of findings) {
+      const result = {
+        ruleId,
+        level: toSarifLevel(f.severity),
+        message: { text: f.message || f.title || ruleId },
+      };
+
+      // Physical location — only when we have a file reference.
+      if (f.file) {
+        const loc = {
+          physicalLocation: {
+            artifactLocation: {
+              // SARIF URIs use forward-slash separators and are typically relative.
+              uri: f.file.replace(/\\/g, "/"),
+            },
+          },
+        };
+        if (typeof f.line === "number" && f.line > 0) {
+          loc.physicalLocation.region = { startLine: f.line };
+        }
+        result.locations = [loc];
+      }
+
+      sarifResults.push(result);
+    }
+  }
+
+  return {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "@connections/architect",
+            rules: [...rulesById.values()],
+          },
+        },
+        results: sarifResults,
+      },
+    ],
+  };
+}

package/src/update/publish-core.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// publish-core — RELEASE-TIME publisher for the Architect CORE (mirror of services/studio/local-mcp/
+// publish-impl.mjs). Bundles src/core/ + src/checks/ into a SHA-pinned manifest and uploads it +
+// version.json to a public-read S3 object, so every installed @connections/architect self-updates its
+// core on next run (see self-update.mjs). This is NOT part of the dev/test loop — run it at release.
+// Creds: value-blind from break-glass/sia (same pattern as the rest of the repo's break-glass scripts).
+//
+//   node src/update/publish-core.mjs
+import { readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve, relative } from "node:path";
+import { walkFiles } from "../core/fs-walk.mjs";
+import { sha256Hex } from "./self-update.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG = resolve(HERE, "..", ".."); // packages/connections-architect
+const SRC = join(PKG, "src");
+const REPO = resolve(PKG, "..", ".."); // repo root
+const ACCT = "637560253023";
+const REGION = "us-east-1";
+const BUCKET = `connections-architect-core-${ACCT}`;
+const AWS = process.env.AWS_CLI || "aws";
+const TMP = os.tmpdir();
+
+const version = JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version;
+
+// Build the manifest: every core/ + checks/ .mjs as { "core/…": source }. (Posix-normalized paths.)
+const files = {};
+for (const top of ["core", "checks"]) {
+  for (const f of walkFiles(join(SRC, top))) {
+    if (!f.endsWith(".mjs")) continue;
+    files[relative(SRC, f).split("\\").join("/")] = readFileSync(f, "utf8");
+  }
+}
+const sha = sha256Hex(JSON.stringify(files));
+const manifest = { version, sha, files };
+console.log(`Architect core v${version}: ${Object.keys(files).length} files, sha ${sha.slice(0, 16)}…`);
+
+// ── creds: value-blind from break-glass/sia (split JSON objects, match this account) ───────────────────
+function splitObjects(t) {
+  const out = [];
+  let d = 0, s = -1, inS = false, esc = false;
+  for (let i = 0; i < t.length; i++) {
+    const c = t[i];
+    if (inS) { if (esc) esc = false; else if (c === "\\") esc = true; else if (c === '"') inS = false; continue; }
+    if (c === '"') inS = true;
+    else if (c === "{") { if (d === 0) s = i; d++; }
+    else if (c === "}") { d--; if (d === 0 && s >= 0) { out.push(t.slice(s, i + 1)); s = -1; } }
+  }
+  return out;
+}
+const cred = splitObjects(readFileSync(join(REPO, "break-glass", "sia"), "utf8").replace(/^/, ""))
+  .map((s) => { try { return JSON.parse(s); } catch { return null; } })
+  .filter(Boolean)
+  .find((o) => String(o.accountId) === ACCT && /^AKIA[A-Z0-9]{16}$/.test(o.accessKeyId || ""));
+if (!cred) {
+  console.error(`no Studio (${ACCT}) creds in break-glass/sia`);
+  process.exit(1);
+}
+const env = { ...process.env, AWS_ACCESS_KEY_ID: cred.accessKeyId, AWS_SECRET_ACCESS_KEY: cred.secretAccessKey, AWS_DEFAULT_REGION: REGION, AWS_PAGER: "" };
+const run = (args, ok) => {
+  try { return { ok: true, out: execFileSync(AWS, args, { env, encoding: "utf8", maxBuffer: 1 << 26, shell: true }) }; }
+  catch (e) { const m = String(e.stderr || e.message || ""); return ok && ok(m) ? { ok: true, out: m } : { ok: false, out: m }; }
+};
+
+// bucket + public-read policy (idempotent), then upload the manifest + a small version.json pointer.
+if (!run(["s3api", "head-bucket", "--bucket", BUCKET]).ok) run(["s3api", "create-bucket", "--bucket", BUCKET, "--region", REGION]);
+run(["s3api", "put-public-access-block", "--bucket", BUCKET, "--public-access-block-configuration", "BlockPublicAcls=false,IgnorePublicAcls=false,BlockPublicPolicy=false,RestrictPublicBuckets=false"]);
+const polFile = join(TMP, "architect-core-policy.json");
+writeFileSync(polFile, JSON.stringify({ Version: "2012-10-17", Statement: [{ Sid: "PublicReadCore", Effect: "Allow", Principal: "*", Action: "s3:GetObject", Resource: `arn:aws:s3:::${BUCKET}/*` }] }));
+run(["s3api", "put-bucket-policy", "--bucket", BUCKET, "--policy", `file://${polFile}`]);
+
+const manFile = join(TMP, "architect-core.json");
+const verFile = join(TMP, "architect-version.json");
+writeFileSync(manFile, JSON.stringify(manifest));
+writeFileSync(verFile, JSON.stringify({ version, sha, fileCount: Object.keys(files).length }));
+const up1 = run(["s3", "cp", manFile, `s3://${BUCKET}/architect-core.json`, "--content-type", "application/json", "--cache-control", "max-age=60", "--metadata-directive", "REPLACE"]);
+const up2 = run(["s3", "cp", verFile, `s3://${BUCKET}/version.json`, "--content-type", "application/json", "--cache-control", "max-age=60", "--metadata-directive", "REPLACE"]);
+if (!up1.ok || !up2.ok) {
+  console.error("upload failed:\n" + (up1.out || "") + "\n" + (up2.out || ""));
+  process.exit(1);
+}
+
+// verify live
+const url = `https://${BUCKET}.s3.${REGION}.amazonaws.com/architect-core.json`;
+const res = await fetch(url, { headers: { accept: "application/json" } });
+const body = await res.json().catch(() => null);
+const valid = res.ok && body?.version === version && body?.sha === sha;
+console.log(`GET ${url} → HTTP ${res.status} · sha ${body?.sha === sha ? "match" : "MISMATCH"}`);
+console.log(valid ? `\n✅ PUBLISHED + verified: Architect core v${version}` : `\n❌ verification failed`);
+process.exit(valid ? 0 : 1);

package/src/update/self-update.mjs

@@ -0,0 +1,90 @@
+// Self-update — the Architect's pull-and-refresh channel, a direct mirror of the MCP loader.mjs
+// resilience ladder applied to the CORE. On launch (gated by config.update), fetch the published core
+// manifest from Connections, SHA-verify it, and swap the shipped core (src/core + src/checks) in place,
+// keeping a `.prev` for rollback. It NEVER writes outside core/+checks/, so your-checks/ and your config
+// stay yours and the core stays updatable underneath them — exactly the loader's "push to AWS, every
+// machine updates next run" property.
+import { createHash } from "node:crypto";
+import { writeFileSync, mkdirSync, rmSync, cpSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+export const DEFAULT_CORE_URL = "https://connections-architect-core-637560253023.s3.us-east-1.amazonaws.com";
+
+export function sha256Hex(s) {
+  return createHash("sha256").update(s).digest("hex");
+}
+
+// Strictly-newer semver-ish compare ("1.4.0" > "1.3.9").
+export function isNewer(a, b) {
+  const pa = String(a).split(".").map(Number);
+  const pb = String(b).split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x > y;
+  }
+  return false;
+}
+
+// A core manifest is { version, sha, files: { "core/finding.mjs": "<source>", "checks/code/x.mjs": "…" } }.
+// `sha` is sha256 of JSON.stringify(files). Apply it to <srcDir> (the package's src/), with a .prev backup
+// and rollback on any write error. Only ever writes under core/ + checks/.
+export function applyCoreManifest(manifest, srcDir) {
+  if (!manifest || typeof manifest.version !== "string" || !manifest.files || typeof manifest.files !== "object") {
+    throw new Error("invalid core manifest");
+  }
+  const got = sha256Hex(JSON.stringify(manifest.files));
+  if (manifest.sha && manifest.sha !== got) {
+    throw new Error(`core manifest SHA mismatch (want ${String(manifest.sha).slice(0, 12)}…, got ${got.slice(0, 12)}…)`);
+  }
+  const prev = srcDir + ".prev";
+  try {
+    rmSync(prev, { recursive: true, force: true });
+    cpSync(srcDir, prev, { recursive: true });
+  } catch {
+    /* best-effort backup */
+  }
+  try {
+    let applied = 0;
+    for (const [rel, content] of Object.entries(manifest.files)) {
+      if (!/^(core|checks)\//.test(rel) || rel.includes("..")) continue; // never escape core/+checks/
+      const path = join(srcDir, rel);
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, content, "utf8");
+      applied++;
+    }
+    return { applied, version: manifest.version };
+  } catch (e) {
+    // Roll back to the last-good core — never leave a half-written core (loader.mjs's .prev restore).
+    try {
+      rmSync(srcDir, { recursive: true, force: true });
+      cpSync(prev, srcDir, { recursive: true });
+    } catch {
+      /* best-effort restore */
+    }
+    throw e;
+  }
+}
+
+// Orchestration: version-gate → fetch manifest → SHA-verify → apply. Network-gated and fail-soft: any
+// error (offline, 404, bad SHA) keeps the current cached core so a user's run is NEVER broken by an
+// update attempt. Inert until the core bucket exists (pre-release it simply skips).
+export async function selfUpdate({ installedVersion, srcDir, config = {}, coreUrl = DEFAULT_CORE_URL, fetchImpl = fetch }) {
+  const u = config.update || {};
+  if (u.autoUpdate === false) return { skipped: "disabled" };
+  if (u.pinnedVersion) return { skipped: "pinned", pinned: u.pinnedVersion };
+  if (process.env.ARCHITECT_NO_SELF_UPDATE) return { skipped: "env-disabled" };
+  try {
+    const vRes = await fetchImpl(`${coreUrl}/version.json`, { signal: AbortSignal.timeout(5000) });
+    if (!vRes.ok) return { skipped: "no-version" };
+    const v = await vRes.json();
+    if (!v?.version || !isNewer(v.version, installedVersion)) return { skipped: "up-to-date", remote: v?.version };
+    const mRes = await fetchImpl(`${coreUrl}/architect-core.json`, { signal: AbortSignal.timeout(8000) });
+    if (!mRes.ok) return { skipped: "no-manifest" };
+    const manifest = await mRes.json();
+    if (!isNewer(manifest.version, installedVersion)) return { skipped: "stale-manifest" };
+    return applyCoreManifest(manifest, srcDir);
+  } catch (e) {
+    return { skipped: "error", error: String(e?.message || e) };
+  }
+}

package/your-checks/README.md

@@ -0,0 +1,27 @@
+# your-checks/
+
+Your own Architect checks live here. **The core never touches this folder** — self-update only ever
+refreshes the shipped core, so your rules stay yours while the core keeps improving underneath them.
+
+A check is any `.mjs` exporting `audit`:
+
+```js
+export const audit = {
+  id: "my-rule",        // unique; SAME id as a core check ⇒ yours SHADOWS the core's
+  title: "My rule",
+  category: "custom",
+  domain: "code",       // "code" (your repo) | "hosted" (your cloud, via the MCP vault)
+  requires: {},         // {} = any repo; e.g. { ecosystems: ["npm"] }
+  gating: false,        // true ⇒ blocks `architect --fail-on-drift`
+  async run(ctx) {
+    // ctx = { root, config, checkConfig, project, vault? }
+    return { failed: false, findings: [/* createFinding(...) */], report: "" };
+  },
+};
+```
+
+Drop it under `your-checks/code/` (or `your-checks/hosted/`) and it auto-registers — no wiring. Copy
+`code/example-check.mjs` to start. Import helpers with `import { createFinding, walkFiles } from "connections-architect"`.
+
+**Forking / pinning:** set `update.autoUpdate: false` (or pin `update.pinnedVersion`) in `architect.config.json`
+to stop pulling the core entirely and own it outright — GitHub-fork style.

package/your-checks/code/example-check.mjs

@@ -0,0 +1,24 @@
+// ── Your own check. Copy this file, rename it, make it yours. ──
+// The Architect core NEVER overwrites anything under your-checks/ — your rules stay yours while the core
+// keeps improving underneath them. A check is just a module exporting `audit` with an `id` + `run(ctx)`.
+//
+//   import { createFinding, walkFiles } from "connections-architect";
+//
+// (Plain { id, title, severity, file, line, message } objects work too — createFinding just fills defaults.)
+
+export const audit = {
+  id: "example-your-check",
+  title: "Example — your own check goes here",
+  category: "custom",
+  domain: "code", // "code" runs in your repo; "hosted" runs through the MCP vault against your cloud
+  requires: {}, // {} = any repo; e.g. { ecosystems: ["npm"] } to scope it
+  gating: false, // true ⇒ blocks `architect --fail-on-drift`
+  async run(ctx) {
+    // ctx = { root, config, checkConfig, project, vault? }
+    // Example skeleton:
+    //   const findings = [];
+    //   for (const file of walkFiles(ctx.root)) { /* inspect; push createFinding(...) */ }
+    //   return { failed: findings.some(f => f.severity === "error"), findings, report: "" };
+    return { failed: false, findings: [], report: "" };
+  },
+};