simple_wiki — Copilot Instructions

<!--toc:start--> • General • Development Environment • Frontend JavaScript • Storybook • Testing • Fixing Problems <!--toc:end-->

• Make Uncle Bob proud. • Prefer modern, idiomatic approaches for the language in use. Update idioms as you see them to align with current best practices (Boyscout Rule). • Type Clarity: Prioritize clear and explicit type declarations. For Go, prefer any over interface{}. • Standard Idioms and Tooling: Prefer standard idioms and approaches for the language in use. Leverage appropriate code generation tools when beneficial (e.g., go:generate for Go). For JavaScript, utilize tools like bun build for bundling and web-test-runner for testing. • Generated files should be committed to the repository. This ensures that developers can build and test the project without needing to have all code generation tools installed locally. Any files created or modified by go generate ./... should be included in commits. • prefer IoC approaches. Make \*-er interfaces for all the things! • Avoid Parameter Objects and Config Structs: Don't bundle unrelated parameters into "Options", "Config", "Settings", or "Dependencies" structs. These become implicit global variables - shared spaces where unrelated concerns accumulate. Instead, pass explicit parameters to functions. This makes dependencies clear, prevents coupling between unrelated features, and avoids the "god object" anti-pattern. Bad: `go type Options struct { Host string Port int Debug bool Timeout time.Duration // Grows over time with unrelated fields... } func SetupServer(opts Options) { ... } ` Good: `go func SetupServer(host string, port int) { ... } func SetupServerWithTLS(host string, port int, tlsPort int, tlsConfig *tls.Config) { ... } ` When a function needs many parameters, it's often a sign the function is doing too much. Consider breaking it into smaller, focused functions rather than hiding complexity behind a config struct. • Avoid Meaningless Names: Avoid generic, meaningless names like "Manager", "Handler", "Processor", "Service", "Util", or "Helper" unless they genuinely describe the specific purpose. These names are often cop-outs that don't convey meaningful information about what the type or function actually does. Instead, use descriptive names that clearly indicate the specific responsibility or behavior. Bad Examples: • PageManager (vague - manages what about pages?) • DataProcessor (vague - processes how?) • RequestHandler (vague - handles how?) • UserService (vague - what service?) Good Examples: • PageReaderMutator (specific - reads and mutates pages) • DataValidator (specific - validates data) • RequestRouter (specific - routes requests) • UserAuthenticator (specific - authenticates users) • Defensive Error Handling: Take a defensive coding approach. Check inputs, assert preconditions, and enforce invariants. For recoverable issues, prefer returning an error or throwing an exception rather than causing a program crash (panic). Crashes/panics should be reserved for truly exceptional and unrecoverable situations. This allows the caller to handle the problem more gracefully. Go Example (Returning Error): `go func MyFunction(input int) error { if input < 0 { return fmt.Errorf("input cannot be negative") } // ... return nil } ` TypeScript Example (Throwing Exception): `typescript function myFunction(input: number): boolean { if (input < 0) { throw new Error("Input cannot be negative"); } return true; } `

• Use Devbox by Jetify to create isolated, reproducible development environments. • Add new dependencies via devbox add <package>. This ensures the devbox.json and devbox.lock files are updated correctly. • Use either devbox shell (for an interactive shell) or devbox run <command> (for running specific commands) to work within the Devbox environment. • When possible, use scripts defined in devbox.json to run commands. Run devbox run to see a list of available scripts.

• All JavaScript frontend code and project files should be located under the static/js directory. • This includes JavaScript source files, test files, configuration files (e.g., vitest.config.js), and package management files (e.g., package.json, bun.lock). • Use Bun as the package manager for modern JavaScript tooling and faster performance. • Since this is primarily a Go project, JavaScript is only for the frontend portion and should be contained within the static/js directory. • Organize frontend JavaScript files within appropriate subdirectories under static/js (e.g., web-components, utils). • Test files should be placed next to the production code they test, using the .test.js suffix. For example, wiki-search.js should have its tests in wiki-search.test.js in the same directory. • Scalar Variable Units: Always include units in scalar variable names when the unit is meaningful. For example, use timeoutMs instead of timeout, delaySeconds instead of delay, heightPx instead of height. This makes the code self-documenting and prevents unit confusion.