@nshipster/sosumi 1.0.0 → 1.0.4

package/public/index.html

@@ -223,18 +223,24 @@
         }
 
         #clients .interface-tabs,
-        #clients .client-tabs {
+        #clients .mcp-tabs,
+        #cli .cli-tabs,
+        #skill .skill-tabs {
             background: var(--surface-inset);
             border-radius: 0.5rem;
             overflow: hidden;
         }
 
-        #clients .tab-buttons {
+        #clients .mcp-tabs .tab-buttons,
+        #cli .cli-tabs .tab-buttons,
+        #skill .skill-tabs .tab-buttons {
             display: flex;
             border-bottom: 1px solid var(--border);
         }
 
-        #clients .tab-button {
+        #clients .mcp-tabs .tab-button,
+        #cli .cli-tabs .tab-button,
+        #skill .skill-tabs .tab-button {
             flex: 1;
             padding: 1rem 1.5rem;
             background: transparent;
@@ -247,72 +253,93 @@
             border-bottom: 2px solid transparent;
         }
 
-        #clients .tab-button:hover {
+        #clients .mcp-tabs .tab-button:hover,
+        #cli .cli-tabs .tab-button:hover,
+        #skill .skill-tabs .tab-button:hover {
             color: var(--text);
             background: var(--surface-inset-deep);
         }
 
-        #clients .tab-button.active {
+        #clients .mcp-tabs .tab-button.active,
+        #cli .cli-tabs .tab-button.active,
+        #skill .skill-tabs .tab-button.active {
             color: var(--text);
             border-bottom-color: var(--accent);
             background: var(--surface);
         }
 
-        #clients .tab-content {
+        #clients .mcp-tabs .tab-content,
+        #skill .skill-tabs .tab-content {
             position: relative;
         }
 
-        #clients .tab-pane {
+        #clients .mcp-tabs .tab-pane,
+        #cli .cli-tabs .tab-pane,
+        #skill .skill-tabs .tab-pane {
             display: none;
             padding: 1.5rem;
         }
 
-        #clients .tab-pane.active {
+        #clients .mcp-tabs .tab-pane.active,
+        #cli .cli-tabs .tab-pane.active,
+        #skill .skill-tabs .tab-pane.active {
             display: block;
         }
 
-        #clients .tab-pane h3 {
+        #clients .mcp-tabs .tab-pane h3 {
             margin-top: 0;
             margin-bottom: 1rem;
             color: var(--text);
         }
 
-        #clients .tab-pane h4 {
+        #clients .mcp-tabs .tab-pane h4 {
             margin-top: 1.5rem;
             margin-bottom: 0.75rem;
             color: var(--text-secondary);
             font-size: 1rem;
         }
 
-        #clients .tab-pane ol {
+        #clients .mcp-tabs .tab-pane ol {
             margin: 0.75rem 0;
             padding-left: 1.5rem;
         }
 
-        #clients .tab-pane li {
+        #clients .mcp-tabs .tab-pane li {
             margin-bottom: 0.5rem;
         }
 
-        #clients .tab-pane p {
+        #clients .mcp-tabs .tab-pane p,
+        #cli .cli-tabs .tab-pane p,
+        #skill .skill-tabs .tab-pane p {
             margin: 0.75rem 0;
         }
 
-        #clients .tab-pane em {
+        #clients .mcp-tabs .tab-pane em {
             color: var(--text-secondary);
             font-style: italic;
         }
 
+        #cli .cli-tabs {
+            margin-top: 1.5rem;
+        }
+
         @media (max-width: 768px) {
-            #clients .tab-buttons {
+            #clients .mcp-tabs .tab-buttons,
+            #cli .cli-tabs .tab-buttons,
+            #skill .skill-tabs .tab-buttons {
                 flex-direction: column;
             }
 
-            #clients .tab-button {
+            #clients .mcp-tabs .tab-button,
+            #cli .cli-tabs .tab-button,
+            #skill .skill-tabs .tab-button {
                 border-bottom: 1px solid var(--border);
                 border-right: none;
             }
 
-            #clients .tab-button.active {
+            #clients .mcp-tabs .tab-button.active,
+            #cli .cli-tabs .tab-button.active,
+            #skill .skill-tabs .tab-button.active {
                 border-bottom-color: var(--border);
                 border-right: 2px solid var(--accent);
             }
@@ -342,6 +369,20 @@
             overflow-wrap: break-word;
         }
 
+        pre {
+            background: var(--surface-inset);
+            padding: 1.25rem;
+            border-radius: 0.5rem;
+            overflow-x: auto;
+        }
+
+        pre code {
+            background: none;
+            padding: 0;
+            word-break: normal;
+            overflow-wrap: normal;
+        }
+
         main header {
             margin-bottom: 2rem;
         }
@@ -418,6 +459,11 @@
             color: var(--code-punctuation-color);
         }
 
+        pre code .comment {
+            color: var(--text-tertiary);
+            font-style: italic;
+        }
+
         pre code .sosumi-entry {
             background-color: var(--surface-inset-deep);
             display: block;
@@ -514,20 +560,17 @@
                 });
             });
 
-            // Client tabs (Cursor, VSCode, etc.)
-            const clientTabButtons = document.querySelectorAll('.client-tabs .tab-button');
-            const clientTabPanes = document.querySelectorAll('.client-tabs .tab-pane');
-            clientTabButtons.forEach(button => {
-                button.addEventListener('click', function () {
-                    const targetTab = this.getAttribute('data-tab');
-
-                    // Remove active class from all client buttons and panes
-                    clientTabButtons.forEach(btn => btn.classList.remove('active'));
-                    clientTabPanes.forEach(pane => pane.classList.remove('active'));
-
-                    // Add active class to clicked button and corresponding pane
-                    this.classList.add('active');
-                    document.getElementById(targetTab + '-tab').classList.add('active');
+            document.querySelectorAll('.mcp-tabs, .cli-tabs, .skill-tabs').forEach(tabGroup => {
+                const buttons = tabGroup.querySelectorAll('.tab-button');
+                const panes = tabGroup.querySelectorAll('.tab-pane');
+                buttons.forEach(button => {
+                    button.addEventListener('click', function () {
+                        const targetTab = this.getAttribute('data-tab');
+                        buttons.forEach(btn => btn.classList.remove('active'));
+                        panes.forEach(pane => pane.classList.remove('active'));
+                        this.classList.add('active');
+                        document.getElementById(targetTab + '-tab').classList.add('active');
+                    });
                 });
             });
         });
@@ -571,6 +614,9 @@
             <p>
                 This service translates Apple Developer documentation, Human Interface Guidelines, WWDC sessions, and external Swift-DocC sites into AI-friendly Markdown.
             </p>
+            <p>
+                Access it in your <a href="#http">browser</a>, over <a href="#mcp">MCP</a>, from the <a href="#cli">command line</a>, as an <a href="#skill">AI skill</a>, or with an unofficial <a href="https://chromewebstore.google.com/detail/donffakeimppgoehccpfhlchmbfdmfpj" rel="noopener noreferrer">Chrome extension</a>.
+            </p>
         </header>
 
         <section id="http">
@@ -610,25 +656,6 @@
         </section>
 
 
-        <section id="bot">
-            <header>
-                <h2>Bot & Crawling Policy</h2>
-                <p>
-                    Fetches are made with the user agent
-                    <code class="no-wrap">sosumi-ai/1.0 (+https://sosumi.ai/#bot)</code>.
-                </p>
-                <p>
-                    For external Swift-DocC hosts, sosumi honors
-                    <code class="no-wrap">robots.txt</code> rules and opt-out response directives such as
-                    <code class="no-wrap">X-Robots-Tag: noai</code>.
-                </p>
-                <p>
-                    Questions or issues: <a href="mailto:info@sosumi.ai">info@sosumi.ai</a>
-                </p>
-            </header>
-        </section>
-
-
         <section id="mcp">
             <header>
                 <h2>MCP Usage</h2>
@@ -638,7 +665,7 @@
                 </p>
 
                 <figure id="clients">
-                    <div class="client-tabs">
+                    <div class="mcp-tabs">
                         <div class="tab-buttons">
                             <button class="tab-button active" data-tab="copilot-xcode">GitHub Copilot for Xcode</button>
                             <button class="tab-button" data-tab="cursor">Cursor</button>
@@ -807,21 +834,19 @@
                     </li>
                 </ul>
             </div>
-        </section>
-
 
-        <div class="troubleshooting">
-            <h3>Troubleshooting</h3>
-            <p>
-                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.
-            </p>
-            <p>
-                Configure your MCP client to use a proxy by adding environment variables:
-            </p>
-            <pre><code class="mcp-config"><span class="dimmed"><span class="punctuation">{</span></span>
+            <div class="troubleshooting">
+                <h3>Troubleshooting</h3>
+                <p>
+                    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.
+                </p>
+                <p>
+                    Configure your MCP client to use a proxy by adding environment variables:
+                </p>
+                <pre><code class="mcp-config"><span class="dimmed"><span class="punctuation">{</span></span>
 <span class="dimmed">  <span class="key">"mcpServers"</span><span class="punctuation">:</span> <span class="punctuation">{</span></span>
 <span class="sosumi-entry">    <span class="key">"sosumi"</span><span class="punctuation">:</span> <span class="punctuation">{</span>
       <span class="key">"command"</span><span class="punctuation">:</span> <span class="string">"npx"</span><span class="punctuation">,</span>
@@ -836,12 +861,140 @@
       <span class="punctuation">}</span>
     <span class="punctuation">}</span></span><span class="dimmed">  <span class="punctuation">}</span></span>
 <span class="dimmed"><span class="punctuation">}</span></span></code></pre>
+                <p>
+                    Replace <code>proxy.example.com:8080</code> with your actual proxy server details.
+                    For authenticated proxies, use the format:
+                    <code>http://username:password@proxy.example.com:8080</code>
+                </p>
+            </div>
+        </section>
+
+
+        <section id="cli">
+            <header>
+                <h2>CLI Usage</h2>
+                <p>
+                    Sosumi also provides a CLI that complements MCP.
+                </p>
+            </header>
+
+            <div class="cli-tabs">
+                <div class="tab-buttons">
+                    <button class="tab-button active" data-tab="rt-node">Node.js</button>
+                    <button class="tab-button" data-tab="rt-bun">Bun</button>
+                    <button class="tab-button" data-tab="rt-deno">Deno</button>
+                </div>
+
+                <div class="tab-pane active" id="rt-node-tab">
+                    <p>Run directly with <a href="https://docs.npmjs.com/cli/commands/npx" rel="noopener noreferrer"><code>npx</code></a>
+                        (included with <a href="https://nodejs.org/" rel="noopener noreferrer">Node.js</a>):</p>
+                    <pre><code>npx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array</code></pre>
+                    <p>If you use it regularly, install it once:</p>
+                    <pre><code>npm i -g @nshipster/sosumi</code></pre>
+                </div>
+
+                <div class="tab-pane" id="rt-bun-tab">
+                    <p>Run directly with <a href="https://bun.sh/docs/cli/bunx" rel="noopener noreferrer"><code>bunx</code></a>
+                        (included with <a href="https://bun.sh/" rel="noopener noreferrer">Bun</a>):</p>
+                    <pre><code>bunx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array</code></pre>
+                    <p>If you use it regularly, install it once:</p>
+                    <pre><code>bun i -g @nshipster/sosumi</code></pre>
+                </div>
+
+                <div class="tab-pane" id="rt-deno-tab">
+                    <p>Run directly with <a href="https://docs.deno.com/runtime/reference/cli/run/" rel="noopener noreferrer"><code>deno run</code></a>:</p>
+                    <pre><code>deno run -A npm:@nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array</code></pre>
+                    <p>If you use it regularly, install it once:</p>
+                    <pre><code>deno install -g -A npm:@nshipster/sosumi</code></pre>
+                </div>
+            </div>
+
+            <h3>Fetching Documentation</h3>
             <p>
-                Replace <code>proxy.example.com:8080</code> with your actual proxy server details.
-                For authenticated proxies, use the format:
-                <code>http://username:password@proxy.example.com:8080</code>
+                Fetch any content type supported by the MCP tools —
+                API docs, Human Interface Guidelines, WWDC sessions, and external Swift-DocC pages:
             </p>
-        </div>
+            <pre><code>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</code></pre>
+
+            <h3>Searching</h3>
+            <p>Search Apple Developer documentation:</p>
+            <pre><code>sosumi search "SwiftData"</code></pre>
+
+            <h3>JSON Output</h3>
+            <p>
+                By default, output is plain text / Markdown.
+                Add <code>--json</code> for scripts:
+            </p>
+            <pre><code>sosumi fetch /documentation/swift/array --json
+sosumi search "SwiftData" --json</code></pre>
+
+            <h3>Local Server</h3>
+            <p>Run a local instance of the server from the published package:</p>
+            <pre><code>sosumi serve
+sosumi serve --port 8787</code></pre>
+        </section>
+
+        <section id="skill">
+            <header>
+                <h2>AI Agent Skill</h2>
+                <p>
+                    Teach your coding assistant to use Sosumi consistently with:
+                    <code class="no-wrap"><a href="https://sosumi.ai/SKILL.md">https://sosumi.ai/SKILL.md</a></code>
+                </p>
+                <p>
+                    Spec-compliant clients can also discover the skill from this domain:
+                </p>
+                <pre><code>npx skills add https://sosumi.ai</code></pre>
+            </header>
+
+            <div class="skill-tabs">
+                <div class="tab-buttons">
+                    <button class="tab-button active" data-tab="skill-claude-code">Claude Code</button>
+                    <button class="tab-button" data-tab="skill-codex">Codex</button>
+                    <button class="tab-button" data-tab="skill-cursor">Cursor</button>
+                    <button class="tab-button" data-tab="skill-agents">Other</button>
+                </div>
+
+                <div class="tab-content">
+                    <div class="tab-pane active" id="skill-claude-code-tab">
+                        <p>Install as a reusable skill (personal or project-level):</p>
+                        <pre><code><span class="comment"># Personal skill (all your projects)</span>
+mkdir -p ~/.claude/skills/sosumi
+curl -o ~/.claude/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md
+
+<span class="comment"># Project skill (just this project)</span>
+mkdir -p .claude/skills/sosumi
+curl -o .claude/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md</code></pre>
+                    </div>
+
+                    <div class="tab-pane" id="skill-codex-tab">
+                        <p>Install globally:</p>
+                        <pre><code><span class="comment"># Global instructions (all your projects)</span>
+mkdir -p ~/.agents/skills/sosumi
+curl -o ~/.agents/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md</code></pre>
+                    </div>
+
+                    <div class="tab-pane" id="skill-cursor-tab">
+                        <p>Install as a Cursor skill (global or project-level):</p>
+                        <pre><code><span class="comment"># Personal skill (all your projects)</span>
+mkdir -p ~/.cursor/skills/sosumi
+curl -o ~/.cursor/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md
+
+<span class="comment"># Project skill (just this project)</span>
+mkdir -p .cursor/skills/sosumi
+curl -o .cursor/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md</code></pre>
+                    </div>
+
+                    <div class="tab-pane" id="skill-agents-tab">
+                        <p>For AGENTS-compatible tools, install as a reusable skill:</p>
+                        <pre><code>mkdir -p ~/.agents/skills/sosumi
+curl -o ~/.agents/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md</code></pre>
+                    </div>
+                </div>
+            </div>
         </section>
     </main>
 
@@ -876,6 +1029,13 @@
                 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.
             </p>
+            <p id="bot">
+                Fetches are made with the user agent
+                <code class="no-wrap">sosumi-ai/1.0 (+https://sosumi.ai/#bot)</code>.
+                For external Swift-DocC hosts, sosumi honors
+                <code class="no-wrap">robots.txt</code> rules and opt-out response directives such as
+                <code class="no-wrap">X-Robots-Tag: noai</code>.
+            </p>
             <p>
                 <strong>Contact:</strong> <a href="mailto:info@sosumi.ai">info@sosumi.ai</a>
             </p>