XyPriss Internal & Plugin Workspace System

Overview

The XyPriss Workspace System provides a mechanism for developers and plugin contributors to define specialized system instances (like $plug) with restricted filesystem access and isolated logic execution. This is particularly useful for building plugins that need to manage their own workspace without interfering with the main project root.

Configuration

Specialized systems are configured in the xypriss.config.json file under the $internal key.

Example Configuration

{
    "__sys__": {
        "__name__": "My-App"
    },
    "$internal": {
        "$plug": {
            "__xfs__": {
                "path": "#$/.private"
            },
            "__meta__": {
                "path": "#$/.private/.meta"
            }
        }
    }
}

Configuration Parameters

Usage in Code

Once configured, the specialized system is automatically added to the global __sys__ object.

Accessing the Workspace FileSystem

You can access the specialized filesystem using the name defined in the config (e.g., $plug).

import { type XyPrissSys } from "xypriss";

export function myPlugin() {
    // Both properties point to the same specialized workspace
    const workspaceA = (__sys__ as XyPrissSys).$plug;
    const workspaceB = (__sys__ as XyPrissSys).$plg;

    // Using the short alias for file operations
    const files = workspaceB?.$lsDirs(".");
}

Distributed Configuration & Auto-Discovery

XyPriss supports a distributed configuration model, allowing plugins and internal modules to provide their own xypriss.config.json files. The system automatically scans for these files in standard project directories:

• Project Root
• /plugins/*
• /mods/*
• /simulations/*
• /shared/*

This enables plugin contributors to define their own workspaces and meta-logic without requiring manual configuration from the end-user.

Path Resolution Placeholders

The path resolver supports two main types of resolution:

• Project Root Resolution: Using #$ or $# will resolve the path relative to the Global Project Root (the highest directory containing a xypriss.config.json or package.json).
• Local Resolution: Any standard relative path (e.g., ./.private or workspace/data) will be resolved relative to the directory containing the specific configuration file being processed.

Format Flexibility

The resolver is whitespace-aware and robust against extra spaces around slashes or placeholders.

• "$ # / simulations" resolves correctly to the project's simulations folder.
• "./ .meta" (in a plugin folder) resolves correctly to that specific plugin's .meta directory.

Error Reporting

The system provides detailed error logs if a configuration cannot be parsed or if a defined __xfs__ or __meta__ path is unresolvable, facilitating easier debugging for plugin developers.

Meta Logic Execution

The system automatically scans defined __meta__ paths for +xypriss.meta.ts/js files.

• If the path is a file, it executes the exported run() function.
• If the path is a directory, it searches for +xypriss.meta.ts/js within that directory (and specialized subfolders like .meta).