From 7124b16fc164a5b9f2e973e506d1808f0de84da4 Mon Sep 17 00:00:00 2001 From: David Gwilliam Date: Mon, 22 Jun 2026 02:46:34 -0700 Subject: [PATCH] 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) --- .gitignore | 2 ++ AGENTS.md | 27 ++++++++++++----- README.md | 2 +- web/ui/app.js | 23 --------------- web/ui/util.js | 25 +++++++++++++++- web/ui/util.test.js | 72 ++++++++++++++++++++++++++++++++++++++++++++- 6 files changed, 118 insertions(+), 33 deletions(-) diff --git a/.gitignore b/.gitignore index 0ecb5b5..dc3a578 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,5 @@ web/ui/node_modules/ # Temp /tmp/ +akai-fetch.test +cover.out diff --git a/AGENTS.md b/AGENTS.md index 23ce31c..977c4de 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 `` 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 diff --git a/README.md b/README.md index 61e70b7..002e93b 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/web/ui/app.js b/web/ui/app.js index 675ffb4..6124a6f 100644 --- a/web/ui/app.js +++ b/web/ui/app.js @@ -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 => `
diff --git a/web/ui/util.js b/web/ui/util.js index a40a83c..c81ce90 100644 --- a/web/ui/util.js +++ b/web/ui/util.js @@ -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 } } \ No newline at end of file diff --git a/web/ui/util.test.js b/web/ui/util.test.js index 26b461b..4f6f173 100644 --- a/web/ui/util.test.js +++ b/web/ui/util.test.js @@ -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') + }) }) \ No newline at end of file