# 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._