this repo has no description
chadtmiller.com
1# PDS File Reorganization Implementation Plan
2
3> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
4
5**Goal:** Reorganize pds.js into logical domain sections with box-style headers for improved readability.
6
7**Architecture:** Reorder existing code into 12 logical domains without changing functionality. Add Unicode box-style section headers. Group related utilities that are currently scattered.
8
9**Tech Stack:** JavaScript, JSDoc
10
11---
12
13## Box Header Format
14
15All section headers use this format (80 chars wide):
16```javascript
17// ╔══════════════════════════════════════════════════════════════════════════════╗
18// ║ SECTION NAME ║
19// ║ Brief description of what this section contains ║
20// ╚══════════════════════════════════════════════════════════════════════════════╝
21```
22
23---
24
25### Task 1: Types & Constants Section
26
27**Files:**
28- Modify: `src/pds.js` (lines 17-84, plus scattered constants)
29
30**Step 1: Create the new section header and gather all types/constants**
31
32Move these items to the top (after the file header comment):
33- `CBOR_FALSE`, `CBOR_TRUE`, `CBOR_NULL`, `CBOR_TAG_CID` (from lines 19-24)
34- `CODEC_DAG_CBOR`, `CODEC_RAW` (from lines 480-481)
35- `TID_CHARS`, `clockId`, `lastTimestamp` (from lines 563-566)
36- `P256_N`, `P256_N_DIV_2` (from lines 638-641)
37- All typedefs: `Env`, `BlockRow`, `RecordRow`, `CommitRow`, `SeqEventRow`, `BlobRow`, `JwtPayload`
38
39Add header:
40```javascript
41// ╔══════════════════════════════════════════════════════════════════════════════╗
42// ║ TYPES & CONSTANTS ║
43// ║ Environment bindings, SQL row types, protocol constants ║
44// ╚══════════════════════════════════════════════════════════════════════════════╝
45```
46
47**Step 2: Run typecheck to verify no breakage**
48
49Run: `npm run typecheck`
50Expected: 0 errors
51
52**Step 3: Commit**
53
54```bash
55git add src/pds.js
56git commit -m "refactor: consolidate types and constants section"
57```
58
59---
60
61### Task 2: Utilities Section
62
63**Files:**
64- Modify: `src/pds.js`
65
66**Step 1: Create utilities section after types/constants**
67
68Move these functions together:
69- `errorResponse()` (from line 92)
70- `bytesToHex()` (from line 990)
71- `hexToBytes()` (from line 1001)
72- `bytesToBigInt()` (from line 647)
73- `bigIntToBytes()` (from line 660)
74- `base32Encode()` (from line 538)
75- `base32Decode()` (from line 1237)
76- `base64UrlEncode()` (from line 745)
77- `base64UrlDecode()` (from line 759)
78- `varint()` (from line 1211)
79
80Add header:
81```javascript
82// ╔══════════════════════════════════════════════════════════════════════════════╗
83// ║ UTILITIES ║
84// ║ Error responses, byte conversion, base encoding ║
85// ╚══════════════════════════════════════════════════════════════════════════════╝
86```
87
88**Step 2: Run typecheck**
89
90Run: `npm run typecheck`
91Expected: 0 errors
92
93**Step 3: Commit**
94
95```bash
96git add src/pds.js
97git commit -m "refactor: consolidate utilities section"
98```
99
100---
101
102### Task 3: CBOR Encoding Section
103
104**Files:**
105- Modify: `src/pds.js`
106
107**Step 1: Create CBOR section**
108
109Keep together (already grouped, just add new header):
110- `encodeHead()`
111- `cborEncode()`
112- `cborEncodeDagCbor()`
113- `cborDecode()`
114
115Replace `// === CBOR ENCODING ===` with:
116```javascript
117// ╔══════════════════════════════════════════════════════════════════════════════╗
118// ║ CBOR ENCODING ║
119// ║ RFC 8949 CBOR and DAG-CBOR for content-addressed data ║
120// ╚══════════════════════════════════════════════════════════════════════════════╝
121```
122
123**Step 2: Run typecheck**
124
125Run: `npm run typecheck`
126Expected: 0 errors
127
128**Step 3: Commit**
129
130```bash
131git add src/pds.js
132git commit -m "refactor: add CBOR encoding section header"
133```
134
135---
136
137### Task 4: Content Identifiers Section
138
139**Files:**
140- Modify: `src/pds.js`
141
142**Step 1: Create CID/TID section**
143
144Group together:
145- `class CID` (from line 238)
146- `createCidWithCodec()` (from line 489)
147- `createCid()` (from line 510)
148- `createBlobCid()` (from line 519)
149- `cidToString()` (from line 528)
150- `cidToBytes()` (from line 1226)
151- `createTid()` (from line 572)
152
153Add header:
154```javascript
155// ╔══════════════════════════════════════════════════════════════════════════════╗
156// ║ CONTENT IDENTIFIERS ║
157// ║ CIDs (content hashes) and TIDs (timestamp IDs) ║
158// ╚══════════════════════════════════════════════════════════════════════════════╝
159```
160
161**Step 2: Run typecheck**
162
163Run: `npm run typecheck`
164Expected: 0 errors
165
166**Step 3: Commit**
167
168```bash
169git add src/pds.js
170git commit -m "refactor: consolidate content identifiers section"
171```
172
173---
174
175### Task 5: Cryptography Section
176
177**Files:**
178- Modify: `src/pds.js`
179
180**Step 1: Create cryptography section**
181
182Group together:
183- `sha256()` (from line 1016)
184- `importPrivateKey()` (from line 606)
185- `generateKeyPair()` (from line 705)
186- `compressPublicKey()` (from line 728)
187- `sign()` (from line 675)
188
189Add header:
190```javascript
191// ╔══════════════════════════════════════════════════════════════════════════════╗
192// ║ CRYPTOGRAPHY ║
193// ║ P-256 signing with low-S normalization, key management ║
194// ╚══════════════════════════════════════════════════════════════════════════════╝
195```
196
197**Step 2: Run typecheck**
198
199Run: `npm run typecheck`
200Expected: 0 errors
201
202**Step 3: Commit**
203
204```bash
205git add src/pds.js
206git commit -m "refactor: create cryptography section"
207```
208
209---
210
211### Task 6: Authentication Section
212
213**Files:**
214- Modify: `src/pds.js`
215
216**Step 1: Create authentication section**
217
218Group together:
219- `hmacSign()` (from line 777)
220- `createAccessJwt()` (from line 800)
221- `createRefreshJwt()` (from line 829)
222- `verifyJwt()` (from line 876)
223- `verifyAccessJwt()` (from line 919)
224- `verifyRefreshJwt()` (from line 931)
225- `createServiceJwt()` (from line 952)
226
227Add header:
228```javascript
229// ╔══════════════════════════════════════════════════════════════════════════════╗
230// ║ AUTHENTICATION ║
231// ║ JWT creation/verification for sessions and service auth ║
232// ╚══════════════════════════════════════════════════════════════════════════════╝
233```
234
235**Step 2: Run typecheck**
236
237Run: `npm run typecheck`
238Expected: 0 errors
239
240**Step 3: Commit**
241
242```bash
243git add src/pds.js
244git commit -m "refactor: create authentication section"
245```
246
247---
248
249### Task 7: Merkle Search Tree Section
250
251**Files:**
252- Modify: `src/pds.js`
253
254**Step 1: Update MST section header**
255
256Keep together (already grouped):
257- `keyDepthCache`
258- `getKeyDepth()`
259- `commonPrefixLen()`
260- `class MST`
261
262Replace `// === MERKLE SEARCH TREE ===` with:
263```javascript
264// ╔══════════════════════════════════════════════════════════════════════════════╗
265// ║ MERKLE SEARCH TREE ║
266// ║ MST for ATProto repository structure ║
267// ╚══════════════════════════════════════════════════════════════════════════════╝
268```
269
270**Step 2: Run typecheck**
271
272Run: `npm run typecheck`
273Expected: 0 errors
274
275**Step 3: Commit**
276
277```bash
278git add src/pds.js
279git commit -m "refactor: update MST section header"
280```
281
282---
283
284### Task 8: CAR Files Section
285
286**Files:**
287- Modify: `src/pds.js`
288
289**Step 1: Update CAR section**
290
291Keep only:
292- `buildCarFile()`
293
294(Note: `varint()`, `cidToBytes()`, `base32Decode()` moved to earlier sections)
295
296Replace `// === CAR FILE BUILDER ===` with:
297```javascript
298// ╔══════════════════════════════════════════════════════════════════════════════╗
299// ║ CAR FILES ║
300// ║ Content Addressable aRchive format for repo sync ║
301// ╚══════════════════════════════════════════════════════════════════════════════╝
302```
303
304**Step 2: Run typecheck**
305
306Run: `npm run typecheck`
307Expected: 0 errors
308
309**Step 3: Commit**
310
311```bash
312git add src/pds.js
313git commit -m "refactor: update CAR files section"
314```
315
316---
317
318### Task 9: Blob Handling Section
319
320**Files:**
321- Modify: `src/pds.js`
322
323**Step 1: Create blob handling section**
324
325Group together:
326- `sniffMimeType()` (from line 105)
327- `findBlobRefs()` (from line 181)
328- `CRAWL_NOTIFY_THRESHOLD`, `lastCrawlNotify` (from lines 207-208)
329- `notifyCrawlers()` (from line 214)
330
331Add header:
332```javascript
333// ╔══════════════════════════════════════════════════════════════════════════════╗
334// ║ BLOB HANDLING ║
335// ║ MIME detection, blob reference scanning, crawler notification ║
336// ╚══════════════════════════════════════════════════════════════════════════════╝
337```
338
339**Step 2: Run typecheck**
340
341Run: `npm run typecheck`
342Expected: 0 errors
343
344**Step 3: Commit**
345
346```bash
347git add src/pds.js
348git commit -m "refactor: create blob handling section"
349```
350
351---
352
353### Task 10: Routing Section
354
355**Files:**
356- Modify: `src/pds.js`
357
358**Step 1: Add routing section header**
359
360Before `RouteHandler` callback typedef, add:
361```javascript
362// ╔══════════════════════════════════════════════════════════════════════════════╗
363// ║ ROUTING ║
364// ║ XRPC endpoint definitions ║
365// ╚══════════════════════════════════════════════════════════════════════════════╝
366```
367
368This section contains:
369- `RouteHandler` (callback typedef)
370- `Route` (typedef)
371- `pdsRoutes`
372
373**Step 2: Run typecheck**
374
375Run: `npm run typecheck`
376Expected: 0 errors
377
378**Step 3: Commit**
379
380```bash
381git add src/pds.js
382git commit -m "refactor: add routing section header"
383```
384
385---
386
387### Task 11: Personal Data Server Section
388
389**Files:**
390- Modify: `src/pds.js`
391
392**Step 1: Add PDS class section header**
393
394Before `class PersonalDataServer`, add:
395```javascript
396// ╔══════════════════════════════════════════════════════════════════════════════╗
397// ║ PERSONAL DATA SERVER ║
398// ║ Durable Object class implementing ATProto PDS ║
399// ╚══════════════════════════════════════════════════════════════════════════════╝
400```
401
402**Step 2: Run typecheck**
403
404Run: `npm run typecheck`
405Expected: 0 errors
406
407**Step 3: Commit**
408
409```bash
410git add src/pds.js
411git commit -m "refactor: add PDS class section header"
412```
413
414---
415
416### Task 12: Workers Entry Point Section
417
418**Files:**
419- Modify: `src/pds.js`
420
421**Step 1: Add workers entry point section header**
422
423Before `corsHeaders`, add:
424```javascript
425// ╔══════════════════════════════════════════════════════════════════════════════╗
426// ║ WORKERS ENTRY POINT ║
427// ║ Request handling, CORS, auth middleware ║
428// ╚══════════════════════════════════════════════════════════════════════════════╝
429```
430
431This section contains:
432- `corsHeaders`
433- `addCorsHeaders()`
434- `getSubdomain()`
435- `requireAuth()`
436- `handleAuthenticatedBlobUpload()`
437- `handleAuthenticatedRepoWrite()`
438- `handleRequest()`
439- `default export`
440
441**Step 2: Run typecheck**
442
443Run: `npm run typecheck`
444Expected: 0 errors
445
446**Step 3: Commit**
447
448```bash
449git add src/pds.js
450git commit -m "refactor: add workers entry point section header"
451```
452
453---
454
455### Task 13: Final Verification
456
457**Step 1: Run full typecheck**
458
459Run: `npm run typecheck`
460Expected: 0 errors
461
462**Step 2: Run tests**
463
464Run: `npm test`
465Expected: All tests pass
466
467**Step 3: Run e2e tests if available**
468
469Run: `npm run test:e2e`
470Expected: All tests pass
471
472**Step 4: Final commit if any cleanup needed**
473
474```bash
475git add src/pds.js
476git commit -m "refactor: complete pds.js reorganization with box headers"
477```
478
479---
480
481## Section Order Summary
482
483Final file structure (top to bottom):
4841. File header comment
4852. TYPES & CONSTANTS
4863. UTILITIES
4874. CBOR ENCODING
4885. CONTENT IDENTIFIERS
4896. CRYPTOGRAPHY
4907. AUTHENTICATION
4918. MERKLE SEARCH TREE
4929. CAR FILES
49310. BLOB HANDLING
49411. ROUTING
49512. PERSONAL DATA SERVER
49613. WORKERS ENTRY POINT