2026-06-22 02:48:06 +00:00
2 changed files with 220 additions and 0 deletions
@@ -0,0 +1,121 @@
+# 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
+```
+
+All build/run tasks are defined in `mise.toml`:
+
+```bash
+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)
+
+```bash
+# 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:
+```bash
+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.
@@ -0,0 +1,99 @@
+# AKAI Utils
+
+AKAI sampler toolkit — search, download, browse, extract, and package AKAI S900/S950/S1000/S1100/S3000/CD3000 sample libraries.
+
+Two interfaces:
+- **CLI** (`akai-fetch`) — search archive.org, download ISOs, extract WAVs
+- **Web UI / Electron** — full visual browser with disk inspection, sample preview, and disk packaging
+
+## Quickstart
+
+### Toolchain (mise)
+```bash
+mise trust        # first time only
+mise install      # installs go 1.26, node 22
+mise run build    # → ./fetch
+```
+
+### Docker
+```bash
+docker compose up --build
+# Open http://localhost:8080
+```
+
+### Build from source
+```bash
+# CLI
+mise run build
+./fetch search --filter vocal
+
+# Web server
+mise run serve
+# Open http://localhost:8080
+
+# Electron (macOS)
+mise run electron-deps
+mise run electron-build-mac
+```
+
+### CLI Usage
+```
+akai-fetch search [flags]          search archive.org for AKAI sampler ISOs
+akai-fetch list <identifier>       list downloadable ISO files in an item
+akai-fetch download [flags]        download ISOs from archive.org
+akai-fetch extract [flags]         extract WAVs from downloaded ISOs
+akai-fetch pipeline [flags]        search → download → extract in one command
+akai-fetch serve [flags]           start HTTP server with web UI
+```
+
+## Architecture
+
+```
+fetch serve (Go HTTP server, embedded web UI)
+  ├── /api/search       archive.org search
+  ├── /api/list         list ISO files in an item
+  ├── /api/download     download ISOs with SSE progress
+  ├── /api/extract      extract WAVs via akaiutil
+  └── /api/progress     SSE download progress stream
+
+electron/               Electron wrapper (spawns fetch serve as sidecar)
+  ├── main.js           main process
+  ├── preload.js        context bridge
+  └── package.json      electron-builder config
+
+third_party/akaiutil/   Vendored akaiutil 4.6.7 (C, GPLv2)
+scripts/extract_wavs.sh Bash wrapper for batch WAV extraction
+```
+
+## Tech Stack
+
+| Component   | Tech               | External Deps |
+|-------------|--------------------|---------------|
+| CLI server  | Go 1.26, stdlib    | 0             |
+| Web UI      | HTML/CSS/JS (vanilla) | 0          |
+| Electron    | Electron 33, electron-builder | Node deps |
+| Extraction  | akaiutil (C), bash | vendored      |
+
+Zero Go dependencies. The web UI uses no framework — vanilla JS, Web Audio API, Server-Sent Events.
+
+## Feature Roadmap
+
+See [open issues](https://git.notsosm.art/david/akai-utils/issues).
+
+| # | Feature | Status |
+|---|---------|--------|
+| — | Search, download, extract, pipeline (CLI) | done |
+| — | HTTP server + web UI + Electron shell | done |
+| #1 | Disk Browser — browse AKAI filesystem in web UI | todo |
+| #2 | Disk Inspector — detailed disk metadata | todo |
+| #3 | WAV→Disk Packager — create AKAI ISOs from WAVs | todo |
+| #4 | Batch S900 Compressor | todo |
+| #5 | Partition Backup/Restore | todo |
+| #6 | Direct-to-Disk Take Extraction | todo |
+| #7 | TAR Bulk Import/Export | todo |
+| #8 | Sample Tag Editor | todo |
+| #9 | Audio Preview Player | todo |
+
+## License
+
+MIT. Contains vendored [akaiutil 4.6.7](https://github.com/kmi9000/akaiutil) (GPLv2, (c) Klaus Michael Indlekofer).