v0.5.15: default async SQL, job result cmd, --no-limit, --sync, profile detail, SHOW limit protection, fix ai_message help injection

- SQL execution defaults to async, returns job_id immediately; use --sync for synchronous
- New 'job result <job_id>' command: polls is_job_finished then fetches result set
- Add --no-limit flag to sql and job result to disable row limit protection
- SHOW statements now covered by row limit protection (client-side truncation)
- Rename 'profile show' to 'profile detail' (show kept as hidden alias)
- Fix output.error: only inject --help into ai_message for Click UsageError, not business errors
- Use fetchmany(size) instead of fetchall() when limit is known

Author: lin.zhang

README.md

@@ -236,7 +236,7 @@ This command provides an interactive installer to add bundled skills (from `cz_c
 cz-cli profile list
 
 # Show a single profile
-cz-cli profile show <name>
+cz-cli profile detail <name>
 
 # Create profile (username/password)
 cz-cli profile create <name> --username <user> --password <pass> \

cz_cli/cli_group.py

@@ -59,6 +59,7 @@ class CLIGroup(click.Group):
     """Click Group that auto-injects common options into every command."""
 
     def add_command(self, cmd: click.Command, name: str | None = None) -> None:
+        _inject_connection_options(cmd)
         _inject_profile_option(cmd)
         _inject_output_option(cmd)
         _inject_debug_option(cmd)
@@ -131,3 +132,50 @@ def _inject_profile_option(cmd: click.Command) -> None:
         expose_value=False,
     )
     cmd.params = [_opt] + cmd.params
+
+
+def _connection_callback(ctx: click.Context, param: click.Option, value: str | None) -> str | None:
+    """Store a connection override in ctx.obj when provided at subcommand level."""
+    if value is not None:
+        ctx.ensure_object(dict)
+        ctx.obj[param.name] = value
+    return value
+
+
+# (name, [cli flags], help text, extra kwargs)
+_CONNECTION_OPTIONS: list[tuple[str, list[str], str, dict]] = [
+    ("jdbc_url", ["--jdbc"], "JDBC connection URL", {}),
+    ("pat", ["--pat"], "Personal Access Token", {}),
+    ("username", ["--username"], "Username", {}),
+    ("password", ["--password"], "Password", {}),
+    ("service", ["--service"], "Service endpoint", {}),
+    ("protocol", ["--protocol"], "Protocol (https/http)", {"type": click.Choice(["https", "http"], case_sensitive=False)}),
+    ("instance", ["--instance"], "Instance name", {}),
+    ("workspace", ["--workspace"], "Workspace name", {}),
+    ("schema", ["--schema", "-s"], "Default schema", {}),
+    ("vcluster", ["--vcluster", "-v"], "Virtual cluster", {}),
+]
+
+
+def _inject_connection_options(cmd: click.Command) -> None:
+    """Add connection override options to *cmd* if not already present."""
+    existing_names = {getattr(p, "name", None) for p in cmd.params}
+    existing_flags: set[str] = set()
+    for p in cmd.params:
+        existing_flags.update(getattr(p, "opts", []))
+        existing_flags.update(getattr(p, "secondary_opts", []))
+    for param_name, flags, help_text, extra in _CONNECTION_OPTIONS:
+        if param_name in existing_names:
+            continue
+        if any(f in existing_flags for f in flags):
+            continue
+        opt = click.Option(
+            flags,
+            default=None,
+            help=help_text,
+            callback=_connection_callback,
+            expose_value=False,
+            **extra,
+        )
+        opt._injected_connection = True  # type: ignore[attr-defined]
+        cmd.params.append(opt)

cz_cli/commands/job.py

@@ -178,11 +178,74 @@ def job_status(ctx: click.Context, job_id: str) -> None:
         return
 
     try:
-        summary = conn.get_job_summary(job_id)
+        progress = conn.get_job_progress(job_id)
         log_operation("job status", ok=True)
-        output.success(summary, fmt=fmt)
+        output.success(progress, fmt=fmt)
     except Exception as exc:
         log_operation("job status", ok=False, error_code="JOB_STATUS_ERROR")
         output.error("JOB_STATUS_ERROR", str(exc), fmt=fmt)
     finally:
         conn.close()
+
+
+@job_cmd.command("result")
+@click.argument("job_id")
+@click.option("--no-limit", is_flag=True, help="Disable automatic row limit protection.")
+@click.pass_context
+def job_result(ctx: click.Context, job_id: str, no_limit: bool) -> None:
+    """Fetch result set of a SQL job by job ID (waits if still running)."""
+    import logging
+    import time
+    from cz_cli.connection import get_connection
+    from cz_cli.connection_ctx import connection_kwargs_from_ctx
+    from cz_cli.masking import mask_rows
+    from cz_cli.commands.sql import _truncate_large_fields, DEFAULT_TRUNCATE_LEN, ROW_PROBE_LIMIT
+
+    logger = logging.getLogger(__name__)
+    fmt: str = ctx.obj.get("format", "json")
+    profile: str | None = ctx.obj.get("profile")
+    jdbc_url: str | None = ctx.obj.get("jdbc_url")
+
+    try:
+        conn = get_connection(jdbc_url=jdbc_url, profile=profile, **connection_kwargs_from_ctx(ctx))
+    except Exception as exc:
+        log_operation("job result", ok=False, error_code="CONNECTION_ERROR")
+        output.error("CONNECTION_ERROR", str(exc), fmt=fmt)
+        return
+
+    timer = output.Timer()
+    try:
+        cursor = conn.cursor()
+        try:
+            with timer:
+                while True:
+                    if cursor.is_job_finished(job_id):
+                        break
+                    logger.debug(f"job_id: {job_id} is running...")
+                    time.sleep(0.2)
+
+                cursor.get_result_set(job_id)
+                if cursor.description is not None:
+                    columns = [d[0] for d in cursor.description]
+                    ai_msg = None
+                    if no_limit:
+                        rows = [dict(zip(columns, row)) for row in cursor.fetchall()]
+                    else:
+                        rows = [dict(zip(columns, row)) for row in cursor.fetchmany(ROW_PROBE_LIMIT)]
+                        if len(rows) > ROW_PROBE_LIMIT - 1:
+                            rows = rows[:ROW_PROBE_LIMIT - 1]
+                            ai_msg = f"Results truncated to 100 rows. Use --no-limit to fetch all: cz-cli job result --no-limit {job_id}"
+                    rows = _truncate_large_fields(rows, DEFAULT_TRUNCATE_LEN)
+                    rows = mask_rows(columns, rows)
+                    log_operation("job result", ok=True, rows=len(rows), time_ms=timer.elapsed_ms)
+                    output.success_rows(columns, rows, time_ms=timer.elapsed_ms, fmt=fmt, extra={"job_id": job_id}, ai_message=ai_msg)
+                else:
+                    log_operation("job result", ok=True, time_ms=timer.elapsed_ms)
+                    output.success({"job_id": job_id, "message": "Job completed with no result set."}, time_ms=timer.elapsed_ms, fmt=fmt)
+        finally:
+            cursor.close()
+    except Exception as exc:
+        log_operation("job result", ok=False, error_code="JOB_RESULT_ERROR")
+        output.error("JOB_RESULT_ERROR", str(exc), fmt=fmt)
+    finally:
+        conn.close()

cz_cli/commands/profile.py

@@ -94,7 +94,7 @@ def _save_profiles(data: dict[str, Any]) -> None:
 @click.group("profile", cls=CLIGroup)
 @click.pass_context
 def profile_cmd(ctx: click.Context) -> None:
-    """Manage connection profiles. Use --show-secret on list/show to reveal secrets."""
+    """Manage connection profiles. Use --show-secret on list/detail to reveal secrets."""
 
 
 @profile_cmd.command("list")
@@ -155,7 +155,7 @@ def list_profiles(ctx: click.Context, show_secret: bool) -> None:
         output.error("INTERNAL_ERROR", str(exc), fmt=fmt)
 
 
-@profile_cmd.command("show")
+@profile_cmd.command("detail")
 @click.argument("name")
 @click.option(
     "--show-secret",
@@ -179,7 +179,7 @@ def show_profile(ctx: click.Context, name: str, show_secret: bool) -> None:
         default_profile = data.get("default_profile")
         profile = profiles.get(name)
         if profile is None:
-            log_operation("profile show", ok=False, error_code="PROFILE_NOT_FOUND")
+            log_operation("profile detail", ok=False, error_code="PROFILE_NOT_FOUND")
             output.error("PROFILE_NOT_FOUND", f"Profile '{name}' not found", fmt=fmt)
             return
 
@@ -191,10 +191,10 @@ def show_profile(ctx: click.Context, name: str, show_secret: bool) -> None:
             if result.get("password"):
                 result["password"] = "******"
 
-        log_operation("profile show", ok=True)
+        log_operation("profile detail", ok=True)
         output.success(result, fmt=fmt)
     except Exception as exc:
-        log_operation("profile show", ok=False, error_code="INTERNAL_ERROR")
+        log_operation("profile detail", ok=False, error_code="INTERNAL_ERROR")
         output.error("INTERNAL_ERROR", str(exc), fmt=fmt)
 
 
@@ -527,11 +527,16 @@ def use_profile(ctx: click.Context, name: str) -> None:
 list_profiles.epilog = examples_epilog(list_profiles.examples)  # type: ignore[attr-defined]
 
 show_profile.examples = [  # type: ignore[attr-defined]
-    {"cmd": "cz-cli profile show dev", "desc": "Show config for 'dev' profile (password/PAT redacted by default)"},
-    {"cmd": "cz-cli profile show dev --show-secret", "desc": "Show config including plaintext password/PAT"},
+    {"cmd": "cz-cli profile detail dev", "desc": "Show config for 'dev' profile (password/PAT redacted by default)"},
+    {"cmd": "cz-cli profile detail dev --show-secret", "desc": "Show config including plaintext password/PAT"},
 ]
 show_profile.epilog = examples_epilog(show_profile.examples)  # type: ignore[attr-defined]
 
+# Keep "show" as a hidden alias for backward compatibility.
+profile_cmd.add_command(show_profile, "show")
+# Hide the alias from help output.
+profile_cmd.commands["show"].hidden = True
+
 create_profile.examples = [  # type: ignore[attr-defined]
     {
         "cmd": "cz-cli profile create dev --username alice --password s3cr3t --instance my-inst --workspace ws1",