opencode-wiki-historian 0.2.0

package/dist/tools/local.js

@@ -0,0 +1,107 @@
+/**
+ * historian_translate_snippet + historian_map: tools that never write to the
+ * wiki engine (map refresh writes its cache page + mirror via the engine, but
+ * only on the explicit refresh action). translate_snippet surfaces engine
+ * TranslateError causes as structured output — never a throw.
+ */
+import { tool } from '@opencode-ai/plugin';
+import { TranslateError } from '../translate.js';
+import { buildChronology, filterRowsByPath } from '../chronology.js';
+import { getMap, refreshMapCache, CACHE_PATH } from '../map.js';
+import { errEnvelope, okJson, reportUrls, URL_MANDATE } from './shared.js';
+const s = tool.schema;
+const TRANSLATE_ARGS = {
+    text: s.string(),
+    from: s.enum(['en', 'zh']).default('en'),
+    to: s.enum(['en', 'zh']).default('zh'),
+};
+const TranslateArgsSchema = s.object(TRANSLATE_ARGS);
+// --- historian_translate_snippet ---------------------------------------------
+export function makeTranslateSnippetTool(deps) {
+    return tool({
+        description: `Translate a text snippet with the configured translation engine (pure-local, no wiki interaction). ` +
+            `The engine may emit thinking parts first — only the final translated text is returned. ` +
+            `Read the translation and verify it reads naturally in context before reuse.`,
+        args: TRANSLATE_ARGS,
+        execute: async (raw) => {
+            const args = TranslateArgsSchema.parse(raw);
+            if (deps.translate === undefined) {
+                return JSON.stringify({
+                    ok: false,
+                    error: 'not-wired',
+                    detail: 'No translation engine wired — configure translate (endpoint/model/apiKey) or pass a translator to buildTools.',
+                    actionableHint: 'Wire translation in the plugin config and retry.',
+                }, null, 2);
+            }
+            try {
+                const translated = await deps.translate(args.text, args.from, args.to);
+                return okJson({ translated, from: args.from, to: args.to });
+            }
+            catch (err) {
+                if (err instanceof TranslateError) {
+                    return JSON.stringify({
+                        ok: false,
+                        error: err.cause,
+                        detail: err.detail,
+                        message: err.message,
+                        actionableHint: 'Retry the translation, or use the raw text as-is.',
+                    }, null, 2);
+                }
+                return errEnvelope(err);
+            }
+        },
+    });
+}
+const MAP_ARGS = {
+    action: s.enum(['show', 'refresh', 'timeline']).default('show'),
+    days: s.number().int().positive().optional().describe('timeline: keep only rows updated within the last N days'),
+    path: s.string().optional().describe('timeline: section/path prefix filter (e.g. ops)'),
+};
+const MapArgsSchema = s.object(MAP_ARGS);
+// --- historian_map -----------------------------------------------------------
+export function makeMapTool(deps) {
+    return tool({
+        description: `Inspect (show), rebuild (refresh), or aggregate recent updates (timeline) over the en/zh page map ` +
+            `with its local mirror + _meta/page-map cache page. ` +
+            `show reads the local mirror (zero writes); refresh rebuilds from the wiki and writes the mirror + cache page ` +
+            `(idempotent — the engine upserts via full RMW); timeline groups mirror rows by ISO week (newest first, ` +
+            `optional days window + section/path prefix filter) into a human markdown table + machine-readable weeks JSON. ` +
+            `${URL_MANDATE}.`,
+        args: MAP_ARGS,
+        execute: async (raw) => {
+            const args = MapArgsSchema.parse(raw);
+            try {
+                const mapDeps = { client: deps.getClient(), options: deps.options };
+                if (args.action === 'refresh') {
+                    const result = await refreshMapCache(mapDeps, { homeDir: deps.homeDir });
+                    return okJson({ action: 'refresh', stats: result.stats, cacheUrl: result.cacheUrl });
+                }
+                const snapshot = await getMap(mapDeps, deps.homeDir);
+                if (args.action === 'timeline') {
+                    const rows = args.path === undefined ? snapshot.rows : filterRowsByPath(snapshot.rows, args.path);
+                    const chrono = buildChronology(rows, { days: args.days });
+                    return okJson({
+                        action: 'timeline',
+                        days: args.days ?? null,
+                        pathPrefix: args.path ?? null,
+                        generatedAt: snapshot.generatedAt,
+                        rows: rows.length,
+                        weeks: chrono.weeks,
+                        markdown: chrono.markdown,
+                        urls: reportUrls(deps.options.baseUrl, CACHE_PATH, 'en'),
+                    });
+                }
+                return okJson({
+                    action: 'show',
+                    generatedAt: snapshot.generatedAt,
+                    staleSeconds: snapshot.staleSeconds,
+                    stats: snapshot.stats,
+                    rows: snapshot.rows,
+                });
+            }
+            catch (err) {
+                return errEnvelope(err);
+            }
+        },
+    });
+}

package/dist/tools/mutate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * historian_delete + historian_move + historian_migrate: destructive ops are
+ * gated on confirm:"yes" BEFORE any fetch; migrate runs the todo-14 engine —
+ * dry-run (LLM restyle + deterministic checklist, no writes) or apply
+ * (pre-image backup first, per-locale upsert, checkpoint, verification).
+ */
+import { type ToolDefinition } from '@opencode-ai/plugin';
+import { type ToolDeps } from './shared.js';
+export declare function makeDeleteTool(deps: ToolDeps): ToolDefinition;
+export declare function makeMoveTool(deps: ToolDeps): ToolDefinition;
+export declare function makeMigrateTool(deps: ToolDeps): ToolDefinition;

package/dist/tools/mutate.js

@@ -0,0 +1,157 @@
+/**
+ * historian_delete + historian_move + historian_migrate: destructive ops are
+ * gated on confirm:"yes" BEFORE any fetch; migrate runs the todo-14 engine —
+ * dry-run (LLM restyle + deterministic checklist, no writes) or apply
+ * (pre-image backup first, per-locale upsert, checkpoint, verification).
+ */
+import { tool } from '@opencode-ai/plugin';
+import { deletePage, movePage } from '../wiki/pages.js';
+import { selfReviewChecklist } from '../templates/genres.js';
+import { confirmRequiredJson, errEnvelope, okJson, urlPair, URL_MANDATE, pageDeps } from './shared.js';
+import { reformatPageDraft } from '../migrate.js';
+import { applyMigration } from '../migrate-apply.js';
+const s = tool.schema;
+const GENRES = ['G1', 'G2', 'G3', 'G4', 'G5'];
+const DELETE_ARGS = {
+    path: s.string(),
+    locale: s.enum(['en', 'zh']).default('en'),
+    confirm: s.string().optional().describe('Must be exactly "yes" to delete'),
+};
+const DeleteArgsSchema = s.object(DELETE_ARGS);
+// --- historian_delete --------------------------------------------------------
+export function makeDeleteTool(deps) {
+    return tool({
+        description: `Delete a wiki page. Requires the explicit acknowledgement confirm:"yes" — anything else is ` +
+            `refused before the wiki is even contacted. ${URL_MANDATE}.`,
+        args: DELETE_ARGS,
+        execute: async (raw) => {
+            const args = DeleteArgsSchema.parse(raw);
+            if (args.confirm !== 'yes')
+                return confirmRequiredJson('historian_delete', args.confirm);
+            try {
+                const result = await deletePage(pageDeps(deps), args.path, args.locale, 'yes');
+                return okJson({
+                    mode: 'delete',
+                    path: args.path,
+                    locale: args.locale,
+                    pageId: result.pageId,
+                    urls: urlPair(result),
+                });
+            }
+            catch (err) {
+                return errEnvelope(err);
+            }
+        },
+    });
+}
+const MOVE_ARGS = {
+    path: s.string(),
+    locale: s.enum(['en', 'zh']).default('en'),
+    newPath: s.string().describe('Destination path (first segment must NOT look like a locale code)'),
+    newLocale: s.enum(['en', 'zh']).optional(),
+    confirm: s.string().optional().describe('Must be exactly "yes" to move'),
+};
+const MoveArgsSchema = s.object(MOVE_ARGS);
+// --- historian_move ----------------------------------------------------------
+export function makeMoveTool(deps) {
+    return tool({
+        description: `Move a wiki page to a new path (optionally a new locale). Requires the explicit acknowledgement ` +
+            `confirm:"yes". Reports the NEW page URLs. ${URL_MANDATE}.`,
+        args: MOVE_ARGS,
+        execute: async (raw) => {
+            const args = MoveArgsSchema.parse(raw);
+            if (args.confirm !== 'yes')
+                return confirmRequiredJson('historian_move', args.confirm);
+            try {
+                const destLocale = args.newLocale ?? args.locale;
+                const result = await movePage(pageDeps(deps), args.path, args.locale, args.newPath, destLocale, 'yes');
+                return okJson({
+                    mode: 'move',
+                    from: { path: args.path, locale: args.locale },
+                    path: result.path,
+                    locale: result.locale,
+                    pageId: result.pageId,
+                    urls: urlPair(result),
+                });
+            }
+            catch (err) {
+                return errEnvelope(err);
+            }
+        },
+    });
+}
+const MIGRATE_ARGS = {
+    path: s.string(),
+    genre: s.enum(GENRES).optional().describe('Explicit genre; absent → engine classification of the page content'),
+    apply: s.boolean().default(false).describe('true → apply the migration: pre-image backup first, per-locale upsert, checkpoint'),
+};
+const MigrateArgsSchema = s.object(MIGRATE_ARGS);
+// --- historian_migrate -------------------------------------------------------
+/** MigrateDeps built from the tool deps; the engine reaches the LLM through
+ *  the injected fetchImpl (mocked in tests, real fetch in production). */
+function migrateDeps(deps) {
+    return {
+        client: deps.getClient(),
+        options: deps.options,
+        translate: deps.translate,
+        fetchImpl: deps.fetchImpl,
+        homeDir: deps.homeDir,
+        resultsDir: deps.resultsDir,
+    };
+}
+export function makeMigrateTool(deps) {
+    return tool({
+        description: `Migration of a legacy page into a genre skeleton: reads the page (en, or zh fallback), ` +
+            `reformats it via the LLM to the suggested genre (explicit arg wins, else engine classification) ` +
+            `and scores the 10-item self-review checklist on the DRAFT. Dry-run writes nothing. ` +
+            `apply=true persists: pre-image backup FIRST (results/pilot-backup-<section>-<date>.json), then ` +
+            `a per-locale upsert (missing twin auto-created via the translation engine) and a path-level ` +
+            `checkpoint (re-apply of unchanged content is a no-op). ${URL_MANDATE}.`,
+        args: MIGRATE_ARGS,
+        execute: async (raw) => {
+            const args = MigrateArgsSchema.parse(raw);
+            try {
+                const engine = migrateDeps(deps);
+                const dry = await reformatPageDraft(engine, { path: args.path, genre: args.genre });
+                if (!dry.ok)
+                    return errEnvelope(dry.error);
+                if (!args.apply) {
+                    return okJson({
+                        mode: 'dry-run',
+                        path: args.path,
+                        locale: dry.sourceLocale,
+                        suggestedGenre: dry.genre,
+                        genre: dry.genre,
+                        confidence: dry.confidence,
+                        signals: dry.signals,
+                        content: dry.sourceContent,
+                        draft: dry.draft,
+                        alreadyConforms: dry.alreadyConforms,
+                        missingTwin: dry.missingTwin,
+                        checklist: selfReviewChecklist(dry.genre),
+                        checklistResults: dry.checklistResults,
+                        urls: dry.urls,
+                    });
+                }
+                const out = await applyMigration(engine, { path: args.path, genre: dry.genre, draft: dry.draft });
+                if (!out.ok)
+                    return errEnvelope(out.error);
+                return okJson({
+                    mode: 'apply',
+                    path: args.path,
+                    genre: dry.genre,
+                    alreadyConforms: dry.alreadyConforms,
+                    applied: out.applied,
+                    backupPath: out.backupPath,
+                    skipped: out.skipped,
+                    urls: dry.urls,
+                    note: `Pre-image backed up at ${out.backupPath}; restore = replay that file (historian_page_update ` +
+                        `with its fields, historian_delete for locales recorded null) or the wiki.js history view.`,
+                });
+            }
+            catch (err) {
+                return errEnvelope(err);
+            }
+        },
+    });
+}

package/dist/tools/read.d.ts

@@ -0,0 +1,9 @@
+/**
+ * historian_read + historian_search: read-side tools. All URL composition is
+ * reserved-path safe (reportUrls); search results carry per-hit URLs so the
+ * agent never needs a second call to find a page.
+ */
+import { type ToolDefinition } from '@opencode-ai/plugin';
+import { type ToolDeps } from './shared.js';
+export declare function makeReadTool(deps: ToolDeps): ToolDefinition;
+export declare function makeSearchTool(deps: ToolDeps): ToolDefinition;

package/dist/tools/read.js

@@ -0,0 +1,104 @@
+/**
+ * historian_read + historian_search: read-side tools. All URL composition is
+ * reserved-path safe (reportUrls); search results carry per-hit URLs so the
+ * agent never needs a second call to find a page.
+ */
+import { tool } from '@opencode-ai/plugin';
+import { normalizeLocale } from '../wiki/locale.js';
+import { readPage, searchPages } from '../wiki/pages.js';
+import { errEnvelope, okJson, reportUrls, URL_MANDATE } from './shared.js';
+const s = tool.schema;
+const READ_ARGS = {
+    path: s.string(),
+    locale: s.enum(['en', 'zh']).default('en'),
+};
+const ReadArgsSchema = s.object(READ_ARGS);
+// --- historian_read ----------------------------------------------------------
+export function makeReadTool(deps) {
+    return tool({
+        description: `Read a wiki page (path + locale → full content; no raw id). A missing page returns ` +
+            `found:false with a twin hint instead of failing. ${URL_MANDATE}.`,
+        args: READ_ARGS,
+        execute: async (raw) => {
+            const args = ReadArgsSchema.parse(raw);
+            try {
+                const page = await readPage(deps.getClient(), args.path, args.locale);
+                if (page === null) {
+                    const pair = reportUrls(deps.options.baseUrl, args.path, args.locale);
+                    const twinUrl = args.locale === 'en' ? pair.zh : pair.en;
+                    return okJson({
+                        found: false,
+                        path: args.path,
+                        locale: args.locale,
+                        twinHint: `No page at '${args.path}' (${args.locale}). The twin may exist at ${twinUrl} — run historian_map or historian_search to verify.`,
+                    });
+                }
+                return okJson({
+                    found: true,
+                    path: page.path,
+                    locale: page.locale,
+                    page: {
+                        id: page.id,
+                        title: page.title,
+                        description: page.description,
+                        tags: page.tags,
+                        isPublished: page.isPublished,
+                        contentType: page.contentType,
+                        updatedAt: page.updatedAt,
+                    },
+                    content: page.content,
+                    urls: reportUrls(deps.options.baseUrl, page.path, page.locale),
+                });
+            }
+            catch (err) {
+                return errEnvelope(err);
+            }
+        },
+    });
+}
+const SEARCH_ARGS = {
+    query: s.string(),
+    kind: s.enum(['title', 'content']).default('content').describe('Informational intent; the wiki index covers both title and content'),
+};
+const SearchArgsSchema = s.object(SEARCH_ARGS);
+// --- historian_search --------------------------------------------------------
+export function makeSearchTool(deps) {
+    return tool({
+        description: `Full-text search over the wiki. kind is informational intent only — the live wiki.js ` +
+            `search indexes title AND content (the engine signature is search(query, path, locale), no field scope). ` +
+            `Results carry their en/zh URLs. ${URL_MANDATE}.`,
+        args: SEARCH_ARGS,
+        execute: async (raw) => {
+            const args = SearchArgsSchema.parse(raw);
+            try {
+                const resp = await searchPages(deps.getClient(), args.query);
+                const results = resp.results.map((r) => {
+                    try {
+                        const locale = normalizeLocale(r.locale);
+                        return {
+                            id: r.id,
+                            title: r.title,
+                            description: r.description,
+                            path: r.path,
+                            locale: r.locale,
+                            url: reportUrls(deps.options.baseUrl, r.path, locale)[locale],
+                        };
+                    }
+                    catch {
+                        return { id: r.id, title: r.title, description: r.description, path: r.path, locale: r.locale, url: null };
+                    }
+                });
+                return okJson({
+                    query: args.query,
+                    kind: args.kind,
+                    totalHits: resp.totalHits,
+                    suggestions: resp.suggestions,
+                    results,
+                });
+            }
+            catch (err) {
+                return errEnvelope(err);
+            }
+        },
+    });
+}

package/dist/tools/shared.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared plumbing for the historian_* tool surface (todo 11): the tool
+ * dependency bag, locale-aware URL helpers (reserved-path safe), the uniform
+ * JSON envelope helpers and the error → envelope mapping.
+ *
+ * The tools layer is a thin adapter: all wiki logic lives in the engine
+ * modules (src/wiki/*, src/map.ts, src/templates/*, src/translate.ts,
+ * src/migrate*.ts) and is reused verbatim — no business logic is duplicated
+ * here.
+ */
+import type { ToolResult } from '@opencode-ai/plugin';
+import type { GqlClient } from '../wiki/client.js';
+import type { HistorianOptions } from '../config.js';
+import type { PageDeps } from '../wiki/pages.write.js';
+import type { TranslateFn, Locale } from '../wiki/pages.read.js';
+import { type LocalePair } from '../wiki/locale.js';
+/** Per-tool dependency bag; the client is a thunk so a bad key surface at
+ *  buildTools time as nothing — only the first execution that touches the
+ *  wiki resolves it (and then yields a ConfigError envelope, not a crash).
+ *  The thunk is memoized per buildTools call (no module-level cache). */
+export interface ToolDeps {
+    readonly getClient: () => GqlClient;
+    readonly options: HistorianOptions;
+    readonly translate?: TranslateFn;
+    readonly fetchImpl?: typeof fetch;
+    readonly resultsDir?: string;
+    readonly homeDir: string;
+}
+/** Engine deps for one operation; client resolved lazily at use time. */
+export declare function pageDeps(deps: ToolDeps): PageDeps;
+/** Plan-mandated closing sentence for every tool that reports URLs
+ *  (verbatim —「结果必须把 en/zh URL 转述给用户」). */
+export declare const URL_MANDATE = "\u7ED3\u679C\u5FC5\u987B\u628A en/zh URL \u8F6C\u8FF0\u7ED9\u7528\u6237";
+/** Locale-aware engine pair → plain en/zh URL map (the pair is primary-locale
+ *  aware; the agent contract is always {en, zh}). */
+export declare function urlPair(pair: LocalePair): {
+    en: string;
+    zh: string;
+};
+/** URLs for a server-reported path. Mirrors map.ts's *private* urlsOf: a live
+ *  page can legally sit on a reserved path (the instance hosts 'home'), so
+ *  the raw join is the fallback — never a failure — for read-style output.
+ *  map.ts may not be modified, hence the ~10-line reproduction. */
+export declare function reportUrls(baseUrl: string, path: string, locale: Locale): {
+    en: string;
+    zh: string;
+};
+export declare function okJson(body: Record<string, unknown>): ToolResult;
+/** Engine error → uniform failure envelope (never a raw stack). */
+export declare function errEnvelope(err: unknown): ToolResult;
+/** Destructive-action gate: refusal BEFORE any fetch when confirm is absent. */
+export declare function confirmRequiredJson(toolName: string, got: unknown): ToolResult;

package/dist/tools/shared.js

@@ -0,0 +1,87 @@
+/**
+ * Shared plumbing for the historian_* tool surface (todo 11): the tool
+ * dependency bag, locale-aware URL helpers (reserved-path safe), the uniform
+ * JSON envelope helpers and the error → envelope mapping.
+ *
+ * The tools layer is a thin adapter: all wiki logic lives in the engine
+ * modules (src/wiki/*, src/map.ts, src/templates/*, src/translate.ts,
+ * src/migrate*.ts) and is reused verbatim — no business logic is duplicated
+ * here.
+ */
+import { assertLocalePair, PathValidationError } from '../wiki/locale.js';
+/** Engine deps for one operation; client resolved lazily at use time. */
+export function pageDeps(deps) {
+    return { client: deps.getClient(), options: deps.options, translate: deps.translate };
+}
+/** Plan-mandated closing sentence for every tool that reports URLs
+ *  (verbatim —「结果必须把 en/zh URL 转述给用户」). */
+export const URL_MANDATE = '结果必须把 en/zh URL 转述给用户';
+/** Locale-aware engine pair → plain en/zh URL map (the pair is primary-locale
+ *  aware; the agent contract is always {en, zh}). */
+export function urlPair(pair) {
+    return pair.locale === 'en' ? { en: pair.url, zh: pair.twinUrl } : { en: pair.twinUrl, zh: pair.url };
+}
+/** URLs for a server-reported path. Mirrors map.ts's *private* urlsOf: a live
+ *  page can legally sit on a reserved path (the instance hosts 'home'), so
+ *  the raw join is the fallback — never a failure — for read-style output.
+ *  map.ts may not be modified, hence the ~10-line reproduction. */
+export function reportUrls(baseUrl, path, locale) {
+    const raw = (l) => `${baseUrl.replace(/\/+$/, '')}/${l}/${path}`;
+    try {
+        return urlPair(assertLocalePair(path, locale, baseUrl));
+    }
+    catch (err) {
+        if (!(err instanceof PathValidationError))
+            throw err;
+        return { en: raw('en'), zh: raw('zh') };
+    }
+}
+// --- JSON envelopes ----------------------------------------------------------
+const dump = (body) => JSON.stringify(body, null, 2);
+export function okJson(body) {
+    return dump({ ok: true, ...body });
+}
+/** Engine error → uniform failure envelope (never a raw stack). */
+export function errEnvelope(err) {
+    const errorKind = err instanceof Error ? err.name : 'UnknownError';
+    const message = err instanceof Error ? err.message : String(err);
+    return dump({ ok: false, errorKind, message, actionableHint: hintFor(errorKind) });
+}
+/** Destructive-action gate: refusal BEFORE any fetch when confirm is absent. */
+export function confirmRequiredJson(toolName, got) {
+    return dump({
+        ok: false,
+        error: 'confirm-required',
+        errorKind: 'ConfirmRequiredError',
+        message: `${toolName} requires confirm:"yes" (got ${JSON.stringify(got)})`,
+        actionableHint: 'Re-run the tool with confirm:"yes" to acknowledge the destructive action.',
+    });
+}
+/** errorKind (class name) → what the agent should DO. Default covers
+ *  engine-internal errors whose class names map to no dedicated guidance. */
+function hintFor(errorKind) {
+    switch (errorKind) {
+        case 'PathValidationError':
+            return 'Correct the path argument per the error message and retry.';
+        case 'ContentEmptyError':
+            return 'Provide non-empty content, or call historian_page_create without content for a local genre template.';
+        case 'ConfirmRequiredError':
+            return 'Re-run the tool with confirm:"yes" to acknowledge the destructive action.';
+        case 'PageNotFoundError':
+            return 'The page does not exist at that path/locale — run historian_map or historian_read to verify.';
+        case 'PermissionError':
+            return 'The wiki.js token lacks the required scope — check Admin ▸ API Access token groups / page rules (move additionally needs manage:pages).';
+        case 'WikiError':
+            return 'The wiki rejected the operation — inspect message/errorCode and retry.';
+        case 'TranslateError':
+            return 'Translation failed — the page may still be saved with zh_status pending; retry translation later.';
+        case 'ConfigError':
+            return 'Fix the plugin configuration (api key file / env) and retry.';
+        case 'HttpError':
+            return 'The wiki endpoint is unreachable or misconfigured — check baseUrl and network.';
+        case 'GraphQLError':
+            return 'The wiki answered a GraphQL error — check the path/locale arguments.';
+        default:
+            return 'Inspect the message and retry.';
+    }
+}

package/dist/tools/write.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 { type ToolDefinition } from '@opencode-ai/plugin';
+import { type ToolDeps } from './shared.js';
+export declare function makeUpdateTool(deps: ToolDeps): ToolDefinition;
+export declare function makeAppendTool(deps: ToolDeps): ToolDefinition;