@edryslabs/edrys-dev 0.1.2 → 0.3.0

package/dist/chat.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import fsp from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { EventEmitter } from 'node:events';
@@ -6,59 +7,307 @@ 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
+// what a saved chat keeps, oldest first out
 const MAX_ENTRIES = 500;
+// ids become file names
+const ID = /^[\w-]{1,64}$/;
+// what a panel gets on (re)load, in characters of JSON: 500 long messages
+// could be 25 MB; read_chat has the rest
+const HISTORY_MAX = 1_000_000;
+// a burst of messages is saved once
+const SAVE_MS = 300;
+// The progress line says what the server knows: the message waits until an
+// agent takes it (Chat.activity()), and after a while without any sign of the
+// agent a hint below says so. As in LiaScript DevServer (src/lib.ts there).
+export const WAITING = 'Waiting for the agent…';
+export const THINKING = 'Thinking…';
+// the server cannot know whether an idle agent listens (a channel wakes it)
+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
+ * empty is '' or missing.
+ */
+export function validAnswer(inputs, values) {
+    if (!values || typeof values !== 'object' || Array.isArray(values))
+        return null;
+    for (const [id, value] of Object.entries(values)) {
+        const input = inputs.find((i) => i.id === id);
+        if (!input)
+            return null;
+        if (input.type === 'checkbox') {
+            if (!Array.isArray(value) || new Set(value).size !== value.length)
+                return null;
+            if (!value.every((v) => input.options.includes(v)))
+                return null;
+        }
+        else if (value !== '' && !input.options.includes(value))
+            return null;
+    }
+    return values;
+}
+// UTC time and a random part: sorted by time, and no clash between two runs
+function newId(t = Date.now()) {
+    return new Date(t).toISOString().slice(0, 19).replace(/:/g, '-') + '-' + crypto.randomBytes(2).toString('hex');
+}
+/**
+ * The entries of a saved list, numbered upwards also if an older edrys-dev
+ * saved them without numbers; [] for a file edited by hand or of another tool.
+ */
+function readEntries(list) {
+    if (!Array.isArray(list))
+        return [];
+    const entries = list.filter((e) => e && typeof e === 'object' && typeof e.type === 'string').slice(-MAX_ENTRIES);
+    let next = 1;
+    for (const entry of entries) {
+        if (!Number.isInteger(entry.n) || entry.n < next)
+            entry.n = next;
+        next = entry.n + 1;
+    }
+    return entries;
+}
+/** The first message of the user, else the first line of the agent, else the date. */
+export function title(session) {
+    const user = session.entries.find((e) => e.type === 'user');
+    const ai = session.entries.find((e) => e.type === 'ai');
+    let text = user?.type === 'user' ? user.text : '';
+    if (!text && ai?.type === 'ai') {
+        text = ai.markdown.split('\n').map((line) => line.replace(/[#*_`>]/g, '').trim()).find(Boolean) ?? '';
+    }
+    text = text.replace(/\s+/g, ' ').trim();
+    if (!text)
+        return new Date(session.created).toISOString().slice(0, 16).replace('T', ' ');
+    return text.length > 60 ? text.slice(0, 59) + '…' : text;
+}
+function summary(session) {
+    return {
+        id: session.id,
+        title: title(session),
+        updated: session.entries.at(-1)?.t ?? session.created,
+        count: session.entries.length,
+    };
+}
 /**
- * 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.
+ * The agent chat over the class tab: its chats, saved next to the lab in
+ * .edrys-dev/chats/<id>.json, and the panel's endpoints. Not the class's own
+ * (signed) chat: only the author and the agent see it. It continues the chat
+ * that changed last; a new one gets its file with its first entry.
  *
  * Emits `user` (entry) when the user typed, `answer` (entry) when they
- * answered a form, and `connection` (boolean) when the panel came or went.
+ * answered a form, `session` ({id, title, resumed}) when they opened another
+ * chat, and `connection` (boolean) when the panel came, or was gone for
+ * `settleMs`: a reload of the class tab is no going.
  */
 export class Chat extends EventEmitter {
-    file;
-    entries = [];
+    settleMs;
+    hintMs;
+    /** The chat the panel shows. */
+    session;
     /** The one form the user can still answer. Forms of earlier runs are closed. */
     open = null;
+    /** The inputs of the open form. */
+    form = [];
     status = '';
+    hint = '';
+    lab = null;
+    // a message of the user waits for the first sign of an agent
+    pending = false;
+    quiet;
+    next = 1;
     panels = new Set();
-    constructor(file) {
+    reported = false;
+    settling;
+    saveTimer;
+    // chats with entries not saved yet
+    dirty = new Set();
+    // one write after the other, never two at once into the same file
+    saving = Promise.resolve();
+    dir;
+    // the saved chats, for the menu
+    summaries = new Map();
+    // the chats read in this run: a file may still lag behind them
+    loaded = new Map();
+    /** `folder` is .edrys-dev next to the lab. */
+    constructor(folder, settleMs = 0, hintMs = HINT_MS) {
         super();
-        this.file = file;
+        this.settleMs = settleMs;
+        this.hintMs = hintMs;
+        this.dir = path.join(folder, 'chats');
+        this.migrate(path.join(folder, 'chat.json'));
+        let names = [];
+        try {
+            names = fs.readdirSync(this.dir);
+        }
+        catch { }
+        for (const name of names) {
+            const session = name.endsWith('.json') && this.load(name.slice(0, -5));
+            if (session)
+                this.summaries.set(session.id, summary(session));
+        }
+        const latest = this.list()[0];
+        this.session = (latest && this.load(latest.id)) || { id: newId(), created: Date.now(), entries: [] };
+        this.next = (this.session.entries.at(-1)?.n ?? 0) + 1;
+    }
+    /** The entries of the chat the panel shows. */
+    get entries() {
+        return this.session.entries;
+    }
+    /** The saved chats, the one changed last first. */
+    list() {
+        return [...this.summaries.values()].sort((a, b) => b.updated - a.updated);
+    }
+    /** The chat `id`, the current one without; undefined if there is none. */
+    read(id) {
+        return id === undefined || id === this.session.id ? this.session : this.load(id);
+    }
+    /**
+     * Shows the saved chat `id`, or with null a new one (unless the current one
+     * is new still). False if there is no such chat.
+     */
+    switchTo(id) {
+        let next;
+        if (id === null) {
+            if (!this.session.entries.length)
+                return true;
+            next = { id: newId(), created: Date.now(), entries: [] };
+        }
+        else {
+            if (id === this.session.id)
+                return true;
+            next = this.summaries.has(id) ? this.load(id) : undefined;
+            if (!next)
+                return false;
+        }
+        // the forms and the progress line belong to the chat before
+        this.open = null;
+        this.form = [];
+        this.pending = false;
+        this.status = this.hint = '';
+        clearTimeout(this.quiet);
+        this.session = next;
+        this.next = (next.entries.at(-1)?.n ?? 0) + 1;
+        const history = `data: ${JSON.stringify(this.history())}\n\n`;
+        for (const panel of this.panels)
+            panel.write(history);
+        this.emit('session', { id: next.id, title: title(next), resumed: next.entries.length > 0 });
+        return true;
+    }
+    // the chat.json of an older edrys-dev becomes the first saved chat
+    migrate(file) {
         try {
-            this.entries = JSON.parse(fs.readFileSync(file, 'utf8'));
+            const entries = readEntries(JSON.parse(fs.readFileSync(file, 'utf8')));
+            if (!entries.length)
+                return;
+            const session = { id: newId(entries[0].t), created: entries[0].t, entries };
+            fs.mkdirSync(this.dir, { recursive: true });
+            fs.writeFileSync(path.join(this.dir, session.id + '.json'), JSON.stringify(session));
+            fs.rmSync(file);
         }
         catch { }
     }
+    load(id) {
+        if (!ID.test(id))
+            return undefined;
+        const known = this.loaded.get(id);
+        if (known)
+            return known;
+        try {
+            const saved = JSON.parse(fs.readFileSync(path.join(this.dir, id + '.json'), 'utf8'));
+            if (saved?.id !== id || !Array.isArray(saved.entries))
+                return undefined;
+            const entries = readEntries(saved.entries);
+            const created = Number.isFinite(saved.created) ? saved.created : entries[0]?.t ?? 0;
+            const session = { id, created, entries };
+            this.loaded.set(id, session);
+            return session;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Whether a panel is open, or was until less than `settleMs` ago; what it missed comes with the history. */
     get connected() {
-        return this.panels.size > 0;
+        return this.reported;
     }
     /** 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 } : {}) };
+        const entry = { t: Date.now(), n: this.next++, type: 'ai', markdown, ...(ask ? { ask, inputs } : {}) };
         // only the newest form stays open
         if (ask) {
             this.closeForm();
             this.open = ask;
+            this.form = inputs;
         }
         this.add(entry);
         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 });
+        this.watchQuiet();
+    }
+    /**
+     * A sign of the agent: a tool call, or an event handed to it. A message
+     * that waited for it is now being worked on.
+     */
+    activity() {
+        this.pending = false;
+        if (this.status === WAITING)
+            this.setStatus(THINKING);
+        else
+            this.watchQuiet();
+    }
+    /** The entries of the user (typed or answered) after entry `n`. */
+    newerThan(n) {
+        return this.entries.filter((e) => e.n > n && e.type !== 'ai');
     }
     /** Withdraws the open form; returns its id, or null if there was none. */
-    closeForm() {
+    closeForm(reason) {
         const closed = this.open;
         this.open = null;
         if (closed)
-            this.send({ type: 'close', ask: closed });
+            this.send({ type: 'close', ask: closed, ...(reason ? { reason } : {}) });
         return closed;
     }
+    // restarts the clock whenever something happens while a progress line shows
+    watchQuiet() {
+        clearTimeout(this.quiet);
+        if (this.hint)
+            this.send({ type: 'hint', text: (this.hint = '') });
+        if (!this.status)
+            return;
+        this.quiet = setTimeout(() => this.send({ type: 'hint', text: (this.hint = this.pending ? NO_REACTION : QUIET) }), this.pending ? this.hintMs.noReaction : this.hintMs.quiet);
+        // a pending hint must not keep a stopped edrys-dev alive
+        this.quiet.unref();
+    }
+    // the user sees at once that the message arrived, until the agent takes it
+    waitForAgent() {
+        this.pending = true;
+        this.setStatus(WAITING);
+    }
     routes(app) {
         app.get('/edrys-dev/chat/events', (req, res) => {
             res.writeHead(200, {
@@ -66,31 +315,50 @@ export class Chat extends EventEmitter {
                 '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`);
+            // a reload shows the chat again, with the open form and status
+            res.write(`data: ${JSON.stringify(this.history())}\n\n`);
             this.panels.add(res);
-            if (this.panels.size === 1)
-                this.emit('connection', true);
+            clearTimeout(this.settling);
+            if (!this.reported)
+                this.emit('connection', (this.reported = true));
             req.on('close', () => {
                 this.panels.delete(res);
-                if (this.panels.size === 0)
-                    this.emit('connection', false);
+                if (this.panels.size)
+                    return;
+                clearTimeout(this.settling);
+                this.settling = setTimeout(() => {
+                    if (!this.panels.size && this.reported)
+                        this.emit('connection', (this.reported = false));
+                }, this.settleMs);
             });
         });
         app.post('/edrys-dev/chat', express.json(), (req, res) => {
             if (!sameOrigin(req))
                 return res.sendStatus(403);
             const { text, ask, values } = req.body ?? {};
+            // the menu: another saved chat, or null for a new one
+            if (req.body && Object.hasOwn(req.body, 'session')) {
+                const { session } = req.body;
+                if (session !== null && typeof session !== 'string')
+                    return res.sendStatus(400);
+                return res.sendStatus(this.switchTo(session) ? 204 : 404);
+            }
             if (typeof text === 'string' && text.trim()) {
-                const entry = { t: Date.now(), type: 'user', text: text.slice(0, 10000) };
+                const entry = { t: Date.now(), n: this.next++, type: 'user', text: text.slice(0, 10000) };
                 this.add(entry);
+                this.waitForAgent();
                 this.emit('user', entry);
                 return res.sendStatus(204);
             }
-            if (typeof ask === 'string' && ask === this.open && values && typeof values === 'object') {
+            if (typeof ask === 'string' && ask === this.open) {
+                // the agent gets what its form offered, or nothing
+                const answer = validAnswer(this.form, values);
+                if (!answer)
+                    return res.sendStatus(400);
                 this.open = null;
-                const entry = { t: Date.now(), type: 'answer', ask, values };
+                const entry = { t: Date.now(), n: this.next++, type: 'answer', ask, values: answer };
                 this.add(entry);
+                this.waitForAgent();
                 this.emit('answer', entry);
                 return res.sendStatus(204);
             }
@@ -99,20 +367,77 @@ export class Chat extends EventEmitter {
         });
     }
     add(entry) {
-        this.entries.push(entry);
-        if (this.entries.length > MAX_ENTRIES)
-            this.entries.splice(0, this.entries.length - MAX_ENTRIES);
+        const session = this.session;
+        session.entries.push(entry);
+        if (session.entries.length > MAX_ENTRIES)
+            session.entries.splice(0, session.entries.length - MAX_ENTRIES);
+        this.loaded.set(session.id, session);
         this.send({ type: 'entry', entry });
+        // the menu changes with a new chat's first entry, or its first message of the user
+        const before = this.summaries.get(session.id)?.title;
+        this.summaries.set(session.id, summary(session));
+        if (this.summaries.get(session.id).title !== before)
+            this.send({ type: 'sessions', sessions: this.list() });
         this.save();
     }
+    // what a panel gets first, and after a switch
+    history() {
+        const entries = this.recent();
+        return {
+            type: 'history',
+            session: { id: this.session.id, title: title(this.session) },
+            sessions: this.list(),
+            entries,
+            skipped: this.entries.length - entries.length,
+            open: this.open,
+            status: this.status,
+            hint: this.hint,
+            lab: this.lab,
+        };
+    }
     send(message) {
         for (const panel of this.panels)
             panel.write(`data: ${JSON.stringify(message)}\n\n`);
     }
+    /** The newest entries that fit into HISTORY_MAX, at least the last one. */
+    recent() {
+        let start = this.entries.length;
+        let size = 0;
+        while (start > 0) {
+            size += JSON.stringify(this.entries[start - 1]).length;
+            if (size > HISTORY_MAX && start < this.entries.length)
+                break;
+            start--;
+        }
+        return this.entries.slice(start);
+    }
     save() {
+        this.dirty.add(this.session);
+        this.saveTimer ??= setTimeout(() => this.writeDirty(), SAVE_MS);
+    }
+    writeDirty() {
+        clearTimeout(this.saveTimer);
+        this.saveTimer = undefined;
+        const sessions = [...this.dirty];
+        this.dirty.clear();
+        this.saving = this.saving.then(async () => {
+            for (const session of sessions)
+                await this.write(session);
+        });
+    }
+    /** Writes what is not saved yet, e.g. before edrys-dev exits. */
+    async flush() {
+        if (this.saveTimer)
+            this.writeDirty();
+        await this.saving;
+    }
+    // a copy renamed over the file: a crash midway leaves the old chat, not half a one
+    async write(session) {
+        const file = path.join(this.dir, session.id + '.json');
         try {
-            fs.mkdirSync(path.dirname(this.file), { recursive: true });
-            fs.writeFileSync(this.file, JSON.stringify(this.entries));
+            await fsp.mkdir(this.dir, { recursive: true });
+            await fsp.writeFile(file + '.tmp', JSON.stringify(session));
+            await fsp.rename(file + '.tmp', file);
         }
         catch (error) {
             console.error('edrys-dev: could not save the chat:', error.message);

package/dist/index.js

@@ -5,13 +5,18 @@ import { parseArgs } from 'node:util';
 import open from 'open';
 import { startDevServer } from './server.js';
 import { startMcp } from './mcp.js';
+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)
-      --host <host>   address to listen on, default 127.0.0.1
+      --host <host>   address to listen on, default 127.0.0.1; another one
+                      (e.g. 0.0.0.0) lets others on the network in, with
+                      --mcp also into the agent chat
       --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
@@ -43,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);
@@ -62,6 +78,14 @@ const server = await startDevServer({
     modules,
     agent: values.mcp,
 });
+// Ctrl+C, or a process manager or agent client stopping it; the chat is saved
+// first. Before anything is printed: whoever waits for that may stop it at once.
+for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.once(signal, async () => {
+        await server.close();
+        process.exit(0);
+    });
+}
 server.bus.on('report', (report) => {
     switch (report.type) {
         case 'open':
@@ -77,11 +101,11 @@ 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 (reachable(values.host)) {
+    console.error(`edrys-dev: listening on ${values.host}, not only on this machine: others on the network can open the class` +
+        (values.mcp ? ' and type to the agent in its chat' : ''));
+}
 if (values.mcp)
     startMcp(server, { lab, url });
 if (values.open)
     await open(url);
-process.on('SIGINT', async () => {
-    await server.close();
-    process.exit(0);
-});

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.`);
+}