@agent-workshop/adoc-core 0.1.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (C) 2026 adoc contributors
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,49 @@
+# Third-party notices
+
+adoc's original code and documentation use the Zero-Clause BSD License (0BSD). That license does not replace the
+licenses of third-party components, and no third-party component is relicensed by this repository.
+
+## Browser distributions
+
+Two packages carry bundled browser code:
+
+- `@agent-workshop/adoc-webapp`: the web UI in `dist/`. Its build records the packages actually bundled in
+  `dist/licenses/packages.json` and copies their upstream LICENSE, COPYING, COPYRIGHT and NOTICE files beneath
+  `dist/licenses/`.
+- `@agent-workshop/adoc-plugin-sketch`: the drawing board in `client/`, with its inventory and license files in
+  `client/licenses/`.
+
+Keep these files when redistributing the built browser assets.
+
+The main browser dependencies are React, React DOM, React Router, Mermaid (with KaTeX), xterm.js and Lucide in the web
+UI, and Excalidraw with React and Radix UI in the drawing board. Most use MIT, ISC, BSD or Apache-2.0.
+
+- DOMPurify offers MPL-2.0 OR Apache-2.0; adoc uses the Apache-2.0 option.
+- Some packages are published without a license file although their manifest names one: Excalidraw, the Radix UI
+  primitives, react-remove-scroll-bar and fastdom (all MIT). The build includes the upstream texts kept in
+  `tooling/licenses/`.
+
+### Eclipse Layout Kernel / elkjs
+
+Mermaid bundles elkjs, a separately licensed layout engine, which adoc uses under EPL-2.0 without modifying it. Its
+license is included in the generated license inventory. Corresponding source is available from:
+
+- https://github.com/kieler/elkjs (select the release matching the inventory version)
+- https://github.com/eclipse/elk (the underlying Eclipse Layout Kernel)
+- https://www.eclipse.org/legal/epl-2.0/
+
+Recipients may obtain, modify and redistribute the EPL-covered source under EPL-2.0. adoc's 0BSD license applies to its
+independent code, not to ELK.
+
+## Fonts
+
+- The web UI serves Pretendard, D2Coding (both SIL Open Font License 1.1) and Symbols Nerd Font Mono; their license
+  files are next to them in `dist/assets/fonts/`.
+- The drawing board serves the fonts that Excalidraw ships in `client/fonts/` (Excalifont, Virgil, Nunito, Lilita One,
+  Comic Shanns, Cascadia Code, Liberation Sans, Assistant and Xiaolai); they are distributed under the terms that
+  Excalidraw states for them in https://github.com/excalidraw/excalidraw.
+
+## Installed runtime dependencies
+
+The packages that npm installs next to adoc, such as the MCP SDK, ws, yaml, zod, semver, commander, markdown-it and
+highlight.js, are not bundled: each keeps its own license in its own package.

package/dist/claim.d.ts

@@ -0,0 +1,17 @@
+import type { AdocHome } from './home.js';
+import type { ResolvedPane } from './herdr.js';
+export declare const CLAIM_FILE = "claim.yaml";
+/** _Agent_Claim_: the herdr pane where the _Assigned_Agent_ runs, kept in `.adoc/claim.yaml`. */
+export interface AgentClaim {
+    herdrSession: string;
+    socket: string;
+    pane: string;
+    terminal: string;
+    agent?: string;
+    agentSession?: string;
+    claimedAt: string;
+}
+export declare function claimPath(home: AdocHome): string;
+export declare function readClaim(home: AdocHome): Promise<AgentClaim | undefined>;
+export declare function writeClaim(home: AdocHome, resolved: ResolvedPane): Promise<AgentClaim>;
+export declare function removeClaim(home: AdocHome): Promise<void>;

package/dist/claim.js

@@ -0,0 +1,35 @@
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse, stringify } from 'yaml';
+export const CLAIM_FILE = 'claim.yaml';
+export function claimPath(home) {
+    return join(home.home, CLAIM_FILE);
+}
+export async function readClaim(home) {
+    try {
+        const value = parse(await readFile(claimPath(home), 'utf8'));
+        return value && typeof value.pane === 'string' && typeof value.socket === 'string' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function writeClaim(home, resolved) {
+    const claim = {
+        herdrSession: resolved.herdrSession,
+        socket: resolved.socket,
+        pane: resolved.pane.pane_id,
+        terminal: resolved.pane.terminal_id,
+        claimedAt: new Date().toISOString(),
+    };
+    if (resolved.pane.agent)
+        claim.agent = resolved.pane.agent;
+    if (resolved.pane.agent_session?.value)
+        claim.agentSession = resolved.pane.agent_session.value;
+    await writeFile(claimPath(home), `# The herdr pane of the assigned agent on this computer. Written by adoc agent claim; do not commit.\n${stringify(claim)}`);
+    return claim;
+}
+export async function removeClaim(home) {
+    await rm(claimPath(home), { force: true });
+}
+//# sourceMappingURL=claim.js.map

package/dist/claim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.js","sourceRoot":"","sources":["../src/claim.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAIxC,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC;AAavC,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAc;IAC5C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAsB,CAAC;QAClF,OAAO,KAAK,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACzG,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAc,EAAE,QAAsB;IACrE,MAAM,KAAK,GAAe;QACxB,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,OAAO;QAC3B,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW;QACnC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IACF,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK;QAAE,KAAK,CAAC,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;IAC3D,IAAI,QAAQ,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK;QAAE,KAAK,CAAC,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;IAC/F,MAAM,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,yGAAyG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC9J,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAc;IAC9C,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAC7C,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+import type { AdocConfig } from './config.js';
+/** Talks to the running _Adoc_Server_ of a workspace from the command line. */
+export declare class ServerClient {
+    readonly url: string;
+    private readonly workspace;
+    private constructor();
+    /** Finds the server through its _Server_Record_, falling back to the address in adoc.yaml. */
+    static find(config: AdocConfig, workspace: string): Promise<ServerClient>;
+    /** Fails with a clear error unless the server of this workspace answers. */
+    ensure(): Promise<void>;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,49 @@
+import { AdocError, errorMessage } from './errors.js';
+import { readServerRecord } from './registry.js';
+import { PROTOCOL } from './server.js';
+/** Talks to the running _Adoc_Server_ of a workspace from the command line. */
+export class ServerClient {
+    url;
+    workspace;
+    constructor(url, workspace) {
+        this.url = url;
+        this.workspace = workspace;
+    }
+    /** Finds the server through its _Server_Record_, falling back to the address in adoc.yaml. */
+    static async find(config, workspace) {
+        const record = await readServerRecord(workspace);
+        if (record)
+            return new ServerClient(record.url, workspace);
+        const host = config.server.host === '0.0.0.0' || config.server.host === '::' ? '127.0.0.1' : config.server.host;
+        return new ServerClient(`http://${host}:${config.server.port}`, workspace);
+    }
+    /** Fails with a clear error unless the server of this workspace answers. */
+    async ensure() {
+        let health;
+        try {
+            const response = await fetch(`${this.url}/api/health`, { signal: AbortSignal.timeout(2000) });
+            health = (await response.json());
+        }
+        catch (error) {
+            throw new AdocError('server.unreachable', `No adoc server answers at ${this.url} (${errorMessage(error)}); start it with adoc server run.`);
+        }
+        if (health.protocol !== PROTOCOL)
+            throw new AdocError('server.protocol', `${this.url} is not an adoc server.`);
+        if (health.workspace !== this.workspace)
+            throw new AdocError('server.workspace', `The adoc server at ${this.url} serves ${health.workspace}, not ${this.workspace}.`);
+    }
+    async get(path) {
+        return this.request(path, {});
+    }
+    async post(path, body) {
+        return this.request(path, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+    }
+    async request(path, init) {
+        const response = await fetch(this.url + path, init);
+        const body = (await response.json());
+        if (!response.ok)
+            throw new AdocError('server.request', body.error ?? `${path} failed with ${response.status}`);
+        return body;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import type { AdocHome } from './home.js';
+declare const transportSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"herdr">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"wait">;
+}, z.core.$strip>], "kind">;
+/** A _Plugin_ that the config declares: its key, its _Plugin_Source_ and the folder of the file that declares it. */
+export interface DeclaredPlugin {
+    readonly key: string;
+    readonly source: string;
+    /** Relative paths and npm lookups of the source start here. */
+    readonly base: string;
+}
+/** The _Adoc_Config_ laid over the _User_Config_. */
+export interface AdocConfig {
+    /** In tab order: `ui.tabs` first, then the order of declaration. */
+    readonly plugins: readonly DeclaredPlugin[];
+    /** Relative to the workspace root. */
+    readonly watch: readonly string[];
+    readonly agent: {
+        readonly name: string;
+        readonly transport: TransportConfig;
+    };
+    readonly server: {
+        readonly host: string;
+        readonly port: number;
+    };
+    readonly ui: {
+        readonly theme: 'dark' | 'light' | 'system';
+    };
+}
+export type TransportConfig = z.infer<typeof transportSchema>;
+/** The _User_Config_: `adoc/adoc.yaml` in the XDG config directory. */
+export declare function userConfigPath(env?: NodeJS.ProcessEnv): string;
+/** Reads the _User_Config_ and the _Adoc_Config_, and lays the second over the first, setting by setting. */
+export declare function readConfig(home: AdocHome, env?: NodeJS.ProcessEnv): Promise<AdocConfig>;
+export declare const CONFIG_TEMPLATE = "# adoc workspace configuration, laid over ~/.config/adoc/adoc.yaml. Paths are relative to this file.\nplugins:                        # plugin key: npm:<package>, github:<owner>/<repo>/<folder>, a path such as ./plugins/x, or off\n  NOTE: npm:@agent-workshop/adoc-plugin-note\n  TODO: npm:@agent-workshop/adoc-plugin-todo\n  SKETCH: npm:@agent-workshop/adoc-plugin-sketch\n  TASK: npm:@agent-workshop/adoc-plugin-task\n  KANBAN: npm:@agent-workshop/adoc-plugin-kanban\nwatch:\n  - ../docs\nagent:\n  name: agent\n  transport:\n    kind: herdr                 # herdr (the pane from adoc agent claim) | wait (the agent runs adoc message wait)\nserver:\n  host: 127.0.0.1               # 0.0.0.0 to accept connections from the internal network (no authentication)\n  port: 7700\nui:\n  tabs: [NOTE, TODO, SKETCH, TASK, KANBAN]\n  theme: dark                   # default colour scheme of the web UI: dark | light | system; each browser may choose another\n";
+export {};

package/dist/config.js

@@ -0,0 +1,110 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { parse } from 'yaml';
+import { z } from 'zod';
+import { AdocError } from './errors.js';
+import { PLUGIN_KEY_PATTERN } from './names.js';
+const transportSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('herdr') }),
+    z.object({ kind: z.literal('wait') }),
+]);
+/** One config file, the _Adoc_Config_ or the _User_Config_: every setting is optional, since the two are laid over each other. */
+const fileSchema = z.object({
+    plugins: z.record(z.string().regex(PLUGIN_KEY_PATTERN, 'a plugin key must be uppercase letters A-Z only'), z.string().min(1)).optional(),
+    watch: z.array(z.string().min(1)).optional(),
+    agent: z.object({ name: z.string().min(1).optional(), transport: transportSchema.optional() }).optional(),
+    server: z.object({ host: z.string().optional(), port: z.number().int().min(1).max(65535).optional() }).optional(),
+    ui: z.object({ tabs: z.array(z.string()).optional(), theme: z.enum(['dark', 'light', 'system']).optional() }).optional(),
+});
+/** The _User_Config_: `adoc/adoc.yaml` in the XDG config directory. */
+export function userConfigPath(env = process.env) {
+    return join(env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config'), 'adoc', 'adoc.yaml');
+}
+const FORMAT_HINT = 'plugins:\n  TODO: npm:@agent-workshop/adoc-plugin-todo\n  TASK: ./plugins/task';
+async function readFileConfig(path, required) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        if (required)
+            throw new AdocError('config.missing', `Cannot read ${path}; run adoc init.`);
+        return {};
+    }
+    let raw;
+    try {
+        raw = parse(text) ?? {};
+    }
+    catch (error) {
+        throw new AdocError('config.invalid', `${path}: ${error.message}`);
+    }
+    if (Array.isArray(raw.plugins)) {
+        throw new AdocError('config.format', `${path}: plugins is a list in an earlier format; write it as a map from each plugin key to its source:\n${FORMAT_HINT}`);
+    }
+    const result = fileSchema.safeParse(raw);
+    if (!result.success) {
+        const details = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+        throw new AdocError('config.invalid', `${path}: ${details}`);
+    }
+    return result.data;
+}
+/** Reads the _User_Config_ and the _Adoc_Config_, and lays the second over the first, setting by setting. */
+export async function readConfig(home, env = process.env) {
+    const userPath = userConfigPath(env);
+    const user = await readFileConfig(userPath, false);
+    const project = await readFileConfig(home.configPath, true);
+    const layers = [
+        { file: user, base: dirname(userPath) },
+        { file: project, base: home.home },
+    ];
+    const declared = new Map();
+    // The project's own plugins come before the ones only the user declares.
+    for (const { file, base } of [...layers].reverse()) {
+        for (const [key, source] of Object.entries(file.plugins ?? {}))
+            if (!declared.has(key))
+                declared.set(key, { key, source, base });
+    }
+    for (const [key, plugin] of declared)
+        if (plugin.source === 'off')
+            declared.delete(key);
+    const last = (pick) => {
+        for (const { file, base } of [...layers].reverse()) {
+            const value = pick(file);
+            if (value !== undefined)
+                return { value, base };
+        }
+        return undefined;
+    };
+    const tabs = last((f) => f.ui?.tabs)?.value ?? [];
+    const ordered = [...tabs.filter((key) => declared.has(key)), ...[...declared.keys()].filter((key) => !tabs.includes(key))];
+    const watch = last((f) => f.watch);
+    return {
+        plugins: ordered.map((key) => declared.get(key)),
+        watch: watch ? watch.value.map((path) => relative(home.workspace, resolve(watch.base, path)) || '.') : ['docs'],
+        agent: { name: last((f) => f.agent?.name)?.value ?? 'agent', transport: last((f) => f.agent?.transport)?.value ?? { kind: 'herdr' } },
+        server: { host: last((f) => f.server?.host)?.value ?? '127.0.0.1', port: last((f) => f.server?.port)?.value ?? 7700 },
+        ui: { theme: last((f) => f.ui?.theme)?.value ?? 'dark' },
+    };
+}
+export const CONFIG_TEMPLATE = `# adoc workspace configuration, laid over ~/.config/adoc/adoc.yaml. Paths are relative to this file.
+plugins:                        # plugin key: npm:<package>, github:<owner>/<repo>/<folder>, a path such as ./plugins/x, or off
+  NOTE: npm:@agent-workshop/adoc-plugin-note
+  TODO: npm:@agent-workshop/adoc-plugin-todo
+  SKETCH: npm:@agent-workshop/adoc-plugin-sketch
+  TASK: npm:@agent-workshop/adoc-plugin-task
+  KANBAN: npm:@agent-workshop/adoc-plugin-kanban
+watch:
+  - ../docs
+agent:
+  name: agent
+  transport:
+    kind: herdr                 # herdr (the pane from adoc agent claim) | wait (the agent runs adoc message wait)
+server:
+  host: 127.0.0.1               # 0.0.0.0 to accept connections from the internal network (no authentication)
+  port: 7700
+ui:
+  tabs: [NOTE, TODO, SKETCH, TASK, KANBAN]
+  theme: dark                   # default colour scheme of the web UI: dark | light | system; each browser may choose another
+`;
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+/** An expected failure with a stable code and a message meant for the user or agent reading it. */
+export declare class AdocError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function errorMessage(error: unknown): string;

package/dist/errors.js

@@ -0,0 +1,13 @@
+/** An expected failure with a stable code and a message meant for the user or agent reading it. */
+export class AdocError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AdocError';
+    }
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,MAAM,OAAO,SAAU,SAAQ,KAAK;IAEvB,IAAI;IADf,YACW,IAAY,EACrB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;oBAHN,IAAI;QAIb,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}

package/dist/fetch.d.ts

@@ -0,0 +1,19 @@
+import type { AdocConfig } from './config.js';
+/** What happened to one GitHub _Plugin_Source_. */
+export interface FetchOutcome {
+    readonly key: string;
+    readonly source: string;
+    readonly status: 'fetched' | 'present' | 'refused' | 'failed';
+    readonly commit?: string;
+    readonly reason?: string;
+}
+/** A hash of every file of a folder, by relative path and content, so that a changed fetched folder is noticed. */
+export declare function folderHash(folder: string): Promise<string>;
+/**
+ * Fetches the GitHub _Plugin_Source_ entries of the config into their _Plugin_Directory_: with `update` false only the
+ * ones not fetched yet, with `update` true again, refusing a folder whose files differ from what was fetched.
+ */
+export declare function fetchGithubPlugins(config: AdocConfig, options: {
+    update: boolean;
+    keys?: readonly string[];
+}, env?: NodeJS.ProcessEnv): Promise<FetchOutcome[]>;

package/dist/fetch.js

@@ -0,0 +1,106 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { cp, mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import { promisify } from 'node:util';
+import { AdocError, errorMessage } from './errors.js';
+import { fetchedFolder, parseGithubSource, pluginDirectory } from './plugins.js';
+const run = promisify(execFile);
+const LOCK_FILE = 'plugins-lock.json';
+async function readLock(directory) {
+    try {
+        return JSON.parse(await readFile(join(directory, LOCK_FILE), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+async function writeLock(directory, lock) {
+    const sorted = Object.fromEntries(Object.entries(lock).sort(([a], [b]) => a.localeCompare(b)));
+    await writeFile(join(directory, LOCK_FILE), `${JSON.stringify(sorted, null, 2)}\n`);
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A hash of every file of a folder, by relative path and content, so that a changed fetched folder is noticed. */
+export async function folderHash(folder) {
+    const hash = createHash('sha256');
+    const walk = async (dir) => {
+        for (const entry of (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(path);
+            else
+                hash.update(relative(folder, path)).update('\0').update(await readFile(path)).update('\0');
+        }
+    };
+    await walk(folder);
+    return hash.digest('hex');
+}
+/** Fetches the folder of a GitHub _Plugin_Source_ at its ref into `target`, and returns the commit. */
+async function fetchInto(source, target, env) {
+    const github = parseGithubSource(source);
+    const url = `${env.ADOC_GITHUB_URL || 'https://github.com'}/${github.owner}/${github.repo}.git`;
+    const work = await mkdtemp(join(tmpdir(), 'adoc-fetch-'));
+    try {
+        await run('git', ['-C', work, 'init', '-q']);
+        await run('git', ['-C', work, 'fetch', '-q', '--depth', '1', url, github.ref ?? 'HEAD']);
+        await run('git', ['-C', work, 'checkout', '-q', 'FETCH_HEAD']);
+        const commit = (await run('git', ['-C', work, 'rev-parse', 'HEAD'])).stdout.trim();
+        const folder = join(work, github.folder);
+        if (!(await exists(join(folder, 'index.js'))) && !(await exists(join(folder, 'index.ts'))) && !(await exists(join(folder, 'index.mjs')))) {
+            throw new Error(`${github.folder || 'the repository root'} of ${github.owner}/${github.repo} has no index.ts or index.js`);
+        }
+        await rm(target, { recursive: true, force: true });
+        await mkdir(target, { recursive: true });
+        await cp(folder, target, { recursive: true, filter: (path) => !relative(folder, path).split(/[\\/]/).includes('.git') });
+        return commit;
+    }
+    finally {
+        await rm(work, { recursive: true, force: true });
+    }
+}
+/**
+ * Fetches the GitHub _Plugin_Source_ entries of the config into their _Plugin_Directory_: with `update` false only the
+ * ones not fetched yet, with `update` true again, refusing a folder whose files differ from what was fetched.
+ */
+export async function fetchGithubPlugins(config, options, env = process.env) {
+    const github = config.plugins.filter((p) => parseGithubSource(p.source));
+    const unknown = options.keys?.filter((key) => !github.some((p) => p.key === key)) ?? [];
+    if (unknown.length)
+        throw new AdocError('plugin.unknown', `No GitHub plugin source is declared for ${unknown.join(', ')}.`);
+    const chosen = options.keys?.length ? github.filter((p) => options.keys.includes(p.key)) : github;
+    const outcomes = [];
+    for (const plugin of chosen)
+        outcomes.push(await fetchOne(plugin, options.update, env));
+    return outcomes;
+}
+async function fetchOne(plugin, update, env) {
+    const { key, source } = plugin;
+    const directory = pluginDirectory(plugin.base);
+    const target = fetchedFolder(plugin);
+    const name = key.toLowerCase();
+    const lock = await readLock(directory);
+    const present = await exists(target);
+    if (present && !update)
+        return { key, source, status: 'present', ...(lock[name] ? { commit: lock[name].commit } : {}) };
+    if (present && (!lock[name] || lock[name].hash !== (await folderHash(target)))) {
+        return { key, source, status: 'refused', reason: `${target} differs from what was fetched; copy it to another folder to change it, or remove it to fetch again` };
+    }
+    try {
+        const commit = await fetchInto(source, target, env);
+        await writeLock(directory, { ...(await readLock(directory)), [name]: { source, commit, hash: await folderHash(target) } });
+        return { key, source, status: 'fetched', commit };
+    }
+    catch (error) {
+        return { key, source, status: 'failed', reason: errorMessage(error) };
+    }
+}
+//# sourceMappingURL=fetch.js.map

package/dist/fetch.js.map

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

package/dist/git.d.ts

@@ -0,0 +1 @@
+export declare function isGitRepository(directory: string): Promise<boolean>;

package/dist/git.js

@@ -0,0 +1,13 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+export async function isGitRepository(directory) {
+    try {
+        const { stdout } = await run('git', ['rev-parse', '--is-inside-work-tree'], { cwd: directory });
+        return stdout.trim() === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,GAAG,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAEhC,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,SAAiB;IACrD,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,uBAAuB,CAAC,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC;QAChG,OAAO,MAAM,CAAC,IAAI,EAAE,KAAK,MAAM,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/herdr.d.ts

@@ -0,0 +1,44 @@
+/** One pane as herdr's `session.snapshot` reports it. */
+export interface HerdrPane {
+    pane_id: string;
+    terminal_id: string;
+    agent?: string;
+    agent_status?: string;
+    agent_session?: {
+        agent?: string;
+        kind?: string;
+        value?: string;
+    };
+}
+/** Sends one request over a herdr session socket (NDJSON) and returns its result. */
+export declare function herdrCall<T>(socketPath: string, method: string, params?: unknown): Promise<T>;
+/**
+ * Subscribes to herdr events on a session socket; the connection stays open.
+ * Returns a function that closes the subscription.
+ */
+export declare function herdrSubscribe(socketPath: string, subscriptions: unknown[], onEvent: (event: {
+    event?: string;
+    data?: unknown;
+}) => void, onClose: () => void): () => void;
+/** The socket of every herdr session on this computer, by session name. */
+export declare function herdrSessions(home?: string): Promise<Array<{
+    name: string;
+    socket: string;
+}>>;
+export declare function herdrPanes(socketPath: string): Promise<HerdrPane[]>;
+/** Whether this process runs under a shared agent daemon such as the Codex app-server, whose HERDR_PANE_ID is not the agent's. */
+export declare function underSharedDaemon(pid?: number): Promise<boolean>;
+export interface ResolvedPane {
+    herdrSession: string;
+    socket: string;
+    pane: HerdrPane;
+    via: 'option' | 'session-id' | 'environment';
+}
+/**
+ * Finds the caller's herdr pane, in the order of _Agent_Claim_Command_: `--pane`, then the pane whose
+ * recorded agent session is the caller's session id, then HERDR_PANE_ID unless under a shared daemon.
+ */
+export declare function resolveAgentPane(env: NodeJS.ProcessEnv, options?: {
+    pane?: string;
+    herdrSession?: string;
+}): Promise<ResolvedPane>;