|
2 | 2 |
|
3 | 3 | Guidance for coding agents working in this repo. |
4 | 4 |
|
5 | | -## Read First |
| 5 | +## Local Setup |
6 | 6 |
|
7 | | -Before assuming the browser or local dev setup is broken, check: |
| 7 | +- `http://localhost:5173` — Vite dev server (frontend). |
| 8 | +- `http://localhost:9883` — local Atomic Server. |
8 | 9 |
|
9 | | -- [`README.md`](/Users/joep/dev/github/atomicdata-dev/atomic-server/README.md) |
10 | | -- [`CONTRIBUTING.md`](/Users/joep/dev/github/atomicdata-dev/atomic-server/CONTRIBUTING.md) |
11 | | -- [`browser/CONTRIBUTING.md`](/Users/joep/dev/github/atomicdata-dev/atomic-server/browser/CONTRIBUTING.md) |
12 | | -- [`browser/e2e/tests/e2e.spec.ts`](/Users/joep/dev/github/atomicdata-dev/atomic-server/browser/e2e/tests/e2e.spec.ts) |
13 | | -- [`browser/e2e/tests/test-utils.ts`](/Users/joep/dev/github/atomicdata-dev/atomic-server/browser/e2e/tests/test-utils.ts) |
| 10 | +The frontend auto-updates via HMR. If changes don't appear, reload the page. If you edit `@tomic/lib` or `@tomic/react`, those packages may need a rebuild first. |
14 | 11 |
|
15 | | -The Playwright E2E helpers are the best source of truth for expected local browser flows. |
| 12 | +## Quick Dev Setup |
16 | 13 |
|
17 | | -## Local Browser Mental Model |
| 14 | +Navigate to `http://localhost:5173/app/dev-drive` to instantly create a fresh agent + drive on `localhost:9883` and switch to it. Only works in dev mode. |
18 | 15 |
|
19 | | -- `http://localhost:5173` is the frontend app origin. |
20 | | -- `http://localhost:9883` is the local Atomic Server origin. |
21 | | -- The frontend on `5173` should auto-update during normal local development. |
22 | | -- If you patch browser code and do not see the change, reload the page first. |
23 | | -- If the UI still looks stale, check whether the changed package needs a rebuild. |
| 16 | +In E2E tests, use `devDrive(page)` from `test-utils.ts`: |
24 | 17 |
|
25 | | -From [`browser/CONTRIBUTING.md`](/Users/joep/dev/github/atomicdata-dev/atomic-server/browser/CONTRIBUTING.md): |
26 | | - |
27 | | -- Vite provides HMR for the data browser. |
28 | | -- If you edit `@tomic/lib` or `@tomic/react`, the browser may still depend on built `.js` output, so those packages may need rebuilding or watch mode. |
| 18 | +```ts |
| 19 | +await devDrive(page); // goes to /app/dev-drive and waits for the drive to be ready |
| 20 | +``` |
29 | 21 |
|
30 | 22 | ## Charlotte / Browser Automation |
31 | 23 |
|
32 | | -When using Charlotte or any browser automation: |
33 | | - |
34 | | -- Keep the main automation anchored in the frontend app at `5173`. |
35 | | -- Do not treat direct navigation to `9883` as equivalent to the app state on `5173`. |
36 | | -- Use the top-left `Open Drive Settings` control as the main entry point for drive/server changes. |
37 | | - |
38 | | -If the app is pointed at `5173` as its active drive/server, the UI can look broken: |
39 | | - |
40 | | -- opening `http://localhost:5173/` as a resource returns `404` |
41 | | -- websocket attempts go to `ws://localhost:5173/ws` and fail |
42 | | -- you may see `Unauthorized`, `Resource not found`, or `Something went wrong` |
43 | | - |
44 | | -This usually means the drive/server configuration is wrong, not that the app is dead. |
45 | | - |
46 | | -## Known Good UI Flow |
47 | | - |
48 | | -### Sign in or create a local identity |
49 | | - |
50 | | -1. Open `Login / New User`. |
51 | | -2. Click `Create new identity`. |
52 | | -3. Copy the generated secret. |
53 | | -4. Click `Yes, I've stored it safely`. |
54 | | - |
55 | | -After that, the sidebar entry becomes `User Settings`. |
56 | | - |
57 | | -Known oddity: |
58 | | - |
59 | | -- During identity creation you may see an error like `Could not fetch url 'did:ad:agent:...', must start with http.` |
60 | | -- Treat that as noise unless it blocks the flow. |
61 | | - |
62 | | -### Switch to the local server |
63 | | - |
64 | | -1. Click `Open Drive Settings`. |
65 | | -2. Go to the drive configuration UI. |
66 | | -3. Set the custom drive URL to `http://localhost:9883`. |
67 | | -4. Save it. |
68 | | - |
69 | | -See the `changeDrive()` helper in [`browser/e2e/tests/test-utils.ts`](/Users/joep/dev/github/atomicdata-dev/atomic-server/browser/e2e/tests/test-utils.ts). |
70 | | - |
71 | | -### Create a fresh drive |
72 | | - |
73 | | -Once an agent exists: |
74 | | - |
75 | | -1. Click `Open Drive Settings`. |
76 | | -2. Click `New Drive`. |
77 | | -3. Fill `Name` and `Subdomain`. |
78 | | -4. Click `Create`. |
79 | | -5. Wait for the app to navigate to a `did:ad:` subject. |
80 | | -6. Confirm the sidebar drive title updates. |
81 | | - |
82 | | -See the `newDrive()` helper in [`browser/e2e/tests/test-utils.ts`](/Users/joep/dev/github/atomicdata-dev/atomic-server/browser/e2e/tests/test-utils.ts). |
| 24 | +- Always operate the app at `localhost:5173`, not `9883` directly. |
| 25 | +- Start every session by navigating to `http://localhost:5173/app/dev-drive` to get a clean, authenticated state. |
| 26 | +- If the app shows `Unauthorized` or `Something went wrong`, navigate to `/app/dev-drive` to fix it. |
83 | 27 |
|
84 | | -## Practical Debugging Checklist |
| 28 | +## Debugging Checklist |
85 | 29 |
|
86 | 30 | - Is the frontend open on `5173`? |
87 | | -- Is the active drive/server actually `9883`? |
| 31 | +- Is the active drive/server `9883`? |
88 | 32 | - Is there a signed-in agent? |
89 | | -- If browser flows need isolation, create a fresh drive first. |
90 | | -- For browser behavior, compare against the E2E helpers before inventing a new interaction path. |
| 33 | +- Run `devDrive(page)` to reset to a clean state. |
0 commit comments