1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
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._
|
