@enactprotocol/shared 1.2.11 → 2.0.0

package/src/types.ts

@@ -1,189 +1,6 @@
-// src/types.ts - Type definitions for Enact CLI Core
-export interface EnactTool {
-	// REQUIRED FIELDS
-	name: string; // Tool identifier with hierarchical path
-	description: string; // Human-readable description
-	command: string; // Shell command to execute with version pins
+/**
+ * Type definitions for shared utilities
+ */
 
-	// RECOMMENDED FIELDS
-	from?: string; // Container image to run the command on (optional, defaults to system shell)
-	timeout?: string; // Go duration format: "30s", "5m", "1h" (default: "30s")
-	tags?: string[]; // Tags for search and categorization
-	license?: string; // SPDX License identifier (e.g., "MIT", "Apache-2.0")
-	outputSchema?: JSONSchemaDefinition; // Output structure as JSON Schema (strongly recommended)
-
-	// OPTIONAL FIELDS
-	enact?: string; // Protocol version (e.g., "1.0.0")
-	version?: string; // Tool definition version for tracking changes
-	namespace?: string; // Environment variable namespace (deprecated, use name hierarchy)
-
-	// Resource requirements
-	resources?: {
-		memory?: string; // System memory needed (e.g., "16Gi", "32Gi")
-		gpu?: string; // GPU memory needed (e.g., "24Gi", "48Gi")
-		disk?: string; // Disk space needed (e.g., "100Gi", "500Gi")
-	};
-
-	// Environment variables
-	env?: Record<
-		string,
-		{
-			description: string; // What this variable is for (required)
-			source: string; // Where to get this value (required)
-			required: boolean; // Whether this is required (required)
-			default?: string; // Default value if not set (optional)
-		}
-	>;
-
-	// Input/Output JSON Schemas
-	inputSchema?: JSONSchemaDefinition;
-
-	// Documentation and Testing
-	doc?: string; // Markdown documentation
-	authors?: Array<{
-		name: string; // Author name (required)
-		email?: string; // Author email (optional)
-		url?: string; // Author website (optional)
-	}>;
-
-	examples?: Array<{
-		input: Record<string, any>; // Input parameters
-		output?: any; // Expected output
-		description?: string; // Test description
-	}>;
-
-	// Behavior Annotations (MCP-aligned, all default to false)
-	annotations?: {
-		title?: string; // Human-readable display name
-		readOnlyHint?: boolean; // No environment modifications
-		destructiveHint?: boolean; // May make irreversible changes
-		idempotentHint?: boolean; // Multiple calls = single call
-		openWorldHint?: boolean; // Interacts with external systems
-	};
-
-	// Security
-	signature?: {
-		algorithm: string; // Hash algorithm: "sha256"
-		type: string; // Signature type: "ecdsa-p256"
-		signer: string; // Signer identifier
-		created: string; // ISO timestamp
-		value: string; // Base64 encoded signature
-		role?: string; // Optional description of the signer
-	};
-
-	// Multi-signature support (array format)
-	signatures?: {
-		signer: string; // Signer identifier (UUID or human-readable name)
-		algorithm: string; // Hash algorithm: "sha256"
-		type: string; // Signature type: "ecdsa-p256"
-		value: string; // Base64 encoded signature
-		created: string; // ISO timestamp
-		role?: string; // Optional description of the signer (e.g., "author", "reviewer", "approver")
-	}[];
-
-	// Extensions pattern (x-prefixed fields)
-	[key: string]: any; // Allow x- prefixed extension fields
-}
-
-// JSON Schema type definitions
-export interface JSONSchemaDefinition {
-	type?: string | string[]; // JSON Schema type(s)
-	description?: string; // Human-readable description
-	format?: string; // Format specifier (e.g., "email", "date-time")
-	default?: any; // Default value
-	enum?: any[]; // Enumeration of possible values
-	const?: any; // Constant value
-
-	// String validations
-	pattern?: string; // Regular expression pattern
-	minLength?: number; // Minimum string length
-	maxLength?: number; // Maximum string length
-
-	// Number validations
-	minimum?: number; // Minimum value
-	maximum?: number; // Maximum value
-	exclusiveMinimum?: number; // Exclusive minimum
-	exclusiveMaximum?: number; // Exclusive maximum
-	multipleOf?: number; // Multiple of
-
-	// Array validations
-	items?: JSONSchemaDefinition | JSONSchemaDefinition[]; // Items schema
-	minItems?: number; // Minimum items
-	maxItems?: number; // Maximum items
-	uniqueItems?: boolean; // Items must be unique
-
-	// Object validations
-	properties?: Record<string, JSONSchemaDefinition>; // Properties
-	required?: string[]; // Required properties
-	additionalProperties?: JSONSchemaDefinition | boolean; // Additional properties
-
-	// Combiners
-	allOf?: JSONSchemaDefinition[]; // All of these schemas
-	anyOf?: JSONSchemaDefinition[]; // Any of these schemas
-	oneOf?: JSONSchemaDefinition[]; // Exactly one of these schemas
-	not?: JSONSchemaDefinition; // Not this schema
-
-	// Other
-	definitions?: Record<string, JSONSchemaDefinition>; // Definitions
-	$ref?: string; // JSON Schema reference
-	$id?: string; // Schema ID
-	$schema?: string; // Schema version
-
-	// Custom extensions
-	[key: string]: any; // Additional properties
-}
-
-export interface ExecutionResult {
-	success: boolean;
-	output?: any; // Command output/result
-	error?: {
-		message: string;
-		code?: string;
-		details?: any;
-	};
-	metadata: {
-		executionId: string;
-		toolName: string; // Changed from toolId
-		version?: string;
-		executedAt: string;
-		environment: string;
-		timeout?: string;
-		command?: string; // The actual command that was executed
-	};
-}
-
-// Execution environment interface
-export interface ExecutionEnvironment {
-	vars: Record<string, any>; // Environment variables
-	resources?: {
-		memory?: string;
-		gpu?: string;
-		disk?: string;
-		timeout?: string;
-	};
-	namespace?: string; // Environment variable namespace
-	mount?: string; // Mount local directory to container (format: "localPath" or "localPath:containerPath")
-}
-
-// Updated execution provider interface
-export abstract class ExecutionProvider {
-	abstract setup(tool: EnactTool): Promise<boolean>;
-	abstract execute(
-		tool: EnactTool,
-		inputs: Record<string, any>,
-		environment: ExecutionEnvironment,
-	): Promise<ExecutionResult>;
-	abstract cleanup(): Promise<boolean>;
-	abstract resolveEnvironmentVariables(
-		envConfig: Record<string, any>,
-		namespace?: string,
-	): Promise<Record<string, any>>;
-
-	// New method for command execution
-	abstract executeCommand(
-		command: string,
-		inputs: Record<string, any>,
-		environment: ExecutionEnvironment,
-		timeout?: string,
-	): Promise<{ stdout: string; stderr: string; exitCode: number }>;
-}
+// Placeholder for Phase 3 implementation
+export type EnactManifest = Record<string, unknown>;

package/src/utils/fs.ts

@@ -0,0 +1,281 @@
+/**
+ * @enactprotocol/shared - File system helpers
+ *
+ * Provides utilities for common filesystem operations.
+ */
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * Ensure a directory exists, creating it if necessary
+ */
+export function ensureDir(dirPath: string): void {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Ensure the parent directory of a file exists
+ */
+export function ensureParentDir(filePath: string): void {
+  const parentDir = dirname(filePath);
+  ensureDir(parentDir);
+}
+
+/**
+ * Check if a path exists
+ */
+export function pathExists(path: string): boolean {
+  return existsSync(path);
+}
+
+/**
+ * Check if a path is a directory
+ */
+export function isDirectory(path: string): boolean {
+  try {
+    return existsSync(path) && statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a path is a file
+ */
+export function isFile(path: string): boolean {
+  try {
+    return existsSync(path) && statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read and parse a JSON file
+ * @throws Error if file doesn't exist or isn't valid JSON
+ */
+export function readJsonFile<T = unknown>(filePath: string): T {
+  const content = readFileSync(filePath, "utf-8");
+  return JSON.parse(content) as T;
+}
+
+/**
+ * Try to read and parse a JSON file
+ * @returns The parsed JSON or null if file doesn't exist or is invalid
+ */
+export function tryReadJsonFile<T = unknown>(filePath: string): T | null {
+  try {
+    return readJsonFile<T>(filePath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write data to a JSON file with formatting
+ */
+export function writeJsonFile(
+  filePath: string,
+  data: unknown,
+  options?: { indent?: number | undefined }
+): void {
+  const indent = options?.indent ?? 2;
+  ensureParentDir(filePath);
+  writeFileSync(filePath, `${JSON.stringify(data, null, indent)}\n`, "utf-8");
+}
+
+/**
+ * Read a text file
+ */
+export function readTextFile(filePath: string): string {
+  return readFileSync(filePath, "utf-8");
+}
+
+/**
+ * Try to read a text file
+ * @returns The file content or null if file doesn't exist
+ */
+export function tryReadTextFile(filePath: string): string | null {
+  try {
+    return readTextFile(filePath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write content to a text file
+ */
+export function writeTextFile(filePath: string, content: string): void {
+  ensureParentDir(filePath);
+  writeFileSync(filePath, content, "utf-8");
+}
+
+/**
+ * Copy a file
+ */
+export function copyFile(src: string, dest: string): void {
+  ensureParentDir(dest);
+  copyFileSync(src, dest);
+}
+
+/**
+ * Copy a directory recursively
+ */
+export function copyDir(src: string, dest: string): void {
+  ensureDir(dest);
+
+  const entries = readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      copyFile(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Remove a file or directory
+ */
+export function remove(path: string): void {
+  if (existsSync(path)) {
+    rmSync(path, { recursive: true, force: true });
+  }
+}
+
+/**
+ * List directory contents
+ */
+export function listDir(dirPath: string): string[] {
+  if (!existsSync(dirPath)) {
+    return [];
+  }
+  return readdirSync(dirPath);
+}
+
+/**
+ * List directory entries with types
+ */
+export function listDirEntries(dirPath: string): Array<{
+  name: string;
+  type: "file" | "directory" | "unknown";
+  path: string;
+}> {
+  if (!existsSync(dirPath)) {
+    return [];
+  }
+
+  const entries = readdirSync(dirPath, { withFileTypes: true });
+  return entries.map((entry) => ({
+    name: entry.name,
+    type: entry.isDirectory() ? "directory" : entry.isFile() ? "file" : "unknown",
+    path: join(dirPath, entry.name),
+  }));
+}
+
+/**
+ * Find files matching a pattern in a directory (non-recursive)
+ */
+export function findFiles(dirPath: string, pattern: RegExp | string): string[] {
+  const entries = listDir(dirPath);
+  const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
+
+  return entries
+    .filter((name) => regex.test(name) && isFile(join(dirPath, name)))
+    .map((name) => join(dirPath, name));
+}
+
+/**
+ * Find files recursively
+ */
+export function findFilesRecursive(dirPath: string, pattern?: RegExp | string): string[] {
+  const results: string[] = [];
+
+  if (!existsSync(dirPath)) {
+    return results;
+  }
+
+  const regex =
+    pattern !== undefined ? (typeof pattern === "string" ? new RegExp(pattern) : pattern) : null;
+
+  function walk(dir: string) {
+    const entries = readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        if (!regex || regex.test(entry.name)) {
+          results.push(fullPath);
+        }
+      }
+    }
+  }
+
+  walk(dirPath);
+  return results;
+}
+
+/**
+ * Get file stats
+ */
+export function getStats(path: string): {
+  size: number;
+  isFile: boolean;
+  isDirectory: boolean;
+  created: Date;
+  modified: Date;
+} | null {
+  try {
+    const stats = statSync(path);
+    return {
+      size: stats.size,
+      isFile: stats.isFile(),
+      isDirectory: stats.isDirectory(),
+      created: stats.birthtime,
+      modified: stats.mtime,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get file size in bytes
+ */
+export function getFileSize(filePath: string): number | null {
+  const stats = getStats(filePath);
+  return stats?.isFile ? stats.size : null;
+}
+
+/**
+ * Touch a file (create if not exists, update mtime if exists)
+ */
+export function touchFile(filePath: string): void {
+  ensureParentDir(filePath);
+  if (existsSync(filePath)) {
+    // Update access and modification time by rewriting the file
+    writeFileSync(filePath, readFileSync(filePath));
+  } else {
+    writeFileSync(filePath, "", "utf-8");
+  }
+}