opencode-wiki-historian 0.2.0

package/dist/config.js

@@ -0,0 +1,158 @@
+/**
+ * Configuration model for the opencode-historian plugin.
+ *
+ * The plugin keeps a zero-runtime-dependency surface: no zod, no bun, only
+ * node builtins. Secrets are resolved from explicit sources (raw plugin
+ * options, env vars, the machine's opencode.jsonc) and never from the network.
+ *
+ * Home directory and env are injectable parameters on every resolver so unit
+ * tests drive fixtures in tmp dirs — the real ~/.config is never touched by
+ * the suite (see test/config.test.ts).
+ */
+import { homedir } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { parseJsonc, isRecord } from './jsonc.js';
+import { ConfigError } from './jsonc.js';
+// Contract re-exports: consumers (client.ts, translate.ts) import these from
+// './config.js'.
+export { ConfigError } from './jsonc.js';
+// --- Defaults (single source of truth for the plan's contract) --------------
+// Machine-agnostic by contract: the shipped package carries no deployment's
+// section taxonomy, translation gateway URL, or provider layout.
+export const DEFAULT_BASE_URL = 'http://localhost:3000';
+export const DEFAULT_API_KEY_PATH = '~/.wikijs-api-key';
+/** Env leg of the endpoint chain: raw option → this env var → unset (''). */
+export const ENV_TRANSLATE_ENDPOINT = 'HISTORIAN_TRANSLATE_ENDPOINT';
+export const DEFAULT_TRANSLATE_MODEL = 'qwen3.7-plus';
+/** Empty = no path-prefix restriction (see HistorianOptions.sections). */
+export const DEFAULT_SECTIONS = [];
+export const DEFAULT_LOCALES = ['en', 'zh'];
+/** Reading loop is on unless explicitly disabled (plan v2 todo 8). */
+export const DEFAULT_READING_LOOP = true;
+/** Capture reminders are opt-in (plan v2 todo 9). */
+export const DEFAULT_CAPTURE_ENABLED = false;
+// --- Resolution -------------------------------------------------------------
+/**
+ * Resolve raw plugin options against defaults, env vars and the machine's
+ * `~/.config/opencode/opencode.jsonc` into a fully typed HistorianOptions.
+ *
+ * Translation key priority (highest wins):
+ *   1. raw.translate.apiKey
+ *   2. env DASHSCOPE_API_KEY
+ *   3. jsonc provider[translate.providerKey].options.apiKey — only when
+ *      `translate.providerKey` is set explicitly (no default provider name)
+ *   4. throw ConfigError('missing translation key')
+ *
+ * Translation endpoint priority: raw.translate.endpoint →
+ * env HISTORIAN_TRANSLATE_ENDPOINT → unset (''). There is no baked-in
+ * gateway URL; an unset endpoint degrades translate calls to
+ * TranslateError('config') (twins go pending, see translate.ts).
+ *
+ * There is deliberately NO anthropic fallback leg (removed by plan — the
+ * provider layout varies per machine; the jsonc leg is opt-in via
+ * translate.providerKey).
+ */
+export function resolveOptions(raw, env = process.env, homeDir = homedir()) {
+    const providerKey = raw.translate?.providerKey ?? '';
+    const translateApiKey = resolveTranslationApiKey(raw, env, homeDir, providerKey);
+    return {
+        baseUrl: raw.baseUrl ?? DEFAULT_BASE_URL,
+        apiKeyPath: raw.apiKeyPath ?? DEFAULT_API_KEY_PATH,
+        translate: {
+            endpoint: raw.translate?.endpoint ?? env[ENV_TRANSLATE_ENDPOINT] ?? '',
+            model: raw.translate?.model ?? DEFAULT_TRANSLATE_MODEL,
+            apiKey: translateApiKey,
+            providerKey,
+        },
+        sections: raw.sections ?? DEFAULT_SECTIONS,
+        locales: raw.locales ?? DEFAULT_LOCALES,
+        readingLoop: raw.readingLoop ?? DEFAULT_READING_LOOP,
+        capture: { enabled: raw.capture?.enabled ?? DEFAULT_CAPTURE_ENABLED },
+    };
+}
+function resolveTranslationApiKey(raw, env, homeDir, providerKey) {
+    const rawKey = raw.translate?.apiKey;
+    if (isNonEmpty(rawKey))
+        return rawKey;
+    const envKey = env.DASHSCOPE_API_KEY;
+    if (isNonEmpty(envKey))
+        return envKey;
+    if (providerKey !== '') {
+        const jsoncKey = readProviderApiKeyFromJsonc(homeDir, providerKey);
+        if (isNonEmpty(jsoncKey))
+            return jsoncKey;
+    }
+    const jsoncHint = providerKey !== ''
+        ? `add provider["${providerKey}"].options.apiKey`
+        : `set translate.providerKey and add the key to provider["<name>"].options.apiKey`;
+    throw new ConfigError('missing-translation-key', `Missing translation api key: set plugin option translate.apiKey, ` +
+        `export DASHSCOPE_API_KEY, or ${jsoncHint} ` +
+        `in ${opencodeJsoncPath(homeDir)}.`);
+}
+/**
+ * Read the wiki.js api key. Priority: key file (path from options.apiKeyPath,
+ * `~` expanded) first; env WIKIJS_API_KEY as fallback; ConfigError otherwise.
+ * The key file content is trimmed (a trailing newline is common).
+ */
+export function readWikiApiKey(options, env = process.env, homeDir = homedir()) {
+    const expandedPath = expandHome(options.apiKeyPath, homeDir);
+    let fileKey;
+    try {
+        fileKey = readFileSync(expandedPath, 'utf8').trim();
+    }
+    catch {
+        fileKey = undefined; // fall through to env leg; the thrown error names the path
+    }
+    if (isNonEmpty(fileKey))
+        return fileKey;
+    const envKey = env.WIKIJS_API_KEY;
+    if (isNonEmpty(envKey))
+        return envKey;
+    throw new ConfigError('missing-wiki-api-key', `Missing wiki.js api key: create '${expandedPath}' containing the token ` +
+        '(one line, trimmed on read) or export WIKIJS_API_KEY.');
+}
+// --- jsonc source leg -------------------------------------------------------
+function opencodeJsoncPath(homeDir) {
+    return `${homeDir}/.config/opencode/opencode.jsonc`;
+}
+/** Read provider[providerKey].options.apiKey from the machine config.
+ *  Missing file or missing key -> undefined (a later leg decides); malformed
+ *  file -> ConfigError. Commented-out apiKey lines never survive stripping. */
+function readProviderApiKeyFromJsonc(homeDir, providerKey) {
+    const path = opencodeJsoncPath(homeDir);
+    let content;
+    try {
+        content = readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined; // no config file -> simply not a key source
+    }
+    const parsed = parseJsonc(content, path);
+    if (!isRecord(parsed)) {
+        throw new ConfigError('invalid-jsonc', `Invalid opencode config '${path}': top-level value must be a JSON object.`);
+    }
+    const provider = parsed.provider;
+    if (!isRecord(provider))
+        return undefined; // no providers at all -> not a key source
+    const chosen = provider[providerKey];
+    if (!isRecord(chosen))
+        return undefined;
+    const options = chosen.options;
+    if (!isRecord(options))
+        return undefined;
+    const apiKey = options.apiKey;
+    return typeof apiKey === 'string' && apiKey.trim() !== '' ? apiKey : undefined;
+}
+// --- small helpers ----------------------------------------------------------
+function isNonEmpty(value) {
+    return value !== undefined && value.trim() !== '';
+}
+/** Expand a leading `~` in a path against homeDir. Only `~` and `~/...` are
+ *  supported (no `~user` forms). */
+function expandHome(p, homeDir) {
+    if (p === '~')
+        return homeDir;
+    if (p.startsWith('~/'))
+        return `${homeDir}/${p.slice(2)}`;
+    return p;
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * opencode-historian plugin entry (todo 12).
+ *
+ * Exports the V1 plugin object shape verified by the oracle:
+ *   export default { id: string, server: (input, options?) => Promise<Hooks> }
+ *
+ * The server() hook resolves plugin options and returns:
+ *   - config: mutates cfg.skills.paths to ship the bundled skills/ directory
+ *     and registers the /historian-capture command (todo 9)
+ *   - tool: 10 historian_* tools wired by buildTools(opts)
+ *   - experimental.chat.system.transform: pushes the historian-first reading
+ *     loop advisory onto output.system[] (gated by opts.readingLoop)
+ *   - event: on session.idle emits ONE capture reminder toast per session
+ *     (gated by opts.capture.enabled; reminder-only — the page write happens
+ *     through /historian-capture -> historian_page_create, never here)
+ *
+ * Defensive: if resolveOptions throws (e.g. missing translate key), we catch
+ * at the server() boundary, log once to console.error, and return hooks with
+ * empty tools. The plugin registration itself must not crash opencode startup;
+ * individual tool calls will fail with a clear error if invoked without valid
+ * options. This matches the plan's "fail with clear one-time console.error"
+ * contract.
+ */
+import type { PluginInput, PluginOptions, Hooks } from '@opencode-ai/plugin';
+type ServerFn = (input: PluginInput, options?: PluginOptions) => Promise<Hooks>;
+interface PluginExport {
+    readonly id: string;
+    readonly server: ServerFn;
+}
+declare const plugin: PluginExport;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,136 @@
+/**
+ * opencode-historian plugin entry (todo 12).
+ *
+ * Exports the V1 plugin object shape verified by the oracle:
+ *   export default { id: string, server: (input, options?) => Promise<Hooks> }
+ *
+ * The server() hook resolves plugin options and returns:
+ *   - config: mutates cfg.skills.paths to ship the bundled skills/ directory
+ *     and registers the /historian-capture command (todo 9)
+ *   - tool: 10 historian_* tools wired by buildTools(opts)
+ *   - experimental.chat.system.transform: pushes the historian-first reading
+ *     loop advisory onto output.system[] (gated by opts.readingLoop)
+ *   - event: on session.idle emits ONE capture reminder toast per session
+ *     (gated by opts.capture.enabled; reminder-only — the page write happens
+ *     through /historian-capture -> historian_page_create, never here)
+ *
+ * Defensive: if resolveOptions throws (e.g. missing translate key), we catch
+ * at the server() boundary, log once to console.error, and return hooks with
+ * empty tools. The plugin registration itself must not crash opencode startup;
+ * individual tool calls will fail with a clear error if invoked without valid
+ * options. This matches the plan's "fail with clear one-time console.error"
+ * contract.
+ */
+import { fileURLToPath } from 'url';
+import { resolveOptions } from './config.js';
+import { buildTools } from './tools.js';
+/** Resolve the absolute path to the bundled skills/ directory. Uses
+ *  import.meta.url so it works whether loaded from dist/ (compiled) or src/
+ *  (dev). The skills/ directory may not exist yet (todo 13 creates it) — that
+ *  is plan-sanctioned; the config hook must not throw on a nonexistent dir,
+ *  opencode will simply skip it. */
+const skillsDir = fileURLToPath(new URL('../skills/', import.meta.url));
+/** Deduplicate an array of strings preserving first-occurrence order. Small
+ *  local helper — no reason to pull a dependency for a 3-liner. */
+function unique(items) {
+    return [...new Set(items)];
+}
+/** Reading-loop advisory (plan v2 todo 8): the machine wiki is the
+ *  authoritative institutional memory; consult it before acting, cite URLs.
+ *  Shipped text — generic wording only (privacy-audit scans dist). */
+const READING_LOOP_ADVISORY = [
+    'You have a historian: a wiki.js knowledge base acting as this machine\'s authoritative institutional memory.',
+    'Before doing work that touches this machine\'s deployments, history, pitfalls, or decisions, consult it first:',
+    '- historian_search by topic for relevant pages; historian_map action:"timeline" for what changed recently;',
+    '- G5 current-state ledger pages answer "what is deployed/running now" — check each row\'s verified date before trusting it.',
+    'Cite the wiki page URLs you relied on. If you learn something new worth keeping, offer to record it as a page.',
+].join('\n');
+/** /historian-capture command (plan v2 todo 9): the always-available manual
+ *  path from "notable session" to "G1 event page" — registered regardless of
+ *  capture.enabled; the enabled-gated toast only nudges toward it. Agent-facing
+ *  instruction text, generic wording only (ships in the tarball). */
+const CAPTURE_COMMAND_DESCRIPTION = '把本次会话记为史官事件页 / record this session as a historian event page';
+const CAPTURE_COMMAND_TEMPLATE = [
+    'Summarize the current session as a historian G1 event page (an append-only record of what happened).',
+    '',
+    '1. Draft four sections: 过程/Process (what was done, in order), 原因/Cause (why it was needed), 后果/Consequence (impact, artifacts), 改进/Improvement (follow-ups, preventions).',
+    "2. Run historian_map action:'show' to see existing sections, then choose a short factual path under one.",
+    '3. Save with historian_page_create (genre "G1"); the zh twin is auto-created. If the session only repeated known knowledge, say so and skip writing.',
+    '4. Echo both page URLs (en + zh) back to the user.',
+].join('\n');
+const CAPTURE_TOAST_MESSAGE = '会话空闲：有值得留存的决定/修复/踩坑就跑 /historian-capture。Session idle — run /historian-capture if it produced decisions, fixes, or pitfalls worth keeping.';
+async function server(input, options) {
+    let opts;
+    try {
+        opts = resolveOptions((options ?? {}));
+    }
+    catch (err) {
+        // Defensive: log once and return empty hooks. The plugin must not crash
+        // opencode startup if configuration is incomplete. Individual tool calls
+        // would fail here anyway since buildTools requires full HistorianOptions.
+        console.error('[opencode-historian] Failed to resolve plugin options; tools disabled.', err instanceof Error ? err.message : err);
+        return {};
+    }
+    const captureReminded = new Set();
+    const hooks = {
+        config: async (cfg) => {
+            const cfgWithSkills = cfg;
+            cfgWithSkills.skills ??= {};
+            cfgWithSkills.skills.paths = unique([...(cfgWithSkills.skills.paths ?? []), skillsDir]);
+            cfg.command ??= {};
+            // ??= — a user-defined /historian-capture in their own config wins;
+            // the plugin only supplies the default.
+            cfg.command['historian-capture'] ??= {
+                description: CAPTURE_COMMAND_DESCRIPTION,
+                template: CAPTURE_COMMAND_TEMPLATE,
+            };
+        },
+        tool: buildTools(opts),
+        'experimental.chat.system.transform': async (_input, output) => {
+            try {
+                if (opts.readingLoop !== true)
+                    return;
+                if (output.system.some((block) => block.includes('historian_search')))
+                    return;
+                output.system.push(READING_LOOP_ADVISORY);
+            }
+            catch (err) {
+                // A broken inject must never crash a chat request (plan v2 todo 8).
+                console.error('[opencode-historian] reading-loop advisory skipped:', err instanceof Error ? err.message : err);
+            }
+        },
+        event: async ({ event }) => {
+            try {
+                if (opts.capture.enabled !== true)
+                    return;
+                if (event.type !== 'session.idle')
+                    return;
+                // Feature-detect recordable work: session.idle only fires on a
+                // busy→idle transition (a session that never ran a prompt never goes
+                // idle), and each session is reminded at most once per plugin load.
+                const sessionID = event.properties.sessionID;
+                if (captureReminded.has(sessionID))
+                    return;
+                captureReminded.add(sessionID);
+                await input.client.tui.showToast({
+                    body: {
+                        title: '史官 / historian',
+                        message: CAPTURE_TOAST_MESSAGE,
+                        variant: 'info',
+                        duration: 15000,
+                    },
+                });
+            }
+            catch (err) {
+                // A failed reminder must never break the event stream (plan v2 todo 9).
+                console.error('[opencode-historian] capture reminder skipped:', err instanceof Error ? err.message : err);
+            }
+        },
+    };
+    return hooks;
+}
+const plugin = {
+    id: 'opencode-historian',
+    server,
+};
+export default plugin;

package/dist/jsonc.d.ts

@@ -0,0 +1,17 @@
+/**
+ * JSONC parsing for opencode's `~/.config/opencode/opencode.jsonc`.
+ *
+ * String-aware comment stripping — a `//` or `/*` inside a quoted string
+ * (e.g. "https://...") is literal, never a comment. Malformed input always
+ * surfaces as ConfigError, never a raw SyntaxError.
+ */
+export type ConfigErrorCode = 'missing-translation-key' | 'invalid-jsonc' | 'missing-wiki-api-key';
+/** Structured configuration error. `code` lets callers branch programmatically;
+ *  `message` is written for a human to act on. Never throw bare strings. */
+export declare class ConfigError extends Error {
+    readonly code: ConfigErrorCode;
+    constructor(code: ConfigErrorCode, message: string);
+}
+/** Parse JSONC into an unknown value. `path` is used in error messages. */
+export declare function parseJsonc(content: string, path: string): unknown;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/jsonc.js

@@ -0,0 +1,131 @@
+/**
+ * JSONC parsing for opencode's `~/.config/opencode/opencode.jsonc`.
+ *
+ * String-aware comment stripping — a `//` or `/*` inside a quoted string
+ * (e.g. "https://...") is literal, never a comment. Malformed input always
+ * surfaces as ConfigError, never a raw SyntaxError.
+ */
+/** Structured configuration error. `code` lets callers branch programmatically;
+ *  `message` is written for a human to act on. Never throw bare strings. */
+export class ConfigError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ConfigError';
+        this.code = code;
+    }
+}
+/** Parse JSONC into an unknown value. `path` is used in error messages. */
+export function parseJsonc(content, path) {
+    const stripped = stripComments(content, path);
+    const withCommasStripped = stripTrailingCommas(stripped, path);
+    try {
+        return JSON.parse(withCommasStripped);
+    }
+    catch (err) {
+        throw new ConfigError('invalid-jsonc', `Invalid opencode config '${path}': JSON parse failed (${err.message}).`);
+    }
+}
+/** Character scanner (not regex) so comment markers inside strings stay literal. */
+function stripComments(content, path) {
+    let out = '';
+    let inString = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+    for (let i = 0; i < content.length; i++) {
+        const c = content[i];
+        const next = content[i + 1];
+        if (inLineComment) {
+            if (c === '\n') {
+                inLineComment = false;
+                out += c;
+            }
+            continue;
+        }
+        if (inBlockComment) {
+            if (c === '*' && next === '/') {
+                inBlockComment = false;
+                i++;
+            }
+            continue;
+        }
+        if (inString) {
+            out += c;
+            if (c === '\\' && next !== undefined) {
+                out += next;
+                i++;
+            }
+            else if (c === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            out += c;
+            continue;
+        }
+        if (c === '/' && next === '/') {
+            inLineComment = true;
+            i++;
+            continue;
+        }
+        if (c === '/' && next === '*') {
+            inBlockComment = true;
+            i++;
+            continue;
+        }
+        out += c;
+    }
+    if (inBlockComment) {
+        throw new ConfigError('invalid-jsonc', `Invalid opencode config '${path}': unterminated block comment.`);
+    }
+    if (inString) {
+        throw new ConfigError('invalid-jsonc', `Invalid opencode config '${path}': unterminated string.`);
+    }
+    return out;
+}
+/** Drop commas that trail an object/array entry: `[1,2,]` -> `[1,2]`. */
+function stripTrailingCommas(content, path) {
+    let out = '';
+    let inString = false;
+    for (let i = 0; i < content.length; i++) {
+        const c = content[i];
+        if (inString) {
+            out += c;
+            if (c === '\\' && content[i + 1] !== undefined) {
+                out += content[i + 1];
+                i++;
+            }
+            else if (c === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            out += c;
+            continue;
+        }
+        if (c === ',') {
+            let j = i + 1;
+            while (j < content.length &&
+                (content[j] === ' ' || content[j] === '\t' || content[j] === '\n' || content[j] === '\r')) {
+                j++;
+            }
+            if (content[j] === '}' || content[j] === ']') {
+                continue; // drop the trailing comma
+            }
+            out += c;
+            continue;
+        }
+        out += c;
+    }
+    if (inString) {
+        throw new ConfigError('invalid-jsonc', `Invalid opencode config '${path}': unterminated string.`);
+    }
+    return out;
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/map.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Locale-aware page map (todo 10): full cross-locale inventory with en/zh twin
+ * pairing, rendered as the markdown `_meta/page-map` cache page + local mirror.
+ */
+import type { HistorianOptions } from './config.js';
+import type { GqlClient } from './wiki/client.js';
+import { type Locale } from './wiki/pages.read.js';
+export interface MapDeps {
+    readonly client: GqlClient;
+    readonly options: HistorianOptions;
+}
+export interface MapRow {
+    readonly id: number;
+    readonly locale: Locale;
+    readonly path: string;
+    readonly title: string;
+    readonly updatedAt: string;
+    readonly url: string;
+    readonly twinUrl: string | null;
+    readonly twinId: number | null;
+}
+export interface MapStats {
+    readonly rows: number;
+    readonly paths: number;
+    readonly perLocale: Readonly<Record<string, number>>;
+    readonly missingTwinPaths: readonly string[];
+}
+export interface PageMap {
+    readonly rows: readonly MapRow[];
+    readonly stats: MapStats;
+}
+export interface MapSnapshot extends PageMap {
+    readonly generatedAt: string | null;
+    readonly staleSeconds: number | null;
+}
+export declare const CACHE_PATH = "_meta/page-map";
+export declare const HEADER_ROW = "| ID | Locale | Path | Title | View URL | Twin | Updated At |";
+export declare function mirrorPath(home: string): string;
+/** Full inventory: every page of every configured locale (only private-
+ *  namespace pages are excluded — they are not anonymously reachable), twins
+ *  paired by exact path, rows sorted by path then locale. */
+export declare function buildPageMap(deps: MapDeps): Promise<PageMap>;
+export declare function renderMapMarkdown(rows: readonly MapRow[]): string;
+export interface RefreshOptions {
+    readonly now?: Date;
+    readonly homeDir?: string;
+}
+export interface RefreshResult {
+    readonly stats: MapStats;
+    readonly cacheUrl: string;
+}
+/** Rebuild + write cycle: fresh map → local mirror → `_meta/page-map` upsert.
+ *  An existing cache page is patched content-only — updatePage is a full RMW,
+ *  so the machine-fact isPrivate/isPublished/tags survive (pitfall #1). */
+export declare function refreshMapCache(deps: MapDeps, opts?: RefreshOptions): Promise<RefreshResult>;
+/** Read the local mirror with staleness in whole seconds; absent or damaged
+ *  mirror → a live build (read-only — no cache page write, no mirror write). */
+export declare function getMap(deps: MapDeps, homeDir?: string): Promise<MapSnapshot>;