Imported from Authula/authula (AGENTS.md). Install upstream with npx skills add Authula/authula. Copyright stays with the author.

Authula Project Guidelines

Authula is an open-source authentication solution that scales with you. Embed it as a library in your Go app, or run it as a standalone auth server with any tech stack. It simplifies adding robust authentication to backend services, empowering developers to build secure applications faster.

Code Style Guide

• Always write clean code that is easy to read and maintain.
• Follow consistent naming conventions for variables, functions, and structs.
• Include comments where necessary to explain complex logic. DO NOT write comments for every line of code, only for parts that are not immediately clear. The code should be self-explanatory as much as possible.
• Ensure proper error handling throughout the codebase.
• Follow best practices and concepts from SOLID principles for better software design.
• Use Go modules for dependency management.
• Adhere to idiomatic Go practices as outlined in the official Go documentation.
• Use gofmt to format your code and run make lint and fix any linting errors before committing.
• Avoid global variables unless absolutely necessary.
• Use interfaces to define behavior and promote decoupling. Never code to implementations. When writing services, make sure they implement an interface of a repository e.g. UserService imports UserRepository. This ensures that the service can be easily tested and swapped out with different implementations if needed.
• For other services, define interfaces in the interfaces.go file within the services package and implement them in separate files just like the password service is an interface which has an argon2 implementation. So now it can easily be swapped out for another implementation if needed without changing the rest of the code that depends on it.
• When you need pointer variables, use the new function to create them instead of creating a redudant variable and then assigning the address of it to the next pointer variable.

For example, instead of the following:

someNum := 100
config.SomeNum = &someNum

Do this instead:

config.SomeNum := new(100)

This is now supported in Go 1.26+ which the project is using. This makes the code cleaner and more concise.

Testing Guidelines

• Write unit tests for as many components as possible to ensure reliability such as repositories, services and handlers as well as plugins.
• Use descriptive names for test cases to clearly indicate their purpose.
• Maintain a high level of code coverage to catch potential issues early.
• A good way to ensure high quality code is to write unit tests first to outline the feature and behaviour you want before implementing it. Then implement the code to make the tests pass. Finally, refactor the code while ensuring all tests still pass.
• Use table-driven tests to cover multiple scenarios in a concise manner.
• Mock external dependencies to isolate the unit being tested.
• Regularly run tests during development to catch issues early.
• Run make format to format the code.
• Run make lint to check if there are any linting issues.
• Run make build to ensure the project builds successfully after changes.
• Then run make test to run all tests in the project.

Documentation Guidelines

• Keep documentation up to date with code changes.
• Use clear and concise language in documentation.
• Include examples where applicable to illustrate usage.
• Document public APIs, functions, and complex logic thoroughly.
• Use markdown format for README files and other documentation.
• Maintain a changelog to track significant changes and updates in the project.
• Use inline code comments to explain non-obvious parts of the code.
• When updating a feature, ensure that any related documentation is also updated to reflect the changes.
• Create all docs in markdown format and within a top level docs/ directory.

Security Guidelines

• Follow best practices for secure coding to prevent vulnerabilities.
• Regularly review and update dependencies to address security issues.
• Make sure to always follow defensive programming practices to prevent potential security breaches.
• Use secure libraries and frameworks that are well-maintained and widely used in the community.
• Implement proper authentication and authorization mechanisms to protect sensitive data and resources.
• Take into account the principle of least privilege when designing access controls.
• Always take into consideration edge cases and loopholes that could be exploited by attackers and implement safeguards against them.

Agent Skills

Always follow the Agent Skills located in the folder .agents/skills/ as it contains all the skills and playbooks you need to follow to make sure you are adhering to the project guidelines and best practices.