@rolepod/uiproof 0.5.0 → 0.6.1

package/dist/bin/rolepod-uiproof.js

@@ -175,7 +175,7 @@ function runInstallMobile() {
 
 // src/cli/replay.ts
 import { readFile } from "fs/promises";
-import { resolve as resolve3 } from "path";
+import { resolve as resolve4 } from "path";
 
 // src/artifact/ArtifactStore.ts
 import { randomUUID } from "crypto";
@@ -201,19 +201,74 @@ var log = {
   }
 };
 
+// src/util/rolepodProtocol.ts
+import { execSync } from "child_process";
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { join as join2 } from "path";
+function detectRolepodParent(cwd = process.cwd()) {
+  let gitRoot = cwd;
+  try {
+    gitRoot = execSync("git rev-parse --show-toplevel", {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+  }
+  const file = join2(gitRoot, ".rolepod", "parent-active");
+  if (!existsSync2(file)) {
+    return { active: false, protocol: null, gitRoot };
+  }
+  const protocol = readFileSync(file, "utf8").trim().split(/\r?\n/)[0] ?? null;
+  return { active: true, protocol, gitRoot };
+}
+
 // src/artifact/ArtifactStore.ts
 var ArtifactStore = class {
   rootDir;
+  mode;
+  baselineRoot;
   constructor(opts = {}) {
-    this.rootDir = opts.rootDir ?? resolve2(process.cwd(), ".rolepod-uiproof", "artifacts");
+    const parent = detectRolepodParent();
+    this.mode = opts.mode ?? (parent.active ? "with-parent" : "standalone");
+    if (opts.rootDir !== void 0) {
+      this.rootDir = opts.rootDir;
+    } else if (this.mode === "with-parent") {
+      this.rootDir = resolve2(parent.gitRoot, ".rolepod", "evidence");
+    } else {
+      this.rootDir = resolve2(process.cwd(), ".rolepod-uiproof", "artifacts");
+    }
+    this.baselineRoot = resolve2(process.cwd(), ".rolepod-uiproof", "baselines");
   }
-  /** Allocate a fresh run id and ensure its directory exists. */
-  async startRun(prefix = "run") {
-    const runId = `${prefix}_${this.timestampSlug()}_${randomUUID().slice(0, 8)}`;
+  /**
+   * Allocate a fresh run dir and ensure it exists.
+   *
+   * - standalone: `./.rolepod-uiproof/artifacts/{prefix}_{ts}_{uuid}/`
+   * - with-parent: `<git-root>/.rolepod/evidence/{ts}-rolepod-uiproof-{skill}/`
+   *
+   * `prefix` is preserved for back-compat with v0.5 callers; new callers
+   * should also pass `opts.skill` so the with-parent path can be derived
+   * unambiguously and the manifest can be emitted with the canonical
+   * skill name.
+   */
+  async startRun(prefix = "run", opts = {}) {
+    const ts = this.timestampSlug();
+    const skill = opts.skill ?? prefix;
+    let runId;
+    if (this.mode === "with-parent") {
+      runId = `${ts}-rolepod-uiproof-${skill}`;
+    } else {
+      runId = `${prefix}_${ts}_${randomUUID().slice(0, 8)}`;
+    }
     const runDir = resolve2(this.rootDir, runId);
     await mkdir(runDir, { recursive: true });
-    log.debug("artifact run started", { run_id: runId, dir: runDir });
-    return { runId, runDir };
+    log.debug("artifact run started", {
+      run_id: runId,
+      dir: runDir,
+      mode: this.mode,
+      skill
+    });
+    return { runId, runDir, skill, mode: this.mode };
   }
   async writeScreenshot(runDir, buf, name) {
     const path = resolve2(runDir, `${name}.png`);
@@ -241,7 +296,7 @@ var ArtifactStore = class {
   }
   /** Root for stored visual baselines: `./.rolepod-uiproof/baselines/`. */
   get baselineDir() {
-    return resolve2(this.rootDir, "..", "baselines");
+    return this.baselineRoot;
   }
   timestampSlug() {
     const d = /* @__PURE__ */ new Date();
@@ -1170,21 +1225,21 @@ var PlaywrightEngine = class {
     if (s.dialogArming) {
       s.dialogArming.resolve(false);
     }
-    return new Promise((resolve6) => {
+    return new Promise((resolve7) => {
       const arming = {
         action: opts.action,
         text: opts.text,
         expiresAt,
         resolve: (handled) => {
           s.dialogArming = null;
-          resolve6({ handled });
+          resolve7({ handled });
         }
       };
       s.dialogArming = arming;
       const timer = setTimeout(() => {
         if (s.dialogArming === arming) {
           s.dialogArming = null;
-          resolve6({ handled: false });
+          resolve7({ handled: false });
         }
       }, timeoutMs);
       timer.unref?.();
@@ -2035,6 +2090,37 @@ async function ddmin(input, reproduces) {
   return current;
 }
 
+// src/util/manifest.ts
+import { writeFile as writeFile2 } from "fs/promises";
+import { resolve as resolve3 } from "path";
+var ROLEPOD_PROTOCOL_VERSION = "rolepod/v1";
+async function writeManifest(input) {
+  const manifest = {
+    protocol: ROLEPOD_PROTOCOL_VERSION,
+    plugin: "rolepod-uiproof",
+    skill: input.skill,
+    phase: input.phase,
+    status: input.status,
+    summary: input.summary,
+    started_at: input.startedAt,
+    finished_at: input.finishedAt,
+    artifacts: input.artifacts,
+    metadata: input.metadata ?? {}
+  };
+  const path = resolve3(input.runDir, "manifest.json");
+  try {
+    await writeFile2(path, JSON.stringify(manifest, null, 2), "utf8");
+    return path;
+  } catch (err) {
+    log.warn("manifest write failed", {
+      run_dir: input.runDir,
+      skill: input.skill,
+      err: String(err)
+    });
+    return void 0;
+  }
+}
+
 // src/tools/result.ts
 function ok(value) {
   return {
@@ -2076,7 +2162,11 @@ var verifyUiFlowTool = {
   inputShape: verifyUiFlowShape,
   build(ctx) {
     return safeHandler(async (args) => {
-      const { runId, runDir } = await ctx.store.startRun("verify");
+      const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const { runId, runDir, skill } = await ctx.store.startRun(
+        "verify",
+        { skill: "verify-ui" }
+      );
       const initial = await runFlow(ctx, args, args.steps, runDir, {
         captureEvidence: true,
         bundleName: "replay.json"
@@ -2101,10 +2191,49 @@ var verifyUiFlowTool = {
           attempts: min.attempts
         };
       }
+      const manifestPath = await writeManifest({
+        runDir,
+        skill,
+        phase: "verify",
+        status: initial.passed ? "pass" : "fail",
+        summary: buildVerifySummary(args, initial),
+        startedAt,
+        finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        artifacts: flattenVerifyEvidence(initial.evidence),
+        metadata: {
+          mode: args.mode,
+          step_count: args.steps.length,
+          expect_count: args.expect.length,
+          ...initial.finalUrl !== void 0 ? { final_url: initial.finalUrl } : {}
+        }
+      });
+      if (manifestPath) result.manifest = manifestPath;
       return ok(result);
     });
   }
 };
+function buildVerifySummary(args, outcome) {
+  const stepCount = args.steps.length;
+  const expectCount = args.expect.length;
+  if (outcome.passed) {
+    return `${stepCount} step(s), ${expectCount} expect(s) passed`;
+  }
+  if (outcome.failedAtStep !== void 0) {
+    return `failed at step ${outcome.failedAtStep}: ${outcome.failureReason ?? "unknown"}`;
+  }
+  return `failed: ${outcome.failureReason ?? "unknown"}`;
+}
+function flattenVerifyEvidence(ev) {
+  const out = [];
+  for (const s of ev.screenshots) out.push({ type: "screenshot", path: s });
+  if (ev.replay_bundle) out.push({ type: "replay_bundle", path: ev.replay_bundle });
+  if (ev.console) out.push({ type: "console", path: ev.console });
+  if (ev.a11y_tree) out.push({ type: "a11y_tree", path: ev.a11y_tree });
+  if (ev.har) out.push({ type: "har", path: ev.har });
+  if (ev.trace) out.push({ type: "trace", path: ev.trace });
+  if (ev.video) for (const v of ev.video) out.push({ type: "video", path: v });
+  return out;
+}
 function buildCaptureOptions(captures, runDir) {
   const cap = {};
   if (captures.has("har")) {
@@ -2518,7 +2647,7 @@ function treeHasText(tree, text) {
 
 // src/cli/replay.ts
 async function runReplay(bundlePath) {
-  const abs = resolve3(bundlePath);
+  const abs = resolve4(bundlePath);
   const raw = await readFile(abs, "utf8");
   const bundle = JSON.parse(raw);
   if (bundle.version !== 1) {
@@ -3042,7 +3171,11 @@ var auditA11yTool = {
   inputShape: auditA11yShape,
   build(ctx) {
     return safeHandler(async (args) => {
-      const { runId, runDir } = await ctx.store.startRun("audit");
+      const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const { runId, runDir, skill } = await ctx.store.startRun(
+        "audit",
+        { skill: "audit-a11y" }
+      );
       const session = await ctx.registry.open(args.open);
       const engine = ctx.registry.engineFor(session.id);
       if (!(engine instanceof PlaywrightEngine)) {
@@ -3110,15 +3243,45 @@ var auditA11yTool = {
           await ctx.registry.close(session).catch(() => void 0);
         }
       }
+      const counts = countBySeverity(issues);
+      const status = a11yStatus(counts);
+      const artifacts = reportPath ? [{ type: "report", path: reportPath }] : [];
+      const manifestPath = await writeManifest({
+        runDir,
+        skill,
+        phase: "verify",
+        status,
+        summary: buildAuditSummary(args.level, counts, status),
+        startedAt,
+        finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        artifacts,
+        metadata: {
+          level: args.level,
+          scope: args.scope,
+          counts,
+          report_format: args.report_format
+        }
+      });
       return ok({
         run_id: runId,
-        counts: countBySeverity(issues),
+        counts,
         issues,
-        report_path: reportPath
+        report_path: reportPath,
+        ...manifestPath ? { manifest: manifestPath } : {}
       });
     });
   }
 };
+function a11yStatus(counts) {
+  if ((counts.critical ?? 0) + (counts.serious ?? 0) > 0) return "fail";
+  if ((counts.moderate ?? 0) + (counts.minor ?? 0) > 0) return "warn";
+  return "pass";
+}
+function buildAuditSummary(level, counts, status) {
+  const total = (counts.critical ?? 0) + (counts.serious ?? 0) + (counts.moderate ?? 0) + (counts.minor ?? 0);
+  if (status === "pass") return `${level}: 0 issues`;
+  return `${level}: ${total} issue(s) \u2014 critical=${counts.critical ?? 0}, serious=${counts.serious ?? 0}, moderate=${counts.moderate ?? 0}, minor=${counts.minor ?? 0}`;
+}
 function pickWcagRef(tags) {
   return tags.find((t) => /^wcag\d/.test(t));
 }
@@ -3235,14 +3398,18 @@ function scoreTree(root, tokens) {
 
 // src/tools/composite/scaffold_e2e.ts
 import { readFile as readFile2 } from "fs/promises";
-import { resolve as resolve4 } from "path";
+import { resolve as resolve5 } from "path";
 var scaffoldE2eTool = {
   name: ToolNames.scaffoldE2e,
   description: "Generate a runnable e2e test file (playwright-test, vitest+playwright, or pytest+selenium) from a scenario description and optional replay bundle from a prior verify_ui_flow run.",
   inputShape: scaffoldE2eShape,
   build(ctx) {
     return safeHandler(async (args) => {
-      const { runId, runDir } = await ctx.store.startRun("scaffold");
+      const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const { runId, runDir, skill } = await ctx.store.startRun(
+        "scaffold",
+        { skill: "scaffold-e2e" }
+      );
       const slug = slugify(args.scenario_nl);
       const bundle = args.recorded_bundle ? await loadReplay(args.recorded_bundle) : null;
       const ctxObj = { args, slug, bundle };
@@ -3280,19 +3447,35 @@ var scaffoldE2eTool = {
           );
       }
       const path = await ctx.store.writeReport(runDir, filename, body);
+      const manifestPath = await writeManifest({
+        runDir,
+        skill,
+        phase: "build",
+        status: "pass",
+        summary: `generated ${args.framework} test "${filename}" from ${bundle ? "replay bundle" : "scenario"}`,
+        startedAt,
+        finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        artifacts: [{ type: "test_file", path }],
+        metadata: {
+          framework: args.framework,
+          language,
+          from_replay_bundle: Boolean(bundle)
+        }
+      });
       return ok({
         run_id: runId,
         test_file_path: path,
         language,
         dependencies,
         setup_notes: setupNotes,
-        from_replay_bundle: Boolean(bundle)
+        from_replay_bundle: Boolean(bundle),
+        ...manifestPath ? { manifest: manifestPath } : {}
       });
     });
   }
 };
 async function loadReplay(bundlePath) {
-  const raw = await readFile2(resolve4(bundlePath), "utf8");
+  const raw = await readFile2(resolve5(bundlePath), "utf8");
   return JSON.parse(raw);
 }
 function slugify(s) {
@@ -3579,9 +3762,9 @@ function indent(block, n) {
 }
 
 // src/tools/composite/visual_diff.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { readFile as readFile3 } from "fs/promises";
-import { resolve as resolve5 } from "path";
+import { resolve as resolve6 } from "path";
 import pixelmatch from "pixelmatch";
 import { PNG } from "pngjs";
 var visualDiffTool = {
@@ -3590,7 +3773,11 @@ var visualDiffTool = {
   inputShape: visualDiffShape,
   build(ctx) {
     return safeHandler(async (args) => {
-      const { runId, runDir } = await ctx.store.startRun("vdiff");
+      const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const { runId, runDir, skill } = await ctx.store.startRun(
+        "vdiff",
+        { skill: "visual-diff" }
+      );
       const session = await ctx.registry.open({
         ...args.open,
         ...args.viewport ? { viewport: args.viewport } : {}
@@ -3609,16 +3796,30 @@ var visualDiffTool = {
         );
         const currentPath = await ctx.store.writeScreenshot(runDir, buf, "current");
         await ctx.store.ensureDir(ctx.store.baselineDir);
-        const baselinePath = resolve5(
+        const baselinePath = resolve6(
           ctx.store.baselineDir,
           `${args.baseline_id}.png`
         );
-        if (!existsSync2(baselinePath)) {
+        if (!existsSync3(baselinePath)) {
           await ctx.store.writeBytes(
             ctx.store.baselineDir,
             `${args.baseline_id}.png`,
             buf
           );
+          const manifestPath2 = await writeManifest({
+            runDir,
+            skill,
+            phase: "verify",
+            status: "pass",
+            summary: `baseline "${args.baseline_id}" seeded from current capture`,
+            startedAt,
+            finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            artifacts: [
+              { type: "baseline", path: baselinePath },
+              { type: "screenshot", path: currentPath }
+            ],
+            metadata: { baseline_id: args.baseline_id, seeded: true }
+          });
           return ok({
             run_id: runId,
             baseline_id: args.baseline_id,
@@ -3626,6 +3827,7 @@ var visualDiffTool = {
             passed: true,
             baseline_path: baselinePath,
             current_path: currentPath,
+            ...manifestPath2 ? { manifest: manifestPath2 } : {},
             note: "Baseline did not exist \u2014 current capture saved as the new baseline."
           });
         }
@@ -3656,21 +3858,45 @@ var visualDiffTool = {
         );
         const total = baseline.width * baseline.height;
         const diffPct = diffPixels / total;
+        const passed = diffPct <= args.threshold_pct;
         const diffImagePath = await ctx.store.writeBytes(
           runDir,
           "diff.png",
           PNG.sync.write(diff)
         );
+        const artifacts = [
+          { type: "baseline", path: baselinePath },
+          { type: "screenshot", path: currentPath },
+          { type: "diff", path: diffImagePath }
+        ];
+        const manifestPath = await writeManifest({
+          runDir,
+          skill,
+          phase: "verify",
+          status: passed ? "pass" : "fail",
+          summary: `diff ${(diffPct * 100).toFixed(3)}% vs baseline "${args.baseline_id}" (threshold ${(args.threshold_pct * 100).toFixed(3)}%)`,
+          startedAt,
+          finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          artifacts,
+          metadata: {
+            baseline_id: args.baseline_id,
+            diff_pct: Number(diffPct.toFixed(6)),
+            diff_pixels: diffPixels,
+            total_pixels: total,
+            threshold_pct: args.threshold_pct
+          }
+        });
         return ok({
           run_id: runId,
           baseline_id: args.baseline_id,
           diff_pct: Number(diffPct.toFixed(6)),
           diff_pixels: diffPixels,
           total_pixels: total,
-          passed: diffPct <= args.threshold_pct,
+          passed,
           baseline_path: baselinePath,
           current_path: currentPath,
-          diff_image_path: diffImagePath
+          diff_image_path: diffImagePath,
+          ...manifestPath ? { manifest: manifestPath } : {}
         });
       } finally {
         if (args.close_on_finish) {
@@ -3939,8 +4165,19 @@ var toolMetadata = {
 
 // src/server.ts
 var SERVER_NAME = "rolepod-uiproof";
-var SERVER_VERSION = "0.5.0";
+var SERVER_VERSION = "0.6.1";
+var SUPPORTED_PROTOCOL = "v1";
+function checkProtocolCompat() {
+  const parent = detectRolepodParent();
+  if (!parent.active || !parent.protocol) return;
+  if (parent.protocol !== SUPPORTED_PROTOCOL) {
+    console.warn(
+      `rolepod protocol mismatch: expected ${SUPPORTED_PROTOCOL}, got ${parent.protocol}. Manifest will still be written in ${SUPPORTED_PROTOCOL} shape \u2014 parent may not parse it correctly.`
+    );
+  }
+}
 function buildServer(opts = {}) {
+  checkProtocolCompat();
   const webEngine = createWebEngine();
   const registry = new SessionRegistry({ idleTimeoutMs: opts.idleTimeoutMs });
   registry.register("web", webEngine);
@@ -4001,6 +4238,8 @@ function buildServer(opts = {}) {
   }
   log.info("rolepod-uiproof server built", {
     version: SERVER_VERSION,
+    protocol: SUPPORTED_PROTOCOL,
+    mode: store.mode,
     tools: tools.map((t) => t.name)
   });
   return {