@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/skills/lit-code/references/go/bootstrap.md

@@ -0,0 +1,328 @@
+# Bootstrap — Project Layout, Toolchain, Taskfile, CI
+
+What every new Go project gets in the first 60 seconds. Drop the script in `scripts/go/new-project.go` does all of this — this document explains *what* it produces and *why*.
+
+## Toolchain pin
+
+`go.work` (monorepo) or just rely on `go.mod`'s `go 1.23` directive (single module). Go 1.21+ auto-downloads matching toolchain when the local `go` binary is older. **No `.tool-versions` / `asdf` / `mise` indirection required** unless your shop standardizes on it.
+
+```bash
+# Confirm a working toolchain
+go env GOTOOLCHAIN   # should be "auto" or your pinned version
+go version           # ≥ 1.23
+```
+
+## Required global installs
+
+These are CLI tools, installed once per machine via `go install`:
+
+```bash
+go install mvdan.cc/gofumpt@latest
+go install golang.org/x/tools/cmd/goimports@latest
+go install github.com/golangci/golangci-lint/cmd/golangci-lint@v2.0.0
+go install go.uber.org/nilaway/cmd/nilaway@latest
+go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
+go install github.com/pressly/goose/v3/cmd/goose@latest
+go install go.uber.org/mock/mockgen@latest
+go install github.com/go-task/task/v3/cmd/task@latest
+```
+
+For Connect/protobuf projects, additionally:
+
+```bash
+go install github.com/bufbuild/buf/cmd/buf@latest
+go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
+go install connectrpc.com/connect/cmd/protoc-gen-connect-go@latest
+```
+
+## Project layout — the canonical tree
+
+```
+myservice/
+├── go.mod
+├── go.sum
+├── Taskfile.yml               # task runner
+├── .golangci.yml              # see golangci-strict.md
+├── .editorconfig
+├── .gitignore
+├── README.md
+├── AGENTS.md                  # agent-readable project facts
+├── cmd/
+│   └── server/
+│       └── main.go            # ONLY: parse flags, call cmd.Execute(); ≤ 50 LOC
+├── internal/                  # NEVER importable from outside this module
+│   ├── api/                   # transport layer (gin/connect routers)
+│   │   ├── server.go          # gin engine setup, route registration
+│   │   ├── middleware/
+│   │   │   ├── request_id.go
+│   │   │   ├── logging.go
+│   │   │   └── auth.go
+│   │   └── handlers/
+│   │       ├── users.go
+│   │       └── users_test.go
+│   ├── domain/                # parse-don't-validate types, smart constructors
+│   │   ├── user.go
+│   │   └── email.go
+│   ├── service/               # business logic, depends on domain only
+│   │   └── user_service.go
+│   ├── store/                 # persistence; sqlc-generated code lives here
+│   │   ├── sqlc/              # sqlc-generated, do not hand-edit
+│   │   ├── queries/           # *.sql files sqlc reads
+│   │   └── migrations/        # goose migrations
+│   ├── config/                # env-driven config (caarlos0/env)
+│   │   └── config.go
+│   └── obs/                   # observability: slog setup, otel, healthz
+│       └── logger.go
+├── pkg/                       # exportable libraries — only if you publish
+│   └── …
+├── proto/                     # *.proto definitions (Connect/gRPC projects)
+│   └── service.proto
+├── gen/                       # generated code (Connect, OpenAPI)
+│   └── service/v1/
+│       ├── service.pb.go
+│       └── servicev1connect/
+├── test/                      # cross-cutting test helpers, fixtures
+└── .github/workflows/ci.yml
+```
+
+**Rules**:
+
+- `cmd/<binary>/main.go` is ≤ 50 LOC. Anything more lives in `internal/cmd/`.
+- `internal/` is **the** business code. Other modules cannot import it (Go compiler-enforced).
+- `pkg/` is for things you genuinely want third parties to import. Empty until proven otherwise.
+- No `utils/`, `helpers/`, `common/`, `shared/`. **REJECT.** Files are named after the concept they own.
+- One package per directory. One responsibility per package.
+
+## `Taskfile.yml` — the entry point for every action
+
+`go-task/task` is the modern Make replacement. Cross-platform, YAML, fast.
+
+```yaml
+version: '3'
+
+vars:
+  BINARY: server
+  PKG: ./cmd/server
+
+tasks:
+  default:
+    deps: [fmt, lint, test]
+
+  fmt:
+    desc: Format all Go files
+    cmds:
+      - gofumpt -w .
+      - goimports -w -local "$(go list -m)" .
+
+  lint:
+    desc: Run all linters
+    cmds:
+      - golangci-lint run --timeout 5m ./...
+      - nilaway -include-pkgs "$(go list -m)/..." ./...
+
+  test:
+    desc: Run tests with race detector
+    cmds:
+      - go test -race -shuffle=on -count=1 ./...
+
+  test-cover:
+    desc: Coverage report
+    cmds:
+      - go test -race -shuffle=on -count=1 -coverprofile=coverage.out ./...
+      - go tool cover -html=coverage.out -o coverage.html
+
+  build:
+    desc: Build the binary
+    cmds:
+      - go build -trimpath -ldflags="-s -w" -o bin/{{.BINARY}} {{.PKG}}
+
+  run:
+    desc: Run the server locally
+    deps: [build]
+    cmds:
+      - ./bin/{{.BINARY}}
+
+  gen:
+    desc: Run all code generators
+    cmds:
+      - task: gen:sqlc
+      - task: gen:mocks
+      - task: gen:proto
+
+  gen:sqlc:
+    cmds:
+      - sqlc generate
+    sources:
+      - internal/store/queries/*.sql
+      - internal/store/sqlc.yaml
+    generates:
+      - internal/store/sqlc/*.go
+
+  gen:mocks:
+    cmds:
+      - go generate ./...
+
+  gen:proto:
+    cmds:
+      - buf generate
+    sources:
+      - proto/**/*.proto
+      - buf.yaml
+      - buf.gen.yaml
+
+  migrate:up:
+    cmds:
+      - goose -dir internal/store/migrations postgres "$DATABASE_URL" up
+
+  migrate:down:
+    cmds:
+      - goose -dir internal/store/migrations postgres "$DATABASE_URL" down
+
+  ci:
+    desc: Everything CI does, locally
+    deps: [fmt, lint, test, build]
+```
+
+`task` (no args) runs format + lint + test in parallel where possible. `task ci` runs the full pipeline.
+
+## `go.mod` template
+
+```go
+module github.com/your-org/myservice
+
+go 1.23
+
+require (
+    github.com/caarlos0/env/v11 v11.2.2
+    github.com/gin-gonic/gin v1.10.1
+    github.com/go-playground/validator/v10 v10.22.1
+    github.com/google/uuid v1.6.0
+    github.com/jackc/pgx/v5 v5.7.6
+    golang.org/x/sync v0.18.0
+)
+```
+
+Only direct deps listed; `go mod tidy` populates indirects.
+
+## `.editorconfig`
+
+```ini
+root = true
+
+[*]
+indent_style = tab
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{yml,yaml,json,md}]
+indent_style = space
+indent_size = 2
+```
+
+## `.gitignore`
+
+```gitignore
+bin/
+coverage.out
+coverage.html
+*.test
+*.prof
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Local env
+.env
+.env.local
+
+# Secrets
+*.pem
+*.key
+```
+
+## CI — minimal GitHub Actions
+
+`.github/workflows/ci.yml`:
+
+```yaml
+name: ci
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+          cache: true
+
+      - name: Install tools
+        run: |
+          go install mvdan.cc/gofumpt@latest
+          go install github.com/golangci/golangci-lint/cmd/golangci-lint@v2.0.0
+          go install go.uber.org/nilaway/cmd/nilaway@latest
+          go install github.com/go-task/task/v3/cmd/task@latest
+
+      - name: Format check
+        run: gofumpt -l . | (! grep .)
+
+      - name: Lint
+        run: golangci-lint run --timeout 5m ./...
+
+      - name: Nilaway
+        run: nilaway ./...
+
+      - name: Test
+        run: go test -race -shuffle=on -count=1 ./...
+
+      - name: Build
+        run: go build -trimpath ./...
+```
+
+The order matters: format → lint → nilaway → test → build. Fail fast on the cheap checks.
+
+## `AGENTS.md` — agent-readable project facts
+
+Every new project gets an `AGENTS.md` at the root. The content is **machine-friendly**: short, declarative, no marketing prose. Example:
+
+```markdown
+# AGENTS.md
+
+Go 1.23+ HTTP service for {one-line purpose}.
+
+## Commands
+- `task` — fmt + lint + test
+- `task build` — produce ./bin/server
+- `task gen` — regenerate sqlc + mocks + proto
+
+## Architecture
+- `cmd/server/main.go` — entrypoint, ≤50 LOC
+- `internal/api/` — gin handlers + middleware
+- `internal/domain/` — smart-constructor types, no I/O
+- `internal/store/sqlc/` — generated; never hand-edit
+
+## Conventions
+- `slog` for all logs; never `log.*`, never `fmt.Println`
+- `context.Context` first arg for every public function
+- Errors wrapped with `%w`; check with `errors.Is/As`
+- 250 pure LOC ceiling per file — split before adding lines
+```
+
+The skill's `cmd/new-project.go` writes this file with project-specific values filled in.
+
+## Sources
+
+- Go modules reference: https://go.dev/ref/mod
+- go-task: https://taskfile.dev
+- golangci-lint v2: https://golangci-lint.run/docs/configuration/
+- Standard project layout debate: https://go.dev/doc/modules/layout (NOT `golang-standards/project-layout` — that repo is community, not official)

package/marketplace/plugins/litcodex/skills/lit-code/references/go/bubbletea-v2.md

@@ -0,0 +1,360 @@
+# Bubbletea v2 — TUI with First-Class CJK / IME Support
+
+The TUI stack for 2026. Use **v2 RC**, not v1. If your users include Korean, Japanese, or Chinese speakers, v1 is broken — IME composition lands in the wrong cells. v2 fixes this. This document is the canonical setup.
+
+The reference implementation this document is distilled from is an IME-focused floating window manager built specifically to nail down v2 + IME.
+
+---
+
+## Why v2 (not v1) — the IME story
+
+Bubbletea v1 manages cursor positioning in software ("virtual cursor"). It draws a `█` at the cursor position. The terminal's *real* cursor stays at `(0, 0)`.
+
+This breaks every CJK input method. IME candidate windows (the popup showing Hangul composition choices for Korean, kana → kanji for Japanese, and pinyin lookup for Chinese) anchor to the terminal's **real** cursor position. With v1, the candidate window appears at top-left while you are typing somewhere in the middle of the screen.
+
+Bubbletea v2 fixes this with two changes:
+
+1. **`tea.View{Cursor: *tea.Cursor}`** — your `View()` method returns a view that *includes* the desired cursor position. The framework moves the terminal's real cursor there.
+2. **`textarea.SetVirtualCursor(false)`** — textareas no longer draw their own `█`. They expose `.Cursor()` so you can read where they want the real cursor.
+
+Together: IME popups appear where the user is typing. As they should.
+
+### Other v2 wins (incidental)
+
+- `tea.MouseClickMsg` / `MouseMotionMsg` / `MouseReleaseMsg` instead of one coarse `MouseMsg`.
+- Cleaner `View` struct with `AltScreen`, `MouseMode` fields instead of `tea.Cmd` setters.
+- Pluggable rendering pipeline; better performance under high message volume.
+
+---
+
+## `go.mod`
+
+```go
+module github.com/your-org/mytui
+
+go 1.23
+
+require (
+    charm.land/bubbletea/v2 v2.0.0-rc.2
+    charm.land/bubbles/v2   v2.0.0-rc.1
+    charm.land/lipgloss/v2  v2.0.0-beta.3
+    github.com/mattn/go-runewidth v0.0.19
+)
+```
+
+The packages live under `charm.land/` (NOT `github.com/charmbracelet/...`) for v2. This is the Charm team's deliberate import-path break to keep v2 separate from v1 until stable.
+
+---
+
+## Minimal app — the IME-correct skeleton
+
+```go
+package main
+
+import (
+    "fmt"
+    "log"
+
+    tea "charm.land/bubbletea/v2"
+    "charm.land/bubbles/v2/textarea"
+)
+
+type model struct {
+    width, height int
+    ta            textarea.Model
+}
+
+func initial() model {
+    ta := textarea.New()
+    ta.Placeholder = "Type Korean / Japanese / Chinese here..."
+    ta.SetWidth(60)
+    ta.SetHeight(10)
+    ta.SetVirtualCursor(false)  // ← THE LINE. Without this, IME breaks.
+    ta.Focus()
+    return model{ta: ta}
+}
+
+func (m model) Init() tea.Cmd { return textarea.Blink }
+
+func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+    switch msg := msg.(type) {
+    case tea.WindowSizeMsg:
+        m.width, m.height = msg.Width, msg.Height
+    case tea.KeyPressMsg:
+        if msg.String() == "ctrl+c" {
+            return m, tea.Quit
+        }
+    }
+    var cmd tea.Cmd
+    m.ta, cmd = m.ta.Update(msg)
+    return m, cmd
+}
+
+func (m model) View() tea.View {
+    var view tea.View
+    view.AltScreen = true
+    view.SetContent(m.ta.View())
+
+    // ── THE OTHER LINE. Position the REAL cursor for IME. ──
+    if cursor := m.ta.Cursor(); cursor != nil {
+        view.Cursor = cursor
+    }
+    return view
+}
+
+func main() {
+    if _, err := tea.NewProgram(initial(), tea.WithAltScreen()).Run(); err != nil {
+        log.Fatal(err)
+    }
+    fmt.Println("bye")
+}
+```
+
+The two lines that matter:
+
+1. `ta.SetVirtualCursor(false)` — disables the virtual `█`.
+2. `view.Cursor = cursor` (where `cursor = m.ta.Cursor()`) — exports the real cursor position to the framework.
+
+Without **both**, IME breaks.
+
+---
+
+## CJK width — go-runewidth, not `len()`
+
+Korean, Japanese, Chinese characters render as **two terminal cells** (wide characters per Unicode East Asian Width). Naive `len(string)` returns byte count, not display width. `utf8.RuneCountInString` returns rune count, also not display width.
+
+Use `github.com/mattn/go-runewidth`:
+
+```go
+import "github.com/mattn/go-runewidth"
+
+func displayWidth(s string) int {
+    return runewidth.StringWidth(s)
+}
+
+// Wide character occupies two cells; pad accordingly
+for _, r := range s {
+    cell := string(r)
+    w := runewidth.RuneWidth(r)
+    canvas = append(canvas, cell)
+    if w == 2 {
+        canvas = append(canvas, "")  // placeholder for second cell
+    }
+}
+```
+
+`lipgloss/v2` uses `go-runewidth` internally — `lipgloss.Width("\u4e2d\u6587")` returns 4, not 2. **If you measure outside lipgloss, you must call runewidth directly.**
+
+---
+
+## Mouse — v2 has typed events
+
+```go
+case tea.MouseClickMsg:
+    // msg.X, msg.Y, msg.Button
+    return m.handleClick(msg.X, msg.Y, msg.Button)
+
+case tea.MouseMotionMsg:
+    return m.handleHover(msg.X, msg.Y)
+
+case tea.MouseReleaseMsg:
+    return m.handleRelease(msg.X, msg.Y)
+```
+
+Enable mouse via the `View`:
+
+```go
+view.MouseMode = tea.MouseModeCellMotion  // or MouseModeAll
+```
+
+`CellMotion` reports clicks + motion-while-button-pressed (drag). `MouseModeAll` reports motion always — heavier, only when you need hover.
+
+---
+
+## Components from `bubbles/v2`
+
+```go
+import (
+    "charm.land/bubbles/v2/textarea"
+    "charm.land/bubbles/v2/textinput"
+    "charm.land/bubbles/v2/spinner"
+    "charm.land/bubbles/v2/viewport"
+    "charm.land/bubbles/v2/list"
+    "charm.land/bubbles/v2/table"
+    "charm.land/bubbles/v2/help"
+    "charm.land/bubbles/v2/key"
+)
+```
+
+All v2 components support `SetVirtualCursor(false)` where they accept text input. Use it for every text input that users might type CJK into — and "might" should be assumed *yes*.
+
+---
+
+## Styling — `lipgloss/v2`
+
+```go
+import "charm.land/lipgloss/v2"
+
+titleStyle := lipgloss.NewStyle().
+    Bold(true).
+    Foreground(lipgloss.Color("230")).
+    Background(lipgloss.Color("62")).
+    Padding(0, 1).
+    Border(lipgloss.RoundedBorder()).
+    BorderForeground(lipgloss.Color("63"))
+
+rendered := titleStyle.Render("\u4e2d\u6587")
+```
+
+`lipgloss/v2` width and padding correctly account for CJK display width. v1 did too — this is not a v2-specific fix, just a reminder.
+
+---
+
+## Architecture pattern — Model–Update–View
+
+```
++--------------------------------------------+
+|  tea.Program runs the event loop           |
+|                                            |
+|  loop:                                     |
+|    msg <- queue                            |
+|    model, cmd = model.Update(msg)          |
+|    view = model.View()                     |
+|    render(view)                            |
+|    if cmd != nil: go run(cmd) -> queue     |
++--------------------------------------------+
+```
+
+Rules:
+
+- **Model is a value type, not a pointer.** Bubbletea calls `Update` with a value receiver and expects a new value returned. Pointer receivers cause subtle bugs where state mutation leaks across draws.
+- **`Update` is pure.** No I/O. No goroutines started inline. Any I/O returns a `tea.Cmd` — Bubbletea runs it in a goroutine and feeds the result back as a message.
+- **`View` is read-only.** It returns a `tea.View` without modifying state.
+- **`tea.Cmd` is `func() tea.Msg`.** It runs once, returns a message, exits. For repeating work, use `tea.Tick` or a self-resending command.
+
+```go
+// One-shot command
+func loadData() tea.Cmd {
+    return func() tea.Msg {
+        data, err := fetch()
+        if err != nil { return errMsg{err} }
+        return dataLoadedMsg{data}
+    }
+}
+
+// Periodic
+func tickEvery() tea.Cmd {
+    return tea.Tick(time.Second, func(t time.Time) tea.Msg {
+        return tickMsg{t}
+    })
+}
+```
+
+---
+
+## Splitting the model — sub-models
+
+```go
+type model struct {
+    list    list.Model
+    input   textinput.Model
+    spinner spinner.Model
+}
+
+func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+    var cmds []tea.Cmd
+    var cmd tea.Cmd
+
+    m.list, cmd = m.list.Update(msg)
+    cmds = append(cmds, cmd)
+
+    m.input, cmd = m.input.Update(msg)
+    cmds = append(cmds, cmd)
+
+    m.spinner, cmd = m.spinner.Update(msg)
+    cmds = append(cmds, cmd)
+
+    return m, tea.Batch(cmds...)
+}
+```
+
+`tea.Batch` runs commands concurrently. The framework collects their results in the order they arrive.
+
+When the model exceeds 250 LOC, split by sub-model into separate files:
+
+```
+internal/ui/
+├── model.go          # root model orchestration
+├── list.go           # list sub-model state + update + view
+├── input.go          # input sub-model
+└── spinner.go        # spinner sub-model
+```
+
+---
+
+## Testing TUI code — `teatest`
+
+```go
+import "charm.land/bubbletea/v2/teatest"
+
+func TestModel_typing_cjk_keeps_cursor_in_position(t *testing.T) {
+    // Given
+    m := initial()
+    tm := teatest.NewTestModel(t, m, teatest.WithInitialTermSize(80, 24))
+
+    // When — simulate typing two CJK wide characters
+    tm.Send(tea.KeyPressMsg{Code: '\u4e2d'})
+    tm.Send(tea.KeyPressMsg{Code: '\u6587'})
+
+    // Then
+    out := tm.FinalOutput(t)
+    require.Contains(t, string(out), "\u4e2d\u6587")
+    // Cursor should be at column 4 (two wide chars = 4 cells)
+    // ...
+}
+```
+
+`teatest` lets you drive the model through synthetic messages and inspect the rendered output. Pair with `autogold` snapshots for full-view regression tests.
+
+---
+
+## Common antipatterns
+
+| Bad | Why | Good |
+|---|---|---|
+| `tea.Program` with `tea.WithoutSignals()` | Ctrl-C does not work | Default signal handling |
+| Pointer receivers on Model | Bubbletea expects value semantics | Value receivers, return new model |
+| `time.Sleep` inside `Update` | Blocks the event loop | `tea.Tick` or async `tea.Cmd` |
+| `fmt.Println` for debug | Corrupts the rendered output | `tea.Printf` for logging, or write to a file |
+| `len(s)` for CJK width | Off by 2x | `runewidth.StringWidth(s)` |
+| `Bubbletea v1` for an app with text input | Korean/Japanese IME breaks | v2 + `SetVirtualCursor(false)` |
+| Drawing your own `█` block cursor in v2 | Conflicts with `view.Cursor` | Let the terminal handle it |
+
+---
+
+## Performance — when v2 starts to crawl
+
+- **Reduce View frequency.** If the model changes 60 times/sec but the rendered view changes once/sec, gate redraws on a "dirty" flag.
+- **`viewport.Model` for scrollable content.** Avoid re-rendering thousands of lines on every keystroke.
+- **`Batch` your commands.** A series of synchronous `tea.Cmd` returns serializes; `tea.Batch` parallelizes.
+- **Profile with `tea.WithFPS(N)`** to cap repaint rate during development.
+
+---
+
+## When NOT to use Bubbletea
+
+- The app is one prompt + one answer. Use `huh` (also from Charm) — simpler, no Model–Update–View ceremony.
+- The app is a long-running daemon with occasional status output. Use `slog` to stderr and `tea.Program` only if interactivity becomes necessary.
+- The app must run as a non-tty subprocess (CI, redirected stdin). `tea.Program` requires a tty for input. Detect via `term.IsTerminal(int(os.Stdin.Fd()))` and fall back to a non-interactive path.
+
+---
+
+## Sources
+
+- bubbletea v2 RC: https://github.com/charmbracelet/bubbletea/tree/v2
+- bubbles v2: https://github.com/charmbracelet/bubbles/tree/v2
+- lipgloss v2: https://github.com/charmbracelet/lipgloss/tree/v2
+- IME-focused bubbletea v2 window-manager reference notes
+- crush CLI (production IME impl): https://github.com/charmbracelet/crush
+- go-runewidth: https://github.com/mattn/go-runewidth
+- Unicode East Asian Width: https://www.unicode.org/reports/tr11/