sakumock: Instructions file for Claude Code

sakumock

Service Conventions

The repository is a single Go module (github.com/sacloud/sakumock); each service is a package under its own subdirectory, and shared building blocks live in core/. Services must not import each other; shared code goes through core. All services are also aggregated into a single sakumock binary (cmd/sakumock) exposing each as a subcommand with the same flags as the standalone sakumock-<service> binary; only the unified binary is released (GoReleaser), per-service binaries stay go install-able.

Required public API

The contract is type-enforced: server.go asserts var _ core.ServiceConfig = Config{} and var _ core.Server = (*Server)(nil), so a drifting service fails to build.

• Config — kong-tagged struct satisfying core.ServiceConfig: Name() (short name = subcommand, e.g. "apprun-dedicated"), ListenAddr() (= Config.Addr), ClientEnv() []core.EnvVar (the SAKURA_ENDPOINTS_* override(s) a client sets to reach this mock — the single source for the env var name, used by startup logs, sakumock env, and service link), Doc() (= Doc), NewServer(opts core.ServerOptions) (applies the shared opts, adapts NewHandler). Add a field to core.ServerOptions to inject a dependency into every service without changing the interface.
• Command — embeds Config, adds Routes bool / Docs bool and Run(ctx) error; shared by the standalone and unified binaries. --routes prints the route table, --docs the embedded README, then exit.
• Doc string — README.md embedded in doc.go.
• NewHandler(cfg Config) (*Server, error) — handler without listener (return nil error when construction cannot fail; keep the signature uniform).
• NewTestServer(cfg Config) *Server — starts an httptest.Server (panics on error).
• *Server satisfies core.Server: http.Handler + Routes() []core.Route + TestURL() ("" when built by NewHandler, never panics) + Close().

File structure

• store.go (Store interface, domain types), store_memory.go, new_store.go (factory)
• handler.go — HTTP handlers and JSON types
• route.go — routeTable() is the single source of truth driving both buildMux() and Routes()
• validate_gen.go + generate.go — generated validation tables and their //go:generate directive; validate_overrides.go for declared spec gaps
• server.go — Config, Server, NewHandler, NewTestServer
• cli.go — Command; Run sets up logging/tracing, prints routes/docs, or serves via core.Serve, and holds the startup log lines
• doc.go — //go:embed README.md
• cmd/sakumock-<service>/ — thin standalone entrypoint (core.NotifyContext for signals)
• Makefile, README.md, openapi/