Cline rules

1# Application Creation Guidance
2- Cline must use hello-msal-multiple-account and hello-msal-single-account apps in the examples folder as the golden examples when generating an MSAL-integrated application. hello-msal-multiple-account for when the user wants multiple account mode, and hello-msal-single-account for when the user wants single account mode.
3- If user does not specify between multiple account mode and single account mode in MSAL, the default mode used should be MULTIPLE. Make sure the configuration json includes which account mode the application is being built for, and use the appropriate example based on this selection.
4- Ensure that the latest MSAL Version is used. Reference the MSAL repo to see latest version. At the very least, MSAL 7.+ should be used.
5- Cline must copy the following gradle files exactly when creating a new application:
6  1. Root level build.gradle (project level) from examples/hello-msal-multiple-account/build.gradle or examples/hello-msal-single-account/build.gradle
7  2. App level build.gradle from examples/hello-msal-multiple-account/app/build.gradle or examples/hello-msal-single-account/app/build.gradle
8  3. gradle.properties from examples/hello-msal-multiple-account/gradle.properties or examples/hello-msal-single-account/gradle.properties
9  4. settings.gradle from examples/hello-msal-multiple-account/settings.gradle or examples/hello-msal-single-account/settings.gradle
10 
11  These files must be placed in their corresponding locations in the new application's directory structure. The only modification allowed is updating the applicationId and namespace in app/build.gradle and rootProject.name in settings.gradle to match the new application's package name. Cline can divert from these files as needed once initial creation is complete.
12 
13# MSAL API Usage
14- Broker integration (Microsoft Authenticator, Company Portal, or Link To Windows) should ALWAYS be enabled for enhanced security and SSO capabilities. The broker_redirect_uri_registered field in auth_config.json should be set to "true" unless explicitly disabled by the user's request.
15- ALWAYS use MSAL's Parameters-based APIs instead of deprecated methods. Here are the required patterns:
16 
17For interactive token acquisition in multiple account applications:
18```java
19AcquireTokenParameters parameters = new AcquireTokenParameters.Builder()
20    .withScopes(SCOPES)
21    .withCallback(callback)
22    .build();
23mPCA.acquireToken(parameters);
24```
25 
26For silent token acquisition:
27```java
28AcquireTokenSilentParameters parameters = new AcquireTokenSilentParameters.Builder()
29    .withScopes(SCOPES)
30    .forAccount(account)
31    .forceRefresh(false)
32    .withCallback(callback)
33    .build();
34mPCA.acquireTokenSilent(parameters);
35```
36 
37For sign-in in single account applications only:
38```java
39SignInParameters parameters = new SignInParameters.Builder()
40    .startActivity(activity)
41    .withCallback(callback)
42    .build();
43mPCA.signIn(parameters);
44```
45 
46Important notes:
47- For multiple account applications, use acquireToken for sign in, removeAccount for sign out
48- For single account applications, use signIn and signOut. Also, use signInAgain if you want to reauthenticate
49- acquireTokenWithDeviceCode method is only meant for back compatibility, and will be deprecated soon. It is not recommended due to security concerns in the industry.
50- Do not use deprecated methods like:
51  - acquireToken(activity, scopes, callback)
52  - acquireTokenSilentAsync(scopes, account, authority, callback)
53  - signIn(activity, scopes, callback)
54 
55# Multiple Account Mode UI Requirements
56- Account spinner must include a "No Account Selected" option at position 0
57- Sign In button must always be enabled to allow adding new accounts
58- Sign Out button must only be enabled when an account is selected in the spinner
59- Acquire Token Silent button must only be enabled when an account is selected in the spinner
60 
61# Icon and Resource Guidelines
62- For application icons, only use resources that are explicitly created in the project
63- Do not reference any resources (mipmap/drawable) that haven't been created
64- When using adaptive icons:
65  1. Create the necessary foreground vector drawable
66  2. Define the background color in colors.xml
67  3. Create the adaptive icon XML files
68  4. Remove any references to non-existent icon resources from AndroidManifest.xml
69 
70# Code Implementation Guidelines
71- Use ArrayList/List instead of arrays for better API compatibility
72- Always initialize member variables in their declaration or constructor
73- Use proper access modifiers (private for member variables)
74- Follow Android naming conventions (mVariable for member variables)
75- Handle UI updates on the main thread using activity.runOnUiThread
76- Validate PublicClientApplication (PCA) initialization before making any MSAL API calls
77- Refresh account lists after authentication operations
78- Use proper callback interfaces for communication between components
79 
80# Configuration and Manifest
81- Use auth_config.template.json as a guide for enabling and disabling MSAL configuration settings based on user needs.
82- When generating the configuration file, include all mandatory settings (client_id, redirect_uri, and authorities), and only include optional configurations that differ from their default values.
83- Cline must generate an AndroidManifest that includes the user's application name and signature hash. See AndroidManifest.xml in the golden example apps mentioned above for reference. The signature hash and redirect URI in the AndroidManifest.xml must NOT be URL encoded. For example:
84```xml
85  <data
86      android:scheme="msauth" 
87      android:host="your.app.package.name"
88      android:path="/ABcDeFgJQiLoiEmd-vn14qR*okk=" />
89```
90 
91- When generating the auth_config.json file, the redirect_uri field MUST contain URL encoded values. For example:
92```json
93  {
94      "redirect_uri": "msauth://your.app.package.name/ABcDeFgJQiLoiEmd-vn14qR%2Aokk%3D%0A"
95  }
96```
97  Note that special characters like '+' and '=' are URL encoded to %2B and %3D respectively.
98 
99- When generating an application, make sure to print the result of the PublicClientApplication creation process so users are aware of any issues. The user can decide to remove this later. Also, no PublicClientApplication APIs should be callable if the PublicClientApplication has not been successfully created.
100 
101# Azure App Registration Fields
102- If the user prompts cline to create an application and provides the Client ID and redirect uri to be used in the project, Cline must place them in the configuration json and the android manifest.
103- If the user does not prompt cline with the client id and redirect uri, then Cline should ask them to enter them as part of a later prompt to be placed in the correct locations mentioned above. Guide them to this link (https://learn.microsoft.com/en-us/entra/identity-platform/msal-client-application-configuration) to assist them in the app registration process.
104 
105# UI Requirements and Best Practices
106 
107## Theme Configuration
108- Applications should use a consistent theme throughout the app
109- If using Material Design (optional), extend appropriate Material theme
110- Required theme attributes regardless of design system:
111```xml
112  <style name="AppTheme">
113      <item name="colorPrimary">@color/colorPrimary</item>
114      <item name="colorPrimaryDark">@color/colorPrimaryDark</item>
115      <item name="colorAccent">@color/colorAccent</item>
116      <item name="android:windowBackground">@color/windowBackground</item>
117  </style>
118```
119- Ensure theme is properly set in AndroidManifest.xml using android:theme attribute
120 
121## Required Resource Structure
122- Mandatory resource directories and files:
123  1. res/values/colors.xml - Define standard color palette
124  2. res/values/styles.xml - Define app theme and styles
125  3. res/values/strings.xml - All string resources
126  4. res/layout/ - Layout files
127  5. res/drawable/ - Vector drawables and other graphics
128  6. res/mipmap-*/ - Launcher icons in various densities
129- Icon configuration:
130  1. Create adaptive icons using foreground and background layers
131  2. Include mipmap-anydpi-v26 for adaptive icon support
132  3. Provide round and regular launcher variants
133  4. Define ic_launcher_foreground.xml in drawable
134  5. Define launcher background color in colors.xml
135 
136## UI Component Guidelines
137- Use consistent UI components throughout the app
138- If using Material Design components:
139  1. Include Material Design dependency
140  2. Use appropriate Material components
141  3. Follow Material Design guidelines
142- For standard Android widgets:
143  1. Apply consistent styling
144  2. Use appropriate view attributes
145  3. Implement proper view hierarchies
146- Use modern layout systems (ConstraintLayout recommended)
147- Implement proper view binding instead of findViewById
148 
149## Best Practices
150- Resource naming conventions:
151  1. Layout files: activity_*, fragment_*, item_*, etc.
152  2. Drawable files: ic_*, bg_*, etc.
153  3. Color resources: semantic names like colorPrimary, colorError
154  4. String resources: screen_action_description pattern
155- Layout organization:
156  1. Use styles for repeated view attributes
157  2. Extract dimensions to dimens.xml
158  3. Use proper layout_width/height (wrap_content/match_parent appropriately)
159  4. Implement landscape variations where needed
160- Theme inheritance:
161  1. Create specific styles for different UI components
162  2. Use theme overlays when needed
163  3. Consider dark theme support
164- Error handling:
165  1. Show clear error states
166  2. Implement proper loading states
167  3. Use progress indicators for async operations
168