AI Role Factory Engine

The canonical TypeScript generation engine behind the AI Role Factory hosted builder and @ai-role-factory/cli.

Most people should use the hosted builder or CLI. Install the engine when you need to generate or inspect workspaces inside another TypeScript application.

This package is in public preview and requires Node.js 24. Its API is not yet frozen.

Install

npm install @ai-role-factory/engine@preview

Main entry points

• generateWorkspace orchestrates deterministic workspace generation and returns files plus non-fatal warnings.
• generateFiles exposes the lower-level file generator.
• createInstanceManifest and serializeInstanceManifest create the local ownership and maintenance contract used by generated workspaces.
• ownershipForPath classifies factory-owned, customer-owned, and mixed paths.
• Catalog, template, recommendation, placeholder, integration, operating-scope, and configuration helpers are exported from the package root.
• @ai-role-factory/engine/catalog provides the catalog entry point.

The exported TypeScript declarations are included in the package.

Generation shape

import { generateWorkspace } from '@ai-role-factory/engine';

const result = generateWorkspace({
  values,
  selectedIntegrations,
  selectedPacks,
  authModes,
  operatingScope,
  generationMetadata,
  templates,
});

for (const [path, contents] of Object.entries(result.files)) {
  // The caller decides where and how files are stored.
}

The generation functions do not write files, make network requests, or send telemetry. Storage and delivery remain the caller's responsibility.

Instance maintenance

The engine defines the manifest and ownership rules. The CLI provides the read-only doctor and plan-update commands that operators run against local workspaces.

See the public workspace maintenance guide for the operator workflow and safety boundaries.