expedait-cli 0.2.1__tar.gz → 0.3.0__tar.gz

expedait_cli-0.3.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.3.0
+
+Adapt the CLI to the product's four-primitive domain model (objectives,
+deliverables, context, review).
+
+### Added
+- `deliverables` command group (`list`, `get`, `inspect`, `download`) — the
+  rename of `pages`, pointed at `/api/v1/deliverables/...`.
+- `deliverables get --include` — comma-separated section reads (`meta`,
+  `content`, `template`, `requirements`, `writer_instructions`, `dependencies`,
+  `external_context`, `score`, `comments`, `versions`), defaulting to `content`.
+  `meta` surfaces `parent_deliverable_id`.
+- `objectives overview DELIVERABLE_ID` — objective metadata plus its full
+  descendant tree.
+- `context get DELIVERABLE_ID` — read-only LLM context snapshot for a
+  deliverable.
+- `review` command group: `review issues DELIVERABLE_ID [--state open|muted|all]`
+  and `review mute ISSUE_ID [--note TEXT] [--unmute]`.
+- `comments create --agent-run-id` to link a comment to a build run.
+- `expedait-cli` console-script alias so `uvx expedait-cli …` keeps working.
+
+### Changed
+- `comments create` now resolves anchor offsets from the deliverable content;
+  only `--text` and `--selected-text` are required. `--start-offset` /
+  `--end-offset` remain available as explicit overrides.
+- Renamed `comments create --source-page-id` → `--source-deliverable-id`
+  (payload field `source_page_id` → `source_deliverable_id`).
+- `comments resolve` / `comments delete` now use the deliverable-scoped routes
+  `/api/v1/deliverables/{id}/comments/{comment_id}`.
+
+### Deprecated
+- The `pages` command group. `expedait pages …` still works for one release
+  (warns and forwards to `deliverables`) and will then be removed.

expedait_cli-0.3.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: expedait-cli
+Version: 0.3.0
+Summary: CLI for Expedait project management — download specs, post comments
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# Expedait CLI
+
+[![PyPI](https://img.shields.io/pypi/v/expedait-cli)](https://pypi.org/project/expedait-cli/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+CLI for [Expedait](https://expedait.org) — lets AI coding agents download project specs and post comments via the Expedait API.
+
+## The model
+
+Expedait organizes specs around four primitives:
+
+- **Objectives** — top-level goals. An objective is itself a deliverable that nests child deliverables beneath it (`parent_deliverable_id`).
+- **Deliverables** — the individual spec documents (formerly "pages").
+- **Context** — the assembled LLM context for one deliverable: dependency deliverables, linked external sources, uploaded files, and aggregate sizes.
+- **Review** — scoring findings raised on a deliverable: severity, description, the criteria that flagged them, and anchor offsets.
+
+## Usage
+
+### Run with `uvx` (recommended)
+
+No installation needed — run directly:
+
+```bash
+uvx expedait-cli auth login
+uvx expedait-cli projects list
+uvx expedait-cli projects download 1
+```
+
+### Add as a dev dependency
+
+If your AI agent needs it available in the project environment:
+
+```bash
+uv add --group dev expedait-cli
+```
+
+Then reference it in your agent configuration (e.g. `CLAUDE.md`, `.cursor/rules`, etc.).
+
+## Project Setup
+
+After authenticating, run `init` inside your project directory to store your tenant and project settings locally:
+
+```bash
+uvx expedait-cli init
+```
+
+This creates `.expedait/settings.json` with your `tenant_id` and `project_id`. Add `.expedait/` to your `.gitignore`.
+
+Once initialized, commands that need a project ID will resolve it automatically. Downloads default to `.expedait/context/`:
+
+```bash
+expedait projects download              # downloads to .expedait/context/
+expedait deliverables list              # no --project-id needed
+expedait deliverables download 42       # downloads to .expedait/context/
+```
+
+**Resolution order for tenant/project:** CLI flag > env var > `.expedait/settings.json` > `~/.expedait/config.json`.
+
+## Authentication
+
+### Interactive login
+
+```bash
+uvx expedait-cli auth login
+```
+
+Prompts for login method (SSO or email/password). Stores credentials in `~/.expedait/config.json`.
+
+### Environment variables (CI / agents)
+
+```bash
+export EXPEDAIT_TOKEN="your-jwt-token"
+export EXPEDAIT_API_URL="https://your-instance.expedait.org"
+export EXPEDAIT_TENANT_ID=1
+```
+
+**Token resolution order:** `EXPEDAIT_TOKEN` env var > `~/.expedait/config.json` > error.
+
+## Commands
+
+### Auth
+
+```bash
+expedait auth login       # Interactive login
+expedait auth status      # Show current user and tenant
+expedait auth logout      # Clear stored credentials
+```
+
+### Projects
+
+```bash
+expedait projects list                       # List all projects
+expedait projects get PROJECT_ID             # Get project details
+expedait projects download PROJECT_ID        # Extract all deliverables to .expedait/context/
+expedait projects download PROJECT_ID --output-dir ./specs  # Extract to a custom directory
+```
+
+### Deliverables
+
+```bash
+expedait deliverables list --project-id PROJECT_ID   # List deliverables in a project
+expedait deliverables get DELIVERABLE_ID             # Print deliverable markdown content
+expedait deliverables get DELIVERABLE_ID --include meta,content,dependencies,score
+expedait deliverables inspect DELIVERABLE_ID         # Full context (content + comments + deps + lock)
+expedait deliverables download DELIVERABLE_ID        # Extract to .expedait/context/
+```
+
+`--include` accepts a comma-separated subset of: `meta`, `content`, `template`,
+`requirements`, `writer_instructions`, `dependencies`, `external_context`,
+`score`, `comments`, `versions`. It defaults to `content`. `meta` surfaces
+`parent_deliverable_id` (non-null ⇒ this deliverable is a child nested under an
+objective).
+
+### Objectives
+
+```bash
+expedait objectives overview DELIVERABLE_ID   # Objective metadata + full descendant tree
+```
+
+### Context
+
+```bash
+expedait context get DELIVERABLE_ID           # The LLM context snapshot for one deliverable
+```
+
+### Review
+
+```bash
+expedait review issues DELIVERABLE_ID                 # List scoring findings (default: all)
+expedait review issues DELIVERABLE_ID --state open    # Only open findings
+expedait review mute ISSUE_ID --note "by design"      # Mute a finding
+expedait review mute ISSUE_ID --unmute                # Unmute a finding
+```
+
+### Comments
+
+```bash
+expedait comments list DELIVERABLE_ID                 # List comments on a deliverable
+expedait comments create DELIVERABLE_ID \             # Create a comment (offsets resolved automatically)
+  --text "Comment content" \
+  --selected-text "text from the deliverable" \
+  --source-deliverable-id 5                            # Optional: agent's source deliverable
+expedait comments resolve DELIVERABLE_ID COMMENT_ID   # Mark as resolved
+expedait comments delete DELIVERABLE_ID COMMENT_ID    # Delete a comment
+```
+
+Only `--text` and `--selected-text` are required; the CLI locates the selected
+text in the deliverable to compute anchor offsets. Pass `--start-offset` and
+`--end-offset` to anchor explicitly (e.g. when the selected text appears more
+than once).
+
+### Global Options
+
+```bash
+expedait --api-url https://host:8000 ...    # Override API URL
+expedait --tenant-id 2 ...                  # Override tenant
+expedait --format json ...                  # Force JSON output
+expedait --format text ...                  # Force human-readable output
+expedait --version                          # Show version
+```
+
+Output format defaults to `text` when connected to a terminal, `json` when piped.
+
+> **Migration note:** the `pages` command group has been renamed to
+> `deliverables`. `expedait pages …` still works for one release (it warns and
+> forwards) but will be removed.
+
+## Agent Skills
+
+For step-by-step guides on using the CLI from AI coding agents, see [expedait-skills](https://github.com/Expedait/expedait-skills).
+
+## Development
+
+```bash
+git clone https://github.com/Expedait/expedait-cli.git
+cd expedait-cli
+uv sync --group dev
+uv run python -m pytest
+```
+
+## License
+
+[Apache License 2.0](LICENSE)

expedait_cli-0.3.0/README.md

@@ -0,0 +1,184 @@
+# Expedait CLI
+
+[![PyPI](https://img.shields.io/pypi/v/expedait-cli)](https://pypi.org/project/expedait-cli/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+CLI for [Expedait](https://expedait.org) — lets AI coding agents download project specs and post comments via the Expedait API.
+
+## The model
+
+Expedait organizes specs around four primitives:
+
+- **Objectives** — top-level goals. An objective is itself a deliverable that nests child deliverables beneath it (`parent_deliverable_id`).
+- **Deliverables** — the individual spec documents (formerly "pages").
+- **Context** — the assembled LLM context for one deliverable: dependency deliverables, linked external sources, uploaded files, and aggregate sizes.
+- **Review** — scoring findings raised on a deliverable: severity, description, the criteria that flagged them, and anchor offsets.
+
+## Usage
+
+### Run with `uvx` (recommended)
+
+No installation needed — run directly:
+
+```bash
+uvx expedait-cli auth login
+uvx expedait-cli projects list
+uvx expedait-cli projects download 1
+```
+
+### Add as a dev dependency
+
+If your AI agent needs it available in the project environment:
+
+```bash
+uv add --group dev expedait-cli
+```
+
+Then reference it in your agent configuration (e.g. `CLAUDE.md`, `.cursor/rules`, etc.).
+
+## Project Setup
+
+After authenticating, run `init` inside your project directory to store your tenant and project settings locally:
+
+```bash
+uvx expedait-cli init
+```
+
+This creates `.expedait/settings.json` with your `tenant_id` and `project_id`. Add `.expedait/` to your `.gitignore`.
+
+Once initialized, commands that need a project ID will resolve it automatically. Downloads default to `.expedait/context/`:
+
+```bash
+expedait projects download              # downloads to .expedait/context/
+expedait deliverables list              # no --project-id needed
+expedait deliverables download 42       # downloads to .expedait/context/
+```
+
+**Resolution order for tenant/project:** CLI flag > env var > `.expedait/settings.json` > `~/.expedait/config.json`.
+
+## Authentication
+
+### Interactive login
+
+```bash
+uvx expedait-cli auth login
+```
+
+Prompts for login method (SSO or email/password). Stores credentials in `~/.expedait/config.json`.
+
+### Environment variables (CI / agents)
+
+```bash
+export EXPEDAIT_TOKEN="your-jwt-token"
+export EXPEDAIT_API_URL="https://your-instance.expedait.org"
+export EXPEDAIT_TENANT_ID=1
+```
+
+**Token resolution order:** `EXPEDAIT_TOKEN` env var > `~/.expedait/config.json` > error.
+
+## Commands
+
+### Auth
+
+```bash
+expedait auth login       # Interactive login
+expedait auth status      # Show current user and tenant
+expedait auth logout      # Clear stored credentials
+```
+
+### Projects
+
+```bash
+expedait projects list                       # List all projects
+expedait projects get PROJECT_ID             # Get project details
+expedait projects download PROJECT_ID        # Extract all deliverables to .expedait/context/
+expedait projects download PROJECT_ID --output-dir ./specs  # Extract to a custom directory
+```
+
+### Deliverables
+
+```bash
+expedait deliverables list --project-id PROJECT_ID   # List deliverables in a project
+expedait deliverables get DELIVERABLE_ID             # Print deliverable markdown content
+expedait deliverables get DELIVERABLE_ID --include meta,content,dependencies,score
+expedait deliverables inspect DELIVERABLE_ID         # Full context (content + comments + deps + lock)
+expedait deliverables download DELIVERABLE_ID        # Extract to .expedait/context/
+```
+
+`--include` accepts a comma-separated subset of: `meta`, `content`, `template`,
+`requirements`, `writer_instructions`, `dependencies`, `external_context`,
+`score`, `comments`, `versions`. It defaults to `content`. `meta` surfaces
+`parent_deliverable_id` (non-null ⇒ this deliverable is a child nested under an
+objective).
+
+### Objectives
+
+```bash
+expedait objectives overview DELIVERABLE_ID   # Objective metadata + full descendant tree
+```
+
+### Context
+
+```bash
+expedait context get DELIVERABLE_ID           # The LLM context snapshot for one deliverable
+```
+
+### Review
+
+```bash
+expedait review issues DELIVERABLE_ID                 # List scoring findings (default: all)
+expedait review issues DELIVERABLE_ID --state open    # Only open findings
+expedait review mute ISSUE_ID --note "by design"      # Mute a finding
+expedait review mute ISSUE_ID --unmute                # Unmute a finding
+```
+
+### Comments
+
+```bash
+expedait comments list DELIVERABLE_ID                 # List comments on a deliverable
+expedait comments create DELIVERABLE_ID \             # Create a comment (offsets resolved automatically)
+  --text "Comment content" \
+  --selected-text "text from the deliverable" \
+  --source-deliverable-id 5                            # Optional: agent's source deliverable
+expedait comments resolve DELIVERABLE_ID COMMENT_ID   # Mark as resolved
+expedait comments delete DELIVERABLE_ID COMMENT_ID    # Delete a comment
+```
+
+Only `--text` and `--selected-text` are required; the CLI locates the selected
+text in the deliverable to compute anchor offsets. Pass `--start-offset` and
+`--end-offset` to anchor explicitly (e.g. when the selected text appears more
+than once).
+
+### Global Options
+
+```bash
+expedait --api-url https://host:8000 ...    # Override API URL
+expedait --tenant-id 2 ...                  # Override tenant
+expedait --format json ...                  # Force JSON output
+expedait --format text ...                  # Force human-readable output
+expedait --version                          # Show version
+```
+
+Output format defaults to `text` when connected to a terminal, `json` when piped.
+
+> **Migration note:** the `pages` command group has been renamed to
+> `deliverables`. `expedait pages …` still works for one release (it warns and
+> forwards) but will be removed.
+
+## Agent Skills
+
+For step-by-step guides on using the CLI from AI coding agents, see [expedait-skills](https://github.com/Expedait/expedait-skills).
+
+## Development
+
+```bash
+git clone https://github.com/Expedait/expedait-cli.git
+cd expedait-cli
+uv sync --group dev
+uv run python -m pytest
+```
+
+## License
+
+[Apache License 2.0](LICENSE)

{expedait_cli-0.2.1 → expedait_cli-0.3.0}/expedait_cli/auth.py

@@ -7,6 +7,7 @@ import os
 import click
 
 from .config import load_config
+from .settings import load_settings
 
 
 def resolve_token(config_path=None) -> str:
@@ -41,15 +42,42 @@ def resolve_api_url(explicit: str | None = None, config_path=None) -> str:
     return "https://app.expedait.org"
 
 
-def resolve_tenant_id(explicit: int | None = None, config_path=None) -> int | None:
-    """Return tenant ID from flag > env > config."""
+def resolve_tenant_id(
+    explicit: int | None = None,
+    config_path=None,
+    settings_path=None,
+) -> int | None:
+    """Return tenant ID from flag > env > local settings > config."""
     if explicit is not None:
         return explicit
     env = os.environ.get("EXPEDAIT_TENANT_ID")
     if env:
         return int(env)
+    # Local project settings
+    settings = load_settings(settings_path)
+    tid = settings.get("tenant_id")
+    if tid is not None:
+        return int(tid)
+    # Global config
     cfg = load_config(config_path)
     tid = cfg.get("tenant_id")
     if tid is not None:
         return int(tid)
     return None
+
+
+def resolve_project_id(
+    explicit: int | None = None,
+    settings_path=None,
+) -> int | None:
+    """Return project ID from flag > env > local settings."""
+    if explicit is not None:
+        return explicit
+    env = os.environ.get("EXPEDAIT_PROJECT_ID")
+    if env:
+        return int(env)
+    settings = load_settings(settings_path)
+    pid = settings.get("project_id")
+    if pid is not None:
+        return int(pid)
+    return None

expedait_cli-0.3.0/expedait_cli/client.py

@@ -0,0 +1,184 @@
+"""HTTP client wrapper for Expedait API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+import httpx
+
+
+class ExpedaitClient:
+    """Thin wrapper around httpx with auth and tenant headers."""
+
+    def __init__(self, api_url: str, token: str, tenant_id: int | None = None):
+        headers: dict[str, str] = {"Authorization": f"Bearer {token}"}
+        if tenant_id is not None:
+            headers["X-Active-Tenant-Id"] = str(tenant_id)
+        # follow_redirects: collection endpoints are mounted at "/", so the
+        # API 307-redirects e.g. /api/v1/deliverables -> /api/v1/deliverables/.
+        self._http = httpx.Client(
+            base_url=api_url, headers=headers, timeout=30.0, follow_redirects=True,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    # -- helpers ----------------------------------------------------------
+
+    def _check(self, resp: httpx.Response) -> None:
+        if resp.status_code == 401:
+            raise click.UsageError(
+                "Authentication failed (401). Run 'expedait auth login'."
+            )
+        if resp.status_code == 403:
+            raise click.UsageError(
+                "Permission denied (403). Check your tenant access."
+            )
+        if resp.status_code == 404:
+            raise click.UsageError("Resource not found (404).")
+        if resp.status_code >= 400:
+            detail = ""
+            try:
+                detail = resp.json().get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise click.ClickException(f"API error {resp.status_code}: {detail}")
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Make request, handle errors, return parsed JSON."""
+        resp = self._http.request(method, path, **kwargs)
+        self._check(resp)
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    def _request_raw(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """Make request, handle errors, return raw response."""
+        resp = self._http.request(method, path, **kwargs)
+        self._check(resp)
+        return resp
+
+    # -- auth -------------------------------------------------------------
+
+    @staticmethod
+    def login(api_url: str, email: str, password: str) -> dict[str, Any]:
+        """POST /api/v1/auth/login — returns token payload."""
+        resp = httpx.post(
+            f"{api_url}/api/v1/auth/login",
+            json={"email": email, "password": password},
+            timeout=15.0,
+        )
+        if resp.status_code == 401:
+            raise click.UsageError("Invalid email or password.")
+        if resp.status_code >= 400:
+            raise click.ClickException(f"Login failed ({resp.status_code}).")
+        return resp.json()
+
+    def get_me(self) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/auth/me")
+
+    # -- projects ---------------------------------------------------------
+
+    def list_projects(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/api/v1/projects")
+
+    def get_project(self, project_id: int) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/projects/{project_id}")
+
+    def get_workspace(self, project_id: int) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/projects/{project_id}/workspace")
+
+    def download_project(self, project_id: int) -> bytes:
+        resp = self._request_raw("GET", f"/api/v1/projects/{project_id}/download")
+        return resp.content
+
+    # -- deliverables -----------------------------------------------------
+
+    def list_deliverables(
+        self, project_id: int, skip: int = 0, limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        return self._request(
+            "GET", "/api/v1/deliverables",
+            params={"project_id": project_id, "skip": skip, "limit": limit},
+        )
+
+    def get_deliverable(self, deliverable_id: int) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/deliverables/{deliverable_id}")
+
+    def get_deliverable_full(self, deliverable_id: int) -> dict[str, Any]:
+        """Full payload: dependencies, comments, versions, lock status."""
+        return self._request("GET", f"/api/v1/deliverables/{deliverable_id}/full")
+
+    def get_deliverable_type(self, type_id: int) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/deliverables/types/{type_id}")
+
+    def get_deliverable_sources(self, deliverable_id: int) -> list[dict[str, Any]]:
+        return self._request("GET", f"/api/v1/deliverables/{deliverable_id}/sources")
+
+    def download_deliverable(self, deliverable_id: int) -> bytes:
+        resp = self._request_raw(
+            "GET", f"/api/v1/deliverables/{deliverable_id}/download",
+        )
+        return resp.content
+
+    def get_objective_overview(self, deliverable_id: int) -> dict[str, Any]:
+        """Objective metadata + descendant tree. 400 if not an objective."""
+        resp = self._http.request(
+            "GET", f"/api/v1/deliverables/{deliverable_id}/objective-overview",
+        )
+        if resp.status_code == 400:
+            raise click.UsageError(
+                f"Deliverable {deliverable_id} is not an objective."
+            )
+        self._check(resp)
+        return resp.json()
+
+    def get_deliverable_context(self, deliverable_id: int) -> dict[str, Any]:
+        """Read-only LLM context snapshot for a deliverable."""
+        return self._request(
+            "GET", f"/api/v1/deliverables/{deliverable_id}/context-summary",
+        )
+
+    # -- review issues ----------------------------------------------------
+
+    def list_review_issues(
+        self, deliverable_id: int, state: str = "all",
+    ) -> list[dict[str, Any]]:
+        # Backend default (no state param) is open + muted == 'all'.
+        params = {} if state == "all" else {"state": state}
+        return self._request(
+            "GET", f"/api/v1/deliverables/{deliverable_id}/issues", params=params,
+        )
+
+    def mute_review_issue(
+        self, issue_id: int, muted: bool = True, note: str | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"state": "muted" if muted else "open"}
+        if muted and note is not None:
+            payload["muted_note"] = note
+        return self._request(
+            "PATCH", f"/api/v1/deliverables/issues/{issue_id}", json=payload,
+        )
+
+    # -- comments ---------------------------------------------------------
+
+    def list_comments(self, deliverable_id: int) -> list[dict[str, Any]]:
+        return self._request("GET", f"/api/v1/deliverables/{deliverable_id}/comments")
+
+    def create_comment(self, deliverable_id: int, data: dict[str, Any]) -> dict[str, Any]:
+        return self._request(
+            "POST", f"/api/v1/deliverables/{deliverable_id}/comments", json=data,
+        )
+
+    def resolve_comment(self, deliverable_id: int, comment_id: int) -> dict[str, Any]:
+        return self._request(
+            "PUT",
+            f"/api/v1/deliverables/{deliverable_id}/comments/{comment_id}",
+            params={"is_resolved": "true"},
+        )
+
+    def delete_comment(self, deliverable_id: int, comment_id: int) -> Any:
+        return self._request(
+            "DELETE", f"/api/v1/deliverables/{deliverable_id}/comments/{comment_id}",
+        )