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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/PKG-INFO +95 -12
  2. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/README.md +94 -11
  3. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/commands/_common.py +56 -0
  4. monolynx_cli-0.4.0/src/monolynx_cli/commands/blog.py +209 -0
  5. monolynx_cli-0.4.0/src/monolynx_cli/commands/graph.py +143 -0
  6. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/commands/ticket.py +37 -8
  7. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/main.py +6 -4
  8. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/version.py +1 -1
  9. monolynx_cli-0.4.0/tests/test_blog_commands.py +1195 -0
  10. monolynx_cli-0.4.0/tests/test_graph_commands.py +563 -0
  11. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_main.py +10 -0
  12. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_member_commands.py +0 -1
  13. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_oauth.py +1 -1
  14. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_ticket_commands.py +490 -14
  15. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_version_command.py +2 -2
  16. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_wiki_commands.py +12 -0
  17. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/.gitignore +0 -0
  18. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/LICENSE +0 -0
  19. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/packaging/homebrew/README.md +0 -0
  20. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/packaging/homebrew/monolynx.rb +0 -0
  21. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/pyproject.toml +0 -0
  22. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/scripts/bump_formula.py +0 -0
  23. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/__init__.py +0 -0
  24. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/__main__.py +0 -0
  25. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/client.py +0 -0
  26. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/commands/__init__.py +0 -0
  27. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/commands/auth.py +0 -0
  28. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/commands/completion.py +0 -0
  29. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/commands/config.py +0 -0
  30. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/commands/member.py +0 -0
  31. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/commands/project.py +0 -0
  32. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/commands/sprint.py +0 -0
  33. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/commands/version.py +0 -0
  34. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/commands/wiki.py +0 -0
  35. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/config.py +0 -0
  36. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/oauth.py +0 -0
  37. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/options.py +0 -0
  38. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/src/monolynx_cli/output.py +0 -0
  39. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/conftest.py +0 -0
  40. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_auth_commands.py +0 -0
  41. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_client.py +0 -0
  42. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_commands_common.py +0 -0
  43. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_completion.py +0 -0
  44. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_config.py +0 -0
  45. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_config_commands.py +0 -0
  46. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_error_handling.py +0 -0
  47. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_output.py +0 -0
  48. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_project_commands.py +0 -0
  49. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_smoke_e2e.py +0 -0
  50. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_sprint_commands.py +0 -0
  51. {monolynx_cli-0.2.0 → monolynx_cli-0.4.0}/tests/test_token_leak.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: monolynx-cli
3
- Version: 0.2.0
3
+ Version: 0.4.0
4
4
  Summary: Interfejs wiersza poleceń dla platformy Monolynx
5
5
  Project-URL: Homepage, https://gitlab.com/piotrkrych/monolynx
6
6
  Project-URL: Documentation, https://gitlab.com/piotrkrych/monolynx/-/blob/main/cli/README.md
@@ -34,7 +34,7 @@ Description-Content-Type: text/markdown
34
34
 
35
35
  [![PyPI](https://img.shields.io/pypi/v/monolynx-cli)](https://pypi.org/project/monolynx-cli/)
36
36
 
37
- Command-line client for the Monolynx platform: manage projects, tickets, sprints and wiki pages from your terminal.
37
+ Command-line client for the Monolynx platform: manage projects, tickets, sprints, wiki pages and blog posts (metadata, lint, publishing), and read the code dependency graph, from your terminal.
38
38
 
39
39
  ## Installation
40
40
 
@@ -157,7 +157,7 @@ monolynx auth login --endpoint https://monolynx.example.com --profile work
157
157
  - `--token` stores an API token without a browser (`auth_type = "token"`).
158
158
  - `--endpoint` and `--profile` work with both flows.
159
159
 
160
- 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:
160
+ The OAuth access token is valid for 30 days. Every command that calls the API keeps the session alive. `project`, `member`, `ticket`, `sprint`, `wiki`, `blog` and `graph` commands do it in two ways, `auth whoami` only reactively:
161
161
 
162
162
  - 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.
163
163
  - 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
239
239
 
240
240
  | Command | Arguments and options | Description |
241
241
  |---|---|---|
242
- | `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. |
242
+ | `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. |
243
243
  | `ticket search` | `[query]`, `--status`, `--priority`, `--assignee`, `--sprint`, `--due-before`, `--due-after`, `--page` | Search tickets by phrase (title or description) and filters (one page). |
244
- | `ticket get` | `<ticket>` | Show ticket details. |
245
- | `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). |
246
- | `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). |
244
+ | `ticket get` | `<ticket>` | Show ticket details, including `spec_page_id` (`null` when the ticket has no spec page). |
245
+ | `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. |
246
+ | `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. |
247
247
  | `ticket delete` | `<ticket>`, `-y`/`--yes` | Delete a ticket (asks for confirmation unless `--yes`). |
248
248
  | `ticket bulk-update` | `<tickets>...`, `--status`, `--priority`, `--assignee`, `--sprint`, `--due` | Update many tickets in one request. |
249
249
  | `ticket comment list` | `<ticket>` | List ticket comments (all pages, flat list). |
@@ -261,6 +261,11 @@ Notes:
261
261
  - 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.
262
262
  - `--description -` and `--body -` read the text from stdin.
263
263
  - In `ticket update` and `ticket bulk-update`, an empty string for `--sprint`, `--assignee` or `--due` clears the value.
264
+ - `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`.
265
+ - `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.
266
+ - `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.
267
+ - `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`.
268
+ - `--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.
264
269
 
265
270
  ```bash
266
271
  monolynx --project my-project ticket create --title "Fix login redirect" --priority high --sp 2 --ac "Redirect keeps the next parameter"
@@ -295,7 +300,85 @@ git log -1 --format=%B | monolynx --project my-project ticket comment add MP-11
295
300
  | `wiki config get` | | Show the LLM Wiki method configuration of the project. |
296
301
  | `wiki config set` | `--enabled`/`--disabled` | Turn the LLM Wiki method on or off (requires the `settings:write` permission). |
297
302
 
298
- `--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).
303
+ `--public` publishes the page at `/blog/{slug}`, visible to anyone without signing in. It is the lower level of publishing, without the lint gate: `blog publish` runs the lint first and refuses a post with lint errors, and `blog unpublish` takes a post offline. Publishing needs the blog permission on your account, on top of `wiki:write`: `wiki create --public`, and a `wiki update --public` or `wiki update --no-public` that changes the current state, are refused with a 403 (`Brak uprawnienia blog:write`, exit code 3) for an account without it, and nothing is saved. The permission is described under [`blog`](#blog). `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).
304
+
305
+ ### `blog`
306
+
307
+ Blog posts: metadata, lint, publishing and unpublishing. A blog post is a wiki page that has a blog metadata row; the page content stays in `monolynx wiki`. All `blog` commands work on the project resolved from `--project`, `MONOLYNX_PROJECT` or the profile. `blog list`, `blog get` and `blog lint` need the `wiki:read` permission; `blog meta`, `blog publish` and `blog unpublish` need `wiki:write` and the blog permission (`blog publish` runs the lint, so it needs `wiki:read` as well).
308
+
309
+ The blog permission (`blog:write`) belongs to the user account, not to a role in a project, and is off by default. Only a superuser grants or revokes it, with the switch on the account edit page in the dashboard (`/dashboard/users/{user_id}`); a superuser always has it. A project owner or admin cannot grant it, and the CLI has no command for it. Without it, `blog meta`, `blog publish` and `blog unpublish` end with a 403 (`Brak uprawnienia blog:write`) and exit code 3, before the post is looked up or linted, and nothing is changed. Signing in again does not help: ask a superuser to grant the permission.
310
+
311
+ | Command | Arguments and options | Description |
312
+ |---|---|---|
313
+ | `blog list` | `--status` (`published` or `draft`) | List the blog posts of the project, published ones and drafts, with their metadata and without the content (all pages, flat list). Without `--status` every post is listed. |
314
+ | `blog get` | `<page_id>` | Show a blog post: metadata, public URLs and the markdown content. |
315
+ | `blog meta` | `<page_id>`, `--slug`, `--description`, `--author`, `--tag`, `--no-tags`, `--lang`, `--translation-of`, `--cover`, `--verified` | Change the metadata of a blog post; only the given options are sent. `--tag` can be repeated. |
316
+ | `blog lint` | `<page_id>` | Lint a blog post for AI readers (description, TLDR block, headings, image alt text, graphic blocks, links): a list of problems and a score from 0 to 100. Exit code 1 when at least one problem is an error. |
317
+ | `blog publish` | `<page_id>`, `--force` | Publish a blog post after the lint. A post with lint errors is refused (exit code 1) and stays private, unless `--force` is given. |
318
+ | `blog unpublish` | `<page_id>` | Unpublish a blog post: its address and its `.md` version answer 404, the publication date and the slug stay. |
319
+
320
+ Notes:
321
+
322
+ - `<page_id>` is the UUID of the wiki page that is the blog post: the `page_id` field from `blog list`, the same id `wiki get` takes.
323
+ - `blog list` with `-o table` prints six columns: `title`, `slug`, `is_public`, `lang`, `published_at` and `tags` (the tags joined with `, `). With `-o json`, `-o yaml` and `-o csv` every post carries all its fields, so read `page_id` from one of those formats, for example `-o json`.
324
+ - A draft is a page that has a metadata row and `is_public` set to `false`; `--status draft` lists those, `--status published` the public ones. A wiki page without a metadata row is not a blog post: it is not on the list, and `blog get` ends with a 404 (exit code 1). The row is created when the page is published (`blog publish`, `wiki create --public`, `wiki update --public`) or by the first `blog meta` on that page. The server rejects any other `--status` value with a 422 (exit code 1).
325
+ - Outside the `blog list` table, every post carries `page_id`, `title`, `slug`, `previous_slugs`, `description`, `published_at`, `author_name`, `tags`, `lang`, `translation_of_id`, `cover_attachment_id`, `last_verified_at`, `is_public`, `public_url` and `markdown_url`; `blog get` adds `content`. `public_url` (the server's public address followed by `/blog/<slug>`) and `markdown_url` (`public_url` followed by `.md`) are `null` for a page that is not public. `markdown_url` is the address of the markdown twin of the post.
326
+ - `blog meta` options: `--slug` sets a new slug (the old one goes to `previous_slugs` and redirects), `--description` the post description (meta description), `--author` the author name, `--lang` the post language (`pl` or `en`), `--translation-of` the UUID of the wiki page holding the original of a translation, `--cover` the UUID of an attachment of the same page used as the cover, `--verified` the date the content was last verified (`YYYY-MM-DD`).
327
+ - `--tag` replaces the current tags with the given ones; `--no-tags` removes all tags. Giving both is a usage error.
328
+ - An empty string clears `--translation-of`, `--cover` and `--verified` (the CLI sends `null`), for example `--cover ""`.
329
+ - `blog meta` without any option, or with `--tag` and `--no-tags` together, is a usage error: exit code 2, no request sent.
330
+ - `blog get`, `blog lint` and `blog publish` read the post content from object storage. When the storage is unavailable the server answers 503 and the command ends with exit code 1 (`blog get` and `blog lint` after the retries; `blog publish` is a POST, which is not retried on a 5xx, and the post is not published); `blog list`, `blog meta` and `blog unpublish` do not read the content.
331
+ - `blog lint` result: `page_id`, `score` (0 to 100: 100 minus 20 for every error and 5 for every warning, never below 0; an info does not lower it), `error_count`, `warning_count`, `info_count` and `issues`, a list of objects with `rule` (the rule name, for example `tldr-missing` or `image-alt-short`), `level` (`error`, `warning` or `info`), `line` (the line of the post source, counted from 1; `0` for a problem with the metadata or with no place in the text) and `message` (in Polish). `-o json` and `-o yaml` print the whole object. `-o table` prints one row per problem with the columns `line`, `level`, `rule` and `message`, and the score as `Ocena: <score>/100` on standard error (`--quiet` hides it).
332
+ - `blog lint` exit codes: 0 when the post has no error (warnings and infos alone are still 0), 1 when at least one problem has the level `error`. The report is printed before the command exits, so with exit code 1 check standard output first: a report there means lint errors, an empty one means an API error (for example a 404 for a page that is not a blog post) or an invalid server response. The lint never changes the post.
333
+ - `blog publish` runs the same lint as `blog lint` and then makes the page public at `/blog/<slug>`. When the lint finds at least one problem of the level `error`, the server refuses with a 422: the command ends with exit code 1, prints the reason on standard error (`Publikacja odrzucona: wpis ma błędy lintu (<count>): <rule> (linia <line>), ... Napraw je albo użyj force.`, only the rules of the level `error`) and nothing on standard output, and the post stays private. Warnings and infos do not block the publication.
334
+ - `--force` publishes in spite of lint errors. It is a switch and takes no value.
335
+ - `blog publish` result: the post fields listed above, now with `is_public` set to `true` and both URLs filled in, plus `lint`, the object `blog lint` returns (`page_id`, `score`, `error_count`, `warning_count`, `info_count`, `issues`). Read it with `-o json` or `-o yaml`.
336
+ - `published_at` is set by the first publication only. Publishing an already public post, or publishing again after `blog unpublish`, keeps the date, the slug and the address.
337
+ - `blog publish` on a wiki page without a metadata row creates the row (slug taken from the page). A public page with the same slug in another project, or a slug already used by another post, is a 422 with a readable reason (exit code 1); nothing is published.
338
+ - `blog unpublish` sets `is_public` to `false`: `/blog/<slug>` and `/blog/<slug>.md` answer 404, and the result carries `public_url` and `markdown_url` as `null`. The slug and `published_at` stay. On a post that is already private it succeeds without a change; on a wiki page without a metadata row it ends with a 404 (exit code 1).
339
+ - `wiki create --public`, `wiki update --public` and `wiki update --no-public` still work as the lower level, without the lint gate, but behind the same blog permission: a change of the public state by an account without it is a 403 (exit code 3). Use `blog publish` and `blog unpublish` when the lint should decide.
340
+ - `blog meta` does not change the title, the content, `is_public` or `published_at`. Use `wiki update` for the title and the content, and `blog publish` / `blog unpublish` for publishing.
341
+ - 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. After `blog meta`, `blog publish` or `blog unpublish` the write may already have reached the server, so check the post with `blog get` before repeating the command.
342
+
343
+ ```bash
344
+ monolynx --project my-project blog list --status draft
345
+ monolynx -o json --project my-project blog get "<page_id>" | jq -r '.public_url'
346
+ monolynx --project my-project blog meta "<page_id>" --description "How we ship releases" --tag release --tag cli
347
+ monolynx --project my-project blog meta "<page_id>" --no-tags --cover ""
348
+ monolynx --project my-project blog lint "<page_id>"
349
+ monolynx -o json --project my-project blog lint "<page_id>" | jq -r '.issues[] | select(.level == "error") | "\(.line): \(.rule)"'
350
+ monolynx -o json --project my-project blog publish "<page_id>" | jq -r '.public_url'
351
+ monolynx --project my-project blog publish "<page_id>" --force
352
+ monolynx --project my-project blog unpublish "<page_id>"
353
+ ```
354
+
355
+ ### `graph`
356
+
357
+ 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.
358
+
359
+ | Command | Arguments and options | Description |
360
+ |---|---|---|
361
+ | `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. |
362
+ | `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. |
363
+ | `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. |
364
+ | `graph path` | `--source-id` (required), `--target-id` (required) | Find the shortest path between two nodes. |
365
+ | `graph stats` | | Show graph statistics: the number of nodes and edges, in total and per type. |
366
+
367
+ Notes:
368
+
369
+ - `<node_id>` is the `id` field from `graph nodes`. It may contain `/`; the CLI URL-encodes it.
370
+ - Node types are `File`, `Class`, `Method`, `Function`, `Const` and `Module`. Relation types are `CONTAINS`, `CALLS`, `IMPORTS`, `INHERITS`, `USES` and `IMPLEMENTS`.
371
+ - `--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.
372
+ - `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`.
373
+ - 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.
374
+ - 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).
375
+ - 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.
376
+
377
+ ```bash
378
+ monolynx --project my-project graph nodes --type Class --search Sprint
379
+ monolynx --project my-project graph node "<node_id>" --depth 2 --relation-type CALLS --relation-type IMPORTS
380
+ monolynx -o json --project my-project graph stats | jq '.nodes_by_type'
381
+ ```
299
382
 
300
383
  ### `version`
301
384
 
@@ -312,7 +395,7 @@ monolynx -o json version --check
312
395
 
313
396
  ### Reserved groups
314
397
 
315
- `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).
398
+ `monitoring`, `issues`, `time`, `plan`, `rozliczenia`, `pipeline`, `heartbeat` and `role` appear in `monolynx --help` but are reserved: they have no commands yet (not yet available).
316
399
 
317
400
  ### Confirmations
318
401
 
@@ -387,9 +470,9 @@ Resolution order for every setting: command-line option, then environment variab
387
470
  | Code | Meaning | Example causes |
388
471
  |---|---|---|
389
472
  | `0` | Success | |
390
- | `1` | API or local error | 4xx other than 401/403 (for example 404 or 422), 429 or 5xx after all retries; corrupted config file; declined confirmation; `config get` for a key without a value |
473
+ | `1` | API or local error | 4xx other than 401/403 (for example 404 or 422), 429 or 5xx after all retries; corrupted config file; declined confirmation; `config get` for a key without a value; `blog lint` on a post with at least one lint error (the report is printed first); `blog publish` refused because of lint errors (a 422, the reason on standard error) |
391
474
  | `2` | Usage error | Unknown option or bad argument; no project resolved; destructive command without `--yes` outside a terminal; `--timeout` not greater than zero; invalid `config` key; `update` without any field to change; empty stdin for `--content -`; a bare `.` or `..` as an identifier in a URL path |
392
- | `3` | Authentication error | 401 or 403; failed token refresh; no token stored; OAuth login timeout, denied consent or mismatched `state` |
475
+ | `3` | Authentication error | 401 or 403 (a 403 is a missing permission, for example `Brak uprawnienia blog:write` for publishing without the blog permission); failed token refresh; no token stored; OAuth login timeout, denied consent or mismatched `state` |
393
476
  | `4` | Network error | Timeout, connection refused, DNS failure |
394
477
 
395
478
  Errors are printed on stderr as `Błąd: <status> <title>: <detail>`. `--quiet` does not silence them.
@@ -425,7 +508,7 @@ monolynx -o json --project my-project ticket list | jq -r '.items[] | .key'
425
508
  monolynx -o json --project my-project ticket list --page 2 | jq '.total_pages'
426
509
  ```
427
510
 
428
- `project list`, `member list`, `wiki list`, `sprint list`, `ticket comment list`, `ticket label list` and `ticket ac list` fetch all pages themselves and return a flat list, so there is no `.items`:
511
+ `project list`, `member list`, `wiki list`, `blog list`, `sprint list`, `ticket comment list`, `ticket label list` and `ticket ac list` fetch all pages themselves and return a flat list, so there is no `.items`:
429
512
 
430
513
  ```bash
431
514
  monolynx -o json project list | jq -r '.[].slug'
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![PyPI](https://img.shields.io/pypi/v/monolynx-cli)](https://pypi.org/project/monolynx-cli/)
4
4
 
5
- Command-line client for the Monolynx platform: manage projects, tickets, sprints and wiki pages from your terminal.
5
+ Command-line client for the Monolynx platform: manage projects, tickets, sprints, wiki pages and blog posts (metadata, lint, publishing), and read the code dependency graph, from your terminal.
6
6
 
7
7
  ## Installation
8
8
 
@@ -125,7 +125,7 @@ monolynx auth login --endpoint https://monolynx.example.com --profile work
125
125
  - `--token` stores an API token without a browser (`auth_type = "token"`).
126
126
  - `--endpoint` and `--profile` work with both flows.
127
127
 
128
- 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:
128
+ The OAuth access token is valid for 30 days. Every command that calls the API keeps the session alive. `project`, `member`, `ticket`, `sprint`, `wiki`, `blog` and `graph` commands do it in two ways, `auth whoami` only reactively:
129
129
 
130
130
  - 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.
131
131
  - 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
207
207
 
208
208
  | Command | Arguments and options | Description |
209
209
  |---|---|---|
210
- | `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. |
210
+ | `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. |
211
211
  | `ticket search` | `[query]`, `--status`, `--priority`, `--assignee`, `--sprint`, `--due-before`, `--due-after`, `--page` | Search tickets by phrase (title or description) and filters (one page). |
212
- | `ticket get` | `<ticket>` | Show ticket details. |
213
- | `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). |
214
- | `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). |
212
+ | `ticket get` | `<ticket>` | Show ticket details, including `spec_page_id` (`null` when the ticket has no spec page). |
213
+ | `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. |
214
+ | `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. |
215
215
  | `ticket delete` | `<ticket>`, `-y`/`--yes` | Delete a ticket (asks for confirmation unless `--yes`). |
216
216
  | `ticket bulk-update` | `<tickets>...`, `--status`, `--priority`, `--assignee`, `--sprint`, `--due` | Update many tickets in one request. |
217
217
  | `ticket comment list` | `<ticket>` | List ticket comments (all pages, flat list). |
@@ -229,6 +229,11 @@ Notes:
229
229
  - 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.
230
230
  - `--description -` and `--body -` read the text from stdin.
231
231
  - In `ticket update` and `ticket bulk-update`, an empty string for `--sprint`, `--assignee` or `--due` clears the value.
232
+ - `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`.
233
+ - `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.
234
+ - `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.
235
+ - `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`.
236
+ - `--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.
232
237
 
233
238
  ```bash
234
239
  monolynx --project my-project ticket create --title "Fix login redirect" --priority high --sp 2 --ac "Redirect keeps the next parameter"
@@ -263,7 +268,85 @@ git log -1 --format=%B | monolynx --project my-project ticket comment add MP-11
263
268
  | `wiki config get` | | Show the LLM Wiki method configuration of the project. |
264
269
  | `wiki config set` | `--enabled`/`--disabled` | Turn the LLM Wiki method on or off (requires the `settings:write` permission). |
265
270
 
266
- `--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).
271
+ `--public` publishes the page at `/blog/{slug}`, visible to anyone without signing in. It is the lower level of publishing, without the lint gate: `blog publish` runs the lint first and refuses a post with lint errors, and `blog unpublish` takes a post offline. Publishing needs the blog permission on your account, on top of `wiki:write`: `wiki create --public`, and a `wiki update --public` or `wiki update --no-public` that changes the current state, are refused with a 403 (`Brak uprawnienia blog:write`, exit code 3) for an account without it, and nothing is saved. The permission is described under [`blog`](#blog). `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).
272
+
273
+ ### `blog`
274
+
275
+ Blog posts: metadata, lint, publishing and unpublishing. A blog post is a wiki page that has a blog metadata row; the page content stays in `monolynx wiki`. All `blog` commands work on the project resolved from `--project`, `MONOLYNX_PROJECT` or the profile. `blog list`, `blog get` and `blog lint` need the `wiki:read` permission; `blog meta`, `blog publish` and `blog unpublish` need `wiki:write` and the blog permission (`blog publish` runs the lint, so it needs `wiki:read` as well).
276
+
277
+ The blog permission (`blog:write`) belongs to the user account, not to a role in a project, and is off by default. Only a superuser grants or revokes it, with the switch on the account edit page in the dashboard (`/dashboard/users/{user_id}`); a superuser always has it. A project owner or admin cannot grant it, and the CLI has no command for it. Without it, `blog meta`, `blog publish` and `blog unpublish` end with a 403 (`Brak uprawnienia blog:write`) and exit code 3, before the post is looked up or linted, and nothing is changed. Signing in again does not help: ask a superuser to grant the permission.
278
+
279
+ | Command | Arguments and options | Description |
280
+ |---|---|---|
281
+ | `blog list` | `--status` (`published` or `draft`) | List the blog posts of the project, published ones and drafts, with their metadata and without the content (all pages, flat list). Without `--status` every post is listed. |
282
+ | `blog get` | `<page_id>` | Show a blog post: metadata, public URLs and the markdown content. |
283
+ | `blog meta` | `<page_id>`, `--slug`, `--description`, `--author`, `--tag`, `--no-tags`, `--lang`, `--translation-of`, `--cover`, `--verified` | Change the metadata of a blog post; only the given options are sent. `--tag` can be repeated. |
284
+ | `blog lint` | `<page_id>` | Lint a blog post for AI readers (description, TLDR block, headings, image alt text, graphic blocks, links): a list of problems and a score from 0 to 100. Exit code 1 when at least one problem is an error. |
285
+ | `blog publish` | `<page_id>`, `--force` | Publish a blog post after the lint. A post with lint errors is refused (exit code 1) and stays private, unless `--force` is given. |
286
+ | `blog unpublish` | `<page_id>` | Unpublish a blog post: its address and its `.md` version answer 404, the publication date and the slug stay. |
287
+
288
+ Notes:
289
+
290
+ - `<page_id>` is the UUID of the wiki page that is the blog post: the `page_id` field from `blog list`, the same id `wiki get` takes.
291
+ - `blog list` with `-o table` prints six columns: `title`, `slug`, `is_public`, `lang`, `published_at` and `tags` (the tags joined with `, `). With `-o json`, `-o yaml` and `-o csv` every post carries all its fields, so read `page_id` from one of those formats, for example `-o json`.
292
+ - A draft is a page that has a metadata row and `is_public` set to `false`; `--status draft` lists those, `--status published` the public ones. A wiki page without a metadata row is not a blog post: it is not on the list, and `blog get` ends with a 404 (exit code 1). The row is created when the page is published (`blog publish`, `wiki create --public`, `wiki update --public`) or by the first `blog meta` on that page. The server rejects any other `--status` value with a 422 (exit code 1).
293
+ - Outside the `blog list` table, every post carries `page_id`, `title`, `slug`, `previous_slugs`, `description`, `published_at`, `author_name`, `tags`, `lang`, `translation_of_id`, `cover_attachment_id`, `last_verified_at`, `is_public`, `public_url` and `markdown_url`; `blog get` adds `content`. `public_url` (the server's public address followed by `/blog/<slug>`) and `markdown_url` (`public_url` followed by `.md`) are `null` for a page that is not public. `markdown_url` is the address of the markdown twin of the post.
294
+ - `blog meta` options: `--slug` sets a new slug (the old one goes to `previous_slugs` and redirects), `--description` the post description (meta description), `--author` the author name, `--lang` the post language (`pl` or `en`), `--translation-of` the UUID of the wiki page holding the original of a translation, `--cover` the UUID of an attachment of the same page used as the cover, `--verified` the date the content was last verified (`YYYY-MM-DD`).
295
+ - `--tag` replaces the current tags with the given ones; `--no-tags` removes all tags. Giving both is a usage error.
296
+ - An empty string clears `--translation-of`, `--cover` and `--verified` (the CLI sends `null`), for example `--cover ""`.
297
+ - `blog meta` without any option, or with `--tag` and `--no-tags` together, is a usage error: exit code 2, no request sent.
298
+ - `blog get`, `blog lint` and `blog publish` read the post content from object storage. When the storage is unavailable the server answers 503 and the command ends with exit code 1 (`blog get` and `blog lint` after the retries; `blog publish` is a POST, which is not retried on a 5xx, and the post is not published); `blog list`, `blog meta` and `blog unpublish` do not read the content.
299
+ - `blog lint` result: `page_id`, `score` (0 to 100: 100 minus 20 for every error and 5 for every warning, never below 0; an info does not lower it), `error_count`, `warning_count`, `info_count` and `issues`, a list of objects with `rule` (the rule name, for example `tldr-missing` or `image-alt-short`), `level` (`error`, `warning` or `info`), `line` (the line of the post source, counted from 1; `0` for a problem with the metadata or with no place in the text) and `message` (in Polish). `-o json` and `-o yaml` print the whole object. `-o table` prints one row per problem with the columns `line`, `level`, `rule` and `message`, and the score as `Ocena: <score>/100` on standard error (`--quiet` hides it).
300
+ - `blog lint` exit codes: 0 when the post has no error (warnings and infos alone are still 0), 1 when at least one problem has the level `error`. The report is printed before the command exits, so with exit code 1 check standard output first: a report there means lint errors, an empty one means an API error (for example a 404 for a page that is not a blog post) or an invalid server response. The lint never changes the post.
301
+ - `blog publish` runs the same lint as `blog lint` and then makes the page public at `/blog/<slug>`. When the lint finds at least one problem of the level `error`, the server refuses with a 422: the command ends with exit code 1, prints the reason on standard error (`Publikacja odrzucona: wpis ma błędy lintu (<count>): <rule> (linia <line>), ... Napraw je albo użyj force.`, only the rules of the level `error`) and nothing on standard output, and the post stays private. Warnings and infos do not block the publication.
302
+ - `--force` publishes in spite of lint errors. It is a switch and takes no value.
303
+ - `blog publish` result: the post fields listed above, now with `is_public` set to `true` and both URLs filled in, plus `lint`, the object `blog lint` returns (`page_id`, `score`, `error_count`, `warning_count`, `info_count`, `issues`). Read it with `-o json` or `-o yaml`.
304
+ - `published_at` is set by the first publication only. Publishing an already public post, or publishing again after `blog unpublish`, keeps the date, the slug and the address.
305
+ - `blog publish` on a wiki page without a metadata row creates the row (slug taken from the page). A public page with the same slug in another project, or a slug already used by another post, is a 422 with a readable reason (exit code 1); nothing is published.
306
+ - `blog unpublish` sets `is_public` to `false`: `/blog/<slug>` and `/blog/<slug>.md` answer 404, and the result carries `public_url` and `markdown_url` as `null`. The slug and `published_at` stay. On a post that is already private it succeeds without a change; on a wiki page without a metadata row it ends with a 404 (exit code 1).
307
+ - `wiki create --public`, `wiki update --public` and `wiki update --no-public` still work as the lower level, without the lint gate, but behind the same blog permission: a change of the public state by an account without it is a 403 (exit code 3). Use `blog publish` and `blog unpublish` when the lint should decide.
308
+ - `blog meta` does not change the title, the content, `is_public` or `published_at`. Use `wiki update` for the title and the content, and `blog publish` / `blog unpublish` for publishing.
309
+ - 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. After `blog meta`, `blog publish` or `blog unpublish` the write may already have reached the server, so check the post with `blog get` before repeating the command.
310
+
311
+ ```bash
312
+ monolynx --project my-project blog list --status draft
313
+ monolynx -o json --project my-project blog get "<page_id>" | jq -r '.public_url'
314
+ monolynx --project my-project blog meta "<page_id>" --description "How we ship releases" --tag release --tag cli
315
+ monolynx --project my-project blog meta "<page_id>" --no-tags --cover ""
316
+ monolynx --project my-project blog lint "<page_id>"
317
+ monolynx -o json --project my-project blog lint "<page_id>" | jq -r '.issues[] | select(.level == "error") | "\(.line): \(.rule)"'
318
+ monolynx -o json --project my-project blog publish "<page_id>" | jq -r '.public_url'
319
+ monolynx --project my-project blog publish "<page_id>" --force
320
+ monolynx --project my-project blog unpublish "<page_id>"
321
+ ```
322
+
323
+ ### `graph`
324
+
325
+ 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.
326
+
327
+ | Command | Arguments and options | Description |
328
+ |---|---|---|
329
+ | `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. |
330
+ | `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. |
331
+ | `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. |
332
+ | `graph path` | `--source-id` (required), `--target-id` (required) | Find the shortest path between two nodes. |
333
+ | `graph stats` | | Show graph statistics: the number of nodes and edges, in total and per type. |
334
+
335
+ Notes:
336
+
337
+ - `<node_id>` is the `id` field from `graph nodes`. It may contain `/`; the CLI URL-encodes it.
338
+ - Node types are `File`, `Class`, `Method`, `Function`, `Const` and `Module`. Relation types are `CONTAINS`, `CALLS`, `IMPORTS`, `INHERITS`, `USES` and `IMPLEMENTS`.
339
+ - `--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.
340
+ - `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`.
341
+ - 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.
342
+ - 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).
343
+ - 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.
344
+
345
+ ```bash
346
+ monolynx --project my-project graph nodes --type Class --search Sprint
347
+ monolynx --project my-project graph node "<node_id>" --depth 2 --relation-type CALLS --relation-type IMPORTS
348
+ monolynx -o json --project my-project graph stats | jq '.nodes_by_type'
349
+ ```
267
350
 
268
351
  ### `version`
269
352
 
@@ -280,7 +363,7 @@ monolynx -o json version --check
280
363
 
281
364
  ### Reserved groups
282
365
 
283
- `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).
366
+ `monitoring`, `issues`, `time`, `plan`, `rozliczenia`, `pipeline`, `heartbeat` and `role` appear in `monolynx --help` but are reserved: they have no commands yet (not yet available).
284
367
 
285
368
  ### Confirmations
286
369
 
@@ -355,9 +438,9 @@ Resolution order for every setting: command-line option, then environment variab
355
438
  | Code | Meaning | Example causes |
356
439
  |---|---|---|
357
440
  | `0` | Success | |
358
- | `1` | API or local error | 4xx other than 401/403 (for example 404 or 422), 429 or 5xx after all retries; corrupted config file; declined confirmation; `config get` for a key without a value |
441
+ | `1` | API or local error | 4xx other than 401/403 (for example 404 or 422), 429 or 5xx after all retries; corrupted config file; declined confirmation; `config get` for a key without a value; `blog lint` on a post with at least one lint error (the report is printed first); `blog publish` refused because of lint errors (a 422, the reason on standard error) |
359
442
  | `2` | Usage error | Unknown option or bad argument; no project resolved; destructive command without `--yes` outside a terminal; `--timeout` not greater than zero; invalid `config` key; `update` without any field to change; empty stdin for `--content -`; a bare `.` or `..` as an identifier in a URL path |
360
- | `3` | Authentication error | 401 or 403; failed token refresh; no token stored; OAuth login timeout, denied consent or mismatched `state` |
443
+ | `3` | Authentication error | 401 or 403 (a 403 is a missing permission, for example `Brak uprawnienia blog:write` for publishing without the blog permission); failed token refresh; no token stored; OAuth login timeout, denied consent or mismatched `state` |
361
444
  | `4` | Network error | Timeout, connection refused, DNS failure |
362
445
 
363
446
  Errors are printed on stderr as `Błąd: <status> <title>: <detail>`. `--quiet` does not silence them.
@@ -393,7 +476,7 @@ monolynx -o json --project my-project ticket list | jq -r '.items[] | .key'
393
476
  monolynx -o json --project my-project ticket list --page 2 | jq '.total_pages'
394
477
  ```
395
478
 
396
- `project list`, `member list`, `wiki list`, `sprint list`, `ticket comment list`, `ticket label list` and `ticket ac list` fetch all pages themselves and return a flat list, so there is no `.items`:
479
+ `project list`, `member list`, `wiki list`, `blog list`, `sprint list`, `ticket comment list`, `ticket label list` and `ticket ac list` fetch all pages themselves and return a flat list, so there is no `.items`:
397
480
 
398
481
  ```bash
399
482
  monolynx -o json project list | jq -r '.[].slug'
@@ -32,6 +32,7 @@ from monolynx_cli.options import get_options
32
32
 
33
33
  PER_PAGE = 100
34
34
  STDIN_MARKER = "-"
35
+ BRIEF_TICKET_KEYS = ("id", "key", "title", "status", "sprint_id", "blocked_by", "blocks")
35
36
 
36
37
 
37
38
  def _stdin_is_tty() -> bool:
@@ -136,6 +137,61 @@ def _invalid_page(detail: str) -> MonolynxAPIError:
136
137
  return MonolynxAPIError(200, "Nieprawidłowa odpowiedź serwera", detail)
137
138
 
138
139
 
140
+ def require_list_with_blockers(payload: Any) -> dict[str, Any]:
141
+ """Sprawdź kontrakt odpowiedzi `ticket list`: koperta z `items`, każdy element z listą `blocked_by`.
142
+
143
+ Serwer sprzed MON-246 nie niesie `blocked_by`; kolumna z kluczami blokerów pokazałaby wtedy
144
+ puste pole, nieodróżnialne od ticketu bez blokerów, więc brak pola to błąd kontraktu.
145
+ """
146
+ if not isinstance(payload, dict):
147
+ raise _invalid_page("Odpowiedź nie jest obiektem JSON.")
148
+ items = payload.get("items")
149
+ if not isinstance(items, list) or not all(isinstance(item, dict) for item in items):
150
+ raise _invalid_page("Pole items nie jest listą obiektów.")
151
+ for index, item in enumerate(items):
152
+ blockers = item.get("blocked_by")
153
+ if not isinstance(blockers, list):
154
+ raise _invalid_page(f"Element items[{index}] nie ma listy blocked_by (serwer bez obsługi blokerów w liście ticketów).")
155
+ for position, blocker in enumerate(blockers):
156
+ if not isinstance(blocker, dict) or not isinstance(blocker.get("key"), str) or not blocker["key"]:
157
+ raise _invalid_page(f"Element items[{index}].blocked_by[{position}] nie jest obiektem z niepustym kluczem key.")
158
+ return payload
159
+
160
+
161
+ def require_spec_page_id(payload: Any) -> dict[str, Any]:
162
+ """Sprawdź kontrakt odpowiedzi `ticket get`: klucz `spec_page_id` musi istnieć (wartość `null` jest poprawna)."""
163
+ if not isinstance(payload, dict):
164
+ raise _invalid_page("Odpowiedź nie jest obiektem JSON.")
165
+ if "spec_page_id" not in payload:
166
+ raise _invalid_page("Brak pola spec_page_id (serwer bez obsługi spec_page_id w szczegółach ticketu).")
167
+ return payload
168
+
169
+
170
+ def require_brief_ticket(payload: Any) -> dict[str, Any]:
171
+ """Sprawdź kontrakt odpowiedzi `ticket create|update` pod `--brief` i zwróć tylko 7 pól w stałej kolejności.
172
+
173
+ Brak klucza albo zły typ to błąd kontraktu, nigdy puste pole z kodem 0: agent czytający
174
+ potwierdzenie zapisu nie odróżniłby `""` od ticketu bez statusu. `sprint_id` może być `null`.
175
+ """
176
+ if not isinstance(payload, dict):
177
+ raise _invalid_page("Odpowiedź nie jest obiektem JSON.")
178
+ for name in ("id", "key"):
179
+ value = payload.get(name)
180
+ if not isinstance(value, str) or not value:
181
+ raise _invalid_page(f"Pole {name} nie jest niepustym tekstem.")
182
+ for name in ("title", "status", "sprint_id"):
183
+ if name not in payload:
184
+ raise _invalid_page(f"Brak pola {name} w odpowiedzi ticketu.")
185
+ for name in ("blocked_by", "blocks"):
186
+ relations = payload.get(name)
187
+ if not isinstance(relations, list):
188
+ raise _invalid_page(f"Pole {name} nie jest listą (brak lub zły typ w odpowiedzi ticketu).")
189
+ for position, relation in enumerate(relations):
190
+ if not isinstance(relation, dict) or not isinstance(relation.get("key"), str) or not relation["key"]:
191
+ raise _invalid_page(f"Element {name}[{position}] nie jest obiektem z niepustym kluczem key.")
192
+ return {name: payload[name] for name in BRIEF_TICKET_KEYS}
193
+
194
+
139
195
  def fetch_all(client: MonolynxClient, path: str, params: dict[str, Any] | None = None) -> list[dict[str, Any]]:
140
196
  """Pobierz elementy ze wszystkich stron; `params` (np. filtr statusu) idą na każdą stronę."""
141
197
  items: list[dict[str, Any]] = []