npm - create-workframe - Versions diffs - 0.1.0 - Mend

create-workframe 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (415) hide show

package/workframe-api/email_sender.py ADDED Viewed

@@ -0,0 +1,220 @@
+"""
+Email sender module for Workframe API.
+Sends OTP verification emails via SMTP (env or stack_config).
+"""
+from __future__ import annotations
+import os
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from typing import Any
+import stack_config
+APP_BASE_URL = os.environ.get("APP_BASE_URL", "http://127.0.0.1:18644").rstrip("/")
+def _tls_flags(cfg: dict[str, Any]) -> tuple[bool, bool]:
+    port = int(cfg.get("port") or 587)
+    secure = stack_config.normalize_smtp_secure(port, str(cfg.get("secure") or ""))
+    use_ssl = secure == "ssl"
+    use_tls = secure == "starttls"
+    return use_ssl, use_tls
+def _smtp_send(msg: MIMEMultipart, to_email: str, cfg: dict[str, Any]) -> None:
+    host = str(cfg.get("host") or "").strip()
+    if not host:
+        raise RuntimeError("SMTP_HOST not configured")
+    port = int(cfg.get("port") or 587)
+    user = str(cfg.get("user") or "").strip()
+    password = str(cfg.get("password") or "").strip().replace(" ", "")
+    from_addr = str(cfg.get("from") or user or "").strip()
+    if not from_addr:
+        raise RuntimeError("SMTP from address not configured")
+    if user and not password:
+        raise RuntimeError("SMTP password is required when SMTP user is set")
+    msg["From"] = from_addr
+    use_ssl, use_tls = _tls_flags(cfg)
+    try:
+        if use_ssl:
+            server = smtplib.SMTP_SSL(host, port, timeout=30)
+        else:
+            server = smtplib.SMTP(host, port, timeout=30)
+        with server:
+            server.ehlo()
+            if use_tls and not use_ssl:
+                server.starttls()
+                server.ehlo()
+            if user:
+                server.login(user, password)
+            server.sendmail(from_addr, [to_email], msg.as_string())
+    except smtplib.SMTPAuthenticationError as exc:
+        raise RuntimeError(f"SMTP login failed: {exc}") from exc
+    except smtplib.SMTPSenderRefused as exc:
+        sender = str(getattr(exc, "sender", "") or from_addr)
+        if user and sender.lower() != user.lower():
+            raise RuntimeError(
+                f"SMTP rejected From address {sender!r} for login {user!r}"
+            ) from exc
+        raise RuntimeError(f"SMTP error: {exc}") from exc
+    except smtplib.SMTPException as exc:
+        raise RuntimeError(f"SMTP error: {exc}") from exc
+    except OSError as exc:
+        raise RuntimeError(f"Network error sending email: {exc}") from exc
+def _active_smtp() -> dict[str, Any]:
+    cfg = stack_config.resolved_smtp()
+    if cfg.get("source") == "none":
+        return {}
+    return cfg
+def send_email_with_config(
+    to_email: str,
+    subject: str,
+    body_text: str,
+    body_html: str = "",
+    cfg: dict[str, Any] | None = None,
+) -> None:
+    smtp = cfg or _active_smtp()
+    if not smtp.get("host"):
+        raise RuntimeError("SMTP_HOST not configured")
+    msg = MIMEMultipart("alternative")
+    msg["Subject"] = subject
+    msg["To"] = to_email
+    msg.attach(MIMEText(body_text, "plain"))
+    if body_html:
+        msg.attach(MIMEText(body_html, "html"))
+    _smtp_send(msg, to_email, smtp)
+def _branded_html(
+    *,
+    brand: str,
+    headline: str,
+    intro: str,
+    body_html: str,
+    logo_url: str = "",
+    footer: str = "If you didn't request this, you can safely ignore this email.",
+) -> str:
+    logo_block = (
+        f'<img src="{logo_url}" alt="" style="height:40px;margin-bottom:12px;" />'
+        if logo_url
+        else ""
+    )
+    return f"""\
+<html>
+<body style="margin:0; background:#f6f7fb; font-family:-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; color:#1d2340;">
+  <div style="max-width:560px; margin:0 auto; padding:32px 20px;">
+    <div style="background:#ffffff; border:1px solid #e4e7f2; border-radius:20px; padding:32px; box-shadow:0 24px 64px rgba(14,20,49,0.08);">
+      {logo_block}
+      <div style="font-size:12px; font-weight:700; letter-spacing:0.14em; text-transform:uppercase; color:#6c5ce7; margin-bottom:12px;">{brand}</div>
+      <h1 style="margin:0 0 12px; font-size:28px; line-height:1.2;">{headline}</h1>
+      <p style="margin:0 0 24px; color:#4f5878; font-size:16px; line-height:1.6;">{intro}</p>
+      {body_html}
+      <p style="margin:24px 0 0; color:#7b849d; font-size:12px; line-height:1.6;">{footer}</p>
+    </div>
+  </div>
+</body>
+</html>
+"""
+def _code_block_html(code: str) -> str:
+    return f"""\
+<div style="background:linear-gradient(180deg, #f5f7ff 0%, #eef1ff 100%); border:1px solid #d9defa; border-radius:16px; padding:18px 20px; text-align:center; margin-bottom:20px;">
+  <div style="font-size:12px; font-weight:700; letter-spacing:0.08em; text-transform:uppercase; color:#6b7280; margin-bottom:10px;">Verification code</div>
+  <div style="font-size:34px; font-weight:800; letter-spacing:10px; color:#111827; font-variant-numeric:tabular-nums;">{code}</div>
+</div>
+<p style="margin:0 0 20px; color:#4f5878; font-size:14px; line-height:1.6;">This code expires in 10 minutes.</p>
+"""
+def _cta_button_html(url: str, label: str) -> str:
+    return (
+        f'<a href="{url}" style="display:inline-block; padding:12px 20px; background:#6c5ce7; '
+        f'color:#ffffff; text-decoration:none; border-radius:10px; font-weight:700;">{label}</a>'
+    )
+def _build_verification_email(
+    to_email: str,
+    code: str,
+    verification_url: str,
+    workspace_name: str = "Workframe",
+    logo_url: str = "",
+) -> MIMEMultipart:
+    msg = MIMEMultipart("alternative")
+    brand = workspace_name or "Workframe"
+    msg["Subject"] = f"Your {brand} sign-in code"
+    msg["To"] = to_email
+    text_body = f"""\
+{brand} sign-in code
+Your verification code is:
+{code}
+This code expires in 10 minutes.
+Or click the link to verify:
+{verification_url}
+If you didn't request this, ignore this email.
+"""
+    body_html = _code_block_html(code) + _cta_button_html(verification_url, "Verify now")
+    html_body = _branded_html(
+        brand=brand,
+        headline="Sign in with your code",
+        intro="Use this one-time code to finish signing in to Workframe.",
+        body_html=body_html,
+        logo_url=logo_url,
+    )
+    msg.attach(MIMEText(text_body, "plain"))
+    msg.attach(MIMEText(html_body, "html"))
+    return msg
+def send_verification_email(
+    to_email: str,
+    code: str,
+    verification_url: str,
+    workspace_name: str = "",
+    logo_url: str = "",
+) -> None:
+    msg = _build_verification_email(to_email, code, verification_url, workspace_name, logo_url)
+    _smtp_send(msg, to_email, _active_smtp())
+def send_email(to_email: str, subject: str, body_text: str, body_html: str = "") -> None:
+    send_email_with_config(to_email, subject, body_text, body_html)
+def send_branded_invite_email(
+    to_email: str,
+    workspace_name: str,
+    invite_url: str,
+    logo_url: str = "",
+) -> None:
+    brand = workspace_name or "Workframe"
+    subject = f"Join {brand} on Workframe"
+    text = f"You were invited to {brand}.\n\nAccept: {invite_url}\n"
+    body_html = _cta_button_html(invite_url, "Accept invite")
+    html = _branded_html(
+        brand=brand,
+        headline=f"Join {brand}",
+        intro="You were invited to collaborate on Workframe.",
+        body_html=body_html,
+        logo_url=logo_url,
+        footer="If you weren't expecting this invite, you can ignore this email.",
+    )
+    send_email_with_config(to_email, subject, text, html)
+if __name__ == "__main__":
+    html = _build_verification_email("test@example.com", "123456", "http://127.0.0.1:18644/?code=123456").as_string()
+    assert "Verification code" in html and "Verify now" in html

package/workframe-api/google_auth.py ADDED Viewed

@@ -0,0 +1,90 @@
+"""Google Sign-In for Workframe (workspace-configured OAuth app)."""
+from __future__ import annotations
+import json
+import os
+import secrets
+import urllib.parse
+import urllib.request
+from typing import Any
+import oidc_jwt
+import stack_config
+APP_BASE_URL = os.environ.get("APP_BASE_URL", "http://127.0.0.1:18644").rstrip("/")
+_PENDING: dict[str, dict[str, str]] = {}
+def _google_creds() -> tuple[str, str]:
+    cfg = stack_config.resolved_google_oauth()
+    client_id = str(cfg.get("client_id") or "").strip()
+    client_secret = str(cfg.get("client_secret") or "").strip()
+    if not client_id or not client_secret:
+        raise ValueError("Google Sign-In is not configured")
+    return client_id, client_secret
+def start_google_auth(invite_email: str = "", invite_token: str = "") -> dict[str, Any]:
+    client_id, _ = _google_creds()
+    state = secrets.token_urlsafe(24)
+    _PENDING[state] = {
+        "invite_email": invite_email.strip().lower(),
+        "invite_token": invite_token.strip(),
+    }
+    redirect_uri = f"{APP_BASE_URL}/api/auth/google/callback"
+    params = {
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "response_type": "code",
+        "scope": "openid email profile",
+        "state": state,
+        "access_type": "online",
+        "prompt": "select_account",
+    }
+    if invite_email:
+        params["login_hint"] = invite_email.strip()
+    url = "https://accounts.google.com/o/oauth2/v2/auth?" + urllib.parse.urlencode(params)
+    return {"ok": True, "auth_url": url, "state": state}
+def exchange_google_code(code: str, state: str) -> dict[str, Any]:
+    pending = _PENDING.pop(state, None)
+    if not pending:
+        raise ValueError("invalid or expired OAuth state")
+    client_id, client_secret = _google_creds()
+    redirect_uri = f"{APP_BASE_URL}/api/auth/google/callback"
+    data = urllib.parse.urlencode(
+        {
+            "code": code,
+            "client_id": client_id,
+            "client_secret": client_secret,
+            "redirect_uri": redirect_uri,
+            "grant_type": "authorization_code",
+        }
+    ).encode()
+    req = urllib.request.Request(
+        "https://oauth2.googleapis.com/token",
+        data=data,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        token_payload = json.loads(resp.read().decode())
+    id_token = str(token_payload.get("id_token") or "")
+    if not id_token:
+        raise ValueError("Google did not return an id_token")
+    claims = oidc_jwt.verify_google_id_token(id_token, client_id)
+    email = str(claims.get("email") or "").strip().lower()
+    if not email:
+        raise ValueError("Google account has no email")
+    if claims.get("email_verified") is False:
+        raise ValueError("Google email is not verified")
+    invite_email = pending.get("invite_email") or ""
+    if invite_email and email != invite_email:
+        raise ValueError("Google email does not match the invited address")
+    return {
+        "email": email,
+        "display_name": str(claims.get("name") or email),
+        "invite_token": pending.get("invite_token") or "",
+    }

package/workframe-api/install_api.py ADDED Viewed

@@ -0,0 +1,359 @@
+"""Install / stack-setup API helpers."""
+from __future__ import annotations
+import os
+import re
+import sqlite3
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any
+import stack_config
+from email_sender import send_email_with_config
+HERMES_DATA = Path(os.environ.get("HERMES_DATA", "/opt/data"))
+NATIVE_PROFILE = os.environ.get("WORKFRAME_NATIVE_PROFILE", "workframe-agent").strip() or "workframe-agent"
+def _user_count(db_path: str) -> int:
+    try:
+        conn = sqlite3.connect(db_path, timeout=2.0)
+        row = conn.execute("SELECT COUNT(*) FROM users").fetchone()
+        conn.close()
+        return int(row[0]) if row else 0
+    except (sqlite3.Error, OSError):
+        return 0
+def install_window_open(db_path: str) -> bool:
+    """Open until operator marks install complete — users may exist mid-onboarding."""
+    del db_path  # ponytail: reserved for future per-install DB path checks
+    return not bool(stack_config.get_stack_config().get("install_complete"))
+def _hermes_native_present() -> bool:
+    for slug in (NATIVE_PROFILE, "workframe-agent"):
+        if not slug:
+            continue
+        prof_dir = HERMES_DATA / "profiles" / slug
+        if (prof_dir / "config.yaml").is_file() or (prof_dir / "profile.yaml").is_file():
+            return True
+    return False
+def _setup_complete(db_path: str) -> bool:
+    try:
+        conn = sqlite3.connect(db_path, timeout=2.0)
+        row = conn.execute(
+            "SELECT COUNT(*) FROM agent_profiles WHERE deleted_at IS NULL"
+        ).fetchone()
+        conn.close()
+        return bool(row and row[0] > 0)
+    except (sqlite3.Error, OSError):
+        return _hermes_native_present()
+def install_status_payload(
+    deployment_mode: str,
+    secure_mode: bool,
+    dev_unsafe: bool,
+    db_path: str,
+) -> dict[str, Any]:
+    hermes = _hermes_native_present()
+    setup = _setup_complete(db_path)
+    smtp_ok = stack_config.smtp_configured()
+    return {
+        "ok": True,
+        "phase": "ready" if hermes and setup else ("hermes" if not hermes else "workspace"),
+        "hermes_present": hermes,
+        "setup_complete": setup,
+        "api_ok": True,
+        "deployment_mode": deployment_mode,
+        "mode": "dev_unsafe" if dev_unsafe else ("secure" if secure_mode else "dev_unsafe"),
+        "smtp_configured": smtp_ok,
+        "install_complete": bool(stack_config.get_stack_config().get("install_complete")),
+        "install_window_open": install_window_open(db_path),
+        "native_profile": NATIVE_PROFILE,
+    }
+def smtp_test_send(to_email: str) -> dict[str, Any]:
+    to_email = str(to_email or "").strip().lower()
+    if not to_email or "@" not in to_email:
+        raise ValueError("valid email required")
+    cfg = stack_config.resolved_smtp()
+    if not cfg.get("host"):
+        raise ValueError("SMTP is not configured yet")
+    subject = "Workframe test email"
+    text = "If you received this, your Workframe SMTP settings are working."
+    html = "<p>If you received this, your Workframe SMTP settings are working.</p>"
+    send_email_with_config(to_email, subject, text, html, cfg)
+    stack_config.patch_stack_config({"smtp": {"admin_email": to_email}})
+    stack_config.mark_smtp_tested()
+    return {"ok": True, "email_sent": True, "to": to_email}
+def _normalize_app_base_url(url: str) -> str:
+    """Ensure app_base_url has a scheme for health checks and OAuth callbacks."""
+    u = str(url or "").strip().rstrip("/")
+    if not u:
+        return ""
+    if not u.lower().startswith(("http://", "https://")):
+        u = f"https://{u}"
+    return u
+def _hostname_only(url: str) -> str:
+    u = _normalize_app_base_url(url)
+    if not u:
+        return ""
+    try:
+        return urllib.parse.urlparse(u).hostname or ""
+    except Exception:
+        return str(url or "").strip().lower()
+def dns_record_name(hostname: str) -> str:
+    host = _hostname_only(hostname) or str(hostname or "").strip().lower().rstrip(".")
+    if not host:
+        return "@"
+    parts = host.split(".")
+    if len(parts) <= 2:
+        return "@"
+    return parts[0]
+def apex_domain(hostname: str) -> str:
+    host = _hostname_only(hostname) or str(hostname or "").strip().lower().rstrip(".")
+    if not host:
+        return ""
+    parts = host.split(".")
+    if len(parts) <= 2:
+        return host
+    return ".".join(parts[-2:])
+def detect_public_ipv4() -> str | None:
+    for url in ("https://api4.ipify.org", "https://ifconfig.me/ip"):
+        try:
+            with urllib.request.urlopen(url, timeout=4) as resp:
+                ip = resp.read().decode("utf-8", errors="replace").strip()
+                if ip and "." in ip:
+                    return ip
+        except (urllib.error.URLError, OSError, TimeoutError, ValueError):
+            continue
+    return None
+def publish_hints_payload(public_url: str) -> dict[str, Any]:
+    host = _hostname_only(public_url)
+    apex = apex_domain(host)
+    ui_port = int(os.environ.get("WORKFRAME_UI_PORT", "18644") or "18644")
+    public_ip = detect_public_ipv4()
+    project_root = (
+        os.environ.get("WORKFRAME_HOST_PROJECT_ROOT", "").strip()
+        or "/opt/workframe/ProjectX"
+    )
+    setup_command = (
+        f"sudo bash {project_root}/scripts/workframe/setup-public-https.sh {host} {ui_port}"
+        if host
+        else ""
+    )
+    dns_name = dns_record_name(host)
+    return {
+        "ok": True,
+        "hostname": host,
+        "apex_domain": apex,
+        "public_ipv4": public_ip,
+        "ui_port": ui_port,
+        "project_root": project_root,
+        "health_url": f"https://{host}/api/health" if host else "",
+        "dns": {
+            "type": "A",
+            "name": dns_name,
+            "value": public_ip or "",
+            "ttl": "600",
+        },
+        "dns_cname": {
+            "type": "CNAME",
+            "name": dns_name,
+            "value": apex,
+            "hint": "Optional: point the subdomain at your apex hostname instead of an IP. CNAME cannot target an IP address.",
+        }
+        if apex and dns_name != "@"
+        else None,
+        "registrar_links": [
+            {
+                "label": "GoDaddy DNS",
+                "url": f"https://dcc.godaddy.com/manage/{apex}/dns" if apex else "https://dcc.godaddy.com/control/portfolio",
+            },
+            {
+                "label": "Namecheap DNS",
+                "url": f"https://ap.www.namecheap.com/Domains/DomainControlPanel/{apex}/advancedns"
+                if apex
+                else "https://www.namecheap.com/domains/",
+            },
+            {"label": "Cloudflare", "url": "https://dash.cloudflare.com"},
+        ],
+        "setup_command": setup_command,
+    }
+def _loopback_hostname(hostname: str) -> bool:
+    h = (hostname or "").strip().lower().rstrip(".")
+    return h in ("127.0.0.1", "localhost", "::1") or h.endswith(".localhost")
+def _fetch_health(url: str, timeout: float = 8) -> dict[str, Any]:
+    with urllib.request.urlopen(url, timeout=timeout) as resp:
+        body = resp.read().decode("utf-8", errors="replace")
+        ok = resp.status == 200 and '"ok"' in body
+        return {"ok": ok, "status": resp.status, "checked_url": url}
+def _local_stack_health() -> dict[str, Any]:
+    ui_port = int(os.environ.get("WORKFRAME_UI_PORT", "18644") or "18644")
+    app_base = str(
+        stack_config.get_stack_config().get("app_base_url")
+        or os.environ.get("APP_BASE_URL", "")
+        or f"http://127.0.0.1:{ui_port}",
+    )
+    host_header = _hostname_only(app_base) or "127.0.0.1"
+    req = urllib.request.Request(
+        "http://workframe-ui/api/health",
+        headers={"Host": f"{host_header}:{ui_port}"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=8) as resp:
+            body = resp.read().decode("utf-8", errors="replace")
+            ok = resp.status == 200 and '"ok"' in body
+            return {"ok": ok, "status": resp.status, "local_ok": ok, "checked_url": req.full_url}
+    except Exception as exc:
+        return {"local_ok": False, "error": str(exc)}
+def _url_test_hint(exc: Exception, *, local: dict[str, Any]) -> str:
+    msg = str(exc).lower()
+    ui_port = int(os.environ.get("WORKFRAME_UI_PORT", "18644") or "18644")
+    if "connection refused" in msg or "errno 111" in msg:
+        base = (
+            f"Nothing is listening on HTTPS for that host yet. Use step 2 (Set up HTTPS on this server), "
+            f"point DNS here, and open ports 80/443. Caddy proxies to 127.0.0.1:{ui_port}."
+        )
+        if local.get("local_ok"):
+            return f"Workframe is healthy on this server. {base}"
+        return base
+    if "timed out" in msg or "timeout" in msg:
+        return (
+            "Timed out reaching that URL — DNS may not point to this server yet, or HTTPS is not ready. "
+            "Add the A record, run Set up HTTPS, wait a minute, then retry."
+        )
+    if local.get("local_ok"):
+        return "Workframe is running on this server; the public URL is not reachable from here yet."
+    return "Check DNS, HTTPS (Caddy), and that the domain matches this server."
+def url_test(app_base_url: str) -> dict[str, Any]:
+    url = _normalize_app_base_url(app_base_url)
+    if not url:
+        raise ValueError("app_base_url required")
+    host = _hostname_only(url)
+    if _loopback_hostname(host):
+        try:
+            local = _local_stack_health()
+            if local.get("local_ok"):
+                return {
+                    "ok": True,
+                    "status": local.get("status"),
+                    "url": url,
+                    "checked_url": local.get("checked_url"),
+                    "hint": "Loopback URL — verified via the UI proxy on this stack.",
+                }
+            return {
+                "ok": False,
+                "url": url,
+                "error": str(local.get("error") or "local health check failed"),
+                "hint": "Is the Workframe UI container running?",
+            }
+        except Exception as exc:
+            return {
+                "ok": False,
+                "url": url,
+                "error": str(exc),
+                "hint": "Is the Workframe UI container running?",
+            }
+    health_url = f"{url.rstrip('/')}/api/health"
+    local = _local_stack_health()
+    try:
+        return {**_fetch_health(health_url), "url": health_url}
+    except urllib.error.HTTPError as exc:
+        return {
+            "ok": False,
+            "status": exc.code,
+            "url": health_url,
+            "error": str(exc),
+            "hint": _url_test_hint(exc, local=local),
+            "local_ok": bool(local.get("local_ok")),
+        }
+    except Exception as exc:
+        return {
+            "ok": False,
+            "url": health_url,
+            "error": str(exc),
+            "hint": _url_test_hint(exc, local=local),
+            "local_ok": bool(local.get("local_ok")),
+        }
+def smtp_error_hint(exc: Exception) -> str:
+    msg = str(exc).lower()
+    if "smtp login failed" in msg or "535" in msg or "badcredentials" in msg:
+        return "Check SMTP username and app password. For Gmail, use an App Password—not your normal password."
+    if "smtp password is required" in msg:
+        return "Enter the SMTP app password. Compose uses SMTP_PASS; onboarding saves it in stack config."
+    if "rejected from address" in msg:
+        return (
+            "Gmail rejected that From address for this login. Leave From blank to send as your login email, "
+            "or add the address under Gmail Settings → Accounts → Send mail as."
+        )
+    if "530" in msg and "authentication required" in msg:
+        return "SMTP authentication did not complete. Check username, app password, and port (465=SSL, 587=STARTTLS)."
+    if "connect" in msg or "timed out" in msg or "unexpectedly closed" in msg:
+        return "Check SMTP host and port. Port 465 needs SSL; port 587 uses STARTTLS."
+    if "certificate" in msg or "ssl" in msg:
+        return "Try toggling TLS/SSL settings to match your provider."
+    return "Double-check host, port, username, password, and From address, then try again."
+def normalize_setup_https(host: str, port: int | str | None = None) -> tuple[str, int]:
+    name = _hostname_only(host) or str(host or "").strip().lower()
+    if not name or not re.fullmatch(r"[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?", name, re.IGNORECASE):
+        raise ValueError("valid hostname required")
+    ui_port = int(port or os.environ.get("WORKFRAME_UI_PORT", "18644") or "18644")
+    return name, ui_port
+if __name__ == "__main__":
+    assert dns_record_name("dev.alanborger.com") == "dev"
+    assert dns_record_name("alanborger.com") == "@"
+    assert apex_domain("dev.alanborger.com") == "alanborger.com"
+    assert _loopback_hostname("127.0.0.1")
+    assert _loopback_hostname("localhost")
+    assert not _loopback_hostname("dev.example.com")
+    import tempfile
+    from pathlib import Path
+    td = Path(tempfile.mkdtemp())
+    os.environ["WORKFRAME_API_DATA_DIR"] = str(td)
+    stack_config.patch_stack_config({"smtp": {"host": "smtp.test", "user": "a", "password": "b"}})
+    assert not stack_config.smtp_tested()
+    stack_config.mark_smtp_tested()
+    assert stack_config.smtp_tested()
+    stack_config.patch_stack_config({"smtp": {"host": "smtp.other"}})
+    assert not stack_config.smtp_tested()
+    print("install_api publish hints ok")