YSFOML (Yasir Sultan File Operations Markup Language) Specification and Documentation, Version 1.0.6

3.17 action:treeFilesJSON ↑ Top

• Purpose: Generates a machine-readable JSON representation of the full directory and file structure starting from a specified folder. This action is primarily intended for AI models to programmatically understand the complete project structure, including files.
• Parameters:
  • foldername: (Optional, String) The folder from which to start the tree generation, relative to the base folder. If omitted, the base folder itself is used.
• Security Level: low
• Content: Not used.
• Behavior:
  • Outputs a JSON object representing the full file and folder tree to the "Operation Results" panel.
  • Each item (folder or file) is represented with its name, type ("directory" or "file"), and relative path. Folders also include a list of their contents.
• Example:
  YSFOML

  <YSFOML>
  action:treeFilesJSON;
  foldername:
  </YSFOML>

4. YSFOML future aspects ↑ Top

Looking to the future, a significant advancement planned for the YSFOML ecosystem involves the integration of the Multi-Client Protocol (MCP) directly within the YSFOML parser application. This strategic integration will largely eliminate the current need for manual copy-pasting of YSFOML code into the parser, although this option will remain available for flexibility. Instead, developers will be able to receive and review YSFOML code directly within a rich GUI environment, facilitating a more seamless and efficient workflow where their primary role shifts to critical review and approval.

It is important to clarify that while the MCP protocol and YSFOML are distinct entities--YSFOML defining file operations and MCP facilitating communication and interaction--their integration is designed to create a profoundly secure and exceptionally user-friendly development workspace. This synergy will combine YSFOML's precise control over file operations with MCP's robust communication capabilities, resulting in an environment where AI-driven file management is both powerful and inherently safe.

Further enhancing YSFOML's utility and flexibility, future iterations are planned to incorporate the crucial concepts of variables and conditional logic. These additions will enable more dynamic and intelligent file operation sequences, allowing YSFOML to adapt to varying contexts and execute operations based on specific criteria.

To address the critical need for running scripts and compiling code in a strict secured way, YSFOML will introduce new actions and security protocols designed to integrate these powerful capabilities without compromising the system's integrity. This will involve:

• Dedicated Actions for Execution and Compilation: New YSFOML actions, such as executeScript and compileCode, will be introduced. These actions will be classified under the extremelyHigh security level, mandating explicit human review and approval via the rich GUI provided by the MCP integration. Parameters for these actions will include the script/source file path, interpreter/compiler executable, arguments, and options for capturing output (stdout/stderr).
• Enhanced Human-in-the-Loop Review: The MCP-integrated GUI will provide a highly detailed and prominent display for any YSFOML block containing executeScript or compileCode actions. This display will highlight the exact command to be executed, its parameters, and any potential security implications, ensuring the human operator has all necessary information for a fully informed approval or rejection.
• Whitelisting and Sandboxing Mechanisms: To mitigate risks, the YSFOML parser will support configurable whitelisting of approved script interpreters (e.g., specific Python versions, specific shell paths) and compilers. For even greater security, future considerations include sandboxing capabilities, where scripts and compilation processes are executed within isolated environments with limited access to the file system and network, further containing any potential malicious activity.
• Output Capture and Analysis: The output (both standard output and error output) of executed scripts and compilation processes will be captured by the YSFOML parser and presented to the human reviewer within the GUI. This allows for immediate verification of the operation's success or failure, and crucially, enables the human to identify any unexpected behavior or errors before proceeding with subsequent YSFOML operations.
• Integration with Variables and Conditional Logic for Safety: The introduction of variables and conditional logic will be instrumental in building robust security checks around script execution and compilation. For instance, a YSFOML sequence could first use findFile or readFileAll to verify the content or digital signature of a script before executeScript is allowed to proceed, or compileCode could be conditional on the successful outcome of a prior security scan. This allows for highly sophisticated, self-regulating security protocols defined directly within YSFOML.
• Comprehensive Logging and Audit Trails: Every instance of script execution or code compilation, along with the human approval status and captured output, will be meticulously logged. This provides an immutable audit trail, critical for security compliance, debugging, and post-incident analysis.

By meticulously designing these new capabilities with security as the paramount concern, YSFOML will empower AI models to automate complex development tasks, including building and testing, while maintaining the essential human oversight that guarantees safety and control.

5. YSFOML and Artificial Intelligence ↑ Top

YSFOML is designed with Artificial Intelligence (AI) interaction in mind, serving as a structured and human-readable language for AI models to specify file system operations. This allows AI to communicate desired file manipulations in a clear, auditable format.

A core principle of YSFOML's design, especially when used with AI, is the "human-in-the-loop" security model. AI models can generate YSFOML instructions based on user requests (e.g., "Please create a Python script and save it as 'hello.py'"). However, the execution of these instructions is intentionally manual: the AI provides the YSFOML text, and the user must then copy and paste this text into the YSFOML Parser application. This manual step acts as a critical security layer, preventing direct, unsupervised AI access to your local file system.

By generating YSFOML instructions, AI can help users understand, create, and edit code, manage project files, or perform other file-related tasks. This approach empowers users with AI assistance while maintaining ultimate control and oversight over their file system.

It is crucial to understand that the execution of any YSFOML instructions, whether generated by an AI or written manually, is entirely at the user's own risk. Users are strongly advised to always review the generated YSFOML content carefully before processing it with the YSFOML Parser, especially for actions with medium or high security levels that can modify or delete files.

5.1 AI Workflow for Project Understanding and Modification ↑ Top

For an AI to effectively assist with file system operations, especially in complex projects, it's essential for the AI to first gain an understanding of the project's structure and existing content. The action:treeFoldersJSON and action:treeFilesJSON actions are specifically designed for this purpose.

• Initial Project Overview: An AI should begin by requesting a JSON representation of the project's folder or file tree using action:treeFoldersJSON (for a high-level folder structure) or action:treeFilesJSON (for a detailed view including all files). This provides the AI with a structured, machine-readable map of the project.
• Content Analysis: Once the AI has the project structure, it can then identify relevant files (e.g., source code, configuration files, data files). For specific files, the AI can then use action:readFileAll or action:readFileLines to read their content and understand their purpose or identify areas for modification.
• Generating Modification Instructions: With a clear understanding of the project structure and file contents, the AI can then generate precise YSFOML instructions for operations like action:create, action:append, action:replaceInFile, or action:insertAt to make the desired changes. This iterative process of "read-then-write" ensures that AI-generated modifications are contextually aware and accurate.

This structured approach allows the AI to provide more intelligent and targeted assistance, while the human-in-the-loop model ensures safety and oversight.

5.2 Key AI Interaction Capabilities ↑ Top

YSFOML offers several powerful and secure ways for Artificial Intelligence (AI) to interact with file systems:

• AI-Driven File Generation and Creation: AI can generate YSFOML instructions to create new files, such as source code, configuration files, or documentation, based on user requirements.
• AI-Assisted File Modification: AI can generate YSFOML to perform operations that modify existing files, including appending content, inserting content at specific locations, or replacing text within files. This allows AI to "edit" files in a structured and auditable manner.
• AI-Powered Project Structure Understanding: YSFOML provides specific actions that allow AI models to programmatically obtain a machine-readable JSON representation of a project's directory and file structure. This is crucial for AI to gain context and understand the layout of a project before suggesting or performing operations.
• AI-Guided File System Querying and Analysis: AI can use YSFOML's read-only operations to analyze file content and structure. This includes searching for specific files, finding strings within files, or reading entire file contents or specific lines. This enables AI to perform detailed analysis and retrieve necessary information from the file system.
• Human-in-the-Loop Automation and Security: A core principle highlighted is the "human-in-the-loop" security model. While AI can generate complex YSFOML instructions, the execution is intentionally manual. The user reviews the AI-generated YSFOML before processing it with the YSFOML Parser. This ensures that users maintain ultimate control and oversight over their local file system, especially for operations with medium or high security levels that can modify or delete files.

In summary, YSFOML serves as a structured, human-readable interface that allows AI to understand, query, and propose modifications to file systems, while ensuring a critical human review step for security and control.

5.3 Examples of YSFOML Instructions for AI Usage Scenarios ↑ Top

<YSFOML>
action:create;
filename:hello_world.py
</YSFOML>
print("Hello, YSFOML World!")

<YSFOML>
action:append;
filename:application.log
</YSFOML>
[2025-06-28 15:30:00] INFO: User 'admin' logged in successfully.

<YSFOML>
action:replaceInFile;
filename:config.ini;
searchString:DB_PASSWORD=YOUR_PASSWORD;
newString:DB_PASSWORD=secure_ai_pass123;
</YSFOML>

<YSFOML>
action:insertAt;
filename:my_utility.py;
lineNum:1;
colNum:1
</YSFOML>
def calculate_sum(a, b):
    return a + b

<YSFOML>
action:treeFoldersJSON;
foldername:src/components;
</YSFOML>

<YSFOML>
action:treeFilesJSON;
foldername:public/assets;
</YSFOML>

<YSFOML>
action:readFileAll;
filename:src/main.js
</YSFOML>

<YSFOML>
action:findInFile;
filename:database/schema.sql;
searchString:user_id;
</YSFOML>

<YSFOML>
action:findFile;
filename:config.json;
foldername:;
</YSFOML>

<YSFOML>
action:deleteFolder;
foldername:old_backup_data;
</YSFOML>

6. AI Chat Examples ↑ Top

<YSFOML>
action:create;
filename:index.html
</YSFOML>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dark/Light Mode Toggle</title>
    <link rel="stylesheet" href="style.css">
</head>
<body class="light-mode">
    <div class="container">
        <h1>Welcome to My Website</h1>
        <p>This is a simple example demonstrating dark and light mode toggling.</p>
        <button id="modeToggle">Toggle Mode</button>
    </div>
    <script src="script.js"></script>
</body>
</html>
<YSFOML>
action:create;
filename:style.css
</YSFOML>
body {
    font-family: Arial, sans-serif;
    margin: 0;
    display: flex;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
    transition: background-color 0.3s, color 0.3s;
}

/* Light Mode Styles */
body.light-mode {
    background-color: #f0f0f0;
    color: #333;
}

/* Dark Mode Styles */
body.dark-mode {
    background-color: #333;
    color: #f0f0f0;
}

.container {
    text-align: center;
    padding: 20px;
    border-radius: 8px;
    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
    background-color: #fff; /* White background for container in light mode */
    transition: background-color 0.3s, box-shadow 0.3s;
}

body.dark-mode .container {
    background-color: #555; /* Darker background for container in dark mode */
    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.5);
}

h1 {
    margin-bottom: 15px;
}

p {
    margin-bottom: 25px;
}

button {
    padding: 10px 20px;
    font-size: 16px;
    border: none;
    border-radius: 5px;
    cursor: pointer;
    transition: background-color 0.3s, color 0.3s;
}

body.light-mode button {
    background-color: #007bff;
    color: white;
}

body.light-mode button:hover {
    background-color: #0056b3;
}

body.dark-mode button {
    background-color: #28a745;
    color: white;
}

body.dark-mode button:hover {
    background-color: #218838;
}
<YSFOML>
action:create;
filename:script.js
</YSFOML>
document.addEventListener('DOMContentLoaded', () => {
    const modeToggle = document.getElementById('modeToggle');
    const body = document.body;

    // Check for saved theme preference
    const savedTheme = localStorage.getItem('theme');
    if (savedTheme) {
        body.className = savedTheme;
    } else {
        // Default to light mode if no preference is saved
        body.className = 'light-mode';
    }

    modeToggle.addEventListener('click', () => {
        if (body.classList.contains('light-mode')) {
            body.classList.remove('light-mode');
            body.classList.add('dark-mode');
            localStorage.setItem('theme', 'dark-mode');
        } else {
            body.classList.remove('dark-mode');
            body.classList.add('light-mode');
            localStorage.setItem('theme', 'light-mode');
        }
    });
});

<YSFOML>
action:treeFiles;
foldername:
</YSFOML>

--- File Tree for '' ---
website2/
    index.html
    script.js
    style.css
    logs/
        input_2025-06-28_11-51-39.txt
        input_2025-06-28_18-12-21.txt
        processing_log_2025-06-28_11-51-39.txt
        results_log_2025-06-28_11-51-39.txt
--- End File Tree ---

<YSFOML>
action:treeFilesJSON;
foldername:app/Models;
</YSFOML>

<YSFOML>
action:treeFilesJSON;
foldername:app/Http/Controllers;
</YSFOML>

<YSFOML>
action:treeFilesJSON;
foldername:resources/views;
</YSFOML>

<YSFOML>
action:treeFilesJSON;
foldername:routes;
</YSFOML>

7. Using the YSFOML Parser Application ↑ Top

The provided Python script YSFOML_GUI acts as a parser and executor for YSFOML documents.

7.1 Requirements ↑ Top

• Python 3.x
• tkinter (usually included with Python)
• requests library (pip install requests)
• For action:json with jsonPath, a JSONPath library might be required (e.g., pip install jsonpath-ng).

7.2 Running the Application ↑ Top

1. Save the provided Python code as a .py file (e.g., ysfoml_parser.py).
2. Run it from your terminal: python ysfoml_parser.py

7.3 Application Interface ↑ Top

The GUI provides the following main components:

• YSFOML Input: A text area where you paste or type your YSFOML document.
• Project Folder: An entry field and a "Browse" button to select the base directory where all file operations will be performed. By default, it creates an YSFOML_output folder in the current working directory.
• Process YSFOML Button: Initiates the parsing and execution of the YSFOML content.
• Processing Logs: Displays detailed logs of each step, including warnings, errors, and success messages for file operations.
• Operation Results: Displays the output of query-based operations like treeFolders, findFile, readFileAll, etc.
• Security Level Dropdown: Allows the user to select a security level (low, medium, high, extremelyHigh) that will restrict which YSFOML actions can be executed.