aesthetic.computer
Monorepo for Aesthetic.Computer
aesthetic.computer
1# Repository Guidelines
2
3## Project Structure & Module Organization
4- `system/` holds the main web app (Netlify config, public assets, templates, scripts) and is the primary entry for feature work.
5- `ac-electron/` is the macOS/Windows desktop Electron app (AC Pane). Edit files here when working on the desktop app.
6- `session-server/` contains the real-time session backend (Jamsocket).
7- `shared/` offers reusable browser/server utilities; use these before adding new helpers.
8- `utilities/` scripts generate or sync assets (e.g., `generate-new-piece.mjs`).
9- `tests/` covers integration/performance; `spec/` is for KidLisp language specs; project-wide docs live at the repo root. Place new feature code next to its runtime (client in `system/`, server in `session-server/`).
10- `reference/strudel/` contains a local clone of the Strudel live coding project (from Codeberg). Key packages for audio/scheduling: `packages/core/cyclist.mjs` (event scheduler), `packages/core/pattern.mjs` (`.onTrigger()` callback for hooking into pattern events), `packages/webaudio/` (Web Audio integration), `packages/draw/` (visualization sync). Use this reference when working on Strudel integration in `kidlisp.com`.
11
12## Build, Test, and Development Commands
13Run from the repo root unless noted:
14- `npm run aesthetic` — starts site, session server, edge services, Stripe mocks, and URL helper; use for full-stack local work.
15- `npm run site` — launches the client stack only (`system/`).
16- `npm test` — runs the top-level smoke/integration tests.
17- `npm run test:perf` or `npm run test:perf:chrome` — performance harnesses in `tests/performance/`.
18- `npm run test:kidlisp` — watches and runs KidLisp specs in `spec/`.
19- `npm run url` — prints your local tunnel URL for hitting the app in browsers/devices.
20
21## Fish Shell Commands (DevContainer)
22The devcontainer provides these `ac-*` commands (defined in `.devcontainer/config.fish`):
23
24### Machine & SSH Helpers
25- `ac-host` — List all machines from `vault/machines.json` with SSH connection info.
26- `ac-host <key> ssh` — SSH to a specific machine (e.g., `ac-host jeffrey-macbook ssh`).
27- `ac-host <key> ip` — Get just the IP address of a machine.
28- `ac-host <key> info` — Show full JSON config for a machine.
29- `ac-machines` — Alias for `ac-host` (list all machines).
30
31### FF1 Art Computer
32- `ac-ff1` — Show FF1 info and available commands.
33- `ac-ff1 scan` — Find FF1 via MacBook mDNS (discovers IP changes).
34- `ac-ff1 ping` — Check if FF1 is responding.
35- `ac-ff1 cast <url>` — Send a URL to display on FF1 (e.g., `ac-ff1 cast https://aesthetic.computer/purple`).
36- `ac-ff1 tunnel` — Create SSH tunnel for local FF1 development (localhost:1111 → FF1).
37
38### Electron App (Mac Host)
39- `ac-electron-restart` — Restart the Electron app on the host Mac.
40- `ac-electron-stop` — Stop the Electron app.
41- `ac-electron-start` — Start the Electron app.
42- `ac-electron-dev` — Toggle dev mode (on/off/status). When enabled, the production app loads files from the repo.
43- `ac-electron-reload` — Reload Electron windows (triggers Cmd+R).
44
45**Electron App Source**: `ac-electron/` contains the desktop app:
46- `main.js` — Main process (window management, IPC handlers, tray menu)
47- `preload.js` — Preload for BrowserWindows (exposes `window.ac` API)
48- `webview-preload.js` — Preload for webviews (exposes `window.acElectron` for window control)
49- `renderer/flip-view.html` — Main AC Pane UI (3D flip card with webview + terminal)
50- `renderer/preferences.html` — Preferences window
51
52**Dev Mode**: Create `~/.ac-electron-dev` on the Mac host to make the production app load renderer files from `~/aesthetic-computer/ac-electron/` instead of the app bundle. This enables live iteration without rebuilding:
531. `ac-electron-dev on` — Enable dev mode
542. Edit files in `ac-electron/`
553. `ac-electron-reload` or Cmd+R in app — See changes
564. `ac-electron-dev off` — Disable when done
57
58### Development
59- `ac-tv` — Query TV API endpoints.
60- `ac-pack` — Package a piece for NFT minting.
61- `ac-keep` — Mint a KidLisp piece as an NFT.
62- `ac-repl` — Start KidLisp REPL.
63- `ac-emacs-restart` — Restart Emacs daemon.
64
65## Emacs Terminal Buffers
66The development environment uses Emacs with multiple named terminal buffers (eat terminals). When the user refers to these by name or nickname, use the Emacs MCP tools (`mcp_emacs_*`) instead of `run_in_terminal`:
67
68- `🐟-fishy` or "fishy" — Main fish shell terminal for general commands
69- `🩸-artery` or "artery" — Artery service logs
70- `💳-stripe-print` — Stripe print logs
71- `🤖-chat-system` — Chat system logs
72- `📋-session` — Session server logs
73- `🌐-site` — Site/web server logs
74- `🔴-redis` — Redis logs
75- `🖼️-views` — Views logs
76- `🤖-llm` — LLM service logs
77- `💥-crash-diary` — Crash logs
78- `📊-top` — System monitoring (top)
79- `🧪-kidlisp` — KidLisp test runner
80- `📦-media` — Media service logs
81- `🔥-oven` — Oven service logs
82- `🔖-bookmarks` — Bookmarks
83- `⏰-chat-clock` — Chat clock logs
84- `🧠-chat-sotce` — Sotce chat logs
85- `🎫-stripe-ticket` — Stripe ticket logs
86- `⚡-url` — URL service logs
87- `🚇-tunnel` — Tunnel logs
88
89**Usage**: When asked to run commands in "fishy" or any named terminal, use:
901. `mcp_emacs_emacs_switch_buffer` to switch to the buffer
912. `mcp_emacs_emacs_send_keys` to send the command
923. Send a newline character to execute
93
94Emacs tabs can be switched with `(tab-bar-select-tab N)` via `mcp_emacs_execute_emacs_lisp`.
95
96## Coding Style & Naming Conventions
97- JavaScript/TypeScript modules use ESM (`.mjs`); prefer 2-space indentation and trailing commas.
98- Run Prettier where available (`npx prettier --write <files>`); respect existing file conventions (some legacy scripts mix shell/Fish).
99- Name new pieces and assets with lowercase-hyphenated paths; colocate tests as `<name>.test.mjs` near related code or under `tests/`.
100- Keep configuration in `.env`-style files out of version control; use sample files if needed.
101
102## Testing Guidelines
103- Add focused `.test.mjs` files; use Jasmine for KidLisp specs and Node test runners for integration.
104- Prefer running `npm test` before PRs; include performance runs when touching rendering/audio paths.
105- For perf tests, document baseline numbers and hardware in the PR description.
106- Snapshot or fixture data should live in `tests/` subfolders; avoid large binaries in git.
107
108## Commit & Pull Request Guidelines
109- Follow the existing history: short, action-led subjects (`fix: ...`, `docs: ...`, or descriptive phrases).
110- PRs should describe the change, runtime targets (web/session), and how to reproduce/test.
111- Link related issues or user-facing commands; add screenshots or clips for UI/visual changes.
112- Keep commits logically scoped; prefer small, reviewable units over large drops.
113- Ensure `npm test` (and relevant perf or KidLisp suites) are green before requesting review.
114
115## Security & Configuration Tips
116- Never commit secrets; use environment variables and the Netlify/Jamsocket env management scripts in `system/`.
117- When syncing assets, use `npm run assets:sync:down`/`up` and verify paths under `system/public/assets`.
118- Treat production endpoints in scripts as sensitive; dry-run changes against local or dev tunnels first.