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 /raw/{id}

Build and test

Use make help as the source of truth for available build/test targets and descriptions.

Coding conventions

• Keep changes minimal and focused.
• Backward compatibility is not a concern 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.