@patimweb/pi-outline-wiki 1.0.0

package/src/tools/outline-read.ts

@@ -0,0 +1,104 @@
+/**
+ * outline_read tool -- Read one document's markdown body.
+ *
+ * Long wiki pages can blow a context window, so the body is truncated by
+ * default and the caller decides how much to pull in.
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import {
+  getDocument,
+  listDocuments,
+  slugifyTitle,
+  writeMarkdownFile,
+} from "../clients/outline-client.ts";
+import { formatDocument, formatDocumentList } from "../formatting/formatters.ts";
+
+const DEFAULT_MAX_CHARS = 20_000;
+
+export const OutlineReadTool = {
+  name: "outline_read",
+  label: "Outline Read Document",
+  description:
+    "Read a document's full markdown body by id (the id or urlId from outline_search, outline_list or outline_structure). Optionally list its child documents or save it to a local markdown file.",
+  parameters: Type.Object({
+    id: Type.String({
+      description: "Document id (uuid) or urlId from an Outline URL.",
+    }),
+    maxChars: Type.Optional(
+      Type.Number({
+        description:
+          "Truncate the body after this many characters. Default 20000. Use 0 for no limit.",
+        default: DEFAULT_MAX_CHARS,
+      }),
+    ),
+    includeChildren: Type.Optional(
+      Type.Boolean({
+        description: "Also list the direct child documents. Default false.",
+        default: false,
+      }),
+    ),
+    saveDir: Type.Optional(
+      Type.String({
+        description:
+          "Directory to save the document as a .md file in. Absolute paths are safest.",
+      }),
+    ),
+    profile: Type.Optional(
+      Type.String({ description: "Outline profile to use. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: {
+      id: string;
+      maxChars?: number;
+      includeChildren?: boolean;
+      saveDir?: string;
+      profile?: string;
+    },
+    signal: AbortSignal,
+  ) {
+    const config = resolveConfig(params.profile);
+    const doc = await getDocument(config, params.id, signal);
+    const maxChars = params.maxChars ?? DEFAULT_MAX_CHARS;
+
+    const sections = [formatDocument(doc, { maxChars })];
+
+    let savedPath: string | undefined;
+    if (params.saveDir) {
+      savedPath = writeMarkdownFile(
+        params.saveDir,
+        `${slugifyTitle(doc.title)}.md`,
+        `# ${doc.title}\n\n${doc.text}\n`,
+      );
+      sections.push(`\nSaved full document to ${savedPath}`);
+    }
+
+    let childCount = 0;
+    if (params.includeChildren) {
+      const { documents } = await listDocuments(
+        config,
+        { parentDocumentId: doc.id, limit: 50 },
+        signal,
+      );
+      childCount = documents.length;
+      sections.push(`\n${formatDocumentList(documents, "Child documents")}`);
+    }
+
+    return {
+      content: [{ type: "text" as const, text: sections.join("\n") }],
+      details: {
+        id: doc.id,
+        title: doc.title,
+        collectionId: doc.collectionId,
+        length: doc.text.length,
+        truncated: maxChars > 0 && doc.text.length > maxChars,
+        childCount,
+        savedPath,
+      },
+    };
+  },
+};

package/src/tools/outline-search.ts

@@ -0,0 +1,114 @@
+/**
+ * outline_search tool -- Full-text search across the workspace.
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import { searchDocuments } from "../clients/outline-client.ts";
+import { formatSearchResults } from "../formatting/formatters.ts";
+
+const VALID_STATUS = new Set(["draft", "archived", "published"]);
+const VALID_DATE = new Set(["day", "week", "month", "year"]);
+
+export const OutlineSearchTool = {
+  name: "outline_search",
+  label: "Outline Search",
+  description:
+    "Full-text search across the Outline wiki. Returns matching documents with a snippet and their ids; read the full text with outline_read. Prefer two or three distinctive keywords over long sentences.",
+  parameters: Type.Object({
+    query: Type.String({
+      description: "Search keywords. Distinctive nouns work better than full questions.",
+    }),
+    limit: Type.Optional(
+      Type.Number({ description: "How many results to return. Default 15.", default: 15 }),
+    ),
+    offset: Type.Optional(
+      Type.Number({ description: "Pagination offset. Default 0.", default: 0 }),
+    ),
+    collectionId: Type.Optional(
+      Type.String({ description: "Restrict the search to one collection." }),
+    ),
+    documentId: Type.Optional(
+      Type.String({ description: "Restrict the search to one document and its children." }),
+    ),
+    statusFilter: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          "Restrict to document states: any of draft, archived, published. Defaults to published documents.",
+      }),
+    ),
+    dateFilter: Type.Optional(
+      Type.String({
+        description: "Only documents updated within: day, week, month or year.",
+      }),
+    ),
+    profile: Type.Optional(
+      Type.String({ description: "Outline profile to use. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: {
+      query: string;
+      limit?: number;
+      offset?: number;
+      collectionId?: string;
+      documentId?: string;
+      statusFilter?: string[];
+      dateFilter?: string;
+      profile?: string;
+    },
+    signal: AbortSignal,
+  ) {
+    if (!params.query || !params.query.trim()) {
+      throw new Error("query must not be empty.");
+    }
+    if (params.statusFilter) {
+      const invalid = params.statusFilter.filter((s) => !VALID_STATUS.has(s));
+      if (invalid.length > 0) {
+        throw new Error(
+          `Invalid statusFilter value(s): ${invalid.join(", ")}. Use draft, archived or published.`,
+        );
+      }
+    }
+    if (params.dateFilter && !VALID_DATE.has(params.dateFilter)) {
+      throw new Error(
+        `Invalid dateFilter "${params.dateFilter}". Use day, week, month or year.`,
+      );
+    }
+
+    const config = resolveConfig(params.profile);
+    const { hits, pagination } = await searchDocuments(
+      config,
+      {
+        query: params.query.trim(),
+        limit: params.limit,
+        offset: params.offset,
+        collectionId: params.collectionId,
+        documentId: params.documentId,
+        statusFilter: params.statusFilter,
+        dateFilter: params.dateFilter,
+      },
+      signal,
+    );
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: formatSearchResults(hits, params.query.trim(), pagination),
+        },
+      ],
+      details: {
+        query: params.query.trim(),
+        count: hits.length,
+        documents: hits.map((hit) => ({
+          id: hit.document.id,
+          title: hit.document.title,
+        })),
+        pagination,
+      },
+    };
+  },
+};

package/src/tools/outline-setup.ts

@@ -0,0 +1,71 @@
+/**
+ * outline_setup tool -- Configure an Outline workspace.
+ *
+ * Stores a named profile. A profile is automatically set as active
+ * if it's the first one. Use outline_status to see all profiles and
+ * outline_profile to switch between them.
+ */
+
+import { Type } from "typebox";
+import { saveProfile, normalizeBaseUrl, resolveConfig } from "../config.ts";
+import { getWorkspaceInfo } from "../clients/outline-client.ts";
+import { formatWorkspaceInfo } from "../formatting/formatters.ts";
+import type { OutlineConfig, SetupParams } from "../types.ts";
+
+export const OutlineSetupTool = {
+  name: "outline_setup",
+  label: "Outline Setup",
+  description:
+    "Configure an Outline workspace (URL + API key). Call this first before using any other outline tool. The API key is created in Outline under Settings -> API & Apps and starts with 'ol_api_'. Credentials are stored in ~/.pi/outline-config.json (readable only by you). Works with both cloud (yourteam.getoutline.com) and self-hosted installations.",
+  parameters: Type.Object({
+    name: Type.String({
+      description:
+        "Profile name, e.g. 'work', 'company-wiki'. Use a short, memorable name.",
+    }),
+    url: Type.String({
+      description:
+        "Workspace URL, e.g. https://acme.getoutline.com or https://wiki.example.com. A trailing /api or /mcp is stripped automatically.",
+    }),
+    apiKey: Type.String({
+      description: "Outline API key from Settings -> API & Apps (starts with ol_api_).",
+    }),
+    insecureTls: Type.Optional(
+      Type.Boolean({
+        description:
+          "Skip TLS certificate validation. Only for self-hosted instances with a self-signed certificate; this disables validation for the whole pi process.",
+      }),
+    ),
+  }),
+
+  async execute(_toolCallId: string, params: SetupParams, signal: AbortSignal) {
+    const config: OutlineConfig = {
+      url: normalizeBaseUrl(params.url),
+      apiKey: params.apiKey.trim(),
+      ...(params.insecureTls !== undefined && { insecureTls: params.insecureTls }),
+    };
+
+    saveProfile(params.name, config);
+
+    // Verify immediately: a typo in the URL or key is much cheaper to find
+    // here than inside the first real document call.
+    let verification: string;
+    let verified = false;
+    try {
+      const info = await getWorkspaceInfo(resolveConfig(params.name), signal);
+      verification = formatWorkspaceInfo(info);
+      verified = true;
+    } catch (err) {
+      verification = `Saved, but the connection test failed: ${(err as Error).message}`;
+    }
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Outline profile "${params.name}" saved and set as active (${config.url}).\n\n${verification}`,
+        },
+      ],
+      details: { profileName: params.name, url: config.url, verified },
+    };
+  },
+};

package/src/tools/outline-status.ts

@@ -0,0 +1,64 @@
+/**
+ * outline_status tool -- Show configuration status and verify the connection.
+ */
+
+import { Type } from "typebox";
+import { getProfiles, getActiveProfile, resolveConfig } from "../config.ts";
+import { getWorkspaceInfo, isTlsValidationDisabled } from "../clients/outline-client.ts";
+import { formatProfileStatus, formatWorkspaceInfo } from "../formatting/formatters.ts";
+
+export const OutlineStatusTool = {
+  name: "outline_status",
+  label: "Outline Status",
+  description:
+    "Show which Outline workspaces are configured and verify that the active API key still works.",
+  parameters: Type.Object({
+    profile: Type.Optional(
+      Type.String({ description: "Profile to verify. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { profile?: string },
+    signal: AbortSignal,
+  ) {
+    const allProfiles = getProfiles();
+    const active = getActiveProfile();
+    const overview = formatProfileStatus(allProfiles, active);
+
+    if (Object.keys(allProfiles).length === 0) {
+      return {
+        content: [{ type: "text" as const, text: overview }],
+        details: { configured: false, profileCount: 0, activeProfile: null },
+      };
+    }
+
+    let connection: string;
+    let reachable = false;
+    try {
+      const info = await getWorkspaceInfo(resolveConfig(params.profile), signal);
+      connection = formatWorkspaceInfo(info);
+      reachable = true;
+    } catch (err) {
+      connection = `Connection test failed: ${(err as Error).message}`;
+    }
+
+    const warning = isTlsValidationDisabled()
+      ? "\n\nWarning: TLS certificate validation is disabled in this pi process."
+      : "";
+
+    return {
+      content: [
+        { type: "text" as const, text: `${overview}\n\n${connection}${warning}` },
+      ],
+      details: {
+        configured: true,
+        profileCount: Object.keys(allProfiles).length,
+        activeProfile: active,
+        profiles: Object.keys(allProfiles),
+        reachable,
+      },
+    };
+  },
+};

package/src/tools/outline-structure.ts

@@ -0,0 +1,63 @@
+/**
+ * outline_structure tool -- Show the nested document tree of a collection.
+ *
+ * Cheaper and more useful than listing documents flat: it reveals how the
+ * wiki is organised, which is what you need before filing a new document.
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import { getCollectionStructure, listCollections } from "../clients/outline-client.ts";
+import { formatCollectionStructure } from "../formatting/formatters.ts";
+
+export const OutlineStructureTool = {
+  name: "outline_structure",
+  label: "Outline Collection Structure",
+  description:
+    "Show the nested document tree of one collection (titles and ids, parents and children). Use it to understand how a wiki section is organised before creating or moving documents.",
+  parameters: Type.Object({
+    collectionId: Type.String({
+      description: "Collection id. Get it from outline_collections.",
+    }),
+    profile: Type.Optional(
+      Type.String({ description: "Outline profile to use. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { collectionId: string; profile?: string },
+    signal: AbortSignal,
+  ) {
+    const config = resolveConfig(params.profile);
+    const nodes = await getCollectionStructure(config, params.collectionId, signal);
+
+    // The tree endpoint returns no collection name, so resolve it for output.
+    let collectionName: string | undefined;
+    try {
+      const { collections } = await listCollections(config, { limit: 100 }, signal);
+      collectionName = collections.find((c) => c.id === params.collectionId)?.name;
+    } catch {
+      /* naming is cosmetic -- never fail the call over it */
+    }
+
+    function countNodes(items: ReadonlyArray<{ children: ReadonlyArray<any> }>): number {
+      return items.reduce((total, node) => total + 1 + countNodes(node.children), 0);
+    }
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: formatCollectionStructure(nodes, collectionName),
+        },
+      ],
+      details: {
+        collectionId: params.collectionId,
+        collectionName,
+        topLevelCount: nodes.length,
+        totalCount: countNodes(nodes),
+      },
+    };
+  },
+};

package/src/tools/outline-update.ts

@@ -0,0 +1,106 @@
+/**
+ * outline_update tool -- Change an existing document.
+ *
+ * `replace` overwrites the body, so append/prepend exist to add to a page
+ * (changelog, decision log, FAQ) without having to read and re-send it.
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import { getDocument, updateDocument } from "../clients/outline-client.ts";
+import { formatDocumentSaved } from "../formatting/formatters.ts";
+
+const VALID_MODES = new Set(["replace", "append", "prepend"]);
+
+export const OutlineUpdateTool = {
+  name: "outline_update",
+  label: "Outline Update Document",
+  description:
+    "Update an existing document: replace the body, append or prepend a section, rename it, or publish a draft. Read the document first when replacing, so nothing is lost.",
+  parameters: Type.Object({
+    id: Type.String({ description: "Document id or urlId." }),
+    text: Type.Optional(Type.String({ description: "Markdown to write, append or prepend." })),
+    mode: Type.Optional(
+      Type.String({
+        description:
+          "How to apply text: replace (default, overwrites the whole body), append (add at the end), prepend (add at the top).",
+        default: "replace",
+      }),
+    ),
+    title: Type.Optional(Type.String({ description: "New title." })),
+    icon: Type.Optional(Type.String({ description: "New emoji or icon." })),
+    publish: Type.Optional(
+      Type.Boolean({ description: "Publish a draft document so others can see it." }),
+    ),
+    profile: Type.Optional(
+      Type.String({ description: "Outline profile to use. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: {
+      id: string;
+      text?: string;
+      mode?: string;
+      title?: string;
+      icon?: string;
+      publish?: boolean;
+      profile?: string;
+    },
+    signal: AbortSignal,
+  ) {
+    const mode = (params.mode ?? "replace").toLowerCase();
+    if (!VALID_MODES.has(mode)) {
+      throw new Error(`Invalid mode "${params.mode}". Use replace, append or prepend.`);
+    }
+    if (
+      params.text === undefined &&
+      params.title === undefined &&
+      params.icon === undefined &&
+      params.publish === undefined
+    ) {
+      throw new Error("Nothing to update: pass at least one of text, title, icon or publish.");
+    }
+
+    const config = resolveConfig(params.profile);
+
+    let text = params.text;
+    if (text !== undefined && mode !== "replace") {
+      const current = await getDocument(config, params.id, signal);
+      const existing = current.text ?? "";
+      text =
+        mode === "append"
+          ? `${existing.replace(/\s*$/, "")}\n\n${text}\n`
+          : `${text}\n\n${existing.replace(/^\s*/, "")}`;
+    }
+
+    const doc = await updateDocument(
+      config,
+      {
+        id: params.id,
+        text,
+        title: params.title,
+        icon: params.icon,
+        publish: params.publish,
+      },
+      signal,
+    );
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `${formatDocumentSaved(doc, "updated")}\nMode: ${mode}`,
+        },
+      ],
+      details: {
+        id: doc.id,
+        title: doc.title,
+        url: doc.url,
+        mode,
+        length: doc.text.length,
+      },
+    };
+  },
+};

package/src/types.ts

@@ -0,0 +1,169 @@
+/**
+ * Data types for the pi Outline Wiki extension.
+ *
+ * All domain data is represented as plain immutable-shaped interfaces.
+ * No behavior, no classes, no inheritance -- just data (errors excepted).
+ */
+
+// Configuration
+
+export interface OutlineConfig {
+  /**
+   * Workspace base URL without a trailing slash and without the `/api`
+   * suffix, e.g. `https://acme.getoutline.com` or `https://wiki.example.com`.
+   */
+  readonly url: string;
+  /** Personal API key, starts with `ol_api_`. */
+  readonly apiKey: string;
+  /**
+   * Skip TLS certificate validation. Only for self-hosted instances behind a
+   * self-signed certificate. Disables validation process-wide, so it is off
+   * unless explicitly requested.
+   */
+  readonly insecureTls?: boolean;
+}
+
+export interface OutlineProfiles {
+  readonly profiles: Record<string, OutlineConfig>;
+  readonly activeProfile: string | null;
+}
+
+// Domain
+
+export interface UserRef {
+  readonly id?: string;
+  readonly name?: string;
+  readonly email?: string;
+}
+
+export interface CollectionSummary {
+  readonly id: string;
+  readonly name: string;
+  readonly description?: string | null;
+  readonly icon?: string | null;
+  readonly color?: string | null;
+  readonly permission?: string | null;
+  readonly updatedAt?: string;
+}
+
+export interface DocumentSummary {
+  readonly id: string;
+  readonly urlId?: string;
+  readonly title: string;
+  readonly url?: string;
+  readonly icon?: string | null;
+  readonly collectionId?: string | null;
+  readonly parentDocumentId?: string | null;
+  readonly template?: boolean;
+  readonly fullWidth?: boolean;
+  readonly createdAt?: string;
+  readonly updatedAt?: string;
+  readonly archivedAt?: string | null;
+  readonly deletedAt?: string | null;
+  readonly publishedAt?: string | null;
+  readonly createdBy?: UserRef;
+  readonly updatedBy?: UserRef;
+}
+
+export interface DocumentDetail extends DocumentSummary {
+  /** Markdown body. */
+  readonly text: string;
+}
+
+export interface SearchHit {
+  readonly ranking?: number;
+  /** Snippet around the match, may contain markdown highlight markers. */
+  readonly context: string;
+  readonly document: DocumentSummary;
+}
+
+export interface NavigationNode {
+  readonly id: string;
+  readonly title: string;
+  readonly url?: string;
+  readonly children: ReadonlyArray<NavigationNode>;
+}
+
+export interface CommentEntry {
+  readonly id: string;
+  readonly documentId?: string;
+  readonly parentCommentId?: string | null;
+  /** Plain text flattened from the stored rich-text document. */
+  readonly text: string;
+  readonly createdAt?: string;
+  readonly updatedAt?: string;
+  readonly resolvedAt?: string | null;
+  readonly createdBy?: UserRef;
+}
+
+export interface WorkspaceInfo {
+  readonly userName?: string;
+  readonly userEmail?: string;
+  readonly teamName?: string;
+  readonly teamUrl?: string;
+}
+
+export interface Pagination {
+  readonly offset?: number;
+  readonly limit?: number;
+  readonly total?: number;
+  readonly nextPath?: string;
+}
+
+/** Envelope every Outline API method returns. */
+export interface OutlineResponse<T> {
+  readonly ok: boolean;
+  readonly data: T;
+  readonly pagination?: Pagination;
+  readonly status?: number;
+  readonly error?: string;
+  readonly message?: string;
+}
+
+// Tool parameter shapes
+
+export interface SetupParams {
+  readonly name: string;
+  readonly url: string;
+  readonly apiKey: string;
+  readonly insecureTls?: boolean;
+}
+
+// Errors
+
+export class OutlineNotConfiguredError extends Error {
+  constructor() {
+    super(
+      "Outline is not configured. Use the outline_setup tool first (workspace URL + API key).",
+    );
+    this.name = "OutlineNotConfiguredError";
+  }
+}
+
+export class OutlineApiError extends Error {
+  readonly method: string;
+  readonly status: number;
+  readonly code?: string;
+
+  constructor(method: string, status: number, message: string, code?: string) {
+    super(message);
+    this.name = "OutlineApiError";
+    this.method = method;
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export class OutlineNotFoundError extends Error {
+  constructor(what: string) {
+    super(`${what} not found. Check the id, or search for it with outline_search.`);
+    this.name = "OutlineNotFoundError";
+  }
+}
+
+export class UnsafeExportPathError extends Error {
+  constructor(target: string) {
+    super(`Refusing to write outside the target directory: ${target}`);
+    this.name = "UnsafeExportPathError";
+  }
+}