opencode-wiki-historian 0.2.0

package/dist/wiki/client.js

@@ -0,0 +1,221 @@
+/**
+ * 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 { readWikiApiKey } from '../config.js';
+import { isRecord } from '../jsonc.js';
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/** Transport/parse-layer failure: non-2xx status, unparseable or malformed
+ *  bodies, timeouts (status 0 = no HTTP response was received). */
+export class HttpError extends Error {
+    status;
+    bodySnippet;
+    url;
+    constructor(message, status, bodySnippet, url) {
+        super(message);
+        this.name = 'HttpError';
+        this.status = status;
+        this.bodySnippet = bodySnippet;
+        this.url = url;
+    }
+}
+/** GraphQL-layer failure: the server answered 2xx but reported errors[]. */
+export class GraphQLError extends Error {
+    rawErrors;
+    constructor(message, rawErrors) {
+        super(message);
+        this.name = 'GraphQLError';
+        this.rawErrors = rawErrors;
+    }
+}
+/** Wiki.js payload-layer failure: responseResult.succeeded === false. */
+export class WikiError extends Error {
+    errorCode;
+    slug;
+    constructor(errorCode, slug, message) {
+        super(message);
+        this.name = 'WikiError';
+        this.errorCode = errorCode;
+        this.slug = slug;
+    }
+}
+/** 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 class PermissionError extends WikiError {
+    constructor(errorCode, slug, message) {
+        super(errorCode, slug, message);
+        this.name = 'PermissionError';
+    }
+}
+/** Api keys live here, keyed by client identity — never on the client object
+ *  (which would make them enumerable/loggable) and never in messages. */
+const keys = new WeakMap();
+export function createClient(options, deps) {
+    const client = {
+        baseUrl: options.baseUrl,
+        fetchImpl: deps?.fetchImpl ?? fetch,
+        timeoutMs: deps?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    };
+    keys.set(client, readWikiApiKey(options, deps?.env, deps?.homeDir));
+    return client;
+}
+// --- Helpers ----------------------------------------------------------------
+const PERMISSION_PATTERN = /permission|forbidden|denied|unauthorized|not\.authorized|access/i;
+function isAbortError(err) {
+    return (err !== null &&
+        typeof err === 'object' &&
+        err.name === 'AbortError');
+}
+function errorMessageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Replaces the secret with a placeholder so body-derived text can never leak
+ *  it into errors. Applied before any snippet or GraphQL message is built. */
+function redact(text, key) {
+    return key === '' || !text.includes(key) ? text : text.split(key).join('<redacted>');
+}
+function snippetOf(text) {
+    const MAX = 200;
+    return text.length <= MAX ? text : `${text.slice(0, MAX)}…`;
+}
+async function readTextSafely(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return '';
+    }
+}
+function asString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function toRawError(value) {
+    if (isRecord(value)) {
+        const message = asString(value.message) || 'graphql error';
+        const path = Array.isArray(value.path)
+            ? value.path.filter((p) => typeof p === 'string' || typeof p === 'number')
+            : undefined;
+        return path === undefined ? { message } : { message, path };
+    }
+    return { message: JSON.stringify(value) };
+}
+/** wiki.js wraps every pages.* operation result in a `responseResult` object
+ *  (pitfall #3); the operation name varies, so neither the root field nor the
+ *  operation field is hardcoded. Two nesting shapes are checked:
+ *  `data.<root>.<op>.responseResult` (live instance: PageMutation ->
+ *  PageResponse) and the flat `data.<root>.responseResult` wrapper. Plain
+ *  query results (e.g. `data.pages.list` arrays) expose no responseResult and
+ *  pass through untouched. */
+function findResponseResult(data) {
+    const firstKey = Object.keys(data)[0];
+    if (firstKey === undefined)
+        return undefined;
+    const value = data[firstKey];
+    if (!isRecord(value))
+        return undefined;
+    // Shape 1: data.<root>.responseResult
+    const direct = value.responseResult;
+    if (isRecord(direct))
+        return direct;
+    // Shape 2: data.<root>.<op>.responseResult
+    const secondKey = Object.keys(value)[0];
+    if (secondKey === undefined)
+        return undefined;
+    const nested = value[secondKey];
+    if (!isRecord(nested))
+        return undefined;
+    const viaNested = nested.responseResult;
+    return isRecord(viaNested) ? viaNested : undefined;
+}
+function isPermissionish(errorCode, message) {
+    return PERMISSION_PATTERN.test(errorCode) || PERMISSION_PATTERN.test(message);
+}
+function transportFailure(err, key, url, timeoutMs) {
+    if (isAbortError(err)) {
+        return new HttpError(`graphql request to ${url} timed out after ${timeoutMs}ms`, 0, '', url);
+    }
+    return new HttpError(`graphql request to ${url} failed: ${redact(errorMessageOf(err), key)}`, 0, '', url);
+}
+// --- gql --------------------------------------------------------------------
+export async function gql(client, query, vars) {
+    const url = `${client.baseUrl}/graphql`;
+    const key = keys.get(client);
+    if (key === undefined) {
+        throw new Error('gql: client is not bound to a wiki api key (create it via createClient)');
+    }
+    let res;
+    try {
+        res = await client.fetchImpl(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+            body: JSON.stringify({ query, variables: vars }),
+            signal: AbortSignal.timeout(client.timeoutMs),
+        });
+    }
+    catch (err) {
+        throw transportFailure(err, key, url, client.timeoutMs);
+    }
+    const rawBody = redact(await readTextSafely(res), key);
+    // Layer 1: HTTP status.
+    if (res.status < 200 || res.status >= 300) {
+        const snippet = snippetOf(rawBody);
+        if (res.status === 401 || res.status === 403) {
+            throw new PermissionError(`http-${res.status}`, '', `HTTP ${res.status} from ${url}: ${snippet === '' ? 'permission denied' : snippet}`);
+        }
+        throw new HttpError(`HTTP ${res.status} from ${url}`, res.status, snippet, url);
+    }
+    // Layer 2: parseable JSON body.
+    let parsed;
+    try {
+        parsed = JSON.parse(rawBody);
+    }
+    catch {
+        throw new HttpError('non-json response', res.status, snippetOf(rawBody), url);
+    }
+    if (!isRecord(parsed)) {
+        throw new HttpError('response body is not a JSON object', res.status, snippetOf(rawBody), url);
+    }
+    // Layer 3: top-level GraphQL errors.
+    const errors = parsed.errors;
+    if (Array.isArray(errors) && errors.length > 0) {
+        const rawErrors = errors.map(toRawError);
+        throw new GraphQLError(rawErrors.map((e) => e.message).join(' | '), rawErrors);
+    }
+    // Layer 4: wiki.js payload convention (pitfall #3).
+    const data = parsed.data;
+    if (!isRecord(data)) {
+        throw new HttpError('response missing data field', res.status, snippetOf(rawBody), url);
+    }
+    const responseResult = findResponseResult(data);
+    if (responseResult !== undefined && responseResult.succeeded === false) {
+        const errorCode = asString(responseResult.errorCode);
+        const slug = asString(responseResult.slug);
+        const message = asString(responseResult.message);
+        if (isPermissionish(errorCode, message)) {
+            throw new PermissionError(errorCode, slug, message || `permission denied (${errorCode})`);
+        }
+        throw new WikiError(errorCode, slug, message || `operation failed (${errorCode})`);
+    }
+    return data;
+}

package/dist/wiki/locale.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Path validation + locale URL model.
+ *
+ * This module is the boundary parser for wiki.js URLs: every path segment
+ * must be safe for the wiki.js router (no path traversal, no reserved words
+ * that collide with wiki.js's own endpoints, no locale-shaped first segments
+ * that wiki.js `parsePath` would reinterpret as a namespace prefix — pitfall
+ * #9). Errors are thrown as `PathValidationError` with ACTIONABLE messages
+ * naming the offending segment + the rule, so callers (pages.ts, tools.ts)
+ * surface the diagnostic directly to the user.
+ */
+export declare class PathValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reject paths that wiki.js would misinterpret or that are unsafe:
+ *
+ *  1. empty / whitespace-only
+ *  2. absolute (leading `/`)
+ *  3. contains `..` (path traversal)
+ *  4. contains space, backslash, or `//` (wiki.js URL-unsafe)
+ *  5. first segment matches the locale shape (pitfall #9)
+ *  6. any segment is length 1 (wiki.js rejects single-char path components)
+ *  7. any segment contains characters outside `[A-Za-z0-9._-]`
+ *  8. any segment is a reserved word (wiki.js endpoint collision)
+ *
+ * Order matters: cheap substring checks first, then per-segment rules.
+ * Every rejection names the offending segment + the rule in the message.
+ */
+export declare function validatePath(p: string): void;
+/**
+ * Map a locale input to the instance's active locale set (en | zh).
+ *
+ * Whitelist (case-insensitive):
+ *  - 'en', 'en-<region>'  -> 'en'
+ *  - 'zh', 'zh-cn'        -> 'zh'
+ *
+ * Everything else (including 'zh-tw', 'zh-hant', 'de', '') throws
+ * PathValidationError naming the input. Silent mapping of unsupported
+ * variants (e.g. zh-tw -> zh) would hide config drift, so it is forbidden.
+ */
+export declare function normalizeLocale(l: string): 'en' | 'zh';
+/**
+ * Compose `<baseUrl>/<locale>/<path>` with a single slash between each part.
+ * Trailing slashes on baseUrl are stripped. Caller must pass a normalized
+ * locale (run normalizeLocale first); path is validated via validatePath.
+ */
+export declare function localeUrl(baseUrl: string, locale: 'en' | 'zh', path: string): string;
+/**
+ * Return the other locale of the (en, zh) pair. Exhaustive switch — no
+ * default leg; the TS compiler enforces completeness at compile time.
+ */
+export declare function twinOf(locale: 'en' | 'zh'): 'en' | 'zh';
+export interface LocalePair {
+    readonly path: string;
+    readonly locale: 'en' | 'zh';
+    readonly url: string;
+    readonly twinLocale: 'en' | 'zh';
+    readonly twinUrl: string;
+}
+/**
+ * Build the (url, twinUrl) pair for a path at the given locale. Used by
+ * pages.ts to return both the canonical URL and its twin in every tool
+ * result (plan contract: every page op returns both URLs).
+ */
+export declare function assertLocalePair(path: string, locale: 'en' | 'zh', baseUrl: string): LocalePair;

package/dist/wiki/locale.js

@@ -0,0 +1,154 @@
+/**
+ * Path validation + locale URL model.
+ *
+ * This module is the boundary parser for wiki.js URLs: every path segment
+ * must be safe for the wiki.js router (no path traversal, no reserved words
+ * that collide with wiki.js's own endpoints, no locale-shaped first segments
+ * that wiki.js `parsePath` would reinterpret as a namespace prefix — pitfall
+ * #9). Errors are thrown as `PathValidationError` with ACTIONABLE messages
+ * naming the offending segment + the rule, so callers (pages.ts, tools.ts)
+ * surface the diagnostic directly to the user.
+ */
+// --- Error ------------------------------------------------------------------
+export class PathValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PathValidationError';
+    }
+}
+// --- Constants --------------------------------------------------------------
+const RESERVED_WORDS = new Set([
+    'home',
+    'login',
+    'register',
+    'graphql',
+    'healthz',
+    '_assets',
+    'favicon',
+]);
+// wiki.js parsePath treats ANY 2-letter (or 2-letter + dash + 2-letter) first
+// segment as a locale candidate. Rejecting shape-matches (not a fixed list) is
+// the only way to stop wiki.js from silently reinterpreting `zh/foo` as
+// "locale=zh, path=foo" and creating a duplicate namespace. This applies
+// equally to `xy/foo` — the shape is the danger, not the specific letters.
+const LOCALE_SHAPE = /^[A-Za-z]{2}(-[A-Za-z]{2})?$/;
+const SEGMENT_CHARS = /^[A-Za-z0-9._-]+$/;
+// --- validatePath -----------------------------------------------------------
+/**
+ * Reject paths that wiki.js would misinterpret or that are unsafe:
+ *
+ *  1. empty / whitespace-only
+ *  2. absolute (leading `/`)
+ *  3. contains `..` (path traversal)
+ *  4. contains space, backslash, or `//` (wiki.js URL-unsafe)
+ *  5. first segment matches the locale shape (pitfall #9)
+ *  6. any segment is length 1 (wiki.js rejects single-char path components)
+ *  7. any segment contains characters outside `[A-Za-z0-9._-]`
+ *  8. any segment is a reserved word (wiki.js endpoint collision)
+ *
+ * Order matters: cheap substring checks first, then per-segment rules.
+ * Every rejection names the offending segment + the rule in the message.
+ */
+export function validatePath(p) {
+    if (p.trim() === '') {
+        throw new PathValidationError(`path is empty or whitespace-only (got ${JSON.stringify(p)})`);
+    }
+    if (p.startsWith('/')) {
+        throw new PathValidationError(`path must not be absolute (got leading '/'; drop the leading slash)`);
+    }
+    if (p.includes('..')) {
+        throw new PathValidationError(`path contains '..' (path traversal; remove any '..' segment)`);
+    }
+    if (p.includes(' ')) {
+        throw new PathValidationError(`path contains a space character (spaces are URL-unsafe in wiki.js paths)`);
+    }
+    if (p.includes('\\')) {
+        throw new PathValidationError(`path contains a backslash (use '/' as the segment separator)`);
+    }
+    if (p.includes('//')) {
+        throw new PathValidationError(`path contains '//' (empty segment between two slashes; remove the duplicate separator)`);
+    }
+    const segments = p.split('/');
+    const first = segments[0];
+    if (first === undefined) {
+        throw new PathValidationError(`path has no segments (got ${JSON.stringify(p)})`);
+    }
+    if (LOCALE_SHAPE.test(first)) {
+        throw new PathValidationError(`first segment '${first}' matches the locale shape (2 letters, optionally +dash+2 letters); ` +
+            `wiki.js would reinterpret it as a namespace prefix — use a longer or digit-bearing name`);
+    }
+    for (const seg of segments) {
+        if (seg.length === 1) {
+            throw new PathValidationError(`segment '${seg}' has length 1 (wiki.js rejects single-character path segments)`);
+        }
+        if (!SEGMENT_CHARS.test(seg)) {
+            throw new PathValidationError(`segment '${seg}' contains invalid characters (allowed: [A-Za-z0-9._-])`);
+        }
+        if (RESERVED_WORDS.has(seg.toLowerCase())) {
+            throw new PathValidationError(`segment '${seg}' is a reserved wiki.js word (home|login|register|graphql|healthz|_assets|favicon)`);
+        }
+    }
+}
+// --- normalizeLocale --------------------------------------------------------
+/**
+ * Map a locale input to the instance's active locale set (en | zh).
+ *
+ * Whitelist (case-insensitive):
+ *  - 'en', 'en-<region>'  -> 'en'
+ *  - 'zh', 'zh-cn'        -> 'zh'
+ *
+ * Everything else (including 'zh-tw', 'zh-hant', 'de', '') throws
+ * PathValidationError naming the input. Silent mapping of unsupported
+ * variants (e.g. zh-tw -> zh) would hide config drift, so it is forbidden.
+ */
+export function normalizeLocale(l) {
+    const lower = l.toLowerCase();
+    if (lower === 'en')
+        return 'en';
+    if (lower === 'zh')
+        return 'zh';
+    if (lower === 'zh-cn')
+        return 'zh';
+    if (lower.startsWith('en-'))
+        return 'en';
+    throw new PathValidationError(`unsupported locale '${l}' (instance whitelist: en, zh, en-<region>, zh-cn)`);
+}
+// --- localeUrl --------------------------------------------------------------
+/**
+ * Compose `<baseUrl>/<locale>/<path>` with a single slash between each part.
+ * Trailing slashes on baseUrl are stripped. Caller must pass a normalized
+ * locale (run normalizeLocale first); path is validated via validatePath.
+ */
+export function localeUrl(baseUrl, locale, path) {
+    validatePath(path);
+    const base = baseUrl.replace(/\/+$/, '');
+    return `${base}/${locale}/${path}`;
+}
+// --- twinOf ----------------------------------------------------------------
+/**
+ * Return the other locale of the (en, zh) pair. Exhaustive switch — no
+ * default leg; the TS compiler enforces completeness at compile time.
+ */
+export function twinOf(locale) {
+    switch (locale) {
+        case 'en':
+            return 'zh';
+        case 'zh':
+            return 'en';
+    }
+}
+/**
+ * Build the (url, twinUrl) pair for a path at the given locale. Used by
+ * pages.ts to return both the canonical URL and its twin in every tool
+ * result (plan contract: every page op returns both URLs).
+ */
+export function assertLocalePair(path, locale, baseUrl) {
+    const twin = twinOf(locale);
+    return {
+        path,
+        locale,
+        url: localeUrl(baseUrl, locale, path),
+        twinLocale: twin,
+        twinUrl: localeUrl(baseUrl, twin, path),
+    };
+}

package/dist/wiki/pages.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Page operations facade — re-exports the read and write halves so callers
+ * import a single module. The split (pages.read.ts / pages.write.ts) keeps
+ * every source file under the 250-LOC ceiling.
+ */
+export * from './pages.read.js';
+export * from './pages.write.js';

package/dist/wiki/pages.js

@@ -0,0 +1,7 @@
+/**
+ * Page operations facade — re-exports the read and write halves so callers
+ * import a single module. The split (pages.read.ts / pages.write.ts) keeps
+ * every source file under the 250-LOC ceiling.
+ */
+export * from './pages.read.js';
+export * from './pages.write.js';

package/dist/wiki/pages.read.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Page READ operations (readPage, searchPages) + the shared page types.
+ *
+ * Split from pages.ts (write ops live in pages.write.ts) to keep every source
+ * file under the 250-LOC ceiling. Field names are LIVE-INTROSPECTED on the
+ * running wiki.js instance (anonymous __schema), never guessed:
+ *
+ *   - singleByPath(path, locale) — locale is REQUIRED (pitfall #9)
+ *   - a missing page answers with a top-level GraphQL error whose message
+ *     contains 'does not exist' (live-verified) → surfaced as a null read
+ *   - Page.tag is a nested PageTag object { tag, ... } → mapped to strings
+ */
+import { type GqlClient } from './client.js';
+export type Locale = 'en' | 'zh';
+/** Port for todo 8 (real translation engine); pages.write injects it. */
+export type TranslateFn = (text: string, from: Locale, to: Locale) => Promise<string>;
+export interface PageRecord {
+    readonly id: number;
+    readonly path: string;
+    readonly locale: Locale;
+    readonly title: string;
+    readonly description: string;
+    readonly content: string;
+    readonly isPublished: boolean;
+    readonly isPrivate: boolean;
+    readonly contentType: string;
+    readonly tags: readonly string[];
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface SearchOptions {
+    readonly path?: string;
+    readonly locale?: Locale;
+}
+export interface PageSearchResult {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    readonly path: string;
+    readonly locale: string;
+}
+export interface PageSearchResponse {
+    readonly results: readonly PageSearchResult[];
+    readonly suggestions: readonly string[];
+    readonly totalHits: number;
+}
+/** One pages.list row (live-introspected: tags arrive as flat strings, unlike
+ *  Page's nested PageTag objects; privateNS is null unless the page lives in a
+ *  private namespace). */
+export interface PageListItem {
+    readonly id: number;
+    readonly path: string;
+    readonly locale: Locale;
+    readonly title: string;
+    readonly description: string;
+    readonly contentType: string;
+    readonly isPublished: boolean;
+    readonly isPrivate: boolean;
+    readonly privateNS: string | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly tags: readonly string[];
+}
+export interface ListPagesOptions {
+    readonly locale?: Locale;
+    readonly tags?: readonly string[];
+}
+interface RawPageShape {
+    readonly id: unknown;
+    readonly path: unknown;
+    readonly locale: unknown;
+    readonly title: unknown;
+    readonly description: unknown;
+    readonly content: unknown;
+    readonly isPublished: unknown;
+    readonly isPrivate: unknown;
+    readonly contentType: unknown;
+    readonly tags: unknown;
+    readonly createdAt: unknown;
+    readonly updatedAt: unknown;
+}
+export declare function str(v: unknown): string;
+export declare function bool(v: unknown): boolean;
+export declare function num(v: unknown): number;
+/** PageTag { tag, ... } → plain string[] (live read type nests tags). */
+export declare function mapTags(v: unknown): readonly string[];
+export declare function mapPage(raw: RawPageShape): PageRecord;
+interface RawListPageShape {
+    readonly id: unknown;
+    readonly path: unknown;
+    readonly locale: unknown;
+    readonly title: unknown;
+    readonly description: unknown;
+    readonly contentType: unknown;
+    readonly isPublished: unknown;
+    readonly isPrivate: unknown;
+    readonly privateNS: unknown;
+    readonly createdAt: unknown;
+    readonly updatedAt: unknown;
+    readonly tags: unknown;
+}
+export declare function mapListItem(raw: RawListPageShape): PageListItem;
+/** Read a page by (path, locale). A missing page — wiki.js answers with a
+ *  top-level GraphQL error containing 'does not exist' — is a null read;
+ *  every other failure rethrows as-is. */
+export declare function readPage(client: GqlClient, path: string, locale: Locale): Promise<PageRecord | null>;
+/** Full unbounded fetch of pages.list, optionally scoped to one locale and/or
+ *  tags (the list query has NO responseResult — failures surface as top-level
+ *  errors and are rethrown by the gql layer). */
+export declare function listPages(client: GqlClient, opts?: ListPagesOptions): Promise<readonly PageListItem[]>;
+/** Pass-through of pages.search — the response already carries a per-result
+ *  locale and the gql layer leaves it untouched. */
+export declare function searchPages(client: GqlClient, query: string, opts?: SearchOptions): Promise<PageSearchResponse>;
+export {};

package/dist/wiki/pages.read.js

@@ -0,0 +1,114 @@
+/**
+ * Page READ operations (readPage, searchPages) + the shared page types.
+ *
+ * Split from pages.ts (write ops live in pages.write.ts) to keep every source
+ * file under the 250-LOC ceiling. Field names are LIVE-INTROSPECTED on the
+ * running wiki.js instance (anonymous __schema), never guessed:
+ *
+ *   - singleByPath(path, locale) — locale is REQUIRED (pitfall #9)
+ *   - a missing page answers with a top-level GraphQL error whose message
+ *     contains 'does not exist' (live-verified) → surfaced as a null read
+ *   - Page.tag is a nested PageTag object { tag, ... } → mapped to strings
+ */
+import { gql, GraphQLError } from './client.js';
+import { normalizeLocale, validatePath } from './locale.js';
+// --- GraphQL shapes (introspection-verified) --------------------------------
+const READ_FIELDS = 'id path locale title description content isPublished isPrivate contentType tags { tag } createdAt updatedAt';
+const READ_QUERY = `query r($path: String!, $locale: String!) { pages { singleByPath(path: $path, locale: $locale) { ${READ_FIELDS} } } }`;
+const SEARCH_QUERY = `query q($query: String!, $path: String, $locale: String) { pages { search(query: $query, path: $path, locale: $locale) { results { id title description path locale } suggestions totalHits } } }`;
+const LIST_FIELDS = 'id path locale title description contentType isPublished isPrivate privateNS createdAt updatedAt tags';
+const LIST_QUERY = `query l($locale: String, $tags: [String!]) { pages { list(locale: $locale, tags: $tags) { ${LIST_FIELDS} } } }`;
+export function str(v) {
+    return typeof v === 'string' ? v : '';
+}
+export function bool(v) {
+    return v === true;
+}
+export function num(v) {
+    return typeof v === 'number' ? v : Number(str(v));
+}
+/** PageTag { tag, ... } → plain string[] (live read type nests tags). */
+export function mapTags(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.map((t) => {
+        if (t !== null && typeof t === 'object' && 'tag' in t) {
+            return str(t.tag);
+        }
+        return str(t);
+    });
+}
+export function mapPage(raw) {
+    return {
+        id: num(raw.id),
+        path: str(raw.path),
+        locale: normalizeLocale(str(raw.locale)),
+        title: str(raw.title),
+        description: str(raw.description),
+        content: str(raw.content),
+        isPublished: bool(raw.isPublished),
+        isPrivate: bool(raw.isPrivate),
+        contentType: str(raw.contentType),
+        tags: mapTags(raw.tags),
+        createdAt: str(raw.createdAt),
+        updatedAt: str(raw.updatedAt),
+    };
+}
+export function mapListItem(raw) {
+    const privateNS = raw.privateNS;
+    return {
+        id: num(raw.id),
+        path: str(raw.path),
+        locale: normalizeLocale(str(raw.locale)),
+        title: str(raw.title),
+        description: str(raw.description),
+        contentType: str(raw.contentType),
+        isPublished: bool(raw.isPublished),
+        isPrivate: bool(raw.isPrivate),
+        privateNS: typeof privateNS === 'string' && privateNS !== '' ? privateNS : null,
+        createdAt: str(raw.createdAt),
+        updatedAt: str(raw.updatedAt),
+        tags: mapTags(raw.tags),
+    };
+}
+// --- readPage ---------------------------------------------------------------
+/** Read a page by (path, locale). A missing page — wiki.js answers with a
+ *  top-level GraphQL error containing 'does not exist' — is a null read;
+ *  every other failure rethrows as-is. */
+export async function readPage(client, path, locale) {
+    validatePath(path);
+    try {
+        const data = await gql(client, READ_QUERY, {
+            path,
+            locale,
+        });
+        return data.pages.singleByPath === null ? null : mapPage(data.pages.singleByPath);
+    }
+    catch (err) {
+        if (err instanceof GraphQLError && err.message.includes('does not exist'))
+            return null;
+        throw err;
+    }
+}
+// --- listPages --------------------------------------------------------------
+/** Full unbounded fetch of pages.list, optionally scoped to one locale and/or
+ *  tags (the list query has NO responseResult — failures surface as top-level
+ *  errors and are rethrown by the gql layer). */
+export async function listPages(client, opts) {
+    const data = await gql(client, LIST_QUERY, {
+        locale: opts?.locale ?? null,
+        tags: opts?.tags !== undefined && opts.tags.length > 0 ? [...opts.tags] : null,
+    });
+    return data.pages.list.map(mapListItem);
+}
+// --- searchPages ------------------------------------------------------------
+/** Pass-through of pages.search — the response already carries a per-result
+ *  locale and the gql layer leaves it untouched. */
+export async function searchPages(client, query, opts) {
+    const data = await gql(client, SEARCH_QUERY, {
+        query,
+        path: opts?.path ?? null,
+        locale: opts?.locale ?? null,
+    });
+    return data.pages.search;
+}