docs: update AGENTS.md and README for new features, add JS tests

Docs: - AGENTS.md: updated toolchain section with js-lint/js-test tasks, expanded web/ui/ directory listing, added event delegation and Web Audio API to key patterns, updated testing section - README: marked issue #9 (Audio Preview Player) as done - .gitignore: added akai-fetch.test and cover.out Tests: - Moved groupWavs and cleanName to util.js (pure functions) - Added 10 new JS tests: 6 groupWavs, 4 cleanName - Total JS tests: 29 (up from 19)
2026-06-22 02:46:34 -07:00
parent e0bad5e5ac
commit 7124b16fc1
6 changed files with 118 additions and 33 deletions
@@ -30,3 +30,5 @@ web/ui/node_modules/

 # Temp
 /tmp/
+akai-fetch.test
+cover.out
@@ -16,7 +16,9 @@ mise run serve             # → starts HTTP server, opens browser
 mise run electron-deps     # installs electron + electron-builder
 mise run electron-dev      # runs electron in dev mode
 mise run docker-up         # docker compose up --build
-mise run lint              # go vet ./...
+mise run lint              # golangci-lint run (Go)
+mise run js-lint            # eslint (JS)
+mise run js-test            # node --test (JS)
 mise run check-all         # verify gcc, brew, mise, go, node, docker, colima
 ```

@@ -55,7 +57,14 @@ Single binary (`fetch`) with subcommands. No external Go dependencies — pure s
 ```
 main.go        CLI entry, commands (search/list/download/extract/pipeline/serve)
 serve.go       HTTP server + REST API + embedded web UI (embed.FS)
-web/ui/        Static frontend (index.html, style.css, app.js)
+web/ui/        Static frontend
+  ├── index.html              HTML layout
+  ├── style.css               CSS custom properties theme
+  ├── util.js                 shared utility functions
+  ├── app.js                  application logic, event delegation
+  ├── util.test.js            JS tests (node --test)
+  ├── eslint.config.js        ESLint flat config
+  └── package.json            ESLint + test scripts
 electron/      Electron wrapper shell
 scripts/       Bash helpers called via exec
  ├── extract_wavs.sh            batch WAV extraction via akaiutil
@@ -70,8 +79,9 @@ third_party/   Vendored akaiutil C binary (GPLv2)
 - **Flag parsing**: each command creates its own `flag.NewFlagSet` — avoids global flag state
 - **Concurrency**: semaphore channel pattern (`sem := make(chan struct{}, N)`) for bounded parallelism
 - **SSE progress**: `serve.go:handleProgress` — 500ms ticker, EventSource stream, auto-closes when all done
+- **Event delegation**: `app.js` — single click listener on document, dispatches by `[data-action]` attribute (download, list, play)
 - **akaiutil wrapper**: `extract.go` — persistent stdin/stdout pipes, no bash intermediary
- **Zero-deps web UI**: vanilla JS, no bundler, no framework. API calls use `fetch()` + `EventSource`
+- **Zero-deps web UI**: vanilla JS, no bundler, no framework. API calls use `fetch()` + `EventSource`. Web Audio API for WAV playback.
 - **Embed directive**: `//go:embed web/ui/*` in `serve.go` — frontend baked into the binary
 - **Bind address handling**: `serve.go:37` — `--host` flag defaults to `127.0.0.1` for local dev; set `--host 0.0.0.0` for Docker. When binding to `0.0.0.0`, prints both `localhost` and `<host-ip>` URLs for clarity.

@@ -124,12 +134,15 @@ All akaiutil calls use `-r` (read-only) flag. Write operations (S900 compress, p

 ## Testing

-No test framework yet. Manual verification:
 ```bash
-go build -o /dev/null .        # compile check
+# Go
+go test -cover                  # unit tests (extract, serve, http, download, cli, util)
 go vet ./...                   # static analysis
-golangci-lint run              # comprehensive lint
-./akai-fetch serve              # manual smoke test
+golangci-lint run              # comprehensive lint (uses .golangci.yml)
+
+# JavaScript
+mise run js-test               # node --test (19 tests: esc, sanitize, formatBytes, formatTime)
+mise run js-lint               # eslint (flat config)
 ```

 ## Secrets & Tokens
@@ -110,7 +110,7 @@ See [open issues](https://git.notsosm.art/david/akai-utils/issues).
 | #6 | Direct-to-Disk Take Extraction | todo |
 | #7 | TAR Bulk Import/Export | todo |
 | #8 | Sample Tag Editor | todo |
-| #9 | Audio Preview Player | todo |
+| #9 | Audio Preview Player | done |

 ## License

@@ -200,29 +200,6 @@ let animationFrame = null;

 document.getElementById('wav-browse-btn').addEventListener('click', browseWavs);

-function groupWavs(paths) {
-  const libs = {};
-  for (const p of paths) {
-    const parts = p.split('/');
-    let lib, prog, file;
-    if (parts.length === 1) {
-      file = parts[0];
-    } else if (parts.length === 2) {
-      lib = parts[0]; prog = parts[0]; file = parts[1];
-    } else {
-      lib = parts[0]; prog = parts[1]; file = parts[parts.length - 1];
-    }
-    if (!libs[lib]) libs[lib] = {};
-    if (!libs[lib][prog]) libs[lib][prog] = [];
-    libs[lib][prog].push({ fullPath: p, name: file.replace(/\.wav$/i, '') });
-  }
-  return libs;
-}
-
-function cleanName(name) {
-  return name.replace(/_+/g, ' ').trim();
-}
-
 function renderSampleCards(samples) {
  return samples.map(s => `
    <div class="sample-card" data-action="play" data-wav="${esc(s.fullPath)}">
@@ -24,6 +24,29 @@ function formatTime(secs) {
  return m + ':' + s.toString().padStart(2, '0')
 }

+function groupWavs(paths) {
+  const libs = {}
+  for (const p of paths) {
+    const parts = p.split('/')
+    let lib, prog, file
+    if (parts.length === 1) {
+      lib = ''; prog = parts[0]; file = parts[0]
+    } else if (parts.length === 2) {
+      lib = parts[0]; prog = parts[0]; file = parts[1]
+    } else {
+      lib = parts[0]; prog = parts[1]; file = parts[parts.length - 1]
+    }
+    if (!libs[lib]) libs[lib] = {}
+    if (!libs[lib][prog]) libs[lib][prog] = []
+    libs[lib][prog].push({ fullPath: p, name: file.replace(/\.wav$/i, '') })
+  }
+  return libs
+}
+
+function cleanName(name) {
+  return name.replace(/_+/g, ' ').trim()
+}
+
 if (typeof module !== 'undefined' && module.exports) {
-  module.exports = { esc, sanitize, formatBytes, formatTime }
+  module.exports = { esc, sanitize, formatBytes, formatTime, groupWavs, cleanName }
 }
@@ -1,6 +1,6 @@
 const { describe, it } = require('node:test')
 const assert = require('node:assert/strict')
-const { esc, sanitize, formatBytes, formatTime } = require('./util.js')
+const { esc, sanitize, formatBytes, formatTime, groupWavs, cleanName } = require('./util.js')

 describe('esc', () => {
  it('escapes HTML entities', () => {
@@ -88,4 +88,74 @@ describe('formatTime', () => {
  it('formats large times', () => {
    assert.strictEqual(formatTime(3661), '61:01')
  })
+})
+
+describe('groupWavs', () => {
+  it('groups by library and program', () => {
+    const paths = [
+      'LibA/Prog1/kick.wav',
+      'LibA/Prog1/snare.wav',
+      'LibA/Prog2/hat.wav'
+    ]
+    const result = groupWavs(paths)
+    assert.strictEqual(Object.keys(result).length, 1)
+    assert.strictEqual(Object.keys(result.LibA).length, 2)
+    assert.strictEqual(result.LibA.Prog1.length, 2)
+    assert.strictEqual(result.LibA.Prog2.length, 1)
+  })
+
+  it('handles multiple libraries', () => {
+    const paths = [
+      'LibA/kick.wav',
+      'LibB/snare.wav'
+    ]
+    const result = groupWavs(paths)
+    assert.strictEqual(Object.keys(result).length, 2)
+    assert.strictEqual(result.LibA.LibA[0].name, 'kick')
+    assert.strictEqual(result.LibB.LibB[0].name, 'snare')
+  })
+
+  it('strips .wav extension case-insensitively', () => {
+    const paths = ['Lib/Prog/KICK.WAV']
+    const result = groupWavs(paths)
+    assert.strictEqual(result.Lib.Prog[0].name, 'KICK')
+  })
+
+  it('handles deeply nested paths', () => {
+    const paths = ['A/B/C/D/file.wav']
+    const result = groupWavs(paths)
+    assert.strictEqual(result.A.B.length, 1)
+    assert.strictEqual(result.A.B[0].name, 'file')
+    assert.strictEqual(result.A.B[0].fullPath, 'A/B/C/D/file.wav')
+  })
+
+  it('handles flat paths with no directory', () => {
+    const paths = ['sound.wav']
+    const result = groupWavs(paths)
+    assert.strictEqual(Object.keys(result).length, 1)
+    assert.strictEqual(Object.keys(result['']).length, 1)
+  })
+
+  it('returns empty object for empty input', () => {
+    const result = groupWavs([])
+    assert.strictEqual(Object.keys(result).length, 0)
+  })
+})
+
+describe('cleanName', () => {
+  it('replaces underscores with spaces', () => {
+    assert.strictEqual(cleanName('hello_world'), 'hello world')
+  })
+
+  it('collapses multiple underscores', () => {
+    assert.strictEqual(cleanName('AMG_-_Black__II'), 'AMG - Black II')
+  })
+
+  it('trims leading/trailing spaces from underscores', () => {
+    assert.strictEqual(cleanName('_padded_'), 'padded')
+  })
+
+  it('preserves regular text', () => {
+    assert.strictEqual(cleanName('Kick Drum'), 'Kick Drum')
+  })
 })