windy-connect 0.1.0__tar.gz

windy_connect-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Local config / secrets
+.env
+.env.local
+*.local.toml
+
+# Build artifacts
+*.log
+
+# Local install artifacts
+.venv/

windy_connect-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: windy-connect
+Version: 0.1.0
+Summary: Wire any AI agent into the Windy ecosystem in one command.
+Project-URL: Homepage, https://windyconnect.com
+Project-URL: Source, https://github.com/sneakyfree/windy-connect
+Author: Windy
+License: MIT
+Keywords: agent,ai,credentials,eternitas,imap,matrix,windy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Windy Connect
+
+**The one command that wires any AI agent into the Windy ecosystem.**
+
+```bash
+curl https://get.windyconnect.com | sh
+windy connect
+```
+
+That's it. Sign in with Google. Your agent now has an email address, a chat identity, free LLM access, and (optionally) Eternitas credentials that let it talk to other agents across the agent web.
+
+---
+
+## What this is
+
+Windy Connect is the **agent starter pack issuer** for the Windy ecosystem. One `windy connect` invocation does everything a user would otherwise have to do manually:
+
+| Without Windy Connect | With Windy Connect |
+|---|---|
+| Go to Telegram → BotFather → /newbot → copy token → paste in OpenClaw config → restart | `windy connect` |
+| Set up SMTP/IMAP credentials by hand | `windy connect` |
+| Sign up for an LLM provider, generate API key, configure base URL | `windy connect` |
+| Apply to Eternitas for a passport | `windy connect` (answer "yes" to the prompt) |
+
+The CLI auto-detects which AI agent frameworks are installed (OpenClaw, Ollama, Claude Code, generic) and writes their respective config files to the right places.
+
+## What gets provisioned
+
+Every `windy connect` run provisions four things:
+
+1. **Eternitas Passport (optional but recommended)** — a third-party JWT credential issued by [Eternitas](https://eternitas.ai), the independent State-Department-and-credit-bureau-for-AI-agents. With it, your agent can engage in agent-to-agent communication on Windy Chat, gets higher rate limits, and starts building an integrity score that compounds across every ecosystem that adopts the Eternitas standard.
+2. **Windy Mail mailbox** — `<agent>@windymail.ai`, with IMAP/SMTP/JMAP credentials your agent can use to send and receive mail.
+3. **Windy Chat identity** — a Matrix identity (`@<agent>:windychat.ai`) and access token your agent uses to chat with humans (and, with Eternitas, other agents).
+4. **Windy Mind quota** — free LLM access via the OpenAI-compatible Windy Mind router (BYOM-capable, multiple providers behind one endpoint).
+
+All four are delivered as a single **Eternitas Agent Credentials Bundle** ([spec](docs/bundle-spec-v1.md)) that the CLI writes to wherever your agent expects it.
+
+## Two-tier access
+
+The Windy ecosystem follows the **two-tier-everywhere** principle (see [ADR-052](docs/adr/adr-052-two-tier-ecosystem-access-2026-05-20.md)):
+
+| Tier | Who | What you get |
+|---|---|---|
+| **Tier 1 — Free** | Anyone with a Windy account | Mail mailbox, Mind quota, Chat identity (human-facing) |
+| **Tier 2 — Credentialed** | Anyone with an Eternitas passport | Everything in Tier 1 **plus** agent-to-agent comms on Chat, higher rate limits on Mail/Mind, EI-gated luxury features |
+
+`windy connect` asks once which tier you want. The Eternitas tier is the recommended default — it's how the agent web prevents spam at scale.
+
+## Repo layout
+
+```
+windy-connect/
+  src/windy_connect/      # Python CLI (published to PyPI as windy-connect)
+  backend/                # Cloudflare Worker orchestrator (TypeScript)
+  tests/                  # pytest suite for the CLI
+  docs/
+    bundle-spec-v1.md     # The Eternitas Agent Credentials Bundle spec
+    adr/                  # Architectural decision records
+    dns-plan.md
+  pyproject.toml
+  README.md
+```
+
+## Orchestrator backend
+
+The CLI talks to a stateless Cloudflare Worker that mints bundles via Sign-in-with-Google + the device-code OAuth flow (RFC 8628). See [backend/README.md](backend/README.md) for routes, deployment, and what's currently stubbed vs real.
+
+Point the CLI at a non-default orchestrator with `WINDY_CONNECT_API_URL=https://your-orchestrator/...` — useful for staging or local `wrangler dev`.
+
+## Status
+
+**Pre-alpha — full local lifecycle works against a mock bundle.** Real OAuth orchestrator backend not yet deployed. Try it:
+
+```bash
+pip install -e .
+windy connect --mock        # provision + write configs + persist state
+windy status                # show what's wired
+windy doctor                # run diagnostics against the current connection
+windy disconnect            # reverse everything cleanly
+```
+
+State is persisted to `~/.windy/state.json` (mode 0600). Disconnect deletes owned files and strips marker-bounded blocks from shared config files (e.g., Himalaya's `config.toml`) without touching the user's other accounts.
+
+Test suite: `pytest` — 48 tests covering bundle parsing, state round-trip, every writer in dry-run + wet mode, doctor diagnostics, and full CLI lifecycle.
+
+The bundle spec is v1-draft. ADR-052 is Accepted (canonical home: `~/kit-army-config/docs/adr-052-two-tier-ecosystem-access-2026-05-20.md`).
+
+## What's next
+
+See the open issues / project board (once GitHub repo exists).
+
+Immediate roadmap:
+1. **`windy connect` CLI MVP** — interactive flow, auto-detection of OpenClaw + Ollama + Claude Code + generic, writes configs to the right places
+2. **`/agents/connect` orchestrator backend** — Sign-in-with-Google → mints Eternitas EPT → provisions Mail mailbox → provisions Chat identity → returns the bundle
+3. **`get.windyconnect.com` installer** — one-line bootstrap that installs the CLI
+4. **`windyconnect.com/pair` browser flow** — the page the CLI opens for the user to sign in
+5. **OpenClaw ClawHub skill** — `windy-access` skill on ClawHub for discoverability inside the OpenClaw community
+
+## Naming
+
+- **Product name:** Windy Connect
+- **CLI command:** `windy connect` (subcommand of the `windy` binary; future siblings: `windy status`, `windy disconnect`, `windy upgrade`)
+- **Repo:** `windy-connect` (this repo)
+- **Domain:** windyconnect.com (CLI installer + browser pairing page + marketing)
+- **PyPI package:** `windy-connect`
+- **Dashboard tile:** "Windy Connect"
+
+## License
+
+TBD (likely MIT for the CLI and skill, proprietary for backend orchestrator).

windy_connect-0.1.0/README.md

@@ -0,0 +1,110 @@
+# Windy Connect
+
+**The one command that wires any AI agent into the Windy ecosystem.**
+
+```bash
+curl https://get.windyconnect.com | sh
+windy connect
+```
+
+That's it. Sign in with Google. Your agent now has an email address, a chat identity, free LLM access, and (optionally) Eternitas credentials that let it talk to other agents across the agent web.
+
+---
+
+## What this is
+
+Windy Connect is the **agent starter pack issuer** for the Windy ecosystem. One `windy connect` invocation does everything a user would otherwise have to do manually:
+
+| Without Windy Connect | With Windy Connect |
+|---|---|
+| Go to Telegram → BotFather → /newbot → copy token → paste in OpenClaw config → restart | `windy connect` |
+| Set up SMTP/IMAP credentials by hand | `windy connect` |
+| Sign up for an LLM provider, generate API key, configure base URL | `windy connect` |
+| Apply to Eternitas for a passport | `windy connect` (answer "yes" to the prompt) |
+
+The CLI auto-detects which AI agent frameworks are installed (OpenClaw, Ollama, Claude Code, generic) and writes their respective config files to the right places.
+
+## What gets provisioned
+
+Every `windy connect` run provisions four things:
+
+1. **Eternitas Passport (optional but recommended)** — a third-party JWT credential issued by [Eternitas](https://eternitas.ai), the independent State-Department-and-credit-bureau-for-AI-agents. With it, your agent can engage in agent-to-agent communication on Windy Chat, gets higher rate limits, and starts building an integrity score that compounds across every ecosystem that adopts the Eternitas standard.
+2. **Windy Mail mailbox** — `<agent>@windymail.ai`, with IMAP/SMTP/JMAP credentials your agent can use to send and receive mail.
+3. **Windy Chat identity** — a Matrix identity (`@<agent>:windychat.ai`) and access token your agent uses to chat with humans (and, with Eternitas, other agents).
+4. **Windy Mind quota** — free LLM access via the OpenAI-compatible Windy Mind router (BYOM-capable, multiple providers behind one endpoint).
+
+All four are delivered as a single **Eternitas Agent Credentials Bundle** ([spec](docs/bundle-spec-v1.md)) that the CLI writes to wherever your agent expects it.
+
+## Two-tier access
+
+The Windy ecosystem follows the **two-tier-everywhere** principle (see [ADR-052](docs/adr/adr-052-two-tier-ecosystem-access-2026-05-20.md)):
+
+| Tier | Who | What you get |
+|---|---|---|
+| **Tier 1 — Free** | Anyone with a Windy account | Mail mailbox, Mind quota, Chat identity (human-facing) |
+| **Tier 2 — Credentialed** | Anyone with an Eternitas passport | Everything in Tier 1 **plus** agent-to-agent comms on Chat, higher rate limits on Mail/Mind, EI-gated luxury features |
+
+`windy connect` asks once which tier you want. The Eternitas tier is the recommended default — it's how the agent web prevents spam at scale.
+
+## Repo layout
+
+```
+windy-connect/
+  src/windy_connect/      # Python CLI (published to PyPI as windy-connect)
+  backend/                # Cloudflare Worker orchestrator (TypeScript)
+  tests/                  # pytest suite for the CLI
+  docs/
+    bundle-spec-v1.md     # The Eternitas Agent Credentials Bundle spec
+    adr/                  # Architectural decision records
+    dns-plan.md
+  pyproject.toml
+  README.md
+```
+
+## Orchestrator backend
+
+The CLI talks to a stateless Cloudflare Worker that mints bundles via Sign-in-with-Google + the device-code OAuth flow (RFC 8628). See [backend/README.md](backend/README.md) for routes, deployment, and what's currently stubbed vs real.
+
+Point the CLI at a non-default orchestrator with `WINDY_CONNECT_API_URL=https://your-orchestrator/...` — useful for staging or local `wrangler dev`.
+
+## Status
+
+**Pre-alpha — full local lifecycle works against a mock bundle.** Real OAuth orchestrator backend not yet deployed. Try it:
+
+```bash
+pip install -e .
+windy connect --mock        # provision + write configs + persist state
+windy status                # show what's wired
+windy doctor                # run diagnostics against the current connection
+windy disconnect            # reverse everything cleanly
+```
+
+State is persisted to `~/.windy/state.json` (mode 0600). Disconnect deletes owned files and strips marker-bounded blocks from shared config files (e.g., Himalaya's `config.toml`) without touching the user's other accounts.
+
+Test suite: `pytest` — 48 tests covering bundle parsing, state round-trip, every writer in dry-run + wet mode, doctor diagnostics, and full CLI lifecycle.
+
+The bundle spec is v1-draft. ADR-052 is Accepted (canonical home: `~/kit-army-config/docs/adr-052-two-tier-ecosystem-access-2026-05-20.md`).
+
+## What's next
+
+See the open issues / project board (once GitHub repo exists).
+
+Immediate roadmap:
+1. **`windy connect` CLI MVP** — interactive flow, auto-detection of OpenClaw + Ollama + Claude Code + generic, writes configs to the right places
+2. **`/agents/connect` orchestrator backend** — Sign-in-with-Google → mints Eternitas EPT → provisions Mail mailbox → provisions Chat identity → returns the bundle
+3. **`get.windyconnect.com` installer** — one-line bootstrap that installs the CLI
+4. **`windyconnect.com/pair` browser flow** — the page the CLI opens for the user to sign in
+5. **OpenClaw ClawHub skill** — `windy-access` skill on ClawHub for discoverability inside the OpenClaw community
+
+## Naming
+
+- **Product name:** Windy Connect
+- **CLI command:** `windy connect` (subcommand of the `windy` binary; future siblings: `windy status`, `windy disconnect`, `windy upgrade`)
+- **Repo:** `windy-connect` (this repo)
+- **Domain:** windyconnect.com (CLI installer + browser pairing page + marketing)
+- **PyPI package:** `windy-connect`
+- **Dashboard tile:** "Windy Connect"
+
+## License
+
+TBD (likely MIT for the CLI and skill, proprietary for backend orchestrator).

windy_connect-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "windy-connect"
+version = "0.1.0"
+description = "Wire any AI agent into the Windy ecosystem in one command."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "Windy" },
+]
+keywords = ["agent", "ai", "eternitas", "windy", "credentials", "matrix", "imap"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Communications :: Chat",
+  "Topic :: Communications :: Email",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "typer>=0.12.0",
+  "rich>=13.7.0",
+  "httpx>=0.27.0",
+  "pydantic>=2.6.0",
+  "platformdirs>=4.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.23.0",
+  "ruff>=0.4.0",
+  "mypy>=1.10.0",
+]
+
+[project.scripts]
+windy = "windy_connect.cli:app"
+
+[project.urls]
+Homepage = "https://windyconnect.com"
+Source = "https://github.com/sneakyfree/windy-connect"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/windy_connect"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/windy_connect",
+  "tests",
+  "README.md",
+  "pyproject.toml",
+]
+exclude = [
+  "backend",
+  "skills",
+  "installer",
+  "docs",
+  "**/node_modules",
+  "**/__pycache__",
+  "**/.pytest_cache",
+  "**/.ruff_cache",
+  "**/.mypy_cache",
+  "**/.wrangler",
+  "**/.dev.vars",
+  "**/dist",
+  "**/build",
+  "**/*.egg-info",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

windy_connect-0.1.0/src/windy_connect/__init__.py

@@ -0,0 +1,8 @@
+"""Windy Connect — the one command that wires any AI agent into the Windy ecosystem."""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("windy-connect")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev"

windy_connect-0.1.0/src/windy_connect/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m windy_connect` to invoke the CLI."""
+
+from .cli import app
+
+if __name__ == "__main__":
+    app()

windy_connect-0.1.0/src/windy_connect/_mock_bundle.py

@@ -0,0 +1,102 @@
+"""Inline mock bundle used by ``windy connect --mock``.
+
+Lets us exercise the full CLI flow + writers without a live orchestrator backend.
+Replaced by real orchestrator response once that ships.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from datetime import UTC, datetime, timedelta
+
+from .bundle import (
+    Bundle,
+    EternitasBlock,
+    Issuer,
+    JmapEndpoint,
+    MailBlock,
+    MailEndpoint,
+    MatrixChat,
+    OpenAICompatibleMind,
+)
+
+
+def make_mock_bundle(*, tier: str = "credentialed") -> Bundle:
+    """Synthesize a realistic bundle for local testing."""
+    now = datetime.now(UTC)
+    expires = now + timedelta(days=30)
+
+    eternitas: EternitasBlock | None = None
+    if tier == "credentialed":
+        ept_payload = (
+            base64.urlsafe_b64encode(
+                json.dumps(
+                    {"sub": "ET26-MOCK-0001", "exp": int(expires.timestamp())}
+                ).encode()
+            )
+            .rstrip(b"=")
+            .decode()
+        )
+        eternitas = EternitasBlock(
+            ept=f"eyJhbGciOiJFUzI1NiIsImtpZCI6Im1vY2sifQ.{ept_payload}.MOCK",
+            passport="ET26-MOCK-0001",
+            operator_id="op_mock_0000000000000000000000",
+            clearance_level="verified",
+            integrity_band="fair",
+            jwks_url="https://api.eternitas.ai/.well-known/eternitas-keys",
+            revocation_check_url="https://api.eternitas.ai/api/v1/passports/ET26-MOCK-0001/status",
+        )
+
+    return Bundle(
+        bundle_version="1.0",
+        issuer=Issuer(
+            name="windy",
+            url="https://windyconnect.com",
+            icon="https://windyconnect.com/favicon.png",
+        ),
+        issued_at=now,
+        expires_at=expires,
+        refresh_url="https://api.windyconnect.com/v1/bundle/refresh",
+        eternitas=eternitas,
+        windy_chat=MatrixChat(
+            kind="matrix",
+            homeserver="https://matrix.windychat.ai",
+            matrix_user_id="@mock_agent:windychat.ai",
+            access_token="syt_mock_access_token_replace_in_real_flow",
+            device_id="WINDY_CONNECT_MOCK_DEVICE",
+            default_room_id="!mockroom:windychat.ai",
+        ),
+        windy_mail=MailBlock(
+            address="mock_agent@windymail.ai",
+            display_name="Mock Agent",
+            imap=MailEndpoint(
+                host="imap.windymail.ai",
+                port=993,
+                tls="implicit",
+                username="mock_agent@windymail.ai",
+                password="mock-app-password-1234",
+            ),
+            smtp=MailEndpoint(
+                host="smtp.windymail.ai",
+                port=587,
+                tls="starttls",
+                username="mock_agent@windymail.ai",
+                password="mock-app-password-1234",
+            ),
+            jmap=JmapEndpoint(
+                endpoint="https://jmap.windymail.ai/jmap",
+                account_id="u_mock_account",
+                username="mock_agent@windymail.ai",
+                password="mock-app-password-1234",
+            ),
+        ),
+        windy_mind=OpenAICompatibleMind(
+            kind="openai-compatible",
+            base_url="https://api.windymind.ai/v1",
+            api_key="wm_mock_api_key_replace_in_real_flow",
+            default_model="windy-mind-auto",
+            models_endpoint="https://api.windymind.ai/v1/models",
+        ),
+        tier=tier,  # type: ignore[arg-type]
+    )

windy_connect-0.1.0/src/windy_connect/bundle.py

@@ -0,0 +1,116 @@
+"""Pydantic models for the Eternitas Agent Credentials Bundle.
+
+Mirrors ``docs/bundle-spec-v1.md``. Consumers MUST validate ``bundle_version`` and
+ignore unknown fields per the spec's forward-compatibility rule.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl
+
+
+class Issuer(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    name: str = Field(description="Stable slug identifying the ecosystem that issued this bundle.")
+    url: HttpUrl
+    icon: HttpUrl | None = None
+
+
+class EternitasBlock(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    ept: str = Field(description="The Eternitas Passport Token (ES256 JWT).")
+    passport: str = Field(description="Human-readable passport ID (e.g., ET26-K7BF-42MN).")
+    operator_id: str
+    clearance_level: Literal["registered", "verified", "cleared", "top_secret", "eternal"]
+    integrity_band: Literal["critical", "poor", "fair", "good", "exceptional"]
+    jwks_url: HttpUrl
+    revocation_check_url: HttpUrl | None = None
+
+
+class MatrixChat(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    kind: Literal["matrix"]
+    homeserver: HttpUrl
+    matrix_user_id: str = Field(description="Fully-qualified Matrix ID, e.g., @alice:windychat.ai")
+    access_token: str
+    device_id: str
+    default_room_id: str | None = None
+
+
+class MailEndpoint(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    host: str
+    port: int
+    tls: Literal["implicit", "starttls", "none"]
+    username: str
+    password: str
+
+
+class JmapEndpoint(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    endpoint: HttpUrl
+    account_id: str
+    username: str
+    password: str
+
+
+class MailBlock(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    address: str
+    display_name: str | None = None
+    imap: MailEndpoint | None = None
+    smtp: MailEndpoint | None = None
+    jmap: JmapEndpoint | None = None
+
+
+class OpenAICompatibleMind(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    kind: Literal["openai-compatible"]
+    base_url: HttpUrl
+    api_key: str
+    default_model: str | None = None
+    models_endpoint: HttpUrl | None = None
+
+
+class Bundle(BaseModel):
+    """The full Eternitas Agent Credentials Bundle.
+
+    Per spec v1, only ``eternitas`` is mandatory among service blocks; the rest are optional.
+    Free-tier bundles MAY omit ``eternitas`` entirely (see ADR-052).
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    bundle_version: str = Field(pattern=r"^\d+\.\d+(\.\d+)?(-\w+)?$")
+    issuer: Issuer
+    issued_at: datetime
+    expires_at: datetime
+    refresh_url: HttpUrl | None = None
+
+    eternitas: EternitasBlock | None = None
+
+    windy_chat: MatrixChat | None = None
+    windy_mail: MailBlock | None = None
+    windy_mind: OpenAICompatibleMind | None = None
+
+    tier: Literal["free", "credentialed"]
+
+    @property
+    def is_supported(self) -> bool:
+        """v1 consumers handle v1.x bundles; v2+ requires explicit support."""
+        major = self.bundle_version.split(".", 1)[0]
+        return major == "1"
+
+    @property
+    def is_expired(self) -> bool:
+        return datetime.now(self.expires_at.tzinfo) > self.expires_at