@cohortapp/agent-sdk 2.3.0

package/scripts/ci/check-no-build-artifacts.mjs

@@ -0,0 +1,111 @@
+/**
+ * check-no-build-artifacts.mjs — packaging hygiene ratchet (Phase 0 item 0.5).
+ *
+ * The npm tarball ships everything under the package.json `files[]` allowlist,
+ * which includes `scripts/`. Two artifact classes must never be tracked there:
+ *
+ *   1. Python bytecode (`*.pyc`, `*.pyo`, anything under `__pycache__/`). Beyond
+ *      being build output, the original instance shipped cross-tenant bytecode
+ *      (e.g. `send-email-as-principal.cpython-313.pyc`) inside the tarball — a
+ *      confidentiality leak that source-level scrubbing alone would miss.
+ *   2. Symlinks. A tracked symlink resolves only on the author's machine
+ *      (the broken `validate_outbound.py -> /Users/agent/...` symlink silently
+ *      disabled Layer-0 outbound validation on every other machine) and cannot
+ *      survive `npm pack`/install intact. Ship real files, never links.
+ *
+ * Source of truth is `git ls-files -s` (the index), so this catches artifacts
+ * the moment they are staged, before they can be published.
+ *
+ * Pure, dependency-light: Node builtins only. ESM.
+ *
+ * Usage: `node scripts/ci/check-no-build-artifacts.mjs`  (exit 0 ok / 1 found)
+ * @module scripts/ci/check-no-build-artifacts
+ */
+
+"use strict";
+
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = path.resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+
+/** Tracked-path patterns that must never appear in the index. @type {Array<{label:string, re:RegExp}>} */
+export const ARTIFACT_PATTERNS = [
+  { label: "python bytecode (*.pyc)", re: /\.pyc$/ },
+  { label: "python bytecode (*.pyo)", re: /\.pyo$/ },
+  { label: "bytecode cache dir (__pycache__)", re: /(^|\/)__pycache__(\/|$)/ },
+];
+
+/** git's mode for a symbolic link entry in `git ls-files -s`. */
+const GIT_SYMLINK_MODE = "120000";
+
+/**
+ * Parse `git ls-files -s` output into {mode, path} rows. Each line is:
+ *   <mode> <object> <stage>\t<path>
+ * @param {string} stdout
+ * @returns {Array<{mode:string, path:string}>}
+ */
+export function parseLsFiles(stdout) {
+  const rows = [];
+  for (const line of stdout.split("\n")) {
+    if (!line) continue;
+    const tab = line.indexOf("\t");
+    if (tab === -1) continue;
+    const meta = line.slice(0, tab).split(/\s+/);
+    const file = line.slice(tab + 1);
+    rows.push({ mode: meta[0] || "", path: file });
+  }
+  return rows;
+}
+
+/**
+ * @param {object} [opts] @param {string} [opts.cwd=REPO_ROOT]
+ * @returns {Array<{ file: string, reason: string }>}
+ */
+export function findArtifacts(opts = {}) {
+  const cwd = opts.cwd || REPO_ROOT;
+  let stdout;
+  try {
+    stdout = execFileSync("git", ["ls-files", "-s"], { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  } catch (err) {
+    // No git / not a work tree: cannot assess, fail closed.
+    throw new Error(`git ls-files failed: ${err && err.message ? err.message : err}`);
+  }
+  const offenders = [];
+  for (const { mode, path: file } of parseLsFiles(stdout)) {
+    if (mode === GIT_SYMLINK_MODE) {
+      offenders.push({ file, reason: "tracked symlink (does not survive npm pack; may point cross-tenant)" });
+      continue;
+    }
+    for (const p of ARTIFACT_PATTERNS) {
+      if (p.re.test(file)) {
+        offenders.push({ file, reason: p.label });
+        break;
+      }
+    }
+  }
+  return offenders;
+}
+
+/** @param {string} [cwd=REPO_ROOT] @returns {Promise<number>} */
+export async function run(cwd = REPO_ROOT) {
+  let offenders;
+  try {
+    offenders = findArtifacts({ cwd });
+  } catch (err) {
+    console.error(`check-no-build-artifacts: ERROR — ${err.message}`);
+    return 2;
+  }
+  if (offenders.length === 0) {
+    console.log("check-no-build-artifacts: OK (no tracked bytecode or symlinks)");
+    return 0;
+  }
+  console.error("check-no-build-artifacts: FAIL — packaging artifacts tracked in the index:");
+  for (const o of offenders) console.error(`  ${o.file} :: ${o.reason}`);
+  return 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run().then((c) => process.exit(c)).catch((e) => { console.error("check-no-build-artifacts: ERROR", e && e.message ? e.message : e); process.exit(2); });
+}

package/scripts/ci/check-no-build-artifacts.test.mjs

@@ -0,0 +1,71 @@
+/**
+ * Tests for check-no-build-artifacts.mjs — packaging hygiene guard.
+ * Pure-function level (parseLsFiles + pattern matching); no git invocation.
+ * @module scripts/ci/check-no-build-artifacts.test
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseLsFiles, ARTIFACT_PATTERNS } from "./check-no-build-artifacts.mjs";
+
+/** Re-implement the offender classification over parsed rows (mirrors findArtifacts' inner loop). */
+function classify(rows) {
+  const out = [];
+  for (const { mode, path: file } of rows) {
+    if (mode === "120000") { out.push({ file, reason: "symlink" }); continue; }
+    for (const p of ARTIFACT_PATTERNS) if (p.re.test(file)) { out.push({ file, reason: p.label }); break; }
+  }
+  return out;
+}
+
+describe("check-no-build-artifacts: parseLsFiles", () => {
+  it("parses mode + path from `git ls-files -s` rows", () => {
+    const stdout = [
+      "100644 abc123 0\tlib/index.js",
+      "120000 def456 0\tscripts/validate_outbound.py",
+      "100755 aaa111 0\tscripts/send-email.sh",
+    ].join("\n");
+    const rows = parseLsFiles(stdout);
+    assert.equal(rows.length, 3);
+    assert.deepEqual(rows[0], { mode: "100644", path: "lib/index.js" });
+    assert.equal(rows[1].mode, "120000");
+    assert.equal(rows[1].path, "scripts/validate_outbound.py");
+  });
+
+  it("ignores blank lines and malformed rows (no tab)", () => {
+    const rows = parseLsFiles("\n100644 abc 0\tok.js\ngarbage-no-tab\n");
+    assert.equal(rows.length, 1);
+    assert.equal(rows[0].path, "ok.js");
+  });
+
+  it("preserves paths containing spaces (split only on the first tab)", () => {
+    const rows = parseLsFiles("100644 abc 0\tdocs/a file with spaces.md");
+    assert.equal(rows[0].path, "docs/a file with spaces.md");
+  });
+});
+
+describe("check-no-build-artifacts: classification", () => {
+  it("flags tracked symlinks", () => {
+    const off = classify(parseLsFiles("120000 x 0\tscripts/validate_outbound.py"));
+    assert.equal(off.length, 1);
+    assert.equal(off[0].reason, "symlink");
+  });
+
+  it("flags .pyc, .pyo, and __pycache__ paths", () => {
+    const off = classify(parseLsFiles([
+      "100644 a 0\tscripts/__pycache__/x.cpython-313.pyc",
+      "100644 b 0\tscripts/foo.pyo",
+      "100644 c 0\tscripts/__pycache__/bar.py",
+    ].join("\n")));
+    assert.equal(off.length, 3);
+  });
+
+  it("passes clean trees (real source files, executable shell)", () => {
+    const off = classify(parseLsFiles([
+      "100644 a 0\tlib/index.js",
+      "100755 b 0\tscripts/send-email.sh",
+      "100644 c 0\tscripts/validate_outbound.py",
+    ].join("\n")));
+    assert.equal(off.length, 0);
+  });
+});

package/scripts/ci/check-no-confidential.mjs

@@ -0,0 +1,198 @@
+/**
+ * check-no-confidential.mjs — CI guard that fails if confidential instance data
+ * would ship in the published npm tarball.
+ *
+ * Why this exists: `@cohortapp/agent-sdk` is a *framework* published (publicly) to
+ * npm and copied into every agent repo. It must never carry one instance's
+ * confidential business data. A path-based prune (`files[]` + `.npmignore`) is
+ * necessary but NOT sufficient — confidential markers leak into otherwise-
+ * legitimate framework files (e.g. architecture docs that use real M&A targets
+ * as examples). This guard inspects the *contents* of every file that would
+ * actually ship (`npm pack --dry-run --json`) for a denylist of markers and
+ * fails closed.
+ *
+ * IMPORTANT — the denylist is NOT hardcoded here. A content-denylist that
+ * embeds the confidential terms would itself become the leak it prevents (a
+ * shipped file that literally lists the protected names). The sensitive
+ * markers live in `<repo>/.confidential-patterns.json`, which is deliberately
+ * NOT shipped (absent from files[]; listed in .npmignore). This source file
+ * contains only safe, generic structural logic. If that denylist file is
+ * absent (e.g. in an installed package or a fork), the content scan is skipped
+ * with a warning and only the generic path check runs.
+ *
+ * Scope note: the denylist is the genuinely-confidential set (named live
+ * acquisition targets, their principals, entity registration numbers) — NOT
+ * pervasive instance identity (the original Sophie/Mehran/Adaptic deployment). De-
+ * identifying those is the check-no-residual-identity guard's job.
+ *
+ * Pure, dependency-light: Node builtins only. ESM ("type":"module").
+ *
+ * Usage: `node scripts/ci/check-no-confidential.mjs`
+ *   exit 0 → clean; exit 1 → confidential content would ship; exit 2 → could
+ *   not run `npm pack` (fail closed for a security guard).
+ *
+ * @module scripts/ci/check-no-confidential
+ */
+
+"use strict";
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Repo root: two levels up from scripts/ci/. @type {string} */
+const REPO_ROOT = path.resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+
+/** Non-shipped denylist file (see header). @type {string} */
+export const DENYLIST_RELATIVE = ".confidential-patterns.json";
+
+/**
+ * Generic, safe-to-ship path markers (directory/category names, not the
+ * confidential association itself). Defense-in-depth against re-adding a
+ * `docs/` blanket to files[].
+ * @type {RegExp}
+ */
+export const DENY_PATH_RE = /(?:^|\/)business-synthesis\/|ownership-structure|final-ownership/i;
+
+/** Extensions whose contents are scanned (text formats only). @type {Set<string>} */
+export const TEXT_EXT = new Set([
+  ".md", ".markdown", ".json", ".yaml", ".yml", ".js", ".mjs", ".cjs",
+  ".ts", ".txt", ".html", ".htm", ".latex", ".tex", ".sh", ".py", ".env", ".example",
+]);
+
+/**
+ * Load and compile content patterns from the non-shipped denylist file.
+ *
+ * @param {string} [cwd=REPO_ROOT]
+ * @returns {{ patterns: Array<{ label: string, re: RegExp }>, present: boolean }}
+ */
+export function loadContentPatterns(cwd = REPO_ROOT) {
+  const file = path.join(cwd, DENYLIST_RELATIVE);
+  if (!existsSync(file)) return { patterns: [], present: false };
+  const raw = JSON.parse(readFileSync(file, "utf8"));
+  const patterns = (raw.contentPatterns || []).map((p) => ({
+    label: p.label || "confidential marker",
+    re: new RegExp(p.pattern, p.flags || ""),
+  }));
+  return { patterns, present: true };
+}
+
+/**
+ * Scan a single text blob for confidential markers. Pure (no I/O) — unit-testable.
+ *
+ * @param {string} text
+ * @param {Array<{ label: string, re: RegExp }>} patterns
+ * @returns {Array<{ label: string, match: string }>}
+ */
+export function scanText(text, patterns) {
+  if (typeof text !== "string" || text.length === 0 || !Array.isArray(patterns)) return [];
+  const hits = [];
+  for (const p of patterns) {
+    const m = text.match(p.re);
+    if (m) hits.push({ label: p.label, match: m[0] });
+  }
+  return hits;
+}
+
+/**
+ * Ask npm which files the tarball would contain.
+ *
+ * @param {string} [cwd=REPO_ROOT]
+ * @returns {string[]} relative paths
+ */
+export function listPackedFiles(cwd = REPO_ROOT) {
+  const out = execFileSync("npm", ["pack", "--dry-run", "--json"], {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const parsed = JSON.parse(out);
+  const entry = Array.isArray(parsed) ? parsed[0] : parsed;
+  const files = (entry && entry.files) || [];
+  return files.map((f) => f.path).filter((p) => typeof p === "string");
+}
+
+/**
+ * Inspect every would-ship file for confidential paths/content.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd=REPO_ROOT]
+ * @param {string[]} [opts.files] - Pre-computed packed file list (skips npm pack).
+ * @param {Array<{ label: string, re: RegExp }>} [opts.patterns] - Pre-loaded content patterns.
+ * @returns {{ ok: boolean, scanned: number, denylistPresent: boolean, pathHits: string[], contentHits: Array<{ file: string, label: string, match: string }> }}
+ */
+export function scanPackedForConfidential(opts = {}) {
+  const cwd = opts.cwd || REPO_ROOT;
+  const files = opts.files || listPackedFiles(cwd);
+  let patterns = opts.patterns;
+  let denylistPresent = true;
+  if (!patterns) {
+    const loaded = loadContentPatterns(cwd);
+    patterns = loaded.patterns;
+    denylistPresent = loaded.present;
+  }
+  const pathHits = files.filter((f) => DENY_PATH_RE.test(f));
+  const contentHits = [];
+  let scanned = 0;
+  if (patterns.length > 0) {
+    for (const rel of files) {
+      const ext = path.extname(rel).toLowerCase();
+      if (!TEXT_EXT.has(ext)) continue;
+      const abs = path.resolve(cwd, rel);
+      if (!existsSync(abs)) continue;
+      let body;
+      try {
+        body = readFileSync(abs, "utf8");
+      } catch {
+        continue;
+      }
+      scanned++;
+      for (const hit of scanText(body, patterns)) {
+        contentHits.push({ file: rel, label: hit.label, match: hit.match });
+      }
+    }
+  }
+  return { ok: pathHits.length === 0 && contentHits.length === 0, scanned, denylistPresent, pathHits, contentHits };
+}
+
+/**
+ * Run the guard and print a human report.
+ *
+ * @param {string} [cwd=REPO_ROOT]
+ * @returns {Promise<number>} exit code (0 ok, 1 leak found, 2 could not run).
+ */
+export async function run(cwd = REPO_ROOT) {
+  let result;
+  try {
+    result = scanPackedForConfidential({ cwd });
+  } catch (err) {
+    console.error("check-no-confidential: ERROR — could not run `npm pack --dry-run --json` (failing closed):", err && err.message ? err.message : err);
+    return 2;
+  }
+  const { ok, scanned, denylistPresent, pathHits, contentHits } = result;
+  if (!denylistPresent) {
+    console.warn(`check-no-confidential: WARN — ${DENYLIST_RELATIVE} not present; ran path-only scan (content scan skipped).`);
+  }
+  if (ok) {
+    const mode = denylistPresent ? `${scanned} packed text files scanned` : "path-only";
+    console.log(`check-no-confidential: OK (${mode}; no confidential markers)`);
+    return 0;
+  }
+  console.error("check-no-confidential: FAIL — confidential content would ship in the npm tarball:");
+  for (const p of pathHits) console.error(`  [path]    ${p}`);
+  for (const c of contentHits) console.error(`  [content] ${c.file} :: ${c.label} ("${c.match}")`);
+  console.error(`check-no-confidential: ${pathHits.length} path hit(s) + ${contentHits.length} content hit(s)`);
+  return 1;
+}
+
+// Run when invoked directly (not when imported).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error("check-no-confidential: ERROR", err && err.message ? err.message : err);
+      process.exit(2);
+    });
+}

package/scripts/ci/check-no-conflict-markers.mjs

@@ -0,0 +1,169 @@
+/**
+ * check-no-conflict-markers.mjs — CI guard that fails if any tracked file
+ * contains a git merge-conflict marker.
+ *
+ * Ported/adapted from OpenClaw's scripts/check-no-conflict-markers.mjs idea.
+ * Pure, dependency-light: Node builtins + git (via execFile) only. ESM module
+ * (maestro is "type":"module").
+ *
+ * A successful `git merge` that hit a conflict leaves lines like
+ * `<<<<<<< HEAD`, `=======`, `>>>>>>> branch`, and (with merge.conflictStyle
+ * diff3) `||||||| base`. If one of those slips past review into a commit, the
+ * code may still parse but is semantically broken. This guard scans every
+ * tracked, text file for those exact markers and exits non-zero if found.
+ *
+ * Usage (standalone): `node scripts/ci/check-no-conflict-markers.mjs`
+ *   exit 0 → clean; exit 1 → markers found (details printed to stderr).
+ *
+ * Programmatic: `import { findConflictMarkers, lineHasConflictMarker } from "./check-no-conflict-markers.mjs"`
+ *
+ * @module scripts/ci/check-no-conflict-markers
+ */
+
+"use strict";
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const execFileAsync = promisify(execFile);
+
+/** Repo root: two levels up from scripts/ci/. @type {string} */
+const REPO_ROOT = path.resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+
+/**
+ * Conflict-marker prefixes. A line is a marker if, after stripping a trailing
+ * carriage return, it equals one of these or starts with one followed by a
+ * space. Markers are exactly seven repeated characters — we match the prefix
+ * and then require either end-of-line or a single space so that e.g. a markdown
+ * rule of eight or more `=` does not false-positive.
+ * @type {string[]}
+ */
+const MARKER_PREFIXES = ["<<<<<<<", "=======", ">>>>>>>", "|||||||"];
+
+/**
+ * True if a single line of text is a git conflict marker.
+ *
+ * @param {string} line - One line of file content (without the newline).
+ * @returns {boolean}
+ */
+export function lineHasConflictMarker(line) {
+  if (typeof line !== "string") return false;
+  // Tolerate CRLF: drop a trailing carriage return.
+  const trimmed = line.endsWith("\r") ? line.slice(0, -1) : line;
+  for (const prefix of MARKER_PREFIXES) {
+    if (trimmed === prefix) return true;
+    if (trimmed.startsWith(prefix + " ")) return true;
+  }
+  return false;
+}
+
+/**
+ * Scan a blob of file content for conflict markers.
+ *
+ * @param {string} content - Full file text.
+ * @returns {Array<{ line: number, text: string }>} 1-based line hits.
+ */
+export function scanContentForMarkers(content) {
+  if (typeof content !== "string" || content.length === 0) return [];
+  const hits = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (lineHasConflictMarker(lines[i])) {
+      hits.push({ line: i + 1, text: lines[i].replace(/\r$/, "") });
+    }
+  }
+  return hits;
+}
+
+/**
+ * Heuristic: skip obviously-binary content so we don't read megabytes of
+ * images/audio looking for ASCII markers. A NUL byte in the first 8 KiB is the
+ * classic "this is binary" signal git itself uses.
+ *
+ * @param {Buffer} buf
+ * @returns {boolean}
+ */
+function looksBinary(buf) {
+  const n = Math.min(buf.length, 8192);
+  for (let i = 0; i < n; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+/**
+ * List every tracked file path (relative to repo root) via git.
+ *
+ * @param {string} [cwd=REPO_ROOT]
+ * @returns {Promise<string[]>}
+ */
+export async function listTrackedFiles(cwd = REPO_ROOT) {
+  // -z gives NUL-separated paths so filenames with spaces/newlines are safe.
+  const { stdout } = await execFileAsync("git", ["ls-files", "-z"], {
+    cwd,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return stdout.split("\0").filter((p) => p.length > 0);
+}
+
+/**
+ * Scan all tracked files for conflict markers.
+ *
+ * @param {string} [cwd=REPO_ROOT]
+ * @returns {Promise<Array<{ file: string, hits: Array<{ line: number, text: string }> }>>}
+ *   One entry per offending file. Empty array means the tree is clean.
+ */
+export async function findConflictMarkers(cwd = REPO_ROOT) {
+  const files = await listTrackedFiles(cwd);
+  const offenders = [];
+  for (const rel of files) {
+    const abs = path.resolve(cwd, rel);
+    let buf;
+    try {
+      buf = await readFile(abs);
+    } catch {
+      // File tracked but missing on disk (sparse checkout, deleted-not-staged):
+      // nothing to scan, skip quietly.
+      continue;
+    }
+    if (looksBinary(buf)) continue;
+    const hits = scanContentForMarkers(buf.toString("utf8"));
+    if (hits.length > 0) offenders.push({ file: rel, hits });
+  }
+  return offenders;
+}
+
+/**
+ * Run the check and print a human report.
+ *
+ * @param {string} [cwd=REPO_ROOT]
+ * @returns {Promise<number>} Process exit code (0 = clean, 1 = markers found).
+ */
+export async function run(cwd = REPO_ROOT) {
+  const offenders = await findConflictMarkers(cwd);
+  if (offenders.length === 0) {
+    console.log("check-no-conflict-markers: OK (no conflict markers in tracked files)");
+    return 0;
+  }
+  console.error("check-no-conflict-markers: FAIL — conflict markers found:");
+  for (const { file, hits } of offenders) {
+    for (const h of hits) {
+      console.error(`  ${file}:${h.line}: ${h.text}`);
+    }
+  }
+  console.error(`check-no-conflict-markers: ${offenders.length} file(s) contain conflict markers`);
+  return 1;
+}
+
+// Run when invoked directly (not when imported).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error("check-no-conflict-markers: ERROR", err && err.message ? err.message : err);
+      process.exit(2);
+    });
+}