qualiow-exploratory-testing 2.0.0 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/.claude-plugin/marketplace.json +26 -0
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/CHANGELOG.md +83 -0
  4. package/README.md +123 -12
  5. package/agents/qa-diff-indexer-agent.md +81 -0
  6. package/agents/qa-gather-agent.md +21 -4
  7. package/agents/qa-page-mapper-agent.md +74 -0
  8. package/agents/qa-reporting-agent.md +103 -0
  9. package/bin/qualiow +49 -0
  10. package/data/knowledge/manifest.yml +22 -0
  11. package/dist/cli/index.js +1111 -62
  12. package/dist/index.d.ts +91 -2
  13. package/dist/index.js +532 -48
  14. package/docs/GETTING-STARTED.md +127 -8
  15. package/hooks/hooks.json +27 -0
  16. package/hooks/scripts/read-guard.mjs +95 -0
  17. package/hooks/scripts/secret-patterns.d.mts +8 -0
  18. package/hooks/scripts/secret-patterns.mjs +136 -0
  19. package/hooks/scripts/write-guard.mjs +87 -0
  20. package/package.json +3 -2
  21. package/skills/qa-explore/SKILL.md +2 -1
  22. package/skills/qa-explore/phases/00-setup.md +16 -8
  23. package/skills/qa-explore/phases/03-discovery.md +48 -6
  24. package/skills/qa-explore/phases/07-reporting.md +36 -15
  25. package/skills/qa-explore/references/delegation-rules.md +82 -0
  26. package/skills/qa-explore/references/output-contract.md +7 -2
  27. package/skills/qa-explore/references/paths.md +25 -1
  28. package/skills/qa-explore/references/security-rules.md +4 -0
  29. package/skills/qa-explore/references/session-rules.md +2 -1
  30. package/skills/qa-explore-cleanup/SKILL.md +44 -19
  31. package/skills/qa-explore-feedback/SKILL.md +5 -0
  32. package/skills/qa-explore-mobile/SKILL.md +1 -1
  33. package/skills/qa-explore-mobile/phases/07-reporting.md +33 -11
  34. package/skills/qa-explore-quick/SKILL.md +12 -2
  35. package/skills/qa-explore-report/SKILL.md +29 -5
  36. package/skills/qa-gather/SKILL.md +30 -9
  37. package/skills/qa-knowledge-add/SKILL.md +10 -5
  38. package/skills/qa-knowledge-list/SKILL.md +28 -40
  39. package/skills/qa-verify-backend/SKILL.md +7 -4
  40. package/skills/qa-verify-backend/phases/02-static-review.md +11 -0
  41. package/skills/qa-verify-backend/phases/03-live-verification.md +3 -1
  42. package/skills/qa-verify-backend/phases/03b-api-verification.md +3 -1
  43. package/skills/qa-verify-backend/phases/05-reporting.md +51 -19
package/dist/index.js CHANGED
@@ -231,7 +231,10 @@ var KnowledgeManifestEntrySchema = z3.object({
231
231
  var LoadingStrategySchema = z3.object({
232
232
  always: z3.array(z3.string()),
233
233
  by_domain: z3.record(z3.string(), z3.array(z3.string())),
234
- by_tag: z3.record(z3.string(), z3.array(z3.string()))
234
+ by_tag: z3.record(z3.string(), z3.array(z3.string())),
235
+ /** Per-skill selection used by `qualiow kb digest --for <skill>`. Optional so
236
+ * a manifest written before this key still validates. */
237
+ by_skill: z3.record(z3.string(), z3.array(z3.string())).optional()
235
238
  });
236
239
  var KnowledgeManifestSchema = z3.object({
237
240
  version: z3.string().min(1),
@@ -684,7 +687,8 @@ function validateKnowledgeBase(dataDir) {
684
687
  const allRefs = [
685
688
  ...ls.always,
686
689
  ...Object.values(ls.by_domain).flat(),
687
- ...Object.values(ls.by_tag).flat()
690
+ ...Object.values(ls.by_tag).flat(),
691
+ ...Object.values(ls.by_skill ?? {}).flat()
688
692
  ];
689
693
  for (const id of allRefs) {
690
694
  if (!registryIds.has(id)) {
@@ -786,6 +790,7 @@ function appendSessionMetricsDeduped(outputDir, metrics) {
786
790
  // src/utils/session-dir.ts
787
791
  var SESSION_KINDS = ["explore", "quick", "mobile", "backend"];
788
792
  var SESSION_DIR_RE = /^(\d{4}-\d{2}-\d{2}-\d{4})-(explore|quick|mobile|backend)-([a-z0-9][a-z0-9-]*)$/;
793
+ var LEGACY_SESSION_DIR_RE = /^\d{4}-\d{2}-\d{2}(?:-\d{4})?-.+/;
789
794
  function slugify(input) {
790
795
  let s = (input ?? "").trim();
791
796
  try {
@@ -811,6 +816,17 @@ function parseSessionDirName(name) {
811
816
  if (!m) return null;
812
817
  return { timestamp: m[1], kind: m[2], slug: m[3] };
813
818
  }
819
+ var DATE_PREFIX_RE = /^(\d{4})-(\d{2})-(\d{2})(?:-(\d{2})(\d{2}))?(?=-|$)/;
820
+ function describeSessionDir(name) {
821
+ const parsed = parseSessionDirName(name);
822
+ const legacy = !parsed;
823
+ if (!parsed && !LEGACY_SESSION_DIR_RE.test(name)) return null;
824
+ const m = DATE_PREFIX_RE.exec(name);
825
+ if (!m) return null;
826
+ const [, y, mo, d, h, mi] = m;
827
+ const timestamp = new Date(Number(y), Number(mo) - 1, Number(d), Number(h ?? 0), Number(mi ?? 0));
828
+ return { name, timestamp, legacy };
829
+ }
814
830
 
815
831
  // src/utils/markdown-table.ts
816
832
  function splitRow(line) {
@@ -922,6 +938,22 @@ var ALL_BUGS_MD_HEADER = table(
922
938
  "_Consolidated index across all exploratory testing sessions._",
923
939
  ALL_BUGS_COLUMNS
924
940
  );
941
+ function keysOf(columns) {
942
+ return columns.map((c) => c.trim().toLowerCase());
943
+ }
944
+ function headersMatchColumns(headers, columns) {
945
+ const a = keysOf(headers);
946
+ const b = keysOf(columns);
947
+ return a.length === b.length && a.every((h, i) => h === b[i]);
948
+ }
949
+ function missingColumns(headers, columns) {
950
+ const present = new Set(keysOf(headers));
951
+ return columns.filter((c) => !present.has(c.trim().toLowerCase()));
952
+ }
953
+ function buildTableRow(headers, values) {
954
+ const cells = keysOf(headers).map((key) => values[key] ?? "");
955
+ return `| ${cells.join(" | ")} |`;
956
+ }
925
957
 
926
958
  // src/utils/gitignore.ts
927
959
  var QUALIOW_GITIGNORE_HEADER = "# Qualiow";
@@ -1003,6 +1035,19 @@ function resolveTargetPath(cwd, name, pkgRoot = getPackageRoot()) {
1003
1035
  if (existsSync4(cwdDefault)) return cwdDefault;
1004
1036
  return resolve2(pkgRoot, "data", "targets", "_default.yml");
1005
1037
  }
1038
+ function resolveDataDir(cwd, explicit, pkgRoot = getPackageRoot()) {
1039
+ if (explicit) return resolve2(cwd, explicit);
1040
+ const projectLocal = resolve2(cwd, "data");
1041
+ if (existsSync4(join4(projectLocal, "knowledge", "manifest.yml"))) {
1042
+ return projectLocal;
1043
+ }
1044
+ const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
1045
+ if (pluginRoot) {
1046
+ const pluginData = resolve2(pluginRoot, "data");
1047
+ if (existsSync4(pluginData)) return pluginData;
1048
+ }
1049
+ return resolve2(pkgRoot, "data");
1050
+ }
1006
1051
  function resolveDomainPath(dataDir, id) {
1007
1052
  const direct = join4(dataDir, "domains", `${id}.yml`);
1008
1053
  if (existsSync4(direct)) return direct;
@@ -1933,6 +1978,66 @@ import {
1933
1978
  chmodSync
1934
1979
  } from "fs";
1935
1980
  import chalk from "chalk";
1981
+
1982
+ // src/utils/settings-merge.ts
1983
+ var QUALIOW_HOOK_ENTRIES = [
1984
+ { matcher: "Read", command: 'node "$CLAUDE_PROJECT_DIR/qa/hooks/read-guard.mjs"' },
1985
+ {
1986
+ matcher: "Write|Edit|MultiEdit",
1987
+ command: 'node "$CLAUDE_PROJECT_DIR/qa/hooks/write-guard.mjs"'
1988
+ }
1989
+ ];
1990
+ var QUALIOW_PERMISSION_ALLOW = [
1991
+ "Bash(playwright-cli:*)",
1992
+ "Bash(npx playwright-cli:*)",
1993
+ "Bash(qualiow:*)"
1994
+ ];
1995
+ function isRecord(v) {
1996
+ return typeof v === "object" && v !== null && !Array.isArray(v);
1997
+ }
1998
+ function existingHookCommands(settings) {
1999
+ const commands = /* @__PURE__ */ new Set();
2000
+ const hooks = settings.hooks;
2001
+ if (!isRecord(hooks)) return commands;
2002
+ const preToolUse = hooks.PreToolUse;
2003
+ if (!Array.isArray(preToolUse)) return commands;
2004
+ for (const entry of preToolUse) {
2005
+ if (!isRecord(entry) || !Array.isArray(entry.hooks)) continue;
2006
+ for (const h of entry.hooks) {
2007
+ if (isRecord(h) && typeof h.command === "string") commands.add(h.command);
2008
+ }
2009
+ }
2010
+ return commands;
2011
+ }
2012
+ function mergeQualiowHookSettings(existing) {
2013
+ const settings = isRecord(existing) ? { ...existing } : {};
2014
+ let changed = false;
2015
+ const hooksSection = isRecord(settings.hooks) ? { ...settings.hooks } : {};
2016
+ const preToolUse = Array.isArray(hooksSection.PreToolUse) ? [...hooksSection.PreToolUse] : [];
2017
+ const haveCommands = existingHookCommands(settings);
2018
+ for (const { matcher, command } of QUALIOW_HOOK_ENTRIES) {
2019
+ if (haveCommands.has(command)) continue;
2020
+ preToolUse.push({ matcher, hooks: [{ type: "command", command }] });
2021
+ haveCommands.add(command);
2022
+ changed = true;
2023
+ }
2024
+ hooksSection.PreToolUse = preToolUse;
2025
+ settings.hooks = hooksSection;
2026
+ const permissions = isRecord(settings.permissions) ? { ...settings.permissions } : {};
2027
+ const allow = Array.isArray(permissions.allow) ? [...permissions.allow] : [];
2028
+ const allowSet = new Set(allow.filter((a) => typeof a === "string"));
2029
+ for (const rule of QUALIOW_PERMISSION_ALLOW) {
2030
+ if (allowSet.has(rule)) continue;
2031
+ allow.push(rule);
2032
+ allowSet.add(rule);
2033
+ changed = true;
2034
+ }
2035
+ permissions.allow = allow;
2036
+ settings.permissions = permissions;
2037
+ return { settings, changed };
2038
+ }
2039
+
2040
+ // src/cli/commands/init.ts
1936
2041
  function sameContent(a, b) {
1937
2042
  try {
1938
2043
  return readFileSync6(a).equals(readFileSync6(b));
@@ -2000,14 +2105,14 @@ async function runInit(options, ctx) {
2000
2105
  filter: (rel2) => rel2.startsWith("qa-")
2001
2106
  })
2002
2107
  );
2003
- const agentCandidates = [
2004
- join6(pkgRoot, "agents", "qa-gather-agent.md"),
2005
- join6(pkgRoot, ".claude", "agents", "qa-gather-agent.md")
2006
- ];
2007
- const agentSrc = agentCandidates.find((p) => existsSync6(p));
2008
- if (agentSrc) {
2108
+ const agentsCandidates = [join6(pkgRoot, "agents"), join6(pkgRoot, ".claude", "agents")];
2109
+ const agentsSrc = agentsCandidates.find((p) => existsSync6(p));
2110
+ if (agentsSrc) {
2009
2111
  copies.push(
2010
- copyEntry(agentSrc, join6(cwd, ".claude", "agents", "qa-gather-agent.md"), copyOpts)
2112
+ ...copyTree(agentsSrc, join6(cwd, ".claude", "agents"), {
2113
+ ...copyOpts,
2114
+ filter: (rel2) => rel2.endsWith(".md")
2115
+ })
2011
2116
  );
2012
2117
  }
2013
2118
  const dataSrc = join6(pkgRoot, "data");
@@ -2033,7 +2138,12 @@ async function runInit(options, ctx) {
2033
2138
  })
2034
2139
  );
2035
2140
  const binSrc = join6(pkgRoot, "bin");
2036
- copies.push(...copyTree(binSrc, join6(cwd, "qa", "bin"), copyOpts));
2141
+ copies.push(
2142
+ ...copyTree(binSrc, join6(cwd, "qa", "bin"), {
2143
+ ...copyOpts,
2144
+ filter: (rel2) => rel2 !== "qualiow"
2145
+ })
2146
+ );
2037
2147
  if (existsSync6(binSrc)) {
2038
2148
  const versionPath = join6(cwd, "qa", "bin", "VERSION");
2039
2149
  const version = `${getPackageVersion(pkgRoot)}
@@ -2052,6 +2162,32 @@ async function runInit(options, ctx) {
2052
2162
  copies.push(copyEntry(envExampleSrc, join6(cwd, "qa", ".env.example"), copyOpts));
2053
2163
  }
2054
2164
  }
2165
+ let hooksSettingsChanged = false;
2166
+ if (options.hooks) {
2167
+ const hooksScriptsSrc = join6(pkgRoot, "hooks", "scripts");
2168
+ copies.push(
2169
+ ...copyTree(hooksScriptsSrc, join6(cwd, "qa", "hooks"), {
2170
+ ...copyOpts,
2171
+ filter: (rel2) => rel2.endsWith(".mjs")
2172
+ })
2173
+ );
2174
+ const settingsPath = join6(cwd, ".claude", "settings.json");
2175
+ const settingsExisted = existsSync6(settingsPath);
2176
+ let existingSettings;
2177
+ if (settingsExisted) {
2178
+ try {
2179
+ existingSettings = JSON.parse(readFileSync6(settingsPath, "utf-8"));
2180
+ } catch {
2181
+ existingSettings = void 0;
2182
+ }
2183
+ }
2184
+ const { settings, changed } = mergeQualiowHookSettings(existingSettings);
2185
+ hooksSettingsChanged = changed || !settingsExisted;
2186
+ if (!options.dryRun) {
2187
+ mkdirSync2(dirname3(settingsPath), { recursive: true });
2188
+ writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n");
2189
+ }
2190
+ }
2055
2191
  for (const dir of ["output/sessions", "output/bugs", "output/context", ".auth", "qa"]) {
2056
2192
  const full = join6(cwd, dir);
2057
2193
  if (!existsSync6(full)) {
@@ -2095,12 +2231,20 @@ async function runInit(options, ctx) {
2095
2231
  log(
2096
2232
  gitignoreUpdated ? chalk.green(" \u2713 Updated .gitignore (Qualiow block)") : chalk.cyan(" \u25CB .gitignore already up to date")
2097
2233
  );
2234
+ if (options.hooks) {
2235
+ log(
2236
+ hooksSettingsChanged ? chalk.green(" \u2713 Wired hooks into .claude/settings.json") : chalk.cyan(" \u25CB .claude/settings.json hooks already up to date")
2237
+ );
2238
+ }
2098
2239
  log("");
2099
2240
  log(chalk.cyan.bold(options.dryRun ? "Dry run complete." : "Qualiow initialized."));
2100
2241
  log("");
2101
2242
  log(chalk.white("Next steps:"));
2102
2243
  log(chalk.white(" 1. npx playwright-cli install --skills # official Playwright skill, next to qualiow"));
2103
2244
  log(chalk.white(" 2. cp qa/.env.example qa/.env # credentials by env var name only"));
2245
+ if (options.hooks) {
2246
+ log(chalk.white(' QUALIOW_HOOKS=off or QUALIOW_READ_MAX_LINES=<n> under "env" in .claude/settings.json tune the guards'));
2247
+ }
2104
2248
  log(chalk.white(" 3. /qa-target-setup or /qa-explore https://your-app.com"));
2105
2249
  log(chalk.white(" 4. mobile: qa/bin/doctor-mobile.sh # then /qa-explore-mobile --target <id>"));
2106
2250
  log("");
@@ -2172,7 +2316,7 @@ ${details}`);
2172
2316
  log(chalk2.white(` Time box: ${minutes} min`));
2173
2317
  return { sessionDir };
2174
2318
  }
2175
- for (const sub of ["", "screenshots", "bugs", "videos"]) {
2319
+ for (const sub of ["", "screenshots", "bugs", "videos", "snapshots"]) {
2176
2320
  mkdirSync3(join7(sessionDir, sub), { recursive: true });
2177
2321
  }
2178
2322
  const date = now.toISOString().slice(0, 10);
@@ -2309,13 +2453,13 @@ import { existsSync as existsSync9, readFileSync as readFileSync8, readdirSync a
2309
2453
  import { parse as parseYaml3 } from "yaml";
2310
2454
  import { globSync as globSync3 } from "glob";
2311
2455
  import chalk4 from "chalk";
2312
- async function runList(type, cwd) {
2456
+ async function runList(type, cwd, options = {}, log = (line) => console.log(line)) {
2313
2457
  switch (type) {
2314
2458
  case "sessions":
2315
- listSessions(cwd);
2459
+ listSessions(cwd, log);
2316
2460
  break;
2317
2461
  case "knowledge":
2318
- listKnowledge(cwd);
2462
+ listKnowledge(cwd, options, log);
2319
2463
  break;
2320
2464
  case "targets":
2321
2465
  listTargets(cwd);
@@ -2347,74 +2491,168 @@ function readSessionIndex(indexPath) {
2347
2491
  }
2348
2492
  return rows;
2349
2493
  }
2350
- function listSessions(cwd) {
2494
+ function reportDirName(report) {
2495
+ const link = /\]\(([^)]+)\)/.exec(report);
2496
+ const path = (link ? link[1] : report).trim();
2497
+ return basename6(path.replace(/\/session-report\.md$/, ""));
2498
+ }
2499
+ function listSessions(cwd, log) {
2351
2500
  const sessionsDir = resolve6(cwd, "output", "sessions");
2352
2501
  const indexPath = join9(sessionsDir, "INDEX.md");
2353
2502
  if (!existsSync9(sessionsDir)) {
2354
- console.log(chalk4.yellow("No sessions directory. Run `npx qualiow init` first, then start a session."));
2503
+ log(chalk4.yellow("No sessions directory. Run `npx qualiow init` first, then start a session."));
2355
2504
  return;
2356
2505
  }
2357
2506
  const rows = readSessionIndex(indexPath);
2358
- const indexedDirs = new Set(rows.map((r) => basename6(r.report.replace(/\/session-report\.md$/, ""))));
2359
- const unindexed = readdirSync5(sessionsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && SESSION_DIR_RE.test(d.name) && !indexedDirs.has(d.name)).map((d) => d.name).sort();
2360
- console.log(chalk4.cyan.bold("\nSessions:"));
2361
- console.log("");
2507
+ const indexedDirs = new Set(rows.map((r) => reportDirName(r.report)));
2508
+ const unindexed = readdirSync5(sessionsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => describeSessionDir(d.name)).filter((d) => d !== null && !indexedDirs.has(d.name)).sort((a, b) => a.name.localeCompare(b.name));
2509
+ log(chalk4.cyan.bold("\nSessions:"));
2510
+ log("");
2362
2511
  if (rows.length === 0 && unindexed.length === 0) {
2363
- console.log(chalk4.yellow(" No sessions recorded yet."));
2364
- console.log(chalk4.white(" Start one with: /qa-explore <url>"));
2365
- console.log("");
2512
+ log(chalk4.yellow(" No sessions recorded yet."));
2513
+ log(chalk4.white(" Start one with: /qa-explore <url>"));
2514
+ log("");
2366
2515
  return;
2367
2516
  }
2368
- const widths = [16, 8, 22, 5, 9, 12];
2517
+ const widths = [16, 8, 22, 5, 9, 18];
2369
2518
  const header = INDEX_COLUMNS.map((c, i) => i < widths.length ? pad2(c, widths[i]) : c).join(" ");
2370
- console.log(chalk4.bold(` ${header}`));
2371
- console.log(` ${widths.map((w) => "\u2500".repeat(w)).join(" ")} ${"\u2500".repeat(30)}`);
2519
+ log(chalk4.bold(` ${header}`));
2520
+ log(` ${widths.map((w) => "\u2500".repeat(w)).join(" ")} ${"\u2500".repeat(30)}`);
2372
2521
  for (const r of rows) {
2373
- console.log(
2374
- ` ${pad2(r.date, 16)} ${pad2(r.kind, 8)} ${pad2(r.target, 22)} ${pad2(r.bugs, 5)} ${pad2(r.duration, 9)} ${pad2(r.status, 12)} ${r.report}`
2522
+ log(
2523
+ ` ${pad2(r.date, 16)} ${pad2(r.kind, 8)} ${pad2(r.target, 22)} ${pad2(r.bugs, 5)} ${pad2(r.duration, 9)} ${pad2(r.status, 18)} ${r.report}`
2375
2524
  );
2376
2525
  }
2377
2526
  for (const d of unindexed) {
2378
- console.log(chalk4.gray(` ${pad2(d.slice(0, 15), 16)} ${pad2("", 8)} ${pad2("", 22)} ${pad2("", 5)} ${pad2("", 9)} ${pad2("unindexed", 12)} ${d}`));
2527
+ const status = d.legacy ? "unindexed (legacy)" : "unindexed";
2528
+ log(chalk4.gray(` ${pad2(d.name.slice(0, 15), 16)} ${pad2("", 8)} ${pad2("", 22)} ${pad2("", 5)} ${pad2("", 9)} ${pad2(status, 18)} ${d.name}`));
2379
2529
  }
2380
- console.log("");
2381
- console.log(chalk4.white(` Total: ${rows.length} session(s)` + (unindexed.length ? chalk4.gray(` (+${unindexed.length} unindexed)`) : "")));
2382
- console.log("");
2530
+ log("");
2531
+ log(chalk4.white(` Total: ${rows.length} session(s)` + (unindexed.length ? chalk4.gray(` (+${unindexed.length} unindexed)`) : "")));
2532
+ log("");
2383
2533
  }
2384
- function listKnowledge(cwd) {
2385
- const knowledgeDir = resolve6(cwd, "data", "knowledge");
2534
+ function listKnowledge(cwd, options, log) {
2535
+ const dataDir = resolveDataDir(cwd, options.data);
2536
+ const knowledgeDir = join9(dataDir, "knowledge");
2386
2537
  const manifestPath = join9(knowledgeDir, "manifest.yml");
2387
2538
  if (!existsSync9(manifestPath)) {
2388
- console.log(chalk4.yellow("No knowledge base found. Run `npx qualiow init` first."));
2539
+ log(chalk4.yellow(`No knowledge base at ${manifestPath}. Run \`npx qualiow init\` first.`));
2540
+ return;
2541
+ }
2542
+ const manifest = KnowledgeManifestSchema.parse(
2543
+ parseYaml3(readFileSync8(manifestPath, "utf-8"))
2544
+ );
2545
+ if (options.entry) {
2546
+ log(readEntryFile(knowledgeDir, manifest.entries, options.entry));
2547
+ return;
2548
+ }
2549
+ if (options.changelog) {
2550
+ printKnowledgeChangelog(knowledgeDir, log);
2551
+ return;
2552
+ }
2553
+ if (options.stats) {
2554
+ printKnowledgeStats(manifest, log);
2389
2555
  return;
2390
2556
  }
2391
- const manifest = parseYaml3(readFileSync8(manifestPath, "utf-8"));
2392
2557
  const filesOnDisk = globSync3(join9(knowledgeDir, "releases", "*", "entries", "*.yml")).length;
2393
- console.log(chalk4.cyan.bold("\nKnowledge Base:"));
2394
- console.log(chalk4.white(` Version: ${manifest.version} | Entries: ${manifest.entries.length}`));
2558
+ log(chalk4.cyan.bold("\nKnowledge Base:"));
2559
+ log(chalk4.white(` Version: ${manifest.version} | Entries: ${manifest.entries.length}`));
2395
2560
  if (filesOnDisk !== manifest.entries.length || manifest.stats.total_entries !== filesOnDisk) {
2396
- console.log(
2561
+ log(
2397
2562
  chalk4.yellow(
2398
2563
  ` \u26A0 Registry (${manifest.entries.length}) / stats (${manifest.stats.total_entries}) disagree with ${filesOnDisk} entry files \u2014 run: npx qualiow kb sync`
2399
2564
  )
2400
2565
  );
2401
2566
  }
2402
- console.log("");
2567
+ const filters = [];
2568
+ if (options.domain) filters.push(`domain ${options.domain}`);
2569
+ if (options.tag) filters.push(`tag ${options.tag}`);
2570
+ if (options.type) filters.push(`type ${options.type}`);
2571
+ const entries = manifest.entries.filter(
2572
+ (e) => (!options.domain || e.domains.includes(options.domain) || e.domains.includes("all")) && (!options.tag || e.tags.includes(options.tag)) && (!options.type || e.type === options.type)
2573
+ );
2574
+ if (filters.length) {
2575
+ log(chalk4.white(` Filter: ${filters.join(", ")} \u2192 ${entries.length} entries`));
2576
+ }
2577
+ log("");
2578
+ if (entries.length === 0) {
2579
+ log(chalk4.yellow(" No entries match that filter."));
2580
+ log("");
2581
+ return;
2582
+ }
2403
2583
  const grouped = /* @__PURE__ */ new Map();
2404
- for (const entry of manifest.entries) {
2584
+ for (const entry of entries) {
2405
2585
  const list = grouped.get(entry.type) ?? [];
2406
2586
  list.push(entry);
2407
2587
  grouped.set(entry.type, list);
2408
2588
  }
2409
- for (const [type, entries] of grouped) {
2410
- console.log(chalk4.cyan(` ${type.charAt(0).toUpperCase() + type.slice(1)}s (${entries.length}):`));
2411
- for (const entry of entries) {
2589
+ for (const [type, group] of grouped) {
2590
+ log(chalk4.cyan(` ${type.charAt(0).toUpperCase() + type.slice(1)}s (${group.length}):`));
2591
+ for (const entry of group) {
2412
2592
  const priorityColor = entry.priority === "high" ? chalk4.red : entry.priority === "medium" ? chalk4.yellow : chalk4.white;
2413
2593
  const tags = entry.tags.map((t) => chalk4.gray(t)).join(", ");
2414
- console.log(` ${priorityColor(`[${entry.priority}]`)} ${entry.id} ${chalk4.gray("tags:")} ${tags}`);
2594
+ log(` ${priorityColor(`[${entry.priority}]`)} ${entry.id} ${chalk4.gray("tags:")} ${tags}`);
2415
2595
  }
2416
- console.log("");
2596
+ log("");
2597
+ }
2598
+ }
2599
+ function readEntryFile(knowledgeDir, entries, id) {
2600
+ const meta = entries.find((e) => e.id === id);
2601
+ const path = meta ? join9(knowledgeDir, meta.file) : join9(knowledgeDir, "custom", `${id}.yml`);
2602
+ if (!existsSync9(path)) {
2603
+ throw new Error(`Unknown entry "${id}". Run \`qualiow list knowledge\` to see the available ids.`);
2417
2604
  }
2605
+ return readFileSync8(path, "utf-8").trimEnd();
2606
+ }
2607
+ function printKnowledgeChangelog(knowledgeDir, log) {
2608
+ const changelogPath = join9(knowledgeDir, "changelog.yml");
2609
+ if (!existsSync9(changelogPath)) {
2610
+ log(chalk4.yellow(`No changelog at ${changelogPath}.`));
2611
+ return;
2612
+ }
2613
+ const changelog = KnowledgeChangelogSchema.parse(
2614
+ parseYaml3(readFileSync8(changelogPath, "utf-8"))
2615
+ );
2616
+ log(chalk4.cyan.bold("\nKnowledge Base Changelog:"));
2617
+ log("");
2618
+ for (const release of changelog.releases) {
2619
+ log(` ${chalk4.bold(`v${release.version}`)} ${chalk4.gray(`\xB7 ${release.date}`)}`);
2620
+ log(` ${release.summary}`);
2621
+ const added = release.entries_added.map((e) => e.id);
2622
+ if (added.length) log(` ${chalk4.gray("added:")} ${added.join(", ")}`);
2623
+ if (release.entries_modified.length) {
2624
+ log(` ${chalk4.gray("modified:")} ${release.entries_modified.join(", ")}`);
2625
+ }
2626
+ if (release.entries_removed.length) {
2627
+ log(` ${chalk4.gray("removed:")} ${release.entries_removed.join(", ")}`);
2628
+ }
2629
+ log("");
2630
+ }
2631
+ }
2632
+ function printKnowledgeStats(manifest, log) {
2633
+ log(chalk4.cyan.bold("\nKnowledge Base Stats:"));
2634
+ log(chalk4.white(` Version: ${manifest.version}`));
2635
+ log("");
2636
+ for (const [key, value] of Object.entries(manifest.stats)) {
2637
+ log(` ${pad2(key.replace(/_/g, " "), 18)} ${value}`);
2638
+ }
2639
+ log("");
2640
+ log(chalk4.cyan(` Active releases (${manifest.active_releases.length}):`));
2641
+ log(` ${manifest.active_releases.join(", ")}`);
2642
+ log("");
2643
+ const ls = manifest.loading_strategy;
2644
+ log(chalk4.cyan(" Loading strategy:"));
2645
+ log(` ${pad2("always", 12)} ${ls.always.length} entries`);
2646
+ for (const [bucket, map] of [
2647
+ ["by_domain", ls.by_domain],
2648
+ ["by_tag", ls.by_tag],
2649
+ ["by_skill", ls.by_skill ?? {}]
2650
+ ]) {
2651
+ const keys = Object.keys(map);
2652
+ const total = Object.values(map).reduce((n, ids) => n + ids.length, 0);
2653
+ log(` ${pad2(bucket, 12)} ${keys.length} keys, ${total} references`);
2654
+ }
2655
+ log("");
2418
2656
  }
2419
2657
  function listTargets(cwd) {
2420
2658
  const targetsDir = resolve6(cwd, "data", "targets");
@@ -2561,9 +2799,13 @@ function printResult(result, cwd) {
2561
2799
 
2562
2800
  // src/cli/commands/kb.ts
2563
2801
  import { Command as Command6 } from "commander";
2564
- import { resolve as resolve8 } from "path";
2565
- import { existsSync as existsSync11 } from "fs";
2802
+ import { resolve as resolve8, join as join11 } from "path";
2803
+ import { existsSync as existsSync11, readFileSync as readFileSync9, readdirSync as readdirSync6 } from "fs";
2566
2804
  import chalk6 from "chalk";
2805
+ import { parse as parseYaml4 } from "yaml";
2806
+ var DEFAULT_MAX_LINES = 12;
2807
+ var WRAP_COLUMN = 100;
2808
+ var WHEN_TO_USE_ITEMS = 3;
2567
2809
  function runKb(mode, cwd) {
2568
2810
  const dataDir = resolve8(cwd, "data");
2569
2811
  if (!existsSync11(resolve8(dataDir, "knowledge", "manifest.yml"))) {
@@ -2571,6 +2813,241 @@ function runKb(mode, cwd) {
2571
2813
  }
2572
2814
  return syncKnowledgeManifest(dataDir, { check: mode === "check" });
2573
2815
  }
2816
+ function runKbDigest(options, cwd) {
2817
+ const dataDir = resolveDataDir(cwd, options.data);
2818
+ const knowledgeDir = join11(dataDir, "knowledge");
2819
+ const manifestPath = join11(knowledgeDir, "manifest.yml");
2820
+ if (!existsSync11(manifestPath)) {
2821
+ throw new Error(
2822
+ `No knowledge manifest at ${manifestPath}. Pass --data <dir>, or run \`npx qualiow init\` first.`
2823
+ );
2824
+ }
2825
+ const manifest = KnowledgeManifestSchema.parse(
2826
+ parseYaml4(readFileSync9(manifestPath, "utf-8"))
2827
+ );
2828
+ const byId = new Map(manifest.entries.map((e) => [e.id, e]));
2829
+ const maxLines = Math.max(1, options.maxLines ?? DEFAULT_MAX_LINES);
2830
+ if (options.entry) {
2831
+ return readWholeEntry(knowledgeDir, byId, options.entry);
2832
+ }
2833
+ const ls = manifest.loading_strategy;
2834
+ const selected = [];
2835
+ const add = (ids) => {
2836
+ let added = 0;
2837
+ for (const id of ids ?? []) {
2838
+ if (selected.includes(id)) continue;
2839
+ selected.push(id);
2840
+ added++;
2841
+ }
2842
+ return added;
2843
+ };
2844
+ add(ls.always);
2845
+ const domainAdded = options.domain ? add(ls.by_domain[options.domain]) : 0;
2846
+ const tags = options.tag ?? [];
2847
+ let tagAdded = 0;
2848
+ for (const tag of tags) tagAdded += add(ls.by_tag[tag]);
2849
+ let skillAdded = 0;
2850
+ if (options.for) {
2851
+ const bySkill = ls.by_skill;
2852
+ if (!bySkill) {
2853
+ throw new Error(
2854
+ "This manifest has no loading_strategy.by_skill, so --for has nothing to select."
2855
+ );
2856
+ }
2857
+ if (!Object.prototype.hasOwnProperty.call(bySkill, options.for)) {
2858
+ throw new Error(
2859
+ `Unknown skill "${options.for}". Known: ${Object.keys(bySkill).sort().join(", ")}.`
2860
+ );
2861
+ }
2862
+ skillAdded = add(bySkill[options.for]);
2863
+ }
2864
+ const unknown = selected.filter((id) => !byId.has(id));
2865
+ if (unknown.length) {
2866
+ throw new Error(
2867
+ `loading_strategy references ${unknown.length} unknown entry id(s): ${unknown.join(", ")}. Run \`qualiow kb sync\` and \`qualiow validate --kb\`.`
2868
+ );
2869
+ }
2870
+ const header = [
2871
+ `# Knowledge digest v${manifest.version}`,
2872
+ `${selected.length} entries`,
2873
+ `always ${ls.always.length}`
2874
+ ];
2875
+ if (options.domain) header.push(`domain ${options.domain} +${domainAdded}`);
2876
+ if (tags.length) header.push(`tags ${tags.join(", ")} +${tagAdded}`);
2877
+ if (options.for) header.push(`skill ${options.for} +${skillAdded}`);
2878
+ const lines = [header.join(" \xB7 ")];
2879
+ for (const id of selected) {
2880
+ const meta = byId.get(id);
2881
+ lines.push(...entryBlock(join11(knowledgeDir, meta.file), meta, maxLines));
2882
+ }
2883
+ lines.push(...customSection(knowledgeDir, maxLines));
2884
+ lines.push(...learnedPatternsSection(cwd, knowledgeDir));
2885
+ return lines.join("\n");
2886
+ }
2887
+ function readWholeEntry(knowledgeDir, byId, id) {
2888
+ const meta = byId.get(id);
2889
+ const path = meta ? join11(knowledgeDir, meta.file) : join11(knowledgeDir, "custom", `${id}.yml`);
2890
+ if (!existsSync11(path)) {
2891
+ throw new Error(
2892
+ `Unknown entry "${id}". Run \`qualiow list knowledge\` to see the available ids.`
2893
+ );
2894
+ }
2895
+ return readFileSync9(path, "utf-8").trimEnd();
2896
+ }
2897
+ function entryBlock(file, meta, maxLines, custom = false) {
2898
+ if (!existsSync11(file)) {
2899
+ throw new Error(`Entry "${meta.id}" is registered but its file is missing: ${file}`);
2900
+ }
2901
+ const entry = KnowledgeEntrySchema.parse(parseYaml4(readFileSync9(file, "utf-8")));
2902
+ const content = entry.content;
2903
+ const marker = custom ? " [custom]" : "";
2904
+ const out = [
2905
+ `- ${meta.id} [${meta.type}/${meta.priority}]${marker} tags: ${meta.tags.join(", ")}`
2906
+ ];
2907
+ out.push(...wrap(collapse(entry.content.summary)));
2908
+ for (const [key, items] of namedArrays(content)) {
2909
+ const rendered = items.map((item) => {
2910
+ const lead = subItemLead(item);
2911
+ return lead ? `${item.name} \u2014 ${lead}` : item.name;
2912
+ }).join("; ");
2913
+ out.push(...wrap(`${humanise(key)}: ${rendered}`));
2914
+ }
2915
+ const whenToUse = content["when_to_use"];
2916
+ if (Array.isArray(whenToUse) && whenToUse.length) {
2917
+ const items = whenToUse.slice(0, WHEN_TO_USE_ITEMS).filter((v) => typeof v === "string").map(collapse);
2918
+ if (items.length) out.push(...wrap(`when to use: ${items.join("; ")}`));
2919
+ }
2920
+ return capLines(out, maxLines);
2921
+ }
2922
+ function customSection(knowledgeDir, maxLines) {
2923
+ const customDir = join11(knowledgeDir, "custom");
2924
+ if (!existsSync11(customDir)) return [];
2925
+ const files = readdirSync6(customDir).filter((f) => f.endsWith(".yml")).sort();
2926
+ if (!files.length) return [];
2927
+ const lines = ["", "## Custom entries"];
2928
+ for (const file of files) {
2929
+ const path = join11(customDir, file);
2930
+ const parsed = parseYaml4(readFileSync9(path, "utf-8"));
2931
+ lines.push(
2932
+ ...entryBlock(
2933
+ path,
2934
+ {
2935
+ id: parsed.id ?? file.replace(/\.yml$/, ""),
2936
+ type: parsed.type ?? "custom",
2937
+ priority: parsed.priority ?? "medium",
2938
+ tags: parsed.tags ?? []
2939
+ },
2940
+ maxLines,
2941
+ true
2942
+ )
2943
+ );
2944
+ }
2945
+ return lines;
2946
+ }
2947
+ function learnedPatternsSection(cwd, knowledgeDir) {
2948
+ const candidates = [
2949
+ resolve8(cwd, "data", "knowledge", "learned-patterns.md"),
2950
+ join11(knowledgeDir, "learned-patterns.md")
2951
+ ];
2952
+ const path = candidates.find((p) => existsSync11(p));
2953
+ if (!path) return [];
2954
+ const sections = learnedPatternLeadIns(readFileSync9(path, "utf-8"));
2955
+ if (!sections.length) return [];
2956
+ const lines = ["", "## Learned patterns", "Grep the file for the full entry."];
2957
+ for (const section of sections) {
2958
+ lines.push(...wrap(`${section.heading}: ${section.items.join("; ")}`));
2959
+ }
2960
+ return lines;
2961
+ }
2962
+ function learnedPatternLeadIns(markdown) {
2963
+ const sections = [];
2964
+ let current = null;
2965
+ let bullet = null;
2966
+ const flush = () => {
2967
+ if (bullet !== null && current) {
2968
+ const match = /^\*\*([\s\S]+?)\*\*/.exec(bullet);
2969
+ if (match) current.items.push(collapse(match[1]));
2970
+ }
2971
+ bullet = null;
2972
+ };
2973
+ for (const raw of markdown.split("\n")) {
2974
+ const heading = /^#{2,}\s+(.+)$/.exec(raw);
2975
+ if (heading) {
2976
+ flush();
2977
+ current = { heading: heading[1].trim(), items: [] };
2978
+ sections.push(current);
2979
+ continue;
2980
+ }
2981
+ const start = /^[-*]\s+(.*)$/.exec(raw);
2982
+ if (start) {
2983
+ flush();
2984
+ bullet = start[1];
2985
+ continue;
2986
+ }
2987
+ if (bullet !== null) {
2988
+ if (raw.trim() === "") flush();
2989
+ else bullet += ` ${raw.trim()}`;
2990
+ }
2991
+ }
2992
+ flush();
2993
+ return sections.filter((s) => s.items.length > 0);
2994
+ }
2995
+ function namedArrays(content) {
2996
+ const found = [];
2997
+ for (const [key, value] of Object.entries(content)) {
2998
+ if (key === "summary" || key === "when_to_use") continue;
2999
+ if (!Array.isArray(value) || value.length === 0) continue;
3000
+ const items = value.filter(
3001
+ (v) => typeof v === "object" && v !== null && typeof v.name === "string"
3002
+ );
3003
+ if (items.length === value.length) found.push([key, items]);
3004
+ }
3005
+ return found;
3006
+ }
3007
+ function subItemLead(item) {
3008
+ const questions = item["questions"];
3009
+ if (Array.isArray(questions) && typeof questions[0] === "string") {
3010
+ return truncate(collapse(questions[0]));
3011
+ }
3012
+ const description = item["description"];
3013
+ if (typeof description === "string") return truncate(collapse(description));
3014
+ return "";
3015
+ }
3016
+ function collapse(text) {
3017
+ return text.replace(/\s+/g, " ").trim();
3018
+ }
3019
+ function truncate(text, limit = WRAP_COLUMN) {
3020
+ if (text.length <= limit) return text;
3021
+ const cut = text.slice(0, limit - 1);
3022
+ const lastSpace = cut.lastIndexOf(" ");
3023
+ return `${(lastSpace > limit / 2 ? cut.slice(0, lastSpace) : cut).trimEnd()}\u2026`;
3024
+ }
3025
+ function humanise(key) {
3026
+ const spaced = key.replace(/_/g, " ");
3027
+ return spaced.charAt(0).toUpperCase() + spaced.slice(1);
3028
+ }
3029
+ function wrap(text, width = WRAP_COLUMN, indent = " ", hanging = " ") {
3030
+ const words = collapse(text).split(" ").filter(Boolean);
3031
+ if (!words.length) return [];
3032
+ const out = [];
3033
+ let line = indent + words[0];
3034
+ for (const word of words.slice(1)) {
3035
+ if (line.length + 1 + word.length > width) {
3036
+ out.push(line);
3037
+ line = hanging + word;
3038
+ } else {
3039
+ line += ` ${word}`;
3040
+ }
3041
+ }
3042
+ out.push(line);
3043
+ return out;
3044
+ }
3045
+ function capLines(lines, maxLines) {
3046
+ if (lines.length <= maxLines) return lines;
3047
+ const kept = lines.slice(0, maxLines);
3048
+ kept[kept.length - 1] = `${kept[kept.length - 1]} \u2026`;
3049
+ return kept;
3050
+ }
2574
3051
  export {
2575
3052
  ALL_BUGS_COLUMNS,
2576
3053
  ALL_BUGS_MD_HEADER,
@@ -2590,6 +3067,7 @@ export {
2590
3067
  KnowledgeManifestSchema,
2591
3068
  KnowledgeManifestStatsSchema,
2592
3069
  KnowledgeReleaseSchema,
3070
+ LEGACY_SESSION_DIR_RE,
2593
3071
  LoadingStrategySchema,
2594
3072
  MobileAppConfigSchema,
2595
3073
  MobileDeviceConfigSchema,
@@ -2611,9 +3089,11 @@ export {
2611
3089
  appendSessionMetrics,
2612
3090
  appendSessionMetricsDeduped,
2613
3091
  buildManifestRegistry,
3092
+ buildTableRow,
2614
3093
  computeStats,
2615
3094
  containsSecrets,
2616
3095
  csvEscape,
3096
+ describeSessionDir,
2617
3097
  extractCoverage,
2618
3098
  extractListSection,
2619
3099
  extractReportMeta,
@@ -2624,9 +3104,11 @@ export {
2624
3104
  getPackageRoot,
2625
3105
  getPackageVersion,
2626
3106
  hasConfidentialityHeader,
3107
+ headersMatchColumns,
2627
3108
  listReleaseDirs,
2628
3109
  loadSessionForOutput,
2629
3110
  mergeGitignore,
3111
+ missingColumns,
2630
3112
  parseBugReport,
2631
3113
  parseMarkdownTable,
2632
3114
  parseSession,
@@ -2635,6 +3117,7 @@ export {
2635
3117
  readAllMetrics,
2636
3118
  readSessionIndex,
2637
3119
  redact,
3120
+ resolveDataDir,
2638
3121
  resolveDomainPath,
2639
3122
  resolveSessionDir,
2640
3123
  resolveSkillsSource,
@@ -2642,6 +3125,7 @@ export {
2642
3125
  runExplore,
2643
3126
  runInit,
2644
3127
  runKb,
3128
+ runKbDigest,
2645
3129
  runList,
2646
3130
  runReport,
2647
3131
  runValidate,