Make a failed run say so, and stop shipping a file people fill with secrets

Three problems that all showed up as "it does nothing".

A run that could not start printed nothing and exited 0. loguru begins with no
sinks, src/logging.py removes them again and only adds one if LOG_TO_FILE or
LOG_TO_CONSOLE is set, and both were False. main.py catches every exception,
hands it to that silent logger and falls off the end of the function. Measured
with a required file removed: empty stdout, empty stderr, exit 0, and the shell
reporting success. Every other first-run problem went the same way, a wrong key,
no Chrome, an unreachable posting. Console logging is on and the handlers exit 1.

data_folder held the file the setup instructions tell you to put your API key in,
and it was tracked. Filling it in staged a live credential on the next commit,
which is exactly how one got in here. Same for plain_text_resume.yaml, which
wants your address and phone number. Those three files are untracked and ignored
now, and main.py creates them from data_folder_example on first run and tells you
what to edit, so the manual copy step is gone as well.

The error message pointed at Auto_Jobs_Applier_AIHawk, a name this repository has
not had for a while.

Tests for all of it, each checked against the failure it describes: reverting the
console flag turns both visibility tests red, and the placeholder check now
refuses six credential prefixes rather than one, verified against four.

Author: feder-cr

.gitignore

@@ -161,4 +161,7 @@ venv.bak/
 # Mono Auto Generated Files
 mono_crash.*
 
-job_applications/
+job_applications/
+# Your own key, your own CV, your own address. Created from data_folder_example
+# on first run. Was tracked until it leaked an API key.
+data_folder/*.yaml

README.md

@@ -6,7 +6,10 @@
 LOG_LEVEL = 'ERROR'
 LOG_SELENIUM_LEVEL = ERROR
 LOG_TO_FILE = False
-LOG_TO_CONSOLE = False
+# Errors go through loguru, and loguru starts with every sink removed. With this
+# False the program was silent about everything: a missing config file, a bad API
+# key, an unreachable posting. It exited 0 and printed nothing.
+LOG_TO_CONSOLE = True
 
 MINIMUM_WAIT_TIME_IN_SECONDS = 60
 

config.py

@@ -1,4 +1,5 @@
 import base64
+import shutil
 import sys
 from pathlib import Path
 import traceback
@@ -186,6 +187,28 @@ class FileManager:
 
     REQUIRED_FILES = [SECRETS_YAML, WORK_PREFERENCES_YAML, PLAIN_TEXT_RESUME_YAML]
 
+    @staticmethod
+    def bootstrap_data_folder(app_data_folder: Path, example_folder: Path) -> List[str]:
+        """Create the data folder from the example on a fresh clone.
+
+        data_folder holds your API key, your CV and your address, so it is not in
+        git. That used to mean a fresh clone had nothing there and the run died on
+        a missing file. Copying it is a step nobody should have to read about.
+
+        Returns the names of the files it had to create, empty if there was
+        nothing to do.
+        """
+        created = []
+        app_data_folder.mkdir(parents=True, exist_ok=True)
+        for name in FileManager.REQUIRED_FILES:
+            target = app_data_folder / name
+            source = example_folder / name
+            if target.exists() or not source.exists():
+                continue
+            shutil.copyfile(source, target)
+            created.append(name)
+        return created
+
     @staticmethod
     def validate_data_folder(app_data_folder: Path) -> Tuple[Path, Path, Path, Path]:
         """Validate the existence of the data folder and required files."""
@@ -529,6 +552,17 @@ def main():
     try:
         # Define and validate the data folder
         data_folder = Path("data_folder")
+        created = FileManager.bootstrap_data_folder(data_folder, Path("data_folder_example"))
+        if created:
+            logger.error(
+                f"Created {', '.join(created)} in {data_folder}/ from the example. "
+                "Open them and put your own details in: plain_text_resume.yaml is "
+                "your experience, work_preferences.yaml is what you are looking "
+                "for, and secrets.yaml takes your OpenAI API key. Then run this "
+                "again."
+            )
+            sys.exit(1)
+
         secrets_file, config_file, plain_text_resume_file, output_folder = FileManager.validate_data_folder(data_folder)
 
         # Validate configuration and secrets
@@ -549,16 +583,20 @@ def main():
         logger.error(f"Configuration error: {ce}")
         logger.error(
             "Refer to the configuration guide for troubleshooting: "
-            "https://github.com/feder-cr/Auto_Jobs_Applier_AIHawk?tab=readme-ov-file#configuration"
+            "https://github.com/feder-cr/Jobs_Applier_AI_Agent_AIHawk?tab=readme-ov-file#configuration"
         )
+        sys.exit(1)
     except FileNotFoundError as fnf:
         logger.error(f"File not found: {fnf}")
         logger.error("Ensure all required files are present in the data folder.")
+        sys.exit(1)
     except RuntimeError as re:
         logger.error(f"Runtime error: {re}")
         logger.debug(traceback.format_exc())
+        sys.exit(1)
     except Exception as e:
         logger.exception(f"An unexpected error occurred: {e}")
+        sys.exit(1)
 
 
 if __name__ == "__main__":

data_folder/plain_text_resume.yaml

@@ -0,0 +1,76 @@
+"""A run that cannot proceed has to say so, on the terminal and in the exit code.
+
+It did neither. loguru starts with no sinks, src/logging.py removes them again
+and only adds one if LOG_TO_FILE or LOG_TO_CONSOLE is set, and config.py had both
+False. main.py catches every exception, hands it to that sink-less logger and
+falls off the end of the function. Measured before the fix: a run with a required
+config file missing printed nothing at all on stdout or stderr and exited 0. The
+shell reported success.
+
+Every other first-run problem went the same way: a wrong API key, no Chrome, an
+unreachable posting.
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def run_in(folder: Path):
+    env = {**os.environ, "PYTHONPATH": str(ROOT), "PYTHONIOENCODING": "utf-8"}
+    return subprocess.run(
+        [sys.executable, str(ROOT / "main.py")],
+        cwd=folder,
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=120,
+        stdin=subprocess.DEVNULL,
+    )
+
+
+def prepare(folder: Path):
+    """Give the run a copy of the shipped example to work from."""
+    shutil.copytree(ROOT / "data_folder_example", folder / "data_folder_example")
+    return folder
+
+
+def test_a_fresh_clone_creates_the_data_folder_and_says_what_to_edit(tmp_path):
+    prepare(tmp_path)
+
+    done = run_in(tmp_path)
+    combined = done.stdout + done.stderr
+
+    for name in ("secrets.yaml", "work_preferences.yaml", "plain_text_resume.yaml"):
+        assert (tmp_path / "data_folder" / name).exists(), f"{name} was not created"
+    assert done.returncode != 0, "the first run has nothing to work with yet"
+    assert "secrets.yaml" in combined, (
+        "the run has to name what it created and ask for real values. Got:\n"
+        f"stdout={done.stdout!r}\nstderr={done.stderr!r}"
+    )
+
+
+def test_a_broken_config_is_reported_rather_than_swallowed(tmp_path):
+    """The bootstrap above cannot help with a file that exists and is wrong, which
+    is the case that used to exit 0 in silence."""
+    prepare(tmp_path)
+    data = tmp_path / "data_folder"
+    shutil.copytree(ROOT / "data_folder_example", data)
+    prefs = data / "work_preferences.yaml"
+    prefs.write_text(
+        prefs.read_text(encoding="utf-8").replace("distance:", "distance_typo:"),
+        encoding="utf-8",
+    )
+
+    done = run_in(tmp_path)
+    combined = done.stdout + done.stderr
+
+    assert done.returncode != 0, "an invalid config must not report success"
+    assert "distance" in combined.lower(), (
+        "the run has to name what is wrong with the config. Got:\n"
+        f"stdout={done.stdout!r}\nstderr={done.stderr!r}"
+    )

data_folder/secrets.yaml

@@ -13,7 +13,9 @@
 
 import main
 
-SHIPPED = ["data_folder", "data_folder_example"]
+# data_folder is no longer tracked: it holds the user's key and CV, and it is
+# created from this example on first run. The example is the only shipped copy.
+SHIPPED = ["data_folder_example"]
 
 
 @pytest.mark.parametrize("folder", SHIPPED)
@@ -29,13 +31,21 @@ def test_shipped_secrets_provide_a_key(folder):
     assert main.ConfigValidator.validate_secrets(Path(folder) / "secrets.yaml")
 
 
+# Prefixes the common providers put on their keys. sk- covers OpenAI and
+# Anthropic, AIza is Google, hf_ is HuggingFace, gsk_ is Groq. The project only
+# calls OpenAI today, but somebody pasting any of these into the shipped file is
+# the accident this guards.
+KEY_PREFIXES = ("sk-", "AIza", "hf_", "gsk_", "xai-", "pplx-")
+
+
 @pytest.mark.parametrize("folder", SHIPPED)
 def test_shipped_secrets_are_a_placeholder_and_not_a_real_key(folder):
     key = main.ConfigValidator.validate_secrets(Path(folder) / "secrets.yaml")
-    assert not key.startswith("sk-"), (
-        f"{folder}/secrets.yaml looks like a real API key rather than a placeholder. "
-        "Credentials must never be committed here: put yours in the file locally and "
-        "keep it out of the diff."
+    looks_real = [p for p in KEY_PREFIXES if key.startswith(p)]
+    assert not looks_real, (
+        f"{folder}/secrets.yaml starts with {looks_real[0]!r}, which is what a real "
+        "API key looks like rather than a placeholder. Credentials must never be "
+        "committed here: put yours in the file locally and keep it out of the diff."
     )