Unverified Commit 09b29f9e authored by Hong Minhee's avatar Hong Minhee
Browse files

Add LLM coding agent instructions 



Create instructions for LLM coding agents with guidelines for working
with the Fedify codebase. Instructions follow the project's Markdown
conventions and cover key aspects of development workflow.

[ci skip]

Co-Authored-By: default avatarClaude <noreply@anthropic.com>
parent ab931192

.cursorrules

0 → 120000
+1 −0
Original line number Diff line number Diff line 
.github/copilot-instructions.md
 
 No newline at end of file

.github/copilot-instructions.md

0 → 100644
+205 −0
Original line number Diff line number Diff line 
<!-- deno-fmt-ignore-file -->



Fedify LLM Coding Agent Instructions

====================================



This file contains instructions for LLM coding agents working with the Fedify

codebase.





Project Overview

----------------



Fedify is a TypeScript library for building federated server applications

powered by ActivityPub and related standards, facilitating integration with

the Fediverse. The project aims to eliminate complexity and boilerplate code

when implementing federation protocols.



Main features:



 -  Type-safe ActivityPub vocabulary implementation

 -  WebFinger client and server

 -  HTTP Signatures and Linked Data Signatures

 -  Object Integrity Proofs

 -  Federation middleware for handling webhooks

 -  NodeInfo protocol support

 -  Interoperability with Mastodon and other fediverse software

 -  Integration with various web frameworks

 -  CLI toolchain for testing and debugging





Development Environment

-----------------------



 -  Primary development environment: [Deno]

 -  Additional test environments: [Node.js] and [Bun]

 -  Recommended editor: [Visual Studio Code] with [Deno extension]

 -  Important: Run `deno task codegen` before working with the codebase (for

    code generation)



[Deno]: https://deno.com/

[Node.js]: https://nodejs.org/

[Bun]: https://bun.sh/

[Visual Studio Code]: https://code.visualstudio.com/

[Deno extension]: https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno





Repository Structure

--------------------



 -  *cli/*: Fedify CLI implementation (built with Deno)

 -  *docs/*: Documentation built with Node.js and VitePress

 -  *examples/*: Example projects demonstrating Fedify usage

 -  *src/*: Main library code

    -  *codegen/*: Code generation scripts

    -  *compat/*: Compatibility layer

    -  *federation/*: Core federation functionality

    -  *nodeinfo/*: NodeInfo protocol implementation

    -  *runtime/*: Runtime utilities

    -  *shim/*: Platform abstraction layer

    -  *sig/*: Signature implementation

    -  *testing/*: Testing utilities

    -  *vocab/*: ActivityPub vocabulary implementation

    -  *webfinger/*: WebFinger protocol implementation

    -  *x/*: Framework integrations





Code Patterns and Principles

----------------------------



1. **Builder Pattern**: The `FederationBuilder` class follows a fluent builder

   pattern for configuring federation components.



2. **Dispatcher Callbacks**: Use function callbacks for mapping routes to

   handlers, following the pattern in existing dispatchers.



3. **Type Safety**: Maintain strict TypeScript typing throughout. Use generics

   like `<TContextData>` to allow applications to customize context data.



4. **Testing**: Follow the existing test patterns using Deno's testing

   framework. Use in-memory stores for testing.



5. **Framework Agnostic**: Code should work across Deno, Node.js, and Bun

   environments.



6. **ActivityPub Objects**: All vocabulary objects follow the class pattern

   established in the *vocab/* directory.





Development Workflow

--------------------



1. **Code Generation**: Run `deno task codegen` whenever vocabulary YAML files

   or code generation scripts change.



2. **Checking Code**: Before committing, run `deno task check` in the *src/*

   directory.



3. **Running Tests**: Use `deno task test` for basic tests or

   `deno task test-all` to test across all environments.



4. **Documentation**: Follow the Markdown conventions in CONTRIBUTING.md:

    -  80 characters per line (except for code blocks and URLs)

    -  Use reference links over inline links

    -  Use setext headings over ATX headings

    -  Two new lines before H1/H2 headings

    -  Wrap file paths in asterisks

    -  Code blocks should use quadruple tildes with language specified





Federation Handling

-------------------



When working with federation code:



1. Use the builder pattern following the `FederationBuilder` class

2. Implement proper HTTP signature verification for security

3. Keep ActivityPub compliance in mind for interoperability

4. Follow existing patterns for handling inbox/outbox operations

5. Use the queue system for background processing of federation activities





Common Tasks

------------



### Adding ActivityPub Vocabulary Types



1. Create a new YAML file in *src/vocab/* following existing patterns

2. Run `deno task codegen` to generate TypeScript classes

3. Export the new types from appropriate module files



### Implementing Framework Integrations



1. Add new integrations in the *src/x/* directory

2. Follow pattern from existing integrations (hono.ts, sveltekit.ts)

3. Use standard request/response interfaces for compatibility



### Creating Database Adapters



1. Implement the KV store interface in *src/federation/kv.ts*

2. Implement the message queue interface in *src/federation/mq.ts*

3. Add new file in *src/x/* for specific database adaptations





Important Security Considerations

---------------------------------



1. **HTTP Signatures**: Always verify HTTP signatures for incoming federation

   requests

2. **Object Integrity**: Use Object Integrity Proofs for content verification

3. **Key Management**: Follow best practices for key storage and rotation

4. **Rate Limiting**: Implement rate limiting for public endpoints

5. **Input Validation**: Validate all input from federated sources





Testing Requirements

--------------------



1. Write unit tests for all new functionality

2. Follow the pattern of existing tests

3. Use the testing utilities in *src/testing/*

4. Consider interoperability with other fediverse software





Documentation Standards

-----------------------



1. Include JSDoc comments for public APIs

2. Update documentation when changing public APIs

3. Follow Markdown conventions as described in CONTRIBUTING.md

4. Include examples for new features





Bugfix Process

--------------



When fixing bugs:



1. Add regression tests that demonstrate the bug

2. Fix the bug

3. Update CHANGES.md with the issue number, PR number, and your name

4. Target the oldest applicable maintenance branch





Feature Implementation Process

------------------------------



When adding features:



1. Add unit tests for the new feature

2. Implement the feature

3. Update documentation for API changes

4. Verify examples work with the change

5. Update CHANGES.md with details

6. Target the main branch





Build and Distribution

----------------------



The project uses a custom build process to support multiple environments:

1. Deno-native modules

2. npm package via dnt (Deno to Node Transform)

3. JSR package distribution



Ensure changes work across all distribution formats.

.windsurfrules

0 → 120000
+1 −0
Original line number Diff line number Diff line 
.github/copilot-instructions.md
 
 No newline at end of file

CLAUDE.md

0 → 120000
+1 −0
Original line number Diff line number Diff line 
.github/copilot-instructions.md
 
 No newline at end of file

CONTRIBUTING.md

+7 −0
Original line number Diff line number Diff line
@@ -232,6 +232,13 @@ the following command: 
deno task -f @fedify/fedify test

~~~~



Or you can use `--filter` option to run a specific test.  For example, if you

want to run the `verifyRequest` test:



~~~~ bash

deno task -f @fedify/fedify test --filter verifyRequest

~~~~



If the tests pass, you should run `deno task test-all` command to test

the library with Deno, Node.js, and [Bun]: