heyecco 0.1.0__py3-none-any.whl

ecco_cli/__init__.py

@@ -0,0 +1 @@
+"""Deterministic Ecco client setup; never a model or an auth server."""

ecco_cli/bootstrap.py

@@ -0,0 +1,282 @@
+"""Signup-free board bootstrap with caller-owned, private recovery state."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import secrets
+import subprocess
+import tempfile
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+CONTRACT = "ecco.signup-free.v1"
+DEFAULT_API = "https://api.heyecco.com"
+MAX_RESPONSE = 262_144
+
+
+class BootstrapFailure(ValueError):
+    pass
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect())
+
+
+def _sha(value: str) -> str:
+    return hashlib.sha256(value.encode()).hexdigest()
+
+
+def _state_root() -> Path:
+    if os.name == "nt":
+        base = os.environ.get("LOCALAPPDATA")
+        if not base:
+            raise BootstrapFailure("LOCALAPPDATA is required for private state.")
+        return Path(base) / "ecco" / "boards"
+    base = os.environ.get("XDG_STATE_HOME")
+    root = Path(base) if base else Path.home() / ".local" / "state"
+    return root / "ecco" / "boards"
+
+
+def _private_directory(path: Path) -> None:
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    if path.is_symlink() or not path.is_dir():
+        raise BootstrapFailure("State directory must be a real directory.")
+    if os.name != "nt":
+        status = path.stat()
+        if status.st_uid != os.getuid() or status.st_mode & 0o077:
+            raise BootstrapFailure("State directory must be private (mode 0700).")
+
+
+def _write_private(path: Path, data: bytes) -> None:
+    _private_directory(path.parent)
+    fd, temporary = tempfile.mkstemp(prefix=".ecco-state-", dir=path.parent)
+    try:
+        if os.name != "nt":
+            os.fchmod(fd, 0o600)
+        with os.fdopen(fd, "wb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+        temporary = ""
+        if os.name != "nt" and path.stat().st_mode & 0o077:
+            raise BootstrapFailure("Private state permissions could not be enforced.")
+    finally:
+        if temporary:
+            Path(temporary).unlink(missing_ok=True)
+
+
+def _read_private(path: Path) -> dict[str, Any]:
+    path = path.absolute()
+    if path != path.resolve() or not path.is_file():
+        raise BootstrapFailure("State must be a direct path to a regular file.")
+    status = path.stat()
+    if os.name != "nt" and (status.st_uid != os.getuid() or status.st_mode & 0o077):
+        raise BootstrapFailure("State file must be private (mode 0600).")
+    try:
+        value = json.loads(path.read_bytes())
+    except (OSError, ValueError, TypeError):
+        raise BootstrapFailure("State file is unavailable or invalid.") from None
+    if not isinstance(value, dict) or value.get("contract_version") != CONTRACT:
+        raise BootstrapFailure("State file uses an unsupported contract.")
+    return value
+
+
+def _api_origin(value: str) -> str:
+    parsed = urllib.parse.urlsplit(value)
+    if (
+        parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username
+        or parsed.password
+        or parsed.path not in {"", "/"}
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise BootstrapFailure("API base must be an exact HTTPS origin.")
+    return value.rstrip("/")
+
+
+def _request_json(
+    url: str, payload: dict[str, Any], *, attempt_id: str, recovery: str | None
+) -> tuple[int, dict[str, Any]]:
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "User-Agent": "ecco-cli/0.1",
+        "Idempotency-Key": attempt_id,
+    }
+    if recovery is not None:
+        headers["Ecco-Recovery"] = recovery
+    request = urllib.request.Request(
+        url, data=json.dumps(payload, separators=(",", ":")).encode(), headers=headers
+    )
+    try:
+        response = _OPENER.open(request, timeout=15)
+    except urllib.error.HTTPError as exc:
+        body = exc.read(MAX_RESPONSE + 1)
+        if len(body) > MAX_RESPONSE:
+            raise BootstrapFailure(f"Bootstrap failed with HTTP {exc.code}.") from None
+        try:
+            document = json.loads(body)
+        except (ValueError, TypeError):
+            document = {}
+        code = document.get("code") if isinstance(document, dict) else None
+        if not isinstance(code, str) or re.fullmatch(r"[a-z0-9_]{1,64}", code) is None:
+            code = None
+        raise BootstrapFailure(
+            f"Bootstrap failed with HTTP {exc.code}"
+            + (f" ({code})." if code is not None else ".")
+        ) from None
+    with response:
+        body = response.read(MAX_RESPONSE + 1)
+    if len(body) > MAX_RESPONSE:
+        raise BootstrapFailure("Bootstrap returned an oversized response.")
+    try:
+        document = json.loads(body)
+    except (ValueError, TypeError):
+        raise BootstrapFailure("Bootstrap returned invalid JSON.") from None
+    if not isinstance(document, dict) or document.get("contract_version") != CONTRACT:
+        raise BootstrapFailure("Bootstrap returned an unsupported contract.")
+    return response.status, document
+
+
+def create(
+    *,
+    board_name: str,
+    task_title: str | None,
+    task_body: str | None,
+    client_name: str,
+    client_version: str,
+    api_base: str = DEFAULT_API,
+    state_directory: Path | None = None,
+) -> dict[str, Any]:
+    api_base = _api_origin(api_base)
+    attempt_id = str(uuid4())
+    # Worker authentication intentionally reserves exact 64-character hex
+    # credentials; other bearer shapes are routed through OAuth.
+    worker = secrets.token_hex(32)
+    capability = secrets.token_urlsafe(32)
+    recovery = secrets.token_urlsafe(32)
+    payload: dict[str, Any] = {
+        "contract_version": CONTRACT,
+        "board_name": board_name,
+        "client": {"name": client_name, "version": client_version},
+        "worker_token_sha256": _sha(worker),
+        "claim_capability_sha256": _sha(capability),
+        "recovery_secret_sha256": _sha(recovery),
+    }
+    if task_title is not None:
+        payload["first_task"] = {"title": task_title, "body": task_body}
+    selected_root = state_directory or _state_root()
+    if selected_root.is_symlink():
+        raise BootstrapFailure("State directory cannot be a symbolic link.")
+    root = selected_root.expanduser().resolve()
+    state_path = root / f"{attempt_id}.json"
+    state: dict[str, Any] = {
+        "contract_version": CONTRACT,
+        "attempt_id": attempt_id,
+        "api_base": api_base,
+        "request": payload,
+        "worker_token": worker,
+        "claim_capability": capability,
+        "recovery_secret": recovery,
+        "manifest": None,
+    }
+    _write_private(state_path, json.dumps(state, separators=(",", ":")).encode())
+    try:
+        _, manifest = _request_json(
+            api_base + "/agent-start",
+            payload,
+            attempt_id=attempt_id,
+            recovery=None,
+        )
+    except (urllib.error.URLError, TimeoutError):
+        try:
+            _, manifest = _request_json(
+                api_base + "/agent-start",
+                payload,
+                attempt_id=attempt_id,
+                recovery=recovery,
+            )
+        except (urllib.error.URLError, TimeoutError) as exc:
+            raise BootstrapFailure(
+                f"Bootstrap outcome is unknown; retry with state {state_path}."
+            ) from exc
+    state["manifest"] = manifest
+    claim_base = manifest.get("claim", {}).get("url_base")
+    if not isinstance(claim_base, str):
+        raise BootstrapFailure("Bootstrap response omitted the claim URL.")
+    claim_file = root / f"{attempt_id}.claim-link.txt"
+    full_claim = claim_base + "#capability=" + urllib.parse.quote(capability, safe="")
+    _write_private(claim_file, (full_claim + "\n").encode())
+    _write_private(state_path, json.dumps(state, separators=(",", ":")).encode())
+    return _public_result(state_path, claim_file, manifest)
+
+
+def retry(state_path: Path) -> dict[str, Any]:
+    state = _read_private(state_path)
+    manifest = state.get("manifest")
+    if manifest is None:
+        _, manifest = _request_json(
+            _api_origin(str(state["api_base"])) + "/agent-start",
+            state["request"],
+            attempt_id=str(state["attempt_id"]),
+            recovery=str(state["recovery_secret"]),
+        )
+        state["manifest"] = manifest
+        _write_private(state_path, json.dumps(state, separators=(",", ":")).encode())
+    claim_file = state_path.with_name(state_path.stem + ".claim-link.txt")
+    claim_base = manifest["claim"]["url_base"]
+    value = (
+        claim_base
+        + "#capability="
+        + urllib.parse.quote(str(state["claim_capability"]), safe="")
+    )
+    _write_private(claim_file, (value + "\n").encode())
+    return _public_result(state_path, claim_file, manifest)
+
+
+def run(state_path: Path, command: list[str]) -> int:
+    if not command:
+        raise BootstrapFailure("Resume requires a command after --.")
+    state = _read_private(state_path)
+    manifest = state.get("manifest")
+    if not isinstance(manifest, dict):
+        raise BootstrapFailure("Bootstrap is incomplete; retry it first.")
+    environment = os.environ.copy()
+    environment.update(
+        {
+            "ECCO_AGENT_TOKEN": str(state["worker_token"]),
+            "ECCO_MCP_URL": str(manifest["connection"]["mcp_url"]),
+            "ECCO_WORKSPACE_ID": str(manifest["board"]["workspace_id"]),
+        }
+    )
+    return subprocess.run(command, env=environment, check=False).returncode
+
+
+def _public_result(
+    state_path: Path, claim_file: Path, manifest: dict[str, Any]
+) -> dict[str, Any]:
+    return {
+        "status": "ready",
+        "board": manifest.get("board"),
+        "first_task": manifest.get("first_task"),
+        "connection": manifest.get("connection"),
+        "limits": manifest.get("limits"),
+        "claim_url_base": manifest.get("claim", {}).get("url_base"),
+        "state_file": str(state_path),
+        "claim_link_file": str(claim_file),
+        "secrets_printed": False,
+    }

ecco_cli/discovery.py

@@ -0,0 +1,161 @@
+"""Find explicit native config targets without reading credential stores.
+
+Inventory is deliberately conservative: duplicate names require resolution in
+the native client rather than guessing about trust, launch flags or profiles.
+This does not claim to reproduce a running client's effective configuration.
+"""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import tomlkit
+
+from ecco_cli.files import snapshot
+from ecco_cli.migration import MigrationError
+from ecco_cli.serialization import _DECODER
+
+
+@dataclass(frozen=True)
+class Target:
+    path: Path
+    scope: str
+    project: str | None = None
+
+
+def native_target(*, client: str, name: str, scope: str, project: Path) -> Target:
+    """Resolve on-disk CLI config; do not inspect authentication caches."""
+    if client == "claude":
+        custom = os.environ.get("CLAUDE_CONFIG_DIR")
+        config_home = Path(custom) if custom else Path.home() / ".claude"
+        user_config = (config_home if custom else Path.home()) / ".claude.json"
+        directories = (
+            Path("/Library/Application Support/ClaudeCode"),
+            Path("/etc/claude-code"),
+        )
+        managed = tuple(
+            directory / filename
+            for directory in directories
+            for filename in (
+                "managed-mcp.json",
+                "managed-settings.json",
+                "managed-settings.d",
+            )
+        ) + (
+            config_home / "remote-settings.json",
+            Path("/Library/Managed Preferences/com.anthropic.claudecode.plist"),
+            Path("/Library/Managed Preferences")
+            / Path.home().name
+            / "com.anthropic.claudecode.plist",
+        )
+    else:
+        config_home = Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
+        user_config = config_home / "config.toml"
+        managed = (
+            Path("/etc/codex/requirements.toml"),
+            Path("/etc/codex/managed_config.toml"),
+            Path("/etc/codex/config.toml"),
+            config_home / "managed_config.toml",
+        )
+    return discover(
+        client=client,
+        name=name,
+        scope=scope,
+        project=project,
+        user_config=user_config,
+        managed_paths=managed,
+    )
+
+
+def _document(path: Path, client: str) -> dict:
+    if not path.exists() and not path.is_symlink():
+        return {}
+    try:
+        source = snapshot(path).content.decode("utf-8")
+        document = (
+            _DECODER.decode(source) if client == "claude" else tomlkit.parse(source)
+        )
+        if not isinstance(document, dict):
+            raise ValueError
+        return document
+    except MigrationError:
+        raise
+    except (ValueError, TypeError, RecursionError):
+        raise MigrationError("Cannot inspect native configuration safely.") from None
+
+
+def _contains(document: dict, key: str, name: str) -> bool:
+    entries = document.get(key, {})
+    if not isinstance(entries, dict):
+        raise MigrationError("Native MCP configuration is not an object.")
+    return name in entries
+
+
+def discover(
+    *,
+    client: str,
+    name: str,
+    scope: str,
+    project: Path,
+    user_config: Path,
+    managed_paths: tuple[Path, ...],
+) -> Target:
+    """Resolve one named CLI connector within supplied native config locations.
+
+    user_config is the native user's configuration file, resolved by the caller.
+    managed_paths includes system config/policy
+    files: their presence stops this migration, without reading their contents.
+    No fallback to another name, scope, workspace or credential is permitted.
+    """
+    if any(path.exists() or path.is_symlink() for path in managed_paths):
+        raise MigrationError("Managed configuration requires administrator review.")
+    if client not in {"claude", "codex"}:
+        raise MigrationError("Unsupported client.")
+    project = project.absolute()
+    if project != project.resolve() or not project.is_dir():
+        raise MigrationError("Select an existing, non-symlink project directory.")
+    found: list[Target] = []
+    if client == "claude":
+        user_path = user_config
+        user = _document(user_path, client)
+        if _contains(user, "mcpServers", name):
+            found.append(Target(user_path, "user"))
+        projects = user.get("projects", {})
+        if not isinstance(projects, dict):
+            raise MigrationError("Native project configuration is not an object.")
+        local = projects.get(str(project), {})
+        if not isinstance(local, dict):
+            raise MigrationError("Native project configuration is not an object.")
+        if _contains(local, "mcpServers", name):
+            found.append(Target(user_path, "local", str(project)))
+        path = project / ".mcp.json"
+        if _contains(_document(path, client), "mcpServers", name):
+            found.append(Target(path, "project"))
+    else:
+        path = user_config
+        user = _document(path, client)
+        if user.get("profile") or user.get("profiles"):
+            raise MigrationError("Profile configuration requires native-client review.")
+        if _contains(user, "mcp_servers", name):
+            found.append(Target(path, "user"))
+        # Include every ancestor conservatively. Even an untrusted project layer
+        # may become active later; migration must never silently trust that project.
+        for directory in (project, *project.parents):
+            path = directory / ".codex" / "config.toml"
+            if path == user_config:
+                continue
+            if _contains(_document(path, client), "mcp_servers", name):
+                found.append(Target(path, "project"))
+    if not found:
+        raise MigrationError("The selected connector was not found in native config.")
+    if len(found) != 1:
+        raise MigrationError(
+            "This connector name exists in multiple scopes or layers; "
+            "resolve the overlap in the native client before migrating."
+        )
+    target = found[0]
+    if target.scope != scope:
+        raise MigrationError(
+            "The connector exists in a different scope; select it explicitly."
+        )
+    return target

ecco_cli/files.py

@@ -0,0 +1,195 @@
+"""Guarded local configuration edits; caller selects and approves the target.
+
+Only POSIX is supported here. Advisory locks coordinate Ecco invocations, not
+arbitrary editors: close the native client while applying. Recheck content and
+inode immediately before the atomic replacement. Never auto-retry a conflict.
+"""
+
+import fcntl
+import os
+import stat
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ecco_cli.migration import MigrationError, Plan, UncertainWriteError
+from ecco_cli.serialization import MAX_CONFIG_BYTES, RenderedMigration, render
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    path: Path
+    device: int
+    inode: int
+    mode: int
+    content: bytes = field(repr=False)
+
+
+def _safe_path(path: Path) -> Path:
+    path = path.absolute()
+    if path != path.resolve():
+        raise MigrationError("Use a direct configuration path, not a symbolic link.")
+    parent = path.parent.stat()
+    if parent.st_uid != os.getuid() or parent.st_mode & 0o022:
+        raise MigrationError(
+            "Configuration directory must be owned and writable only by you."
+        )
+    return path
+
+
+def snapshot(path: Path) -> Snapshot:
+    """Read one bounded, owned, non-linked file without echoing its contents."""
+    try:
+        path = _safe_path(path)
+        fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+        with os.fdopen(fd, "rb") as stream:
+            before = os.fstat(stream.fileno())
+            if (
+                not stat.S_ISREG(before.st_mode)
+                or before.st_uid != os.getuid()
+                or before.st_nlink != 1
+                or before.st_mode & 0o022
+            ):
+                raise MigrationError(
+                    "Configuration must be an owned, non-linked regular file."
+                )
+            data = stream.read(MAX_CONFIG_BYTES + 1)
+            after = os.fstat(stream.fileno())
+            if len(data) > MAX_CONFIG_BYTES:
+                raise MigrationError("Configuration exceeds the supported size limit.")
+            if (before.st_mtime_ns, before.st_size) != (
+                after.st_mtime_ns,
+                after.st_size,
+            ):
+                raise MigrationError(
+                    "Configuration changed during read; preview again."
+                )
+            return Snapshot(
+                path, before.st_dev, before.st_ino, stat.S_IMODE(before.st_mode), data
+            )
+    except OSError:
+        raise MigrationError(
+            "Cannot safely access the selected configuration."
+        ) from None
+
+
+def preview(path: Path, **selection) -> tuple[Snapshot, RenderedMigration]:
+    current = snapshot(path)
+    return current, render(current.content, **selection)
+
+
+def _same(expected: Snapshot, current: Snapshot) -> bool:
+    return (
+        expected.path == current.path
+        and expected.device == current.device
+        and expected.inode == current.inode
+        and expected.mode == current.mode
+        and expected.content == current.content
+    )
+
+
+def apply(expected: Snapshot, edit: RenderedMigration) -> Path | None:
+    """Apply an approved preview and return a private recovery copy, if changed.
+
+    Callers must not present this as authenticated connectivity. No token cache
+    is opened, migrated or deleted. Recovery copies can contain existing config
+    secrets, so they are private (0600) and must never be printed or committed.
+    """
+    if edit.before != expected.content:
+        raise MigrationError("Preview does not belong to this configuration.")
+    if not edit.plan.changed:
+        if not _same(expected, snapshot(expected.path)):
+            raise MigrationError("Configuration changed after preview; preview again.")
+        return None
+    lock_path = expected.path.with_name(expected.path.name + ".ecco-lock")
+    temporary: str | None = None
+    replaced = False
+    try:
+        _safe_path(expected.path)
+        lock_fd = os.open(lock_path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+        with os.fdopen(lock_fd, "rb") as lock:
+            lock_stat = os.fstat(lock.fileno())
+            if (
+                not stat.S_ISREG(lock_stat.st_mode)
+                or lock_stat.st_uid != os.getuid()
+                or lock_stat.st_nlink != 1
+                or stat.S_IMODE(lock_stat.st_mode) != 0o600
+            ):
+                raise MigrationError("Unsafe configuration lock; no change made.")
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            if not _same(expected, snapshot(expected.path)):
+                raise MigrationError(
+                    "Configuration changed after preview; preview again."
+                )
+            # Backup is never used to overwrite a later edit automatically.
+            backup_fd, backup_name = tempfile.mkstemp(
+                prefix=expected.path.name + ".ecco-backup-", dir=expected.path.parent
+            )
+            with os.fdopen(backup_fd, "wb") as backup:
+                backup.write(expected.content)
+                backup.flush()
+                os.fsync(backup.fileno())
+            target_fd, temporary = tempfile.mkstemp(
+                prefix=".ecco-edit-", dir=expected.path.parent
+            )
+            with os.fdopen(target_fd, "wb") as target:
+                target.write(edit.after)
+                os.fchmod(target.fileno(), expected.mode)
+                target.flush()
+                os.fsync(target.fileno())
+            if not _same(expected, snapshot(expected.path)):
+                raise MigrationError(
+                    "Configuration changed during apply; preview again."
+                )
+            os.replace(temporary, expected.path)
+            temporary = None
+            replaced = True
+            directory_fd = os.open(expected.path.parent, os.O_RDONLY)
+            try:
+                os.fsync(directory_fd)
+            finally:
+                os.close(directory_fd)
+            return Path(backup_name)
+    except OSError:
+        if replaced:
+            raise UncertainWriteError(
+                "Configuration was replaced but durability is uncertain; "
+                "inspect it before any retry. The private backup is retained."
+            ) from None
+        raise MigrationError(
+            "Configuration edit unavailable; inspect status before retrying."
+        ) from None
+    finally:
+        if temporary is not None:
+            os.unlink(temporary)
+
+
+def rollback(path: Path, recovery: Path, **selection) -> Path | None:
+    """Restore only a matching migration; refuse to discard subsequent edits."""
+    current = snapshot(path)
+    saved = snapshot(recovery)
+    if (
+        saved.path.parent != current.path.parent
+        or not saved.path.name.startswith(current.path.name + ".ecco-backup-")
+        or saved.mode != 0o600
+    ):
+        raise MigrationError("Recovery copy does not belong to this configuration.")
+    original_edit = render(saved.content, **selection)
+    if not original_edit.plan.changed:
+        raise MigrationError("Recovery copy does not contain a migration source.")
+    if current.content == saved.content:
+        return None
+    if current.content != original_edit.after:
+        raise MigrationError(
+            "Configuration has later edits; automatic rollback refused."
+        )
+    reverse = RenderedMigration(
+        Plan(
+            original_edit.plan.path,
+            original_edit.plan.new_url,
+            original_edit.plan.old_url,
+        ),
+        current.content,
+        saved.content,
+    )
+    return apply(current, reverse)

ecco_cli/main.py

@@ -0,0 +1,178 @@
+"""Explicit preview/apply migration commands; login is owned by ECO-1035."""
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+
+from ecco_cli import bootstrap
+from ecco_cli.migration import MigrationError, UncertainWriteError
+
+if os.name != "nt":
+    from ecco_cli.discovery import native_target
+    from ecco_cli.files import apply, preview, rollback, snapshot
+    from ecco_cli.metadata import verify
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog=Path(sys.argv[0]).name)
+    commands = parser.add_subparsers(dest="command", required=True)
+    new = commands.add_parser("new", help="Create a signup-free agent board")
+    new.add_argument("name", help="Board name")
+    new.add_argument("--task", "--task-title", dest="task_title")
+    new.add_argument("--task-body")
+    new.add_argument("--client", default="heyecco")
+    new.add_argument("--client-version", default="0.1.0")
+    new.add_argument("--api-base", default=bootstrap.DEFAULT_API)
+    new.add_argument("--state-directory", type=Path)
+    resume = commands.add_parser("resume", help="Resume from private board state")
+    resume.add_argument("--state", type=Path, required=True)
+    resume.add_argument("--retry-bootstrap", action="store_true")
+    resume.add_argument("child", nargs=argparse.REMAINDER)
+    migrate = commands.add_parser(
+        "migrate", help="Preview one legacy MCP endpoint update"
+    )
+    migrate.add_argument("--client", choices=("claude", "codex"), required=True)
+    migrate.add_argument("--scope", choices=("user", "project", "local"), required=True)
+    migrate.add_argument("--name", required=True)
+    migrate.add_argument(
+        "--config", type=Path, help="Assert the discovered config path"
+    )
+    migrate.add_argument("--project", help="Exact project key for Claude local scope")
+    migrate.add_argument("--project-dir", type=Path, default=Path.cwd())
+    action = migrate.add_mutually_exclusive_group()
+    action.add_argument("--apply", action="store_true")
+    action.add_argument("--rollback", type=Path, metavar="RECOVERY_COPY")
+    migrate.add_argument("--expected-digest", help="SHA-256 from the preview")
+    migrate.add_argument(
+        "--client-closed",
+        action="store_true",
+        help="Confirm the client is closed while its config is changed",
+    )
+    args = parser.parse_args(argv)
+    if args.command == "new":
+        try:
+            result = bootstrap.create(
+                board_name=args.name,
+                task_title=args.task_title,
+                task_body=args.task_body,
+                client_name=args.client,
+                client_version=args.client_version,
+                api_base=args.api_base,
+                state_directory=args.state_directory,
+            )
+            print(json.dumps(result))
+            return 0
+        except bootstrap.BootstrapFailure as exc:
+            print(json.dumps({"status": "not_ready", "error": str(exc)}))
+            return 2
+    if args.command == "resume":
+        try:
+            if args.retry_bootstrap:
+                if args.child:
+                    raise bootstrap.BootstrapFailure(
+                        "Retry bootstrap and child execution are separate steps."
+                    )
+                print(json.dumps(bootstrap.retry(args.state)))
+                return 0
+            child = args.child[1:] if args.child[:1] == ["--"] else args.child
+            return bootstrap.run(args.state, child)
+        except bootstrap.BootstrapFailure as exc:
+            print(json.dumps({"status": "not_ready", "error": str(exc)}))
+            return 2
+    if os.name == "nt":
+        print(
+            json.dumps(
+                {
+                    "status": "not_applied",
+                    "error": "Connector migration is supported on POSIX hosts only.",
+                    "authenticated": False,
+                }
+            )
+        )
+        return 2
+    try:
+        target = native_target(
+            client=args.client,
+            name=args.name,
+            scope=args.scope,
+            project=args.project_dir,
+        )
+        if args.config is not None and args.config.absolute() != target.path.absolute():
+            raise MigrationError("The supplied path does not match native discovery.")
+        if args.project is not None and args.project != target.project:
+            raise MigrationError("The selected local project does not match discovery.")
+        args.config = target.path
+        selection = {
+            "client": args.client,
+            "scope": args.scope,
+            "name": args.name,
+            "project": target.project,
+        }
+        before = snapshot(args.config)
+        digest = hashlib.sha256(before.content).hexdigest()
+        writing = args.apply or args.rollback is not None
+        if writing and (not args.client_closed or args.expected_digest != digest):
+            raise MigrationError(
+                "Apply requires the preview digest and confirmation "
+                "the client is closed."
+            )
+        if args.rollback is not None:
+            backup = rollback(args.config, args.rollback, **selection)
+            result = {
+                "status": "restored" if backup else "already_restored",
+                "authenticated": False,
+            }
+        else:
+            before, edit = preview(args.config, **selection)
+            # Recheck the digest after parsing, before passing the snapshot to apply.
+            if hashlib.sha256(before.content).hexdigest() != digest:
+                raise MigrationError("Configuration changed during preview; try again.")
+            result = {
+                "status": "preview" if edit.plan.changed else "already_canonical",
+                "from": edit.plan.old_url,
+                "to": edit.plan.new_url,
+                "digest": digest,
+                "authenticated": False,
+            }
+            backup = None
+            if args.apply:
+                verify()
+                if (
+                    native_target(
+                        client=args.client,
+                        name=args.name,
+                        scope=args.scope,
+                        project=args.project_dir,
+                    )
+                    != target
+                ):
+                    raise MigrationError("Native configuration changed; preview again.")
+                backup = apply(before, edit)
+                result["status"] = "reload_required"
+                result["next"] = (
+                    "Reload the connector; native reauthorization may be required."
+                )
+        if backup is not None:
+            result["recovery_copy"] = str(backup)
+        print(json.dumps(result))
+        return 0
+    except MigrationError as exc:
+        print(
+            json.dumps(
+                {
+                    "status": "inspect_required"
+                    if isinstance(exc, UncertainWriteError)
+                    else "not_applied",
+                    "error": str(exc),
+                    "authenticated": False,
+                }
+            )
+        )
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ecco_cli/metadata.py

@@ -0,0 +1,122 @@
+"""Bounded, credential-free check of the canonical MCP resource identity."""
+
+import json
+import socket
+import ssl
+import subprocess
+import sys
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlsplit
+from urllib.request import HTTPRedirectHandler, ProxyHandler, Request, build_opener
+
+from ecco_cli.migration import CANONICAL, MigrationError
+
+METADATA_URL = "https://api.heyecco.com/.well-known/oauth-protected-resource/mcp"
+MAX_BYTES = 65536
+
+
+class NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def validate(document: object) -> None:
+    if not isinstance(document, dict) or document.get("resource") != CANONICAL:
+        raise MigrationError(
+            "Public OAuth resource does not match the canonical MCP URL."
+        )
+    issuers = document.get("authorization_servers")
+    if not isinstance(issuers, list) or not issuers:
+        raise MigrationError("Public OAuth metadata has no authorization server.")
+    for issuer in issuers:
+        if not isinstance(issuer, str):
+            raise MigrationError("Public OAuth authorization server is invalid.")
+        parsed = urlsplit(issuer)
+        if (
+            parsed.scheme != "https"
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise MigrationError("Public OAuth authorization server is invalid.")
+
+
+def probe() -> dict:
+    """Only a fixed public endpoint; no client config, invite or auth header."""
+    try:
+        opener = build_opener(NoRedirect(), ProxyHandler({}))
+        request = Request(METADATA_URL, headers={"Accept": "application/json"})
+        with opener.open(request, timeout=8) as response:
+            if response.status != 200:
+                return {"ok": False, "category": "http", "status": response.status}
+            body = response.read(MAX_BYTES + 1)
+        if len(body) > MAX_BYTES:
+            return {"ok": False, "category": "metadata_size"}
+        validate(json.loads(body))
+        return {"ok": True, "resource": CANONICAL, "authenticated": False}
+    except HTTPError as exc:
+        return {"ok": False, "category": "http", "status": exc.code}
+    except URLError as exc:
+        reason = exc.reason
+        category = (
+            "tls"
+            if isinstance(reason, ssl.SSLError)
+            else "dns"
+            if isinstance(reason, socket.gaierror)
+            else "timeout"
+            if isinstance(reason, TimeoutError)
+            else "transport"
+        )
+        return {"ok": False, "category": category}
+    except TimeoutError:
+        return {"ok": False, "category": "timeout"}
+    except (ValueError, UnicodeError):
+        return {"ok": False, "category": "metadata"}
+    except OSError:
+        return {"ok": False, "category": "transport"}
+
+
+def verify() -> None:
+    # A child enforces a wall-clock deadline even if OS DNS resolution stalls.
+    # This runs installed package code, never a downloaded script or a model.
+    try:
+        completed = subprocess.run(
+            [sys.executable, "-m", "ecco_cli.metadata"],
+            stdin=subprocess.DEVNULL,
+            capture_output=True,
+            timeout=12,
+            check=False,
+        )
+        report = json.loads(completed.stdout)
+        if completed.returncode != 0 or not isinstance(report, dict):
+            raise ValueError
+    except subprocess.TimeoutExpired:
+        raise MigrationError(
+            "Public metadata check timed out after 12 seconds; no credential was used."
+        ) from None
+    except (OSError, ValueError):
+        raise MigrationError("Public metadata check could not complete.") from None
+    if report.get("ok") is True and report.get("resource") == CANONICAL:
+        return
+    category = report.get("category")
+    if category not in {
+        "http",
+        "tls",
+        "dns",
+        "timeout",
+        "transport",
+        "metadata",
+        "metadata_size",
+    }:
+        category = "metadata"
+    status = report.get("status")
+    detail = f" HTTP {status}" if type(status) is int and 100 <= status <= 599 else ""
+    raise MigrationError(
+        f"Public metadata check failed ({category}{detail}); no credential was used."
+    )
+
+
+if __name__ == "__main__":
+    print(json.dumps(probe()))  # CLI protocol only; no request/response body logging.

ecco_cli/migration.py

@@ -0,0 +1,87 @@
+"""Pure migration planning. No credentials, filesystem writes or network calls."""
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any
+
+CANONICAL = "https://api.heyecco.com/mcp"
+LEGACY = frozenset(
+    "https://eco-backend-production-4659.up.railway.app" + path
+    for path in ("", "/", "/mcp", "/mcp/")
+)
+
+
+class MigrationError(ValueError):
+    """A safe, credential-free explanation of why no change was made."""
+
+
+class UncertainWriteError(MigrationError):
+    """Replacement happened but durability could not be confirmed."""
+
+
+@dataclass(frozen=True)
+class Plan:
+    path: tuple[str, ...]
+    old_url: str
+    new_url: str = CANONICAL
+
+    @property
+    def changed(self) -> bool:
+        return self.old_url != self.new_url
+
+
+def plan(
+    document: dict[str, Any],
+    *,
+    client: str,
+    name: str,
+    scope: str,
+    project: str | None = None,
+) -> Plan:
+    """Select one explicit client/name/scope; never guess from display names.
+
+    Documents are supplied by the caller. This planner neither discovers nor
+    reads token stores. Callers must separately enforce managed configuration,
+    effective-scope precedence and file ownership before applying a plan.
+    """
+    if client == "claude":
+        if scope in {"user", "project"}:
+            path = ("mcpServers", name, "url")
+        elif scope == "local" and project:
+            path = ("projects", project, "mcpServers", name, "url")
+        else:
+            raise MigrationError("Select a supported scope and project explicitly.")
+    elif client == "codex" and scope in {"user", "project"}:
+        path = ("mcp_servers", name, "url")
+    else:
+        raise MigrationError("Unsupported client or configuration scope.")
+    entry: Any = document
+    for key in path[:-1]:
+        if not isinstance(entry, dict) or key not in entry:
+            raise MigrationError("The selected connector is not configured here.")
+        entry = entry[key]
+    if not isinstance(entry, dict):
+        raise MigrationError("The selected connector configuration is invalid.")
+    if "command" in entry or (
+        client == "claude" and entry.get("type") not in {"http", "streamable-http"}
+    ):
+        raise MigrationError("Only an explicit HTTP connector can be migrated.")
+    url = entry.get("url")
+    if not isinstance(url, str) or url not in LEGACY | {CANONICAL}:
+        # Never echo arbitrary URLs: they may contain credentials or invite codes.
+        raise MigrationError("Endpoint is not a recognized Ecco migration source.")
+    return Plan(path=path, old_url=url)
+
+
+def apply_to_document(document: dict[str, Any], migration: Plan) -> dict[str, Any]:
+    """Reference semantic change used to verify a lossless serialized edit."""
+    updated = deepcopy(document)
+    entry: Any = updated
+    for key in migration.path[:-1]:
+        if not isinstance(entry, dict) or key not in entry:
+            raise MigrationError("Configuration changed after preview; preview again.")
+        entry = entry[key]
+    if not isinstance(entry, dict) or entry.get("url") != migration.old_url:
+        raise MigrationError("Configuration changed after preview; preview again.")
+    entry["url"] = migration.new_url
+    return updated

ecco_cli/serialization.py

@@ -0,0 +1,110 @@
+"""Preserve configuration formatting and secrets without displaying either."""
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+import tomlkit
+
+from ecco_cli.migration import MigrationError, Plan, apply_to_document, plan
+
+MAX_CONFIG_BYTES = 1024 * 1024
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    value: dict[str, Any] = {}
+    for key, item in pairs:
+        if key in value:
+            raise MigrationError("Duplicate configuration keys; resolve them first.")
+        value[key] = item
+    return value
+
+
+def _reject_constant(value: str) -> None:
+    raise MigrationError("Nonstandard JSON constants are not supported.")
+
+
+_DECODER = json.JSONDecoder(
+    object_pairs_hook=_unique_object, parse_constant=_reject_constant
+)
+
+
+def _skip_space(source: str, start: int) -> int:
+    while start < len(source) and source[start] in " \r\n\t":
+        start += 1
+    return start
+
+
+def _json_value_span(source: str, start: int, path: tuple[str, ...]) -> tuple[int, int]:
+    """Find one value in already-validated JSON, respecting escaped keys."""
+    start = _skip_space(source, start)
+    if not path:
+        _, end = _DECODER.raw_decode(source, start)
+        return start, end
+    if source[start] != "{":
+        raise MigrationError("Selected configuration path is not an object.")
+    cursor = _skip_space(source, start + 1)
+    while source[cursor] != "}":
+        key, cursor = _DECODER.raw_decode(source, cursor)
+        cursor = _skip_space(source, cursor)
+        cursor = _skip_space(source, cursor + 1)  # Validated colon.
+        if key == path[0]:
+            return _json_value_span(source, cursor, path[1:])
+        _, cursor = _DECODER.raw_decode(source, cursor)
+        cursor = _skip_space(source, cursor)
+        if source[cursor] == ",":
+            cursor = _skip_space(source, cursor + 1)
+    raise MigrationError("Selected connector is no longer available.")
+
+
+@dataclass(frozen=True)
+class RenderedMigration:
+    plan: Plan
+    before: bytes = field(repr=False)
+    after: bytes = field(repr=False)
+
+
+def render(
+    data: bytes,
+    *,
+    client: str,
+    name: str,
+    scope: str,
+    project: str | None = None,
+) -> RenderedMigration:
+    """Return an in-memory preview; never read/write a client configuration."""
+    if len(data) > MAX_CONFIG_BYTES:
+        raise MigrationError("Configuration exceeds the supported size limit.")
+    try:
+        source = data.decode("utf-8")
+        if client == "claude":
+            document = _DECODER.decode(source)
+        elif client == "codex":
+            document = tomlkit.parse(source)
+        else:
+            raise MigrationError("Unsupported client.")
+        if not isinstance(document, dict):
+            raise MigrationError("Configuration must be an object.")
+        migration = plan(
+            document, client=client, name=name, scope=scope, project=project
+        )
+        if not migration.changed:
+            return RenderedMigration(migration, data, data)
+        expected = apply_to_document(document, migration)
+        if client == "claude":
+            start, end = _json_value_span(source, 0, migration.path)
+            changed = source[:start] + json.dumps(migration.new_url) + source[end:]
+            parsed = _DECODER.decode(changed)
+        else:
+            changed = tomlkit.dumps(expected)
+            parsed = tomlkit.parse(changed)
+        if parsed != expected:
+            raise MigrationError("Configuration preservation check failed.")
+        return RenderedMigration(migration, data, changed.encode("utf-8"))
+    except MigrationError:
+        raise
+    except (ValueError, TypeError, KeyError, IndexError, RecursionError):
+        # Parser diagnostics may quote private configuration. Never forward them.
+        raise MigrationError(
+            "Cannot safely parse this configuration; no change made."
+        ) from None

heyecco-0.1.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: heyecco
+Version: 0.1.0
+Summary: Start and resume an Ecco agent board without an account
+Project-URL: Homepage, https://heyecco.com/for-agents
+Project-URL: Documentation, https://heyecco.com/for-agents
+License-Expression: AGPL-3.0-only
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Groupware
+Requires-Python: >=3.11
+Requires-Dist: tomlkit<1,>=0.13.2
+Description-Content-Type: text/markdown
+
+# Ecco CLI
+
+This package supplies signup-free agent boards and safe connector migration.
+Python 3.11+ is required. Start from any directory without a GitHub checkout or
+Ecco account:
+
+```sh
+uvx heyecco new "Launch Acme" --task "Draft the launch plan"
+```
+
+For local development:
+
+```sh
+cd cli
+uv sync
+uv run ecco --help
+```
+
+## Start a board without an account
+
+```sh
+heyecco new "Launch Acme" \
+  --task "Draft the launch plan" \
+  --task-body "## Outcome\nA reviewable launch plan exists."
+```
+
+The public PyPI package is named `heyecco` because the `ecco` package name belongs
+to an unrelated project. It installs both `heyecco` and `ecco` commands; existing
+`--task-title` calls remain supported as an alias for `--task`.
+
+The command creates caller-owned random worker, claim and recovery secrets, writes
+them to a private state file before making the HTTPS request, and prints one JSON
+receipt containing public board metadata plus the state-file and claim-link-file
+paths. It never prints a raw secret or writes one into a repository or native
+client configuration. The board accepts 100 task creations and agent access ends
+after seven days; the private claim link remains usable for 30 more days.
+
+If the first response is lost, the CLI retries the exact request once with the
+stored recovery proof. If the outcome remains unknown, use the reported state:
+
+```sh
+ecco resume --state /private/path/ATTEMPT.json --retry-bootstrap
+```
+
+To run an agent with the saved bearer without printing it, place the agent command
+after `--`. The child receives `ECCO_AGENT_TOKEN`, `ECCO_MCP_URL`, and
+`ECCO_WORKSPACE_ID` in its environment:
+
+```sh
+ecco resume --state /private/path/ATTEMPT.json -- your-agent-command
+```
+
+The child or its supported MCP configuration should read the token from
+`ECCO_AGENT_TOKEN`. The full human handoff URL is in the mode-0600
+`*.claim-link.txt` file named in the receipt; share it only with the intended
+owner.
+
+### Supported paths
+
+| Platform | `ecco new` / `resume` | Private state |
+| --- | --- | --- |
+| macOS | Supported | `$XDG_STATE_HOME/ecco/boards` or `~/.local/state/ecco/boards`, mode 0700/0600 |
+| Linux | Supported | `$XDG_STATE_HOME/ecco/boards` or `~/.local/state/ecco/boards`, mode 0700/0600 |
+| Windows | Supported | `%LOCALAPPDATA%\ecco\boards`, protected by the user profile ACL |
+
+Connector migration below remains POSIX-only because it uses advisory file locks.
+
+## Migrate an existing connector
+
+Close the client before applying a change. Preview from the project where the
+connector is used; select its existing name and scope, not a new identity:
+
+```sh
+ecco migrate --client claude --name ecco --scope user --project-dir /absolute/project
+```
+
+For Codex use `--client codex`. Claude supports `user`, `project`, and `local`;
+Codex supports `user` and `project`. `CLAUDE_CONFIG_DIR` and `CODEX_HOME` are
+honored. No credential-store files are read and no Keychain process is invoked.
+Preview is read-only and prints a digest, not configuration contents.
+
+Repeat with the returned digest to apply:
+
+```sh
+ecco migrate --client claude --name ecco --scope user --project-dir /absolute/project \
+  --apply --expected-digest DIGEST_FROM_PREVIEW --client-closed
+```
+
+Only the exact legacy Ecco Railway URL is replaced by
+`https://api.heyecco.com/mcp`. Existing connector names, OAuth registration,
+permissions, unrelated settings and formatting are retained. The canonical URL
+is a no-op. Public OAuth metadata must match before a changed file is written.
+Its check has a 12-second wall-clock deadline and never sends credentials.
+
+Duplicated names across local config layers, selected profiles, known managed
+files, unsafe files and changed previews stop migration. The command never edits
+managed policy, trust settings or OAuth caches. On-disk discovery does not prove
+the effective configuration of a running app: cloud policy, launch overrides and
+desktop-specific behavior remain the native client's responsibility. If the
+client still reports a different URL, inspect that client's active source; do not
+delete other connectors or weaken resource validation.
+
+Apply returns `reload_required`, **not connected**. Reload the connector. A native
+OAuth client may require authorization for the canonical resource because cached
+grants can be bound to the old resource or client registration. This command does
+not transplant refresh tokens, trigger login or assume the old grant is valid for
+the new URL. Under the no-Keychain policy, do not launch macOS Claude OAuth login
+until a supported non-Keychain path has been selected. Configuration parsing,
+authorization and an authenticated `list_projects` call are separate proofs.
+
+## Recovery
+
+Apply retains a private mode-0600 backup beside the config and reports its path.
+It may contain existing configuration secrets: never share or commit it. To undo,
+preview the current file again and use its new digest:
+
+```sh
+ecco migrate --client claude --name ecco --scope user --project-dir /absolute/project \
+  --rollback /absolute/config.ecco-backup-SUFFIX \
+  --expected-digest CURRENT_DIGEST --client-closed
+```
+
+Rollback works offline and refuses to overwrite later edits. An `inspect_required`
+result means replacement occurred but filesystem durability could not be confirmed;
+inspect the file and retained backup rather than retrying blindly. Ecco's advisory
+lock coordinates its own processes, not arbitrary editors.
+
+## Verification
+
+```sh
+uv run ruff check .
+uv run ruff format --check .
+uv run python -m unittest discover -s tests -v
+uv build --wheel
+# macOS only, with installed Claude and Codex; no auth or model calls:
+ECCO_NATIVE_CLIENT_SMOKE=1 uv run python -m unittest discover -s tests -p test_native_clients.py -v
+```
+
+The opt-in native checks use disposable configs and deny network, Keychain and
+real-client configuration access at the OS boundary. They verify parsing, not
+the normal-permission end-to-end login acceptance owned by ECO-1032.

heyecco-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+ecco_cli/__init__.py,sha256=Foo0vlpy2GeWWm3a2M39FhCX_Tk6MaGwWNyMQ7krst4,72
+ecco_cli/bootstrap.py,sha256=L2N71NIBTWEP_wdaY49B6cKv9MeryZjta9uHikRtDOc,10157
+ecco_cli/discovery.py,sha256=S0wYPol4VVMnEEASBGpl0694EbsIGueFWszTgP2JF8k,6148
+ecco_cli/files.py,sha256=twY9biaKvs4bSPWSZr0QkMW1DJ6RIQD8Dl6OMsjmeIk,7558
+ecco_cli/main.py,sha256=R3RbGn4f2AiOKEW8fZwXujmAco2w0uIuu5LH1MNO5MA,7212
+ecco_cli/metadata.py,sha256=vhqHGkOx8Xj_t3lU95Pwx3GWPijGU29g66fpwkEOKXo,4465
+ecco_cli/migration.py,sha256=RaVq730l-AVBOX25cEx63KLSwFS57D_aM0v7Lmh5nSY,3230
+ecco_cli/serialization.py,sha256=QFcPC-nJtP3X3WrltSwX7Dn89PDi4vkZwDYLlFHLRiU,3904
+heyecco-0.1.0.dist-info/METADATA,sha256=CtPgPng8TnV2-DOguJ410oyt45jVOXw_iOWEewH5C6o,6556
+heyecco-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+heyecco-0.1.0.dist-info/entry_points.txt,sha256=uONFc77PgGysT4CQqqrCX5p0zuVO3ttO-zVTHNCyPtc,73
+heyecco-0.1.0.dist-info/RECORD,,

heyecco-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

heyecco-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ecco = ecco_cli.main:main
+heyecco = ecco_cli.main:main