@nshipster/sosumi 1.0.0 → 1.0.4

package/public/llms.txt

@@ -9,29 +9,34 @@ If they try to fetch it, all they see is:
 > This page requires JavaScript.
 > Please turn on JavaScript in your browser and refresh the page to view its content.
 
-This service translates Apple Developer documentation pages into AI-friendly Markdown.
+This service translates Apple Developer documentation,
+Human Interface Guidelines, WWDC sessions,
+and external Swift-DocC sites into AI-friendly Markdown.
+Access it in your browser, over MCP, from the command line, as an AI skill,
+or with an unofficial [Chrome extension](https://chromewebstore.google.com/detail/donffakeimppgoehccpfhlchmbfdmfpj).
 
 ## HTTP Usage
 
 Replace `developer.apple.com` with `sosumi.ai`:
 
 **Original:**
-https://developer.apple.com/documentation/swift/array
+<https://developer.apple.com/documentation/swift/array>
 
 **AI-readable:**
-https://sosumi.ai/documentation/swift/array
+<https://sosumi.ai/documentation/swift/array>
 
 ### Examples
 
-**Developer Documentation:**
-- Swift: https://sosumi.ai/documentation/swift
-- SwiftUI: https://sosumi.ai/documentation/swiftui
-- Human Interface Guidelines: https://sosumi.ai/design/human-interface-guidelines
-- WWDC sessions: https://sosumi.ai/videos/play/wwdc2021/10133
+- Swift: <https://sosumi.ai/documentation/swift>
+- SwiftUI: <https://sosumi.ai/documentation/swiftui>
+- Human Interface Guidelines: <https://sosumi.ai/design/human-interface-guidelines>
+- WWDC21 — Protect mutable state with Swift actors: <https://sosumi.ai/videos/play/wwdc2021/10133>
+- Swift Argument Parser (GitHub Pages): <https://sosumi.ai/external/https://apple.github.io/swift-argument-parser/documentation/argumentparser/>
+- The Composable Architecture (Swift Package Index): <https://sosumi.ai/external/https://swiftpackageindex.com/pointfreeco/swift-composable-architecture/1.23.1/documentation/composablearchitecture>
 
 ## MCP Usage
 
-Connect your MCP client to `https://sosumi.ai/mcp`:
+Connect your MCP client to `https://sosumi.ai/mcp`.
 
 ### GitHub Copilot for Xcode
 
@@ -89,7 +94,7 @@ Run the following command in your terminal:
 claude mcp add --transport http sosumi https://sosumi.ai/mcp
 ```
 
-### Other
+### Other MCP Clients
 
 Sosumi's MCP server supports Streamable HTTP and Server-Sent Events (SSE) transport.
 **If your client supports either of these,
@@ -113,25 +118,21 @@ you can run this command to proxy over stdio:
 
 - `searchAppleDocumentation` - Searches Apple Developer documentation
   - Parameters: `query` (string)
-  - Returns structured results with titles,
-    URLs,
-    descriptions,
-    breadcrumbs,
-    and tags
+  - Returns structured results with titles, URLs, descriptions, breadcrumbs, and tags
 
 - `fetchAppleDocumentation` - Fetches Apple Developer documentation and Human Interface Guidelines by path
   - Parameters: `path` (string) - Documentation path (e.g., '/documentation/swift', 'design/human-interface-guidelines/foundations/color')
   - Returns content as Markdown
 
-- `fetchAppleVideoTranscript` - Fetches video transcripts, including WWDC sessions
-  - Parameters: `path` (string) - video path (e.g., `/videos/play/wwdc2021/10133`)
+- `fetchAppleVideoTranscript` - Fetches video transcripts, including WWDC sessions, by video path
+  - Parameters: `path` (string) - video path (e.g., '/videos/play/wwdc2021/10133', '/videos/play/meet-with-apple/208')
   - Returns content as Markdown
 
 - `fetchExternalDocumentation` - Fetches external Swift-DocC documentation by absolute HTTPS URL
-  - Parameters: `url` (string) - External URL (e.g., `https://apple.github.io/swift-argument-parser/documentation/argumentparser`)
+  - Parameters: `url` (string) - External URL (e.g., '<https://apple.github.io/swift-argument-parser/documentation/argumentparser>')
   - Returns content as Markdown
 
-## Troubleshooting
+### Troubleshooting
 
 If you're experiencing connection timeouts or network issues with the MCP server,
 you may need to configure a proxy.
@@ -159,14 +160,163 @@ Replace `proxy.example.com:8080` with your actual proxy server details.
 For authenticated proxies, use the format:
 `http://username:password@proxy.example.com:8080`
 
-## About
+## CLI Usage
+
+Sosumi also provides a CLI that complements MCP.
+
+### Node.js
+
+Run directly with [`npx`](https://docs.npmjs.com/cli/commands/npx)
+(included with [Node.js](https://nodejs.org/)):
+
+```shell
+npx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array
+```
+
+If you use it regularly, install it once:
+
+```shell
+npm i -g @nshipster/sosumi
+```
+
+### Bun
+
+Run directly with [`bunx`](https://bun.sh/docs/cli/bunx)
+(included with [Bun](https://bun.sh/)):
+
+```shell
+bunx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array
+```
+
+If you use it regularly, install it once:
+
+```shell
+bun i -g @nshipster/sosumi
+```
+
+### Deno
+
+Run directly with [`deno run`](https://docs.deno.com/runtime/reference/cli/run/):
+
+```shell
+deno run -A npm:@nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array
+```
+
+If you use it regularly, install it once:
+
+```shell
+deno install -g -A npm:@nshipster/sosumi
+```
+
+### Fetching Documentation
+
+Fetch any content type supported by the MCP tools —
+API docs, Human Interface Guidelines, WWDC sessions, and external Swift-DocC pages:
+
+```shell
+sosumi fetch /documentation/swift/array
+sosumi fetch /design/human-interface-guidelines/color
+sosumi fetch /videos/play/wwdc2021/10133
+sosumi fetch https://apple.github.io/swift-argument-parser/documentation/argumentparser
+```
+
+### Searching
+
+Search Apple Developer documentation:
+
+```shell
+sosumi search "SwiftData"
+```
+
+### JSON Output
 
-This is an unofficial,
-independent project and is not affiliated with or endorsed by Apple Inc.
+By default, output is plain text / Markdown.
+Add `--json` for scripts:
+
+```shell
+sosumi fetch /documentation/swift/array --json
+sosumi search "SwiftData" --json
+```
+
+### Local Server
+
+Run a local instance of the server from the published package:
+
+```shell
+sosumi serve
+sosumi serve --port 8787
+```
+
+## AI Agent Skill
+
+Teach your coding assistant to use Sosumi consistently with:
+`https://sosumi.ai/SKILL.md`
+
+Spec-compliant clients can also discover and install it from this domain:
+
+```bash
+npx skills add https://sosumi.ai
+```
+
+### Claude Code
+
+Install as a reusable skill (personal or project-level):
+
+```bash
+# Personal skill (all your projects)
+mkdir -p ~/.claude/skills/sosumi
+curl -o ~/.claude/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md
+
+# Project skill (just this project)
+mkdir -p .claude/skills/sosumi
+curl -o .claude/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md
+```
+
+### Codex
+
+Install globally:
+
+```bash
+# Global instructions (all your projects)
+mkdir -p ~/.agents/skills/sosumi
+curl -o ~/.agents/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md
+```
+
+### Cursor
+
+Install as a Cursor skill (global or project-level):
+
+```bash
+# Personal skill (all your projects)
+mkdir -p ~/.cursor/skills/sosumi
+curl -o ~/.cursor/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md
+
+# Project skill (just this project)
+mkdir -p .cursor/skills/sosumi
+curl -o .cursor/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md
+```
+
+### Other
+
+For AGENTS-compatible tools, install as a reusable skill:
+
+```bash
+mkdir -p ~/.agents/skills/sosumi
+curl -o ~/.agents/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md
+```
+
+Use this together with Sosumi MCP at `https://sosumi.ai/mcp`.
+
+## Legal
+
+This is an unofficial, independent project
+and is not affiliated with or endorsed by Apple Inc.
 "Apple", "Xcode", and related marks are trademarks of Apple Inc.
 
-This service is an accessibility-first,
-on‑demand renderer.
+This project is open source and available on
+[GitHub](https://github.com/NSHipster/sosumi.ai).
+
+This service is an accessibility-first, on-demand renderer.
 It converts a single Apple Developer page to Markdown only when requested by a user.
 It does not crawl, spider, or bulk download;
 it does not attempt to bypass authentication or security;
@@ -181,4 +331,8 @@ Your use of this service must comply with Apple's Terms of Use and applicable la
 You are solely responsible for how you access and use Apple's content through this tool.
 Do not use this service to circumvent technical measures or for redistribution.
 
-**Contact:** info@sosumi.ai
+Fetches are made with the user agent `sosumi-ai/1.0 (+https://sosumi.ai/#bot)`.
+For external Swift-DocC hosts, sosumi honors `robots.txt` rules
+and opt-out response directives such as `X-Robots-Tag: noai`.
+
+**Contact:** <info@sosumi.ai>

package/public/robots.txt

@@ -0,0 +1,8 @@
+User-agent: *
+Allow: /
+Disallow: /documentation/
+Disallow: /external/
+Disallow: /design/human-interface-guidelines
+Disallow: /videos/play/
+
+Sitemap: https://sosumi.ai/sitemap.xml

package/public/sitemap.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://sosumi.ai/</loc>
+  </url>
+</urlset>

package/src/index.ts

@@ -1,5 +1,6 @@
 import { StreamableHTTPTransport } from "@hono/mcp"
 import { Hono } from "hono"
+import { accepts } from "hono/accepts"
 import { cache } from "hono/cache"
 import { cors } from "hono/cors"
 import { HTTPException } from "hono/http-exception"
@@ -21,6 +22,14 @@ import {
 import { createMcpServer } from "./lib/mcp"
 import { fetchJSONData, renderFromJSON } from "./lib/reference"
 import { searchAppleDeveloperDocs } from "./lib/search"
+import {
+  createSkillIndex,
+  loadSkill,
+  SKILL_NAME,
+  skillExists,
+  skillHeaders,
+  skillIndexHeaders,
+} from "./lib/skill"
 import { generateAppleDocUrl, isValidAppleDocUrl, normalizeDocumentationPath } from "./lib/url"
 import { fetchVideoTranscriptMarkdown, TranscriptNotFoundError } from "./lib/video"
 
@@ -32,24 +41,6 @@ interface Env {
 }
 
 const app = new Hono<{ Bindings: Env }>()
-const mcpServerCache = new Map<string, ReturnType<typeof createMcpServer>>()
-
-function getMcpServer(env: Env) {
-  const allowlist = env.EXTERNAL_DOC_HOST_ALLOWLIST ?? ""
-  const blocklist = env.EXTERNAL_DOC_HOST_BLOCKLIST ?? ""
-  const cacheKey = `${allowlist}\n---\n${blocklist}`
-  const cached = mcpServerCache.get(cacheKey)
-  if (cached) {
-    return cached
-  }
-
-  const server = createMcpServer({
-    EXTERNAL_DOC_HOST_ALLOWLIST: env.EXTERNAL_DOC_HOST_ALLOWLIST,
-    EXTERNAL_DOC_HOST_BLOCKLIST: env.EXTERNAL_DOC_HOST_BLOCKLIST,
-  })
-  mcpServerCache.set(cacheKey, server)
-  return server
-}
 
 app.use("*", async (c, next) => {
   await next()
@@ -84,15 +75,89 @@ app.use("*", async (c, next) => {
   await next()
 })
 
+app.get("/", async (c) => {
+  const accepted = accepts(c, {
+    header: "Accept",
+    supports: ["text/markdown", "text/html"],
+    default: "text/html",
+  })
+
+  if (accepted === "text/markdown") {
+    const llmsUrl = new URL("/llms.txt", c.req.url)
+    const llmsResponse = await c.env.ASSETS.fetch(new Request(llmsUrl.toString()))
+
+    if (!llmsResponse.ok) {
+      throw new HTTPException(500, {
+        message: "Failed to load llms.txt",
+      })
+    }
+
+    const markdown = await llmsResponse.text()
+    return c.text(markdown, 200, {
+      "Content-Type": "text/markdown; charset=utf-8",
+      "Cache-Control": "public, max-age=300, s-maxage=600",
+    })
+  }
+
+  return c.env.ASSETS.fetch(c.req.raw)
+})
+
+app.all("/.well-known/agent-skills/index.json", async (c) => {
+  if (c.req.method !== "GET" && c.req.method !== "HEAD") {
+    return c.text("Method Not Allowed", 405, { Allow: "GET, HEAD" })
+  }
+
+  if (c.req.method === "HEAD") {
+    if (!(await skillExists(c.env.ASSETS, c.req.url))) {
+      throw new HTTPException(500, { message: "Failed to load SKILL.md" })
+    }
+    return new Response(null, {
+      status: 200,
+      headers: skillIndexHeaders,
+    })
+  }
+
+  const skill = await loadSkill(c.env.ASSETS, c.req.url)
+  const index = await createSkillIndex(skill)
+
+  return c.json(index, 200, skillIndexHeaders)
+})
+
+app.all(`/.well-known/agent-skills/${SKILL_NAME}/SKILL.md`, async (c) => {
+  if (c.req.method !== "GET" && c.req.method !== "HEAD") {
+    return c.text("Method Not Allowed", 405, { Allow: "GET, HEAD" })
+  }
+
+  if (c.req.method === "HEAD") {
+    if (!(await skillExists(c.env.ASSETS, c.req.url))) {
+      throw new HTTPException(500, { message: "Failed to load SKILL.md" })
+    }
+    return new Response(null, {
+      status: 200,
+      headers: skillHeaders,
+    })
+  }
+
+  const skill = await loadSkill(c.env.ASSETS, c.req.url)
+
+  return new Response(skill.bytes, {
+    status: 200,
+    headers: skillHeaders,
+  })
+})
+
+app.get("/bot", (c) => c.redirect("/#bot", 302))
+
 app.all("/mcp", async (c) => {
-  const mcpServer = getMcpServer(c.env)
+  const mcpServer = createMcpServer({
+    EXTERNAL_DOC_HOST_ALLOWLIST: c.env.EXTERNAL_DOC_HOST_ALLOWLIST,
+    EXTERNAL_DOC_HOST_BLOCKLIST: c.env.EXTERNAL_DOC_HOST_BLOCKLIST,
+  })
   const transport = new StreamableHTTPTransport()
   await mcpServer.connect(transport)
   return transport.handleRequest(c)
 })
 
-app.get("/bot", (c) => c.redirect("/#bot", 302))
-
 app.get("/search", async (c) => {
   const query = c.req.query("q")?.trim() ?? ""
   if (!query) {
@@ -183,6 +248,7 @@ This service only works with Apple Developer documentation URLs:
     "Content-Location": appleUrl,
     "Cache-Control": "public, max-age=3600, s-maxage=86400",
     ETag: `"${Buffer.from(markdown).toString("base64").slice(0, 16)}"`,
+    "X-Robots-Tag": "noindex, nofollow, noarchive",
   }
 
   if (c.req.header("Accept")?.includes("application/json")) {
@@ -225,6 +291,7 @@ app.get("/external/*", async (c) => {
     "Content-Location": targetUrl.toString(),
     "Cache-Control": "public, max-age=3600, s-maxage=86400",
     ETag: `"${Buffer.from(markdown).toString("base64").slice(0, 16)}"`,
+    "X-Robots-Tag": "noindex, nofollow, noarchive",
   }
 
   if (c.req.header("Accept")?.includes("application/json")) {
@@ -263,6 +330,7 @@ app.get("/design/human-interface-guidelines", async (c) => {
     "Content-Location": sourceUrl,
     "Cache-Control": "public, max-age=3600, s-maxage=86400",
     ETag: `"${Buffer.from(markdown).toString("base64").slice(0, 16)}"`,
+    "X-Robots-Tag": "noindex, nofollow, noarchive",
   }
 
   if (c.req.header("Accept")?.includes("application/json")) {
@@ -305,6 +373,7 @@ app.get("/design/human-interface-guidelines/:path{.+}", async (c) => {
     "Content-Location": sourceUrl,
     "Cache-Control": "public, max-age=3600, s-maxage=86400",
     ETag: `"${Buffer.from(markdown).toString("base64").slice(0, 16)}"`,
+    "X-Robots-Tag": "noindex, nofollow, noarchive",
   }
 
   if (c.req.header("Accept")?.includes("application/json")) {
@@ -358,6 +427,7 @@ app.get("/videos/play/:collection/:id", async (c) => {
     "Content-Location": sourceUrl,
     "Cache-Control": "public, max-age=3600, s-maxage=86400",
     ETag: `"${Buffer.from(markdown).toString("base64").slice(0, 16)}"`,
+    "X-Robots-Tag": "noindex, nofollow, noarchive",
   }
 
   if (c.req.header("Accept")?.includes("application/json")) {

package/src/lib/hig/render.ts

@@ -496,7 +496,10 @@ function renderHIGTocItems(items: HIGTocItem[], headingLevel: number): string {
 
   for (const item of items) {
     if (item.type === "module" || item.type === "symbol") {
-      // Main sections get headings
+      // Ensure blank line before heading when preceding content was a list
+      if (markdown && !markdown.endsWith("\n\n")) {
+        markdown += "\n"
+      }
       const hashes = "#".repeat(Math.min(headingLevel, 6))
       markdown += `${hashes} ${item.title}\n\n`
 

package/src/lib/reference/render.ts

@@ -6,6 +6,7 @@ import type {
   AppleDocJSON,
   ContentItem,
   IndexContentItem,
+  PossibleValueItem,
   PropertyItem,
   TopicSection,
   Variant,
@@ -94,6 +95,18 @@ export async function renderFromJSON(
       )
     }
 
+    // Add possible values (used by enum/string type pages)
+    const possibleValuesSection = jsonData.primaryContentSections.find(
+      (s) => s.kind === "possibleValues",
+    )
+    if (possibleValuesSection?.values) {
+      markdown += renderPossibleValues(
+        possibleValuesSection.values,
+        jsonData.references,
+        options.externalOrigin,
+      )
+    }
+
     // Add content sections
     const contentSections = jsonData.primaryContentSections.filter((s) => s.kind === "content")
     for (const section of contentSections) {
@@ -294,6 +307,34 @@ function renderProperties(
   return markdown
 }
 
+/**
+ * Render possible values section for enum/string type pages.
+ */
+function renderPossibleValues(
+  values: PossibleValueItem[],
+  references?: Record<string, ContentItem>,
+  externalOrigin?: string,
+): string {
+  if (values.length === 0) return ""
+
+  let markdown = "## Possible Values\n\n"
+
+  for (const value of values) {
+    if (!value.name) continue
+
+    markdown += `### \`${value.name}\`\n\n`
+
+    if (value.content && Array.isArray(value.content)) {
+      const text = renderContentArray(value.content, references, 0, externalOrigin).trim()
+      if (text) {
+        markdown += `${text}\n\n`
+      }
+    }
+  }
+
+  return markdown
+}
+
 function renderPropertyType(
   type: Array<{ text?: string; kind?: string; identifier?: string }> | undefined,
   references?: Record<string, ContentItem>,
@@ -397,6 +438,16 @@ function renderContentArray(
       markdown += `> [!${calloutType}]\n> ${cleanContent}\n\n`
     } else if (item.type === "table") {
       markdown += renderTable(item, references, depth, externalOrigin)
+    } else if (item.type === "tabNavigator" && item.tabs?.length) {
+      for (const tab of item.tabs) {
+        const label = tab.title?.trim()
+        if (label) {
+          markdown += `**${label}**\n\n`
+        }
+        if (tab.content?.length) {
+          markdown += renderContentArray(tab.content, references, depth + 1, externalOrigin)
+        }
+      }
     }
   }
 

package/src/lib/reference/types.ts

@@ -20,6 +20,7 @@ export type {
   LanguageVariant,
   Parameter,
   Platform,
+  PossibleValueItem,
   PrimaryContentSection,
   PropertyItem,
   SeeAlsoSection,