feat(create-pds): add create-pds cli (#19)

Author: ascorbic

EDGE_PDS_PLAN.md

@@ -108,6 +108,49 @@ Build a single-user AT Protocol Personal Data Server (PDS) on Cloudflare Workers
 
 - None! All planned phases are complete.
 
+### Future Work: did:plc Migration Support
+
+Account migration is now possible from bsky.social. To support users migrating their existing `did:plc` accounts to this PDS, we need to implement the full migration flow.
+
+**Migration Flow (4 phases):**
+
+1. **Account Creation** - New PDS creates account in "deactivated" state with existing DID
+2. **Data Migration** - Export repo as CAR, import to new PDS, migrate blobs
+3. **Identity Update** - Old PDS signs PLC operation, new PDS submits to plc.directory
+4. **Finalization** - Activate on new PDS, deactivate on old
+
+**Endpoints needed for incoming migration:**
+
+| Endpoint                                            | Status | Purpose                               |
+| --------------------------------------------------- | ------ | ------------------------------------- |
+| `com.atproto.server.createAccount`                  | ❌     | Create account with existing DID      |
+| `com.atproto.identity.getRecommendedDidCredentials` | ❌     | Provide DID params for PLC operation  |
+| `com.atproto.identity.submitPlcOperation`           | ❌     | Submit signed PLC op to plc.directory |
+| `com.atproto.server.activateAccount`                | ❌     | Activate migrated account             |
+| `com.atproto.repo.listMissingBlobs`                 | ❌     | Check which blobs need migration      |
+
+**Endpoints needed for outgoing migration:**
+
+| Endpoint                                            | Status | Purpose                                   |
+| --------------------------------------------------- | ------ | ----------------------------------------- |
+| `com.atproto.server.getServiceAuth`                 | ❌     | Generate service auth token for migration |
+| `com.atproto.identity.requestPlcOperationSignature` | ❌     | Request email verification token          |
+| `com.atproto.identity.signPlcOperation`             | ❌     | Sign PLC operation with rotation key      |
+| `com.atproto.server.deactivateAccount`              | ❌     | Deactivate account after migration        |
+
+**Already implemented:**
+
+- ✅ `com.atproto.sync.getRepo` - Export repository as CAR
+- ✅ `com.atproto.repo.importRepo` - Import repository from CAR
+- ✅ `com.atproto.sync.listBlobs` - List blobs for migration
+- ✅ `com.atproto.server.getAccountStatus` - Check account status
+
+**References:**
+
+- [Account Migration - AT Protocol](https://atproto.com/guides/account-migration)
+- [Account Migration Details Discussion](https://github.com/bluesky-social/atproto/discussions/3176)
+- [Enabling Account Migration Back to Bluesky's PDS](https://docs.bsky.app/blog/incoming-migration)
+
 ### Testing & Development Notes
 
 **Vitest 4 Migration**: Successfully migrated to vitest 4 with `@cloudflare/vitest-pool-workers` PR build (#11632). This required:
@@ -195,7 +238,7 @@ for (const [cidStr, bytes] of internalMap) { ... }
 | ----------------- | --------------------------------------- |
 | OAuth Provider    | Complex, not needed for single-user MVP |
 | Rate Limiting     | Single user, not needed for MVP         |
-| Account Migration | Complex, post-MVP feature               |
+| did:plc Migration | Complex - see "Future Work" section     |
 | Labelling         | AppView concern, not PDS                |
 
 ---
@@ -2064,6 +2107,7 @@ wrangler secret put PASSWORD_HASH # Generate: npx bcryptjs hash "your-password"
 - Email verification
 - Rate limiting
 - Advanced admin endpoints
+- Full did:plc migration (partial support exists - see "Future Work" section)
 
 These can all be added later.
 

README.md

@@ -2,6 +2,10 @@
 
 A single-user AT Protocol Personal Data Server (PDS) running on Cloudflare Workers with Durable Objects.
 
+> **⚠️ Experimental Software**
+>
+> This is an early-stage project under active development. **Do not migrate your main Bluesky account to this PDS yet.** Use a test account or create a new identity for experimentation. Data loss, breaking changes, and missing features are expected.
+
 ## Overview
 
 This PDS is designed to federate with the Bluesky network - relays can sync from it, and AppViews can read from it.

demos/pds/README.md

@@ -2,6 +2,10 @@
 
 This is an example deployment of `@ascorbic/pds-worker` - a single-user AT Protocol Personal Data Server on Cloudflare Workers.
 
+> **⚠️ Experimental Software**
+>
+> This is an early-stage project under active development. **Do not migrate your main Bluesky account to this PDS yet.** Use a test account or create a new identity for experimentation.
+
 ## Setup
 
 ### 1. Install dependencies
@@ -15,7 +19,7 @@ pnpm install
 Use the PDS CLI to generate keys and configure your local dev environment:
 
 ```bash
-pnpm pds init --local
+pnpm pds init
 ```
 
 This will prompt for your hostname, handle, and password, then write configuration to `.dev.vars`.

demos/pds/wrangler.jsonc

@@ -1,6 +1,6 @@
 {
 	// Demo PDS Deployment
-	// Run `pnpm pds init` to configure, or `pnpm pds init --local` for local dev
+	// Run `pnpm pds init` to configure, or `pnpm pds init --production` to deploy secrets
 	"name": "atproto-pds",
 	"main": "src/index.ts",
 	"compatibility_date": "2025-12-02",

package.json

@@ -4,9 +4,9 @@
 	"version": "1.0.0",
 	"description": "AT Protocol PDS on Cloudflare Workers",
 	"scripts": {
-		"check": "pnpm run --filter @ascorbic/* check",
-		"test": "pnpm run --filter @ascorbic/* test",
-		"build": "pnpm run --filter @ascorbic/* build",
+		"check": "pnpm run --filter '@ascorbic/*' --filter 'create-pds' check",
+		"test": "pnpm run --filter '@ascorbic/*' --filter 'create-pds' test",
+		"build": "pnpm run --filter '@ascorbic/*' --filter 'create-pds' build",
 		"format": "prettier --write ."
 	},
 	"keywords": [],

packages/create-pds/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "create-pds",
+	"version": "0.0.0",
+	"description": "Create a new AT Protocol PDS on Cloudflare Workers",
+	"type": "module",
+	"bin": {
+		"create-pds": "./dist/index.js"
+	},
+	"files": [
+		"dist",
+		"templates"
+	],
+	"scripts": {
+		"build": "tsdown",
+		"test": "vitest run",
+		"check": "publint"
+	},
+	"devDependencies": {
+		"@clack/prompts": "^0.11.0",
+		"@types/node": "^24.10.4",
+		"citty": "^0.1.6",
+		"publint": "^0.3.16",
+		"tsdown": "^0.18.3",
+		"typescript": "^5.9.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ascorbic/atproto-worker.git",
+		"directory": "packages/create-pds"
+	},
+	"homepage": "https://github.com/ascorbic/atproto-worker",
+	"keywords": [
+		"atproto",
+		"bluesky",
+		"pds",
+		"cloudflare-workers"
+	],
+	"author": "Matt Kane",
+	"license": "MIT"
+}