openstat-cli 1.0.0__py3-none-any.whl

openstat/commands/viz_adv_cmds.py

@@ -0,0 +1,312 @@
+"""Advanced visualization: 3D, interactive, animated, missing, map."""
+
+from __future__ import annotations
+
+from openstat.commands.base import command, CommandArgs, friendly_error
+from openstat.session import Session
+
+
+@command("plot3d", usage="plot3d <x> <y> <z> [--color=<col>]")
+def cmd_plot3d(session: Session, args: str) -> str:
+    """3D scatter plot.
+
+    Examples:
+      plot3d x y z
+      plot3d age income educ --color=gender
+    """
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    from mpl_toolkits.mplot3d import Axes3D  # noqa: F401
+    import numpy as np
+    import polars as pl
+
+    ca = CommandArgs(args)
+    if len(ca.positional) < 3:
+        return "Usage: plot3d <x> <y> <z> [--color=<col>]"
+    x_col, y_col, z_col = ca.positional[:3]
+    color_col = ca.options.get("color")
+
+    try:
+        df = session.require_data()
+        for c in [x_col, y_col, z_col]:
+            if c not in df.columns:
+                return f"Column not found: {c}"
+
+        cols = [x_col, y_col, z_col]
+        if color_col and color_col in df.columns:
+            cols.append(color_col)
+        sub = df.select(cols).drop_nulls()
+
+        x = sub[x_col].to_numpy().astype(float)
+        y = sub[y_col].to_numpy().astype(float)
+        z = sub[z_col].to_numpy().astype(float)
+
+        fig = plt.figure(figsize=(9, 7))
+        ax = fig.add_subplot(111, projection="3d")
+
+        if color_col and color_col in sub.columns:
+            cats = sub[color_col].cast(pl.Utf8).to_list()
+            unique_cats = sorted(set(cats))
+            cmap = plt.colormaps.get_cmap("tab10")
+            for i, cat in enumerate(unique_cats):
+                mask = [c == cat for c in cats]
+                ax.scatter(x[mask], y[mask], z[mask],
+                           label=str(cat), alpha=0.7, color=cmap(i / max(len(unique_cats), 1)))
+            ax.legend(title=color_col)
+        else:
+            ax.scatter(x, y, z, alpha=0.6, color="#4C72B0")
+
+        ax.set_xlabel(x_col)
+        ax.set_ylabel(y_col)
+        ax.set_zlabel(z_col)
+        ax.set_title(f"3D Scatter: {x_col} × {y_col} × {z_col}")
+        fig.tight_layout()
+
+        session.output_dir.mkdir(parents=True, exist_ok=True)
+        from pathlib import Path
+        path = session.output_dir / "scatter3d.png"
+        fig.savefig(path, dpi=150)
+        plt.close(fig)
+        session.plot_paths.append(str(path))
+        return f"3D scatter plot saved: {path}"
+    except Exception as e:
+        return friendly_error(e, "plot3d")
+
+
+@command("plotmissing", usage="plotmissing [cols...]")
+def cmd_plotmissing(session: Session, args: str) -> str:
+    """Missing data heatmap: visualise missingness patterns across columns.
+
+    Shows rows (sampled if large) × columns with missing/present colour coding.
+
+    Examples:
+      plotmissing
+      plotmissing income age education
+    """
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    import numpy as np
+    import polars as pl
+
+    ca = CommandArgs(args)
+    try:
+        df = session.require_data()
+        cols = ca.positional if ca.positional else df.columns
+
+        missing_cols = [c for c in cols if c not in df.columns]
+        if missing_cols:
+            return f"Columns not found: {', '.join(missing_cols)}"
+
+        # Sample up to 500 rows for readability
+        MAX_ROWS = 500
+        if df.height > MAX_ROWS:
+            import random
+            idx = sorted(random.sample(range(df.height), MAX_ROWS))
+            sub = df[idx].select(cols)
+        else:
+            sub = df.select(cols)
+
+        # Build missing matrix
+        mat = np.zeros((sub.height, len(cols)))
+        for j, c in enumerate(cols):
+            mat[:, j] = sub[c].is_null().to_numpy().astype(float)
+
+        miss_pct = [f"{100*df[c].null_count()/df.height:.0f}%" for c in cols]
+        labels = [f"{c}\n({p})" for c, p in zip(cols, miss_pct)]
+
+        fig, ax = plt.subplots(figsize=(max(8, len(cols) * 0.5 + 2), 6))
+        ax.imshow(mat.T, aspect="auto", cmap="RdYlGn_r", interpolation="nearest",
+                  vmin=0, vmax=1)
+        ax.set_yticks(range(len(cols)))
+        ax.set_yticklabels(labels, fontsize=8)
+        ax.set_xlabel("Rows")
+        ax.set_title("Missingness Heatmap (red=missing, green=present)")
+        fig.tight_layout()
+
+        session.output_dir.mkdir(parents=True, exist_ok=True)
+        from pathlib import Path
+        path = session.output_dir / "missing_heatmap.png"
+        fig.savefig(path, dpi=150)
+        plt.close(fig)
+        session.plot_paths.append(str(path))
+
+        # Summary table
+        lines = [f"Missing data heatmap saved: {path}", ""]
+        lines.append(f"  {'Column':<25} {'Missing':>8} {'%':>6}")
+        lines.append("  " + "-" * 42)
+        for c in cols:
+            n = df[c].null_count()
+            p = 100 * n / df.height
+            lines.append(f"  {c:<25} {n:>8,} {p:>5.1f}%")
+        return "\n".join(lines)
+    except Exception as e:
+        return friendly_error(e, "plotmissing")
+
+
+@command("plotinteractive", usage="plotinteractive scatter|bar|line|hist <args> [--out=plot.html]")
+def cmd_plotinteractive(session: Session, args: str) -> str:
+    """Interactive Plotly chart (saved as HTML — open in browser).
+
+    Sub-commands: scatter, bar, line, hist, box, heatmap
+
+    Options:
+      --out=<path>   output HTML file (default: outputs/interactive_plot.html)
+      --title=<txt>  chart title
+
+    Examples:
+      plotinteractive scatter y x
+      plotinteractive hist income --out=income_dist.html
+      plotinteractive bar category value
+      plotinteractive line date price --title="Price Over Time"
+    """
+    try:
+        import plotly.express as px
+        import plotly.io as pio
+    except ImportError:
+        return "plotly required. Install: pip install plotly"
+
+    import polars as pl
+    ca = CommandArgs(args)
+    if not ca.positional:
+        return "Usage: plotinteractive scatter|bar|line|hist|box|heatmap <args>"
+
+    subcmd = ca.positional[0].lower()
+    out_path = ca.options.get("out", str(session.output_dir / "interactive_plot.html"))
+    title = ca.options.get("title", f"Interactive {subcmd.title()}")
+
+    try:
+        df = session.require_data()
+        pd_df = df.to_pandas()
+
+        if subcmd == "scatter":
+            if len(ca.positional) < 3:
+                return "Usage: plotinteractive scatter <y> <x>"
+            y_col, x_col = ca.positional[1], ca.positional[2]
+            color_col = ca.options.get("color")
+            fig = px.scatter(pd_df, x=x_col, y=y_col, color=color_col, title=title, trendline="ols")
+
+        elif subcmd == "hist":
+            if len(ca.positional) < 2:
+                return "Usage: plotinteractive hist <col>"
+            col = ca.positional[1]
+            fig = px.histogram(pd_df, x=col, title=title, nbins=30)
+
+        elif subcmd == "bar":
+            if len(ca.positional) < 3:
+                return "Usage: plotinteractive bar <category> <value>"
+            cat_col, val_col = ca.positional[1], ca.positional[2]
+            fig = px.bar(pd_df, x=cat_col, y=val_col, title=title)
+
+        elif subcmd == "line":
+            if len(ca.positional) < 3:
+                return "Usage: plotinteractive line <x> <y>"
+            x_col, y_col = ca.positional[1], ca.positional[2]
+            color_col = ca.options.get("color")
+            fig = px.line(pd_df, x=x_col, y=y_col, color=color_col, title=title)
+
+        elif subcmd == "box":
+            if len(ca.positional) < 2:
+                return "Usage: plotinteractive box <col> [by <group>]"
+            col = ca.positional[1]
+            by_raw = ca.rest_after("by")
+            group = by_raw.strip().split()[0] if by_raw else None
+            fig = px.box(pd_df, y=col, x=group, title=title)
+
+        elif subcmd == "heatmap":
+        
+            NUMERIC = ["float32", "float64", "int32", "int64", "int8", "int16"]
+            num_cols = [c for c in df.columns if str(df[c].dtype).lower() in NUMERIC]
+            corr = df.select(num_cols).to_pandas().corr()
+            fig = px.imshow(corr, title="Correlation Heatmap", color_continuous_scale="RdBu", zmin=-1, zmax=1)
+
+        else:
+            return f"Unknown sub-command: {subcmd}"
+
+        from pathlib import Path
+        Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+        pio.write_html(fig, out_path)
+        return f"Interactive {subcmd} chart saved: {out_path}\nOpen in a web browser to view."
+    except Exception as e:
+        return friendly_error(e, "plotinteractive")
+
+
+@command("plotanimated", usage="plotanimated <y> <x> <time_col> [--out=anim.gif]")
+def cmd_plotanimated(session: Session, args: str) -> str:
+    """Animated line/scatter plot over a time variable (saved as GIF).
+
+    Shows how the relationship between x and y changes across time steps.
+
+    Examples:
+      plotanimated sales month year --out=sales_trend.gif
+      plotanimated price date --out=price_animation.gif
+    """
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    import matplotlib.animation as animation
+    import numpy as np
+    import polars as pl
+
+    ca = CommandArgs(args)
+    if len(ca.positional) < 3:
+        return "Usage: plotanimated <y> <x> <time_col> [--out=anim.gif]"
+
+    y_col, x_col, t_col = ca.positional[0], ca.positional[1], ca.positional[2]
+    out_path = ca.options.get("out", str(session.output_dir / "animated.gif"))
+
+    try:
+        df = session.require_data()
+        for c in [y_col, x_col, t_col]:
+            if c not in df.columns:
+                return f"Column not found: {c}"
+
+        sub = df.select([t_col, x_col, y_col]).drop_nulls().sort(t_col)
+        time_vals = sub[t_col].cast(pl.Utf8).to_list()
+        unique_times = sorted(set(time_vals))
+
+        if len(unique_times) < 2:
+            return f"Need at least 2 unique values in '{t_col}' for animation."
+        if len(unique_times) > 60:
+            unique_times = unique_times[:60]  # cap
+
+        x_all = sub[x_col].to_numpy().astype(float)
+        y_all = sub[y_col].to_numpy().astype(float)
+        x_min, x_max = x_all.min(), x_all.max()
+        y_min, y_max = y_all.min(), y_all.max()
+
+        fig, ax = plt.subplots(figsize=(7, 5))
+        scatter = ax.scatter([], [], alpha=0.7, color="#4C72B0", s=30)
+        ax.set_xlim(x_min - abs(x_min) * 0.05, x_max + abs(x_max) * 0.05)
+        ax.set_ylim(y_min - abs(y_min) * 0.05, y_max + abs(y_max) * 0.05)
+        ax.set_xlabel(x_col)
+        ax.set_ylabel(y_col)
+        title_obj = ax.set_title("")
+
+        def update(frame):
+            t = unique_times[frame]
+            mask = [tv == t for tv in time_vals]
+            xd = x_all[mask]
+            yd = y_all[mask]
+            scatter.set_offsets(np.column_stack([xd, yd]))
+            title_obj.set_text(f"{t_col}: {t}")
+            return scatter, title_obj
+
+        ani = animation.FuncAnimation(fig, update, frames=len(unique_times),
+                                      interval=300, blit=False)
+
+        from pathlib import Path
+        Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+        try:
+            ani.save(out_path, writer="pillow", fps=3)
+        except Exception:
+            # Fallback: save as MP4 or just first frame
+            out_path = out_path.replace(".gif", ".png")
+            update(0)
+            fig.savefig(out_path, dpi=120)
+        plt.close(fig)
+        session.plot_paths.append(out_path)
+        return f"Animated plot saved: {out_path}  ({len(unique_times)} frames)"
+    except Exception as e:
+        return friendly_error(e, "plotanimated")

openstat/commands/viz_extra_cmds.py

@@ -0,0 +1,251 @@
+"""Extra visualization commands: corrplot, pairplot, violin, qq, residplot."""
+
+from __future__ import annotations
+
+import re
+
+from openstat.commands.base import command
+from openstat.session import Session
+
+
+def _stata_opts(raw: str) -> tuple[list[str], dict[str, str]]:
+    opts: dict[str, str] = {}
+    for m in re.finditer(r'(\w+)\(([^)]*)\)', raw):
+        opts[m.group(1).lower()] = m.group(2)
+    rest = re.sub(r'\w+\([^)]*\)', '', raw)
+    positional = [t.strip(',') for t in rest.split() if t.strip(',')]
+    return positional, opts
+
+
+def _save_or_show(fig, path: str | None, default_name: str) -> str:
+    import os
+    if path:
+        os.makedirs(os.path.dirname(path) if os.path.dirname(path) else ".", exist_ok=True)
+        fig.savefig(path, dpi=150, bbox_inches="tight")
+        return path
+    os.makedirs("outputs", exist_ok=True)
+    out = f"outputs/{default_name}"
+    fig.savefig(out, dpi=150, bbox_inches="tight")
+    return out
+
+
+@command("corrplot", usage="corrplot [var1 var2 ...] [saving(path.png)]")
+def cmd_corrplot(session: Session, args: str) -> str:
+    """Correlation matrix heatmap."""
+    try:
+        import matplotlib.pyplot as plt
+        import numpy as np
+    except ImportError:
+        return "matplotlib not installed."
+    df = session.require_data()
+    positional, opts = _stata_opts(args)
+    cols = [c for c in positional if c in df.columns]
+    if not cols:
+        cols = [c for c in df.columns if df[c].dtype in (
+            __import__("polars").Float64, __import__("polars").Float32,
+            __import__("polars").Int64, __import__("polars").Int32,
+        )][:12]
+    if len(cols) < 2:
+        return "corrplot requires at least 2 numeric variables."
+    try:
+        import polars as pl
+        data = df.select(cols).drop_nulls().to_numpy().astype(float)
+        corr = np.corrcoef(data.T)
+        fig, ax = plt.subplots(figsize=(max(6, len(cols)), max(5, len(cols) - 1)))
+        im = ax.imshow(corr, cmap="RdBu_r", vmin=-1, vmax=1, aspect="auto")
+        plt.colorbar(im, ax=ax, shrink=0.8)
+        ax.set_xticks(range(len(cols)))
+        ax.set_yticks(range(len(cols)))
+        ax.set_xticklabels(cols, rotation=45, ha="right", fontsize=9)
+        ax.set_yticklabels(cols, fontsize=9)
+        for i in range(len(cols)):
+            for j in range(len(cols)):
+                ax.text(j, i, f"{corr[i,j]:.2f}", ha="center", va="center", fontsize=7,
+                        color="white" if abs(corr[i, j]) > 0.6 else "black")
+        ax.set_title("Correlation Matrix")
+        fig.tight_layout()
+        path = opts.get("saving")
+        out = _save_or_show(fig, path, "corrplot.png")
+        plt.close(fig)
+        return f"Correlation plot saved: {out}"
+    except Exception as exc:
+        return f"corrplot error: {exc}"
+
+
+@command("pairplot", usage="pairplot [var1 var2 ...] [saving(path.png)]")
+def cmd_pairplot(session: Session, args: str) -> str:
+    """Scatter matrix (pairplot) of numeric variables."""
+    try:
+        import matplotlib.pyplot as plt
+        import numpy as np
+    except ImportError:
+        return "matplotlib not installed."
+    df = session.require_data()
+    positional, opts = _stata_opts(args)
+    cols = [c for c in positional if c in df.columns]
+    if not cols:
+        import polars as pl
+        cols = [c for c in df.columns if df[c].dtype in (
+            pl.Float64, pl.Float32, pl.Int64, pl.Int32,
+        )][:6]
+    if len(cols) < 2:
+        return "pairplot requires at least 2 numeric variables."
+    try:
+        data = df.select(cols).drop_nulls().to_numpy().astype(float)
+        k = len(cols)
+        fig, axes = plt.subplots(k, k, figsize=(2.5 * k, 2.5 * k))
+        for i in range(k):
+            for j in range(k):
+                ax = axes[i, j]
+                if i == j:
+                    ax.hist(data[:, i], bins=20, color="steelblue", alpha=0.7)
+                    ax.set_ylabel("")
+                else:
+                    ax.scatter(data[:, j], data[:, i], alpha=0.3, s=10, color="steelblue")
+                if i == k - 1:
+                    ax.set_xlabel(cols[j], fontsize=8)
+                if j == 0:
+                    ax.set_ylabel(cols[i], fontsize=8)
+                ax.tick_params(labelsize=6)
+        fig.suptitle("Scatter Matrix", fontsize=12)
+        fig.tight_layout()
+        path = opts.get("saving")
+        out = _save_or_show(fig, path, "pairplot.png")
+        plt.close(fig)
+        return f"Pair plot saved: {out}"
+    except Exception as exc:
+        return f"pairplot error: {exc}"
+
+
+@command("violin", usage="violin var [by(groupvar)] [saving(path.png)]")
+def cmd_violin(session: Session, args: str) -> str:
+    """Violin plot for distribution visualization."""
+    try:
+        import matplotlib.pyplot as plt
+        import numpy as np
+    except ImportError:
+        return "matplotlib not installed."
+    df = session.require_data()
+    positional, opts = _stata_opts(args)
+    if not positional:
+        return "Usage: violin var [by(groupvar)] [saving(path.png)]"
+    col = positional[0]
+    if col not in df.columns:
+        return f"Column '{col}' not found."
+    by = opts.get("by")
+    try:
+        fig, ax = plt.subplots(figsize=(8, 5))
+        if by and by in df.columns:
+            groups = df[by].drop_nulls().unique().sort().to_list()
+            data_groups = [df.filter(__import__("polars").col(by) == g)[col].drop_nulls().to_numpy().astype(float)
+                           for g in groups]
+            parts = ax.violinplot(data_groups, showmedians=True)
+            ax.set_xticks(range(1, len(groups) + 1))
+            ax.set_xticklabels([str(g) for g in groups])
+            ax.set_xlabel(str(by))
+        else:
+            data = df[col].drop_nulls().to_numpy().astype(float)
+            ax.violinplot([data], showmedians=True)
+            ax.set_xticks([1])
+            ax.set_xticklabels([col])
+        ax.set_ylabel(col)
+        ax.set_title(f"Violin Plot: {col}")
+        fig.tight_layout()
+        path = opts.get("saving")
+        out = _save_or_show(fig, path, f"violin_{col}.png")
+        plt.close(fig)
+        return f"Violin plot saved: {out}"
+    except Exception as exc:
+        return f"violin error: {exc}"
+
+
+@command("qqplot", usage="qqplot var [saving(path.png)]")
+def cmd_qqplot(session: Session, args: str) -> str:
+    """Quantile-Quantile (Q-Q) normality plot."""
+    try:
+        import matplotlib.pyplot as plt
+        import numpy as np
+        from scipy import stats as sp_stats
+    except ImportError:
+        return "matplotlib or scipy not installed."
+    df = session.require_data()
+    positional, opts = _stata_opts(args)
+    if not positional:
+        return "Usage: qqplot var [saving(path.png)]"
+    col = positional[0]
+    if col not in df.columns:
+        return f"Column '{col}' not found."
+    try:
+        data = df[col].drop_nulls().to_numpy().astype(float)
+        fig, ax = plt.subplots(figsize=(6, 6))
+        (osm, osr), (slope, intercept, r) = sp_stats.probplot(data, dist="norm")
+        ax.scatter(osm, osr, alpha=0.5, s=15, color="steelblue", label="Data")
+        x_line = np.array([osm.min(), osm.max()])
+        ax.plot(x_line, slope * x_line + intercept, "r-", lw=2, label="Normal line")
+        ax.set_xlabel("Theoretical quantiles")
+        ax.set_ylabel("Sample quantiles")
+        ax.set_title(f"Q-Q Plot: {col}")
+        ax.legend()
+        # Shapiro-Wilk stat
+        if len(data) <= 5000:
+            sw_stat, sw_p = sp_stats.shapiro(data[:5000])
+            ax.text(0.05, 0.95, f"Shapiro-Wilk p = {sw_p:.4f}", transform=ax.transAxes,
+                    fontsize=9, verticalalignment="top")
+        fig.tight_layout()
+        path = opts.get("saving")
+        out = _save_or_show(fig, path, f"qqplot_{col}.png")
+        plt.close(fig)
+        return f"Q-Q plot saved: {out} (R²={r**2:.4f})"
+    except Exception as exc:
+        return f"qqplot error: {exc}"
+
+
+@command("residplot", usage="residplot dep var1 [var2 ...] [saving(path.png)]")
+def cmd_residplot(session: Session, args: str) -> str:
+    """Residual vs fitted and scale-location plots for OLS."""
+    try:
+        import matplotlib.pyplot as plt
+        import numpy as np
+    except ImportError:
+        return "matplotlib not installed."
+    df = session.require_data()
+    positional, opts = _stata_opts(args)
+    if len(positional) < 2:
+        return "Usage: residplot dep var1 [var2 ...]"
+    dep = positional[0]
+    indeps = [c for c in positional[1:] if c in df.columns]
+    if dep not in df.columns:
+        return f"Column '{dep}' not found."
+    if not indeps:
+        return "No valid predictor variables."
+    try:
+        sub = df.select([dep] + indeps).drop_nulls()
+        y = sub[dep].to_numpy().astype(float)
+        X = np.column_stack([np.ones(len(y)), sub.select(indeps).to_numpy().astype(float)])
+        beta = np.linalg.lstsq(X, y, rcond=None)[0]
+        fitted = X @ beta
+        resid = y - fitted
+        std_resid = resid / max(resid.std(), 1e-10)
+
+        fig, axes = plt.subplots(1, 2, figsize=(12, 5))
+
+        # Residuals vs Fitted
+        axes[0].scatter(fitted, resid, alpha=0.4, s=15, color="steelblue")
+        axes[0].axhline(0, color="red", lw=1)
+        axes[0].set_xlabel("Fitted values")
+        axes[0].set_ylabel("Residuals")
+        axes[0].set_title("Residuals vs Fitted")
+
+        # Scale-Location
+        axes[1].scatter(fitted, np.sqrt(np.abs(std_resid)), alpha=0.4, s=15, color="steelblue")
+        axes[1].set_xlabel("Fitted values")
+        axes[1].set_ylabel("√|Standardized residuals|")
+        axes[1].set_title("Scale-Location")
+
+        fig.tight_layout()
+        path = opts.get("saving")
+        out = _save_or_show(fig, path, f"residplot_{dep}.png")
+        plt.close(fig)
+        return f"Residual plots saved: {out}"
+    except Exception as exc:
+        return f"residplot error: {exc}"

openstat/commands/watch_cmds.py

@@ -0,0 +1,69 @@
+"""Watch command: re-run a script automatically when the file changes."""
+
+from __future__ import annotations
+
+import time
+import os
+
+from openstat.commands.base import command, CommandArgs
+from openstat.session import Session
+
+
+@command("watch", usage="watch <script.ost> [--interval=2]")
+def cmd_watch(session: Session, args: str) -> str:
+    """Watch a script file and re-run it whenever it changes.
+
+    Monitors the file's modification time every N seconds (default 2).
+    Press Ctrl+C to stop watching.
+
+    Examples:
+      watch analysis.ost
+      watch pipeline.ost --interval=5
+    """
+    ca = CommandArgs(args)
+    if not ca.positional:
+        return "Usage: watch <script.ost> [--interval=2]"
+
+    script_path = ca.positional[0]
+    interval = float(ca.options.get("interval", 2))
+
+    if not os.path.exists(script_path):
+        return f"File not found: {script_path}"
+
+    from openstat.script_runner import run_script_advanced
+
+    last_mtime = os.path.getmtime(script_path)
+
+    print(f"Watching {script_path} (interval={interval}s). Press Ctrl+C to stop.")
+
+    try:
+        # Run once immediately
+        run_script_advanced(script_path, session)
+        print(f"[Initial run complete]")
+
+        while True:
+            time.sleep(interval)
+            try:
+                current_mtime = os.path.getmtime(script_path)
+            except FileNotFoundError:
+                print(f"File removed: {script_path}. Stopping watch.")
+                break
+
+            if current_mtime != last_mtime:
+                last_mtime = current_mtime
+                print(f"\n[{_timestamp()}] File changed — re-running {script_path}...")
+                try:
+                    run_script_advanced(script_path, session)
+                    print(f"[{_timestamp()}] Done.")
+                except Exception as exc:
+                    print(f"[{_timestamp()}] Error: {exc}")
+
+    except KeyboardInterrupt:
+        pass
+
+    return f"Watch stopped: {script_path}"
+
+
+def _timestamp() -> str:
+    from datetime import datetime
+    return datetime.now().strftime("%H:%M:%S")