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

All build/run tasks are defined in mise.toml:

mise run build             # → ./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              # go vet ./...

Build & Run (manual)

# Build Go binary (zero CGO)
go build -buildvcs=false -o fetch .   # → ./fetch

# Build and run web server
./fetch serve          # → starts on free port, opens browser

# Docker
docker compose up --build    # serves on :8080

# Electron dev
(cd electron && npm install)
(cd electron && npx electron .)

# Cross-compile for macOS (from Linux)
GOOS=darwin GOARCH=arm64 go build -o fetch-darwin-arm64 .
GOOS=darwin GOARCH=amd64 go build -o 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.go       HTTP server + REST API + embedded web UI (embed.FS)
web/ui/        Static frontend (index.html, style.css, app.js)
electron/      Electron wrapper shell
scripts/       Bash helpers called via exec
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
• Script discovery: serve.go:findScript() — tries multiple candidate paths, fallback chain
• Zero-deps web UI: vanilla JS, no bundler, no framework. API calls use fetch() + EventSource
• Embed directive: //go:embed web/ui/* in serve.go — frontend baked into the binary

akaiutil integration

scripts/extract_wavs.sh shells out to akaiutil 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.

Electron integration

electron/main.js spawns the Go binary in serve mode:

1. Finds fetch binary next to app or in process.resourcesPath
2. Spawns 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

No test framework yet. Manual verification:

go build -o /dev/null .   # compile check
./fetch serve              # manual smoke test

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.