@bernierllc/onboarding-plugin-website-builder

Onboarding feature plugin that builds a site config conversationally — the first concrete implementation of the onboarding-feature-plugin contract.

Overview

WebsiteBuilderPlugin implements OnboardingFeaturePlugin to wire the Website Builder cluster into an AI onboarding agent session. It contributes:

• Goals — branding set, theme configured, at least one content section added, site marked ready
• Questions — phase-organized: business identity, logo & colors (with vision-guided color extraction), content sections
• Tools — wb_updateBranding, wb_updateTheme, wb_upsertSection, wb_getSiteStatus, wb_markSiteReady (all in agent-tool-registry format, calling into an injected SiteBuilder)
• Panel — side-panel descriptor pointing to SitePreviewCard from @bernierllc/site-preview-ui
• Handoffs — "View your live site" (route) and "Review your site settings" (task)

Installation

npm install @bernierllc/onboarding-plugin-website-builder

Usage

import { SiteBuilder, InMemorySiteConfigStore } from '@bernierllc/site-builder-service';
import { mergePluginContributions } from '@bernierllc/onboarding-feature-plugin';
import { ToolRegistry } from '@bernierllc/agent-tool-registry';
import {
  WebsiteBuilderPlugin,
  buildAgentToolDefinitions,
  WEBSITE_BUILDER_EVALUATORS,
} from '@bernierllc/onboarding-plugin-website-builder';

// Create the site builder with a store adapter
const siteBuilder = new SiteBuilder({ store: new InMemorySiteConfigStore() });

// Instantiate the plugin
const plugin = new WebsiteBuilderPlugin({
  siteBuilder,
  tenantId: 'tenant-123',
  slug: 'acme-co',
  offeredSections: ['services', 'contact', 'hours'],
  defaults: { heroStyle: 'minimal' },
});

// Contribute goals, phases, questions, and tools to an onboarding session
const goals = plugin.contributeGoals();
const phases = plugin.contributePhases({ baseConfig: onboardingConfig, pluginConfig: {} });
const questions = plugin.contributeQuestions();
const tools = plugin.contributeTools();
const panel = plugin.contributePanel({ baseConfig: onboardingConfig, pluginConfig: {} });
const handoffs = plugin.contributeHandoffs();

// Register executable tools with agent-tool-registry
const toolRegistry = new ToolRegistry();
for (const tool of buildAgentToolDefinitions(siteBuilder, 'tenant-123', 'acme-co')) {
  toolRegistry.register(tool);
}

// Merge plugin contributions into a base onboarding config
const merged = mergePluginContributions(baseOnboardingConfig, [{ plugin, config: {} }]);

API Reference

WebsiteBuilderPlugin

The main plugin class implementing OnboardingFeaturePlugin.

Constructor

new WebsiteBuilderPlugin(config: WebsiteBuilderPluginConfig)

| Parameter | Type | Description | |-----------|------|-------------| | siteBuilder | SiteBuilder | Site builder service instance | | tenantId | string | Tenant identifier | | slug | string | Site slug | | offeredSections | SiteSectionType[] | Optional list of offered section types | | defaults | Partial<SiteTheme> | Optional default theme overrides |

Methods

| Method | Returns | Description | |--------|---------|-------------| | contributeGoals() | GoalDefinition[] | Returns the 4 website builder goals | | contributeQuestions() | PhaseQuestion[] | Returns all onboarding questions | | contributeTools() | PluginToolDefinition[] | Returns 5 schema-only tool definitions | | contributePhases(ctx) | OnboardingPhase[] | Returns 3 onboarding phases | | contributePanel(ctx) | PanelDescriptor | Returns side-panel descriptor | | contributeHandoffs() | Handoff[] | Returns 2 completion handoffs |

buildAgentToolDefinitions

Builds ToolDefinition objects with executable handlers for registration with @bernierllc/agent-tool-registry.

function buildAgentToolDefinitions(
  siteBuilder: SiteBuilder,
  tenantId: string,
  slug: string,
  logger?: Logger
): ToolDefinition[]

Returns definitions for: wb_updateBranding, wb_updateTheme, wb_upsertSection, wb_getSiteStatus, wb_markSiteReady.

GOALS

Array of 4 GoalDefinition objects: wb.branding, wb.theme, wb.sections, wb.ready.

WEBSITE_BUILDER_EVALUATORS

Custom goal evaluator map for use with evaluateGoals from @bernierllc/onboarding-config-core.

PLUGIN_TOOL_DEFINITIONS

Schema-only PluginToolDefinition[] for the 5 website builder tools.

Error Classes

All errors extend OnboardingPluginWebsiteBuilderError which extends Error.

| Class | Code | Usage | |-------|------|-------| | OnboardingPluginWebsiteBuilderError | ONBOARDING_PLUGIN_WB_ERROR | Base error class | | WebsiteBuilderConfigError | WB_CONFIG_INVALID | Invalid plugin configuration | | WebsiteBuilderToolError | WB_TOOL_ERROR | Tool execution failure |

import {
  WebsiteBuilderConfigError,
  WebsiteBuilderToolError,
} from '@bernierllc/onboarding-plugin-website-builder';

try {
  await toolDef.execute(input);
} catch (err) {
  if (err instanceof WebsiteBuilderToolError) {
    console.error(err.code, err.context, err.cause);
  }
}

Integration Status

| Integration | Status | Notes | |-------------|--------|-------| | Logger: | integrated | Uses @bernierllc/logger for tool execution events | | NeverHub: | optional | Pass neverhub option to SiteBuilder constructor |

Logger integration

The plugin uses @bernierllc/logger inside buildAgentToolDefinitions. Pass an external logger instance to share log context:

import { Logger, LogLevel } from '@bernierllc/logger';

const logger = new Logger({ level: LogLevel.INFO, transports: [consoleTransport] });
const tools = buildAgentToolDefinitions(siteBuilder, tenantId, slug, logger);

NeverHub integration

NeverHub integration is handled at the SiteBuilder level (via @bernierllc/site-builder-service), not this plugin directly. Configure it when constructing SiteBuilder:

const siteBuilder = new SiteBuilder({
  store: myStore,
  neverhub: { enabled: true },
});

Graceful degradation: if NeverHub is unavailable, SiteBuilder continues operating with core functionality intact.

License

Copyright (c) 2025 Bernier LLC. Limited-use license — see LICENSE for details.