# 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` |