akai-utils/AGENTS.md

# 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              # go vet ./...
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, style.css, app.js)
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
- **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`
- **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

No test framework yet. Manual verification:
```bash
go build -o /dev/null .        # compile check
go vet ./...                   # static analysis
golangci-lint run              # comprehensive lint
./akai-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.