@piwitests/reporter 0.20.0 → 0.22.0

package/dist/cli/index.js

@@ -26,7 +26,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 // src/cli/gate.ts
 var fs = __toESM(require("fs"));
 
-// ../packages/core/src/gate.ts
+// ../core/src/gate.ts
 function formatGateResult(result) {
   const { facts } = result;
   const lines = [
@@ -51,7 +51,7 @@ var USAGE = `
 piwi gate \u2014 fail a CI job on the dashboard's analysis of a run
 
 Usage:
-  npx piwi gate [options]
+  npx @piwitests/reporter gate [options]
 
 Where the run comes from (first match wins):
   --run-id <id>            Run id to evaluate
@@ -92,9 +92,9 @@ function readCount(argv, name) {
   if (!Number.isFinite(n) || n < 0) throw new Error(`${name} expects a non-negative number, got "${raw}"`);
   return Math.floor(n);
 }
-function readRunIdFromFile(path) {
+function readRunIdFromFile(path4) {
   try {
-    const parsed = JSON.parse(fs.readFileSync(path, "utf-8"));
+    const parsed = JSON.parse(fs.readFileSync(path4, "utf-8"));
     const runId = Number(parsed.runId);
     return Number.isFinite(runId) && runId > 0 ? runId : null;
   } catch {
@@ -168,32 +168,675 @@ async function runGate(argv, env = process.env) {
   return result.passed ? EXIT_OK : EXIT_VIOLATED;
 }
 
-// src/cli/index.ts
+// src/cli/init.ts
+var fs4 = __toESM(require("fs"));
+var path3 = __toESM(require("path"));
+var import_node_child_process = require("child_process");
+
+// src/cli/report.ts
+var STATUS_MARK = {
+  created: "+",
+  updated: "~",
+  already: "=",
+  manual: "!",
+  skipped: "-",
+  error: "x"
+};
+function formatStep(result) {
+  const where = result.file ? ` ${result.file}` : "";
+  return `  ${STATUS_MARK[result.status]} [${result.status}] ${result.step}${where} \u2014 ${result.detail}`;
+}
+
+// src/cli/detect.ts
+var fs2 = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var CONFIG_NAMES = [
+  "playwright.config.ts",
+  "playwright.config.mts",
+  "playwright.config.cts",
+  "playwright.config.js",
+  "playwright.config.mjs",
+  "playwright.config.cjs"
+];
+var LOCKFILES = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lockb", "bun"],
+  ["bun.lock", "bun"],
+  ["package-lock.json", "npm"]
+];
+var REPORTER_PACKAGE = "@piwitests/reporter";
+function readPackageJson(root) {
+  const pkgPath = path.join(root, "package.json");
+  try {
+    return { pkg: JSON.parse(fs2.readFileSync(pkgPath, "utf-8")), pkgPath };
+  } catch {
+    return { pkg: null, pkgPath: null };
+  }
+}
+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;
+  }
+  return "npm";
+}
+function findConfig(root) {
+  for (const name of CONFIG_NAMES) {
+    const candidate = path.join(root, name);
+    if (fs2.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+function langOf(configPath) {
+  if (!configPath) return "ts";
+  return /\.[cm]?js$/.test(configPath) ? "js" : "ts";
+}
+function suggestProjectName(root, pkg) {
+  const fromPkg = pkg?.name?.replace(/^@[^/]+\//, "").trim();
+  return fromPkg || path.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 { pkg, pkgPath } = readPackageJson(absRoot);
+  const configPath = findConfig(absRoot);
+  return {
+    root: absRoot,
+    packageJson: pkg,
+    packageJsonPath: pkgPath,
+    packageManager: detectPackageManager(absRoot, pkg),
+    configPath,
+    configLang: langOf(configPath),
+    reporterInstalled: hasReporter(pkg),
+    suggestedProjectName: suggestProjectName(absRoot, pkg)
+  };
+}
+function installCommand(manager) {
+  switch (manager) {
+    case "pnpm":
+      return `pnpm add -D ${REPORTER_PACKAGE}`;
+    case "yarn":
+      return `yarn add -D ${REPORTER_PACKAGE}`;
+    case "bun":
+      return `bun add -d ${REPORTER_PACKAGE}`;
+    case "npm":
+      return `npm install --save-dev ${REPORTER_PACKAGE}`;
+  }
+}
+
+// src/cli/configure.ts
+var REPORTER_IMPORT = "import { wrapConfig } from '@piwitests/reporter'";
+var MANUAL_HINT = "Could not find `export default defineConfig(...)`. Wrap your exported config by hand: import { wrapConfig } from '@piwitests/reporter', then export default wrapConfig(defineConfig({ ... }), { serverUrl, projectName }).";
+function quote(value) {
+  return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+function matchClosingParen(src, openIndex) {
+  let depth = 0;
+  let quoteChar = null;
+  for (let i = openIndex; i < src.length; i++) {
+    const c = src[i];
+    if (quoteChar) {
+      if (c === quoteChar && src[i - 1] !== "\\") quoteChar = null;
+      continue;
+    }
+    if (c === "/" && src[i + 1] === "/") {
+      const nl = src.indexOf("\n", i);
+      if (nl === -1) return -1;
+      i = nl;
+      continue;
+    }
+    if (c === "/" && src[i + 1] === "*") {
+      const end = src.indexOf("*/", i + 2);
+      if (end === -1) return -1;
+      i = end + 1;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      quoteChar = c;
+      continue;
+    }
+    if (c === "(") depth++;
+    else if (c === ")") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+function optionsLiteral(opts) {
+  const lines = [];
+  if (opts.serverUrl) lines.push(`    serverUrl: ${quote(opts.serverUrl)},`);
+  lines.push(`    projectName: ${quote(opts.projectName)},`);
+  return `{
+${lines.join("\n")}
+  }`;
+}
+function withReporterImport(head) {
+  const importLine = /^import\b.*$/gm;
+  let insertAt = -1;
+  let match;
+  while (match = importLine.exec(head)) {
+    const line = match[0];
+    const complete = /from\s*['"][^'"]+['"]\s*;?\s*$/.test(line) || /^import\s+['"][^'"]+['"]\s*;?\s*$/.test(line);
+    if (complete) insertAt = match.index + line.length;
+  }
+  if (insertAt === -1) return `${REPORTER_IMPORT}
+${head}`;
+  return `${head.slice(0, insertAt)}
+${REPORTER_IMPORT}${head.slice(insertAt)}`;
+}
+function wrapPlaywrightConfig(source, opts) {
+  if (/@piwitests\/reporter/.test(source)) {
+    return { text: source, status: "already", detail: "Piwi reporter is already wired into the config" };
+  }
+  const match = /export\s+default\s+defineConfig\s*\(/.exec(source);
+  if (!match) return { text: source, status: "manual", detail: MANUAL_HINT };
+  const openParen = match.index + match[0].length - 1;
+  const closeParen = matchClosingParen(source, openParen);
+  const callStart = source.indexOf("defineConfig", match.index);
+  if (closeParen === -1 || callStart === -1) return { text: source, status: "manual", detail: MANUAL_HINT };
+  const callExpr = source.slice(callStart, closeParen + 1);
+  let before = withReporterImport(source.slice(0, match.index));
+  const after = source.slice(closeParen + 1);
+  if (before.length && !before.endsWith("\n")) before += "\n";
+  const wrapped = `export default wrapConfig(
+  ${callExpr},
+  ${optionsLiteral(opts)},
+)`;
+  const text = `${before}${wrapped}${after}`;
+  return { text, status: "updated", detail: "Wrapped defineConfig(...) with wrapConfig(...) and added the import" };
+}
+function fixturesContents() {
+  return [
+    "import { test as base, expect } from '@playwright/test'",
+    "import { piwiFixtures } from '@piwitests/reporter'",
+    "",
+    "export const test = base.extend(piwiFixtures)",
+    "export { expect }",
+    ""
+  ].join("\n");
+}
+function upsertEnvKeys(existing, entries) {
+  let text = existing;
+  const added = [];
+  for (const [key, value] of entries) {
+    if (new RegExp(`^\\s*${key}=`, "m").test(text)) continue;
+    if (text.length && !text.endsWith("\n")) text += "\n";
+    text += `${key}=${value}
+`;
+    added.push(key);
+  }
+  return { text, added };
+}
+function ensureGitignoreEntry(existing, entry = ".env") {
+  const present = existing.split(/\r?\n/).some((line) => line.trim() === entry);
+  if (present) return { text: existing, added: false };
+  let text = existing;
+  if (text.length && !text.endsWith("\n")) text += "\n";
+  text += `${entry}
+`;
+  return { text, added: true };
+}
+
+// src/cli/skills.ts
+var fs3 = __toESM(require("fs"));
+var path2 = __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");
+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 (parent === dir) break;
+    dir = parent;
+  }
+  return path2.resolve(fromDir, "..", "..", "templates");
+}
+function readFrontMatter(markdown) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(markdown);
+  if (!match) return {};
+  const out = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = /^(name|description):\s*(.*)$/.exec(line);
+    if (kv) out[kv[1]] = kv[2].trim().replace(/^['"]|['"]$/g, "");
+  }
+  return out;
+}
+function templatePath(templatesDir, slug) {
+  return path2.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"));
+    infos.push({ slug, name: front.name ?? slug, description: front.description ?? "" });
+  }
+  return infos;
+}
+function installSkills(opts) {
+  const results = [];
+  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)) {
+      results.push({ step, status: "error", detail: `no template found for "${slug}"` });
+      continue;
+    }
+    const contents = fs3.readFileSync(source, "utf-8");
+    const exists = fs3.existsSync(dest);
+    if (exists && !opts.force) {
+      const identical = fs3.readFileSync(dest, "utf-8") === contents;
+      results.push({
+        step,
+        file: relDest,
+        status: identical ? "already" : "skipped",
+        detail: identical ? "skill already installed" : "skill exists and differs \u2014 pass --force to overwrite"
+      });
+      continue;
+    }
+    if (!opts.dryRun) {
+      fs3.mkdirSync(path2.dirname(dest), { recursive: true });
+      fs3.writeFileSync(dest, contents);
+    }
+    results.push({ step, file: relDest, status: exists ? "updated" : "created", detail: "installed skill" });
+  }
+  return results;
+}
 var USAGE2 = `
+piwi skills \u2014 install the Piwi agent skills into this project
+
+Usage:
+  npx @piwitests/reporter skills list
+  npx @piwitests/reporter skills add [names...] [options]
+
+Commands:
+  list              Show the available skills and what each one is for
+  add [names...]    Install the named skills (default: all of them)
+
+Options for "add":
+  --dir <path>      Directory to install into (default: ${DEFAULT_SKILLS_DIR})
+  --cwd <path>      Project root to operate on (default: current directory)
+  --force           Overwrite a skill file that already exists
+  --dry-run         Report what would be written without writing
+  --json            Print the results as JSON
+
+Skills: ${ALL_SKILLS.join(", ")}
+`.trim();
+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);
+  if (index === -1) return void 0;
+  const value = argv[index + 1];
+  return value && !value.startsWith("--") ? value : void 0;
+}
+function positionalSlugs(argv) {
+  const slugs = [];
+  for (const arg of argv) {
+    if (arg.startsWith("--")) break;
+    slugs.push(arg);
+  }
+  return slugs;
+}
+function runSkills(argv, templatesDir, cwd = process.cwd()) {
+  const [sub, ...rest] = argv;
+  if (sub === void 0 || sub === "-h" || sub === "--help") {
+    console.log(USAGE2);
+    return 0;
+  }
+  if (sub === "list") {
+    const infos = listSkills(templatesDir);
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(infos, null, 2));
+    } else {
+      console.log("Available Piwi skills:\n");
+      for (const info of infos) console.log(`  ${info.slug}
+    ${info.description}
+`);
+    }
+    return 0;
+  }
+  if (sub === "add") {
+    const requested = positionalSlugs(rest);
+    const unknown = requested.filter((slug) => !ALL_SKILLS.includes(slug));
+    if (unknown.length) {
+      console.error(`piwi skills: unknown skill(s): ${unknown.join(", ")}
+`);
+      console.error(USAGE2);
+      return 2;
+    }
+    const results = installSkills({
+      templatesDir,
+      root: path2.resolve(readOption2(rest, "--cwd") ?? cwd),
+      skillsDir: readOption2(rest, "--dir") ?? DEFAULT_SKILLS_DIR,
+      slugs: requested.length ? requested : ALL_SKILLS,
+      force: rest.includes("--force"),
+      dryRun: rest.includes("--dry-run")
+    });
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(results, null, 2));
+    } else {
+      for (const result of results)
+        console.log(`  [${result.status}] ${result.file ?? result.step} \u2014 ${result.detail}`);
+    }
+    return results.some((r) => r.status === "error") ? 2 : 0;
+  }
+  console.error(`piwi skills: unknown command "${sub}"
+`);
+  console.error(USAGE2);
+  return 2;
+}
+
+// src/cli/init.ts
+var DEFAULT_SERVER_URL = "http://localhost:3000";
+var USAGE3 = `
+piwi init \u2014 wire a Playwright project up to a Piwi Dashboard
+
+Usage:
+  npx @piwitests/reporter init [options]
+
+What it does (each step is idempotent and safe to re-run):
+  - installs @piwitests/reporter as a dev dependency
+  - wraps export default defineConfig(...) with wrapConfig(...)
+  - creates the capture-fixtures file (tests/fixtures.ts)
+  - records PIWI_* connection settings in .env / .env.example and .gitignore
+  - installs the Piwi agent skills so your coding agent can use them
+
+Options:
+  --server-url <url>   Dashboard URL to write into the config (env PIWI_DASHBOARD_URL,
+                       default ${DEFAULT_SERVER_URL})
+  --project <name>     Project name to report under (default: your package/folder name)
+  --api-key <key>      API key to write into .env (env PIWI_API_KEY). Omit to keep it a
+                       .env.example placeholder you fill in yourself.
+  --cwd <path>         Project root to operate on (default: current directory)
+  --skills <list>      Comma-separated skills to install, or "all" / "none"
+                       (default: ${WORKFLOW_SKILLS.join(", ")})
+  --skills-dir <path>  Directory to install skills into (default: ${DEFAULT_SKILLS_DIR})
+  --skills-only        Only install skills; do not touch the config or env
+  --no-skills          Configure the project but install no skills
+  --no-install         Do not run the package manager; record the dependency only
+  --force              Overwrite skill files that already exist
+  --dry-run            Report every change without writing anything
+  --json               Print the plan/result as JSON (for agents)
+  -h, --help           Show this help
+
+Skills: ${ALL_SKILLS.join(", ")}
+`.trim();
+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);
+  if (index === -1) return void 0;
+  const value = argv[index + 1];
+  return value && !value.startsWith("--") ? value : void 0;
+}
+function resolveSkillSlugs(raw) {
+  if (raw === void 0) return WORKFLOW_SKILLS;
+  const trimmed = raw.trim().toLowerCase();
+  if (trimmed === "none") return [];
+  if (trimmed === "all") return ALL_SKILLS;
+  return raw.split(",").map((slug) => slug.trim()).filter(Boolean);
+}
+function parseInitArgs(argv, env, cwd) {
+  const root = path3.resolve(readOption3(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")),
+    install: !argv.includes("--no-install"),
+    force: argv.includes("--force"),
+    dryRun: argv.includes("--dry-run"),
+    json: argv.includes("--json"),
+    skillsOnly: argv.includes("--skills-only"),
+    noSkills: argv.includes("--no-skills")
+  };
+}
+function readFileOr(file, fallback) {
+  try {
+    return fs4.readFileSync(file, "utf-8");
+  } catch {
+    return fallback;
+  }
+}
+function installArgv(manager) {
+  switch (manager) {
+    case "pnpm":
+      return ["pnpm", ["add", "-D", REPORTER_PACKAGE]];
+    case "yarn":
+      return ["yarn", ["add", "-D", REPORTER_PACKAGE]];
+    case "bun":
+      return ["bun", ["add", "-d", REPORTER_PACKAGE]];
+    case "npm":
+      return ["npm", ["install", "--save-dev", REPORTER_PACKAGE]];
+  }
+}
+function stepInstallReporter(project, opts) {
+  const step = "dependency";
+  if (project.reporterInstalled)
+    return { step, status: "already", detail: `${REPORTER_PACKAGE} is already a dependency` };
+  if (!project.packageJson)
+    return {
+      step,
+      status: "manual",
+      detail: `No package.json here \u2014 run \`npm init\`, then \`${installCommand(project.packageManager)}\``
+    };
+  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" });
+  if (result.status === 0) return { step, status: "updated", detail: `Installed ${REPORTER_PACKAGE}` };
+  return {
+    step,
+    status: "error",
+    detail: `\`${installCommand(project.packageManager)}\` failed (exit ${result.status ?? "unknown"}) \u2014 install it by hand`
+  };
+}
+function stepConfig(project, opts) {
+  const step = "config";
+  if (!project.configPath)
+    return {
+      step,
+      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 edit = wrapPlaywrightConfig(readFileOr(project.configPath, ""), {
+    serverUrl: opts.serverUrl,
+    projectName: opts.projectName
+  });
+  if (edit.status === "updated" && !opts.dryRun) fs4.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 current = readFileOr(dest, "");
+    if (/piwiFixtures/.test(current))
+      return { step, file: rel, status: "already", detail: "capture fixtures already set up" };
+    return {
+      step,
+      file: rel,
+      status: "manual",
+      detail: "A fixtures file exists \u2014 extend it: `import { piwiFixtures } from '@piwitests/reporter'` and `base.extend(piwiFixtures)`"
+    };
+  }
+  if (!opts.dryRun) {
+    fs4.mkdirSync(path3.dirname(dest), { recursive: true });
+    fs4.writeFileSync(dest, fixturesContents());
+  }
+  return {
+    step,
+    file: rel,
+    status: "created",
+    detail: "Created capture fixtures \u2014 import `test` from here in your specs"
+  };
+}
+function stepEnv(project, opts) {
+  const results = [];
+  const examplePath = path3.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);
+  results.push({
+    step: "env",
+    file: ".env.example",
+    status: example.added.length ? "updated" : "already",
+    detail: example.added.length ? `Recorded ${example.added.join(", ")}` : "connection template already present"
+  });
+  if (opts.apiKey) {
+    const envPath = path3.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);
+    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 gitignore = ensureGitignoreEntry(readFileOr(gitignorePath, ""));
+    if (gitignore.added && !opts.dryRun) fs4.writeFileSync(gitignorePath, gitignore.text);
+    results.push({
+      step: "gitignore",
+      file: ".gitignore",
+      status: gitignore.added ? "updated" : "already",
+      detail: gitignore.added ? "Added .env" : ".env already ignored"
+    });
+  }
+  return results;
+}
+function nextSteps(opts, steps) {
+  const out = [];
+  if (!opts.apiKey) {
+    out.push(
+      "If your dashboard has authentication on, create an API key (Settings \u2192 Users \u2192 API keys), put it in .env as PIWI_API_KEY, and keep .env out of git."
+    );
+  }
+  if (steps.some((s) => s.status === "manual")) {
+    out.push("Finish the steps marked [manual] above \u2014 each one carries the exact change to make.");
+  }
+  out.push("In your specs, import `test` (and `expect`) from your fixtures file instead of `@playwright/test`.");
+  out.push(`Run \`npx playwright test\` \u2014 the run should appear at ${opts.serverUrl}.`);
+  out.push(
+    "For a machine-readable check, set PIWI_OUTPUT_FILE=piwi-run.json and read runUrl from that file after the run."
+  );
+  return out;
+}
+async function runInit(argv, env = process.env, cwd = process.cwd()) {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    console.log(USAGE3);
+    return 0;
+  }
+  const opts = parseInitArgs(argv, env, cwd);
+  const project = detectProject(opts.root);
+  const steps = [];
+  if (!opts.skillsOnly) {
+    steps.push(stepInstallReporter(project, opts));
+    steps.push(stepConfig(project, opts));
+    steps.push(stepFixtures(project, opts));
+    steps.push(...stepEnv(project, opts));
+  }
+  if (!opts.noSkills && opts.skillSlugs.length) {
+    steps.push(
+      ...installSkills({
+        templatesDir: findTemplatesDir(__dirname),
+        root: opts.root,
+        skillsDir: opts.skillsDir,
+        slugs: opts.skillSlugs,
+        force: opts.force,
+        dryRun: opts.dryRun
+      })
+    );
+  }
+  const guidance = nextSteps(opts, steps);
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          dryRun: opts.dryRun,
+          project: {
+            root: project.root,
+            packageManager: project.packageManager,
+            configPath: project.configPath ? path3.relative(project.root, project.configPath) : null,
+            projectName: opts.projectName,
+            serverUrl: opts.serverUrl
+          },
+          steps,
+          nextSteps: guidance
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.log(`
+Piwi setup${opts.dryRun ? " (dry run \u2014 nothing written)" : ""} for "${opts.projectName}":
+`);
+    for (const step of steps) console.log(formatStep(step));
+    console.log("\nNext:");
+    for (const line of guidance) console.log(`  \u2022 ${line}`);
+    console.log("");
+  }
+  return steps.some((s) => s.status === "error") ? 1 : 0;
+}
+
+// src/cli/index.ts
+var USAGE4 = `
 piwi \u2014 companion commands for the Piwi Dashboard reporter
 
 Usage:
-  npx piwi <command> [options]
+  npx @piwitests/reporter <command> [options]
 
 Commands:
-  gate    Fail a CI job on the dashboard's analysis of a run
+  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
 
-Run \`npx piwi gate --help\` for that command's options.
+Run \`npx @piwitests/reporter <command> --help\` for a command's options.
+(The published package is @piwitests/reporter; its command is piwi. Invoke it
+through the package name so npx resolves this package, not an unrelated "piwi".)
 `.trim();
 async function main() {
   const [command, ...rest] = process.argv.slice(2);
   switch (command) {
+    case "init":
+      return runInit(rest);
+    case "skills":
+      return runSkills(rest, findTemplatesDir(__dirname));
     case "gate":
       return runGate(rest);
     case void 0:
     case "-h":
     case "--help":
-      console.log(USAGE2);
+      console.log(USAGE4);
       return 0;
     default:
       console.error(`piwi: unknown command "${command}"
 `);
-      console.error(USAGE2);
+      console.error(USAGE4);
       return 2;
   }
 }