AGENTS.md — pixe

Build & Run

make build                # GoReleaser snapshot → ./pixe (production build)
make build-debug          # go build with debug symbols (for dlv)
make run ARGS="sort -h"   # build + run with arguments
make clean                # remove binary, dist/, coverage files

Test Commands

make test                 # unit tests only (excludes integration/)
make test-all             # all tests including integration
make test-integration     # integration tests only

# Single test by name:
go test -race -timeout 120s ./internal/pipeline/ -run TestRun_basicSort -v

# Single package:
go test -race -timeout 120s ./internal/archivedb/...

# With coverage:
make test-cover           # prints coverage summary
make test-cover-html      # opens HTML report in browser

Always use -race when running tests. The Makefile sets TEST_FLAGS := -race -timeout 120s.

Lint & Format

make lint                 # golangci-lint run ./...
make vet                  # go vet ./...
make fmt                  # gofmt -w -s .
make fmt-check            # check formatting without modifying (CI gate)
make check                # fmt-check + vet + unit tests (fast pre-commit gate)

CI runs golangci-lint and go test -v -short ./... on every push/PR to main.

Code Style

File Header

Every .go file starts with the Apache 2.0 copyright block:

// Copyright 2026 Chris Wells <chris@rhza.org>
//
// Licensed under the Apache License, Version 2.0 (the "License");
// ...

Package Comments

Every package has a doc comment on the package line or in a doc.go. Use // style, not /* */. Describe what the package does and any key design decisions:

// Package archivedb provides SQLite-backed persistence for the Pixe archive
// database. It replaces the earlier JSON manifest with a cumulative registry
// that tracks all files ever sorted into a destination archive across all runs.
package archivedb

Imports

Three groups separated by blank lines: stdlib, external, internal. Sorted alphabetically within each group. Use named imports only when there's a collision:

import (
    "fmt"
    "os"
    "path/filepath"

    "github.com/spf13/cobra"
    "github.com/spf13/viper"

    "github.com/cwlls/pixe/internal/archivedb"
    copypkg "github.com/cwlls/pixe/internal/copy"    // named: avoids collision with builtin
    jpeghandler "github.com/cwlls/pixe/internal/handler/jpeg"  // named: handler packages share type names
)

Handler packages use the convention <format>handler for their import alias (e.g., jpeghandler, heichandler, dnghandler).

Naming

• Packages: lowercase, single word when possible (archivedb, discovery, pathbuilder).
• Exported types: PascalCase. Structs use noun names (Registry, Hasher, DB).
• Constructors: New() returns the primary type. NewFoo() if the package has multiple types.
• Methods: receiver name is 1–2 letters derived from the type (db, h, r, m, sw).
• Constants: PascalCase for exported, camelCase for unexported. Status enums use Status prefix: StatusPending, StatusComplete, StatusFailed.
• Test helpers: unexported, use t.Helper(). Common pattern: openTestDB(t), copyFixture(t, dir, name), writeFile(t, path, content).

Types & Structs

• Use *string, *time.Time, *int64 for nullable DB fields (maps to sql.NullString etc. in scan).
• Config structs (AppConfig, SortOptions) are passed by pointer.
• Domain types live in internal/domain/ — shared across packages without import cycles.
• The FileTypeHandler interface is the extension point for new formats (Section 6 of the architecture).

Error Handling

• Wrap errors with fmt.Errorf("context: %w", err) — always include the package or function as context prefix.
• Use errors.Is() for sentinel checks (e.g., errors.Is(err, os.ErrNotExist)).
• DB scan errors: return (nil, nil) for sql.ErrNoRows when "not found" is a valid result.
• Non-fatal errors (e.g., tag failure): log a warning to out and continue. Do not return an error.
• Fatal errors: return the error up the call chain. The CLI layer (cmd/) prints it and exits.

// Pattern: wrap with package prefix
return nil, fmt.Errorf("archivedb: insert run: %w", err)

// Pattern: nil-nil for not-found
if errors.Is(err, sql.ErrNoRows) {
    return nil, nil
}

Testing

• Tests use the stdlib testing package only — no testify or other assertion libraries.
• Test files are in the same package (white-box testing): package pipeline not package pipeline_test.
• Use t.TempDir() for filesystem tests — auto-cleaned.
• Use t.Helper() on all helper functions.
• Test names: TestTypeName_methodOrBehavior (e.g., TestRun_basicSort, TestCheckDuplicate_notFound).
• Table-driven tests use anonymous struct slices with want/got pattern.
• Integration tests live in internal/integration/ and are excluded from make test.
• Locale-sensitive tests pin locale via TestMain: pathbuilder.SetLocaleForTesting(language.English).

SQL

• SQL strings use backtick-quoted const blocks with the query name as the const name.
• Use ? placeholders (SQLite positional params).
• All DDL uses IF NOT EXISTS for idempotency.
• Schema migrations are additive (ALTER TABLE ADD COLUMN), never destructive.

Concurrency

• Worker pool pattern: coordinator goroutine owns DB writes; workers own I/O.
• syncWriter wraps io.Writer with a mutex for concurrent stdout access.
• Per-worker assignment channels (buffered 1) for coordinator→worker communication.
• context.Context threaded through concurrent paths for cancellation.

Project Layout

cmd/                    CLI commands (Cobra). No business logic here.
internal/
  archivedb/            SQLite database (schema, CRUD, queries)
  benchmark/            Centralized benchmark suite (hash, copy, db, discovery, pathbuilder)
  cli/                  Bubble Tea progress bar model and Lip Gloss styles
  config/               AppConfig struct (populated by cmd/, read by pipeline/)
  copy/                 File copy + verify
  dblocator/            Database path resolution (local vs network mount)
  discovery/            File walking + handler registry
  docgen/               Development-time doc generation tool (marker-based injection)
  domain/               Shared types (FileStatus, Ledger, Manifest, FileTypeHandler)
  fileutil/             Shared file-path utilities (extension normalization)
  handler/              FileTypeHandler implementations (jpeg/, heic/, mp4/, tiffraw/, dng/, ...)
  hash/                 Configurable hasher (MD5, SHA-1, SHA-256, BLAKE3, xxHash)
  ignore/               Glob-based file ignore matching with .pixeignore support
  integration/          End-to-end tests (excluded from `make test`)
  manifest/             JSON ledger/manifest persistence
  migrate/              Legacy JSON manifest → SQLite migration
  pathbuilder/          Destination path construction (date-based, locale-aware)
  pipeline/             Sort orchestrator (sequential + concurrent)
  progress/             Pipeline event bus (typed events, non-blocking channel, plain text writer)
  tagging/              Metadata tag injection (dispatch via handler capability)
  verify/               Post-sort verification
  xmp/                  XMP sidecar file generation (Adobe-compatible)

Key Architectural Rules

1. dirA is read-only. Only .pixe_ledger.json is written there. Never modify source files.
2. No external binaries. No os/exec. All parsing is pure Go.
3. Copy-then-verify. Every file is re-hashed after copy. Mismatches are flagged, never silent.
4. No Viper below cmd/. Only cmd/ reads Viper. Everything else receives *config.AppConfig.
5. Version from git tags. No version literals in source. Injected via ldflags at build time.