david/akai-utils
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README/AGENTS for current codebase

Browse Source 
- All references updated from fetch → akai-fetch
- AGENTS: document golangci-lint, extract.go replaces bash,
  remove findScript, update Electron binary name
- README: update roadmap, extraction tech stack
- mise.toml: add golangci-lint tool
This commit is contained in:
David Gwilliam
2026-06-21 23:22:00 -07:00
parent a17f22ccb2
commit 470fb9a4c4
3 changed files with 32 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+23 -12
View File
@@ -11,7 +11,7 @@ mise run gopls # install gopls (Go LSP) — one-time dev setup
All build/run tasks are defined in `mise.toml`: All build/run tasks are defined in `mise.toml`:
```bash ```bash
mise run build # → ./fetch mise run build # → ./akai-fetch
mise run serve # → starts HTTP server, opens browser mise run serve # → starts HTTP server, opens browser
mise run electron-deps # installs electron + electron-builder mise run electron-deps # installs electron + electron-builder
mise run electron-dev # runs electron in dev mode mise run electron-dev # runs electron in dev mode
@@ -20,15 +20,21 @@ mise run lint # go vet ./...
mise run check-all # verify gcc, brew, mise, go, node, docker, colima 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) ## Build & Run (manual)
```bash ```bash
# Build Go binary (zero CGO) # Build Go binary (zero CGO)
go build -buildvcs=false -o fetch . # → ./fetch go build -buildvcs=false -o akai-fetch . # → ./akai-fetch
# Build and run web server # Build and run web server
./fetch serve # → starts on free port, opens browser ./akai-fetch serve # → starts on free port, opens browser
./fetch serve --host 0.0.0.0 -p 8080 # → Docker / network-accessible mode ./akai-fetch serve --host 0.0.0.0 -p 8080 # → Docker / network-accessible mode
# Docker # Docker
docker compose up --build # serves on :8080, binds 0.0.0.0 docker compose up --build # serves on :8080, binds 0.0.0.0
@@ -38,8 +44,8 @@ docker compose up --build # serves on :8080, binds 0.0.0.0
(cd electron && npx electron .) (cd electron && npx electron .)
# Cross-compile for macOS (from Linux) # Cross-compile for macOS (from Linux)
GOOS=darwin GOARCH=arm64 go build -o fetch-darwin-arm64 . GOOS=darwin GOARCH=arm64 go build -o akai-fetch-darwin-arm64 .
GOOS=darwin GOARCH=amd64 go build -o fetch-darwin-amd64 . GOOS=darwin GOARCH=amd64 go build -o akai-fetch-darwin-amd64 .
``` ```
## Architecture ## Architecture
@@ -64,14 +70,17 @@ third_party/ Vendored akaiutil C binary (GPLv2)
- **Flag parsing**: each command creates its own `flag.NewFlagSet` — avoids global flag state - **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 - **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 - **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 - **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` - **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 - **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. - **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 ### akaiutil integration
`scripts/extract_wavs.sh` shells out to `akaiutil` for: `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) - `df` — disk info (partitions, block counts)
- `dir` — list volumes/files - `dir` — list volumes/files
- `sample2wavall` — batch WAV extraction - `sample2wavall` — batch WAV extraction
@@ -86,8 +95,8 @@ All akaiutil calls use `-r` (read-only) flag. Write operations (S900 compress, p
### Electron integration ### Electron integration
`electron/main.js` spawns the Go binary in `serve` mode: `electron/main.js` spawns the Go binary in `serve` mode:
1. Finds `fetch` binary next to app or in `process.resourcesPath` 1. Finds `akai-fetch` binary next to app or in `process.resourcesPath`
2. Spawns `fetch serve -p 0 --no-browser` 2. Spawns `akai-fetch serve -p 0 --no-browser`
3. Parses `stdout` for `Local: http://localhost:XXXX` to get port 3. Parses `stdout` for `Local: http://localhost:XXXX` to get port
4. Creates `BrowserWindow` pointing at that URL 4. Creates `BrowserWindow` pointing at that URL
5. Kills server on quit 5. Kills server on quit
@@ -117,8 +126,10 @@ All akaiutil calls use `-r` (read-only) flag. Write operations (S900 compress, p
No test framework yet. Manual verification: No test framework yet. Manual verification:
```bash ```bash
go build -o /dev/null . # compile check go build -o /dev/null . # compile check
./fetch serve # manual smoke test go vet ./... # static analysis
golangci-lint run # comprehensive lint
./akai-fetch serve # manual smoke test
``` ```
## Secrets & Tokens ## Secrets & Tokens
README.md
+8 -6
View File
@@ -12,7 +12,7 @@ Two interfaces:
```bash ```bash
mise trust # first time only mise trust # first time only
mise install # installs go 1.26, node 22 mise install # installs go 1.26, node 22
mise run build # → ./fetch mise run build # → ./akai-fetch
``` ```
### Toolchain check ### Toolchain check
@@ -32,14 +32,14 @@ mise run docker-up
```bash ```bash
# CLI # CLI
mise run build mise run build
./fetch search --filter vocal ./akai-fetch search --filter vocal
# Web server (local) # Web server (local)
mise run serve mise run serve
# Open http://localhost:PORT (auto-assigned) # Open http://localhost:PORT (auto-assigned)
# Web server (Docker / network-accessible) # Web server (Docker / network-accessible)
./fetch serve --host 0.0.0.0 -p 8080 ./akai-fetch serve --host 0.0.0.0 -p 8080
# Open http://<host-ip>:8080 # Open http://<host-ip>:8080
# Electron (macOS) # Electron (macOS)
@@ -60,14 +60,14 @@ akai-fetch serve [flags] start HTTP server with web UI
## Architecture ## Architecture
``` ```
fetch serve (Go HTTP server, embedded web UI) akai-fetch serve (Go HTTP server, embedded web UI)
├── /api/search archive.org search ├── /api/search archive.org search
├── /api/list list ISO files in an item ├── /api/list list ISO files in an item
├── /api/download download ISOs with SSE progress ├── /api/download download ISOs with SSE progress
├── /api/extract extract WAVs via akaiutil ├── /api/extract extract WAVs via akaiutil
└── /api/progress SSE download progress stream └── /api/progress SSE download progress stream
electron/ Electron wrapper (spawns fetch serve as sidecar) electron/ Electron wrapper (spawns akai-fetch serve as sidecar)
├── main.js main process ├── main.js main process
├── preload.js context bridge ├── preload.js context bridge
└── package.json electron-builder config └── package.json electron-builder config
@@ -87,7 +87,7 @@ third_party/akaiutil/ Vendored akaiutil 4.6.7 (C, GPLv2)
| CLI server | Go 1.26, stdlib | 0 | | CLI server | Go 1.26, stdlib | 0 |
| Web UI | HTML/CSS/JS (vanilla) | 0 | | Web UI | HTML/CSS/JS (vanilla) | 0 |
| Electron | Electron 33, electron-builder | Node deps | | Electron | Electron 33, electron-builder | Node deps |
| Extraction | akaiutil (C), bash | vendored C source | | Extraction | akaiutil (C) via Go wrappers | vendored C source |
Zero Go dependencies. The web UI uses no framework — vanilla JS, Web Audio API, Server-Sent Events. Zero Go dependencies. The web UI uses no framework — vanilla JS, Web Audio API, Server-Sent Events.
@@ -99,6 +99,8 @@ See [open issues](https://git.notsosm.art/david/akai-utils/issues).
|---|---------|--------| |---|---------|--------|
| — | Search, download, extract, pipeline (CLI) | done | | — | Search, download, extract, pipeline (CLI) | done |
| — | HTTP server + web UI + Electron shell | done | | — | HTTP server + web UI + Electron shell | done |
| — | WAV extraction re-implemented in Go | done |
| — | MkdirAll error handling + parent dir creation for downloads | done |
| — | Docker compose + mise toolchain + toolchain checks | done | | — | Docker compose + mise toolchain + toolchain checks | done |
| #1 | Disk Browser — browse AKAI filesystem in web UI | todo | | #1 | Disk Browser — browse AKAI filesystem in web UI | todo |
| #2 | Disk Inspector — detailed disk metadata | todo | | #2 | Disk Inspector — detailed disk metadata | todo |
mise.toml
+1
View File
@@ -1,5 +1,6 @@
[tools] [tools]
go = "1.26" go = "1.26"
golangci-lint = "latest"
node = "22" node = "22"
[env] [env]