@moretea-labs/forge 1.6.0 → 1.7.0

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 { dirname, join } from 'path';
+import { CONTROLLER_SCOPE_REPO_ID, controllerSystemRoot } from '../../cli/repositories/controller-home';
 import type {
   AssistantPluginActionDescriptor,
   AssistantPluginActionExecutionInput,
+  AssistantPluginBuildContext,
   AssistantPluginCapability,
   AssistantPluginHealth,
   AssistantPluginManifest,
@@ -45,6 +47,12 @@ interface AppStoreConnectAuthState {
   warnings: string[];
 }
 
+export interface AppStoreConnectXcodeAuthenticationReference {
+  privateKeyPath: string;
+  keyId: string;
+  issuerId: string;
+}
+
 function now(): string {
   return new Date().toISOString();
 }
@@ -70,6 +78,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,26 +97,57 @@ 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 {
@@ -165,6 +208,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 };
@@ -308,6 +382,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 +404,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 +451,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 +666,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 +763,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 +776,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 +788,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,7 +801,7 @@ 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) };
   }
 
@@ -730,6 +823,16 @@ export async function executeAppStoreConnectPluginAction(input: AssistantPluginA
       };
     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 +966,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,
 };