feat(gateway): reconcile managed gateway API assignments

The built-in 'managed' gateway is not returned by GET /gateways, so its per-API assignments were never extracted, published, or reconciled. This left dev/prod divergence (e.g. an API removed from managed in dev remained assigned in prod).

- extract: query gateways/managed/apis and write gateways/managed/apis.json (only when non-empty)
- publish: skip PUT of the built-in managed Gateway resource (its GatewayApi associations still publish)
- delete-unmatched: reconcile GatewayApi assignments (incl. managed), scoped to gateways that own a local assignment, so untracked gateways are never touched
- add MANAGED_GATEWAY_NAME constant; tests for extract/publish/delete-unmatched

Author: Alexey-Zheltov

src/models/resource-types.ts

@@ -45,6 +45,13 @@ export enum ResourceType {
   Workspace = 'Workspace',
 }
 
+/**
+ * The built-in "managed" gateway id. It is not returned by `GET /gateways`
+ * (which lists only self-hosted/custom gateways), but its per-API assignments
+ * are queryable/manageable at `gateways/managed/apis`.
+ */
+export const MANAGED_GATEWAY_NAME = 'managed';
+
 /**
  * Pure-data descriptor for a single APIM resource type.
  *

src/services/delete-unmatched-service.ts

@@ -123,6 +123,11 @@ export async function computeDeleteActions(
 
   // For each resource type in reverse dependency order
   for (const resourceType of reverseOrder) {
+    // GatewayApi assignments are reconciled by computeGatewayApiDeleteActions
+    // below (they require a parent gateway and cannot be listed generically).
+    if (resourceType === ResourceType.GatewayApi) {
+      continue;
+    }
     try {
       // List all resources of this type in APIM
       const apimResources = client.listResources(context, resourceType);
@@ -177,9 +182,106 @@ export async function computeDeleteActions(
     }
   }
 
+  // Gateway → API assignments cannot be enumerated by the generic loop above
+  // (GatewayApi requires a parent gateway and GET is not supported at the
+  // collection root). Reconcile them explicitly, scoped to the gateways that
+  // the local artifacts actually track (including the built-in "managed"
+  // gateway). This keeps the blast radius limited: gateways with no local
+  // apis.json are never touched.
+  const gatewayApiDeletes = await computeGatewayApiDeleteActions(
+    client,
+    context,
+    config,
+    localDescriptors,
+    localSet
+  );
+  // Run association removals first (children before parents).
+  deleteDescriptors.unshift(...gatewayApiDeletes);
+
   return deleteDescriptors;
 }
 
+/**
+ * Reconcile per-gateway API assignments (ResourceType.GatewayApi).
+ *
+ * Only gateways that appear as a parent of at least one local GatewayApi
+ * artifact are considered, so a workspace that does not track gateway
+ * associations is left completely untouched. For each such gateway the deployed
+ * assignments are listed and any assignment missing from the local artifacts is
+ * queued for deletion (i.e. the API is un-assigned from that gateway).
+ */
+async function computeGatewayApiDeleteActions(
+  client: IApimClient,
+  context: ApimServiceContext,
+  config: PublishConfig,
+  localDescriptors: ResourceDescriptor[],
+  localSet: Set<string>
+): Promise<ResourceDescriptor[]> {
+  const { envMapping } = config;
+
+  // Distinct gateway names that own at least one local GatewayApi artifact.
+  const gatewayNames = new Set<string>();
+  for (const descriptor of localDescriptors) {
+    if (descriptor.type === ResourceType.GatewayApi) {
+      const gatewayName = getNamePart(descriptor.nameParts, 0);
+      if (gatewayName) {
+        gatewayNames.add(gatewayName);
+      }
+    }
+  }
+
+  if (gatewayNames.size === 0) {
+    return [];
+  }
+
+  const deletes: ResourceDescriptor[] = [];
+
+  for (const gatewayName of gatewayNames) {
+    const gatewayDescriptor: ResourceDescriptor = {
+      type: ResourceType.Gateway,
+      nameParts: [gatewayName],
+    };
+
+    try {
+      for await (const apiJson of client.listResources(
+        context,
+        ResourceType.GatewayApi,
+        gatewayDescriptor
+      )) {
+        const apiName = extractResourceName(apiJson);
+        if (!apiName) {
+          continue;
+        }
+
+        const deployedDescriptor: ResourceDescriptor = {
+          type: ResourceType.GatewayApi,
+          nameParts: [gatewayName, apiName],
+        };
+
+        if (envMapping !== undefined) {
+          const canonicalDescriptor = toCanonicalDescriptor(deployedDescriptor, envMapping);
+          if (canonicalDescriptor === null) {
+            // Belongs to another environment — do not touch.
+            continue;
+          }
+          if (!localSet.has(getResourceKey(canonicalDescriptor))) {
+            deletes.push(deployedDescriptor);
+          }
+        } else if (!localSet.has(getResourceKey(deployedDescriptor))) {
+          deletes.push(deployedDescriptor);
+        }
+      }
+    } catch (error) {
+      logger.debug(
+        `[delete-unmatched] Skipping gateway "${gatewayName}" API reconciliation: ${(error as Error).message}`
+      );
+      continue;
+    }
+  }
+
+  return deletes;
+}
+
 /**
  * Create a set of resource keys from descriptors for fast lookup
  */

src/services/extract-service.ts

@@ -11,7 +11,7 @@ import { IApimClient } from '../clients/iapim-client.js';
 import { IArtifactStore } from '../clients/iartifact-store.js';
 import { ExtractConfig, FilterConfig } from '../models/config.js';
 import { ApimServiceContext, ResourceDescriptor } from '../models/types.js';
-import { ResourceType } from '../models/resource-types.js';
+import { ResourceType, MANAGED_GATEWAY_NAME } from '../models/resource-types.js';
 import {
   TIER_1_RESOURCES,
   TIER_2_RESOURCES,
@@ -470,6 +470,34 @@ async function extractGatewayAssociations(
       }
     }
   }
+
+  // The built-in "managed" gateway is not returned by GET /gateways, so extract
+  // its API assignments explicitly. Recording them lets publish/delete-unmatched
+  // reconcile managed membership (e.g. an API intentionally removed from managed).
+  const managedDescriptor: ResourceDescriptor = {
+    type: ResourceType.Gateway,
+    nameParts: [MANAGED_GATEWAY_NAME],
+  };
+  try {
+    const apiNames: string[] = [];
+    for await (const apiJson of client.listResources(context, ResourceType.GatewayApi, managedDescriptor)) {
+      const name = apiJson.name as string | undefined;
+      if (name) {
+        apiNames.push(name);
+      }
+    }
+    // Only record the managed gateway when it actually has assignments. An empty
+    // apis.json would neither help publish nor delete-unmatched reconciliation
+    // (which scopes to gateways that own at least one local assignment).
+    if (apiNames.length > 0) {
+      await store.writeAssociation(outputDir, managedDescriptor, 'apis', apiNames);
+      result.totalExtracted++;
+      logger.info(`Extracted ${apiNames.length} API associations for gateway "${MANAGED_GATEWAY_NAME}"`);
+    }
+  } catch (error) {
+    logger.warn(`Failed to extract API associations for managed gateway: ${(error as Error).message}`);
+    result.totalErrors++;
+  }
 }
 
 /**

src/services/resource-publisher.ts

@@ -11,7 +11,7 @@ import type { IApimClient } from '../clients/iapim-client.js';
 import type { IArtifactStore } from '../clients/iartifact-store.js';
 import type { ApimServiceContext, ResourceDescriptor } from '../models/types.js';
 import type { PublishConfig } from '../models/config.js';
-import { ResourceType, RESOURCE_TYPE_METADATA } from '../models/resource-types.js';
+import { ResourceType, RESOURCE_TYPE_METADATA, MANAGED_GATEWAY_NAME } from '../models/resource-types.js';
 import { applyOverrides } from './override-merger.js';
 import { checkKeyVaultSecretAccess } from './keyvault-checker.js';
 import { getNamePart } from '../lib/resource-path.js';
@@ -208,6 +208,13 @@ export async function publishResource(
   config: PublishConfig
 ): Promise<ResourcePublishResult> {
   try {
+    // The built-in "managed" gateway cannot be created/updated as a resource;
+    // only its API assignments are manageable. Skip any managed Gateway resource
+    // PUT (its GatewayApi associations are still published via the branch below).
+    if (descriptor.type === ResourceType.Gateway && getNamePart(descriptor.nameParts, 0) === MANAGED_GATEWAY_NAME) {
+      return { descriptor, status: 'skipped', action: 'noop' };
+    }
+
     // Handle association types (ProductApi, ProductGroup, GatewayApi)
     const associationType = ASSOCIATION_TYPES.get(descriptor.type);
     if (associationType) {

tests/unit/services/delete-unmatched-service.test.ts

@@ -229,6 +229,43 @@ describe('delete-unmatched-service', () => {
         nameParts: ['api1'],
       });
     });
+
+    it('should un-assign a stale managed gateway API not present in artifacts', async () => {
+      const apimResources = new Map<ResourceType, Record<string, unknown>[]>([
+        [ResourceType.GatewayApi, [{ name: 'api-keep' }, { name: 'api-stale' }]],
+      ]);
+
+      // Local artifacts track the managed gateway with only api-keep assigned.
+      const localDescriptors: ResourceDescriptor[] = [
+        { type: ResourceType.GatewayApi, nameParts: ['managed', 'api-keep'] },
+      ];
+
+      const client = createMockClient(apimResources);
+      const store = createMockStore(localDescriptors);
+
+      const result = await computeDeleteActions(client, store, testContext, testConfig);
+
+      const gatewayApiDeletes = result.filter((d) => d.type === ResourceType.GatewayApi);
+      expect(gatewayApiDeletes).toHaveLength(1);
+      expect(gatewayApiDeletes[0]).toMatchObject({
+        type: ResourceType.GatewayApi,
+        nameParts: ['managed', 'api-stale'],
+      });
+    });
+
+    it('should not touch any gateway assignments when artifacts track no gateways', async () => {
+      const apimResources = new Map<ResourceType, Record<string, unknown>[]>([
+        [ResourceType.GatewayApi, [{ name: 'api-a' }, { name: 'api-b' }]],
+      ]);
+
+      // No local GatewayApi artifacts → reconciliation must be a no-op.
+      const client = createMockClient(apimResources);
+      const store = createMockStore([]);
+
+      const result = await computeDeleteActions(client, store, testContext, testConfig);
+
+      expect(result.filter((d) => d.type === ResourceType.GatewayApi)).toHaveLength(0);
+    });
   });
 
   describe('filterRevisionDeletesHandledByBaseApi', () => {

tests/unit/services/extract-service.test.ts

@@ -604,6 +604,56 @@ describe('extract-service', () => {
       );
     });
 
+    it('should extract managed gateway API associations', async () => {
+      // Managed gateway is NOT returned by GET /gateways, only its apis are queryable.
+      const client = createMockClient();
+      client.listResources = async function* (_ctx: ApimServiceContext, type: ResourceType, parent?: ResourceDescriptor) {
+        if (type === ResourceType.GatewayApi && parent?.nameParts[0] === 'managed') {
+          yield { name: 'managed-api-1' };
+          yield { name: 'managed-api-2' };
+        }
+      };
+
+      const store = createMockStore();
+
+      const config: ExtractConfig = {
+        service: testContext,
+        outputDir: '/output',
+        includeTransitive: false,
+        logLevel: LogLevel.INFO,
+      };
+
+      await runExtraction(client, store, config);
+
+      expect(store.writeAssociation).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ type: ResourceType.Gateway, nameParts: ['managed'] }),
+        'apis',
+        expect.arrayContaining(['managed-api-1', 'managed-api-2'])
+      );
+    });
+
+    it('should not write a managed gateway association when it has no apis', async () => {
+      // Empty managed gateway must not produce an artifact or inflate the count.
+      const client = createMockClient();
+      const store = createMockStore();
+
+      const result = await runExtraction(client, store, {
+        service: testContext,
+        outputDir: '/output',
+        includeTransitive: false,
+        logLevel: LogLevel.INFO,
+      });
+
+      expect(store.writeAssociation).not.toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ nameParts: ['managed'] }),
+        'apis',
+        expect.anything()
+      );
+      expect(result.totalExtracted).toBe(0);
+    });
+
     it('should handle gateway association extraction error gracefully', async () => {
       const client = createMockClient({
         [ResourceType.Gateway]: [

tests/unit/services/resource-publisher.test.ts

@@ -98,6 +98,24 @@ describe('resource-publisher', () => {
       expect(client.putResource).not.toHaveBeenCalled();
     });
 
+    it('should skip the built-in managed gateway resource without a PUT', async () => {
+      const client = createMockClient();
+      const store = createMockStore();
+      store.readResource.mockResolvedValue({ name: 'managed', properties: {} });
+
+      const descriptor: ResourceDescriptor = {
+        type: ResourceType.Gateway,
+        nameParts: ['managed'],
+      };
+
+      const result = await publishResource(client, store, testContext, descriptor, testConfig);
+
+      expect(result.status).toBe('skipped');
+      expect(result.action).toBe('noop');
+      expect(client.putResource).not.toHaveBeenCalled();
+    });
+
+
     it('should return success and call putResource on success', async () => {
       const client = createMockClient();
       const store = createMockStore();