monolynx-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{monolynx_cli-0.2.0 → monolynx_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: monolynx-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Interfejs wiersza poleceń dla platformy Monolynx
 Project-URL: Homepage, https://gitlab.com/piotrkrych/monolynx
 Project-URL: Documentation, https://gitlab.com/piotrkrych/monolynx/-/blob/main/cli/README.md
@@ -34,7 +34,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/monolynx-cli)](https://pypi.org/project/monolynx-cli/)
 
-Command-line client for the Monolynx platform: manage projects, tickets, sprints and wiki pages from your terminal.
+Command-line client for the Monolynx platform: manage projects, tickets, sprints and wiki pages, and read the code dependency graph, from your terminal.
 
 ## Installation
 
@@ -157,7 +157,7 @@ monolynx auth login --endpoint https://monolynx.example.com --profile work
 - `--token` stores an API token without a browser (`auth_type = "token"`).
 - `--endpoint` and `--profile` work with both flows.
 
-The OAuth access token is valid for 30 days. Every command that calls the API keeps the session alive. `project`, `member`, `ticket`, `sprint` and `wiki` commands do it in two ways, `auth whoami` only reactively:
+The OAuth access token is valid for 30 days. Every command that calls the API keeps the session alive. `project`, `member`, `ticket`, `sprint`, `wiki` and `graph` commands do it in two ways, `auth whoami` only reactively:
 
 - Proactively (not in `auth whoami`): when the profile's `expires_at` is less than 24 hours away (or already past), the CLI refreshes the tokens once before the first request of the command and sends the request with the new access token. The server rotates the refresh token and both new tokens are saved in the profile, so regular use extends the session. If this refresh fails, the command goes on with the current token.
 - Reactively: when the server answers 401, the CLI refreshes the tokens once and repeats the request. A failed refresh ends with a message asking you to run `monolynx auth login` and exit code 3.
@@ -239,11 +239,11 @@ All `ticket` commands work on the project resolved from `--project`, `MONOLYNX_P
 
 | Command | Arguments and options | Description |
 |---|---|---|
-| `ticket list` | `--status`, `--priority`, `--search`, `--sprint`, `--due-before`, `--due-after`, `--overdue`, `--label`, `--page` | List project tickets with filters (one page). `--search` matches the title only; use `ticket search` to match the description too. |
+| `ticket list` | `--status`, `--priority`, `--search`, `--sprint`, `--due-before`, `--due-after`, `--overdue`, `--label`, `--page`, `--compact` | List project tickets with filters (one page); every ticket carries its blockers (`blocked_by`). `--compact` leaves out the ticket descriptions. `--search` matches the title only; use `ticket search` to match the description too. |
 | `ticket search` | `[query]`, `--status`, `--priority`, `--assignee`, `--sprint`, `--due-before`, `--due-after`, `--page` | Search tickets by phrase (title or description) and filters (one page). |
-| `ticket get` | `<ticket>` | Show ticket details. |
-| `ticket create` | `--title` (required), `--description`, `--description-file`, `--priority`, `--sp`/`--story-points`, `--sprint`, `--assignee`, `--due`, `--label`, `--ac`, `--spec-page`, `--blocked-by` | Create a ticket. `--label`, `--ac` and `--blocked-by` can be repeated; `--blocked-by` takes the UUID of the blocking ticket (not the key). |
-| `ticket update` | `<ticket>`, `--title`, `--description`, `--description-file`, `--status`, `--priority`, `--sp`/`--story-points`, `--sprint`, `--assignee`, `--due`, `--label`, `--blocked-by`, `--no-blockers` | Update a ticket; only the given fields are sent. `--label` and `--blocked-by` replace the current values; `--blocked-by` takes the UUID of the blocking ticket (not the key). |
+| `ticket get` | `<ticket>` | Show ticket details, including `spec_page_id` (`null` when the ticket has no spec page). |
+| `ticket create` | `--title` (required), `--description`, `--description-file`, `--priority`, `--sp`/`--story-points`, `--sprint`, `--assignee`, `--due`, `--label`, `--ac`, `--spec-page`, `--blocked-by`, `--brief` | Create a ticket. `--label`, `--ac` and `--blocked-by` can be repeated; `--blocked-by` takes the UUID of the blocking ticket (not the key). `--brief` prints only the identifying fields, status and relations. |
+| `ticket update` | `<ticket>`, `--title`, `--description`, `--description-file`, `--status`, `--priority`, `--sp`/`--story-points`, `--sprint`, `--assignee`, `--due`, `--label`, `--blocked-by`, `--no-blockers`, `--brief` | Update a ticket; only the given fields are sent. `--label` and `--blocked-by` replace the current values; `--blocked-by` takes the UUID of the blocking ticket (not the key). `--brief` prints only the identifying fields, status and relations. |
 | `ticket delete` | `<ticket>`, `-y`/`--yes` | Delete a ticket (asks for confirmation unless `--yes`). |
 | `ticket bulk-update` | `<tickets>...`, `--status`, `--priority`, `--assignee`, `--sprint`, `--due` | Update many tickets in one request. |
 | `ticket comment list` | `<ticket>` | List ticket comments (all pages, flat list). |
@@ -261,6 +261,11 @@ Notes:
 - Identifiers in the URL path (ticket, sprint, page, criterion, project slug) are URL-encoded. A bare `.` or `..` (or an empty value) is refused with exit code 2 before any request is sent.
 - `--description -` and `--body -` read the text from stdin.
 - In `ticket update` and `ticket bulk-update`, an empty string for `--sprint`, `--assignee` or `--due` clears the value.
+- `ticket list` shows blockers per ticket. With `-o json` and `-o yaml`, `blocked_by` is the full list of objects (`id`, `key`, `title`, `status`), empty when the ticket has no blockers. With `-o table` and `-o csv` it is one `blocked_by` column holding the blocker keys joined with `, ` (empty when there are none). `ticket search` results carry no `blocked_by`.
+- `ticket list` and `ticket get` check the server response before rendering. A list item without a `blocked_by` list, or ticket details without the `spec_page_id` key, end with the error `Nieprawidłowa odpowiedź serwera` and exit code 1. This happens against a server older than the CLI, which does not send these fields yet; the CLI refuses to render rather than show a ticket as having no blockers or no spec page.
+- `ticket list --compact` sends `compact=true`, and the server returns the list items without the `description` field; every other field stays, including `blocked_by`. Without the flag the parameter is not sent and the items carry `description` as before.
+- `ticket create --brief` and `ticket update --brief` print exactly seven fields, in this order: `id`, `key`, `title`, `status`, `sprint_id`, `blocked_by`, `blocks`. The request and the server response are unchanged; the CLI filters the output. With `-o json` and `-o yaml`, `blocked_by` and `blocks` are full lists of objects (`id`, `key`, `title`, `status`); with `-o table` and `-o csv` each is one column holding the ticket keys joined with `, `, as in `ticket list`.
+- `--brief` checks the server response before rendering. A response that is not an object, has an empty or missing `id` or `key`, lacks the `title`, `status` or `sprint_id` key (`sprint_id` may be `null`), or whose `blocked_by` or `blocks` is not a list of objects with a non-empty `key` ends with the error `Nieprawidłowa odpowiedź serwera` and exit code 1. The write may already have reached the server, so check the ticket before repeating the command.
 
 ```bash
 monolynx --project my-project ticket create --title "Fix login redirect" --priority high --sp 2 --ac "Redirect keeps the next parameter"
@@ -297,6 +302,34 @@ git log -1 --format=%B | monolynx --project my-project ticket comment add MP-11
 
 `--public` publishes the page at `/blog/{slug}`, visible to anyone without signing in. `wiki delete` has no `-y` short form. `--content -` with an empty standard input, an unreadable or non-UTF-8 `--file`, and a missing project are usage errors (exit code 2, no request sent).
 
+### `graph`
+
+Read-only commands for the code dependency graph of the Connections module. All of them work on the project resolved from `--project`, `MONOLYNX_PROJECT` or the profile, and need the `connections:read` permission.
+
+| Command | Arguments and options | Description |
+|---|---|---|
+| `graph nodes` | `--type`, `--search`, `--limit` (1 to 1000) | List graph nodes, optionally filtered by type and by a fragment of the name (case-insensitive). The server default for `--limit` is 100. |
+| `graph node` | `<node_id>`, `--depth` (min. 1, the server caps it at 5), `--relation-type`, `--node-type` | Show a node with its neighborhood: the node itself, the neighboring nodes, the edges and the depth of every node. `--relation-type` and `--node-type` can be repeated. |
+| `graph query` | `--node-type`, `--search`, `--limit` (1 to 1000) | Fetch the graph or a subgraph of the project (nodes and edges). `--search` matches a fragment of the name or file path and returns the matching nodes with their direct neighbors. The server default for `--limit` is 200. |
+| `graph path` | `--source-id` (required), `--target-id` (required) | Find the shortest path between two nodes. |
+| `graph stats` | | Show graph statistics: the number of nodes and edges, in total and per type. |
+
+Notes:
+
+- `<node_id>` is the `id` field from `graph nodes`. It may contain `/`; the CLI URL-encodes it.
+- Node types are `File`, `Class`, `Method`, `Function`, `Const` and `Module`. Relation types are `CONTAINS`, `CALLS`, `IMPORTS`, `INHERITS`, `USES` and `IMPLEMENTS`.
+- `--depth` is the neighborhood depth: at least 1, and the server caps larger values at 5 (the server default is 1). A `--depth` below 1 or a `--limit` outside 1 to 1000 (`graph nodes`, `graph query`) is a usage error: exit code 2, no request sent. Options you leave out are not sent, so the defaults stay on the server.
+- `graph nodes` prints a flat list. `graph query` and `graph path` print an object with `nodes` and `edges`; `graph node` adds `node` and `depth_map` (node id to depth). `graph stats` prints `total_nodes`, `total_edges`, `nodes_by_type` and `edges_by_type`. When there is no path, `graph path` succeeds with empty `nodes` and `edges`.
+- Every command checks the server response before rendering. A missing required field or a wrong type ends with the error `Nieprawidłowa odpowiedź serwera` and exit code 1, never with an empty result and exit code 0.
+- A project with the graph database turned off, or an unreachable graph database, ends with a 503 error (exit code 1 after the retries). An unknown node in `graph node` is a 404 (exit code 1).
+- There are no commands that write to the graph. The graph is filled by the graphify sync (`cicd/sync_graph.py`), see the Connections module in the dashboard.
+
+```bash
+monolynx --project my-project graph nodes --type Class --search Sprint
+monolynx --project my-project graph node "<node_id>" --depth 2 --relation-type CALLS --relation-type IMPORTS
+monolynx -o json --project my-project graph stats | jq '.nodes_by_type'
+```
+
 ### `version`
 
 | Command | Arguments and options | Description |
@@ -312,7 +345,7 @@ monolynx -o json version --check
 
 ### Reserved groups
 
-`monitoring`, `issues`, `time`, `plan`, `rozliczenia`, `graph`, `pipeline`, `heartbeat` and `role` appear in `monolynx --help` but are reserved: they have no commands yet (not yet available).
+`monitoring`, `issues`, `time`, `plan`, `rozliczenia`, `pipeline`, `heartbeat` and `role` appear in `monolynx --help` but are reserved: they have no commands yet (not yet available).
 
 ### Confirmations
 

{monolynx_cli-0.2.0 → monolynx_cli-0.3.0}/README.md

@@ -2,7 +2,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/monolynx-cli)](https://pypi.org/project/monolynx-cli/)
 
-Command-line client for the Monolynx platform: manage projects, tickets, sprints and wiki pages from your terminal.
+Command-line client for the Monolynx platform: manage projects, tickets, sprints and wiki pages, and read the code dependency graph, from your terminal.
 
 ## Installation
 
@@ -125,7 +125,7 @@ monolynx auth login --endpoint https://monolynx.example.com --profile work
 - `--token` stores an API token without a browser (`auth_type = "token"`).
 - `--endpoint` and `--profile` work with both flows.
 
-The OAuth access token is valid for 30 days. Every command that calls the API keeps the session alive. `project`, `member`, `ticket`, `sprint` and `wiki` commands do it in two ways, `auth whoami` only reactively:
+The OAuth access token is valid for 30 days. Every command that calls the API keeps the session alive. `project`, `member`, `ticket`, `sprint`, `wiki` and `graph` commands do it in two ways, `auth whoami` only reactively:
 
 - Proactively (not in `auth whoami`): when the profile's `expires_at` is less than 24 hours away (or already past), the CLI refreshes the tokens once before the first request of the command and sends the request with the new access token. The server rotates the refresh token and both new tokens are saved in the profile, so regular use extends the session. If this refresh fails, the command goes on with the current token.
 - Reactively: when the server answers 401, the CLI refreshes the tokens once and repeats the request. A failed refresh ends with a message asking you to run `monolynx auth login` and exit code 3.
@@ -207,11 +207,11 @@ All `ticket` commands work on the project resolved from `--project`, `MONOLYNX_P
 
 | Command | Arguments and options | Description |
 |---|---|---|
-| `ticket list` | `--status`, `--priority`, `--search`, `--sprint`, `--due-before`, `--due-after`, `--overdue`, `--label`, `--page` | List project tickets with filters (one page). `--search` matches the title only; use `ticket search` to match the description too. |
+| `ticket list` | `--status`, `--priority`, `--search`, `--sprint`, `--due-before`, `--due-after`, `--overdue`, `--label`, `--page`, `--compact` | List project tickets with filters (one page); every ticket carries its blockers (`blocked_by`). `--compact` leaves out the ticket descriptions. `--search` matches the title only; use `ticket search` to match the description too. |
 | `ticket search` | `[query]`, `--status`, `--priority`, `--assignee`, `--sprint`, `--due-before`, `--due-after`, `--page` | Search tickets by phrase (title or description) and filters (one page). |
-| `ticket get` | `<ticket>` | Show ticket details. |
-| `ticket create` | `--title` (required), `--description`, `--description-file`, `--priority`, `--sp`/`--story-points`, `--sprint`, `--assignee`, `--due`, `--label`, `--ac`, `--spec-page`, `--blocked-by` | Create a ticket. `--label`, `--ac` and `--blocked-by` can be repeated; `--blocked-by` takes the UUID of the blocking ticket (not the key). |
-| `ticket update` | `<ticket>`, `--title`, `--description`, `--description-file`, `--status`, `--priority`, `--sp`/`--story-points`, `--sprint`, `--assignee`, `--due`, `--label`, `--blocked-by`, `--no-blockers` | Update a ticket; only the given fields are sent. `--label` and `--blocked-by` replace the current values; `--blocked-by` takes the UUID of the blocking ticket (not the key). |
+| `ticket get` | `<ticket>` | Show ticket details, including `spec_page_id` (`null` when the ticket has no spec page). |
+| `ticket create` | `--title` (required), `--description`, `--description-file`, `--priority`, `--sp`/`--story-points`, `--sprint`, `--assignee`, `--due`, `--label`, `--ac`, `--spec-page`, `--blocked-by`, `--brief` | Create a ticket. `--label`, `--ac` and `--blocked-by` can be repeated; `--blocked-by` takes the UUID of the blocking ticket (not the key). `--brief` prints only the identifying fields, status and relations. |
+| `ticket update` | `<ticket>`, `--title`, `--description`, `--description-file`, `--status`, `--priority`, `--sp`/`--story-points`, `--sprint`, `--assignee`, `--due`, `--label`, `--blocked-by`, `--no-blockers`, `--brief` | Update a ticket; only the given fields are sent. `--label` and `--blocked-by` replace the current values; `--blocked-by` takes the UUID of the blocking ticket (not the key). `--brief` prints only the identifying fields, status and relations. |
 | `ticket delete` | `<ticket>`, `-y`/`--yes` | Delete a ticket (asks for confirmation unless `--yes`). |
 | `ticket bulk-update` | `<tickets>...`, `--status`, `--priority`, `--assignee`, `--sprint`, `--due` | Update many tickets in one request. |
 | `ticket comment list` | `<ticket>` | List ticket comments (all pages, flat list). |
@@ -229,6 +229,11 @@ Notes:
 - Identifiers in the URL path (ticket, sprint, page, criterion, project slug) are URL-encoded. A bare `.` or `..` (or an empty value) is refused with exit code 2 before any request is sent.
 - `--description -` and `--body -` read the text from stdin.
 - In `ticket update` and `ticket bulk-update`, an empty string for `--sprint`, `--assignee` or `--due` clears the value.
+- `ticket list` shows blockers per ticket. With `-o json` and `-o yaml`, `blocked_by` is the full list of objects (`id`, `key`, `title`, `status`), empty when the ticket has no blockers. With `-o table` and `-o csv` it is one `blocked_by` column holding the blocker keys joined with `, ` (empty when there are none). `ticket search` results carry no `blocked_by`.
+- `ticket list` and `ticket get` check the server response before rendering. A list item without a `blocked_by` list, or ticket details without the `spec_page_id` key, end with the error `Nieprawidłowa odpowiedź serwera` and exit code 1. This happens against a server older than the CLI, which does not send these fields yet; the CLI refuses to render rather than show a ticket as having no blockers or no spec page.
+- `ticket list --compact` sends `compact=true`, and the server returns the list items without the `description` field; every other field stays, including `blocked_by`. Without the flag the parameter is not sent and the items carry `description` as before.
+- `ticket create --brief` and `ticket update --brief` print exactly seven fields, in this order: `id`, `key`, `title`, `status`, `sprint_id`, `blocked_by`, `blocks`. The request and the server response are unchanged; the CLI filters the output. With `-o json` and `-o yaml`, `blocked_by` and `blocks` are full lists of objects (`id`, `key`, `title`, `status`); with `-o table` and `-o csv` each is one column holding the ticket keys joined with `, `, as in `ticket list`.
+- `--brief` checks the server response before rendering. A response that is not an object, has an empty or missing `id` or `key`, lacks the `title`, `status` or `sprint_id` key (`sprint_id` may be `null`), or whose `blocked_by` or `blocks` is not a list of objects with a non-empty `key` ends with the error `Nieprawidłowa odpowiedź serwera` and exit code 1. The write may already have reached the server, so check the ticket before repeating the command.
 
 ```bash
 monolynx --project my-project ticket create --title "Fix login redirect" --priority high --sp 2 --ac "Redirect keeps the next parameter"
@@ -265,6 +270,34 @@ git log -1 --format=%B | monolynx --project my-project ticket comment add MP-11
 
 `--public` publishes the page at `/blog/{slug}`, visible to anyone without signing in. `wiki delete` has no `-y` short form. `--content -` with an empty standard input, an unreadable or non-UTF-8 `--file`, and a missing project are usage errors (exit code 2, no request sent).
 
+### `graph`
+
+Read-only commands for the code dependency graph of the Connections module. All of them work on the project resolved from `--project`, `MONOLYNX_PROJECT` or the profile, and need the `connections:read` permission.
+
+| Command | Arguments and options | Description |
+|---|---|---|
+| `graph nodes` | `--type`, `--search`, `--limit` (1 to 1000) | List graph nodes, optionally filtered by type and by a fragment of the name (case-insensitive). The server default for `--limit` is 100. |
+| `graph node` | `<node_id>`, `--depth` (min. 1, the server caps it at 5), `--relation-type`, `--node-type` | Show a node with its neighborhood: the node itself, the neighboring nodes, the edges and the depth of every node. `--relation-type` and `--node-type` can be repeated. |
+| `graph query` | `--node-type`, `--search`, `--limit` (1 to 1000) | Fetch the graph or a subgraph of the project (nodes and edges). `--search` matches a fragment of the name or file path and returns the matching nodes with their direct neighbors. The server default for `--limit` is 200. |
+| `graph path` | `--source-id` (required), `--target-id` (required) | Find the shortest path between two nodes. |
+| `graph stats` | | Show graph statistics: the number of nodes and edges, in total and per type. |
+
+Notes:
+
+- `<node_id>` is the `id` field from `graph nodes`. It may contain `/`; the CLI URL-encodes it.
+- Node types are `File`, `Class`, `Method`, `Function`, `Const` and `Module`. Relation types are `CONTAINS`, `CALLS`, `IMPORTS`, `INHERITS`, `USES` and `IMPLEMENTS`.
+- `--depth` is the neighborhood depth: at least 1, and the server caps larger values at 5 (the server default is 1). A `--depth` below 1 or a `--limit` outside 1 to 1000 (`graph nodes`, `graph query`) is a usage error: exit code 2, no request sent. Options you leave out are not sent, so the defaults stay on the server.
+- `graph nodes` prints a flat list. `graph query` and `graph path` print an object with `nodes` and `edges`; `graph node` adds `node` and `depth_map` (node id to depth). `graph stats` prints `total_nodes`, `total_edges`, `nodes_by_type` and `edges_by_type`. When there is no path, `graph path` succeeds with empty `nodes` and `edges`.
+- Every command checks the server response before rendering. A missing required field or a wrong type ends with the error `Nieprawidłowa odpowiedź serwera` and exit code 1, never with an empty result and exit code 0.
+- A project with the graph database turned off, or an unreachable graph database, ends with a 503 error (exit code 1 after the retries). An unknown node in `graph node` is a 404 (exit code 1).
+- There are no commands that write to the graph. The graph is filled by the graphify sync (`cicd/sync_graph.py`), see the Connections module in the dashboard.
+
+```bash
+monolynx --project my-project graph nodes --type Class --search Sprint
+monolynx --project my-project graph node "<node_id>" --depth 2 --relation-type CALLS --relation-type IMPORTS
+monolynx -o json --project my-project graph stats | jq '.nodes_by_type'
+```
+
 ### `version`
 
 | Command | Arguments and options | Description |
@@ -280,7 +313,7 @@ monolynx -o json version --check
 
 ### Reserved groups
 
-`monitoring`, `issues`, `time`, `plan`, `rozliczenia`, `graph`, `pipeline`, `heartbeat` and `role` appear in `monolynx --help` but are reserved: they have no commands yet (not yet available).
+`monitoring`, `issues`, `time`, `plan`, `rozliczenia`, `pipeline`, `heartbeat` and `role` appear in `monolynx --help` but are reserved: they have no commands yet (not yet available).
 
 ### Confirmations
 

{monolynx_cli-0.2.0 → monolynx_cli-0.3.0}/src/monolynx_cli/commands/_common.py

@@ -32,6 +32,7 @@ from monolynx_cli.options import get_options
 
 PER_PAGE = 100
 STDIN_MARKER = "-"
+BRIEF_TICKET_KEYS = ("id", "key", "title", "status", "sprint_id", "blocked_by", "blocks")
 
 
 def _stdin_is_tty() -> bool:
@@ -136,6 +137,61 @@ def _invalid_page(detail: str) -> MonolynxAPIError:
     return MonolynxAPIError(200, "Nieprawidłowa odpowiedź serwera", detail)
 
 
+def require_list_with_blockers(payload: Any) -> dict[str, Any]:
+    """Sprawdź kontrakt odpowiedzi `ticket list`: koperta z `items`, każdy element z listą `blocked_by`.
+
+    Serwer sprzed MON-246 nie niesie `blocked_by`; kolumna z kluczami blokerów pokazałaby wtedy
+    puste pole, nieodróżnialne od ticketu bez blokerów, więc brak pola to błąd kontraktu.
+    """
+    if not isinstance(payload, dict):
+        raise _invalid_page("Odpowiedź nie jest obiektem JSON.")
+    items = payload.get("items")
+    if not isinstance(items, list) or not all(isinstance(item, dict) for item in items):
+        raise _invalid_page("Pole items nie jest listą obiektów.")
+    for index, item in enumerate(items):
+        blockers = item.get("blocked_by")
+        if not isinstance(blockers, list):
+            raise _invalid_page(f"Element items[{index}] nie ma listy blocked_by (serwer bez obsługi blokerów w liście ticketów).")
+        for position, blocker in enumerate(blockers):
+            if not isinstance(blocker, dict) or not isinstance(blocker.get("key"), str) or not blocker["key"]:
+                raise _invalid_page(f"Element items[{index}].blocked_by[{position}] nie jest obiektem z niepustym kluczem key.")
+    return payload
+
+
+def require_spec_page_id(payload: Any) -> dict[str, Any]:
+    """Sprawdź kontrakt odpowiedzi `ticket get`: klucz `spec_page_id` musi istnieć (wartość `null` jest poprawna)."""
+    if not isinstance(payload, dict):
+        raise _invalid_page("Odpowiedź nie jest obiektem JSON.")
+    if "spec_page_id" not in payload:
+        raise _invalid_page("Brak pola spec_page_id (serwer bez obsługi spec_page_id w szczegółach ticketu).")
+    return payload
+
+
+def require_brief_ticket(payload: Any) -> dict[str, Any]:
+    """Sprawdź kontrakt odpowiedzi `ticket create|update` pod `--brief` i zwróć tylko 7 pól w stałej kolejności.
+
+    Brak klucza albo zły typ to błąd kontraktu, nigdy puste pole z kodem 0: agent czytający
+    potwierdzenie zapisu nie odróżniłby `""` od ticketu bez statusu. `sprint_id` może być `null`.
+    """
+    if not isinstance(payload, dict):
+        raise _invalid_page("Odpowiedź nie jest obiektem JSON.")
+    for name in ("id", "key"):
+        value = payload.get(name)
+        if not isinstance(value, str) or not value:
+            raise _invalid_page(f"Pole {name} nie jest niepustym tekstem.")
+    for name in ("title", "status", "sprint_id"):
+        if name not in payload:
+            raise _invalid_page(f"Brak pola {name} w odpowiedzi ticketu.")
+    for name in ("blocked_by", "blocks"):
+        relations = payload.get(name)
+        if not isinstance(relations, list):
+            raise _invalid_page(f"Pole {name} nie jest listą (brak lub zły typ w odpowiedzi ticketu).")
+        for position, relation in enumerate(relations):
+            if not isinstance(relation, dict) or not isinstance(relation.get("key"), str) or not relation["key"]:
+                raise _invalid_page(f"Element {name}[{position}] nie jest obiektem z niepustym kluczem key.")
+    return {name: payload[name] for name in BRIEF_TICKET_KEYS}
+
+
 def fetch_all(client: MonolynxClient, path: str, params: dict[str, Any] | None = None) -> list[dict[str, Any]]:
     """Pobierz elementy ze wszystkich stron; `params` (np. filtr statusu) idą na każdą stronę."""
     items: list[dict[str, Any]] = []

monolynx_cli-0.3.0/src/monolynx_cli/commands/graph.py

@@ -0,0 +1,143 @@
+"""Komendy monolynx_cli.commands.graph: nodes, node, query, path, stats (tylko odczyt grafu Połączeń).
+
+Komendy biją w /api/v2/projects/{slug}/graph/* przez klienta z `_common.open_project`. Zapis
+grafu (tworzenie, usuwanie, replace_graph) jest wyłącznie w MCP i synchronizacji CI. Kształt
+każdej odpowiedzi jest sprawdzany przed użyciem: brak wymaganego pola albo zły typ to
+MonolynxAPIError (kod wyjścia 1), nigdy pusty wynik z kodem 0. Filtry nieustawione przez
+użytkownika nie trafiają do żądania, więc domyślne wartości zostają po stronie serwera.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from monolynx_cli.client import MonolynxAPIError
+from monolynx_cli.commands import _common
+from monolynx_cli.output import emit
+
+app = typer.Typer(no_args_is_help=True)
+
+
+def _invalid(detail: str) -> MonolynxAPIError:
+    return MonolynxAPIError(200, "Nieprawidłowa odpowiedź serwera", detail)
+
+
+def _require_objects(value: Any, name: str) -> list[dict[str, Any]]:
+    if not isinstance(value, list):
+        raise _invalid(f"Pole {name} nie jest listą.")
+    for index, item in enumerate(value):
+        if not isinstance(item, dict):
+            raise _invalid(f"Element {name}[{index}] nie jest obiektem JSON.")
+    return value
+
+
+def _require_object(payload: Any) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise _invalid("Odpowiedź nie jest obiektem JSON.")
+    return payload
+
+
+def _require_subgraph(payload: Any) -> dict[str, Any]:
+    data = _require_object(payload)
+    _require_objects(data.get("nodes"), "nodes")
+    _require_objects(data.get("edges"), "edges")
+    return data
+
+
+def _require_node_detail(payload: Any) -> dict[str, Any]:
+    data = _require_subgraph(payload)
+    if not isinstance(data.get("node"), dict):
+        raise _invalid("Pole node nie jest obiektem JSON.")
+    if not isinstance(data.get("depth_map"), dict):
+        raise _invalid("Pole depth_map nie jest obiektem JSON.")
+    return data
+
+
+def _require_stats(payload: Any) -> dict[str, Any]:
+    data = _require_object(payload)
+    for name in ("total_nodes", "total_edges"):
+        value = data.get(name)
+        if not isinstance(value, int) or isinstance(value, bool):
+            raise _invalid(f"Pole {name} nie jest liczbą całkowitą.")
+    for name in ("nodes_by_type", "edges_by_type"):
+        if not isinstance(data.get(name), dict):
+            raise _invalid(f"Pole {name} nie jest obiektem JSON.")
+    return data
+
+
+@app.command("nodes")
+def list_nodes(
+    ctx: typer.Context,
+    node_type: str | None = typer.Option(None, "--type", help="Typ node'a: File, Class, Method, Function, Const lub Module."),
+    search: str | None = typer.Option(None, "--search", help="Fragment nazwy node'a (bez rozróżniania wielkości liter)."),
+    limit: int | None = typer.Option(None, "--limit", min=1, max=1000, help="Maksymalna liczba node'ów (domyślnie 100 po stronie serwera)."),
+) -> None:
+    """Wyświetl node'y grafu Połączeń z opcjonalnym filtrem po typie i nazwie."""
+    client, slug = _common.open_project(ctx)
+    params = _common.without_none({"type": node_type, "search": search, "limit": limit})
+    with client:
+        payload = client.get(_common.project_path(slug, "/graph/nodes"), params=params)
+    emit(ctx, _require_objects(payload, "odpowiedź"))
+
+
+@app.command("node")
+def get_node(
+    ctx: typer.Context,
+    node_id: str = typer.Argument(..., help="Identyfikator node'a (pole id z `graph nodes`)."),
+    depth: int | None = typer.Option(
+        None, "--depth", min=1, help="Głębokość sąsiedztwa, min. 1, serwer obcina do 5 (domyślnie 1 po stronie serwera)."
+    ),
+    relation_type: list[str] | None = typer.Option(
+        None, "--relation-type", help="Typ relacji: CONTAINS, CALLS, IMPORTS, INHERITS, USES lub IMPLEMENTS. Można powtarzać."
+    ),
+    node_type: list[str] | None = typer.Option(
+        None, "--node-type", help="Typ sąsiada: File, Class, Method, Function, Const lub Module. Można powtarzać."
+    ),
+) -> None:
+    """Pokaż node wraz z sąsiedztwem (node'y, krawędzie i głębokość każdego node'a)."""
+    client, slug = _common.open_project(ctx)
+    params = _common.without_none({"depth": depth, "relation_types": relation_type or None, "node_types": node_type or None})
+    with client:
+        payload = client.get(_common.project_path(slug, f"/graph/nodes/{_common.path_segment(node_id)}"), params=params)
+    emit(ctx, _require_node_detail(payload))
+
+
+@app.command("query")
+def query_graph(
+    ctx: typer.Context,
+    node_type: str | None = typer.Option(None, "--node-type", help="Typ node'a: File, Class, Method, Function, Const lub Module."),
+    search: str | None = typer.Option(
+        None, "--search", help="Fragment nazwy lub ścieżki pliku: zwraca dopasowane node'y i ich bezpośrednich sąsiadów."
+    ),
+    limit: int | None = typer.Option(None, "--limit", min=1, max=1000, help="Maksymalna liczba node'ów, 1-1000 (domyślnie 200 po stronie serwera)."),
+) -> None:
+    """Pobierz graf albo podgraf projektu (node'y i krawędzie)."""
+    client, slug = _common.open_project(ctx)
+    params = _common.without_none({"node_type": node_type, "search": search, "limit": limit})
+    with client:
+        payload = client.get(_common.project_path(slug, "/graph/query"), params=params)
+    emit(ctx, _require_subgraph(payload))
+
+
+@app.command("path")
+def find_path(
+    ctx: typer.Context,
+    source_id: str = typer.Option(..., "--source-id", help="Identyfikator node'a początkowego."),
+    target_id: str = typer.Option(..., "--target-id", help="Identyfikator node'a docelowego."),
+) -> None:
+    """Znajdź najkrótszą ścieżkę między dwoma node'ami (brak ścieżki daje puste listy)."""
+    client, slug = _common.open_project(ctx)
+    with client:
+        payload = client.get(_common.project_path(slug, "/graph/path"), params={"source_id": source_id, "target_id": target_id})
+    emit(ctx, _require_subgraph(payload))
+
+
+@app.command("stats")
+def graph_stats(ctx: typer.Context) -> None:
+    """Pokaż statystyki grafu: liczba node'ów i krawędzi, także per typ."""
+    client, slug = _common.open_project(ctx)
+    with client:
+        payload = client.get(_common.project_path(slug, "/graph/stats"))
+    emit(ctx, _require_stats(payload))

{monolynx_cli-0.2.0 → monolynx_cli-0.3.0}/src/monolynx_cli/commands/ticket.py

@@ -8,7 +8,12 @@ i każda inna wartość użytkownika w ścieżce przechodzą przez `_common.path
 priorytetów i dat idą do API bez walidacji po stronie CLI: `create`, `update` i `bulk-update`
 odrzuca serwer (422 -> kod wyjścia 1), ale nieznany status lub priorytet w filtrze (`list`,
 `search`) serwer po cichu ignoruje - filtr nie działa, a odpowiedź to sukces.
-`list`, `search` zwracają jedną stronę w kopercie (`--page`); `comment list`, `label list`
+`list`, `search` zwracają jedną stronę w kopercie (`--page`); `list` waliduje, że każdy element
+niesie listę `blocked_by` (table i csv pokazują ją jako klucze po przecinku, json i yaml w pełni),
+a `get` waliduje obecność `spec_page_id`; brak pola to błąd kontraktu (kod 1) przed renderem;
+`list --compact` pomija opisy (parametr `compact` API, bez zmiany reszty odpowiedzi), a `create --brief` i
+`update --brief` wypisują tylko `id`, `key`, `title`, `status`, `sprint_id`, `blocked_by` i `blocks` (filtr po
+stronie klienta, table i csv pokazują relacje jako klucze po przecinku); odpowiedź bez tych pól to błąd kontraktu; `comment list`, `label list`
 i `ac list` pobierają wszystkie strony (`_common.fetch_all`) i wypisują płaską listę.
 
 Tekst opisu i komentarza można podać flagą, przez `-` (stdin) albo z pliku
@@ -25,7 +30,8 @@ from typing import Annotated, Any
 import typer
 
 from monolynx_cli.commands import _common
-from monolynx_cli.output import emit
+from monolynx_cli.options import OutputFormat, get_options
+from monolynx_cli.output import emit, resolve_format
 
 app = typer.Typer(no_args_is_help=True)
 comment_app = typer.Typer(no_args_is_help=True)
@@ -44,6 +50,17 @@ def _ticket_path(slug: str, ticket: str, suffix: str = "") -> str:
     return _common.project_path(slug, f"/tickets/{_common.path_segment(ticket)}{suffix}")
 
 
+def _blocker_keys(blockers: list[Any]) -> str:
+    return ", ".join(b["key"] for b in blockers)
+
+
+def _emit_brief(ctx: typer.Context, payload: Any) -> None:
+    brief = _common.require_brief_ticket(payload)
+    if resolve_format(get_options(ctx).output) in (OutputFormat.TABLE, OutputFormat.CSV):
+        brief = {**brief, "blocked_by": _blocker_keys(brief["blocked_by"]), "blocks": _blocker_keys(brief["blocks"])}
+    emit(ctx, brief)
+
+
 @app.command("list")
 def list_tickets(
     ctx: typer.Context,
@@ -56,8 +73,9 @@ def list_tickets(
     overdue: Annotated[bool, typer.Option("--overdue", help="Tylko przeterminowane.")] = False,
     label: Annotated[str | None, typer.Option("--label", help="ID etykiety.")] = None,
     page: _PAGE_OPT = None,
+    compact: Annotated[bool, typer.Option("--compact", help="Lista bez opisów ticketów (pole description pominięte).")] = False,
 ) -> None:
-    """Wypisz tickety projektu z filtrami."""
+    """Wypisz tickety projektu z filtrami; każdy ticket niesie blokery (blocked_by), z --compact bez opisów."""
     client, slug = _common.open_project(ctx)
     params = _common.without_none(
         {
@@ -69,11 +87,14 @@ def list_tickets(
             "due_date_after": due_after,
             "overdue": "true" if overdue else None,
             "label_id": label,
+            "compact": "true" if compact else None,
             "page": page,
         }
     )
     with client:
-        payload = client.get(_common.project_path(slug, "/tickets"), params=params)
+        payload = _common.require_list_with_blockers(client.get(_common.project_path(slug, "/tickets"), params=params))
+    if resolve_format(get_options(ctx).output) in (OutputFormat.TABLE, OutputFormat.CSV):
+        payload = {**payload, "items": [{**item, "blocked_by": _blocker_keys(item["blocked_by"])} for item in payload["items"]]}
     emit(ctx, payload)
 
 
@@ -110,10 +131,10 @@ def search_tickets(
 
 @app.command("get")
 def get_ticket(ctx: typer.Context, ticket: _TICKET_ARG) -> None:
-    """Pokaż szczegóły ticketu."""
+    """Pokaż szczegóły ticketu, w tym spec_page_id (null, gdy ticket nie ma strony specyfikacji)."""
     client, slug = _common.open_project(ctx)
     with client:
-        payload = client.get(_ticket_path(slug, ticket))
+        payload = _common.require_spec_page_id(client.get(_ticket_path(slug, ticket)))
     emit(ctx, payload)
 
 
@@ -132,8 +153,9 @@ def create_ticket(
     ac: Annotated[list[str] | None, typer.Option("--ac", help="Kryterium akceptacji; można powtarzać.")] = None,
     spec_page: Annotated[str | None, typer.Option("--spec-page", help="ID strony wiki ze specyfikacją.")] = None,
     blocked_by: Annotated[list[str] | None, typer.Option("--blocked-by", help="UUID ticketu blokującego; można powtarzać.")] = None,
+    brief: Annotated[bool, typer.Option("--brief", help="Wypisz tylko id, key, title, status, sprint_id, blocked_by i blocks.")] = False,
 ) -> None:
-    """Utwórz ticket."""
+    """Utwórz ticket; z --brief wypisuje tylko id, key, title, status, sprint_id i relacje."""
     text = _common.read_text_option(description, description_file, option="--description", file_option="--description-file")
     client, slug = _common.open_project(ctx)
     body = _common.without_none(
@@ -153,6 +175,9 @@ def create_ticket(
     )
     with client:
         payload = client.post(_common.project_path(slug, "/tickets"), json=body)
+    if brief:
+        _emit_brief(ctx, payload)
+        return
     emit(ctx, payload)
 
 
@@ -172,8 +197,9 @@ def update_ticket(
     label: Annotated[list[str] | None, typer.Option("--label", help="ID etykiety (zastępuje dotychczasowe); można powtarzać.")] = None,
     blocked_by: Annotated[list[str] | None, typer.Option("--blocked-by", help="UUID ticketu blokującego (nadpisuje); można powtarzać.")] = None,
     no_blockers: Annotated[bool, typer.Option("--no-blockers", help="Usuń wszystkie blokery.")] = False,
+    brief: Annotated[bool, typer.Option("--brief", help="Wypisz tylko id, key, title, status, sprint_id, blocked_by i blocks.")] = False,
 ) -> None:
-    """Zaktualizuj ticket; do API trafiają tylko podane pola."""
+    """Zaktualizuj ticket; do API trafiają tylko podane pola, z --brief wynik skrócony do pól identyfikujących i relacji."""
     if blocked_by and no_blockers:
         raise _common.usage_error("Podaj --blocked-by albo --no-blockers, nie oba naraz.")
     text = _common.read_text_option(description, description_file, option="--description", file_option="--description-file")
@@ -196,6 +222,9 @@ def update_ticket(
     client, slug = _common.open_project(ctx)
     with client:
         payload = client.patch(_ticket_path(slug, ticket), json=body)
+    if brief:
+        _emit_brief(ctx, payload)
+        return
     emit(ctx, payload)
 
 

{monolynx_cli-0.2.0 → monolynx_cli-0.3.0}/src/monolynx_cli/main.py

@@ -1,6 +1,6 @@
 """Punkt wejścia CLI monolynx-cli: opcja --version, globalne flagi i szkielet 16 grup podkomend.
 
-`auth`, `config`, `project`, `member`, `ticket`, `sprint` i `wiki` mają realne komendy (moduły
+`auth`, `config`, `project`, `member`, `ticket`, `sprint`, `wiki` i `graph` (tylko odczyt) mają realne komendy (moduły
 monolynx_cli.commands.*). Pozostałe grupy są nadal puste -- kolejne tickety dodadzą do
 nich podkomendy, ewentualnie wynosząc rozrośniętą grupę do własnego modułu. Poza grupami root
 ma samodzielne komendy `completion <shell>` (skrypt uzupełniania na stdout, patrz
@@ -36,6 +36,7 @@ from monolynx_cli.client import DEFAULT_TIMEOUT, MonolynxError
 from monolynx_cli.commands.auth import app as auth_app
 from monolynx_cli.commands.completion import completion
 from monolynx_cli.commands.config import app as config_app
+from monolynx_cli.commands.graph import app as graph_app
 from monolynx_cli.commands.member import app as member_app
 from monolynx_cli.commands.project import app as project_app
 from monolynx_cli.commands.sprint import app as sprint_app
@@ -127,7 +128,6 @@ issues_app = typer.Typer(no_args_is_help=True)
 time_app = typer.Typer(no_args_is_help=True)
 plan_app = typer.Typer(no_args_is_help=True)
 rozliczenia_app = typer.Typer(no_args_is_help=True)
-graph_app = typer.Typer(no_args_is_help=True)
 pipeline_app = typer.Typer(no_args_is_help=True)
 heartbeat_app = typer.Typer(no_args_is_help=True)
 role_app = typer.Typer(no_args_is_help=True)

{monolynx_cli-0.2.0 → monolynx_cli-0.3.0}/src/monolynx_cli/version.py

@@ -6,4 +6,4 @@ istnieje jako pole statyczne. Job `publish-pypi` / `publish-testpypi` w CI
 porównuje tę wartość z tagiem `cli-v<wersja>` przed uploadem na PyPI.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"