@superblocksteam/shared 0.9607.2 → 0.9608.0

package/src/database-lifecycle/providerDiagnostics.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from 'vitest';
+
+import { inspectLifecycleProviderDiagnosticCandidate, sanitizeLifecycleProviderDiagnostics } from './index.js';
+
+describe('lifecycle provider diagnostic sanitization', () => {
+  test('derives canonical AWS fields and reports a stripped request ID', () => {
+    expect(
+      inspectLifecycleProviderDiagnosticCandidate({
+        errorCode: 'AccessDenied',
+        nextAction: 'untrusted-action',
+        operation: 'CreateDBCluster',
+        phase: 'future-phase',
+        provider: 'aws',
+        requestId: 'not-a-request-id',
+        retryable: false,
+        service: 'rds',
+        summary: 'provider-authored text'
+      })
+    ).toEqual({
+      diagnostic: {
+        errorCode: 'AccessDenied',
+        nextAction: 'review_aws_operation',
+        operation: 'CreateDBCluster',
+        phase: 'unknown',
+        provider: 'aws',
+        retryable: false,
+        service: 'rds'
+      },
+      provider: 'aws',
+      sanitizedFields: ['requestId']
+    });
+  });
+
+  test.each([
+    ['rds', 'CreateDBCluster', 'AccessDenied', '123e4567-e89b-12d3-a456-426614174000'],
+    ['s3', 'CreateBucket', 'AccessDenied', 'A1B2C3D4E5F6G7H8'],
+    ['dynamodb', 'CreateTable', 'AccessDeniedException', 'A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6']
+  ])('preserves a valid %s request ID', (service, operation, errorCode, requestId) => {
+    expect(
+      inspectLifecycleProviderDiagnosticCandidate({
+        errorCode,
+        operation,
+        phase: 'apply',
+        provider: 'aws',
+        requestId,
+        retryable: false,
+        service
+      })
+    ).toEqual({
+      diagnostic: {
+        errorCode,
+        nextAction: 'review_aws_operation',
+        operation,
+        phase: 'apply',
+        provider: 'aws',
+        requestId,
+        retryable: false,
+        service
+      },
+      provider: 'aws'
+    });
+  });
+
+  test('does not apply service-specific request ID formats to unrelated services', () => {
+    expect(
+      inspectLifecycleProviderDiagnosticCandidate({
+        errorCode: 'AccessDenied',
+        operation: 'CreateDBCluster',
+        phase: 'apply',
+        provider: 'aws',
+        requestId: 'A1B2C3D4E5F6G7H8',
+        retryable: false,
+        service: 'rds'
+      })
+    ).toEqual({
+      diagnostic: {
+        errorCode: 'AccessDenied',
+        nextAction: 'review_aws_operation',
+        operation: 'CreateDBCluster',
+        phase: 'apply',
+        provider: 'aws',
+        retryable: false,
+        service: 'rds'
+      },
+      provider: 'aws',
+      sanitizedFields: ['requestId']
+    });
+  });
+
+  test('reports rejected provider fields without retaining input text', () => {
+    expect(
+      inspectLifecycleProviderDiagnosticCandidate({
+        errorCode: 'Access Denied',
+        operation: 'Create DB Cluster',
+        provider: 'aws',
+        retryable: 'false',
+        service: 'RDS'
+      })
+    ).toEqual({
+      provider: 'aws',
+      rejectedFields: ['errorCode', 'operation', 'retryable', 'service']
+    });
+  });
+
+  test('applies the persistence cap after validation', () => {
+    const valid = {
+      nextAction: 'ignored',
+      phase: 'apply',
+      provider: 'postgresql',
+      retryable: false,
+      sqlState: '28P01'
+    };
+
+    expect(
+      sanitizeLifecycleProviderDiagnostics([
+        { provider: 'postgresql', sqlState: 'invalid' },
+        valid,
+        { ...valid, sqlState: '42P07' },
+        { ...valid, sqlState: '08006' },
+        { ...valid, sqlState: '42501' }
+      ])
+    ).toEqual([
+      { nextAction: 'review_database_operation', phase: 'apply', provider: 'postgresql', retryable: false, sqlState: '28P01' },
+      { nextAction: 'review_database_operation', phase: 'apply', provider: 'postgresql', retryable: false, sqlState: '42P07' },
+      { nextAction: 'review_database_operation', phase: 'apply', provider: 'postgresql', retryable: false, sqlState: '08006' }
+    ]);
+  });
+
+  test('treats non-array payloads and arrays without valid entries as absent', () => {
+    expect(sanitizeLifecycleProviderDiagnostics(null)).toBeUndefined();
+    expect(sanitizeLifecycleProviderDiagnostics({ provider: 'aws' })).toBeUndefined();
+    expect(sanitizeLifecycleProviderDiagnostics([{ provider: 'unknown' }])).toBeUndefined();
+  });
+});

package/src/environment-compatibility/appEnvironmentCompatibility.test.ts

@@ -0,0 +1,326 @@
+import { describe, expect, it } from 'vitest';
+
+import type { AppDatabaseCompatibility } from '../database-lifecycle/appDatabaseCompatibility.js';
+import { ViewMode } from '../types/event/index.js';
+import {
+  getAppDatabaseRemediationActions,
+  getIntegrationRemediationActions,
+  rollUpAppEnvironmentCompatibility,
+  summarizeIntegrationConfigurations,
+  summarizeIntegrationCoverage
+} from './appEnvironmentCompatibility.js';
+
+const compatibleAppDatabase: AppDatabaseCompatibility = {
+  applicationId: 'application-id',
+  hasAppDatabase: true,
+  needsAttention: false,
+  overallState: 'compatible',
+  tags: []
+};
+
+describe('app Environment compatibility contract', () => {
+  it('summarizes configured integration data tags and default fallback', () => {
+    expect(
+      summarizeIntegrationConfigurations([
+        { isDefault: false, profileNames: ['staging', 'production'] },
+        { isDefault: false, profileNames: ['staging'] },
+        { isDefault: true }
+      ])
+    ).toEqual({
+      hasDefaultConfiguration: true,
+      supportedProfileKeys: ['production', 'staging']
+    });
+    expect(summarizeIntegrationConfigurations([])).toEqual({
+      hasDefaultConfiguration: false,
+      supportedProfileKeys: []
+    });
+  });
+
+  it('marks integration gaps as warnings without blocking', () => {
+    expect(
+      rollUpAppEnvironmentCompatibility({
+        appDatabase: compatibleAppDatabase,
+        integrations: [
+          {
+            integrationId: 'integration-id',
+            integrationName: 'Warehouse',
+            mismatchedAppProfileKeys: ['production'],
+            pluginId: 'postgres',
+            supportedProfileKeys: [],
+            tags: [
+              {
+                availableModes: [ViewMode.DEPLOYED],
+                profileId: 'profile-id',
+                profileKey: 'production',
+                remediationActions: ['configure_integration', 'change_app_environment'],
+                state: 'none'
+              }
+            ]
+          }
+        ]
+      })
+    ).toEqual({
+      isBlocking: false,
+      needsAttention: true,
+      overallState: 'warning',
+      remediationActions: ['change_app_environment', 'configure_integration']
+    });
+  });
+
+  it('keeps App Database incompatibility blocking when integrations are compatible', () => {
+    expect(
+      rollUpAppEnvironmentCompatibility({
+        appDatabase: {
+          ...compatibleAppDatabase,
+          needsAttention: true,
+          overallState: 'incompatible'
+        },
+        integrations: []
+      })
+    ).toEqual({
+      isBlocking: true,
+      needsAttention: true,
+      overallState: 'blocked',
+      remediationActions: []
+    });
+  });
+
+  it('does not block environment changes when the app has no App Database', () => {
+    expect(
+      rollUpAppEnvironmentCompatibility({
+        appDatabase: {
+          ...compatibleAppDatabase,
+          hasAppDatabase: false,
+          needsAttention: true,
+          overallState: 'incompatible'
+        },
+        appDatabaseRemediationActions: getAppDatabaseRemediationActions('incompatible', true),
+        integrations: []
+      })
+    ).toEqual({
+      isBlocking: false,
+      needsAttention: false,
+      overallState: 'compatible',
+      remediationActions: []
+    });
+  });
+
+  it('blocks a temporarily unavailable App Database, matching the server gate', () => {
+    expect(
+      rollUpAppEnvironmentCompatibility({
+        appDatabase: {
+          ...compatibleAppDatabase,
+          overallState: 'temporarily_unavailable'
+        },
+        appDatabaseRemediationActions: getAppDatabaseRemediationActions('temporarily_unavailable', true),
+        integrations: []
+      })
+    ).toEqual({
+      isBlocking: true,
+      needsAttention: true,
+      overallState: 'blocked',
+      remediationActions: ['retry_later']
+    });
+  });
+
+  it('keeps a temporarily unavailable integration tag a non-blocking warning', () => {
+    expect(
+      rollUpAppEnvironmentCompatibility({
+        appDatabase: compatibleAppDatabase,
+        integrations: [
+          {
+            integrationId: 'integration-id',
+            integrationName: 'Warehouse',
+            mismatchedAppProfileKeys: ['production'],
+            pluginId: 'postgres',
+            supportedProfileKeys: [],
+            tags: [
+              {
+                availableModes: [ViewMode.DEPLOYED],
+                profileId: 'profile-id',
+                profileKey: 'production',
+                remediationActions: ['retry_later'],
+                state: 'temporarily_unavailable'
+              }
+            ]
+          }
+        ]
+      })
+    ).toEqual({
+      isBlocking: false,
+      needsAttention: true,
+      overallState: 'warning',
+      remediationActions: ['retry_later']
+    });
+  });
+
+  it('does not surface remediations for organization tags the app does not use', () => {
+    expect(
+      rollUpAppEnvironmentCompatibility({
+        appDatabase: compatibleAppDatabase,
+        integrations: [
+          {
+            integrationId: 'integration-id',
+            integrationName: 'Warehouse',
+            mismatchedAppProfileKeys: [],
+            pluginId: 'postgres',
+            supportedProfileKeys: [],
+            tags: [
+              {
+                availableModes: [],
+                profileId: 'unused-id',
+                profileKey: 'unused',
+                remediationActions: ['change_app_environment', 'configure_integration'],
+                state: 'none'
+              }
+            ]
+          }
+        ]
+      })
+    ).toEqual({
+      isBlocking: false,
+      needsAttention: false,
+      overallState: 'compatible',
+      remediationActions: []
+    });
+  });
+
+  it('reports a temporary integration read failure as a non-blocking warning', () => {
+    expect(
+      rollUpAppEnvironmentCompatibility({
+        appDatabase: compatibleAppDatabase,
+        integrationReadState: 'temporarily_unavailable',
+        integrations: []
+      })
+    ).toEqual({
+      isBlocking: false,
+      needsAttention: true,
+      overallState: 'warning',
+      remediationActions: ['retry_later']
+    });
+  });
+
+  it('deduplicates and sorts server-provided remediation actions', () => {
+    expect(
+      rollUpAppEnvironmentCompatibility({
+        appDatabase: compatibleAppDatabase,
+        integrations: [
+          {
+            integrationId: 'integration-id',
+            integrationName: 'Warehouse',
+            mismatchedAppProfileKeys: ['production'],
+            pluginId: 'postgres',
+            supportedProfileKeys: [],
+            tags: [
+              {
+                availableModes: [ViewMode.DEPLOYED],
+                profileId: 'first-profile',
+                profileKey: 'production',
+                remediationActions: ['configure_integration', 'request_environment_access'],
+                state: 'none'
+              },
+              {
+                availableModes: [ViewMode.EDITOR],
+                profileId: 'second-profile',
+                profileKey: 'staging',
+                remediationActions: ['retry_later', 'configure_integration'],
+                state: 'temporarily_unavailable'
+              }
+            ]
+          }
+        ]
+      }).remediationActions
+    ).toEqual(['configure_integration', 'request_environment_access', 'retry_later']);
+  });
+
+  it('treats default-fallback tags as supported because the integration still works', () => {
+    expect(
+      summarizeIntegrationCoverage([
+        {
+          availableModes: [ViewMode.EDITOR],
+          profileId: 'staging-id',
+          profileKey: 'staging',
+          remediationActions: [],
+          state: 'exact'
+        },
+        {
+          availableModes: [ViewMode.DEPLOYED],
+          profileId: 'production-id',
+          profileKey: 'production',
+          remediationActions: [],
+          state: 'default_fallback'
+        },
+        {
+          availableModes: [],
+          profileId: 'prod-eu-id',
+          profileKey: 'prod-eu',
+          remediationActions: [],
+          state: 'exact'
+        },
+        {
+          availableModes: [ViewMode.PREVIEW],
+          profileId: 'preview-id',
+          profileKey: 'preview',
+          remediationActions: ['configure_integration'],
+          state: 'none'
+        },
+        {
+          availableModes: [],
+          profileId: 'unused-id',
+          profileKey: 'unused',
+          remediationActions: [],
+          state: 'none'
+        }
+      ])
+    ).toEqual({
+      mismatchedAppProfileKeys: ['preview'],
+      supportedProfileKeys: ['prod-eu', 'production', 'staging']
+    });
+  });
+
+  it('does not warn when an app tag uses the integration default configuration', () => {
+    expect(
+      rollUpAppEnvironmentCompatibility({
+        appDatabase: compatibleAppDatabase,
+        integrations: [
+          {
+            integrationId: 'integration-id',
+            integrationName: 'Warehouse',
+            mismatchedAppProfileKeys: [],
+            pluginId: 'postgres',
+            supportedProfileKeys: ['production'],
+            tags: [
+              {
+                availableModes: [ViewMode.DEPLOYED],
+                profileId: 'production-id',
+                profileKey: 'production',
+                remediationActions: [],
+                state: 'default_fallback'
+              }
+            ]
+          }
+        ]
+      })
+    ).toEqual({
+      isBlocking: false,
+      needsAttention: false,
+      overallState: 'compatible',
+      remediationActions: []
+    });
+  });
+
+  it('returns only failure-specific integration remediation actions', () => {
+    expect(getIntegrationRemediationActions('exact', true)).toEqual([]);
+    expect(getIntegrationRemediationActions('default_fallback', true)).toEqual([]);
+    expect(getIntegrationRemediationActions('none', true)).toEqual(['change_app_environment', 'configure_integration']);
+    expect(getIntegrationRemediationActions('none', false)).toEqual(['configure_integration', 'request_environment_access']);
+    expect(getIntegrationRemediationActions('temporarily_unavailable', true)).toEqual(['retry_later']);
+  });
+
+  it('returns only failure-specific App Database remediation actions', () => {
+    expect(getAppDatabaseRemediationActions('compatible', true)).toEqual([]);
+    expect(getAppDatabaseRemediationActions('incompatible', true)).toEqual(['change_app_environment', 'connect_lifecycle_agent']);
+    expect(getAppDatabaseRemediationActions('incompatible', false)).toEqual(['connect_lifecycle_agent', 'request_environment_access']);
+    expect(getAppDatabaseRemediationActions('temporarily_unavailable', true)).toEqual(['retry_later']);
+  });
+});

package/src/environment-compatibility/appEnvironmentCompatibility.ts

@@ -0,0 +1,173 @@
+import type { AppDatabaseCompatibility, AppDatabaseCompatibilityState } from '../database-lifecycle/appDatabaseCompatibility.js';
+import type { ViewMode } from '../types/event/index.js';
+
+export type AppEnvironmentRemediationAction =
+  | 'change_app_environment'
+  | 'configure_integration'
+  | 'connect_lifecycle_agent'
+  | 'request_environment_access'
+  | 'retry_later';
+export const APP_ENVIRONMENT_REMEDIATION_ACTIONS: readonly AppEnvironmentRemediationAction[] = [
+  'change_app_environment',
+  'configure_integration',
+  'connect_lifecycle_agent',
+  'request_environment_access',
+  'retry_later'
+];
+
+export type IntegrationCompatibilityState = 'default_fallback' | 'exact' | 'none' | 'temporarily_unavailable';
+export const INTEGRATION_COMPATIBILITY_STATES: readonly IntegrationCompatibilityState[] = [
+  'default_fallback',
+  'exact',
+  'none',
+  'temporarily_unavailable'
+];
+
+export type IntegrationCompatibilityReadState = 'available' | 'temporarily_unavailable';
+export const INTEGRATION_COMPATIBILITY_READ_STATES: readonly IntegrationCompatibilityReadState[] = ['available', 'temporarily_unavailable'];
+
+export type AppEnvironmentCompatibilityState = 'blocked' | 'compatible' | 'warning';
+export const APP_ENVIRONMENT_COMPATIBILITY_STATES: readonly AppEnvironmentCompatibilityState[] = ['blocked', 'compatible', 'warning'];
+
+export type IntegrationTagCompatibility = {
+  availableModes: ViewMode[];
+  profileId: string;
+  profileKey: string;
+  remediationActions: AppEnvironmentRemediationAction[];
+  state: IntegrationCompatibilityState;
+};
+
+export type AppEnvironmentDataTag = {
+  availableModes: ViewMode[];
+  profileId: string;
+  profileKey: string;
+};
+
+export type OrganizationEnvironmentDataTag = {
+  displayName: string;
+  profileId: string;
+  profileKey: string;
+};
+
+export type IntegrationCompatibility = {
+  integrationId: string;
+  integrationName: string;
+  mismatchedAppProfileKeys: string[];
+  pluginId: string;
+  supportedProfileKeys: string[];
+  tags: IntegrationTagCompatibility[];
+};
+
+export type AppEnvironmentCompatibility = {
+  appDatabase: AppDatabaseCompatibility;
+  appDataTags: AppEnvironmentDataTag[];
+  applicationId: string;
+  canManageEnvironments: boolean;
+  integrationReadState: IntegrationCompatibilityReadState;
+  integrations: IntegrationCompatibility[];
+  isBlocking: boolean;
+  needsAttention: boolean;
+  organizationDataTags: OrganizationEnvironmentDataTag[];
+  overallState: AppEnvironmentCompatibilityState;
+  remediationActions: AppEnvironmentRemediationAction[];
+};
+
+export function summarizeIntegrationConfigurations(
+  configurations: readonly {
+    isDefault: boolean;
+    profileNames?: readonly string[];
+  }[]
+): {
+  hasDefaultConfiguration: boolean;
+  supportedProfileKeys: string[];
+} {
+  return {
+    hasDefaultConfiguration: configurations.some((configuration) => configuration.isDefault),
+    supportedProfileKeys: [...new Set(configurations.flatMap((configuration) => configuration.profileNames ?? []))].sort()
+  };
+}
+
+export function summarizeIntegrationCoverage(
+  tags: readonly IntegrationTagCompatibility[]
+): Pick<IntegrationCompatibility, 'mismatchedAppProfileKeys' | 'supportedProfileKeys'> {
+  return {
+    mismatchedAppProfileKeys: tags
+      .filter((tag) => tag.availableModes.length > 0 && tag.state !== 'exact' && tag.state !== 'default_fallback')
+      .map((tag) => tag.profileKey)
+      .sort(),
+    supportedProfileKeys: tags
+      .filter((tag) => tag.state === 'exact' || tag.state === 'default_fallback')
+      .map((tag) => tag.profileKey)
+      .sort()
+  };
+}
+
+export function getIntegrationRemediationActions(
+  state: IntegrationCompatibilityState,
+  canManageEnvironments: boolean
+): AppEnvironmentRemediationAction[] {
+  if (state === 'exact' || state === 'default_fallback') {
+    return [];
+  }
+  if (state === 'temporarily_unavailable') {
+    return ['retry_later'];
+  }
+  return canManageEnvironments
+    ? ['change_app_environment', 'configure_integration']
+    : ['configure_integration', 'request_environment_access'];
+}
+
+export function getAppDatabaseRemediationActions(
+  state: AppDatabaseCompatibilityState,
+  canManageEnvironments: boolean
+): AppEnvironmentRemediationAction[] {
+  if (state === 'compatible') {
+    return [];
+  }
+  if (state === 'temporarily_unavailable') {
+    return ['retry_later'];
+  }
+  return canManageEnvironments
+    ? ['change_app_environment', 'connect_lifecycle_agent']
+    : ['connect_lifecycle_agent', 'request_environment_access'];
+}
+
+export function rollUpAppEnvironmentCompatibility({
+  appDatabase,
+  appDatabaseRemediationActions = [],
+  integrationReadState = 'available',
+  integrations
+}: {
+  appDatabase: AppDatabaseCompatibility;
+  appDatabaseRemediationActions?: AppEnvironmentRemediationAction[];
+  integrationReadState?: IntegrationCompatibilityReadState;
+  integrations: readonly IntegrationCompatibility[];
+}): Pick<AppEnvironmentCompatibility, 'isBlocking' | 'needsAttention' | 'overallState' | 'remediationActions'> {
+  const integrationNeedsAttention = integrations.some((integration) =>
+    integration.tags.some((tag) => tag.state === 'temporarily_unavailable' || (tag.availableModes.length > 0 && tag.state === 'none'))
+  );
+  // The settings write only refuses App Database apps. An unserved data tag on
+  // an ordinary app is not a block, so previewing it as one would stop a change
+  // the server would accept.
+  const appDatabaseBlocks = appDatabase.hasAppDatabase && appDatabase.overallState !== 'compatible';
+  const isBlocking = appDatabaseBlocks;
+  const needsAttention = appDatabaseBlocks || integrationNeedsAttention || integrationReadState === 'temporarily_unavailable';
+  const readRemediationActions: AppEnvironmentRemediationAction[] =
+    integrationReadState === 'temporarily_unavailable' ? ['retry_later'] : [];
+  const remediationActions = [
+    ...new Set([
+      ...(appDatabaseBlocks ? appDatabaseRemediationActions : []),
+      ...readRemediationActions,
+      ...integrations.flatMap((integration) =>
+        integration.tags.flatMap((tag) => (tag.availableModes.length > 0 ? tag.remediationActions : []))
+      )
+    ])
+  ].sort();
+
+  return {
+    isBlocking,
+    needsAttention,
+    overallState: isBlocking ? 'blocked' : needsAttention ? 'warning' : 'compatible',
+    remediationActions
+  };
+}

package/src/errors/http.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+
+import { BadGatewayError, GatewayTimeoutError, InternalServerError, RetryableHttpError, ServiceUnavailableError } from './http.js';
+
+describe('GatewayTimeoutError', () => {
+  it('reports 504 so a caller can tell a slow upstream from a broken server', () => {
+    const error = new GatewayTimeoutError('upstream took too long');
+
+    expect(error.status).toBe(504);
+    expect(error.message).toBe('upstream took too long');
+  });
+});
+
+describe('retry hints', () => {
+  const retryableErrors: [number, (retryAfterSeconds?: number) => RetryableHttpError][] = [
+    [502, (retryAfterSeconds) => new BadGatewayError('upstream refused', retryAfterSeconds)],
+    [503, (retryAfterSeconds) => new ServiceUnavailableError('upstream at capacity', retryAfterSeconds)],
+    [504, (retryAfterSeconds) => new GatewayTimeoutError('upstream took too long', retryAfterSeconds)]
+  ];
+
+  it.each(retryableErrors)('a %i carries the seconds a client should wait', (status, build) => {
+    expect(build(7)).toMatchObject({ status, retryAfterSeconds: 7 });
+  });
+
+  it.each(retryableErrors)('a %i without a hint leaves the wait unspecified', (_status, build) => {
+    expect(build().retryAfterSeconds).toBeUndefined();
+  });
+
+  it('never invites a retry of an outright server fault', () => {
+    expect(new InternalServerError('it broke')).not.toBeInstanceOf(RetryableHttpError);
+  });
+});