opencode-wiki-historian 0.2.0

package/dist/tools/write.js

@@ -0,0 +1,148 @@
+/**
+ * historian_page_update + historian_page_append: engine RMW update and the
+ * bilingual append (en append + zh twin handling per the wiki-biling
+ * semantics — the twin bootstrap composes engine primitives only:
+ * appendSection / createPage / readPage / translate; never reimplemented).
+ */
+import { tool } from '@opencode-ai/plugin';
+import { appendSection, createPage, updatePage, PageNotFoundError } from '../wiki/pages.js';
+import { readPage } from '../wiki/pages.read.js';
+import { errEnvelope, okJson, urlPair, URL_MANDATE, pageDeps } from './shared.js';
+const s = tool.schema;
+const UPDATE_ARGS = {
+    path: s.string(),
+    locale: s.enum(['en', 'zh']).default('en'),
+    title: s.string().optional(),
+    content: s.string().optional(),
+    description: s.string().optional(),
+    tags: s.array(s.string()).optional(),
+};
+const UpdateArgsSchema = s.object(UPDATE_ARGS);
+export function makeUpdateTool(deps) {
+    return tool({
+        description: `Update a wiki page: full read-modify-write — omitted fields are kept unchanged (engine preserves them). ` +
+            `Path + locale resolve the page; no raw id. ${URL_MANDATE}.`,
+        args: UPDATE_ARGS,
+        execute: async (raw) => {
+            const args = UpdateArgsSchema.parse(raw);
+            try {
+                const page = await readPage(deps.getClient(), args.path, args.locale);
+                if (page === null) {
+                    return errEnvelope(new PageNotFoundError(`page '${args.path}' (${args.locale}) does not exist`));
+                }
+                const result = await updatePage(pageDeps(deps), page.id, {
+                    title: args.title,
+                    content: args.content,
+                    description: args.description,
+                    tags: args.tags,
+                });
+                return okJson({
+                    mode: 'update',
+                    path: args.path,
+                    locale: args.locale,
+                    pageId: result.pageId,
+                    page: {
+                        id: result.page.id,
+                        title: result.page.title,
+                        description: result.page.description,
+                        tags: result.page.tags,
+                        isPublished: result.page.isPublished,
+                        contentType: result.page.contentType,
+                        updatedAt: result.page.updatedAt,
+                    },
+                    urls: urlPair(result),
+                });
+            }
+            catch (err) {
+                return errEnvelope(err);
+            }
+        },
+    });
+}
+async function bootstrapTwin(deps, primary, section, source) {
+    const translate = source === 'translate' ? deps.translate : undefined;
+    try {
+        const title = translate !== undefined ? await translate(primary.title, 'en', 'zh') : primary.title;
+        const content = translate !== undefined ? await translate(section, 'en', 'zh') : section;
+        await createPage(pageDeps(deps), {
+            path: primary.path,
+            locale: 'zh',
+            title,
+            content,
+            tags: primary.tags,
+            isPublished: primary.isPublished,
+            twin: false,
+        });
+        return { status: 'created' };
+    }
+    catch (err) {
+        return { status: 'pending', note: `zh twin bootstrap failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+const APPEND_ARGS = {
+    path: s.string(),
+    section: s.string(),
+    locale: s.enum(['en', 'zh']).default('en'),
+    sectionZh: s.string().optional().describe('Explicit zh section; when absent the zh side falls back to translation/wiring'),
+};
+const AppendArgsSchema = s.object(APPEND_ARGS);
+export function makeAppendTool(deps) {
+    return tool({
+        description: `Append a section to an existing page (engine append + RMW). For the en page with a MISSING zh twin, ` +
+            `the twin is auto-created — from sectionZh when given, else translated when the translator is wired. ` +
+            `${URL_MANDATE}.`,
+        args: APPEND_ARGS,
+        execute: async (raw) => {
+            const args = AppendArgsSchema.parse(raw);
+            try {
+                const appended = await appendSection(pageDeps(deps), args.path, args.locale, args.section);
+                let zhStatus;
+                let zhNote;
+                if (args.locale === 'zh') {
+                    zhStatus = 'appended';
+                    zhNote = 'Primary locale is zh — the en twin is untouched (check with historian_read(path, "en")).';
+                }
+                else if (args.sectionZh !== undefined) {
+                    const twin = await readPage(deps.getClient(), args.path, 'zh');
+                    if (twin !== null) {
+                        await appendSection(pageDeps(deps), args.path, 'zh', args.sectionZh);
+                        zhStatus = 'appended';
+                    }
+                    else {
+                        const outcome = await bootstrapTwin(deps, appended.page, args.sectionZh, 'explicit');
+                        zhStatus = outcome.status;
+                        zhNote = outcome.note;
+                    }
+                }
+                else {
+                    const twin = await readPage(deps.getClient(), args.path, 'zh');
+                    if (twin !== null) {
+                        zhStatus = 'exists';
+                        zhNote = 'zh twin untouched — pass sectionZh to sync it, or call historian_page_append with locale "zh".';
+                    }
+                    else if (deps.translate !== undefined) {
+                        const outcome = await bootstrapTwin(deps, appended.page, args.section, 'translate');
+                        zhStatus = outcome.status;
+                        zhNote = outcome.note;
+                    }
+                    else {
+                        zhStatus = 'missing';
+                        zhNote = 'No zh twin exists and no translator is wired — provide sectionZh to bootstrap it.';
+                    }
+                }
+                return okJson({
+                    mode: 'append',
+                    path: args.path,
+                    locale: args.locale,
+                    pageId: appended.pageId,
+                    urls: urlPair(appended),
+                    zhStatus,
+                    zhNote,
+                });
+            }
+            catch (err) {
+                return errEnvelope(err);
+            }
+        },
+    });
+}

package/dist/tools.d.ts

@@ -0,0 +1,23 @@
+/**
+ * historian_* tool surface (todo 11) — barrel + composition.
+ *
+ * buildTools wires the 10 custom tools from the engine modules; this file
+ * holds no engine logic, only wiring. Per-call construction (no module-level
+ * cache — each buildTools call resolves a fresh client/translator), and the
+ * client is resolved LAZILY: a missing/invalid wiki key surfaces as a
+ * ConfigError envelope on first execution, never as a buildTools crash that
+ * would kill plugin registration (todo 12).
+ */
+import type { ToolDefinition } from '@opencode-ai/plugin';
+import { type GqlClient } from './wiki/client.js';
+import type { HistorianOptions } from './config.js';
+import type { TranslateFn } from './wiki/pages.read.js';
+export interface BuildDeps {
+    readonly client?: GqlClient;
+    readonly translate?: TranslateFn;
+    readonly fetchImpl?: typeof fetch;
+    readonly resultsDir?: string;
+    readonly homeDir?: string;
+}
+export type HistorianTools = Readonly<Record<string, ToolDefinition>>;
+export declare function buildTools(opts: HistorianOptions, deps?: BuildDeps): HistorianTools;

package/dist/tools.js

@@ -0,0 +1,43 @@
+/**
+ * historian_* tool surface (todo 11) — barrel + composition.
+ *
+ * buildTools wires the 10 custom tools from the engine modules; this file
+ * holds no engine logic, only wiring. Per-call construction (no module-level
+ * cache — each buildTools call resolves a fresh client/translator), and the
+ * client is resolved LAZILY: a missing/invalid wiki key surfaces as a
+ * ConfigError envelope on first execution, never as a buildTools crash that
+ * would kill plugin registration (todo 12).
+ */
+import { homedir } from 'node:os';
+import { createClient } from './wiki/client.js';
+import { makeTranslator } from './translate.js';
+import { makeCreateTool } from './tools/create.js';
+import { makeUpdateTool, makeAppendTool } from './tools/write.js';
+import { makeReadTool, makeSearchTool } from './tools/read.js';
+import { makeTranslateSnippetTool, makeMapTool } from './tools/local.js';
+import { makeDeleteTool, makeMoveTool, makeMigrateTool } from './tools/mutate.js';
+export function buildTools(opts, deps = {}) {
+    const homeDir = deps.homeDir ?? homedir();
+    // Translator must exist with NO injected deps (production plugin path):
+    // gating on deps.fetchImpl degraded twins to pending(translator-not-wired)
+    // in production while tests/pilot got a live one — regression-tested.
+    const translate = deps.translate ?? makeTranslator(opts, deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {});
+    let client;
+    const getClient = () => {
+        client ??= deps.client ?? createClient(opts, { fetchImpl: deps.fetchImpl, homeDir });
+        return client;
+    };
+    const toolDeps = { getClient, options: opts, translate, fetchImpl: deps.fetchImpl, resultsDir: deps.resultsDir, homeDir };
+    return {
+        historian_page_create: makeCreateTool(toolDeps),
+        historian_page_update: makeUpdateTool(toolDeps),
+        historian_page_append: makeAppendTool(toolDeps),
+        historian_translate_snippet: makeTranslateSnippetTool(toolDeps),
+        historian_search: makeSearchTool(toolDeps),
+        historian_read: makeReadTool(toolDeps),
+        historian_map: makeMapTool(toolDeps),
+        historian_migrate: makeMigrateTool(toolDeps),
+        historian_delete: makeDeleteTool(toolDeps),
+        historian_move: makeMoveTool(toolDeps),
+    };
+}

package/dist/translate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * DashScope Anthropic-compatible translation engine (replaces wiki-biling.py).
+ * Every failure surfaces as a named TranslateError. URL: append /v1/messages
+ * unless the endpoint already ends with /v1 or /v1/messages (double-v1 trap,
+ * machine-verified). Key redacted from body-derived details; no retry loop
+ * (chunked translation is deterministic, each request costs quota).
+ */
+import type { HistorianOptions } from './config.js';
+import type { Locale, TranslateFn } from './wiki/pages.read.js';
+export type TranslateErrorCause = 'network' | 'http' | 'malformed' | 'truncated' | 'timeout' | 'config';
+export declare class TranslateError extends Error {
+    readonly cause: TranslateErrorCause;
+    readonly detail: string;
+    constructor(cause: TranslateErrorCause, detail: string);
+}
+export declare const DEFAULT_TRANSLATE_TIMEOUT_MS = 300000;
+export declare function normalizeMessagesUrl(endpoint: string): string;
+/** Split on blank lines into groups of at most `max` chars. Oversized single
+ *  blocks and fence runs pass through whole (never split inside ``` fences),
+ *  so rejoining translated groups with '\n\n' reproduces the input structure. */
+export declare function splitMarkdownBlocks(text: string, max: number): string[];
+/** Primary: the first content part when it is a text part. Fallback: join
+ *  all text-type parts (content[0] may be a tool_use part). Missing/empty
+ *  text is malformed — never silently translated to ''. */
+export declare function pickResponseText(json: unknown): string;
+/** Machine-consumed routing tokens (DIRECTION, GLOSSARY table) plus the
+ *  untranslatable-surface rules. Tests pin the tokens, not the prose. */
+export declare function buildSystemPrompt(from: Locale, to: Locale, glossary?: Record<string, string>): string;
+export interface TranslateDeps {
+    readonly fetchImpl?: typeof fetch;
+    readonly timeoutMs?: number;
+    readonly glossary?: Record<string, string>;
+}
+/** One raw Anthropic-compatible messages call: caller-supplied system + user
+ *  prompt, shared URL/auth/timeout/error-taxonomy with the translation engine.
+ *  The migrate reformatter (todo 14) reuses this path with its own prompt; a
+ *  reformat call is never chunked (a restyle must see the whole page). */
+export interface MessagesCall {
+    readonly system: string;
+    readonly user: string;
+    readonly maxTokens?: number;
+}
+export declare function callMessages(opts: HistorianOptions, deps: TranslateDeps | undefined, call: MessagesCall): Promise<string>;
+export declare function makeTranslator(opts: HistorianOptions, deps?: TranslateDeps): TranslateFn;

package/dist/translate.js

@@ -0,0 +1,207 @@
+/**
+ * DashScope Anthropic-compatible translation engine (replaces wiki-biling.py).
+ * Every failure surfaces as a named TranslateError. URL: append /v1/messages
+ * unless the endpoint already ends with /v1 or /v1/messages (double-v1 trap,
+ * machine-verified). Key redacted from body-derived details; no retry loop
+ * (chunked translation is deterministic, each request costs quota).
+ */
+import { isRecord } from './jsonc.js';
+export class TranslateError extends Error {
+    cause;
+    detail;
+    constructor(cause, detail) {
+        super(`translate ${cause}: ${detail}`);
+        this.name = 'TranslateError';
+        this.cause = cause;
+        this.detail = detail;
+    }
+}
+// --- Constants (legacy wiki-biling values, config-driven via opts) ----------
+export const DEFAULT_TRANSLATE_TIMEOUT_MS = 300_000;
+const MAX_CHUNK_CHARS = 4000;
+const SHORT_TEXT_CHARS = 1500;
+const SHORT_MAX_TOKENS = 500;
+const LONG_MAX_TOKENS = 32_000;
+const ANTHROPIC_VERSION = '2023-06-01';
+// --- URL normalization ------------------------------------------------------
+export function normalizeMessagesUrl(endpoint) {
+    const base = endpoint.endsWith('/') ? endpoint.slice(0, -1) : endpoint;
+    const lower = base.toLowerCase();
+    if (lower.endsWith('/v1/messages') || lower.endsWith('/v1'))
+        return base;
+    return `${base}/v1/messages`;
+}
+// --- Chunking ---------------------------------------------------------------
+const FENCE_LINE = /^\s*```/;
+/** True when the block toggles the fence-open state (odd delimiter count). */
+function togglesFence(block) {
+    return block.split('\n').reduce((c, l) => (FENCE_LINE.test(l) ? c + 1 : c), 0) % 2 === 1;
+}
+/** Split on blank lines into groups of at most `max` chars. Oversized single
+ *  blocks and fence runs pass through whole (never split inside ``` fences),
+ *  so rejoining translated groups with '\n\n' reproduces the input structure. */
+export function splitMarkdownBlocks(text, max) {
+    if (text.length <= max)
+        return [text];
+    const groups = [];
+    let current = [];
+    let currentLen = 0;
+    let inFence = false;
+    const flush = () => {
+        if (current.length > 0)
+            groups.push(current.join('\n\n'));
+        current = [];
+        currentLen = 0;
+    };
+    for (const block of text.split(/\n\s*\n/)) {
+        if (inFence) {
+            current.push(block);
+            currentLen += 2 + block.length;
+            if (togglesFence(block)) {
+                inFence = false;
+                flush();
+            }
+            continue;
+        }
+        if (togglesFence(block)) {
+            if (currentLen > 0)
+                flush();
+            inFence = true;
+            current.push(block);
+            currentLen = block.length;
+            continue;
+        }
+        if (currentLen > 0 && currentLen + 2 + block.length > max)
+            flush();
+        current.push(block);
+        currentLen = currentLen === 0 ? block.length : currentLen + 2 + block.length;
+    }
+    flush();
+    return groups;
+}
+// --- Response parsing -------------------------------------------------------
+/** Primary: the first content part when it is a text part. Fallback: join
+ *  all text-type parts (content[0] may be a tool_use part). Missing/empty
+ *  text is malformed — never silently translated to ''. */
+export function pickResponseText(json) {
+    if (!isRecord(json))
+        throw new TranslateError('malformed', 'response body is not a JSON object');
+    const content = json.content;
+    if (!Array.isArray(content)) {
+        throw new TranslateError('malformed', 'response content is missing or not an array');
+    }
+    const texts = [];
+    for (const part of content) {
+        if (isRecord(part) && part.type === 'text' && typeof part.text === 'string') {
+            texts.push(part.text);
+        }
+    }
+    if (texts.length === 0) {
+        throw new TranslateError('malformed', 'response content has no text parts');
+    }
+    const out = isRecord(content[0]) && content[0].type === 'text' && typeof content[0].text === 'string'
+        ? content[0].text
+        : texts.join('');
+    if (out === '')
+        throw new TranslateError('malformed', 'response text is empty');
+    return out;
+}
+// --- System prompt ----------------------------------------------------------
+/** Machine-consumed routing tokens (DIRECTION, GLOSSARY table) plus the
+ *  untranslatable-surface rules. Tests pin the tokens, not the prose. */
+export function buildSystemPrompt(from, to, glossary) {
+    const lines = [
+        `DIRECTION: ${from}->${to}`,
+        'Translate only natural prose. Preserve markdown structure exactly: do not translate code blocks, inline code, URLs, HTML tags, .is-* marker classes, table cell structure (pipes, alignment rows), numbers, or IDs.',
+    ];
+    if (glossary !== undefined) {
+        lines.push('GLOSSARY:');
+        for (const [term, translation] of Object.entries(glossary)) {
+            lines.push(`${term}|${translation}`);
+        }
+    }
+    return lines.join('\n');
+}
+export async function callMessages(opts, deps, call) {
+    if (opts.translate.endpoint.trim() === '') {
+        throw new TranslateError('config', 'translate.endpoint not configured — set plugin option translate.endpoint ' +
+            'or export HISTORIAN_TRANSLATE_ENDPOINT.');
+    }
+    const url = normalizeMessagesUrl(opts.translate.endpoint);
+    const key = opts.translate.apiKey;
+    const fetchImpl = deps?.fetchImpl ?? fetch;
+    const timeoutMs = deps?.timeoutMs ?? DEFAULT_TRANSLATE_TIMEOUT_MS;
+    const maxTokens = call.maxTokens ?? LONG_MAX_TOKENS;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                'x-api-key': key,
+                'anthropic-version': ANTHROPIC_VERSION,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+                model: opts.translate.model,
+                max_tokens: maxTokens,
+                system: call.system,
+                messages: [{ role: 'user', content: call.user }],
+            }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        if (isAbortError(err)) {
+            throw new TranslateError('timeout', `request to ${url} timed out after ${timeoutMs}ms`);
+        }
+        throw new TranslateError('network', `request to ${url} failed: ${redact(err instanceof Error ? err.message : String(err), key)}`);
+    }
+    const rawBody = redact(await readTextSafely(res), key);
+    if (res.status < 200 || res.status >= 300) {
+        throw new TranslateError('http', `HTTP ${res.status} from ${url}: ${snippetOf(rawBody)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawBody);
+    }
+    catch {
+        throw new TranslateError('malformed', `non-json response from ${url}: ${snippetOf(rawBody)}`);
+    }
+    if (isRecord(parsed) && parsed.stop_reason === 'max_tokens') {
+        throw new TranslateError('truncated', `response stop_reason 'max_tokens' from ${url}`);
+    }
+    return pickResponseText(parsed);
+}
+export function makeTranslator(opts, deps) {
+    const glossary = deps?.glossary;
+    return async (text, from, to) => {
+        const chunks = splitMarkdownBlocks(text, MAX_CHUNK_CHARS);
+        const translated = [];
+        for (const chunk of chunks) {
+            translated.push(await translateChunk(chunk, from, to));
+        }
+        return translated.join('\n\n');
+    };
+    async function translateChunk(chunk, from, to) {
+        const maxTokens = chunk.length < SHORT_TEXT_CHARS ? SHORT_MAX_TOKENS : LONG_MAX_TOKENS;
+        return callMessages(opts, deps, {
+            system: buildSystemPrompt(from, to, glossary),
+            user: chunk,
+            maxTokens,
+        });
+    }
+}
+// --- small helpers (client.ts's guard patterns, kept local) -----------------
+function isAbortError(err) {
+    return (err !== null && typeof err === 'object' && err.name === 'AbortError');
+}
+const redact = (text, key) => key === '' || !text.includes(key) ? text : text.split(key).join('<redacted>');
+const snippetOf = (text) => text.length <= 200 ? text : `${text.slice(0, 200)}…`;
+async function readTextSafely(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return '';
+    }
+}

package/dist/wiki/assets.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Asset upload via POST /u (wiki.js multipart endpoint, pitfall #7).
+ *
+ * Body: FormData, field `mediaUpload` (filename = sanitizeAssetName(filename)).
+ * Optional `parent` field carries numeric folderId for folder-scoped uploads.
+ * Auth: Bearer token. Api key is INJECTED via `deps.apiKey` — resolution
+ * lives in the caller (tools layer, todo 11, via readWikiApiKey), so this
+ * module stays network- and config-free (pure + injected, trivially testable).
+ *
+ * Response JSON: `{type:'success', location}` or `{type:'error', msg}`.
+ * Non-JSON and timeouts → AssetUploadError (message names 'timeout').
+ */
+/** Server-rejected upload or transport failure. `serverMsg` carries the
+ *  wiki.js `msg` field on server errors; empty on transport failures. */
+export declare class AssetUploadError extends Error {
+    readonly serverMsg: string;
+    constructor(message: string, serverMsg?: string);
+}
+/**
+ * Lowercase; ` `/`,`/`;`/`#` → `_`; collapse `_+`; strip leading `_`;
+ * preserve the extension (last dot group) lowercased. Fallback `'asset'`
+ * on empty / degenerate inputs. Invariant: never produces `'..'`.
+ * Non-ASCII letters are preserved (only named chars above are replaced).
+ */
+export declare function sanitizeAssetName(name: string): string;
+export interface AssetUploadResult {
+    readonly url: string;
+    readonly name: string;
+    readonly size: number;
+}
+export interface UploadDeps {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly fetchImpl?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+export interface UploadFile {
+    readonly bytes: Uint8Array | string;
+    readonly filename: string;
+}
+/** POST a single file to /u. Returns {url, sanitizedName, byteLength}. */
+export declare function uploadAsset(deps: UploadDeps, file: UploadFile, folderId?: number): Promise<AssetUploadResult>;

package/dist/wiki/assets.js

@@ -0,0 +1,91 @@
+/**
+ * Asset upload via POST /u (wiki.js multipart endpoint, pitfall #7).
+ *
+ * Body: FormData, field `mediaUpload` (filename = sanitizeAssetName(filename)).
+ * Optional `parent` field carries numeric folderId for folder-scoped uploads.
+ * Auth: Bearer token. Api key is INJECTED via `deps.apiKey` — resolution
+ * lives in the caller (tools layer, todo 11, via readWikiApiKey), so this
+ * module stays network- and config-free (pure + injected, trivially testable).
+ *
+ * Response JSON: `{type:'success', location}` or `{type:'error', msg}`.
+ * Non-JSON and timeouts → AssetUploadError (message names 'timeout').
+ */
+// --- Error ------------------------------------------------------------------
+/** Server-rejected upload or transport failure. `serverMsg` carries the
+ *  wiki.js `msg` field on server errors; empty on transport failures. */
+export class AssetUploadError extends Error {
+    serverMsg;
+    constructor(message, serverMsg = '') {
+        super(message);
+        this.name = 'AssetUploadError';
+        this.serverMsg = serverMsg;
+    }
+}
+// --- sanitizeAssetName ------------------------------------------------------
+/**
+ * Lowercase; ` `/`,`/`;`/`#` → `_`; collapse `_+`; strip leading `_`;
+ * preserve the extension (last dot group) lowercased. Fallback `'asset'`
+ * on empty / degenerate inputs. Invariant: never produces `'..'`.
+ * Non-ASCII letters are preserved (only named chars above are replaced).
+ */
+export function sanitizeAssetName(name) {
+    if (name === '')
+        return 'asset';
+    const dot = name.lastIndexOf('.');
+    const hasExt = dot > 0 && dot < name.length - 1;
+    const base = (hasExt ? name.slice(0, dot) : name)
+        .toLowerCase()
+        .replace(/[ ,;#]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_+/, '');
+    if (base === '' || base.includes('..'))
+        return 'asset';
+    return hasExt ? `${base}.${name.slice(dot + 1).toLowerCase()}` : base;
+}
+const DEFAULT_TIMEOUT_MS = 30_000;
+function isAbort(err) {
+    return err != null && typeof err === 'object' && err.name === 'AbortError';
+}
+/** POST a single file to /u. Returns {url, sanitizedName, byteLength}. */
+export async function uploadAsset(deps, file, folderId) {
+    const url = `${deps.baseUrl.replace(/\/+$/, '')}/u`;
+    const name = sanitizeAssetName(file.filename);
+    const bytes = typeof file.bytes === 'string' ? new TextEncoder().encode(file.bytes) : file.bytes;
+    const form = new FormData();
+    form.set('mediaUpload', new File([bytes], name));
+    if (folderId !== undefined)
+        form.set('parent', String(folderId));
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let res;
+    try {
+        res = await (deps.fetchImpl ?? fetch)(url, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${deps.apiKey}` },
+            body: form,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        const detail = isAbort(err) ? `timeout after ${timeoutMs}ms` : err.message;
+        throw new AssetUploadError(`asset upload to ${url} ${detail}`);
+    }
+    const text = await res.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw new AssetUploadError(`asset upload to ${url} returned non-JSON (HTTP ${res.status})`);
+    }
+    const type = body?.type;
+    if (type === 'success') {
+        const loc = body.location;
+        return { url: typeof loc === 'string' ? loc : '', name, size: bytes.byteLength };
+    }
+    if (type === 'error') {
+        const msg = body.msg;
+        const s = typeof msg === 'string' ? msg : 'asset upload rejected by server';
+        throw new AssetUploadError(s, s);
+    }
+    throw new AssetUploadError(`asset upload to ${url} returned unexpected payload (HTTP ${res.status})`);
+}

package/dist/wiki/client.d.ts

@@ -0,0 +1,67 @@
+/**
+ * wiki.js GraphQL client with three-layer error discrimination.
+ *
+ * Every failure from `gql` surfaces as one of four named, structured errors —
+ * never a raw fetch/parse exception:
+ *
+ *   1. HTTP status outside 2xx          -> HttpError (401/403 -> PermissionError)
+ *   2. Body that is not parseable JSON  -> HttpError ('non-json response')
+ *   3. Top-level GraphQL `errors[]`     -> GraphQLError
+ *   4. Payload `responseResult.succeeded === false` -> WikiError (permission-ish
+ *      errorCode/message -> PermissionError, the class the plan's R-b contract
+ *      refers to). The responseResult lookup is field-name agnostic: wiki.js
+ *      wraps every pages.* operation's result key, so we inspect the first key
+ *      of `data` (pitfall #3).
+ *
+ * The api key is resolved eagerly at createClient time (ConfigError
+ * propagates) and retained in a module-private WeakMap — never an enumerable
+ * client field, never embedded in any thrown message (bodies are redacted
+ * before they become snippets or GraphQL error text).
+ *
+ * The responseResult lookup is field-name agnostic — the operation name is
+ * never hardcoded. Two nesting shapes occur: the live instance nests it as
+ * `data.pages.<op>.responseResult` (PageMutation -> PageResponse), and a flat
+ * variant sits as `data.<root-field>.responseResult`. Both are covered.
+ */
+import { type HistorianOptions } from '../config.js';
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export interface RawGraphQLError {
+    readonly message: string;
+    readonly path?: readonly (string | number)[];
+}
+/** Transport/parse-layer failure: non-2xx status, unparseable or malformed
+ *  bodies, timeouts (status 0 = no HTTP response was received). */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly bodySnippet: string;
+    readonly url: string;
+    constructor(message: string, status: number, bodySnippet: string, url: string);
+}
+/** GraphQL-layer failure: the server answered 2xx but reported errors[]. */
+export declare class GraphQLError extends Error {
+    readonly rawErrors: readonly RawGraphQLError[];
+    constructor(message: string, rawErrors: readonly RawGraphQLError[]);
+}
+/** Wiki.js payload-layer failure: responseResult.succeeded === false. */
+export declare class WikiError extends Error {
+    readonly errorCode: string;
+    readonly slug: string;
+    constructor(errorCode: string, slug: string, message: string);
+}
+/** Permission failures from either layer — HTTP 401/403 or a permission-ish
+ *  payload errorCode/message. Named per plan R-b (wiki token scope shortage). */
+export declare class PermissionError extends WikiError {
+    constructor(errorCode: string, slug: string, message: string);
+}
+export interface GqlClient {
+    readonly baseUrl: string;
+    readonly fetchImpl: typeof fetch;
+    readonly timeoutMs: number;
+}
+export declare function createClient(options: HistorianOptions, deps?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+}): GqlClient;
+export declare function gql<T>(client: GqlClient, query: string, vars: Record<string, unknown>): Promise<T>;