@edryslabs/edrys-dev 0.2.0 → 0.3.0

package/README.md

@@ -22,6 +22,7 @@ You need [Node.js](https://nodejs.org) 20 or newer.
 
            Edit lab.yml, save it, and watch this text change.
        width: full
+       height: tall
    ```
 
 2. Start edrys-dev in that folder:
@@ -89,6 +90,16 @@ edrys-dev can work together with an AI coding agent such as Claude Code or GitHu
 
 ### Setup
 
+The quick way, for a new lab:
+
+```bash
+npx @edryslabs/edrys-dev init my-lab
+```
+
+This makes the folder `my-lab` with a starter `lab.yml`, the agent configuration for Claude Code (`.mcp.json`) and VS Code Copilot (`.vscode/mcp.json`), instructions for the agent (`AGENTS.md`, `CLAUDE.md`), Claude Code settings that let the agent use edrys-dev and edit `lab.yml` and `modules/` without asking each time (`.claude/settings.json`), and a `.gitignore`. In a folder that already has some of these files, it keeps them. If the edrys skills (step 2 below) are not installed yet, it offers to install them for you. Then open the folder in your agent and write "start".
+
+By hand:
+
 1. Create a file `.mcp.json` in your lab folder:
 
    ```json
@@ -107,12 +118,14 @@ edrys-dev can work together with an AI coding agent such as Claude Code or GitHu
    npx skills add edrys-labs/skills
    ```
 
-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.
+3. Start your agent in the lab folder. **The agent starts edrys-dev itself**; don't start it by hand as well. If the folder has no `lab.yml` yet, edrys-dev creates a starter lab there. Ask the agent for the class address if your browser doesn't open it.
 
 ### Talking to the agent from the class
 
 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.
 
+When the class cannot take your lab file, for example after a typing mistake, a red note in the chat says so in plain words, with edrys-Lite's message under "Details". It goes away once the file loads again.
+
 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.
 
 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.

package/dist/chat.js

@@ -25,6 +25,18 @@ export const THINKING = 'Thinking…';
 const NO_REACTION = 'The agent has not reacted yet, maybe it is not connected. Your message is saved, it answers once it starts.';
 const QUIET = 'The agent is still working, this can take a while.';
 const HINT_MS = { noReaction: 30_000, quiet: 60_000 };
+const STILL = 'The class still shows the last version that worked. Ask the agent here to fix it.';
+/** A LabProblem from the message of edrys-Lite's DevBridge (fetchLab there). */
+export function explain(message) {
+    // js-yaml names line and column: "could not parse <path>: <what> (4:4)\n\n<snippet>"
+    const line = /^could not parse .*?: .*? \((\d+):\d+\)/.exec(message)?.[1];
+    const text = line
+        ? `There is a typing mistake in the lab file, around line ${line}.`
+        : message.startsWith('not a classroom')
+            ? 'The lab file is not a lab that edrys can read.'
+            : 'The class could not load the lab file.';
+    return { text: `${text} ${STILL}`, detail: message.slice(0, 2000) };
+}
 /**
  * `values` if they answer `inputs`: only their ids, each with one of its
  * options, a checkbox with a list of them. A radio or buttons input left
@@ -111,6 +123,7 @@ export class Chat extends EventEmitter {
     form = [];
     status = '';
     hint = '';
+    lab = null;
     // a message of the user waits for the first sign of an agent
     pending = false;
     quiet;
@@ -244,6 +257,13 @@ export class Chat extends EventEmitter {
         this.setStatus(status ?? '');
         return ask;
     }
+    /** The lab file does not load (a problem), or loads again (null): the panel shows it until then. */
+    labProblem(problem) {
+        if (JSON.stringify(problem) === JSON.stringify(this.lab))
+            return;
+        this.lab = problem;
+        this.send({ type: 'lab', problem });
+    }
     setStatus(status) {
         this.status = status;
         this.send({ type: 'status', text: status });
@@ -372,6 +392,7 @@ export class Chat extends EventEmitter {
             open: this.open,
             status: this.status,
             hint: this.hint,
+            lab: this.lab,
         };
     }
     send(message) {

package/dist/index.js

@@ -9,6 +9,8 @@ import { reachable } from './origin.js';
 const HELP = `edrys-dev: develop an edrys-Lite lab locally
 
 Usage: edrys-dev [lab.yml] [options]
+       edrys-dev init [folder]   set up a new lab for an AI agent: lab.yml,
+                                 agent config and instructions
 
   -i, --input <file>  lab file (YAML or JSON), default ./lab.yml
   -p, --port <port>   port, default 3210 (the next free one if taken)
@@ -46,7 +48,18 @@ if (values.help) {
     say(HELP);
     process.exit(0);
 }
+if (positionals[0] === 'init' && !values.input) {
+    const { init } = await import('./init.js');
+    await init(positionals[1] ?? '.');
+    process.exit(0);
+}
 const lab = path.resolve(values.input ?? positionals[0] ?? 'lab.yml');
+// an agent started in an empty folder gets a lab to work on, not a failed server
+if (!fs.existsSync(lab) && values.mcp && /\.ya?ml$/i.test(lab) && fs.statSync(path.dirname(lab), { throwIfNoEntry: false })?.isDirectory()) {
+    const { starterLab } = await import('./init.js');
+    fs.writeFileSync(lab, starterLab(path.basename(path.dirname(lab))), { flag: 'wx' });
+    say(`edrys-dev: no lab file yet, created ${lab}`);
+}
 if (!fs.existsSync(lab)) {
     console.error(`edrys-dev: no lab file at ${lab}\n\n${HELP}`);
     process.exit(1);

package/dist/init.js

@@ -0,0 +1,108 @@
+// edrys-dev init: a lab folder that an AI agent can start in, without writing
+// any config by hand. Files that exist are kept.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+const SERVER = { command: 'npx', args: ['-y', '@edryslabs/edrys-dev', '--mcp', 'lab.yml'] };
+const SETTINGS = {
+    enabledMcpjsonServers: ['edrys'],
+    permissions: { allow: ['mcp__edrys', 'Edit(/lab.yml)', 'Edit(/modules/**)'] },
+};
+/** A lab with a welcome page; also what `--mcp` starts with when there is no lab file. */
+export const starterLab = (name) => `name: ${JSON.stringify(name)}
+meta:
+  description: Made with edrys-dev.
+modules:
+  - url: https://edrys-labs.github.io/module-markdown-it/index.html
+    config:
+      content: |
+        # Welcome
+
+        Open the 🤖 chat (bottom right) and tell the agent what this lab should do.
+    width: full
+    height: tall
+`;
+const agents = (name) => `# ${name}
+
+This folder is an edrys-Lite lab: \`lab.yml\` is the classroom configuration, \`modules/\` (if there) holds modules written for it. The user works in the class in their browser and talks to you through the chat there; they may not look at this session.
+
+When a session starts:
+
+1. Call \`get_state\` of the edrys MCP server. If \`connected\` is false, open its \`url\` in the browser (browser automation or the system's open command), or tell the user the address.
+2. If \`messages\` is above 0, call \`read_chat\` and pick up where the chat left off.
+3. Serve the chat until the user says stop: answer every chat event with the \`chat\` tool, as the edrys server's instructions say.
+
+The user may not be a programmer. Answer in plain words, show no YAML or code in the chat unless they ask, and offer choices as chat forms (buttons).
+
+If the edrys-lab and edrys-module skills are installed, use them to write the lab and its modules.
+`;
+const FILES = [
+    ['lab.yml', starterLab],
+    ['.mcp.json', () => JSON.stringify({ mcpServers: { edrys: SERVER } }, null, 2) + '\n'],
+    ['.vscode/mcp.json', () => JSON.stringify({ servers: { edrys: { type: 'stdio', ...SERVER } } }, null, 2) + '\n'],
+    ['AGENTS.md', agents],
+    // Claude Code reads CLAUDE.md, which imports AGENTS.md
+    ['CLAUDE.md', () => '@AGENTS.md\n'],
+    // no prompts for the edrys server and for edits of the lab and its modules
+    ['.claude/settings.json', () => JSON.stringify(SETTINGS, null, 2) + '\n'],
+];
+// The edrys skills, for every lab of this user: in ~/.agents/skills, which
+// Copilot reads, linked into ~/.claude/skills. In the lab folder they would be
+// published with it.
+const SKILLS = ['-y', 'skills', 'add', 'edrys-labs/skills', '-g', '--skill', '*', '--agent', 'claude-code', 'github-copilot', '-y'];
+const SKILLS_HINT = 'npx skills add edrys-labs/skills';
+function skillsInstalled() {
+    return ['.claude', '.agents'].some((dir) => ['edrys-lab', 'edrys-module'].every((name) => fs.existsSync(path.join(os.homedir(), dir, 'skills', name))));
+}
+async function ask(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await rl.question(question)).trim();
+    rl.close();
+    return answer;
+}
+export async function init(folder, say = console.log) {
+    const dir = path.resolve(folder);
+    fs.mkdirSync(dir, { recursive: true });
+    let name = path.basename(dir);
+    if (process.stdin.isTTY && !fs.existsSync(path.join(dir, 'lab.yml'))) {
+        name = (await ask(`Name of your lab (${name}): `)) || name;
+    }
+    for (const [file, content] of FILES) {
+        const target = path.join(dir, file);
+        if (fs.existsSync(target)) {
+            say(`  kept     ${file} (already there)`);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, content(name));
+        say(`  created  ${file}`);
+    }
+    const ignore = path.join(dir, '.gitignore');
+    const lines = fs.existsSync(ignore) ? fs.readFileSync(ignore, 'utf8') : null;
+    if (lines === null) {
+        fs.writeFileSync(ignore, '.edrys-dev/\n');
+        say('  created  .gitignore');
+    }
+    else if (!lines.split(/\r?\n/).some((line) => ['.edrys-dev', '.edrys-dev/', '/.edrys-dev/'].includes(line.trim()))) {
+        fs.appendFileSync(ignore, (lines === '' || lines.endsWith('\n') ? '' : '\n') + '.edrys-dev/\n');
+        say('  added    .edrys-dev/ to .gitignore');
+    }
+    if (!skillsInstalled()) {
+        const yes = process.stdin.isTTY &&
+            /^(y|yes|)$/i.test(await ask('\nInstall the edrys skills, so your agent knows how labs and modules are written? (Y/n) '));
+        // npx is npx.cmd on Windows, which needs a shell
+        const run = yes && spawnSync('npx', SKILLS, { stdio: 'inherit', shell: process.platform === 'win32' });
+        if (run && run.status === 0)
+            say('  installed the edrys skills');
+        else
+            say(`\n${run ? 'Could not install the edrys skills. ' : ''}To install them later: ${SKILLS_HINT}`);
+    }
+    say(`
+Your lab is ready in ${dir}
+
+Next: open this folder in your AI agent (Claude Code, or VS Code with Copilot)
+and write "start". The agent starts edrys-dev and opens the class in your
+browser; from then on you can talk to it in the 🤖 chat there.`);
+}

package/dist/server.js

@@ -9,7 +9,7 @@ import { unpack } from 'msgpackr';
 import { readSaved, watchFile, watchModules } from './watch.js';
 import { moduleApp } from './modules.js';
 import { hostGuard, hostNames, sameOrigin } from './origin.js';
-import { Chat, panelFiles, panelScript } from './chat.js';
+import { Chat, explain, panelFiles, panelScript } from './chat.js';
 // entries the log keeps, oldest first out
 const LOG_MAX = 300;
 // a body in the log is cut to this many characters of JSON
@@ -128,6 +128,11 @@ export async function startDevServer(options) {
             const { type, ...state } = report;
             classState = state;
         }
+        // the user may not see the terminal or the agent: the chat panel says it too
+        if (report.type === 'error')
+            chat.labProblem(explain(String(report.message)));
+        if (report.type === 'applied')
+            chat.labProblem(null);
         if (report.type === 'messages' && Array.isArray(report.messages)) {
             for (const m of report.messages)
                 addLog({ ...m, body: readableBody(m.body), kind: 'message' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edryslabs/edrys-dev",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Develop edrys-Lite labs locally: serves edrys-Lite, syncs on its own port and republishes the class whenever the lab file changes",
   "type": "module",
   "bin": {

package/views/panel.js

@@ -75,6 +75,11 @@
       border: 1px solid var(--accent); background: transparent; color: var(--accent);
     }
     .msg form[aria-disabled="true"] { opacity: .5; pointer-events: none; }
+    .problem { margin: 0 12px 8px; padding: 8px 10px; border-radius: 8px; font-size: 13px; line-height: 1.4;
+      border: 1px solid #e0452b; background: rgba(224,69,43,.1); }
+    .problem[hidden] { display: none; }
+    .problem summary { cursor: pointer; color: var(--muted); font-size: 12px; margin-top: 4px; }
+    .problem pre { margin: 4px 0 0; white-space: pre-wrap; overflow-wrap: anywhere; font: 12px ui-monospace, monospace; }
     .status { padding: 0 12px 6px; font-size: 12px; color: var(--muted); min-height: 1em; }
     .hint { padding: 0 12px 6px; font-size: 12px; color: var(--muted); font-style: italic; }
     .hint:empty { display: none; }
@@ -107,6 +112,7 @@
           <small title="edrys-dev: not the class's chat">only you see this</small>
         </header>
         <div class="log" role="log" aria-live="polite"></div>
+        <div class="problem" role="alert" hidden></div>
         <div class="status" aria-live="polite"></div>
         <div class="hint" aria-live="polite"></div>
         <form class="compose">
@@ -123,6 +129,7 @@
   const log = root.querySelector('.log')
   const statusLine = root.querySelector('.status')
   const hintLine = root.querySelector('.hint')
+  const problemBox = root.querySelector('.problem')
   const compose = root.querySelector('.compose')
   const textarea = root.querySelector('textarea')
   const menu = root.querySelector('#sessions')
@@ -287,6 +294,22 @@
     })
   }
 
+  // the lab file does not load: until it does, in plain words, edrys-Lite's message folded
+  function showProblem(problem) {
+    problemBox.hidden = !problem
+    if (!problem) return problemBox.replaceChildren()
+    const text = document.createElement('div')
+    text.textContent = problem.text
+    const details = document.createElement('details')
+    const summary = document.createElement('summary')
+    summary.textContent = 'Details'
+    const pre = document.createElement('pre')
+    pre.textContent = problem.detail
+    details.append(summary, pre)
+    problemBox.replaceChildren(text, details)
+    if (!panel.classList.contains('open')) toggle.classList.add('unread')
+  }
+
   function show(entry) {
     const div = document.createElement('div')
     div.className = 'msg ' + entry.type
@@ -325,6 +348,10 @@
           statusLine.textContent = message.status
           hintLine.textContent = message.hint || ''
           toggle.classList.remove('unread')
+          showProblem(message.lab)
+          break
+        case 'lab':
+          showProblem(message.problem)
           break
         case 'entry':
           if (message.entry.type === 'ai' && message.entry.ask) open = message.entry.ask