heyecco 0.1.0__tar.gz

heyecco-0.1.0/.gitignore

@@ -0,0 +1,72 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+
+# Node / Next.js
+node_modules/
+.next/
+out/
+.turbo/
+*.tsbuildinfo
+next-env.d.ts
+
+# Env / secrets — credentials live in Railway, fetched via `railway run`
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Claude Code — agent worktrees are ephemeral scratch, never commit them
+.claude/worktrees/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local data
+*.db
+*.sqlite
+*.sqlite3
+data/
+state/
+
+# Build artifacts
+.cache/
+.parcel-cache/
+
+# Lorah harness guard — these belong in lorah-app repo, not ecco (ECO-89)
+backend/ecco/lorah_scheduler/
+backend/tests/test_linear_queue_priority.py
+
+# Test artifacts
+frontend/coverage/
+frontend/playwright-report/
+frontend/test-results/
+frontend/package-lock.json
+
+# stray local screenshot (untracked 2026-08-20)
+railway.png
+
+docs/ai-powered-development-phases.md
+
+# ECO-1198: Sanity Studio local state
+studio/.sanity/

heyecco-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,141 @@
+# 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/ecco_cli/__init__.py

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

heyecco-0.1.0/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,
+    }