akai-utils/AGENTS.md

AGENTS.md — AKAI Utils Development Guide

Toolchain (mise)

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:

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:

mise install golangci-lint   # one-time setup
golangci-lint run            # comprehensive lint

Build & Run (manual)

# 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 <host-ip> 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 <strings.h>.

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: <json>\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

# 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.