harper-knowledge 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,317 @@
+/**
+ * harper-knowledge — Type Definitions
+ *
+ * TypeScript interfaces for all table records, search parameters,
+ * and Harper global type declarations.
+ */
+/**
+ * Describes what environment/configuration a knowledge entry applies to.
+ * Stored on KnowledgeEntry.appliesTo.
+ */
+export interface ApplicabilityScope {
+    /** Harper version or semver range (e.g., ">=4.6.0") */
+    harper?: string;
+    /** Storage engine type (e.g., "lmdb", "rocksdb") */
+    storageEngine?: string;
+    /** Node.js version or semver range */
+    node?: string;
+    /** Platform identifier (e.g., "linux", "darwin", "win32") */
+    platform?: string;
+}
+/**
+ * Caller's context for search filtering — same shape as ApplicabilityScope.
+ * Used to boost or demote results based on the caller's environment.
+ */
+export interface ApplicabilityContext {
+    /** Harper version the caller is running */
+    harper?: string;
+    /** Storage engine the caller is using */
+    storageEngine?: string;
+    /** Node.js version the caller is running */
+    node?: string;
+    /** Platform the caller is running on */
+    platform?: string;
+}
+/**
+ * Core knowledge base entry with vector embedding for semantic search.
+ * Stored in tables.KnowledgeEntry.
+ */
+export interface KnowledgeEntry {
+    id: string;
+    title: string;
+    content: string;
+    tags: string[];
+    appliesTo?: ApplicabilityScope;
+    source?: string;
+    sourceUrl?: string;
+    /** "verified", "reviewed", or "ai-generated" */
+    confidence: string;
+    addedBy?: string;
+    reviewedBy?: string;
+    embedding?: number[];
+    supersedesId?: string;
+    supersededById?: string;
+    siblingIds?: string[];
+    relatedIds?: string[];
+    customerContext?: Record<string, unknown>;
+    deprecated?: boolean;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+/**
+ * Data for creating or updating a knowledge entry.
+ * All fields except id are optional for updates.
+ */
+export interface KnowledgeEntryInput {
+    id?: string;
+    title: string;
+    content: string;
+    tags?: string[];
+    appliesTo?: ApplicabilityScope;
+    source?: string;
+    sourceUrl?: string;
+    confidence?: string;
+    addedBy?: string;
+    reviewedBy?: string;
+    customerContext?: Record<string, unknown>;
+    deprecated?: boolean;
+}
+/**
+ * Data for partial updates to an existing knowledge entry.
+ */
+export interface KnowledgeEntryUpdate {
+    title?: string;
+    content?: string;
+    tags?: string[];
+    appliesTo?: ApplicabilityScope;
+    source?: string;
+    sourceUrl?: string;
+    confidence?: string;
+    addedBy?: string;
+    reviewedBy?: string;
+    customerContext?: Record<string, unknown>;
+    deprecated?: boolean;
+}
+/**
+ * Triage item for webhook intake queue.
+ * 7-day TTL. Stored in tables.TriageItem.
+ */
+export interface TriageItem {
+    id: string;
+    source: string;
+    sourceId?: string;
+    rawPayload?: unknown;
+    summary?: string;
+    /** "pending", "processing", "accepted", or "dismissed" */
+    status: string;
+    matchedEntryId?: string;
+    draftEntryId?: string;
+    action?: string;
+    processedBy?: string;
+    createdAt?: Date;
+    processedAt?: Date;
+}
+/**
+ * Tag metadata with usage count.
+ * Tag name serves as the ID. Stored in tables.KnowledgeTag.
+ */
+export interface KnowledgeTag {
+    /** Tag name (also serves as primary key) */
+    id: string;
+    description?: string;
+    entryCount: number;
+}
+/**
+ * Search query analytics log entry.
+ * 30-day TTL. Stored in tables.QueryLog.
+ */
+export interface QueryLog {
+    id: string;
+    query: string;
+    context?: ApplicabilityContext;
+    source?: string;
+    resultCount: number;
+    topResultId?: string;
+    createdAt?: Date;
+}
+/**
+ * API key for webhooks and service accounts.
+ * Stored in tables.ServiceKey.
+ */
+export interface ServiceKey {
+    id: string;
+    name: string;
+    keyHash: string;
+    /** "service_account" or "ai_agent" */
+    role: string;
+    permissions?: Record<string, unknown>;
+    createdBy?: string;
+    createdAt?: Date;
+    lastUsedAt?: Date;
+}
+/**
+ * Edit history record for a knowledge entry.
+ * Append-only audit log. Stored in tables.KnowledgeEntryEdit.
+ */
+export interface KnowledgeEntryEdit {
+    id: string;
+    /** ID of the knowledge entry that was edited */
+    entryId: string;
+    /** Username of who made the edit */
+    editedBy: string;
+    /** Brief description of what changed and why */
+    editSummary?: string;
+    /** Snapshot of the entry before this edit */
+    previousSnapshot: Record<string, unknown>;
+    /** List of field names that were changed */
+    changedFields: string[];
+    createdAt?: Date;
+}
+/**
+ * Parameters for searching the knowledge base.
+ */
+export interface SearchParams {
+    /** Search query string */
+    query: string;
+    /** Filter by tags */
+    tags?: string[];
+    /** Maximum number of results */
+    limit?: number;
+    /** Caller's environment context for applicability filtering */
+    context?: ApplicabilityContext;
+    /** Search mode: keyword, semantic, or hybrid (default) */
+    mode?: "keyword" | "semantic" | "hybrid";
+}
+/**
+ * A search result extends a knowledge entry with relevance scoring.
+ */
+export interface SearchResult extends KnowledgeEntry {
+    /** Relevance score (higher is better) */
+    score: number;
+    /** How this result was matched: "keyword", "semantic", or "hybrid" */
+    matchType: string;
+}
+/** Action to take on a triage item */
+export type TriageAction = "accepted" | "dismissed" | "linked";
+/** Options for processing a triage item */
+export interface TriageProcessOptions {
+    /** Entry data to create when accepting */
+    entryData?: KnowledgeEntryInput;
+    /** Existing entry ID to link to */
+    linkedEntryId?: string;
+}
+/**
+ * Webhook configuration for GitHub and Datadog integrations.
+ */
+export interface WebhookConfig {
+    github?: {
+        /** HMAC-SHA256 secret for validating GitHub webhook signatures */
+        secret?: string;
+        /** Events to process (default: all supported events) */
+        enabledEvents?: string[];
+    };
+    datadog?: {
+        /** API key for validating Datadog webhook requests */
+        apiKey?: string;
+    };
+}
+/**
+ * Plugin configuration options (from parent's config.yaml).
+ */
+export interface KnowledgePluginConfig {
+    /** Embedding model name (default: "nomic-embed-text") */
+    embeddingModel?: string;
+    /** Webhook intake configuration */
+    webhooks?: WebhookConfig;
+}
+/**
+ * Logger interface matching Harper's component logger.
+ */
+export interface Logger {
+    info?: (message: string, ...args: unknown[]) => void;
+    error?: (message: string, ...args: unknown[]) => void;
+    warn?: (message: string, ...args: unknown[]) => void;
+    debug?: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * Harper table search query.
+ */
+export interface TableSearchQuery {
+    conditions?: TableCondition[];
+    sort?: TableSort;
+    limit?: number;
+    offset?: number;
+}
+export interface TableCondition {
+    attribute: string;
+    comparator: string;
+    value: unknown;
+}
+export interface TableSort {
+    attribute: string;
+    descending?: boolean;
+    /** Target vector for HNSW nearest-neighbor search */
+    target?: number[];
+}
+/**
+ * Harper table instance — methods available on each table global.
+ */
+export interface Table {
+    get(id: string): Promise<Record<string, unknown> | null>;
+    put(record: Record<string, unknown>): Promise<void>;
+    delete(id: string): Promise<void>;
+    search(query: TableSearchQuery): AsyncIterable<Record<string, unknown>>;
+}
+/**
+ * Harper Scope passed to handleApplication for sub-component plugins.
+ */
+export interface Scope {
+    logger: Logger;
+    resources: {
+        set(name: string, resource: unknown): void;
+    };
+    server: {
+        http?: (handler: (request: HarperRequest, next: (req: HarperRequest) => Promise<unknown>) => Promise<unknown>, options?: {
+            runFirst?: boolean;
+        }) => void;
+    };
+    options: {
+        get(keys: string[]): unknown;
+        getAll(): Record<string, unknown>;
+        on(event: string, handler: (...args: unknown[]) => void): void;
+    };
+    on(event: string, handler: (...args: unknown[]) => void): void;
+}
+/**
+ * Harper HTTP request object.
+ */
+export interface HarperRequest {
+    method?: string;
+    pathname?: string;
+    url?: string;
+    headers?: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    session?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Augment the global scope with Harper's runtime globals.
+ * These are available at runtime but not at compile time.
+ */
+declare global {
+    const databases: {
+        kb: {
+            KnowledgeEntry: Table;
+            TriageItem: Table;
+            KnowledgeTag: Table;
+            QueryLog: Table;
+            ServiceKey: Table;
+            OAuthClient: Table;
+            OAuthCode: Table;
+            OAuthRefreshToken: Table;
+            OAuthSigningKey: Table;
+            KnowledgeEntryEdit: Table;
+        };
+    };
+    const logger: Logger;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * harper-knowledge — Type Definitions
+ *
+ * TypeScript interfaces for all table records, search parameters,
+ * and Harper global type declarations.
+ */
+export {};

package/dist/webhooks/datadog.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Datadog Webhook Handler
+ *
+ * Validates Datadog webhook requests via API key and parses
+ * alert/monitor and incident payloads.
+ */
+import type { WebhookResult } from "./types.ts";
+/**
+ * Validate a Datadog webhook request by comparing the provided API key.
+ *
+ * Checks DD-API-KEY or X-API-Key headers against the configured key.
+ *
+ * @param headerValue - The API key from the request header
+ * @param configuredKey - The expected API key from config
+ * @returns true if the key is valid
+ */
+export declare function validateApiKey(headerValue: string, configuredKey: string): boolean;
+/**
+ * Parse a Datadog webhook payload and extract a triage-ready result.
+ *
+ * Detects payload type (alert/monitor vs incident) and formats accordingly.
+ *
+ * @param payload - The parsed JSON payload
+ * @returns A WebhookResult for triage
+ */
+export declare function parsePayload(payload: Record<string, any>): WebhookResult;

package/dist/webhooks/datadog.js

@@ -0,0 +1,120 @@
+/**
+ * Datadog Webhook Handler
+ *
+ * Validates Datadog webhook requests via API key and parses
+ * alert/monitor and incident payloads.
+ */
+import crypto from "node:crypto";
+/** Maximum body/text length included in the summary */
+const MAX_BODY_LENGTH = 500;
+/**
+ * Validate a Datadog webhook request by comparing the provided API key.
+ *
+ * Checks DD-API-KEY or X-API-Key headers against the configured key.
+ *
+ * @param headerValue - The API key from the request header
+ * @param configuredKey - The expected API key from config
+ * @returns true if the key is valid
+ */
+export function validateApiKey(headerValue, configuredKey) {
+    if (!headerValue || !configuredKey)
+        return false;
+    // Constant-time comparison to prevent timing attacks
+    if (headerValue.length !== configuredKey.length)
+        return false;
+    return crypto.timingSafeEqual(Buffer.from(headerValue), Buffer.from(configuredKey));
+}
+/**
+ * Parse a Datadog webhook payload and extract a triage-ready result.
+ *
+ * Detects payload type (alert/monitor vs incident) and formats accordingly.
+ *
+ * @param payload - The parsed JSON payload
+ * @returns A WebhookResult for triage
+ */
+export function parsePayload(payload) {
+    // Alert/monitor payload: has alert_type or event_type === 'alert'
+    if (payload.alert_type || payload.event_type === "alert") {
+        return parseAlertPayload(payload);
+    }
+    // Incident payload: has severity or status field with incident-like structure
+    if (payload.severity !== undefined ||
+        (payload.status && payload.incident_id)) {
+        return parseIncidentPayload(payload);
+    }
+    // Fallback: unknown format, still triage it
+    return parseFallbackPayload(payload);
+}
+function parseAlertPayload(payload) {
+    const id = payload.alert_id || payload.id || payload.event_id || crypto.randomUUID();
+    const title = payload.title ||
+        payload.alert_title ||
+        payload.msg_title ||
+        "Untitled Alert";
+    const priority = payload.priority ? `P${payload.priority}` : "";
+    const alertType = payload.alert_type || "alert";
+    const text = truncate(payload.body || payload.text || payload.msg_text || "");
+    const tags = formatTags(payload.tags);
+    const parts = [
+        `[Datadog Alert] ${title}${priority ? ` (${priority}, ${alertType})` : ` (${alertType})`}`,
+    ];
+    if (tags)
+        parts.push(`Tags: ${tags}`);
+    parts.push("---");
+    parts.push(text);
+    return {
+        source: "datadog-webhook",
+        sourceId: `datadog:alert:${id}`,
+        summary: parts.join("\n"),
+        rawPayload: payload,
+    };
+}
+function parseIncidentPayload(payload) {
+    const id = payload.incident_id || payload.id || crypto.randomUUID();
+    const title = payload.title || payload.incident_title || "Untitled Incident";
+    const severity = payload.severity || "unknown";
+    const status = payload.status || "unknown";
+    const text = truncate(payload.body || payload.text || payload.description || "");
+    const tags = formatTags(payload.tags);
+    const parts = [
+        `[Datadog Incident] ${title} (severity: ${severity}, status: ${status})`,
+    ];
+    if (tags)
+        parts.push(`Tags: ${tags}`);
+    parts.push("---");
+    parts.push(text);
+    return {
+        source: "datadog-webhook",
+        sourceId: `datadog:incident:${id}`,
+        summary: parts.join("\n"),
+        rawPayload: payload,
+    };
+}
+function parseFallbackPayload(payload) {
+    const id = payload.id || crypto.randomUUID();
+    const title = payload.title || payload.subject || "Datadog Event";
+    const text = truncate(payload.body ||
+        payload.text ||
+        payload.message ||
+        JSON.stringify(payload).slice(0, MAX_BODY_LENGTH));
+    return {
+        source: "datadog-webhook",
+        sourceId: `datadog:event:${id}`,
+        summary: `[Datadog Event] ${title}\n---\n${text}`,
+        rawPayload: payload,
+    };
+}
+function formatTags(tags) {
+    if (!tags)
+        return "";
+    if (Array.isArray(tags))
+        return tags.join(", ");
+    if (typeof tags === "string")
+        return tags;
+    return "";
+}
+function truncate(text) {
+    if (text.length <= MAX_BODY_LENGTH)
+        return text;
+    return text.slice(0, MAX_BODY_LENGTH) + "...";
+}

package/dist/webhooks/github.d.ts

@@ -0,0 +1,24 @@
+/**
+ * GitHub Webhook Handler
+ *
+ * Validates GitHub webhook signatures (HMAC-SHA256) and parses payloads
+ * for issues, issue comments, discussions, and discussion comments.
+ */
+import type { WebhookResult } from "./types.ts";
+/**
+ * Validate a GitHub webhook signature using HMAC-SHA256.
+ *
+ * @param rawBody - The raw request body string
+ * @param signature - The X-Hub-Signature-256 header value
+ * @param secret - The configured webhook secret
+ * @returns true if the signature is valid
+ */
+export declare function validateSignature(rawBody: string, signature: string, secret: string): boolean;
+/**
+ * Parse a GitHub webhook payload and extract a triage-ready result.
+ *
+ * @param event - The X-GitHub-Event header value
+ * @param payload - The parsed JSON payload
+ * @returns A WebhookResult for triage, or null if the event should be ignored
+ */
+export declare function parsePayload(event: string, payload: Record<string, any>): WebhookResult | null;

package/dist/webhooks/github.js

@@ -0,0 +1,167 @@
+/**
+ * GitHub Webhook Handler
+ *
+ * Validates GitHub webhook signatures (HMAC-SHA256) and parses payloads
+ * for issues, issue comments, discussions, and discussion comments.
+ */
+import crypto from "node:crypto";
+/** Maximum body length included in the summary */
+const MAX_BODY_LENGTH = 500;
+/**
+ * Validate a GitHub webhook signature using HMAC-SHA256.
+ *
+ * @param rawBody - The raw request body string
+ * @param signature - The X-Hub-Signature-256 header value
+ * @param secret - The configured webhook secret
+ * @returns true if the signature is valid
+ */
+export function validateSignature(rawBody, signature, secret) {
+    if (!signature || !secret)
+        return false;
+    const expected = "sha256=" +
+        crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
+    // Constant-time comparison to prevent timing attacks
+    if (expected.length !== signature.length)
+        return false;
+    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
+}
+/**
+ * Parse a GitHub webhook payload and extract a triage-ready result.
+ *
+ * @param event - The X-GitHub-Event header value
+ * @param payload - The parsed JSON payload
+ * @returns A WebhookResult for triage, or null if the event should be ignored
+ */
+export function parsePayload(event, payload) {
+    switch (event) {
+        case "issues":
+            return parseIssueEvent(payload);
+        case "issue_comment":
+            return parseIssueCommentEvent(payload);
+        case "discussion":
+            return parseDiscussionEvent(payload);
+        case "discussion_comment":
+            return parseDiscussionCommentEvent(payload);
+        default:
+            return null;
+    }
+}
+function parseIssueEvent(payload) {
+    const action = payload.action;
+    const issue = payload.issue;
+    const repo = payload.repository?.full_name;
+    if (!issue || !repo)
+        return null;
+    // Only handle opened, closed, reopened
+    const directActions = ["opened", "closed", "reopened"];
+    if (directActions.includes(action)) {
+        return {
+            source: "github-webhook",
+            sourceId: `github:issues:${action}:${repo}#${issue.number}`,
+            summary: formatIssueSummary(repo, issue, action),
+            rawPayload: payload,
+        };
+    }
+    // Handle labeled — only if the label is "kb-candidate"
+    if (action === "labeled") {
+        const label = payload.label;
+        if (label?.name === "kb-candidate") {
+            return {
+                source: "github-webhook",
+                sourceId: `github:issues:labeled:${repo}#${issue.number}`,
+                summary: formatIssueSummary(repo, issue, "labeled"),
+                rawPayload: payload,
+            };
+        }
+        return null;
+    }
+    return null;
+}
+function parseIssueCommentEvent(payload) {
+    const action = payload.action;
+    if (action !== "created")
+        return null;
+    const comment = payload.comment;
+    const issue = payload.issue;
+    const repo = payload.repository?.full_name;
+    if (!comment || !issue || !repo)
+        return null;
+    const body = truncate(comment.body || "");
+    const summary = [
+        `[GitHub Comment] ${repo}#${issue.number}: "${issue.title}" (comment by ${comment.user?.login || "unknown"})`,
+        "---",
+        body,
+    ].join("\n");
+    return {
+        source: "github-webhook",
+        sourceId: `github:issue_comment:${comment.id}`,
+        summary,
+        rawPayload: payload,
+    };
+}
+function parseDiscussionEvent(payload) {
+    const action = payload.action;
+    if (action !== "created" && action !== "answered")
+        return null;
+    const discussion = payload.discussion;
+    const repo = payload.repository?.full_name;
+    if (!discussion || !repo)
+        return null;
+    const body = truncate(discussion.body || "");
+    const category = discussion.category?.name;
+    const summary = [
+        `[GitHub Discussion] ${repo}#${discussion.number}: "${discussion.title}" (${action} by ${discussion.user?.login || "unknown"})`,
+        category ? `Category: ${category}` : "",
+        "---",
+        body,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return {
+        source: "github-webhook",
+        sourceId: `github:discussion:${action}:${repo}#${discussion.number}`,
+        summary,
+        rawPayload: payload,
+    };
+}
+function parseDiscussionCommentEvent(payload) {
+    const action = payload.action;
+    if (action !== "created")
+        return null;
+    const comment = payload.comment;
+    const discussion = payload.discussion;
+    const repo = payload.repository?.full_name;
+    if (!comment || !discussion || !repo)
+        return null;
+    const body = truncate(comment.body || "");
+    const summary = [
+        `[GitHub Discussion Comment] ${repo}#${discussion.number}: "${discussion.title}" (comment by ${comment.user?.login || "unknown"})`,
+        "---",
+        body,
+    ].join("\n");
+    return {
+        source: "github-webhook",
+        sourceId: `github:discussion_comment:${comment.id}`,
+        summary,
+        rawPayload: payload,
+    };
+}
+function formatIssueSummary(repo, issue, action) {
+    const labels = (issue.labels || [])
+        .map((l) => l.name)
+        .join(", ");
+    const body = truncate(issue.body || "");
+    const parts = [
+        `[GitHub Issue] ${repo}#${issue.number}: "${issue.title}" (${action} by ${issue.user?.login || "unknown"})`,
+    ];
+    if (labels)
+        parts.push(`Labels: ${labels}`);
+    parts.push("---");
+    parts.push(body);
+    return parts.join("\n");
+}
+function truncate(text) {
+    if (text.length <= MAX_BODY_LENGTH)
+        return text;
+    return text.slice(0, MAX_BODY_LENGTH) + "...";
+}

package/dist/webhooks/middleware.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Webhook Middleware
+ *
+ * HTTP middleware for Harper's scope.server.http() that routes
+ * /webhooks/* requests to the appropriate webhook handler.
+ */
+import type { Scope, HarperRequest } from "../types.ts";
+/**
+ * Create a webhook middleware function for Harper's scope.server.http().
+ *
+ * Reads webhook config from scope.options and watches for changes
+ * to support secret rotation without restart.
+ */
+export declare function createWebhookMiddleware(scope: Scope): (request: HarperRequest, next: (req: HarperRequest) => Promise<unknown>) => Promise<unknown>;