netconverter-cli 0.4.1__tar.gz → 0.4.3__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 (65) hide show
  1. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/CHANGELOG.md +52 -0
  2. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/PKG-INFO +1 -1
  3. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/docs/COMMANDS.md +14 -4
  4. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/docs/PRIVACY.md +10 -4
  5. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/docs/connect/README.md +1 -0
  6. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/pyproject.toml +2 -1
  7. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/__init__.py +1 -1
  8. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/api.py +19 -5
  9. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/cli.py +127 -20
  10. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/commands.py +7 -0
  11. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/controller.py +45 -0
  12. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/credentials.py +53 -0
  13. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/mcp_server.py +133 -14
  14. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/presentation.py +32 -0
  15. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/remote_mcp.py +40 -1
  16. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/tui.py +21 -0
  17. netconverter_cli-0.4.3/tests/test_folders_cd_ls.py +77 -0
  18. netconverter_cli-0.4.3/tests/test_keyring_bus_017.py +102 -0
  19. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_mcp.py +29 -1
  20. netconverter_cli-0.4.3/tests/test_mcp_auth_016.py +127 -0
  21. netconverter_cli-0.4.3/tests/test_readonly_workspace.py +56 -0
  22. netconverter_cli-0.4.3/tests/test_strict_view_015.py +174 -0
  23. netconverter_cli-0.4.3/tests/test_vendor_error_022.py +91 -0
  24. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/.gitignore +0 -0
  25. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/LICENSE +0 -0
  26. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/QUICK_START.md +0 -0
  27. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/README.md +0 -0
  28. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/SECURITY.md +0 -0
  29. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/docs/RELEASING.md +0 -0
  30. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/docs/VERIFICATION.md +0 -0
  31. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/docs/connect/chatgpt.md +0 -0
  32. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/docs/connect/claude-ai.md +0 -0
  33. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/docs/connect/claude-code.md +0 -0
  34. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/docs/connect/claude-desktop.md +0 -0
  35. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/docs/connect/getting-access.md +0 -0
  36. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/docs/connect/other-assistants.md +0 -0
  37. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/examples/README.md +0 -0
  38. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/activity.py +0 -0
  39. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/backend.py +0 -0
  40. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/branding.py +0 -0
  41. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/catalog.py +0 -0
  42. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/clerk.py +0 -0
  43. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/connect.py +0 -0
  44. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/guided.py +0 -0
  45. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/palette.py +0 -0
  46. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/privacy.py +0 -0
  47. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/providers.py +0 -0
  48. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/setup.py +0 -0
  49. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/update.py +0 -0
  50. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/src/netconverter_cli/workspace.py +0 -0
  51. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/conftest.py +0 -0
  52. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_boundaries.py +0 -0
  53. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_clerk.py +0 -0
  54. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_clerk_host_binding.py +0 -0
  55. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_cli_020.py +0 -0
  56. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_connect_030.py +0 -0
  57. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_connect_031.py +0 -0
  58. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_download_analysis.py +0 -0
  59. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_inline.py +0 -0
  60. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_presentation.py +0 -0
  61. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_protocols.py +0 -0
  62. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_sessions.py +0 -0
  63. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_setup.py +0 -0
  64. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_signin_default.py +0 -0
  65. {netconverter_cli-0.4.1 → netconverter_cli-0.4.3}/tests/test_update.py +0 -0
@@ -1,5 +1,57 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.4.3 — 2026-10-23
4
+
5
+ - **Move between folders in the terminal app.** `/ls [FOLDER]` (or `/dir`) lists files and
6
+ folders with sizes, folders first, hidden files left out; it never reads file contents.
7
+ `/cd FOLDER` makes another folder the workspace (`~`, `..`, relative or absolute) and
8
+ loads that folder's own remembered jobs; a missing or read-only folder is refused and
9
+ nothing changes. `/pwd` shows the current folder. These are typed commands only: the
10
+ model cannot choose them, and the MCP bridge keeps the `--workspace` it was started with.
11
+
12
+ ## 0.4.2 — 2026-10-23
13
+
14
+ - **Running from a read-only folder no longer crashes.** Started from `/` (or any folder
15
+ you can't write) without `--workspace`, the CLI uses `~/migrations`, the folder the
16
+ installer creates, and says so on stderr. Before, first-run setup tried to create
17
+ `/.netconverter` and stopped with `OSError: Read-only file system`. An explicit
18
+ `--workspace` that can't be written is a one-line error. `login --key` from such a
19
+ folder still stores the key and skips remembering the server there.
20
+ - **`mcp --strict` requests and verifies the server's strict view (#15).** The bridge sends
21
+ `X-NetConverter-View: strict` on every remote request (the server may only lower the
22
+ grant's view) and reads the view in force from `get_account`; `account` now reports
23
+ `view_mode` and `strict_enforced_by` (`server`/`client`) next to the `strict_mode` flag.
24
+ Until the server applies the strict view for the account, the bridge enforces it locally:
25
+ `get_evidence section=unparsed_lines`, `get_job_brief focus=target` and any `fetch` that is
26
+ not `kb:<doc_id>` are refused before any network call, every IPv4/IPv6 address or prefix in
27
+ a remote result is masked as `<ip>`/`<cidr>`, and one stderr line says so. Names inside
28
+ summaries are tokenised only by the server's strict view.
29
+ - **Linux: the bridge finds the keyring when the assistant hides the D-Bus bus (#17).**
30
+ Codex, Cursor CLI and OpenClaw start MCP servers without `DBUS_SESSION_BUS_ADDRESS`, so
31
+ the Clerk sign-in in the Secret Service was invisible and every tool said "not signed
32
+ in". The client now points at `$XDG_RUNTIME_DIR/bus`, then `/run/user/<uid>/bus`, before
33
+ keyring picks its backend. When no OS keyring is reachable, tool errors and the
34
+ `netconverter mcp` startup line say `keyring_unreachable` and name the fix (set the bus
35
+ address or `NETCONVERTER_API_KEY` in the assistant's MCP env) instead of "sign in".
36
+ - **One credential per `netconverter mcp` process (#16).** The bridge honours
37
+ `NETCONVERTER_AUTH` (`NETCONVERTER_MCP_AUTH` still overrides it for `mcp` alone). In
38
+ `auto` mode a Clerk sign-in is preferred and used for both the REST API and the remote
39
+ tools; an API key from `NETCONVERTER_API_KEY` or the credential store is used only when
40
+ chosen (`--auth key`) or when there is no sign-in, never for one surface while the
41
+ sign-in serves the other. A startup line on stderr names the credential in use and the
42
+ one left unused; `account` reports it as `credential_source`.
43
+ - **Refused requests show the server's reason (#22).** `APIError` now reads the External
44
+ API's `error.message` (an older server's string `detail` too) and prints it, so
45
+ `validate --vendor auto` says `unknown source_vendor 'auto'; valid: [...]` instead of a
46
+ bare HTTP 422; MCP tool errors carry the same reason. `validate`/`analyze`/`optimize`/
47
+ `convert` also check `--vendor` against the server's capabilities before uploading and
48
+ list the valid source codes (there is no `auto`; detection lives in the guided flow).
49
+ - **`wait_for_job` fits a 60 s client tool timeout (#18).** The default `timeout_s` is 45
50
+ (was 300; max still 600). A job still running when the wait ends comes back with
51
+ `timed_out: true` and `next: "still running; call wait_for_job again …"` instead of the
52
+ call being cut off by Codex or OpenClaw mid-job. Pass a larger `timeout_s` explicitly when
53
+ the client allows a longer wait.
54
+
3
55
  ## 0.4.1 — 2026-10-22
4
56
 
5
57
  - **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.3
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
@@ -22,6 +22,7 @@ commands their arguments there (`/open "edge.cfg" fortinet`).
22
22
  | `/validate` (`/analyze`) | Readiness, findings and parse gaps for a configuration |
23
23
  | `/optimize` | Cleanup and optimization findings |
24
24
  | `/open` | Choose a configuration without submitting |
25
+ | `/ls [FOLDER]` · `/dir` · `/cd FOLDER` · `/pwd` | List files (names and sizes) · work in another folder (`~`, `..`, relative or absolute; each folder keeps its own jobs) · show the current folder |
25
26
  | `/jobs` · `/resume JOB_ID` · `/status` | List jobs · follow one · refresh the active job |
26
27
  | `/download` | Save the active job's outputs beside its source, hash-verified |
27
28
  | `/target` | Save the generated configuration and select it for `/validate` |
@@ -110,8 +111,8 @@ delays a command; its result is cached in your user cache folder.
110
111
  | --- | --- |
111
112
  | `submit_file(path, source_vendor, target_vendor?, job_type?, options?)` | `job_id`, `status`, `sha256`, `bytes`. `job_type`: `convert`, `validate`, `optimize`, or `analyze` (= validate) |
112
113
  | `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` |
114
+ | `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 |
115
+ | `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
116
  | `download(job_id, dest_dir=".")` | Saved file names, sizes and SHA-256 |
116
117
 
117
118
  Remote NetConverter tools are proxied only from a fixed allowlist, and never a
@@ -126,11 +127,19 @@ Remote NetConverter tools are proxied only from a fixed allowlist, and never a
126
127
  With `--strict`: `list_jobs`, `select_job`, `get_account`, `search`, `fetch`,
127
128
  `kb_search`, `kb_explain`, `vendor_capability_lookup`, `get_job_brief`,
128
129
  `get_evidence`, `get_report`. A listed tool appears only if the server offers it.
130
+ `--strict` also asks the server for its strict view on every request (`X-NetConverter-View: strict`;
131
+ the server may only lower the grant's view, never raise it) and reads the view in force from
132
+ `get_account`. Until the server applies it, the bridge enforces strict locally: it refuses
133
+ `get_evidence section=unparsed_lines`, `get_job_brief focus=target` and any `fetch` that is not
134
+ `kb:<doc_id>` before any network call, masks every IPv4/IPv6 address and prefix in remote results
135
+ as `<ip>`/`<cidr>`, and says so once on stderr. Names in summaries are tokenised only by the
136
+ server's strict view; `account` reports which side is enforcing.
129
137
 
130
138
  Global options go before the subcommand: `netconverter --workspace DIR --server URL …`.
131
139
  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`),
140
+ `NETCONVERTER_AUTH=key` or `=clerk` (force one credential; unset, plain commands use a stored key first, then
141
+ your sign-in, while `mcp` prefers the sign-in and says on stderr which API key it leaves unused;
142
+ `NETCONVERTER_MCP_AUTH` overrides it for `mcp` only), `NETCONVERTER_TRUSTED_HOSTS`, `NETCONVERTER_MCP_STRICT=1` (same as `mcp --strict`),
134
143
  `NETCONVERTER_NO_UPDATE_CHECK=1` (no daily update check or notice; `account` then reports
135
144
  `update_available: null`).
136
145
  Never put a literal key in shell history or a shared script.
@@ -157,6 +166,7 @@ Never put a literal key in shell history or a shared script.
157
166
  | No verified configuration | Read validation reports and warnings; evidence can be available even when no deployable output is produced |
158
167
  | 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
168
  | Full-screen UI unsuitable | Use `netconverter plain` or individual CLI commands |
169
+ | `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
170
  | 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
171
  | `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
172
 
@@ -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.3"
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.3"
@@ -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:
@@ -5,6 +5,7 @@ import shlex
5
5
 
6
6
  HELP = """/open "file.cfg" VENDOR_CODE (vendor codes: netconverter --json capabilities)
7
7
  /convert {"target_vendor":"palo_alto_xml"} /validate /optimize
8
+ /cd FOLDER /ls [FOLDER] /dir /pwd
8
9
  /jobs /resume [job_id] /status /target /download /allowance
9
10
  /unused_objects /routes /interfaces /policy /nat
10
11
  /dependencies {"object_name":"NAME"}
@@ -27,6 +28,12 @@ def execute(controller, text):
27
28
  rest = rest.strip()
28
29
  if command == "help":
29
30
  return {"help": HELP}
31
+ if command == "cd":
32
+ return controller.change_folder(rest)
33
+ if command in {"ls", "dir"}:
34
+ return controller.list_folder(rest)
35
+ if command == "pwd":
36
+ return {"folder": str(controller.workspace.root)}
30
37
  if command == "open":
31
38
  parts = shlex.split(rest)
32
39
  if len(parts) != 2:
@@ -1,10 +1,13 @@
1
1
  """User-directed local orchestration; providers never receive this object."""
2
2
 
3
3
  import base64
4
+ import os
4
5
  import hashlib
5
6
  import json
6
7
  import time
7
8
  import uuid
9
+ from pathlib import Path
10
+
8
11
  from .workspace import Workspace, WorkspaceError
9
12
  from .api import APIError, Client, ExternalClient
10
13
  from .backend import EXTERNAL_MAX_BYTES, download_external, submit_external
@@ -60,6 +63,48 @@ class Controller:
60
63
  self.allowance = {}
61
64
  self.catalog = Catalog()
62
65
 
66
+ # -- folders (typed by the user; never a model operation) -------------------
67
+
68
+ MAX_LISTED = 200
69
+
70
+ def _resolve_folder(self, path):
71
+ raw = Path(os.path.expanduser(path or "~"))
72
+ target = (raw if raw.is_absolute() else self.workspace.root / raw).resolve()
73
+ if not target.is_dir():
74
+ raise WorkspaceError(f"Not a folder: {target}")
75
+ return target
76
+
77
+ def change_folder(self, path):
78
+ """/cd: make another folder the workspace and load its own job state.
79
+
80
+ Only the user can type this. It is not in the model's operation list, and the
81
+ MCP bridge keeps its configured root, so a prompt cannot move the boundary.
82
+ """
83
+ target = self._resolve_folder(path)
84
+ if not os.access(target, os.W_OK):
85
+ raise WorkspaceError(f"{target} is not writable; choose a folder you own")
86
+ workspace = Workspace(target)
87
+ state = workspace.load() # refuse before switching if its state is invalid
88
+ self.workspace, self.state = workspace, state
89
+ return {"folder": str(target), "jobs_here": len(state.get("jobs", {}))}
90
+
91
+ def list_folder(self, path=""):
92
+ """/ls, /dir: names and sizes only, never file contents."""
93
+ target = self._resolve_folder(path or ".")
94
+ entries = []
95
+ for item in target.iterdir():
96
+ if item.name.startswith("."):
97
+ continue
98
+ try:
99
+ is_dir = item.is_dir()
100
+ size = None if is_dir else item.stat().st_size
101
+ except OSError:
102
+ continue
103
+ entries.append({"name": item.name, "folder": is_dir, "bytes": size})
104
+ entries.sort(key=lambda e: (not e["folder"], e["name"].lower()))
105
+ return {"folder": str(target), "entries": entries[: self.MAX_LISTED],
106
+ "total": len(entries), "inside_workspace": target.is_relative_to(self.workspace.root)}
107
+
63
108
  @property
64
109
  def external(self) -> bool:
65
110
  return self.kind == "external"
@@ -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