WA-Editing

WA-Editing is an Agent-friendly CLI and Codex Skill for editing and optimizing WeakAuras.lua without guessing which WeakAuras or WoW source applies.

It reads the user's installed WeakAuras TOC and XML/Lua load order, asks wowdoc for immutable WeakAuras and Blizzard source evidence, converts WeakAuras.lua to/from !WA:2!, captures objective performance evidence, and validates edits with a uv-pinned Python 3.12 runtime and managed Lua 5.1 compiler.

Install

npm install --global @follenfang/wa-editing
wa-editing setup --json

setup uses uv to install the pinned Python 3.12.12, explicitly creates ~/.wa-editing/runtime/.venv with uv venv, and then synchronizes the frozen lock into that environment. Venv creation and synchronization disable implicit Python downloads. Python commands run only through the verified managed venv; a system Python fallback is not used.

@follenfang/wowdoc is an npm dependency. WA-Editing invokes the public wowdoc command by prepending its own node_modules/.bin to the child PATH and then preserving the user's PATH.

Main commands

wa-editing install
wa-editing update
wa-editing setup
wa-editing doctor

wa-editing source resolve --help
wa-editing aura --help
wa-editing performance --help
wa-editing hooks install --help

Resolve a real installation from SavedVariables:

wa-editing source resolve --json `
  --saved-variables "D:\World of Warcraft\_classic_era_\WTF\Account\ACCOUNT\SavedVariables\WeakAuras.lua" `
  --product classic-era

Or provide the installation and AddOn paths directly:

wa-editing source resolve --json `
  --wow-path "D:\World of Warcraft\_classic_era_" `
  --wa-addon-path "D:\World of Warcraft\_classic_era_\Interface\AddOns\WeakAuras" `
  --product classic-era `
  --wow-build "<installed-build-or-commit>"

If the installed TOC contains @project-version@, provide another installed artifact when available:

wa-editing source resolve --json `
  --wa-addon-path "D:\path\Interface\AddOns\WeakAuras" `
  --product classic-era `
  --wa-metadata "D:\path\Interface\AddOns\WeakAuras\Init.lua" `
  --error-log "D:\path\WowError.txt"

Version evidence is evaluated as installed TOC, installed metadata, error log, explicit --wa-version, then main. Product evidence is evaluated as explicit product, installation path, client build metadata, --wow-build, then Interface inference.

Validate against the generated immutable receipt:

wa-editing aura validate --json `
  --weakauras-lua "D:\path\WeakAuras.lua" `
  --aura-id "My Aura" `
  --receipt "C:\Users\me\.wa-editing\state\resolutions\<hash>.json" `
  --create-backup

Encode one Aura or group as one import string:

wa-editing aura encode --json `
  --input "D:\path\WeakAuras.lua" `
  --id "My Aura" `
  --include-children `
  --output "D:\exports\aura.txt" `
  --client-version classic-era

Decode an import string:

wa-editing aura decode --json `
  --input "D:\path\aura.txt" `
  --output "D:\exports\aura.lua" `
  --client-version retail

Split a large SavedVariables file into one !WA:2! file per top-level Aura tree plus an ordered manifest:

wa-editing aura split --json `
  --input "D:\path\WeakAuras.lua" `
  --top-level `
  --output-dir "D:\exports\auras" `
  --client-version classic-era

Use --children-of <id>, repeated --id <id>, --top-level, or --all-displays to select split outputs. Split creates WA import strings, not editable Lua source files.

Performance evidence

The Skill owns performance hypotheses and behavior-aware edits. The CLI records facts without assigning scores, severity, diagnoses, or automatic fixes. Performance work is report-first: the Agent investigates, presents evidence and the exact proposed change, then waits for explicit confirmation before writing the Aura.

wa-editing performance snapshot --json `
  --weakauras-lua "D:\work\WeakAuras.lua" `
  --aura-id "My Aura" `
  --receipt "C:\Users\me\.wa-editing\state\resolutions\<hash>.json" `
  --output "D:\work\before.json"

wa-editing performance diff --json `
  --snapshot "D:\work\before.json" `
  --weakauras-lua "D:\work\WeakAuras.lua" `
  --receipt "C:\Users\me\.wa-editing\state\resolutions\<hash>.json" `
  --output "D:\work\diff.json"

wa-editing performance profile --json `
  --input "D:\work\profile-input.json" `
  --output "D:\work\profile-summary.json"

Profile summaries report elapsed time, spike, share, and average only when a distinct cumulative calls value exists. Native WeakAuras count is an active nesting balance, not a call counter; non-zero means the profile is incomplete.

Compatibility aliases

Existing scripts continue to work: resolve maps to source resolve, validate maps to aura validate, install-hooks maps to hooks install, and legacy convert --mode ... --granularity ... maps to the corresponding aura encode, aura decode, or aura split behavior.

Source and runtime ownership

The three dimensions stay separate:

1. WeakAuras version selects a WeakAuras release tag, immutable commit, and snapshot.
2. WoW product/build selects the Blizzard wow-ui-source product branch and immutable commit.
3. Installed TOC selects the actual flavor-specific file list and XML/Lua load graph present on the user's machine.

The receipt distinguishes the exactness of each dimension. An exact WeakAuras tag does not make the combined environment exact when the WoW build is missing or the product came only from Interface inference; inspect missingInputs, confidence, and match.

Cache layout:

~/.wowdoc/
  Git mirrors, refs, snapshots, source indexes, and query data

~/.wa-editing/
  runtime/       explicit uv venv using managed Python 3.12.12
  toolchains/    managed Lua 5.1 luac
  state/         setup and resolution receipts plus backups
  logs/
  tmp/

WA-Editing does not clone WeakAuras or Blizzard repositories and does not create ~/.wa-editing/sources.

Agent workflow

The installed $wa-editing Skill enforces this order:

1. doctor, then setup when needed.
2. source resolve the installed TOC and immutable source context.
3. Read the relevant installed load-graph files and receipt evidence.
4. Detect a live WTF file and running WoW process; defer any close/edit prompt until a write is approved.
5. For performance work, capture a lossless performance snapshot.
6. Run baseline aura validate read-only.
7. Report source identities, observed behavior, candidate hotspots, measured versus static evidence, the exact proposed edit, behavior invariants, risks, and the validation/rollback plan.
8. Stop and wait for explicit confirmation of that report; the initial optimization request is not edit approval.
9. Recheck the input hash and receipt, create the backup, then apply the confirmed narrow behavior-preserving edit. Drift requires a refreshed report.
10. Run aura validate and performance diff against the same receipt.
11. Optionally summarize supplied runtime measurements with performance profile.

Passing luac proves only Lua 5.1 syntax; it is not sufficient by itself to prove WeakAuras or Blizzard correctness.

Development

npm install
npm test
npm pack --dry-run

Repository: https://github.com/Follen/WA-Editing

npm: https://www.npmjs.com/package/@follenfang/wa-editing