Add stable je_auto_control.api facade and portable failure bundles

New integrations get a small, lazy, typed entry point instead of the
eager historical top-level surface. Failed runs produce one atomic,
redacted autocontrol.failure-bundle/v1 ZIP (manifest, context, events,
log tail, optional screenshot/diagnostics) with best-effort collectors
so a broken screen grab cannot lose the bundle. codegen --failure-bundle
wraps generated pytest in automatic diagnostics; the secret redactor now
masks explicit key=value and bearer-token syntax regardless of entropy.

Author: JE-Chen

benchmarks/core_latency.py

@@ -0,0 +1,31 @@
+"""Repeatable smoke benchmark for stable headless entry points."""
+import json
+import statistics
+import time
+
+
+def _measure(callable_, repeats=20):
+    samples = []
+    for _ in range(repeats):
+        start = time.perf_counter()
+        callable_()
+        samples.append((time.perf_counter() - start) * 1000)
+    ordered = sorted(samples)
+    return {
+        "median_ms": round(statistics.median(samples), 3),
+        "p95_ms": round(ordered[max(0, int(len(ordered) * .95) - 1)], 3),
+    }
+
+
+def main():
+    import je_auto_control.api as ac
+    results = {
+        "diagnostics_ms": _measure(ac.run_diagnostics, repeats=5),
+        "codegen_ms": _measure(
+            lambda: ac.generate_code([["AC_screen_size"]]), repeats=20),
+    }
+    print(json.dumps(results, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

je_auto_control/api/__init__.py

@@ -0,0 +1,22 @@
+"""Small, versioned entry points for new integrations.
+
+The historical top-level package remains compatible.  New consumers should
+prefer this namespace so importing core automation does not eagerly import
+hundreds of optional integrations.
+"""
+
+from je_auto_control.api.core import (
+    FailureBundleOptions,
+    create_failure_bundle,
+    execute_action,
+    execute_action_with_vars,
+    generate_code,
+    failure_bundle_on_error,
+    run_diagnostics,
+)
+
+__all__ = [
+    "FailureBundleOptions", "create_failure_bundle", "execute_action",
+    "execute_action_with_vars", "failure_bundle_on_error", "generate_code",
+    "run_diagnostics",
+]

je_auto_control/api/core.py

@@ -0,0 +1,19 @@
+"""Stable, headless AutoControl API façade."""
+
+from je_auto_control.utils.codegen.codegen import generate_code
+from je_auto_control.utils.diagnostics import run_diagnostics
+from je_auto_control.utils.executor.action_executor import (
+    execute_action,
+    execute_action_with_vars,
+)
+from je_auto_control.utils.failure_bundle import (
+    FailureBundleOptions,
+    create_failure_bundle,
+    failure_bundle_on_error,
+)
+
+__all__ = [
+    "FailureBundleOptions", "create_failure_bundle", "execute_action",
+    "execute_action_with_vars", "failure_bundle_on_error", "generate_code",
+    "run_diagnostics",
+]

je_auto_control/cli.py

@@ -11,6 +11,7 @@
     je_auto_control fmt script.json [--check]
     je_auto_control record out.json [--duration 5]
     je_auto_control codegen script.json [--target pytest] [-o test_flow.py]
+    je_auto_control failure-bundle failure.zip [--error "message"]
     je_auto_control version
     je_auto_control list-jobs
     je_auto_control start-server --port 9938
@@ -147,11 +148,13 @@ def cmd_codegen(args: argparse.Namespace) -> int:
     from je_auto_control.utils.json.json_file import read_action_json
     if args.output:
         generate_code_file(args.script, args.output, target=args.target,
-                           name=args.name, style=args.style)
+                           name=args.name, style=args.style,
+                           failure_bundle=args.failure_bundle)
         sys.stderr.write(f"Wrote {args.target} code to {args.output}\n")
     else:
         code = generate_code(read_action_json(args.script), target=args.target,
-                             name=args.name, style=args.style)
+                             name=args.name, style=args.style,
+                             failure_bundle=args.failure_bundle)
         sys.stdout.write(code)
     return 0
 
@@ -166,6 +169,25 @@ def cmd_version(_: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_failure_bundle(args: argparse.Namespace) -> int:
+    """Collect a portable, redacted diagnostic archive."""
+    from je_auto_control.utils.failure_bundle import (
+        FailureBundleOptions, create_failure_bundle,
+    )
+    context = json.loads(args.context) if args.context else {}
+    path = create_failure_bundle(
+        args.output, error=args.error, context=context,
+        options=FailureBundleOptions(
+            screenshot=not args.no_screenshot,
+            diagnostics=not args.no_diagnostics,
+            log_path=args.log,
+            attachments=tuple(args.attach or ()),
+        ),
+    )
+    sys.stdout.write(path + "\n")
+    return 0
+
+
 def cmd_list_jobs(_: argparse.Namespace) -> int:
     from je_auto_control.utils.scheduler.scheduler import default_scheduler
     jobs = default_scheduler.list_jobs()
@@ -253,11 +275,26 @@ def build_parser() -> argparse.ArgumentParser:
                            default="calls")
     p_codegen.add_argument("--name", default="recorded_flow")
     p_codegen.add_argument("-o", "--output", help="Write to file instead of stdout")
+    p_codegen.add_argument(
+        "--failure-bundle", action="store_true",
+        help="Wrap generated pytest in automatic failure diagnostics")
     p_codegen.set_defaults(func=cmd_codegen)
 
     p_version = sub.add_parser("version", help="Print the installed version")
     p_version.set_defaults(func=cmd_version)
 
+    p_bundle = sub.add_parser(
+        "failure-bundle", help="Create a redacted failure diagnostic ZIP")
+    p_bundle.add_argument("output")
+    p_bundle.add_argument("--error", help="Failure summary")
+    p_bundle.add_argument("--context", help="JSON object with run context")
+    p_bundle.add_argument("--log", help="Log file whose redacted tail is included")
+    p_bundle.add_argument("--attach", action="append",
+                          help="Explicit attachment; may be repeated")
+    p_bundle.add_argument("--no-screenshot", action="store_true")
+    p_bundle.add_argument("--no-diagnostics", action="store_true")
+    p_bundle.set_defaults(func=cmd_failure_bundle)
+
     p_jobs = sub.add_parser("list-jobs", help="List scheduler jobs")
     p_jobs.set_defaults(func=cmd_list_jobs)
 

je_auto_control/utils/codegen/codegen.py

@@ -72,14 +72,24 @@ def _body(actions: Sequence, style: str) -> str:
     raise ValueError(f"unknown codegen style: {style!r}")
 
 
-def _render_pytest(actions: Sequence, name: str, style: str) -> str:
-    body = textwrap.indent(_body(actions, style), "    ")
+def _render_pytest(actions: Sequence, name: str, style: str,
+                   failure_bundle: bool = False) -> str:
+    raw_body = _body(actions, style)
+    if failure_bundle:
+        body = ("    with ac.failure_bundle_on_error(\n"
+                f"            {(_slug(name) + '-failure.zip')!r},\n"
+                f"            context={{'generated_test': {_slug(name)!r}}}):\n"
+                + textwrap.indent(raw_body, "        "))
+    else:
+        body = textwrap.indent(raw_body, "    ")
     return (f'"""{_HEADER}"""\n'
-            "import je_auto_control as ac\n\n\n"
-            f"def test_{_slug(name)}():\n{body}\n")
+            + ("import je_auto_control.api as ac\n\n\n" if failure_bundle
+               else "import je_auto_control as ac\n\n\n")
+            + f"def test_{_slug(name)}():\n{body}\n")
 
 
-def _render_python(actions: Sequence, name: str, style: str) -> str:
+def _render_python(actions: Sequence, name: str, style: str,
+                   _failure_bundle: bool = False) -> str:
     slug = _slug(name)
     body = textwrap.indent(_body(actions, style), "    ")
     return (f'"""{_HEADER}"""\n'
@@ -89,7 +99,8 @@ def _render_python(actions: Sequence, name: str, style: str) -> str:
             f"    {slug}()\n")
 
 
-def _render_robot(actions: Sequence, name: str, _style: str) -> str:
+def _render_robot(actions: Sequence, name: str, _style: str,
+                  _failure_bundle: bool = False) -> str:
     payload = json.dumps([list(action) for action in actions],
                          ensure_ascii=False)
     test_name = name.replace("_", " ").strip().title() or "Recorded Flow"
@@ -113,22 +124,27 @@ def _render_robot(actions: Sequence, name: str, _style: str) -> str:
 
 
 def generate_code(actions: Sequence, target: str = "pytest",
-                  name: str = "recorded_flow", style: str = "calls") -> str:
+                  name: str = "recorded_flow", style: str = "calls",
+                  failure_bundle: bool = False) -> str:
     """Render ``actions`` as source code for ``target`` (pytest/python/robot)."""
     if not isinstance(actions, list) or not actions:
         raise ValueError("actions must be a non-empty list")
     renderer = _RENDERERS.get(target)
     if renderer is None:
         raise ValueError(f"unknown codegen target: {target!r}")
-    return renderer(actions, name, style)
+    if failure_bundle and target != "pytest":
+        raise ValueError("failure_bundle is currently supported for pytest only")
+    return renderer(actions, name, style, failure_bundle)
 
 
 def generate_code_file(source, output_path: str, target: str = "pytest",
-                       name: str = "recorded_flow", style: str = "calls") -> str:
+                       name: str = "recorded_flow", style: str = "calls",
+                       failure_bundle: bool = False) -> str:
     """Generate code from a list or JSON action-file path; write and return it."""
     actions = source if isinstance(source, list) else read_action_json(
         os.path.realpath(source))
-    code = generate_code(actions, target=target, name=name, style=style)
+    code = generate_code(actions, target=target, name=name, style=style,
+                         failure_bundle=failure_bundle)
     with open(os.path.realpath(output_path), "w", encoding="utf-8") as handle:
         handle.write(code)
     return code

je_auto_control/utils/config_redaction/config_redaction.py

@@ -44,11 +44,26 @@ def redact_config(obj: Any, *, mask: str = _DEFAULT_MASK) -> Any:
 
 def redact_secret_text(text: str, *, mask: str = _DEFAULT_MASK) -> str:
     """Mask secret-looking tokens within a free-text string (e.g. a log line)."""
+    # Explicit credential syntax must be masked even when the value is short or
+    # low-entropy and therefore intentionally below the generic scanner's
+    # threshold (common in tests, local deployments, and leaked error text).
+    text = re.sub(
+        r"(?i)(\bauthorization\s*:\s*bearer\s+)[^\s,;]+",
+        lambda match: match.group(1) + mask,
+        text or "",
+    )
+    text = re.sub(
+        r"(?i)(\b(?:api[_-]?key|access[_-]?token|token|password|passwd|secret)"
+        r"\s*[=:]\s*)([^\s,;]+)",
+        lambda match: match.group(1) + mask,
+        text,
+    )
+
     def _replace(match: "re.Match[str]") -> str:
         token = match.group(0)
         core = token.strip(_PUNCT)
         if core and scan_secrets({"value": core}):
             return token.replace(core, mask)
         return token
 
-    return re.sub(r"\S+", _replace, text or "")
+    return re.sub(r"\S+", _replace, text)

je_auto_control/utils/deprecation.py

@@ -0,0 +1,35 @@
+"""Consistent deprecation warnings for public AutoControl APIs."""
+from __future__ import annotations
+
+import functools
+import warnings
+from typing import Callable, TypeVar, cast
+
+F = TypeVar("F", bound=Callable)
+
+
+class AutoControlDeprecationWarning(FutureWarning):
+    """A user-visible warning for an API scheduled for removal."""
+
+
+def deprecated(*, since: str, removal: str, replacement: str = ""):
+    """Mark a callable deprecated with actionable lifecycle metadata."""
+    def decorate(func: F) -> F:
+        message = f"{func.__qualname__} is deprecated since {since}"
+        message += f" and will be removed in {removal}."
+        if replacement:
+            message += f" Use {replacement} instead."
+
+        @functools.wraps(func)
+        def wrapped(*args, **kwargs):
+            warnings.warn(message, AutoControlDeprecationWarning,
+                          stacklevel=2)
+            return func(*args, **kwargs)
+        wrapped.__deprecated__ = {  # type: ignore[attr-defined]
+            "since": since, "removal": removal, "replacement": replacement,
+        }
+        return cast(F, wrapped)
+    return decorate
+
+
+__all__ = ["AutoControlDeprecationWarning", "deprecated"]

je_auto_control/utils/failure_bundle/__init__.py

@@ -0,0 +1,11 @@
+"""Portable, redacted failure diagnostics."""
+
+from je_auto_control.utils.failure_bundle.bundle import (
+    FailureBundleOptions,
+    create_failure_bundle,
+    failure_bundle_on_error,
+)
+
+__all__ = [
+    "FailureBundleOptions", "create_failure_bundle", "failure_bundle_on_error",
+]