@chronova/wiki-agent 1.1.4

package/README.md

@@ -0,0 +1,248 @@
+# Wiki Agent
+
+A standalone Ollama-only documentation agent. It inspects your source code and generates a wiki under `.wiki/` in your project root.
+
+## Features
+
+- **Ollama-only** — uses the native `ollama` SDK, no LangChain dependency
+- **Local or Cloud** — connect to a local Ollama server or Ollama Cloud with an API key
+- **TUI + Headless** — interactive terminal UI or `--print` for CI/CD
+- **Two commands** — `--init` to create docs from scratch, `--update` to refresh existing docs
+- **Configurable** — global config in `~/.wiki/`, project config in `.wiki/`
+- **GitHub Actions** — `--init` automatically creates a scheduled update workflow in your repo
+- **Repo instructions** — reads `AGENTS.md` or `CLAUDE.md` from the project root and follows all conventions documented there
+- **Change reports** — each run writes `.wiki/.last-update-report.md` with created/edited pages, used as the PR body in CI
+- **Self-invocation guard** — the agent cannot recursively invoke `wiki` or `wiki-agent` via shell commands
+
+## Quickstart
+
+### 1. Install
+
+Build from source and install globally with bun:
+
+```bash
+git clone https://github.com/nx-solutions-ug/wiki-agent.git
+cd wiki-agent
+npm install
+npx tsc -p tsconfig.json
+bun pm pack
+cd ~/.bun/install/global && bun add /path/to/wiki-agent/wiki-agent-0.1.0.tgz
+```
+
+Verify the install:
+
+```bash
+wiki --help
+```
+
+### 2. Configure
+
+Run interactively once to set up credentials:
+
+```bash
+cd your-project
+wiki --init
+```
+
+This launches the TUI where you select Ollama Local or Cloud and enter your API key (if cloud). The default model is `kimi-k2.7-code`.
+
+### 3. Use
+
+```bash
+# Initialize documentation (also creates .github/workflows/update-wiki.yml)
+wiki --init
+
+# Update existing documentation
+wiki --update
+
+# Headless mode (for CI)
+wiki --update --print
+
+# Specify a model override
+wiki --init --print --model llama3.2
+```
+
+## Configuration
+
+### Global config (`~/.wiki/config.json`)
+
+```json
+{
+  "mode": "local",
+  "defaultModel": "kimi-k2.7-code"
+}
+```
+
+For cloud:
+
+```json
+{
+  "mode": "cloud",
+  "apiKey": "your-api-key",
+  "defaultModel": "kimi-k2.7-code"
+}
+```
+
+### Project config (`.wiki/config.json`)
+
+```json
+{
+  "modelOverride": "llama3.2",
+  "lastUpdate": {
+    "commitSha": "abc1234",
+    "timestamp": "2026-07-17T00:00:00Z"
+  }
+}
+```
+
+### Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `WIKI_OLLAMA_MODE` | `"local"` or `"cloud"` | from config |
+| `WIKI_OLLAMA_API_KEY` | API key for cloud mode | from config |
+| `WIKI_OLLAMA_BASE_URL` | Override Ollama server URL | `http://localhost:11434` / `https://ollama.com` |
+| `WIKI_MODEL` | Override model ID | from config |
+| `WIKI_RECURSION_LIMIT` | Max agent iterations | `200` |
+
+Environment variables take priority over config files.
+
+## GitHub Actions
+
+Running `wiki --init` automatically creates `.github/workflows/update-wiki.yml` in your repo. The workflow:
+
+1. Generates a GitHub App token if `APP_CLIENT_ID` and `APP_PRIVATE_KEY` secrets are set (falls back to `GITHUB_TOKEN`)
+2. Checks out your repo
+3. Clones and builds wiki-agent from `nx-solutions-ug/wiki-agent`
+4. Runs `wiki --update --print` with your Ollama Cloud credentials
+5. Reads `.wiki/.last-update-report.md` and uses it as the PR body
+6. Creates a pull request with the `.wiki/` changes
+
+```yaml
+name: Wiki Update
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: "0 8 * * *"
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate token
+        id: token
+        uses: actions/create-github-app-token@v3
+        with:
+          client-id: ${{ secrets.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+        continue-on-error: true
+
+      - uses: actions/checkout@v7
+        with:
+          token: ${{ steps.token.outputs.token || secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "25"
+
+      - name: Build Wiki Agent
+        run: |
+          git clone --branch main --depth 1 https://github.com/nx-solutions-ug/wiki-agent.git /tmp/wiki-agent
+          cd /tmp/wiki-agent
+          npm install
+          npx tsc -p tsconfig.json
+
+      - name: Run Wiki Agent
+        run: node /tmp/wiki-agent/dist/cli.js --update --print
+        env:
+          WIKI_OLLAMA_MODE: cloud
+          WIKI_OLLAMA_API_KEY: ${{ secrets.WIKI_OLLAMA_API_KEY }}
+          WIKI_MODEL: ${{ vars.WIKI_MODEL || 'kimi-k2.7-code' }}
+
+      - name: Generate timestamp
+        id: timestamp
+        run: echo "timestamp=$(date +%s)" >> $GITHUB_OUTPUT
+
+      - name: Read update report
+        id: report
+        run: |
+          if [ -f .wiki/.last-update-report.md ]; then
+            echo "body<<EOF" >> $GITHUB_OUTPUT
+            cat .wiki/.last-update-report.md >> $GITHUB_OUTPUT
+            echo "EOF" >> $GITHUB_OUTPUT
+          else
+            echo "body=Automated wiki documentation update." >> $GITHUB_OUTPUT
+          fi
+
+      - uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ steps.token.outputs.token || secrets.GITHUB_TOKEN }}
+          add-paths: .wiki
+          branch: wiki/update-${{ steps.timestamp.outputs.timestamp }}
+          commit-message: "docs: update wiki"
+          title: "docs: update wiki"
+          body: ${{ steps.report.outputs.body }}
+```
+
+### Required secrets
+
+| Secret | Required | Description |
+|--------|----------|-------------|
+| `WIKI_OLLAMA_API_KEY` | Yes | Ollama Cloud API key |
+| `APP_CLIENT_ID` | No | GitHub App client ID for token generation (falls back to `GITHUB_TOKEN`) |
+| `APP_PRIVATE_KEY` | No | GitHub App private key |
+
+### Optional variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `WIKI_MODEL` | `kimi-k2.7-code` | Model ID override |
+
+## Output
+
+Each run produces:
+
+```
+.wiki/
+├── .last-updated.json        # ISO timestamp of last run
+├── .last-update-report.md    # Change report (created/edited pages)
+├── config.json               # Project-specific config
+├── quickstart.md             # Entry point
+├── architecture/
+│   ├── index.md              # Auto-generated directory index
+│   └── overview.md
+├── cli/
+│   ├── index.md
+│   └── usage.md
+└── index.md                  # Root directory index
+```
+
+- `.last-updated.json` — `{ "lastUpdated": "2026-07-17T10:30:00.000Z" }`
+- `.last-update-report.md` — markdown report listing created and edited pages, used as the PR body in CI
+- `index.md` files — auto-generated for each directory, listing pages and subdirectories with frontmatter titles/descriptions
+
+## Development
+
+```bash
+bun install
+npx tsc -p tsconfig.json
+npx vitest run
+bun pm pack
+```
+
+## How it works
+
+1. The agent reads `AGENTS.md` or `CLAUDE.md` from the project root and follows all conventions documented there
+2. It inspects your source code using filesystem tools (read, grep, glob, execute)
+3. It generates wiki pages under `.wiki/` with YAML frontmatter
+4. After the run, `index.md` files are synchronized for each directory
+5. `.last-updated.json` and `.last-update-report.md` are written
+6. On `--init`, a GitHub Actions workflow is created for scheduled updates
+7. In update mode, only pages affected by recent changes are refreshed
+
+The agent uses a manual tool-calling loop with the Ollama chat API — no LangChain or LangGraph dependency. The recursion limit prevents infinite loops. The `execute` tool blocks self-invocation to prevent recursive runs.

package/dist/agent.d.ts

@@ -0,0 +1,35 @@
+import { type WikiCommand } from "./prompt.js";
+import { Ollama } from "ollama";
+export type AgentEvent = {
+    type: "assistant";
+    content: string;
+} | {
+    type: "tool";
+    name: string;
+    result: string;
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "done";
+    summary: string;
+};
+export interface RunOptions {
+    command: WikiCommand;
+    projectRoot: string;
+    model: string;
+    gitSummary?: string;
+    maxIterations?: number;
+    stream?: boolean;
+    onEvent?: (event: AgentEvent) => void;
+}
+export declare function runAgent(client: Ollama, options: RunOptions): Promise<void>;
+/**
+ * Generates a markdown report of what changed during this run.
+ * Written to .wiki/.last-update-report.md and used as the PR body.
+ */
+export declare function generateUpdateReport(command: WikiCommand, changedFiles: {
+    action: string;
+    path: string;
+    description?: string;
+}[]): string;

package/dist/agent.js

@@ -0,0 +1,317 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createSystemPrompt, createUserMessage } from "./prompt.js";
+import { createTools, executeTool } from "./tools.js";
+import { synchronizeWikiIndexes } from "./index-middleware.js";
+const DEFAULT_MAX_ITERATIONS = 200;
+function resolveMaxIterations() {
+    const env = process.env.WIKI_RECURSION_LIMIT;
+    if (!env) {
+        return DEFAULT_MAX_ITERATIONS;
+    }
+    const parsed = Number.parseInt(env, 10);
+    if (Number.isSafeInteger(parsed) && parsed > 0) {
+        return parsed;
+    }
+    return DEFAULT_MAX_ITERATIONS;
+}
+/**
+ * Normalizes tool call arguments to an object. The Ollama API returns
+ * arguments as a JSON string or as a parsed object depending on the model —
+ * handle both.
+ */
+function normalizeToolCallArgs(args) {
+    if (args === null || args === undefined) {
+        return {};
+    }
+    if (typeof args === "string") {
+        try {
+            const parsed = JSON.parse(args);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Malformed JSON — return empty so the tool gets called with no args
+            return {};
+        }
+        return {};
+    }
+    if (typeof args === "object" && !Array.isArray(args)) {
+        return args;
+    }
+    return {};
+}
+export async function runAgent(client, options) {
+    const { command, projectRoot, model, gitSummary, maxIterations, stream = false, onEvent = () => { }, } = options;
+    const maxIter = maxIterations ?? resolveMaxIterations();
+    const tools = createTools(projectRoot);
+    const systemPrompt = await createSystemPrompt(projectRoot);
+    const userMessage = createUserMessage(command, projectRoot, gitSummary);
+    const messages = [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userMessage },
+    ];
+    const changedFiles = [];
+    for (let i = 0; i < maxIter; i++) {
+        let assistantContent = "";
+        let toolCalls = [];
+        try {
+            if (stream) {
+                const streamResponse = await client.chat({
+                    model,
+                    messages: messages,
+                    tools: tools.map((t) => t.definition),
+                    stream: true,
+                });
+                for await (const chunk of streamResponse) {
+                    if (chunk.message?.content) {
+                        assistantContent += chunk.message.content;
+                        onEvent({ type: "assistant", content: chunk.message.content });
+                    }
+                    if (chunk.message?.tool_calls) {
+                        for (const tc of chunk.message.tool_calls) {
+                            if (tc.function?.name) {
+                                toolCalls.push({
+                                    function: {
+                                        name: tc.function.name,
+                                        arguments: normalizeToolCallArgs(tc.function.arguments),
+                                    },
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+            else {
+                const result = await client.chat({
+                    model,
+                    messages: messages,
+                    tools: tools.map((t) => t.definition),
+                    stream: false,
+                });
+                const msgContent = result.message?.content;
+                assistantContent = typeof msgContent === "string" ? msgContent : "";
+                onEvent({ type: "assistant", content: assistantContent });
+                if (result.message?.tool_calls) {
+                    for (const tc of result.message.tool_calls) {
+                        if (tc.function?.name) {
+                            toolCalls.push({
+                                function: {
+                                    name: tc.function.name,
+                                    arguments: normalizeToolCallArgs(tc.function.arguments),
+                                },
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (assistantContent) {
+                onEvent({
+                    type: "done",
+                    summary: `Agent completed with API warning: ${message}`,
+                });
+                break;
+            }
+            onEvent({ type: "error", message });
+            break;
+        }
+        const assistantMessage = {
+            role: "assistant",
+            content: assistantContent,
+            ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+        };
+        messages.push(assistantMessage);
+        if (toolCalls.length === 0) {
+            break;
+        }
+        for (const toolCall of toolCalls) {
+            const toolName = toolCall.function.name;
+            const args = toolCall.function.arguments;
+            onEvent({ type: "tool", name: toolName, result: "" });
+            const result = await executeTool(toolName, args, projectRoot);
+            if (toolName === "write_file" || toolName === "edit_file") {
+                const filePath = typeof args.path === "string" ? args.path : "unknown";
+                if (result.startsWith("Wrote ") || result.startsWith("Edited ")) {
+                    // Use the assistant's prose preceding this tool call as the
+                    // human-readable description of what changed. Falls back to the
+                    // tool result if the model didn't narrate the change.
+                    const description = assistantContent.trim() || result;
+                    changedFiles.push({
+                        action: toolName === "write_file" ? "created" : "edited",
+                        path: filePath,
+                        description,
+                    });
+                }
+            }
+            onEvent({ type: "tool", name: toolName, result });
+            // Ollama uses tool_name (not tool_call_id) to associate tool results
+            messages.push({
+                role: "tool",
+                content: result,
+                tool_name: toolName,
+            });
+        }
+    }
+    await createWorkflowFile(projectRoot);
+    onEvent({ type: "tool", name: "create_workflow", result: "Created .github/workflows/update-wiki.yml" });
+    if (changedFiles.length === 0) {
+        onEvent({ type: "done", summary: "Wiki is already current. No files changed." });
+        return;
+    }
+    await synchronizeWikiIndexes(path.join(projectRoot, ".wiki"));
+    await writeFile(path.join(projectRoot, ".wiki", ".last-updated.json"), JSON.stringify({ lastUpdated: new Date().toISOString() }, null, 2) + "\n", "utf8");
+    const report = generateUpdateReport(command, changedFiles);
+    await writeFile(path.join(projectRoot, ".wiki", ".last-update-report.md"), report, "utf8");
+    onEvent({ type: "done", summary: "Agent run complete" });
+}
+/**
+ * Creates a GitHub Actions workflow file in the target repo that checks out
+ * the wiki-agent source, builds it, and runs --update --print on a schedule.
+ */
+async function createWorkflowFile(projectRoot) {
+    const workflowsDir = path.join(projectRoot, ".github", "workflows");
+    const workflowPath = path.join(workflowsDir, "update-wiki.yml");
+    await mkdir(workflowsDir, { recursive: true });
+    const workflow = [
+        "name: Wiki Update",
+        "",
+        "on:",
+        "  workflow_dispatch:",
+        "  push:",
+        "    branches:",
+        "      - main",
+        "  schedule:",
+        '    - cron: "0 8 * * *"',
+        "",
+        "permissions:",
+        "  contents: write",
+        "  pull-requests: write",
+        "",
+        "jobs:",
+        "  update:",
+        "    runs-on: ubuntu-latest",
+        "    steps:",
+        "      - name: Generate token",
+        "        id: token",
+        "        uses: actions/create-github-app-token@v3",
+        "        with:",
+        "          client-id: ${{ secrets.APP_CLIENT_ID }}",
+        "          private-key: ${{ secrets.APP_PRIVATE_KEY }}",
+        "        continue-on-error: true",
+        "",
+        "      - name: Check out repository",
+        "        uses: actions/checkout@v7",
+        "        with:",
+        "          token: ${{ steps.token.outputs.token || secrets.GITHUB_TOKEN }}",
+        "",
+        "      - name: Set up Node.js",
+        "        uses: actions/setup-node@v7",
+        "        with:",
+        '          node-version: "25"',
+        "",
+        "      - name: Build Wiki Agent",
+        "        run: |",
+        "          git clone --branch main --depth 1 https://github.com/nx-solutions-ug/wiki-agent.git /tmp/wiki-agent",
+        "          cd /tmp/wiki-agent",
+        "          npm install",
+        "          npx tsc -p tsconfig.json",
+        "",
+        "      - name: Run Wiki Agent",
+        "        run: node /tmp/wiki-agent/dist/cli.js --update --print --verbose",
+        "        env:",
+        "          WIKI_OLLAMA_MODE: cloud",
+        '          WIKI_OLLAMA_API_KEY: ${{ secrets.WIKI_OLLAMA_API_KEY }}',
+        "          WIKI_MODEL: ${{ vars.WIKI_MODEL || 'kimi-k2.7-code' }}",
+        "      - name: Generate timestamp",
+        "        id: timestamp",
+        "        run: echo \"timestamp=$(date +%s)\" >> $GITHUB_OUTPUT",
+        "",
+        "      - name: Check for changes",
+        "        id: report",
+        "        run: |",
+        "          # Collect changes under .wiki (tracked + untracked), excluding",
+        "          # the run metadata files. Only content changes open a PR.",
+        "          changes=$(git status --porcelain .wiki | sed 's/^...//' | grep -vE '^\\.wiki/\\.(last-update-report\\.md|last-updated\\.json)$' | sed '/^[[:space:]]*$/d')",
+        "          if [ -n \"$changes\" ]; then",
+        "            echo \"has_changes=true\" >> $GITHUB_OUTPUT",
+        "            echo \"body<<EOF\" >> $GITHUB_OUTPUT",
+        "            cat .wiki/.last-update-report.md >> $GITHUB_OUTPUT",
+        "            echo \"\" >> $GITHUB_OUTPUT",
+        "            echo \"EOF\" >> $GITHUB_OUTPUT",
+        "          else",
+        "            echo \"has_changes=false\" >> $GITHUB_OUTPUT",
+        "          fi",
+        "",
+        "      - name: Create Wiki update pull request",
+        "        uses: peter-evans/create-pull-request@v8",
+        "        if: steps.report.outputs.has_changes == 'true'",
+        "        with:",
+        "          token: ${{ steps.token.outputs.token || secrets.GITHUB_TOKEN }}",
+        "          branch: wiki/update-${{ steps.timestamp.outputs.timestamp }}",
+        "          add-paths: .wiki",
+        '          title: "docs: update wiki"',
+        '          body: ${{ steps.report.outputs.body }}',
+    ].join("\n");
+    await writeFile(workflowPath, workflow, "utf8");
+}
+/**
+ * Generates a markdown report of what changed during this run.
+ * Written to .wiki/.last-update-report.md and used as the PR body.
+ */
+export function generateUpdateReport(command, changedFiles) {
+    const timestamp = new Date().toISOString();
+    const actionLabel = command === "init" ? "Initialized" : "Updated";
+    if (changedFiles.length === 0) {
+        return [
+            `# Wiki ${actionLabel}`,
+            "",
+            "No files were changed. The wiki is already current.",
+        ].join("\n") + "\n";
+    }
+    const created = changedFiles.filter((f) => f.action === "created");
+    const edited = changedFiles.filter((f) => f.action === "edited");
+    const lines = [
+        `# Wiki ${actionLabel}`,
+        "",
+        `Run completed at ${timestamp}.`,
+        "",
+    ];
+    if (created.length > 0) {
+        lines.push("## New pages", "");
+        for (const f of created) {
+            lines.push(`- \`${f.path}\``);
+            if (f.description && f.description.trim()) {
+                lines.push(...formatDescription(f.description));
+            }
+        }
+        lines.push("");
+    }
+    if (edited.length > 0) {
+        lines.push("## Updated pages", "");
+        for (const f of edited) {
+            lines.push(`- \`${f.path}\``);
+            if (f.description && f.description.trim()) {
+                lines.push(...formatDescription(f.description));
+            }
+        }
+        lines.push("");
+    }
+    lines.push("## Summary", "", `This ${command === "init" ? "initialization" : "update"} run ${created.length > 0 ? `created ${created.length} page${created.length > 1 ? "s" : ""}` : ""}${created.length > 0 && edited.length > 0 ? " and " : ""}${edited.length > 0 ? `edited ${edited.length} page${edited.length > 1 ? "s" : ""}` : ""}.`);
+    return lines.join("\n") + "\n";
+}
+/**
+ * Formats a change description as indented markdown under a file listing.
+ * Collapses whitespace, truncates overly long prose, and wraps it as a
+ * blockquote so it renders cleanly under the `- \`path\`` bullet.
+ */
+function formatDescription(description) {
+    const trimmed = description.trim().replace(/\s+/g, " ");
+    const maxLen = 500;
+    const text = trimmed.length > maxLen ? trimmed.slice(0, maxLen) + "…" : trimmed;
+    // Indent under the bullet as a nested blockquote
+    return ["", `  > ${text}`, ""];
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};