@edryslabs/edrys-dev 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 edrys-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The MCP server (src/mcp.ts) and the agent chat follow LiaScript DevServer
+(https://github.com/LiaScript/LiaScript-DevServer), MIT License,
+Copyright (c) 2021 LiaScript.

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# edrys-dev
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Develop an [edrys-Lite](https://github.com/edrys-labs/edrys-Lite) lab on your own machine. `edrys-dev` serves edrys-Lite from localhost and keeps a class in step with your lab file: save `lab.yml` and the class updates in every open tab.
+
+```bash
+npm install -g @edryslabs/edrys-dev
+edrys-dev lab.yml --open
+```
+
+Or without installing: `npx @edryslabs/edrys-dev lab.yml --open`. Needs Node.js 20 or newer.
+
+```
+edrys-dev: /home/you/my-lab/lab.yml
+  http://localhost:3210/?dev
+class open, share link:
+  http://localhost:3210/?/classroom/…
+```
+
+- The tab opened at `/?dev` owns the class. It imports the lab the first time and republishes it, signed, whenever the file changes. The same lab file reopens the same class after a restart.
+- 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.
+- 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=…`).
+- 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.
+
+When the lab is done, publish `lab.yml` as usual (for example with a deploy link to https://edrys-labs.github.io).
+
+## Local modules
+
+Put modules you are writing into a `modules/` folder next to the lab, one per subfolder, and use their local address in `lab.yml`:
+
+```yaml
+modules:
+  - url: http://localhost:3211/my-module/index.html
+```
+
+edrys-dev serves that folder on the port after its own (3211 by default; another origin, as real modules have). Saving a file in `modules/my-module/` reloads that module in the class tab, without touching the others, and reloads student and station tabs. Its HTML pages get a small script that reports uncaught errors and `console.error` to edrys-dev, for the agent. Such a lab only works on your machine: replace the local addresses with the published ones before you deploy it.
+
+## With an AI agent (`--mcp`)
+
+With `--mcp`, edrys-dev is an MCP server over stdio: an agent such as Claude Code starts it, edits `lab.yml` with its own file tools and hears from the browser when the class could not take the lab. Put it into the lab folder's `.mcp.json`; do not start `--mcp` yourself:
+
+```json
+{
+  "mcpServers": {
+    "edrys": { "command": "npx", "args": ["-y", "@edryslabs/edrys-dev", "--mcp", "lab.yml"] }
+  }
+}
+```
+
+With edrys-dev installed globally, `"command": "edrys-dev", "args": ["--mcp", "lab.yml"]` starts faster.
+
+Tools: `get_state` (lab file, class URL, share link, the class: rooms, users, modules), `goto` (move the class tab to a room, open a student or station tab), `chat` and `read_chat`, `read_messages` (module messages the class tab saw, and errors of local modules), `read_module_state` (what the modules share in a room), `run_in_module` (JavaScript in a local module's frame, only when you ask for it), `wait_for_event`. Browser events reach Claude Code as channel messages; agents without channels read the event stream in `get_state.events` (e.g. with a Monitor) or call `wait_for_event`. If the port is taken, the next free one is used; the agent finds the URL with `get_state`.
+
+The class tab gets a chat panel (🤖, bottom right) where you and the agent talk; it is not the class's own chat, nobody else sees it. The agent can ask with buttons or checkboxes there. The chat is saved in `.edrys-dev/chat.json` next to the lab, so a restarted agent can read it; add `.edrys-dev/` to the lab's `.gitignore`.
+
+The tools show the agent whether the lab works; what to write comes from the [edrys skills](https://github.com/edrys-labs/skills), recommended with edrys-dev: `edrys-lab` for labs, `edrys-module` for modules. Both say how to use edrys-dev when it is connected.
+
+```bash
+npx skills add edrys-labs/skills
+```
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `[lab.yml]`, `-i, --input <file>` | `./lab.yml` | lab file, YAML or JSON |
+| `-p, --port <port>` | `3210` | the next free port is used if it is taken |
+| `--host <host>` | `127.0.0.1` | address to listen on |
+| `--local` | off | sync on edrys-dev's own port instead of edrys-Lite's default transport |
+| `-m, --modules <dir>` | `./modules` next to the lab, if it exists | local modules, one per subfolder, see above |
+| `-o, --open` | off | open the lab in the browser |
+| `--mcp` | off | serve an AI agent over stdio, see above |
+
+## Development
+
+```bash
+npm install
+npm run build    # tsc → dist/
+npm test         # builds, then runs test/*.test.js
+```
+
+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.
+
+## License
+
+[MIT](LICENSE). The MCP server and the agent chat follow [LiaScript DevServer](https://github.com/LiaScript/LiaScript-DevServer) (MIT).

package/dist/chat.js

@@ -0,0 +1,136 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import express from 'express';
+import { sameOrigin } from './origin.js';
+// what the saved chat keeps, oldest first out
+const MAX_ENTRIES = 500;
+/**
+ * The agent chat over the class tab: its history, saved next to the lab in
+ * .edrys-dev/chat.json, and the panel's endpoints. Not the class's own
+ * (signed) chat: only the author and the agent see it.
+ *
+ * Emits `user` (entry) when the user typed, `answer` (entry) when they
+ * answered a form, and `connection` (boolean) when the panel came or went.
+ */
+export class Chat extends EventEmitter {
+    file;
+    entries = [];
+    /** The one form the user can still answer. Forms of earlier runs are closed. */
+    open = null;
+    status = '';
+    panels = new Set();
+    constructor(file) {
+        super();
+        this.file = file;
+        try {
+            this.entries = JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch { }
+    }
+    get connected() {
+        return this.panels.size > 0;
+    }
+    /** Posts a message; returns the id of its form if it has inputs. */
+    say(markdown, inputs = [], status) {
+        const ask = inputs.length ? 'ask-' + crypto.randomBytes(4).toString('hex') : undefined;
+        const entry = { t: Date.now(), type: 'ai', markdown, ...(ask ? { ask, inputs } : {}) };
+        // only the newest form stays open
+        if (ask) {
+            this.closeForm();
+            this.open = ask;
+        }
+        this.add(entry);
+        this.setStatus(status ?? '');
+        return ask;
+    }
+    setStatus(status) {
+        this.status = status;
+        this.send({ type: 'status', text: status });
+    }
+    /** Withdraws the open form; returns its id, or null if there was none. */
+    closeForm() {
+        const closed = this.open;
+        this.open = null;
+        if (closed)
+            this.send({ type: 'close', ask: closed });
+        return closed;
+    }
+    routes(app) {
+        app.get('/edrys-dev/chat/events', (req, res) => {
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                Connection: 'keep-alive',
+            });
+            // a reload shows the whole chat again, with the open form and status
+            res.write(`data: ${JSON.stringify({ type: 'history', entries: this.entries, open: this.open, status: this.status })}\n\n`);
+            this.panels.add(res);
+            if (this.panels.size === 1)
+                this.emit('connection', true);
+            req.on('close', () => {
+                this.panels.delete(res);
+                if (this.panels.size === 0)
+                    this.emit('connection', false);
+            });
+        });
+        app.post('/edrys-dev/chat', express.json(), (req, res) => {
+            if (!sameOrigin(req))
+                return res.sendStatus(403);
+            const { text, ask, values } = req.body ?? {};
+            if (typeof text === 'string' && text.trim()) {
+                const entry = { t: Date.now(), type: 'user', text: text.slice(0, 10000) };
+                this.add(entry);
+                this.emit('user', entry);
+                return res.sendStatus(204);
+            }
+            if (typeof ask === 'string' && ask === this.open && values && typeof values === 'object') {
+                this.open = null;
+                const entry = { t: Date.now(), type: 'answer', ask, values };
+                this.add(entry);
+                this.emit('answer', entry);
+                return res.sendStatus(204);
+            }
+            // e.g. a form that was closed in the meantime
+            res.sendStatus(409);
+        });
+        for (const [file, source] of Object.entries(PANEL_FILES)) {
+            // dotfiles: sendFile checks the whole absolute path, and installs often
+            // live under one (~/.nvm, ~/.npm/_npx); the path is ours, not the request's
+            app.get('/edrys-dev/' + file, (req, res) => res.sendFile(source(), { dotfiles: 'allow' }));
+        }
+    }
+    add(entry) {
+        this.entries.push(entry);
+        if (this.entries.length > MAX_ENTRIES)
+            this.entries.splice(0, this.entries.length - MAX_ENTRIES);
+        this.send({ type: 'entry', entry });
+        this.save();
+    }
+    send(message) {
+        for (const panel of this.panels)
+            panel.write(`data: ${JSON.stringify(message)}\n\n`);
+    }
+    save() {
+        try {
+            fs.mkdirSync(path.dirname(this.file), { recursive: true });
+            fs.writeFileSync(this.file, JSON.stringify(this.entries));
+        }
+        catch (error) {
+            console.error('edrys-dev: could not save the chat:', error.message);
+        }
+    }
+}
+const require = createRequire(import.meta.url);
+const views = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'views');
+// browser builds that set window.marked and window.DOMPurify
+const PANEL_FILES = {
+    'panel.js': () => path.join(views, 'panel.js'),
+    'marked.js': () => path.join(path.dirname(require.resolve('marked/package.json')), 'lib', 'marked.umd.js'),
+    'purify.js': () => require.resolve('dompurify/purify.min.js'),
+};
+/** The script tag that brings the panel into the edrys-Lite page. */
+export const PANEL_SCRIPT = '<script src="/edrys-dev/panel.js" defer></script>';

package/dist/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import open from 'open';
+import { startDevServer } from './server.js';
+import { startMcp } from './mcp.js';
+const HELP = `edrys-dev: develop an edrys-Lite lab locally
+
+Usage: edrys-dev [lab.yml] [options]
+
+  -i, --input <file>  lab file (YAML or JSON), default ./lab.yml
+  -p, --port <port>   port, default 3210 (the next free one if taken)
+      --host <host>   address to listen on, default 127.0.0.1
+      --local         sync on this server instead of edrys-Lite's default
+                      transport (works offline)
+  -m, --modules <dir> local modules, one per subfolder, served on the next
+                      port (default ./modules next to the lab, if it exists);
+                      a save there reloads that module in the class
+  -o, --open          open the lab in the browser
+      --mcp           serve an AI agent over stdio (MCP); started by the
+                      agent from its MCP config, not by hand
+  -h, --help          show this help
+
+The tab opened at /?dev owns the class and republishes it whenever the lab
+file changes. Open its share link in another browser to join as a student.`;
+const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+        input: { type: 'string', short: 'i' },
+        port: { type: 'string', short: 'p', default: '3210' },
+        host: { type: 'string', default: '127.0.0.1' },
+        local: { type: 'boolean', default: false },
+        modules: { type: 'string', short: 'm' },
+        open: { type: 'boolean', short: 'o', default: false },
+        mcp: { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+    },
+});
+// with --mcp, stdout carries the protocol
+const say = values.mcp ? console.error : console.log;
+if (values.help) {
+    say(HELP);
+    process.exit(0);
+}
+const lab = path.resolve(values.input ?? positionals[0] ?? 'lab.yml');
+if (!fs.existsSync(lab)) {
+    console.error(`edrys-dev: no lab file at ${lab}\n\n${HELP}`);
+    process.exit(1);
+}
+const nextToLab = path.join(path.dirname(lab), 'modules');
+const modules = values.modules ? path.resolve(values.modules) : fs.existsSync(nextToLab) ? nextToLab : undefined;
+if (modules && !fs.statSync(modules, { throwIfNoEntry: false })?.isDirectory()) {
+    console.error(`edrys-dev: no modules folder at ${modules}`);
+    process.exit(1);
+}
+const server = await startDevServer({
+    lab,
+    port: Number(values.port),
+    host: values.host,
+    local: values.local,
+    modules,
+});
+server.bus.on('report', (report) => {
+    switch (report.type) {
+        case 'open':
+            say(`class open, share link:\n  ${report.url}`);
+            break;
+        case 'error':
+            console.error(`lab error: ${report.message}`);
+            break;
+    }
+});
+const host = ['127.0.0.1', '0.0.0.0', '::'].includes(values.host) ? 'localhost' : values.host;
+const url = `http://${host}:${server.port}/?dev`;
+say(`edrys-dev: ${lab}\n  ${url}`);
+if (server.modules)
+    say(`modules: ${server.modules.dir}\n  ${server.modules.url}<name>/...`);
+if (values.mcp)
+    startMcp(server, { lab, url });
+if (values.open)
+    await open(url);
+process.on('SIGINT', async () => {
+    await server.close();
+    process.exit(0);
+});