@patimweb/pi-outline-wiki 1.0.0

package/src/config.ts

@@ -0,0 +1,218 @@
+/**
+ * Configuration persistence and state.
+ *
+ * Stores named Outline workspace profiles in ~/.pi/outline-config.json.
+ * Supports multiple profiles with an active profile selector.
+ *
+ * File format:
+ *   { "profiles": { "name": OutlineConfig, ... }, "activeProfile": "name" }
+ *
+ * Backward-compatible: a flat { url, apiKey } object is migrated to
+ * { profiles: { "default": ... }, activeProfile: "default" }.
+ */
+
+import type { OutlineConfig, OutlineProfiles } from "./types.ts";
+import { OutlineNotConfiguredError } from "./types.ts";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// Mutable state
+
+let profiles: Record<string, OutlineConfig> = {};
+let activeProfile: string | null = null;
+
+// Path resolution
+
+function configPath(): string {
+  const home = process.env.HOME || process.env.USERPROFILE || "~";
+  return path.join(home, ".pi", "outline-config.json");
+}
+
+// URL normalisation
+
+/**
+ * Accepts what people actually paste: a bare host, a URL with a trailing
+ * slash, the `/api` base, or the `/mcp` endpoint from Outline's MCP docs.
+ * Returns the workspace root without a trailing slash.
+ */
+export function normalizeBaseUrl(raw: string): string {
+  let url = String(raw ?? "").trim();
+  if (!url) {
+    throw new Error("Workspace URL must not be empty.");
+  }
+  if (!/^https?:\/\//i.test(url)) {
+    url = `https://${url}`;
+  }
+  url = url.replace(/\/+$/, "");
+  url = url.replace(/\/(api|mcp)$/i, "");
+  url = url.replace(/\/+$/, "");
+
+  try {
+    // Throws on malformed input, so setup fails loudly instead of at call time.
+    new URL(url);
+  } catch {
+    throw new Error(`"${raw}" is not a valid workspace URL.`);
+  }
+  return url;
+}
+
+// Persistence
+
+/**
+ * Write the profile store.
+ *
+ * The file holds a plaintext API key, so it must never be group- or
+ * world-readable. writeFileSync's `mode` only applies when the file is
+ * created, so an existing file keeps its old (possibly 0644) permissions --
+ * we therefore write to a private temp file and rename it into place. That
+ * is also atomic, so a crash mid-write cannot truncate the config.
+ */
+function persistProfiles(): void {
+  const filePath = configPath();
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+
+  const data: OutlineProfiles = { profiles, activeProfile };
+  const tmpPath = `${filePath}.${process.pid}.tmp`;
+
+  try {
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), {
+      encoding: "utf-8",
+      mode: 0o600,
+    });
+    fs.chmodSync(tmpPath, 0o600);
+    fs.renameSync(tmpPath, filePath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch {
+      /* ignore */
+    }
+    throw err;
+  }
+}
+
+export function loadConfig(): void {
+  try {
+    const filePath = configPath();
+    if (!fs.existsSync(filePath)) {
+      profiles = {};
+      activeProfile = null;
+      return;
+    }
+
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+
+    // Tighten permissions on config files written by older versions.
+    try {
+      const mode = fs.statSync(filePath).mode & 0o777;
+      if (mode !== 0o600) fs.chmodSync(filePath, 0o600);
+    } catch {
+      /* ignore */
+    }
+
+    if (raw && typeof raw === "object" && raw.apiKey && !("profiles" in raw)) {
+      profiles = { default: raw as OutlineConfig };
+      activeProfile = "default";
+      persistProfiles();
+      return;
+    }
+
+    if (raw && typeof raw === "object" && raw.profiles) {
+      profiles = raw.profiles;
+      if (raw.activeProfile && profiles[raw.activeProfile]) {
+        activeProfile = raw.activeProfile;
+      } else if (Object.keys(profiles).length > 0) {
+        activeProfile = Object.keys(profiles)[0];
+      } else {
+        activeProfile = null;
+      }
+    }
+  } catch {
+    profiles = {};
+    activeProfile = null;
+  }
+}
+
+// Access
+
+export function getConfig(): OutlineConfig | null {
+  if (!activeProfile) return null;
+  return profiles[activeProfile] ?? null;
+}
+
+export function getConfigOrThrow(): OutlineConfig {
+  const config = getConfig();
+  if (!config) {
+    throw new OutlineNotConfiguredError();
+  }
+  return config;
+}
+
+export function getProfile(name: string): OutlineConfig | null {
+  return profiles[name] ?? null;
+}
+
+/**
+ * Resolve a profile parameter: if a name is given, return that profile
+ * (or throw if not found). Otherwise, return the active profile or throw.
+ */
+export function resolveConfig(profileName?: string): OutlineConfig {
+  if (profileName) {
+    const config = getProfile(profileName);
+    if (!config) {
+      throw new Error(
+        `Profile "${profileName}" not found. Available: ${Object.keys(profiles).join(", ") || "none"}`,
+      );
+    }
+    return config;
+  }
+  return getConfigOrThrow();
+}
+
+export function getProfiles(): Record<string, OutlineConfig> {
+  return { ...profiles };
+}
+
+export function getActiveProfile(): string | null {
+  return activeProfile;
+}
+
+// Mutations
+
+export function saveProfile(name: string, config: OutlineConfig): void {
+  profiles[name] = { ...config, url: normalizeBaseUrl(config.url) };
+  if (!activeProfile || Object.keys(profiles).length === 1) {
+    activeProfile = name;
+  }
+  persistProfiles();
+}
+
+export function setActiveProfile(name: string): void {
+  if (!profiles[name]) {
+    throw new Error(
+      `Profile "${name}" does not exist. Available: ${Object.keys(profiles).join(", ") || "none"}`,
+    );
+  }
+  activeProfile = name;
+  persistProfiles();
+}
+
+export function deleteProfile(name: string): boolean {
+  if (!profiles[name]) return false;
+  delete profiles[name];
+  if (activeProfile === name) {
+    const keys = Object.keys(profiles);
+    activeProfile = keys.length > 0 ? keys[0] : null;
+  }
+  persistProfiles();
+  return true;
+}
+
+/** @internal Reset state -- for testing only */
+export function _resetForTesting(): void {
+  profiles = {};
+  activeProfile = null;
+}

package/src/formatting/formatters.ts

@@ -0,0 +1,258 @@
+/**
+ * Output formatters.
+ *
+ * Pure functions that transform domain data into display strings.
+ * No emojis, no side effects.
+ */
+
+import type {
+  CollectionSummary,
+  CommentEntry,
+  DocumentDetail,
+  DocumentSummary,
+  NavigationNode,
+  OutlineConfig,
+  Pagination,
+  SearchHit,
+  WorkspaceInfo,
+} from "../types.ts";
+
+/** Show only the last four characters of an API key. */
+export function maskApiKey(apiKey: string): string {
+  if (!apiKey) return "(none)";
+  if (apiKey.length <= 8) return "****";
+  return `${apiKey.slice(0, 7)}...${apiKey.slice(-4)}`;
+}
+
+function shortDate(value?: string | null): string {
+  if (!value) return "-";
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return String(value);
+  return date.toISOString().slice(0, 16).replace("T", " ");
+}
+
+function statusMarkers(doc: DocumentSummary): string {
+  const markers: string[] = [];
+  if (doc.deletedAt) markers.push("trashed");
+  else if (doc.archivedAt) markers.push("archived");
+  else if (!doc.publishedAt) markers.push("draft");
+  if (doc.template) markers.push("template");
+  return markers.length > 0 ? ` [${markers.join(",")}]` : "";
+}
+
+function paginationNote(pagination?: Pagination, shown = 0): string {
+  if (!pagination) return "";
+  const offset = pagination.offset ?? 0;
+  const limit = pagination.limit ?? shown;
+  if (shown < limit) return "";
+  return `\n\nMore results may exist. Re-run with offset ${offset + limit}.`;
+}
+
+// Profiles
+
+export function formatProfileStatus(
+  profiles: Record<string, OutlineConfig>,
+  active: string | null,
+): string {
+  const names = Object.keys(profiles);
+  if (names.length === 0) {
+    return "No Outline workspace configured. Use outline_setup with your workspace URL and an API key from Settings -> API & Apps.";
+  }
+
+  const lines = names.map((name) => {
+    const config = profiles[name];
+    const marker = name === active ? "*" : " ";
+    const insecure = config.insecureTls ? " (TLS validation off)" : "";
+    return `${marker} ${name}: ${config.url} key ${maskApiKey(config.apiKey)}${insecure}`;
+  });
+
+  return [
+    `Outline profiles (${names.length}), * marks the active one:`,
+    ...lines,
+  ].join("\n");
+}
+
+export function formatWorkspaceInfo(info: WorkspaceInfo): string {
+  const lines = [
+    `Workspace: ${info.teamName ?? "(unknown)"}`,
+    `URL: ${info.teamUrl ?? "(unknown)"}`,
+    `Authenticated as: ${info.userName ?? "(unknown)"}${info.userEmail ? ` <${info.userEmail}>` : ""}`,
+  ];
+  return lines.join("\n");
+}
+
+// Collections
+
+export function formatCollectionList(
+  collections: ReadonlyArray<CollectionSummary>,
+): string {
+  if (collections.length === 0) {
+    return "No collections found. The API key's user may not be a member of any collection.";
+  }
+
+  const lines = collections.map((collection) => {
+    const description = collection.description
+      ? ` -- ${collection.description.replace(/\s+/g, " ").slice(0, 100)}`
+      : "";
+    return `- ${collection.name} (id ${collection.id})${description}`;
+  });
+
+  return [`Collections (${collections.length}):`, ...lines].join("\n");
+}
+
+export function formatCollectionStructure(
+  nodes: ReadonlyArray<NavigationNode>,
+  collectionName?: string,
+): string {
+  if (nodes.length === 0) {
+    return `Collection ${collectionName ?? ""} has no documents.`.trim();
+  }
+
+  const lines: string[] = [];
+  function walk(items: ReadonlyArray<NavigationNode>, indent: string): void {
+    for (const node of items) {
+      lines.push(`${indent}- ${node.title} (id ${node.id})`);
+      if (node.children.length > 0) {
+        walk(node.children, `${indent}  `);
+      }
+    }
+  }
+  walk(nodes, "");
+
+  const header = collectionName
+    ? `Document tree of "${collectionName}":`
+    : "Document tree:";
+  return [header, ...lines].join("\n");
+}
+
+// Documents
+
+export function formatDocumentList(
+  documents: ReadonlyArray<DocumentSummary>,
+  heading: string,
+  pagination?: Pagination,
+): string {
+  if (documents.length === 0) {
+    return `${heading}: nothing found.`;
+  }
+
+  const lines = documents.map((doc) => {
+    const author = doc.updatedBy?.name ? ` by ${doc.updatedBy.name}` : "";
+    return `- ${doc.title}${statusMarkers(doc)}\n  id ${doc.id} | updated ${shortDate(doc.updatedAt)}${author}`;
+  });
+
+  return (
+    `${heading} (${documents.length}):\n` +
+    lines.join("\n") +
+    paginationNote(pagination, documents.length)
+  );
+}
+
+export function formatSearchResults(
+  hits: ReadonlyArray<SearchHit>,
+  query: string,
+  pagination?: Pagination,
+): string {
+  if (hits.length === 0) {
+    return `No documents match "${query}". Try fewer or more general keywords, or drop the collection filter.`;
+  }
+
+  const lines = hits.map((hit, index) => {
+    const context = hit.context.replace(/\s+/g, " ").trim();
+    return [
+      `${index + 1}. ${hit.document.title}${statusMarkers(hit.document)}`,
+      `   id ${hit.document.id} | updated ${shortDate(hit.document.updatedAt)}`,
+      context ? `   ${context.slice(0, 300)}` : "",
+    ]
+      .filter(Boolean)
+      .join("\n");
+  });
+
+  return (
+    `Search "${query}" -- ${hits.length} result(s). Read one with outline_read.\n` +
+    lines.join("\n") +
+    paginationNote(pagination, hits.length)
+  );
+}
+
+export function formatDocument(
+  doc: DocumentDetail,
+  options: { maxChars?: number } = {},
+): string {
+  const maxChars = options.maxChars ?? 0;
+  let body = doc.text || "(this document has no content yet)";
+  let truncated = false;
+
+  if (maxChars > 0 && body.length > maxChars) {
+    body = body.slice(0, maxChars);
+    truncated = true;
+  }
+
+  const header = [
+    `Title: ${doc.title}${statusMarkers(doc)}`,
+    `Id: ${doc.id}`,
+    doc.collectionId ? `Collection: ${doc.collectionId}` : "",
+    doc.parentDocumentId ? `Parent document: ${doc.parentDocumentId}` : "",
+    doc.url ? `URL: ${doc.url}` : "",
+    `Updated: ${shortDate(doc.updatedAt)}${doc.updatedBy?.name ? ` by ${doc.updatedBy.name}` : ""}`,
+  ].filter(Boolean);
+
+  const footer = truncated
+    ? `\n\n[truncated after ${maxChars} characters -- re-run outline_read with a larger maxChars to see the rest]`
+    : "";
+
+  return `${header.join("\n")}\n\n---\n\n${body}${footer}`;
+}
+
+export function formatDocumentSaved(
+  doc: DocumentSummary,
+  action: "created" | "updated",
+): string {
+  const state = doc.publishedAt ? "published" : "draft";
+  return [
+    `Document ${action} (${state}): ${doc.title}`,
+    `Id: ${doc.id}`,
+    doc.url ? `URL: ${doc.url}` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+// Comments
+
+export function formatComments(
+  comments: ReadonlyArray<CommentEntry>,
+  documentId: string,
+): string {
+  if (comments.length === 0) {
+    return `No comments on document ${documentId}.`;
+  }
+
+  const byParent = new Map<string, CommentEntry[]>();
+  const roots: CommentEntry[] = [];
+  for (const comment of comments) {
+    if (comment.parentCommentId) {
+      const siblings = byParent.get(comment.parentCommentId) ?? [];
+      siblings.push(comment);
+      byParent.set(comment.parentCommentId, siblings);
+    } else {
+      roots.push(comment);
+    }
+  }
+
+  const lines: string[] = [];
+  function render(entry: CommentEntry, indent: string): void {
+    const author = entry.createdBy?.name ?? "unknown";
+    const resolved = entry.resolvedAt ? " [resolved]" : "";
+    lines.push(`${indent}- ${author} at ${shortDate(entry.createdAt)}${resolved} (id ${entry.id})`);
+    for (const line of (entry.text || "(empty)").split("\n")) {
+      lines.push(`${indent}  ${line}`);
+    }
+    for (const child of byParent.get(entry.id) ?? []) {
+      render(child, `${indent}  `);
+    }
+  }
+  for (const root of roots) render(root, "");
+
+  return [`Comments on document ${documentId} (${comments.length}):`, ...lines].join("\n");
+}

package/src/tools/outline-archive.ts

@@ -0,0 +1,70 @@
+/**
+ * outline_archive tool -- Archive, restore or unpublish a document.
+ *
+ * Archiving is the reversible way to retire a wiki page: it disappears from
+ * the collection but stays searchable in the archive.
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import { documentLifecycle } from "../clients/outline-client.ts";
+
+const ACTIONS: Record<string, "archive" | "restore" | "unpublish"> = {
+  archive: "archive",
+  restore: "restore",
+  unarchive: "restore",
+  unpublish: "unpublish",
+};
+
+export const OutlineArchiveTool = {
+  name: "outline_archive",
+  label: "Outline Archive Document",
+  description:
+    "Archive a document (reversible, keeps it out of the collection), restore an archived or trashed document, or unpublish a document back into a draft. Use outline_delete only when the page should really go away.",
+  parameters: Type.Object({
+    id: Type.String({ description: "Document id." }),
+    action: Type.Optional(
+      Type.String({
+        description: "One of: archive (default), restore, unpublish.",
+        default: "archive",
+      }),
+    ),
+    profile: Type.Optional(
+      Type.String({ description: "Outline profile to use. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { id: string; action?: string; profile?: string },
+    signal: AbortSignal,
+  ) {
+    const requested = (params.action ?? "archive").toLowerCase();
+    const action = ACTIONS[requested];
+    if (!action) {
+      throw new Error(
+        `Unknown action "${params.action}". Use archive, restore or unpublish.`,
+      );
+    }
+
+    const config = resolveConfig(params.profile);
+    const doc = await documentLifecycle(config, action, { id: params.id }, signal);
+
+    const done =
+      action === "archive"
+        ? "archived"
+        : action === "restore"
+          ? "restored"
+          : "unpublished (now a draft)";
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Document ${doc?.title ?? params.id} ${done}.\nId: ${doc?.id ?? params.id}`,
+        },
+      ],
+      details: { id: doc?.id ?? params.id, action, title: doc?.title },
+    };
+  },
+};

package/src/tools/outline-collections.ts

@@ -0,0 +1,52 @@
+/**
+ * outline_collections tool -- List the collections of the workspace.
+ *
+ * Collections are the top level of an Outline wiki; every published document
+ * lives in exactly one. Most write tools need a collectionId, so this is
+ * usually the first read call in a session.
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import { listCollections } from "../clients/outline-client.ts";
+import { formatCollectionList } from "../formatting/formatters.ts";
+
+export const OutlineCollectionsTool = {
+  name: "outline_collections",
+  label: "Outline Collections",
+  description:
+    "List the collections (top-level sections) of the Outline workspace with their ids. Use this to find the collectionId needed by outline_create, outline_search filters and outline_structure.",
+  parameters: Type.Object({
+    limit: Type.Optional(
+      Type.Number({ description: "How many collections 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: { limit?: number; offset?: number; profile?: string },
+    signal: AbortSignal,
+  ) {
+    const config = resolveConfig(params.profile);
+    const { collections, pagination } = await listCollections(
+      config,
+      { limit: params.limit, offset: params.offset },
+      signal,
+    );
+
+    return {
+      content: [{ type: "text" as const, text: formatCollectionList(collections) }],
+      details: {
+        count: collections.length,
+        collections: collections.map((c) => ({ id: c.id, name: c.name })),
+        pagination,
+      },
+    };
+  },
+};

package/src/tools/outline-comment.ts

@@ -0,0 +1,65 @@
+/**
+ * outline_comment tool -- Post a comment or a reply on a document.
+ */
+
+import { Type } from "typebox";
+import { resolveConfig } from "../config.ts";
+import { createComment } from "../clients/outline-client.ts";
+
+export const OutlineCommentTool = {
+  name: "outline_comment",
+  label: "Outline Post Comment",
+  description:
+    "Post a comment on a document, or reply to an existing comment thread. Use this to leave a question or a note for the humans who own the page instead of editing it silently.",
+  parameters: Type.Object({
+    documentId: Type.String({ description: "Document id to comment on." }),
+    text: Type.String({ description: "Comment text." }),
+    parentCommentId: Type.Optional(
+      Type.String({ description: "Reply inside this comment thread." }),
+    ),
+    profile: Type.Optional(
+      Type.String({ description: "Outline profile to use. Defaults to the active one." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: {
+      documentId: string;
+      text: string;
+      parentCommentId?: string;
+      profile?: string;
+    },
+    signal: AbortSignal,
+  ) {
+    if (!params.text || !params.text.trim()) {
+      throw new Error("text must not be empty.");
+    }
+
+    const config = resolveConfig(params.profile);
+    const comment = await createComment(
+      config,
+      {
+        documentId: params.documentId,
+        text: params.text.trim(),
+        parentCommentId: params.parentCommentId,
+      },
+      signal,
+    );
+
+    const kind = params.parentCommentId ? "Reply" : "Comment";
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `${kind} posted on document ${params.documentId}.\nComment id: ${comment.id}`,
+        },
+      ],
+      details: {
+        id: comment.id,
+        documentId: params.documentId,
+        parentCommentId: params.parentCommentId ?? null,
+      },
+    };
+  },
+};