Skip to main content

Script Sources and Script Structure

Understanding how Paracore finds and organizes your automation tools is the first step to a clean workflow.

1. What is a Script Source?​

A Script Source is the primary organizational system for your Paracore tools. It is a mandatory container folder that groups related automation projects into a structure the engine can efficiently scan and manage.

Unlike the REPL, which allows you to run independent code snippets on the fly, the Script Gallery relies on these sources to provide features like Magic Hydration, Visual Query Building, and professional IDE scaffolding. You cannot load a standalone script into the gallery; it must be part of a valid Script Source.

The engine identifies a source by looking for a hidden .paracore marker file, which acts as a "Signpost" telling Paracore: "Start scanning for scripts from this point."

Rules for Initialization​

  • Empty Folders Only: You can only initialize an empty folder as a new script source.
  • The Signpost: Initializing creates the .paracore file and prepares the folder for your projects.

2. Containers vs. Sources (The Scanning Logic)​

Paracore uses a smart scanning loop to load your tools efficiently:

  • The Container: A standard folder (like a project folder or a discipline root) that is not a source itself (it has no .paracore file).
  • Loading a Folder: When you load a folder into Paracore, it checks for a .paracore file:
    • If NOT found: It treats the folder as a Container. It scans the immediate children. If any child folder is a Script Source (has a .paracore file), it loads it into the sidebar. Use this to load many sources at once (e.g., loading an ExampleProject folder that contains both Structural and Architectural script sources).
    • If FOUND: It loads the folder as a Script Source and stops. It will not scan deeper for other sources.
No Nesting

Never put a script source inside another script source. The outer source will mask the inner ones, making them invisible to Paracore.

3. The "C# Project" Hierarchy​

When you create a new script or sentinel, Paracore scaffolds a professional directory structure:

ScriptSource / ProjectName / Scripts / ProjectName.cs

Why this structure?​

  1. Encapsulation: Your executable code lives exclusively in the Scripts/ subfolder.
  2. In-Place Scaffolding: Clicking "Edit Script" generates IDE files (.csproj, .sln, etc.) in the ProjectName/ root.
  3. No Contamination: By keeping your code in the Scripts/ folder, the helper files created by VS Code never interfere with your pure execution scripts.

4. Multi-File Support (Selective Compilation)​

Paracore supports complex tools spread across multiple files without slowing down execution:

  • Entry Script Discovery: The engine identifies your "Entry Script" (the top-level logic).
  • Smart Combination: The engine does not combine every .cs file in the folder automatically.
  • Reference Scanning: It scans your entry script to see which other files in the Scripts/ folder are actually referenced (classes, methods, or helpers).
  • Selective Compilation: Only the referenced files are combined. This keeps your execution context efficient and focused.

Next Step: Explore the 01 - Step-by-Step Exercise to practice managing your script sources.