@moretea-labs/forge 1.6.0 → 1.7.1

package/src/runtime/plugins/app-store-connect-adapter.ts

@@ -1,9 +1,11 @@
 import { createPrivateKey, sign } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { accessSync, constants as fsConstants, existsSync, mkdirSync, promises as fsPromises, readFileSync, statSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
+import { CONTROLLER_SCOPE_REPO_ID, controllerSystemRoot } from '../../cli/repositories/controller-home';
 import type {
   AssistantPluginActionDescriptor,
   AssistantPluginActionExecutionInput,
+  AssistantPluginBuildContext,
   AssistantPluginCapability,
   AssistantPluginHealth,
   AssistantPluginManifest,
@@ -17,6 +19,8 @@ const CONFIG_ROOT = '.forge/plugins';
 const LEGACY_CONFIG_ROOT = '.repo-harness/plugins';
 const API_BASE_URL = 'https://api.appstoreconnect.apple.com';
 const DEFAULT_TIMEOUT_MS = 60_000;
+const PRIVATE_KEY_READ_MAX_ATTEMPTS = 4;
+const PRIVATE_KEY_READ_RETRY_BASE_MS = 10;
 
 type AppStoreConnectProviderKind = 'mock' | 'app-store-connect-api';
 
@@ -45,6 +49,12 @@ interface AppStoreConnectAuthState {
   warnings: string[];
 }
 
+export interface AppStoreConnectXcodeAuthenticationReference {
+  privateKeyPath: string;
+  keyId: string;
+  issuerId: string;
+}
+
 function now(): string {
   return new Date().toISOString();
 }
@@ -70,6 +80,10 @@ function legacyConfigPath(repoRoot: string): string {
   return join(repoRoot, LEGACY_CONFIG_ROOT, 'app-store-connect.json');
 }
 
+function globalConfigPath(controllerHome: string): string {
+  return join(controllerSystemRoot(controllerHome), 'plugins', 'profiles', 'app-store-connect.json');
+}
+
 function normalizeConfig(raw: Partial<AppStoreConnectPluginConfig>): AppStoreConnectPluginConfig {
   return {
     schemaVersion: 1,
@@ -85,46 +99,139 @@ function normalizeConfig(raw: Partial<AppStoreConnectPluginConfig>): AppStoreCon
   };
 }
 
-function loadConfig(repoRoot: string): AppStoreConnectPluginConfig {
-  // `.forge/plugins` is the current authority, but installations created before
-  // the Forge config-root migration may still have the App Store Connect config
-  // under `.repo-harness/plugins`. Read that legacy file only when the current
-  // path is absent; the next explicit configure action writes the current path.
-  const path = existsSync(configPath(repoRoot)) ? configPath(repoRoot) : legacyConfigPath(repoRoot);
-  if (!existsSync(path)) return normalizeConfig({});
+function readConfigFile(path: string): Partial<AppStoreConnectPluginConfig> | undefined {
+  if (!existsSync(path)) return undefined;
   try {
-    return normalizeConfig(JSON.parse(readFileSync(path, 'utf-8')) as Partial<AppStoreConnectPluginConfig>);
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as Partial<AppStoreConnectPluginConfig>;
+    return parsed && typeof parsed === 'object' ? parsed : undefined;
   } catch {
-    return normalizeConfig({});
+    return undefined;
   }
 }
 
-function saveConfig(repoRoot: string, patch: Partial<AppStoreConnectPluginConfig>): AppStoreConnectPluginConfig {
-  const next = normalizeConfig({ ...loadConfig(repoRoot), ...patch });
+function repositoryConfig(repoRoot: string): { raw?: Partial<AppStoreConnectPluginConfig>; source?: 'current' | 'legacy' } {
+  const current = readConfigFile(configPath(repoRoot));
+  if (current) return { raw: current, source: 'current' };
+  const legacy = readConfigFile(legacyConfigPath(repoRoot));
+  return legacy ? { raw: legacy, source: 'legacy' } : {};
+}
+
+function loadConfig(repoRoot: string, controllerHome?: string, repoId?: string): AppStoreConnectPluginConfig {
+  const global = controllerHome ? readConfigFile(globalConfigPath(controllerHome)) : undefined;
+  if (repoId === CONTROLLER_SCOPE_REPO_ID) return normalizeConfig(global ?? {});
+  const local = repositoryConfig(repoRoot).raw;
+  return normalizeConfig({ ...(global ?? {}), ...(local ?? {}) });
+}
+
+function definedPatch(patch: Partial<AppStoreConnectPluginConfig>): Partial<AppStoreConnectPluginConfig> {
+  return Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined)) as Partial<AppStoreConnectPluginConfig>;
+}
+
+function saveConfig(
+  repoRoot: string,
+  patch: Partial<AppStoreConnectPluginConfig>,
+  controllerHome?: string,
+  repoId?: string,
+): AppStoreConnectPluginConfig {
+  const cleanPatch = definedPatch(patch);
+  if (controllerHome && repoId === CONTROLLER_SCOPE_REPO_ID) {
+    const path = globalConfigPath(controllerHome);
+    const next = normalizeConfig({ ...(readConfigFile(path) ?? {}), ...cleanPatch });
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, 'utf-8');
+    return next;
+  }
+
+  // Repository state is an overlay only. Do not materialize inherited global
+  // credential references into every repository just because configure ran.
+  const existing = repositoryConfig(repoRoot).raw ?? {};
+  const overlay = { schemaVersion: 1 as const, ...existing, ...cleanPatch };
   const path = configPath(repoRoot);
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, 'utf-8');
-  return next;
+  writeFileSync(path, `${JSON.stringify(overlay, null, 2)}\n`, 'utf-8');
+  return loadConfig(repoRoot, controllerHome, repoId);
 }
 
 function envValue(name: string): string | undefined {
   return stringValue(process.env[name]);
 }
 
-function privateKeyMaterial(config: AppStoreConnectPluginConfig): { key?: string; source?: string; warning?: string } {
+interface AppStoreConnectPrivateKeyReference {
+  available: boolean;
+  source?: string;
+  warning?: string;
+}
+
+function privateKeyPathReference(path: string, source: string): AppStoreConnectPrivateKeyReference {
+  if (!existsSync(path)) {
+    return { available: false, source, warning: 'Configured App Store Connect private key path does not exist.' };
+  }
+  try {
+    if (!statSync(path).isFile()) {
+      return { available: false, source, warning: 'Configured App Store Connect private key path is not a regular file.' };
+    }
+    accessSync(path, fsConstants.R_OK);
+    return { available: true, source };
+  } catch {
+    // Capability discovery and auth_status are metadata reads. They must never
+    // synchronously consume secret bytes just to decide whether a credential
+    // reference is usable; filesystem contention (including macOS EDEADLK)
+    // therefore degrades readiness instead of escaping as a raw read error.
+    return { available: false, source, warning: 'Configured App Store Connect private key path is not readable.' };
+  }
+}
+
+function privateKeyReference(config: AppStoreConnectPluginConfig): AppStoreConnectPrivateKeyReference {
   const inline = envValue('FORGE_ASC_PRIVATE_KEY');
-  if (inline) return { key: inline.replace(/\\n/g, '\n'), source: 'env:FORGE_ASC_PRIVATE_KEY' };
+  if (inline) return { available: true, source: 'env:FORGE_ASC_PRIVATE_KEY' };
   const envKeyPath = envValue('FORGE_ASC_PRIVATE_KEY_PATH');
-  if (envKeyPath) {
-    return existsSync(envKeyPath)
-      ? { key: readFileSync(envKeyPath, 'utf-8'), source: 'env:FORGE_ASC_PRIVATE_KEY_PATH' }
-      : { source: 'env:FORGE_ASC_PRIVATE_KEY_PATH', warning: 'Configured App Store Connect private key path does not exist.' };
-  }
-  if (config.privateKeyPath) {
-    return existsSync(config.privateKeyPath)
-      ? { key: readFileSync(config.privateKeyPath, 'utf-8'), source: 'config:privateKeyPath' }
-      : { source: 'config:privateKeyPath', warning: 'Configured App Store Connect private key path does not exist.' };
+  if (envKeyPath) return privateKeyPathReference(envKeyPath, 'env:FORGE_ASC_PRIVATE_KEY_PATH');
+  if (config.privateKeyPath) return privateKeyPathReference(config.privateKeyPath, 'config:privateKeyPath');
+  return { available: false };
+}
+
+function fsErrorCode(error: unknown): string | undefined {
+  if (!error || typeof error !== 'object' || !('code' in error)) return undefined;
+  const code = (error as { code?: unknown }).code;
+  return typeof code === 'string' ? code : undefined;
+}
+
+async function readPrivateKeyFile(path: string, source: string): Promise<{ key?: string; source: string; warning?: string }> {
+  for (let attempt = 1; attempt <= PRIVATE_KEY_READ_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      return { key: await fsPromises.readFile(path, 'utf-8'), source };
+    } catch (error) {
+      const code = fsErrorCode(error);
+      if (code === 'ENOENT') {
+        return { source, warning: 'Configured App Store Connect private key path does not exist.' };
+      }
+      if (code === 'EDEADLK' && attempt < PRIVATE_KEY_READ_MAX_ATTEMPTS) {
+        await new Promise((resolve) => setTimeout(resolve, PRIVATE_KEY_READ_RETRY_BASE_MS * attempt));
+        continue;
+      }
+      if (code === 'EDEADLK') {
+        throw new AssistantPluginError(
+          'PLUGIN_PROVIDER_UNAVAILABLE',
+          'App Store Connect private key is temporarily unavailable because the filesystem is busy.',
+          { retryable: true, details: { credentialSource: source, code } },
+        );
+      }
+      throw new AssistantPluginError(
+        'PLUGIN_AUTH_REQUIRED',
+        'Configured App Store Connect private key could not be read.',
+        { retryable: false, details: { credentialSource: source, code } },
+      );
+    }
   }
+  throw new AssistantPluginError('PLUGIN_PROVIDER_UNAVAILABLE', 'App Store Connect private key is temporarily unavailable.', { retryable: true });
+}
+
+async function privateKeyMaterial(config: AppStoreConnectPluginConfig): Promise<{ key?: string; source?: string; warning?: string }> {
+  const inline = envValue('FORGE_ASC_PRIVATE_KEY');
+  if (inline) return { key: inline.replace(/\\n/g, '\n'), source: 'env:FORGE_ASC_PRIVATE_KEY' };
+  const envKeyPath = envValue('FORGE_ASC_PRIVATE_KEY_PATH');
+  if (envKeyPath) return readPrivateKeyFile(envKeyPath, 'env:FORGE_ASC_PRIVATE_KEY_PATH');
+  if (config.privateKeyPath) return readPrivateKeyFile(config.privateKeyPath, 'config:privateKeyPath');
   return {};
 }
 
@@ -145,12 +252,12 @@ function resolveAuth(config: AppStoreConnectPluginConfig): AppStoreConnectAuthSt
 
   const issuerId = envValue('FORGE_ASC_ISSUER_ID') ?? config.issuerId;
   const keyId = envValue('FORGE_ASC_KEY_ID') ?? config.keyId;
-  const key = privateKeyMaterial(config);
+  const key = privateKeyReference(config);
   const errors: string[] = [];
   const warnings: string[] = key.warning ? [key.warning] : [];
   if (!issuerId) errors.push('Set FORGE_ASC_ISSUER_ID or configure issuer_id.');
   if (!keyId) errors.push('Set FORGE_ASC_KEY_ID or configure key_id.');
-  if (!key.key) errors.push('Set FORGE_ASC_PRIVATE_KEY, FORGE_ASC_PRIVATE_KEY_PATH, or configure private_key_path.');
+  if (!key.available) errors.push('Set FORGE_ASC_PRIVATE_KEY, FORGE_ASC_PRIVATE_KEY_PATH, or configure private_key_path.');
 
   return {
     provider: 'app-store-connect-api',
@@ -165,6 +272,37 @@ function resolveAuth(config: AppStoreConnectPluginConfig): AppStoreConnectAuthSt
   };
 }
 
+export function resolveAppStoreConnectXcodeAuthenticationReference(
+  repoRoot: string,
+  controllerHome: string,
+  repoId: string,
+): AppStoreConnectXcodeAuthenticationReference {
+  const config = loadConfig(repoRoot, controllerHome, repoId);
+  if (!config.enabled) {
+    throw new AssistantPluginError('PLUGIN_DISABLED', 'App Store Connect is disabled for this repository.', { retryable: false });
+  }
+  if (config.provider !== 'app-store-connect-api') {
+    throw new AssistantPluginError('PLUGIN_DEPENDENCY_MISSING', 'Xcode provisioning requires the App Store Connect API provider.', { retryable: false });
+  }
+  const privateKeyPath = envValue('FORGE_ASC_PRIVATE_KEY_PATH') ?? config.privateKeyPath;
+  const keyId = envValue('FORGE_ASC_KEY_ID') ?? config.keyId;
+  const issuerId = envValue('FORGE_ASC_ISSUER_ID') ?? config.issuerId;
+  if (!privateKeyPath) {
+    throw new AssistantPluginError(
+      'PLUGIN_DEPENDENCY_MISSING',
+      'Xcode provisioning requires a file-backed App Store Connect private key path; inline key material is not accepted for this path.',
+      { retryable: false },
+    );
+  }
+  if (!existsSync(privateKeyPath)) {
+    throw new AssistantPluginError('PLUGIN_DEPENDENCY_MISSING', 'Configured App Store Connect private key path does not exist.', { retryable: false });
+  }
+  if (!keyId || !issuerId) {
+    throw new AssistantPluginError('PLUGIN_DEPENDENCY_MISSING', 'App Store Connect key id and issuer id are required for Xcode provisioning.', { retryable: false });
+  }
+  return { privateKeyPath, keyId, issuerId };
+}
+
 function readLength(buffer: Buffer, offset: number): { length: number; next: number } {
   const first = buffer[offset];
   if (first < 0x80) return { length: first, next: offset + 1 };
@@ -195,10 +333,10 @@ function derSignatureToJose(signature: Buffer): string {
   return Buffer.concat([derIntegerToJose(r), derIntegerToJose(s)]).toString('base64url');
 }
 
-function createJwt(config: AppStoreConnectPluginConfig): string {
+async function createJwt(config: AppStoreConnectPluginConfig): Promise<string> {
   const issuerId = envValue('FORGE_ASC_ISSUER_ID') ?? config.issuerId;
   const keyId = envValue('FORGE_ASC_KEY_ID') ?? config.keyId;
-  const key = privateKeyMaterial(config).key;
+  const key = (await privateKeyMaterial(config)).key;
   if (!issuerId || !keyId || !key) throw new AssistantPluginError('PLUGIN_AUTH_REQUIRED', 'App Store Connect API credentials are incomplete.', { retryable: false });
 
   const issuedAt = Math.floor(Date.now() / 1000);
@@ -224,7 +362,7 @@ async function apiRequest<T>(config: AppStoreConnectPluginConfig, options: {
     const response = await fetch(url, {
       method: options.method ?? 'GET',
       headers: {
-        authorization: `Bearer ${createJwt(config)}`,
+        authorization: `Bearer ${await createJwt(config)}`,
         accept: 'application/json',
         ...(options.body === undefined ? {} : { 'content-type': 'application/json' }),
       },
@@ -308,6 +446,7 @@ function permission(scope: string, mode: 'read' | 'write', description: string,
 function permissions(ready: boolean): AssistantPluginPermissionScope[] {
   return [
     permission('appstoreconnect.apps.read', 'read', 'Read App Store Connect apps, versions, localizations, builds, and TestFlight groups.', ready),
+    permission('appstoreconnect.developer_resources.read', 'read', 'Read Apple Developer bundle IDs, capabilities, certificates, devices, and provisioning profiles.', ready),
     permission('appstoreconnect.metadata.write', 'write', 'Patch App Store Connect metadata after dry-run review and authorization.', ready),
     permission('appstoreconnect.testflight.write', 'write', 'Assign builds to TestFlight groups and prepare beta review submissions.', ready),
     permission('appstoreconnect.release.write', 'write', 'Create App Store versions and gated review submissions.', ready),
@@ -329,6 +468,13 @@ function capabilities(): AssistantPluginCapability[] {
         'list_beta_groups', 'list_beta_testers', 'list_review_submissions',
       ],
     },
+    {
+      capabilityId: 'developer-resources-read',
+      title: 'Apple Developer Resources',
+      description: 'Read Certificates, Identifiers & Profiles resources to diagnose provisioning authorization without mutating Apple Developer state.',
+      scopes: ['appstoreconnect.developer_resources.read'],
+      actions: ['list_bundle_ids', 'list_bundle_id_capabilities', 'list_certificates', 'list_devices', 'list_profiles'],
+    },
     {
       capabilityId: 'app-store-metadata',
       title: 'App Metadata Update',
@@ -369,11 +515,16 @@ function actions(): AssistantPluginActionDescriptor[] {
   return [
     {
       actionId: 'configure', title: 'Configure App Store Connect plugin', description: 'Enable official App Store Connect API access and save non-secret defaults.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: true,
-      scopes: ['appstoreconnect.apps.read', 'appstoreconnect.metadata.write', 'appstoreconnect.testflight.write', 'appstoreconnect.release.write', 'appstoreconnect.xcodecloud.read', 'appstoreconnect.xcodecloud.write'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
+      scopes: ['appstoreconnect.apps.read', 'appstoreconnect.developer_resources.read', 'appstoreconnect.metadata.write', 'appstoreconnect.testflight.write', 'appstoreconnect.release.write', 'appstoreconnect.xcodecloud.read', 'appstoreconnect.xcodecloud.write'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }],
       argumentsSchema: { type: 'object', properties: { enabled: { type: 'boolean' }, provider: { type: 'string', enum: ['mock', 'app-store-connect-api'] }, issuer_id: { type: 'string' }, key_id: { type: 'string' }, private_key_path: { type: 'string' }, clear_private_key_path: { type: 'boolean' }, clear_api_identity: { type: 'boolean' }, team_id: { type: 'string' }, clear_team_id: { type: 'boolean' }, default_app_id: { type: 'string' }, clear_default_app_id: { type: 'boolean' }, default_locale: { type: 'string' }, default_timeout_ms: { type: 'number' } }, additionalProperties: false },
     },
     { actionId: 'auth_status', title: 'Check App Store Connect auth', description: 'Report API readiness without returning secrets.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 10_000, cancellable: true, idempotent: true, scopes: ['appstoreconnect.apps.read'], resourceClaims: [], argumentsSchema: { type: 'object', properties: {}, additionalProperties: false } },
     { actionId: 'list_apps', title: 'List apps', description: 'List App Store Connect apps, optionally filtered by bundle ID or name.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 45_000, cancellable: true, idempotent: true, scopes: ['appstoreconnect.apps.read'], resourceClaims: readRemote, argumentsSchema: { type: 'object', properties: { bundle_id: { type: 'string' }, name: { type: 'string' }, limit: { type: 'number' } }, additionalProperties: false } },
+    { actionId: 'list_bundle_ids', title: 'List Apple Developer bundle IDs', description: 'Read registered Bundle IDs, optionally filtered by exact identifier or name.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 45_000, cancellable: true, idempotent: true, scopes: ['appstoreconnect.developer_resources.read'], resourceClaims: readRemote, argumentsSchema: { type: 'object', properties: { identifier: { type: 'string' }, name: { type: 'string' }, limit: { type: 'number' } }, additionalProperties: false } },
+    { actionId: 'list_bundle_id_capabilities', title: 'List Bundle ID capabilities', description: 'Read enabled capabilities for one exact Apple Developer Bundle ID resource.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 45_000, cancellable: true, idempotent: true, scopes: ['appstoreconnect.developer_resources.read'], resourceClaims: readRemote, argumentsSchema: { type: 'object', properties: { bundle_id_resource_id: { type: 'string' }, limit: { type: 'number' } }, required: ['bundle_id_resource_id'], additionalProperties: false } },
+    { actionId: 'list_certificates', title: 'List Apple Developer certificates', description: 'Read certificates available to the current Apple Developer API identity.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 45_000, cancellable: true, idempotent: true, scopes: ['appstoreconnect.developer_resources.read'], resourceClaims: readRemote, argumentsSchema: { type: 'object', properties: { certificate_type: { type: 'string' }, limit: { type: 'number' } }, additionalProperties: false } },
+    { actionId: 'list_devices', title: 'List Apple Developer devices', description: 'Read registered devices, optionally filtered by UDID.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 45_000, cancellable: true, idempotent: true, scopes: ['appstoreconnect.developer_resources.read'], resourceClaims: readRemote, argumentsSchema: { type: 'object', properties: { udid: { type: 'string' }, limit: { type: 'number' } }, additionalProperties: false } },
+    { actionId: 'list_profiles', title: 'List provisioning profiles', description: 'Read Apple Developer provisioning profiles, optionally filtered by profile name or type.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 45_000, cancellable: true, idempotent: true, scopes: ['appstoreconnect.developer_resources.read'], resourceClaims: readRemote, argumentsSchema: { type: 'object', properties: { name: { type: 'string' }, profile_type: { type: 'string' }, limit: { type: 'number' } }, additionalProperties: false } },
     { actionId: 'list_app_store_versions', title: 'List App Store versions', description: 'List App Store versions for one app.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 45_000, cancellable: true, idempotent: true, scopes: ['appstoreconnect.apps.read'], resourceClaims: readRemote, argumentsSchema: { type: 'object', properties: { app_id: { type: 'string' }, limit: { type: 'number' } }, additionalProperties: false } },
     { actionId: 'list_app_store_version_localizations', title: 'List App Store version localizations', description: 'List localizations for one App Store version.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 45_000, cancellable: true, idempotent: true, scopes: ['appstoreconnect.apps.read'], resourceClaims: readRemote, argumentsSchema: { type: 'object', properties: { version_id: { type: 'string' }, limit: { type: 'number' } }, required: ['version_id'], additionalProperties: false } },
     { actionId: 'get_app_info', title: 'Get app info', description: 'Get App Info records and localizations for one app.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 45_000, cancellable: true, idempotent: true, scopes: ['appstoreconnect.apps.read'], resourceClaims: readRemote, argumentsSchema: { type: 'object', properties: { app_id: { type: 'string' } }, additionalProperties: false } },
@@ -579,6 +730,11 @@ function mockResponse(actionId: string, args: Record<string, unknown>, config: A
       }],
     };
   }
+  if (actionId === 'list_bundle_ids') return { data: [{ type: 'bundleIds', id: stableMockId('bundle_id', args), attributes: { identifier: stringValue(args.identifier) ?? 'com.example.app', name: stringValue(args.name) ?? 'Mock Bundle ID', platform: 'IOS' } }] };
+  if (actionId === 'list_bundle_id_capabilities') return { data: [{ type: 'bundleIdCapabilities', id: stableMockId('bundle_capability', args), attributes: { capabilityType: 'ICLOUD', settings: [] } }] };
+  if (actionId === 'list_certificates') return { data: [{ type: 'certificates', id: stableMockId('certificate', args), attributes: { certificateType: stringValue(args.certificate_type) ?? 'DEVELOPMENT', displayName: 'Mock Certificate' } }] };
+  if (actionId === 'list_devices') return { data: [{ type: 'devices', id: stableMockId('device', args), attributes: { udid: stringValue(args.udid) ?? 'MOCK-UDID', name: 'Mock iPhone', platform: 'IOS', status: 'ENABLED' } }] };
+  if (actionId === 'list_profiles') return { data: [{ type: 'profiles', id: stableMockId('profile', args), attributes: { name: stringValue(args.name) ?? 'Mock Profile', profileType: stringValue(args.profile_type) ?? 'IOS_APP_DEVELOPMENT', profileState: 'ACTIVE' } }] };
   if (actionId === 'list_xcode_cloud_products') return { data: [{ type: 'ciProducts', id: stableMockId('ci_product', { id }), attributes: { name: 'Mock Xcode Cloud Product', productType: 'APP' } }] };
   if (actionId === 'list_xcode_cloud_workflows') return { data: [{ type: 'ciWorkflows', id: stableMockId('ci_workflow', { product: args.product_id }), attributes: { name: 'CI', isEnabled: true, clean: false } }] };
   if (actionId === 'get_xcode_cloud_workflow') return { data: { type: 'ciWorkflows', id: requiredArg(args, 'workflow_id'), attributes: { name: 'CI', isEnabled: true, branchStartCondition: {} } } };
@@ -671,8 +827,9 @@ function mockResponse(actionId: string, args: Record<string, unknown>, config: A
   throw new AssistantPluginError('PLUGIN_ACTION_NOT_SUPPORTED', `app_store_connect/${actionId} is not supported.`, { retryable: false });
 }
 
-export function buildAppStoreConnectPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string): AssistantPluginManifest {
-  const config = loadConfig(repoRoot ?? process.cwd());
+export function buildAppStoreConnectPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string, context?: AssistantPluginBuildContext): AssistantPluginManifest {
+  const effectiveRepoRoot = repoRoot ?? context?.repoRoot ?? process.cwd();
+  const config = loadConfig(effectiveRepoRoot, context?.controllerHome, context?.repoId);
   const auth = resolveAuth(config);
   const state = pluginState(config, auth);
   return {
@@ -683,7 +840,7 @@ export function buildAppStoreConnectPluginManifest(previousRevision = 0, previou
     provider: 'apple',
     displayName: 'App Store Connect API Plugin',
     pluginVersion: '1.1.1',
-    authority: { strategy: 'derived', duplicateStateAllowed: false, sourceOfTruth: [`repo-local:${CONFIG_ROOT}/app-store-connect.json`, `legacy-read-fallback:${LEGACY_CONFIG_ROOT}/app-store-connect.json`, 'env:FORGE_ASC_*'] },
+    authority: { strategy: 'derived', duplicateStateAllowed: false, sourceOfTruth: ['controller-global:system/plugins/profiles/app-store-connect.json', `repo-overlay:${CONFIG_ROOT}/app-store-connect.json`, `legacy-read-fallback:${LEGACY_CONFIG_ROOT}/app-store-connect.json`, 'env:FORGE_ASC_*'] },
     enabled: config.enabled,
     lifecycle: { state: state.lifecycleState, reason: !config.enabled ? 'App Store Connect plugin is disabled.' : auth.ready ? 'App Store Connect API credentials are ready.' : auth.errors[0] ?? auth.warnings[0] },
     health: state.health,
@@ -695,7 +852,7 @@ export function buildAppStoreConnectPluginManifest(previousRevision = 0, previou
 }
 
 export async function executeAppStoreConnectPluginAction(input: AssistantPluginActionExecutionInput): Promise<Record<string, unknown>> {
-  const config = loadConfig(input.repoRoot);
+  const config = loadConfig(input.repoRoot, input.controllerHome, input.repoId);
   if (input.actionId === 'configure') {
     const args = input.args;
     const next = saveConfig(input.repoRoot, {
@@ -708,28 +865,39 @@ export async function executeAppStoreConnectPluginAction(input: AssistantPluginA
       defaultAppId: args.clear_default_app_id === true ? '' : stringValue(args.default_app_id),
       defaultLocale: stringValue(args.default_locale),
       defaultTimeoutMs: boundedTimeout(args.default_timeout_ms),
-    });
+    }, input.controllerHome, input.repoId);
     return { config: next, auth: resolveAuth(next) };
   }
 
   if (config.provider === 'mock') return mockResponse(input.actionId, input.args, config);
   const auth = resolveAuth(config);
+  if (input.actionId === 'auth_status') {
+    return {
+      ready: config.enabled && auth.ready,
+      provider: auth.provider,
+      issuerId: auth.issuerId ? 'configured' : undefined,
+      keyId: auth.keyId ? 'configured' : undefined,
+      credentialSource: auth.credentialSource,
+      errors: auth.errors,
+      warnings: auth.warnings,
+      userFacingStatus: userFacingAscStatus(config, auth),
+    };
+  }
   if (!config.enabled || !auth.ready) throw new AssistantPluginError('PLUGIN_NOT_READY', 'App Store Connect plugin is not ready.', { retryable: false, details: { enabled: config.enabled, errors: auth.errors } });
 
   switch (input.actionId) {
-    case 'auth_status':
-      return {
-        ready: auth.ready,
-        provider: auth.provider,
-        issuerId: auth.issuerId ? 'configured' : undefined,
-        keyId: auth.keyId ? 'configured' : undefined,
-        credentialSource: auth.credentialSource,
-        errors: auth.errors,
-        warnings: auth.warnings,
-        userFacingStatus: userFacingAscStatus(config, auth),
-      };
     case 'list_apps':
       return apiRequest(config, { path: '/v1/apps', query: { 'filter[bundleId]': stringValue(input.args.bundle_id), 'filter[name]': stringValue(input.args.name), limit: limit(input.args.limit) } });
+    case 'list_bundle_ids':
+      return apiRequest(config, { path: '/v1/bundleIds', query: { 'filter[identifier]': stringValue(input.args.identifier), 'filter[name]': stringValue(input.args.name), limit: limit(input.args.limit) } });
+    case 'list_bundle_id_capabilities':
+      return apiRequest(config, { path: `/v1/bundleIds/${encodeURIComponent(requiredArg(input.args, 'bundle_id_resource_id'))}/bundleIdCapabilities`, query: { limit: limit(input.args.limit) } });
+    case 'list_certificates':
+      return apiRequest(config, { path: '/v1/certificates', query: { 'filter[certificateType]': stringValue(input.args.certificate_type), limit: limit(input.args.limit) } });
+    case 'list_devices':
+      return apiRequest(config, { path: '/v1/devices', query: { 'filter[udid]': stringValue(input.args.udid), limit: limit(input.args.limit) } });
+    case 'list_profiles':
+      return apiRequest(config, { path: '/v1/profiles', query: { 'filter[name]': stringValue(input.args.name), 'filter[profileType]': stringValue(input.args.profile_type), limit: limit(input.args.limit) } });
     case 'list_app_store_versions':
       return apiRequest(config, { path: '/v1/appStoreVersions', query: { 'filter[app]': appId(input.args, config), limit: limit(input.args.limit) } });
     case 'list_app_store_version_localizations':
@@ -863,6 +1031,7 @@ export async function executeAppStoreConnectPluginAction(input: AssistantPluginA
 
 export const appStoreConnectPluginAdapter = {
   pluginId: APP_STORE_CONNECT_PLUGIN_ID,
+  scope: 'controller_with_repository_overlay' as const,
   buildManifest: buildAppStoreConnectPluginManifest,
   executeAction: executeAppStoreConnectPluginAction,
 };