@mhosaic/feedback-cli 0.20.0 → 0.22.0

package/dist/sitemap-vue-EJDQTCYM.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+import {
+  buildSitemap
+} from "./chunk-AZQSQJNQ.js";
+import {
+  loadQaConfig
+} from "./chunk-IHJPCMYF.js";
+
+// src/qa/sitemap-vue.ts
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { dirname, isAbsolute, join, resolve } from "path";
+import vm from "vm";
+import ts from "typescript";
+var STUB = new Proxy(function stub() {
+}, {
+  get: (_t, prop) => prop === Symbol.toPrimitive || prop === Symbol.toStringTag ? () => "" : STUB,
+  apply: () => STUB,
+  construct: () => ({})
+});
+function isStub(v) {
+  return v === STUB;
+}
+function transpileToCjs(source, fileName) {
+  return ts.transpileModule(source, {
+    fileName,
+    compilerOptions: {
+      module: ts.ModuleKind.CommonJS,
+      target: ts.ScriptTarget.ES2020,
+      esModuleInterop: true,
+      isolatedModules: true
+    }
+  }).outputText;
+}
+function resolveInTree(specifier, fromDir, alias, confineDir) {
+  if (/\.(vue|json|css|scss|sass|less|svg|png|jpe?g|gif|webp|woff2?|ttf)$/i.test(specifier)) {
+    return null;
+  }
+  let base = null;
+  if (specifier.startsWith("./") || specifier.startsWith("../")) {
+    base = resolve(fromDir, specifier);
+  } else if (alias) {
+    for (const [key, target] of Object.entries(alias)) {
+      if (specifier === key || specifier.startsWith(`${key}/`)) {
+        const rest = specifier === key ? "" : specifier.slice(key.length + 1);
+        base = rest ? join(target, rest) : target;
+        break;
+      }
+    }
+  }
+  if (base === null) return null;
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.mjs`,
+    `${base}.js`,
+    join(base, "index.ts"),
+    join(base, "index.mjs"),
+    join(base, "index.js")
+  ];
+  for (const cand of candidates) {
+    try {
+      if (existsSync(cand) && statSync(cand).isFile()) {
+        return isWithin(confineDir, cand) ? cand : null;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function isWithin(dir, child) {
+  const d = resolve(dir);
+  const c = resolve(child);
+  return c === d || c.startsWith(d.endsWith("/") ? d : `${d}/`);
+}
+function evaluateModule(absPath, alias, cache, confineDir) {
+  const cached = cache.get(absPath);
+  if (cached) return cached;
+  const moduleObj = { exports: {} };
+  cache.set(absPath, moduleObj.exports);
+  const source = readFileSync(absPath, "utf8");
+  const cjs = transpileToCjs(source, absPath);
+  const fromDir = dirname(absPath);
+  const requireFn = (specifier) => {
+    const resolved = resolveInTree(specifier, fromDir, alias, confineDir);
+    if (resolved) {
+      const exp = evaluateModule(resolved, alias, cache, confineDir);
+      return cache.get(resolved) ?? exp;
+    }
+    return STUB;
+  };
+  const context = vm.createContext({
+    module: moduleObj,
+    exports: moduleObj.exports,
+    require: requireFn,
+    console
+  });
+  vm.runInContext(cjs, context, { filename: absPath });
+  cache.set(absPath, moduleObj.exports);
+  return moduleObj.exports;
+}
+function findEntry(dir) {
+  for (const name of ["index.ts", "index.mjs", "index.js"]) {
+    const p = join(dir, name);
+    if (existsSync(p) && statSync(p).isFile()) return p;
+  }
+  const cache = /* @__PURE__ */ new Map();
+  for (const file of routerFiles(dir)) {
+    try {
+      const ns = evaluateModule(file, void 0, cache, dir);
+      if (pickRoutes(ns)) return file;
+    } catch {
+    }
+  }
+  return null;
+}
+function routerFiles(dir) {
+  const out = [];
+  const walk = (d) => {
+    let entries;
+    try {
+      entries = readdirSync(d, { withFileTypes: true, encoding: "utf8" });
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = join(d, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (/\.(ts|mjs|js)$/.test(entry.name)) {
+        out.push(full);
+      }
+    }
+  };
+  walk(dir);
+  return out;
+}
+function pickRoutes(ns) {
+  if (Array.isArray(ns.routes)) return ns.routes;
+  if (Array.isArray(ns.default)) return ns.default;
+  return null;
+}
+function flattenAndCheck(raw, warnings) {
+  const out = [];
+  for (const entry of raw) {
+    if (Array.isArray(entry)) {
+      out.push(...flattenAndCheck(entry, warnings));
+      continue;
+    }
+    if (isStub(entry)) {
+      warnings.push(
+        "a top-level route entry resolved to a STUB (an import could not be followed in-tree) \u2014 its subtree is missing from the sitemap"
+      );
+      continue;
+    }
+    if (entry === null || typeof entry !== "object") {
+      warnings.push(
+        `a top-level route entry is not a route object (got ${entry === null ? "null" : typeof entry}) \u2014 skipped`
+      );
+      continue;
+    }
+    out.push(entry);
+  }
+  return out;
+}
+function makeTitleFor(titlesFrom) {
+  if (!titlesFrom || !existsSync(titlesFrom)) return void 0;
+  let messages = {};
+  try {
+    const parsed = JSON.parse(readFileSync(titlesFrom, "utf8"));
+    if (parsed && typeof parsed === "object") messages = parsed;
+  } catch {
+    return void 0;
+  }
+  const pages = messages.pages && typeof messages.pages === "object" ? messages.pages : messages;
+  return (routeName) => {
+    if (!routeName) return void 0;
+    const v = pages[routeName];
+    return typeof v === "string" ? v : void 0;
+  };
+}
+function extractWithWarnings(opts) {
+  const warnings = [];
+  const dir = isAbsolute(opts.routerDir) ? opts.routerDir : resolve(opts.routerDir);
+  const entry = findEntry(dir);
+  let rawRoutes = null;
+  if (!entry) {
+    warnings.push(`No router entry (index.{ts,mjs,js}) found under ${dir}`);
+  } else {
+    try {
+      const cache = /* @__PURE__ */ new Map();
+      const ns = evaluateModule(entry, opts.alias, cache, dir);
+      rawRoutes = pickRoutes(ns);
+      if (!rawRoutes) {
+        warnings.push(`No \`routes\` export found in ${entry}`);
+      }
+    } catch (err) {
+      warnings.push(`${entry}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  const routes = rawRoutes ? flattenAndCheck(rawRoutes, warnings) : [];
+  const titleFor = makeTitleFor(opts.titlesFrom);
+  const payload = buildSitemap(routes, titleFor ? { titleFor } : {});
+  return { payload, warnings };
+}
+function extractVueRouterSitemap(opts) {
+  return extractWithWarnings(opts).payload;
+}
+async function runSitemap(_args) {
+  const cfg = loadQaConfig(process.cwd());
+  if (!cfg.sitemap || cfg.sitemap.framework !== "vue-router") {
+    process.stderr.write(
+      'qa sitemap: config.sitemap.framework must be "vue-router". Add a `sitemap` block with `framework: "vue-router"`, `routerDir`, and `file` to qa-meter.config.json.\n'
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (!cfg.sitemap.routerDir) {
+    process.stderr.write("qa sitemap: config.sitemap.routerDir is required for the vue-router adapter.\n");
+    process.exitCode = 1;
+    return;
+  }
+  const { payload, warnings } = extractWithWarnings({
+    routerDir: cfg.sitemap.routerDir,
+    ...cfg.sitemap.titlesFrom ? { titlesFrom: cfg.sitemap.titlesFrom } : {},
+    ...cfg.sitemap.alias ? { alias: cfg.sitemap.alias } : {}
+  });
+  const outFile = cfg.sitemap.file;
+  mkdirSync(dirname(outFile), { recursive: true });
+  writeFileSync(outFile, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+  process.stderr.write(`qa sitemap \u2192 ${outFile} (${payload.pages.length} pages)
+`);
+  for (const warning of warnings) {
+    process.stderr.write(`  warning: ${warning}
+`);
+  }
+}
+export {
+  extractVueRouterSitemap,
+  extractWithWarnings,
+  runSitemap
+};
+//# sourceMappingURL=sitemap-vue-EJDQTCYM.js.map

package/dist/sitemap-vue-EJDQTCYM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/qa/sitemap-vue.ts"],"sourcesContent":["/**\n * vue-router adapter for `qa sitemap` (Track A3, generalized from the Vigilance\n * donor `scripts/sync-sitemap.mjs`).\n *\n * Statically evaluates the router declaration files (`routes` export) without\n * booting the app, real `.vue`/store imports, or dev deps (`vite-node`/`tsx`).\n *\n * How: each source file is transpiled ESM/TS → CommonJS with `ts.transpileModule`\n * (the real TS compiler — handles default/named/re-exports, casts, multi-line\n * imports, every syntax for free), then evaluated in a `node:vm` context with a\n * `module`/`exports` sandbox and a custom `require`. The custom require:\n *   1. resolves IN-TREE relative/aliased imports (`./x`, `../x`, `@/x`) to a real\n *      file under the router tree and evaluates THAT module recursively (cached by\n *      absolute path; cycles return the in-progress `exports`), so sibling route\n *      modules contribute their REAL exported arrays — embedded + spread survive;\n *   2. returns a harmless callable STUB Proxy for everything else (`.vue`\n *      components, `vue-router`, unresolved aliases, bare/node_modules specifiers)\n *      so `component:`/library references never explode.\n *\n * The honesty pass then scans the resolved `routes` tree: any top-level entry that\n * resolved to a STUB (a silently-truncated subtree) is surfaced as a warning.\n */\nimport { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'\nimport { dirname, isAbsolute, join, resolve } from 'node:path'\nimport vm from 'node:vm'\nimport ts from 'typescript'\nimport { buildSitemap, type RawRoute, type SitemapPayload } from './sitemap-core'\nimport { loadQaConfig } from './config'\n\nexport interface VueRouterAdapterOptions {\n  /** Directory holding the router declaration file(s). Absolute. */\n  routerDir: string\n  /** Optional locale/title JSON; `pages.<routeName>` keys resolve human titles. Absolute. */\n  titlesFrom?: string\n  /**\n   * Optional import-alias map (e.g. `{ '@': '/abs/path/to/src' }`). When a\n   * specifier starts with an alias key + '/', it resolves to the mapped absolute\n   * base before the in-tree check. Default: none (so `@/…` falls through to the\n   * stub).\n   */\n  alias?: Record<string, string>\n}\n\n/**\n * Replacement value for any non-relevant import (`.vue` components, stores,\n * enums, `vue-router`, lodash…). Callable, constructable, indexable — and never\n * actually read by the builder, which only walks `path`/`name`/`children`.\n * Lifted verbatim from the donor.\n */\nconst STUB: unknown = new Proxy(function stub() {}, {\n  get: (_t, prop) => (prop === Symbol.toPrimitive || prop === Symbol.toStringTag ? () => '' : STUB),\n  apply: () => STUB,\n  construct: () => ({}),\n})\n\n/** True if `v` is the shared STUB Proxy. */\nfunction isStub(v: unknown): boolean {\n  return v === STUB\n}\n\n/** Transpile one TS/ESM source to CommonJS via the real compiler (no type-check). */\nfunction transpileToCjs(source: string, fileName: string): string {\n  return ts.transpileModule(source, {\n    fileName,\n    compilerOptions: {\n      module: ts.ModuleKind.CommonJS,\n      target: ts.ScriptTarget.ES2020,\n      esModuleInterop: true,\n      isolatedModules: true,\n    },\n  }).outputText\n}\n\n/**\n * Resolve an import specifier to an absolute file UNDER the router tree, or null\n * if it is out-of-tree / unresolvable (→ caller stubs it).\n *\n *  - relative `./x`, `../x` → resolved against the importing file's dir;\n *  - aliased `@/x` (when `alias` maps `@`) → resolved against the mapped base;\n *  - bare / node_modules / `.vue` / unmapped alias → null.\n *\n * Candidate extensions tried in order: as-is, `.ts`, `.mjs`, `.js`, `/index.ts`,\n * `/index.mjs`, `/index.js`. `.vue` and non-JS/TS asset specifiers (`.json`,\n * `.css`, images, …) are always treated as out-of-tree: the evaluator only\n * transpiles JS/TS, so feeding it raw JSON crashes `ts.transpileModule`\n * (\"Output generation failed\"). Routes never depend on such assets\n * structurally, so stubbing them is the honest, lossless choice.\n */\nfunction resolveInTree(\n  specifier: string,\n  fromDir: string,\n  alias: Record<string, string> | undefined,\n  confineDir: string,\n): string | null {\n  if (/\\.(vue|json|css|scss|sass|less|svg|png|jpe?g|gif|webp|woff2?|ttf)$/i.test(specifier)) {\n    return null\n  }\n\n  let base: string | null = null\n  if (specifier.startsWith('./') || specifier.startsWith('../')) {\n    base = resolve(fromDir, specifier)\n  } else if (alias) {\n    for (const [key, target] of Object.entries(alias)) {\n      if (specifier === key || specifier.startsWith(`${key}/`)) {\n        const rest = specifier === key ? '' : specifier.slice(key.length + 1)\n        base = rest ? join(target, rest) : target\n        break\n      }\n    }\n  }\n  if (base === null) return null\n\n  const candidates = [\n    base,\n    `${base}.ts`,\n    `${base}.mjs`,\n    `${base}.js`,\n    join(base, 'index.ts'),\n    join(base, 'index.mjs'),\n    join(base, 'index.js'),\n  ]\n  for (const cand of candidates) {\n    try {\n      if (existsSync(cand) && statSync(cand).isFile()) {\n        // Confine the follow to the router subtree. Alias maps (`@`) point at\n        // the WHOLE `src` tree, so without this an `@/stores/…` or `@/plugins/…`\n        // import in a route module would drag the adapter into the app graph —\n        // Vite-only code (`import.meta`), real stores, services — that crashes\n        // the vm sandbox and is irrelevant to route SHAPE. Route MODULES live\n        // under routerDir; everything else (components, stores, models) is a\n        // leaf reference the builder never reads, so stubbing it is lossless.\n        return isWithin(confineDir, cand) ? cand : null\n      }\n    } catch {\n      // ignore and try the next candidate\n    }\n  }\n  return null\n}\n\n/** True if absolute `child` is `dir` itself or nested under it (path-segment safe). */\nfunction isWithin(dir: string, child: string): boolean {\n  const d = resolve(dir)\n  const c = resolve(child)\n  return c === d || c.startsWith(d.endsWith('/') ? d : `${d}/`)\n}\n\n/**\n * Evaluate a CommonJS-shaped module in a `vm` context, recursively following\n * in-tree `require`s. `cache` keys by absolute path; a module already in-flight\n * (cycle) returns its in-progress `exports`.\n */\nfunction evaluateModule(\n  absPath: string,\n  alias: Record<string, string> | undefined,\n  cache: Map<string, Record<string, unknown>>,\n  confineDir: string,\n): Record<string, unknown> {\n  const cached = cache.get(absPath)\n  if (cached) return cached\n\n  const moduleObj: { exports: Record<string, unknown> } = { exports: {} }\n  // Register BEFORE evaluating so a cycle resolves to the in-progress exports.\n  cache.set(absPath, moduleObj.exports)\n\n  const source = readFileSync(absPath, 'utf8')\n  const cjs = transpileToCjs(source, absPath)\n  const fromDir = dirname(absPath)\n\n  const requireFn = (specifier: string): unknown => {\n    const resolved = resolveInTree(specifier, fromDir, alias, confineDir)\n    if (resolved) {\n      const exp = evaluateModule(resolved, alias, cache, confineDir)\n      // After evaluating, the module object may have been reassigned\n      // (`module.exports = …`); read the freshest value from cache.\n      return cache.get(resolved) ?? exp\n    }\n    return STUB\n  }\n\n  const context = vm.createContext({\n    module: moduleObj,\n    exports: moduleObj.exports,\n    require: requireFn,\n    console,\n  })\n  vm.runInContext(cjs, context, { filename: absPath })\n\n  // `module.exports = …` may have replaced the object; refresh the cache entry.\n  cache.set(absPath, moduleObj.exports)\n  return moduleObj.exports\n}\n\n/** Locate the router-tree ENTRY file: `<dir>/index.{ts,mjs,js}`, else the first scanned file with a `routes`/`default` array. */\nfunction findEntry(dir: string): string | null {\n  for (const name of ['index.ts', 'index.mjs', 'index.js']) {\n    const p = join(dir, name)\n    if (existsSync(p) && statSync(p).isFile()) return p\n  }\n  // Fallback: scan recursively, return the first file exporting routes.\n  const cache = new Map<string, Record<string, unknown>>()\n  for (const file of routerFiles(dir)) {\n    try {\n      const ns = evaluateModule(file, undefined, cache, dir)\n      if (pickRoutes(ns)) return file\n    } catch {\n      // ignore unreadable candidates during discovery\n    }\n  }\n  return null\n}\n\n/** List candidate router declaration files under `dir` (recursively, sorted). */\nfunction routerFiles(dir: string): string[] {\n  const out: string[] = []\n  const walk = (d: string): void => {\n    let entries: import('node:fs').Dirent[]\n    try {\n      entries = readdirSync(d, { withFileTypes: true, encoding: 'utf8' })\n    } catch {\n      return\n    }\n    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {\n      const full = join(d, entry.name)\n      if (entry.isDirectory()) {\n        walk(full)\n      } else if (/\\.(ts|mjs|js)$/.test(entry.name)) {\n        out.push(full)\n      }\n    }\n  }\n  walk(dir)\n  return out\n}\n\n/** Pull the `routes` array out of an evaluated namespace (named export, then default). */\nfunction pickRoutes(ns: Record<string, unknown>): ReadonlyArray<unknown> | null {\n  if (Array.isArray(ns.routes)) return ns.routes as ReadonlyArray<unknown>\n  if (Array.isArray(ns.default)) return ns.default as ReadonlyArray<unknown>\n  return null\n}\n\n/**\n * Flatten the raw `routes` array: a sibling route MODULE imported as a single\n * embedded element resolves to an ARRAY (`routes: [ adminRoutes, … ]` where\n * `adminRoutes` is `[{…}]`), so we splice nested arrays up one level. Honesty\n * warnings are collected for any top-level entry that is the STUB (a silently\n * truncated import) or otherwise not a plain route object.\n */\nfunction flattenAndCheck(\n  raw: ReadonlyArray<unknown>,\n  warnings: string[],\n): RawRoute[] {\n  const out: RawRoute[] = []\n  for (const entry of raw) {\n    if (Array.isArray(entry)) {\n      // Embedded in-tree route module (its default/named export is an array).\n      out.push(...flattenAndCheck(entry, warnings))\n      continue\n    }\n    if (isStub(entry)) {\n      warnings.push(\n        'a top-level route entry resolved to a STUB (an import could not be ' +\n          'followed in-tree) — its subtree is missing from the sitemap',\n      )\n      continue\n    }\n    if (entry === null || typeof entry !== 'object') {\n      warnings.push(\n        `a top-level route entry is not a route object (got ${entry === null ? 'null' : typeof entry}) — skipped`,\n      )\n      continue\n    }\n    out.push(entry as RawRoute)\n  }\n  return out\n}\n\n/** Build a `titleFor` resolver from a flat `pages.<routeName>` JSON, or undefined. */\nfunction makeTitleFor(\n  titlesFrom: string | undefined,\n): ((routeName: string | undefined, pattern: string) => string | undefined) | undefined {\n  if (!titlesFrom || !existsSync(titlesFrom)) return undefined\n  let messages: Record<string, unknown> = {}\n  try {\n    const parsed = JSON.parse(readFileSync(titlesFrom, 'utf8'))\n    if (parsed && typeof parsed === 'object') messages = parsed as Record<string, unknown>\n  } catch {\n    return undefined\n  }\n  const pages =\n    messages.pages && typeof messages.pages === 'object'\n      ? (messages.pages as Record<string, unknown>)\n      : messages\n  return (routeName) => {\n    if (!routeName) return undefined\n    const v = pages[routeName]\n    return typeof v === 'string' ? v : undefined\n  }\n}\n\n/** Result of a static extraction: the payload plus any honesty/IO warnings. */\ninterface ExtractResult {\n  payload: SitemapPayload\n  warnings: string[]\n}\n\n/**\n * Internal worker that also reports warnings (consumed by `runSitemap`).\n * Exported for tests — the public extractor (`extractVueRouterSitemap`) returns\n * only the `SitemapPayload`; this exposes the honesty warnings alongside it.\n * @internal\n */\nexport function extractWithWarnings(opts: VueRouterAdapterOptions): ExtractResult {\n  const warnings: string[] = []\n  const dir = isAbsolute(opts.routerDir) ? opts.routerDir : resolve(opts.routerDir)\n  const entry = findEntry(dir)\n\n  let rawRoutes: ReadonlyArray<unknown> | null = null\n  if (!entry) {\n    warnings.push(`No router entry (index.{ts,mjs,js}) found under ${dir}`)\n  } else {\n    try {\n      const cache = new Map<string, Record<string, unknown>>()\n      const ns = evaluateModule(entry, opts.alias, cache, dir)\n      rawRoutes = pickRoutes(ns)\n      if (!rawRoutes) {\n        warnings.push(`No \\`routes\\` export found in ${entry}`)\n      }\n    } catch (err) {\n      warnings.push(`${entry}: ${err instanceof Error ? err.message : String(err)}`)\n    }\n  }\n\n  const routes = rawRoutes ? flattenAndCheck(rawRoutes, warnings) : []\n  const titleFor = makeTitleFor(opts.titlesFrom)\n  const payload = buildSitemap(routes, titleFor ? { titleFor } : {})\n  return { payload, warnings }\n}\n\n/**\n * Statically evaluate the vue-router declarations under `routerDir` and return\n * the doc-03 §3.1 sitemap payload. Pure with respect to the inputs (idempotent).\n */\nexport function extractVueRouterSitemap(opts: VueRouterAdapterOptions): SitemapPayload {\n  return extractWithWarnings(opts).payload\n}\n\n/** CLI entry: `qa sitemap` — load config, extract, write pretty JSON, report. */\nexport async function runSitemap(_args: string[]): Promise<void> {\n  const cfg = loadQaConfig(process.cwd())\n  if (!cfg.sitemap || cfg.sitemap.framework !== 'vue-router') {\n    process.stderr.write(\n      'qa sitemap: config.sitemap.framework must be \"vue-router\". ' +\n        'Add a `sitemap` block with `framework: \"vue-router\"`, `routerDir`, and `file` to qa-meter.config.json.\\n',\n    )\n    process.exitCode = 1\n    return\n  }\n  if (!cfg.sitemap.routerDir) {\n    process.stderr.write('qa sitemap: config.sitemap.routerDir is required for the vue-router adapter.\\n')\n    process.exitCode = 1\n    return\n  }\n\n  const { payload, warnings } = extractWithWarnings({\n    routerDir: cfg.sitemap.routerDir,\n    ...(cfg.sitemap.titlesFrom ? { titlesFrom: cfg.sitemap.titlesFrom } : {}),\n    ...(cfg.sitemap.alias ? { alias: cfg.sitemap.alias } : {}),\n  })\n\n  const outFile = cfg.sitemap.file\n  mkdirSync(dirname(outFile), { recursive: true })\n  writeFileSync(outFile, `${JSON.stringify(payload, null, 2)}\\n`, 'utf8')\n\n  process.stderr.write(`qa sitemap → ${outFile} (${payload.pages.length} pages)\\n`)\n  for (const warning of warnings) {\n    process.stderr.write(`  warning: ${warning}\\n`)\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhosaic/feedback-cli",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "CLI to install @mhosaic/feedback into a host app, verify the integration, and drop a guided Claude Code skill (/integrate-feedback) into ~/.claude/skills.",
   "type": "module",
   "bin": {
@@ -13,13 +13,14 @@
   ],
   "dependencies": {
     "kleur": "^4.1.5",
-    "prompts": "^2.4.2"
+    "prompts": "^2.4.2",
+    "typescript": "5.6.3",
+    "yaml": "^2.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",
     "@types/prompts": "^2.4.9",
     "tsup": "^8.3.0",
-    "typescript": "5.6.3",
     "vitest": "^2.1.0"
   },
   "scripts": {

package/skills/integrate-feedback/SKILL.md

@@ -58,6 +58,13 @@ The project's `allowed_origins` doesn't include the URL the request comes from.
 **"Do clients get email digests?"**
 Not by default — notification dispatcher is `NoopDispatcher` on prod. Ping the operator if the client wants the weekly digest (it's a backend env var change).
 
+**"How do I also enable the QA Meter?"**
+The QA Meter is an opt-in second FAB (half size, stacked above the feedback button) that shows test-coverage status. It's host-served and host-gated — no backend involvement. Build the artifact with `mhosaic-feedback qa refresh`, serve `qa-status.json` as a static asset (or from your own endpoint), then enable it per surface:
+- **npm / React provider:** `createFeedback({ …, qaMeter: { source: '/qa-status.json' } })` — `<FeedbackProvider>` forwards the `qaMeter` prop automatically.
+- **CDN / loader embed:** add `data-qa-source="/qa-status.json"` to the `<script>` tag (optional `data-qa-locale`).
+
+Only enable it where you want it (e.g. staging); omit the option in production to ship feedback-only.
+
 **"Where's the human-readable doc?"**
 `docs/INTEGRATING.md` in this repo. Covers the skill, the manual fallback, the CLI command reference, and a troubleshooting matrix.
 

package/skills/integrate-qa-meter/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: integrate-qa-meter
+description: Guided setup for the @mhosaic/feedback QA Meter — the opt-in second FAB (half size, stacked above the feedback button) that shows per-page test-coverage status. Covers detecting the host's Playwright + router setup, scaffolding qa-meter.config.json, running `mhosaic-feedback qa refresh` to build the host-served qa-status.json artifact, serving it as a static asset, enabling it via the qaMeter config (npm / React) or data-qa-source (CDN / loader), wiring it into CI after the e2e run, and troubleshooting. Use whenever the user mentions: the QA Meter, the test-coverage FAB, the second/secondary FAB, qa-status.json, qa-meter.config.json, `qa refresh` / `qa build` / `qa sitemap` / `qa generate` / `qa check`, the sitemap modal, the honesty model, or showing test coverage inside the widget. Both a slash-command runbook and a reference Claude reads to answer ad-hoc QA-Meter questions.
+user-invocable: true
+---
+
+# /integrate-qa-meter — guided QA Meter setup
+
+The **QA Meter** is an opt-in *second FAB* that stacks above the feedback button at half size and shows the current page's test-coverage status: a heartbeat pastille → hover panel (per-page scenarios, with code/bot/human lanes) → full sitemap modal. It's fed by a single static `qa-status.json` the CLI builds from your test suite — **no backend involvement, host-served and host-gated.**
+
+It rides on top of an already-integrated feedback widget: you turn it on by adding a `qaMeter` block to the same `createFeedback(…)` / `<FeedbackProvider>` / embed `<script>` you already wired. So this skill assumes the widget is in. If it isn't, run **`/integrate-feedback` first**, then come back.
+
+This skill is **both** a slash-command runbook AND a reference doc. On `/integrate-qa-meter`, run the procedural flow below. On an ad-hoc question, answer from the Q&A.
+
+---
+
+## Quick Q&A
+
+**"What does the QA Meter need?"**
+Three things: (1) the feedback widget already integrated (the QA Meter is a `qaMeter` option on it), on a build of `@mhosaic/feedback` that ships the second-FAB integration; (2) a `qa-status.json` artifact, built by `mhosaic-feedback qa refresh`; (3) that artifact served as a static file your app already exposes (e.g. `public/qa-status.json`). No backend, no new key, no CORS.
+
+**"Does it need a backend or a project key?"**
+No. Unlike the feedback FAB, the QA Meter is 100% client-side + host-served. It reads a JSON file over plain `fetch`. It uses the *same* `createFeedback` call only as a mounting point.
+
+**"Does it need `identify()`?"**
+No. The feedback FAB is identity-gated (hidden until `identify()` fires); the QA pastille is **not** — it mounts as soon as `qaMeter.source` is set, for anonymous and identified users alike. (It's host-gated instead: you only set the source where you want it.)
+
+**"What does `qa refresh` actually do?"**
+Three deterministic steps, in order: `qa sitemap` (build the page tree from your router — vue-router adapter, or a hand-provided sitemap) → `qa generate` (static analysis of your Playwright specs → per-page scenario suites) → `qa build` (merge suites + sitemap + optional test results into `qa-status.json`). No tests are executed; it reads source files only.
+
+**"Why is my meter all gray / 0% passing?"**
+That's the **honesty model** working: with no Playwright results fed in (`resultsFile: null`), every scenario is `never_run` → gray. Only real evidence turns it green. To get color, run your e2e suite and point `resultsFile` at Playwright's JSON report, then re-run `qa build`. See `references/qa-meter-troubleshooting.md`.
+
+**"What test frameworks / routers are supported?"**
+Spec analysis is **Playwright**-specific. The sitemap adapter ships **vue-router**; for any other router (or no router) you hand-provide a `sitemap.json` (or skip the sitemap for a flat page list). Full matrix in `references/qa-meter-config.md`.
+
+**"Where's the human-readable doc?"**
+`docs/qa-meter/INTEGRATING.md` (this flow, end to end) and `docs/qa-meter/SUITE-FORMAT.md` (the test-suite YAML contract, for hand-authored suites + annotations).
+
+**"Can I run the QA Meter without the feedback widget at all?"**
+Yes, via the standalone subpath `import { createQaMeter } from '@mhosaic/feedback/qa-meter'`, mounted yourself. But the *second-FAB* experience this skill sets up is the `qaMeter` option on the feedback widget — prefer that unless you specifically want QA-only with no feedback button.
+
+---
+
+## Step 0 — Pre-flight
+
+1. **Confirm the widget is integrated.** Grep the host for an existing install: `createFeedback(`, `@mhosaic/feedback`, `FeedbackProvider`, or `embed.min.js` / `data-key`. If none is found, stop and redirect:
+
+   > "The QA Meter is an option on the feedback widget, which isn't integrated here yet. Run `/integrate-feedback` first to wire the widget, then re-run `/integrate-qa-meter`."
+
+2. **Confirm the package build supports it.** The `qaMeter` option exists only on builds of `@mhosaic/feedback` that ship the second-FAB integration. If the host pins an older version, note that it must be bumped (or, for an unreleased build, consume a local `pnpm pack` tarball — see `references/qa-meter-config.md`).
+
+3. **Confirm the CLI is reachable.** `npx @mhosaic/feedback-cli@latest qa` (prints the usage line). A global `npm i -g @mhosaic/feedback-cli@latest` saves typing if you'll run it often / in CI.
+
+Don't continue until the widget is confirmed present.
+
+---
+
+## Step 1 — Detect the project shape
+
+Read enough of the host to fill in the config without guessing. Determine and record:
+
+- **Integration surface** — how `createFeedback` is called: bare npm (`createFeedback({…})`), React (`<FeedbackProvider>`), or CDN/loader (`<script … data-key>`). This decides *where* you add the source in Step 4.
+- **Static-asset dir + its public URL** — where the app serves static files from (`public/`, `static/`, `dist/`…) and what URL a file there resolves to at runtime (usually `/<filename>`). This is the `outFile` target and the `qaMeter.source` value.
+- **E2E layout** — the Playwright root (`e2e/`?), the spec glob (`tests/**/*.spec.ts`), the fixtures file that maps fixture name → page-object class, and the page-objects dir. Check `playwright.config.*` for `testDir`.
+- **Router** — framework (`vue-router` in deps?) and the dir holding the route declarations + entry (`src/router` with an `index.ts` exporting `routes`). Note the import alias (e.g. `@` → `src`) and any locale JSON for human page titles.
+
+If there's no Playwright suite, or the router isn't vue-router, read `references/qa-meter-config.md` for the escape hatches (sitemap-only, hand-provided `sitemap.json`, hand-authored suites) before proceeding.
+
+---
+
+## Step 2 — Scaffold `qa-meter.config.json`
+
+Create `qa-meter.config.json` **in the directory you'll run the CLI from** (config discovery is cwd-only, no walk-up). All path fields resolve *relative to that file's directory*; `testsGlob` / `fixturesFile` / `pageObjectsDir` resolve relative to `e2eDir`.
+
+Copy the shipped starter **`references/qa-meter.config.example.json`** to the project root as `qa-meter.config.json`, then adjust the paths (field-by-field reference in **`references/qa-meter-config.md`**). It's a vue-router + Playwright shape:
+
+```json
+{
+  "e2eDir": "e2e",
+  "suitesDir": "qa-meter/suites",
+  "outFile": "frontend/public/qa-status.json",
+  "testsGlob": "tests/**/*.spec.ts",
+  "fixturesFile": "helpers/fixtures.ts",
+  "pageObjectsDir": "pages",
+  "environment": "staging",
+  "resultsFile": null,
+  "sitemap": {
+    "file": "qa-meter/sitemap.json",
+    "framework": "vue-router",
+    "routerDir": "frontend/src/router",
+    "titlesFrom": "frontend/src/locales/fr.json",
+    "alias": { "@": "frontend/src" }
+  }
+}
+```
+
+Confirm the placement with the user if more than one root is plausible (e.g. a monorepo where e2e and the app live in sibling dirs — put the config at their common parent and use relative paths into each, exactly as above).
+
+---
+
+## Step 3 — Generate the artifact
+
+From the dir holding `qa-meter.config.json`:
+
+```bash
+npx @mhosaic/feedback-cli@latest qa refresh
+```
+
+Read the output. Expect, on a healthy first run:
+
+- `qa sitemap → …/sitemap.json (N pages)`
+- `qa generate: N suite(s), M case(s) → <suitesDir>/generated`
+- `qa build → <outFile>` with a `X% pages with scenarios · Y% scenarios passing` line.
+
+**Warnings are normal, not failures.** `qa generate` reports specs it can't statically map (`unmappable`), specs that produce no cases (`zero-case` — factory/loop/dynamic-title tests), and tests skipped for a non-static title. The artifact still builds. To improve coverage of those, add `@mhosaic:pages /route, /other` or `@mhosaic:scenario <id>` annotations to the spec headers, or give tests string-literal titles — see `docs/qa-meter/SUITE-FORMAT.md`. Surface the counts to the user; don't silently ignore a large unmappable set.
+
+If a step errors (commonly `qa sitemap`), see the adapter section of `references/qa-meter-troubleshooting.md`.
+
+---
+
+## Step 4 — Serve it + enable the FAB
+
+1. **Serve.** Confirm `outFile` lands inside the app's static dir so it's reachable at runtime. Verify once the dev server is up: `curl -s <origin>/qa-status.json -o /dev/null -w "%{http_code}\n"` → `200`.
+
+2. **Enable** on the surface from Step 1 (apply with `Edit`):
+
+   ```ts
+   // npm
+   createFeedback({ apiKey: '…', endpoint: '…', qaMeter: { source: '/qa-status.json' } })
+
+   // React — FeedbackProvider forwards the prop
+   <FeedbackProvider apiKey="…" endpoint="…" qaMeter={{ source: '/qa-status.json' }}>
+   ```
+   ```html
+   <!-- CDN / loader embed -->
+   <script src="…/embed.min.js" data-key="pk_proj_…" data-endpoint="…"
+           data-qa-source="/qa-status.json" defer></script>
+   ```
+
+   Optional knobs (npm/React): `locale: 'fr' | 'en'`, `size: 'sm' | 'md'` (default `sm`, the half-size second FAB), `position`, `getCurrentPage`. CDN: `data-qa-locale`. All documented in `references/qa-meter-config.md`.
+
+3. **Host-gate it.** Only set the source where you want the meter — staging / internal envs. Omit it (or gate the env var) in production to ship feedback-only. Confirm with the user which environments should show it.
+
+---
+
+## Step 5 — Verify
+
+Start the dev server and confirm, in the browser (or via the Preview/Chrome MCP if available):
+
+- The QA pastille mounts: `document.querySelector('[data-mqa-host]')` is non-null, and `[data-mqa-host]`'s `data-mqa-size` is `sm`.
+- It's stacked above the feedback FAB (bottom-right), at half size.
+- Clicking it opens the **sitemap modal**: the page tree, the `X% pages with scenarios · Y% passing` KPIs, and the freshness/version/env stamp from the artifact. The current route is marked "you are here".
+
+If the pastille is missing, the source wasn't wired or the artifact 404s; if the modal is empty, the artifact loaded but has no pages. Diagnostics: `references/qa-meter-troubleshooting.md`.
+
+Don't claim "done" without a screenshot of the mounted pastille and the opened modal (or an enumerated list of what's still broken).
+
+---
+
+## Step 6 — Wire CI (recommended)
+
+The artifact is a build output; rebuild it whenever the suite or routes change so it doesn't drift. The high-value version runs **after** the e2e job and feeds real results:
+
+```bash
+# after `playwright test --reporter=json > e2e/results.json`
+npx @mhosaic/feedback-cli@latest qa refresh --version "$APP_VERSION"
+#   ↳ with resultsFile pointed at e2e/results.json, scenarios light up green/red
+```
+
+Set `resultsFile` in the config to the Playwright JSON report path. Optionally add a tripwire that fails CI when the inputs drift out of sync with the artifact:
+
+```bash
+npx @mhosaic/feedback-cli@latest qa check --strict
+```
+
+Publish the refreshed `qa-status.json` with your static assets (it ships in the build output / CDN like any other file in `public/`). Full CI recipe in `references/qa-meter-config.md`.
+
+---
+
+## Principles
+
+- **Honesty model.** Gray = no evidence. Only a real passing Playwright run (or a recorded human validation) turns a scenario green. Never fabricate a `resultsFile` to make the meter look better — an empty/gray meter is the truthful state of an unrun suite.
+- **Host-served, host-gated, no backend.** The meter never talks to the feedback backend. It reads one static JSON. Enable it per environment; it's a staging/dev tool by default.
+- **Independent of identity.** The QA pastille shows regardless of `identify()`. Don't gate it behind login.
+- **Warnings ≠ failures, but don't hide them.** A big unmappable/zero-case count means real specs aren't represented — report it and offer annotations, don't bury it.
+- **Confirm at every fork.** Use `AskUserQuestion` for choices (which env, which surface, where the config lives); plain text for free-form paths.
+
+---
+
+## Skill files
+
+```
+.claude/skills/integrate-qa-meter/
+├── SKILL.md                          # this file (runbook + Q&A)
+└── references/
+    ├── qa-meter-config.md            # config schema, framework matrix, surfaces, CI
+    └── qa-meter-troubleshooting.md   # diagnostics: gray meter, 404, adapter, unmappable, missing FAB
+```
+
+Human-readable docs in the repo: `docs/qa-meter/INTEGRATING.md` (this flow) and `docs/qa-meter/SUITE-FORMAT.md` (suite YAML + annotations).