From 470fb9a4c455cbd1902562e2218343047a58668a Mon Sep 17 00:00:00 2001 From: David Gwilliam Date: Sun, 21 Jun 2026 23:22:00 -0700 Subject: [PATCH] docs: update README/AGENTS for current codebase MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- AGENTS.md | 35 +++++++++++++++++++++++------------ README.md | 14 ++++++++------ mise.toml | 1 + 3 files changed, 32 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4f8f18d..23ce31c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ mise run gopls # install gopls (Go LSP) — one-time dev setup All build/run tasks are defined in `mise.toml`: ```bash -mise run build # → ./fetch +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 @@ -20,15 +20,21 @@ 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 fetch . # → ./fetch +go build -buildvcs=false -o akai-fetch . # → ./akai-fetch # Build and run web server -./fetch serve # → starts on free port, opens browser -./fetch serve --host 0.0.0.0 -p 8080 # → Docker / network-accessible mode +./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 @@ -38,8 +44,8 @@ docker compose up --build # serves on :8080, binds 0.0.0.0 (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 . +GOOS=darwin GOARCH=arm64 go build -o akai-fetch-darwin-arm64 . +GOOS=darwin GOARCH=amd64 go build -o akai-fetch-darwin-amd64 . ``` ## 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 - **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 +- **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 `` URLs for clarity. ### 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) - `dir` — list volumes/files - `sample2wavall` — batch WAV extraction @@ -86,8 +95,8 @@ All akaiutil calls use `-r` (read-only) flag. Write operations (S900 compress, p ### 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` +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 @@ -117,8 +126,10 @@ All akaiutil calls use `-r` (read-only) flag. Write operations (S900 compress, p No test framework yet. Manual verification: ```bash -go build -o /dev/null . # compile check -./fetch serve # manual smoke test +go build -o /dev/null . # compile check +go vet ./... # static analysis +golangci-lint run # comprehensive lint +./akai-fetch serve # manual smoke test ``` ## Secrets & Tokens diff --git a/README.md b/README.md index db314d3..61e70b7 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Two interfaces: ```bash mise trust # first time only mise install # installs go 1.26, node 22 -mise run build # → ./fetch +mise run build # → ./akai-fetch ``` ### Toolchain check @@ -32,14 +32,14 @@ mise run docker-up ```bash # CLI mise run build -./fetch search --filter vocal +./akai-fetch search --filter vocal # Web server (local) mise run serve # Open http://localhost:PORT (auto-assigned) # 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://:8080 # Electron (macOS) @@ -60,14 +60,14 @@ akai-fetch serve [flags] start HTTP server with web UI ## Architecture ``` -fetch serve (Go HTTP server, embedded web UI) +akai-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) +electron/ Electron wrapper (spawns akai-fetch serve as sidecar) ├── main.js main process ├── preload.js context bridge └── 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 | | Web UI | HTML/CSS/JS (vanilla) | 0 | | 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. @@ -99,6 +99,8 @@ See [open issues](https://git.notsosm.art/david/akai-utils/issues). |---|---------|--------| | — | Search, download, extract, pipeline (CLI) | 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 | | #1 | Disk Browser — browse AKAI filesystem in web UI | todo | | #2 | Disk Inspector — detailed disk metadata | todo | diff --git a/mise.toml b/mise.toml index 5101ae8..9cd4483 100644 --- a/mise.toml +++ b/mise.toml @@ -1,5 +1,6 @@ [tools] go = "1.26" +golangci-lint = "latest" node = "22" [env]