@biaoo/tiangong-wiki 0.2.0

package/dist/commands/setup.js

@@ -0,0 +1,15 @@
+import { getPackageRoot } from "../core/paths.js";
+import { runSetupWizard } from "../core/onboarding.js";
+export function registerSetupCommand(program) {
+    program
+        .command("setup")
+        .description("Run the step-by-step wiki configuration wizard")
+        .action(async () => {
+        await runSetupWizard(process.env, {
+            cwd: process.cwd(),
+            input: process.stdin,
+            output: process.stdout,
+            packageRoot: getPackageRoot(),
+        });
+    });
+}

package/dist/commands/stat.js

@@ -0,0 +1,20 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { getWikiStat } from "../operations/query.js";
+import { writeJson } from "../utils/output.js";
+export function registerStatCommand(program) {
+    program
+        .command("stat")
+        .description("Show aggregate wiki index statistics")
+        .action(async () => {
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => getWikiStat(process.env),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/stat",
+            }),
+        });
+        writeJson(payload);
+    });
+}

package/dist/commands/sync.js

@@ -0,0 +1,38 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { runSyncCommand } from "../operations/write.js";
+import { writeJson } from "../utils/output.js";
+export function registerSyncCommand(program) {
+    program
+        .command("sync")
+        .description("Incrementally sync wiki pages, embeddings, and vault metadata")
+        .option("--path <pagePath>", "Only sync a single wiki page")
+        .option("--force", "Force a full rebuild of the index")
+        .option("--skip-embedding", "Skip embedding generation")
+        .option("--process", "Process vault queue items after sync")
+        .option("--vault-file <fileId>", "Only process one vault queue file_id (relative to VAULT_PATH)")
+        .action(async (options) => {
+        const result = await executeServerBackedOperation({
+            kind: "write",
+            local: () => runSyncCommand(process.env, {
+                targetPaths: options.path ? [options.path] : undefined,
+                force: options.force === true,
+                skipEmbedding: options.skipEmbedding === true,
+                process: options.process === true,
+                vaultFileId: options.vaultFile ?? undefined,
+            }),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "POST",
+                path: "/sync",
+                body: {
+                    path: options.path ?? undefined,
+                    force: options.force === true,
+                    skipEmbedding: options.skipEmbedding === true,
+                    process: options.process === true,
+                    vaultFileId: options.vaultFile ?? undefined,
+                },
+            }),
+        });
+        writeJson(result);
+    });
+}

package/dist/commands/template.js

@@ -0,0 +1,71 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { createTemplate, listTemplates, showTemplate } from "../operations/type-template.js";
+import { ensureTextOrJson, writeJson, writeText } from "../utils/output.js";
+export function registerTemplateCommand(program) {
+    const template = program.command("template").description("List, show, or create wiki templates");
+    template
+        .command("list")
+        .option("--format <format>", "Output format: text or json", "text")
+        .action(async (options) => {
+        const format = ensureTextOrJson(options.format);
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => listTemplates(process.env),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/template/list",
+            }),
+        });
+        if (format === "json") {
+            writeJson(payload);
+            return;
+        }
+        writeText(payload.map((entry) => `${entry.pageType} -> ${entry.file}`).join("\n"));
+    });
+    template
+        .command("show")
+        .argument("<pageType>", "Registered pageType")
+        .option("--format <format>", "Output format: text or json", "text")
+        .action(async (pageType, options) => {
+        const format = ensureTextOrJson(options.format);
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => showTemplate(process.env, pageType),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/template/show",
+                query: { pageType },
+            }),
+        });
+        if (format === "json") {
+            writeJson(payload);
+            return;
+        }
+        writeText(String(payload.content ?? ""));
+    });
+    template
+        .command("create")
+        .requiredOption("--type <pageType>", "New pageType")
+        .requiredOption("--title <title>", "Human title used inside the template frontmatter")
+        .action(async (options) => {
+        const payload = await executeServerBackedOperation({
+            kind: "write",
+            local: () => Promise.resolve(createTemplate(process.env, {
+                type: options.type,
+                title: options.title,
+            })),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "POST",
+                path: "/template/create",
+                body: {
+                    type: options.type,
+                    title: options.title,
+                },
+            }),
+        });
+        writeJson(payload);
+    });
+}

package/dist/commands/type.js

@@ -0,0 +1,88 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { listTypes, recommendTypes, showType } from "../operations/type-template.js";
+import { ensureTextOrJson, writeJson, writeText } from "../utils/output.js";
+export function registerTypeCommand(program) {
+    const typeCommand = program.command("type").description("Inspect and recommend wiki page types");
+    typeCommand
+        .command("list")
+        .option("--format <format>", "Output format: text or json", "text")
+        .action(async (options) => {
+        const format = ensureTextOrJson(options.format);
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => listTypes(process.env),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/type/list",
+            }),
+        });
+        if (format === "json") {
+            writeJson(payload);
+            return;
+        }
+        writeText(payload.map((entry) => `${entry.pageType} -> ${entry.file}`).join("\n"));
+    });
+    typeCommand
+        .command("show")
+        .argument("<pageType>", "Registered pageType")
+        .option("--format <format>", "Output format: text or json", "text")
+        .action(async (pageType, options) => {
+        const format = ensureTextOrJson(options.format);
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => showType(process.env, pageType),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/type/show",
+                query: { pageType },
+            }),
+        });
+        if (format === "json") {
+            writeJson(payload);
+            return;
+        }
+        writeText([
+            `pageType: ${payload.pageType}`,
+            `file: ${payload.file}`,
+            `columns: ${Object.keys(payload.columns ?? {}).join(", ") || "(none)"}`,
+            `edges: ${Object.keys(payload.edges ?? {}).join(", ") || "(none)"}`,
+            `summaryFields: ${payload.summaryFields.join(", ") || "(none)"}`,
+        ].join("\n"));
+    });
+    typeCommand
+        .command("recommend")
+        .requiredOption("--text <text>", "Short summary or extracted content")
+        .option("--keywords <keywords>", "Comma-separated keywords")
+        .option("--limit <limit>", "Max number of recommendations", "5")
+        .option("--format <format>", "Output format: text or json", "text")
+        .action(async (options) => {
+        const format = ensureTextOrJson(options.format);
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => recommendTypes(process.env, {
+                text: String(options.text ?? ""),
+                keywords: options.keywords ?? undefined,
+                limit: options.limit ?? undefined,
+            }),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "POST",
+                path: "/type/recommend",
+                body: {
+                    text: String(options.text ?? ""),
+                    keywords: options.keywords ?? undefined,
+                    limit: options.limit ?? undefined,
+                },
+            }),
+        });
+        if (format === "json") {
+            writeJson(payload);
+            return;
+        }
+        writeText(payload.recommendations
+            .map((entry) => `${entry.pageType} (${entry.score.toFixed(4)}) ${entry.signals.join(" | ")}`)
+            .join("\n"));
+    });
+}

package/dist/commands/vault.js

@@ -0,0 +1,64 @@
+import { executeServerBackedOperation, requestDaemonJson } from "../daemon/client.js";
+import { diffVaultFiles, getVaultQueue, listVaultFiles } from "../operations/query.js";
+import { writeJson } from "../utils/output.js";
+export function registerVaultCommand(program) {
+    const vault = program.command("vault").description("Inspect indexed vault files and changelog entries");
+    vault
+        .command("list")
+        .option("--path <prefix>", "Filter by relative path prefix")
+        .option("--ext <ext>", "Filter by file extension")
+        .action(async (options) => {
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => listVaultFiles(process.env, options),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/vault/list",
+                query: {
+                    path: options.path ?? undefined,
+                    ext: options.ext ?? undefined,
+                },
+            }),
+        });
+        writeJson(payload);
+    });
+    vault
+        .command("diff")
+        .option("--since <date>", "Show changes since a timestamp")
+        .option("--path <prefix>", "Filter by relative path prefix")
+        .action(async (options) => {
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => diffVaultFiles(process.env, options),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/vault/diff",
+                query: {
+                    since: options.since ?? undefined,
+                    path: options.path ?? undefined,
+                },
+            }),
+        });
+        writeJson(payload);
+    });
+    vault
+        .command("queue")
+        .option("--status <status>", "Filter queue items by status")
+        .action(async (options) => {
+        const payload = await executeServerBackedOperation({
+            kind: "read",
+            local: () => getVaultQueue(process.env, options),
+            remote: (endpoint) => requestDaemonJson({
+                endpoint,
+                method: "GET",
+                path: "/vault/queue",
+                query: {
+                    status: options.status ?? undefined,
+                },
+            }),
+        });
+        writeJson(payload);
+    });
+}

package/dist/core/agent.js

@@ -0,0 +1,201 @@
+import OpenAI from "openai";
+import { AppError } from "../utils/errors.js";
+function parseBoolean(value) {
+    return /^(1|true|yes|on)$/i.test((value ?? "").trim());
+}
+function parseBatchSize(value) {
+    const raw = value?.trim() || "5";
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new AppError(`WIKI_AGENT_BATCH_SIZE must be a non-negative integer, got ${value}`, "config");
+    }
+    return parsed;
+}
+function normalizeBaseUrl(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return "https://api.openai.com/v1";
+    }
+    return trimmed.replace(/\/+$/g, "");
+}
+function normalizeMessageContent(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (!Array.isArray(value)) {
+        return "";
+    }
+    return value
+        .map((item) => item.text ?? "")
+        .join("")
+        .trim();
+}
+function normalizeStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((item) => String(item ?? "").trim())
+        .filter(Boolean);
+}
+function parseDecisionPayload(raw) {
+    const cleaned = raw.trim().replace(/^```json\s*/i, "").replace(/^```\s*/i, "").replace(/\s*```$/i, "");
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch (error) {
+        throw new AppError("Wiki agent returned invalid JSON", "runtime", {
+            cause: error instanceof Error ? error.message : String(error),
+            raw,
+        });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new AppError("Wiki agent returned a non-object payload", "runtime", { raw });
+    }
+    const payload = parsed;
+    const action = String(payload.action ?? "").trim();
+    if (action !== "create" && action !== "update" && action !== "skip") {
+        throw new AppError("Wiki agent action must be create, update, or skip", "runtime", { raw });
+    }
+    const reason = String(payload.reason ?? "").trim();
+    if (!reason) {
+        throw new AppError("Wiki agent payload is missing reason", "runtime", { raw });
+    }
+    const decision = {
+        action,
+        reason,
+        keyFindings: normalizeStringArray(payload.keyFindings),
+        tags: normalizeStringArray(payload.tags),
+        relatedPages: normalizeStringArray(payload.relatedPages),
+    };
+    if (typeof payload.title === "string" && payload.title.trim()) {
+        decision.title = payload.title.trim();
+    }
+    if (typeof payload.bodyMarkdown === "string" && payload.bodyMarkdown.trim()) {
+        decision.bodyMarkdown = payload.bodyMarkdown.trim();
+    }
+    if ((action === "create" || action === "update") && !decision.bodyMarkdown) {
+        throw new AppError("Wiki agent payload must include bodyMarkdown for create/update", "runtime", {
+            raw,
+        });
+    }
+    if (action === "create" && !decision.title) {
+        throw new AppError("Wiki agent payload must include title for create", "runtime", { raw });
+    }
+    return decision;
+}
+export function inspectWikiAgentSettings(env = process.env) {
+    const enabled = parseBoolean(env.WIKI_AGENT_ENABLED);
+    const baseUrl = normalizeBaseUrl(env.WIKI_AGENT_BASE_URL);
+    const model = env.WIKI_AGENT_MODEL?.trim() || null;
+    const errors = [];
+    const batchSize = parseBatchSize(env.WIKI_AGENT_BATCH_SIZE);
+    if (enabled) {
+        if (!(env.WIKI_AGENT_API_KEY ?? "").trim()) {
+            errors.push("WIKI_AGENT_API_KEY is required when WIKI_AGENT_ENABLED=true");
+        }
+        if (!model) {
+            errors.push("WIKI_AGENT_MODEL is required when WIKI_AGENT_ENABLED=true");
+        }
+    }
+    return {
+        enabled,
+        configured: enabled ? errors.length === 0 : false,
+        baseUrl: enabled ? baseUrl : null,
+        model,
+        batchSize,
+        errors,
+    };
+}
+export function resolveWikiAgentSettings(env = process.env) {
+    const inspected = inspectWikiAgentSettings(env);
+    if (!inspected.enabled) {
+        return null;
+    }
+    if (inspected.errors.length > 0) {
+        throw new AppError(inspected.errors.join("; "), "config");
+    }
+    return {
+        enabled: true,
+        baseUrl: inspected.baseUrl ?? "https://api.openai.com/v1",
+        apiKey: (env.WIKI_AGENT_API_KEY ?? "").trim(),
+        model: inspected.model ?? "",
+        batchSize: inspected.batchSize,
+    };
+}
+export class WikiAgentClient {
+    settings;
+    client;
+    constructor(settings) {
+        this.settings = settings;
+        this.client = new OpenAI({
+            apiKey: settings.apiKey,
+            baseURL: settings.baseUrl,
+            maxRetries: 0,
+            timeout: 60_000,
+        });
+    }
+    async decideSourceAction(input) {
+        try {
+            const response = await this.client.chat.completions.create({
+                model: this.settings.model,
+                response_format: { type: "json_object" },
+                messages: [
+                    {
+                        role: "system",
+                        content: "You are a local wiki ingestion agent. Decide whether a vault file should create, update, or skip a source-summary page. Return JSON only.",
+                    },
+                    {
+                        role: "user",
+                        content: JSON.stringify({
+                            task: "Decide how to process one vault file into the local wiki.",
+                            rules: [
+                                "Prefer source-summary pages for durable source files.",
+                                "Treat pdf, docx, pptx, xlsx, and md files with readable extracted text as durable by default unless they are clear duplicates or pure noise.",
+                                "Skip transient, duplicate, or low-signal files.",
+                                "If existingPageId is present, you may update that page instead of creating a new one.",
+                                "Body markdown must be substantive and use the provided template headings.",
+                                "bodyMarkdown must contain markdown sections only and must not include YAML frontmatter or code fences.",
+                                "Do not invent unsupported page ids in relatedPages.",
+                            ],
+                            file: {
+                                fileId: input.fileId,
+                                fileExt: input.fileExt,
+                                sourceType: input.sourceType,
+                            },
+                            existingPageId: input.existingPageId ?? null,
+                            existingPageContent: input.existingPageContent ?? null,
+                            wikiStats: input.wikiStats,
+                            sourceSummaryTemplate: input.templateText,
+                            vaultToWikiInstruction: input.instructionText,
+                            extractedText: input.extractedText,
+                            outputSchema: {
+                                action: "create | update | skip",
+                                reason: "short explanation",
+                                title: "required for create",
+                                keyFindings: ["1-5 concise findings"],
+                                tags: ["optional", "tags"],
+                                relatedPages: ["optional/page-id.md"],
+                                bodyMarkdown: "full markdown body using the source-summary template headings",
+                            },
+                        }, null, 2),
+                    },
+                ],
+            });
+            const content = normalizeMessageContent(response.choices?.[0]?.message?.content ?? undefined);
+            if (!content) {
+                throw new AppError("Wiki agent returned an empty response", "runtime");
+            }
+            return parseDecisionPayload(content);
+        }
+        catch (error) {
+            if (error instanceof AppError) {
+                throw error;
+            }
+            throw new AppError("Wiki agent request failed", "runtime", {
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}

package/dist/core/cli-env.js

@@ -0,0 +1,129 @@
+import path from "node:path";
+import { pathExistsSync, readTextFileSync } from "../utils/fs.js";
+export const DEFAULT_WIKI_ENV_FILE = ".wiki.env";
+const EMPTY_INFO = {
+    requestedPath: null,
+    loadedPath: null,
+    autoDiscovered: false,
+    missingRequestedPath: false,
+    loadedKeys: [],
+};
+let lastCliEnvInfo = EMPTY_INFO;
+const CORE_RUNTIME_ENV_KEYS = [
+    "WIKI_PATH",
+    "VAULT_PATH",
+    "WIKI_DB_PATH",
+    "WIKI_CONFIG_PATH",
+    "WIKI_TEMPLATES_PATH",
+];
+function unquoteEnvValue(rawValue) {
+    const value = rawValue.trim();
+    if (value.length < 2) {
+        return value;
+    }
+    if (value.startsWith('"') && value.endsWith('"')) {
+        return value.slice(1, -1).replace(/\\n/g, "\n").replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    }
+    if (value.startsWith("'") && value.endsWith("'")) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function findNearestEnvFile(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const candidate = path.join(current, DEFAULT_WIKI_ENV_FILE);
+        if (pathExistsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+export function parseEnvFile(text) {
+    const entries = {};
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        const normalized = line.startsWith("export ") ? line.slice("export ".length).trim() : line;
+        const separatorIndex = normalized.indexOf("=");
+        if (separatorIndex <= 0) {
+            continue;
+        }
+        const key = normalized.slice(0, separatorIndex).trim();
+        const value = normalized.slice(separatorIndex + 1);
+        if (!key) {
+            continue;
+        }
+        entries[key] = unquoteEnvValue(value);
+    }
+    return entries;
+}
+function hasExplicitCoreRuntimeEnv(targetEnv) {
+    return CORE_RUNTIME_ENV_KEYS.some((key) => {
+        const value = targetEnv[key];
+        return value !== undefined && value.trim().length > 0;
+    });
+}
+function quoteEnvValue(value) {
+    if (/^[A-Za-z0-9_./:@+-]+$/.test(value)) {
+        return value;
+    }
+    return JSON.stringify(value);
+}
+export function serializeEnvEntries(entries) {
+    return `${entries
+        .filter(([, value]) => value !== null && value !== undefined)
+        .map(([key, value]) => `${key}=${quoteEnvValue(String(value))}`)
+        .join("\n")}\n`;
+}
+export function applyCliEnvironment(targetEnv = process.env, cwd = process.cwd()) {
+    const requestedEnvFile = targetEnv.WIKI_ENV_FILE?.trim();
+    const requestedPath = requestedEnvFile ? path.resolve(cwd, requestedEnvFile) : null;
+    if (!requestedPath && hasExplicitCoreRuntimeEnv(targetEnv)) {
+        lastCliEnvInfo = { ...EMPTY_INFO };
+        return lastCliEnvInfo;
+    }
+    const candidatePath = requestedPath ?? findNearestEnvFile(cwd);
+    if (!candidatePath) {
+        lastCliEnvInfo = { ...EMPTY_INFO, requestedPath };
+        return lastCliEnvInfo;
+    }
+    if (!pathExistsSync(candidatePath)) {
+        lastCliEnvInfo = {
+            requestedPath: candidatePath,
+            loadedPath: null,
+            autoDiscovered: false,
+            missingRequestedPath: requestedPath !== null,
+            loadedKeys: [],
+        };
+        return lastCliEnvInfo;
+    }
+    const parsed = parseEnvFile(readTextFileSync(candidatePath));
+    const loadedKeys = [];
+    for (const [key, value] of Object.entries(parsed)) {
+        if (targetEnv[key] === undefined) {
+            targetEnv[key] = value;
+            loadedKeys.push(key);
+        }
+    }
+    if (!targetEnv.WIKI_ENV_FILE) {
+        targetEnv.WIKI_ENV_FILE = candidatePath;
+    }
+    lastCliEnvInfo = {
+        requestedPath,
+        loadedPath: candidatePath,
+        autoDiscovered: requestedPath === null,
+        missingRequestedPath: false,
+        loadedKeys,
+    };
+    return lastCliEnvInfo;
+}
+export function getCliEnvironmentInfo() {
+    return lastCliEnvInfo;
+}