@agent-workshop/adoc-core 0.1.0

package/dist/skills.d.ts

@@ -0,0 +1,46 @@
+import { type SkillSource } from './plugins.js';
+import type { CheckEntry, Workspace } from './workspace.js';
+/** One _Agent_Skill_ of the workspace; `pluginKey` for a _Plugin_Skill_. */
+export interface SkillEntry extends SkillSource {
+    readonly pluginKey?: string;
+}
+/** Every _Agent_Skill_: the core package and the kit in user scope, then each loaded plugin's skill in its scope. */
+export declare function listSkills(workspace: Workspace): Promise<SkillEntry[]>;
+/** The `SKILL.md` of a skill, selected by its name as `adoc skill list` shows it, without its front matter. */
+export declare function viewSkill(workspace: Workspace, name: string): Promise<{
+    entry: SkillEntry;
+    body: string;
+}>;
+export interface SkillInstallOptions {
+    /** Agent names passed on to `skills --agent`, such as `claude-code` or `codex`; the skills CLI picks them when empty. */
+    agents?: string[];
+    env?: NodeJS.ProcessEnv;
+}
+/** _Skill_Install_Command_ `install` / `update`: `skills add <folder>` for each skill, `-g` for user scope. */
+export declare function installSkills(workspace: Workspace, options?: SkillInstallOptions): Promise<SkillEntry[]>;
+/** _Skill_Install_Command_ `uninstall`: `skills remove` for the skills of each scope. */
+export declare function uninstallSkills(workspace: Workspace, options?: SkillInstallOptions): Promise<SkillEntry[]>;
+/**
+ * _Skill_Check_: each skill must be installed in `.agents/skills` or `.claude/skills` of the workspace or of the user's
+ * home, with the same `SKILL.md` as its source.
+ */
+export declare function checkSkills(workspace: Workspace, home?: string): Promise<CheckEntry[]>;
+/** The `SKILL.md` of a skill with its version, for the _File_Editor_. */
+export declare function readSkillFile(workspace: Workspace, name: string): Promise<{
+    name: string;
+    file: string;
+    version: string;
+    text: string;
+}>;
+/**
+ * Writes a `SKILL.md` that the user edited in the _File_Editor_, when `version` is still current; answers with the
+ * new version and the unified diff from `since` (the text the unsent edits started from) to the new text.
+ */
+export declare function editSkillFile(workspace: Workspace, name: string, version: string, text: string, since?: string): Promise<{
+    status: 'applied';
+    version: string;
+    diff: string;
+} | {
+    status: 'refused';
+    reason: string;
+}>;

package/dist/skills.js

@@ -0,0 +1,131 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { unifiedDiff } from '@agent-workshop/adoc-plugin-kit';
+import { AdocError } from './errors.js';
+import { readSkillSource } from './plugins.js';
+/** The folders of the core package and the _Plugin_Kit_, which own the skills `adoc` and `adoc-plugin-authoring`. */
+const OWNERS = [dirname(dirname(fileURLToPath(import.meta.url))), dirname(dirname(createRequire(import.meta.url).resolve('@agent-workshop/adoc-plugin-kit/skill/SKILL.md')))];
+/** Every _Agent_Skill_: the core package and the kit in user scope, then each loaded plugin's skill in its scope. */
+export async function listSkills(workspace) {
+    const entries = [];
+    for (const owner of OWNERS)
+        entries.push(await readSkillSource(owner, 'user'));
+    for (const plugin of workspace.loadedPlugins())
+        if (plugin.skill)
+            entries.push({ ...plugin.skill, pluginKey: plugin.key });
+    return entries;
+}
+/** The `SKILL.md` of a skill, selected by its name as `adoc skill list` shows it, without its front matter. */
+export async function viewSkill(workspace, name) {
+    const entries = await listSkills(workspace);
+    const entry = entries.find((e) => e.name === name);
+    if (!entry)
+        throw new AdocError('skill.missing', `No skill ${name}. Known: ${entries.map((e) => e.name).join(', ')}.`);
+    const text = await readFile(join(entry.directory, 'SKILL.md'), 'utf8');
+    return { entry, body: text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n+/, '') };
+}
+/** How to run the Vercel `skills` CLI: `ADOC_SKILLS_CLI`, by default `npx -y skills@1`. */
+function skillsCommand(env) {
+    return (env.ADOC_SKILLS_CLI || 'npx -y skills@1').split(/\s+/).filter(Boolean);
+}
+function runSkills(args, cwd, env) {
+    const [command, ...prefix] = skillsCommand(env);
+    return new Promise((done, fail) => {
+        const child = spawn(command, [...prefix, ...args], { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+        let output = '';
+        child.stdout.on('data', (chunk) => (output += chunk.toString('utf8')));
+        child.stderr.on('data', (chunk) => (output += chunk.toString('utf8')));
+        child.on('error', (error) => fail(new AdocError('skill.install', `cannot run ${command}: ${error.message}`)));
+        child.on('exit', (code) => (code === 0 ? done(output) : fail(new AdocError('skill.install', `${[command, ...prefix, ...args].join(' ')} failed (exit ${code}):\n${output.trim()}`))));
+    });
+}
+/** _Skill_Install_Command_ `install` / `update`: `skills add <folder>` for each skill, `-g` for user scope. */
+export async function installSkills(workspace, options = {}) {
+    const env = options.env ?? process.env;
+    const entries = await listSkills(workspace);
+    const agents = options.agents?.length ? ['--agent', ...options.agents] : [];
+    for (const entry of entries)
+        await runSkills(['add', entry.directory, '--yes', ...(entry.scope === 'user' ? ['--global'] : []), ...agents], workspace.root, env);
+    return entries;
+}
+/** _Skill_Install_Command_ `uninstall`: `skills remove` for the skills of each scope. */
+export async function uninstallSkills(workspace, options = {}) {
+    const env = options.env ?? process.env;
+    const entries = await listSkills(workspace);
+    const agents = options.agents?.length ? ['--agent', ...options.agents] : [];
+    for (const scope of ['project', 'user']) {
+        const names = entries.filter((e) => e.scope === scope).map((e) => e.name);
+        if (names.length)
+            await runSkills(['remove', ...names, '--yes', ...(scope === 'user' ? ['--global'] : []), ...agents], workspace.root, env);
+    }
+    return entries;
+}
+async function readIfThere(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * _Skill_Check_: each skill must be installed in `.agents/skills` or `.claude/skills` of the workspace or of the user's
+ * home, with the same `SKILL.md` as its source.
+ */
+export async function checkSkills(workspace, home = homedir()) {
+    const found = [];
+    for (const entry of await listSkills(workspace)) {
+        const source = await readFile(join(entry.directory, 'SKILL.md'), 'utf8');
+        const installed = [];
+        for (const base of [workspace.root, home]) {
+            for (const place of ['.agents/skills', '.claude/skills']) {
+                const text = await readIfThere(join(base, place, entry.name, 'SKILL.md'));
+                if (text !== undefined)
+                    installed.push(text);
+            }
+        }
+        if (!installed.length)
+            found.push({ level: 'warning', kind: 'skill-missing', message: `The agent skill ${entry.name} is not installed; run adoc skill install.` });
+        else if (!installed.includes(source))
+            found.push({ level: 'warning', kind: 'skill-outdated', message: `The installed agent skill ${entry.name} differs from this adoc; run adoc skill update.` });
+    }
+    return found;
+}
+/** The version of a skill file: a hash of its text, as for documents. */
+function skillVersion(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+/** The path of a skill file as people read it: relative to the workspace when inside it, otherwise from the home. */
+function shownPath(workspace, path) {
+    const rel = relative(workspace.root, path);
+    if (!rel.startsWith('..') && !isAbsolute(rel))
+        return rel;
+    const home = homedir();
+    return path.startsWith(`${home}/`) ? `~/${path.slice(home.length + 1)}` : path;
+}
+/** The `SKILL.md` of a skill with its version, for the _File_Editor_. */
+export async function readSkillFile(workspace, name) {
+    const entry = (await listSkills(workspace)).find((e) => e.name === name);
+    if (!entry)
+        throw new AdocError('skill.missing', `No skill ${name}.`);
+    const text = await readFile(join(entry.directory, 'SKILL.md'), 'utf8');
+    return { name, file: shownPath(workspace, join(entry.directory, 'SKILL.md')), version: skillVersion(text), text };
+}
+/**
+ * Writes a `SKILL.md` that the user edited in the _File_Editor_, when `version` is still current; answers with the
+ * new version and the unified diff from `since` (the text the unsent edits started from) to the new text.
+ */
+export async function editSkillFile(workspace, name, version, text, since) {
+    const current = await readSkillFile(workspace, name);
+    if (current.version !== version)
+        return { status: 'refused', reason: `${current.file} changed while you were editing; your text is kept, copy it and edit again.` };
+    const entry = (await listSkills(workspace)).find((e) => e.name === name);
+    await writeFile(join(entry.directory, 'SKILL.md'), text);
+    return { status: 'applied', version: skillVersion(text), diff: unifiedDiff(since ?? current.text, text, current.file) };
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/dist/terminal.d.ts

@@ -0,0 +1,28 @@
+import type { WebSocket } from 'ws';
+import type { AgentClaim } from './claim.js';
+type Mode = 'observe' | 'control';
+/**
+ * _Agent_Terminal_Stream_: relays the claimed pane's terminal between herdr and browser sockets.
+ * One socket at a time controls the terminal (`herdr terminal session control`); every other socket observes.
+ */
+export declare class TerminalRelay {
+    private readonly claim;
+    private readonly log;
+    private readonly streams;
+    constructor(claim: () => AgentClaim | undefined, log: (line: string) => void);
+    /** Starts or restarts the stream of a socket in the given mode and size; taking control downgrades the previous controller. */
+    open(ws: WebSocket, mode: Mode, cols: number, rows: number): void;
+    /** Sends keys or text typed in the controlling browser. */
+    input(ws: WebSocket, data: string): void;
+    resize(ws: WebSocket, cols: number, rows: number): void;
+    /** Scrolls the pane's view through its scrollback: positive lines scroll up (back in history), negative down. */
+    scroll(ws: WebSocket, lines: number): void;
+    /** Sends a mouse event at a 0-based cell; herdr passes it to the program when the program tracks the mouse. */
+    mouse(ws: WebSocket, action: 'down' | 'up' | 'drag' | 'move', button: 'left' | 'middle' | 'right', column: number, row: number): void;
+    /** Stops the stream of a socket; a controller releases the pane first so that it gets its own size back. */
+    stop(ws: WebSocket): void;
+    /** Ends every stream, for example when the claim changes; browsers reopen with the new pane. */
+    stopAll(reason: string): void;
+    private command;
+}
+export {};

package/dist/terminal.js

@@ -0,0 +1,110 @@
+import { spawn } from 'node:child_process';
+/**
+ * _Agent_Terminal_Stream_: relays the claimed pane's terminal between herdr and browser sockets.
+ * One socket at a time controls the terminal (`herdr terminal session control`); every other socket observes.
+ */
+export class TerminalRelay {
+    claim;
+    log;
+    streams = new Map();
+    constructor(claim, log) {
+        this.claim = claim;
+        this.log = log;
+    }
+    /** Starts or restarts the stream of a socket in the given mode and size; taking control downgrades the previous controller. */
+    open(ws, mode, cols, rows) {
+        const claim = this.claim();
+        if (!claim) {
+            send(ws, { type: 'terminal.closed', reason: 'no-claim' });
+            return;
+        }
+        if (mode === 'control') {
+            for (const [other, stream] of this.streams)
+                if (other !== ws && stream.mode === 'control')
+                    this.open(other, 'observe', stream.cols, stream.rows);
+        }
+        this.stop(ws);
+        const args = ['terminal', 'session', mode, claim.pane, '--cols', String(cols), '--rows', String(rows)];
+        const child = spawn('herdr', args, { env: { ...process.env, HERDR_SOCKET_PATH: claim.socket } });
+        const stream = { mode, child, cols, rows };
+        this.streams.set(ws, stream);
+        let buffer = '';
+        child.stdout.on('data', (chunk) => {
+            buffer += chunk.toString('utf8');
+            let end;
+            while ((end = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, end);
+                buffer = buffer.slice(end + 1);
+                try {
+                    const record = JSON.parse(line);
+                    if (record.type === 'terminal.frame' || record.type === 'terminal.closed')
+                        send(ws, record);
+                }
+                catch {
+                    // Ignore a malformed line.
+                }
+            }
+        });
+        child.stderr.on('data', (chunk) => this.log(`adoc: herdr terminal ${mode}: ${chunk.toString('utf8').trim()}`));
+        child.on('exit', () => {
+            if (this.streams.get(ws)?.child === child) {
+                this.streams.delete(ws);
+                send(ws, { type: 'terminal.closed', reason: 'stream-ended' });
+            }
+        });
+        send(ws, { type: 'terminal.mode', mode });
+    }
+    /** Sends keys or text typed in the controlling browser. */
+    input(ws, data) {
+        this.command(ws, { type: 'terminal.input', text: data });
+    }
+    resize(ws, cols, rows) {
+        const stream = this.streams.get(ws);
+        if (!stream)
+            return;
+        stream.cols = cols;
+        stream.rows = rows;
+        if (stream.mode === 'control')
+            this.command(ws, { type: 'terminal.resize', cols, rows });
+        else
+            this.open(ws, 'observe', cols, rows);
+    }
+    /** Scrolls the pane's view through its scrollback: positive lines scroll up (back in history), negative down. */
+    scroll(ws, lines) {
+        if (lines === 0)
+            return;
+        this.command(ws, { type: 'terminal.scroll', direction: lines > 0 ? 'up' : 'down', lines: Math.min(Math.abs(Math.round(lines)), 200) });
+    }
+    /** Sends a mouse event at a 0-based cell; herdr passes it to the program when the program tracks the mouse. */
+    mouse(ws, action, button, column, row) {
+        this.command(ws, { type: 'terminal.mouse', action, button, column: Math.max(0, Math.floor(column)), row: Math.max(0, Math.floor(row)) });
+    }
+    /** Stops the stream of a socket; a controller releases the pane first so that it gets its own size back. */
+    stop(ws) {
+        const stream = this.streams.get(ws);
+        if (!stream)
+            return;
+        this.streams.delete(ws);
+        if (stream.mode === 'control' && stream.child.stdin.writable)
+            stream.child.stdin.write(JSON.stringify({ type: 'terminal.release' }) + '\n');
+        stream.child.stdin.end();
+        setTimeout(() => stream.child.kill(), 500).unref();
+    }
+    /** Ends every stream, for example when the claim changes; browsers reopen with the new pane. */
+    stopAll(reason) {
+        for (const ws of [...this.streams.keys()]) {
+            this.stop(ws);
+            send(ws, { type: 'terminal.closed', reason });
+        }
+    }
+    command(ws, command) {
+        const stream = this.streams.get(ws);
+        if (stream?.mode === 'control' && stream.child.stdin.writable)
+            stream.child.stdin.write(JSON.stringify(command) + '\n');
+    }
+}
+function send(ws, message) {
+    if (ws.readyState === ws.OPEN)
+        ws.send(JSON.stringify(message));
+}
+//# sourceMappingURL=terminal.js.map

package/dist/terminal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.js","sourceRoot":"","sources":["../src/terminal.ts"],"names":[],"mappings":"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"}

package/dist/transports.d.ts

@@ -0,0 +1,21 @@
+import type { AgentClaim } from './claim.js';
+import type { TransportConfig } from './config.js';
+import { type MessageQueue, type UserMessage } from './messages.js';
+/**
+ * _User_Message_Transport_: how a held message reaches the _Assigned_Agent_.
+ * A push transport delivers each message as soon as it is created; the wait transport leaves
+ * messages held until `adoc message wait` takes them.
+ */
+export interface MessageTransport {
+    readonly kind: string;
+    /** Pushes one message; resolves when delivered, rejects when delivery failed. Absent for the wait transport. */
+    push?(message: UserMessage): Promise<void>;
+}
+/** The current _Agent_Claim_, read when a message is pushed. */
+export type ClaimSource = () => AgentClaim | undefined;
+export declare function createTransport(config: TransportConfig, claim?: ClaimSource): MessageTransport;
+/**
+ * Connects a push transport to the queue: every new message, and every message still held after a failure, is retried in order.
+ * Returns a function that retries the held messages, for example after a new _Agent_Claim_.
+ */
+export declare function attachTransport(queue: MessageQueue, transport: MessageTransport, log: (line: string) => void): () => void;

package/dist/transports.js

@@ -0,0 +1,69 @@
+import { herdrCall } from './herdr.js';
+import { errorMessage } from './errors.js';
+import { formatMessage } from './messages.js';
+export function createTransport(config, claim = () => undefined) {
+    switch (config.kind) {
+        case 'wait':
+            return { kind: 'wait' };
+        case 'herdr':
+            return {
+                kind: 'herdr',
+                push: async (message) => {
+                    const current = claim();
+                    if (!current)
+                        throw new Error('no agent has claimed this workspace; run adoc agent claim in the agent pane');
+                    const text = formatMessage(message);
+                    try {
+                        await herdrCall(current.socket, 'agent.prompt', { target: current.pane, text });
+                    }
+                    catch (error) {
+                        // herdr refuses agent.prompt until it has detected an agent in the pane; type the message instead.
+                        if (!/not found/.test(errorMessage(error)))
+                            throw error;
+                        await herdrCall(current.socket, 'pane.send_input', { pane_id: current.pane, text, keys: ['enter'] });
+                    }
+                },
+            };
+    }
+}
+/**
+ * Connects a push transport to the queue: every new message, and every message still held after a failure, is retried in order.
+ * Returns a function that retries the held messages, for example after a new _Agent_Claim_.
+ */
+export function attachTransport(queue, transport, log) {
+    const push = transport.push;
+    if (!push)
+        return () => undefined;
+    let busy = false;
+    let again = false;
+    const flush = async () => {
+        if (busy) {
+            again = true;
+            return;
+        }
+        busy = true;
+        try {
+            for (const message of queue.list()) {
+                try {
+                    await push(message);
+                    queue.markDelivered([message.number]);
+                }
+                catch (error) {
+                    log(`adoc: ${transport.kind} delivery of message ${message.number} failed: ${errorMessage(error)}`);
+                    again = false;
+                    return;
+                }
+            }
+        }
+        finally {
+            busy = false;
+        }
+        if (again) {
+            again = false;
+            await flush();
+        }
+    };
+    queue.on('added', () => void flush());
+    return () => void flush();
+}
+//# sourceMappingURL=transports.js.map

package/dist/transports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transports.js","sourceRoot":"","sources":["../src/transports.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAuC,MAAM,eAAe,CAAC;AAgBnF,MAAM,UAAU,eAAe,CAAC,MAAuB,EAAE,KAAK,GAAgB,GAAG,EAAE,CAAC,SAAS;IAC3F,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,MAAM;YACT,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAC1B,KAAK,OAAO;YACV,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;oBACtB,MAAM,OAAO,GAAG,KAAK,EAAE,CAAC;oBACxB,IAAI,CAAC,OAAO;wBAAE,MAAM,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAC;oBAC7G,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;oBACpC,IAAI,CAAC;wBACH,MAAM,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;oBAClF,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,mGAAmG;wBACnG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;4BAAE,MAAM,KAAK,CAAC;wBACxD,MAAM,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;oBACvG,CAAC;gBACH,CAAC;aACF,CAAC;IACN,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAmB,EAAE,SAA2B,EAAE,GAA2B;IAC3G,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;IAC5B,IAAI,CAAC,IAAI;QAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;IAClC,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,MAAM,KAAK,GAAG,KAAK,IAAmB,EAAE;QACtC,IAAI,IAAI,EAAE,CAAC;YACT,KAAK,GAAG,IAAI,CAAC;YACb,OAAO;QACT,CAAC;QACD,IAAI,GAAG,IAAI,CAAC;QACZ,IAAI,CAAC;YACH,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;gBACnC,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;oBACpB,KAAK,CAAC,aAAa,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;gBACxC,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,GAAG,CAAC,SAAS,SAAS,CAAC,IAAI,wBAAwB,OAAO,CAAC,MAAM,YAAY,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;oBACpG,KAAK,GAAG,KAAK,CAAC;oBACd,OAAO;gBACT,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,GAAG,KAAK,CAAC;QACf,CAAC;QACD,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,GAAG,KAAK,CAAC;YACd,MAAM,KAAK,EAAE,CAAC;QAChB,CAAC;IACH,CAAC,CAAC;IACF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;IACtC,OAAO,GAAG,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC;AAC5B,CAAC"}

package/dist/workspace.d.ts

@@ -0,0 +1,182 @@
+import { type ActionEvent, type DocumentSummary } from '@agent-workshop/adoc-plugin-kit';
+import { type AdocConfig } from './config.js';
+import type { AdocHome } from './home.js';
+import { type LoadedPlugin, type Scope } from './plugins.js';
+import { type DocumentRecord, type ScanProblem } from './scan.js';
+import type { ActionMessageInput } from './messages.js';
+/** One entry of a _Document_Summary_List_: the summary, or the key with the parse error, and the last update of the document. */
+export interface SummaryEntry {
+    key: string;
+    path: string;
+    updatedAt: string;
+    archived: boolean;
+    summary?: DocumentSummary;
+    error?: string;
+}
+/** Everything the _Document_Detail_View_ needs for one document. */
+export interface DocumentView {
+    key: string;
+    pluginKey: string;
+    path: string;
+    file: string;
+    version: string;
+    archived: boolean;
+    summary?: DocumentSummary;
+    summaryError?: string;
+    html?: string;
+    renderError?: string;
+}
+/** The changes of a document since a base version, from the _Document_Version_Store_. */
+export interface DocumentChanges {
+    base: string;
+    available: boolean;
+    html?: string;
+    error?: string;
+}
+/** One version held by the _Document_Version_Store_. */
+export interface StoredVersion {
+    version: string;
+    seenAt: string;
+    current: boolean;
+}
+/** One entry of the report of _Adoc_Check_Command_. */
+export interface CheckEntry {
+    level: 'error' | 'warning';
+    kind: ScanProblem['kind'] | 'plugin-load' | 'parse-error' | 'broken-reference' | 'no-git' | 'skill-missing' | 'skill-outdated';
+    message: string;
+    path?: string;
+    key?: string;
+}
+export interface PluginInfo {
+    key: string;
+    /** The _Plugin_Source_ as declared. */
+    source: string;
+    description?: string;
+    layout?: string;
+    /** The plugin folder and the scope of the place it was loaded from. */
+    directory?: string;
+    scope?: Scope;
+    /** The name of the _Plugin_Skill_, such as `adoc-kanban`. */
+    skill?: string;
+    /** The _Plugin_Client_Module_, when the plugin has one: whether it has a stylesheet too. */
+    client?: {
+        style: boolean;
+    };
+    error?: string;
+    documents: number;
+}
+export type ActionOutcome = {
+    status: 'applied' | 'sent';
+    version?: string;
+    message?: ActionMessageInput;
+} | {
+    status: 'refused';
+    reason: string;
+} | {
+    status: 'failed';
+    error: string;
+};
+/**
+ * An opened _Adoc_Workspace_: its configuration, loaded plugins and indexed documents.
+ * Plugin calls are cached by _Document_Version_; `refresh` rescans after file changes.
+ */
+export declare class Workspace {
+    readonly home: AdocHome;
+    readonly config: AdocConfig;
+    private plugins;
+    private documents;
+    private problems;
+    private cache;
+    /** _Document_Version_Store_: recent versions of each document, oldest first. */
+    private versions;
+    private changeCache;
+    revision: number;
+    /** Whether the workspace is inside a git repository, checked on every refresh. */
+    git: boolean;
+    private constructor();
+    static open(home: AdocHome, env?: NodeJS.ProcessEnv): Promise<Workspace>;
+    /** Reloads every plugin from disk, for example after its index.ts changed, and rescans. */
+    reloadPlugins(): Promise<void>;
+    get root(): string;
+    get name(): string;
+    /** Rescans the watch paths. Returns the keys whose version changed, appeared or disappeared. */
+    refresh(): Promise<string[]>;
+    private remember;
+    /** The changes of a document since `base`: the plugin's renderChanges, or a line diff of the main file. */
+    changes(key: string, base: string): DocumentChanges | undefined;
+    /** The versions of a document in the _Document_Version_Store_, newest first. */
+    storedVersions(key: string): StoredVersion[] | undefined;
+    pluginInfos(): PluginInfo[];
+    /** Every declared plugin, loaded or failed, in the order of the _Adoc_Config_. */
+    loadedPlugins(): LoadedPlugin[];
+    plugin(key: string): LoadedPlugin | undefined;
+    record(key: string): DocumentRecord | undefined;
+    private definitionOf;
+    private entry;
+    /** The _Document_Summary_ of a document, computed once per version. */
+    summarize(key: string): {
+        summary?: DocumentSummary;
+        error?: string;
+    } | undefined;
+    /** The body HTML of a document from its _Plugin_Renderer_, computed once per version. */
+    render(key: string): {
+        html?: string;
+        error?: string;
+    } | undefined;
+    /** The _Document_Summary_List_ of one plugin, ordered by key. */
+    summaryList(pluginKey: string): SummaryEntry[];
+    /** _Document_Find_Command_ `list`: the entries of every plugin (or one), archived or not as asked, newest first. */
+    findDocuments(options: {
+        pluginKey?: string;
+        archived: boolean;
+    }): Array<SummaryEntry & {
+        pluginKey: string;
+    }>;
+    /** _Document_Find_Command_ `search`: every line of a document file that contains the text, case-insensitive. */
+    searchDocuments(text: string, options: {
+        pluginKey?: string;
+        archived: boolean;
+    }): Array<{
+        key: string;
+        path: string;
+        line: number;
+        text: string;
+    }>;
+    /**
+     * Writes the main file that the user edited in the _Document_Editor_, when `version` is still current; answers
+     * with the new version and the unified diff from `since` (the text the unsent edits started from) to the new text.
+     */
+    editMainFile(key: string, version: string, text: string, since?: string): Promise<{
+        status: 'applied';
+        version: string;
+        diff: string;
+    } | {
+        status: 'refused';
+        reason: string;
+    }>;
+    /** The main file of a document with its version, for the elements of a _Plugin_Client_Module_. */
+    mainFile(key: string): {
+        key: string;
+        version: string;
+        file: string;
+        text: string;
+    } | undefined;
+    view(key: string): DocumentView | undefined;
+    /** _Document_Reference_Resolution_: the summary of the referenced document, or `found: false`. */
+    resolve(target: string): {
+        found: boolean;
+        key: string;
+        archived?: boolean;
+        summary?: DocumentSummary;
+        error?: string;
+    };
+    /** Every _Document_Reference_ that the renderer of a document marked. */
+    references(key: string): string[];
+    /** The report of _Adoc_Check_Command_. */
+    check(): CheckEntry[];
+    /**
+     * Handles one _Document_Action_: runs the _Plugin_Action_Handler_ or the _Default_Action_Handler_,
+     * refuses a change when the _Document_Version_ moved, writes returned files and returns the message to send.
+     */
+    applyAction(key: string, event: ActionEvent, version: string): Promise<ActionOutcome>;
+}