Managers API

Reference for internal manager classes and methods used by ao-forge.

Overview

ao-forge uses several manager classes to handle different aspects of the development workflow, including project management, process management, and build management.

ProjectManager

Manages project creation, configuration, and structure.

Methods

createProject(options)

Creates a new project with the specified options.

interface CreateProjectOptions {
  name: string
  framework: 'nextjs' | 'nuxtjs'
  packageManager: 'npm' | 'pnpm' | 'yarn'
  template?: string
  path?: string
}

async createProject(options: CreateProjectOptions): Promise<void>

validateProject(path: string)

Validates that a project is properly configured.

async validateProject(path: string): Promise<boolean>

getProjectInfo(path: string)

Gets information about a project.

interface ProjectInfo {
  name: string
  framework: string
  packageManager: string
  version: string
  description?: string
}

async getProjectInfo(path: string): Promise<ProjectInfo>

ProcessManager

Manages AO processes and their lifecycle.

Methods

startProcess(options)

Starts an AO process with the specified options.

interface StartProcessOptions {
  name: string
  wallet?: string
  module?: string
  cron?: string
  sqlite?: boolean
  monitor?: boolean
}

async startProcess(options: StartProcessOptions): Promise<void>

stopProcess(name: string)

Stops a running AO process.

async stopProcess(name: string): Promise<void>

listProcesses()

Lists all available processes.

interface ProcessInfo {
  name: string
  status: 'running' | 'stopped' | 'error'
  pid?: number
  startTime?: Date
}

async listProcesses(): Promise<ProcessInfo[]>

monitorProcess(name: string)

Monitors a process for activity and logs.

async monitorProcess(name: string): Promise<void>

BuildManager

Manages build processes and optimization.

Methods

build(options)

Builds the project with the specified options.

interface BuildOptions {
  framework?: string
  output?: string
  optimize?: boolean
  sourceMaps?: boolean
  minify?: boolean
  static?: boolean
  server?: boolean
}

async build(options: BuildOptions): Promise<void>

optimizeAssets(path: string)

Optimizes assets for production.

async optimizeAssets(path: string): Promise<void>

generateSourceMaps(path: string)

Generates source maps for debugging.

async generateSourceMaps(path: string): Promise<void>

ConfigManager

Manages configuration files and settings.

Methods

loadConfig(path: string)

Loads configuration from a file.

interface Config {
  name: string
  framework: string
  packageManager: string
  luaFiles: string[]
  autoStart: boolean
  ports: {
    dev: number
    ao: number
    monitoring: number
  }
  build: {
    output: string
    optimize: boolean
    sourceMaps: boolean
    minify: boolean
  }
  deploy: {
    platform: string
    environment: string
    domain: string
  }
}

async loadConfig(path: string): Promise<Config>

saveConfig(config: Config, path: string)

Saves configuration to a file.

async saveConfig(config: Config, path: string): Promise<void>

validateConfig(config: Config)

Validates configuration against schema.

interface ValidationResult {
  valid: boolean
  errors: string[]
  warnings: string[]
}

async validateConfig(config: Config): Promise<ValidationResult>

AOManager

Manages AO-specific functionality and AOS CLI integration.

Methods

installAOS()

Installs the AOS CLI tool.

async installAOS(): Promise<void>

checkAOSInstallation()

Checks if AOS CLI is installed.

async checkAOSInstallation(): Promise<boolean>

executeAOSCommand(command: string, args: string[])

Executes an AOS CLI command.

interface AOSResult {
  success: boolean
  output: string
  error?: string
}

async executeAOSCommand(command: string, args: string[]): Promise<AOSResult>

TemplateManager

Manages project templates and scaffolding.

Methods

listTemplates()

Lists all available templates.

interface Template {
  name: string
  description: string
  framework: string
  features: string[]
}

async listTemplates(): Promise<Template[]>

getTemplate(name: string)

Gets information about a specific template.

async getTemplate(name: string): Promise<Template>

applyTemplate(template: string, targetPath: string, options: any)

Applies a template to a target directory.

async applyTemplate(template: string, targetPath: string, options: any): Promise<void>

DeploymentManager

Manages deployment to various platforms.

Methods

deploy(options)

Deploys the project to the specified platform.

interface DeployOptions {
  platform: 'vercel' | 'netlify' | 'github' | 'docker'
  environment: 'development' | 'staging' | 'production'
  domain?: string
  customDomain?: string
}

async deploy(options: DeployOptions): Promise<void>

buildForDeployment(platform: string)

Builds the project for a specific deployment platform.

async buildForDeployment(platform: string): Promise<void>

Error Handling

All managers include comprehensive error handling:

interface ManagerError {
  code: string
  message: string
  details?: any
  stack?: string
}

class ManagerError extends Error {
  constructor(code: string, message: string, details?: any) {
    super(message)
    this.code = code
    this.details = details
  }
}

Error Codes

  • PROJECT_NOT_FOUND - Project directory not found
  • INVALID_CONFIG - Configuration file is invalid
  • PROCESS_FAILED - AO process failed to start
  • BUILD_FAILED - Build process failed
  • DEPLOYMENT_FAILED - Deployment failed
  • AOS_NOT_INSTALLED - AOS CLI not installed
  • TEMPLATE_NOT_FOUND - Template not found

Usage Examples

Creating a Project

import { ProjectManager } from '@ao-forge/core'

const projectManager = new ProjectManager()

await projectManager.createProject({
  name: 'my-ao-app',
  framework: 'nextjs',
  packageManager: 'pnpm',
  template: 'default'
})

Starting a Process

import { ProcessManager } from '@ao-forge/core'

const processManager = new ProcessManager()

await processManager.startProcess({
  name: 'my-process',
  monitor: true,
  sqlite: true
})

Building a Project

import { BuildManager } from '@ao-forge/core'

const buildManager = new BuildManager()

await buildManager.build({
  optimize: true,
  sourceMaps: false,
  minify: true
})

Best Practices

  1. Error Handling - Always handle errors appropriately
  2. Async Operations - Use async/await for all operations
  3. Validation - Validate inputs before processing
  4. Logging - Log important operations and errors
  5. Testing - Write tests for all manager methods
Table of Contents