Run Preview & Script Execution
Relevant source files
The following files were used as context for generating this wiki page:
The Run Preview and Script Execution system provides a specialized interface for executing commands, previewing results, and managing automated tasks such as Project Wiki generation. This system bridges the gap between the static codebase and dynamic execution by leveraging terminal orchestration and specialized UI panels to display output in real-time.
Within the ATMOS architecture, this module is primary responsible for handling long-running processes—specifically documentation generation and incremental updates—through a controlled command execution pipeline. It ensures that users can trigger complex scripts (like those used by Code Agents) while maintaining visibility into the execution status.
Sources: specs/tech/project-wiki.md:1-20, apps/web/src/components/run-preview/RunPreviewPanel.tsx
System Architecture & Component Hierarchy
The execution system is structured around a centralized panel that manages different execution states. It utilizes a RunPreviewPanel as the main container, which conditionally renders either a setup interface, a script execution view, or a preview of the resulting artifacts.
Component Breakdown
| Component | Responsibility |
|---|---|
RunPreviewPanel | Orchestrates the high-level state (Setup vs. Active Execution). |
RunScript | Handles the selection of Code Agents and the dispatching of shell commands. |
Preview | Renders the output or artifacts generated by a successful execution. |
TerminalGrid | Provides the underlying terminal emulation for script I/O. |
Sources: specs/tech/project-wiki.md:30-50, apps/web/src/components/run-preview/RunPreviewPanel.tsx
Execution Flow Architecture
The following diagram illustrates how a user request for script execution (specifically for Wiki generation) flows from the UI to the backend terminal engine.
Terminal Orchestration & Script Dispatching
Script execution is managed through a TerminalGridHandle which allows the application to programmatically create and control terminal tabs. This is critical for non-blocking execution where the user needs to see the progress of a command without freezing the main application thread.
Command Safety and Sanitization
To prevent arbitrary code execution, the system uses a controlled preset map for agent commands. All interpolated values, such as paths or user-provided prompts, are processed through a shellQuote utility to ensure they are safe for the target shell environment.
const AGENT_COMMANDS = {
claude: (prompt: string) => `claude ${shellQuote(prompt)}`,
codex: (prompt: string) => `codex ${shellQuote(prompt)}`,
aider: (prompt: string) => `aider --message ${shellQuote(prompt)}`,
} as const;
Sources: specs/tech/project-wiki.md:100-115
Terminal Control Interface
The interface for terminal interaction includes the following core capabilities:
- addTerminal: Creates a new terminal tab with an optional title.
- sendToTerminal: Dispatches raw input strings to a specific terminal pane.
- createAndRunTerminal: A composite action that initializes a fresh session and executes a command upon the session becoming ready.
Sources: specs/tech/project-wiki.md:120-130
Project Wiki Generation & Update Lifecycle
A primary use case for the execution system is the Project Wiki lifecycle. This involves two distinct execution patterns: full generation and incremental updates based on Git commit tracking.
Sequence of Wiki Generation
Incremental Update Logic
When a wiki already exists, the system compares the recorded commit_hash in the metadata with the current Git HEAD. If they differ, the system triggers the project-wiki-update skill, which executes a hybrid change-detection strategy:
- Phase 1: Identifies pages whose direct source files have changed via
git diff. - Phase 2: Uses AI reasoning to determine if new files require new documentation pages.
- Phase 3: Performs cross-cutting impact checks for core abstractions.
Sources: specs/tech/wiki_incremental_update.md:100-150, skills/project-wiki-update/SKILL.md:20-40
Metadata and Validation Scripts
The execution of documentation scripts results in several auxiliary artifacts used for validation. The system relies on zero-dependency scripts to ensure the integrity of the generated output.
Validation Pipeline
After a script completes execution, the following validation scripts are typically invoked within the terminal context:
| Script | Purpose |
|---|---|
validate_catalog.py | Validates the JSON structure of the navigation catalog. |
validate_frontmatter.py | Ensures all generated Markdown files have valid YAML frontmatter. |
validate_content.py | Checks word counts, Mermaid diagram presence, and section depth. |
Sources: skills/project-wiki/SKILL.md:300-320, skills/project-wiki-update/SKILL.md:110-120
Summary
The Run Preview & Script Execution system provides a robust framework for managing asynchronous tasks within ATMOS. By combining terminal orchestration with specialized UI components like RunScript and Preview, it enables complex workflows such as AI-driven documentation generation. The integration with Git for incremental updates and the use of controlled command presets ensures that the system is both technically efficient and secure for developer use.
Sources: specs/tech/project-wiki.md:220-230, DOCUMENTATION.md:50-70