netconverter-cli 0.4.1__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.1 → netconverter_cli-0.4.2}/CHANGELOG.md +43 -0
  2. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/PKG-INFO +1 -1
  3. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/docs/COMMANDS.md +13 -4
  4. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/docs/PRIVACY.md +10 -4
  5. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/docs/connect/README.md +1 -0
  6. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/pyproject.toml +2 -1
  7. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/__init__.py +1 -1
  8. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/api.py +19 -5
  9. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/cli.py +127 -20
  10. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/credentials.py +53 -0
  11. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/mcp_server.py +133 -14
  12. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/remote_mcp.py +40 -1
  13. netconverter_cli-0.4.2/tests/test_keyring_bus_017.py +102 -0
  14. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_mcp.py +29 -1
  15. netconverter_cli-0.4.2/tests/test_mcp_auth_016.py +127 -0
  16. netconverter_cli-0.4.2/tests/test_readonly_workspace.py +56 -0
  17. netconverter_cli-0.4.2/tests/test_strict_view_015.py +174 -0
  18. netconverter_cli-0.4.2/tests/test_vendor_error_022.py +91 -0
  19. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/.gitignore +0 -0
  20. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/LICENSE +0 -0
  21. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/QUICK_START.md +0 -0
  22. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/README.md +0 -0
  23. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/SECURITY.md +0 -0
  24. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/docs/RELEASING.md +0 -0
  25. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/docs/VERIFICATION.md +0 -0
  26. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/docs/connect/chatgpt.md +0 -0
  27. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/docs/connect/claude-ai.md +0 -0
  28. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/docs/connect/claude-code.md +0 -0
  29. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/docs/connect/claude-desktop.md +0 -0
  30. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/docs/connect/getting-access.md +0 -0
  31. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/docs/connect/other-assistants.md +0 -0
  32. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/examples/README.md +0 -0
  33. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/activity.py +0 -0
  34. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/backend.py +0 -0
  35. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/branding.py +0 -0
  36. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/catalog.py +0 -0
  37. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/clerk.py +0 -0
  38. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/commands.py +0 -0
  39. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/connect.py +0 -0
  40. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/controller.py +0 -0
  41. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/guided.py +0 -0
  42. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/palette.py +0 -0
  43. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/presentation.py +0 -0
  44. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/privacy.py +0 -0
  45. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/providers.py +0 -0
  46. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/setup.py +0 -0
  47. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/tui.py +0 -0
  48. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/update.py +0 -0
  49. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/src/netconverter_cli/workspace.py +0 -0
  50. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/conftest.py +0 -0
  51. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_boundaries.py +0 -0
  52. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_clerk.py +0 -0
  53. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_clerk_host_binding.py +0 -0
  54. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_cli_020.py +0 -0
  55. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_connect_030.py +0 -0
  56. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_connect_031.py +0 -0
  57. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_download_analysis.py +0 -0
  58. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_inline.py +0 -0
  59. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_presentation.py +0 -0
  60. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_protocols.py +0 -0
  61. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_sessions.py +0 -0
  62. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_setup.py +0 -0
  63. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_signin_default.py +0 -0
  64. {netconverter_cli-0.4.1 → netconverter_cli-0.4.2}/tests/test_update.py +0 -0
@@ -1,5 +1,48 @@
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
+
3
46
  ## 0.4.1 — 2026-10-22
4
47
 
5
48
  - **First-run setup honours the Clerk sign-in (#6).** `NETCONVERTER_API_KEY` in the
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: netconverter-cli
3
- Version: 0.4.1
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.1"
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.1"
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(
@@ -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, load_secret, 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
@@ -152,36 +152,103 @@ def whoami(args):
152
152
  print(json.dumps(out, indent=2))
153
153
 
154
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
+
155
215
  def run_mcp(args):
156
216
  from .mcp_server import Bridge, run_stdio
157
217
  from .remote_mcp import RemoteMCP
158
218
  from . import __version__
159
219
 
160
- key = get_secret(account(args.server), prompt=False) if args.auth in ("auto", "key") else ""
161
- session = _clerk_session() if args.auth in ("auto", "clerk") else None
162
- key = key or None
163
220
  mcp_url = args.mcp_url or mcp_url_for(args.server)
164
- # The Clerk token goes only to trusted NetConverter hosts, per destination.
165
- rest_session = session if session is not None and clerk_allowed(args.server) else None
166
- remote_session = session if session is not None and clerk_allowed(mcp_url) else None
167
- if session is not None and (rest_session is None or remote_session is None):
168
- print("netconverter: your sign-in is only sent to trusted NetConverter hosts; "
169
- "an untrusted server or MCP URL will not receive it", file=sys.stderr)
170
- if args.auth == "auto":
171
- # Today: API keys reach the REST API; Clerk tokens reach remote MCP.
172
- rest, remote_credential = (key or rest_session), (remote_session or key)
173
- else:
174
- 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))
175
225
  remote = None
176
226
  if remote_credential is not None and not args.no_remote:
177
- 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 {}))
178
230
  try:
179
- 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))
180
232
  finally:
181
233
  if remote:
182
234
  remote.close()
183
235
 
184
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
+
185
252
  def remote_for(server, credential):
186
253
  """The NetConverter MCP endpoint for questions, only over a trusted host for a sign-in."""
187
254
  from .remote_mcp import RemoteMCP
@@ -282,6 +349,41 @@ ACCOUNT_COMMANDS = frozenset({"login", "logout", "whoami", "update"})
282
349
  NO_UPDATE_NOTICE = frozenset({"mcp", "update"})
283
350
 
284
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
+
285
387
  def workspace_settings(args) -> dict:
286
388
  """Saved folder settings; a missing folder is a clear message, never a traceback.
287
389
 
@@ -304,7 +406,7 @@ def parser():
304
406
 
305
407
  p = argparse.ArgumentParser(prog="netconverter")
306
408
  p.add_argument("--version", action="version", version=f"netconverter-cli {__version__}")
307
- p.add_argument("--workspace", default=".")
409
+ p.add_argument("--workspace", default=None)
308
410
  p.add_argument("--server", default=os.getenv("NETCONVERTER_URL"))
309
411
  p.add_argument(
310
412
  "--provider",
@@ -323,7 +425,9 @@ def parser():
323
425
  logout.add_argument("--all", action="store_true", help="also remove the stored API key for this server")
324
426
  subs.add_parser("whoami", help="show the signed-in account (never prints tokens)")
325
427
  mcp = subs.add_parser("mcp", help="run the local stdio MCP server for AI clients")
326
- 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")
327
431
  mcp.add_argument("--mcp-url", default=os.getenv("NETCONVERTER_MCP_URL"))
328
432
  mcp.add_argument("--no-remote", action="store_true", help="serve only the local file tools")
329
433
  mcp.add_argument("--strict", action="store_true", default=os.getenv("NETCONVERTER_MCP_STRICT") == "1",
@@ -365,6 +469,7 @@ def parser():
365
469
 
366
470
  def main(argv=None):
367
471
  args = parser().parse_args(argv)
472
+ resolve_workspace(args)
368
473
  if args.command == "update":
369
474
  from . import update
370
475
 
@@ -407,7 +512,8 @@ def main(argv=None):
407
512
  kind, _ = detect_profile(key, args.server)
408
513
  stored = save_secret(account(args.server), key)
409
514
  from .workspace import Workspace
410
- 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):
411
517
  workspace = Workspace(args.workspace)
412
518
  workspace._inside(workspace.state_dir).mkdir(mode=0o700, exist_ok=True)
413
519
  workspace._atomic_replace(workspace.state_dir / "connection.json", json.dumps({**settings, "server": args.server}).encode())
@@ -464,6 +570,7 @@ def main(argv=None):
464
570
  result = c.capabilities()
465
571
  elif args.command in {"validate", "analyze", "optimize", "convert"}:
466
572
  c.capabilities()
573
+ check_source_vendor(args.vendor, c.catalog) # before anything is uploaded (#22)
467
574
  c.select(args.file, args.vendor)
468
575
  options = json.loads(args.options)
469
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