chore: import upstream snapshot with attribution

examples/integrations/_parity/lib/diff.ts

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+
+export function sha256(buf: Buffer | string): string {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+export function fileSha256(path: string): string {
+  return sha256(readFileSync(path));
+}
+
+export function fileExists(path: string): boolean {
+  try {
+    statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getByPath(obj: unknown, path: string): unknown {
+  const parts = path.split(".");
+  let cur: unknown = obj;
+  for (const part of parts) {
+    if (cur == null || typeof cur !== "object") return undefined;
+    cur = (cur as Record<string, unknown>)[part];
+  }
+  return cur;
+}
+
+export function setByPath(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const parts = path.split(".");
+  let cur: Record<string, unknown> = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i]!;
+    const next = cur[key];
+    if (next == null || typeof next !== "object" || Array.isArray(next)) {
+      cur[key] = {};
+    }
+    cur = cur[key] as Record<string, unknown>;
+  }
+  cur[parts[parts.length - 1]!] = value;
+}

examples/integrations/_parity/lib/manifest.ts

@@ -0,0 +1,96 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export type InstanceRole = "north-star" | "instance";
+
+export interface AgentSurface {
+  toolNames: string[];
+  stateKeys: string[];
+  modelFamily: string;
+}
+
+export interface TrackedSurface {
+  verbatimFiles: string[];
+  packageJsonPaths: string[];
+  agentSurface: AgentSurface;
+}
+
+export interface InstanceAgent {
+  language: "python" | "typescript";
+  runtime: string;
+}
+
+export interface Instance {
+  role: InstanceRole;
+  agent: InstanceAgent;
+  allowedDivergence: string[];
+  packageJsonOverrides: Record<string, string>;
+}
+
+export interface Manifest {
+  version: number;
+  northStar: string;
+  canonicalPromptFile: string;
+  tracked: TrackedSurface;
+  instances: Record<string, Instance>;
+}
+
+export interface ParityRoot {
+  /** Absolute path to the parity dir, e.g. …/examples/integrations/_parity */
+  parityDir: string;
+  /** Absolute path to the integrations root, e.g. …/examples/integrations */
+  integrationsDir: string;
+  manifest: Manifest;
+}
+
+export function loadManifest(parityDir: string): ParityRoot {
+  const manifestPath = resolve(parityDir, "manifest.json");
+  const raw = readFileSync(manifestPath, "utf8");
+  const parsed = JSON.parse(raw) as Manifest;
+  validate(parsed, manifestPath);
+  return {
+    parityDir,
+    integrationsDir: resolve(parityDir, ".."),
+    manifest: parsed,
+  };
+}
+
+function validate(m: Manifest, source: string): void {
+  const err = (msg: string): never => {
+    throw new Error(`[parity] invalid manifest at ${source}: ${msg}`);
+  };
+  if (m.version !== 1) err(`unsupported version ${m.version}`);
+  if (!m.northStar) err("missing northStar");
+  if (!m.instances?.[m.northStar])
+    err(`northStar '${m.northStar}' not in instances`);
+  if (m.instances[m.northStar].role !== "north-star")
+    err(`northStar '${m.northStar}' must have role=north-star`);
+
+  const nonNorthStar = Object.entries(m.instances).filter(
+    ([n]) => n !== m.northStar,
+  );
+  for (const [name, inst] of nonNorthStar) {
+    if (inst.role !== "instance")
+      err(`instance '${name}' must have role=instance`);
+  }
+
+  if (!m.tracked?.verbatimFiles?.length) err("tracked.verbatimFiles empty");
+  if (!m.tracked?.packageJsonPaths?.length)
+    err("tracked.packageJsonPaths empty");
+  if (!m.tracked?.agentSurface?.toolNames?.length)
+    err("tracked.agentSurface.toolNames empty");
+}
+
+export function instanceDir(root: ParityRoot, name: string): string {
+  return resolve(root.integrationsDir, name);
+}
+
+export function northStarDir(root: ParityRoot): string {
+  return instanceDir(root, root.manifest.northStar);
+}
+
+export function listInstances(root: ParityRoot): string[] {
+  return Object.keys(root.manifest.instances).filter(
+    (n) => n !== root.manifest.northStar,
+  );
+}

examples/integrations/_parity/lib/report.ts

@@ -0,0 +1,77 @@
+export type Severity = "ok" | "warn" | "error";
+
+export interface DriftItem {
+  severity: Severity;
+  instance: string;
+  kind:
+    | "verbatim-file"
+    | "package-json"
+    | "agent-tool"
+    | "agent-state"
+    | "prompt"
+    | "missing-instance";
+  subject: string;
+  detail?: string;
+  expected?: string;
+  actual?: string;
+}
+
+export interface Report {
+  instance: string;
+  items: DriftItem[];
+}
+
+export function hasErrors(reports: Report[]): boolean {
+  return reports.some((r) => r.items.some((i) => i.severity === "error"));
+}
+
+const RESET = "\x1b[0m";
+const RED = "\x1b[31m";
+const YEL = "\x1b[33m";
+const GRN = "\x1b[32m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+
+function color(enabled: boolean, code: string, s: string): string {
+  return enabled ? `${code}${s}${RESET}` : s;
+}
+
+export function printReports(reports: Report[], useColor = true): void {
+  for (const r of reports) {
+    const errors = r.items.filter((i) => i.severity === "error");
+    const warns = r.items.filter((i) => i.severity === "warn");
+    const oks = r.items.filter((i) => i.severity === "ok");
+
+    const header = color(
+      useColor,
+      BOLD,
+      `\n${r.instance} — ${oks.length} ok, ${warns.length} warn, ${errors.length} error`,
+    );
+    process.stdout.write(header + "\n");
+
+    for (const item of [...errors, ...warns]) {
+      const tag =
+        item.severity === "error"
+          ? color(useColor, RED, "  ✗")
+          : color(useColor, YEL, "  !");
+      const kindStr = color(useColor, DIM, `[${item.kind}]`);
+      process.stdout.write(`${tag} ${kindStr} ${item.subject}\n`);
+      if (item.detail) process.stdout.write(`      ${item.detail}\n`);
+      if (item.expected !== undefined || item.actual !== undefined) {
+        if (item.expected !== undefined)
+          process.stdout.write(`      expected: ${truncate(item.expected)}\n`);
+        if (item.actual !== undefined)
+          process.stdout.write(`      actual:   ${truncate(item.actual)}\n`);
+      }
+    }
+
+    if (errors.length === 0 && warns.length === 0) {
+      process.stdout.write(color(useColor, GRN, "  ✓ no drift\n"));
+    }
+  }
+}
+
+function truncate(s: string, max = 120): string {
+  if (s.length <= max) return s;
+  return s.slice(0, max) + "…";
+}