libretto 0.5.0 → 0.5.2

package/dist/shared/visualization/highlight.js

@@ -92,12 +92,15 @@ async function showHighlight(page, params) {
 }
 async function clearHighlights(page) {
   try {
-    await page.evaluate(({ layerId }) => {
-      const layer = document.getElementById(layerId);
-      if (!layer) return;
-      const rects = layer.querySelectorAll(".__libretto_highlight_rect__");
-      rects.forEach((r) => r.remove());
-    }, { layerId: LAYER_ID });
+    await page.evaluate(
+      ({ layerId }) => {
+        const layer = document.getElementById(layerId);
+        if (!layer) return;
+        const rects = layer.querySelectorAll(".__libretto_highlight_rect__");
+        rects.forEach((r) => r.remove());
+      },
+      { layerId: LAYER_ID }
+    );
   } catch {
   }
 }

package/dist/shared/workflow/workflow.d.ts

@@ -2,8 +2,8 @@ import { Page } from 'playwright';
 import { MinimalLogger } from '../logger/logger.js';
 
 declare const LIBRETTO_WORKFLOW_BRAND: unique symbol;
-type LibrettoWorkflowMetadata = {};
 type LibrettoWorkflowContext<S = {}> = {
+    session: string;
     page: Page;
     logger: MinimalLogger;
     services: S;
@@ -11,11 +11,10 @@ type LibrettoWorkflowContext<S = {}> = {
 type LibrettoWorkflowHandler<Input = unknown, Output = unknown, S = {}> = (ctx: LibrettoWorkflowContext<S>, input: Input) => Promise<Output>;
 declare class LibrettoWorkflow<Input = unknown, Output = unknown, S = {}> {
     readonly [LIBRETTO_WORKFLOW_BRAND] = true;
-    readonly metadata: LibrettoWorkflowMetadata;
     private readonly handler;
-    constructor(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output, S>);
+    constructor(handler: LibrettoWorkflowHandler<Input, Output, S>);
     run(ctx: LibrettoWorkflowContext<S>, input: Input): Promise<Output>;
 }
-declare function workflow<Input = unknown, Output = unknown, S = {}>(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output, S>): LibrettoWorkflow<Input, Output, S>;
+declare function workflow<Input = unknown, Output = unknown, S = {}>(handler: LibrettoWorkflowHandler<Input, Output, S>): LibrettoWorkflow<Input, Output, S>;
 
-export { LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, type LibrettoWorkflowMetadata, workflow };
+export { LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, workflow };

package/dist/shared/workflow/workflow.js

@@ -1,18 +1,16 @@
 const LIBRETTO_WORKFLOW_BRAND = /* @__PURE__ */ Symbol.for("libretto.workflow");
 class LibrettoWorkflow {
   [LIBRETTO_WORKFLOW_BRAND] = true;
-  metadata;
   handler;
-  constructor(metadata, handler) {
-    this.metadata = metadata;
+  constructor(handler) {
     this.handler = handler;
   }
   async run(ctx, input) {
     return this.handler(ctx, input);
   }
 }
-function workflow(metadata, handler) {
-  return new LibrettoWorkflow(metadata, handler);
+function workflow(handler) {
+  return new LibrettoWorkflow(handler);
 }
 export {
   LIBRETTO_WORKFLOW_BRAND,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,8 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
+    "sync-skills": "node scripts/sync-skills.mjs",
+    "check:skills": "node scripts/check-skills-sync.mjs",
     "build": "tsup --config tsup.config.ts",
     "type-check": "tsc --noEmit",
     "test": "pnpm run build && vitest run",
@@ -38,6 +40,7 @@
     "benchmark": "pnpm run build && tsx benchmarks/run.ts",
     "test:watch": "vitest",
     "cli": "node dist/index.js",
+    "prepare-release": "bash ./scripts/prepare-release.sh",
     "prepack": "pnpm run build"
   },
   "peerDependencies": {
@@ -61,12 +64,13 @@
     }
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.75",
     "@ai-sdk/anthropic": "^3.0.58",
     "@ai-sdk/google": "^3.0.51",
     "@ai-sdk/google-vertex": "^4.0.80",
     "@ai-sdk/openai": "^3.0.41",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.75",
     "@types/node": "^25.5.0",
+    "glimpseui": "^0.5.1",
     "openai": "^6.29.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",

package/scripts/check-skills-sync.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compareSkillDirs, SKILL_DIRS } from "./skills-libretto.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, "..");
+const result = compareSkillDirs(repoRoot);
+
+if (result.ok) {
+  console.log(
+    `libretto: verified identical skill mirrors across ${SKILL_DIRS.join(", ")}`,
+  );
+  process.exit(0);
+}
+
+console.error("libretto: skill directories must be identical:");
+for (const issue of result.issues) {
+  console.error(`- ${issue}`);
+}
+console.error("");
+console.error("Run `pnpm i` to resync the mirrors in this repository.");
+process.exit(1);

package/scripts/compare-eval-summary.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+function usage() {
+  console.error(
+    "Usage: node scripts/compare-eval-summary.mjs <baseline-summary.json> <current-summary.json> [threshold-percent]",
+  );
+}
+
+const [, , baselineArg, currentArg, thresholdArg] = process.argv;
+
+if (!baselineArg || !currentArg) {
+  usage();
+  process.exit(1);
+}
+
+const baseline = JSON.parse(readFileSync(resolve(baselineArg), "utf8"));
+const current = JSON.parse(readFileSync(resolve(currentArg), "utf8"));
+const threshold = thresholdArg ? Number(thresholdArg) : 5;
+
+if (!Number.isFinite(threshold) || threshold < 0) {
+  console.error(`Invalid threshold percent: ${thresholdArg}`);
+  process.exit(1);
+}
+
+const delta = Number((current.percent - baseline.percent).toFixed(2));
+const withinThreshold = Math.abs(delta) <= threshold;
+
+const lines = [
+  "# Eval Baseline Comparison",
+  "",
+  `- Baseline score: \`${baseline.percent}%\``,
+  `- Current score: \`${current.percent}%\``,
+  `- Delta: \`${delta > 0 ? "+" : ""}${delta}%\``,
+  `- Allowed range: \`+/-${threshold}%\``,
+];
+
+process.stdout.write(`${lines.join("\n")}\n`);
+
+if (!withinThreshold) {
+  console.error(
+    `Eval score delta ${delta > 0 ? "+" : ""}${delta}% is outside the allowed +/-${threshold}% range.`,
+  );
+  process.exit(1);
+}

package/scripts/postinstall.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
+import { SKILL_DIRS, syncSkillDir } from "./skills-libretto.mjs";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
 
@@ -29,22 +31,20 @@ const gitResult = spawnSync("git", ["rev-parse", "--show-toplevel"], {
   encoding: "utf-8",
   stdio: ["pipe", "pipe", "pipe"],
 });
-const repoRoot = gitResult.status === 0 && gitResult.stdout
-  ? gitResult.stdout.trim()
-  : installCwd;
+const repoRoot =
+  gitResult.status === 0 && gitResult.stdout
+    ? gitResult.stdout.trim()
+    : installCwd;
 
-// Sync skills to any agent dirs at repo root
 const sourceDir = join(packageRoot, "skills", "libretto");
 if (!existsSync(sourceDir)) process.exit(0);
 
-const agentDirNames = [".agents", ".claude"];
-for (const name of agentDirNames) {
-  const agentDir = join(repoRoot, name);
-  if (!existsSync(agentDir)) continue;
-  const dest = join(agentDir, "skills", "libretto");
-  if (existsSync(dest)) rmSync(dest, { recursive: true });
-  mkdirSync(dirname(dest), { recursive: true });
-  cpSync(sourceDir, dest, { recursive: true });
-  const count = readdirSync(dest).length;
-  console.log(`libretto: synced ${count} skill files to ${dest}`);
+const syncMissingDirs = repoRoot === packageRoot;
+for (const dir of SKILL_DIRS.slice(1)) {
+  const rootName = dir.split("/")[0];
+  const rootDir = join(repoRoot, rootName);
+  if (!syncMissingDirs && !existsSync(rootDir)) continue;
+  const dest = join(repoRoot, dir);
+  syncSkillDir(sourceDir, dest);
+  console.log(`libretto: synced skills/libretto -> ${dest}`);
 }

package/scripts/prepare-release.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/prepare-release.sh [patch|minor|major]
+
+Creates a release PR branch from main, bumps package.json, pushes the branch,
+and opens a pull request targeting main.
+EOF
+}
+
+bump="${1:-patch}"
+
+case "$bump" in
+  patch|minor|major)
+    ;;
+  -h|--help|help)
+    usage
+    exit 0
+    ;;
+  *)
+    echo "Invalid bump type: $bump" >&2
+    usage >&2
+    exit 1
+    ;;
+esac
+
+if ! command -v gh >/dev/null 2>&1; then
+  echo "gh CLI is required." >&2
+  exit 1
+fi
+
+if [ -n "$(git status --porcelain)" ]; then
+  echo "Working tree must be clean before preparing a release." >&2
+  exit 1
+fi
+
+current_branch="$(git branch --show-current)"
+if [ "$current_branch" != "main" ]; then
+  echo "Switching from $current_branch to main."
+fi
+
+git fetch origin
+git checkout main
+git pull --ff-only origin main
+
+pnpm install --frozen-lockfile
+pnpm type-check
+pnpm test
+
+current_version="$(node -p "require('./package.json').version")"
+next_version="$(node -e '
+const [major, minor, patch] = process.argv[1].split(".").map(Number)
+const bump = process.argv[2]
+
+let next
+if (bump === "major") next = [major + 1, 0, 0]
+else if (bump === "minor") next = [major, minor + 1, 0]
+else next = [major, minor, patch + 1]
+
+process.stdout.write(next.join("."))
+' "$current_version" "$bump")"
+branch_name="tk-release-v${next_version}"
+
+if git show-ref --verify --quiet "refs/heads/${branch_name}"; then
+  echo "Local branch ${branch_name} already exists." >&2
+  exit 1
+fi
+
+if git ls-remote --exit-code --heads origin "${branch_name}" >/dev/null 2>&1; then
+  echo "Remote branch ${branch_name} already exists." >&2
+  exit 1
+fi
+
+npm version "$next_version" --no-git-tag-version >/dev/null
+
+git checkout -b "$branch_name"
+git add package.json
+git commit -m "release: v${next_version}"
+git push -u origin "$branch_name"
+
+gh pr create \
+  --base main \
+  --head "$branch_name" \
+  --title "release: v${next_version}" \
+  --body "$(cat <<EOF
+## Summary
+
+- release libretto v${next_version}
+
+## Verification
+
+- pnpm type-check
+- pnpm test
+EOF
+)"

package/scripts/skills-libretto.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+} from "node:fs";
+import { relative, resolve, join } from "node:path";
+
+export const SKILL_DIRS = [
+  "skills/libretto",
+  ".agents/skills/libretto",
+  ".claude/skills/libretto",
+];
+
+function walkFiles(dir, baseDir = dir) {
+  const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkFiles(fullPath, baseDir));
+      continue;
+    }
+    if (entry.isFile()) files.push(relative(baseDir, fullPath));
+  }
+
+  return files;
+}
+
+export function syncSkillDir(sourceDir, destDir) {
+  rmSync(destDir, { recursive: true, force: true });
+  mkdirSync(destDir, { recursive: true });
+  cpSync(sourceDir, destDir, { recursive: true });
+}
+
+export function syncRepoSkills(repoRoot) {
+  const sourceDir = resolve(repoRoot, "skills/libretto");
+  for (const dir of SKILL_DIRS.slice(1)) {
+    syncSkillDir(sourceDir, resolve(repoRoot, dir));
+  }
+}
+
+export function compareSkillDirs(repoRoot) {
+  const roots = SKILL_DIRS.map((dir) => ({
+    label: dir,
+    absPath: resolve(repoRoot, dir),
+  }));
+  const missing = roots.filter(({ absPath }) => !existsSync(absPath));
+  const mismatches = [];
+
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      issues: missing.map(({ label }) => `missing directory: ${label}`),
+    };
+  }
+
+  const expectedFiles = walkFiles(roots[0].absPath);
+  const expectedFileSet = new Set(expectedFiles);
+
+  for (const root of roots.slice(1)) {
+    const actualFiles = walkFiles(root.absPath);
+    const actualFileSet = new Set(actualFiles);
+
+    for (const file of expectedFiles) {
+      if (!actualFileSet.has(file)) {
+        mismatches.push(`${root.label} is missing file: ${file}`);
+      }
+    }
+
+    for (const file of actualFiles) {
+      if (!expectedFileSet.has(file)) {
+        mismatches.push(`${root.label} has unexpected file: ${file}`);
+      }
+    }
+  }
+
+  for (const file of expectedFiles) {
+    const expectedContent = readFileSync(join(roots[0].absPath, file));
+    for (const root of roots.slice(1)) {
+      const targetPath = join(root.absPath, file);
+      if (!existsSync(targetPath)) continue;
+      const actualContent = readFileSync(targetPath);
+      if (!expectedContent.equals(actualContent)) {
+        mismatches.push(
+          `${root.label} differs from ${roots[0].label}: ${file}`,
+        );
+      }
+    }
+  }
+
+  return {
+    ok: mismatches.length === 0,
+    issues: mismatches,
+  };
+}

package/scripts/summarize-evals.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function usage() {
+  console.error(
+    "Usage: node scripts/summarize-evals.mjs <score-dir> <summary-json-path>",
+  );
+}
+
+function normalizeFailureRecord(failure) {
+  return {
+    criterion: String(failure?.criterion ?? "").trim(),
+    reason: String(failure?.reason ?? "").trim(),
+  };
+}
+
+function normalizeRecord(record) {
+  const failures = Array.isArray(record?.failures)
+    ? record.failures
+        .map(normalizeFailureRecord)
+        .filter(
+          (failure) =>
+            failure.criterion.length > 0 && failure.reason.length > 0,
+        )
+    : [];
+
+  return {
+    name: String(record?.name ?? "").trim(),
+    passed: Number(record?.passed ?? 0),
+    total: Number(record?.total ?? 0),
+    percent: Number(record?.percent ?? 0),
+    failures,
+  };
+}
+
+export function loadScoreRecords(scoreDirArg) {
+  const scoreDir = resolve(scoreDirArg);
+  return readdirSync(scoreDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) =>
+      JSON.parse(readFileSync(join(scoreDir, entry.name), "utf8")),
+    )
+    .map(normalizeRecord)
+    .sort((a, b) => String(a.name).localeCompare(String(b.name)));
+}
+
+export function buildSummary(records) {
+  const passed = records.reduce(
+    (sum, record) => sum + Number(record.passed || 0),
+    0,
+  );
+  const total = records.reduce(
+    (sum, record) => sum + Number(record.total || 0),
+    0,
+  );
+  const percent = total > 0 ? Number(((passed / total) * 100).toFixed(2)) : 0;
+  const failingRecords = records.filter((record) => record.failures.length > 0);
+
+  return {
+    generatedAt: new Date().toISOString(),
+    recordCount: records.length,
+    passed,
+    total,
+    percent,
+    failingRecordCount: failingRecords.length,
+    records,
+  };
+}
+
+export function buildMarkdown(summary, summaryPathArg) {
+  const lines = [
+    "# Eval Summary",
+    "",
+    `- Overall score: \`${summary.percent}%\``,
+    `- Passed criteria: \`${summary.passed}/${summary.total}\``,
+    `- Recorded score entries: \`${summary.recordCount}\``,
+    `- Failed evals: \`${summary.failingRecordCount}\``,
+    `- Summary file: \`${basename(summaryPathArg)}\``,
+  ];
+
+  if (summary.records.length > 0) {
+    lines.push("", "## Breakdown", "");
+    for (const record of summary.records) {
+      const status = record.failures.length > 0 ? "fail" : "pass";
+      lines.push(
+        `- ${status} \`${record.name}\`: \`${record.percent}%\` (${record.passed}/${record.total})`,
+      );
+    }
+  }
+
+  if (summary.failingRecordCount > 0) {
+    lines.push("", "## Failed Evals", "");
+    for (const record of summary.records.filter(
+      (candidate) => candidate.failures.length > 0,
+    )) {
+      lines.push(`### \`${record.name}\``);
+      lines.push("");
+      lines.push(
+        `- Score: \`${record.percent}%\` (${record.passed}/${record.total})`,
+      );
+      for (const failure of record.failures) {
+        lines.push(`- ${failure.criterion}: ${failure.reason}`);
+      }
+      lines.push("");
+    }
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function main(argv) {
+  const [, , scoreDirArg, summaryPathArg] = argv;
+
+  if (!scoreDirArg || !summaryPathArg) {
+    usage();
+    process.exit(1);
+  }
+
+  const summaryPath = resolve(summaryPathArg);
+  const records = loadScoreRecords(scoreDirArg);
+  const summary = buildSummary(records);
+
+  writeFileSync(summaryPath, `${JSON.stringify(summary, null, 2)}\n`, "utf8");
+  process.stdout.write(buildMarkdown(summary, summaryPath));
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  main(process.argv);
+}

package/scripts/sync-skills.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { SKILL_DIRS, syncRepoSkills } from "./skills-libretto.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, "..");
+
+syncRepoSkills(repoRoot);
+console.log(`libretto: synced skill mirrors across ${SKILL_DIRS.join(", ")}`);