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

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:

{
  "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

mkdir -p packages/blobs-fs/test

Step 4: Verify package resolves

node -e "import('@pdsjs/blobs-fs').then(m => console.log('OK:', Object.keys(m)))"

Expected: OK: [ 'createFsBlobs' ] (or similar export names)

Step 5: Commit

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

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:

{
  "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

mkdir -p packages/blobs-s3/test

Step 4: Verify package resolves

node -e "import('@pdsjs/blobs-s3').then(m => console.log('OK:', Object.keys(m)))"

Expected: OK: [ 'createS3Blobs' ] (or similar)

Step 5: Commit

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

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:

{
  "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:

{
  "name": "@pdsjs/blobs-deno",
  "version": "0.1.0",
  "exports": "./src/index.js"
}

Step 4: Create empty test directory

mkdir -p packages/blobs-deno/test

Step 5: Commit

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

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:

{
  "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

mkdir -p packages/storage-sqlite/test

Step 4: Verify package resolves

node -e "import('@pdsjs/storage-sqlite').then(m => console.log('OK:', Object.keys(m)))"

Expected: OK: [ 'createBetterSqliteStorage' ] (or similar)

Step 5: Commit

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

mkdir -p packages/core/src
mv packages/core/*.js packages/core/src/

Step 2: Update package.json

Replace packages/core/package.json with:

{
  "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

mkdir -p packages/core/test

Step 4: Verify package resolves

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

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

mkdir -p packages/node/src
mv packages/node/index.js packages/node/src/

Step 2: Update package.json

Replace packages/node/package.json with:

{
  "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

mkdir -p packages/node/test

Step 4: Verify package resolves

node -e "import('@pdsjs/node').then(m => console.log('OK:', Object.keys(m)))"

Expected: OK: [ 'createServer' ] (or similar)

Step 5: Commit

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

mkdir -p packages/deno/src
mv packages/deno/index.js packages/deno/src/

Step 2: Update package.json

Replace packages/deno/package.json with:

{
  "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:

{
  "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

mkdir -p packages/deno/test

Step 5: Commit

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

mkdir -p packages/cloudflare/src
mv packages/cloudflare/index.js packages/cloudflare/src/

Step 2: Update package.json

Replace packages/cloudflare/package.json with:

{
  "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

mkdir -p packages/cloudflare/test

Step 4: Verify package resolves

node -e "import('@pdsjs/cloudflare').then(m => console.log('OK:', Object.keys(m)))"

Expected: OK: [ 'createCloudflareHandler', 'PDSDurableObject' ] (or similar)

Step 5: Commit

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:

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

npm test

Expected: Existing tests in test/ still run and pass.

Step 3: Commit

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:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "declaration": true,
    "emitDeclarationOnly": true
  },
  "include": ["packages/*/src/**/*.js"]
}

Step 3: Regenerate type declarations

rm -f packages/*/*.d.ts packages/*/src/*.d.ts
npm run typecheck

Expected: New .d.ts files appear in packages/*/src/

Step 4: Commit

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:

cd examples/node && node -e "import('@pdsjs/node').then(m => console.log('OK'))"

Expected: OK

Step 2: Run E2E tests to verify everything works

npm run test:e2e:node

Expected: All E2E tests pass.

Step 3: Commit any fixes if needed

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

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

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

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

npm test
npm run test:e2e:node

Expected: All tests pass.

Step 2: Run type check

npm run typecheck

Expected: No errors.

Step 3: Run lint

npm run check

Expected: No errors.

Step 4: Final commit if any stragglers

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`

chadtmiller.com/pds.js Switch repository Loading…

Package Restructure Implementation Plan

Task 1: Restructure blobs-fs Package

Task 2: Restructure blobs-s3 Package

Task 3: Restructure blobs-deno Package

Task 4: Restructure storage-sqlite Package

Task 5: Restructure core Package

Task 6: Restructure node Package

Task 7: Restructure deno Package

Task 8: Restructure cloudflare Package

Task 9: Update Vitest Configuration

Task 10: Update TypeScript Build Configuration

Task 11: Update Examples to Use New Paths

Task 12: Clean Up Old Declaration Files

Task 13: Final Verification

Summary

chadtmiller.com/pds.js

Switch repository

Loading…