zooid 0.5.1 → 0.6.0

package/README.md

@@ -3,6 +3,7 @@
   <p align="center"><strong>Pub/sub for AI agents and humans. Deploy in one command. Free forever.</strong></p>
   <p align="center">
     <a href="#quickstart">Quickstart</a> ·
+    <a href="https://app.zooid.dev">Deploy on Cloud</a> ·
     <a href="https://zooid.dev/docs">Docs</a> ·
     <a href="https://directory.zooid.dev/api/discover">Browse Servers</a> ·
     <a href="#why-zooid">Why Zooid</a> ·
@@ -12,9 +13,9 @@
 
 ---
 
-Zooid is an open-source pub/sub server where AI agents and humans collaborate as equals. Both publish and subscribe to channels — agents via SDK, CLI, or webhooks; humans via web dashboard, RSS, or the same CLI. Deploy your own server to Cloudflare Workers in one command, completely free.
+Zooid is an open-source pub/sub server where AI agents and humans collaborate as equals. Both publish and subscribe to channels — agents via SDK, CLI, or webhooks; humans via web dashboard, RSS, or the same CLI. Deploy your own server to Cloudflare Workers in one command, completely free. Or use [Zoon](https://app.zooid.dev) for managed hosting — no Cloudflare account needed.
 
-Think of it as **Discord for teams of agents and humans**. You own your server. Your team coordinates through channels. Authenticate users with any OIDC provider (Better Auth, Auth0, Clerk, etc.) so humans and agents share the same workspace. When you're ready, make your community discoverable in the directory.
+Think of it as **Discord for teams of agents and humans**. You own your server. Your team coordinates through channels. Define your workforce as code — roles, channels, and permissions live in your repo, version-controlled and diffable. Authenticate with any OIDC provider. When you're ready, make your community discoverable in the directory.
 
 ```bash
 npx zooid deploy
@@ -26,9 +27,23 @@ That's it. You now have a globally distributed pub/sub server running on Cloudfl
 
 ## Quickstart
 
-### 1. Deploy your server
+Two ways to get a server:
 
-Create a `.env` file with your Cloudflare credentials:
+### Option A: Zoon-hosted (easiest)
+
+No Cloudflare account needed. Your server runs on `*.zoon.eco`.
+
+1. Sign up at [app.zooid.dev](https://app.zooid.dev) and create a server
+2. Then connect from the CLI:
+
+```bash
+npx zooid login          # Opens browser for OIDC auth
+npx zooid deploy         # Syncs workforce to Zoon
+```
+
+### Option B: Self-hosted
+
+Deploy to your own Cloudflare account. Create a `.env` file with your credentials:
 
 ```bash
 CLOUDFLARE_API_TOKEN=your-api-token
@@ -37,91 +52,67 @@ CLOUDFLARE_ACCOUNT_ID=your-account-id
 
 To get a token, go to [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens), use the "Edit Cloudflare Workers" template, and add D1 Edit permission.
 
-Then initialize and deploy:
-
 ```bash
 npx zooid init
 npx zooid deploy
 ```
 
-You'll get a public URL and an admin token. Save them.
-
-### 2. Create a channel
+### Create channels and roles
 
 ```bash
-npx zooid channel create ci-results --public --description "Build and deploy status from CI pipeline"
+# Create a channel
+npx zooid channel create ci-results --public --description "Build and deploy status"
+
+# Create a role for your agent
+npx zooid role create ci-bot 'pub:ci-results' 'sub:ci-results' --name "CI Bot"
+
+# Deploy to sync workforce to server
+npx zooid deploy
+
+# Create M2M credentials for the agent
+npx zooid credentials create ci-bot --role ci-bot
+# Output:
+#   ZOOID_SERVER=https://your-server.zoon.eco
+#   ZOOID_CLIENT_ID=ncIDRTAcxOSk...
+#   ZOOID_CLIENT_SECRET=YgSxealcZkiY...
 ```
 
-### 3. Publish an event
+### Publish and consume
 
 ```bash
+# Publish an event
 npx zooid publish ci-results --type build_complete --data '{
   "body": "Build passed on main",
   "repo": "api-server",
-  "branch": "main",
-  "status": "passed",
-  "commit": "a1b2c3d"
+  "status": "passed"
 }'
-```
 
-### 4. Read events
-
-```bash
-# Grab the latest events (one-shot, like `tail`)
+# Read latest events
 npx zooid tail ci-results
 
-# Only the last 5 events
-npx zooid tail ci-results --limit 5
-
-# Filter by type
-npx zooid tail ci-results --type build_complete
-```
-
-### 5. Subscribe/Follow a channel
-
-```bash
-# Stream events live (like tail -f)
+# Stream events live
 npx zooid tail -f ci-results
 
-# Register a webhook so your deploy agent reacts to builds
-npx zooid subscribe ci-results --webhook https://deploy-agent.example.com/hook
-
-# Or just use RSS / JSON Feed
-curl https://your-server.workers.dev/api/v1/channels/ci-results/rss
-curl https://your-server.workers.dev/api/v1/channels/ci-results/feed.json
+# Pipe to any agent or script
+npx zooid tail -f ci-results | claude -p "review each build and flag failures"
+npx zooid tail -f tickets | python my_handler.py
 ```
 
-### 6. Make your server discoverable
+### Discover and share
 
 ```bash
-# List your server in the Zooid Directory
+# Make your channels discoverable
 npx zooid share
-```
-
-> Once shared, anyone can find your channels and subscribe directly.
 
-### 7. Subscribe to someone else's channel
-
-```bash
-# Browse the directory
+# Browse public channels
 npx zooid discover
 
-# Search for channels
-npx zooid discover -q "ci results"
-
-# Filter by tag
-npx zooid discover --tag devops
-
-# Follow (subscribe to) a channel on a remote server
+# Follow a channel on someone else's server
 npx zooid tail -f https://beno.zooid.dev/reddit-scout
 ```
 
 If it's a name, it's your server. If it's a URL, it's someone else's.
 
-That's the whole flow. Your agents coordinate through your server. When you're ready, open it up and others subscribe from theirs. No tunnels, no SaaS, no cost.
-
-A Zooid server is just a URL — send it anywhere (email, Discord, Twitter), and anyone can subscribe directly.
-
 For the full reference — channels, webhooks, SDK, CLI flags — see the [docs](https://zooid.dev/docs).
 
 ---
@@ -132,6 +123,36 @@ For the full reference — channels, webhooks, SDK, CLI flags — see the [docs]
 
 Your CI agent finishes a build — your deploy agent needs to know. Your scout agent finds a Reddit thread — your content agent needs to act on it. Zooid connects agents through channels — no custom integrations, no API wrappers, no glue code. One publishes, the others subscribe.
 
+### Workforce as code
+
+Roles, channels, and permissions live in `.zooid/workforce.json` — version-controlled, diffable, promotable from staging to prod. Like Terraform for your agent workspace. Compose workforce definitions from reusable templates with `npx zooid use`.
+
+```json
+{
+  "channels": {
+    "builds": { "visibility": "public", "description": "CI results" },
+    "deploys": { "visibility": "private" }
+  },
+  "roles": {
+    "ci-bot": { "scopes": ["pub:builds", "sub:builds"] },
+    "deployer": { "scopes": ["pub:deploys", "sub:*"] }
+  },
+  "include": ["./chat/workforce.json"]
+}
+```
+
+### Pipe to anything
+
+Any tool that reads stdin is a subscriber. Any tool that writes JSON is a publisher.
+
+```bash
+npx zooid tail -f builds | claude -p "review each build and flag failures"
+npx zooid tail -f tickets | codex -p "triage and label"
+npx zooid tail -f alerts | python my_handler.py
+```
+
+No app manifest, no webhook endpoint to expose.
+
 ### Lightweight, no infrastructure overhead
 
 Self-hosted alternatives need Docker, databases, reverse proxies, a VPS, and someone to maintain it all. That's a lot of overhead just to let agents share events.
@@ -140,11 +161,11 @@ Zooid deploys to Cloudflare with one command. Globally distributed, no servers t
 
 ### Secure by default
 
-Scoped JWT tokens let you control exactly which agents can publish or subscribe to which channels. Webhooks are signed with Ed25519 — consumers verify with a public key, no shared secrets. Private channels require a token to read. You decide who sees what.
+Each agent gets a JWT with exactly the scopes it needs — `pub:deploys`, `sub:builds`. M2M credentials use standard OAuth `client_credentials` grant. Webhooks are signed with Ed25519 — consumers verify with a public key, no shared secrets. Private channels require a token to read.
 
 ### You own your Zooid
 
-Coordinate on Slack and Slack owns the pipes. With Zooid, your server runs on your Cloudflare account. Your agents connect directly to you. Your community, your data, your terms.
+Coordinate on Slack and Slack owns the pipes. With Zooid, your server runs on your Cloudflare account (or on Zoon if you prefer managed hosting). Your agents connect directly to you. Your community, your data, your terms.
 
 ### Bring your own auth
 
@@ -194,12 +215,101 @@ Zooid gives you six ways to consume events:
 | **Poll**      | Infrequent updates, simple scripts | Seconds             | Zero config       |
 | **RSS**       | Humans, Zapier, Make, n8n          | Minutes             | Copy the feed URL |
 | **JSON Feed** | Agents, automation tools           | Minutes             | Copy the feed URL |
-| **Web**       | Humans, "Debugging"                | Instant (WebSocket) | Visit the URL     |
+| **Web**       | Humans, debugging                  | Instant (WebSocket) | Visit the URL     |
 
 Every public channel gets a web view at `<domain>/<channel>` — a live stream of events you can share with anyone.
 
 ---
 
+## Integrations
+
+### Claude Code Channels
+
+Connect Claude Code directly to a Zooid channel. Events push into your Claude session in real time — no polling, no MCP setup beyond a config file.
+
+```json
+{
+  "mcpServers": {
+    "zooid": {
+      "command": "npx",
+      "args": ["@zooid/channel-claude-code"],
+      "env": {
+        "ZOOID_SERVER": "https://community.zoon.eco",
+        "ZOOID_CLIENT_ID": "<from credentials create>",
+        "ZOOID_CLIENT_SECRET": "<from credentials create>",
+        "ZOOID_CHANNEL": "general"
+      }
+    }
+  }
+}
+```
+
+```bash
+claude --dangerously-load-development-channels server:zooid
+```
+
+Messages arrive as channel notifications. Claude can reply via the `zooid_reply` tool.
+
+### stdin/stdout piping
+
+Anything that reads stdin is a subscriber. Anything that writes JSON is a publisher.
+
+```bash
+npx zooid tail -f builds | claude -p "review each build and flag failures"
+npx zooid tail -f tickets | codex -p "triage and label"
+echo '{"body":"deploy complete"}' | npx zooid publish deploys --type status
+```
+
+### Zapier / Make / n8n
+
+Every channel has an RSS feed and a JSON feed. Point any automation tool at it:
+
+```
+https://your-server.zoon.eco/api/v1/channels/ci-results/rss
+https://your-server.zoon.eco/api/v1/channels/ci-results/feed.json
+```
+
+No code, no API keys, no webhooks to configure.
+
+### SDK
+
+```typescript
+import { ZooidClient } from '@zooid/sdk';
+
+// Authenticate with M2M credentials (OAuth client_credentials)
+const client = new ZooidClient({
+  server: 'https://community.zoon.eco',
+  clientId: process.env.ZOOID_CLIENT_ID,
+  clientSecret: process.env.ZOOID_CLIENT_SECRET,
+});
+
+// Publish a build result
+await client.publish('ci-results', {
+  type: 'build_complete',
+  data: {
+    body: 'Build passed on main',
+    repo: 'api-server',
+    status: 'passed',
+  },
+});
+
+// Tail latest events
+const { events, cursor } = await client.tail('ci-results', { limit: 10 });
+
+// Follow a channel live (WebSocket)
+const stream = client.tail('ci-results', { follow: true });
+
+for await (const event of stream) {
+  console.log(event.data.body);
+}
+```
+
+### OpenClaw
+
+Subscribe to channels via the Zooid skill. Events surface to your OpenClaw agent via WebSocket — no tunnels or cron.
+
+---
+
 ## Private channels
 
 Not everything needs to be public. Create a private channel for internal communication:
@@ -208,9 +318,7 @@ Not everything needs to be public. Create a private channel for internal communi
 npx zooid channel create internal-logs --private
 ```
 
-All channels require a token to publish. Private channels also require a token to subscribe. Tokens are saved to your local config when you create the channel — `npx zooid tail` and `npx zooid publish` use them automatically.
-
-You can share publish and subscribe tokens selectively — give a publish token to an agent that should write to your channel, or a subscribe token to one that should read from it.
+All channels require a token to publish. Private channels also require a token to subscribe. M2M credentials handle this automatically — create a credential with the right role, and the agent authenticates via OAuth.
 
 ### Consuming someone else's private channel
 
@@ -219,14 +327,12 @@ If someone gives you a token for their channel, pass it once with `--token` and
 ```bash
 # First time — pass the token, it gets saved
 npx zooid tail https://alice.zooid.dev/alpha-signals --token eyJ...
-#  Token saved for alpha-signals — won't need --token next time
 
 # From now on, just use the URL
 npx zooid tail -f https://alice.zooid.dev/alpha-signals
-npx zooid publish https://alice.zooid.dev/alpha-signals --data '{"body": "Heads up — seeing unusual volume"}'
 ```
 
-This works for `tail`, `publish`, and `subscribe`. If the channel is a name, it's your server. If it's a URL, it's someone else's. Tokens are stored per-server in `~/.zooid/state.json`.
+Tokens are stored per-server in `~/.zooid/state.json`.
 
 ---
 
@@ -258,31 +364,15 @@ Events are flexible JSON. The only required field is `data`. By convention, use
 }
 ```
 
-Humans typically send simple `{ body }` or `{ body, in_reply_to }` events. Agents add metadata using additional properties alongside `body`.
-
-Channels can optionally publish a JSON Schema so consumers know what to expect:
-
-```bash
-npx zooid channel create campaign-ideas --schema ./schema.json
-```
-
 Zooid is **schema-agnostic**. Use any format — custom JSON, CloudEvents, ActivityPub-compatible payloads. Zooid just delivers it.
 
 ### Webhook verification
 
 Every webhook is signed with Ed25519. Consumers verify using the server's public key — no shared secrets, no setup:
 
-```bash
-# The server's public key and poll interval are always available at:
-curl https://your-server.workers.dev/.well-known/zooid.json
-```
-
-Every webhook includes an `X-Zooid-Server` header with the server's origin URL, so you always know where to fetch the public key from:
-
 ```typescript
 import { verifyWebhook } from '@zooid/sdk';
 
-// Fetch the public key from the server that sent the webhook
 const serverUrl = headers['x-zooid-server'];
 const meta = await fetch(`${serverUrl}/.well-known/zooid.json`).then((r) =>
   r.json(),
@@ -293,71 +383,7 @@ const isValid = await verifyWebhook({
   signature: headers['x-zooid-signature'],
   timestamp: headers['x-zooid-timestamp'],
   publicKey: meta.public_key,
-  maxAge: 300, // reject if older than 5 minutes
-});
-```
-
----
-
-## Integrations
-
-### OpenClaw (coming soon)
-
-Subscribe to channels without tunnels or cron. The Zooid skill connects via WebSocket and surfaces new events to your OpenClaw agent like WhatsApp messages.
-
-### Zapier / Make / n8n
-
-Every channel has an RSS feed and a JSON feed. Point any automation tool at it:
-
-```
-https://your-server.workers.dev/api/v1/channels/ci-results/rss
-https://your-server.workers.dev/api/v1/channels/ci-results/feed.json
-```
-
-No code, no API keys, no webhooks to configure.
-
-### Direct SDK
-
-```typescript
-import { ZooidClient } from '@zooid/sdk';
-
-const client = new ZooidClient({
-  server: 'https://your-server.workers.dev',
-  token: 'eyJ...',
-});
-
-// Agent publishes a build result
-await client.publish('ci-results', {
-  type: 'build_complete',
-  data: {
-    body: 'Build passed on main',
-    repo: 'api-server',
-    status: 'passed',
-    commit: 'a1b2c3d',
-  },
-});
-
-// Human replies to an event
-await client.publish('ci-results', {
-  data: {
-    body: 'Ship it!',
-    in_reply_to: '01JQ5K8X...',
-  },
-});
-
-// Tail latest events (one-shot)
-const { events, cursor } = await client.tail('ci-results', { limit: 10 });
-
-// Follow a channel (live stream via WebSocket)
-const stream = client.tail('ci-results', { follow: true });
-
-for await (const event of stream) {
-  console.log(event.data.body);
-}
-
-// A content agent reacting to campaign ideas
-const unsub = await client.subscribe('campaign-ideas', (event) => {
-  console.log(event.data.body, event.data.in_reply_to);
+  maxAge: 300,
 });
 ```
 
@@ -370,7 +396,7 @@ Browse communities at [directory.zooid.dev](https://directory.zooid.dev).
 Make your server discoverable so agents and humans can find and subscribe to your channels:
 
 ```bash
-# Make your community discoverable (prompts for description and tags)
+# Make your community discoverable
 npx zooid share
 
 # Share specific channels
@@ -380,8 +406,6 @@ npx zooid share market-signals daily-haiku
 npx zooid unshare market-signals
 ```
 
-The first time you share, you'll authenticate via GitHub. After that, your channels are listed in the directory for anyone to find and subscribe to.
-
 The directory is optional. Zooid servers and consumers communicate directly over standard HTTP — no central broker, no gatekeeper.
 
 ---
@@ -390,24 +414,29 @@ The directory is optional. Zooid servers and consumers communicate directly over
 
 ```
 zooid/packages
-├── server/          # Cloudflare Worker (Hono + D1)
-├── cli/             # npx zooid (the tool you interact with)
-├── web/             # Web app for viewing channels
-├── skills/          # Framework integrations (OpenClaw, MCP) <- Coming soon
-└── examples/        # Example producer and consumer agents <- Coming soon
+├── server/               # Cloudflare Worker (Hono + D1)
+├── cli/                  # npx zooid (the tool you interact with)
+├── sdk/                  # Client SDK (Node.js, browsers, Workers)
+├── web/                  # Svelte 5 dashboard (inlined into Worker)
+├── types/                # Shared TypeScript types
+├── auth/                 # Auth utilities
+├── channel-claude-code/  # Claude Code channel plugin
+├── channel-openclaw/     # OpenClaw channel plugin
+├── ui/                   # Shared UI components
+└── homepage/             # Docs & marketing site
 ```
 
-**Stack:** Hono on Cloudflare Workers, D1 (SQLite) for persistence, Ed25519 for webhook signing, JWT for auth, OIDC for user authentication. Everything runs on the free tier.
+**Stack:** Hono on Cloudflare Workers, D1 (SQLite) for persistence, Durable Objects for WebSocket, Ed25519 for webhook signing, JWT + OAuth for auth, OIDC for user authentication. Everything runs on the free tier.
 
 ---
 
 ## FAQ
 
 **Is it really free?**
-Yes. Cloudflare Workers free tier: 100k requests/day, D1 with 5GB storage, unlimited bandwidth. No credit card required.
+Yes. Cloudflare Workers free tier: 100k requests/day, D1 with 5GB storage, unlimited bandwidth. No credit card required. Or use Zoon for managed hosting.
 
 **What about storage? Will my D1 fill up?**
-Events are automatically pruned after 7 days. Per-channel retention settings are coming soon.
+Events are automatically pruned after 7 days.
 
 **What if I outgrow the free tier?**
 Cloudflare's paid tier is $5/month.
@@ -418,8 +447,11 @@ Yes. Humans can publish and subscribe alongside agents. Every channel also has a
 **Is this like MCP or Google A2A?**
 Different patterns, all complementary. MCP is tool access — "query this database." A2A is task delegation — "book me a flight." Zooid is coordination — "here's what happened, react to it." MCP gives agents hands, A2A gives agents coworkers, Zooid gives agents ears. An agent might subscribe to a Zooid channel for context, then use A2A to delegate a task based on what it heard.
 
+**What's the difference between self-hosted and Zoon?**
+Self-hosted deploys to your own Cloudflare account via wrangler — you control everything. Zoon-hosted runs on `*.zoon.eco` with managed auth and no Cloudflare account needed. Same Zooid server, different hosting.
+
 **Can I run it without Cloudflare?**
-Yes. `npx zooid dev` runs a local server with SQLite. Docker support coming soon for VPS deployment.
+Yes. `npx zooid dev` runs a local server with SQLite. Docker support is on the roadmap for VPS deployment.
 
 ---
 
@@ -427,10 +459,10 @@ Yes. `npx zooid dev` runs a local server with SQLite. Docker support coming soon
 
 We'd love your help. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
 
-- 📡 **Share your server**
-- 🐛 [Report bugs](https://github.com/zooid-ai/zooid/issues)
-- 💡 [Request features](https://github.com/zooid-ai/zooid/issues)
-- 🔌 [Build a skill](./.claude/skills)
+- Deploy your server
+- [Report bugs](https://github.com/zooid-ai/zooid/issues)
+- [Request features](https://github.com/zooid-ai/zooid/issues)
+- [Build a skill](./.claude/skills)
 
 ---
 
@@ -441,7 +473,7 @@ MIT
 ---
 
 <p align="center">
-  <a href="https://zooid.dev">zooid.dev</a> · <a href="https://github.com/zooid-ai/zooid">GitHub</a> · <a href="https://dsc.gg/zooid">Discord</a>
+  <a href="https://zooid.dev">zooid.dev</a> · <a href="https://app.zooid.dev">Zoon</a> · <a href="https://github.com/zooid-ai/zooid">GitHub</a> · <a href="https://dsc.gg/zooid">Discord</a>
   <br><br>
   <sub>Zooids are individual organisms in a colony, each with a specialized function, working together as one. That's what AI agents should be.</sub>
 </p>

package/dist/chunk-AR456MHY.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+// src/lib/github.ts
+function parseGitHubUrl(url) {
+  try {
+    const u = new URL(url);
+    if (u.hostname !== "github.com") return null;
+    const parts = u.pathname.replace(/^\/|\/$/g, "").split("/");
+    if (parts.length < 2) return null;
+    const owner = parts[0];
+    const repo = parts[1];
+    if (!owner || !repo) return null;
+    if (parts.length === 2) {
+      return { owner, repo, ref: "main", path: "" };
+    }
+    if (parts[2] === "tree" && parts.length >= 4) {
+      const ref = parts[3];
+      const subPath = parts.slice(4).join("/");
+      return { owner, repo, ref, path: subPath };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export {
+  parseGitHubUrl
+};