expedait-cli 0.2.2__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.2.2 → expedait_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: expedait-cli
-Version: 0.2.2
+Version: 0.3.0
 Summary: CLI for Expedait project management — download specs, post comments
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -17,6 +17,15 @@ Description-Content-Type: text/markdown
 
 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)
@@ -53,8 +62,8 @@ Once initialized, commands that need a project ID will resolve it automatically.
 
 ```bash
 expedait projects download              # downloads to .expedait/context/
-expedait pages list                     # no --project-id needed
-expedait pages download 42              # 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`.
@@ -92,37 +101,66 @@ 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 markdown to .expedait/context/
-expedait projects download PROJECT_ID --download-format json  # Download as JSON
-expedait projects download PROJECT_ID --output-dir ./specs    # Extract to custom directory
+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
 ```
 
-### Pages
+### Context
 
 ```bash
-expedait pages list --project-id PROJECT_ID         # List pages in a project
-expedait pages get PAGE_ID                          # Print page markdown content
-expedait pages full PAGE_ID                         # Full context (content + comments + deps)
-expedait pages download PAGE_ID                     # Extract markdown to .expedait/context/
-expedait pages download PAGE_ID --download-format json  # Download as JSON
+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 PAGE_ID                      # List comments on a page
-expedait comments create PAGE_ID \                  # Create a comment
+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 page" \
-  --start-offset 100 \
-  --end-offset 120 \
-  --source-page-id 5                                # Optional: agent's source page
-expedait comments resolve PAGE_ID COMMENT_ID        # Mark as resolved
-expedait comments delete PAGE_ID COMMENT_ID         # Delete a comment
+  --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
@@ -135,6 +173,10 @@ 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).

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.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}",
+        )

expedait_cli-0.3.0/expedait_cli/commands/comments.py

@@ -0,0 +1,146 @@
+"""Comment commands: list, create, resolve, delete."""
+
+from __future__ import annotations
+
+import click
+
+from ..auth import resolve_api_url, resolve_tenant_id, resolve_token
+from ..client import ExpedaitClient
+from ..formatters import output
+
+
+def _make_client(ctx: click.Context) -> ExpedaitClient:
+    token = resolve_token()
+    api_url = resolve_api_url(ctx.obj.get("api_url"))
+    tenant_id = resolve_tenant_id(ctx.obj.get("tenant_id"))
+    return ExpedaitClient(api_url, token, tenant_id)
+
+
+def _resolve_offsets(
+    client: ExpedaitClient,
+    deliverable_id: int,
+    selected_text: str,
+    start_offset: int | None,
+    end_offset: int | None,
+) -> tuple[int, int]:
+    """Resolve anchor offsets from the deliverable content.
+
+    The backend requires start/end offsets, but callers should only have to
+    supply the selected text. If both offsets are given we trust them;
+    otherwise we locate the selected text in the current content.
+    """
+    if start_offset is not None and end_offset is not None:
+        return start_offset, end_offset
+
+    deliverable = client.get_deliverable(deliverable_id)
+    content = deliverable.get("content") or ""
+    idx = content.find(selected_text)
+    if idx < 0:
+        raise click.UsageError(
+            "Could not find the selected text in deliverable "
+            f"{deliverable_id}. Pass --start-offset/--end-offset explicitly."
+        )
+    if content.find(selected_text, idx + 1) >= 0:
+        click.echo(
+            "Warning: selected text appears multiple times; anchoring to the "
+            "first occurrence. Pass --start-offset/--end-offset to disambiguate.",
+            err=True,
+        )
+    return idx, idx + len(selected_text)
+
+
+@click.group()
+def comments() -> None:
+    """Manage deliverable comments."""
+
+
+@comments.command("list")
+@click.argument("deliverable_id", type=int)
+@click.pass_context
+def list_comments(ctx: click.Context, deliverable_id: int) -> None:
+    """List comments on a deliverable."""
+    client = _make_client(ctx)
+    try:
+        data = client.list_comments(deliverable_id)
+    finally:
+        client.close()
+    output(data, ctx.obj.get("fmt"))
+
+
+@comments.command("create")
+@click.argument("deliverable_id", type=int)
+@click.option("--text", required=True, help="Comment content.")
+@click.option("--selected-text", required=True, help="The text being commented on.")
+@click.option("--start-offset", type=int, default=None, help="Start char offset (resolved from content if omitted).")
+@click.option("--end-offset", type=int, default=None, help="End char offset (resolved from content if omitted).")
+@click.option("--source-deliverable-id", type=int, default=None, help="Agent's source deliverable ID.")
+@click.option("--parent-comment-id", type=int, default=None, help="Reply to comment ID.")
+@click.option("--agent-run-id", type=int, default=None, help="Link comment to a build run.")
+@click.pass_context
+def create_comment(
+    ctx: click.Context,
+    deliverable_id: int,
+    text: str,
+    selected_text: str,
+    start_offset: int | None,
+    end_offset: int | None,
+    source_deliverable_id: int | None,
+    parent_comment_id: int | None,
+    agent_run_id: int | None,
+) -> None:
+    """Create a comment on a deliverable.
+
+    Only --text and --selected-text are required; anchor offsets are resolved
+    from the deliverable content automatically.
+    """
+    client = _make_client(ctx)
+    try:
+        start, end = _resolve_offsets(
+            client, deliverable_id, selected_text, start_offset, end_offset,
+        )
+        payload: dict = {
+            "comment_text": text,
+            "selected_text": selected_text,
+            "start_offset": start,
+            "end_offset": end,
+            "is_agent_comment": True,
+        }
+        if source_deliverable_id is not None:
+            payload["source_deliverable_id"] = source_deliverable_id
+        if parent_comment_id is not None:
+            payload["parent_comment_id"] = parent_comment_id
+        if agent_run_id is not None:
+            payload["agent_run_id"] = agent_run_id
+
+        data = client.create_comment(deliverable_id, payload)
+    finally:
+        client.close()
+    output(data, ctx.obj.get("fmt"))
+
+
+@comments.command("resolve")
+@click.argument("deliverable_id", type=int)
+@click.argument("comment_id", type=int)
+@click.pass_context
+def resolve_comment(ctx: click.Context, deliverable_id: int, comment_id: int) -> None:
+    """Mark a comment as resolved."""
+    client = _make_client(ctx)
+    try:
+        data = client.resolve_comment(deliverable_id, comment_id)
+    finally:
+        client.close()
+    output(data, ctx.obj.get("fmt"))
+
+
+@comments.command("delete")
+@click.argument("deliverable_id", type=int)
+@click.argument("comment_id", type=int)
+@click.pass_context
+def delete_comment(ctx: click.Context, deliverable_id: int, comment_id: int) -> None:
+    """Delete a comment."""
+    client = _make_client(ctx)
+    try:
+        client.delete_comment(deliverable_id, comment_id)
+    finally:
+        client.close()
+    click.echo("Comment deleted.")