@chronova/wiki-agent 1.1.4

package/dist/cli.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import React from "react";
+import { render as inkRender } from "ink";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { runAgent } from "./agent.js";
+import { resolveConfig, createOllamaClient, } from "./config.js";
+import { getHelpText } from "./prompt.js";
+import { App } from "./tui/App.js";
+const execAsync = promisify(exec);
+function parseArgs(argv) {
+    const args = { command: null, print: false, verbose: false, help: false };
+    for (let i = 2; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--init":
+                args.command = "init";
+                break;
+            case "--update":
+                args.command = "update";
+                break;
+            case "--print":
+                args.print = true;
+                break;
+            case "--verbose":
+            case "-v":
+                args.verbose = true;
+                break;
+            case "--model":
+                args.model = argv[++i];
+                break;
+            case "--help":
+            case "-h":
+                args.help = true;
+                break;
+        }
+    }
+    return args;
+}
+async function getGitSummary(cwd) {
+    try {
+        const { stdout } = await execAsync("git log --oneline -30", {
+            cwd,
+            maxBuffer: 1024 * 1024,
+        });
+        return stdout.trim();
+    }
+    catch {
+        return "(git not available or not a git repository)";
+    }
+}
+async function runHeadless(command, cwd, model, verbose) {
+    const config = await resolveConfig(cwd, model);
+    const client = createOllamaClient(config);
+    const gitSummary = await getGitSummary(cwd);
+    await runAgent(client, {
+        command,
+        projectRoot: cwd,
+        model: config.model,
+        gitSummary,
+        stream: false,
+        onEvent: (event) => {
+            switch (event.type) {
+                case "assistant":
+                    if (event.content) {
+                        process.stdout.write(`\n${event.content}\n`);
+                    }
+                    break;
+                case "tool":
+                    if (event.result && verbose) {
+                        process.stdout.write(`\n[tool: ${event.name}]\n${event.result}\n`);
+                    }
+                    break;
+                case "error":
+                    process.stderr.write(`\nError: ${event.message}\n`);
+                    break;
+                case "done":
+                    process.stdout.write(`\n${event.summary}\n`);
+                    break;
+            }
+        },
+    });
+}
+async function main() {
+    const args = parseArgs(process.argv);
+    if (args.help || args.command === null) {
+        console.log(getHelpText());
+        process.exit(0);
+    }
+    const command = args.command;
+    const cwd = process.cwd();
+    const config = await resolveConfig(cwd, args.model);
+    if (config.mode === "cloud" && !config.apiKey) {
+        console.error("WIKI_OLLAMA_API_KEY is required for cloud mode. Set it via environment variable or run interactively to configure.");
+        process.exit(1);
+    }
+    if (args.print) {
+        await runHeadless(command, cwd, config.model, args.verbose);
+    }
+    else {
+        const { waitUntilExit } = inkRender(React.createElement(App, {
+            command,
+            cwd,
+            config,
+            verbose: args.verbose,
+        }));
+        await waitUntilExit();
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/config.d.ts

@@ -0,0 +1,44 @@
+import { Ollama } from "ollama";
+export type OllamaMode = "local" | "cloud";
+export interface GlobalConfig {
+    mode: OllamaMode;
+    apiKey?: string;
+    baseUrl?: string;
+    defaultModel: string;
+}
+export interface ProjectConfig {
+    modelOverride?: string;
+    lastUpdate?: {
+        commitSha: string;
+        timestamp: string;
+    };
+}
+export interface ResolvedConfig {
+    mode: OllamaMode;
+    apiKey?: string;
+    baseUrl: string;
+    model: string;
+}
+declare function getGlobalConfigDir(): string;
+declare const DEFAULT_MODEL = "kimi-k2.7-code";
+declare const MAX_TOOL_RESULT_LENGTH = 10000;
+export { getGlobalConfigDir };
+export declare function loadGlobalConfig(): Promise<GlobalConfig>;
+export declare function saveGlobalConfig(config: GlobalConfig): Promise<void>;
+export declare function loadProjectConfig(projectRoot: string): Promise<ProjectConfig>;
+export declare function saveProjectConfig(projectRoot: string, config: ProjectConfig): Promise<void>;
+/**
+ * Resolves the effective configuration by merging (in priority order):
+ * 1. Environment variables (WIKI_OLLAMA_MODE, WIKI_OLLAMA_API_KEY,
+ *    WIKI_OLLAMA_BASE_URL, WIKI_MODEL)
+ * 2. Global config file (~/.wiki/config.json)
+ * 3. Project config (.wiki/config.json modelOverride)
+ * 4. Built-in defaults
+ */
+export declare function resolveConfig(projectRoot: string, modelOverride?: string): Promise<ResolvedConfig>;
+/**
+ * Creates an Ollama client from resolved config.
+ */
+export declare function createOllamaClient(config: ResolvedConfig): Ollama;
+export declare function truncateResult(result: string): string;
+export { DEFAULT_MODEL, MAX_TOOL_RESULT_LENGTH };

package/dist/config.js

@@ -0,0 +1,95 @@
+import { mkdir, readFile, writeFile, chmod } from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { Ollama } from "ollama";
+function getGlobalConfigDir() {
+    return path.join(os.homedir(), ".wiki");
+}
+function getGlobalConfigPath() {
+    return path.join(getGlobalConfigDir(), "config.json");
+}
+const DEFAULT_LOCAL_HOST = "http://localhost:11434";
+const DEFAULT_CLOUD_HOST = "https://ollama.com";
+const DEFAULT_MODEL = "kimi-k2.7-code";
+const MAX_TOOL_RESULT_LENGTH = 10_000;
+function defaultGlobalConfig() {
+    return { mode: "local", defaultModel: DEFAULT_MODEL };
+}
+export { getGlobalConfigDir };
+export async function loadGlobalConfig() {
+    try {
+        const raw = await readFile(getGlobalConfigPath(), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return defaultGlobalConfig();
+    }
+}
+export async function saveGlobalConfig(config) {
+    const dir = getGlobalConfigDir();
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const configPath = getGlobalConfigPath();
+    await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+    await chmod(configPath, 0o600);
+}
+export async function loadProjectConfig(projectRoot) {
+    const configPath = path.join(projectRoot, ".wiki", "config.json");
+    try {
+        const raw = await readFile(configPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export async function saveProjectConfig(projectRoot, config) {
+    const configDir = path.join(projectRoot, ".wiki");
+    await mkdir(configDir, { recursive: true });
+    const configPath = path.join(configDir, "config.json");
+    await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+/**
+ * Resolves the effective configuration by merging (in priority order):
+ * 1. Environment variables (WIKI_OLLAMA_MODE, WIKI_OLLAMA_API_KEY,
+ *    WIKI_OLLAMA_BASE_URL, WIKI_MODEL)
+ * 2. Global config file (~/.wiki/config.json)
+ * 3. Project config (.wiki/config.json modelOverride)
+ * 4. Built-in defaults
+ */
+export async function resolveConfig(projectRoot, modelOverride) {
+    const globalConfig = await loadGlobalConfig();
+    const projectConfig = await loadProjectConfig(projectRoot);
+    const env = process.env;
+    const mode = env.WIKI_OLLAMA_MODE === "cloud" || env.WIKI_OLLAMA_MODE === "local"
+        ? env.WIKI_OLLAMA_MODE
+        : globalConfig.mode;
+    const apiKey = env.WIKI_OLLAMA_API_KEY ?? globalConfig.apiKey;
+    const baseUrl = env.WIKI_OLLAMA_BASE_URL ??
+        globalConfig.baseUrl ??
+        (mode === "cloud" ? DEFAULT_CLOUD_HOST : DEFAULT_LOCAL_HOST);
+    const model = modelOverride ??
+        projectConfig.modelOverride ??
+        env.WIKI_MODEL ??
+        globalConfig.defaultModel ??
+        DEFAULT_MODEL;
+    return { mode, apiKey, baseUrl, model };
+}
+/**
+ * Creates an Ollama client from resolved config.
+ */
+export function createOllamaClient(config) {
+    if (config.mode === "cloud" && config.apiKey) {
+        return new Ollama({
+            host: config.baseUrl,
+            headers: { Authorization: `Bearer ${config.apiKey}` },
+        });
+    }
+    return new Ollama({ host: config.baseUrl });
+}
+export function truncateResult(result) {
+    if (result.length <= MAX_TOOL_RESULT_LENGTH) {
+        return result;
+    }
+    return result.slice(0, MAX_TOOL_RESULT_LENGTH) + "\n... (truncated)";
+}
+export { DEFAULT_MODEL, MAX_TOOL_RESULT_LENGTH };

package/dist/index-middleware.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Synchronizes index.md files for every directory under the wiki root.
+ * Call this after the agent run completes.
+ */
+export declare function synchronizeWikiIndexes(wikiRoot: string): Promise<void>;

package/dist/index-middleware.js

@@ -0,0 +1,135 @@
+import { readFile, writeFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { parse } from "yaml";
+const INDEX_FILE = "index.md";
+const EXCLUDED_FILES = new Set([INDEX_FILE, "_plan.md"]);
+/**
+ * Synchronizes index.md files for every directory under the wiki root.
+ * Call this after the agent run completes.
+ */
+export async function synchronizeWikiIndexes(wikiRoot) {
+    try {
+        await stat(wikiRoot);
+    }
+    catch {
+        return;
+    }
+    await synchronizeDirectory(wikiRoot, wikiRoot);
+}
+async function synchronizeDirectory(dirPath, root) {
+    const entries = await collectEntries(dirPath);
+    const files = [];
+    const directories = [];
+    for (const entry of entries) {
+        if (!entry.name || entry.name.startsWith("."))
+            continue;
+        if (entry.isDir) {
+            directories.push({ href: `${encodeURIComponent(entry.name)}/`, label: entry.name });
+            await synchronizeDirectory(path.join(dirPath, entry.name), root);
+            continue;
+        }
+        if (path.extname(entry.name).toLowerCase() !== ".md")
+            continue;
+        if (EXCLUDED_FILES.has(entry.name))
+            continue;
+        const filePath = path.join(dirPath, entry.name);
+        const metadata = await parseFrontmatter(filePath);
+        files.push({
+            description: metadata.description,
+            href: encodeURIComponent(entry.name),
+            label: metadata.title ?? path.basename(entry.name, ".md"),
+        });
+    }
+    const indexPath = path.join(dirPath, INDEX_FILE);
+    const title = dirPath === root ? "Wiki" : titleFromSlug(path.basename(dirPath));
+    const content = renderIndex(title, files, directories);
+    let existing = null;
+    try {
+        existing = await readFile(indexPath, "utf8");
+    }
+    catch {
+        // index.md doesn't exist yet
+    }
+    if (existing === content)
+        return;
+    await writeFile(indexPath, content, "utf8");
+}
+async function collectEntries(dirPath) {
+    const names = await readdir(dirPath, { withFileTypes: true });
+    return names.map((entry) => ({
+        name: entry.name,
+        isDir: entry.isDirectory(),
+    }));
+}
+function renderIndex(title, files, directories) {
+    const sections = [
+        renderLinks("Files", files, true),
+        renderLinks("Directories", directories, false),
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+    return `---\ntype: Documentation Index\ntitle: ${JSON.stringify(title)}\ndescription: ${JSON.stringify(`Files and subdirectories in ${title}.`)}\n---\n\n${sections}\n`;
+}
+function renderLinks(heading, links, includeDescription) {
+    if (links.length === 0)
+        return "";
+    links.sort((left, right) => left.href.localeCompare(right.href));
+    const items = links.map(({ description, href, label }) => {
+        const link = `- [${escapeLabel(label)}](${href})`;
+        return includeDescription && description
+            ? `${link} - ${description}`
+            : link;
+    });
+    return `# ${heading}\n\n${items.join("\n")}`;
+}
+async function parseFrontmatter(filePath) {
+    let content;
+    try {
+        content = await readFile(filePath, "utf8");
+    }
+    catch {
+        return {};
+    }
+    const block = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(content)?.[1];
+    if (!block)
+        return {};
+    let fields;
+    try {
+        fields = parse(`\n${block}`, {
+            maxAliasCount: 100,
+            schema: "core",
+            uniqueKeys: true,
+        });
+    }
+    catch (error) {
+        throw new Error(`${filePath} contains invalid YAML front matter: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (fields === null || typeof fields !== "object" || Array.isArray(fields)) {
+        throw new Error(`${filePath} YAML front matter must be a mapping.`);
+    }
+    const { description, title } = fields;
+    if (description !== undefined &&
+        (typeof description !== "string" || !description.trim())) {
+        throw new Error(`${filePath} YAML description must be a non-empty string.`);
+    }
+    if (title !== undefined && typeof title !== "string") {
+        throw new Error(`${filePath} YAML title must be a string.`);
+    }
+    return {
+        ...(description ? { description } : {}),
+        ...(title ? { title } : {}),
+    };
+}
+function titleFromSlug(slug) {
+    return slug
+        .split(/[-_\s]+/u)
+        .filter(Boolean)
+        .map((word) => word[0].toUpperCase() + word.slice(1))
+        .join(" ");
+}
+function escapeLabel(value) {
+    return value
+        .replaceAll("\\", "\\\\")
+        .replaceAll("[", "\\[")
+        .replaceAll("]", "\\]");
+}

package/dist/prompt.d.ts

@@ -0,0 +1,4 @@
+export type WikiCommand = "init" | "update";
+export declare function createSystemPrompt(projectRoot: string): Promise<string>;
+export declare function createUserMessage(command: WikiCommand, projectRoot: string, gitSummary?: string): string;
+export declare function getHelpText(): string;

package/dist/prompt.js

@@ -0,0 +1,145 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Reads AGENTS.md or CLAUDE.md from the project root, if either exists.
+ * Returns the file content (first match wins: AGENTS.md, then CLAUDE.md).
+ */
+async function loadRepoInstructions(projectRoot) {
+    for (const filename of ["AGENTS.md", "CLAUDE.md"]) {
+        try {
+            const content = await readFile(path.join(projectRoot, filename), "utf8");
+            return content.trim();
+        }
+        catch {
+            // File doesn't exist — try the next one
+        }
+    }
+    return null;
+}
+export async function createSystemPrompt(projectRoot) {
+    const repoInstructions = await loadRepoInstructions(projectRoot);
+    const instructionsSection = repoInstructions
+        ? `\n\nRepository instructions (from AGENTS.md or CLAUDE.md in the project root):\nYou MUST follow these rules when generating documentation. Acknowledge and respect all conventions, code style rules, and constraints documented here:\n\n${repoInstructions}\n`
+        : "";
+    return `
+You are Wiki Agent, an expert technical writer, software architect, and product analyst.
+
+Your job is to inspect the source evidence in the repository and produce documentation in .wiki/ that is excellent for both humans and future agents.
+
+# Capabilities and constraints
+
+You have a FIXED, LIMITED set of tools. You CANNOT execute arbitrary commands on the host system. There is no shell tool. The tools available to you are:
+- read_file, ls, glob, grep: read-only filesystem discovery scoped to the project root.
+- ast_grep: search code by AST pattern (structural match). Use $NAME for a single node metavariable and $$$ARGS for zero-or-more. Requires an explicit language. Prefer this over grep for precise structural queries (function calls, exports, control flow).
+- ast_search: search code using an inline ast-grep YAML rule. More powerful than ast_grep — supports relational/inside/has constraints. Use for complex structural queries a single pattern cannot express.
+- write_file, edit_file: write or edit documentation files. These are the ONLY mutating tools and are constrained to paths under .wiki/.
+- git: run a READ-ONLY git subcommand (log, diff, show, ls-files, blame, status, remote, describe, rev-parse, shortlog, name-rev, ls-tree, cat-file, reflog). This is the ONLY way to access repository history. Mutating git operations and arbitrary shell commands are NOT available — do not attempt them and do not assume any command outside this list will work.
+
+You cannot run build tools, package managers, test runners, scripts, or any program other than git (read-only). If documentation requires information only obtainable by executing code, say so explicitly rather than attempting to run it. Ground every important claim in source files, existing docs, or git evidence you have inspected.
+
+# Output location
+- Write documentation under .wiki/ in the project root. Use paths such as .wiki/quickstart.md, .wiki/architecture/overview.md, .wiki/cli/usage.md.
+- Never write markdown files outside .wiki/.
+- Each wiki page must start with YAML frontmatter:
+  ---
+  type: <type>
+  title: <title>
+  description: <description>
+  tags: [<tags>]
+  ---
+
+Use only the tools listed above. Do not invent files, modules, APIs, business rules, or behavior. Ground every important claim in source files, existing docs, or git evidence you have inspected.
+
+# Run discipline
+- Never pass host absolute paths like /Users/... to filesystem tools; use paths relative to the project root.
+- Do not exhaustively read every file. Inspect the repository tree, package/config files, README-style files, entrypoints, routing files, database/schema files, and representative files for each major domain.
+- Do not call glob with **/* from the root. Use targeted discovery by directory and extension. Prefer ls on specific directories and glob with constrained paths; exclude .git, node_modules, dist, build, cache directories, and existing generated wiki output mentally when interpreting results.
+- Prefer grep, ast_grep, and short targeted read_file calls over full-file reads when files are large.
+- Use ast_grep when you need structural precision (finding all call sites of a symbol, all exports, a specific control-flow shape). Use ast_search only when a single pattern is insufficient.
+- Use git for history and change evidence: 'git log --oneline -30', 'git diff --stat', 'git ls-files', 'git show <sha>:<path>'. This is the only source of temporal evidence — there is no other shell access.
+- Create a strong first-pass wiki that is accurate and navigable, then stop. The wiki can be refined in later update runs.
+- Keep the initial documentation set focused: quickstart plus the smallest set of section pages needed to explain the repo clearly.
+- Before writing documentation, read AGENTS.md or CLAUDE.md from the repository root if either exists, and apply all conventions, code style rules, and constraints documented there.
+
+# Loop prevention
+- Work in phases: discover → plan → write → verify. Do not restart discovery once you have moved to planning or writing.
+- Track what you have already inspected. If you are about to run the same command or read the same file a second time, stop — you already have that information.
+- Make one targeted discovery pass per area. If you find yourself listing the same directory or re-running git log without a new, specific question, you are looping. Stop and proceed to the next phase.
+- Process each tool result fully before issuing the next call. If a tool returned the information you need, use it — do not re-request it.
+- Do not begin a response with "I'll start by exploring" or "Let me start by exploring" more than once. The first discovery pass is enough; after that, you should be writing or editing.
+- If you are stuck or uncertain about a specific fact, make a targeted single read or grep, then proceed with the best available evidence. Do not loop on discovery as a way to resolve uncertainty.
+
+# Documentation quality
+- Give each concept one canonical home. Link to it from other pages when needed.
+- Keep the docs concise enough to maintain. Avoid repeating the same concept across pages.
+- Use code examples sparingly — only when they clarify a non-obvious API or pattern.
+- If the source material already has substantial docs or prior wiki pages, create a wiki that functions as an opinionated map and synthesis layer over those docs.
+- Before every write_file or edit_file call, write one or two sentences explaining what you are changing and why — the source evidence that drove the change, what section was added/revised, and the intended improvement. This narration is used verbatim as the per-file change description in the update report and pull request body, so be specific and substantive; do not write generic filler like "Updated the page" or "Improved docs".
+- Updates may be a no-op. If there are no relevant source changes since the previous successful run, and the current wiki is already accurate, do not edit files. Say that the wiki is already current.
+${instructionsSection}
+`.trim();
+}
+export function createUserMessage(command, projectRoot, gitSummary) {
+    if (command === "init") {
+        return `
+Initialize wiki documentation for this repository.
+
+Inspect the relevant evidence thoroughly, identify the major technical, business, or knowledge domains, and write the initial documentation under .wiki/.
+
+Start with .wiki/quickstart.md as the entrypoint. Then create section directories and pages that explain the subject in a way that is useful to both humans and future agents.
+
+Make one focused discovery pass, then write the plan and proceed to documentation. Do not loop on repeated exploration steps.
+
+Git context:
+${gitSummary ?? "(not available)"}
+`.trim();
+    }
+    return `
+Update the existing OpenWiki documentation for this repository.
+
+Inspect .wiki/, identify recent source changes or newly relevant evidence, and refresh only the documentation pages directly affected by those changes. Use the git evidence below when available. Keep edits surgical: do not rewrite accurate sections, do not update source maps or git evidence just to refresh them, and do not make formatting-only changes. If the wiki is already current, do not edit files.
+
+Make one focused discovery pass to identify what changed, then proceed to surgical edits. Do not loop on repeated exploration steps.
+
+Git change summary:
+${gitSummary ?? "(not available)"}
+`.trim();
+}
+export function getHelpText() {
+    return `
+    __        _____ _  _____      _    ____ _____ _   _ _____
+   \\ \\      / /_ _| |/ /_ _|    / \\  / ___| ____| \\ | |_   _|
+    \\ \\ /\\ / / | || ' / | |    / _ \\| |  _|  _| |  \\| | | |
+     \\ V  V /  | || . \\ | |   / ___ \\ |_| | |___| |\\  | | |
+      \\_/\\_/  |___|_|\\_\\___| /_/   \\_\\____|_____|_| \\_| |_|
+
+Usage
+  wiki --init                    Initialize wiki documentation (interactive)
+  wiki --update                  Update existing wiki documentation (interactive)
+  wiki --init --print            Headless init (non-interactive)
+  wiki --update --print          Headless update (non-interactive)
+  wiki --init --print --model <id>   Specify model
+  wiki --update --print --verbose    Headless update with full tool logs
+  wiki --help                     Show this help
+
+Options
+  --init          Initialize documentation for the current repository
+  --update        Update existing documentation
+  --print         Run headless (non-interactive, output to stdout)
+  --verbose, -v   Show full tool call results (default: assistant prose only)
+  --model <id>    Override the model ID
+  --help, -h      Show help
+
+Environment variables
+  WIKI_OLLAMA_MODE        "local" or "cloud"
+  WIKI_OLLAMA_API_KEY     API key (required for cloud mode)
+  WIKI_OLLAMA_BASE_URL    Override the Ollama server URL
+  WIKI_MODEL              Override the model ID
+  WIKI_RECURSION_LIMIT    Max agent iterations (default: 200)
+
+Configuration
+  Global:    ~/.wiki/config.json
+  Project:   .wiki/config.json
+  Output:    .wiki/ (in the project root)
+`.trim();
+}

package/dist/tools.d.ts

@@ -0,0 +1,24 @@
+declare const MAX_READ_LENGTH = 50000;
+declare const MAX_TOOL_RESULT_LENGTH = 10000;
+interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+    };
+}
+export interface Tool {
+    definition: ToolDefinition;
+    handler: (args: Record<string, unknown>, projectRoot: string) => Promise<string>;
+}
+export declare function createTools(projectRoot: string): Tool[];
+/**
+ * Execute a tool by name with the given arguments.
+ */
+export declare function executeTool(toolName: string, args: Record<string, unknown>, projectRoot: string): Promise<string>;
+export { MAX_READ_LENGTH, MAX_TOOL_RESULT_LENGTH };