# AGENTS.md — AKAI Utils Development Guide ## Toolchain (mise) ```bash mise trust # trust the mise.toml config (first time only) mise install # installs go 1.26, node 22 mise run gopls # install gopls (Go LSP) — one-time dev setup ``` All build/run tasks are defined in `mise.toml`: ```bash mise run build # → ./akai-fetch 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 # 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 ``` Install golangci-lint: ```bash mise install golangci-lint # one-time setup golangci-lint run # comprehensive lint ``` ## Build & Run (manual) ```bash # Build Go binary (zero CGO) go build -buildvcs=false -o akai-fetch . # → ./akai-fetch # Build and run web server ./akai-fetch serve # → starts on free port, opens browser ./akai-fetch serve --host 0.0.0.0 -p 8080 # → Docker / network-accessible mode # Docker docker compose up --build # serves on :8080, binds 0.0.0.0 # Electron dev (cd electron && npm install) (cd electron && npx electron .) # Cross-compile for macOS (from Linux) GOOS=darwin GOARCH=arm64 go build -o akai-fetch-darwin-arm64 . GOOS=darwin GOARCH=amd64 go build -o akai-fetch-darwin-amd64 . ``` ## Architecture Single binary (`fetch`) with subcommands. No external Go dependencies — pure stdlib. ``` 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 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 ├── check-toolchain.sh verify gcc, brew, mise, go, node └── check-docker-toolchain.sh verify docker, compose, colima third_party/ Vendored akaiutil C binary (GPLv2) ``` ### Key patterns - **Subcommand dispatch**: `main.go:60` — switch on `os.Args[1]`, each case calls `cmdXxx(args)` - **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`. 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. ### akaiutil integration `extract.go` wraps akaiutil via stdin/stdout pipes — no bash intermediary. `scripts/check-toolchain.sh` and `check-docker-toolchain.sh` verify the dev environment. akaiutil is used for: - `df` — disk info (partitions, block counts) - `dir` — list volumes/files - `sample2wavall` — batch WAV extraction - Many more commands available (see `docs/akaiutil.md`) All akaiutil calls use `-r` (read-only) flag. Write operations (S900 compress, partitioning, tagging) require removing `-r`. ### macOS compatibility - `third_party/akaiutil/commoninclude.h` has `bcopy`/`bzero` declarations guarded with `#ifdef _VISUALCPC` to avoid conflicts with macOS system headers that define these in ``. ### Electron integration `electron/main.js` spawns the Go binary in `serve` mode: 1. Finds `akai-fetch` binary next to app or in `process.resourcesPath` 2. Spawns `akai-fetch serve -p 0 --no-browser` 3. Parses `stdout` for `Local: http://localhost:XXXX` to get port 4. Creates `BrowserWindow` pointing at that URL 5. Kills server on quit ## Adding a new feature 1. **New API endpoint**: add handler in `serve.go`, register in `cmdServe` mux 2. **New web UI section**: add HTML in `index.html`, CSS in `style.css`, JS in `app.js` 3. **New akaiutil wrapper**: create a bash script in `scripts/` or call akaiutil directly via `exec.Command` in Go 4. **New CLI subcommand**: add case in `main.go:60`, implement `cmdXxx(args)` function ### API conventions - All responses have `Content-Type: application/json` and `Access-Control-Allow-Origin: *` - Use `writeJSON(w, v)` for responses, it sets headers and marshals - Download progress uses SSE (`text/event-stream`) with `data: \n\n` - Error responses use `http.Error(w, msg, code)` or return JSON with `"error"` key ## Format conventions - Go: standard `gofmt` (no custom formatter) - Bash: `set -euo pipefail`, shellcheck-compatible - JS: no semicolons (ASI style), `const` preferred over `let` - CSS: CSS custom properties for theming (`:root { --bg: ... }`) ## Testing ```bash # Go go test -cover # unit tests (extract, serve, http, download, cli, util) go vet ./... # static analysis 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 None required. archive.org API is public and unauthenticated. AKAIUTIL environment variable controls the akaiutil binary path. ## Project Repo Git remote: `git@git.notsosm.art:david/akai-utils.git` Issues managed via `tea` CLI.