feat: mandatory engine lifecycle + text-file path guardrails

[Copilot]

The engine had no lifecycle contract — it would run automations in any state, with no enforcement boundary. Text-file path payloads had no safety validation, leaving pipelines open to path traversal and extension-based attacks.

Engine lifecycle (engine.py)

• Added start() / stop() methods to AutomationEngine; stop() triggers teardown() on all registered components
• trigger() / trigger_type() now raise EngineNotStartedError if the engine hasn't been started — lifecycle is mandatory
• is_running property exposes current state
• default_engine is auto-started to preserve backward compatibility

Text-file guardrail (guardrails.py, new)

• TextFileGuardrail — pipeline component that validates string file-path payloads before downstream steps execute
  • Rejects: path traversal (..), null bytes, absolute paths (configurable), disallowed extensions
  • Passes payload through unchanged on success
• DEFAULT_TEXT_EXTENSIONS — configurable frozenset of allowed extensions (.txt, .log, .csv, .md, .rst, …)

Exports

EngineNotStartedError, TextFileGuardrail, and DEFAULT_TEXT_EXTENSIONS added to automation.__all__.

Usage

engine = AutomationEngine()
engine.start()

engine.components.register("guard", TextFileGuardrail())
engine.register_fn("read", lambda inp: open(inp.payload).read())
engine.define(AutomationDefinition(
    name="safe_read",
    triggers=["file.read"],
    steps=["guard", "read"],
))

# Blocked — path traversal
engine.trigger_type("file.read", payload="../secrets.txt")  # FAILED

# Allowed
engine.trigger_type("file.read", payload="data.txt")  # SUCCESS

engine.stop()  # tears down all components

[qodo-code-review]

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

[Copilot]

Pull request overview

This PR introduces an explicit lifecycle contract for AutomationEngine (requiring start() before triggering runs, and adding stop() teardown semantics) and adds a new TextFileGuardrail component to validate string file-path payloads against traversal/absolute-path/null-byte/extension rules. It also updates package exports and expands regression tests to cover the new lifecycle and guardrail behaviors.

Changes:

• Added mandatory engine lifecycle (start()/stop(), is_running, and EngineNotStartedError enforcement in trigger()/trigger_type()), with default_engine auto-started for backward compatibility.
• Added TextFileGuardrail + DEFAULT_TEXT_EXTENSIONS guardrail component for file-path payload validation.
• Added/updated tests and public exports for the new engine error and guardrail symbols.

Reviewed changes

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

File	Description
tests/test_automation_review_regressions.py	Adds regression coverage for lifecycle enforcement and TextFileGuardrail validation + pipeline behavior.
src/automation/guardrails.py	Introduces TextFileGuardrail and DEFAULT_TEXT_EXTENSIONS for safe text-file path payload validation.
src/automation/engine.py	Adds lifecycle management (start/stop), enforces “must be started” on triggers, and auto-starts default_engine.
src/automation/init.py	Exposes EngineNotStartedError, TextFileGuardrail, and DEFAULT_TEXT_EXTENSIONS via package exports.

---

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