feat(01-01): config system, Fernet crypto, setup wizard

[coder-ishan]

What Was Built

Fernet-encrypted config system, setup wizard CLI, and package scaffold — the shared config layer every other module will import.

Key Files Created

• pyproject.toml — hatchling build, all deps, asyncio_mode = "auto", job-hunter entry point
• src/ingot/__init__.py — __version__ = "0.1.0"
• src/ingot/config/crypto.py — PBKDF2HMAC key derivation (600k iterations), get_fernet(), encrypt_secret(), decrypt_secret()
• src/ingot/config/schema.py — AppConfig, AgentConfig, SmtpConfig, ImapConfig (Pydantic v2)
• src/ingot/config/manager.py — ConfigManager.load()/save() with atomic write, __encrypted__: prefix for secrets
• src/ingot/cli/setup.py — full setup wizard: interactive (questionary) + non-interactive (env vars), --preset fully_free/best_quality, skips existing values, Rich summary table
• src/ingot/cli/__init__.py — Typer app with setup subcommand
• src/ingot/logging_config.py — structlog dual handlers (stderr WARNING+, rotating file DEBUG+ JSON)

Verification

• python3 -c "import ingot; print(ingot.__version__)" → 0.1.0 ✓
• Fernet roundtrip: decrypt_secret(encrypt_secret("hello")) == "hello" ✓
• All module imports clean: ConfigManager, AppConfig, setup_app ✓

Commits

• a53d0a8 feat(01-01): project scaffold, pyproject.toml, and package structure
• b4b1f02 feat(01-01): Fernet crypto module and ConfigManager
• fa2d6b7 feat(01-01): setup wizard CLI with interactive + non-interactive modes

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR implements the foundational configuration system for INGOT, including Fernet-based encryption for secrets, a Pydantic-based configuration schema, and an interactive/non-interactive setup wizard CLI. This is Plan 01-01, providing the essential infrastructure that all subsequent modules will depend on for loading credentials, selecting LLM backends, and locating application data.

Changes:

• Added Fernet encryption system with PBKDF2 key derivation for protecting API keys and passwords at rest
• Created Pydantic v2 configuration schema with support for 7 core agents and email/LLM service credentials
• Implemented interactive and non-interactive setup wizard with preset configurations for different LLM deployment strategies
• Added structlog-based logging configuration with dual handlers (stderr and rotating file)
• Configured project build system with hatchling, dependencies, and test settings

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
pyproject.toml	Project metadata, dependencies, pytest configuration, and CLI entry point definition
src/ingot/init.py	Package version identifier
src/ingot/config/init.py	Config subsystem package marker
src/ingot/config/crypto.py	Fernet encryption/decryption with PBKDF2 key derivation from machine-specific key file
src/ingot/config/schema.py	Pydantic models for application configuration including agent, SMTP, and IMAP settings
src/ingot/config/manager.py	Configuration persistence with atomic writes and automatic secret encryption/decryption
src/ingot/logging_config.py	Structured logging setup with stderr console output and rotating JSON file logs
src/ingot/cli/init.py	Typer-based CLI application entry point
src/ingot/cli/setup.py	Interactive and non-interactive setup wizard with preset support and validation
.planning/phases/01-foundation-and-core-infrastructure/01-01-SUMMARY.md	Plan completion summary

Comments suppressed due to low confidence (14)

src/ingot/cli/setup.py:217

• When password prompt returns None (user cancels), the code checks if password is falsy but uses the generic error message "Gmail App Password cannot be empty." This treats None (cancelled) the same as an empty string (user pressed enter). Consider distinguishing between cancellation and empty input, or at least catch the cancellation earlier to provide a clearer message.

        password = questionary.password("Gmail App Password:").ask()
        if not password:
            _err.print("[red]Gmail App Password cannot be empty.[/red]")
            raise typer.Exit(code=1)

src/ingot/config/manager.py:77

• If the config.json file contains invalid JSON, json.loads() will raise a JSONDecodeError which is not caught. This could happen if the file is corrupted or manually edited incorrectly. Consider catching JSONDecodeError and providing a helpful error message, or letting it bubble up with context about which file failed to parse.

        raw = json.loads(self.config_path.read_text(encoding="utf-8"))

src/ingot/logging_config.py:17

• The comment references "~/.outreach-agent/" but should reference "log files" or describe what the base_dir parameter represents more generally. The hardcoded path in the docstring doesn't match the function's flexibility to accept any base_dir.

        base_dir: Base directory for log files (e.g., ~/.outreach-agent/).

src/ingot/cli/setup.py:194

• The errors list is initialized but never populated with any error messages. The list is checked at the end but no errors are ever added to it. Either remove the unused error handling code or implement the validation that should add errors (e.g., when required environment variables are missing).

    errors: list[str] = []

    gmail_username = os.environ.get("GMAIL_USERNAME", "")
    gmail_password = os.environ.get("GMAIL_APP_PASSWORD", "")
    anthropic_key = os.environ.get("ANTHROPIC_API_KEY", "")
    openai_key = os.environ.get("OPENAI_API_KEY", "")

    if gmail_username:
        cfg.smtp.username = gmail_username
        cfg.imap.username = gmail_username
    if gmail_password:
        cfg.smtp.password = gmail_password
        cfg.imap.password = gmail_password
    if anthropic_key:
        cfg.anthropic_api_key = anthropic_key
    if openai_key:
        cfg.openai_api_key = openai_key

    # Apply preset or default to fully_free
    effective_preset = preset or _PRESET_FULLY_FREE
    _apply_preset(cfg, effective_preset)

    # Ensure all 7 agents exist
    for agent_name in _AGENT_NAMES:
        if agent_name not in cfg.agents:
            cfg.agents[agent_name] = AgentConfig()

    if errors:
        for error in errors:
            _err.print(f"[red]{error}[/red]")
        raise typer.Exit(code=1)

src/ingot/logging_config.py:31

• The date format uses the current date at the time configure_logging is called, but if the application runs across midnight, logs will continue writing to the old date's file. Consider whether this is the intended behavior or if log rotation should happen at midnight. The RotatingFileHandler rotates based on size, not time.

    date_str = datetime.now().strftime("%Y-%m-%d")
    log_file = log_dir / f"run-{date_str}.log"

src/ingot/config/crypto.py:15

• The stat module is imported but never used. The chmod call on line 59 uses the literal 0o600 instead of stat module constants. Either remove the unused import or use stat.S_IRUSR | stat.S_IWUSR for better clarity.

import stat

src/ingot/cli/init.py:21

• The import of setup_app is placed after code execution (after the app callback function) to avoid circular imports, indicated by the noqa: E402 comment. While this works, consider restructuring the module to avoid this pattern - perhaps by moving the command registration to a separate function or using lazy imports. The current structure makes the code flow less intuitive.

from ingot.cli.setup import setup_app  # noqa: E402

src/ingot/cli/setup.py:66

• Secrets are displayed in the summary table with partial masking via the _mask function. However, showing even the first 4 characters of API keys or passwords could aid in brute-force attacks if an attacker can see the output. Consider either masking more characters or only showing them for debugging purposes with a flag. This is especially important for the summary output which might be logged or shared in screenshots.

def _mask(value: str, show_chars: int = 4) -> str:
    """Return a masked version of a secret for display."""
    if not value:
        return "(not set)"
    if len(value) <= show_chars:
        return "*" * len(value)
    return value[:show_chars] + "*" * (len(value) - show_chars)

src/ingot/cli/setup.py:131

• The traceback import is unused - it's imported but never called. Either use traceback.print_exc() or remove the import.

        import traceback

src/ingot/cli/setup.py:132

• The import statement appears after code execution due to the late import inside the exception handler. This violates PEP 8 conventions which recommend imports at the top of the file. Move the logging and traceback imports to the top of the file with the other imports.

        import traceback
        import logging

src/ingot/cli/setup.py:143

• The verbose parameter is accepted but never used in the setup wizard. It's passed through _run_setup but not utilized to control output verbosity or logging level. Either implement verbose output levels or remove the unused parameter.

    verbose: int = typer.Option(0, "-v", count=True, max=2),
) -> None:
    """Run the INGOT setup wizard to configure credentials and LLM backends."""
    try:
        _run_setup(non_interactive=non_interactive, preset=preset, verbose=verbose)
    except KeyboardInterrupt:
        _err.print("\n[yellow]Setup cancelled.[/yellow]")
        raise typer.Exit(code=1)
    except typer.Exit:
        raise
    except Exception as exc:
        log_path = Path.home() / ".outreach-agent" / "logs"
        _err.print(f"[red][Setup] Something went wrong. Full error logged to {log_path}[/red]")
        # Log the full traceback
        import traceback
        import logging
        logging.getLogger("ingot.cli.setup").error(
            "Setup wizard failed", exc_info=True
        )
        raise typer.Exit(code=1) from exc


def _run_setup(
    *,
    non_interactive: bool,
    preset: str | None,
    verbose: int,

pyproject.toml:16

• The version constraint ">=44" for cryptography is unusual and may be incorrect. The cryptography library typically uses semantic versioning (e.g., 44.0.0). This constraint would match any version >= 44.0.0, but versions typically look like "44.0.0" not "44". Consider using a more standard constraint like ">=44.0.0" or ">=44.0" to be more explicit.

    "cryptography>=44",

src/ingot/config/manager.py:96

• The atomic write uses with_suffix(".tmp") which replaces the file extension. For "config.json", this produces "config.tmp" which is correct. However, if config_path ever doesn't have a suffix (e.g., "config"), this would produce "config.tmp" which is still fine. Consider using a more explicit temp file pattern like config_path.with_name(config_path.name + ".tmp") or documenting why with_suffix is sufficient here.

        tmp_path = self.config_path.with_suffix(".tmp")

src/ingot/config/schema.py:72

• The default factory lambda creates a new list each time, which is correct for mutable defaults. However, the list could be defined as a module-level constant to avoid recreating it. Consider: _DEFAULT_LLM_FALLBACK = ["claude", "openai", "ollama"] and then use default_factory=lambda: _DEFAULT_LLM_FALLBACK.copy()

    llm_fallback_chain: list[str] = Field(
        default_factory=lambda: ["claude", "openai", "ollama"]
    )

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coder-ishan]

Addressed the three valid findings from this review (commit 9162af0):

Fixed:

• TOCTOU race (crypto.py) — replaced write_bytes + chmod with os.open(O_CREAT|O_EXCL, 0o600) so the key file is created with restricted permissions atomically. Also removed the unused stat import.
• Empty API key silently stored (setup.py) — the Anthropic/OpenAI key prompts now loop until a non-empty value is entered, preventing a config save that will always fail at runtime.
• configure_logging never called (setup.py) — wired into _run_setup after ensure_dirs() so structlog handlers are active for the full wizard lifecycle.

Disputed (code already handles these correctly):

• Comments on setup.py:247, :208, :229, :309 — all four claim AttributeError from calling .strip() or .startswith() on a cancelled None prompt, but each call site is already guarded by if value: or if value and value.startswith(...). Replied inline on each thread.

[Copilot]

Pull request overview

Copilot reviewed 69 out of 72 changed files in this pull request and generated 9 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.