941036

Author: davidk

MANUAL.md

@@ -219,6 +219,7 @@ Written inline on the step header line, comma-separated:
 | `retry Nx backoff Xs..Ys jitter Z%` | `retry 3x backoff 30s..300s jitter 10%` | backoff with ±10% jitter |
 | `until "VALUE"` | `until "0"` | disabled |
 | `if fails stop\|warn\|ignore` | `if fails warn` | stop |
+| `interactive` | (bare keyword) | disabled |
 
 `timeout` is a hard execution deadline by default. If you add `reset on output`, it becomes an inactivity timeout instead: every new stdout or stderr chunk from the running command resets the timer.
 
@@ -231,6 +232,18 @@ Example:
 
 This step can run longer than 30 seconds overall as long as it keeps producing CLI output at least once every 30 seconds. If output stops for 30 seconds, the step times out.
 
+### The `interactive` keyword — terminal-interactive steps
+
+The engine automatically detects steps that read from the terminal (`read`, `/dev/tty`, `ssh-copy-id`) and suspends live-progress rendering while they own the terminal. For commands the heuristic cannot detect, add the `interactive` keyword to the step body:
+
+```cgr
+[set password]:
+  run $ passwd deploy_user
+  interactive
+```
+
+This forces PTY allocation and stdin forwarding regardless of the command name. Use it for tools like `passwd`, `kinit`, `gpg --gen-key`, or any other utility that opens the terminal directly.
+
 ### The `first` keyword — why not `after`?
 
 When reading `[install nginx]`, the dependency keyword should answer "what does this step need?" from the perspective of the step you're currently reading.
@@ -1129,6 +1142,7 @@ resource install_nginx {
 | `on_fail` | No | `stop` | What to do on failure: `stop` (abort the graph), `warn` (continue, mark as warned), `ignore` (treat as success). |
 | `when` | No | `null` | Quoted boolean expression. If false, the resource is skipped. Supports `==` and `!=`. |
 | `env` | No | `{}` | Set environment variables. Syntax: `env KEY = "value"`. Repeatable. |
+| `interactive` | No | `false` | Force terminal-interactive mode (PTY + stdin forwarding). Use for commands like `passwd`, `kinit`, or any tool that reads directly from the terminal. The engine auto-detects common patterns (`read`, `/dev/tty`, `ssh-copy-id`); use this keyword for others. |
 
 ### Command delimiters
 

cgr.py

@@ -76,6 +76,7 @@ class ASTResource:
     # Backoff/jitter fields (for retry Nx backoff Xs syntax)
     retry_backoff_max: int = 0   # cap in seconds (0 = no cap)
     retry_jitter_pct: int = 0    # jitter percentage (0 = none)
+    interactive: bool = False    # force terminal-interactive mode (PTY + stdin forwarding)
     # On-success/failure variable bindings
     on_success_set: list[tuple] = field(default_factory=list)  # [(var, val), ...]
     on_failure_set: list[tuple] = field(default_factory=list)

cgr_src/ast_nodes.py

@@ -200,6 +200,7 @@ def _command_reads_tty(cmd) -> bool:
         return False
     return bool(
         "/dev/tty" in cmd
+        or "ssh-copy-id" in cmd
         or re.search(r"(^|[;&|({]\s*)read\s+(-[A-Za-z]*\s+)?", cmd)
     )
 
@@ -242,14 +243,11 @@ def _run_cmd(cmd, node, res, *, timeout, on_output=None, register_proc=None, unr
         interactive_tty = (
             node.via_method != "ssh"
             and stdin_data is None
-            and _command_reads_tty(full)
+            and (res.interactive or _command_reads_tty(full))
             and sys.stdin and sys.stdin.isatty()
             and sys.stdout and sys.stdout.isatty()
         )
         use_pty = bool(on_output) or interactive_tty
-        if (not use_pty and node.via_method != "ssh" and stdin_data is None
-                and isinstance(full, str) and "ssh-copy-id" in full and sys.stdin and sys.stdin.isatty()):
-            use_pty = True
         if use_pty:
             master_fd, slave_fd = pty.openpty()
             echo_pty = on_output is None
@@ -1704,7 +1702,7 @@ def _run_with_start(rid):
                 command_needs_terminal = (
                     live_progress.enabled
                     and node.via_method != "ssh"
-                    and _command_reads_tty(_effective_run_cmd(runtime_res, graph.graph_file))
+                    and (res.interactive or _command_reads_tty(_effective_run_cmd(runtime_res, graph.graph_file)))
                     and sys.stdin and sys.stdin.isatty()
                     and sys.stdout and sys.stdout.isatty()
                 )

cgr_src/executor.py

@@ -307,7 +307,7 @@ def _p_resource_body(self, name, group_defaults=None, is_template_root=False) ->
         desc=""; needs=[]; check=None; run_cmd=None; script_path=None; run_as=d.get("as")
         timeout=d.get("timeout",300); retries=0; retry_delay=5; retry_backoff=False
         timeout_reset_on_output=d.get("timeout_reset_on_output", False)
-        on_fail=d.get("on_fail","stop"); when=None; env={}; env_when={}; children=[]; flags=[]; until=None
+        on_fail=d.get("on_fail","stop"); when=None; env={}; env_when={}; children=[]; flags=[]; until=None; interactive=False
         collect_key=None
         collect_format=None
         collect_var=None
@@ -441,6 +441,8 @@ def _p_resource_body(self, name, group_defaults=None, is_template_root=False) ->
             elif s.value=="from":
                 self._advance()
                 subgraph_path=self._expect(TT.STRING).value
+            elif s.value=="interactive":
+                self._advance(); interactive=True
             # ── Parallel constructs ──────────────────────────────────────
             elif s.value=="parallel":
                 plimit, ppolicy, pchildren = self._p_parallel(group_defaults)
@@ -461,7 +463,7 @@ def _p_resource_body(self, name, group_defaults=None, is_template_root=False) ->
                 subgraph_vars[arg_name] = arg_value.value
             else:
                 raise self._err(f"Unknown '{s.value}' in resource",
-                    "Valid: description, needs, check, run, script, as, timeout, retry, on_fail, on_success, on_failure, when, env, collect, reduce, flag, until, wait, from, tags, resource, parallel, race, each, stage, get, post, put, patch, delete, auth, header, body, expect")
+                    "Valid: description, needs, check, run, script, as, timeout, retry, on_fail, on_success, on_failure, when, env, collect, reduce, flag, until, wait, from, tags, interactive, resource, parallel, race, each, stage, get, post, put, patch, delete, auth, header, body, expect")
         if flags and not run_cmd:
             raise self._err("'flag' requires a 'run' command in the same step")
         if until and retries <= 0:
@@ -479,7 +481,8 @@ def _p_resource_body(self, name, group_defaults=None, is_template_root=False) ->
             wait_kind=wait_kind, wait_target=wait_target,
             subgraph_path=subgraph_path, subgraph_vars=dict(subgraph_vars),
             on_success_set=list(on_success_set), on_failure_set=list(on_failure_set),
-            collect_var=collect_var, reduce_key=reduce_key, reduce_var=reduce_var)
+            collect_var=collect_var, reduce_key=reduce_key, reduce_var=reduce_var,
+            interactive=interactive)
         # Attach optional fields if parsed
         if 'tags' in dir(): res.tags = tags
         if 'parallel_block' in dir(): res.parallel_block = parallel_block; res.parallel_limit = parallel_limit; res.parallel_fail_policy = parallel_fail_policy

cgr_src/parser_cg.py

@@ -703,6 +703,7 @@ def _parse_cgr_step(name: str, header: str, body: list, ln: int, err,
     reduce_var: str|None = None
     flags: list[tuple[str, str|None]] = []
     until: str|None = None
+    interactive: bool = False
     # Provisioning fields (Phase 2)
     prov_block_dest: str|None = None; prov_block_marker: str|None = None
     prov_block_inline: str|None = None; prov_block_from: str|None = None
@@ -1331,6 +1332,11 @@ def _parse_cgr_step(name: str, header: str, body: list, ln: int, err,
             tags.extend(t.strip() for t in tags_m.group(1).split(",") if t.strip())
             i += 1; continue
 
+        # interactive  — force PTY + stdin forwarding
+        if btext.strip() == "interactive":
+            interactive = True
+            i += 1; continue
+
         # description "text" (for templates)
         desc_m = re.match(r'description\s+"([^"]*)"', btext)
         if desc_m:
@@ -1391,7 +1397,8 @@ def _parse_cgr_step(name: str, header: str, body: list, ln: int, err,
         retry_backoff_max=retry_backoff_max, retry_jitter_pct=retry_jitter_pct,
         on_success_set=list(on_success_set), on_failure_set=list(on_failure_set),
         collect_var=collect_var, reduce_key=reduce_key, reduce_var=reduce_var,
-        flags=list(flags), env_when=dict(env_when), until=until)
+        flags=list(flags), env_when=dict(env_when), until=until,
+        interactive=interactive)
 
 
 def _parse_cgr_verify(desc: str, body: list, ln: int, err) -> ASTResource:

cgr_src/parser_cgr.py

@@ -268,6 +268,7 @@ class Resource:
     env_when: dict[str, str] = field(default_factory=dict)
     until: str|None = None
     cgr_phase_name: str|None = None  # name of the phase "..." when "...": block this resource belongs to
+    interactive: bool = False        # force terminal-interactive mode (PTY + stdin forwarding)
 
 @dataclass
 class HostNode:
@@ -878,6 +879,7 @@ def _wire_gate(res_id):
         reduce_key=ast_res.reduce_key, reduce_var=ast_res.reduce_var,
         flags=resolved_flags, env_when=dict(ast_res.env_when), until=ast_res.until,
         cgr_phase_name=ast_res.cgr_phase_name,
+        interactive=ast_res.interactive,
     )
     collector[rid] = res
     dedup_hashes[ihash] = rid

cgr_src/resolver.py

@@ -7,16 +7,17 @@ set -euo pipefail
 # ── Terminal capability detection ─────────────────────────────────────────────
 
 if [ -t 1 ] && [ "${TERM:-dumb}" != "dumb" ] && [ "${NO_COLOR:-}" = "" ]; then
-    _RED='\033[0;31m'
-    _GREEN='\033[0;32m'
-    _YELLOW='\033[1;33m'
-    _BLUE='\033[0;34m'
-    _CYAN='\033[0;36m'
-    _MAGENTA='\033[0;35m'
-    _WHITE='\033[1;37m'
-    _BOLD='\033[1m'
-    _DIM='\033[2m'
-    _RESET='\033[0m'
+    _ESC="$(printf '\033')"
+    _RED="${_ESC}[0;31m"
+    _GREEN="${_ESC}[0;32m"
+    _YELLOW="${_ESC}[1;33m"
+    _BLUE="${_ESC}[0;34m"
+    _CYAN="${_ESC}[0;36m"
+    _MAGENTA="${_ESC}[0;35m"
+    _WHITE="${_ESC}[1;37m"
+    _BOLD="${_ESC}[1m"
+    _DIM="${_ESC}[2m"
+    _RESET="${_ESC}[0m"
 else
     _RED='' _GREEN='' _YELLOW='' _BLUE='' _CYAN='' _MAGENTA=''
     _WHITE='' _BOLD='' _DIM='' _RESET=''

install.sh

@@ -1704,8 +1704,30 @@ def isatty(self):
     def test_command_reads_tty_detection(self):
         assert cg._command_reads_tty("read -rp 'Username: ' user < /dev/tty")
         assert cg._command_reads_tty("printf prompt; read password")
+        assert cg._command_reads_tty("ssh-copy-id -i ~/.ssh/id_ed25519.pub user@example")
         assert not cg._command_reads_tty("printf 'alpha\\n' | wc -l")
 
+    def test_interactive_attribute_parsed(self):
+        src = textwrap.dedent('''\
+            target "local" local:
+              [prompt user]:
+                run $ passwd testuser
+                interactive
+        ''')
+        ast = cg.parse_cgr(src)
+        r = ast.nodes[0].resources[0]
+        assert r.interactive is True
+
+    def test_interactive_attribute_defaults_false(self):
+        src = textwrap.dedent('''\
+            target "local" local:
+              [do thing]:
+                run $ echo hello
+        ''')
+        ast = cg.parse_cgr(src)
+        r = ast.nodes[0].resources[0]
+        assert r.interactive is False
+
     def test_exec_resource_cancel_check_terminates_process(self, tmp_path):
         marker = tmp_path / "cancelled.txt"
         cmd = (