netconverter-cli 0.4.0__tar.gz → 0.4.2__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 (64) hide show
  1. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/CHANGELOG.md +52 -0
  2. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/PKG-INFO +1 -1
  3. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/docs/COMMANDS.md +13 -4
  4. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/docs/PRIVACY.md +10 -4
  5. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/docs/connect/README.md +1 -0
  6. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/pyproject.toml +2 -1
  7. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/__init__.py +1 -1
  8. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/api.py +19 -5
  9. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/clerk.py +5 -2
  10. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/cli.py +129 -21
  11. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/credentials.py +53 -0
  12. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/mcp_server.py +133 -14
  13. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/remote_mcp.py +40 -1
  14. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/setup.py +3 -2
  15. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/conftest.py +9 -0
  16. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_clerk.py +15 -0
  17. netconverter_cli-0.4.2/tests/test_keyring_bus_017.py +102 -0
  18. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_mcp.py +29 -1
  19. netconverter_cli-0.4.2/tests/test_mcp_auth_016.py +127 -0
  20. netconverter_cli-0.4.2/tests/test_readonly_workspace.py +56 -0
  21. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_setup.py +1 -1
  22. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_signin_default.py +20 -2
  23. netconverter_cli-0.4.2/tests/test_strict_view_015.py +174 -0
  24. netconverter_cli-0.4.2/tests/test_vendor_error_022.py +91 -0
  25. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/.gitignore +0 -0
  26. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/LICENSE +0 -0
  27. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/QUICK_START.md +0 -0
  28. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/README.md +0 -0
  29. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/SECURITY.md +0 -0
  30. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/docs/RELEASING.md +0 -0
  31. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/docs/VERIFICATION.md +0 -0
  32. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/docs/connect/chatgpt.md +0 -0
  33. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/docs/connect/claude-ai.md +0 -0
  34. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/docs/connect/claude-code.md +0 -0
  35. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/docs/connect/claude-desktop.md +0 -0
  36. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/docs/connect/getting-access.md +0 -0
  37. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/docs/connect/other-assistants.md +0 -0
  38. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/examples/README.md +0 -0
  39. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/activity.py +0 -0
  40. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/backend.py +0 -0
  41. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/branding.py +0 -0
  42. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/catalog.py +0 -0
  43. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/commands.py +0 -0
  44. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/connect.py +0 -0
  45. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/controller.py +0 -0
  46. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/guided.py +0 -0
  47. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/palette.py +0 -0
  48. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/presentation.py +0 -0
  49. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/privacy.py +0 -0
  50. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/providers.py +0 -0
  51. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/tui.py +0 -0
  52. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/update.py +0 -0
  53. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/src/netconverter_cli/workspace.py +0 -0
  54. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_boundaries.py +0 -0
  55. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_clerk_host_binding.py +0 -0
  56. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_cli_020.py +0 -0
  57. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_connect_030.py +0 -0
  58. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_connect_031.py +0 -0
  59. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_download_analysis.py +0 -0
  60. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_inline.py +0 -0
  61. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_presentation.py +0 -0
  62. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_protocols.py +0 -0
  63. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_sessions.py +0 -0
  64. {netconverter_cli-0.4.0 → netconverter_cli-0.4.2}/tests/test_update.py +0 -0
@@ -1,5 +1,57 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.4.2 — 2026-10-23
4
+
5
+ - **Running from a read-only folder no longer crashes.** Started from `/` (or any folder
6
+ you can't write) without `--workspace`, the CLI uses `~/migrations`, the folder the
7
+ installer creates, and says so on stderr. Before, first-run setup tried to create
8
+ `/.netconverter` and stopped with `OSError: Read-only file system`. An explicit
9
+ `--workspace` that can't be written is a one-line error. `login --key` from such a
10
+ folder still stores the key and skips remembering the server there.
11
+ - **`mcp --strict` requests and verifies the server's strict view (#15).** The bridge sends
12
+ `X-NetConverter-View: strict` on every remote request (the server may only lower the
13
+ grant's view) and reads the view in force from `get_account`; `account` now reports
14
+ `view_mode` and `strict_enforced_by` (`server`/`client`) next to the `strict_mode` flag.
15
+ Until the server applies the strict view for the account, the bridge enforces it locally:
16
+ `get_evidence section=unparsed_lines`, `get_job_brief focus=target` and any `fetch` that is
17
+ not `kb:<doc_id>` are refused before any network call, every IPv4/IPv6 address or prefix in
18
+ a remote result is masked as `<ip>`/`<cidr>`, and one stderr line says so. Names inside
19
+ summaries are tokenised only by the server's strict view.
20
+ - **Linux: the bridge finds the keyring when the assistant hides the D-Bus bus (#17).**
21
+ Codex, Cursor CLI and OpenClaw start MCP servers without `DBUS_SESSION_BUS_ADDRESS`, so
22
+ the Clerk sign-in in the Secret Service was invisible and every tool said "not signed
23
+ in". The client now points at `$XDG_RUNTIME_DIR/bus`, then `/run/user/<uid>/bus`, before
24
+ keyring picks its backend. When no OS keyring is reachable, tool errors and the
25
+ `netconverter mcp` startup line say `keyring_unreachable` and name the fix (set the bus
26
+ address or `NETCONVERTER_API_KEY` in the assistant's MCP env) instead of "sign in".
27
+ - **One credential per `netconverter mcp` process (#16).** The bridge honours
28
+ `NETCONVERTER_AUTH` (`NETCONVERTER_MCP_AUTH` still overrides it for `mcp` alone). In
29
+ `auto` mode a Clerk sign-in is preferred and used for both the REST API and the remote
30
+ tools; an API key from `NETCONVERTER_API_KEY` or the credential store is used only when
31
+ chosen (`--auth key`) or when there is no sign-in, never for one surface while the
32
+ sign-in serves the other. A startup line on stderr names the credential in use and the
33
+ one left unused; `account` reports it as `credential_source`.
34
+ - **Refused requests show the server's reason (#22).** `APIError` now reads the External
35
+ API's `error.message` (an older server's string `detail` too) and prints it, so
36
+ `validate --vendor auto` says `unknown source_vendor 'auto'; valid: [...]` instead of a
37
+ bare HTTP 422; MCP tool errors carry the same reason. `validate`/`analyze`/`optimize`/
38
+ `convert` also check `--vendor` against the server's capabilities before uploading and
39
+ list the valid source codes (there is no `auto`; detection lives in the guided flow).
40
+ - **`wait_for_job` fits a 60 s client tool timeout (#18).** The default `timeout_s` is 45
41
+ (was 300; max still 600). A job still running when the wait ends comes back with
42
+ `timed_out: true` and `next: "still running; call wait_for_job again …"` instead of the
43
+ call being cut off by Codex or OpenClaw mid-job. Pass a larger `timeout_s` explicitly when
44
+ the client allows a longer wait.
45
+
46
+ ## 0.4.1 — 2026-10-22
47
+
48
+ - **First-run setup honours the Clerk sign-in (#6).** `NETCONVERTER_API_KEY` in the
49
+ environment no longer skips the sign-in choice and is never copied into the OS keyring.
50
+ `whoami` reports `api_key_stored` for the keyring only and adds `api_key_in_environment`.
51
+ - **Sign-in errors show Clerk's full reason.** The OAuth error description was cut at
52
+ 200 characters, hiding the cause sentence (e.g. a missing `device_code` grant, #684).
53
+ - **`whoami` shows one label per organization** (name, else slug) instead of the raw `org_...` id.
54
+
3
55
  ## 0.4.0 — 2026-10-21
4
56
 
5
57
  - **On PyPI as `netconverter-cli`.** `uv tool install --python 3.12 netconverter-cli`
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: netconverter-cli
3
- Version: 0.4.0
3
+ Version: 0.4.2
4
4
  Summary: NetConverter CLI — any-vendor network configuration migration, validation and optimization, and a local MCP bridge for your AI assistant
5
5
  Project-URL: Homepage, https://netconverter.ai
6
6
  Project-URL: Repository, https://github.com/valeronlabs/netconverter_terminals
@@ -110,8 +110,8 @@ delays a command; its result is cached in your user cache folder.
110
110
  | --- | --- |
111
111
  | `submit_file(path, source_vendor, target_vendor?, job_type?, options?)` | `job_id`, `status`, `sha256`, `bytes`. `job_type`: `convert`, `validate`, `optimize`, or `analyze` (= validate) |
112
112
  | `job_status(job_id)` | Status, verdict, review flag, progress and stage when sent, reason counts, vendors |
113
- | `wait_for_job(job_id, timeout_s=300)` | The `job_status` summary plus `waited_s` and `timed_out`; polls 2 s, ×1.5, up to 15 s apart, at most 600 s. Sends MCP progress notifications when the call has a progress token |
114
- | `account()` | `tier`, `job_types`, `rate_limit_per_min`, `daily_quota`, `auth_kind`, `profile`, `client_version`, `update_available`, `latest_version`, `strict_mode` |
113
+ | `wait_for_job(job_id, timeout_s=45)` | The `job_status` summary plus `waited_s` and `timed_out` (plus `next` when still running: call it again); polls 2 s, ×1.5, up to 15 s apart, at most 600 s. The default stays under the 60 s tool timeout of Codex and OpenClaw; pass a larger `timeout_s` only when the client allows it. Sends MCP progress notifications when the call has a progress token |
114
+ | `account()` | `tier`, `job_types`, `rate_limit_per_min`, `daily_quota`, `auth_kind`, `profile`, `client_version`, `update_available`, `latest_version`, `strict_mode` (the `--strict` flag), `view_mode` (the view the server applies to this session, from `get_account`), `strict_enforced_by` (`server` when that view is strict, `client` while the bridge enforces it locally), `credential_source` (`clerk_session`, `api_key_environment`, `api_key_stored` or `none`; the one credential REST and the remote tools share) |
115
115
  | `download(job_id, dest_dir=".")` | Saved file names, sizes and SHA-256 |
116
116
 
117
117
  Remote NetConverter tools are proxied only from a fixed allowlist, and never a
@@ -126,11 +126,19 @@ Remote NetConverter tools are proxied only from a fixed allowlist, and never a
126
126
  With `--strict`: `list_jobs`, `select_job`, `get_account`, `search`, `fetch`,
127
127
  `kb_search`, `kb_explain`, `vendor_capability_lookup`, `get_job_brief`,
128
128
  `get_evidence`, `get_report`. A listed tool appears only if the server offers it.
129
+ `--strict` also asks the server for its strict view on every request (`X-NetConverter-View: strict`;
130
+ the server may only lower the grant's view, never raise it) and reads the view in force from
131
+ `get_account`. Until the server applies it, the bridge enforces strict locally: it refuses
132
+ `get_evidence section=unparsed_lines`, `get_job_brief focus=target` and any `fetch` that is not
133
+ `kb:<doc_id>` before any network call, masks every IPv4/IPv6 address and prefix in remote results
134
+ as `<ip>`/`<cidr>`, and says so once on stderr. Names in summaries are tokenised only by the
135
+ server's strict view; `account` reports which side is enforcing.
129
136
 
130
137
  Global options go before the subcommand: `netconverter --workspace DIR --server URL …`.
131
138
  Environment: `NETCONVERTER_URL`, `NETCONVERTER_PROVIDER`, `NETCONVERTER_MODEL`,
132
- `NETCONVERTER_AUTH=key` or `=clerk` (force one credential; unset, a stored key is used first, then
133
- your sign-in), `NETCONVERTER_TRUSTED_HOSTS`, `NETCONVERTER_MCP_STRICT=1` (same as `mcp --strict`),
139
+ `NETCONVERTER_AUTH=key` or `=clerk` (force one credential; unset, plain commands use a stored key first, then
140
+ your sign-in, while `mcp` prefers the sign-in and says on stderr which API key it leaves unused;
141
+ `NETCONVERTER_MCP_AUTH` overrides it for `mcp` only), `NETCONVERTER_TRUSTED_HOSTS`, `NETCONVERTER_MCP_STRICT=1` (same as `mcp --strict`),
134
142
  `NETCONVERTER_NO_UPDATE_CHECK=1` (no daily update check or notice; `account` then reports
135
143
  `update_available: null`).
136
144
  Never put a literal key in shell history or a shared script.
@@ -157,6 +165,7 @@ Never put a literal key in shell history or a shared script.
157
165
  | No verified configuration | Read validation reports and warnings; evidence can be available even when no deployable output is produced |
158
166
  | Proxy-only network fails | Client HTTP connections ignore environment proxy settings and do not follow redirects; use a network with direct access to configured endpoints |
159
167
  | Full-screen UI unsuitable | Use `netconverter plain` or individual CLI commands |
168
+ | `keyring_unreachable` from the bridge (Linux) | The assistant launched `netconverter mcp` without `DBUS_SESSION_BUS_ADDRESS`; the bridge tries `$XDG_RUNTIME_DIR/bus` and `/run/user/<uid>/bus`, else set that variable (or `NETCONVERTER_API_KEY`) in the assistant's MCP server environment and restart it |
160
169
  | Assistant cannot see a NetConverter tool | The bridge lists only allowlisted remote tools the server offers (fewer with `--strict`); update the client with `netconverter update` |
161
170
  | `netconverter update` says uv is not on PATH | Install uv, or follow the printed download, `shasum -a 256 -c SHA256SUMS` and `uv tool install --force` steps |
162
171
 
@@ -40,10 +40,16 @@ until a client release lists it, and a remote tool named `submit_*` is never
40
40
  proxied. `netconverter mcp --strict` (or `NETCONVERTER_MCP_STRICT=1`) narrows the
41
41
  remote tools to the strict-view set (job list and selection, account, search and
42
42
  fetch, knowledge base, vendor capabilities, job brief, evidence, report), whatever
43
- the server advertises; under the server's strict view mode, names in results
44
- arrive as `<name:…>` tokens. `account` returns only tier, job types, rate limit,
45
- daily quota, auth kind and client version facts: no tokens, e-mail addresses, key
46
- hints or tenant IDs. `wait_for_job` progress messages carry only an allowlisted
43
+ the server advertises, and asks the server for its strict view on every request
44
+ (`X-NetConverter-View: strict`; a session can only lower the grant's view). Under
45
+ the server's strict view mode, names in results arrive as `<name:…>` tokens. While
46
+ the server is not applying it, the bridge refuses the configuration-content calls
47
+ (`unparsed_lines`, `focus=target`, non-`kb:` fetch) and masks every address in
48
+ remote results as `<ip>`/`<cidr>` itself; names in summaries are not tokenised
49
+ locally, and `account.strict_enforced_by` says which side is enforcing. `account`
50
+ returns only tier, job types, rate limit, daily quota, auth kind, credential source,
51
+ view mode and client version facts: no tokens, e-mail addresses, key hints or
52
+ tenant IDs. `wait_for_job` progress messages carry only an allowlisted
47
53
  status, stage and percentage.
48
54
 
49
55
  ### Keep the assistant out of the files
@@ -57,5 +57,6 @@ It should list tools such as `list_jobs`, `get_job_brief` and `kb_search`, and
57
57
  | `mcp_not_granted` / "not enabled for this account" | Ask your NetConverter administrator to grant MCP access to your user or organization. |
58
58
  | Sign-in loops or fails (remote connector) | Check the OAuth Client ID in the connector's advanced settings matches the guide, and sign in with your NetConverter account. |
59
59
  | Names appear as `<name:…>` | Your account uses **strict view**: configuration names are tokenised on purpose. |
60
+ | `keyring_unreachable` (Linux: Codex, Cursor CLI, OpenClaw) | The assistant started the bridge without `DBUS_SESSION_BUS_ADDRESS`, so your sign-in in the OS keyring is invisible. The bridge looks for `$XDG_RUNTIME_DIR/bus` and `/run/user/<uid>/bus` itself; if neither exists, set `DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/<uid>/bus` (Codex `env_vars`; Cursor/OpenClaw `env`) or `NETCONVERTER_API_KEY` in the assistant's MCP server config and restart it. |
60
61
 
61
62
  Privacy details: [PRIVACY.md](../PRIVACY.md).
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "netconverter-cli"
7
- version = "0.4.0"
7
+ version = "0.4.2"
8
8
  description = "NetConverter CLI — any-vendor network configuration migration, validation and optimization, and a local MCP bridge for your AI assistant"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -53,4 +53,5 @@ packages = ["src/netconverter_cli"]
53
53
 
54
54
  [tool.pytest.ini_options]
55
55
  testpaths = ["tests"]
56
+ pythonpath = ["."]
56
57
  asyncio_mode = "auto"
@@ -1,3 +1,3 @@
1
1
  """NetConverter CLI: file transfer and conversation are separate paths."""
2
2
 
3
- __version__ = "0.4.0"
3
+ __version__ = "0.4.2"
@@ -11,11 +11,18 @@ import httpx
11
11
  DEFAULT_BASE = "https://api.netconverter.ai/external/v1"
12
12
 
13
13
 
14
+ def _printable(value, limit: int = 300) -> str:
15
+ """Server-supplied text shown to a person: printable characters only, capped."""
16
+ return "".join(ch for ch in str(value or "") if ch.isprintable() or ch == " ")[:limit].strip()
17
+
18
+
14
19
  class APIError(RuntimeError):
15
- def __init__(self, status: int, code: str, request_id: str = "", detail=None):
16
- super().__init__(
17
- f"NetConverter {code} (HTTP {status}, request {request_id or 'unavailable'})"
18
- )
20
+ def __init__(self, status: int, code: str, request_id: str = "", detail=None, message=None):
21
+ self.message = _printable(message) if isinstance(message, str) else ""
22
+ text = f"NetConverter {code} (HTTP {status}, request {request_id or 'unavailable'})"
23
+ if self.message: # the server's reason, e.g. "unknown source_vendor 'auto'; valid: [...]"
24
+ text += f": {self.message}"
25
+ super().__init__(text)
19
26
  self.status, self.code, self.request_id, self.detail = (
20
27
  status,
21
28
  code,
@@ -124,11 +131,18 @@ class Client:
124
131
  error = body.get("error", {}) if isinstance(body, dict) else {}
125
132
  if not isinstance(error, dict):
126
133
  error = {}
134
+ detail = body.get("detail", error.get("detail")) if isinstance(body, dict) else None
135
+ # The External API envelope carries the reason in error.message; an older
136
+ # server may send a plain-string detail instead.
137
+ message = error.get("message")
138
+ if not isinstance(message, str) and isinstance(detail, str):
139
+ message, detail = detail, None
127
140
  return APIError(
128
141
  response.status_code,
129
142
  str(error.get("code", "request_failed")),
130
143
  body.get("request_id", request_id) if isinstance(body, dict) else request_id,
131
- body.get("detail", error.get("detail")) if isinstance(body, dict) else None,
144
+ detail,
145
+ message,
132
146
  )
133
147
 
134
148
  def request(
@@ -180,7 +180,8 @@ class OAuthError(ClerkError):
180
180
  def __init__(self, error: str, body=None):
181
181
  description = ""
182
182
  if isinstance(body, dict):
183
- description = _safe_text(body.get("error_description"))
183
+ # Clerk puts the cause in the last sentence; keep the whole description, not a cut-off head.
184
+ description = _safe_text(body.get("error_description"), 600)
184
185
  super().__init__(
185
186
  f"Sign-in refused: {error}" + (f" ({description})" if description else "")
186
187
  )
@@ -567,9 +568,11 @@ def profile_summary(info: dict) -> dict:
567
568
  if isinstance(info.get(key), str) and info[key]:
568
569
  out[key] = _safe_text(info[key], 120)
569
570
  orgs = []
570
- for key in ("org_id", "org_slug", "org_name"):
571
+ # One label for the active organization: its name, else its slug; the raw id only as a last resort.
572
+ for key in ("org_name", "org_slug", "org_id"):
571
573
  if isinstance(info.get(key), str) and info[key]:
572
574
  orgs.append(_safe_text(info[key], 120))
575
+ break
573
576
  for org in info.get("organizations") or info.get("orgs") or []:
574
577
  if isinstance(org, dict):
575
578
  label = org.get("name") or org.get("slug") or org.get("id")
@@ -8,7 +8,7 @@ import sys
8
8
  from pathlib import Path
9
9
  from .api import Client, DEFAULT_BASE, APIError
10
10
  from .backend import detect_profile, open_client
11
- from .credentials import get_secret, keyring_available, save_secret
11
+ from .credentials import get_secret, keyring_available, keyring_problem, load_secret, save_secret
12
12
  from .controller import Controller
13
13
  from .providers import Provider, ProviderError
14
14
  from .commands import execute
@@ -139,7 +139,8 @@ def logout(args):
139
139
  def whoami(args):
140
140
  from .clerk import ClerkError, profile_summary
141
141
 
142
- out = {"server": args.server, "api_key_stored": bool(get_secret(account(args.server), prompt=False))}
142
+ out = {"server": args.server, "api_key_stored": bool(load_secret(account(args.server))),
143
+ "api_key_in_environment": bool(os.environ.get("NETCONVERTER_API_KEY"))}
143
144
  session = _clerk_session()
144
145
  if session is None:
145
146
  out["clerk"] = None
@@ -151,36 +152,103 @@ def whoami(args):
151
152
  print(json.dumps(out, indent=2))
152
153
 
153
154
 
155
+ MCP_AUTH_MODES = ("auto", "clerk", "key")
156
+
157
+
158
+ def mcp_auth_default() -> str:
159
+ """`mcp --auth` default: NETCONVERTER_MCP_AUTH, else NETCONVERTER_AUTH (#16), else auto."""
160
+ for name in ("NETCONVERTER_MCP_AUTH", "NETCONVERTER_AUTH"):
161
+ value = os.getenv(name, "")
162
+ if value in MCP_AUTH_MODES:
163
+ return value
164
+ return "auto"
165
+
166
+
167
+ def choose_mcp_credential(auth: str, server: str, mcp_url: str):
168
+ """One principal for the whole bridge process (#16).
169
+
170
+ Returns (rest_credential, remote_credential, source, notes). REST and the
171
+ remote tools always get the same credential: ``auto`` prefers the signed-in
172
+ session and names the API key it leaves unused; a key is used only when
173
+ chosen (``--auth key`` / NETCONVERTER_AUTH=key) or when there is no
174
+ sign-in. A sign-in still goes only to trusted NetConverter hosts.
175
+ """
176
+ key = get_secret(account(server), prompt=False) if auth in ("auto", "key") else ""
177
+ key_source = "api_key_environment" if key and os.environ.get("NETCONVERTER_API_KEY") == key else "api_key_stored"
178
+ key_label = "NETCONVERTER_API_KEY" if key_source == "api_key_environment" else "the API key in the OS credential store"
179
+ session = _clerk_session() if auth in ("auto", "clerk") else None
180
+ rest_session = session if session is not None and clerk_allowed(server) else None
181
+ remote_session = session if session is not None and clerk_allowed(mcp_url) else None
182
+ notes = []
183
+ if session is not None and (rest_session is None or remote_session is None):
184
+ notes.append("your sign-in is only sent to trusted NetConverter hosts; "
185
+ "an untrusted server or MCP URL will not receive it")
186
+ if auth == "key":
187
+ return (key or None, key or None, key_source if key else "none",
188
+ notes + [f"credential: {key_label} (--auth key)" if key else "credential: none (--auth key, no API key)"])
189
+ if auth == "clerk" or (session is not None and rest_session is not None and remote_session is not None):
190
+ if auth == "auto" and key:
191
+ notes.append(f"credential: Clerk sign-in; ignoring {key_label} (NETCONVERTER_AUTH=key or "
192
+ "--auth key chooses the key instead)")
193
+ elif session is not None:
194
+ notes.append("credential: Clerk sign-in" + (" (--auth clerk)" if auth == "clerk" else ""))
195
+ else:
196
+ notes.append("credential: none (not signed in; run `netconverter login --clerk`)")
197
+ return rest_session, remote_session, "clerk_session" if session is not None else "none", notes
198
+ if key: # auto: no usable sign-in, so the key serves both surfaces
199
+ notes.append(f"credential: {key_label}" + (" (sign-in present but not usable for this host)"
200
+ if session is not None else ""))
201
+ return key, key, key_source, notes
202
+ if session is not None: # auto: a sign-in usable on one surface only; never a second principal
203
+ notes.append("credential: Clerk sign-in")
204
+ return rest_session, remote_session, "clerk_session", notes
205
+ problem = keyring_problem()
206
+ if problem: # an AI client started us without the desktop keyring (#17): say so, not "sign in"
207
+ notes.append(f"credential: none; {problem}. Start this MCP server with "
208
+ "DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/<uid>/bus in its environment, "
209
+ "or set NETCONVERTER_API_KEY there.")
210
+ else:
211
+ notes.append("credential: none (run `netconverter login --clerk`, or store an API key with `netconverter login`)")
212
+ return None, None, "none", notes
213
+
214
+
154
215
  def run_mcp(args):
155
216
  from .mcp_server import Bridge, run_stdio
156
217
  from .remote_mcp import RemoteMCP
157
218
  from . import __version__
158
219
 
159
- key = get_secret(account(args.server), prompt=False) if args.auth in ("auto", "key") else ""
160
- session = _clerk_session() if args.auth in ("auto", "clerk") else None
161
- key = key or None
162
220
  mcp_url = args.mcp_url or mcp_url_for(args.server)
163
- # The Clerk token goes only to trusted NetConverter hosts, per destination.
164
- rest_session = session if session is not None and clerk_allowed(args.server) else None
165
- remote_session = session if session is not None and clerk_allowed(mcp_url) else None
166
- if session is not None and (rest_session is None or remote_session is None):
167
- print("netconverter: your sign-in is only sent to trusted NetConverter hosts; "
168
- "an untrusted server or MCP URL will not receive it", file=sys.stderr)
169
- if args.auth == "auto":
170
- # Today: API keys reach the REST API; Clerk tokens reach remote MCP.
171
- rest, remote_credential = (key or rest_session), (remote_session or key)
172
- else:
173
- rest, remote_credential = (key, key) if args.auth == "key" else (rest_session, remote_session)
221
+ rest, remote_credential, source, notes = choose_mcp_credential(args.auth, args.server, mcp_url)
222
+ for note in notes:
223
+ print(f"netconverter mcp: {note}", file=sys.stderr)
224
+ strict = bool(getattr(args, "strict", False))
174
225
  remote = None
175
226
  if remote_credential is not None and not args.no_remote:
176
- remote = RemoteMCP(mcp_url, remote_credential, client_version=__version__)
227
+ # --strict asks the server for its strict view on every request (#15).
228
+ remote = RemoteMCP(mcp_url, remote_credential, client_version=__version__,
229
+ **({"view_mode": "strict"} if strict else {}))
177
230
  try:
178
- run_stdio(Bridge(args.workspace, args.server, rest, remote, strict=getattr(args, "strict", False)))
231
+ run_stdio(Bridge(args.workspace, args.server, rest, remote, strict=strict, credential_source=source))
179
232
  finally:
180
233
  if remote:
181
234
  remote.close()
182
235
 
183
236
 
237
+ def check_source_vendor(vendor: str, catalog) -> None:
238
+ """Refuse a source vendor code the server does not list, naming the valid ones (#22).
239
+
240
+ There is no ``auto``: detection exists only in the guided flow. A catalogue
241
+ without a vendor list (an older server) cannot judge, so the server decides.
242
+ """
243
+ if not catalog.loaded or vendor in catalog.vendors:
244
+ return
245
+ sources = sorted(code for code, v in catalog.vendors.items() if "source" in (v.get("roles") or ["source"]))
246
+ print(f"netconverter: unknown source vendor {vendor!r} (there is no 'auto'). "
247
+ f"Valid --vendor codes: {', '.join(sources) or 'none listed'}; "
248
+ "`netconverter capabilities` shows names and conversion paths.")
249
+ raise SystemExit(1)
250
+
251
+
184
252
  def remote_for(server, credential):
185
253
  """The NetConverter MCP endpoint for questions, only over a trusted host for a sign-in."""
186
254
  from .remote_mcp import RemoteMCP
@@ -281,6 +349,41 @@ ACCOUNT_COMMANDS = frozenset({"login", "logout", "whoami", "update"})
281
349
  NO_UPDATE_NOTICE = frozenset({"mcp", "update"})
282
350
 
283
351
 
352
+ # Used when the current folder can't be written (a shell sitting in "/", a
353
+ # read-only mount) and no --workspace was given.
354
+ DEFAULT_WORKSPACE = Path.home() / "migrations" # the folder the installer creates
355
+
356
+
357
+ def resolve_workspace(args) -> None:
358
+ """Pick the folder the file tools work in; never a read-only one.
359
+
360
+ Running from "/" on macOS made setup try to create "/.netconverter" on the
361
+ read-only system volume and crash with a traceback.
362
+ """
363
+ explicit = args.workspace is not None
364
+ args.workspace = args.workspace or "."
365
+ if args.command in ACCOUNT_COMMANDS:
366
+ return
367
+ try:
368
+ root = Path(args.workspace).resolve(strict=True)
369
+ except FileNotFoundError:
370
+ return # workspace_settings reports a deleted folder
371
+ if os.access(root, os.W_OK):
372
+ return
373
+ if explicit:
374
+ raise SystemExit(
375
+ f"netconverter: the folder {str(root)!r} is not writable. "
376
+ f"Pass --workspace with a folder you own, for example --workspace {DEFAULT_WORKSPACE}."
377
+ )
378
+ DEFAULT_WORKSPACE.mkdir(mode=0o700, parents=True, exist_ok=True)
379
+ print(
380
+ f"netconverter: {root} is not writable, so {DEFAULT_WORKSPACE} is the workspace. "
381
+ "cd to your configuration folder or pass --workspace to use another.",
382
+ file=sys.stderr,
383
+ )
384
+ args.workspace = str(DEFAULT_WORKSPACE)
385
+
386
+
284
387
  def workspace_settings(args) -> dict:
285
388
  """Saved folder settings; a missing folder is a clear message, never a traceback.
286
389
 
@@ -303,7 +406,7 @@ def parser():
303
406
 
304
407
  p = argparse.ArgumentParser(prog="netconverter")
305
408
  p.add_argument("--version", action="version", version=f"netconverter-cli {__version__}")
306
- p.add_argument("--workspace", default=".")
409
+ p.add_argument("--workspace", default=None)
307
410
  p.add_argument("--server", default=os.getenv("NETCONVERTER_URL"))
308
411
  p.add_argument(
309
412
  "--provider",
@@ -322,7 +425,9 @@ def parser():
322
425
  logout.add_argument("--all", action="store_true", help="also remove the stored API key for this server")
323
426
  subs.add_parser("whoami", help="show the signed-in account (never prints tokens)")
324
427
  mcp = subs.add_parser("mcp", help="run the local stdio MCP server for AI clients")
325
- mcp.add_argument("--auth", choices=["auto", "clerk", "key"], default=os.getenv("NETCONVERTER_MCP_AUTH", "auto"))
428
+ mcp.add_argument("--auth", choices=list(MCP_AUTH_MODES), default=mcp_auth_default(),
429
+ help="credential: auto (the sign-in, else an API key), clerk or key; "
430
+ "default from NETCONVERTER_MCP_AUTH, else NETCONVERTER_AUTH")
326
431
  mcp.add_argument("--mcp-url", default=os.getenv("NETCONVERTER_MCP_URL"))
327
432
  mcp.add_argument("--no-remote", action="store_true", help="serve only the local file tools")
328
433
  mcp.add_argument("--strict", action="store_true", default=os.getenv("NETCONVERTER_MCP_STRICT") == "1",
@@ -364,6 +469,7 @@ def parser():
364
469
 
365
470
  def main(argv=None):
366
471
  args = parser().parse_args(argv)
472
+ resolve_workspace(args)
367
473
  if args.command == "update":
368
474
  from . import update
369
475
 
@@ -406,7 +512,8 @@ def main(argv=None):
406
512
  kind, _ = detect_profile(key, args.server)
407
513
  stored = save_secret(account(args.server), key)
408
514
  from .workspace import Workspace
409
- if Path(args.workspace).is_dir(): # remembering the server is optional
515
+ # remembering the server is optional; "/" and other read-only folders skip it
516
+ if Path(args.workspace).is_dir() and os.access(args.workspace, os.W_OK):
410
517
  workspace = Workspace(args.workspace)
411
518
  workspace._inside(workspace.state_dir).mkdir(mode=0o700, exist_ok=True)
412
519
  workspace._atomic_replace(workspace.state_dir / "connection.json", json.dumps({**settings, "server": args.server}).encode())
@@ -463,6 +570,7 @@ def main(argv=None):
463
570
  result = c.capabilities()
464
571
  elif args.command in {"validate", "analyze", "optimize", "convert"}:
465
572
  c.capabilities()
573
+ check_source_vendor(args.vendor, c.catalog) # before anything is uploaded (#22)
466
574
  c.select(args.file, args.vendor)
467
575
  options = json.loads(args.options)
468
576
  if args.target:
@@ -2,6 +2,7 @@
2
2
 
3
3
  import getpass
4
4
  import os
5
+ import sys
5
6
 
6
7
  import keyring
7
8
 
@@ -18,7 +19,59 @@ _OS_BACKENDS = frozenset(
18
19
  )
19
20
 
20
21
 
22
+ def session_bus_fallback(environ=None, *, platform=None, uid=None, exists=os.path.exists):
23
+ """Linux: point DBUS_SESSION_BUS_ADDRESS at the user's bus socket when it is unset (#17).
24
+
25
+ Codex, Cursor CLI and OpenClaw start stdio MCP servers with a near-empty
26
+ environment, and jeepney (keyring → Secret Service) reads only that
27
+ variable, so the sign-in in the OS keyring was invisible. Tries
28
+ ``$XDG_RUNTIME_DIR/bus``, then ``/run/user/<uid>/bus``; returns the socket
29
+ path it chose, else None. Must run before keyring picks its backend.
30
+ """
31
+ environ = os.environ if environ is None else environ
32
+ platform = sys.platform if platform is None else platform
33
+ if not platform.startswith("linux") or environ.get("DBUS_SESSION_BUS_ADDRESS"):
34
+ return None
35
+ candidates = []
36
+ runtime = environ.get("XDG_RUNTIME_DIR")
37
+ if runtime:
38
+ candidates.append(f"{runtime.rstrip('/')}/bus")
39
+ if uid is None:
40
+ uid = getattr(os, "getuid", lambda: None)()
41
+ if uid is not None:
42
+ candidates.append(f"/run/user/{uid}/bus")
43
+ for path in dict.fromkeys(candidates): # in order, without a duplicate
44
+ if exists(path):
45
+ environ["DBUS_SESSION_BUS_ADDRESS"] = f"unix:path={path}"
46
+ return path
47
+ return None
48
+
49
+
50
+ def keyring_problem() -> str:
51
+ """Why no OS credential store is reachable; "" when one is (#17).
52
+
53
+ Written for the person reading an AI client's tool error: it names the
54
+ missing D-Bus bus and the keyring backend in use, never a secret.
55
+ """
56
+ session_bus_fallback()
57
+ try:
58
+ backend = keyring.get_keyring()
59
+ except Exception as exc: # noqa: BLE001 - any keyring failure is the answer
60
+ return f"the keyring library failed ({type(exc).__name__})"
61
+ if backend.__class__.__module__ in _OS_BACKENDS:
62
+ return ""
63
+ name = f"{backend.__class__.__module__}.{backend.__class__.__name__}"
64
+ if sys.platform.startswith("linux"):
65
+ if not os.environ.get("DBUS_SESSION_BUS_ADDRESS"):
66
+ return ("no D-Bus session bus: DBUS_SESSION_BUS_ADDRESS is not set and no "
67
+ "/run/user/<uid>/bus socket was found, so the Secret Service keyring is "
68
+ f"unreachable (keyring backend: {name})")
69
+ return f"the Secret Service keyring did not answer on the D-Bus session bus (keyring backend: {name})"
70
+ return f"no OS credential store is available (keyring backend: {name})"
71
+
72
+
21
73
  def _os_backend():
74
+ session_bus_fallback()
22
75
  backend = keyring.get_keyring()
23
76
  if backend.__class__.__module__ not in _OS_BACKENDS:
24
77
  return None