Something went wrong. Try again.
Monorepo for Aesthetic.Computer aesthetic.computer
Something went wrong. Try again.
core AGENTS.md.backup
7.4 kB · 118 lines
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119# Repository Guidelines## Project Structure & Module Organization- `system/` holds the main web app (Netlify config, public assets, templates, scripts) and is the primary entry for feature work. - `ac-electron/` is the macOS/Windows desktop Electron app (AC Pane). Edit files here when working on the desktop app.- `session-server/` contains the real-time session backend (Jamsocket). - `shared/` offers reusable browser/server utilities; use these before adding new helpers. - `utilities/` scripts generate or sync assets (e.g., `generate-new-piece.mjs`). - `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/`).- `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`.## Build, Test, and Development CommandsRun from the repo root unless noted:- `npm run aesthetic` — starts site, session server, edge services, Stripe mocks, and URL helper; use for full-stack local work. - `npm run site` — launches the client stack only (`system/`). - `npm test` — runs the top-level smoke/integration tests. - `npm run test:perf` or `npm run test:perf:chrome` — performance harnesses in `tests/performance/`. - `npm run test:kidlisp` — watches and runs KidLisp specs in `spec/`. - `npm run url` — prints your local tunnel URL for hitting the app in browsers/devices.## Fish Shell Commands (DevContainer)The devcontainer provides these `ac-*` commands (defined in `.devcontainer/config.fish`):### Machine & SSH Helpers- `ac-host` — List all machines from `vault/machines.json` with SSH connection info.- `ac-host <key> ssh` — SSH to a specific machine (e.g., `ac-host jeffrey-macbook ssh`).- `ac-host <key> ip` — Get just the IP address of a machine.- `ac-host <key> info` — Show full JSON config for a machine.- `ac-machines` — Alias for `ac-host` (list all machines).### FF1 Art Computer- `ac-ff1` — Show FF1 info and available commands.- `ac-ff1 scan` — Find FF1 via MacBook mDNS (discovers IP changes).- `ac-ff1 ping` — Check if FF1 is responding.- `ac-ff1 cast <url>` — Send a URL to display on FF1 (e.g., `ac-ff1 cast https://aesthetic.computer/purple`).- `ac-ff1 tunnel` — Create SSH tunnel for local FF1 development (localhost:1111 → FF1).### Electron App (Mac Host)- `ac-electron-restart` — Restart the Electron app on the host Mac.- `ac-electron-stop` — Stop the Electron app.- `ac-electron-start` — Start the Electron app.- `ac-electron-dev` — Toggle dev mode (on/off/status). When enabled, the production app loads files from the repo.- `ac-electron-reload` — Reload Electron windows (triggers Cmd+R).**Electron App Source**: `ac-electron/` contains the desktop app:- `main.js` — Main process (window management, IPC handlers, tray menu)- `preload.js` — Preload for BrowserWindows (exposes `window.ac` API)- `webview-preload.js` — Preload for webviews (exposes `window.acElectron` for window control)- `renderer/flip-view.html` — Main AC Pane UI (3D flip card with webview + terminal)- `renderer/preferences.html` — Preferences window**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:1. `ac-electron-dev on` — Enable dev mode2. Edit files in `ac-electron/`3. `ac-electron-reload` or Cmd+R in app — See changes4. `ac-electron-dev off` — Disable when done### Development- `ac-tv` — Query TV API endpoints.- `ac-pack` — Package a piece for NFT minting.- `ac-keep` — Mint a KidLisp piece as an NFT.- `ac-repl` — Start KidLisp REPL.- `ac-emacs-restart` — Restart Emacs daemon.## Emacs Terminal BuffersThe 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`:- `🐟-fishy` or "fishy" — Main fish shell terminal for general commands- `🩸-artery` or "artery" — Artery service logs- `💳-stripe-print` — Stripe print logs- `🤖-chat-system` — Chat system logs- `📋-session` — Session server logs- `🌐-site` — Site/web server logs- `🔴-redis` — Redis logs- `🖼️-views` — Views logs- `🤖-llm` — LLM service logs- `💥-crash-diary` — Crash logs- `📊-top` — System monitoring (top)- `🧪-kidlisp` — KidLisp test runner- `📦-media` — Media service logs- `🔥-oven` — Oven service logs- `🔖-bookmarks` — Bookmarks- `⏰-chat-clock` — Chat clock logs- `🧠-chat-sotce` — Sotce chat logs- `🎫-stripe-ticket` — Stripe ticket logs- `⚡-url` — URL service logs- `🚇-tunnel` — Tunnel logs**Usage**: When asked to run commands in "fishy" or any named terminal, use:1. `mcp_emacs_emacs_switch_buffer` to switch to the buffer2. `mcp_emacs_emacs_send_keys` to send the command3. Send a newline character to executeEmacs tabs can be switched with `(tab-bar-select-tab N)` via `mcp_emacs_execute_emacs_lisp`.## Coding Style & Naming Conventions- JavaScript/TypeScript modules use ESM (`.mjs`); prefer 2-space indentation and trailing commas. - Run Prettier where available (`npx prettier --write <files>`); respect existing file conventions (some legacy scripts mix shell/Fish). - Name new pieces and assets with lowercase-hyphenated paths; colocate tests as `<name>.test.mjs` near related code or under `tests/`. - Keep configuration in `.env`-style files out of version control; use sample files if needed.## Testing Guidelines- Add focused `.test.mjs` files; use Jasmine for KidLisp specs and Node test runners for integration. - Prefer running `npm test` before PRs; include performance runs when touching rendering/audio paths. - For perf tests, document baseline numbers and hardware in the PR description. - Snapshot or fixture data should live in `tests/` subfolders; avoid large binaries in git.## Commit & Pull Request Guidelines- Follow the existing history: short, action-led subjects (`fix: ...`, `docs: ...`, or descriptive phrases). - PRs should describe the change, runtime targets (web/session), and how to reproduce/test. - Link related issues or user-facing commands; add screenshots or clips for UI/visual changes. - Keep commits logically scoped; prefer small, reviewable units over large drops. - Ensure `npm test` (and relevant perf or KidLisp suites) are green before requesting review.## Security & Configuration Tips- Never commit secrets; use environment variables and the Netlify/Jamsocket env management scripts in `system/`. - When syncing assets, use `npm run assets:sync:down`/`up` and verify paths under `system/public/assets`. - Treat production endpoints in scripts as sensitive; dry-run changes against local or dev tunnels first.