botprint 0.2.0

package/src/profile.ts

@@ -0,0 +1,188 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { z } from "zod";
+import { BotprintError } from "./errors";
+import { EXIT_CODES } from "./exit-codes";
+
+export const SCHEMA_VERSION = "0.3";
+
+const AvailabilitySchema = z.enum(["available", "unavailable", "error"]);
+const TimedAvailabilitySchema = z.enum(["available", "unavailable", "error", "timeout"]);
+const PermissionStateSchema = z.enum(["granted", "denied", "prompt", "unsupported", "error", "unknown"]);
+
+export const PROBE_WARNINGS = ["page-contamination-possible", "default-browser-context", "multiple-browser-contexts", "http-not-captured"] as const;
+
+const FindingSchema = z.object({
+  id: z.string(),
+  severity: z.enum(["normal", "notable", "warning", "compatibility_risk", "high_confidence_automation_signal"]),
+  category: z.string(),
+  title: z.string(),
+  evidence: z.array(z.string()),
+  explanation: z.string(),
+  likely_implications: z.string(),
+  suggested_investigation: z.string(),
+});
+
+const ProfileSchema = z
+  .object({
+    schema_version: z.literal(SCHEMA_VERSION),
+    botprint_version: z.string(),
+    created_at: z.iso.datetime(),
+    source: z.object({
+      label: z.string().optional(),
+      cdp_endpoint_kind: z.enum(["http", "https", "ws", "wss"]),
+      browser_version: z.string(),
+      target_url: z.string(),
+      probe_context: z.enum(["local-diagnostic-page", "existing-target"]),
+      browser_context_id: z.string().optional(),
+      browser_context_source: z.enum(["page-target", "browser-default", "explicit"]).optional(),
+      target_id: z.string().optional(),
+      target_type: z.string().optional(),
+      probe_timeout_ms: z.number().int().positive().optional(),
+      probe_warnings: z.array(z.enum(PROBE_WARNINGS)).optional(),
+    }),
+    signals: z.object({
+      identity: z.object({
+        user_agent: z.string(),
+        user_agent_data: z
+          .object({
+            brands: z.array(z.object({ brand: z.string(), version: z.string() })),
+            mobile: z.boolean(),
+            platform: z.string(),
+          })
+          .optional(),
+        platform: z.string(),
+        language: z.string(),
+        languages: z.array(z.string()),
+        plugins_count: z.number().int().nonnegative(),
+        mime_types_count: z.number().int().nonnegative(),
+        pdf_viewer_enabled: z.boolean().nullable(),
+      }),
+      automation: z.object({
+        webdriver: z.boolean().nullable(),
+        chrome_object: z.boolean(),
+        globals: z.record(z.string(), z.boolean()),
+      }),
+      environment: z.object({
+        timezone: z.string(),
+        viewport: z.object({
+          width: z.number().nonnegative(),
+          height: z.number().nonnegative(),
+          device_scale_factor: z.number().nonnegative(),
+        }),
+        outer_window: z.object({
+          width: z.number().nonnegative(),
+          height: z.number().nonnegative(),
+        }),
+        screen: z.object({
+          width: z.number().nonnegative(),
+          height: z.number().nonnegative(),
+          avail_width: z.number().nonnegative(),
+          avail_height: z.number().nonnegative(),
+          color_depth: z.number().nonnegative(),
+        }),
+        hardware_concurrency: z.number().nonnegative(),
+        device_memory: z.number().nonnegative().nullable(),
+        speech_voices_count: z.number().int().nonnegative(),
+      }),
+      rendering: z.object({
+        webgl: z.object({
+          status: AvailabilitySchema,
+          vendor: z.string().optional(),
+          renderer: z.string().optional(),
+          unmasked_vendor: z.string().optional(),
+          unmasked_renderer: z.string().optional(),
+        }),
+        canvas: z.object({
+          status: z.enum(["stable", "unstable", "unavailable", "error"]),
+          hash: z.string().optional(),
+        }),
+        audio: z.object({
+          status: TimedAvailabilitySchema,
+          hash: z.string().optional(),
+        }),
+        fonts: z.object({
+          status: AvailabilitySchema,
+          checked: z.number().int().nonnegative(),
+          detected: z.array(z.string()),
+        }),
+      }),
+      storage: z.object({
+        cookies_enabled: z.boolean(),
+        local_storage: AvailabilitySchema,
+        session_storage: AvailabilitySchema,
+        indexed_db: TimedAvailabilitySchema,
+        service_worker: AvailabilitySchema,
+      }),
+      permissions: z.record(z.string(), PermissionStateSchema),
+      webrtc: z.object({
+        api_available: z.boolean(),
+        host_candidate_gathering: z.enum(["present", "absent", "unsupported", "error", "timeout"]),
+        candidate_count: z.number().int().nonnegative(),
+      }),
+      http: z
+        .object({
+          status: z.enum(["captured", "not-captured"]),
+          request_headers: z.record(z.string(), z.string()),
+        })
+        .optional(),
+      cdp: z.object({
+        product: z.string(),
+        protocol_version: z.string(),
+        user_agent: z.string(),
+      }),
+    }),
+    findings: z.array(FindingSchema),
+  })
+  .passthrough();
+
+export type BotprintProfile = z.infer<typeof ProfileSchema>;
+export type ProbeWarning = (typeof PROBE_WARNINGS)[number];
+
+export async function readProfile(path: string): Promise<BotprintProfile> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new BotprintError(`Could not read profile ${path}: ${message}`, EXIT_CODES.usage);
+  }
+
+  try {
+    return validateProfile(JSON.parse(raw));
+  } catch (error) {
+    if (error instanceof BotprintError) {
+      throw error;
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    throw new BotprintError(`Profile is not valid JSON: ${message}`, EXIT_CODES.schemaValidation);
+  }
+}
+
+export async function writeProfile(path: string, profile: BotprintProfile): Promise<void> {
+  const validated = validateProfile(profile);
+  await writeFile(path, `${JSON.stringify(validated, null, 2)}\n`, "utf8");
+}
+
+export function validateProfile(profile: unknown): BotprintProfile {
+  const result = ProfileSchema.safeParse(profile);
+  if (!result.success) {
+    const version = typeof profile === "object" && profile !== null ? (profile as { schema_version?: unknown }).schema_version : undefined;
+    const hint =
+      typeof version === "string" && version !== SCHEMA_VERSION
+        ? ` Profile schema_version is ${version}; this Botprint reads ${SCHEMA_VERSION}. Regenerate the profile with \`botprint run\`.`
+        : "";
+    throw new BotprintError(`Profile validation failed: ${z.prettifyError(result.error)}${hint}`, EXIT_CODES.schemaValidation);
+  }
+
+  return result.data;
+}
+
+export function endpointKind(endpoint: string): BotprintProfile["source"]["cdp_endpoint_kind"] {
+  const url = new URL(endpoint);
+  if (url.protocol === "http:") return "http";
+  if (url.protocol === "https:") return "https";
+  if (url.protocol === "ws:") return "ws";
+  if (url.protocol === "wss:") return "wss";
+  throw new BotprintError(`Unsupported CDP endpoint protocol: ${url.protocol}`, EXIT_CODES.usage);
+}

package/src/render.ts

@@ -0,0 +1,268 @@
+import { isObject } from "./coerce";
+import type { AbsentValue, CompareResult, ProfileDiff } from "./compare";
+import { analyzeProfile, type Finding } from "./findings";
+import { SCHEMA_VERSION, validateProfile, type BotprintProfile } from "./profile";
+
+const MAX_REPORT_ITEMS = 5;
+const MAX_AGENT_ITEMS = 4;
+const AGENT_WORD_LIMIT = 200;
+
+export function renderProfileMarkdown(profile: BotprintProfile, findings: Finding[]): string {
+  const lines = [
+    `# Botprint Profile: ${profileLabel(profile)}`,
+    "",
+    "## Summary",
+    `- Browser: ${profile.source.browser_version}`,
+    `- Target: ${profile.source.target_url}`,
+    `- Findings: ${findings.length}`,
+    "",
+    "## Browser Context",
+    `- Probe context: ${probeContextText(profile)}`,
+    `- User agent: ${profile.signals.identity.user_agent}`,
+    `- Platform: ${profile.signals.identity.platform}`,
+    `- Language: ${profile.signals.identity.language || "(empty)"}; languages=${JSON.stringify(profile.signals.identity.languages)}`,
+    `- Timezone: ${profile.signals.environment.timezone}`,
+    `- Viewport: ${profile.signals.environment.viewport.width}x${profile.signals.environment.viewport.height} @ ${profile.signals.environment.viewport.device_scale_factor}; outer ${profile.signals.environment.outer_window.width}x${profile.signals.environment.outer_window.height}`,
+    "",
+    "## Key Signals",
+    `- WebDriver: ${formatValue(profile.signals.automation.webdriver)}; window.chrome: ${profile.signals.automation.chrome_object}`,
+    `- WebGL: ${profile.signals.rendering.webgl.unmasked_renderer ?? profile.signals.rendering.webgl.renderer ?? profile.signals.rendering.webgl.status}`,
+    `- Canvas: ${profile.signals.rendering.canvas.status}; audio: ${profile.signals.rendering.audio.status}`,
+    `- Fonts: ${profile.signals.rendering.fonts.detected.length} of ${profile.signals.rendering.fonts.checked} common fonts detected`,
+    `- Storage: cookies=${profile.signals.storage.cookies_enabled}, indexedDB=${profile.signals.storage.indexed_db}`,
+    `- Accept-Language: ${profile.signals.http?.status === "captured" ? (profile.signals.http.request_headers["accept-language"] ?? "(not sent)") : "(not captured)"}`,
+  ];
+
+  if (profile.source.probe_warnings !== undefined && profile.source.probe_warnings.length > 0) {
+    lines.push("", "## Measurement Notes");
+    for (const warning of profile.source.probe_warnings) {
+      lines.push(`- ${profileWarningText(warning)}`);
+    }
+  }
+
+  const top = topFindings(findings, MAX_REPORT_ITEMS);
+
+  if (top.length > 0) {
+    lines.push("", "## Top Findings");
+    if (findings.length > top.length) {
+      lines.push(`_Showing top ${top.length} of ${findings.length} findings. Use \`--json\` for the full finding list._`);
+    }
+    for (const finding of top) {
+      lines.push(`- **${finding.title}** (${finding.severity}): ${finding.evidence.join(" ")}`);
+    }
+  }
+
+  lines.push("", "## Suggested Investigation");
+  if (top.length === 0) {
+    lines.push("- No notable findings. Compare this profile against a known-good baseline for drift.");
+  } else {
+    for (const finding of top) {
+      lines.push(`- ${finding.suggested_investigation}`);
+    }
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+export function renderCompareMarkdown(result: CompareResult): string {
+  const warnings = result.verdict.warnings;
+  const lines = [
+    `# Botprint Compare: ${result.baseline.label} -> ${result.candidate.label}`,
+    "",
+    "## Summary",
+    `- Verdict: ${result.verdict.level}`,
+    `- Material: ${result.verdict.material ? "yes" : "no"}`,
+    `- Differences: ${result.diffs.length}`,
+  ];
+
+  if (result.verdict.categories.length > 0) {
+    lines.push(`- Categories: ${result.verdict.categories.join(", ")}`);
+  }
+
+  if (warnings.length > 0) {
+    lines.push(`- Warnings: ${warnings.map((warning) => warning.id).join(", ")}`);
+  }
+
+  if (warnings.length > 0) {
+    lines.push("", "## Warnings");
+    for (const warning of warnings) {
+      lines.push(`- **${warning.id}**: ${warning.summary} ${warning.implications} ${formatEvidence(warning.evidence)}`);
+    }
+  }
+
+  if (result.diffs.length === 0) {
+    lines.push("", "No differences found by the current comparison rules.");
+    return `${lines.join("\n")}\n`;
+  }
+
+  lines.push("", "## Top Differences");
+  const top = topDiffs(result.diffs, MAX_REPORT_ITEMS);
+  if (result.diffs.length > top.length) {
+    lines.push(`_Showing top ${top.length} of ${result.diffs.length} differences. Use \`--json\` for the full diff list._`);
+  }
+  for (const diff of top) {
+    lines.push(`- **${diff.summary}** (${diff.level}): ${diff.path} ${formatValue(diff.baseline)} -> ${formatValue(diff.candidate)}`);
+  }
+
+  lines.push("", "## Interpretation");
+  lines.push(compareInterpretation(result));
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+export function renderAgentProfileExplanation(profile: BotprintProfile, findings: Finding[]): string {
+  const top = topFindings(findings, MAX_AGENT_ITEMS);
+  const parts = [
+    `Botprint profile for ${profileLabel(profile)} on ${profile.source.browser_version}.`,
+    `Context: ${profile.signals.identity.platform}, timezone ${profile.signals.environment.timezone}, viewport ${profile.signals.environment.viewport.width}x${profile.signals.environment.viewport.height}.`,
+  ];
+
+  if (top.length === 0) {
+    parts.push("No notable findings were generated. Use compare against a known-good baseline to identify environment drift.");
+  } else {
+    parts.push(`Top findings: ${top.map((finding) => `${finding.id} (${finding.severity})`).join("; ")}.`);
+    parts.push(`Investigate: ${top.map((finding) => finding.suggested_investigation).join(" ")}`);
+  }
+
+  if (profile.source.probe_warnings !== undefined && profile.source.probe_warnings.length > 0) {
+    parts.push(`Measurement notes: ${profile.source.probe_warnings.map(profileWarningText).join(" ")}`);
+  }
+
+  return `${limitWords(parts.join(" "), AGENT_WORD_LIMIT)}\n`;
+}
+
+export function renderAgentCompareExplanation(result: CompareResult): string {
+  const top = topDiffs(result.diffs, MAX_AGENT_ITEMS);
+  const warnings = result.verdict.warnings;
+  const parts = [
+    `Botprint compare ${result.baseline.label} -> ${result.candidate.label}: verdict ${result.verdict.level}, material=${result.verdict.material}.`,
+  ];
+
+  if (top.length === 0) {
+    parts.push("No differences were found by the current comparison rules.");
+  } else {
+    parts.push(`Categories: ${result.verdict.categories.join(", ")}.`);
+    if (warnings.length > 0) {
+      parts.push(`Warnings: ${warnings.map((warning) => `${warning.id} (${warning.summary.replace(/\.$/, "")})`).join("; ")}.`);
+    }
+    parts.push(`Top diffs: ${top.map((diff) => `${diff.path} ${formatValue(diff.baseline)} -> ${formatValue(diff.candidate)} (${diff.level})`).join("; ")}.`);
+    parts.push(compareInterpretation(result));
+  }
+
+  return `${limitWords(parts.join(" "), AGENT_WORD_LIMIT)}\n`;
+}
+
+export function renderAgentExplanation(input: unknown): string {
+  if (isCompareResult(input)) {
+    return renderAgentCompareExplanation(input);
+  }
+
+  const profile = validateProfile(input);
+  return renderAgentProfileExplanation(profile, analyzeProfile(profile));
+}
+
+function isCompareResult(value: unknown): value is CompareResult {
+  if (!isObject(value)) return false;
+  const verdict = value.verdict;
+  return (
+    value.schema_version === SCHEMA_VERSION &&
+    Array.isArray(value.diffs) &&
+    isObject(value.baseline) &&
+    isObject(value.candidate) &&
+    isObject(verdict) &&
+    typeof verdict.level === "string" &&
+    typeof verdict.material === "boolean"
+  );
+}
+
+function topFindings(findings: Finding[], limit: number): Finding[] {
+  return [...findings].sort((left, right) => severityRank(right.severity) - severityRank(left.severity)).slice(0, limit);
+}
+
+function severityRank(severity: Finding["severity"]): number {
+  switch (severity) {
+    case "high_confidence_automation_signal":
+      return 4;
+    case "compatibility_risk":
+      return 3;
+    case "warning":
+      return 2;
+    case "notable":
+      return 1;
+    default:
+      return 0;
+  }
+}
+
+function topDiffs(diffs: ProfileDiff[], limit: number): ProfileDiff[] {
+  return [...diffs].sort((left, right) => levelRank(right.level) - levelRank(left.level)).slice(0, limit);
+}
+
+function levelRank(level: ProfileDiff["level"]): number {
+  if (level === "high_confidence_automation") return 3;
+  if (level === "material") return 2;
+  return 1;
+}
+
+function compareInterpretation(result: CompareResult): string {
+  if (result.verdict.level === "none") {
+    return "The candidate matches the baseline across the current comparison rules.";
+  }
+  if (result.verdict.level === "advisory") {
+    return "The candidate differs from the baseline, but the current rules classify the differences as advisory by default.";
+  }
+  if (result.verdict.level === "high_confidence_automation") {
+    return "The candidate exposes high-confidence automation evidence compared with the baseline.";
+  }
+  return `The candidate differs materially from the baseline across ${result.verdict.categories.join(", ")} signals.`;
+}
+
+function profileLabel(profile: BotprintProfile): string {
+  return profile.source.label ?? profile.source.browser_version;
+}
+
+function probeContextText(profile: BotprintProfile): string {
+  if (profile.source.probe_context === "existing-target") {
+    return `existing target ${profile.source.target_id ?? ""}`.trim();
+  }
+  const source = profile.source.browser_context_source;
+  if (source === "page-target") return "fresh page in the browser context of an existing page target";
+  if (source === "explicit") return "fresh page in an explicitly selected browser context";
+  return "fresh page in the browser default context";
+}
+
+function formatValue(value: unknown): string {
+  if (isAbsentValue(value)) return "<absent>";
+  return JSON.stringify(value);
+}
+
+function isAbsentValue(value: unknown): value is AbsentValue {
+  return isObject(value) && value.kind === "absent";
+}
+
+function formatEvidence(value: Record<string, unknown>): string {
+  const entries = Object.entries(value);
+  if (entries.length === 0) return "";
+  return `(${entries.map(([key, item]) => `${key}=${formatValue(item)}`).join(", ")})`;
+}
+
+function profileWarningText(warning: NonNullable<BotprintProfile["source"]["probe_warnings"]>[number]): string {
+  switch (warning) {
+    case "page-contamination-possible":
+      return "This existing-target profile may reflect page scripts, framework state, service workers, CSP, cookies, or application state.";
+    case "default-browser-context":
+      return "No page targets were open, so the fresh page ran in the browser default context. Framework context options (locale, timezone, viewport, permissions) are not reflected.";
+    case "multiple-browser-contexts":
+      return "Page targets span several browser contexts; the fresh page used the first one. Pass --context <id> to choose another.";
+    case "http-not-captured":
+      return "The browser's request for the diagnostic page was not observed, so HTTP request headers are absent.";
+    default:
+      return warning;
+  }
+}
+
+function limitWords(value: string, maxWords: number): string {
+  const words = value.trim().split(/\s+/);
+  if (words.length <= maxWords) return value.trim();
+  return `${words.slice(0, maxWords).join(" ")}...`;
+}