@piwitests/reporter 0.22.1 → 0.24.0

package/dist/cli/index.js

@@ -23,8 +23,391 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
-// src/cli/gate.ts
+// src/cli/ai.ts
+var path5 = __toESM(require("path"));
+var import_node_child_process = require("child_process");
+
+// src/internal/ai/check.ts
+var fs2 = __toESM(require("fs"));
+var path4 = __toESM(require("path"));
+
+// src/internal/ai/artifact.ts
 var fs = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+
+// src/internal/capture/locator-healing.ts
+var path = __toESM(require("path"));
+
+// ../core/src/locator-methods.ts
+var LOCATOR_BUILDER_METHODS = [
+  "getByRole",
+  "getByTestId",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "locator"
+];
+
+// src/internal/capture/locator-healing.ts
+var LOCATOR_METHODS = [...LOCATOR_BUILDER_METHODS];
+var ACTION_METHODS = [
+  "click",
+  "fill",
+  "check",
+  "uncheck",
+  "selectOption",
+  "dblclick",
+  "tap",
+  "hover",
+  "press",
+  "type",
+  "pressSequentially",
+  "clear",
+  "setInputFiles",
+  "dragTo",
+  "focus",
+  "blur",
+  "scrollIntoViewIfNeeded",
+  "dispatchEvent",
+  "selectText",
+  // Not an action, but a successful waitFor proves the element resolved — the
+  // closest capture hook available for assertion-style usage of a locator.
+  "waitFor"
+];
+var LOCATOR_CREATING_CHAINS = new Set(LOCATOR_METHODS);
+
+// src/internal/ai/artifact.ts
+var ARTIFACT_VERSION = 1;
+var LOCATOR_METHOD_SET = new Set(LOCATOR_METHODS);
+var ACTION_METHOD_SET = new Set(ACTION_METHODS);
+var POSTCONDITION_ASSERTS = /* @__PURE__ */ new Set([
+  "visible",
+  "hidden",
+  "attached",
+  "url"
+]);
+function sortDeep(value) {
+  if (Array.isArray(value)) return value.map(sortDeep);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      const v = value[key];
+      if (v !== void 0) out[key] = sortDeep(v);
+    }
+    return out;
+  }
+  return value;
+}
+function serializeEntry(entry) {
+  return `${JSON.stringify(sortDeep(entry), null, 2)}
+`;
+}
+var ArtifactError = class extends Error {
+};
+function assert(condition, message) {
+  if (!condition) throw new ArtifactError(message);
+}
+function validateStructuredLocator(value, where) {
+  assert(value !== null && typeof value === "object", `${where}: locator must be an object`);
+  const loc = value;
+  assert(typeof loc.method === "string", `${where}: locator.method must be a string`);
+  assert(LOCATOR_METHOD_SET.has(loc.method), `${where}: locator method "${String(loc.method)}" is not allowlisted`);
+  assert(Array.isArray(loc.args), `${where}: locator.args must be an array`);
+  if (loc.chain !== void 0) {
+    assert(Array.isArray(loc.chain), `${where}: locator.chain must be an array`);
+    loc.chain.forEach((child, i) => validateStructuredLocator(child, `${where}.chain[${i}]`));
+  }
+}
+function validateRunStep(value, where) {
+  assert(value !== null && typeof value === "object", `${where}: step must be an object`);
+  const step = value;
+  validateStructuredLocator(step.locator, `${where}.locator`);
+  assert(typeof step.action === "string", `${where}: action must be a string`);
+  assert(ACTION_METHOD_SET.has(step.action), `${where}: action "${String(step.action)}" is not allowlisted`);
+  if (step.value !== void 0) assert(typeof step.value === "string", `${where}: value must be a string`);
+  if (step.optional !== void 0) assert(typeof step.optional === "boolean", `${where}: optional must be a boolean`);
+  if (step.waitForResponse !== void 0) {
+    assert(typeof step.waitForResponse === "string", `${where}: waitForResponse must be a string`);
+  }
+}
+function validatePostcondition(value) {
+  assert(value !== null && typeof value === "object", "postcondition must be an object");
+  const post = value;
+  assert(
+    POSTCONDITION_ASSERTS.has(post.assert),
+    `postcondition.assert "${String(post.assert)}" is not supported`
+  );
+  if (post.assert === "url") {
+    assert(typeof post.url === "string", "postcondition.url must be a string for a url assert");
+  } else {
+    validateStructuredLocator(post.locator, "postcondition.locator");
+  }
+}
+function parseEntry(text) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    throw new ArtifactError(`entry is not valid JSON: ${error.message}`);
+  }
+  assert(raw !== null && typeof raw === "object", "entry must be an object");
+  const obj = raw;
+  assert(obj.version === ARTIFACT_VERSION, `unsupported entry version ${String(obj.version)}`);
+  assert(typeof obj.template === "string", "entry.template must be a string");
+  if (obj.kind === "locator") {
+    validateStructuredLocator(obj.locator, "entry.locator");
+    return obj;
+  }
+  if (obj.kind === "run") {
+    assert(Array.isArray(obj.steps), "entry.steps must be an array");
+    obj.steps.forEach((step, i) => validateRunStep(step, `entry.steps[${i}]`));
+    validatePostcondition(obj.postcondition);
+    return obj;
+  }
+  throw new ArtifactError(`unsupported entry kind "${String(obj.kind)}"`);
+}
+
+// src/internal/ai/keys.ts
+var crypto = __toESM(require("crypto"));
+var path3 = __toESM(require("path"));
+var DEFAULT_AI_DIR = "__piwi__";
+function normalizeTemplate(template) {
+  return template.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+// src/internal/ai/check.ts
+function findEntryFiles(root, dir) {
+  const out = [];
+  const walk = (current) => {
+    let items;
+    try {
+      items = fs2.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const item of items) {
+      const full = path4.join(current, item.name);
+      if (item.isDirectory()) {
+        walk(full);
+      } else if (item.isFile() && item.name.endsWith(".json")) {
+        const specFileDir = path4.dirname(full);
+        const dirName = path4.basename(path4.dirname(specFileDir));
+        if (dirName !== dir) continue;
+        const specDir = path4.dirname(path4.dirname(specFileDir));
+        const specFile = path4.join(specDir, path4.basename(specFileDir));
+        out.push({ file: full, specFile, testSlug: item.name.split(".")[0] });
+      }
+    }
+  };
+  walk(root);
+  return out;
+}
+function readTextOr(file, fallback) {
+  try {
+    return fs2.readFileSync(file, "utf8");
+  } catch {
+    return fallback;
+  }
+}
+function checkAiTree(root, opts = {}) {
+  const dir = opts.dir ?? DEFAULT_AI_DIR;
+  const findings = [];
+  const rel = (file) => path4.relative(root, file).split(path4.sep).join("/");
+  const sourceCache = /* @__PURE__ */ new Map();
+  const duplicates = /* @__PURE__ */ new Map();
+  for (const found of findEntryFiles(root, dir)) {
+    const text = readTextOr(found.file, null);
+    if (text === null) continue;
+    let templateNormalized = null;
+    try {
+      const entry = parseEntry(text);
+      templateNormalized = normalizeTemplate(entry.template);
+      if (serializeEntry(entry) !== text) {
+        findings.push({
+          severity: "error",
+          kind: "non-canonical",
+          file: rel(found.file),
+          message: "file is not in canonical form \u2014 run `piwi ai prune --apply` or re-resolve to rewrite it"
+        });
+      }
+      if (!sourceCache.has(found.specFile)) sourceCache.set(found.specFile, readTextOr(found.specFile, null));
+      const source = sourceCache.get(found.specFile) ?? null;
+      if (source === null) {
+        findings.push({
+          severity: "error",
+          kind: "orphan",
+          file: rel(found.file),
+          message: `spec file is gone (${rel(found.specFile)}) \u2014 the entry is orphaned`
+        });
+      } else if (!source.includes(entry.template.trim())) {
+        findings.push({
+          severity: "error",
+          kind: "orphan",
+          file: rel(found.file),
+          message: `template "${entry.template}" no longer appears in ${rel(found.specFile)} \u2014 the entry is orphaned`
+        });
+      }
+    } catch (error) {
+      findings.push({
+        severity: "error",
+        kind: "invalid",
+        file: rel(found.file),
+        message: `not a valid entry: ${error.message}`
+      });
+    }
+    if (templateNormalized !== null) {
+      const key = `${found.specFile}::${found.testSlug}::${templateNormalized}`;
+      const list = duplicates.get(key) ?? [];
+      list.push(rel(found.file));
+      duplicates.set(key, list);
+    }
+  }
+  for (const files of duplicates.values()) {
+    if (files.length < 2) continue;
+    for (const file of files) {
+      findings.push({
+        severity: "warning",
+        kind: "duplicate-template",
+        file,
+        message: `duplicate template within the same test \u2014 consider distinct phrasings (${files.join(", ")})`
+      });
+    }
+  }
+  return findings.sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
+}
+function hasBlockingFindings(findings) {
+  return findings.some((f) => f.severity === "error");
+}
+
+// src/cli/ai.ts
+var EXIT_OK = 0;
+var EXIT_ISSUES = 1;
+var EXIT_ERROR = 2;
+var USAGE = `
+Usage: piwi ai <command> [options]
+
+Commands:
+  check    Scan committed AI-step entries for orphans, non-canonical files and
+           duplicate templates. Read-only; exits 1 when issues are found.
+  resolve  Author missing entries by running the suite in resolve mode against
+           the configured authoring server (forces --workers=1).
+  prune    Delete orphaned/dormant entries.
+
+Options (check):
+  --dir <name>   Entry directory name per spec        (env PIWI_AI_DIR, default ${DEFAULT_AI_DIR})
+  --cwd <path>   Root to scan                          (default: current directory)
+  --json         Emit findings as JSON
+
+Options (resolve):
+  --grep <re>       Only author entries for matching tests
+  --project <name>  Author under one Playwright project (a resolve profile)
+  --env K=V         Extra env for the run (repeatable \u2014 flags/viewport profiles)
+  --update-ai       Re-author entries that already exist
+                    (needs PIWI_DASHBOARD_URL / PIWI_API_KEY for the server)
+
+Exit codes:
+  0  clean (or --help)
+  1  hygiene issues found
+  2  bad arguments / command unavailable
+`.trim();
+function readOption(argv, name) {
+  const withEquals = argv.find((arg) => arg.startsWith(`${name}=`));
+  if (withEquals) return withEquals.slice(name.length + 1);
+  const index = argv.indexOf(name);
+  if (index === -1) return void 0;
+  const value = argv[index + 1];
+  return value && !value.startsWith("--") ? value : void 0;
+}
+function readAll(argv, name) {
+  const values = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith(`${name}=`)) values.push(argv[i].slice(name.length + 1));
+    else if (argv[i] === name && argv[i + 1] && !argv[i + 1].startsWith("--")) values.push(argv[++i]);
+  }
+  return values;
+}
+function formatFinding(finding) {
+  const mark = finding.severity === "error" ? "\u2716" : "\u26A0";
+  return `${mark} ${finding.file}
+    ${finding.kind}: ${finding.message}`;
+}
+function runCheck(argv, env) {
+  const root = path5.resolve(readOption(argv, "--cwd") ?? process.cwd());
+  const dir = readOption(argv, "--dir") ?? env.PIWI_AI_DIR ?? DEFAULT_AI_DIR;
+  let findings;
+  try {
+    findings = checkAiTree(root, { dir });
+  } catch (error) {
+    console.error(`piwi ai check: ${error.message}`);
+    return EXIT_ERROR;
+  }
+  if (argv.includes("--json")) {
+    console.log(JSON.stringify({ findings }, null, 2));
+  } else if (findings.length === 0) {
+    console.log("piwi ai check: no issues found.");
+  } else {
+    for (const finding of findings) console.log(formatFinding(finding));
+    const errors = findings.filter((f) => f.severity === "error").length;
+    const warnings = findings.length - errors;
+    console.log(`
+${errors} error(s), ${warnings} warning(s).`);
+  }
+  return hasBlockingFindings(findings) ? EXIT_ISSUES : EXIT_OK;
+}
+function buildResolveInvocation(argv, env) {
+  const args = ["playwright", "test"];
+  const grep = readOption(argv, "--grep");
+  if (grep) args.push("--grep", grep);
+  const project = readOption(argv, "--project");
+  if (project) args.push("--project", project);
+  args.push("--workers=1");
+  const childEnv = { ...env, PIWI_AI: "resolve" };
+  if (argv.includes("--update-ai")) childEnv.PIWI_AI_UPDATE = "true";
+  for (const pair of readAll(argv, "--env")) {
+    const eq = pair.indexOf("=");
+    if (eq > 0) childEnv[pair.slice(0, eq)] = pair.slice(eq + 1);
+  }
+  return { command: "npx", args, env: childEnv };
+}
+function runResolve(argv, env) {
+  if (!env.PIWI_DASHBOARD_URL) {
+    console.error("piwi ai resolve: set PIWI_DASHBOARD_URL (the authoring server) before resolving.");
+    return EXIT_ERROR;
+  }
+  const invocation = buildResolveInvocation(argv, env);
+  const result = (0, import_node_child_process.spawnSync)(invocation.command, invocation.args, { stdio: "inherit", env: invocation.env });
+  if (result.error) {
+    console.error(`piwi ai resolve: ${result.error.message}`);
+    return EXIT_ERROR;
+  }
+  return result.status ?? EXIT_ERROR;
+}
+async function runAi(argv, env = process.env) {
+  const [sub, ...rest] = argv;
+  if (sub === void 0 || sub === "-h" || sub === "--help") {
+    console.log(USAGE);
+    return EXIT_OK;
+  }
+  switch (sub) {
+    case "check":
+      return runCheck(rest, env);
+    case "resolve":
+      return runResolve(rest, env);
+    case "prune":
+      console.error("piwi ai prune: three-tier cleanup is not available in this build yet.");
+      return EXIT_ERROR;
+    default:
+      console.error(`piwi ai: unknown command "${sub}"
+`);
+      console.error(USAGE);
+      return EXIT_ERROR;
+  }
+}
+
+// src/cli/gate.ts
+var fs3 = __toESM(require("fs"));
 
 // ../core/src/gate.ts
 function formatGateResult(result) {
@@ -44,10 +427,10 @@ function formatGateResult(result) {
 }
 
 // src/cli/gate.ts
-var EXIT_OK = 0;
+var EXIT_OK2 = 0;
 var EXIT_VIOLATED = 1;
-var EXIT_ERROR = 2;
-var USAGE = `
+var EXIT_ERROR2 = 2;
+var USAGE2 = `
 piwi gate \u2014 fail a CI job on the dashboard's analysis of a run
 
 Usage:
@@ -77,7 +460,7 @@ Other:
 
 Exit codes: 0 satisfied, 1 violated, 2 could not evaluate.
 `.trim();
-function readOption(argv, name) {
+function readOption2(argv, name) {
   const withEquals = argv.find((arg) => arg.startsWith(`${name}=`));
   if (withEquals) return withEquals.slice(name.length + 1);
   const index = argv.indexOf(name);
@@ -86,15 +469,15 @@ function readOption(argv, name) {
   return value && !value.startsWith("--") ? value : void 0;
 }
 function readCount(argv, name) {
-  const raw = readOption(argv, name);
+  const raw = readOption2(argv, name);
   if (raw === void 0) return void 0;
   const n = Number(raw);
   if (!Number.isFinite(n) || n < 0) throw new Error(`${name} expects a non-negative number, got "${raw}"`);
   return Math.floor(n);
 }
-function readRunIdFromFile(path4) {
+function readRunIdFromFile(path9) {
   try {
-    const parsed = JSON.parse(fs.readFileSync(path4, "utf-8"));
+    const parsed = JSON.parse(fs3.readFileSync(path9, "utf-8"));
     const runId = Number(parsed.runId);
     return Number.isFinite(runId) && runId > 0 ? runId : null;
   } catch {
@@ -102,11 +485,11 @@ function readRunIdFromFile(path4) {
   }
 }
 function parseGateArgs(argv, env) {
-  const serverUrl = (readOption(argv, "--server-url") ?? env.PIWI_DASHBOARD_URL ?? "").replace(/\/$/, "");
+  const serverUrl = (readOption2(argv, "--server-url") ?? env.PIWI_DASHBOARD_URL ?? "").replace(/\/$/, "");
   if (!serverUrl) throw new Error("No dashboard URL \u2014 pass --server-url or set PIWI_DASHBOARD_URL");
-  let runId = Number(readOption(argv, "--run-id") ?? NaN);
+  let runId = Number(readOption2(argv, "--run-id") ?? NaN);
   if (!Number.isFinite(runId) || runId <= 0) {
-    const candidate = readOption(argv, "--from-file") ?? env.PIWI_OUTPUT_FILE ?? "piwi-run.json";
+    const candidate = readOption2(argv, "--from-file") ?? env.PIWI_OUTPUT_FILE ?? "piwi-run.json";
     runId = readRunIdFromFile(candidate) ?? NaN;
   }
   if (!Number.isFinite(runId) || runId <= 0) {
@@ -114,7 +497,7 @@ function parseGateArgs(argv, env) {
       "No run to evaluate \u2014 pass --run-id, or set PIWI_OUTPUT_FILE so the reporter records the run it submitted"
     );
   }
-  const requireTags = (readOption(argv, "--require-tag") ?? "").split(",").map((tag) => tag.trim().replace(/^@+/, "")).filter(Boolean);
+  const requireTags = (readOption2(argv, "--require-tag") ?? "").split(",").map((tag) => tag.trim().replace(/^@+/, "")).filter(Boolean);
   const policy = {
     requireTags,
     maxFailed: readCount(argv, "--max-failed"),
@@ -123,7 +506,7 @@ function parseGateArgs(argv, env) {
     maxQuarantined: readCount(argv, "--max-quarantined"),
     failOnNewCluster: argv.includes("--fail-on-new-cluster")
   };
-  return { serverUrl, apiKey: readOption(argv, "--api-key") ?? env.PIWI_API_KEY ?? null, runId, policy };
+  return { serverUrl, apiKey: readOption2(argv, "--api-key") ?? env.PIWI_API_KEY ?? null, runId, policy };
 }
 async function requestGate(args) {
   const headers = { "Content-Type": "application/json" };
@@ -141,8 +524,8 @@ async function requestGate(args) {
 }
 async function runGate(argv, env = process.env) {
   if (argv.includes("-h") || argv.includes("--help")) {
-    console.log(USAGE);
-    return EXIT_OK;
+    console.log(USAGE2);
+    return EXIT_OK2;
   }
   let args;
   try {
@@ -150,28 +533,28 @@ async function runGate(argv, env = process.env) {
   } catch (e) {
     console.error(`piwi gate: ${e.message}
 `);
-    console.error(USAGE);
-    return EXIT_ERROR;
+    console.error(USAGE2);
+    return EXIT_ERROR2;
   }
   let result;
   try {
     result = await requestGate(args);
   } catch (e) {
     console.error(`piwi gate: ${e.message}`);
-    return EXIT_ERROR;
+    return EXIT_ERROR2;
   }
   if (argv.includes("--json")) {
     console.log(JSON.stringify(result, null, 2));
   } else {
     console.log(formatGateResult(result));
   }
-  return result.passed ? EXIT_OK : EXIT_VIOLATED;
+  return result.passed ? EXIT_OK2 : EXIT_VIOLATED;
 }
 
 // src/cli/init.ts
-var fs4 = __toESM(require("fs"));
-var path3 = __toESM(require("path"));
-var import_node_child_process = require("child_process");
+var fs6 = __toESM(require("fs"));
+var path8 = __toESM(require("path"));
+var import_node_child_process2 = require("child_process");
 
 // src/cli/report.ts
 var STATUS_MARK = {
@@ -188,8 +571,8 @@ function formatStep(result) {
 }
 
 // src/cli/detect.ts
-var fs2 = __toESM(require("fs"));
-var path = __toESM(require("path"));
+var fs4 = __toESM(require("fs"));
+var path6 = __toESM(require("path"));
 var CONFIG_NAMES = [
   "playwright.config.ts",
   "playwright.config.mts",
@@ -207,9 +590,9 @@ var LOCKFILES = [
 ];
 var REPORTER_PACKAGE = "@piwitests/reporter";
 function readPackageJson(root) {
-  const pkgPath = path.join(root, "package.json");
+  const pkgPath = path6.join(root, "package.json");
   try {
-    return { pkg: JSON.parse(fs2.readFileSync(pkgPath, "utf-8")), pkgPath };
+    return { pkg: JSON.parse(fs4.readFileSync(pkgPath, "utf-8")), pkgPath };
   } catch {
     return { pkg: null, pkgPath: null };
   }
@@ -218,14 +601,14 @@ function detectPackageManager(root, pkg) {
   const declared = pkg?.packageManager?.split("@")[0];
   if (declared === "pnpm" || declared === "yarn" || declared === "bun" || declared === "npm") return declared;
   for (const [file, manager] of LOCKFILES) {
-    if (fs2.existsSync(path.join(root, file))) return manager;
+    if (fs4.existsSync(path6.join(root, file))) return manager;
   }
   return "npm";
 }
 function findConfig(root) {
   for (const name of CONFIG_NAMES) {
-    const candidate = path.join(root, name);
-    if (fs2.existsSync(candidate)) return candidate;
+    const candidate = path6.join(root, name);
+    if (fs4.existsSync(candidate)) return candidate;
   }
   return null;
 }
@@ -235,14 +618,14 @@ function langOf(configPath) {
 }
 function suggestProjectName(root, pkg) {
   const fromPkg = pkg?.name?.replace(/^@[^/]+\//, "").trim();
-  return fromPkg || path.basename(root) || "default-project";
+  return fromPkg || path6.basename(root) || "default-project";
 }
 function hasReporter(pkg) {
   if (!pkg) return false;
   return Boolean(pkg.dependencies?.[REPORTER_PACKAGE] || pkg.devDependencies?.[REPORTER_PACKAGE]);
 }
 function detectProject(root) {
-  const absRoot = path.resolve(root);
+  const absRoot = path6.resolve(root);
   const { pkg, pkgPath } = readPackageJson(absRoot);
   const configPath = findConfig(absRoot);
   return {
@@ -384,21 +767,21 @@ function ensureGitignoreEntry(existing, entry = ".env") {
 }
 
 // src/cli/skills.ts
-var fs3 = __toESM(require("fs"));
-var path2 = __toESM(require("path"));
+var fs5 = __toESM(require("fs"));
+var path7 = __toESM(require("path"));
 var SETUP_SKILL = "setup-piwi";
 var WORKFLOW_SKILLS = ["investigate-failure", "apply-locator-healing", "stabilize-flaky-tests"];
 var ALL_SKILLS = [SETUP_SKILL, ...WORKFLOW_SKILLS];
-var DEFAULT_SKILLS_DIR = path2.join(".claude", "skills");
+var DEFAULT_SKILLS_DIR = path7.join(".claude", "skills");
 function findTemplatesDir(fromDir) {
   let dir = fromDir;
   for (let i = 0; i < 6; i++) {
-    if (fs3.existsSync(path2.join(dir, "templates", "skills"))) return path2.join(dir, "templates");
-    const parent = path2.dirname(dir);
+    if (fs5.existsSync(path7.join(dir, "templates", "skills"))) return path7.join(dir, "templates");
+    const parent = path7.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  return path2.resolve(fromDir, "..", "..", "templates");
+  return path7.resolve(fromDir, "..", "..", "templates");
 }
 function readFrontMatter(markdown) {
   const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(markdown);
@@ -411,14 +794,14 @@ function readFrontMatter(markdown) {
   return out;
 }
 function templatePath(templatesDir, slug) {
-  return path2.join(templatesDir, "skills", slug, "SKILL.md");
+  return path7.join(templatesDir, "skills", slug, "SKILL.md");
 }
 function listSkills(templatesDir, slugs = ALL_SKILLS) {
   const infos = [];
   for (const slug of slugs) {
     const file = templatePath(templatesDir, slug);
-    if (!fs3.existsSync(file)) continue;
-    const front = readFrontMatter(fs3.readFileSync(file, "utf-8"));
+    if (!fs5.existsSync(file)) continue;
+    const front = readFrontMatter(fs5.readFileSync(file, "utf-8"));
     infos.push({ slug, name: front.name ?? slug, description: front.description ?? "" });
   }
   return infos;
@@ -428,16 +811,16 @@ function installSkills(opts) {
   for (const slug of opts.slugs) {
     const step = `skill:${slug}`;
     const source = templatePath(opts.templatesDir, slug);
-    const relDest = path2.join(opts.skillsDir, slug, "SKILL.md");
-    const dest = path2.join(opts.root, relDest);
-    if (!fs3.existsSync(source)) {
+    const relDest = path7.join(opts.skillsDir, slug, "SKILL.md");
+    const dest = path7.join(opts.root, relDest);
+    if (!fs5.existsSync(source)) {
       results.push({ step, status: "error", detail: `no template found for "${slug}"` });
       continue;
     }
-    const contents = fs3.readFileSync(source, "utf-8");
-    const exists = fs3.existsSync(dest);
+    const contents = fs5.readFileSync(source, "utf-8");
+    const exists = fs5.existsSync(dest);
     if (exists && !opts.force) {
-      const identical = fs3.readFileSync(dest, "utf-8") === contents;
+      const identical = fs5.readFileSync(dest, "utf-8") === contents;
       results.push({
         step,
         file: relDest,
@@ -447,14 +830,14 @@ function installSkills(opts) {
       continue;
     }
     if (!opts.dryRun) {
-      fs3.mkdirSync(path2.dirname(dest), { recursive: true });
-      fs3.writeFileSync(dest, contents);
+      fs5.mkdirSync(path7.dirname(dest), { recursive: true });
+      fs5.writeFileSync(dest, contents);
     }
     results.push({ step, file: relDest, status: exists ? "updated" : "created", detail: "installed skill" });
   }
   return results;
 }
-var USAGE2 = `
+var USAGE3 = `
 piwi skills \u2014 install the Piwi agent skills into this project
 
 Usage:
@@ -474,7 +857,7 @@ Options for "add":
 
 Skills: ${ALL_SKILLS.join(", ")}
 `.trim();
-function readOption2(argv, name) {
+function readOption3(argv, name) {
   const withEquals = argv.find((arg) => arg.startsWith(`${name}=`));
   if (withEquals) return withEquals.slice(name.length + 1);
   const index = argv.indexOf(name);
@@ -493,7 +876,7 @@ function positionalSlugs(argv) {
 function runSkills(argv, templatesDir, cwd = process.cwd()) {
   const [sub, ...rest] = argv;
   if (sub === void 0 || sub === "-h" || sub === "--help") {
-    console.log(USAGE2);
+    console.log(USAGE3);
     return 0;
   }
   if (sub === "list") {
@@ -514,13 +897,13 @@ function runSkills(argv, templatesDir, cwd = process.cwd()) {
     if (unknown.length) {
       console.error(`piwi skills: unknown skill(s): ${unknown.join(", ")}
 `);
-      console.error(USAGE2);
+      console.error(USAGE3);
       return 2;
     }
     const results = installSkills({
       templatesDir,
-      root: path2.resolve(readOption2(rest, "--cwd") ?? cwd),
-      skillsDir: readOption2(rest, "--dir") ?? DEFAULT_SKILLS_DIR,
+      root: path7.resolve(readOption3(rest, "--cwd") ?? cwd),
+      skillsDir: readOption3(rest, "--dir") ?? DEFAULT_SKILLS_DIR,
       slugs: requested.length ? requested : ALL_SKILLS,
       force: rest.includes("--force"),
       dryRun: rest.includes("--dry-run")
@@ -535,13 +918,13 @@ function runSkills(argv, templatesDir, cwd = process.cwd()) {
   }
   console.error(`piwi skills: unknown command "${sub}"
 `);
-  console.error(USAGE2);
+  console.error(USAGE3);
   return 2;
 }
 
 // src/cli/init.ts
 var DEFAULT_SERVER_URL = "http://localhost:3000";
-var USAGE3 = `
+var USAGE4 = `
 piwi init \u2014 wire a Playwright project up to a Piwi Dashboard
 
 Usage:
@@ -574,7 +957,7 @@ Options:
 
 Skills: ${ALL_SKILLS.join(", ")}
 `.trim();
-function readOption3(argv, name) {
+function readOption4(argv, name) {
   const withEquals = argv.find((arg) => arg.startsWith(`${name}=`));
   if (withEquals) return withEquals.slice(name.length + 1);
   const index = argv.indexOf(name);
@@ -590,15 +973,15 @@ function resolveSkillSlugs(raw) {
   return raw.split(",").map((slug) => slug.trim()).filter(Boolean);
 }
 function parseInitArgs(argv, env, cwd) {
-  const root = path3.resolve(readOption3(argv, "--cwd") ?? cwd);
+  const root = path8.resolve(readOption4(argv, "--cwd") ?? cwd);
   const detected = detectProject(root);
   return {
     root,
-    serverUrl: (readOption3(argv, "--server-url") ?? env.PIWI_DASHBOARD_URL ?? DEFAULT_SERVER_URL).replace(/\/$/, ""),
-    projectName: readOption3(argv, "--project") ?? detected.suggestedProjectName,
-    apiKey: readOption3(argv, "--api-key") ?? env.PIWI_API_KEY ?? null,
-    skillsDir: readOption3(argv, "--skills-dir") ?? DEFAULT_SKILLS_DIR,
-    skillSlugs: resolveSkillSlugs(readOption3(argv, "--skills")),
+    serverUrl: (readOption4(argv, "--server-url") ?? env.PIWI_DASHBOARD_URL ?? DEFAULT_SERVER_URL).replace(/\/$/, ""),
+    projectName: readOption4(argv, "--project") ?? detected.suggestedProjectName,
+    apiKey: readOption4(argv, "--api-key") ?? env.PIWI_API_KEY ?? null,
+    skillsDir: readOption4(argv, "--skills-dir") ?? DEFAULT_SKILLS_DIR,
+    skillSlugs: resolveSkillSlugs(readOption4(argv, "--skills")),
     install: !argv.includes("--no-install"),
     force: argv.includes("--force"),
     dryRun: argv.includes("--dry-run"),
@@ -609,7 +992,7 @@ function parseInitArgs(argv, env, cwd) {
 }
 function readFileOr(file, fallback) {
   try {
-    return fs4.readFileSync(file, "utf-8");
+    return fs6.readFileSync(file, "utf-8");
   } catch {
     return fallback;
   }
@@ -639,7 +1022,7 @@ function stepInstallReporter(project, opts) {
   if (opts.dryRun || !opts.install)
     return { step, status: "manual", detail: `Run \`${installCommand(project.packageManager)}\`` };
   const [command, args] = installArgv(project.packageManager);
-  const result = (0, import_node_child_process.spawnSync)(command, args, { cwd: opts.root, stdio: "inherit" });
+  const result = (0, import_node_child_process2.spawnSync)(command, args, { cwd: opts.root, stdio: "inherit" });
   if (result.status === 0) return { step, status: "updated", detail: `Installed ${REPORTER_PACKAGE}` };
   return {
     step,
@@ -655,19 +1038,19 @@ function stepConfig(project, opts) {
       status: "manual",
       detail: "No playwright.config found \u2014 create one, then re-run `npx @piwitests/reporter init`"
     };
-  const rel = path3.relative(project.root, project.configPath) || path3.basename(project.configPath);
+  const rel = path8.relative(project.root, project.configPath) || path8.basename(project.configPath);
   const edit = wrapPlaywrightConfig(readFileOr(project.configPath, ""), {
     serverUrl: opts.serverUrl,
     projectName: opts.projectName
   });
-  if (edit.status === "updated" && !opts.dryRun) fs4.writeFileSync(project.configPath, edit.text);
+  if (edit.status === "updated" && !opts.dryRun) fs6.writeFileSync(project.configPath, edit.text);
   return { step, file: rel, status: edit.status, detail: edit.detail };
 }
 function stepFixtures(project, opts) {
   const step = "fixtures";
-  const rel = path3.join("tests", project.configLang === "js" ? "fixtures.js" : "fixtures.ts");
-  const dest = path3.join(project.root, rel);
-  if (fs4.existsSync(dest)) {
+  const rel = path8.join("tests", project.configLang === "js" ? "fixtures.js" : "fixtures.ts");
+  const dest = path8.join(project.root, rel);
+  if (fs6.existsSync(dest)) {
     const current = readFileOr(dest, "");
     if (/piwiFixtures/.test(current))
       return { step, file: rel, status: "already", detail: "capture fixtures already set up" };
@@ -679,8 +1062,8 @@ function stepFixtures(project, opts) {
     };
   }
   if (!opts.dryRun) {
-    fs4.mkdirSync(path3.dirname(dest), { recursive: true });
-    fs4.writeFileSync(dest, fixturesContents());
+    fs6.mkdirSync(path8.dirname(dest), { recursive: true });
+    fs6.writeFileSync(dest, fixturesContents());
   }
   return {
     step,
@@ -691,12 +1074,12 @@ function stepFixtures(project, opts) {
 }
 function stepEnv(project, opts) {
   const results = [];
-  const examplePath = path3.join(project.root, ".env.example");
+  const examplePath = path8.join(project.root, ".env.example");
   const example = upsertEnvKeys(readFileOr(examplePath, ""), [
     ["PIWI_DASHBOARD_URL", opts.serverUrl],
     ["PIWI_API_KEY", ""]
   ]);
-  if (example.added.length && !opts.dryRun) fs4.writeFileSync(examplePath, example.text);
+  if (example.added.length && !opts.dryRun) fs6.writeFileSync(examplePath, example.text);
   results.push({
     step: "env",
     file: ".env.example",
@@ -704,21 +1087,21 @@ function stepEnv(project, opts) {
     detail: example.added.length ? `Recorded ${example.added.join(", ")}` : "connection template already present"
   });
   if (opts.apiKey) {
-    const envPath = path3.join(project.root, ".env");
+    const envPath = path8.join(project.root, ".env");
     const env = upsertEnvKeys(readFileOr(envPath, ""), [
       ["PIWI_DASHBOARD_URL", opts.serverUrl],
       ["PIWI_API_KEY", opts.apiKey]
     ]);
-    if (env.added.length && !opts.dryRun) fs4.writeFileSync(envPath, env.text);
+    if (env.added.length && !opts.dryRun) fs6.writeFileSync(envPath, env.text);
     results.push({
       step: "env",
       file: ".env",
       status: env.added.length ? "updated" : "already",
       detail: env.added.length ? `Wrote ${env.added.join(", ")} (keep .env out of git)` : "already set"
     });
-    const gitignorePath = path3.join(project.root, ".gitignore");
+    const gitignorePath = path8.join(project.root, ".gitignore");
     const gitignore = ensureGitignoreEntry(readFileOr(gitignorePath, ""));
-    if (gitignore.added && !opts.dryRun) fs4.writeFileSync(gitignorePath, gitignore.text);
+    if (gitignore.added && !opts.dryRun) fs6.writeFileSync(gitignorePath, gitignore.text);
     results.push({
       step: "gitignore",
       file: ".gitignore",
@@ -747,7 +1130,7 @@ function nextSteps(opts, steps) {
 }
 async function runInit(argv, env = process.env, cwd = process.cwd()) {
   if (argv.includes("-h") || argv.includes("--help")) {
-    console.log(USAGE3);
+    console.log(USAGE4);
     return 0;
   }
   const opts = parseInitArgs(argv, env, cwd);
@@ -780,7 +1163,7 @@ async function runInit(argv, env = process.env, cwd = process.cwd()) {
           project: {
             root: project.root,
             packageManager: project.packageManager,
-            configPath: project.configPath ? path3.relative(project.root, project.configPath) : null,
+            configPath: project.configPath ? path8.relative(project.root, project.configPath) : null,
             projectName: opts.projectName,
             serverUrl: opts.serverUrl
           },
@@ -804,7 +1187,7 @@ Piwi setup${opts.dryRun ? " (dry run \u2014 nothing written)" : ""} for "${opts.
 }
 
 // src/cli/index.ts
-var USAGE4 = `
+var USAGE5 = `
 piwi \u2014 companion commands for the Piwi Dashboard reporter
 
 Usage:
@@ -814,6 +1197,7 @@ Commands:
   init      Wire a Playwright project up to a Piwi Dashboard
   skills    Install the Piwi agent skills into this project
   gate      Fail a CI job on the dashboard's analysis of a run
+  ai        Manage committed natural-language AI-step artifacts
 
 Run \`npx @piwitests/reporter <command> --help\` for a command's options.
 (The published package is @piwitests/reporter; its command is piwi. Invoke it
@@ -828,15 +1212,17 @@ async function main() {
       return runSkills(rest, findTemplatesDir(__dirname));
     case "gate":
       return runGate(rest);
+    case "ai":
+      return runAi(rest);
     case void 0:
     case "-h":
     case "--help":
-      console.log(USAGE4);
+      console.log(USAGE5);
       return 0;
     default:
       console.error(`piwi: unknown command "${command}"
 `);
-      console.error(USAGE4);
+      console.error(USAGE5);
       return 2;
   }
 }