@enactprotocol/shared 1.2.13 → 2.0.1

package/src/index.ts

@@ -1,39 +1,247 @@
-// Core exports
-export { EnactCore } from './core/EnactCore';
-export { DirectExecutionProvider } from './core/DirectExecutionProvider';
-export { DaggerExecutionProvider } from './core/DaggerExecutionProvider';
+/**
+ * @enactprotocol/shared
+ *
+ * Core business logic and utilities for Enact.
+ * Provides manifest parsing, configuration management, tool resolution,
+ * and execution engine interfaces.
+ */
 
-// Constants - now handled in config utils
+export const version = "0.1.0";
 
-// Types and utilities
-export type { EnactTool } from './types';
-export type { EnactToolDefinition } from './api/types';
-export { default as LocalToolResolver } from './LocalToolResolver';
-export { default } from './LocalToolResolver';
+// Constants
+export {
+  ENACT_BASE_URL,
+  ENACT_API_URL,
+  ENACT_WEB_URL,
+  ENACT_TOOL_TYPE,
+  ENACT_AUDIT_TYPE,
+  ENACT_BUILD_TYPE,
+  INTOTO_STATEMENT_TYPE,
+  SLSA_PROVENANCE_TYPE,
+} from "./constants";
 
-// Exec utilities
-export { default as logger } from './exec/logger';
-export * from './exec/validate';
+// Path utilities
+export {
+  getEnactHome,
+  getProjectEnactDir,
+  getToolsDir,
+  getCacheDir,
+  getConfigPath,
+  getGlobalEnvPath,
+  getProjectEnvPath,
+  type ToolScope,
+} from "./paths";
 
-// Utils
-export * from './utils/config';
-export * from './utils/env-loader';
-export { showHelp } from './utils/help';
-export { showVersion as utilsShowVersion } from './utils/version';
-export * from './utils/logger';
-export * from './utils/silent-monitor';
-export * from './utils/timeout';
+// Configuration manager
+export {
+  loadConfig,
+  saveConfig,
+  getConfigValue,
+  setConfigValue,
+  resetConfig,
+  configExists,
+  ensureGlobalSetup,
+  DEFAULT_CONFIG,
+  // Local trust management (new unified API)
+  getTrustedIdentities,
+  addTrustedIdentity,
+  removeTrustedIdentity,
+  isIdentityTrusted,
+  getMinimumAttestations,
+  getTrustPolicy,
+  emailToProviderIdentity,
+  // Legacy aliases (deprecated)
+  getTrustedAuditors,
+  addTrustedAuditor,
+  removeTrustedAuditor,
+  isAuditorTrusted,
+  type EnactConfig,
+  type TrustConfig,
+  type CacheConfig,
+  type ExecutionConfig,
+  type RegistryConfig,
+} from "./config";
 
+// Manifest types
+export type {
+  ToolManifest,
+  PackageManifest,
+  ParsedManifest,
+  EnvVariable,
+  EnvVariables,
+  Author,
+  ToolAnnotations,
+  ResourceRequirements,
+  ToolExample,
+  ValidationResult,
+  ValidationError,
+  ValidationWarning,
+  ToolLocation,
+  ToolResolution,
+  ManifestFileName,
+} from "./types/manifest";
 
-// Services
-export * from './services/McpCoreService';
+export { MANIFEST_FILES, PACKAGE_MANIFEST_FILE } from "./types/manifest";
 
-// Web
-export * from './web/env-manager-server';
+// Manifest parsing, validation, and loading
+export {
+  // Parser
+  ManifestParseError,
+  parseManifest,
+  parseManifestAuto,
+  parseYaml,
+  extractFrontmatter,
+  detectFormat,
+  type ManifestFormat,
+  // Validator
+  validateManifest,
+  validateManifestStrict,
+  isValidToolName,
+  isValidVersion,
+  isValidTimeout,
+  ToolManifestSchema,
+  // Loader
+  ManifestLoadError,
+  loadManifest,
+  loadManifestFromDir,
+  findManifestFile,
+  hasManifest,
+  tryLoadManifest,
+  tryLoadManifestFromDir,
+  type LoadedManifest,
+} from "./manifest";
 
-// API
-export * from './api/enact-api';
-export type { ApiResponse, ToolSearchQuery, ToolUsage, CLITokenCreate, OAuthTokenExchange } from './api/types';
+// Tool resolver
+export {
+  ToolResolveError,
+  resolveTool,
+  resolveToolAuto,
+  resolveToolFromPath,
+  tryResolveTool,
+  normalizeToolName,
+  toolNameToPath,
+  getToolPath,
+  getToolSearchPaths,
+  type ResolveOptions,
+} from "./resolver";
 
-// Lib
-export * from './lib/enact-direct';
+// Local tool registry (tools.json management)
+export {
+  loadToolsRegistry,
+  saveToolsRegistry,
+  addToolToRegistry,
+  removeToolFromRegistry,
+  isToolInstalled,
+  getInstalledVersion,
+  getToolCachePath,
+  listInstalledTools,
+  getInstalledToolInfo,
+  getToolsJsonPath,
+  type ToolsRegistry,
+  type RegistryScope,
+  type InstalledToolInfo,
+} from "./registry";
+
+// Logger utility
+export {
+  Logger,
+  createLogger,
+  configureLogger,
+  getLogger,
+  debug,
+  info,
+  warn,
+  error,
+  type LogLevel,
+  type LogEntry,
+  type LoggerOptions,
+} from "./utils/logger";
+
+// Version utilities
+export {
+  parseVersion,
+  isValidVersion as isValidSemver,
+  compareVersions,
+  parseRange,
+  satisfiesRange,
+  sortVersions,
+  getHighestVersion,
+  incrementVersion,
+  coerceVersion,
+  formatVersion,
+  type ParsedVersion,
+  type VersionRange,
+} from "./utils/version";
+
+// File system helpers
+export {
+  ensureDir,
+  ensureParentDir,
+  pathExists,
+  isDirectory,
+  isFile,
+  readJsonFile,
+  tryReadJsonFile,
+  writeJsonFile,
+  readTextFile,
+  tryReadTextFile,
+  writeTextFile,
+  copyFile,
+  copyDir,
+  remove,
+  listDir,
+  listDirEntries,
+  findFiles,
+  findFilesRecursive,
+  getStats,
+  getFileSize,
+  touchFile,
+} from "./utils/fs";
+
+// Execution engine (browser-safe utilities only)
+// NOTE: DaggerExecutionProvider moved to @enactprotocol/execution package
+export {
+  // Types
+  type ExecutionInput,
+  type FileInput,
+  type ExecutionOutput,
+  type ExecutionResult,
+  type ExecutionMetadata,
+  type ExecutionError,
+  type ExecutionErrorCode,
+  type ExecutionOptions,
+  type RetryConfig,
+  type ContainerRuntime,
+  type RuntimeDetection,
+  type RuntimeStatus,
+  type EngineHealth,
+  type EngineState,
+  type ExecutionProvider,
+  type ParsedCommand,
+  type CommandToken,
+  type InterpolationOptions,
+  type InputValidationResult,
+  type InputValidationError,
+  type DryRunResult,
+  // Constants
+  DEFAULT_RETRY_CONFIG,
+  // Runtime
+  detectRuntime,
+  clearRuntimeCache,
+  isRuntimeAvailable,
+  getAvailableRuntimes,
+  RuntimeStatusTracker,
+  createRuntimeTracker,
+  // Command
+  parseCommand,
+  interpolateCommand,
+  shellEscape,
+  parseCommandArgs,
+  prepareCommand,
+  getMissingParams,
+  // Validation
+  validateInputs,
+  applyDefaults,
+  getRequiredParams,
+  getParamInfo,
+} from "./execution";

package/src/manifest/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Manifest module exports
+ */
+
+// Parser
+export {
+  ManifestParseError,
+  parseManifest,
+  parseManifestAuto,
+  parseYaml,
+  extractFrontmatter,
+  detectFormat,
+  type ManifestFormat,
+} from "./parser";
+
+// Validator
+export {
+  validateManifest,
+  validateManifestStrict,
+  isValidToolName,
+  isValidVersion,
+  isValidTimeout,
+  ToolManifestSchema,
+} from "./validator";
+
+// Loader
+export {
+  ManifestLoadError,
+  loadManifest,
+  loadManifestFromDir,
+  findManifestFile,
+  hasManifest,
+  tryLoadManifest,
+  tryLoadManifestFromDir,
+  type LoadedManifest,
+} from "./loader";

package/src/manifest/loader.ts

@@ -0,0 +1,187 @@
+/**
+ * Manifest loader - combines parsing and validation
+ *
+ * Provides high-level functions to load tool manifests from files
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { ParsedManifest, ToolManifest, ValidationResult } from "../types/manifest";
+import { MANIFEST_FILES } from "../types/manifest";
+import { ManifestParseError, parseManifestAuto } from "./parser";
+import { validateManifest } from "./validator";
+
+/**
+ * Error thrown when loading a manifest fails
+ */
+export class ManifestLoadError extends Error {
+  constructor(
+    message: string,
+    public readonly filePath: string,
+    public readonly originalError?: Error
+  ) {
+    super(message);
+    this.name = "ManifestLoadError";
+  }
+}
+
+/**
+ * Result of loading a manifest
+ */
+export interface LoadedManifest {
+  /** The validated manifest */
+  manifest: ToolManifest;
+  /** The markdown body (if from .md file) */
+  body?: string;
+  /** The format the manifest was loaded from */
+  format: "yaml" | "md";
+  /** The file path the manifest was loaded from */
+  filePath: string;
+  /** Validation warnings (if any) */
+  warnings?: ValidationResult["warnings"];
+}
+
+/**
+ * Load a manifest from a file path
+ *
+ * @param filePath - Path to the manifest file (enact.yaml, enact.yml, or enact.md)
+ * @returns LoadedManifest with validated manifest and metadata
+ * @throws ManifestLoadError if file doesn't exist, parse fails, or validation fails
+ */
+export function loadManifest(filePath: string): LoadedManifest {
+  // Check file exists
+  if (!existsSync(filePath)) {
+    throw new ManifestLoadError(`Manifest file not found: ${filePath}`, filePath);
+  }
+
+  // Read file content
+  let content: string;
+  try {
+    content = readFileSync(filePath, "utf-8");
+  } catch (error) {
+    throw new ManifestLoadError(
+      `Failed to read manifest file: ${(error as Error).message}`,
+      filePath,
+      error as Error
+    );
+  }
+
+  // Parse the manifest
+  let parsed: ParsedManifest;
+  try {
+    parsed = parseManifestAuto(content, basename(filePath));
+  } catch (error) {
+    if (error instanceof ManifestParseError) {
+      throw new ManifestLoadError(`Failed to parse manifest: ${error.message}`, filePath, error);
+    }
+    throw new ManifestLoadError(
+      `Failed to parse manifest: ${(error as Error).message}`,
+      filePath,
+      error as Error
+    );
+  }
+
+  // Validate the manifest
+  const validation = validateManifest(parsed.manifest);
+
+  if (!validation.valid) {
+    const errorMessages =
+      validation.errors?.map((e) => `  - ${e.path}: ${e.message}`).join("\n") ?? "";
+    throw new ManifestLoadError(`Manifest validation failed:\n${errorMessages}`, filePath);
+  }
+
+  // Build result
+  const result: LoadedManifest = {
+    manifest: parsed.manifest,
+    format: parsed.format,
+    filePath,
+  };
+
+  if (parsed.body) {
+    result.body = parsed.body;
+  }
+
+  if (validation.warnings && validation.warnings.length > 0) {
+    result.warnings = validation.warnings;
+  }
+
+  return result;
+}
+
+/**
+ * Find and load a manifest from a directory
+ *
+ * Searches for enact.md, enact.yaml, or enact.yml in the given directory
+ *
+ * @param dir - Directory to search for manifest
+ * @returns LoadedManifest if found
+ * @throws ManifestLoadError if no manifest found or loading fails
+ */
+export function loadManifestFromDir(dir: string): LoadedManifest {
+  // Try each manifest filename in order of preference
+  for (const filename of MANIFEST_FILES) {
+    const filePath = join(dir, filename);
+    if (existsSync(filePath)) {
+      return loadManifest(filePath);
+    }
+  }
+
+  throw new ManifestLoadError(
+    `No manifest found in directory: ${dir}. Expected one of: ${MANIFEST_FILES.join(", ")}`,
+    dir
+  );
+}
+
+/**
+ * Find a manifest file in a directory without loading it
+ *
+ * @param dir - Directory to search
+ * @returns Path to manifest file or null if not found
+ */
+export function findManifestFile(dir: string): string | null {
+  for (const filename of MANIFEST_FILES) {
+    const filePath = join(dir, filename);
+    if (existsSync(filePath)) {
+      return filePath;
+    }
+  }
+  return null;
+}
+
+/**
+ * Check if a directory contains a manifest file
+ *
+ * @param dir - Directory to check
+ * @returns true if a manifest file exists
+ */
+export function hasManifest(dir: string): boolean {
+  return findManifestFile(dir) !== null;
+}
+
+/**
+ * Try to load a manifest, returning null instead of throwing
+ *
+ * @param filePath - Path to the manifest file
+ * @returns LoadedManifest or null if loading fails
+ */
+export function tryLoadManifest(filePath: string): LoadedManifest | null {
+  try {
+    return loadManifest(filePath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Try to load a manifest from a directory, returning null instead of throwing
+ *
+ * @param dir - Directory to search
+ * @returns LoadedManifest or null if no manifest found or loading fails
+ */
+export function tryLoadManifestFromDir(dir: string): LoadedManifest | null {
+  try {
+    return loadManifestFromDir(dir);
+  } catch {
+    return null;
+  }
+}

package/src/manifest/parser.ts

@@ -0,0 +1,173 @@
+/**
+ * YAML and Markdown parser for Enact tool manifests
+ *
+ * Handles parsing of:
+ * - enact.yaml files (pure YAML)
+ * - enact.md files (YAML frontmatter + Markdown body)
+ */
+
+import yaml from "js-yaml";
+import type { ParsedManifest, ToolManifest } from "../types/manifest";
+
+/**
+ * Error thrown when parsing fails
+ */
+export class ManifestParseError extends Error {
+  public readonly originalError: Error | undefined;
+
+  constructor(message: string, originalError?: Error) {
+    super(message);
+    this.name = "ManifestParseError";
+    this.originalError = originalError;
+  }
+}
+
+/**
+ * Regex to match YAML frontmatter in Markdown files
+ * Matches content between --- delimiters at the start of the file
+ */
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/**
+ * Parse format type
+ */
+export type ManifestFormat = "yaml" | "md";
+
+/**
+ * Extract YAML frontmatter from Markdown content
+ *
+ * @param content - The full Markdown file content
+ * @returns Object with frontmatter YAML and body Markdown, or null if no frontmatter
+ */
+export function extractFrontmatter(content: string): {
+  frontmatter: string;
+  body: string;
+} | null {
+  const match = content.match(FRONTMATTER_REGEX);
+
+  if (!match) {
+    return null;
+  }
+
+  const frontmatter = match[1];
+  const body = match[2];
+
+  return {
+    frontmatter: frontmatter ? frontmatter.trim() : "",
+    body: body ? body.trim() : "",
+  };
+}
+
+/**
+ * Parse YAML content into a ToolManifest object
+ *
+ * @param yamlContent - Raw YAML string
+ * @returns Parsed object (not yet validated)
+ * @throws ManifestParseError if YAML parsing fails
+ */
+export function parseYaml(yamlContent: string): Record<string, unknown> {
+  try {
+    const parsed = yaml.load(yamlContent);
+
+    if (parsed === null || parsed === undefined) {
+      throw new ManifestParseError("YAML content is empty or null");
+    }
+
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new ManifestParseError("YAML content must be an object, not an array or primitive");
+    }
+
+    return parsed as Record<string, unknown>;
+  } catch (error) {
+    if (error instanceof ManifestParseError) {
+      throw error;
+    }
+
+    const yamlError = error as Error;
+    throw new ManifestParseError(`Failed to parse YAML: ${yamlError.message}`, yamlError);
+  }
+}
+
+/**
+ * Parse a manifest from content string
+ *
+ * @param content - The file content (YAML or Markdown with frontmatter)
+ * @param format - The format of the content ('yaml' or 'md')
+ * @returns ParsedManifest with manifest object and optional body
+ * @throws ManifestParseError if parsing fails
+ */
+export function parseManifest(content: string, format: ManifestFormat): ParsedManifest {
+  if (!content || content.trim() === "") {
+    throw new ManifestParseError("Manifest content is empty");
+  }
+
+  if (format === "yaml") {
+    const parsed = parseYaml(content);
+    return {
+      manifest: parsed as unknown as ToolManifest,
+      format: "yaml",
+    };
+  }
+
+  // Handle Markdown format
+  const extracted = extractFrontmatter(content);
+
+  if (!extracted) {
+    throw new ManifestParseError(
+      "Markdown file must contain YAML frontmatter between --- delimiters"
+    );
+  }
+
+  if (!extracted.frontmatter) {
+    throw new ManifestParseError("YAML frontmatter is empty");
+  }
+
+  const parsed = parseYaml(extracted.frontmatter);
+
+  const result: ParsedManifest = {
+    manifest: parsed as unknown as ToolManifest,
+    format: "md",
+  };
+
+  if (extracted.body) {
+    result.body = extracted.body;
+  }
+
+  return result;
+}
+
+/**
+ * Detect manifest format from filename
+ *
+ * @param filename - The manifest filename
+ * @returns The detected format
+ * @throws ManifestParseError if format cannot be detected
+ */
+export function detectFormat(filename: string): ManifestFormat {
+  const lower = filename.toLowerCase();
+
+  if (lower.endsWith(".yaml") || lower.endsWith(".yml")) {
+    return "yaml";
+  }
+
+  if (lower.endsWith(".md")) {
+    return "md";
+  }
+
+  throw new ManifestParseError(
+    `Cannot detect manifest format from filename: ${filename}. Expected .yaml, .yml, or .md extension.`
+  );
+}
+
+/**
+ * Parse manifest content with automatic format detection
+ *
+ * @param content - The file content
+ * @param filename - The filename (for format detection)
+ * @returns ParsedManifest
+ * @throws ManifestParseError if parsing fails
+ */
+export function parseManifestAuto(content: string, filename: string): ParsedManifest {
+  const format = detectFormat(filename);
+  return parseManifest(content, format);
+}