Skip to content

HACKING.md

Latest commit

 

History

History
151 lines (108 loc) · 4.81 KB

HACKING.md

File metadata and controls

151 lines (108 loc) · 4.81 KB
Raw

Hacking Guide

This guide is for people who want to change Deejay without first reverse-engineering the whole hackathon build.

Project Shape

server/
  index.js        HTTP API, Spotify, OpenAI resolver, queueing, local request log
  spacebase.js    Spacebase1 resolver identity, DPoP, ITP framing, scan/post

public/
  index.html      attendee surface
  attendee.js     human intent -> promise -> accept/revise -> complete flow
  host.html       host surface
  host.js         ready check, QR, pause, test queue, recent requests
  styles.css      shared UI styles
  spacebase-client.js        browser-side Spacebase1 client
  deejay-agent-client.mjs    standalone clean-room agent helper
  agent-instructions.md      static agent guide

scripts/
  doctor.js
  deejay-watchdog.sh

data/
  .gitkeep        runtime files are created here and ignored by Git

Core Flow

Human-led request:

  1. Browser signs up to Spacebase1 commons with a local DPoP key.
  2. Browser posts a top-level commons INTENT addressed to Deejay.
  3. Server watcher sees the intent, resolves the song, searches Spotify, and posts a PROMISE.
  4. Browser shows the promised track.
  5. User approves or rejects/revises.
  6. On approval, server queues the Spotify track and posts COMPLETE.

Agent-led request:

  1. Agent reads /agent-setup.
  2. Agent signs up to Spacebase1 commons.
  3. Agent posts one song INTENT.
  4. Agent scans the request subspace.
  5. Agent accepts a plausible Deejay PROMISE.
  6. Agent waits for COMPLETE.

Fast-path agent command:

curl -sS http://127.0.0.1:5177/deejay-agent-client.mjs -o /tmp/deejay-agent-client.mjs
node /tmp/deejay-agent-client.mjs "that sabrina espresso song"

Important Boundaries

  • Spotify queueing is the primary actuator. Do not add mouse/keyboard Spotify automation unless the API path is deliberately being replaced.
  • The human UI should remain step-by-step. The point is to demonstrate the verbs, not hide them.
  • The agent doorway should stay concise and runnable by agents without local repo access.
  • Do not add attendee accounts, moderation, voting, or heavy duplicate logic in v1.
  • Do not queue before an ACCEPT.
  • Keep runtime state local under data/.

Server Notes

server/index.js is intentionally broad but the responsibilities are grouped:

  • Express routes and static surfaces.
  • Request creation and local log persistence.
  • AI interpretation and Spotify search/selection.
  • Spotify auth, status, queueing, and playlist logging.
  • Spacebase watcher and recovery.
  • Rendered agent docs.

If this grows, the first useful split is:

  • server/spotify.js
  • server/resolver.js
  • server/requests.js
  • server/agent-docs.js

Avoid splitting just to make the file count look nicer. Split when a change is hard to reason about.

Spacebase Notes

Spacebase1 uses framed ITP messages, not ordinary JSON REST calls. The mechanics live in two places:

  • server/spacebase.js for the resolver-agent.
  • public/spacebase-client.js for attendee browsers.

DPoP proofs are single-use. Generate a fresh proof for each signup, continue, scan, and post request. Reusing a proof can trigger replay errors.

Song request subspaces use the song intentId as the space id.

Spotify Notes

Required scopes:

  • user-read-playback-state
  • user-modify-playback-state
  • playlist-modify-private
  • playlist-modify-public

The queue call is followed by a short queue verification loop. If the track does not appear quickly, Deejay retries a small number of times. Spotify's queue UI can lag or hide upcoming tracks, so the app treats API verification as the source of truth.

OpenAI Notes

If OPENAI_API_KEY is missing, Deejay falls back to a simpler resolver. That keeps local Spotify testing possible without AI, but the hackathon demo is better with the AI resolver enabled.

The resolver should prefer popular canonical tracks when requests are vague. Keep failures graceful: fail only when Spotify returns no plausible results or the selected result is clearly unrelated.

Checks

Run:

npm run doctor
npm run check

Manual smoke test:

  1. Start npm run dev.
  2. Open /host.
  3. Connect Spotify.
  4. Make this computer the active Spotify device.
  5. Open /.
  6. Submit that sabrina espresso song.
  7. Approve the promise.
  8. Confirm the UI reaches COMPLETE.

Agent smoke test:

curl -sS http://127.0.0.1:5177/deejay-agent-client.mjs -o /tmp/deejay-agent-client.mjs
node /tmp/deejay-agent-client.mjs "King Kunta by Kendrick Lamar"

Publish Checklist

Before pushing to GitHub:

  • .env is ignored and not committed.
  • data/ only contributes data/.gitkeep.
  • node_modules/ is ignored.
  • npm run check passes.
  • npm run doctor does not show unexpected failures.
  • README examples use placeholders, not event-specific domains or personal paths.
  • Temporary Cloudflare/ngrok config is not committed.