@agent-wiki/mcp-server 0.3.0

package/dist/wiki.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Core Wiki engine — pure data layer, zero LLM dependency.
+ *
+ * Architecture (Karpathy LLM Wiki pattern):
+ *
+ *   raw/     — Immutable source documents. Write-once, never modified.
+ *              Each file has a .meta.yaml sidecar with provenance.
+ *
+ *   wiki/    — Mutable Markdown layer. Three kinds of files:
+ *              1. System: index.md, log.md, timeline.md (auto-maintained)
+ *              2. Entity pages: concept-*, person-*, artifact-*, etc.
+ *              3. Synthesis pages: synthesis-* (distilled from multiple pages)
+ *
+ *   schemas/ — Entity templates (person, concept, event, etc.)
+ *
+ * Key principles:
+ *   - Raw files are IMMUTABLE — the source of truth
+ *   - Wiki pages are MUTABLE — compiled knowledge, continuously refined
+ *   - Self-checking: lint detects contradictions, broken links, stale claims
+ *   - Knowledge compounds: every write improves the whole
+ */
+export interface WikiPage {
+    path: string;
+    title: string;
+    type?: string;
+    tags: string[];
+    sources: string[];
+    content: string;
+    frontmatter: Record<string, unknown>;
+    links: string[];
+    created?: string;
+    updated?: string;
+    derivedFrom?: string[];
+}
+export interface RawDocument {
+    path: string;
+    sourceUrl?: string;
+    downloadedAt: string;
+    sha256: string;
+    size: number;
+    mimeType?: string;
+    description?: string;
+    tags?: string[];
+}
+export interface LintIssue {
+    severity: "error" | "warning" | "info";
+    page: string;
+    message: string;
+    suggestion?: string;
+    autoFixable: boolean;
+    category?: "contradiction" | "orphan" | "broken-link" | "missing-source" | "stale" | "structure" | "integrity";
+}
+export interface LintReport {
+    pagesChecked: number;
+    rawChecked: number;
+    issues: LintIssue[];
+    contradictions: Contradiction[];
+}
+export interface Contradiction {
+    claim: string;
+    pageA: string;
+    excerptA: string;
+    pageB: string;
+    excerptB: string;
+    severity: "error" | "warning";
+}
+export interface TimelineEntry {
+    time: string;
+    operation: string;
+    page?: string;
+    summary: string;
+}
+export interface WikiConfig {
+    /** Where the config file was loaded from (or --wiki-path). */
+    configRoot: string;
+    /** The workspace directory — all data lives here. */
+    workspace: string;
+    wikiDir: string;
+    rawDir: string;
+    schemasDir: string;
+    lint: {
+        checkOrphans: boolean;
+        checkStaleDays: number;
+        checkMissingSources: boolean;
+        checkContradictions: boolean;
+        checkIntegrity: boolean;
+    };
+}
+export declare class Wiki {
+    readonly config: WikiConfig;
+    /**
+     * @param root — path to config root (where .agent-wiki.yaml lives)
+     * @param workspace — override workspace directory (all data: wiki/, raw/, schemas/).
+     *                     If not set, falls back to: AGENT_WIKI_WORKSPACE env → config file → root.
+     */
+    constructor(root?: string, workspace?: string);
+    /**
+     * Initialize a new knowledge base.
+     * @param path — config root (where .agent-wiki.yaml is created)
+     * @param workspace — optional separate workspace directory for all data.
+     *                     If set, wiki/, raw/, schemas/ go there instead of path.
+     */
+    static init(path: string, workspace?: string): Wiki;
+    /**
+     * Load config from .agent-wiki.yaml.
+     *
+     * Workspace resolution priority:
+     *   1. Explicit `workspaceOverride` parameter (from CLI --workspace)
+     *   2. `AGENT_WIKI_WORKSPACE` environment variable
+     *   3. `workspace` field in .agent-wiki.yaml (absolute, or relative to config file)
+     *   4. Fall back to config root itself
+     *
+     * All data dirs (wiki/, raw/, schemas/) resolve relative to workspace.
+     */
+    static loadConfig(root: string, workspaceOverride?: string): WikiConfig;
+    /** Register a raw document. Copies file to raw/ with metadata sidecar.
+     *  If content is provided as string, writes it directly.
+     *  If sourcePath is an existing file, copies it.
+     *  Raw files are IMMUTABLE — re-adding the same path is an error. */
+    rawAdd(filename: string, opts: {
+        content?: string;
+        sourcePath?: string;
+        sourceUrl?: string;
+        description?: string;
+        tags?: string[];
+        mimeType?: string;
+    }): RawDocument;
+    /** List all raw documents with metadata. */
+    rawList(): RawDocument[];
+    /** Read a raw document's content. */
+    rawRead(filename: string): {
+        content: string;
+        meta: RawDocument | null;
+    } | null;
+    /** Verify integrity of all raw files against their stored hashes. */
+    rawVerify(): Array<{
+        path: string;
+        status: "ok" | "corrupted" | "missing-meta";
+    }>;
+    /**
+     * Fetch a file from a URL and save it to raw/.
+     * Supports arXiv smart resolution: arxiv.org/abs/XXXX → arxiv.org/pdf/XXXX.pdf
+     * Returns the RawDocument metadata.
+     */
+    rawFetch(url: string, opts?: {
+        filename?: string;
+        description?: string;
+        tags?: string[];
+    }): Promise<RawDocument>;
+    /** Read a wiki page. Returns null if not found. */
+    read(pagePath: string): WikiPage | null;
+    /** Write (create or update) a wiki page. Content must include frontmatter.
+     *  Automatically injects/updates created and updated timestamps. */
+    write(pagePath: string, content: string, source?: string): void;
+    /** Delete a wiki page. Returns true if it existed. */
+    delete(pagePath: string): boolean;
+    /** List all wiki pages, optionally filtered by type or tag. */
+    list(filterType?: string, filterTag?: string): string[];
+    /** Keyword search across all wiki pages. Returns paths sorted by relevance. */
+    search(query: string, limit?: number): Array<{
+        path: string;
+        score: number;
+        snippet: string;
+    }>;
+    /** Run comprehensive health checks. Pure rules, no LLM.
+     *  Detects: contradictions, orphans, broken links, missing sources,
+     *  stale content, structural issues, integrity problems. */
+    lint(): LintReport;
+    /** Detect contradictions between pages.
+     *  Looks for numeric claims, date claims, and factual statements
+     *  that conflict across pages about the same entity/topic. */
+    private detectContradictions;
+    /** Get context for synthesis: reads multiple pages and returns
+     *  their content for the agent to distill into a new page. */
+    synthesizeContext(pagePaths: string[]): {
+        pages: Array<{
+            path: string;
+            title: string;
+            content: string;
+        }>;
+        suggestions: string[];
+    };
+    /** Auto-classify content into entity type and suggested tags.
+     *  Pure heuristic — zero LLM dependency. Analyzes title, body,
+     *  and structure to determine the best type and relevant tags.
+     *  If frontmatter already has a type, respects it. */
+    classify(content: string): {
+        type: string;
+        tags: string[];
+        confidence: number;
+    };
+    /** Auto-classify and inject type/tags into content if missing.
+     *  Returns the enriched content string. */
+    autoClassifyContent(content: string): string;
+    /** Extract relevant tags from text using keyword matching. */
+    private extractTags;
+    /** List available entity type schemas. */
+    schemas(): Array<{
+        name: string;
+        description: string;
+        template: string;
+    }>;
+    /** Get operation log entries. */
+    getLog(limit?: number): Array<{
+        time: string;
+        operation: string;
+        page: string;
+        summary: string;
+    }>;
+    /** Rebuild index.md from all pages. Groups by type with page counts. */
+    rebuildIndex(): void;
+    /** Rebuild timeline.md — chronological view of all knowledge. */
+    rebuildTimeline(): void;
+    private listAllPages;
+    private parsePage;
+    private log;
+}
+//# sourceMappingURL=wiki.d.ts.map

package/dist/wiki.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki.d.ts","sourceRoot":"","sources":["../src/wiki.ts"],"names":[],"mappings":"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"}