execsql2 2.23.1__py3-none-any.whl → 2.24.0__py3-none-any.whl

execsql/metacommands/effects.py

@@ -0,0 +1,124 @@
+"""What a matched metacommand touches: files it reads, writes or deletes, and connections.
+
+Used by ``run --manifest``, which records the metacommands a run executed.
+It classifies from the handler a metacommand dispatched to and the groups its
+regex captured, so any other reader of a script (a static inspector) can share
+the same answer.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["Effect", "effects"]
+
+
+@dataclass(frozen=True)
+class Effect:
+    """One thing a metacommand touches.
+
+    Attributes:
+        role: ``"read"``, ``"write"`` or ``"delete"`` for a file;
+            ``"connect"`` or ``"use"`` for a database.
+        target: The file path, or for a connection ``alias: server/db`` or
+            ``alias: file``.
+        detail: For a connection, the DBMS and user. Never a password.
+    """
+
+    role: str
+    target: str
+    detail: str = ""
+
+
+_IMPORTS = (
+    "x_import",
+    "x_import_file",
+    "x_import_feather",
+    "x_import_json",
+    "x_import_ods",
+    "x_import_ods_pattern",
+    "x_import_parquet",
+    "x_import_xls",
+    "x_import_xls_pattern",
+    "x_sub_ini",
+    "x_serve",
+)
+_EXPORTS = (
+    "x_export",
+    "x_export_query",
+    "x_export_metadata",
+    "x_export_with_template",
+    "x_export_query_with_template",
+    "x_export_ods_multiple",
+    "x_export_xlsx_multiple",
+)
+_WRITES = (
+    "x_write",
+    "x_writescript",
+    "x_consolesave",
+    "x_cancel_halt_write",
+    "x_error_halt_write",
+    "x_debug_write_config",
+    "x_debug_write_metacommands",
+    "x_debug_write_odbc_drivers",
+    "x_debug_write_subvars",
+)
+
+#: Handler name → {regex group: role}. Groups not listed (passwords,
+#: encodings, prompt paths) are never reported.
+FILE_ROLES: dict[str, dict[str, str]] = {
+    **{name: {"filename": "read"} for name in _IMPORTS},
+    **{name: {"filename": "write", "zipfilename": "write", "template": "read"} for name in _EXPORTS},
+    **{name: {"filename": "write"} for name in _WRITES},
+    **{
+        name: {"filename": "read", "outfile": "write"}
+        for name in ("x_write_create_table", "x_write_create_table_ods", "x_write_create_table_xls")
+    },
+    "x_write_create_table_alias": {"filename": "read"},
+    **{
+        name: {"att_file": "read", "msg_file": "read"}
+        for name in ("x_email", "x_cancel_halt_email", "x_error_halt_email")
+    },
+    "x_zip": {"filename": "read", "zipfilename": "write"},
+    "x_rm_file": {"filename": "delete"},
+}
+
+DBMS = {
+    "pg": "PostgreSQL",
+    "mysql": "MySQL",
+    "ssvr": "SQL Server",
+    "ora": "Oracle",
+    "fb": "Firebird",
+    "sqlite": "SQLite",
+    "duckdb": "DuckDB",
+    "access": "MS Access",
+    "dsn": "ODBC DSN",
+}
+
+
+def _connection(handler: str, groups: dict[str, str | None]) -> Effect | None:
+    if handler == "x_use":
+        return Effect("use", groups.get("db_alias") or "")
+    if not handler.startswith("x_connect_"):
+        return None
+    kind = handler.removeprefix("x_connect_").removeprefix("user_")
+    target = groups.get("filename") or groups.get("dsn") or ""
+    if groups.get("server"):
+        target = f"{groups['server']}/{groups.get('db_name') or ''}"
+    detail = DBMS.get(kind, kind)
+    if groups.get("user"):
+        detail += f", user {groups['user']}"
+    return Effect("connect", f"{groups.get('db_alias') or ''}: {target}".strip(), detail)
+
+
+def effects(handler: str, groups: dict[str, str | None]) -> list[Effect]:
+    """Everything a metacommand dispatched to *handler* with *groups* touches."""
+    connection = _connection(handler, groups)
+    if connection is not None:
+        return [connection]
+    found = []
+    for group, role in FILE_ROLES.get(handler, {}).items():
+        value = groups.get(group)
+        if value:
+            found.append(Effect(role, value.strip().strip('"')))
+    return found

execsql/script/__init__.py

@@ -23,9 +23,6 @@ Key classes:
   handler function + flags).
 - :class:`MetaCommandList` — ordered list of :class:`MetaCommand` entries
   with a keyword index for fast dispatch.
-- :class:`SqlStmt` / :class:`MetacommandStmt` / :class:`ScriptCmd` —
-  statement wrappers carried in the AST and used by ``ctx.last_command``
-  for source-location tracking.
 - :class:`ScriptExecSpec` — specification for deferred script execution
   (used by ``ON ERROR_HALT`` / ``ON CANCEL_HALT EXECUTE SCRIPT``).
 
@@ -46,10 +43,7 @@ from execsql.script.control import BatchLevels
 from execsql.script.engine import (
     MetaCommand,
     MetaCommandList,
-    MetacommandStmt,
-    ScriptCmd,
     ScriptExecSpec,
-    SqlStmt,
     current_script_line,
     set_dynamic_system_vars,
     set_static_system_vars,
@@ -84,9 +78,6 @@ __all__ = [
     "ScriptArgSubVarSet",
     "MetaCommand",
     "MetaCommandList",
-    "SqlStmt",
-    "MetacommandStmt",
-    "ScriptCmd",
     "ScriptExecSpec",
     "set_dynamic_system_vars",
     "set_static_system_vars",

execsql/script/ast.py

@@ -6,7 +6,7 @@ Defines the node types that make up the execsql AST.
 
 Design principles:
     - Every node carries a :class:`SourceSpan` so that error messages,
-      ``--lint``, and the formatter can report precise source locations.
+      ``execsql lint``, and the formatter can report precise source locations.
     - Block structures (IF, LOOP, BATCH, SCRIPT) are represented as nodes
       whose ``body`` (and optional ``else_body``, ``elseif_clauses``) contain
       child nodes, forming the tree structure.

execsql/script/engine.py

@@ -11,9 +11,6 @@ live in :mod:`execsql.script.parser` and
 Classes:
 - :class:`MetaCommand` — one entry in the metacommand dispatch table.
 - :class:`MetaCommandList` — ordered list of :class:`MetaCommand` entries with a keyword index.
-- :class:`SqlStmt` — wraps a single SQL string for execution.
-- :class:`MetacommandStmt` — wraps a metacommand line for dispatch.
-- :class:`ScriptCmd` — pairs a statement with its source-file location.
 - :class:`ScriptExecSpec` — specification for deferred script execution.
 
 Functions:
@@ -28,7 +25,7 @@ import os
 import re
 import uuid
 from pathlib import Path
-from typing import Any, cast
+from typing import Any
 
 import execsql.state as _state
 from execsql.exceptions import ErrInfo
@@ -38,9 +35,6 @@ from execsql.utils.errors import exception_desc
 __all__ = [
     "MetaCommand",
     "MetaCommandList",
-    "SqlStmt",
-    "MetacommandStmt",
-    "ScriptCmd",
     "ScriptExecSpec",
     "set_system_vars",
     "substitute_vars",
@@ -97,8 +91,9 @@ class MetaCommand:
                 raise
             except ErrInfo as errinf:
                 er = errinf
-            except Exception:
+            except Exception as exc:
                 er = ErrInfo("cmd", command_text=cmd_str, exception_msg=exception_desc())
+                er.__cause__ = exc
             if er:
                 if _state.status.halt_on_metacommand_err:
                     from execsql.utils.errors import exit_now
@@ -205,7 +200,7 @@ class MetaCommandList:
     def keywords_by_category(self) -> dict[str, list[str]]:
         """Return ``{category: [keyword, ...]}`` from entries that have both.
 
-        Used by ``--dump-keywords`` to introspect the dispatch table.
+        Used by ``execsql list keywords`` to introspect the dispatch table.
         """
         result: dict[str, list[str]] = {}
         for mc in self._commands:
@@ -239,89 +234,6 @@ class MetaCommandList:
         return None
 
 
-# ---------------------------------------------------------------------------
-# SqlStmt / MetacommandStmt
-# ---------------------------------------------------------------------------
-
-
-class SqlStmt:
-    """A single SQL statement ready to be executed against the active database.
-
-    Data class only — the legacy ``.run()`` method was removed when the AST
-    executor became the sole engine.  SQL execution now goes through
-    :func:`execsql.script.executor._exec_sql`.
-    """
-
-    def __init__(self, sql_statement: str) -> None:
-        self.statement = re.sub(r"\s*;(\s*;\s*)+$", ";", sql_statement)
-
-    def __repr__(self) -> str:
-        return f"SqlStmt({self.statement})"
-
-    def commandline(self) -> str:
-        """Return the raw SQL statement text."""
-        return self.statement
-
-
-class MetacommandStmt:
-    """A single execsql metacommand line.
-
-    Data class only — the legacy ``.run()`` method was removed when the AST
-    executor became the sole engine.  Metacommand dispatch now goes through
-    :func:`execsql.script.executor._exec_metacommand`.
-    """
-
-    def __init__(self, metacommand_statement: str) -> None:
-        self.statement = metacommand_statement
-
-    def __repr__(self) -> str:
-        return f"MetacommandStmt({self.statement})"
-
-    def commandline(self) -> str:
-        """Return the metacommand line in its canonical ``-- !x! ...`` form."""
-        return "-- !x! " + self.statement
-
-
-# ---------------------------------------------------------------------------
-# ScriptCmd
-# ---------------------------------------------------------------------------
-
-
-class ScriptCmd:
-    """A parsed script item: either a :class:`SqlStmt` or a :class:`MetacommandStmt`, with source location."""
-
-    # A SQL script object that is either a SQL statement or a metacommand.
-    def __init__(
-        self,
-        command_source_name: str,
-        command_line_no: int,
-        command_type: str,
-        script_command: Any,
-    ) -> None:
-        self.source = command_source_name
-        self.line_no = command_line_no
-        self.command_type = command_type
-        self.command = script_command
-        # MIGRATION NOTE: differs from monolith (execsql.py) — source_dir and source_name are
-        # resolved once at construction rather than on every statement execution.  For absolute
-        # paths (the common case) the result is identical.  For relative paths the value is
-        # anchored to the CWD at script-load time rather than at each statement's execution time;
-        # the original per-statement resolve could yield inconsistent values across statements of
-        # the same script if a CD metacommand ran between them.
-        _p = Path(command_source_name)
-        self.source_dir: str = str(_p.resolve().parent) + os.sep
-        self.source_name: str = _p.name
-
-    def __repr__(self) -> str:
-        return f"ScriptCmd({self.source!r}, {self.line_no!r}, {self.command_type!r}, {repr(self.command)!r})"
-
-    def current_script_line(self) -> tuple[str, int]:
-        return (self.source, self.line_no)
-
-    def commandline(self) -> str:
-        return cast(str, self.command.statement if self.command_type == "sql" else "-- !x! " + self.command.statement)
-
-
 # ---------------------------------------------------------------------------
 # ScriptExecSpec
 # ---------------------------------------------------------------------------
@@ -509,7 +421,8 @@ def current_script_line() -> tuple[str, int]:
     """Return ``(source_name, line_number)`` for the command currently executing.
 
     Reads from ``_state.last_command``, which the AST executor updates on
-    every statement via the ``_FakeScriptCmd`` shim.  Returns ``("", 0)``
+    every statement via :class:`~execsql.script.executor.ExecutingStatement`.
+    Returns ``("", 0)``
     when nothing has executed yet (e.g. during early initialization errors).
     """
     last = getattr(_state, "last_command", None)

execsql/script/executor.py

@@ -48,6 +48,7 @@ import re
 import time as _time
 from pathlib import Path
 from typing import Any, cast
+from collections.abc import Callable
 
 from execsql.exceptions import ErrInfo
 from execsql.script.ast import (
@@ -64,12 +65,13 @@ from execsql.script.ast import (
     SqlBlock,
     SqlStatement,
 )
+from execsql import manifest as _manifest
 from execsql.script.engine import set_dynamic_system_vars, set_static_system_vars, substitute_vars
 from execsql.script.variables import SubVarSet
 from execsql.state import ExecFrame, RuntimeContext, active_context, get_context, xcmd_test
 from execsql.utils.errors import exception_desc, exit_now, stamp_errinfo
 
-__all__ = ["execute"]
+__all__ = ["execute", "execute_input"]
 
 
 # ---------------------------------------------------------------------------
@@ -256,19 +258,24 @@ def _exec_sql(
             f"Warning: There is a potential un-substituted variable in the command\n     {cmd}\n",
         )
     e = None
+    result = None
     try:
         db = dbs.current()
         if conf.log_sql and ctx.exec_log:
             ctx.exec_log.log_sql_query(cmd, db.name(), line_no)
-        db.execute(cmd)
+        if ctx.prompt_input is not None:
+            result = db.execute(cmd, fetch=True)
+        else:
+            db.execute(cmd)
         if commit:
             db.commit()
     except ErrInfo as errinfo:
         e = errinfo
     except SystemExit:
         raise
-    except Exception:
+    except Exception as exc:
         e = ErrInfo(type="exception", exception_msg=exception_desc())
+        e.__cause__ = exc  # the driver's own message, which a prompt shows
     if e:
         stamp_errinfo(e)
         subvars.add_substitution("$LAST_ERROR", cmd)
@@ -281,6 +288,8 @@ def _exec_sql(
         status.error_history.append((source, line_no, cmd, e.errmsg()))
         return
     subvars.add_substitution("$LAST_SQL", cmd)
+    if ctx.prompt_input is not None:
+        ctx.prompt_input(result)
 
 
 # ---------------------------------------------------------------------------
@@ -319,13 +328,16 @@ def _exec_metacommand(
     try:
         applies, result = metacommandlist.eval(cmd)
         if applies:
+            if (manifest := _manifest.current()) is not None:
+                manifest.record_metacommand(cmd, source, line_no, metacommandlist)
             return result
     except ErrInfo as errinfo:
         e = errinfo
     except SystemExit:
         raise
-    except Exception:
+    except Exception as exc:
         e = ErrInfo(type="exception", exception_msg=exception_desc())
+        e.__cause__ = exc
     if e:
         stamp_errinfo(e)
         status.metacommand_error = True
@@ -402,9 +414,9 @@ def _execute_node(
         text = node.text
         if in_loop:
             text = _convert_deferred_vars(text)
-        # Deduplicate trailing semicolons (matches SqlStmt.__init__)
+        # Deduplicate trailing semicolons
         text = re.sub(r"\s*;(\s*;\s*)+$", ";", text)
-        ctx.last_command = _FakeScriptCmd(node)
+        ctx.last_command = ExecutingStatement(node)
         _exec_sql(
             ctx,
             text,
@@ -413,6 +425,8 @@ def _execute_node(
             localvars,
             commit=not ctx.status.batch.in_batch(),
         )
+        if (manifest := _manifest.current()) is not None:
+            manifest.record_sql()
 
     elif isinstance(node, MetaCommandStatement):
         command = node.command
@@ -425,31 +439,31 @@ def _execute_node(
         expanded = substitute_vars(command, effective_locals, ctx=ctx)
         if _BREAK_RX.match(expanded):
             raise _BreakLoop
-        ctx.last_command = _FakeScriptCmd(node)
+        ctx.last_command = ExecutingStatement(node)
         _exec_metacommand(ctx, expanded, node.span.file, node.span.start_line)
 
     elif isinstance(node, IfBlock):
-        ctx.last_command = _FakeScriptCmd(node)
+        ctx.last_command = ExecutingStatement(node)
         _execute_if(ctx, node, localvars, in_loop=in_loop)
 
     elif isinstance(node, LoopBlock):
-        ctx.last_command = _FakeScriptCmd(node)
+        ctx.last_command = ExecutingStatement(node)
         _execute_loop(ctx, node, localvars)
 
     elif isinstance(node, BatchBlock):
-        ctx.last_command = _FakeScriptCmd(node)
+        ctx.last_command = ExecutingStatement(node)
         _execute_batch(ctx, node, localvars, in_loop=in_loop)
 
     elif isinstance(node, ScriptBlock):
-        ctx.last_command = _FakeScriptCmd(node)
+        ctx.last_command = ExecutingStatement(node)
         _register_script_block(ctx, node)
 
     elif isinstance(node, SqlBlock):
-        ctx.last_command = _FakeScriptCmd(node)
+        ctx.last_command = ExecutingStatement(node)
         _execute_sql_block(ctx, node, localvars, in_loop=in_loop)
 
     elif isinstance(node, IncludeDirective):
-        ctx.last_command = _FakeScriptCmd(node)
+        ctx.last_command = ExecutingStatement(node)
         _execute_include(ctx, node, localvars)
 
     else:
@@ -861,6 +875,8 @@ def _execute_include_native(
     # Parse with AST parser
     encoding = ctx.conf.script_encoding if ctx.conf is not None else "utf-8"
     included_tree = parse_script(target, encoding=encoding)
+    if (manifest := _manifest.current()) is not None:
+        manifest.record_include(target, node.span.file, node.span.start_line)
 
     # Pre-register SCRIPT blocks in the included file so forward references work.
     _pre_register_scripts(ctx, included_tree.body)
@@ -885,40 +901,104 @@ def _execute_include_native(
 # ---------------------------------------------------------------------------
 
 
-class _BreakLoop(Exception):
-    """Raised by BREAK metacommand to exit the innermost loop."""
+class _BreakLoop(BaseException):
+    """Raised by BREAK metacommand to exit the innermost loop.
+
+    A ``BaseException``, like ``KeyboardInterrupt``, so the ``except
+    Exception`` handlers it may pass on its way to the loop leave it alone:
+    a BREAK typed at a BREAKPOINT prompt travels out through the BREAKPOINT
+    metacommand's handler.
+    """
+
+
+def _inside_loop(ctx: RuntimeContext) -> bool:
+    """Whether a BREAK at the current statement would leave a loop within its scope."""
+    for frame in reversed(ctx.ast_exec_stack):
+        if frame.kind in ("loop_while", "loop_until"):
+            return True
+        if frame.kind in ("script", "main"):
+            return frame.kind == "script" and frame.iteration > 0
+    return False
 
 
 _BREAK_RX = re.compile(r"^\s*BREAK\s*$", re.I)
 
 
 # ---------------------------------------------------------------------------
-# Fake ScriptCmd for ctx.last_command compatibility
+# The statement the executor is currently on
 # ---------------------------------------------------------------------------
 
 
-class _FakeScriptCmd:
-    """Minimal stand-in for ScriptCmd to satisfy ctx.last_command readers."""
+class _StatementText:
+    """The text of one statement, in the two spellings its readers expect.
+
+    ``statement`` is the raw text; ``commandline()`` is the text as it
+    appeared in the source, so a metacommand gets its ``-- !x!`` marker back.
+    """
+
+    __slots__ = ("statement", "_prefix")
+
+    def __init__(self, statement: str, prefix: str = "") -> None:
+        self.statement = statement
+        self._prefix = prefix
 
-    __slots__ = ("source", "line_no", "source_dir", "source_name", "command", "command_type")
+    def commandline(self) -> str:
+        return self._prefix + self.statement
+
+
+class ExecutingStatement:
+    """Where the executor is, as ``ctx.last_command`` exposes it.
+
+    The AST node is the single representation of a statement.  This wraps one
+    rather than copying fields out of it, so there is nothing to keep in sync
+    and no second source of truth about what is executing.  Error reporting
+    (:mod:`execsql.utils.errors`), the debug REPL, and ``api.run()`` read
+    these five attributes; everything is derived from ``node`` on access, so
+    constructing one costs a single small object per statement rather than
+    the two classes the previous shim built each time.
+    """
+
+    __slots__ = ("node", "_source_dir")
 
     def __init__(self, node: Node) -> None:
-        self.source = node.span.file
-        self.line_no = node.span.start_line
-        _p = Path(node.span.file)
-        self.source_dir = str(_p.resolve().parent) + os.sep
-        self.source_name = _p.name
-        self.command_type = "sql" if isinstance(node, SqlStatement) else "cmd"
+        self.node = node
+        self._source_dir: str | None = None
+
+    @property
+    def source(self) -> str:
+        return self.node.span.file
+
+    @property
+    def line_no(self) -> int:
+        return self.node.span.start_line
+
+    @property
+    def source_name(self) -> str:
+        return Path(self.node.span.file).name
+
+    @property
+    def source_dir(self) -> str:
+        # resolve() touches the filesystem, so it is done once per statement
+        # object rather than on every read.
+        if self._source_dir is None:
+            self._source_dir = str(Path(self.node.span.file).resolve().parent) + os.sep
+        return self._source_dir
+
+    @property
+    def command_type(self) -> str:
+        return "sql" if isinstance(self.node, SqlStatement) else "cmd"
+
+    @property
+    def command(self) -> _StatementText:
+        node = self.node
         if isinstance(node, SqlStatement):
-            self.command = type("_cmd", (), {"statement": node.text, "commandline": lambda self: self.statement})()
-        elif isinstance(node, MetaCommandStatement):
-            self.command = type(
-                "_cmd",
-                (),
-                {"statement": node.command, "commandline": lambda self: "-- !x! " + self.statement},
-            )()
-        else:
-            self.command = type("_cmd", (), {"statement": "", "commandline": lambda self: ""})()
+            return _StatementText(node.text)
+        if isinstance(node, MetaCommandStatement):
+            return _StatementText(node.command, "-- !x! ")
+        return _StatementText("")
+
+    def __repr__(self) -> str:
+        return f"ExecutingStatement({self.source}:{self.line_no}, {self.command_type})"
 
     def current_script_line(self) -> tuple[str, int]:
         return (self.source, self.line_no)
@@ -1008,3 +1088,42 @@ def execute(script: Script, *, ctx: RuntimeContext | None = None) -> None:
             ) from exc
         finally:
             _pop_frame(ctx)
+
+
+# ---------------------------------------------------------------------------
+# Input typed at a prompt
+# ---------------------------------------------------------------------------
+
+
+def execute_input(
+    script: Script,
+    show: Callable[[tuple[list[str], list] | None], None],
+    *,
+    ctx: RuntimeContext | None = None,
+) -> None:
+    """Run input typed at a BREAKPOINT prompt as the next lines of the paused script.
+
+    The input runs as if it were written where the script paused: in its
+    variable scope, its batch and its loop, so a BREAK leaves that loop.
+    Unlike :func:`execute`, nothing is reset.
+
+    *show* receives the result of each SQL statement run.  An error that
+    would halt the run is raised to the caller instead (see ``exit_now``).
+    The paused script's current statement is restored afterwards, so the
+    debug REPL's ``.where`` still shows it.
+    """
+    if ctx is None:
+        ctx = get_context()
+    with active_context(ctx):
+        _pre_register_scripts(ctx, script.body)
+        last_command, prompt_input = ctx.last_command, ctx.prompt_input
+        ctx.prompt_input = show
+        try:
+            _execute_nodes(ctx, script.body, script.source)
+        except _BreakLoop as exc:
+            if not _inside_loop(ctx):
+                raise ErrInfo(type="cmd", other_msg="BREAK metacommand outside of a LOOP block.") from exc
+            raise
+        finally:
+            ctx.prompt_input = prompt_input
+            ctx.last_command = last_command

execsql/state.py

@@ -33,6 +33,7 @@ import threading
 import types
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
+from collections.abc import Callable
 
 
 @dataclass
@@ -96,10 +97,10 @@ if TYPE_CHECKING:
     from execsql.script import (
         CounterVars,
         MetaCommandList,
-        ScriptCmd,
         ScriptExecSpec,
         SubVarSet,
     )
+    from execsql.script.executor import ExecutingStatement
     from execsql.utils.fileio import FileWriter, Logger, TempFileMgr
     from execsql.utils.mail import MailSpec
     from execsql.utils.timer import Timer
@@ -143,6 +144,7 @@ __all__ = [
     "profile_data",
     # Debug REPL
     "step_mode",
+    "prompt_input",
     # Version
     "primary_vno",
     "secondary_vno",
@@ -239,6 +241,7 @@ _CONTEXT_ATTRS: frozenset[str] = frozenset(
         "profile_data",
         # Debug REPL
         "step_mode",
+        "prompt_input",
         # AST executor
         "ast_scripts",
         "include_chain",
@@ -293,6 +296,7 @@ class RuntimeContext:
         "profile_data",
         # Debug REPL
         "step_mode",
+        "prompt_input",
         # AST executor
         "ast_scripts",
         "include_chain",
@@ -305,7 +309,7 @@ class RuntimeContext:
         self.logfile_encoding: str = "utf8"
 
         # Runtime flags
-        self.last_command: ScriptCmd | None = None
+        self.last_command: ExecutingStatement | None = None
         self.upass: str | None = None
         self.err_halt_writespec: WriteSpec | None = None
         self.err_halt_email: MailSpec | None = None
@@ -347,6 +351,11 @@ class RuntimeContext:
 
         # Debug REPL — True after a ``next`` command; engine re-enters REPL after next statement.
         self.step_mode: bool = False
+        # Set while input typed at a BREAKPOINT prompt runs:
+        # called with each SQL statement's result, as ``(column_names, rows)``
+        # or ``None``.  An error that would halt the run instead returns to the
+        # prompt (see ``exit_now``).
+        self.prompt_input: Callable[[tuple[list[str], list] | None], None] | None = None
 
         # AST executor — script block registry and include-chain tracking.
         self.ast_scripts: dict = {}