@chronova/wiki-agent 1.6.5 → 1.7.1

package/README.md

@@ -16,8 +16,8 @@ A standalone Ollama-only documentation agent. It inspects your source code and g
 - **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 staging PR body in CI
-- **Restricted toolset** — the agent can only read files, write under `.wiki/`, run read-only git subcommands, and inspect pull requests via a read-only `gh` CLI tool; there is no shell tool
-- **Staging PR staleness check** — before writing in update mode, the agent checks for open wiki staging PRs and abandons the update if a newer one already exists, preventing duplicate PRs
+- **Restricted toolset** — the agent can only read files, write under `.wiki/`, run read-only git subcommands, and use a `gh` CLI tool for inspecting pull requests and closing stale wiki staging PRs; there is no shell tool
+- **Staging PR staleness check** — before writing in update mode, the agent checks for open wiki staging PRs, abandons the update if a newer one already exists, and closes stale ones with a comment ("This branch is from an earlier staging run and is stale. Closing")
 - **Frontmatter stripping** — YAML frontmatter is stripped before publishing to the GitHub Wiki tab, since GitHub Wiki renders frontmatter as literal text
 
 ## Quickstart
@@ -120,7 +120,7 @@ For cloud:
 | `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` |
-| `GH_TOKEN` | GitHub token for the read-only `gh` CLI tool (used in CI for the staging PR staleness check) | from environment |
+| `GH_TOKEN` | GitHub token for the `gh` CLI tool (read-only inspection plus staging PR close/comment; used in CI for the staging PR staleness check) | from environment |
 
 Environment variables take priority over config files.
 
@@ -191,8 +191,8 @@ 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 a restricted, read-only toolset: `read_file`, `ls`, `glob`, `grep`, `ast_grep`, `ast_search`, a read-only `git` tool (whitelisted subcommands only — no mutating git, no shell), and a read-only `gh` CLI tool for inspecting pull requests and repository metadata
-3. In update mode, it checks for open wiki staging PRs via `gh pr list` and compares branch timestamps against the latest commit — if a newer staging PR already exists, it abandons the update to prevent duplicates
+2. It inspects your source code using a restricted toolset: `read_file`, `ls`, `glob`, `grep`, `ast_grep`, `ast_search`, a read-only `git` tool (whitelisted subcommands only — no mutating git, no shell), and a `gh` CLI tool for inspecting pull requests and managing stale wiki staging PRs
+3. In update mode, it checks for open wiki staging PRs via `gh pr list` and compares branch timestamps against the latest commit — if a newer staging PR already exists, it abandons the update; stale PRs (older branch timestamp) are closed with a comment ("This branch is from an earlier staging run and is stale. Closing")
 4. It generates wiki pages under `.wiki/` with YAML frontmatter using `write_file` and `edit_file` (the only mutating tools, constrained to `.wiki/`)
 5. After the run, `index.md` files are synchronized for each directory
 6. `.last-updated.json` and `.last-update-report.md` are written
@@ -200,4 +200,4 @@ bun pm pack
 8. In update mode, only pages affected by recent changes are refreshed
 9. With `--wiki`, the workflow flattens the `.wiki/` tree (stripping frontmatter, converting nested paths to flat dash-joined filenames, rewriting links) and publishes to the GitHub Wiki tab by pushing directly to `<repo>.wiki.git` `master`
 
-The agent uses a manual tool-calling loop with the Ollama chat API — no LangChain or LangGraph dependency. The recursion limit prevents infinite loops. There is no general-purpose shell tool; the agent cannot execute arbitrary commands on the host system. The `gh` tool is restricted to read-only subcommands (pr list, pr view, repo view, etc.) — mutating operations like create, merge, and close are blocked.
+The agent uses a manual tool-calling loop with the Ollama chat API — no LangChain or LangGraph dependency. The recursion limit prevents infinite loops. There is no general-purpose shell tool; the agent cannot execute arbitrary commands on the host system. The `gh` tool allows read-only inspection (pr list, pr view, repo view, etc.) plus `pr close` and `pr comment` — but only on wiki staging PRs (branches matching `wiki/staging-*`); all other mutating operations are blocked.

package/dist/prompt.js

@@ -34,9 +34,9 @@ You have a FIXED, LIMITED set of tools. You CANNOT execute arbitrary commands on
 - 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.
-- gh: run a READ-ONLY GitHub CLI (gh) subcommand in the project root. Use to inspect open pull requests, check wiki staging PR branches, and compare timestamps. Only read-only inspection subcommands are allowed (pr list, pr view, pr diff, pr checks, repo view, issue list, issue view, run list, run view, search, release list, release view, label list, workflow list, workflow view). Mutating operations (create, edit, close, merge, delete, etc.) are blocked.
+- gh: run a GitHub CLI (gh) subcommand in the project root. Read-only inspection is always allowed (pr list, pr view, pr diff, repo view, issue list, etc.). Two mutating operations are permitted ONLY on wiki staging PRs (branches matching wiki/staging-*): 'pr close' and 'pr comment'. All other mutating operations (create, merge, edit, delete, etc.) are blocked.
 
-You cannot run build tools, package managers, test runners, scripts, or any program other than git (read-only) and gh (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.
+You cannot run build tools, package managers, test runners, scripts, or any program other than git (read-only) and gh. 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.
@@ -78,8 +78,12 @@ Use only the tools listed above. Do not invent files, modules, APIs, business ru
 - Step 3: Get the repository's latest commit timestamp (also Unix seconds):
   git log -1 --format=%ct
 - Step 4: Compare the integers. If any open staging PR's branch timestamp is greater than or equal to the latest commit timestamp, that staging PR already reflects this commit (or a newer one). Abandon the update: do not write or edit any files. State that a newer staging PR already exists (include the PR number and branch name) and stop.
+- Step 5: Close stale staging PRs. For every open wiki/staging-* PR whose branch timestamp is LESS than the latest commit timestamp (i.e. it is older than the current commit), close it with a comment:
+  gh pr comment <number> --body "This branch is from an earlier staging run and is stale. Closing"
+  gh pr close <number>
+  Do this BEFORE proceeding with your own update. This keeps the PR queue clean and avoids confusing reviewers with outdated snapshots.
 - If the gh command fails (e.g. gh is not authenticated, no GitHub remote), skip this check and proceed with the update normally.
-- This check prevents duplicate staging PRs and avoids overwriting a newer pending review with older content.
+- This check prevents duplicate staging PRs, closes stale ones, and avoids overwriting a newer pending review with older content.
 
 # Loop prevention
 - Work in phases: discover → plan → write → verify. Do not restart discovery once you have moved to planning or writing.

package/dist/tools.js

@@ -444,13 +444,13 @@ export function createTools(projectRoot) {
             type: "function",
             function: {
                 name: "gh",
-                description: "Run a read-only GitHub CLI (gh) subcommand in the project root. Use to inspect open pull requests, check wiki staging PR branches, and compare timestamps. Only read-only inspection subcommands are permitted — no mutating operations (create, edit, close, merge, delete, etc.).",
+                description: "Run a GitHub CLI (gh) subcommand in the project root. Read-only inspection (pr list, pr view, pr diff, repo view, issue list, etc.) is always allowed. Two mutating operations are permitted but ONLY on wiki staging PRs (branches matching wiki/staging-*): `gh pr close <number>` and `gh pr comment <number> --body <text>`. Use to inspect open PRs, check staging branch timestamps, and close stale wiki staging PRs with a comment.",
                 parameters: {
                     type: "object",
                     properties: {
                         args: {
                             type: "string",
-                            description: "gh subcommand and arguments, without the leading 'gh'. Example: 'pr list --state open --head wiki/staging-* --json headRefName,updatedAt,number,title', 'pr view <number> --json updatedAt,headRefName,body', 'pr view <number> --json files'.",
+                            description: "gh subcommand and arguments, without the leading 'gh'. Example: 'pr list --state open --json number,headRefName,title', 'pr view <number> --json headRefName', 'pr close <number> --comment \"This branch is from an earlier staging run and is stale. Closing\"', 'pr comment <number> --body \"stale\"'.",
                         },
                     },
                     required: ["args"],
@@ -459,33 +459,57 @@ export function createTools(projectRoot) {
         },
         handler: async (args) => {
             const argString = args.args ?? "";
-            // Only read-only / inspection subcommands are permitted. The agent
-            // cannot mutate GitHub state through this tool.
             const ALLOWED_GH_SUBCOMMANDS = {
                 pr: true, issue: true, repo: true, run: true, api: true,
                 "search": true, release: true, label: true, workflow: true,
             };
-            // Mutating subcommand prefixes that must never run, even under an
-            // allowed top-level command (e.g. `gh pr create`, `gh pr merge`).
+            // Actions that are always blocked (never safe for an automated agent).
             const BLOCKED_ACTIONS = {
-                create: true, edit: true, close: true, reopen: true, merge: true,
-                delete: true, ready: true, review: true, comment: true,
+                create: true, edit: true, reopen: true, merge: true,
+                delete: true, ready: true, review: true,
                 lock: true, unlock: true, assign: true, unassign: true,
                 label: true, unlabel: true, transfer: true, archive: true,
                 unarchive: true, deploy: true, rerun: true, cancel: true,
                 publish: true, set: true, add: true, remove: true,
             };
+            // Actions allowed ONLY on wiki staging PRs (branches matching
+            // wiki/staging-*). The handler verifies the PR's headRefName before
+            // executing these.
+            const STAGING_ONLY_ACTIONS = {
+                close: true, comment: true,
+            };
             const tokens = argString.trim().split(/\s+/);
             const subcommand = tokens[0] ?? "";
             if (!ALLOWED_GH_SUBCOMMANDS[subcommand]) {
-                return `Error: gh subcommand '${subcommand}' is not permitted. Only read-only inspection subcommands are allowed (pr, issue, repo, run, api, search, release, label, workflow).`;
+                return `Error: gh subcommand '${subcommand}' is not permitted. Only inspection subcommands and pr close/comment on wiki staging PRs are allowed (pr, issue, repo, run, api, search, release, label, workflow).`;
             }
-            // For `gh pr` and similar, check the action token (second token)
-            // against the blocklist. `gh pr list`, `gh pr view`, `gh pr diff`,
-            // `gh pr checks` are read-only and allowed.
             const action = tokens[1] ?? "";
             if (BLOCKED_ACTIONS[action]) {
-                return `Error: gh ${subcommand} ${action} is a mutating operation. Only read-only inspection is allowed (list, view, diff, checks, status).`;
+                return `Error: gh ${subcommand} ${action} is a blocked operation.`;
+            }
+            // For close/comment on PRs, verify the target is a wiki staging PR.
+            // The PR number is the third token: 'gh pr close <number>' or
+            // 'gh pr comment <number> --body ...'.
+            if (STAGING_ONLY_ACTIONS[action] && subcommand === "pr") {
+                const prNumber = tokens[2] ?? "";
+                if (!/^\d+$/.test(prNumber)) {
+                    return `Error: a valid PR number is required for gh pr ${action}.`;
+                }
+                // Fetch the PR's headRefName to verify it's a wiki staging branch.
+                try {
+                    const { stdout } = await execAsync(`gh pr view ${prNumber} --json headRefName`, { cwd: projectRoot, maxBuffer: 1024 * 1024, timeout: 30_000 });
+                    const parsed = JSON.parse(stdout);
+                    if (!parsed.headRefName?.startsWith("wiki/staging-")) {
+                        return `Error: gh pr ${action} is only permitted on wiki staging PRs (branches matching wiki/staging-*). PR #${prNumber} has headRefName '${parsed.headRefName ?? "unknown"}'.`;
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    return `Error: could not verify PR #${prNumber} is a wiki staging PR: ${message}`;
+                }
+            }
+            else if (STAGING_ONLY_ACTIONS[action]) {
+                return `Error: gh ${subcommand} ${action} is not supported. Only gh pr ${action} is permitted, and only on wiki staging PRs.`;
             }
             // Reject shell metacharacters that could chain commands or inject
             // flags, same guard as the git tool.

package/dist/tui/App.js

@@ -2,6 +2,7 @@ import React, { useState, useCallback } from "react";
 import { Box, Text, useApp, useInput } from "ink";
 import { CredentialsSetup } from "./CredentialsSetup.js";
 import { RunView } from "./RunView.js";
+import { VERSION } from "../version.js";
 export function App({ command, cwd, config, verbose, wiki }) {
     const [needsSetup, setNeedsSetup] = useState(config.mode === "cloud" && !config.apiKey);
     const [resolvedConfig, setResolvedConfig] = useState(config);
@@ -21,7 +22,7 @@ export function App({ command, cwd, config, verbose, wiki }) {
             onConfigSaved: handleConfigSaved,
         });
     }
-    return React.createElement(Box, { flexDirection: "column" }, React.createElement(Box, { borderStyle: "round", borderColor: "cyan", paddingX: 1 }, React.createElement(Text, null, React.createElement(Text, { bold: true }, "Wiki Agent v0.1.0"), " | ", React.createElement(Text, { color: "cyan" }, `Ollama (${resolvedConfig.mode})`), " | ", React.createElement(Text, { color: "gray" }, `model: ${resolvedConfig.model}`), " | ", React.createElement(Text, { color: "gray" }, cwd))), React.createElement(RunView, {
+    return React.createElement(Box, { flexDirection: "column" }, React.createElement(Box, { borderStyle: "round", borderColor: "cyan", paddingX: 1 }, React.createElement(Text, null, React.createElement(Text, { bold: true }, `Wiki Agent v${VERSION}`), " | ", React.createElement(Text, { color: "cyan" }, `Ollama (${resolvedConfig.mode})`), " | ", React.createElement(Text, { color: "gray" }, `model: ${resolvedConfig.model}`), " | ", React.createElement(Text, { color: "gray" }, cwd))), React.createElement(RunView, {
         command,
         cwd,
         config: resolvedConfig,

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,6 @@
+import { createRequire } from "node:module";
+// Read the version from package.json so the TUI and CLI stay in sync
+// with releases without a hardcoded string to update.
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+export const VERSION = pkg.version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronova/wiki-agent",
-  "version": "1.6.5",
+  "version": "1.7.1",
   "description": "Standalone Ollama-only documentation agent",
   "type": "module",
   "bin": {