@biaoo/tiangong-wiki 0.2.3 → 0.3.1

package/README.md

@@ -99,7 +99,112 @@ tiangong-wiki dashboard                               # open dashboard in browse
 # or: tiangong-wiki daemon run                        # run the daemon in the foreground for debugging
 ```
 
-> Environment variables are managed via `.wiki.env` (created by `tiangong-wiki setup`). The CLI prefers the nearest local `.wiki.env`, then falls back to the global default workspace config. See [references/troubleshooting.md](./references/troubleshooting.md) for the full reference.
+> Environment variables are managed via `.wiki.env` (created by `tiangong-wiki setup`). The CLI prefers the nearest local `.wiki.env`, then falls back to the global default workspace config. See [references/troubleshooting.md](./references/troubleshooting.md) for the full reference. For a centralized Linux + `systemd` + Nginx deployment, see [references/centralized-service-deployment.md](./references/centralized-service-deployment.md). That deployment guide now also includes Git repository / GitHub remote setup for daemon-side commit and optional auto-push.
+
+## MCP Server
+
+Tiangong Wiki ships a separate MCP adapter that talks to the daemon over HTTP. It uses the MCP Streamable HTTP transport, not stdio.
+
+Start it after the daemon is already listening:
+
+```bash
+tiangong-wiki daemon run
+```
+
+In another shell:
+
+```bash
+export WIKI_DAEMON_BASE_URL=http://127.0.0.1:8787
+export WIKI_MCP_HOST=127.0.0.1
+export WIKI_MCP_PORT=9400
+export WIKI_MCP_PATH=/mcp
+
+tiangong-wiki-mcp-server
+```
+
+The server prints a JSON line like:
+
+```json
+{"status":"listening","host":"127.0.0.1","port":9400,"healthUrl":"http://127.0.0.1:9400/health","mcpUrl":"http://127.0.0.1:9400/mcp"}
+```
+
+If you are running from a source checkout instead of a global install:
+
+```bash
+npm install
+npm run build
+
+WIKI_DAEMON_BASE_URL=http://127.0.0.1:8787 \
+WIKI_MCP_PORT=9400 \
+node mcp-server/dist/index.js
+
+# or during development
+npm run dev:mcp-server
+```
+
+Required MCP-side environment variables:
+
+- `WIKI_DAEMON_BASE_URL`: base URL of the wiki daemon, for example `http://127.0.0.1:8787`
+- `WIKI_MCP_HOST`: bind host for the MCP HTTP server, default `127.0.0.1`
+- `WIKI_MCP_PORT`: bind port for the MCP HTTP server, default random free port
+- `WIKI_MCP_PATH`: MCP route path, default `/mcp`
+
+Bearer token note:
+
+- Bearer tokens are not configured in `.wiki.env`, daemon env, or MCP env
+- In the current V1 deployment model, Bearer tokens live in the reverse proxy config
+- See [references/examples/centralized-service/nginx-centralized-wiki.conf](./references/examples/centralized-service/nginx-centralized-wiki.conf) for the current `map $http_authorization ...` example
+- In production, keep token values in a private Nginx include file such as `/etc/nginx/snippets/wiki-auth-tokens.conf`, then `include` it from the main site config instead of hardcoding secrets in the repo
+
+## Using the MCP From Clients
+
+Any MCP client that supports Streamable HTTP can connect to the MCP endpoint:
+
+- Local debug endpoint: `http://127.0.0.1:9400/mcp`
+- Health check: `http://127.0.0.1:9400/health`
+- Production recommendation: expose `/mcp` behind a reverse proxy and keep daemon/MCP bound to loopback
+
+Read tools can be called directly. Write tools such as `wiki_page_create`, `wiki_page_update`, and `wiki_sync` require these headers:
+
+- `x-wiki-actor-id`
+- `x-wiki-actor-type`
+- `x-request-id`
+
+In production, the recommended model is: the client sends `Authorization: Bearer ...` to the reverse proxy, the proxy validates the token there, and the proxy injects the actor headers before forwarding to the MCP server. For local debugging without a proxy, your client must send those headers itself when calling write tools.
+
+Minimal Node.js MCP client example:
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const transport = new StreamableHTTPClientTransport(new URL("http://127.0.0.1:9400/mcp"), {
+  requestInit: {
+    headers: {
+      "x-wiki-actor-id": "agent:demo",
+      "x-wiki-actor-type": "agent",
+      "x-request-id": "req-demo-1",
+    },
+  },
+});
+
+const client = new Client({ name: "demo-client", version: "1.0.0" });
+await client.connect(transport);
+
+const tools = await client.listTools();
+const search = await client.callTool({
+  name: "wiki_search",
+  arguments: { query: "bayes", limit: 5 },
+});
+```
+
+Current MCP tools include:
+
+- Query: `wiki_find`, `wiki_fts`, `wiki_search`, `wiki_graph`
+- Page: `wiki_page_info`, `wiki_page_read`, `wiki_page_create`, `wiki_page_update`
+- Type: `wiki_type_list`, `wiki_type_show`, `wiki_type_recommend`
+- Vault: `wiki_vault_list`, `wiki_vault_queue`
+- Maintenance: `wiki_sync`, `wiki_lint`
 
 ## CLI
 

package/README.zh-CN.md

@@ -99,7 +99,112 @@ tiangong-wiki dashboard                               # 在浏览器中打开仪
 # 或者：tiangong-wiki daemon run                      # 前台运行 daemon，适合调试
 ```
 
-> 环境变量通过 `.wiki.env` 管理（由 `tiangong-wiki setup` 创建）。CLI 会优先使用最近的本地 `.wiki.env`，找不到时再 fallback 到全局默认工作区配置。完整参考见 [references/troubleshooting.md](./references/troubleshooting.md)。
+> 环境变量通过 `.wiki.env` 管理（由 `tiangong-wiki setup` 创建）。CLI 会优先使用最近的本地 `.wiki.env`，找不到时再 fallback 到全局默认工作区配置。完整参考见 [references/troubleshooting.md](./references/troubleshooting.md)。如需部署中心化服务（Linux + `systemd` + Nginx），见 [references/centralized-service-deployment.md](./references/centralized-service-deployment.md)。该部署文档现在也包含了 Git 仓库初始化、GitHub remote 配置和 daemon 自动 push 的 Git 配置说明。
+
+## MCP Server
+
+Tiangong Wiki 提供了独立的 MCP 适配层，通过 HTTP 调用 daemon。它使用的是 MCP 的 Streamable HTTP 传输，不是 stdio。
+
+启动 MCP 前，先确保 daemon 已经在监听：
+
+```bash
+tiangong-wiki daemon run
+```
+
+另开一个终端：
+
+```bash
+export WIKI_DAEMON_BASE_URL=http://127.0.0.1:8787
+export WIKI_MCP_HOST=127.0.0.1
+export WIKI_MCP_PORT=9400
+export WIKI_MCP_PATH=/mcp
+
+tiangong-wiki-mcp-server
+```
+
+启动后会输出一行 JSON，例如：
+
+```json
+{"status":"listening","host":"127.0.0.1","port":9400,"healthUrl":"http://127.0.0.1:9400/health","mcpUrl":"http://127.0.0.1:9400/mcp"}
+```
+
+如果你不是通过全局安装使用，而是在源码仓库里运行：
+
+```bash
+npm install
+npm run build
+
+WIKI_DAEMON_BASE_URL=http://127.0.0.1:8787 \
+WIKI_MCP_PORT=9400 \
+node mcp-server/dist/index.js
+
+# 或者开发态运行
+npm run dev:mcp-server
+```
+
+MCP 侧需要的环境变量：
+
+- `WIKI_DAEMON_BASE_URL`：wiki daemon 的 base URL，例如 `http://127.0.0.1:8787`
+- `WIKI_MCP_HOST`：MCP HTTP 服务绑定地址，默认 `127.0.0.1`
+- `WIKI_MCP_PORT`：MCP HTTP 服务绑定端口，默认随机空闲端口
+- `WIKI_MCP_PATH`：MCP 路由路径，默认 `/mcp`
+
+Bearer token 说明：
+
+- Bearer token 不配置在 `.wiki.env`、daemon env 或 MCP env 里
+- 当前 V1 部署模型里，Bearer token 配在反向代理层
+- 具体示例见 [references/examples/centralized-service/nginx-centralized-wiki.conf](./references/examples/centralized-service/nginx-centralized-wiki.conf) 中的 `map $http_authorization ...`
+- 生产环境建议把 token 放在私有的 Nginx include 文件中，例如 `/etc/nginx/snippets/wiki-auth-tokens.conf`，再由主站点配置 `include` 进来，不要把真实密钥硬编码在仓库示例里
+
+## 客户端如何使用这个 MCP
+
+任何支持 Streamable HTTP 的 MCP client 都可以连接到这个服务：
+
+- 本地调试地址：`http://127.0.0.1:9400/mcp`
+- 健康检查：`http://127.0.0.1:9400/health`
+- 生产环境建议：对外只暴露反向代理后的 `/mcp`，daemon 和 MCP 自身只监听 loopback
+
+读工具可以直接调用。写工具，如 `wiki_page_create`、`wiki_page_update`、`wiki_sync`，额外要求这些 header：
+
+- `x-wiki-actor-id`
+- `x-wiki-actor-type`
+- `x-request-id`
+
+生产环境推荐模式是：客户端只向反向代理发送 `Authorization: Bearer ...`，由反向代理在代理层完成 token 校验，并在转发到 MCP server 前注入 actor headers。若你在本地直接连 MCP 做调试，则需要由客户端自己带上这些 header 才能调用写工具。
+
+最小 Node.js MCP client 示例：
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const transport = new StreamableHTTPClientTransport(new URL("http://127.0.0.1:9400/mcp"), {
+  requestInit: {
+    headers: {
+      "x-wiki-actor-id": "agent:demo",
+      "x-wiki-actor-type": "agent",
+      "x-request-id": "req-demo-1",
+    },
+  },
+});
+
+const client = new Client({ name: "demo-client", version: "1.0.0" });
+await client.connect(transport);
+
+const tools = await client.listTools();
+const search = await client.callTool({
+  name: "wiki_search",
+  arguments: { query: "bayes", limit: 5 },
+});
+```
+
+当前 MCP tools 包括：
+
+- 查询：`wiki_find`、`wiki_fts`、`wiki_search`、`wiki_graph`
+- 页面：`wiki_page_info`、`wiki_page_read`、`wiki_page_create`、`wiki_page_update`
+- 类型：`wiki_type_list`、`wiki_type_show`、`wiki_type_recommend`
+- Vault：`wiki_vault_list`、`wiki_vault_queue`
+- 维护：`wiki_sync`、`wiki_lint`
 
 ## CLI
 

package/dist/commands/create.js

@@ -1,4 +1,5 @@
 import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { buildCliWriteActor } from "../daemon/write-actor.js";
 import { createPage } from "../operations/write.js";
 import { writeJson } from "../utils/output.js";
 export function registerCreateCommand(program) {
@@ -20,7 +21,9 @@ export function registerCreateCommand(program) {
                 endpoint,
                 method: "POST",
                 path: "/create",
+                timeoutMs: 310_000,
                 body: {
+                    actor: buildCliWriteActor(process.env),
                     type: options.type,
                     title: options.title,
                     nodeId: options.nodeId ?? undefined,

package/dist/commands/sync.js

@@ -1,4 +1,5 @@
 import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { buildCliWriteActor } from "../daemon/write-actor.js";
 import { runSyncCommand } from "../operations/write.js";
 import { writeJson } from "../utils/output.js";
 export function registerSyncCommand(program) {
@@ -24,7 +25,9 @@ export function registerSyncCommand(program) {
                 endpoint,
                 method: "POST",
                 path: "/sync",
+                timeoutMs: 310_000,
                 body: {
+                    actor: buildCliWriteActor(process.env),
                     path: options.path ?? undefined,
                     force: options.force === true,
                     skipEmbedding: options.skipEmbedding === true,

package/dist/commands/template.js

@@ -1,4 +1,5 @@
 import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { buildCliWriteActor } from "../daemon/write-actor.js";
 import { renderTemplateLintResult, runTemplateLint } from "../operations/template-lint.js";
 import { createTemplate, listTemplates, showTemplate } from "../operations/type-template.js";
 import { ensureTextOrJson, writeJson, writeText } from "../utils/output.js";
@@ -90,7 +91,9 @@ export function registerTemplateCommand(program) {
                 endpoint,
                 method: "POST",
                 path: "/template/create",
+                timeoutMs: 310_000,
                 body: {
+                    actor: buildCliWriteActor(process.env),
                     type: options.type,
                     title: options.title,
                 },

package/dist/core/db.js

@@ -149,6 +149,25 @@ function ensureBaseTables(db, embeddingDimensions) {
       key TEXT PRIMARY KEY,
       value TEXT
     );
+
+    CREATE TABLE IF NOT EXISTS daemon_write_jobs (
+      job_id TEXT PRIMARY KEY,
+      task_type TEXT NOT NULL,
+      status TEXT NOT NULL,
+      enqueued_at TEXT NOT NULL,
+      started_at TEXT,
+      finished_at TEXT,
+      duration_ms INTEGER,
+      timeout_ms INTEGER NOT NULL,
+      queue_depth_at_enqueue INTEGER NOT NULL DEFAULT 0,
+      result_summary TEXT,
+      error_message TEXT,
+      error_details TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_daemon_write_jobs_status ON daemon_write_jobs(status);
+    CREATE INDEX IF NOT EXISTS idx_daemon_write_jobs_enqueued_at ON daemon_write_jobs(enqueued_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_daemon_write_jobs_finished_at ON daemon_write_jobs(finished_at DESC);
   `);
     ensureTableColumns(db, "vault_processing_queue", {
         claimed_at: "TEXT",
@@ -191,6 +210,16 @@ export function getMeta(db, key) {
     const row = db.prepare("SELECT value FROM sync_meta WHERE key = ?").get(key);
     return row?.value ?? null;
 }
+export function getVectorTableDimensions(db) {
+    const row = db.prepare("SELECT sql FROM sqlite_master WHERE name = 'vec_pages'").get();
+    const sql = row?.sql ?? "";
+    const match = sql.match(/embedding\s+float\[(\d+)\]/i);
+    if (!match) {
+        return null;
+    }
+    const dimensions = Number.parseInt(match[1], 10);
+    return Number.isFinite(dimensions) && dimensions > 0 ? dimensions : null;
+}
 export function setMeta(db, key, value) {
     if (value === null) {
         db.prepare("DELETE FROM sync_meta WHERE key = ?").run(key);
@@ -276,6 +305,8 @@ export function openDb(dbPath, config, embeddingDimensions) {
     sqliteVec.load(db);
     ensureBaseTables(db, embeddingDimensions);
     ensureFtsTable(db);
+    const vectorDimensions = getVectorTableDimensions(db);
+    const vectorDimensionsChanged = vectorDimensions !== null && vectorDimensions !== embeddingDimensions;
     const storedSchemaVersion = getMeta(db, "schema_version");
     if (storedSchemaVersion && storedSchemaVersion !== SCHEMA_VERSION) {
         db.close();
@@ -288,5 +319,5 @@ export function openDb(dbPath, config, embeddingDimensions) {
         schema_version: SCHEMA_VERSION,
         ...(storedConfigVersion === null ? { config_version: config.configVersion } : {}),
     });
-    return { db, configChanged };
+    return { db, configChanged, vectorDimensions, vectorDimensionsChanged };
 }

package/dist/core/page-source.js

@@ -0,0 +1,25 @@
+import { parsePage } from "./frontmatter.js";
+import { normalizePageId, resolvePagePath } from "./paths.js";
+import { pathExistsSync, readTextFileSync, sha256Text } from "../utils/fs.js";
+export function buildPageRevision(rawMarkdown) {
+    if (rawMarkdown === null) {
+        return null;
+    }
+    return sha256Text(rawMarkdown);
+}
+export function readCanonicalPageSource(filePath, wikiPath, config) {
+    const pageId = normalizePageId(filePath, wikiPath);
+    const rawMarkdown = pathExistsSync(filePath) ? readTextFileSync(filePath) : null;
+    const parsed = rawMarkdown === null ? null : parsePage(filePath, wikiPath, config);
+    return {
+        pageId,
+        pagePath: filePath,
+        rawMarkdown,
+        frontmatter: parsed?.ok ? parsed.parsed.rawData : {},
+        revision: buildPageRevision(rawMarkdown),
+    };
+}
+export function readCanonicalPageSourceById(pageId, wikiPath, config) {
+    const canonicalPageId = normalizePageId(pageId, wikiPath);
+    return readCanonicalPageSource(resolvePagePath(canonicalPageId, wikiPath), wikiPath, config);
+}

package/dist/core/paths.js

@@ -155,6 +155,7 @@ export function resolveRuntimePaths(env = process.env) {
         daemonPidPath: path.join(wikiRoot, ".wiki-daemon.pid"),
         daemonLogPath: path.join(wikiRoot, ".wiki-daemon.log"),
         daemonStatePath: path.join(wikiRoot, ".wiki-daemon.state.json"),
+        auditLogPath: path.join(wikiRoot, "..", ".wiki-runtime", "audit.ndjson"),
     };
 }
 export function normalizePageId(inputPath, wikiPath) {

package/dist/core/runtime.js

@@ -15,6 +15,6 @@ export function loadRuntimeConfig(env = process.env) {
 export function openRuntimeDb(env = process.env) {
     const { paths, config } = loadRuntimeConfig(env);
     const embeddingClient = EmbeddingClient.fromEnv(env);
-    const { db } = openDb(paths.dbPath, config, embeddingClient?.settings.dimensions ?? getEmbeddingDimensionFromEnv(env));
-    return { db, paths, config, embeddingClient };
+    const { db, vectorDimensions, vectorDimensionsChanged } = openDb(paths.dbPath, config, embeddingClient?.settings.dimensions ?? getEmbeddingDimensionFromEnv(env));
+    return { db, paths, config, embeddingClient, vectorDimensions, vectorDimensionsChanged };
 }

package/dist/core/sync.js

@@ -78,17 +78,18 @@ export async function syncWorkspace(options = {}) {
     }
     const config = loadConfig(runtimePaths.configPath);
     const embeddingClient = EmbeddingClient.fromEnv(env);
-    const { db, configChanged } = openDb(runtimePaths.dbPath, config, embeddingClient?.settings.dimensions ?? getEmbeddingDimension(env));
+    const { db, configChanged, vectorDimensionsChanged } = openDb(runtimePaths.dbPath, config, embeddingClient?.settings.dimensions ?? getEmbeddingDimension(env));
     try {
         let mode = options.targetPaths && options.targetPaths.length > 0 && !options.force ? "path" : "full";
         let upgradedToFullSync = false;
         const storedEmbeddingProfile = embeddingClient ? getMeta(db, "embedding_profile") : null;
         const profileChanged = Boolean(embeddingClient && storedEmbeddingProfile && storedEmbeddingProfile !== embeddingClient.profileHash);
-        if (mode === "path" && (configChanged || profileChanged)) {
+        const embeddingDrift = profileChanged || vectorDimensionsChanged;
+        if (mode === "path" && (configChanged || embeddingDrift)) {
             mode = "full";
             upgradedToFullSync = true;
         }
-        if (profileChanged && options.skipEmbedding) {
+        if (embeddingDrift && options.skipEmbedding) {
             throw new AppError("Embedding profile changed, cannot skip embedding.", "config");
         }
         if (options.force) {
@@ -112,7 +113,7 @@ export async function syncWorkspace(options = {}) {
             });
         }
         let embedAll = false;
-        if (embeddingClient && profileChanged) {
+        if (embeddingClient && embeddingDrift) {
             resetVectorTable(db, embeddingClient.settings.dimensions);
             db.prepare("UPDATE pages SET embedding_status = 'pending'").run();
             embedAll = true;
@@ -160,7 +161,7 @@ export async function syncWorkspace(options = {}) {
             mode,
             upgradedToFullSync,
             configChanged,
-            profileChanged,
+            profileChanged: embeddingDrift,
             inserted: applyResult.inserted.length,
             updated: applyResult.updated.length,
             deleted: applyResult.deleted.length,

package/dist/daemon/audit-log.js

@@ -0,0 +1,18 @@
+import { appendFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { ensureDirSync } from "../utils/fs.js";
+import { toOffsetIso } from "../utils/time.js";
+export function appendAuditEvent(paths, actor, input) {
+    ensureDirSync(path.dirname(paths.auditLogPath));
+    const event = {
+        eventId: randomUUID(),
+        timestamp: toOffsetIso(),
+        requestId: actor.requestId,
+        actorId: actor.actorId,
+        actorType: actor.actorType,
+        ...input,
+    };
+    appendFileSync(paths.auditLogPath, `${JSON.stringify(event)}\n`, "utf8");
+    return event;
+}

package/dist/daemon/client.js

@@ -124,7 +124,7 @@ export async function requestDaemonJson(options) {
         method: options.method,
         headers: options.body === undefined ? undefined : { "content-type": "application/json" },
         body: options.body === undefined ? undefined : JSON.stringify(options.body),
-    }, 5_000);
+    }, options.timeoutMs ?? (options.method === "POST" ? 310_000 : 5_000));
 }
 function warnReadFallback(availability) {
     const location = availability.state

package/dist/daemon/git-journal.js

@@ -0,0 +1,114 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { pathExistsSync } from "../utils/fs.js";
+import { AppError } from "../utils/errors.js";
+function buildGitEnv(actor) {
+    const emailLocalPart = actor.actorId.replace(/[^A-Za-z0-9._-]+/g, "_");
+    return {
+        ...process.env,
+        GIT_AUTHOR_NAME: actor.actorId,
+        GIT_AUTHOR_EMAIL: `${emailLocalPart}@tiangong-wiki.local`,
+        GIT_COMMITTER_NAME: actor.actorId,
+        GIT_COMMITTER_EMAIL: `${emailLocalPart}@tiangong-wiki.local`,
+    };
+}
+function runGit(paths, actor, args) {
+    const result = spawnSync("git", ["-C", paths.wikiRoot, ...args], {
+        encoding: "utf8",
+        env: buildGitEnv(actor),
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+function collectStageTargets(paths) {
+    return [
+        path.relative(paths.wikiRoot, paths.wikiPath),
+        path.relative(paths.wikiRoot, paths.dbPath),
+        path.relative(paths.wikiRoot, paths.templatesPath),
+        path.relative(paths.wikiRoot, paths.configPath),
+        path.relative(paths.wikiRoot, paths.queueArtifactsPath),
+    ].filter((entry, index, values) => entry && !entry.startsWith("..") && values.indexOf(entry) === index && pathExistsSync(path.join(paths.wikiRoot, entry)));
+}
+export function commitWriteJournal(paths, actor, input) {
+    const gitRoot = runGit(paths, actor, ["rev-parse", "--show-toplevel"]);
+    if (gitRoot.status !== 0) {
+        throw new AppError("Git repository not initialized for wiki root.", "runtime", {
+            code: "git_commit_failed",
+            stderr: gitRoot.stderr.trim() || gitRoot.stdout.trim(),
+        });
+    }
+    const targets = collectStageTargets(paths);
+    const addResult = runGit(paths, actor, ["add", "-A", "--", ...targets]);
+    if (addResult.status !== 0) {
+        throw new AppError("Failed to stage wiki changes for Git commit.", "runtime", {
+            code: "git_commit_failed",
+            stderr: addResult.stderr.trim() || addResult.stdout.trim(),
+        });
+    }
+    const diffResult = runGit(paths, actor, ["diff", "--cached", "--quiet", "--exit-code"]);
+    if (diffResult.status === 0) {
+        return {
+            status: "no_changes",
+            commitHash: null,
+        };
+    }
+    if (diffResult.status !== 1) {
+        throw new AppError("Failed to inspect staged Git changes.", "runtime", {
+            code: "git_commit_failed",
+            stderr: diffResult.stderr.trim() || diffResult.stdout.trim(),
+        });
+    }
+    const commitMessage = `wiki: ${input.operation} ${input.resourceId ?? "*"} by ${actor.actorId}`;
+    const commitResult = runGit(paths, actor, ["commit", "-m", commitMessage]);
+    if (commitResult.status !== 0) {
+        throw new AppError("Failed to create Git journal commit.", "runtime", {
+            code: "git_commit_failed",
+            stderr: commitResult.stderr.trim() || commitResult.stdout.trim(),
+            commitMessage,
+        });
+    }
+    const hashResult = runGit(paths, actor, ["rev-parse", "HEAD"]);
+    if (hashResult.status !== 0) {
+        throw new AppError("Failed to resolve Git commit hash.", "runtime", {
+            code: "git_commit_failed",
+            stderr: hashResult.stderr.trim() || hashResult.stdout.trim(),
+        });
+    }
+    return {
+        status: "committed",
+        commitHash: hashResult.stdout.trim(),
+    };
+}
+export class GitPushScheduler {
+    paths;
+    log;
+    enabled;
+    delayMs;
+    remote;
+    timer = null;
+    constructor(paths, log, env = process.env) {
+        this.paths = paths;
+        this.log = log;
+        this.enabled = (env.WIKI_GIT_AUTO_PUSH ?? "").trim().toLowerCase() === "true";
+        this.delayMs = Number.parseInt(env.WIKI_GIT_PUSH_DELAY_MS ?? "3000", 10) || 3000;
+        this.remote = env.WIKI_GIT_PUSH_REMOTE?.trim() || "origin";
+    }
+    schedule(actor) {
+        if (!this.enabled || this.timer) {
+            return false;
+        }
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            const result = runGit(this.paths, actor, ["push", this.remote, "HEAD"]);
+            if (result.status === 0) {
+                this.log(`git push ok remote=${this.remote}`);
+                return;
+            }
+            this.log(`git push failed remote=${this.remote}: ${result.stderr.trim() || result.stdout.trim()}`);
+        }, this.delayMs);
+        return true;
+    }
+}