@follenfang/wowdoc 0.0.1

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 follenfang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# wowdoc
+
+`wowdoc` is a source-auditable CLI that gives coding agents versioned evidence from World of Warcraft UI source and supported AddOn repositories.
+
+```powershell
+npm install -g @follenfang/wowdoc
+wowdata init
+wowdoc query --source wow-ui-source --product retail --text C_AuctionHouse.GetItemSearchResultInfo
+```
+
+The npm package installs `wowdoc`, `wowdata`, and the user-level Skill at `~/.agents/skills/wowdoc`. Source mirrors, immutable objects, AST JSON, manifests, and WAL SQLite indexes live under `~/.wowdoc`.
+
+## Development
+
+```powershell
+go test ./...
+go run ./cmd/wowdoc --help
+go run ./cmd/wowdata --help
+npm pack --ignore-scripts
+```

package/bin/run.mjs

@@ -0,0 +1,20 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function run(name) {
+  const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+  const suffix = process.platform === "win32" ? ".exe" : "";
+  const executable = join(packageRoot, "native", name + suffix);
+  if (!existsSync(executable)) {
+    process.stderr.write(`${name}: native binary is missing; reinstall @follenfang/wowdoc\n`);
+    process.exit(4);
+  }
+  const child = spawnSync(executable, process.argv.slice(2), { stdio: "inherit", windowsHide: true });
+  if (child.error) {
+    process.stderr.write(`${name}: ${child.error.message}\n`);
+    process.exit(4);
+  }
+  process.exit(child.status ?? 1);
+}

package/bin/wowdata.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "./run.mjs";
+run("wowdata");

package/bin/wowdoc.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "./run.mjs";
+run("wowdoc");

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@follenfang/wowdoc",
+  "version": "0.0.1",
+  "description": "Auditable WoW UI source intelligence CLI for coding agents",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/follenfang/wowdoc.git"
+  },
+  "bin": {
+    "wowdoc": "bin/wowdoc.mjs",
+    "wowdata": "bin/wowdata.mjs"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install.mjs",
+    "test": "go test ./...",
+    "prepack": "node scripts/check-package.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/scripts/check-package.mjs

@@ -0,0 +1,4 @@
+import { existsSync } from "node:fs";
+for (const path of ["bin/wowdoc.mjs", "bin/wowdata.mjs", "scripts/install.mjs", "skill/SKILL.md"]) {
+  if (!existsSync(new URL(`../${path}`, import.meta.url))) throw new Error(`package file missing: ${path}`);
+}

package/scripts/evaluate-quality.mjs

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const root = resolve(import.meta.dirname, "..");
+const scenarios = JSON.parse(readFileSync(join(root, "quality", "scenarios.json"), "utf8"));
+const home = process.env.WOWDOC_HOME;
+if (!home) throw new Error("WOWDOC_HOME is required so quality data stays isolated");
+const suffix = process.platform === "win32" ? ".exe" : "";
+const wowdoc = process.env.WOWDOC_BIN || join(root, "dist", "wowdoc" + suffix);
+if (!existsSync(wowdoc)) throw new Error(`wowdoc binary not found: ${wowdoc}`);
+
+const listCache = new Map();
+const results = [];
+for (const [index, scenario] of scenarios.entries()) {
+  const listKey = `${scenario.source}:${scenario.product}`;
+  let sourceList = listCache.get(listKey);
+  if (!sourceList) {
+    sourceList = runJSON(["source", "list", "--source", scenario.source, "--product", scenario.product]);
+    listCache.set(listKey, sourceList);
+  }
+  const tags = sourceList.data?.tags ?? [];
+  let ref = scenario.ref ?? "latest";
+  if (Number.isInteger(scenario.tagIndex)) {
+    if (tags.length === 0) {
+      results.push(failedWithoutQuery(scenario, "no catalog Tag is available for this product branch"));
+      continue;
+    }
+    const selected = tags[Math.min(scenario.tagIndex, tags.length - 1)];
+    ref = selected.name ?? selected.Name;
+  }
+  process.stderr.write(`[${index + 1}/${scenarios.length}] ${scenario.id} ref=${ref}\n`);
+  let envelope = runJSON(queryArgs(scenario, ref), true);
+  if (!envelope.ok && envelope.error?.code === "snapshot_not_ready") {
+    const build = runJSON(["index", "build", "--source", scenario.source, "--product", scenario.product, "--ref", ref], true, 30 * 60 * 1000);
+    if (!build.ok) {
+      results.push(failedWithoutQuery(scenario, `index build failed: ${build.error?.code ?? "unknown"}`, ref));
+      continue;
+    }
+    envelope = runJSON(queryArgs(scenario, ref), true);
+  }
+  results.push(evaluate(scenario, ref, envelope));
+}
+
+const summary = summarize(results);
+const artifact = { schema: "wowdoc.quality.v1", generatedAt: new Date().toISOString(), home, summary, results };
+mkdirSync(join(root, "quality"), { recursive: true });
+writeFileSync(join(root, "quality", "results.json"), JSON.stringify(artifact, null, 2));
+writeFileSync(join(root, "quality", "report.md"), markdown(artifact));
+process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+process.exit(summary.passed === summary.total ? 0 : 1);
+
+function queryArgs(s, ref) {
+  return ["query", "--source", s.source, "--product", s.product, "--ref", ref, "--topic", s.topic, "--text", s.query, "--limit", "5"];
+}
+function runJSON(args, allowFailure = false, timeout = 120000) {
+  const child = spawnSync(wowdoc, args, { cwd: root, env: process.env, encoding: "utf8", timeout, windowsHide: true });
+  let parsed;
+  try { parsed = JSON.parse(child.stdout); } catch { parsed = { ok: false, error: { code: "invalid_json", message: child.stdout || child.stderr } }; }
+  if (!allowFailure && (!parsed.ok || child.status !== 0)) throw new Error(`${args.join(" ")}: ${child.stderr || child.stdout}`);
+  return parsed;
+}
+function evaluate(scenario, ref, envelope) {
+  const top = envelope.data?.results?.[0];
+  if (!envelope.ok || !top) return failedWithoutQuery(scenario, envelope.error?.code ?? "no top reference", ref);
+  const expectedName = scenario.expectedName.toLowerCase();
+  const correctness = (top.name ?? "").toLowerCase() === expectedName || top.excerpt.toLowerCase().includes(expectedName);
+  const relevance = top.path.toLowerCase().includes(scenario.expectedPath.toLowerCase());
+  const contextComplete = scenario.context.every(term => top.excerpt.toLowerCase().includes(term.toLowerCase()));
+  const version = envelope.data.resolvedCommit && envelope.data.resolvedCommit.length === 40;
+  const integrity = verifyGitEvidence(scenario.source, envelope.data.resolvedCommit, top);
+  const dimensions = { correctness, relevance, contextComplete, version, traceability: integrity.ok };
+  const score = Object.values(dimensions).filter(Boolean).length * 20;
+  return { id: scenario.id, question: scenario.question, source: scenario.source, product: scenario.product, ref, query: scenario.query, resolvedCommit: envelope.data.resolvedCommit, matchedTag: envelope.data.matchedTag, top, dimensions, score, passed: score === 100, evidenceDiagnostic: integrity.message };
+}
+function verifyGitEvidence(source, commit, top) {
+  try {
+    const mirror = join(home, "repositories", source + ".git");
+    const blob = execFileSync("git", ["--git-dir", mirror, "show", `${commit}:${top.path}`], { encoding: "buffer", maxBuffer: 64 * 1024 * 1024 });
+    const hash = createHash("sha256").update(blob).digest("hex");
+    if (hash !== top.contentHash) return { ok: false, message: "content hash differs from Git blob" };
+    const lines = blob.toString("utf8").split(/\r?\n/);
+    for (const row of top.excerpt.split("\n")) {
+      const match = row.match(/^(\d+): (.*)$/s);
+      if (!match || lines[Number(match[1]) - 1] !== match[2]) return { ok: false, message: `excerpt differs at ${match?.[1] ?? "unknown line"}` };
+    }
+    return { ok: true, message: "path, line, excerpt and SHA-256 match the resolved Commit blob" };
+  } catch (error) { return { ok: false, message: String(error.message ?? error) }; }
+}
+function failedWithoutQuery(scenario, reason, ref = scenario.ref ?? null) {
+  return { id: scenario.id, question: scenario.question, source: scenario.source, product: scenario.product, ref, query: scenario.query, dimensions: { correctness:false,relevance:false,contextComplete:false,version:false,traceability:false }, score: 0, passed: false, evidenceDiagnostic: reason };
+}
+function summarize(items) {
+  const dimensions = ["correctness","relevance","contextComplete","version","traceability"];
+  const summary = { total: items.length, passed: items.filter(x=>x.passed).length, averageScore: Math.round(items.reduce((n,x)=>n+x.score,0)/items.length), dimensions: {} };
+  for (const name of dimensions) summary.dimensions[name] = items.filter(x=>x.dimensions[name]).length;
+  summary.failed = summary.total - summary.passed;
+  return summary;
+}
+function markdown(artifact) {
+  const s=artifact.summary;const rows=["# wowdoc code-reference quality report","",`Generated: ${artifact.generatedAt}`,"",`Strict pass: ${s.passed}/${s.total}; average score: ${s.averageScore}/100.`,"",`Dimensions: correctness ${s.dimensions.correctness}/${s.total}, relevance ${s.dimensions.relevance}/${s.total}, context completeness ${s.dimensions.contextComplete}/${s.total}, version ${s.dimensions.version}/${s.total}, traceability ${s.dimensions.traceability}/${s.total}.`,"","| ID | Product | Ref | Score | Top reference | Result |","| --- | --- | --- | ---: | --- | --- |"];for(const item of artifact.results){const top=item.top?`${item.top.path}:${item.top.line}`:item.evidenceDiagnostic;rows.push(`| ${item.id} | ${item.source}/${item.product} | ${item.ref??""} | ${item.score} | ${String(top).replaceAll("|","\\|")} | ${item.passed?"PASS":"REVIEW"} |`)};rows.push("","A strict pass requires the first code reference to match the expected fact and subsystem, include the required answer context, resolve to an immutable Commit, and reproduce the exact Git blob bytes at the reported path and lines.","");return rows.join("\n")
+}

package/scripts/install.mjs

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const suffix = process.platform === "win32" ? ".exe" : "";
+const platformNames = {
+  "linux-x64": "linux-amd64",
+  "linux-arm64": "linux-arm64",
+  "win32-x64": "windows-amd64",
+  "darwin-x64": "darwin-amd64",
+  "darwin-arm64": "darwin-arm64",
+};
+const platform = platformNames[`${process.platform}-${process.arch}`];
+if (!platform) throw new Error(`unsupported_platform: ${process.platform}-${process.arch}`);
+const nativeDir = join(root, "native");
+mkdirSync(nativeDir, { recursive: true });
+
+for (const name of ["wowdoc", "wowdata"]) {
+  const target = join(nativeDir, name + suffix);
+  const supplied = process.env.WOWDOC_BINARY_DIR && join(process.env.WOWDOC_BINARY_DIR, name + suffix);
+  if (supplied && existsSync(supplied)) {
+    cpSync(supplied, target);
+  } else if (existsSync(join(root, "go.mod"))) {
+    execFileSync("go", ["build", "-trimpath", "-ldflags", `-s -w -X github.com/follenfang/wowdoc/internal/app.Version=${pkg.version}`, "-o", target, `./cmd/${name}`], { cwd: root, stdio: "inherit" });
+  } else {
+    const asset = `${name}-${platform}${suffix}`;
+    const url = `https://github.com/follenfang/wowdoc/releases/download/v${pkg.version}/${asset}`;
+    const response = await fetch(url, { redirect: "follow" });
+    if (!response.ok) throw new Error(`binary_download_failed: ${response.status} ${url}`);
+    writeFileSync(target, Buffer.from(await response.arrayBuffer()));
+  }
+  if (process.platform !== "win32") chmodSync(target, 0o755);
+}
+
+const skillSource = join(root, "skill");
+const skillTarget = join(homedir(), ".agents", "skills", "wowdoc");
+const manifestPath = join(skillTarget, ".wowdoc-manifest.json");
+const incoming = files(skillSource);
+let modified = false;
+if (existsSync(manifestPath)) {
+  const previous = JSON.parse(readFileSync(manifestPath, "utf8"));
+  modified = Object.entries(previous.files ?? {}).some(([path, expected]) => {
+    const current = join(skillTarget, path);
+    return !existsSync(current) || hash(readFileSync(current)) !== expected;
+  });
+}
+if (modified) {
+  const sideBySide = `${skillTarget}.update-${pkg.version}`;
+  rmSync(sideBySide, { recursive: true, force: true });
+  cpSync(skillSource, sideBySide, { recursive: true });
+  writeManifest(sideBySide, incoming);
+  process.stderr.write(`wowdoc: existing Skill was modified; update installed at ${sideBySide}\n`);
+} else {
+  rmSync(skillTarget, { recursive: true, force: true });
+  cpSync(skillSource, skillTarget, { recursive: true });
+  writeManifest(skillTarget, incoming);
+}
+
+function files(directory) {
+  const output = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) output.push(...files(path));
+    else output.push(path);
+  }
+  return output;
+}
+function hash(buffer) { return createHash("sha256").update(buffer).digest("hex"); }
+function writeManifest(target, sourceFiles) {
+  const mapped = {};
+  for (const source of sourceFiles) mapped[relative(skillSource, source).replaceAll("\\", "/")] = hash(readFileSync(source));
+  writeFileSync(join(target, ".wowdoc-manifest.json"), JSON.stringify({ package: pkg.name, version: pkg.version, files: mapped }, null, 2));
+}

package/skill/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: wowdoc
+description: Use wowdoc when an Agent needs versioned World of Warcraft UI or supported AddOn source evidence, API definitions, XML templates, TOC metadata, assets, compatibility checks, or source diffs.
+---
+
+# wowdoc
+
+Translate the user's wording into explicit `source`, `product`, `ref`, `topic`, and query terms using the references in this Skill. The CLI is the source reader; do not infer code facts from this document.
+
+1. Run `wowdoc source list --source SOURCE --product PRODUCT` when source, product, or available versions are uncertain.
+2. Prefer an exact displayed plugin version. The CLI maps it only to an exact Tag and immutable Commit.
+3. Use one read command: `query` for a focused question, `explore` for a subsystem, `inspect` for a known symbol/path, `diff` for two versions, or `validate` for a local AddOn.
+4. If the CLI returns `snapshot_not_ready`, run only the listed `source sync` and `index build|refresh` steps, then retry the original read command.
+5. If an exact plugin version returns `version_not_found`, keep the same source and product, run `source check`, synchronize and refresh if needed, then query `latest`. Mark the answer with `requestedVersion`, `matchedTag=null`, `resolutionMode=latest_fallback`, product branch, resolved Commit, and state that the evidence is from latest rather than the requested version.
+6. Do not apply latest fallback to `ambiguous_version`, `unsupported_build`, `ref_not_found`, or update failures.
+7. Cite `sourceId`, product, Tag when present, resolved Commit, path, line, and the returned excerpt. Treat `dynamic-unresolved` edges as unresolved, not exact.
+
+Read [source-catalog.md](references/source-catalog.md) for source/product names and [commands.md](references/commands.md) for command selection.

package/skill/references/commands.md

@@ -0,0 +1,18 @@
+# Command selection
+
+```text
+wowdoc query   --source SOURCE --product PRODUCT --ref REF --topic TOPIC --text TERM --limit 10
+wowdoc explore --source SOURCE --product PRODUCT --ref REF --topic TOPIC --text TERM --limit 25
+wowdoc inspect --source SOURCE --product PRODUCT --ref REF --symbol QUALIFIED_NAME
+wowdoc inspect --source SOURCE --product PRODUCT --ref REF --path REPOSITORY_PATH
+wowdoc diff    --source SOURCE --product PRODUCT --from REF --to REF
+wowdoc validate --path ADDON_DIR --source SOURCE --product PRODUCT --ref REF
+wowdoc source list  --source SOURCE --product PRODUCT
+wowdoc source check --source SOURCE --product PRODUCT
+wowdoc source sync  --source SOURCE --product PRODUCT
+wowdoc index build  --source SOURCE --product PRODUCT --ref REF
+wowdoc index refresh --source SOURCE --product PRODUCT --ref REF
+wowdoc index status --source SOURCE --product PRODUCT
+```
+
+Use exact qualified identifiers when known. For natural-language questions, select a topic and use the narrowest stable identifier, event, template, TOC field, asset path, or API name present in the question. Prefer results marked `exact_symbol`; verify relationship confidence and retain the returned excerpt as evidence.

package/skill/references/source-catalog.md

@@ -0,0 +1,14 @@
+# Source catalog
+
+| Source | Product | Branch | Notes |
+| --- | --- | --- | --- |
+| `wow-ui-source` | `retail` | `live` | Official generated API and FrameXML |
+| `wow-ui-source` | `ptr`, `ptr2`, `beta` | matching channel | Channel is separate from build |
+| `wow-ui-source` | `classic`, `classic-ptr`, `classic-beta` | matching classic channel | Do not infer compatibility from branch name |
+| `wow-ui-source` | `classic-era`, `classic-era-ptr`, `anniversary`, `titan` | matching channel | Titan is its own product |
+| `elvui` | `main`, `ptr` | matching branch | Version input such as `15.18` maps exactly to Tag `v15.18` |
+| `weakauras` | `main` | `main` | Current source supports its declared TOCs; check the selected snapshot |
+| `ndui` | `main`, `classic`, `era`, `anniversary`, `titan` | `master`, `Classic`, `Era`, `Anniversary`, `Titan` | Tags are filtered by product branch reachability and product-line rule |
+| `ellesmereui` | `main` | `main` | Retail-oriented suite; version input maps to `v` Tag |
+
+The version truth is `Tag -> Commit -> source snapshot`. Release attachments and packaged externals can differ from Tag source; describe evidence as Tag source, not an installed package reconstruction.