@joshualiamzn/open-stack 0.0.1 → 0.0.2

package/src/aws.mjs

@@ -5,6 +5,12 @@ import {
   DescribeDomainCommand,
   ListDomainNamesCommand,
   DescribeDomainsCommand,
+  AddDirectQueryDataSourceCommand,
+  GetDirectQueryDataSourceCommand,
+  CreateApplicationCommand,
+  GetApplicationCommand,
+  UpdateApplicationCommand,
+  ListApplicationsCommand,
 } from '@aws-sdk/client-opensearch';
 import {
   OpenSearchServerlessClient,
@@ -25,14 +31,23 @@ import {
   AmpClient,
   ListWorkspacesCommand,
   CreateWorkspaceCommand,
+  DescribeWorkspaceCommand,
 } from '@aws-sdk/client-amp';
 import {
   OSISClient,
   ListPipelinesCommand,
   CreatePipelineCommand,
   GetPipelineCommand,
-  UpdatePipelineCommand,
 } from '@aws-sdk/client-osis';
+import {
+  EKSClient,
+  DescribeClusterCommand,
+} from '@aws-sdk/client-eks';
+import {
+  ResourceGroupsTaggingAPIClient,
+  GetResourcesCommand,
+  TagResourcesCommand,
+} from '@aws-sdk/client-resource-groups-tagging-api';
 import {
   printStep,
   printSuccess,
@@ -43,6 +58,14 @@ import {
 } from './ui.mjs';
 import chalk from 'chalk';
 
+// ── Tagging ─────────────────────────────────────────────────────────────────
+
+const TAG_KEY = 'open-stack';
+
+function stackTags(stackName) {
+  return [{ Key: TAG_KEY, Value: stackName }];
+}
+
 // ── Prerequisites ───────────────────────────────────────────────────────────
 
 export async function checkRequirements(cfg) {
@@ -71,6 +94,8 @@ export async function checkRequirements(cfg) {
       console.error(`     ${chalk.bold('export AWS_ACCESS_KEY_ID=<key>')}`);
       console.error(`     ${chalk.bold('export AWS_SECRET_ACCESS_KEY=<secret>')}`);
       console.error(`     ${chalk.bold('export AWS_SESSION_TOKEN=<token>')}  ${chalk.dim('(if using temporary creds)')}`);
+      console.error();
+      console.error(`  ${chalk.dim('Docs:')} ${chalk.underline('https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html#getting-started-quickstart-new-command')}`);
     } else if (/expired|ExpiredToken/i.test(err.message)) {
       console.error(`  ${chalk.bold('Your session has expired. Refresh credentials:')}`);
       console.error();
@@ -84,6 +109,8 @@ export async function checkRequirements(cfg) {
       console.error(`  ${chalk.bold('Try:')}`);
       console.error(`     ${chalk.bold('aws configure')}        ${chalk.dim('— set up credentials')}`);
       console.error(`     ${chalk.bold('aws sso login')}        ${chalk.dim('— refresh SSO session')}`);
+      console.error();
+      console.error(`  ${chalk.dim('Docs:')} ${chalk.underline('https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html#getting-started-quickstart-new-command')}`);
     }
     console.error();
     throw new Error('AWS credentials are not configured or have expired');
@@ -145,6 +172,7 @@ async function createServerlessCollection(cfg) {
       await client.send(new CreateCollectionCommand({
         name: collectionName,
         type: 'TIMESERIES',
+        tags: stackTags(cfg.pipelineName).map((t) => ({ key: t.Key, value: t.Value })),
       }));
       printSuccess('Collection creation initiated — waiting for endpoint');
     } catch (err) {
@@ -322,6 +350,7 @@ async function createManagedDomain(cfg) {
           },
         },
         AccessPolicies: accessPolicy,
+        TagList: stackTags(cfg.pipelineName),
       }));
       printSuccess('Domain creation initiated — waiting for endpoint');
     } catch (createErr) {
@@ -397,11 +426,11 @@ export async function mapOsiRoleInDomain(cfg) {
     } else {
       const body = await resp.text();
       printWarning(`FGAC mapping returned ${resp.status}: ${body}`);
-      printInfo('You may need to manually map the IAM role in OpenSearch Dashboards → Security → Roles');
+      printInfo('You may need to manually map the IAM role in OpenSearch UI → Security → Roles');
     }
   } catch (err) {
     printWarning(`Could not map OSI role in FGAC: ${err.message}`);
-    printInfo('You may need to manually map the IAM role in OpenSearch Dashboards → Security → Roles');
+    printInfo('You may need to manually map the IAM role in OpenSearch UI → Security → Roles');
   }
 }
 
@@ -436,6 +465,7 @@ export async function createIamRole(cfg) {
     const result = await client.send(new CreateRoleCommand({
       RoleName: cfg.iamRoleName,
       AssumeRolePolicyDocument: trustPolicy,
+      Tags: stackTags(cfg.pipelineName),
     }));
     cfg.iamRoleArn = result.Role.Arn;
     printSuccess(`Role created: ${cfg.iamRoleArn}`);
@@ -518,7 +548,10 @@ export async function createApsWorkspace(cfg) {
   } catch { /* proceed to create */ }
 
   try {
-    const result = await client.send(new CreateWorkspaceCommand({ alias: cfg.apsWorkspaceAlias }));
+    const result = await client.send(new CreateWorkspaceCommand({
+      alias: cfg.apsWorkspaceAlias,
+      tags: { [TAG_KEY]: cfg.pipelineName },
+    }));
     cfg.apsWorkspaceId = result.workspaceId;
     cfg.prometheusUrl = `https://aps-workspaces.${cfg.region}.amazonaws.com/workspaces/${cfg.apsWorkspaceId}/api/v1/remote_write`;
 
@@ -572,6 +605,8 @@ export async function createOsiPipeline(cfg, pipelineYaml) {
       MinUnits: cfg.minOcu,
       MaxUnits: cfg.maxOcu,
       PipelineConfigurationBody: pipelineYaml,
+      PipelineRoleArn: cfg.iamRoleArn,
+      Tags: stackTags(cfg.pipelineName),
     }));
     printSuccess(`Pipeline '${cfg.pipelineName}' creation initiated`);
   } catch (err) {
@@ -590,7 +625,7 @@ export async function createOsiPipeline(cfg, pipelineYaml) {
   // Wait for pipeline to become active
   const spinner = createSpinner('Waiting for pipeline to activate...');
   spinner.start();
-  const maxWait = 300_000; // 5 min
+  const maxWait = 900_000; // 15 min
   const start = Date.now();
 
   while (Date.now() - start < maxWait) {
@@ -598,10 +633,11 @@ export async function createOsiPipeline(cfg, pipelineYaml) {
       const resp = await client.send(new GetPipelineCommand({ PipelineName: cfg.pipelineName }));
       const status = resp.Pipeline?.Status;
       if (status === 'ACTIVE') {
-        const urls = resp.Pipeline?.IngestEndpointUrls;
+        const urls = resp.Pipeline?.IngestEndpointUrls || [];
+        cfg.ingestEndpoints = urls;
         spinner.succeed('Pipeline is active');
-        if (urls?.length) {
-          printInfo(`Ingestion endpoint: ${urls[0]}`);
+        for (const url of urls) {
+          printInfo(`Ingestion endpoint: https://${url}`);
         }
         return;
       }
@@ -611,13 +647,360 @@ export async function createOsiPipeline(cfg, pipelineYaml) {
         printInfo(`Reason: ${reason}`);
         throw new Error(`Pipeline creation failed: ${reason}`);
       }
-    } catch { /* keep polling */ }
+    } catch (err) {
+      if (err.message?.startsWith('Pipeline creation failed')) throw err;
+      /* keep polling */
+    }
     await sleepWithTicker(10_000, spinner, start,
       (s) => `Waiting for pipeline... (${fmtElapsed(s)})`);
   }
 
-  spinner.warn('Timed out waiting — pipeline may still be provisioning');
-  printInfo(`Check: aws osis get-pipeline --pipeline-name ${cfg.pipelineName} --region ${cfg.region}`);
+  spinner.fail('Timed out waiting for pipeline after 15 minutes');
+  throw new Error(`Pipeline '${cfg.pipelineName}' did not become active within 15 minutes`);
+}
+
+// ── OpenSearch UI workspace ──────────────────────────────────────────
+
+/**
+ * Set up OpenSearch UI: derive the URL and create an Observability workspace.
+ * Skipped when dashboardsAction is 'reuse' (user provided their own URL).
+ * For managed domains, uses basic auth to call the Dashboards API.
+ * For serverless, provides the URL only (workspace setup via AWS console).
+ */
+export async function setupDashboards(cfg) {
+  if (!cfg.opensearchEndpoint) return;
+  if (cfg.dashboardsAction === 'reuse') {
+    printStep('OpenSearch UI');
+    printSuccess(`Using existing Dashboards: ${cfg.dashboardsUrl}`);
+    if (!cfg.serverless) {
+      await createObservabilityWorkspace(cfg);
+    }
+    return;
+  }
+
+  printStep('Setting up OpenSearch UI...');
+
+  // Use OpenSearch Application URL
+  if (!cfg.appEndpoint && cfg.appId) {
+    const client = new OpenSearchClient({ region: cfg.region });
+    await fetchAppEndpoint(client, cfg);
+  }
+  cfg.dashboardsUrl = cfg.appEndpoint || '';
+  if (!cfg.dashboardsUrl) {
+    printWarning('No OpenSearch Application endpoint available');
+    printInfo('Create an OpenSearch Application in the AWS console to get the UI URL');
+    return;
+  }
+  printSuccess(`URL: ${cfg.dashboardsUrl}`);
+
+  // Create observability workspace (managed domains only — uses basic auth)
+  if (!cfg.serverless) {
+    await createObservabilityWorkspace(cfg);
+  }
+}
+
+async function createObservabilityWorkspace(cfg) {
+  if (!cfg.dashboardsUrl) return;
+  const dashboardsBase = cfg.dashboardsUrl.replace(/\/+$/, '');
+  const url = `${dashboardsBase}/api/workspaces`;
+  const auth = Buffer.from(`${MANAGED_MASTER_USER}:${MANAGED_MASTER_PASS}`).toString('base64');
+
+  // Check if an observability workspace already exists
+  try {
+    const listResp = await fetch(url, {
+      method: 'GET',
+      headers: {
+        'osd-xsrf': 'true',
+        'Authorization': `Basic ${auth}`,
+      },
+    });
+
+    if (listResp.ok) {
+      const data = await listResp.json();
+      const existing = (data.result?.workspaces || []).find(
+        (w) => w.name === 'Observability'
+      );
+      if (existing) {
+        printSuccess(`Observability workspace already exists (id: ${existing.id})`);
+        return;
+      }
+    }
+  } catch { /* proceed to create */ }
+
+  try {
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'osd-xsrf': 'true',
+        'Authorization': `Basic ${auth}`,
+      },
+      body: JSON.stringify({
+        attributes: {
+          name: 'Observability',
+          description: 'Observability workspace for traces, logs, and metrics',
+          features: ['use-case-observability'],
+        },
+      }),
+    });
+
+    if (resp.ok) {
+      const data = await resp.json();
+      const workspaceId = data.result?.id;
+      if (workspaceId) {
+        printSuccess(`Observability workspace created (id: ${workspaceId})`);
+      } else {
+        printSuccess('Observability workspace created');
+      }
+    } else {
+      const body = await resp.text();
+      printWarning(`Could not create Observability workspace (${resp.status}): ${body}`);
+      printInfo('You can create one manually in OpenSearch UI → Workspaces');
+    }
+  } catch (err) {
+    printWarning(`Could not create Observability workspace: ${err.message}`);
+    printInfo('You can create one manually in OpenSearch UI → Workspaces');
+  }
+}
+
+// ── Direct Query Data Source (AMP → OpenSearch) ─────────────────────────────
+
+/**
+ * Create an IAM role for the Direct Query Service to access AMP.
+ * Trust policy allows directquery.opensearchservice.amazonaws.com to assume it.
+ */
+export async function createDqsPrometheusRole(cfg) {
+  const roleName = cfg.dqsRoleName;
+  printStep(`Creating DQS Prometheus role '${roleName}'...`);
+
+  const client = new IAMClient({ region: cfg.region });
+
+  // Check if role already exists
+  try {
+    const existing = await client.send(new GetRoleCommand({ RoleName: roleName }));
+    cfg.dqsRoleArn = existing.Role.Arn;
+    printSuccess(`DQS role already exists: ${cfg.dqsRoleArn}`);
+    return;
+  } catch (err) {
+    if (err.name !== 'NoSuchEntityException') throw err;
+  }
+
+  const trustPolicy = JSON.stringify({
+    Version: '2012-10-17',
+    Statement: [{
+      Effect: 'Allow',
+      Principal: { Service: 'directquery.opensearchservice.amazonaws.com' },
+      Action: 'sts:AssumeRole',
+    }],
+  });
+
+  try {
+    const result = await client.send(new CreateRoleCommand({
+      RoleName: roleName,
+      AssumeRolePolicyDocument: trustPolicy,
+      Tags: stackTags(cfg.pipelineName),
+    }));
+    cfg.dqsRoleArn = result.Role.Arn;
+    printSuccess(`DQS role created: ${cfg.dqsRoleArn}`);
+  } catch (err) {
+    printError('Failed to create DQS Prometheus role');
+    console.error(`  ${chalk.dim(err.message)}`);
+    console.error();
+    throw new Error('Failed to create DQS Prometheus role');
+  }
+
+  // Attach APS access policy
+  const apsWorkspaceArn = `arn:aws:aps:${cfg.region}:${cfg.accountId}:workspace/${cfg.apsWorkspaceId}`;
+  const permissionsPolicy = JSON.stringify({
+    Version: '2012-10-17',
+    Statement: [{ Effect: 'Allow', Action: 'aps:*', Resource: apsWorkspaceArn }],
+  });
+
+  try {
+    await client.send(new PutRolePolicyCommand({
+      RoleName: roleName,
+      PolicyName: 'APSAccess',
+      PolicyDocument: permissionsPolicy,
+    }));
+    printSuccess('APS access policy attached to DQS role');
+  } catch (err) {
+    printError('Failed to attach APS policy to DQS role');
+    console.error(`  ${chalk.dim(err.message)}`);
+    console.error();
+    throw new Error('Failed to attach APS policy to DQS role');
+  }
+
+  await sleep(5000);
+}
+
+/**
+ * Create a Direct Query Data Source connecting OpenSearch to AMP (Prometheus).
+ * Uses the OpenSearch service control plane API.
+ */
+export async function createDirectQueryDataSource(cfg) {
+  const dataSourceName = cfg.dqsDataSourceName;
+  printStep(`Creating Direct Query data source '${dataSourceName}'...`);
+
+  const client = new OpenSearchClient({ region: cfg.region });
+  const workspaceArn = `arn:aws:aps:${cfg.region}:${cfg.accountId}:workspace/${cfg.apsWorkspaceId}`;
+
+  try {
+    const result = await client.send(new AddDirectQueryDataSourceCommand({
+      DataSourceName: dataSourceName,
+      DataSourceType: {
+        Prometheus: {
+          RoleArn: cfg.dqsRoleArn,
+          WorkspaceArn: workspaceArn,
+        },
+      },
+      Description: `Prometheus data source for ${cfg.pipelineName} observability stack`,
+    }));
+    cfg.dqsDataSourceArn = result.DataSourceArn;
+    printSuccess(`Direct Query data source created: ${cfg.dqsDataSourceArn}`);
+    await tagResource(cfg.region, cfg.dqsDataSourceArn, cfg.pipelineName);
+  } catch (err) {
+    // Treat "already exists" as success
+    if (/already exists/i.test(err.message) || err.name === 'ResourceAlreadyExistsException') {
+      cfg.dqsDataSourceArn = `arn:aws:opensearch:${cfg.region}:${cfg.accountId}:datasource/${dataSourceName}`;
+      printSuccess(`Data source '${dataSourceName}' already exists`);
+      return;
+    }
+    printError('Failed to create Direct Query data source');
+    console.error(`  ${chalk.dim(err.message)}`);
+    console.error();
+    throw new Error('Failed to create Direct Query data source');
+  }
+}
+
+/**
+ * Create an OpenSearch Application (the new OpenSearch UI) and associate
+ * the OpenSearch domain/collection and the DQS data source with it.
+ */
+export async function createOpenSearchApplication(cfg) {
+  const appName = cfg.appName;
+  printStep(`Creating OpenSearch Application '${appName}'...`);
+
+  const client = new OpenSearchClient({ region: cfg.region });
+
+  // Check if app already exists
+  try {
+    const list = await client.send(new ListApplicationsCommand({}));
+    const existing = (list.ApplicationSummaries || []).find((a) => a.name === appName);
+    if (existing) {
+      cfg.appId = existing.id;
+      printSuccess(`Application '${appName}' already exists (id: ${cfg.appId})`);
+      await fetchAppEndpoint(client, cfg);
+      // Update data sources on existing app
+      await associateDataSourcesWithApp(cfg, client);
+      return;
+    }
+  } catch { /* proceed to create */ }
+
+  // Build data sources list
+  const dataSources = buildAppDataSources(cfg);
+
+  try {
+    const result = await client.send(new CreateApplicationCommand({
+      name: appName,
+      dataSources,
+      appConfigs: [
+        {
+          key: 'opensearchDashboards.dashboardAdmin.users',
+          value: JSON.stringify(['*']),
+        },
+      ],
+      iamIdentityCenterOptions: {
+        enabled: false,
+      },
+    }));
+    cfg.appId = result.id;
+    printSuccess(`Application created: ${cfg.appId}`);
+    if (result.arn) {
+      await tagResource(cfg.region, result.arn, cfg.pipelineName);
+    }
+    await fetchAppEndpoint(client, cfg);
+  } catch (err) {
+    if (/already exists/i.test(err.message) || err.name === 'ResourceAlreadyExistsException' || err.name === 'ConflictException') {
+      printSuccess(`Application '${appName}' already exists`);
+      // Try to find and update it
+      try {
+        const list = await client.send(new ListApplicationsCommand({}));
+        const existing = (list.ApplicationSummaries || []).find((a) => a.name === appName);
+        if (existing) {
+          cfg.appId = existing.id;
+          await fetchAppEndpoint(client, cfg);
+          await associateDataSourcesWithApp(cfg, client);
+        }
+      } catch { /* best effort */ }
+      return;
+    }
+    printWarning(`Could not create OpenSearch Application: ${err.message}`);
+    printInfo('You can create one manually in the AWS console');
+  }
+}
+
+/**
+ * Fetch the application endpoint via GetApplicationCommand.
+ */
+async function fetchAppEndpoint(client, cfg) {
+  if (!cfg.appId) return;
+  try {
+    const resp = await client.send(new GetApplicationCommand({ id: cfg.appId }));
+    cfg.appEndpoint = resp.endpoint || '';
+    // endpoint logged by setupDashboards
+  } catch { /* best effort */ }
+}
+
+/**
+ * Build the data sources list for application create/update.
+ */
+function buildAppDataSources(cfg) {
+  const dataSources = [];
+  if (cfg.serverless) {
+    const collectionId = extractServerlessCollectionId(cfg.opensearchEndpoint);
+    if (collectionId) {
+      dataSources.push({
+        dataSourceArn: `arn:aws:aoss:${cfg.region}:${cfg.accountId}:collection/${collectionId}`,
+      });
+    }
+  } else if (cfg.osDomainName) {
+    dataSources.push({
+      dataSourceArn: `arn:aws:es:${cfg.region}:${cfg.accountId}:domain/${cfg.osDomainName}`,
+    });
+  }
+  if (cfg.dqsDataSourceArn) {
+    dataSources.push({ dataSourceArn: cfg.dqsDataSourceArn });
+  }
+  return dataSources;
+}
+
+/**
+ * Associate the OpenSearch domain and DQS data source with the application.
+ */
+async function associateDataSourcesWithApp(cfg, client) {
+  if (!cfg.appId) return;
+
+  const dataSources = buildAppDataSources(cfg);
+  if (dataSources.length === 0) return;
+
+  try {
+    await client.send(new UpdateApplicationCommand({
+      id: cfg.appId,
+      dataSources,
+    }));
+    printSuccess('Data sources associated with application');
+  } catch (err) {
+    printWarning(`Could not associate data sources: ${err.message}`);
+  }
+}
+
+/**
+ * Extract serverless collection ID from endpoint URL.
+ * Endpoint format: https://<id>.<region>.aoss.amazonaws.com
+ */
+function extractServerlessCollectionId(endpoint) {
+  const match = endpoint?.match(/https?:\/\/([^.]+)\./);
+  return match?.[1] || '';
 }
 
 // ── Resource listing (for interactive reuse selection) ──────────────────────
@@ -710,6 +1093,20 @@ export async function listWorkspaces(region) {
     }));
 }
 
+/**
+ * List OpenSearch Applications in the given region.
+ * Returns [{ name, id, endpoint }].
+ */
+export async function listApplications(region) {
+  const client = new OpenSearchClient({ region });
+  const resp = await client.send(new ListApplicationsCommand({}));
+  return (resp.ApplicationSummaries || []).map((a) => ({
+    name: a.name,
+    id: a.id,
+    endpoint: a.endpoint || '',
+  }));
+}
+
 // ── Pipeline listing / describe / update ─────────────────────────────────────
 
 /**
@@ -729,74 +1126,296 @@ export async function listPipelines(region) {
   }));
 }
 
+
 /**
- * Get full details of a single OSI pipeline.
+ * Get the OTLP ingest endpoint URL for an OSI pipeline.
  */
-export async function getPipeline(region, pipelineName) {
+export async function getPipelineEndpoint(region, pipelineName) {
   const client = new OSISClient({ region });
   const resp = await client.send(new GetPipelineCommand({ PipelineName: pipelineName }));
-  const p = resp.Pipeline;
-  return {
-    name: p.PipelineName,
-    arn: p.PipelineArn,
-    status: p.Status,
-    statusReason: p.StatusReason?.Description,
-    minUnits: p.MinUnits,
-    maxUnits: p.MaxUnits,
-    ingestEndpoints: p.IngestEndpointUrls || [],
-    createdAt: p.CreatedAt,
-    lastUpdatedAt: p.LastUpdatedAt,
-    pipelineConfigurationBody: p.PipelineConfigurationBody,
-    logPublishingOptions: p.LogPublishingOptions,
-    bufferOptions: p.BufferOptions,
-  };
+  const urls = resp.Pipeline?.IngestEndpointUrls;
+  return urls?.length ? urls[0] : null;
 }
 
+// ── Stack discovery (tag-based) ──────────────────────────────────────────────
+
 /**
- * Update an OSI pipeline.
- * @param {string} region
- * @param {string} pipelineName
- * @param {{ minUnits?: number, maxUnits?: number, pipelineConfigurationBody?: string, logPublishingOptions?: object, bufferOptions?: object }} params
+ * Tag a resource after creation using the Resource Groups Tagging API.
+ * Best-effort — failures are silently ignored.
  */
-export async function updatePipeline(region, pipelineName, params) {
-  const client = new OSISClient({ region });
+export async function tagResource(region, arn, stackName) {
+  try {
+    const client = new ResourceGroupsTaggingAPIClient({ region });
+    await client.send(new TagResourcesCommand({
+      ResourceARNList: [arn],
+      Tags: { [TAG_KEY]: stackName },
+    }));
+  } catch { /* best effort */ }
+}
 
-  const cmd = { PipelineName: pipelineName };
-  if (params.minUnits != null) cmd.MinUnits = params.minUnits;
-  if (params.maxUnits != null) cmd.MaxUnits = params.maxUnits;
-  if (params.pipelineConfigurationBody != null) cmd.PipelineConfigurationBody = params.pipelineConfigurationBody;
-  if (params.logPublishingOptions != null) cmd.LogPublishingOptions = params.logPublishingOptions;
-  if (params.bufferOptions != null) cmd.BufferOptions = params.bufferOptions;
+/**
+ * List all open-stack stacks in a region by querying the Resource Groups Tagging API.
+ * Returns [{ name, resources: [{ arn, type }] }] grouped by stack name.
+ */
+export async function listStacks(region) {
+  const client = new ResourceGroupsTaggingAPIClient({ region });
+  const stacks = new Map();
 
-  await client.send(new UpdatePipelineCommand(cmd));
+  let paginationToken;
+  do {
+    const resp = await client.send(new GetResourcesCommand({
+      TagFilters: [{ Key: TAG_KEY }],
+      PaginationToken: paginationToken || undefined,
+    }));
 
-  // Poll for update completion
-  const spinner = createSpinner('Waiting for pipeline update...');
-  spinner.start();
-  const maxWait = 300_000;
-  const start = Date.now();
+    for (const r of resp.ResourceTagMappingList || []) {
+      const tag = (r.Tags || []).find((t) => t.Key === TAG_KEY);
+      if (!tag) continue;
+      const stackName = tag.Value;
+      if (!stacks.has(stackName)) {
+        stacks.set(stackName, []);
+      }
+      stacks.get(stackName).push({
+        arn: r.ResourceARN,
+        type: arnToType(r.ResourceARN),
+      });
+    }
 
-  while (Date.now() - start < maxWait) {
+    paginationToken = resp.PaginationToken;
+  } while (paginationToken);
+
+  // Supplement with OpenSearch Applications (may not appear in tagging API)
+  await supplementApplications(region, stacks);
+
+  return [...stacks.entries()].map(([name, resources]) => ({ name, resources }));
+}
+
+/**
+ * Get all resources for a specific stack by its tag value.
+ * Returns [{ arn, type }].
+ */
+export async function getStackResources(region, stackName) {
+  const client = new ResourceGroupsTaggingAPIClient({ region });
+  const resources = [];
+
+  let paginationToken;
+  do {
+    const resp = await client.send(new GetResourcesCommand({
+      TagFilters: [{ Key: TAG_KEY, Values: [stackName] }],
+      PaginationToken: paginationToken || undefined,
+    }));
+
+    for (const r of resp.ResourceTagMappingList || []) {
+      resources.push({
+        arn: r.ResourceARN,
+        type: arnToType(r.ResourceARN),
+      });
+    }
+
+    paginationToken = resp.PaginationToken;
+  } while (paginationToken);
+
+  // Supplement with OpenSearch Application if not already present
+  const stacks = new Map([[stackName, resources]]);
+  await supplementApplications(region, stacks);
+
+  return resources;
+}
+
+/**
+ * Map an ARN to a human-readable resource type.
+ */
+function arnToType(arn) {
+  if (/^arn:aws:osis:/.test(arn)) return 'OSI Pipeline';
+  if (/^arn:aws:aoss:.*:collection\//.test(arn)) return 'OpenSearch Serverless';
+  if (/^arn:aws:es:.*:domain\//.test(arn)) return 'OpenSearch Domain';
+  if (/^arn:aws:iam:.*:role\//.test(arn)) return 'IAM Role';
+  if (/^arn:aws:aps:.*:workspace\//.test(arn)) return 'APS Workspace';
+  if (/^arn:aws:opensearch:.*:datasource\//.test(arn)) return 'DQ Data Source';
+  if (/^arn:aws:opensearch:.*:application\//.test(arn)) return 'OpenSearch Application';
+  if (/^arn:aws:eks:.*:cluster\//.test(arn)) return 'EKS Cluster';
+  return 'Resource';
+}
+
+/**
+ * Extract the resource name from an ARN.
+ */
+export function arnToName(arn) {
+  // IAM roles: arn:aws:iam::123:role/role-name
+  const iamMatch = arn.match(/:role\/(.+)$/);
+  if (iamMatch) return iamMatch[1];
+  // Most others: .../{name} or ...:<name>
+  const lastSlash = arn.lastIndexOf('/');
+  if (lastSlash !== -1) return arn.slice(lastSlash + 1);
+  const lastColon = arn.lastIndexOf(':');
+  if (lastColon !== -1) return arn.slice(lastColon + 1);
+  return arn;
+}
+
+/**
+ * Enrich resource objects with display names where the ARN-derived name is not
+ * human-friendly (e.g. APS workspace IDs → aliases, application IDs → names).
+ */
+export async function enrichResourceNames(region, resources) {
+  // APS workspaces: resolve alias
+  const apsResources = resources.filter((r) => r.type === 'APS Workspace');
+  if (apsResources.length) {
+    const client = new AmpClient({ region });
+    for (const r of apsResources) {
+      try {
+        const wsId = arnToName(r.arn);
+        const resp = await client.send(new DescribeWorkspaceCommand({ workspaceId: wsId }));
+        if (resp.workspace?.alias) r.displayName = resp.workspace.alias;
+      } catch { /* keep default */ }
+    }
+  }
+  // OpenSearch Applications: resolve name from ID
+  const appResources = resources.filter((r) => r.type === 'OpenSearch Application');
+  if (appResources.length) {
     try {
-      const resp = await client.send(new GetPipelineCommand({ PipelineName: pipelineName }));
-      const status = resp.Pipeline?.Status;
-      if (status === 'ACTIVE') {
-        spinner.succeed('Pipeline updated successfully');
-        return;
+      const client = new OpenSearchClient({ region });
+      const list = await client.send(new ListApplicationsCommand({}));
+      for (const r of appResources) {
+        const appId = arnToName(r.arn);
+        const app = (list.ApplicationSummaries || []).find((a) => a.id === appId);
+        if (app?.name) r.displayName = app.name;
       }
-      if (status === 'UPDATE_FAILED') {
-        const reason = resp.Pipeline?.StatusReason?.Description || 'unknown';
-        spinner.fail('Pipeline update failed');
-        throw new Error(`Pipeline update failed: ${reason}`);
+    } catch { /* keep default */ }
+  }
+}
+
+/**
+ * Find OpenSearch Applications whose name matches a stack name and add them
+ * to the resource list if not already present (tagging API may not return them).
+ */
+async function supplementApplications(region, stacks) {
+  if (stacks.size === 0) return;
+  try {
+    const client = new OpenSearchClient({ region });
+    const list = await client.send(new ListApplicationsCommand({}));
+    for (const app of list.ApplicationSummaries || []) {
+      if (!app.name || !app.arn) continue;
+      const resources = stacks.get(app.name);
+      if (!resources) continue;
+      const alreadyPresent = resources.some((r) => r.type === 'OpenSearch Application');
+      if (!alreadyPresent) {
+        resources.push({ arn: app.arn, type: 'OpenSearch Application' });
       }
-    } catch (err) {
-      if (err.message.startsWith('Pipeline update failed')) throw err;
     }
-    await sleepWithTicker(10_000, spinner, start,
-      (s) => `Waiting for pipeline update... (${fmtElapsed(s)})`);
+  } catch { /* best effort */ }
+}
+
+/**
+ * Fetch detailed information for a single resource by ARN.
+ * Returns { entries: [[label, value], ...], rawConfig?: string }.
+ */
+export async function describeResource(region, resource) {
+  const { arn, type } = resource;
+  const name = arnToName(arn);
+  const entries = [['ARN', arn]];
+  let rawConfig;
+
+  try {
+    if (type === 'OSI Pipeline') {
+      const client = new OSISClient({ region });
+      const resp = await client.send(new GetPipelineCommand({ PipelineName: name }));
+      const p = resp.Pipeline || {};
+      entries.push(['Status', p.Status || 'Unknown']);
+      if (p.StatusReason?.Message) entries.push(['Status Reason', p.StatusReason.Message]);
+      entries.push(['Min Units', String(p.MinUnits ?? '')]);
+      entries.push(['Max Units', String(p.MaxUnits ?? '')]);
+      if (p.IngestEndpointUrls?.length) {
+        for (const url of p.IngestEndpointUrls) entries.push(['Ingest Endpoint', url]);
+      }
+      if (p.PipelineRoleArn) entries.push(['Role ARN', p.PipelineRoleArn]);
+      if (p.CreatedAt) entries.push(['Created', p.CreatedAt.toISOString()]);
+      if (p.LastUpdatedAt) entries.push(['Last Updated', p.LastUpdatedAt.toISOString()]);
+      if (p.PipelineConfigurationBody) rawConfig = p.PipelineConfigurationBody;
+    } else if (type === 'OpenSearch Serverless') {
+      const client = new OpenSearchServerlessClient({ region });
+      const resp = await client.send(new BatchGetCollectionCommand({ ids: [name] }));
+      const c = (resp.collectionDetails || [])[0] || {};
+      if (c.status) entries.push(['Status', c.status]);
+      if (c.type) entries.push(['Type', c.type]);
+      if (c.collectionEndpoint) entries.push(['Collection Endpoint', c.collectionEndpoint]);
+      if (c.dashboardEndpoint) entries.push(['Dashboard Endpoint', c.dashboardEndpoint]);
+      if (c.description) entries.push(['Description', c.description]);
+      if (c.createdDate) entries.push(['Created', new Date(c.createdDate).toISOString()]);
+      if (c.lastModifiedDate) entries.push(['Last Modified', new Date(c.lastModifiedDate).toISOString()]);
+    } else if (type === 'OpenSearch Domain') {
+      const client = new OpenSearchClient({ region });
+      const resp = await client.send(new DescribeDomainCommand({ DomainName: name }));
+      const d = resp.DomainStatus || {};
+      if (d.EngineVersion) entries.push(['Engine Version', d.EngineVersion]);
+      if (d.Endpoint) entries.push(['Endpoint', `https://${d.Endpoint}`]);
+      if (d.ClusterConfig) {
+        const cc = d.ClusterConfig;
+        if (cc.InstanceType) entries.push(['Instance Type', cc.InstanceType]);
+        entries.push(['Instance Count', String(cc.InstanceCount ?? 1)]);
+      }
+      entries.push(['Processing', String(d.Processing ?? false)]);
+      if (d.Created !== undefined) entries.push(['Created', String(d.Created)]);
+    } else if (type === 'APS Workspace') {
+      const wsId = name;
+      const client = new AmpClient({ region });
+      const resp = await client.send(new DescribeWorkspaceCommand({ workspaceId: wsId }));
+      const w = resp.workspace || {};
+      if (w.status?.statusCode) entries.push(['Status', w.status.statusCode]);
+      if (w.alias) entries.push(['Alias', w.alias]);
+      if (w.prometheusEndpoint) entries.push(['Prometheus Endpoint', w.prometheusEndpoint]);
+      if (w.createdAt) entries.push(['Created', w.createdAt.toISOString()]);
+    } else if (type === 'IAM Role') {
+      const client = new IAMClient({ region });
+      const resp = await client.send(new GetRoleCommand({ RoleName: name }));
+      const r = resp.Role || {};
+      if (r.Description) entries.push(['Description', r.Description]);
+      if (r.Path) entries.push(['Path', r.Path]);
+      if (r.CreateDate) entries.push(['Created', r.CreateDate.toISOString()]);
+      if (r.MaxSessionDuration) entries.push(['Max Session Duration', `${r.MaxSessionDuration}s`]);
+    } else if (type === 'DQ Data Source') {
+      const client = new OpenSearchClient({ region });
+      const resp = await client.send(new GetDirectQueryDataSourceCommand({ DataSourceName: name }));
+      if (resp.DataSourceType) {
+        const typeKey = Object.keys(resp.DataSourceType)[0];
+        if (typeKey) entries.push(['Data Source Type', typeKey]);
+      }
+      if (resp.Description) entries.push(['Description', resp.Description]);
+      if (resp.OpenSearchArns?.length) {
+        for (const a of resp.OpenSearchArns) entries.push(['OpenSearch ARN', a]);
+      }
+    } else if (type === 'OpenSearch Application') {
+      const client = new OpenSearchClient({ region });
+      const appId = name;
+      const resp = await client.send(new GetApplicationCommand({ id: appId }));
+      if (resp.status) entries.push(['Status', resp.status]);
+      if (resp.endpoint) entries.push(['Endpoint', resp.endpoint]);
+      if (resp.dataSources?.length) {
+        for (const ds of resp.dataSources) {
+          if (ds.dataSourceArn) entries.push(['Data Source', ds.dataSourceArn]);
+        }
+      }
+      if (resp.createdAt) entries.push(['Created', resp.createdAt.toISOString()]);
+      if (resp.lastUpdatedAt) entries.push(['Last Updated', resp.lastUpdatedAt.toISOString()]);
+    } else if (type === 'EKS Cluster') {
+      const client = new EKSClient({ region });
+      const resp = await client.send(new DescribeClusterCommand({ name }));
+      const c = resp.cluster || {};
+      if (c.status) entries.push(['Status', c.status]);
+      if (c.version) entries.push(['Kubernetes Version', c.version]);
+      if (c.platformVersion) entries.push(['Platform Version', c.platformVersion]);
+      if (c.endpoint) entries.push(['API Endpoint', c.endpoint]);
+      if (c.roleArn) entries.push(['Role ARN', c.roleArn]);
+      if (c.resourcesVpcConfig) {
+        const vpc = c.resourcesVpcConfig;
+        if (vpc.vpcId) entries.push(['VPC', vpc.vpcId]);
+      }
+      if (c.createdAt) entries.push(['Created', c.createdAt.toISOString()]);
+    }
+  } catch (err) {
+    entries.push(['Error', err.message]);
   }
 
-  spinner.warn('Timed out waiting for update — pipeline may still be updating');
+  return { entries, rawConfig };
 }
 
 // ── Helpers ─────────────────────────────────────────────────────────────────