@patimweb/pi-outline-wiki 1.0.0

package/src/tools/outline-comments.ts

@@ -0,0 +1,52 @@
+/**
+ * outline_comments tool -- Read the discussion on a document.
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import { listComments } from "../clients/outline-client.ts";
+import { formatComments } from "../formatting/formatters.ts";
+
+export const OutlineCommentsTool = {
+  name: "outline_comments",
+  label: "Outline Read Comments",
+  description:
+    "Read the comment threads on a document, nested by reply. Useful for open questions and review feedback that never made it into the page body.",
+  parameters: Type.Object({
+    documentId: Type.String({ description: "Document id." }),
+    limit: Type.Optional(
+      Type.Number({ description: "How many comments to return. Default 50.", default: 50 }),
+    ),
+    offset: Type.Optional(
+      Type.Number({ description: "Pagination offset. Default 0.", default: 0 }),
+    ),
+    profile: Type.Optional(
+      Type.String({ description: "Outline profile to use. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { documentId: string; limit?: number; offset?: number; profile?: string },
+    signal: AbortSignal,
+  ) {
+    const config = resolveConfig(params.profile);
+    const { comments, pagination } = await listComments(
+      config,
+      { documentId: params.documentId, limit: params.limit, offset: params.offset },
+      signal,
+    );
+
+    return {
+      content: [
+        { type: "text" as const, text: formatComments(comments, params.documentId) },
+      ],
+      details: {
+        documentId: params.documentId,
+        count: comments.length,
+        unresolved: comments.filter((c) => !c.resolvedAt).length,
+        pagination,
+      },
+    };
+  },
+};

package/src/tools/outline-create.ts

@@ -0,0 +1,99 @@
+/**
+ * outline_create tool -- Create a new wiki document.
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import { createDocument } from "../clients/outline-client.ts";
+import { formatDocumentSaved } from "../formatting/formatters.ts";
+
+export const OutlineCreateTool = {
+  name: "outline_create",
+  label: "Outline Create Document",
+  description:
+    "Create a new document in the Outline wiki from markdown. Give either a collectionId (top level of that collection) or a parentDocumentId (nested under an existing page). Search first -- updating an existing page is usually better than adding a near-duplicate.",
+  parameters: Type.Object({
+    title: Type.String({ description: "Document title. Keep it specific and searchable." }),
+    text: Type.Optional(
+      Type.String({
+        description:
+          "Markdown body. Do not repeat the title as a top-level heading; Outline renders the title separately.",
+      }),
+    ),
+    collectionId: Type.Optional(
+      Type.String({
+        description: "Collection to create the document in. Required unless parentDocumentId is given.",
+      }),
+    ),
+    parentDocumentId: Type.Optional(
+      Type.String({ description: "Create the document as a child of this document." }),
+    ),
+    templateId: Type.Optional(
+      Type.String({ description: "Create the document from this template." }),
+    ),
+    icon: Type.Optional(
+      Type.String({ description: "Emoji or icon name shown next to the title." }),
+    ),
+    publish: Type.Optional(
+      Type.Boolean({
+        description:
+          "Publish immediately so others can see it. Default true. Set false to keep it as a personal draft.",
+        default: true,
+      }),
+    ),
+    profile: Type.Optional(
+      Type.String({ description: "Outline profile to use. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: {
+      title: string;
+      text?: string;
+      collectionId?: string;
+      parentDocumentId?: string;
+      templateId?: string;
+      icon?: string;
+      publish?: boolean;
+      profile?: string;
+    },
+    signal: AbortSignal,
+  ) {
+    if (!params.title || !params.title.trim()) {
+      throw new Error("title must not be empty.");
+    }
+    const publish = params.publish ?? true;
+    if (publish && !params.collectionId && !params.parentDocumentId) {
+      throw new Error(
+        "A published document needs a collectionId or a parentDocumentId. List collections with outline_collections, or pass publish: false to create a draft.",
+      );
+    }
+
+    const config = resolveConfig(params.profile);
+    const doc = await createDocument(
+      config,
+      {
+        title: params.title.trim(),
+        text: params.text ?? "",
+        collectionId: params.collectionId,
+        parentDocumentId: params.parentDocumentId,
+        templateId: params.templateId,
+        icon: params.icon,
+        publish,
+      },
+      signal,
+    );
+
+    return {
+      content: [{ type: "text" as const, text: formatDocumentSaved(doc, "created") }],
+      details: {
+        id: doc.id,
+        title: doc.title,
+        url: doc.url,
+        collectionId: doc.collectionId,
+        published: Boolean(doc.publishedAt),
+      },
+    };
+  },
+};

package/src/tools/outline-delete.ts

@@ -0,0 +1,60 @@
+/**
+ * outline_delete tool -- Move a document to the trash, or erase it.
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import { documentLifecycle, getDocument } from "../clients/outline-client.ts";
+
+export const OutlineDeleteTool = {
+  name: "outline_delete",
+  label: "Outline Delete Document",
+  description:
+    "Move a document to the Outline trash, where it can be restored with outline_archive action 'restore'. With permanent: true it is erased and cannot be recovered -- only do that when explicitly asked. Prefer archiving over deleting.",
+  parameters: Type.Object({
+    id: Type.String({ description: "Document id." }),
+    permanent: Type.Optional(
+      Type.Boolean({
+        description:
+          "Erase the document instead of moving it to the trash. Irreversible. Default false.",
+        default: false,
+      }),
+    ),
+    profile: Type.Optional(
+      Type.String({ description: "Outline profile to use. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { id: string; permanent?: boolean; profile?: string },
+    signal: AbortSignal,
+  ) {
+    const config = resolveConfig(params.profile);
+
+    // Resolve the title before deletion so the confirmation names the page
+    // rather than a bare uuid.
+    let title = params.id;
+    try {
+      title = (await getDocument(config, params.id, signal)).title;
+    } catch {
+      /* the delete call below reports a real failure */
+    }
+
+    await documentLifecycle(
+      config,
+      "delete",
+      { id: params.id, permanent: params.permanent },
+      signal,
+    );
+
+    const text = params.permanent
+      ? `Permanently deleted "${title}" (${params.id}). This cannot be undone.`
+      : `Moved "${title}" (${params.id}) to the trash. Restore it with outline_archive action "restore".`;
+
+    return {
+      content: [{ type: "text" as const, text }],
+      details: { id: params.id, title, permanent: Boolean(params.permanent) },
+    };
+  },
+};

package/src/tools/outline-export.ts

@@ -0,0 +1,146 @@
+/**
+ * outline_export tool -- Save wiki documents to local markdown files.
+ *
+ * The point is to get wiki knowledge into the repository the agent is working
+ * in (docs/, ADRs, onboarding notes) without copying text through the model.
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import {
+  exportDocument,
+  getCollectionStructure,
+  getDocument,
+  slugifyTitle,
+  writeMarkdownFile,
+} from "../clients/outline-client.ts";
+import type { NavigationNode } from "../types.ts";
+
+function flatten(nodes: ReadonlyArray<NavigationNode>, out: NavigationNode[] = []): NavigationNode[] {
+  for (const node of nodes) {
+    out.push(node);
+    flatten(node.children, out);
+  }
+  return out;
+}
+
+export const OutlineExportTool = {
+  name: "outline_export",
+  label: "Outline Export to Files",
+  description:
+    "Export one document (optionally with its children) or a whole collection to local markdown files. Use it to pull wiki content into a repository instead of reading every page through the model.",
+  parameters: Type.Object({
+    targetDir: Type.String({
+      description: "Directory to write the .md files into. Absolute paths are safest.",
+    }),
+    documentId: Type.Optional(
+      Type.String({ description: "Document to export. Mutually exclusive with collectionId." }),
+    ),
+    collectionId: Type.Optional(
+      Type.String({ description: "Export every document of this collection." }),
+    ),
+    includeChildren: Type.Optional(
+      Type.Boolean({
+        description: "With documentId: also export nested child documents. Default false.",
+        default: false,
+      }),
+    ),
+    limit: Type.Optional(
+      Type.Number({
+        description: "Maximum number of documents to write. Default 50.",
+        default: 50,
+      }),
+    ),
+    profile: Type.Optional(
+      Type.String({ description: "Outline profile to use. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: {
+      targetDir: string;
+      documentId?: string;
+      collectionId?: string;
+      includeChildren?: boolean;
+      limit?: number;
+      profile?: string;
+    },
+    signal: AbortSignal,
+  ) {
+    if (!params.documentId && !params.collectionId) {
+      throw new Error("Pass either documentId or collectionId.");
+    }
+    if (params.documentId && params.collectionId) {
+      throw new Error("Pass documentId or collectionId, not both.");
+    }
+
+    const config = resolveConfig(params.profile);
+    const limit = params.limit ?? 50;
+    const targets: Array<{ id: string; title: string }> = [];
+
+    if (params.collectionId) {
+      const tree = await getCollectionStructure(config, params.collectionId, signal);
+      for (const node of flatten(tree)) {
+        targets.push({ id: node.id, title: node.title });
+      }
+    } else {
+      const doc = await getDocument(config, params.documentId!, signal);
+      targets.push({ id: doc.id, title: doc.title });
+      if (params.includeChildren && doc.collectionId) {
+        const tree = await getCollectionStructure(config, doc.collectionId, signal);
+        const self = flatten(tree).find((node) => node.id === doc.id);
+        if (self) {
+          for (const child of flatten(self.children)) {
+            targets.push({ id: child.id, title: child.title });
+          }
+        }
+      }
+    }
+
+    const capped = targets.slice(0, limit);
+    const written: string[] = [];
+    const failed: Array<{ id: string; error: string }> = [];
+    const usedNames = new Set<string>();
+
+    for (const target of capped) {
+      try {
+        const markdown = await exportDocument(config, target.id, signal);
+        let stem = slugifyTitle(target.title);
+        // Wikis are full of pages called "Overview"; keep every file.
+        if (usedNames.has(stem)) stem = `${stem}-${target.id.slice(0, 8)}`;
+        usedNames.add(stem);
+        written.push(writeMarkdownFile(params.targetDir, `${stem}.md`, markdown));
+      } catch (err) {
+        failed.push({ id: target.id, error: (err as Error).message });
+      }
+    }
+
+    const lines = [
+      `Exported ${written.length} document(s) to ${params.targetDir}:`,
+      ...written.map((file) => `- ${file}`),
+    ];
+    if (targets.length > capped.length) {
+      lines.push(
+        `\n${targets.length - capped.length} more document(s) not exported (limit ${limit}).`,
+      );
+    }
+    if (failed.length > 0) {
+      lines.push(
+        `\n${failed.length} document(s) failed:`,
+        ...failed.map((f) => `- ${f.id}: ${f.error}`),
+      );
+    }
+
+    return {
+      content: [{ type: "text" as const, text: lines.join("\n") }],
+      details: {
+        targetDir: params.targetDir,
+        written,
+        writtenCount: written.length,
+        failedCount: failed.length,
+        skipped: targets.length - capped.length,
+      },
+    };
+  },
+};

package/src/tools/outline-list.ts

@@ -0,0 +1,110 @@
+/**
+ * outline_list tool -- Browse documents without searching.
+ *
+ * Useful for "what changed recently", "what is in this collection" and
+ * "what are my unpublished drafts".
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import { listDocuments } from "../clients/outline-client.ts";
+import { formatDocumentList } from "../formatting/formatters.ts";
+
+const VALID_SORT = new Set(["updatedAt", "createdAt", "title", "index"]);
+
+export const OutlineListTool = {
+  name: "outline_list",
+  label: "Outline List Documents",
+  description:
+    "List documents without a search query -- most recently updated first by default. Filter by collection, by parent document, or list your own drafts. Use outline_search when you know what you are looking for.",
+  parameters: Type.Object({
+    collectionId: Type.Optional(
+      Type.String({ description: "Only documents in this collection." }),
+    ),
+    parentDocumentId: Type.Optional(
+      Type.String({ description: "Only direct children of this document." }),
+    ),
+    drafts: Type.Optional(
+      Type.Boolean({
+        description: "List unpublished drafts of the authenticated user instead.",
+        default: false,
+      }),
+    ),
+    limit: Type.Optional(
+      Type.Number({ description: "How many documents to return. Default 25.", default: 25 }),
+    ),
+    offset: Type.Optional(
+      Type.Number({ description: "Pagination offset. Default 0.", default: 0 }),
+    ),
+    sort: Type.Optional(
+      Type.String({
+        description: "Sort field: updatedAt (default), createdAt, title or index.",
+      }),
+    ),
+    direction: Type.Optional(
+      Type.String({ description: "ASC or DESC. Default DESC.", default: "DESC" }),
+    ),
+    profile: Type.Optional(
+      Type.String({ description: "Outline profile to use. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: {
+      collectionId?: string;
+      parentDocumentId?: string;
+      drafts?: boolean;
+      limit?: number;
+      offset?: number;
+      sort?: string;
+      direction?: string;
+      profile?: string;
+    },
+    signal: AbortSignal,
+  ) {
+    if (params.sort && !VALID_SORT.has(params.sort)) {
+      throw new Error(
+        `Invalid sort "${params.sort}". Use updatedAt, createdAt, title or index.`,
+      );
+    }
+    const direction = (params.direction ?? "DESC").toUpperCase();
+    if (direction !== "ASC" && direction !== "DESC") {
+      throw new Error(`Invalid direction "${params.direction}". Use ASC or DESC.`);
+    }
+
+    const config = resolveConfig(params.profile);
+    const { documents, pagination } = await listDocuments(
+      config,
+      {
+        collectionId: params.collectionId,
+        parentDocumentId: params.parentDocumentId,
+        drafts: params.drafts,
+        limit: params.limit,
+        offset: params.offset,
+        sort: params.sort,
+        direction,
+      },
+      signal,
+    );
+
+    const heading = params.drafts
+      ? "Drafts"
+      : params.parentDocumentId
+        ? `Children of ${params.parentDocumentId}`
+        : params.collectionId
+          ? `Documents in collection ${params.collectionId}`
+          : "Recently updated documents";
+
+    return {
+      content: [
+        { type: "text" as const, text: formatDocumentList(documents, heading, pagination) },
+      ],
+      details: {
+        count: documents.length,
+        documents: documents.map((doc) => ({ id: doc.id, title: doc.title })),
+        pagination,
+      },
+    };
+  },
+};

package/src/tools/outline-move.ts

@@ -0,0 +1,99 @@
+/**
+ * outline_move tool -- Re-file a document within the wiki.
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import { getDocument, moveDocument } from "../clients/outline-client.ts";
+
+export const OutlineMoveTool = {
+  name: "outline_move",
+  label: "Outline Move Document",
+  description:
+    "Move a document into another collection or under another parent document. Child documents move with it. Pass toTopLevel to lift a nested document to the root of its collection.",
+  parameters: Type.Object({
+    id: Type.String({ description: "Document id to move." }),
+    collectionId: Type.Optional(
+      Type.String({ description: "Target collection id." }),
+    ),
+    parentDocumentId: Type.Optional(
+      Type.String({ description: "Target parent document id (nests the document under it)." }),
+    ),
+    toTopLevel: Type.Optional(
+      Type.Boolean({
+        description: "Detach from the current parent and place at the collection root.",
+        default: false,
+      }),
+    ),
+    index: Type.Optional(
+      Type.Number({ description: "Position among its new siblings (0 = first)." }),
+    ),
+    profile: Type.Optional(
+      Type.String({ description: "Outline profile to use. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: {
+      id: string;
+      collectionId?: string;
+      parentDocumentId?: string;
+      toTopLevel?: boolean;
+      index?: number;
+      profile?: string;
+    },
+    signal: AbortSignal,
+  ) {
+    if (!params.collectionId && !params.parentDocumentId && !params.toTopLevel) {
+      throw new Error(
+        "Specify a target: collectionId, parentDocumentId, or toTopLevel: true.",
+      );
+    }
+    if (params.parentDocumentId && params.toTopLevel) {
+      throw new Error("parentDocumentId and toTopLevel contradict each other.");
+    }
+
+    const config = resolveConfig(params.profile);
+
+    // documents.move needs a collection when the parent is cleared, so fall
+    // back to the document's current one.
+    let collectionId = params.collectionId;
+    if (!collectionId && params.toTopLevel) {
+      const current = await getDocument(config, params.id, signal);
+      collectionId = current.collectionId ?? undefined;
+    }
+
+    const { documentCount } = await moveDocument(
+      config,
+      {
+        id: params.id,
+        collectionId,
+        parentDocumentId: params.toTopLevel ? null : params.parentDocumentId,
+        index: params.index,
+      },
+      signal,
+    );
+
+    const target = params.toTopLevel
+      ? `the root of collection ${collectionId}`
+      : params.parentDocumentId
+        ? `under document ${params.parentDocumentId}`
+        : `collection ${collectionId}`;
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Moved document ${params.id} to ${target}. ${documentCount} document(s) affected.`,
+        },
+      ],
+      details: {
+        id: params.id,
+        collectionId,
+        parentDocumentId: params.toTopLevel ? null : params.parentDocumentId,
+        documentCount,
+      },
+    };
+  },
+};

package/src/tools/outline-profile.ts

@@ -0,0 +1,82 @@
+/**
+ * outline_profile tool -- List, switch or delete configured workspaces.
+ */
+
+import { Type } from "typebox";
+import {
+  deleteProfile,
+  getActiveProfile,
+  getProfiles,
+  setActiveProfile,
+} from "../config.ts";
+import { formatProfileStatus } from "../formatting/formatters.ts";
+
+export const OutlineProfileTool = {
+  name: "outline_profile",
+  label: "Manage Outline Profiles",
+  description:
+    "List configured Outline workspace profiles, switch the active one, or delete a profile. Without arguments it lists all profiles.",
+  parameters: Type.Object({
+    action: Type.Optional(
+      Type.String({ description: "One of: list, use, delete. Defaults to list." }),
+    ),
+    name: Type.Optional(
+      Type.String({ description: "Profile name for 'use' and 'delete'." }),
+    ),
+  }),
+
+  execute(
+    _toolCallId: string,
+    params: { action?: string; name?: string },
+    _signal: AbortSignal,
+  ) {
+    const action = (params.action || "list").toLowerCase();
+
+    if (action === "list") {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: formatProfileStatus(getProfiles(), getActiveProfile()),
+          },
+        ],
+        details: {
+          profiles: Object.keys(getProfiles()),
+          activeProfile: getActiveProfile(),
+        },
+      };
+    }
+
+    if (!params.name) {
+      throw new Error(`The "${action}" action requires a profile name.`);
+    }
+
+    if (action === "use") {
+      setActiveProfile(params.name);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Active Outline profile is now "${params.name}".`,
+          },
+        ],
+        details: { activeProfile: params.name },
+      };
+    }
+
+    if (action === "delete") {
+      const removed = deleteProfile(params.name);
+      const text = removed
+        ? `Profile "${params.name}" deleted. Active profile is now ${getActiveProfile() ? `"${getActiveProfile()}"` : "unset"}.`
+        : `No profile named "${params.name}".`;
+      return {
+        content: [{ type: "text" as const, text }],
+        details: { deleted: removed, activeProfile: getActiveProfile() },
+      };
+    }
+
+    throw new Error(
+      `Unknown action "${params.action}". Use one of: list, use, delete.`,
+    );
+  },
+};