@agent-native/core 0.69.0 → 0.70.1

package/corpus/core/src/changelog/parse.ts

@@ -0,0 +1,245 @@
+/**
+ * Shared, dependency-free changelog parsing + serialization.
+ *
+ * Used by BOTH:
+ *   - the browser bundle (rendering an app's CHANGELOG.md in the command
+ *     menu / settings "What's new" surface), and
+ *   - the `agent-native changelog` CLI (rolling pending entry files up into
+ *     CHANGELOG.md).
+ *
+ * Keep this file isomorphic: no Node, no browser, no third-party deps. The
+ * markdown shape is the conventional "Keep a Changelog" layout — a top-level
+ * `# Changelog` heading followed by one `## <release>` section per release.
+ */
+
+/** A single released section of a CHANGELOG.md file. */
+export interface ChangelogEntry {
+  /** Stable id derived from the heading — used for "unseen" tracking. */
+  id: string;
+  /** Raw heading text, e.g. `2026-06-23` or `v1.2.0 — 2026-06-23`. */
+  title: string;
+  /** ISO date (YYYY-MM-DD) extracted from the heading, if present. */
+  date?: string;
+  /** Version label extracted from the heading, if present. */
+  version?: string;
+  /** Markdown body beneath the heading (until the next `## ` section). */
+  body: string;
+}
+
+/** A not-yet-released entry authored as a `changelog/<file>.md` file. */
+export interface PendingChangelogEntry {
+  /** Category — `added`, `improved`, `fixed`, `changed`, etc. */
+  type: ChangelogChangeType;
+  /** ISO date the entry was authored (YYYY-MM-DD). */
+  date?: string;
+  /** User-facing description (markdown, single bullet). */
+  text: string;
+}
+
+export type ChangelogChangeType =
+  | "added"
+  | "improved"
+  | "fixed"
+  | "changed"
+  | "removed"
+  | "security";
+
+/**
+ * Order changes are grouped under a release heading. Anything not listed here
+ * falls back to the "changed" group, then renders in insertion order.
+ */
+export const CHANGELOG_GROUP_ORDER: ChangelogChangeType[] = [
+  "added",
+  "improved",
+  "fixed",
+  "changed",
+  "removed",
+  "security",
+];
+
+const GROUP_LABELS: Record<ChangelogChangeType, string> = {
+  added: "Added",
+  improved: "Improved",
+  fixed: "Fixed",
+  changed: "Changed",
+  removed: "Removed",
+  security: "Security",
+};
+
+const ISO_DATE = /(\d{4}-\d{2}-\d{2})/;
+
+/** Lowercase, hyphenate, and strip to a URL/id-safe slug. */
+export function changelogSlug(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+}
+
+function normalizeType(raw: string | undefined): ChangelogChangeType {
+  const value = (raw ?? "").trim().toLowerCase();
+  if ((CHANGELOG_GROUP_ORDER as string[]).includes(value)) {
+    return value as ChangelogChangeType;
+  }
+  // Friendly aliases.
+  if (value === "feature" || value === "new" || value === "add") return "added";
+  if (value === "improvement" || value === "enhancement" || value === "perf") {
+    return "improved";
+  }
+  if (value === "fix" || value === "bugfix" || value === "bug") return "fixed";
+  if (value === "remove" || value === "deprecated") return "removed";
+  return "changed";
+}
+
+/**
+ * Parse a CHANGELOG.md document into structured release entries.
+ *
+ * Tolerant by design: an empty or malformed file yields an empty list rather
+ * than throwing, so a missing/partial changelog never breaks the UI.
+ */
+export function parseChangelog(markdown: string): ChangelogEntry[] {
+  if (!markdown || typeof markdown !== "string") return [];
+
+  const lines = markdown.split(/\r?\n/);
+  const entries: ChangelogEntry[] = [];
+  const seenIds = new Set<string>();
+
+  let currentTitle: string | null = null;
+  let bodyLines: string[] = [];
+
+  const flush = () => {
+    if (currentTitle === null) return;
+    const title = currentTitle.trim();
+    const date = title.match(ISO_DATE)?.[1];
+    const version = title.match(/v?\d+\.\d+(?:\.\d+)?/)?.[0];
+    // Build a stable, unique id from the heading.
+    let base = changelogSlug(title) || "entry";
+    let id = base;
+    let n = 2;
+    while (seenIds.has(id)) id = `${base}-${n++}`;
+    seenIds.add(id);
+    entries.push({
+      id,
+      title,
+      date,
+      version: version && version !== date ? version : undefined,
+      body: bodyLines.join("\n").trim(),
+    });
+    currentTitle = null;
+    bodyLines = [];
+  };
+
+  for (const line of lines) {
+    // `## ` (but not `### `) starts a new release section.
+    const match = /^##\s+(?!#)(.+?)\s*$/.exec(line);
+    if (match) {
+      flush();
+      currentTitle = stripBrackets(match[1]);
+      continue;
+    }
+    // Skip the top-level `# Changelog` title and anything before the first `##`.
+    if (currentTitle === null) continue;
+    bodyLines.push(line);
+  }
+  flush();
+
+  return entries;
+}
+
+/** `## [1.2.0]` → `1.2.0`; leaves un-bracketed headings untouched. */
+function stripBrackets(title: string): string {
+  return title.replace(/^\[(.+?)\]\s*/, "$1 ").trim();
+}
+
+/**
+ * Parse a pending `changelog/<file>.md` entry: optional `---` frontmatter
+ * (`type:` / `date:`) followed by the markdown description body.
+ */
+export function parsePendingEntry(content: string): PendingChangelogEntry {
+  let type: string | undefined;
+  let date: string | undefined;
+  let body = content;
+
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(content);
+  if (fm) {
+    for (const raw of fm[1].split(/\r?\n/)) {
+      const kv = /^([a-zA-Z]+)\s*:\s*(.+?)\s*$/.exec(raw);
+      if (!kv) continue;
+      const key = kv[1].toLowerCase();
+      const value = kv[2].replace(/^["']|["']$/g, "").trim();
+      if (key === "type") type = value;
+      else if (key === "date") date = value.match(ISO_DATE)?.[1] ?? value;
+    }
+    body = content.slice(fm[0].length);
+  }
+
+  return {
+    type: normalizeType(type),
+    date,
+    text: body.trim(),
+  };
+}
+
+/**
+ * Render a set of pending entries as a single dated release section (the body
+ * that goes beneath a `## <date>` heading). Groups bullets by type.
+ */
+export function renderReleaseBody(entries: PendingChangelogEntry[]): string {
+  const groups = new Map<ChangelogChangeType, string[]>();
+  for (const entry of entries) {
+    const text = entry.text.trim();
+    if (!text) continue;
+    const bullet = text.includes("\n")
+      ? // Preserve multi-line bodies, indenting continuation lines.
+        text
+          .split(/\r?\n/)
+          .map((l, i) => (i === 0 ? `- ${l}` : `  ${l}`))
+          .join("\n")
+      : `- ${text}`;
+    const list = groups.get(entry.type) ?? [];
+    list.push(bullet);
+    groups.set(entry.type, list);
+  }
+
+  const sections: string[] = [];
+  for (const type of CHANGELOG_GROUP_ORDER) {
+    const list = groups.get(type);
+    if (!list?.length) continue;
+    sections.push(`### ${GROUP_LABELS[type]}\n\n${list.join("\n")}`);
+  }
+  return sections.join("\n\n");
+}
+
+const CHANGELOG_HEADER =
+  "# Changelog\n\n" +
+  "All notable user-facing changes to this app are documented here.\n";
+
+/**
+ * Roll a batch of pending entries into an existing CHANGELOG.md document,
+ * prepending a new `## <date>` section above the most recent release. Returns
+ * the full updated document. Pure — the CLI handles file IO and deletion.
+ */
+export function rollupChangelog(
+  existing: string,
+  pending: PendingChangelogEntry[],
+  releaseDate: string,
+): string {
+  const body = renderReleaseBody(pending);
+  if (!body) return existing || `${CHANGELOG_HEADER}`;
+
+  const section = `## ${releaseDate}\n\n${body}\n`;
+
+  const doc = (existing || CHANGELOG_HEADER).replace(/\s+$/, "");
+  // Insert the new section immediately before the first existing `## ` release
+  // so the header/intro stays on top and releases stay newest-first.
+  const firstRelease = doc.search(/^##\s+(?!#)/m);
+  if (firstRelease === -1) {
+    return `${doc}\n\n${section}\n`;
+  }
+  const head = doc.slice(0, firstRelease).replace(/\s+$/, "");
+  const rest = doc.slice(firstRelease);
+  return `${head}\n\n${section}\n${rest}\n`;
+}
+
+export { CHANGELOG_HEADER, GROUP_LABELS };

package/corpus/core/src/cli/changelog.ts

@@ -0,0 +1,199 @@
+/**
+ * `agent-native changelog` — author and roll up an app's user-facing changelog.
+ *
+ * The model mirrors changesets: instead of editing the shared CHANGELOG.md
+ * directly (which conflicts when many agents work in parallel), each change
+ * drops a small pending entry file under `changelog/`. A later `release` rolls
+ * every pending file up into a single dated section of CHANGELOG.md.
+ *
+ *   agent-native changelog add "Recordings can be trimmed before sharing" --type added
+ *   agent-native changelog release           # roll pending → CHANGELOG.md (today)
+ *   agent-native changelog list              # show pending + released
+ *
+ * Runs in the current app directory (process.cwd()).
+ */
+import fs from "fs";
+import path from "path";
+
+import {
+  parsePendingEntry,
+  parseChangelog,
+  rollupChangelog,
+  changelogSlug,
+  CHANGELOG_HEADER,
+  type ChangelogChangeType,
+} from "../changelog/parse.js";
+
+const CHANGELOG_FILE = "CHANGELOG.md";
+const PENDING_DIR = "changelog";
+
+function todayIso(): string {
+  // Local date in YYYY-MM-DD. The CLI is the one place a wall-clock read is
+  // appropriate (unlike workflow scripts), so `new Date()` is fine here.
+  const d = new Date();
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+/** Minimal flag parser: supports `--key value` and `--key=value`. */
+function parseFlags(args: string[]): {
+  flags: Record<string, string>;
+  rest: string[];
+} {
+  const flags: Record<string, string> = {};
+  const rest: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (eq !== -1) {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      } else {
+        const next = args[i + 1];
+        if (next && !next.startsWith("--")) {
+          flags[arg.slice(2)] = next;
+          i++;
+        } else {
+          flags[arg.slice(2)] = "true";
+        }
+      }
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { flags, rest };
+}
+
+function printUsage(): void {
+  console.log(
+    [
+      "Usage:",
+      '  agent-native changelog add "<summary>" [--type added|improved|fixed|changed|removed|security] [--date YYYY-MM-DD]',
+      "  agent-native changelog release [--date YYYY-MM-DD]",
+      "  agent-native changelog list",
+      "",
+      "Entries are user-facing notes. `add` writes a pending file under",
+      `  ${PENDING_DIR}/; \`release\` rolls all pending files into ${CHANGELOG_FILE}.`,
+    ].join("\n"),
+  );
+}
+
+function cmdAdd(args: string[]): number {
+  const { flags, rest } = parseFlags(args);
+  const summary = rest.join(" ").trim();
+  if (!summary) {
+    console.error('Provide a summary, e.g. changelog add "Faster search"');
+    return 1;
+  }
+  const type = (flags.type ?? "changed") as ChangelogChangeType;
+  const date = flags.date?.match(/\d{4}-\d{2}-\d{2}/)?.[0] ?? todayIso();
+
+  const dir = path.resolve(PENDING_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const slug = changelogSlug(summary) || "entry";
+  let file = path.join(dir, `${date}-${slug}.md`);
+  let n = 2;
+  while (fs.existsSync(file)) {
+    file = path.join(dir, `${date}-${slug}-${n++}.md`);
+  }
+
+  // Blank line after the closing frontmatter delimiter so the generated file
+  // is already Prettier-clean (Markdown requires a blank line before body text)
+  // and never trips the repo fmt check.
+  const content = `---\ntype: ${type}\ndate: ${date}\n---\n\n${summary}\n`;
+  fs.writeFileSync(file, content, "utf-8");
+  console.log(`Added changelog entry: ${path.relative(process.cwd(), file)}`);
+  return 0;
+}
+
+function readPending(): { file: string; content: string }[] {
+  const dir = path.resolve(PENDING_DIR);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".md") && f.toLowerCase() !== "readme.md")
+    .sort()
+    .map((f) => ({
+      file: path.join(dir, f),
+      content: fs.readFileSync(path.join(dir, f), "utf-8"),
+    }));
+}
+
+function cmdRelease(args: string[]): number {
+  const { flags } = parseFlags(args);
+  const date = flags.date?.match(/\d{4}-\d{2}-\d{2}/)?.[0] ?? todayIso();
+
+  const pendingFiles = readPending();
+  if (pendingFiles.length === 0) {
+    console.log("No pending changelog entries to release.");
+    return 0;
+  }
+
+  const pending = pendingFiles.map((p) => parsePendingEntry(p.content));
+  const changelogPath = path.resolve(CHANGELOG_FILE);
+  const existing = fs.existsSync(changelogPath)
+    ? fs.readFileSync(changelogPath, "utf-8")
+    : "";
+
+  const next = rollupChangelog(existing, pending, date);
+  fs.writeFileSync(changelogPath, next, "utf-8");
+
+  // Remove the pending entries now that they're released.
+  for (const p of pendingFiles) fs.rmSync(p.file);
+
+  console.log(
+    `Released ${pendingFiles.length} entr${
+      pendingFiles.length === 1 ? "y" : "ies"
+    } into ${CHANGELOG_FILE} (## ${date}).`,
+  );
+  return 0;
+}
+
+function cmdList(): number {
+  const pending = readPending();
+  const changelogPath = path.resolve(CHANGELOG_FILE);
+  const released = fs.existsSync(changelogPath)
+    ? parseChangelog(fs.readFileSync(changelogPath, "utf-8"))
+    : [];
+
+  console.log(`Pending (${pending.length}):`);
+  for (const p of pending) {
+    const entry = parsePendingEntry(p.content);
+    console.log(
+      `  - [${entry.type}] ${entry.text.split("\n")[0]}  (${path.basename(
+        p.file,
+      )})`,
+    );
+  }
+  console.log("");
+  console.log(`Released (${released.length}):`);
+  for (const r of released.slice(0, 10)) console.log(`  - ${r.title}`);
+  return 0;
+}
+
+export async function runChangelog(args: string[]): Promise<number> {
+  const sub = args[0];
+  const rest = args.slice(1);
+  switch (sub) {
+    case "add":
+      return cmdAdd(rest);
+    case "release":
+      return cmdRelease(rest);
+    case "list":
+      return cmdList();
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      printUsage();
+      return 0;
+    default:
+      console.error(`Unknown changelog subcommand: ${sub}\n`);
+      printUsage();
+      return 1;
+  }
+}
+
+// Re-export header for callers that want to seed an empty CHANGELOG.md.
+export { CHANGELOG_HEADER };

package/corpus/core/src/cli/index.ts

@@ -827,6 +827,21 @@ switch (command) {
     break;
   }
 
+  case "changelog": {
+    // Author and roll up the app's user-facing changelog (changeset-style
+    // pending entry files → a dated CHANGELOG.md section).
+    import("./changelog.js")
+      .then(async (m) => {
+        const code = await m.runChangelog(args);
+        process.exit(code);
+      })
+      .catch((err) => {
+        console.error(err?.message ?? err);
+        process.exit(1);
+      });
+    break;
+  }
+
   case "--version":
   case "-v": {
     console.log(_version);
@@ -906,6 +921,10 @@ Usage:
                                 Pass a URL instead of a name for a generic
                                 research-and-integrate blueprint. --list to
                                 browse available blueprints.
+  agent-native changelog <cmd>  Author the app's user-facing changelog.
+                                cmds: add "<summary>" [--type added|fixed|...] |
+                                release | list. Pending entries live in
+                                changelog/; 'release' rolls them into CHANGELOG.md.
   agent-native audit-agent-web  Audit a public URL for agent-readable surfaces
   agent-native eval [pattern]   Run the app's evals (**/*.eval.ts, evals/*.ts)
                                 and exit non-zero if any scores below its

package/corpus/core/src/cli/recap.ts

@@ -1932,7 +1932,7 @@ export function buildCommentBody(env: NodeJS.ProcessEnv = process.env): string {
     lines.push(`</a>`);
     lines.push("");
   }
-  lines.push(`**[Open the full interactive recap](${safeUrl})**`);
+  lines.push(`**Open the [full interactive recap](${safeUrl})**`);
   if (env.DIFF_HUGE === "true") {
     lines.push("");
     lines.push(
@@ -2546,6 +2546,25 @@ const RECAP_SHOT_VIEWPORT = {
 };
 const RECAP_SHOT_DEVICE_SCALE_FACTOR = 2;
 
+/**
+ * Identity shim for esbuild's `__name` helper, injected into the browser before
+ * any screenshot init script or `page.evaluate` payload.
+ *
+ * esbuild/tsx `keepNames` (on by default) rewrites a named inner function — e.g.
+ * `const readHeights = (…) => {…}` inside a `page.evaluate` callback — into
+ * `__name(() => {…}, "readHeights")`. Playwright serializes that callback with
+ * `Function.prototype.toString` and runs it in the page, where `__name` does not
+ * exist, throwing `ReferenceError: __name is not defined` and silently dropping
+ * the recap's inline PR-comment screenshot. CI's trusted-workspace path runs this
+ * CLI through `tsx` (esbuild), so it fires there even though the tsc-built
+ * published package never emits `__name`. Defining `__name` as an identity
+ * function (esbuild's helper returns the target unchanged) makes every main-world
+ * payload safe regardless of how the CLI was transpiled. Kept as a raw string so
+ * esbuild can't rewrite the shim itself.
+ */
+const RECAP_SHOT_NAME_SHIM =
+  "globalThis.__name = globalThis.__name || function (value) { return value; };";
+
 type PlaywrightModule = { chromium: import("playwright").BrowserType };
 
 async function defaultImportPlaywright(): Promise<PlaywrightModule> {
@@ -2704,6 +2723,10 @@ export async function runShot(
       deviceScaleFactor: RECAP_SHOT_DEVICE_SCALE_FACTOR,
       ...(theme ? { colorScheme: theme } : {}),
     });
+    // Must run before the theme init script and every page.evaluate below so
+    // esbuild/tsx `keepNames` wrappers don't throw `__name is not defined` in
+    // the browser (see RECAP_SHOT_NAME_SHIM).
+    await context.addInitScript(RECAP_SHOT_NAME_SHIM);
     if (theme) {
       await context.addInitScript(
         ({ background, nextTheme }) => {