Scripts Setup & Requirements#

🔧 How These Scripts Work#

All scripts in scripts/ are designed to run from the workspace root (/workspaces/aesthetic-computer/).

Import Resolution#

• ✅ Backend modules: import { connect } from "../../system/backend/database.mjs"

  • Scripts access backend utilities via relative paths
  • Path goes up 2 levels from scripts/atproto/ to root, then into system/backend/

• ✅ Node modules: import { AtpAgent } from "@atproto/api"

  • Installed in root node_modules/ (shared with system/node_modules)
  • Node.js walks up from script location to find packages
  • Run npm install at root to ensure deps are available

Environment Variables#

Scripts load .env from system/.env using:

import { config } from 'dotenv';
config({ path: './system/.env' });

Note: Path is relative to where you run the script (workspace root).

Required in system/.env:

# MongoDB
MONGODB_CONNECTION_STRING=mongodb+srv://...
MONGODB_NAME=aesthetic

# ATProto PDS
PDS_URL=https://at.aesthetic.computer

# DigitalOcean Spaces (for recovery scripts)
ART_SPACES_KEY=your_key
ART_SPACES_SECRET=your_secret
ART_SPACES_BUCKET=art-aesthetic-computer
ART_SPACES_REGION=nyc3
ART_SPACES_ENDPOINT=https://nyc3.digitaloceanspaces.com

AT_BLOBS_SPACES_KEY=your_key
AT_BLOBS_SPACES_SECRET=your_secret
AT_BLOBS_SPACES_BUCKET=at-blobs-aesthetic-computer
AT_BLOBS_SPACES_REGION=nyc3
AT_BLOBS_SPACES_ENDPOINT=https://nyc3.digitaloceanspaces.com

# Anonymous art account password
ANON_PASSWORD=your_hash

User ATProto Credentials (stored in MongoDB users collection):

{
  "atproto": {
    "did": "did:plc:...",
    "handle": "user.at.aesthetic.computer",
    "password": "encrypted_app_password"
  }
}

Using aesthetic-computer-vault for Secrets#

The aesthetic-computer-vault/ directory contains actual secrets:

# Instead of editing system/.env manually, use:
cd aesthetic-computer-vault
source devault.fish  # Loads secrets from vault/.env

# Or copy vault env to system:
cp aesthetic-computer-vault/.env system/.env

Vault contains:

• ANON_PASSWORD - Anonymous art account password hash
• OVEN_CALLBACK_SECRET - Oven webhook authentication
• SSH credentials for friend's server

📦 Dependencies#

Scripts share dependencies with the main workspace - packages are installed at root level and duplicated in system/ for Netlify functions.

Installing Dependencies#

# Install at root (needed for scripts)
cd /workspaces/aesthetic-computer
npm install

# Key packages (already in package.json):
# - @atproto/api ^0.17.2 (ATProto client)
# - @aws-sdk/client-s3 ^3.896.0 (DigitalOcean Spaces)
# - mongodb ^6.20.0 (MongoDB driver)
# - dotenv ^16.4.7 (Environment variable loading)
# - node-fetch ^3.3.2 (HTTP requests)

These same packages are also in system/package.json for Netlify functions, which is fine - small duplication for clean architecture.

🚀 Running Scripts#

Always run from workspace root so paths resolve correctly:

# ✅ Correct (from /workspaces/aesthetic-computer/)
node scripts/atproto/sync-atproto.mjs live --kidlisp-only
node scripts/recovery/check-tape-zips-in-spaces.mjs @jeffrey

# ❌ Wrong (wrong working directory)
cd scripts/atproto
node sync-atproto.mjs  # Can't find system/.env or system/backend/

🔍 Troubleshooting#

"Cannot find module '../system/backend/database.mjs'"#

• Cause: Running script from wrong directory
• Fix: cd /workspaces/aesthetic-computer && node scripts/...

"MONGODB_CONNECTION_STRING is not set"#

• Cause: Missing or incorrect .env file
• Fix:
  1. Check system/.env exists
  2. Verify it contains MONGODB_CONNECTION_STRING
  3. Or copy from vault: cp aesthetic-computer-vault/.env system/.env

"Cannot use a session that has ended"#

• Cause: ATProto credentials invalid or expired
• Fix:
  1. Check user record in MongoDB has valid atproto.password
  2. Regenerate app password at https://at.aesthetic.computer
  3. Update MongoDB user record

"AccessDenied" from DigitalOcean Spaces#

• Cause: Missing or invalid DO Spaces credentials
• Fix: Add ART_SPACES_* and AT_BLOBS_SPACES_* to system/.env

🔐 Security Notes#

• ❌ Never commit system/.env (already in .gitignore)
• ✅ Always use aesthetic-computer-vault/.env for secrets
• 🔒 Vault is private - only accessible to authorized developers
• 🚨 Rotate credentials if exposed in logs or commits