insightfactory-cli 1.1.2.dev29__tar.gz → 1.1.2.dev31__tar.gz

{insightfactory_cli-1.1.2.dev29 → insightfactory_cli-1.1.2.dev31}/.gitignore

@@ -9,3 +9,4 @@ __pycache__/
 dist/
 build/
 .DS_Store
+.tmp/

{insightfactory_cli-1.1.2.dev29 → insightfactory_cli-1.1.2.dev31}/CHANGELOG.md

@@ -31,6 +31,12 @@ last one has been released, so a cycle's PRs share a section.
 
 ### Changed
 
+- The router's stderr lines now carry the elapsed time since startup, and it logs when
+  the catalogue build starts and when it answers its first `initialize`, so an operator
+  can tell a slow process apart from a slow factory and a client that called before the
+  handshake finished. `if-cli mcp` also now logs a `starting on Python <version>` line
+  before doing anything else, so a process that dies during argument parsing, config
+  load, or profile lookup still leaves one line on stderr instead of none.
 - `release-guard` asks every PR into `develop` for a `CHANGELOG.md` entry, and asks
   for a version bump only when `develop` is still on the version `main` is on. One
   bump opens a release cycle and the PRs after it add to the section it opened,
@@ -39,6 +45,13 @@ last one has been released, so a cycle's PRs share a section.
   has to land above the released version, not merely above the base, and a PR into an
   open cycle has to add a line rather than reword one.
 
+### Fixed
+
+- The router no longer turns a `confirmed:false` preview from a mutating tool into an
+  error pointing at a web UI. That path only belongs to the Databricks connect flow;
+  a form-mode approval gate now comes back as an ordinary result, so the caller
+  confirms by calling again with `confirmed:true` as intended.
+
 ## 1.1.1
 
 ### Added

{insightfactory_cli-1.1.2.dev29 → insightfactory_cli-1.1.2.dev31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: insightfactory-cli
-Version: 1.1.2.dev29
+Version: 1.1.2.dev31
 Summary: Profile-based authentication CLI for the InsightFactory Interfaces API
 Project-URL: Homepage, https://insightfactory.ai
 Author-email: "insightfactory.ai Support" <support@insightfactory.ai>
@@ -265,6 +265,14 @@ uv tool install 'insightfactory-cli[mcp]'
 uvx --from 'insightfactory-cli[mcp]' if-cli mcp foundry
 ```
 
+The first `uvx` launch resolves and downloads the package from PyPI before it runs, which
+added roughly four to six seconds on top of the usual startup in local testing, against
+under two seconds once `uv`'s cache was warm. A client with a fixed handshake budget
+(Claude Code allows 30 seconds) usually has room for that, but a slow network can close
+the gap. Two ways to avoid paying it on every launch: `uv tool install 'insightfactory-cli[mcp]'`
+puts a real script on `PATH` with no resolve step, or run the same `uvx --from ...` command
+by hand once before pointing a client at it, which warms `uv`'s cache for the launches after.
+
 Add it to `.mcp.json`:
 
 ```json

{insightfactory_cli-1.1.2.dev29 → insightfactory_cli-1.1.2.dev31}/README.md

@@ -241,6 +241,14 @@ uv tool install 'insightfactory-cli[mcp]'
 uvx --from 'insightfactory-cli[mcp]' if-cli mcp foundry
 ```
 
+The first `uvx` launch resolves and downloads the package from PyPI before it runs, which
+added roughly four to six seconds on top of the usual startup in local testing, against
+under two seconds once `uv`'s cache was warm. A client with a fixed handshake budget
+(Claude Code allows 30 seconds) usually has room for that, but a slow network can close
+the gap. Two ways to avoid paying it on every launch: `uv tool install 'insightfactory-cli[mcp]'`
+puts a real script on `PATH` with no resolve step, or run the same `uvx --from ...` command
+by hand once before pointing a client at it, which warms `uv`'s cache for the launches after.
+
 Add it to `.mcp.json`:
 
 ```json

{insightfactory_cli-1.1.2.dev29 → insightfactory_cli-1.1.2.dev31}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "insightfactory-cli"
-version = "1.1.2.dev29"
+version = "1.1.2.dev31"
 description = "Profile-based authentication CLI for the InsightFactory Interfaces API"
 readme = "README.md"
 requires-python = ">=3.10"

{insightfactory_cli-1.1.2.dev29 → insightfactory_cli-1.1.2.dev31}/src/if_cli/commands/mcp.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 import importlib.util
+import platform
 import sys
 
 from if_cli.cli import Options, parse_args
 from if_cli.config import config_file, get_profile, list_factories, load_config, parse_factory_section
 from if_cli.http import parse_timeout_seconds
+from if_cli.router.log import log
 from if_cli.runtime import die
 
 MCP_OPTIONS: Options = {
@@ -75,6 +77,8 @@ def _stray_positional(rest: list[str]) -> str | None:
 
 
 def mcp_command(argv: list[str]) -> None:
+    log(f"starting on Python {platform.python_version()}")
+
     if "-h" in argv or "--help" in argv:
         sys.stdout.write(MCP_USAGE)
         return
@@ -146,7 +150,6 @@ def mcp_command(argv: list[str]) -> None:
     # import bug inside if_cli.router propagates instead of reading as a missing extra.
     if importlib.util.find_spec("mcp") is None:
         die(MISSING_MCP_EXTRA)
-    from if_cli.router.log import log
     from if_cli.router.server import build_router, run_server
 
     timeout = parse_timeout_seconds(values["timeout"], "--timeout")

insightfactory_cli-1.1.2.dev31/src/if_cli/router/log.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import sys
+import time
+
+# Captured at import: this module loads before the router does anything else
+# diagnosable, so it stands in for process start. Two `log()` lines can then
+# be subtracted to time the phase between them.
+_START = time.monotonic()
+
+
+def log(message: str) -> None:
+    """Write one timestamped diagnostic line to stderr.
+
+    The router speaks MCP over stdout, so stderr is the only channel that can
+    carry anything to the operator. This lives in its own module because both
+    `server` and `upstream` write to it and `server` imports `upstream`.
+    """
+    elapsed_ms = round((time.monotonic() - _START) * 1000)
+    sys.stderr.write(f"[if-cli mcp] +{elapsed_ms}ms {message}\n")

{insightfactory_cli-1.1.2.dev29 → insightfactory_cli-1.1.2.dev31}/src/if_cli/router/server.py

@@ -9,7 +9,7 @@ from typing import Any, TypeVar
 import anyio
 import mcp_types as types
 from mcp.server import Server
-from mcp.server.context import ServerRequestContext
+from mcp.server.context import CallNext, HandlerResult, ServerMiddleware, ServerRequestContext
 from mcp.server.stdio import stdio_server
 from mcp.shared.exceptions import MCPError
 
@@ -137,6 +137,7 @@ class Router:
 
     async def build_catalog(self) -> list[types.Tool]:
         """Build the merged catalogue. Safe to call again to pick up a new login."""
+        log(f"catalogue: building from {self.config.catalog_source}")
         catalogues = await self._catalogues()
         source = catalogues.get(self.config.catalog_source)
         if source is None:
@@ -536,6 +537,27 @@ def advertised_extensions(router: Router) -> dict[str, dict[str, Any]]:
     return {SKILLS_EXTENSION: {}} if router.config.skills else {}
 
 
+def _log_first_initialize() -> ServerMiddleware[Any]:
+    """Log once the router has answered a client's `initialize`.
+
+    Read against `prime_catalog`'s startup log lines, this tells an operator
+    apart a slow process (nothing logged yet), a slow factory (catalogue
+    build still running past this point), and a client that called before
+    the handshake (a tool call logged before this line ever appears).
+    """
+    logged = False
+
+    async def middleware(ctx: ServerRequestContext[Any, Any], call_next: CallNext) -> HandlerResult:
+        nonlocal logged
+        result = await call_next(ctx)
+        if not logged and ctx.method == "initialize":
+            logged = True
+            log("answered the first initialize")
+        return result
+
+    return middleware
+
+
 async def _serve(router: Router) -> None:
     server: Server[Any] = Server(
         SERVER_NAME,
@@ -553,6 +575,7 @@ async def _serve(router: Router) -> None:
     # the handshake rebuilds its capabilities from `server.extensions` once the
     # protocol version is known, and ignores the ones computed here.
     server.extensions = advertised_extensions(router)
+    server.middleware.append(_log_first_initialize())
     # Answer `initialize` immediately: the catalogue build runs as a background
     # task so one hung factory reads as a slow tools/list, not a failed
     # handshake (clients cap startup time).

{insightfactory_cli-1.1.2.dev29 → insightfactory_cli-1.1.2.dev31}/src/if_cli/router/upstream.py

@@ -138,6 +138,22 @@ class ConnectUrlRecorder:
         return types.ElicitResult(action="decline")
 
 
+def _has_url_request(result: types.InputRequiredResult) -> bool:
+    """Whether any of the result's requests is the Databricks connect flow.
+
+    A request in any other mode (today, only `form`) gates a preview behind a
+    confirmation rather than asking for a trip to a browser, so its presence
+    alone never puts the result on the connect path. A URL-mode request does,
+    even one whose URL fails the origin check in `_connect_url` and so
+    contributes no link: the call still did not run, and the caller still
+    needs the existing refusal, not a result that reads as success.
+    """
+    return any(
+        isinstance(getattr(request, "params", None), types.ElicitRequestURLParams)
+        for request in (result.input_requests or {}).values()
+    )
+
+
 def _relayable_requests(result: types.InputRequiredResult, origin: str) -> tuple[list[str], str | None]:
     """The messages this router will repeat, and the first connect URL it will name.
 
@@ -279,7 +295,16 @@ class Upstream:
         result = await self._run(call, elicitation_callback=recorder)
         if isinstance(result, types.InputRequiredResult):
             lines, url = _relayable_requests(result, self.profile["host"])
-            return self._connect_refusal(lines, url)
+            if _has_url_request(result):
+                return self._connect_refusal(lines, url)
+            # Every mutating tool gates a `confirmed:false` call behind a form-mode
+            # elicitation once the router advertises elicitation at all (see
+            # `ConnectUrlRecorder`). That gate is a preview, not a connect flow: the
+            # factory's own answer to a client with no elicitation capability is a
+            # plain `pending_confirmation` result, and the router owes the caller
+            # the closest thing it can relay to that, not an error pointing at a
+            # web UI the caller was never asked to visit.
+            return self._preview_result(lines)
         if recorder.declined_url_request:
             # The older-revision path. The server elicited in band and carried on
             # once the router declined, so the connect page is in the recorder
@@ -290,6 +315,24 @@ class Upstream:
             return self._connect_refusal(_result_texts(result), recorder.url)
         return result
 
+    def _preview_result(self, lines: list[str]) -> types.CallToolResult:
+        """A form-mode approval gate, relayed as the ordinary result it is.
+
+        This loses the structured `pending_confirmation` JSON a client with no
+        elicitation capability would see (the `approvalId`, `preview`,
+        `impactedResources`): the router has only the elicitation's message
+        text to work with, not the tool's own result body, which the factory
+        never sends once it has decided to gate the call. The message still
+        carries what a caller needs, and the caller still proceeds the same
+        way, by calling again with `confirmed:true`.
+
+        Not an error: the call is still pending, exactly as it would be for a
+        client that never advertised elicitation, and marking this `is_error`
+        would make a normal preview indistinguishable from the connect refusal
+        it is not.
+        """
+        return types.CallToolResult(content=[types.TextContent(text="\n".join(lines))], is_error=False)
+
     def _connect_refusal(self, lines: list[str], url: str | None) -> types.CallToolResult:
         """Turn the factory's request for input into a refusal naming the page to visit.
 

{insightfactory_cli-1.1.2.dev29 → insightfactory_cli-1.1.2.dev31}/tests/test_mcp_command.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import subprocess
 import sys
 import time
@@ -802,11 +803,10 @@ def test_mcp_command_logs_the_resolved_factory_mapping_at_startup(tmp_path: Path
 
         anyio.run(scenario)
         stderr_text = stderr_path.read_text(encoding="utf-8")
-        expected = (
-            f"[if-cli mcp] foundry: dev=profile-a {server_a.origin} (writable); "
-            f"tst=profile-b {server_b.origin}; catalog=dev"
+        expected = re.escape(
+            f"foundry: dev=profile-a {server_a.origin} (writable); tst=profile-b {server_b.origin}; catalog=dev"
         )
-        assert expected in stderr_text
+        assert re.search(rf"\[if-cli mcp\] \+\d+ms {expected}", stderr_text)
     finally:
         server_a.close()
         server_b.close()
@@ -827,8 +827,8 @@ def test_mcp_command_logs_environments_label_without_a_factory(tmp_path: Path):
 
         anyio.run(scenario)
         stderr_text = stderr_path.read_text(encoding="utf-8")
-        expected = f"[if-cli mcp] environments: a=profile-a {server.origin} (writable); catalog=a"
-        assert expected in stderr_text
+        expected = re.escape(f"environments: a=profile-a {server.origin} (writable); catalog=a")
+        assert re.search(rf"\[if-cli mcp\] \+\d+ms {expected}", stderr_text)
     finally:
         server.close()
 

insightfactory_cli-1.1.2.dev31/tests/test_router_log.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from if_cli.router import log as log_module
+
+
+def test_log_prefixes_the_elapsed_time_since_process_start(monkeypatch, capsys):
+    monkeypatch.setattr(log_module, "_START", 10.0)
+    monkeypatch.setattr(log_module.time, "monotonic", lambda: 10.25)
+
+    log_module.log("ready over stdio")
+
+    assert capsys.readouterr().err == "[if-cli mcp] +250ms ready over stdio\n"
+
+
+def test_log_keeps_the_grep_prefix_first(monkeypatch, capsys):
+    """`[if-cli mcp]` must stay the first thing on the line, timestamp or not:
+    it is what an operator (or a script) greps a stdio transcript for."""
+    monkeypatch.setattr(log_module, "_START", 0.0)
+    monkeypatch.setattr(log_module.time, "monotonic", lambda: 0.0)
+
+    log_module.log("WARN dropped a connect URL")
+
+    assert capsys.readouterr().err.startswith("[if-cli mcp] +0ms ")

{insightfactory_cli-1.1.2.dev29 → insightfactory_cli-1.1.2.dev31}/tests/test_router_upstream.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import inspect
+import re
 from typing import Any
 
 import pytest
@@ -253,21 +254,49 @@ def test_call_tool_takes_the_first_same_origin_url():
     ]
 
 
-def test_call_tool_ignores_a_form_mode_request():
-    """Answering a form means relaying it downstream, which the router does not do."""
+def test_call_tool_relays_a_form_mode_request_as_a_preview_not_an_error():
+    """A `confirmed:false` mutating call gates behind a form-mode elicitation once
+    the router advertises elicitation at all; it is a preview, not a connect
+    flow, so it comes back as an ordinary result the caller can act on by
+    calling again with `confirmed:true`."""
     form = types.ElicitRequest(
         params=types.ElicitRequestFormParams(
-            message="Pick one.", requested_schema=types.ElicitRequestedSchema(properties={})
+            message="Ready to add **1** task(s) to production line **NEIL_ROUTER_DEMO**. Ask the user to confirm.",
+            requested_schema=types.ElicitRequestedSchema(properties={}),
         )
     )
     upstream, _ = _upstream_returning(_input_required(form))
 
+    result = anyio.run(lambda: upstream.call_tool("add_tasks_to_production_line", {}))
+
+    assert not result.is_error
+    assert _texts(result) == [
+        "Ready to add **1** task(s) to production line **NEIL_ROUTER_DEMO**. Ask the user to confirm."
+    ]
+
+
+def test_call_tool_treats_a_form_and_url_mix_as_the_connect_flow():
+    """A URL-mode request anywhere in the result keeps today's connect refusal,
+    even alongside a form-mode one: the connect flow must behave exactly as
+    before, so its presence, not the absence of other modes, decides the
+    outcome. The form's own message still rides along as an extra relayed
+    line, same as any other request that is not the chosen connect URL."""
+    form = types.ElicitRequest(
+        params=types.ElicitRequestFormParams(
+            message="Pick one.", requested_schema=types.ElicitRequestedSchema(properties={})
+        )
+    )
+    upstream, _ = _upstream_returning(
+        _input_required(form, _url_request("https://factory.example/my-profile/developer"))
+    )
+
     result = anyio.run(lambda: upstream.call_tool("run_sql_query", {}))
 
     assert result.is_error
     assert _texts(result) == [
         "Pick one.",
-        "[prd] This factory needs input the router cannot relay. Start at https://factory.example.",
+        "Connect your Databricks account.",
+        "[prd] Connect at https://factory.example/my-profile/developer, then retry.",
     ]
 
 
@@ -345,7 +374,9 @@ def test_a_dropped_connect_url_is_reported_on_stderr(capsys):
     anyio.run(lambda: upstream.call_tool("run_sql_query", {}))
 
     stderr = capsys.readouterr().err
-    assert "[if-cli mcp] WARN dropped a connect URL that is not on https://factory.example" in stderr
+    assert re.search(
+        r"\[if-cli mcp\] \+\d+ms WARN dropped a connect URL that is not on https://factory\.example", stderr
+    )
     assert "https://phish.example/connect" in stderr
 
 

insightfactory_cli-1.1.2.dev29/src/if_cli/router/log.py

@@ -1,13 +0,0 @@
-from __future__ import annotations
-
-import sys
-
-
-def log(message: str) -> None:
-    """Write one diagnostic line to stderr.
-
-    The router speaks MCP over stdout, so stderr is the only channel that can
-    carry anything to the operator. This lives in its own module because both
-    `server` and `upstream` write to it and `server` imports `upstream`.
-    """
-    sys.stderr.write(f"[if-cli mcp] {message}\n")