@rolepod/uiproof 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -3,10 +3,18 @@ import { z } from 'zod';
 import { Page } from 'playwright';
 
 /**
- * Writes artifacts under `./.rolepod-uiproof/artifacts/{run_id}/` (D-026).
+ * Writes run artifacts. In **standalone** mode (default) — and in v0.4 and
+ * earlier — runs live under `./.rolepod-uiproof/artifacts/{prefix}_{ts}_{uuid}/`.
  *
- * v0.1 emits two formats: PNG screenshots and a JSON replay bundle. Future
- * milestones extend the format set (HAR, console log, a11y tree, video).
+ * In **with-parent** mode — activated automatically when the env var
+ * `ROLEPOD_PARENT=1` is set by the parent `rolepod` plugin's SessionStart
+ * hook — runs live under `./.rolepod/evidence/{ts}-rolepod-uiproof-{skill}/`,
+ * per the Extension Protocol v1 evidence-path convention. Parent's
+ * `check-work` skill aggregates manifest.json files from this directory.
+ *
+ * Baselines for `visual_diff` always live in `./.rolepod-uiproof/baselines/`
+ * regardless of mode — they are user-curated configuration, not per-run
+ * evidence.
  */
 type ReplayStep = Record<string, unknown>;
 type ReplayBundle = {
@@ -17,16 +25,45 @@ type ReplayBundle = {
     steps: ReplayStep[];
     expect: ReplayStep[];
 };
+type ArtifactMode = "standalone" | "with-parent";
+type StartRunOptions = {
+    /**
+     * Skill name as it appears in marketplace (`verify-ui`, `audit-a11y`,
+     * `visual-diff`, `scaffold-e2e`, `check-errors`). REQUIRED when emitting
+     * a manifest.json (Extension Protocol v1) so parent's `check-work` can
+     * route artifacts to the right phase.
+     *
+     * In `with-parent` mode the run dirname is derived from this field; if
+     * omitted the `prefix` argument is used as a fallback (legacy).
+     */
+    skill?: string;
+};
+type StartRunResult = {
+    runId: string;
+    runDir: string;
+    skill: string;
+    mode: ArtifactMode;
+};
 declare class ArtifactStore {
     readonly rootDir: string;
+    readonly mode: ArtifactMode;
+    private readonly baselineRoot;
     constructor(opts?: {
         rootDir?: string;
+        mode?: ArtifactMode;
     });
-    /** Allocate a fresh run id and ensure its directory exists. */
-    startRun(prefix?: string): Promise<{
-        runId: string;
-        runDir: string;
-    }>;
+    /**
+     * Allocate a fresh run dir and ensure it exists.
+     *
+     * - standalone: `./.rolepod-uiproof/artifacts/{prefix}_{ts}_{uuid}/`
+     * - with-parent: `./.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.
+     */
+    startRun(prefix?: string, opts?: StartRunOptions): Promise<StartRunResult>;
     writeScreenshot(runDir: string, buf: Buffer, name: string): Promise<string>;
     writeReplayBundle(runDir: string, bundle: ReplayBundle, name?: string): Promise<string>;
     writeReport(runDir: string, name: string, body: string): Promise<string>;
@@ -1258,7 +1295,7 @@ declare class SessionRegistry {
 }
 
 declare const SERVER_NAME = "rolepod-uiproof";
-declare const SERVER_VERSION = "0.5.0";
+declare const SERVER_VERSION = "0.6.0";
 type ServerHandle = {
     mcp: McpServer;
     registry: SessionRegistry;

package/dist/index.js

@@ -28,16 +28,49 @@ var log = {
 // src/artifact/ArtifactStore.ts
 var ArtifactStore = class {
   rootDir;
+  mode;
+  baselineRoot;
   constructor(opts = {}) {
-    this.rootDir = opts.rootDir ?? resolve(process.cwd(), ".rolepod-uiproof", "artifacts");
+    const detectedParent = process.env.ROLEPOD_PARENT === "1";
+    this.mode = opts.mode ?? (detectedParent ? "with-parent" : "standalone");
+    if (opts.rootDir !== void 0) {
+      this.rootDir = opts.rootDir;
+    } else if (this.mode === "with-parent") {
+      this.rootDir = resolve(process.cwd(), ".rolepod", "evidence");
+    } else {
+      this.rootDir = resolve(process.cwd(), ".rolepod-uiproof", "artifacts");
+    }
+    this.baselineRoot = resolve(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: `./.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 = resolve(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 = resolve(runDir, `${name}.png`);
@@ -65,7 +98,7 @@ var ArtifactStore = class {
   }
   /** Root for stored visual baselines: `./.rolepod-uiproof/baselines/`. */
   get baselineDir() {
-    return resolve(this.rootDir, "..", "baselines");
+    return this.baselineRoot;
   }
   timestampSlug() {
     const d = /* @__PURE__ */ new Date();
@@ -1003,21 +1036,21 @@ var PlaywrightEngine = class {
     if (s.dialogArming) {
       s.dialogArming.resolve(false);
     }
-    return new Promise((resolve4) => {
+    return new Promise((resolve5) => {
       const arming = {
         action: opts.action,
         text: opts.text,
         expiresAt,
         resolve: (handled) => {
           s.dialogArming = null;
-          resolve4({ handled });
+          resolve5({ handled });
         }
       };
       s.dialogArming = arming;
       const timer = setTimeout(() => {
         if (s.dialogArming === arming) {
           s.dialogArming = null;
-          resolve4({ handled: false });
+          resolve5({ handled: false });
         }
       }, timeoutMs);
       timer.unref?.();
@@ -2336,6 +2369,39 @@ var browserWaitForTool = {
 
 // src/tools/composite/audit_a11y.ts
 import AxeBuilder from "@axe-core/playwright";
+
+// src/util/manifest.ts
+import { writeFile as writeFile2 } from "fs/promises";
+import { resolve as resolve2 } 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 = resolve2(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/composite/audit_a11y.ts
 var TAGS_BY_LEVEL = {
   "wcag-a": ["wcag2a", "wcag21a"],
   "wcag-aa": ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"],
@@ -2360,7 +2426,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)) {
@@ -2428,15 +2498,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));
 }
@@ -2553,14 +2653,18 @@ function scoreTree(root, tokens) {
 
 // src/tools/composite/scaffold_e2e.ts
 import { readFile } from "fs/promises";
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } 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 };
@@ -2598,19 +2702,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 readFile(resolve2(bundlePath), "utf8");
+  const raw = await readFile(resolve3(bundlePath), "utf8");
   return JSON.parse(raw);
 }
 function slugify(s) {
@@ -2934,7 +3054,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"
@@ -2959,10 +3083,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")) {
@@ -3377,7 +3540,7 @@ function treeHasText(tree, text) {
 // src/tools/composite/visual_diff.ts
 import { existsSync } from "fs";
 import { readFile as readFile2 } from "fs/promises";
-import { resolve as resolve3 } from "path";
+import { resolve as resolve4 } from "path";
 import pixelmatch from "pixelmatch";
 import { PNG } from "pngjs";
 var visualDiffTool = {
@@ -3386,7 +3549,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 } : {}
@@ -3405,7 +3572,7 @@ var visualDiffTool = {
         );
         const currentPath = await ctx.store.writeScreenshot(runDir, buf, "current");
         await ctx.store.ensureDir(ctx.store.baselineDir);
-        const baselinePath = resolve3(
+        const baselinePath = resolve4(
           ctx.store.baselineDir,
           `${args.baseline_id}.png`
         );
@@ -3415,6 +3582,20 @@ var visualDiffTool = {
             `${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,
@@ -3422,6 +3603,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."
           });
         }
@@ -3452,21 +3634,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) {
@@ -3735,8 +3941,19 @@ var toolMetadata = {
 
 // src/server.ts
 var SERVER_NAME = "rolepod-uiproof";
-var SERVER_VERSION = "0.5.0";
+var SERVER_VERSION = "0.6.0";
+var SUPPORTED_PROTOCOL = "v1";
+function checkProtocolCompat() {
+  const requested = process.env.ROLEPOD_PROTOCOL;
+  if (!requested) return;
+  if (requested !== SUPPORTED_PROTOCOL) {
+    console.warn(
+      `rolepod protocol mismatch: expected ${SUPPORTED_PROTOCOL}, got ${requested}. 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);
@@ -3797,6 +4014,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 {