feat(cli): wire ai-agents through bootstrap and diagnostics

d4v3-rm · d4v3-rm · commit b21bfb157fca · 2026-03-17T14:04:50.000+01:00
diff --git a/src/commands/register-bootstrap-command.ts b/src/commands/register-bootstrap-command.ts
@@ -12,8 +12,10 @@ export function registerBootstrapCommand(program: Command): void {
     .command('bootstrap')
     .description('Run the idempotent bootstrap only')
     .option('--project-dir <path>', 'Explicit lab asset root instead of the packaged install')
+    .option('--with-ai-agents', 'Include the optional AI agents bootstrap (n8n owner reconciliation)')
     .option('--with-ai-llm, --with-ai', 'Include the optional AI LLM bootstrap (Ollama models)')
     .option('--skip-gitea', 'Skip the Gitea admin reconciliation step')
+    .option('--skip-n8n', 'Skip the n8n owner reconciliation step')
     .option('--skip-ollama', 'Skip the Ollama model reconciliation step')
     .action(async (options: BootstrapCommandOptions) => {
       const normalizedOptions = normalizeAiAliasOptions(options);
diff --git a/src/commands/register-doctor-command.ts b/src/commands/register-doctor-command.ts
@@ -13,6 +13,7 @@ export function registerDoctorCommand(program: Command): void {
     .description('Check host requirements and optionally run smoke tests')
     .option('--project-dir <path>', 'Explicit lab asset root instead of the packaged install')
     .option('--with-ai-llm, --with-ai', 'Include the optional AI LLM layer checks')
+    .option('--with-ai-agents', 'Include the optional AI agents layer checks')
     .option('--with-ai-image, --with-image', 'Include the optional AI image layer checks')
     .option('--with-ai-video', 'Include the optional AI video layer checks')
     .option('--with-workbench', 'Validate the optional workbench Compose layer')
diff --git a/src/commands/register-save-images-command.ts b/src/commands/register-save-images-command.ts
@@ -14,6 +14,7 @@ export function registerSaveImagesCommand(program: Command): void {
     .option('--project-dir <path>', 'Explicit lab asset root instead of the packaged install')
     .option('--output <path>', 'Output archive path (defaults under ./backups/images)')
     .option('--with-ai-llm, --with-ai', 'Include the optional AI LLM layer images')
+    .option('--with-ai-agents', 'Include the optional AI agents layer images')
     .option('--with-ai-image, --with-image', 'Include the optional AI image layer images')
     .option('--with-ai-video', 'Include the optional AI video layer images')
     .option('--with-workbench', 'Include the optional workbench layer images')
diff --git a/src/commands/register-save-volumes-command.ts b/src/commands/register-save-volumes-command.ts
@@ -14,6 +14,7 @@ export function registerSaveVolumesCommand(program: Command): void {
     .option('--project-dir <path>', 'Explicit lab asset root instead of the packaged install')
     .option('--output <path>', 'Output archive path (defaults under ./backups/volumes)')
     .option('--with-ai-llm, --with-ai', 'Include the optional AI LLM layer volumes')
+    .option('--with-ai-agents', 'Include the optional AI agents layer volumes')
     .option('--with-ai-image, --with-image', 'Include the optional AI image layer volumes')
     .option('--with-ai-video', 'Include the optional AI video layer volumes')
     .option('--with-workbench', 'Include the optional workbench layer volumes')
diff --git a/src/commands/register-up-command.ts b/src/commands/register-up-command.ts
@@ -14,6 +14,7 @@ export function registerUpCommand(program: Command): void {
     .option('--project-dir <path>', 'Explicit lab asset root instead of the packaged install')
     .option('--build', 'Rebuild images before starting the stack')
     .option('--with-ai-llm, --with-ai', 'Include the optional AI LLM layer (Open WebUI and Ollama)')
+    .option('--with-ai-agents', 'Include the optional AI agents layer (n8n and external runners)')
     .option(
       '--with-ai-image, --with-image',
       'Include the optional AI image layer (InvokeAI and its paired runtime)'
diff --git a/src/config/lab-env.schema.ts b/src/config/lab-env.schema.ts
@@ -61,7 +61,13 @@ export const bootstrapEnvSchema = labEnvSchema.extend({
   GITEA_GID: requiredEnvValue,
   GITEA_ROOT_USERNAME: requiredEnvValue,
   GITEA_ROOT_PASSWORD: requiredEnvValue,
-  GITEA_ROOT_EMAIL: requiredEnvValue,
+  GITEA_ROOT_EMAIL: requiredEnvValue
+});
+
+/**
+ * Schema for workflows that require AI agents bootstrap env values.
+ */
+export const aiAgentsBootstrapEnvSchema = labEnvSchema.extend({
   N8N_URL: requiredEnvValue,
   N8N_ROOT_FIRST_NAME: requiredEnvValue,
   N8N_ROOT_LAST_NAME: requiredEnvValue,
@@ -74,7 +80,13 @@ export const bootstrapEnvSchema = labEnvSchema.extend({
  */
 export const smokeEnvSchema = labEnvSchema.extend({
   LAB_URL: requiredEnvValue,
-  GITEA_URL: requiredEnvValue,
+  GITEA_URL: requiredEnvValue
+});
+
+/**
+ * Schema for AI agents smoke checks.
+ */
+export const aiAgentsSmokeEnvSchema = labEnvSchema.extend({
   N8N_URL: requiredEnvValue,
   N8N_ROOT_EMAIL: requiredEnvValue,
   N8N_ROOT_PASSWORD: requiredEnvValue
diff --git a/src/services/bootstrap.service.ts b/src/services/bootstrap.service.ts
@@ -2,13 +2,17 @@ import { Listr } from 'listr2';
 import pWaitFor from 'p-wait-for';
 import { createComposeCommandArgs, type ComposeLayerSelection } from '../lib/compose.js';
 import type { BootstrapCommandOptions } from '../types/cli.types.js';
-import type { BootstrapEnv, ProjectContext } from '../types/project.types.js';
+import type { ProjectContext } from '../types/project.types.js';
 import { ensureGiteaAdmin } from './gitea-admin.service.js';
 import { ensureN8nOwner } from './n8n-owner.service.js';
 import { printCommandHeader } from '../ui/banner.js';
 import { formatTaskTitle, printInfo, printSuccess } from '../ui/logger.js';
 import { runCommand } from '../utils/process.js';
-import { parseAiLlmBootstrapEnv, parseBootstrapEnv } from './project.service.js';
+import {
+  parseAiAgentsBootstrapEnv,
+  parseAiLlmBootstrapEnv,
+  parseBootstrapEnv
+} from './project.service.js';
 
 const VERBOSE_TASK_RENDERER = 'verbose' as const;
 
@@ -21,7 +25,7 @@ export async function runBootstrapCommand(
 ): Promise<void> {
   printCommandHeader({
     title: 'Bootstrap Atlas Lab',
-    summary: 'Reconcile core runtime state and optional AI LLM models',
+    summary: 'Reconcile core runtime state plus optional AI agents and AI LLM bootstrap',
     projectRoot: context.projectRoot,
     workingDirectory: context.workingDirectory
   });
@@ -42,6 +46,7 @@ export function createBootstrapTasks(
   options: BootstrapCommandOptions
 ) {
   const env = parseBootstrapEnv(context.env);
+  const aiAgentsEnv = options.withAiAgents ? parseAiAgentsBootstrapEnv(context.env) : undefined;
   const aiLlmEnv = options.withAiLlm ? parseAiLlmBootstrapEnv(context.env) : undefined;
 
   const tasks = [];
@@ -57,15 +62,17 @@ export function createBootstrapTasks(
     });
   }
 
-  tasks.push({
-    title: formatTaskTitle('bootstrap', 'Align n8n owner account'),
-    task: async () => {
-      await waitForService(context, 'n8n');
-      await waitForService(context, 'gateway');
-      const result = await ensureN8nOwner(context, env);
-      printInfo(`n8n owner account ${result}.`, 'bootstrap');
-    }
-  });
+  if (options.withAiAgents && !options.skipN8n && aiAgentsEnv) {
+    tasks.push({
+      title: formatTaskTitle('bootstrap', 'Align n8n owner account'),
+      task: async () => {
+        await waitForService(context, 'n8n', 180, { includeAiAgents: true });
+        await waitForService(context, 'gateway-ai-agents', 180, { includeAiAgents: true });
+        const result = await ensureN8nOwner(context, aiAgentsEnv);
+        printInfo(`n8n owner account ${result}.`, 'bootstrap');
+      }
+    });
+  }
 
   if (options.withAiLlm && !options.skipOllama && aiLlmEnv) {
     tasks.push({
diff --git a/src/services/compose-project.service.ts b/src/services/compose-project.service.ts
@@ -54,12 +54,13 @@ export async function getRunningComposePublishedPorts(
  */
 export async function listConfiguredComposeImages(
   context: ProjectContext,
-  options: Pick<SaveImagesCommandOptions, 'withAiLlm' | 'withAiImage' | 'withAiVideo' | 'withWorkbench'>
+  options: Pick<SaveImagesCommandOptions, 'withAiLlm' | 'withAiAgents' | 'withAiImage' | 'withAiVideo' | 'withWorkbench'>
 ): Promise<string[]> {
   const result = await runCommand(
     'docker',
     createComposeCommandArgs(context, ['config', '--images'], {
       includeAiLlm: Boolean(options.withAiLlm),
+      includeAiAgents: Boolean(options.withAiAgents),
       includeAiImage: Boolean(options.withAiImage),
       includeAiVideo: Boolean(options.withAiVideo),
       includeWorkbench: Boolean(options.withWorkbench)
@@ -81,6 +82,7 @@ export async function listConfiguredDockerVolumes(
   context: ProjectContext,
   options: Pick<GlobalCliOptions, never> & {
     withAiLlm?: boolean;
+    withAiAgents?: boolean;
     withAiImage?: boolean;
     withAiVideo?: boolean;
     withWorkbench?: boolean;
@@ -90,6 +92,7 @@ export async function listConfiguredDockerVolumes(
     'docker',
     createComposeCommandArgs(context, ['config', '--volumes'], {
       includeAiLlm: Boolean(options.withAiLlm),
+      includeAiAgents: Boolean(options.withAiAgents),
       includeAiImage: Boolean(options.withAiImage),
       includeAiVideo: Boolean(options.withAiVideo),
       includeWorkbench: Boolean(options.withWorkbench)
diff --git a/src/services/doctor.service.ts b/src/services/doctor.service.ts
@@ -6,6 +6,7 @@ import { createComposeCommandArgs } from '../lib/compose.js';
 import type { DoctorCommandOptions } from '../types/cli.types.js';
 import type { HostCheckResult, SmokeCheckDefinition } from '../types/doctor.types.js';
 import type {
+  AiAgentsSmokeEnv,
   AiImageSmokeEnv,
   AiVideoSmokeEnv,
   AiLlmSmokeEnv,
@@ -21,6 +22,7 @@ import { readGatewayCertificate } from './gateway-certificate.service.js';
 import { checkNvidiaGpuRuntime } from './gpu-preflight.service.js';
 import { canLoginToN8n } from './n8n-owner.service.js';
 import {
+  parseAiAgentsSmokeEnv,
   parseAiImageSmokeEnv,
   parseAiVideoSmokeEnv,
   parseAiLlmSmokeEnv,
@@ -69,11 +71,12 @@ export async function runDoctorCommand(
 
   if (options.smoke) {
     const env = parseSmokeEnv(context.env);
+    const aiAgentsEnv = options.withAiAgents ? parseAiAgentsSmokeEnv(context.env) : undefined;
     const aiLlmEnv = options.withAiLlm ? parseAiLlmSmokeEnv(context.env) : undefined;
     const aiImageEnv = options.withAiImage ? parseAiImageSmokeEnv(context.env) : undefined;
     const aiVideoEnv = options.withAiVideo ? parseAiVideoSmokeEnv(context.env) : undefined;
     const gatewayCertificate = await readGatewayCertificate(context, 'smoke');
-    for (const smokeCheck of buildSmokeChecks(env, aiLlmEnv, aiImageEnv, aiVideoEnv)) {
+    for (const smokeCheck of buildSmokeChecks(env, aiAgentsEnv, aiLlmEnv, aiImageEnv, aiVideoEnv)) {
       tasks.push(createCheckTask(results, 'smoke', smokeCheck.name, () => smokeCheck.run(gatewayCertificate)));
     }
   }
@@ -193,12 +196,13 @@ function npmCheckCommand(): [string, string[], string] {
  */
 async function checkComposeConfiguration(
   context: ProjectContext,
-  options: Pick<DoctorCommandOptions, 'withAiLlm' | 'withAiImage' | 'withAiVideo' | 'withWorkbench'>
+  options: Pick<DoctorCommandOptions, 'withAiLlm' | 'withAiAgents' | 'withAiImage' | 'withAiVideo' | 'withWorkbench'>
 ): Promise<HostCheckResult> {
   const result = await runCommand(
     'docker',
     createComposeCommandArgs(context, ['config', '-q'], {
       includeAiLlm: Boolean(options.withAiLlm),
+      includeAiAgents: Boolean(options.withAiAgents),
       includeAiImage: Boolean(options.withAiImage),
       includeAiVideo: Boolean(options.withAiVideo),
       includeWorkbench: Boolean(options.withWorkbench)
@@ -239,6 +243,7 @@ function checkRequiredFile(projectRoot: string, relativePath: string): HostCheck
  */
 function buildSmokeChecks(
   env: SmokeEnv,
+  aiAgentsEnv?: AiAgentsSmokeEnv,
   aiLlmEnv?: AiLlmSmokeEnv,
   aiImageEnv?: AiImageSmokeEnv,
   aiVideoEnv?: AiVideoSmokeEnv
@@ -252,23 +257,26 @@ function buildSmokeChecks(
       name: 'Smoke Gitea',
       run: (caCertificate) =>
         runStatusCheck('Smoke Gitea', new URL('/api/healthz', env.GITEA_URL).toString(), caCertificate)
-    },
-    {
+    }
+  ];
+
+  if (!aiAgentsEnv && !aiLlmEnv && !aiImageEnv && !aiVideoEnv) {
+    return checks;
+  }
+
+  if (aiAgentsEnv) {
+    checks.push({
       name: 'Smoke n8n',
       run: async (caCertificate) => {
-        const ok = await canLoginToN8n(env, caCertificate);
+        const ok = await canLoginToN8n(aiAgentsEnv, caCertificate);
 
         return {
           name: 'Smoke n8n',
           ok,
           detail: ok ? 'Owner login verified' : 'Could not authenticate with the configured owner account'
         };
       }
-    }
-  ];
-
-  if (!aiLlmEnv && !aiImageEnv && !aiVideoEnv) {
-    return checks;
+    });
   }
 
   if (aiImageEnv) {
diff --git a/src/services/host-preflight.service.ts b/src/services/host-preflight.service.ts
@@ -12,7 +12,10 @@ import { runCommand } from '../utils/process.js';
 
 const CORE_PORT_ENV_KEYS = [
   'LAB_HTTPS_PORT',
-  'GITEA_HTTPS_PORT',
+  'GITEA_HTTPS_PORT'
+] as const;
+
+const AI_AGENTS_PORT_ENV_KEYS = [
   'N8N_HTTPS_PORT'
 ] as const;
 
@@ -46,6 +49,7 @@ export async function assertPublishedPortsAvailable(
   context: ProjectContext,
   options: {
     includeAiLlm: boolean;
+    includeAiAgents: boolean;
     includeAiImage: boolean;
     includeAiVideo: boolean;
     includeWorkbench: boolean;
@@ -55,6 +59,7 @@ export async function assertPublishedPortsAvailable(
     context.env,
     options.includeWorkbench,
     options.includeAiLlm,
+    options.includeAiAgents,
     options.includeAiImage,
     options.includeAiVideo
   );
@@ -82,12 +87,14 @@ function getConfiguredHostPorts(
   env: LabEnv,
   includeWorkbench: boolean,
   includeAiLlm: boolean,
+  includeAiAgents: boolean,
   includeAiImage: boolean,
   includeAiVideo: boolean
 ): HostPortDefinition[] {
   const envKeys = [
     ...CORE_PORT_ENV_KEYS,
     ...(includeAiLlm ? [...AI_LLM_PORT_ENV_KEYS] : []),
+    ...(includeAiAgents ? [...AI_AGENTS_PORT_ENV_KEYS] : []),
     ...(includeAiImage ? [...AI_IMAGE_PORT_ENV_KEYS] : []),
     ...(includeAiVideo ? [...AI_VIDEO_PORT_ENV_KEYS] : []),
     ...(includeWorkbench ? [...WORKBENCH_PORT_ENV_KEYS] : [])
diff --git a/src/services/n8n-owner.service.ts b/src/services/n8n-owner.service.ts
@@ -1,7 +1,7 @@
 import pWaitFor from 'p-wait-for';
 import { createComposeCommandArgs } from '../lib/compose.js';
 import { readGatewayCertificate } from './gateway-certificate.service.js';
-import type { BootstrapEnv, SmokeEnv, ProjectContext } from '../types/project.types.js';
+import type { AiAgentsBootstrapEnv, AiAgentsSmokeEnv, ProjectContext } from '../types/project.types.js';
 import type { HttpsResponse } from '../types/http.types.js';
 import type {
   N8nOwnerBootstrapResult,
@@ -17,7 +17,7 @@ import { runCommand } from '../utils/process.js';
  */
 export async function ensureN8nOwner(
   context: ProjectContext,
-  env: BootstrapEnv
+  env: AiAgentsBootstrapEnv
 ): Promise<N8nOwnerBootstrapResult> {
   const caCertificate = await readGatewayCertificate(context, 'bootstrap');
   await waitForN8nIngress(env.N8N_URL, caCertificate);
@@ -40,7 +40,9 @@ export async function ensureN8nOwner(
     printInfo('n8n reports an existing owner. Resetting owner management to reconcile credentials.', 'bootstrap');
     await runCommand(
       'docker',
-      createComposeCommandArgs(context, ['exec', '-T', 'n8n', 'n8n', 'user-management:reset']),
+      createComposeCommandArgs(context, ['exec', '-T', 'n8n', 'n8n', 'user-management:reset'], {
+        includeAiAgents: true
+      }),
       {
         cwd: context.projectRoot,
         scope: 'bootstrap'
@@ -110,7 +112,7 @@ function reportN8nIngressWait(n8nUrl: string, attempts: number): void {
  * Performs an authenticated n8n login suitable for smoke checks.
  */
 export async function canLoginToN8n(
-  env: Pick<SmokeEnv, 'N8N_ROOT_EMAIL' | 'N8N_ROOT_PASSWORD' | 'N8N_URL'>,
+  env: Pick<AiAgentsSmokeEnv, 'N8N_ROOT_EMAIL' | 'N8N_ROOT_PASSWORD' | 'N8N_URL'>,
   caCertificate: string
 ): Promise<boolean> {
   const response = await requestHttps(new URL('/rest/login', env.N8N_URL).toString(), {
@@ -152,7 +154,7 @@ export function classifyN8nOwnerSetupResponse(response: HttpsResponse): N8nOwner
  */
 async function setupN8nOwner(
   env: Pick<
-    BootstrapEnv,
+    AiAgentsBootstrapEnv,
     'N8N_ROOT_EMAIL' | 'N8N_ROOT_FIRST_NAME' | 'N8N_ROOT_LAST_NAME' | 'N8N_ROOT_PASSWORD' | 'N8N_URL'
   >,
   caCertificate: string
diff --git a/src/services/project.service.ts b/src/services/project.service.ts
@@ -6,6 +6,8 @@ import dotenv from 'dotenv';
 import { findUpSync } from 'find-up';
 import { ZodError } from 'zod';
 import {
+  aiAgentsBootstrapEnvSchema,
+  aiAgentsSmokeEnvSchema,
   aiImageSmokeEnvSchema,
   aiVideoSmokeEnvSchema,
   aiLlmBootstrapEnvSchema,
@@ -19,6 +21,8 @@ import { PROJECT_MARKERS, REPOSITORY_PATHS, resolveRepositoryLayout } from '../c
 import { ensureDevelopmentFileLogging } from './runtime-log.service.js';
 import type { GlobalCliOptions } from '../types/cli.types.js';
 import type {
+  AiAgentsBootstrapEnv,
+  AiAgentsSmokeEnv,
   AiImageSmokeEnv,
   AiVideoSmokeEnv,
   AiLlmBootstrapEnv,
@@ -67,13 +71,27 @@ export function parseAiLlmBootstrapEnv(env: LabEnv): AiLlmBootstrapEnv {
   return parseWithSchema(() => aiLlmBootstrapEnvSchema.parse(env));
 }
 
+/**
+ * Validates and narrows the env for AI agents bootstrap workflows.
+ */
+export function parseAiAgentsBootstrapEnv(env: LabEnv): AiAgentsBootstrapEnv {
+  return parseWithSchema(() => aiAgentsBootstrapEnvSchema.parse(env));
+}
+
 /**
  * Validates and narrows the env for smoke-check workflows.
  */
 export function parseSmokeEnv(env: LabEnv): SmokeEnv {
   return parseWithSchema(() => smokeEnvSchema.parse(env));
 }
 
+/**
+ * Validates and narrows the env for AI agents smoke-check workflows.
+ */
+export function parseAiAgentsSmokeEnv(env: LabEnv): AiAgentsSmokeEnv {
+  return parseWithSchema(() => aiAgentsSmokeEnvSchema.parse(env));
+}
+
 /**
  * Validates and narrows the env for AI LLM smoke-check workflows.
  */
diff --git a/src/services/stack.service.ts b/src/services/stack.service.ts
diff --git a/src/types/cli.types.ts b/src/types/cli.types.ts
diff --git a/src/types/project.types.ts b/src/types/project.types.ts
diff --git a/src/ui/banner.ts b/src/ui/banner.ts
