goodeye 0.1.0__py3-none-any.whl

goodeye-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: goodeye
+Version: 0.1.0
+Summary: Public CLI for Goodeye - manage AI workflow skills from the terminal.
+Project-URL: Repository, https://github.com/Goodeye-Labs/goodeye-cli
+Project-URL: Issues, https://github.com/Goodeye-Labs/goodeye-cli/issues
+Author: Goodeye Labs
+License: MIT License
+        
+        Copyright (c) 2026 Goodeye Labs
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai,cli,goodeye,mcp,workflows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# goodeye-cli
+
+Command-line client for Goodeye - manage AI workflow skills from the terminal.
+
+Goodeye is an outcome-aligned AI workflow registry: you author skills (markdown
+bodies + manifests) and verifiers that score an AI agent against a measurable
+business outcome. This CLI is wired to the public `/v1/` REST API.
+
+## Install
+
+Requires Python 3.12+.
+
+```sh
+uv tool install goodeye
+# or
+pipx install goodeye
+# or
+pip install goodeye
+```
+
+Once installed, the `goodeye` command is available on your `PATH`.
+
+## Quickstart
+
+```sh
+# Browse the public registry without an account
+goodeye skills list --filter public
+
+# Create an account (emails a one-time code)
+goodeye signup --email you@example.com
+
+# Or log in on a machine with a browser
+goodeye login
+
+# Confirm who you are
+goodeye whoami
+
+# Fetch a public skill as markdown
+goodeye skills get brand-voice > brand-voice.md
+
+# Push a local skill
+goodeye skills push ./my-skill.md --public
+```
+
+### Skill files
+
+`goodeye skills push` reads a markdown file with optional YAML front-matter:
+
+```markdown
+---
+slug: my-skill
+visibility: private
+manifest:
+  title: My skill
+  tags: [data, cleanup]
+---
+
+# Body
+
+The rest of the file is the skill body rendered to the agent at runtime.
+```
+
+`--public` on the command line overrides `visibility`. `--slug` on the command
+line overrides the front-matter `slug`.
+
+## Command reference
+
+```
+goodeye login [--email EMAIL]
+    Without --email: opens the browser for WorkOS device-code approval.
+    With --email: sends a one-time code to your inbox.
+
+goodeye signup --email EMAIL
+    Creates an account and mints your initial API key.
+
+goodeye logout
+    Deletes local credentials. Does not revoke the key server-side; see
+    `goodeye auth list-keys` and `goodeye auth revoke-key`.
+
+goodeye whoami
+    Shows the current user identified by your credentials.
+
+goodeye auth create-key --name NAME [--copy]
+    Mints a new API key. The secret is printed once.
+
+goodeye auth list-keys
+    Table of your API keys (secrets are never returned).
+
+goodeye auth revoke-key <id>
+    Revokes (soft-deletes) a key.
+
+goodeye skills list [--filter all|public|own] [--tag TAG] [--search QUERY] [--json]
+    Paginated listing; auto-follows cursor.
+
+goodeye skills get <id-or-slug> [--version N] [--output PATH] [--json]
+    Emits raw markdown by default; --json returns the envelope.
+
+goodeye skills push <file.md> [--id ID] [--public] [--slug SLUG]
+    Creates or appends a skill version.
+
+goodeye skills set-visibility <id> <private|public>
+goodeye skills delete <id> [--yes]
+
+goodeye design
+    Prints the workflow-designer prompt pack to stdout.
+```
+
+## Configuration
+
+### Credentials
+
+- `GOODEYE_API_KEY` env var (highest precedence).
+- `~/.config/goodeye/credentials.json` (or `$XDG_CONFIG_HOME/goodeye/`).
+
+Credential files are created with mode `0600`.
+
+### Server
+
+- `GOODEYE_SERVER` env var.
+- `server` field inside `credentials.json`.
+- Default: `https://mcp.goodeyelabs.com`.
+
+## REST API, not the CLI
+
+This CLI is pinned to the `/v1/` REST API contract. If you are integrating
+programmatically and want a stable contract, prefer the REST API directly;
+the CLI is a convenience layer over it.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for local-dev setup and the PR
+process. Issues and PRs welcome.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

goodeye-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+goodeye_cli/__init__.py,sha256=RSSlXudxAflV6gv0bxSl7812iWOeg5CE9rVH4kkRqIA,53
+goodeye_cli/__main__.py,sha256=mi3sTSnf-KIOp1YSjj7rd4bdIh6uZ014YmqkIeMwQi8,238
+goodeye_cli/app.py,sha256=PFdsdxja4TQM-eGyJ5WM1f4hlNRjP5OBndjeFqSTwlA,2056
+goodeye_cli/auth_flows.py,sha256=iXjNAOaepYXh57BWjHTD7bd-P_V8Pjclg42MYw07lSg,6367
+goodeye_cli/client.py,sha256=xATishplzeJGxKoiOpwaolXLaRyH25mTQit3pjJwRcI,9927
+goodeye_cli/config.py,sha256=QD6klJQ3iy07IDtuSJjwA3gECwglcjzzVj7aHoVg-tY,4832
+goodeye_cli/errors.py,sha256=reJpX5gSYa5SKAPtUoA3ZQVQzvlORh2tq0SQ_9ioN2U,2849
+goodeye_cli/wire.py,sha256=GFbdZFfqolcB-Za2OBZ9JmvPCnD7KWTr_0lKH5-rmvo,2256
+goodeye_cli/commands/__init__.py,sha256=lt7T0WVXVuhXPgzvaCmzBnCB21N1d0G-u2iJ5unxuCA,32
+goodeye_cli/commands/auth.py,sha256=jBfj2QSRskCuT1lYdb8RCoudI2Mowd-Qfs2jWmEcbDM,3827
+goodeye_cli/commands/design.py,sha256=otAVFVk87wl9YyaxiGhdUVZEs_lr2EMlu5yxQX-1S8U,1478
+goodeye_cli/commands/login.py,sha256=IapCLBccg4_MbwGnf5Ard2-pLLcJbI2n2tl9rhdE3to,1747
+goodeye_cli/commands/logout.py,sha256=MIhapOGWrsoaa-Z0GrIZTezP7OeUsssY5Iu1J059gOI,902
+goodeye_cli/commands/signup.py,sha256=m3qa2kGl223AP2k_zF9laG9IuDgXfnePe0QWq2FJnSI,843
+goodeye_cli/commands/skills.py,sha256=wPZuztOZLYp0Iu85C1CCaM8yH20Iuj1MrKaBy1sLN7U,8439
+goodeye_cli/commands/whoami.py,sha256=agN_cTuk8yL5rbVqd5y_FgzyUcxhtDXxFM0Le_mTUIY,994
+goodeye-0.1.0.dist-info/METADATA,sha256=-wUGoQjNO3Lhev7QXvLxR0zVi8eECkaren8GRLtUT_A,5564
+goodeye-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+goodeye-0.1.0.dist-info/entry_points.txt,sha256=is74w4li0ittV5GT7DagyP_qS5MHHGyA6qZZw3qtzhI,54
+goodeye-0.1.0.dist-info/licenses/LICENSE,sha256=elL9v1FdiFNSU5YJe1YWYjlJ0EqHbvUxINlVOOZytr4,1069
+goodeye-0.1.0.dist-info/RECORD,,

goodeye-0.1.0.dist-info/WHEEL

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

goodeye-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+goodeye = goodeye_cli.__main__:main

goodeye-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Goodeye Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

goodeye_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Public CLI for Goodeye."""
+
+__version__ = "0.1.0"

goodeye_cli/__main__.py

@@ -0,0 +1,16 @@
+"""Module entrypoint.
+
+Enables ``python -m goodeye_cli`` and the ``goodeye`` console script.
+"""
+
+from __future__ import annotations
+
+from goodeye_cli.app import app
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

goodeye_cli/app.py

@@ -0,0 +1,69 @@
+"""Typer app root. Wires subcommands and a global error handler."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+from rich.console import Console
+
+from goodeye_cli import __version__
+from goodeye_cli.commands import auth as auth_cmds
+from goodeye_cli.commands import design as design_cmd
+from goodeye_cli.commands import login as login_cmd
+from goodeye_cli.commands import logout as logout_cmd
+from goodeye_cli.commands import signup as signup_cmd
+from goodeye_cli.commands import skills as skills_cmds
+from goodeye_cli.commands import whoami as whoami_cmd
+from goodeye_cli.errors import GoodeyeError
+
+app = typer.Typer(
+    name="goodeye",
+    help="Public CLI for Goodeye - manage AI workflow skills from the terminal.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+# Top-level commands.
+app.command("login")(login_cmd.login)
+app.command("signup")(signup_cmd.signup)
+app.command("logout")(logout_cmd.logout)
+app.command("whoami")(whoami_cmd.whoami)
+app.command("design")(design_cmd.design)
+
+# Command groups.
+app.add_typer(auth_cmds.app, name="auth", help="Manage API keys.")
+app.add_typer(skills_cmds.app, name="skills", help="Browse and manage skills.")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"goodeye {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the CLI version and exit.",
+    ),
+) -> None:
+    """Global options processed before any subcommand."""
+    # Body intentionally empty; the callback fires only to register the option.
+    _ = version
+
+
+def main() -> None:
+    """Console-script entrypoint with a structured-error-friendly wrapper."""
+    console = Console(stderr=True)
+    try:
+        app()
+    except GoodeyeError as exc:
+        console.print(f"[bold red]{exc.slug}[/bold red]: {exc.message}")
+        if exc.hint:
+            console.print(f"[dim]hint: {exc.hint}[/dim]")
+        sys.exit(1)

goodeye_cli/auth_flows.py

@@ -0,0 +1,168 @@
+"""Browser-assisted and headless auth flows.
+
+Two flows are implemented:
+
+* **Device code flow** (``device_code_login``): used for ``goodeye login`` with no
+  email. Requests a user_code from WorkOS, opens the verification URL in the
+  default browser, polls until the user approves, then exchanges the resulting
+  WorkOS JWT for a Goodeye API key via ``POST /v1/auth/exchange``.
+
+* **Magic-auth flow** (``magic_auth_flow``): used for ``goodeye login --email``
+  and ``goodeye signup --email``. Posts the email to ``/v1/{intent}``, prompts
+  for the emailed code, and posts to ``/v1/{intent}/verify`` to retrieve the
+  initial API key.
+
+The flows are deliberately injection-friendly: every external dependency
+(``httpx`` transport, browser opener, code prompt, clock) can be overridden so
+the flows can be unit-tested with ``respx`` without any real I/O.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import time
+import webbrowser
+from collections.abc import Callable
+
+from rich.console import Console
+
+from goodeye_cli.client import (
+    GoodeyeClient,
+    poll_device_token,
+    request_device_authorization,
+)
+from goodeye_cli.errors import GoodeyeError, InvalidCredentials
+
+
+def device_code_login(
+    server: str,
+    workos_client_id: str,
+    workos_device_authorization_uri: str,
+    workos_token_uri: str,
+    *,
+    hostname: str | None = None,
+    console: Console | None = None,
+    open_browser: Callable[[str], bool] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+    max_wait_s: float | None = None,
+) -> str:
+    """Run the device-code flow and return the minted API key.
+
+    Args:
+        server: Goodeye server base URL (used for ``/v1/auth/exchange``).
+        workos_client_id: The WorkOS application client id, fetched from
+            ``/.well-known/goodeye-client-config``.
+        workos_device_authorization_uri: WorkOS device-authorization endpoint URL.
+        workos_token_uri: WorkOS token endpoint URL.
+        hostname: Optional host label to embed in the minted key's name.
+        console: Rich console for UX output. A default is created when None.
+        open_browser: Overridable function to open the verification URL.
+            Returns False if no browser could be opened.
+        sleep: Overridable sleep for tests.
+        clock: Overridable monotonic clock for tests.
+        max_wait_s: Optional hard cap on total poll duration. Defaults to the
+            ``expires_in`` returned by WorkOS.
+
+    Returns:
+        The newly minted Goodeye API key.
+    """
+    out = console or Console()
+    opener = open_browser or webbrowser.open
+
+    auth = request_device_authorization(workos_device_authorization_uri, workos_client_id)
+    out.print(
+        f"\nVisit this URL to approve the sign-in:\n  [bold]{auth.verification_uri_complete}[/bold]"
+    )
+    out.print(f"User code: [bold]{auth.user_code}[/bold]\n")
+    # Best-effort browser open; failure is non-fatal because the URL is already printed.
+    with contextlib.suppress(Exception):
+        opener(auth.verification_uri_complete)
+
+    deadline = clock() + (max_wait_s if max_wait_s is not None else auth.expires_in)
+    interval = max(1, int(auth.interval))
+
+    access_token: str | None = None
+    while clock() < deadline:
+        status, body = poll_device_token(workos_token_uri, workos_client_id, auth.device_code)
+        if status == 200 and isinstance(body.get("access_token"), str):
+            access_token = str(body["access_token"])
+            break
+        # WorkOS/OAuth pending-states: continue polling. Everything else: fail fast.
+        error = body.get("error") if isinstance(body, dict) else None
+        if status == 400 and error in ("authorization_pending", "slow_down"):
+            if error == "slow_down":
+                interval += 5
+            sleep(interval)
+            continue
+        description = body.get("error_description") if isinstance(body, dict) else None
+        message = description if isinstance(description, str) else "Device authorization failed."
+        raise InvalidCredentials(
+            slug=str(error) if isinstance(error, str) else "invalid_credentials",
+            message=message,
+            status_code=status,
+        )
+
+    if access_token is None:
+        raise GoodeyeError(
+            slug="auth_required",
+            message="Timed out waiting for device approval.",
+            hint="Re-run `goodeye login` and complete approval in the browser.",
+        )
+
+    with GoodeyeClient(server, api_key=access_token) as client:
+        result = client.exchange(hostname=hostname)
+    return result.api_key
+
+
+def magic_auth_flow(
+    server: str,
+    email: str,
+    *,
+    intent: str = "login",
+    prompt_code: Callable[[], str] | None = None,
+    console: Console | None = None,
+) -> str:
+    """Run the magic-auth flow and return the newly minted API key.
+
+    Args:
+        server: Goodeye server base URL.
+        email: The user's email address.
+        intent: ``"login"`` or ``"signup"``. Both call the same underlying WorkOS
+            magic-auth endpoints but are kept separate for logging/legibility.
+        prompt_code: Callable that returns the 6-digit code the user received.
+            Defaults to a Rich input prompt.
+        console: Rich console for UX output.
+
+    Returns:
+        The newly minted Goodeye API key.
+    """
+    if intent not in ("login", "signup"):
+        raise ValueError(f"intent must be 'login' or 'signup', got {intent!r}")
+
+    out = console or Console()
+
+    def _default_prompt() -> str:
+        return out.input("Enter the 6-digit code sent to your email: ").strip()
+
+    prompt = prompt_code or _default_prompt
+
+    with GoodeyeClient(server) as client:
+        if intent == "signup":
+            client.signup(email)
+        else:
+            client.login(email)
+        out.print(f"A sign-in code was sent to [bold]{email}[/bold].")
+        code = prompt()
+        if not code:
+            raise InvalidCredentials(
+                slug="invalid_credentials",
+                message="No code provided.",
+                hint="Check your email and re-run the command.",
+            )
+        result = (
+            client.signup_verify(email, code)
+            if intent == "signup"
+            else client.login_verify(email, code)
+        )
+    return result.api_key