@biaoo/tiangong-wiki 0.2.0

package/dist/operations/type-template.js

@@ -0,0 +1,210 @@
+import matter from "gray-matter";
+import path from "node:path";
+import { getTemplate } from "../core/config.js";
+import { EmbeddingClient } from "../core/embedding.js";
+import { loadRuntimeConfig, openRuntimeDb } from "../core/runtime.js";
+import { ensureDirSync, pathExistsSync, readTextFileSync, writeTextFileSync } from "../utils/fs.js";
+import { AppError } from "../utils/errors.js";
+function distanceToSimilarity(distance) {
+    return 1 / (1 + distance);
+}
+function normalizeKeywords(raw) {
+    return (raw ?? "")
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function parsePositiveLimit(value, label, fallback) {
+    const normalized = value ?? fallback;
+    const limit = Number.parseInt(String(normalized), 10);
+    if (!Number.isFinite(limit) || limit <= 0) {
+        throw new AppError(`Invalid ${label} value: ${value}`, "config");
+    }
+    return limit;
+}
+function toTypeDescriptor(pageType, definition, wikiRoot) {
+    return {
+        pageType,
+        file: definition.file,
+        filePath: path.resolve(wikiRoot, definition.file),
+        columns: Object.keys(definition.columns),
+        edges: Object.keys(definition.edges),
+        summaryFields: definition.summaryFields,
+    };
+}
+function templateSkeleton(pageType, title) {
+    return matter.stringify([
+        "## Summary",
+        "",
+        "- Add a concise overview.",
+        "",
+        "## Details",
+        "",
+        "- Expand the template fields and sections for this page type.",
+    ].join("\n"), {
+        pageType,
+        title,
+        nodeId: "",
+        status: "draft",
+        visibility: "private",
+        sourceRefs: [],
+        relatedPages: [],
+        tags: [],
+        createdAt: "2026-04-06",
+        updatedAt: "2026-04-06",
+    });
+}
+export function listTypes(env = process.env) {
+    const { paths, config } = loadRuntimeConfig(env);
+    return Object.entries(config.templates)
+        .map(([pageType, definition]) => toTypeDescriptor(pageType, definition, paths.wikiRoot))
+        .sort((left, right) => left.pageType.localeCompare(right.pageType));
+}
+export function showType(env = process.env, pageType) {
+    const { paths, config } = loadRuntimeConfig(env);
+    const definition = config.templates[pageType];
+    if (!definition) {
+        throw new AppError(`Unknown type: ${pageType}`, "not_found");
+    }
+    return {
+        ...toTypeDescriptor(pageType, definition, paths.wikiRoot),
+        columns: definition.columns,
+        edges: definition.edges,
+    };
+}
+export async function recommendTypes(env = process.env, options) {
+    const embeddingClient = EmbeddingClient.fromEnv(env);
+    if (!embeddingClient) {
+        throw new AppError("Embedding not configured", "not_configured");
+    }
+    const limit = parsePositiveLimit(options.limit, "--limit", 5);
+    const keywords = normalizeKeywords(options.keywords);
+    const queryText = [options.text.trim(), keywords.length > 0 ? `keywords: ${keywords.join(", ")}` : ""]
+        .filter(Boolean)
+        .join("\n\n");
+    const [queryEmbedding] = await embeddingClient.embedBatch([queryText]);
+    const neighborLimit = Math.max(limit * 8, 24);
+    const { db } = openRuntimeDb(env);
+    try {
+        const hasVectors = db.prepare("SELECT COUNT(*) AS count FROM vec_pages").get().count;
+        if (hasVectors === 0) {
+            throw new AppError("No page embeddings found. Run tiangong-wiki sync with embedding enabled first.", "not_configured");
+        }
+        const rows = db
+            .prepare(`
+          SELECT
+            pages.page_type AS pageType,
+            pages.id AS pageId,
+            pages.title AS title,
+            vec_pages.distance AS distance
+          FROM vec_pages
+          JOIN pages ON pages.id = vec_pages.page_id
+          WHERE vec_pages.embedding MATCH ?
+            AND k = ?
+          ORDER BY vec_pages.distance
+          LIMIT ?
+        `)
+            .all(new Float32Array(queryEmbedding), neighborLimit, neighborLimit);
+        if (rows.length === 0) {
+            throw new AppError("No similar embedded pages found for type recommendation.", "runtime");
+        }
+        const grouped = new Map();
+        for (const row of rows) {
+            const similarity = distanceToSimilarity(Number(row.distance));
+            const bucket = grouped.get(row.pageType) ?? {
+                totalSimilarity: 0,
+                maxSimilarity: 0,
+                supportCount: 0,
+                hits: [],
+            };
+            bucket.totalSimilarity += similarity;
+            bucket.maxSimilarity = Math.max(bucket.maxSimilarity, similarity);
+            bucket.supportCount += 1;
+            bucket.hits.push({
+                pageType: row.pageType,
+                pageId: row.pageId,
+                title: row.title,
+                similarity,
+            });
+            grouped.set(row.pageType, bucket);
+        }
+        const recommendations = [...grouped.entries()]
+            .map(([pageType, bucket]) => {
+            const topHits = bucket.hits
+                .sort((left, right) => right.similarity - left.similarity)
+                .slice(0, 3);
+            return {
+                pageType,
+                score: Number(bucket.totalSimilarity.toFixed(6)),
+                signals: [
+                    `supportCount:${bucket.supportCount}`,
+                    `maxSimilarity:${bucket.maxSimilarity.toFixed(4)}`,
+                    `avgSimilarity:${(bucket.totalSimilarity / bucket.supportCount).toFixed(4)}`,
+                ],
+                similarPages: topHits.map((hit) => `${hit.pageId}@${hit.similarity.toFixed(4)}`),
+            };
+        })
+            .sort((left, right) => right.score - left.score || left.pageType.localeCompare(right.pageType))
+            .slice(0, limit);
+        return {
+            query: { text: options.text, keywords },
+            recommendations,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+export function listTemplates(env = process.env) {
+    const { paths, config } = loadRuntimeConfig(env);
+    return Object.entries(config.templates).map(([pageType, definition]) => ({
+        pageType,
+        file: definition.file,
+        filePath: path.resolve(paths.wikiRoot, definition.file),
+    }));
+}
+export function showTemplate(env = process.env, pageType) {
+    const { paths, config } = loadRuntimeConfig(env);
+    getTemplate(config, pageType);
+    const filePath = path.resolve(paths.wikiRoot, config.templates[pageType].file);
+    return {
+        pageType,
+        filePath,
+        content: readTextFileSync(filePath),
+    };
+}
+export function createTemplate(env = process.env, options) {
+    const { paths, config } = loadRuntimeConfig(env);
+    if (config.templates[options.type]) {
+        throw new AppError(`Template already exists: ${options.type}`, "config");
+    }
+    const templateRelativePath = path.join("templates", `${options.type}.md`).split(path.sep).join("/");
+    const templatePath = path.resolve(paths.wikiRoot, templateRelativePath);
+    ensureDirSync(path.dirname(templatePath));
+    if (pathExistsSync(templatePath)) {
+        throw new AppError(`Template file already exists: ${templatePath}`, "config");
+    }
+    writeTextFileSync(templatePath, templateSkeleton(options.type, options.title));
+    const updatedConfig = {
+        schemaVersion: config.schemaVersion,
+        customColumns: config.customColumns,
+        defaultSummaryFields: config.defaultSummaryFields,
+        vaultFileTypes: config.vaultFileTypes,
+        commonEdges: config.commonEdges,
+        templates: {
+            ...config.templates,
+            [options.type]: {
+                file: templateRelativePath,
+                columns: {},
+                edges: {},
+                summaryFields: [],
+            },
+        },
+    };
+    writeTextFileSync(paths.configPath, `${JSON.stringify(updatedConfig, null, 2)}\n`);
+    return {
+        pageType: options.type,
+        templatePath,
+        configPath: paths.configPath,
+    };
+}

package/dist/operations/write.js

@@ -0,0 +1,143 @@
+import { getTemplate } from "../core/config.js";
+import { resolveAgentSettings } from "../core/paths.js";
+import { createPageFromTemplate } from "../core/page-files.js";
+import { loadRuntimeConfig } from "../core/runtime.js";
+import { syncWorkspace } from "../core/sync.js";
+import { getVaultQueueItem, processVaultQueueBatch } from "../core/vault-processing.js";
+import { AppError } from "../utils/errors.js";
+function assertValidSyncCommandOptions(options) {
+    if (options.vaultFileId && !options.process) {
+        throw new AppError("--vault-file requires --process.", "config");
+    }
+    if (options.process && options.targetPaths && options.targetPaths.length > 0) {
+        throw new AppError("--process cannot be combined with --path.", "config");
+    }
+}
+function assertQueueProcessingEnabled(env) {
+    const agentSettings = resolveAgentSettings(env, { strict: true });
+    if (!agentSettings.enabled) {
+        throw new AppError("Queue processing requires WIKI_AGENT_ENABLED=true.", "config");
+    }
+    if (agentSettings.batchSize === 0) {
+        throw new AppError("Queue processing requires WIKI_AGENT_BATCH_SIZE > 0.", "config");
+    }
+}
+function buildQueueProcessResult(queueResult, meta = {}) {
+    if (!queueResult.enabled) {
+        throw new AppError("Queue processing is disabled.", "config");
+    }
+    return {
+        ...queueResult,
+        enabled: true,
+        requestedFileId: meta.requestedFileId ?? null,
+        currentStatus: meta.currentStatus ?? null,
+        noopReason: meta.noopReason ?? null,
+    };
+}
+function buildQueueProcessNoopResult(fileId, status) {
+    return {
+        enabled: true,
+        requestedFileId: fileId,
+        processed: 0,
+        done: 0,
+        skipped: 0,
+        errored: 0,
+        items: [],
+        currentStatus: status,
+        noopReason: status === "done" ? "already_done" : "already_skipped",
+    };
+}
+export async function runSync(env = process.env, options = {}) {
+    return syncWorkspace({
+        ...options,
+        env,
+    });
+}
+async function processQueueAfterSync(env, options) {
+    assertQueueProcessingEnabled(env);
+    if (!options.vaultFileId) {
+        return buildQueueProcessResult(await processVaultQueueBatch(env, {
+            workflowRunner: options.workflowRunner,
+        }));
+    }
+    const requestedFileId = options.vaultFileId;
+    const queueItem = getVaultQueueItem(env, requestedFileId);
+    if (!queueItem) {
+        throw new AppError(`Vault queue item not found: ${requestedFileId}`, "not_found");
+    }
+    if (queueItem.status === "processing") {
+        throw new AppError(`Vault queue item is already processing: ${requestedFileId}`, "runtime", {
+            fileId: requestedFileId,
+            status: queueItem.status,
+        });
+    }
+    if (queueItem.status === "done" || queueItem.status === "skipped") {
+        return buildQueueProcessNoopResult(requestedFileId, queueItem.status);
+    }
+    const queueResult = await processVaultQueueBatch(env, {
+        maxItems: 1,
+        filterFileIds: [requestedFileId],
+        workflowRunner: options.workflowRunner,
+    });
+    if (queueResult.processed > 0) {
+        return buildQueueProcessResult(queueResult, {
+            requestedFileId,
+            currentStatus: getVaultQueueItem(env, requestedFileId)?.status ?? null,
+        });
+    }
+    const current = getVaultQueueItem(env, requestedFileId);
+    if (!current) {
+        throw new AppError(`Vault queue item not found: ${requestedFileId}`, "not_found");
+    }
+    if (current.status === "done" || current.status === "skipped") {
+        return buildQueueProcessNoopResult(requestedFileId, current.status);
+    }
+    if (current.status === "processing") {
+        throw new AppError(`Vault queue item is already processing: ${requestedFileId}`, "runtime", {
+            fileId: requestedFileId,
+            status: current.status,
+        });
+    }
+    throw new AppError(`Failed to claim vault queue item for processing: ${requestedFileId}`, "runtime", {
+        fileId: requestedFileId,
+        status: current.status,
+    });
+}
+export async function runSyncCommand(env = process.env, options = {}) {
+    assertValidSyncCommandOptions(options);
+    const syncResult = await runSync(env, {
+        targetPaths: options.targetPaths,
+        force: options.force,
+        skipEmbedding: options.skipEmbedding,
+    });
+    if (!options.process) {
+        return {
+            ...syncResult,
+            queueProcess: null,
+        };
+    }
+    return {
+        ...syncResult,
+        queueProcess: await processQueueAfterSync(env, {
+            vaultFileId: options.vaultFileId,
+            workflowRunner: options.workflowRunner,
+        }),
+    };
+}
+export async function createPage(env = process.env, options) {
+    const { paths, config } = loadRuntimeConfig(env);
+    getTemplate(config, options.type);
+    const created = createPageFromTemplate(paths, config, {
+        pageType: options.type,
+        title: options.title,
+        nodeId: options.nodeId ?? undefined,
+    });
+    await syncWorkspace({
+        env,
+        targetPaths: [created.pageId],
+    });
+    return {
+        created: created.pageId,
+        filePath: created.filePath,
+    };
+}

package/dist/types/config.js

@@ -0,0 +1 @@
+export {};

package/dist/types/page.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/case.js

@@ -0,0 +1,22 @@
+export function camelToSnake(input) {
+    return input
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/[-\s]+/g, "_")
+        .toLowerCase();
+}
+export function snakeToCamel(input) {
+    return input.replace(/_([a-z0-9])/g, (_, char) => char.toUpperCase());
+}
+export function kebabToCamel(input) {
+    return input.replace(/-([a-z0-9])/g, (_, char) => char.toUpperCase());
+}
+export function kebabToSnake(input) {
+    return input.replace(/-/g, "_");
+}
+export function humanizeFieldName(input) {
+    return input
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}

package/dist/utils/errors.js

@@ -0,0 +1,26 @@
+export class AppError extends Error {
+    type;
+    exitCode;
+    details;
+    constructor(message, type = "runtime", details) {
+        super(message);
+        this.name = "AppError";
+        this.type = type;
+        this.exitCode = type === "config" ? 2 : 1;
+        this.details = details;
+    }
+}
+export function asAppError(error) {
+    if (error instanceof AppError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new AppError(error.message, "runtime");
+    }
+    return new AppError(String(error), "runtime");
+}
+export function assertCondition(condition, message, type = "runtime") {
+    if (!condition) {
+        throw new AppError(message, type);
+    }
+}

package/dist/utils/fs.js

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+export function ensureDirSync(dirPath) {
+    mkdirSync(dirPath, { recursive: true });
+}
+export function pathExistsSync(filePath) {
+    return existsSync(filePath);
+}
+export function readTextFileSync(filePath) {
+    return readFileSync(filePath, "utf8");
+}
+export function writeTextFileSync(filePath, content) {
+    ensureDirSync(path.dirname(filePath));
+    writeFileSync(filePath, content, "utf8");
+}
+export function copyFileIfMissingSync(sourcePath, targetPath) {
+    if (existsSync(targetPath)) {
+        return false;
+    }
+    ensureDirSync(path.dirname(targetPath));
+    copyFileSync(sourcePath, targetPath);
+    return true;
+}
+export function copyDirectoryContentsSync(sourceDir, targetDir) {
+    ensureDirSync(targetDir);
+    for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const targetPath = path.join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+            copyDirectoryContentsSync(sourcePath, targetPath);
+            continue;
+        }
+        ensureDirSync(path.dirname(targetPath));
+        copyFileSync(sourcePath, targetPath);
+    }
+}
+export function isDirectoryEmptySync(dirPath) {
+    if (!existsSync(dirPath)) {
+        return true;
+    }
+    return readdirSync(dirPath).length === 0;
+}
+export function listFilesRecursiveSync(rootDir, extension) {
+    if (!existsSync(rootDir)) {
+        return [];
+    }
+    const results = [];
+    const visit = (dirPath) => {
+        for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+            const entryPath = path.join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                visit(entryPath);
+                continue;
+            }
+            if (extension && path.extname(entry.name) !== extension) {
+                continue;
+            }
+            results.push(entryPath);
+        }
+    };
+    visit(rootDir);
+    return results.sort();
+}
+export function sha256Buffer(buffer) {
+    return createHash("sha256").update(buffer).digest("hex");
+}
+export function sha256Text(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+export function sha256FileSync(filePath) {
+    return sha256Buffer(readFileSync(filePath));
+}
+export function fileStatSync(filePath) {
+    const stats = statSync(filePath);
+    return { size: stats.size, mtimeMs: stats.mtimeMs };
+}

package/dist/utils/output.js

@@ -0,0 +1,33 @@
+import { AppError, asAppError } from "./errors.js";
+export function writeJson(payload, stream = process.stdout) {
+    stream.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+export function writeText(text, stream = process.stdout) {
+    stream.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+export function handleCliError(error) {
+    const appError = asAppError(error);
+    writeJson({
+        error: appError.message,
+        type: appError.type,
+        ...(appError.details === undefined ? {} : { details: appError.details }),
+    }, process.stderr);
+    process.exit(appError.exitCode);
+}
+export function formatKeyValueLines(values) {
+    return Object.entries(values)
+        .map(([key, value]) => `${key}: ${value === undefined ? "" : String(value)}`)
+        .join("\n");
+}
+export function parseOutputFormat(value) {
+    if (value === "json") {
+        return "json";
+    }
+    return "text";
+}
+export function ensureTextOrJson(value) {
+    if (value && value !== "text" && value !== "json") {
+        throw new AppError(`Unsupported format: ${value}`, "config");
+    }
+    return parseOutputFormat(value);
+}

package/dist/utils/process.js

@@ -0,0 +1,60 @@
+import { spawn } from "node:child_process";
+import { openSync } from "node:fs";
+import { AppError } from "./errors.js";
+export function getCurrentInvocation() {
+    const [, argv1, argv2] = process.argv;
+    if (!argv1) {
+        return { command: process.execPath, args: [] };
+    }
+    const looksLikeTsx = argv1.includes("tsx");
+    if (looksLikeTsx && argv2) {
+        return {
+            command: process.execPath,
+            args: [argv1, argv2],
+        };
+    }
+    return {
+        command: process.execPath,
+        args: [argv1],
+    };
+}
+export function spawnDetachedCurrentProcess(extraArgs, options = {}) {
+    const invocation = getCurrentInvocation();
+    const stdio = options.logFile
+        ? ["ignore", openSync(options.logFile, "a"), openSync(options.logFile, "a")]
+        : "ignore";
+    const child = spawn(invocation.command, [...invocation.args, ...extraArgs], {
+        detached: true,
+        stdio,
+        env: options.env ?? process.env,
+    });
+    child.unref();
+    return child.pid;
+}
+export function openTarget(target) {
+    let command = "";
+    let args = [];
+    if (process.platform === "darwin") {
+        command = "open";
+        args = [target];
+    }
+    else if (process.platform === "win32") {
+        command = "cmd";
+        args = ["/c", "start", "", target];
+    }
+    else {
+        command = "xdg-open";
+        args = [target];
+    }
+    try {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: "ignore",
+            shell: false,
+        });
+        child.unref();
+    }
+    catch (error) {
+        throw new AppError(`Failed to open target ${target}: ${error instanceof Error ? error.message : String(error)}`, "runtime");
+    }
+}

package/dist/utils/segmenter.js

@@ -0,0 +1,24 @@
+const SEGMENTER = new Intl.Segmenter("zh-Hans", { granularity: "word" });
+const CJK_PATTERN = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+const QUERY_TOKEN_PATTERN = /[\p{Letter}\p{Number}_-]+/gu;
+function normalizeWhitespace(text) {
+    return text.trim().replace(/\s+/g, " ");
+}
+export function segmentForFts(text) {
+    const normalized = normalizeWhitespace(text);
+    if (!normalized) {
+        return "";
+    }
+    const tokens = [...SEGMENTER.segment(normalized)]
+        .filter((segment) => segment.isWordLike)
+        .map((segment) => segment.segment.trim())
+        .filter(Boolean);
+    return tokens.length > 0 ? tokens.join(" ") : normalized;
+}
+export function normalizeFtsQuery(query) {
+    const normalized = normalizeWhitespace(query);
+    if (!normalized) {
+        return "";
+    }
+    return normalized.replace(QUERY_TOKEN_PATTERN, (token) => CJK_PATTERN.test(token) ? segmentForFts(token) : token);
+}

package/dist/utils/slug.js

@@ -0,0 +1,10 @@
+export function slugify(input, fallback = "page") {
+    const normalized = input
+        .normalize("NFKC")
+        .trim()
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+    return normalized || fallback;
+}

package/dist/utils/time.js

@@ -0,0 +1,24 @@
+function pad(value) {
+    return String(value).padStart(2, "0");
+}
+export function toOffsetIso(date = new Date()) {
+    const offsetMinutes = -date.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? "+" : "-";
+    const absoluteOffset = Math.abs(offsetMinutes);
+    const offsetHours = Math.floor(absoluteOffset / 60);
+    const offsetRemainder = absoluteOffset % 60;
+    return [
+        `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`,
+        `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`,
+        `${sign}${pad(offsetHours)}:${pad(offsetRemainder)}`,
+    ].join("");
+}
+export function toDateOnly(date = new Date()) {
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+export function makeSyncId(date = new Date()) {
+    return `sync-${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}-${String(date.getMilliseconds()).padStart(3, "0")}`;
+}
+export function addSeconds(date, seconds) {
+    return new Date(date.getTime() + seconds * 1000);
+}