@autorag/librarian 2.0.0 → 2.1.0

package/dist/datasource/skills/gmail/himalaya-connector.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Himalaya-backed mail connector (issue #1304, IMAP path).
+ *
+ * Uses the external `himalaya` CLI (https://pimalaya.org) as the trusted
+ * bridge to any IMAP/Maildir account it has configured — Gmail included —
+ * so no OAuth token plumbing is needed here. Mirrors the katok pattern:
+ * AutoRAG never opens the mailbox itself; it spawns the CLI, parses JSON
+ * envelopes, and reads message bodies. Never throws; failures map onto the
+ * coarse connector failure union with path/PII-opaque messages.
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface HimalayaRunResult {
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number | null;
+}
+export type HimalayaRunner = (args: readonly string[], timeoutMs: number) => Promise<HimalayaRunResult>;
+export interface HimalayaConnectorOptions {
+    /** Path to the himalaya binary. Default bare `himalaya` PATH lookup. */
+    readonly binaryPath?: string;
+    /** Himalaya account name (`himalaya account list`). Default account when omitted. */
+    readonly account?: string;
+    /** Mail folder, e.g. `INBOX`. Himalaya's default folder when omitted. */
+    readonly folder?: string;
+    /** Envelopes per listing page. Default 100. */
+    readonly pageSize?: number;
+    /** Max messages whose bodies are fetched per run. Default 50. */
+    readonly maxDocuments?: number;
+    /** Per-spawn timeout. Default 30s (IMAP fetches can be slow). */
+    readonly timeoutMs?: number;
+    /** Injectable process runner for tests. */
+    readonly runner?: HimalayaRunner;
+}
+export declare class HimalayaConnector implements DatasourceConnector {
+    private readonly options;
+    private readonly runner;
+    constructor(options?: HimalayaConnectorOptions);
+    fetch(): Promise<ConnectorFetchResult>;
+}

package/dist/datasource/skills/gmail/index.d.ts

@@ -0,0 +1,3 @@
+export { GmailConnector, type GmailConnectorOptions } from "./connector.js";
+export { HimalayaConnector, type HimalayaConnectorOptions, type HimalayaRunner, type HimalayaRunResult, } from "./himalaya-connector.js";
+export { GMAIL_SKILL_DEFINITION, GmailSkill, type GmailSkillOptions } from "./skill.js";

package/dist/datasource/skills/gmail/skill.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Gmail datasource skill (issue #1304).
+ *
+ * Thin composition of GmailConnector with the shared
+ * {@link ConnectorDatasourceSkill} base: descriptor, polling metadata,
+ * ok/fail indexing with path/PII-opaque diagnostics, lexical retrieval via
+ * the shared pipeline, opaque `/gmail/<instance>/…` sources, and a
+ * progressive-disclosure agent-skill manifest.
+ */
+import type { DatasourceConnector } from "../../connector.js";
+import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
+import { type GmailConnectorOptions } from "./connector.js";
+export declare const GMAIL_SKILL_DEFINITION: ConnectorSkillDefinition;
+export interface GmailSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+    /**
+     * Trusted pre-built connector; wins over {@link connectorOptions}. Accepts
+     * any mail-backed connector (Gmail REST or the himalaya CLI bridge).
+     */
+    readonly connector?: DatasourceConnector;
+    readonly connectorOptions?: GmailConnectorOptions;
+}
+export declare class GmailSkill extends ConnectorDatasourceSkill {
+    constructor(options?: GmailSkillOptions);
+}

package/dist/datasource/skills/mail-export/connector.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Local mail export connector (issue #1311).
+ *
+ * Parses `.eml` files and `.mbox` archives from trusted, server-configured
+ * filesystem paths using the existing `mailparser` dependency. No network
+ * access. Per-message parse failures aggregate into one count-only warning;
+ * absolute paths never appear in warnings or failure messages.
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface MailExportConnectorOptions {
+    /** Files or directories containing `.eml` / `.mbox` archives. Required. */
+    readonly paths?: readonly string[];
+    readonly maxDocuments?: number;
+    /** Files larger than this are skipped with a warning. Default 50 MiB. */
+    readonly maxBytesPerFile?: number;
+}
+export declare class MailExportConnector implements DatasourceConnector {
+    private readonly options;
+    constructor(options?: MailExportConnectorOptions);
+    fetch(): Promise<ConnectorFetchResult>;
+}

package/dist/datasource/skills/mail-export/index.d.ts

@@ -0,0 +1,2 @@
+export { MailExportConnector, type MailExportConnectorOptions } from "./connector.js";
+export { MAIL_EXPORT_SKILL_DEFINITION, MailExportSkill, type MailExportSkillOptions } from "./skill.js";

package/dist/datasource/skills/mail-export/skill.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Local mail export datasource skill (issue #1311).
+ *
+ * Thin composition of MailExportConnector with the shared
+ * {@link ConnectorDatasourceSkill} base: descriptor, polling metadata,
+ * ok/fail indexing with path/PII-opaque diagnostics, lexical retrieval via
+ * the shared pipeline, opaque `/mail-export/<instance>/…` sources, and a
+ * progressive-disclosure agent-skill manifest.
+ */
+import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
+import { MailExportConnector, type MailExportConnectorOptions } from "./connector.js";
+export declare const MAIL_EXPORT_SKILL_DEFINITION: ConnectorSkillDefinition;
+export interface MailExportSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+    /** Trusted connector configuration; a pre-built connector wins. */
+    readonly connector?: MailExportConnector;
+    readonly connectorOptions?: MailExportConnectorOptions;
+}
+export declare class MailExportSkill extends ConnectorDatasourceSkill {
+    constructor(options?: MailExportSkillOptions);
+}

package/dist/datasource/skills/notion/connector.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Notion workspace connector (issue #1302).
+ *
+ * Enumerates pages/databases via the Notion search API using a trusted,
+ * server-configured integration token, then pulls one page of block children
+ * per page for text content. Per-page block failures degrade to warnings.
+ * Never throws; messages stay path/PII-opaque.
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface NotionConnectorOptions {
+    /** Notion REST base; override to point at a mock server in tests. */
+    readonly baseUrl?: string;
+    /** Integration token; explicit value wins over {@link tokenEnv}. */
+    readonly token?: string;
+    /** Env var name holding the integration token. Default `NOTION_TOKEN`. */
+    readonly tokenEnv?: string;
+    readonly timeoutMs?: number;
+    readonly fetchImpl?: typeof fetch;
+    readonly maxPages?: number;
+    readonly maxDocuments?: number;
+}
+export declare class NotionConnector implements DatasourceConnector {
+    private readonly options;
+    constructor(options?: NotionConnectorOptions);
+    fetch(signal?: AbortSignal): Promise<ConnectorFetchResult>;
+}

package/dist/datasource/skills/notion/index.d.ts

@@ -0,0 +1,2 @@
+export { NotionConnector, type NotionConnectorOptions } from "./connector.js";
+export { NOTION_SKILL_DEFINITION, NotionSkill, type NotionSkillOptions } from "./skill.js";

package/dist/datasource/skills/notion/skill.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Notion workspace datasource skill (issue #1302).
+ *
+ * Thin composition of NotionConnector with the shared
+ * {@link ConnectorDatasourceSkill} base: descriptor, polling metadata,
+ * ok/fail indexing with path/PII-opaque diagnostics, lexical retrieval via
+ * the shared pipeline, opaque `/notion/<instance>/…` sources, and a
+ * progressive-disclosure agent-skill manifest.
+ */
+import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
+import { NotionConnector, type NotionConnectorOptions } from "./connector.js";
+export declare const NOTION_SKILL_DEFINITION: ConnectorSkillDefinition;
+export interface NotionSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+    /** Trusted connector configuration; a pre-built connector wins. */
+    readonly connector?: NotionConnector;
+    readonly connectorOptions?: NotionConnectorOptions;
+}
+export declare class NotionSkill extends ConnectorDatasourceSkill {
+    constructor(options?: NotionSkillOptions);
+}

package/dist/datasource/skills/obsidian/connector.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Obsidian vault connector (issue #1314).
+ *
+ * Walks a trusted, server-configured vault directory for markdown notes,
+ * extracting frontmatter/inline tags, wiki links, and embeds. No network
+ * access. Per-file read failures aggregate into a count-only warning;
+ * absolute paths never appear in warnings (vault-relative segments are the
+ * vault's own logical hierarchy and are allowed in doc ids).
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface ObsidianConnectorOptions {
+    /** Absolute path to the vault root. Required trusted configuration. */
+    readonly vaultPath?: string;
+    readonly maxDocuments?: number;
+    /** Files larger than this are skipped. Default 2 MiB. */
+    readonly maxBytesPerFile?: number;
+}
+export declare class ObsidianConnector implements DatasourceConnector {
+    private readonly options;
+    constructor(options?: ObsidianConnectorOptions);
+    fetch(): Promise<ConnectorFetchResult>;
+}

package/dist/datasource/skills/obsidian/index.d.ts

@@ -0,0 +1,2 @@
+export { ObsidianConnector, type ObsidianConnectorOptions } from "./connector.js";
+export { OBSIDIAN_SKILL_DEFINITION, ObsidianSkill, type ObsidianSkillOptions } from "./skill.js";

package/dist/datasource/skills/obsidian/skill.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Obsidian vault datasource skill (issue #1314).
+ *
+ * Thin composition of ObsidianConnector with the shared
+ * {@link ConnectorDatasourceSkill} base: descriptor, polling metadata,
+ * ok/fail indexing with path/PII-opaque diagnostics, lexical retrieval via
+ * the shared pipeline, opaque `/obsidian/<instance>/…` sources, and a
+ * progressive-disclosure agent-skill manifest.
+ */
+import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
+import { ObsidianConnector, type ObsidianConnectorOptions } from "./connector.js";
+export declare const OBSIDIAN_SKILL_DEFINITION: ConnectorSkillDefinition;
+export interface ObsidianSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+    /** Trusted connector configuration; a pre-built connector wins. */
+    readonly connector?: ObsidianConnector;
+    readonly connectorOptions?: ObsidianConnectorOptions;
+}
+export declare class ObsidianSkill extends ConnectorDatasourceSkill {
+    constructor(options?: ObsidianSkillOptions);
+}

package/dist/datasource/skills/rss/connector.d.ts

@@ -0,0 +1,28 @@
+/**
+ * RSS/news connector (issue #1316).
+ *
+ * Fetches RSS 2.0 / Atom feeds from a trusted, server-configured feed list
+ * using the existing `fast-xml-parser` dependency. Feeds are referenced by
+ * index in warnings — never by URL — so diagnostics stay opaque. Per-feed
+ * failures degrade to warnings; only all feeds failing fails the fetch.
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface RssFeedConfig {
+    readonly url: string;
+    /** Optional category segment inserted into the hierarchy. */
+    readonly category?: string;
+}
+export interface RssConnectorOptions {
+    /** Feeds to poll. Required trusted configuration. */
+    readonly feeds?: readonly RssFeedConfig[];
+    readonly timeoutMs?: number;
+    readonly fetchImpl?: typeof fetch;
+    readonly maxDocuments?: number;
+    readonly maxItemsPerFeed?: number;
+}
+export declare class RssConnector implements DatasourceConnector {
+    private readonly options;
+    private readonly parser;
+    constructor(options?: RssConnectorOptions);
+    fetch(signal?: AbortSignal): Promise<ConnectorFetchResult>;
+}

package/dist/datasource/skills/rss/index.d.ts

@@ -0,0 +1,2 @@
+export { RssConnector, type RssConnectorOptions, type RssFeedConfig } from "./connector.js";
+export { RSS_SKILL_DEFINITION, RssSkill, type RssSkillOptions } from "./skill.js";

package/dist/datasource/skills/rss/skill.d.ts

@@ -0,0 +1,22 @@
+/**
+ * RSS/news datasource skill (issue #1316).
+ *
+ * Thin composition of RssConnector with the shared
+ * {@link ConnectorDatasourceSkill} base: descriptor, polling metadata,
+ * ok/fail indexing with path/PII-opaque diagnostics, lexical retrieval via
+ * the shared pipeline, opaque `/rss/<instance>/…` sources, and a
+ * progressive-disclosure agent-skill manifest.
+ */
+import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
+import { RssConnector, type RssConnectorOptions } from "./connector.js";
+export declare const RSS_SKILL_DEFINITION: ConnectorSkillDefinition;
+export interface RssSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+    /** Trusted connector configuration; a pre-built connector wins. */
+    readonly connector?: RssConnector;
+    readonly connectorOptions?: RssConnectorOptions;
+    /** Dedupe window for re-delivered feed items. Default 24 hours. */
+    readonly dedupeWindowMs?: number;
+}
+export declare class RssSkill extends ConnectorDatasourceSkill {
+    constructor(options?: RssSkillOptions);
+}

package/dist/datasource/skills/slack/connector.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Slack workspace connector (issue #1300).
+ *
+ * Fetches channel history through the Slack Web API using a trusted,
+ * server-configured bot token. Never throws; failures map onto the coarse
+ * connector failure union with path/PII-opaque messages. Per-channel
+ * failures degrade to warnings so one denied channel cannot fail the fetch.
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface SlackConnectorOptions {
+    /** Slack Web API base; override to point at a mock server in tests. */
+    readonly baseUrl?: string;
+    /** Bot token; explicit value wins over {@link tokenEnv}. */
+    readonly token?: string;
+    /** Env var name holding the bot token. Default `SLACK_BOT_TOKEN`. */
+    readonly tokenEnv?: string;
+    /** Restrict indexing to these channel names or ids. */
+    readonly channels?: readonly string[];
+    readonly timeoutMs?: number;
+    readonly fetchImpl?: typeof fetch;
+    readonly maxPages?: number;
+    readonly maxDocuments?: number;
+}
+export declare class SlackConnector implements DatasourceConnector {
+    private readonly options;
+    constructor(options?: SlackConnectorOptions);
+    fetch(signal?: AbortSignal): Promise<ConnectorFetchResult>;
+}

package/dist/datasource/skills/slack/index.d.ts

@@ -0,0 +1,2 @@
+export { SlackConnector, type SlackConnectorOptions } from "./connector.js";
+export { SLACK_SKILL_DEFINITION, SlackSkill, type SlackSkillOptions } from "./skill.js";

package/dist/datasource/skills/slack/skill.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Slack workspace datasource skill (issue #1300).
+ *
+ * Thin composition of SlackConnector with the shared
+ * {@link ConnectorDatasourceSkill} base: descriptor, polling metadata,
+ * ok/fail indexing with path/PII-opaque diagnostics, lexical retrieval via
+ * the shared pipeline, opaque `/slack/<instance>/…` sources, and a
+ * progressive-disclosure agent-skill manifest.
+ */
+import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
+import { SlackConnector, type SlackConnectorOptions } from "./connector.js";
+export declare const SLACK_SKILL_DEFINITION: ConnectorSkillDefinition;
+export interface SlackSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+    /** Trusted connector configuration; a pre-built connector wins. */
+    readonly connector?: SlackConnector;
+    readonly connectorOptions?: SlackConnectorOptions;
+}
+export declare class SlackSkill extends ConnectorDatasourceSkill {
+    constructor(options?: SlackSkillOptions);
+}

package/dist/datasource/skills/spotlight/connector.d.ts

@@ -0,0 +1,59 @@
+/**
+ * macOS Spotlight connector (issue #1350).
+ *
+ * Runs the built-in `mdfind` CLI for trusted, server-configured Spotlight
+ * queries and hydrates text content for chunking. No external installs —
+ * Spotlight ships with macOS. **macOS only**: on any other platform the
+ * connector reports `unavailable` before spawning anything.
+ *
+ * Full Disk Access: Spotlight returns hits for protected locations (Mail,
+ * Messages, Safari data, parts of ~/Library) but reading those files fails
+ * with EPERM/EACCES unless the process running AutoRAG (the terminal app or
+ * host binary) has Full Disk Access under System Settings -> Privacy &
+ * Security. When every content read is denied this maps to the `permission`
+ * failure reason with opaque FDA guidance; partial denials surface as
+ * count-only warnings. Full absolute paths are exposed in document metadata
+ * (`path`) so results stay traceable back to the file on disk — privacy is
+ * the operator's responsibility (run AutoRAG with a local LLM if paths must
+ * not leave the machine).
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface ProcessRunResult {
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number | null;
+    /** Spawn error code, e.g. `"ENOENT"` when the binary is missing. */
+    readonly error?: string;
+}
+/** Process execution seam; injectable for tests. Never throws. */
+export type ProcessRunner = (command: string, args: readonly string[], timeoutMs: number) => Promise<ProcessRunResult>;
+export type FileReader = (path: string) => Promise<string>;
+export interface SpotlightConnectorOptions {
+    /** Trusted Spotlight query strings passed to `mdfind`. Required. */
+    readonly queries?: readonly string[];
+    /** Trusted directory restricting every query (`mdfind -onlyin`). */
+    readonly onlyIn?: string;
+    /** Hits kept per query after dedupe. Default 100. */
+    readonly maxResultsPerQuery?: number;
+    /** Total documents hydrated per fetch. Default 300. */
+    readonly maxDocuments?: number;
+    /** Files larger than this are skipped. Default 256 KiB. */
+    readonly maxBytesPerFile?: number;
+    /** Per-process timeout in ms. Default 15s. */
+    readonly timeoutMs?: number;
+    /** Injectable platform; defaults to `process.platform`. */
+    readonly platform?: NodeJS.Platform;
+    /** Injectable process runner; defaults to a bounded spawn wrapper. */
+    readonly run?: ProcessRunner;
+    /** Injectable file reader; defaults to utf8 `fs.readFile`. */
+    readonly readFile?: FileReader;
+}
+export declare class SpotlightConnector implements DatasourceConnector {
+    private readonly options;
+    private readonly run;
+    private readonly readFile;
+    private readonly platform;
+    constructor(options?: SpotlightConnectorOptions);
+    fetch(): Promise<ConnectorFetchResult>;
+}

package/dist/datasource/skills/spotlight/index.d.ts

@@ -0,0 +1,2 @@
+export { type FileReader, type ProcessRunner, type ProcessRunResult, SpotlightConnector, type SpotlightConnectorOptions, } from "./connector.js";
+export { SPOTLIGHT_SKILL_DEFINITION, SpotlightSkill, type SpotlightSkillOptions } from "./skill.js";

package/dist/datasource/skills/spotlight/skill.d.ts

@@ -0,0 +1,20 @@
+/**
+ * macOS Spotlight datasource skill (issue #1350).
+ *
+ * Thin composition of {@link SpotlightConnector} with the shared
+ * {@link ConnectorDatasourceSkill} base. The skill is **macOS only** and
+ * needs no external installs — it drives the built-in `mdfind` CLI. The
+ * manifest carries operator guidance for mdfind/mdls/mdutil and the Full
+ * Disk Access requirement.
+ */
+import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
+import { SpotlightConnector, type SpotlightConnectorOptions } from "./connector.js";
+export declare const SPOTLIGHT_SKILL_DEFINITION: ConnectorSkillDefinition;
+export interface SpotlightSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+    /** Trusted connector configuration; a pre-built connector wins. */
+    readonly connector?: SpotlightConnector;
+    readonly connectorOptions?: SpotlightConnectorOptions;
+}
+export declare class SpotlightSkill extends ConnectorDatasourceSkill {
+    constructor(options?: SpotlightSkillOptions);
+}