@edryslabs/edrys-dev 0.1.2 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +163 -43
- package/dist/chat.js +332 -28
- package/dist/index.js +16 -5
- package/dist/mcp.js +319 -38
- package/dist/modules.js +14 -3
- package/dist/origin.js +55 -3
- package/dist/server.js +22 -13
- package/dist/sync.js +9 -3
- package/dist/watch.js +18 -0
- package/package.json +2 -2
- package/views/panel.js +92 -11
package/README.md
CHANGED
|
@@ -1,85 +1,205 @@
|
|
|
1
1
|
# edrys-dev
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Build and try out an [edrys-Lite](https://github.com/edrys-labs/edrys-Lite) lab on your own computer before you share it with your students.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
npm install -g @edryslabs/edrys-dev
|
|
7
|
-
edrys-dev lab.yml --open
|
|
8
|
-
```
|
|
5
|
+
You write your lab in a file (`lab.yml`), `edrys-dev` opens it as a class in your browser, and every time you save the file the class updates in all open tabs. No account and no deploy needed while you work.
|
|
9
6
|
|
|
10
|
-
|
|
7
|
+
## Quick start
|
|
11
8
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
9
|
+
You need [Node.js](https://nodejs.org) 20 or newer.
|
|
10
|
+
|
|
11
|
+
1. Make a folder for your lab and create a file `lab.yml` in it:
|
|
12
|
+
|
|
13
|
+
```yaml
|
|
14
|
+
name: My first lab
|
|
15
|
+
meta:
|
|
16
|
+
description: Trying out edrys-dev.
|
|
17
|
+
modules:
|
|
18
|
+
- url: https://edrys-labs.github.io/module-markdown-it/index.html
|
|
19
|
+
config:
|
|
20
|
+
content: |
|
|
21
|
+
# Welcome
|
|
22
|
+
|
|
23
|
+
Edit lab.yml, save it, and watch this text change.
|
|
24
|
+
width: full
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
2. Start edrys-dev in that folder:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npx @edryslabs/edrys-dev lab.yml --open
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Your browser opens the class. In the terminal you see two addresses:
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
edrys-dev: /home/you/my-lab/lab.yml
|
|
37
|
+
http://localhost:3210/?dev
|
|
38
|
+
class open, share link:
|
|
39
|
+
http://localhost:3210/?/classroom/…
|
|
40
|
+
```
|
|
18
41
|
|
|
19
|
-
|
|
20
|
-
- To try the lab as a student or station, open the share link in another browser or a private window. Each browser has its own identity, so it joins as a student, not as the owner.
|
|
21
|
-
- The class connects the way it will for your students: with the lab's own `communicationConfig`, or else edrys-Lite's default transport. With `--local` it syncs over edrys-dev's own port instead, which works offline; the share link then carries the setting (`#comm=…`).
|
|
22
|
-
- The lab file is the source of truth. Changes made in the class's Settings dialog are overwritten on the next save of the file.
|
|
42
|
+
3. Change something in `lab.yml` and save. The class updates on its own.
|
|
23
43
|
|
|
24
|
-
|
|
44
|
+
If you use edrys-dev often, install it once with `npm install -g @edryslabs/edrys-dev` and then start it with just `edrys-dev lab.yml --open`.
|
|
25
45
|
|
|
26
|
-
|
|
46
|
+
Stop it with `Ctrl+C`.
|
|
47
|
+
|
|
48
|
+
## Working on a lab
|
|
49
|
+
|
|
50
|
+
- **The `/?dev` tab is yours.** It is the teacher's view of the class. Keep it open: it is the tab that picks up your changes to `lab.yml`.
|
|
51
|
+
- **Try the lab as a student or station.** Open the share link in a *different* browser or a private window. In the same browser you would be the teacher again.
|
|
52
|
+
- **The file wins.** Anything you change in the class's Settings dialog is replaced the next time you save `lab.yml`. Make your changes in the file.
|
|
53
|
+
- **Restarting is safe.** The same `lab.yml` reopens the same class, so share links you opened before keep working.
|
|
54
|
+
- **Mistakes are reported.** If the class cannot take your lab (for example a YAML typo), the terminal prints `lab error: …`. Fix the file and save again.
|
|
55
|
+
- **Offline?** Start with `--local`. The class then connects through edrys-dev itself instead of the internet.
|
|
56
|
+
|
|
57
|
+
Which modules exist and how to configure them is described in the [edrys-Lite documentation](https://github.com/edrys-labs/edrys-Lite) and the [edrys skills](https://github.com/edrys-labs/skills).
|
|
58
|
+
|
|
59
|
+
### When the lab is done
|
|
60
|
+
|
|
61
|
+
Publish `lab.yml` the way you normally would, for example in a GitHub repository with a deploy link to https://edrys-labs.github.io. Nothing from edrys-dev ends up in the file.
|
|
62
|
+
|
|
63
|
+
## Writing your own modules
|
|
64
|
+
|
|
65
|
+
If you are also writing a module, put it into a `modules/` folder next to the lab, one subfolder per module:
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
my-lab/
|
|
69
|
+
├── lab.yml
|
|
70
|
+
└── modules/
|
|
71
|
+
└── my-module/
|
|
72
|
+
└── index.html
|
|
73
|
+
```
|
|
27
74
|
|
|
28
|
-
|
|
75
|
+
edrys-dev serves this folder on the next port (3211 by default). Use that address in `lab.yml`:
|
|
29
76
|
|
|
30
77
|
```yaml
|
|
31
78
|
modules:
|
|
32
79
|
- url: http://localhost:3211/my-module/index.html
|
|
33
80
|
```
|
|
34
81
|
|
|
35
|
-
|
|
82
|
+
When you save a file in `modules/my-module/`, only that module reloads in the class. Errors from your module's page are collected so an AI agent can see them (see below).
|
|
36
83
|
|
|
37
|
-
|
|
84
|
+
These addresses only work on your computer. Publish the module (for example on GitHub Pages) and put its real address into `lab.yml` before you share the lab.
|
|
38
85
|
|
|
39
|
-
With
|
|
86
|
+
## With an AI agent
|
|
40
87
|
|
|
41
|
-
|
|
42
|
-
{
|
|
43
|
-
"mcpServers": {
|
|
44
|
-
"edrys": { "command": "npx", "args": ["-y", "@edryslabs/edrys-dev", "--mcp", "lab.yml"] }
|
|
45
|
-
}
|
|
46
|
-
}
|
|
47
|
-
```
|
|
88
|
+
edrys-dev can work together with an AI coding agent such as Claude Code or GitHub Copilot. The agent edits `lab.yml` for you, sees whether the class accepts it, and can look into the class: rooms, users, modules and their messages.
|
|
48
89
|
|
|
49
|
-
|
|
90
|
+
### Setup
|
|
50
91
|
|
|
51
|
-
|
|
92
|
+
1. Create a file `.mcp.json` in your lab folder:
|
|
52
93
|
|
|
53
|
-
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"mcpServers": {
|
|
97
|
+
"edrys": { "command": "npx", "args": ["-y", "@edryslabs/edrys-dev", "--mcp", "lab.yml"] }
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
54
101
|
|
|
55
|
-
|
|
102
|
+
If you installed edrys-dev globally, `"command": "edrys-dev", "args": ["--mcp", "lab.yml"]` starts faster.
|
|
56
103
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
```
|
|
104
|
+
2. Install the edrys skills, so the agent knows how labs and modules are written:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
npx skills add edrys-labs/skills
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
3. Start your agent in the lab folder. **The agent starts edrys-dev itself**; don't start it by hand as well. Ask the agent for the class address if your browser doesn't open it.
|
|
111
|
+
|
|
112
|
+
### Talking to the agent from the class
|
|
113
|
+
|
|
114
|
+
The class tab has a chat button (🤖, bottom right). What you write there goes straight to the agent. Only you see this chat; it is not the class chat. The agent can answer with text and also with buttons or checkboxes for you to pick from.
|
|
115
|
+
|
|
116
|
+
Under your message you see "Waiting for the agent…" until the agent picks it up, then "Thinking…". If nothing happens for 30 seconds, the agent may not be listening. Your message is kept and answered once it is.
|
|
117
|
+
|
|
118
|
+
Some agents don't notice new messages on their own while they are idle. In that case start the `chat` prompt of the edrys server once (in VS Code Copilot: type `/edrys.chat`, or `/mcp.edrys.chat` in older versions), and the agent keeps waiting for your messages.
|
|
119
|
+
|
|
120
|
+
Chats are saved in `.edrys-dev/chats/` next to the lab, so a restarted agent can pick up where you left off. The menu at the top of the chat starts a new chat or reopens an old one. Add `.edrys-dev/` to your `.gitignore`.
|
|
121
|
+
|
|
122
|
+
For safety, the chat only accepts messages from the class page on your own computer. Other websites or people on your network cannot write to your agent, as long as you keep `--host` at its default.
|
|
123
|
+
|
|
124
|
+
### What the agent can do
|
|
125
|
+
|
|
126
|
+
| Tool | |
|
|
127
|
+
|---|---|
|
|
128
|
+
| `get_state` | the lab file, class address, share link, rooms, users and modules |
|
|
129
|
+
| `goto` | move your class tab to a room, or open a student or station tab |
|
|
130
|
+
| `chat`, `read_chat` | write to you in the class chat, read your messages |
|
|
131
|
+
| `read_messages` | messages between modules, and errors from your own modules |
|
|
132
|
+
| `read_module_state` | what the modules share in a room |
|
|
133
|
+
| `run_in_module` | run JavaScript inside one of your own modules, only when you ask for it |
|
|
134
|
+
| `wait_for_event` | wait for the next thing that happens in the class |
|
|
60
135
|
|
|
61
136
|
## Options
|
|
62
137
|
|
|
138
|
+
```
|
|
139
|
+
edrys-dev [lab.yml] [options]
|
|
140
|
+
```
|
|
141
|
+
|
|
63
142
|
| Option | Default | |
|
|
64
143
|
|---|---|---|
|
|
65
|
-
| `[lab.yml]`, `-i, --input <file>` | `./lab.yml` | lab file, YAML or JSON |
|
|
66
|
-
| `-
|
|
67
|
-
|
|
|
68
|
-
| `--local` | off |
|
|
69
|
-
| `-m, --modules <dir>` | `./modules
|
|
70
|
-
|
|
|
71
|
-
| `--mcp` | off |
|
|
144
|
+
| `[lab.yml]`, `-i, --input <file>` | `./lab.yml` | the lab file, YAML or JSON |
|
|
145
|
+
| `-o, --open` | off | open the class in the browser |
|
|
146
|
+
| `-p, --port <port>` | `3210` | if it is taken, the next free port is used |
|
|
147
|
+
| `--local` | off | connect the class through edrys-dev instead of the internet; works offline |
|
|
148
|
+
| `-m, --modules <dir>` | `./modules`, if it exists | folder with your own modules |
|
|
149
|
+
| `--host <host>` | `127.0.0.1` | `0.0.0.0` lets others on your network open the class (and, with `--mcp`, write to your agent) |
|
|
150
|
+
| `--mcp` | off | for AI agents; set it in `.mcp.json`, see above |
|
|
151
|
+
| `-h, --help` | | show help |
|
|
152
|
+
|
|
153
|
+
## Troubleshooting
|
|
154
|
+
|
|
155
|
+
- **`no lab file at …`**: edrys-dev looks for `lab.yml` in the current folder. Start it in your lab folder or give the path: `edrys-dev path/to/lab.yml`.
|
|
156
|
+
- **The share link opens me as the teacher.** Open it in another browser or a private window.
|
|
157
|
+
- **My changes in Settings are gone.** They are replaced by `lab.yml` on every save. Put them into the file.
|
|
158
|
+
- **The class doesn't connect / no internet.** Try `--local`.
|
|
159
|
+
- **A different port than 3210.** Another program uses it; edrys-dev took the next free one. The terminal shows the address.
|
|
160
|
+
- **The agent doesn't answer in the chat.** Check that your agent is running in the lab folder with `.mcp.json`, and if it does not wake up on its own, start the `chat` prompt (see above).
|
|
72
161
|
|
|
73
162
|
## Development
|
|
74
163
|
|
|
164
|
+
To work on edrys-dev itself:
|
|
165
|
+
|
|
75
166
|
```bash
|
|
76
167
|
npm install
|
|
77
168
|
npm run build # tsc → dist/
|
|
78
169
|
npm test # builds, then runs test/*.test.js
|
|
79
170
|
```
|
|
80
171
|
|
|
172
|
+
How the parts talk to each other:
|
|
173
|
+
|
|
174
|
+
```mermaid
|
|
175
|
+
flowchart LR
|
|
176
|
+
lab[lab.yml] -- watch --> srv
|
|
177
|
+
mods[modules/] -- watch --> msrv["module server :3211<br/>(module pages + error script)"]
|
|
178
|
+
subgraph srv ["edrys-dev :3210"]
|
|
179
|
+
direction TB
|
|
180
|
+
static["edrys-Lite dist + panel.js"]
|
|
181
|
+
api["/edrys-dev/lab · events · reload · bridge · module-error"]
|
|
182
|
+
end
|
|
183
|
+
srv -- "reload-lab, reload-module (SSE events)" --> tab["class tab /?dev"]
|
|
184
|
+
tab -- "GET lab, republish signed" --> room((class))
|
|
185
|
+
tab -- "state, messages, replies (POST bridge)" --> srv
|
|
186
|
+
msrv -- module frames --> tab
|
|
187
|
+
msrv -. "errors (POST module-error)" .-> srv
|
|
188
|
+
srv -- "reload (SSE)" --> peers
|
|
189
|
+
room -- "default transport, or --local on :3210" --> peers[student / station tabs]
|
|
190
|
+
agent[AI agent] <-- "MCP over stdio (--mcp)" --> srv
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
- `index.ts` reads the options and starts the server, and with `--mcp` the MCP server (`mcp.ts`).
|
|
194
|
+
- `server.ts` serves edrys-Lite, watches the lab (`watch.ts`) and talks to the class tab: events go out over SSE, the tab's reports come back over `POST /edrys-dev/bridge`.
|
|
195
|
+
- In the class tab, edrys-Lite's own `DevBridge` (`src/ts/DevBridge.ts` in edrys-Lite, active with `?dev`) loads and republishes the lab and reports the class. edrys-dev adds `views/panel.js` to the page: the agent chat (`chat.ts` on the server), and in student and station tabs the reload on module changes.
|
|
196
|
+
- `modules.ts` serves local modules on the next port and adds the error reporter to their pages.
|
|
197
|
+
- `sync.ts` is the Yjs sync for `--local`, on edrys-dev's own port.
|
|
198
|
+
|
|
81
199
|
edrys-Lite comes from npm as [`@edryslabs/edrys-lite`](https://www.npmjs.com/package/@edryslabs/edrys-lite), pinned to one version: its `dist/` is what edrys-dev serves. To try changes to edrys-Lite, build it (`npm run build` there) and link the checkout with `npm install ../edrys-Lite`; pin the published version again afterwards. The same goes for [`@edryslabs/websocket-server`](https://www.npmjs.com/package/@edryslabs/websocket-server), an optional dependency that only `--local` uses.
|
|
82
200
|
|
|
201
|
+
Issues and pull requests: https://github.com/edrys-labs/edrys-devserver
|
|
202
|
+
|
|
83
203
|
## License
|
|
84
204
|
|
|
85
205
|
[MIT](LICENSE). The MCP server and the agent chat follow [LiaScript DevServer](https://github.com/LiaScript/LiaScript-DevServer) (MIT).
|