aesthetic.computer
Monorepo for Aesthetic.Computer
aesthetic.computer
1# `/at` Directory Manifest
2
3**Purpose:** ATProto (Authenticated Transfer Protocol) experimentation and Bluesky integration toolkit for Aesthetic Computer.
4
5**Created:** October 6, 2025
6**Status:** 🧪 Experimental - exploring before infrastructure commitment
7
8---
9
10## Directory Structure
11
12```
13/workspaces/aesthetic-computer/at/
14├── README.md # Full documentation and learning resources
15├── QUICKSTART.md # Quick start guide with current state
16├── MANIFEST.md # This file - complete directory documentation
17├── package.json # Node.js project with ATProto dependencies
18├── package-lock.json # Locked dependency versions
19├── .env.example # Environment variable template
20├── .env # Local config (gitignored, create from example)
21├── .gitignore # Git ignore patterns
22├── node_modules/ # Installed dependencies (gitignored)
23├── query-profile.mjs # Query ATProto profiles
24├── query-posts.mjs # Fetch posts from feeds
25├── post-to-bluesky.mjs # Post to @aesthetic.computer account
26├── explore-lexicons.mjs # Browse lexicon schemas
27├── resolve-did.mjs # Resolve DIDs and inspect PDS
28└── test-all.mjs # Test suite for all tools
29```
30
31---
32
33## Dependencies
34
35### NPM Packages (from `package.json`)
36
37| Package | Version | Purpose |
38|---------|---------|---------|
39| `@atproto/api` | ^0.17.0 | Main ATProto SDK for Bluesky |
40| `@atproto/xrpc` | ^0.6.5 | Low-level XRPC client |
41| `@atproto/lexicon` | ^0.4.2 | Lexicon schema tools |
42| `@atproto/identity` | ^0.4.3 | DID resolution and handle verification |
43| `@atproto/syntax` | ^0.3.1 | ATProto syntax utilities |
44| `dotenv` | ^16.4.5 | Environment variable management |
45
46**Total size:** ~23 packages when installed
47
48---
49
50## Tool Documentation
51
52### 1. `query-profile.mjs`
53
54**Purpose:** Query profile information for any ATProto handle or DID.
55
56**Usage:**
57```bash
58node query-profile.mjs aesthetic.computer
59node query-profile.mjs did:plc:k3k3wknzkcnekbnyde4dbatz
60node query-profile.mjs bsky.app
61```
62
63**Output:**
64- Handle and DID
65- Display name and description
66- Follower/following counts
67- Post count
68- Recent posts (last 5)
69- Avatar and banner URLs
70
71**API Used:** `https://public.api.bsky.app/xrpc/app.bsky.actor.getProfile`
72
73**Authentication:** None required (public endpoint)
74
75---
76
77### 2. `query-posts.mjs`
78
79**Purpose:** Fetch and display detailed post information from any account.
80
81**Usage:**
82```bash
83node query-posts.mjs aesthetic.computer
84node query-posts.mjs aesthetic.computer --limit=20
85```
86
87**Output:**
88- Post text and timestamps
89- Engagement metrics (likes, replies, reposts)
90- Embeds (images, links, quoted posts)
91- Rich text features (mentions, links, hashtags)
92- Reply context
93
94**API Used:** `https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed`
95
96**Authentication:** None required (public endpoint)
97
98---
99
100### 3. `post-to-bluesky.mjs`
101
102**Purpose:** Post to the official @aesthetic.computer Bluesky account.
103
104**Usage:**
105```bash
106# Simple text post
107node post-to-bluesky.mjs "Hello from Aesthetic Computer! 🎨"
108
109# Post with image
110node post-to-bluesky.mjs "New painting!" --image=painting.png
111
112# Post with image and alt text
113node post-to-bluesky.mjs "Check this out" --image=art.png --alt="Abstract painting"
114```
115
116**Requirements:**
117- `.env` file with credentials:
118 ```env
119 BSKY_IDENTIFIER=aesthetic.computer
120 BSKY_APP_PASSWORD=your-app-password
121 ```
122- App password from: https://bsky.app/settings/app-passwords
123
124**Output:**
125- Post URI (AT-URI)
126- Post CID (content identifier)
127- Web URL to view on Bluesky
128
129**API Used:** `https://bsky.social` (login + create post)
130
131**Authentication:** Required (OAuth with app password)
132
133---
134
135### 4. `explore-lexicons.mjs`
136
137**Purpose:** Browse and understand ATProto lexicon schemas.
138
139**Usage:**
140```bash
141node explore-lexicons.mjs
142```
143
144**Output:**
145- Standard Bluesky lexicons (`app.bsky.*`)
146 - `app.bsky.feed.post` - Posts/status updates
147 - `app.bsky.feed.like` - Likes on posts
148 - `app.bsky.graph.follow` - Follow relationships
149 - `app.bsky.embed.images` - Image embeds
150 - `app.bsky.embed.external` - Link embeds
151
152- Proposed AC custom lexicons (`computer.aesthetic.*`)
153 - `computer.aesthetic.painting` - Paintings with rich metadata
154 - `computer.aesthetic.piece` - Interactive pieces/programs
155 - `computer.aesthetic.kidlisp` - KidLisp code snippets
156 - `computer.aesthetic.mood` - Mood/emotion entries
157
158**Purpose:** Educational tool to understand federation and lexicon design
159
160---
161
162### 5. `resolve-did.mjs`
163
164**Purpose:** Resolve DIDs to inspect PDS configurations and DID documents.
165
166**Usage:**
167```bash
168node resolve-did.mjs aesthetic.computer
169node resolve-did.mjs did:plc:k3k3wknzkcnekbnyde4dbatz
170node resolve-did.mjs bsky.app
171```
172
173**Output:**
174- DID identifier
175- Verified handles (alsoKnownAs)
176- PDS endpoint (where data is hosted)
177- Verification methods (public keys)
178- Full DID document (JSON)
179
180**API Used:** `https://plc.directory/{did}` for `did:plc:*` DIDs
181
182**Authentication:** None required (public PLC directory)
183
184---
185
186### 6. `test-all.mjs`
187
188**Purpose:** Quick test suite to verify all tools are working.
189
190**Usage:**
191```bash
192node test-all.mjs
193```
194
195**Tests:**
1961. ✅ Profile query
1972. ✅ Feed query
1983. ⏭️ Authentication (if credentials provided)
199
200**Output:** Pass/fail status for each test with helpful error messages.
201
202---
203
204## Current State
205
206### @aesthetic.computer on Bluesky
207
208```json
209{
210 "handle": "aesthetic.computer",
211 "did": "did:plc:k3k3wknzkcnekbnyde4dbatz",
212 "pds": "https://chanterelle.us-west.host.bsky.network",
213 "followers": 0,
214 "following": 2,
215 "posts": 1,
216 "created": "2024-10-20T01:54:27Z",
217 "lastPost": "ty the invite 🦋"
218}
219```
220
221**PDS Provider:** Bluesky (third-party infrastructure)
222
223**Handle Verification:** ✅ Custom domain `aesthetic.computer` verified via DNS
224
225---
226
227## Environment Setup
228
229### Required Environment Variables
230
231Create `.env` file (from `.env.example`):
232
233```env
234# Bluesky Service (default: official PDS)
235BSKY_SERVICE=https://bsky.social
236
237# For posting to @aesthetic.computer (optional)
238BSKY_IDENTIFIER=aesthetic.computer
239BSKY_APP_PASSWORD=your-app-password-here
240
241# For firehose monitoring (future)
242BSKY_RELAY=wss://bsky.network
243```
244
245### Getting App Password
246
2471. Log in to https://bsky.app
2482. Go to Settings → App Passwords
2493. Create new app password
2504. Name it "Aesthetic Computer Dev" or similar
2515. Copy password to `.env`
252
253**Security:** App passwords are scoped - they cannot change account settings or delete the account.
254
255---
256
257## Integration Paths
258
259### Path 1: Simple Integration (Recommended First Step)
260
261**Goal:** Share paintings to @aesthetic.computer Bluesky account
262
263**Implementation:**
264```javascript
265// In AC's painting share handler
266import { BskyAgent } from '@atproto/api'
267
268async function sharePaintingToBluesky(painting, user) {
269 const agent = new BskyAgent({ service: 'https://bsky.social' })
270 await agent.login({
271 identifier: process.env.BSKY_IDENTIFIER,
272 password: process.env.BSKY_APP_PASSWORD
273 })
274
275 // Upload painting image
276 const imageData = await fetch(painting.url).then(r => r.arrayBuffer())
277 const { data } = await agent.uploadBlob(
278 new Uint8Array(imageData),
279 { encoding: 'image/png' }
280 )
281
282 // Post to Bluesky
283 await agent.post({
284 text: `New painting by @${user.handle}: "${painting.title}"\n\n🎨 aesthetic.computer/${painting.slug}`,
285 embed: {
286 $type: 'app.bsky.embed.images',
287 images: [{
288 image: data.blob,
289 alt: painting.description || painting.title
290 }]
291 }
292 })
293}
294```
295
296**Benefits:**
297- ✅ Zero infrastructure
298- ✅ Instant Bluesky presence
299- ✅ Marketing and showcase
300- ✅ Test federation
301- ✅ Learn ATProto
302
303**Drawbacks:**
304- ❌ No per-user identities
305- ❌ All posts from one account
306- ❌ No true data portability
307
308---
309
310### Path 2: Full PDS Deployment (Future)
311
312**Goal:** Run AC's own PDS with per-user identities
313
314**Details:** See [ATProto PDS Roadmap](../plans/atproto-pds-roadmap.md)
315
316**Features:**
317- ✅ Per-user identities (`jeffrey.aesthetic.computer`)
318- ✅ Custom lexicons (`computer.aesthetic.*`)
319- ✅ True data portability
320- ✅ Full federation
321- ✅ Replace Auth0
322
323**Requirements:**
324- GCP Compute Engine e2-small (~$15-20/month)
325- PostgreSQL database
326- DNS configuration
327- PDS deployment and maintenance
328
329---
330
331## Development Workflow
332
333### Testing Changes
334
335```bash
336# 1. Make changes to tools
337vim query-profile.mjs
338
339# 2. Run tests
340node test-all.mjs
341
342# 3. Test specific tool
343node query-profile.mjs aesthetic.computer
344
345# 4. Check for lint errors
346npm run test
347```
348
349### Adding New Tools
350
3511. Create new `.mjs` file in `/at`
3522. Add to `package.json` scripts section
3533. Document in this MANIFEST
3544. Update README.md
3555. Test with `test-all.mjs`
356
357### Updating Dependencies
358
359```bash
360# Check for updates
361npm outdated
362
363# Update all to latest
364npm update
365
366# Update specific package
367npm install @atproto/api@latest
368```
369
370---
371
372## Related Documentation
373
374- **Main README:** [`/at/README.md`](README.md) - Full documentation
375- **Quick Start:** [`/at/QUICKSTART.md`](QUICKSTART.md) - Get started quickly
376- **PDS Roadmap:** [`/plans/atproto-pds-roadmap.md`](../plans/atproto-pds-roadmap.md) - Full PDS strategy
377- **Data Architecture:** [`/plans/atproto-data-architecture.md`](../plans/atproto-data-architecture.md) - Data flow and storage
378
379---
380
381## External Resources
382
383- **ATProto Docs:** https://atproto.com
384- **Bluesky API:** https://docs.bsky.app
385- **ATProto GitHub:** https://github.com/bluesky-social/atproto
386- **SDK Reference:** https://github.com/bluesky-social/atproto/tree/main/packages/api
387- **Lexicon Specs:** https://atproto.com/specs/lexicon
388- **PLC Directory:** https://plc.directory
389- **Bluesky Settings:** https://bsky.app/settings
390
391---
392
393## Docker Integration
394
395### Dockerfile Changes
396
397ATProto dependencies are now included in `.devcontainer/Dockerfile`:
398
399```dockerfile
400# --- ATProto dependencies for /at directory ------------------------------------
401# Note: These will be available globally for ATProto experiments
402# See /at directory for ATProto/Bluesky exploration tools
403RUN export PATH="/home/me/.fnm:${PATH}" && \
404 eval "$(/home/me/.fnm/fnm env --use-on-cd)" && \
405 npm i -g @atproto/api@^0.17.0 @atproto/xrpc@^0.6.5 @atproto/lexicon@^0.4.2 @atproto/identity@^0.4.3 @atproto/syntax@^0.3.1 dotenv@^16.4.5
406```
407
408This ensures all dependencies are available after container rebuilds.
409
410---
411
412## Future Enhancements
413
414### Planned Tools
415
416- [ ] `firehose-monitor.mjs` - Monitor ATProto firehose in real-time
417- [ ] `create-lexicon.mjs` - Generate custom lexicon schemas
418- [ ] `export-data.mjs` - Export all data from a DID as CAR files
419- [ ] `migrate-to-pds.mjs` - Migration tool for when AC runs own PDS
420- [ ] `analyze-network.mjs` - Network analysis and metrics
421
422### Planned Features
423
424- [ ] Batch posting support
425- [ ] Image optimization before upload
426- [ ] Post scheduling
427- [ ] Analytics and engagement tracking
428- [ ] Custom lexicon validator
429- [ ] PDS health monitoring
430
431---
432
433## Changelog
434
435### 2025-10-06 - Initial Creation
436
437- ✅ Created `/at` directory structure
438- ✅ Set up Node.js project with ATProto dependencies
439- ✅ Implemented 6 core tools (query, post, explore, resolve, test)
440- ✅ Documented intermediate integration path
441- ✅ Added to main README and Dockerfile
442- ✅ Tested against @aesthetic.computer Bluesky account
443- ✅ Created comprehensive documentation
444
445**Status:** Ready for experimentation and integration testing
446
447---
448
449**Maintainer:** Jeffrey Scudder (@jeffrey)
450**Last Updated:** October 6, 2025
451**Version:** 0.0.1 (Experimental)