@nshipster/sosumi 1.0.0

package/public/llms.txt

@@ -0,0 +1,184 @@
+# sosumi.ai - Apple Docs for LLMs
+
+Ever notice Claude struggling to write Swift code?
+It might not be their fault!
+
+Apple Developer docs are locked behind JavaScript,
+making them invisible to most LLMs.
+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.
+
+## HTTP Usage
+
+Replace `developer.apple.com` with `sosumi.ai`:
+
+**Original:**
+https://developer.apple.com/documentation/swift/array
+
+**AI-readable:**
+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
+
+## MCP Usage
+
+Connect your MCP client to `https://sosumi.ai/mcp`:
+
+### GitHub Copilot for Xcode
+
+1. Open **GitHub Copilot for Xcode** and go to **Settings…**
+2. Select the **MCP** tab
+3. Click **Edit Config**
+4. Enter the following configuration:
+
+```json
+{
+  "servers": {
+    "sosumi": {
+      "type": "http",
+      "url": "https://sosumi.ai/mcp"
+    }
+  }
+}
+```
+
+### Cursor
+
+Open this deep link to automatically install the sosumi MCP server:
+
+[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=sosumi&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vc29zdW1pLmFpL21jcCJ9)
+
+### VSCode
+
+Create a `.vscode/mcp.json` file in your workspace and enter the following configuration:
+
+```json
+{
+  "servers": {
+    "sosumi": {
+      "type": "http",
+      "url": "https://sosumi.ai/mcp"
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+1. Open **Claude Desktop**
+2. Go to **Settings → Connectors**
+3. Click **"Add custom connector"**
+4. Set **"Name"** to `"sosumi"`
+5. Set **"Remote MCP server URL"** to `"https://sosumi.ai/mcp"`
+6. Click "Add"
+
+### Claude Code
+
+Run the following command in your terminal:
+
+```shell
+claude mcp add --transport http sosumi https://sosumi.ai/mcp
+```
+
+### Other
+
+Sosumi's MCP server supports Streamable HTTP and Server-Sent Events (SSE) transport.
+**If your client supports either of these,
+configure it to connect directly to `https://sosumi.ai/mcp`.**
+
+Otherwise,
+you can run this command to proxy over stdio:
+
+```json
+{
+  "mcpServers": {
+    "sosumi": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://sosumi.ai/mcp"]
+    }
+  }
+}
+```
+
+### Available Tools
+
+- `searchAppleDocumentation` - Searches Apple Developer documentation
+  - Parameters: `query` (string)
+  - 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`)
+  - 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`)
+  - Returns content as Markdown
+
+## Troubleshooting
+
+If you're experiencing connection timeouts or network issues with the MCP server,
+you may need to configure a proxy.
+This is particularly common in corporate environments
+or regions with restricted internet access.
+
+Configure your MCP client to use a proxy by adding environment variables:
+
+```json
+{
+  "mcpServers": {
+    "sosumi": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://sosumi.ai/mcp"],
+      "env": {
+        "HTTP_PROXY": "http://proxy.example.com:8080",
+        "HTTPS_PROXY": "http://proxy.example.com:8080"
+      }
+    }
+  }
+}
+```
+
+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
+
+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.
+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;
+and it implements rate limiting to avoid imposing unreasonable load.
+
+Content is fetched transiently and may be cached briefly to improve performance.
+No permanent archives are maintained.
+All copyrights and other rights in the underlying content remain with Apple Inc.
+Each page links back to the original source.
+
+Your use of this service must comply with Apple's Terms of Use and applicable law.
+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

package/src/cli.ts

@@ -0,0 +1,214 @@
+import { parseCliArgs, resolveFetchEndpoint } from "./lib/cli-endpoints"
+import { fetchExternalDocumentationMarkdown } from "./lib/external"
+import { NotFoundError } from "./lib/fetch"
+import {
+  extractHIGPaths,
+  fetchHIGPageData,
+  fetchHIGTableOfContents,
+  renderHIGFromJSON,
+  renderHIGTableOfContents,
+} from "./lib/hig"
+import { fetchJSONData, renderFromJSON } from "./lib/reference"
+import { searchAppleDeveloperDocs } from "./lib/search"
+import { generateAppleDocUrl, normalizeDocumentationPath } from "./lib/url"
+import { fetchVideoTranscriptMarkdown } from "./lib/video"
+
+function printUsage() {
+  console.error(`Usage:
+  sosumi fetch <url-or-path> [--json]
+  sosumi search <query> [--json]
+  sosumi serve [wrangler-dev-args...]
+
+Examples:
+  npx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array
+  npx @nshipster/sosumi fetch /videos/play/wwdc2021/10133
+  npx @nshipster/sosumi search "SwiftData"
+  npx @nshipster/sosumi serve --port 8787
+`)
+}
+
+function printTextOutput(text: string) {
+  process.stdout.write(text)
+}
+
+function printJsonOutput(value: unknown) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`)
+}
+
+async function runFetch(input: string, json: boolean) {
+  const endpoint = resolveFetchEndpoint(input)
+
+  if (endpoint.startsWith("/documentation/")) {
+    const documentationPath = endpoint.replace(/^\/documentation\//, "")
+    const normalizedPath = normalizeDocumentationPath(documentationPath)
+    const appleUrl = generateAppleDocUrl(normalizedPath)
+    const jsonData = await fetchJSONData(normalizedPath)
+    const markdown = await renderFromJSON(jsonData, appleUrl)
+    if (json) {
+      printJsonOutput({ url: appleUrl, content: markdown })
+    } else {
+      printTextOutput(markdown)
+    }
+    return
+  }
+
+  if (endpoint === "/design/human-interface-guidelines") {
+    const markdown = await renderHIGTableOfContents(await fetchHIGTableOfContents())
+    const sourceUrl = "https://developer.apple.com/design/human-interface-guidelines/"
+    if (json) {
+      printJsonOutput({ url: sourceUrl, content: markdown })
+    } else {
+      printTextOutput(markdown)
+    }
+    return
+  }
+
+  if (endpoint.startsWith("/design/human-interface-guidelines/")) {
+    const higPath = endpoint.replace(/^\/design\/human-interface-guidelines\//, "")
+    const { sourceUrl, markdown } = await fetchHigMarkdown(higPath)
+    if (json) {
+      printJsonOutput({ url: sourceUrl, content: markdown })
+    } else {
+      printTextOutput(markdown)
+    }
+    return
+  }
+
+  if (endpoint.startsWith("/videos/play/")) {
+    const segments = endpoint.split("/")
+    const collection = segments[3] as string
+    const videoId = segments[4] as string
+    const sourceUrl = `https://developer.apple.com/videos/play/${collection}/${videoId}/`
+    const markdown = await fetchVideoTranscriptMarkdown(sourceUrl, collection, videoId)
+    if (json) {
+      printJsonOutput({ url: sourceUrl, content: markdown })
+    } else {
+      printTextOutput(markdown)
+    }
+    return
+  }
+
+  if (endpoint.startsWith("/external/")) {
+    const externalUrl = endpoint.replace(/^\/external\//, "")
+    const markdown = await fetchExternalDocumentationMarkdown(externalUrl, {
+      EXTERNAL_DOC_HOST_ALLOWLIST: process.env.EXTERNAL_DOC_HOST_ALLOWLIST,
+      EXTERNAL_DOC_HOST_BLOCKLIST: process.env.EXTERNAL_DOC_HOST_BLOCKLIST,
+    })
+    if (json) {
+      printJsonOutput({ url: externalUrl, content: markdown })
+    } else {
+      printTextOutput(markdown)
+    }
+    return
+  }
+
+  throw new Error(`Unsupported fetch endpoint: ${endpoint}`)
+}
+
+async function fetchHigMarkdown(higPath: string): Promise<{ sourceUrl: string; markdown: string }> {
+  const sourceUrlFor = (path: string) =>
+    `https://developer.apple.com/design/human-interface-guidelines/${path}`
+
+  const resolvedPath = await resolveHigPathForFetch(higPath)
+
+  try {
+    const sourceUrl = sourceUrlFor(resolvedPath)
+    const markdown = await renderHIGFromJSON(await fetchHIGPageData(resolvedPath), sourceUrl)
+    return { sourceUrl, markdown }
+  } catch (error) {
+    if (error instanceof NotFoundError && resolvedPath !== higPath) {
+      const sourceUrl = sourceUrlFor(higPath)
+      const markdown = await renderHIGFromJSON(await fetchHIGPageData(higPath), sourceUrl)
+      return { sourceUrl, markdown }
+    }
+    throw error
+  }
+}
+
+async function resolveHigPathForFetch(higPath: string): Promise<string> {
+  if (!higPath.includes("/")) {
+    return higPath
+  }
+
+  // HIG moved many topics from grouped paths (e.g. foundations/color -> color).
+  // Resolve legacy grouped paths by leaf slug from the live ToC when unique.
+  const leaf = higPath.split("/").filter(Boolean).pop()
+  if (!leaf) {
+    return higPath
+  }
+
+  const paths = extractHIGPaths(await fetchHIGTableOfContents())
+  const matches = paths.filter((path) => path === leaf || path.endsWith(`/${leaf}`))
+  return matches.length === 1 ? matches[0] : higPath
+}
+
+async function runSearch(query: string, json: boolean) {
+  const trimmedQuery = query.trim()
+  if (!trimmedQuery) {
+    console.error("Search query cannot be empty")
+    process.exitCode = 1
+    return
+  }
+
+  const searchResponse = await searchAppleDeveloperDocs(trimmedQuery)
+  if (json) {
+    printJsonOutput(searchResponse)
+    return
+  }
+
+  if (searchResponse.results.length === 0) {
+    console.error(`No results found for "${trimmedQuery}"`)
+    process.exitCode = 2
+    return
+  }
+
+  const resultText =
+    `Found ${searchResponse.results.length} result(s) for "${trimmedQuery}":\n\n` +
+    searchResponse.results
+      .map(
+        (result, index) =>
+          `${index + 1}. ${result.title}\n   ${result.url}\n   ${result.description || "No description"}`,
+      )
+      .join("\n\n")
+  printTextOutput(resultText)
+}
+
+export async function main(argv: string[] = process.argv.slice(2)) {
+  const { help, flags, positionals } = parseCliArgs(argv)
+  if (help) {
+    printUsage()
+    return
+  }
+
+  if (positionals.length < 2) {
+    printUsage()
+    process.exitCode = 1
+    return
+  }
+
+  const [command, ...rest] = positionals
+  const payload = rest.join(" ")
+
+  if (command === "fetch") {
+    await runFetch(payload, flags.json)
+    return
+  }
+
+  if (command === "search") {
+    await runSearch(payload, flags.json)
+    return
+  }
+
+  // "serve" is still handled by bin wrapper to keep wrangler process behavior.
+  if (command === "serve") {
+    return
+  }
+
+  throw new Error(`Unknown command: ${command}`)
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(`sosumi: ${message}`)
+  process.exit(1)
+})