From 32ca410f4edbff578d71781d943c41573912f476 Mon Sep 17 00:00:00 2001
From: amrkmn
Date: Fri, 26 Dec 2025 22:39:23 +0800
Subject: Initial commit

---
 AGENTS.md | 184 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 184 insertions(+)
 create mode 100644 AGENTS.md

(limited to 'AGENTS.md')

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..005c5b0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,184 @@
+# Agent Instructions for Mihon/Aniyomi Extensions Aggregator
+
+This repository is a SvelteKit project managed with **Bun**. It aggregates extensions for Mihon and Aniyomi, serving them as a static site with an API-like structure in `static/`.
+
+## 1. Environment & Toolchain
+
+- **Runtime**: `bun` (Do not use `npm` or `yarn` or `pnpm`).
+- **Framework**: SvelteKit (Svelte 5).
+- **Language**: TypeScript (Strict mode).
+- **Search**: Meilisearch (client-side integration).
+
+## 2. Development Commands
+
+### Build & Run
+
+- **Install dependencies**:
+    ```bash
+    bun install
+    ```
+- **Start dev server**:
+    ```bash
+    bun run dev
+    ```
+- **Build production output**:
+    ```bash
+    bun run build
+    ```
+    _Note: This runs `bun run update --generate-only` first to regenerate `static/data.json` before Vite builds._
+
+### Linting & Verification
+
+- **Type Check**:
+    ```bash
+    bun run check
+    ```
+    _Always run this after making TypeScript or Svelte changes. There are no unit tests, so strict type checking is your primary safety net._
+- **Format Code**:
+    ```bash
+    bun run format
+    ```
+- **Verify Formatting**:
+    ```bash
+    bun run lint
+    ```
+
+### Data Management
+
+- **Update Extensions**:
+    ```bash
+    bun run update
+    ```
+    _Fetches upstream data. Use `--generate-only` to just rebuild `data.json` locally._
+
+### Testing
+
+- **Run all tests**:
+    ```bash
+    bun test
+    ```
+- **Run a single test file**:
+    ```bash
+    bun test tests/debounce.test.ts
+    ```
+- **Run tests with watch mode**:
+    ```bash
+    bun test --watch
+    ```
+
+## 3. Testing Strategy
+
+**Test Framework**: Uses `bun:test` built-in test runner with TypeScript support.
+
+**Test Coverage**:
+
+- Utility functions in `src/lib/search/` (debouncing, source name formatting)
+- Logger utilities in `scripts/cache/` (transfer stats formatting)
+- Cache manifest operations in `scripts/cache/` (finding caches by key/prefix)
+- File operations in `scripts/cache/` (checksums, directory management)
+- Cache lock utilities (instance ID generation, staleness detection)
+- Cache metadata key generation
+- Cache utility functions (key generation, byte formatting)
+
+**Agent Protocol for Verification**:
+
+1.  **Run Tests**: Execute `bun test` to verify existing functionality.
+2.  **Write Tests**: When adding utility functions, add corresponding test files in `tests/`.
+3.  **Type Check**: Always run `bun run check` after making changes.
+4.  **Build Verification**: Run `bun run build` to ensure static adapter and prerendering complete successfully.
+
+## 4. Code Style & Conventions
+
+### Formatting (Enforced by Prettier)
+
+- **Indentation**: 4 spaces.
+- **Quotes**: Single quotes (`'`).
+- **Trailing Commas**: `none`.
+- **Line Width**: 100 characters.
+- **Line Endings**: LF (`\n`).
+
+### TypeScript
+
+- **Strict Mode**: Enabled. No `any` types unless absolutely necessary.
+- **Imports**: Use standard ESM imports.
+    - SvelteKit aliases: `$lib/` is mapped to `src/lib/`.
+- **Interfaces**: Define specific interfaces for data structures (see `src/lib/types.ts` or `src/lib/search/types.ts`).
+
+### Svelte Components (Svelte 5)
+
+- Use `<script lang="ts">`.
+- Components located in `src/lib/components`.
+- Pages in `src/routes`.
+- Use `app.css` for global styles; component-scoped styles are preferred for components.
+
+### Naming Conventions
+
+- **Files**:
+    - Svelte components: `PascalCase.svelte` (e.g., `ExtensionCard.svelte`).
+    - TS utilities: `camelCase.ts` (e.g., `meilisearch.ts`).
+    - SvelteKit routes: `+page.svelte`, `+layout.svelte`, `+server.ts`.
+- **Variables/Functions**: `camelCase`.
+- **Types/Interfaces**: `PascalCase`.
+
+## 5. Architecture Overview
+
+### Backend / Scripts (`scripts/`)
+
+Logic for fetching, updating, and caching extensions lives here, not in the SvelteKit app.
+
+- `update.ts`: Entry point for updates.
+- `cache/`: logic for S3/R2 caching mechanism.
+- `config.ts`: Configuration for domains and file paths.
+
+### Frontend (`src/`)
+
+- **Data Source**: The app fetches `data.json` (generated by scripts) via `fetch` in `+layout.ts`.
+- **Search**: Uses Meilisearch. Logic is in `src/lib/search/`.
+- **Routing**: Static routing. The "API" is just static JSON files hosted in the same directory structure.
+
+### Cache System
+
+- Uses `tar.zst` archives stored in S3-compatible storage (R2/B2).
+- **Do not modify** cache logic (`scripts/cache/`) without fully understanding the manifest and distributed locking system described in `CLAUDE.md`.
+
+## 6. Common Tasks
+
+**Adding a new Component**
+
+1. Create `src/lib/components/Name.svelte`.
+2. Add necessary props/state using Svelte 5 syntax.
+3. Run `bun run format` to ensure style.
+
+**Modifying Extension Logic**
+
+1. Edit `scripts/update.ts` or `scripts/config.ts`.
+2. Run `bun run check` to verify types.
+3. Test by running `bun run update --generate-only`.
+
+**Updating Dependencies**
+
+1. Use `bun add <package>` or `bun add -d <package>`.
+2. Do not update `bun.lock` manually.
+
+**Writing Tests**
+
+1. Create test files in `tests/` with the pattern `<module>.test.ts`.
+2. Use `bun:test` test runner: `import { test, expect } from 'bun:test'`.
+3. Use `Bun.sleep(ms)` for async test delays.
+4. Run `bun test` to verify tests pass.
+
+## 7. Error Handling
+
+- **Scripts**: Use try/catch blocks in async functions. Log errors explicitly to console (see `scripts/cache/logger.ts`).
+- **Frontend**: Handle fetch failures gracefully (e.g., if `data.json` fails to load).
+- **Type Safety**: Avoid non-null assertions (`!`) if possible; use optional chaining (`?.`) and nullish coalescing (`??`).
+
+## 8. Deployment
+
+- **CI**: GitHub Actions (`.github/workflows/update.yml`) handles updates and mirroring.
+- **Environment Variables**: Local dev requires `.env`. See `.env.example`.
+    - `S3_*` variables are required for full update/cache operations.
+
+---
+
+_Generated for AI Agents interacting with this codebase._
-- 
cgit