@divizend/scratch-core 1.0.0

package/core/Env.ts

@@ -0,0 +1,186 @@
+/**
+ * Environment Variable Utility
+ *
+ * Provides a centralized way to access and validate environment variables
+ * with consistent error messages and validation logic.
+ *
+ * @module Env
+ */
+
+/**
+ * Gets an environment variable with optional validation
+ *
+ * @param name - The name of the environment variable
+ * @param options - Optional configuration
+ * @param options.required - If true, throws an error if the variable is not set (default: true)
+ * @param options.defaultValue - Default value if the variable is not set (only used if required is false)
+ * @param options.errorMessage - Custom error message if the variable is required but not set
+ * @returns The environment variable value
+ * @throws Error if the variable is required but not set
+ */
+export function env(
+  name: string,
+  options?: {
+    required?: boolean;
+    defaultValue?: string;
+    errorMessage?: string;
+  }
+): string {
+  const value = process.env[name];
+  const required = options?.required !== false; // Default to true
+
+  if (!value) {
+    if (required) {
+      const errorMessage =
+        options?.errorMessage ||
+        `${name} environment variable is required but not set`;
+      throw new Error(errorMessage);
+    }
+    return options?.defaultValue || "";
+  }
+
+  return value;
+}
+
+/**
+ * Gets a value from a parameter or falls back to an environment variable
+ * Throws an error if neither is provided
+ *
+ * @param param - The parameter value (can be undefined)
+ * @param envVarName - The name of the environment variable to use as fallback
+ * @param errorMessage - Error message to throw if neither param nor env var is set
+ * @returns The parameter value or the environment variable value
+ * @throws Error if both param and env var are not set
+ *
+ * @example
+ * const apiKey = envOr(providedKey, "API_KEY", "API key is required");
+ */
+export function envOr(
+  param: string | undefined,
+  envVarName: string,
+  errorMessage: string
+): string {
+  if (param) {
+    return param;
+  }
+  const envValue = process.env[envVarName];
+  if (!envValue) {
+    throw new Error(errorMessage);
+  }
+  return envValue;
+}
+
+/**
+ * Gets a value from a parameter or falls back to an environment variable with a default
+ * Returns the default if neither is provided
+ *
+ * @param param - The parameter value (can be undefined)
+ * @param envVarName - The name of the environment variable to use as fallback
+ * @param defaultValue - Default value if neither param nor env var is set
+ * @returns The parameter value, environment variable value, or default value
+ *
+ * @example
+ * const port = envOrDefault(providedPort, "PORT", "3000");
+ */
+export function envOrDefault(
+  param: string | undefined,
+  envVarName: string,
+  defaultValue: string
+): string {
+  if (param) {
+    return param;
+  }
+  return process.env[envVarName] || defaultValue;
+}
+
+/**
+ * Parses environment variables grouped by a common prefix pattern
+ *
+ * Scans all environment variables and groups them by identifier extracted from the prefix.
+ * Useful for parsing variables like GCP_CLIENT_EMAIL_ORG1, GCP_PRIVATE_KEY_ORG1, etc.
+ *
+ * @param prefixes - Array of prefix patterns to match (e.g., ["GCP_CLIENT_EMAIL_", "GCP_PRIVATE_KEY_"])
+ * @param options - Configuration options
+ * @param options.propertyMap - Maps each prefix to a property name in the result object
+ * @param options.identifierExtractor - Function to extract identifier from env var name (default: splits by "_" and takes 4th segment, lowercased)
+ * @param options.required - If true, throws error if no matching env vars found (default: true)
+ * @param options.errorMessage - Custom error message if no env vars found
+ * @returns Object grouped by identifier, each containing properties mapped from prefixes
+ * @throws Error if required is true and no matching env vars are found
+ *
+ * @example
+ * // For env vars: GCP_CLIENT_EMAIL_ORG1=..., GCP_PRIVATE_KEY_ORG1=..., GCP_ADMIN_USER_ORG1=...
+ * const creds = parseEnvGroup(
+ *   ["GCP_CLIENT_EMAIL_", "GCP_PRIVATE_KEY_", "GCP_ADMIN_USER_"],
+ *   {
+ *     propertyMap: {
+ *       "GCP_CLIENT_EMAIL_": "clientEmail",
+ *       "GCP_PRIVATE_KEY_": "privateKey",
+ *       "GCP_ADMIN_USER_": "adminUser",
+ *     }
+ *   }
+ * );
+ * // Returns: { org1: { clientEmail: "...", privateKey: "...", adminUser: "..." } }
+ */
+export function parseEnvGroup<T extends Record<string, string>>(
+  prefixes: string[],
+  options: {
+    propertyMap: { [prefix: string]: keyof T };
+    identifierExtractor?: (key: string, prefix: string) => string;
+    required?: boolean;
+    errorMessage?: string;
+  }
+): { [identifier: string]: Partial<T> } {
+  const result: { [identifier: string]: Partial<T> } = {};
+  const identifierExtractor =
+    options.identifierExtractor ||
+    ((key: string, prefix: string) => {
+      // Default: split by "_" and take the part after the prefix
+      // For "GCP_CLIENT_EMAIL_ORG1", prefix is "GCP_CLIENT_EMAIL_", identifier is "org1"
+      const parts = key.split("_");
+      // Find which prefix matched and get the identifier part
+      for (const p of prefixes) {
+        if (key.startsWith(p)) {
+          // For "GCP_CLIENT_EMAIL_ORG1", split gives ["GCP", "CLIENT", "EMAIL", "ORG1"]
+          // We want the part after the prefix, so we need to count underscores in prefix
+          const prefixParts = p.split("_").filter((x) => x);
+          const identifier = parts.slice(prefixParts.length).join("_");
+          return identifier.toLowerCase();
+        }
+      }
+      return "";
+    });
+
+  // Scan all environment variables
+  for (const key of Object.keys(process.env)) {
+    // Find matching prefix
+    for (const prefix of prefixes) {
+      if (key.startsWith(prefix)) {
+        const identifier = identifierExtractor(key, prefix);
+        if (!identifier) continue;
+
+        if (!result[identifier]) {
+          result[identifier] = {};
+        }
+
+        const propertyName = options.propertyMap[prefix];
+        if (propertyName) {
+          (result[identifier] as any)[propertyName] = process.env[key];
+        }
+        break; // Only match first prefix
+      }
+    }
+  }
+
+  // Validate that we found at least one group
+  if (Object.keys(result).length === 0 && options.required !== false) {
+    const errorMessage =
+      options.errorMessage ||
+      `No environment variables found matching prefixes: ${prefixes.join(
+        ", "
+      )}`;
+    throw new Error(errorMessage);
+  }
+
+  return result;
+}

package/core/Fragment.ts

@@ -0,0 +1,43 @@
+/**
+ * Fragment - Content Abstraction Interface
+ *
+ * The Fragment interface represents the fundamental abstraction for all content
+ * types in the AI Executive system. It provides a unified way to handle
+ * different types of content (emails, documents, attachments, etc.) through
+ * a common interface.
+ *
+ * Fragments support multiple serving modes and can be processed, analyzed,
+ * and transformed while maintaining their original structure and metadata.
+ *
+ * @interface Fragment
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { FragmentServingMode } from "./FragmentServingMode";
+
+export interface Fragment {
+  /**
+   * Unique identifier for this fragment
+   *
+   * The URI provides a standardized way to reference and locate
+   * the fragment within the system, regardless of its content type.
+   */
+  readonly uri: string;
+
+  /**
+   * Serves the fragment content in the specified format
+   *
+   * This method handles the transformation and delivery of fragment content
+   * based on the requested serving mode. It ensures proper content type
+   * headers and data formatting for different use cases.
+   *
+   * @param format - The desired serving mode (original, markdown, JSON, etc.)
+   * @returns Promise containing headers and data for the served content
+   * @throws Error if the serving mode is not supported or content processing fails
+   */
+  serve(format: FragmentServingMode): Promise<{
+    headers: { name: string; value: string }[];
+    data: Buffer;
+  }>;
+}

package/core/FragmentServingMode.ts

@@ -0,0 +1,37 @@
+/**
+ * Fragment Serving Modes
+ *
+ * Defines the different ways in which fragment content can be served.
+ * Each mode represents a different format or representation of the
+ * original content, optimized for different use cases.
+ *
+ * @enum FragmentServingMode
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+export enum FragmentServingMode {
+  /**
+   * Original content format as stored in the system
+   *
+   * Serves the fragment in its native format with original
+   * encoding, headers, and structure preserved.
+   */
+  ORIGINAL = "original",
+
+  /**
+   * JSON metadata and content representation
+   *
+   * Provides structured access to fragment metadata, content,
+   * and relationships in a machine-readable format.
+   */
+  JSON = "json",
+
+  /**
+   * Markdown conversion of the original content
+   *
+   * Converts HTML or plain text content to Markdown format
+   * for easier reading and processing.
+   */
+  MARKDOWN = "markdown",
+}

package/core/JsonSchemaValidator.ts

@@ -0,0 +1,173 @@
+/**
+ * JSON Schema Validator - Schema Validation Utilities
+ *
+ * Provides JSON schema validation functionality for the Universe system.
+ * Uses a default implementation that can be extended or replaced.
+ *
+ * @module JsonSchemaValidator
+ * @version 1.0.0
+ */
+
+export interface JsonSchema {
+  type: "object";
+  properties?: {
+    [key: string]: {
+      type: "string" | "number" | "boolean" | "array" | "object";
+      default?: any;
+      description?: string;
+      enum?: any[];
+      items?: JsonSchema | { type: string };
+      required?: boolean;
+      [key: string]: any; // Allow additional JSON schema properties
+    };
+  };
+  required?: string[];
+  additionalProperties?: boolean;
+  [key: string]: any; // Allow additional JSON schema properties
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  data?: any; // Validated and coerced data
+}
+
+/**
+ * Abstract JSON Schema Validator
+ * Provides a default implementation that can be extended
+ */
+export class JsonSchemaValidator {
+  /**
+   * Validates data against a JSON schema
+   * Default implementation performs basic validation
+   *
+   * @param schema - JSON schema to validate against
+   * @param data - Data to validate
+   * @returns ValidationResult with validation status and errors
+   */
+  validate(schema: JsonSchema, data: any): ValidationResult {
+    const errors: string[] = [];
+    const validated: any = {};
+
+    if (!schema || schema.type !== "object") {
+      return {
+        valid: false,
+        errors: ["Schema must be an object type"],
+      };
+    }
+
+    // Check required properties
+    if (schema.required) {
+      for (const prop of schema.required) {
+        if (
+          !(prop in data) ||
+          data[prop] === undefined ||
+          data[prop] === null ||
+          data[prop] === ""
+        ) {
+          errors.push(`Missing required property: ${prop}`);
+        }
+      }
+    }
+
+    // Validate and coerce properties
+    if (schema.properties) {
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        const value = data[key];
+
+        // Apply default if value is missing
+        if (
+          (value === undefined || value === null || value === "") &&
+          propSchema.default !== undefined
+        ) {
+          validated[key] = propSchema.default;
+          continue;
+        }
+
+        // Skip validation if property is not required and not provided
+        const isRequired = schema.required?.includes(key) ?? false;
+        if (
+          !isRequired &&
+          (value === undefined || value === null || value === "")
+        ) {
+          continue;
+        }
+
+        // Type validation and coercion
+        if (value !== undefined && value !== null && value !== "") {
+          const coerced = this.coerceValue(value, propSchema);
+          if (coerced === null) {
+            errors.push(
+              `Property ${key} has invalid type. Expected ${propSchema.type}`
+            );
+          } else {
+            validated[key] = coerced;
+          }
+        } else if (isRequired) {
+          errors.push(`Missing required property: ${key}`);
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      data: validated,
+    };
+  }
+
+  /**
+   * Coerces a value to match the schema type
+   *
+   * @private
+   * @param value - Value to coerce
+   * @param propSchema - Property schema definition
+   * @returns Coerced value or null if coercion fails
+   */
+  private coerceValue(value: any, propSchema: any): any {
+    const expectedType = propSchema.type;
+
+    switch (expectedType) {
+      case "string":
+        return String(value);
+      case "number":
+        const num = Number(value);
+        return isNaN(num) ? null : num;
+      case "boolean":
+        if (typeof value === "string") {
+          return value === "true" || value === "1";
+        }
+        return Boolean(value);
+      case "array":
+        if (Array.isArray(value)) {
+          return value;
+        }
+        // Try to parse as JSON array
+        try {
+          const parsed = JSON.parse(value);
+          if (Array.isArray(parsed)) {
+            return parsed;
+          }
+        } catch {
+          // Not valid JSON
+        }
+        return null;
+      case "object":
+        if (typeof value === "object" && value !== null) {
+          return value;
+        }
+        // Try to parse as JSON object
+        try {
+          const parsed = JSON.parse(value);
+          if (typeof parsed === "object" && parsed !== null) {
+            return parsed;
+          }
+        } catch {
+          // Not valid JSON
+        }
+        return null;
+      default:
+        return value;
+    }
+  }
+}

package/core/ProjectRoot.ts

@@ -0,0 +1,76 @@
+/**
+ * ProjectRoot - Utility to reliably determine the project root directory
+ *
+ * This function walks up the directory tree from the current file's location
+ * to find the project root by looking for marker files (package.json, tsconfig.json).
+ * The result is cached for performance.
+ */
+
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stat } from "node:fs/promises";
+
+let cachedProjectRoot: string | null = null;
+
+/**
+ * Get the project root directory with 100% certainty
+ * Uses import.meta.url to get the current file location and walks up to find package.json
+ * @returns Absolute path to the project root
+ */
+export async function getProjectRoot(): Promise<string> {
+  // Return cached value if available
+  if (cachedProjectRoot) {
+    return cachedProjectRoot;
+  }
+
+  // Get the directory of the current file (this file)
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+
+  // Start from the current file's directory and walk up
+  let currentDir = resolve(__dirname);
+
+  // Marker files that indicate project root
+  const markers = ["package.json", "tsconfig.json"];
+
+  // Walk up the directory tree
+  while (currentDir !== dirname(currentDir)) {
+    // Check if any marker file exists in current directory
+    for (const marker of markers) {
+      try {
+        const markerPath = join(currentDir, marker);
+        await stat(markerPath);
+        // Found a marker file - this is the project root
+        cachedProjectRoot = currentDir;
+        return cachedProjectRoot;
+      } catch {
+        // Marker file doesn't exist, continue
+      }
+    }
+
+    // Move up one directory
+    currentDir = dirname(currentDir);
+  }
+
+  // Fallback: if we reach the filesystem root without finding a marker,
+  // use the directory containing this utility file and walk up to src/../
+  // This is a last resort fallback
+  const fallbackRoot = resolve(__dirname, "..", "..");
+  cachedProjectRoot = fallbackRoot;
+  return cachedProjectRoot;
+}
+
+/**
+ * Synchronous version - uses cached value or throws if not yet cached
+ * Call getProjectRoot() first to ensure cache is populated
+ * @returns Absolute path to the project root
+ * @throws Error if project root hasn't been determined yet
+ */
+export function getProjectRootSync(): string {
+  if (!cachedProjectRoot) {
+    throw new Error(
+      "Project root not yet determined. Call getProjectRoot() first."
+    );
+  }
+  return cachedProjectRoot;
+}

package/core/Scratch.ts

@@ -0,0 +1,44 @@
+/**
+ * Scratch - Type definitions for Scratch endpoint system
+ */
+
+import { Universe, UniverseModule } from "./Universe";
+
+export interface ScratchBlock {
+  opcode: string;
+  blockType: "command" | "reporter" | "boolean" | "hat";
+  text: string;
+  schema?: {
+    [key: string]: {
+      type: "string" | "number" | "boolean" | "array" | "object" | "json";
+      default?: any;
+      description?: string;
+      schema?: {
+        // Property-level JSON schema (not full JsonSchema)
+        type: "string" | "number" | "boolean" | "array" | "object";
+        default?: any;
+        items?: any;
+        properties?: any;
+        [key: string]: any;
+      }; // Required when type is "json"
+      [key: string]: any; // Allow additional JSON schema properties
+    };
+  };
+}
+
+export interface ScratchContext {
+  userEmail?: string;
+  inputs?: any; // Validated request body/query params (set after validation)
+  universe?: Universe | null; // Universe instance (set by context middleware)
+  authHeader?: string; // Authorization header for nested endpoint calls
+  result?: any; // Result from nested endpoint calls
+  requestHost?: string; // Request host header (e.g., "localhost:3000" or "scratch.divizend.ai")
+}
+
+export interface ScratchEndpointDefinition {
+  block: (context: ScratchContext) => Promise<ScratchBlock>;
+  handler: (context: ScratchContext) => Promise<any>;
+  noAuth?: boolean;
+  /** Array of required Universe modules that must be initialized before handler execution */
+  requiredModules?: UniverseModule[];
+}