create-pds 0.0.6 → 0.0.7

package/README.md

@@ -1,6 +1,6 @@
 # create-pds
 
-Scaffold a new [AT Protocol](https://atproto.com) Personal Data Server (PDS) on Cloudflare Workers.
+Scaffold a new [AT Protocol](https://atproto.com) Personal Data Server (PDS) on Cloudflare Workers. Creates a Cirrus PDS project.
 
 ## Usage
 
@@ -24,7 +24,7 @@ This will:
 create-pds [name]
 
 Arguments:
-  name                Project name (default: pds-worker)
+  name                Project name (default: my-pds)
 
 Options:
   --package-manager   Package manager to use (npm, yarn, pnpm, bun)
@@ -45,4 +45,4 @@ npm run dev
 
 Your PDS will be running at http://localhost:5173
 
-See the [@ascorbic/pds documentation](https://github.com/ascorbic/atproto-worker/tree/main/packages/pds) for configuration and deployment instructions.
+See the [@getcirrus/pds documentation](https://github.com/ascorbic/cirrus/tree/main/packages/pds) for configuration and deployment instructions.

package/dist/index.js

@@ -2564,7 +2564,7 @@ async function replaceInFile(filePath, replacements) {
 }
 async function getLatestPdsVersion() {
 	try {
-		const response = await fetch("https://registry.npmjs.org/@ascorbic/pds/latest");
+		const response = await fetch("https://registry.npmjs.org/@getcirrus/pds/latest");
 		if (!response.ok) throw new Error(`Failed to fetch: ${response.status}`);
 		const data = await response.json();
 		if (data.version) return data.version;
@@ -2689,9 +2689,9 @@ runMain(defineCommand({
 			initGit = gitResult;
 		}
 		const spinner = Y();
-		spinner.start("Fetching latest @ascorbic/pds version...");
+		spinner.start("Fetching latest @getcirrus/pds version...");
 		const pdsVersion = await getLatestPdsVersion();
-		spinner.stop(`Using @ascorbic/pds ${pdsVersion}`);
+		spinner.stop(`Using @getcirrus/pds ${pdsVersion}`);
 		spinner.start("Copying template...");
 		await copyTemplateDir(join(__dirname, "..", "templates", "pds-worker"), targetDir);
 		await replaceInFile(join(targetDir, "package.json"), {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-pds",
-  "version": "0.0.6",
-  "description": "Create a new AT Protocol PDS on Cloudflare Workers",
+  "version": "0.0.7",
+  "description": "Create a new Cirrus AT Protocol PDS on Cloudflare Workers",
   "type": "module",
   "bin": {
     "create-pds": "./dist/index.js"
@@ -20,10 +20,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ascorbic/atproto-worker.git",
+    "url": "git+https://github.com/ascorbic/cirrus.git",
     "directory": "packages/create-pds"
   },
-  "homepage": "https://github.com/ascorbic/atproto-worker",
+  "homepage": "https://github.com/ascorbic/cirrus",
   "keywords": [
     "atproto",
     "bluesky",

package/templates/pds-worker/README.md

@@ -1,4 +1,4 @@
-# Personal PDS on Cloudflare Workers
+# Your Personal PDS
 
 A single-user AT Protocol Personal Data Server running on Cloudflare Workers.
 
@@ -6,26 +6,29 @@ A single-user AT Protocol Personal Data Server running on Cloudflare Workers.
 >
 > 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
+## Getting Started
 
 ### 1. Install dependencies
 
 ```bash
 pnpm install
+# or: npm install / yarn install
 ```
 
-### 2. Configure environment
+### 2. Configure the PDS
 
-If you haven't already, run the setup wizard:
+Run the setup wizard if not already done:
 
 ```bash
 pnpm pds init
-# or
-npm run pds init
-yarn pds init
 ```
 
-This prompts for your hostname, handle, and password, then writes configuration to `.dev.vars`.
+This prompts for:
+- **PDS hostname** – The deployment domain (e.g., `pds.example.com`)
+- **Handle** – The Bluesky username (e.g., `alice.example.com`)
+- **Password** – For logging in from Bluesky apps
+
+The wizard generates cryptographic keys and writes configuration to `.dev.vars` and `wrangler.jsonc`.
 
 ### 3. Run locally
 
@@ -33,60 +36,153 @@ This prompts for your hostname, handle, and password, then writes configuration
 pnpm dev
 ```
 
-This starts a local development server at http://localhost:5173.
+The PDS is now running at http://localhost:5173. Test it with:
+
+```bash
+curl http://localhost:5173/health
+curl http://localhost:5173/.well-known/did.json
+```
 
 ### 4. Deploy to production
 
-First configure for production:
+First, push secrets to Cloudflare:
 
 ```bash
 pnpm pds init --production
+```
+
+Then deploy:
 
-# or
-npm run pds init --production
-yarn pds init --production
+```bash
+pnpm run deploy
 ```
 
-This sets vars in `wrangler.jsonc` and secrets via `wrangler secret put`.
+Finally, configure DNS to point your domain to the worker.
 
-Then deploy:
+## Migrating an Existing Account
+
+To move an existing Bluesky account from bsky.social or another PDS:
+
+### 1. Configure for migration
+
+```bash
+pnpm pds init
+# Answer "Yes" when asked about migrating an existing account
+```
+
+### 2. Deploy and transfer the data
 
 ```bash
 pnpm run deploy
+pnpm pds migrate
+```
+
+This downloads the repository (posts, follows, likes) and all images/videos from the current PDS.
+
+### 3. Update the identity
+
+Follow the [AT Protocol account migration guide](https://atproto.com/guides/account-migration) to update the DID document. This requires email verification from the current PDS.
+
+### 4. Go live
+
+```bash
+pnpm pds activate
 ```
 
+The account is now live on the new PDS.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `pnpm pds init` | Interactive setup wizard |
+| `pnpm pds init --production` | Deploy secrets to Cloudflare |
+| `pnpm pds migrate` | Transfer account from source PDS |
+| `pnpm pds migrate --clean` | Reset and re-import data |
+| `pnpm pds activate` | Enable writes (go live) |
+| `pnpm pds deactivate` | Disable writes (for re-import) |
+| `pnpm pds secret key` | Generate new signing keypair |
+| `pnpm pds secret jwt` | Generate new JWT secret |
+| `pnpm pds secret password` | Set account password |
+
+Add `--dev` to target your local development server instead of production.
+
 ## Configuration
 
-Configuration uses environment variables: vars in `wrangler.jsonc` and secrets.
+### Public Variables (wrangler.jsonc)
+
+| Variable | Description |
+|----------|-------------|
+| `PDS_HOSTNAME` | Public hostname (e.g., pds.example.com) |
+| `DID` | Account DID |
+| `HANDLE` | Account handle |
+| `SIGNING_KEY_PUBLIC` | Public key for DID document |
+
+### Secrets (.dev.vars or Cloudflare)
+
+| Variable | Description |
+|----------|-------------|
+| `AUTH_TOKEN` | Bearer token for API write operations |
+| `SIGNING_KEY` | Private signing key |
+| `JWT_SECRET` | Secret for session tokens |
+| `PASSWORD_HASH` | Bcrypt hash of the account password |
+
+## Handle Verification
+
+Bluesky verifies control of the handle domain.
+
+**If the handle matches the PDS hostname** (for example, both are `pds.example.com`):
+- No extra setup needed. The PDS handles verification automatically.
+
+**If the handle is on a different domain** (for example, handle `alice.example.com`, PDS at `pds.example.com`):
+
+Add a DNS TXT record:
+
+```
+_atproto.alice.example.com  TXT  "did=did:web:pds.example.com"
+```
+
+Verify with:
+
+```bash
+dig TXT _atproto.alice.example.com
+```
 
-**Vars (in wrangler.jsonc):**
+## Project Structure
 
-- `PDS_HOSTNAME` - Public hostname of the PDS
-- `DID` - Account DID (e.g., did:web:pds.example.com)
-- `HANDLE` - Account handle (e.g., alice.example.com)
-- `SIGNING_KEY_PUBLIC` - Public key for DID document (multibase)
+```
+├── src/
+│   └── index.ts          # Worker entry point (re-exports PDS)
+├── wrangler.jsonc        # Cloudflare Worker configuration
+├── .dev.vars             # Local secrets (not committed)
+└── package.json
+```
+
+## Troubleshooting
 
-**Secrets (via wrangler):**
+### "PDS not responding"
 
-- `AUTH_TOKEN` - Bearer token for API write operations
-- `SIGNING_KEY` - Private signing key (secp256k1 JWK)
-- `JWT_SECRET` - Secret for signing session JWTs
-- `PASSWORD_HASH` - Bcrypt hash of account password (for Bluesky app login)
+Ensure the worker is deployed (`pnpm run deploy`) or the dev server is running (`pnpm dev`).
 
-## Endpoints
+### "Failed to resolve handle"
 
-Once deployed, your PDS serves:
+Check the handle configuration:
+- For DNS verification: ensure the TXT record has propagated (`dig TXT _atproto.yourhandle.com`)
+- For same-domain handles: ensure the PDS is accessible at `https://yourdomain.com/.well-known/atproto-did`
 
-- `GET /.well-known/did.json` - DID document
-- `GET /health` - Health check
-- `GET /xrpc/com.atproto.sync.getRepo` - Export repository as CAR
-- `GET /xrpc/com.atproto.sync.subscribeRepos` - WebSocket firehose
-- `POST /xrpc/com.atproto.repo.createRecord` - Create a record (authenticated)
-- `POST /xrpc/com.atproto.repo.uploadBlob` - Upload a blob (authenticated)
-- And more...
+### Migration issues
+
+If migration fails partway through:
+- Run `pnpm pds migrate` again to resume from where you left off
+- Use `pnpm pds migrate --clean` to start fresh (only on deactivated accounts)
 
 ## Resources
 
-- [AT Protocol Docs](https://atproto.com)
+- [AT Protocol Documentation](https://atproto.com)
 - [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
-- [@ascorbic/pds on GitHub](https://github.com/ascorbic/atproto-worker)
+- [@getcirrus/pds Documentation](https://github.com/ascorbic/cirrus/tree/main/packages/pds)
+- [Account Migration Guide](https://atproto.com/guides/account-migration)
+
+## License
+
+MIT

package/templates/pds-worker/package.json.tmpl

@@ -1,11 +1,11 @@
 {
 	"name": "{{name}}",
 	"version": "1.0.0",
-	"description": "AT Protocol PDS on Cloudflare Workers",
+	"description": "Cirrus – AT Protocol PDS on Cloudflare Workers",
 	"type": "module",
 	"private": true,
 	"dependencies": {
-		"@ascorbic/pds": "{{pdsVersion}}"
+		"@getcirrus/pds": "{{pdsVersion}}"
 	},
 	"devDependencies": {
 		"@cloudflare/vite-plugin": "^1.17.0",

package/templates/pds-worker/src/index.ts

@@ -1,2 +1,2 @@
 // Re-export the PDS worker - that's all you need!
-export { default, AccountDurableObject } from "@ascorbic/pds";
+export { default, AccountDurableObject } from "@getcirrus/pds";