chadtmiller.com/pds.js
An atproto PDS in JavaScript, for Cloudflare Workers and Node
0
0
# Package Restructure Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Reorganize packages to use `src/` and `test/` folders for better discoverability and encapsulation.
**Architecture:** Move source files into `src/` subdirectories, update package.json exports, create `test/` folders for unit tests. E2E tests remain centralized. No build step required.
**Tech Stack:** pnpm workspaces, Vitest, TypeScript declarations.
---
## Task 1: Restructure blobs-fs Package
**Files:**
- Create: `packages/blobs-fs/src/`
- Move: `packages/blobs-fs/index.js` → `packages/blobs-fs/src/index.js`
- Modify: `packages/blobs-fs/package.json`
**Step 1: Create src directory and move source file**
```bash
mkdir -p packages/blobs-fs/src
mv packages/blobs-fs/index.js packages/blobs-fs/src/
```
**Step 2: Update package.json**
Replace `packages/blobs-fs/package.json` with:
```json
{
"name": "@pdsjs/blobs-fs",
"version": "0.1.0",
"type": "module",
"main": "./src/index.js",
"types": "./src/index.d.ts",
"exports": {
".": "./src/index.js"
}
}
```
**Step 3: Create empty test directory**
```bash
mkdir -p packages/blobs-fs/test
```
**Step 4: Verify package resolves**
```bash
node -e "import('@pdsjs/blobs-fs').then(m => console.log('OK:', Object.keys(m)))"
```
Expected: `OK: [ 'createFsBlobs' ]` (or similar export names)
**Step 5: Commit**
```bash
git add packages/blobs-fs/
git commit -m "refactor(blobs-fs): move source to src/ folder"
```
---
## Task 2: Restructure blobs-s3 Package
**Files:**
- Create: `packages/blobs-s3/src/`
- Move: `packages/blobs-s3/index.js` → `packages/blobs-s3/src/index.js`
- Modify: `packages/blobs-s3/package.json`
**Step 1: Create src directory and move source file**
```bash
mkdir -p packages/blobs-s3/src
mv packages/blobs-s3/index.js packages/blobs-s3/src/
```
**Step 2: Update package.json**
Replace `packages/blobs-s3/package.json` with:
```json
{
"name": "@pdsjs/blobs-s3",
"version": "0.1.0",
"type": "module",
"main": "./src/index.js",
"types": "./src/index.d.ts",
"exports": {
".": "./src/index.js"
}
}
```
**Step 3: Create empty test directory**
```bash
mkdir -p packages/blobs-s3/test
```
**Step 4: Verify package resolves**
```bash
node -e "import('@pdsjs/blobs-s3').then(m => console.log('OK:', Object.keys(m)))"
```
Expected: `OK: [ 'createS3Blobs' ]` (or similar)
**Step 5: Commit**
```bash
git add packages/blobs-s3/
git commit -m "refactor(blobs-s3): move source to src/ folder"
```
---
## Task 3: Restructure blobs-deno Package
**Files:**
- Create: `packages/blobs-deno/src/`
- Move: `packages/blobs-deno/index.js` → `packages/blobs-deno/src/index.js`
- Modify: `packages/blobs-deno/package.json`
- Modify: `packages/blobs-deno/deno.json`
**Step 1: Create src directory and move source file**
```bash
mkdir -p packages/blobs-deno/src
mv packages/blobs-deno/index.js packages/blobs-deno/src/
```
**Step 2: Update package.json**
Replace `packages/blobs-deno/package.json` with:
```json
{
"name": "@pdsjs/blobs-deno",
"version": "0.1.0",
"type": "module",
"main": "./src/index.js",
"types": "./src/index.d.ts",
"exports": {
".": "./src/index.js"
}
}
```
**Step 3: Update deno.json exports**
Update `packages/blobs-deno/deno.json` to point to src:
```json
{
"name": "@pdsjs/blobs-deno",
"version": "0.1.0",
"exports": "./src/index.js"
}
```
**Step 4: Create empty test directory**
```bash
mkdir -p packages/blobs-deno/test
```
**Step 5: Commit**
```bash
git add packages/blobs-deno/
git commit -m "refactor(blobs-deno): move source to src/ folder"
```
---
## Task 4: Restructure storage-sqlite Package
**Files:**
- Create: `packages/storage-sqlite/src/`
- Move: `packages/storage-sqlite/index.js` → `packages/storage-sqlite/src/index.js`
- Move: `packages/storage-sqlite/driver.js` → `packages/storage-sqlite/src/driver.js`
- Modify: `packages/storage-sqlite/package.json`
**Step 1: Create src directory and move source files**
```bash
mkdir -p packages/storage-sqlite/src
mv packages/storage-sqlite/index.js packages/storage-sqlite/src/
mv packages/storage-sqlite/driver.js packages/storage-sqlite/src/
```
**Step 2: Update package.json**
Replace `packages/storage-sqlite/package.json` with:
```json
{
"name": "@pdsjs/storage-sqlite",
"version": "0.1.0",
"type": "module",
"main": "./src/index.js",
"types": "./src/index.d.ts",
"exports": {
".": "./src/index.js",
"./driver": "./src/driver.js"
},
"peerDependencies": {
"better-sqlite3": ">=9.0.0"
}
}
```
**Step 3: Create empty test directory**
```bash
mkdir -p packages/storage-sqlite/test
```
**Step 4: Verify package resolves**
```bash
node -e "import('@pdsjs/storage-sqlite').then(m => console.log('OK:', Object.keys(m)))"
```
Expected: `OK: [ 'createBetterSqliteStorage' ]` (or similar)
**Step 5: Commit**
```bash
git add packages/storage-sqlite/
git commit -m "refactor(storage-sqlite): move source to src/ folder"
```
---
## Task 5: Restructure core Package
**Files:**
- Create: `packages/core/src/`
- Move: All `.js` files to `packages/core/src/`
- Modify: `packages/core/package.json`
**Step 1: Create src directory and move all source files**
```bash
mkdir -p packages/core/src
mv packages/core/*.js packages/core/src/
```
**Step 2: Update package.json**
Replace `packages/core/package.json` with:
```json
{
"name": "@pdsjs/core",
"version": "0.1.0",
"type": "module",
"main": "./src/index.js",
"types": "./src/index.d.ts",
"exports": {
".": "./src/index.js",
"./repo": "./src/repo.js",
"./auth": "./src/auth.js",
"./crypto": "./src/crypto.js",
"./ports": "./src/ports.js",
"./pds": "./src/pds.js",
"./scope": "./src/scope.js",
"./oauth": "./src/oauth.js"
}
}
```
**Step 3: Create empty test directory**
```bash
mkdir -p packages/core/test
```
**Step 4: Verify package resolves**
```bash
node -e "import('@pdsjs/core').then(m => console.log('OK:', Object.keys(m)))"
node -e "import('@pdsjs/core/pds').then(m => console.log('OK pds:', Object.keys(m)))"
```
Expected: Lists of exports for each
**Step 5: Commit**
```bash
git add packages/core/
git commit -m "refactor(core): move source to src/ folder"
```
---
## Task 6: Restructure node Package
**Files:**
- Create: `packages/node/src/`
- Move: `packages/node/index.js` → `packages/node/src/index.js`
- Modify: `packages/node/package.json`
**Step 1: Create src directory and move source file**
```bash
mkdir -p packages/node/src
mv packages/node/index.js packages/node/src/
```
**Step 2: Update package.json**
Replace `packages/node/package.json` with:
```json
{
"name": "@pdsjs/node",
"version": "0.1.0",
"type": "module",
"main": "./src/index.js",
"types": "./src/index.d.ts",
"exports": {
".": "./src/index.js"
},
"dependencies": {
"@pdsjs/blobs-fs": "workspace:*",
"@pdsjs/core": "workspace:*",
"@pdsjs/storage-sqlite": "workspace:*",
"ws": "^8.19.0"
},
"peerDependencies": {
"better-sqlite3": ">=9.0.0"
}
}
```
**Step 3: Create empty test directory**
```bash
mkdir -p packages/node/test
```
**Step 4: Verify package resolves**
```bash
node -e "import('@pdsjs/node').then(m => console.log('OK:', Object.keys(m)))"
```
Expected: `OK: [ 'createServer' ]` (or similar)
**Step 5: Commit**
```bash
git add packages/node/
git commit -m "refactor(node): move source to src/ folder"
```
---
## Task 7: Restructure deno Package
**Files:**
- Create: `packages/deno/src/`
- Move: `packages/deno/index.js` → `packages/deno/src/index.js`
- Modify: `packages/deno/package.json`
- Modify: `packages/deno/deno.json`
**Step 1: Create src directory and move source file**
```bash
mkdir -p packages/deno/src
mv packages/deno/index.js packages/deno/src/
```
**Step 2: Update package.json**
Replace `packages/deno/package.json` with:
```json
{
"name": "@pdsjs/deno",
"version": "0.1.0",
"type": "module",
"main": "./src/index.js",
"types": "./src/index.d.ts",
"exports": {
".": "./src/index.js"
}
}
```
**Step 3: Update deno.json exports**
Update `packages/deno/deno.json` to point to src:
```json
{
"name": "@pdsjs/deno",
"version": "0.1.0",
"exports": "./src/index.js",
"imports": {
"@pdsjs/core": "../core/src/index.js",
"@pdsjs/core/pds": "../core/src/pds.js",
"@pdsjs/storage-sqlite": "../storage-sqlite/src/index.js",
"@pdsjs/storage-sqlite/driver": "../storage-sqlite/src/driver.js",
"@pdsjs/blobs-deno": "../blobs-deno/src/index.js"
}
}
```
**Step 4: Create empty test directory**
```bash
mkdir -p packages/deno/test
```
**Step 5: Commit**
```bash
git add packages/deno/
git commit -m "refactor(deno): move source to src/ folder"
```
---
## Task 8: Restructure cloudflare Package
**Files:**
- Create: `packages/cloudflare/src/`
- Move: `packages/cloudflare/index.js` → `packages/cloudflare/src/index.js`
- Modify: `packages/cloudflare/package.json`
**Step 1: Create src directory and move source file**
```bash
mkdir -p packages/cloudflare/src
mv packages/cloudflare/index.js packages/cloudflare/src/
```
**Step 2: Update package.json**
Replace `packages/cloudflare/package.json` with:
```json
{
"name": "@pdsjs/cloudflare",
"version": "0.1.0",
"type": "module",
"main": "./src/index.js",
"types": "./src/index.d.ts",
"exports": {
".": "./src/index.js"
},
"dependencies": {
"@pdsjs/core": "workspace:*"
}
}
```
**Step 3: Create empty test directory**
```bash
mkdir -p packages/cloudflare/test
```
**Step 4: Verify package resolves**
```bash
node -e "import('@pdsjs/cloudflare').then(m => console.log('OK:', Object.keys(m)))"
```
Expected: `OK: [ 'createCloudflareHandler', 'PDSDurableObject' ]` (or similar)
**Step 5: Commit**
```bash
git add packages/cloudflare/
git commit -m "refactor(cloudflare): move source to src/ folder"
```
---
## Task 9: Update Vitest Configuration
**Files:**
- Modify: `vitest.config.js`
**Step 1: Update vitest.config.js**
Replace `vitest.config.js` with:
```javascript
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
include: [
'packages/*/test/**/*.test.js',
'test/**/*.test.js'
],
testTimeout: 30000,
hookTimeout: 60000,
coverage: {
provider: 'v8',
reporter: ['text', 'html'],
include: ['packages/*/src/**/*.js'],
},
},
});
```
**Step 2: Verify test discovery still works**
```bash
npm test
```
Expected: Existing tests in `test/` still run and pass.
**Step 3: Commit**
```bash
git add vitest.config.js
git commit -m "build: update vitest config for new package structure"
```
---
## Task 10: Update TypeScript Build Configuration
**Files:**
- Modify: `tsconfig.build.json`
**Step 1: Check current tsconfig.build.json**
Read the file to understand current include patterns.
**Step 2: Update include patterns for src/ folders**
Update `tsconfig.build.json` to generate `.d.ts` files in `src/` directories:
```json
{
"extends": "./tsconfig.json",
"compilerOptions": {
"declaration": true,
"emitDeclarationOnly": true
},
"include": ["packages/*/src/**/*.js"]
}
```
**Step 3: Regenerate type declarations**
```bash
rm -f packages/*/*.d.ts packages/*/src/*.d.ts
npm run typecheck
```
Expected: New `.d.ts` files appear in `packages/*/src/`
**Step 4: Commit**
```bash
git add tsconfig.build.json packages/*/src/*.d.ts
git commit -m "build: update tsconfig for src/ structure, regenerate types"
```
---
## Task 11: Update Examples to Use New Paths
**Files:**
- Check: `examples/node/`
- Check: `examples/deno/`
- Check: `examples/cloudflare/`
**Step 1: Verify examples still work**
Since examples import via package names (`@pdsjs/node`), they should work without changes. Verify:
```bash
cd examples/node && node -e "import('@pdsjs/node').then(m => console.log('OK'))"
```
Expected: `OK`
**Step 2: Run E2E tests to verify everything works**
```bash
npm run test:e2e:node
```
Expected: All E2E tests pass.
**Step 3: Commit any fixes if needed**
```bash
git add -A
git commit -m "fix: update examples for new package structure" --allow-empty
```
---
## Task 12: Clean Up Old Declaration Files
**Files:**
- Remove: `packages/*/*.d.ts` (old location)
**Step 1: Remove old .d.ts files from package roots**
```bash
rm -f packages/blobs-fs/*.d.ts
rm -f packages/blobs-s3/*.d.ts
rm -f packages/blobs-deno/*.d.ts
rm -f packages/storage-sqlite/*.d.ts
rm -f packages/core/*.d.ts
rm -f packages/node/*.d.ts
rm -f packages/deno/*.d.ts
rm -f packages/cloudflare/*.d.ts
```
**Step 2: Verify no stray files remain**
```bash
ls packages/*/*.d.ts 2>/dev/null || echo "Clean - no old .d.ts files"
```
Expected: "Clean - no old .d.ts files"
**Step 3: Commit cleanup**
```bash
git add -A
git commit -m "chore: remove old .d.ts files from package roots"
```
---
## Task 13: Final Verification
**Step 1: Run full test suite**
```bash
npm test
npm run test:e2e:node
```
Expected: All tests pass.
**Step 2: Run type check**
```bash
npm run typecheck
```
Expected: No errors.
**Step 3: Run lint**
```bash
npm run check
```
Expected: No errors.
**Step 4: Final commit if any stragglers**
```bash
git status
git add -A
git commit -m "refactor: complete package restructure to src/test layout" --allow-empty
```
---
## Summary
| Task | Description | Commit Message |
|------|-------------|----------------|
| 1 | Restructure blobs-fs | `refactor(blobs-fs): move source to src/ folder` |
| 2 | Restructure blobs-s3 | `refactor(blobs-s3): move source to src/ folder` |
| 3 | Restructure blobs-deno | `refactor(blobs-deno): move source to src/ folder` |
| 4 | Restructure storage-sqlite | `refactor(storage-sqlite): move source to src/ folder` |
| 5 | Restructure core | `refactor(core): move source to src/ folder` |
| 6 | Restructure node | `refactor(node): move source to src/ folder` |
| 7 | Restructure deno | `refactor(deno): move source to src/ folder` |
| 8 | Restructure cloudflare | `refactor(cloudflare): move source to src/ folder` |
| 9 | Update vitest config | `build: update vitest config for new package structure` |
| 10 | Update tsconfig | `build: update tsconfig for src/ structure, regenerate types` |
| 11 | Verify examples | `fix: update examples for new package structure` |
| 12 | Clean up old .d.ts | `chore: remove old .d.ts files from package roots` |
| 13 | Final verification | `refactor: complete package restructure to src/test layout` |