scratchbox/AGENTS.md

AGENTS.md

Purpose

This repository hosts a small self-hosted scratch service written in Go.

Key product constraints:

• All routes are unauthenticated by design.
• One upload creates one scratch.
• For multiple files, users must upload a single archive file.
• Scratch data is stored gzip-compressed on disk transparently.

Project layout

• cmd/scratchbox: service entrypoint
• internal/config: config loading and validation
• internal/http: HTTP handlers and middleware
• internal/storage: filesystem storage and metadata index
• internal/cleanup: expiration cleanup worker
• web/templates, web/static: UI assets

API routes

• POST /api/scratch
• GET /api/scratch/{id}
• GET /s/{id}
• GET /api/raw/{id}

Build and test

Use make help as the source of truth for available build/test targets and descriptions. Format, Test, Build are the required steps before being done with any coding if there are more then one target for any of these then run them all before considering that step complete.

Coding conventions

• Keep changes minimal and focused.
• Backward compatibility is not a concern unless explicitly requested.
• Do not add compatibility shims, fallback paths, legacy aliases, or dual behavior unless explicitly requested.
• Preserve unauthenticated behavior unless explicitly requested.
• Keep limits/operator controls configurable via config.
• Maintain write-route protections (allowlist and rate limiting).
• Keep storage behavior transparent for clients (compression is internal).
• Add or update tests for behavior changes.

Cobra CLI conventions

• Keep cmd/scratchbox/main.go focused on main() and root command wiring.
• Put each Cobra subcommand in its own file (for example cmd/scratchbox/server.go).
• Start the service through the explicit subcommand (scratchbox server), not from the root command directly.
• Validate command arguments with Cobra arg validators (for example cobra.NoArgs) where applicable.