add copilot instructions to ui repo

Author: beagins

ui/.github/copilot-instructions.md

@@ -0,0 +1,233 @@
+# GitHub Copilot Instructions: Ember Octane & Project Best Practices
+
+This document provides guidelines for code changes within our EmberJS project. GitHub Copilot should use these instructions to provide relevant suggestions, identify potential issues, and assist in adhering to our project's conventions, Ember Octane best practices, and overall code quality.
+
+**Prioritize reusability, testability, and maintainability in all code changes.**
+
+## Guidelines by File Type
+
+### For Files in the `changelog` Directory
+
+**Instruction:** Ensure `changelog` entries for enterprise-only changes explicitly indicate "enterprise" in their description.
+
+* **DON'T:** `ui: descriptive text`
+* **DO:** `ui (enterprise): descriptive text`
+
+### For Files in the `components` Directory
+
+**Instruction:** Do not use `@tracked` on properties that are immutable or do not change throughout the component's lifecycle. `@tracked` is for reactive state.
+
+* **DON'T:** `@secret={{concat "role/" @model.id}}` (Here, `@secret` is an argument, not a reactive property of the component itself.)
+* **DO:** `@tracked myReactiveProperty = "initialValue";` (Use `@tracked` for component-internal state that can change.)
+
+**Instruction:** Component class names should always match their corresponding file names for clarity and Ember's convention.
+
+**Instruction:** Co-locate `.hbs` templates in the same directory as their corresponding `.js` or `.ts` component files (e.g., `app/components/my-component/my-component.js` and `app/components/my-component/my-component.hbs`).
+
+**Instruction:** Avoid unnecessary quotation marks around dynamic data attributes in templates.
+
+* **DON'T:** `data-test-namespace-link="{{option.label}}"`
+* **DO:** `data-test-namespace-link={{option.label}}`
+
+### For Files in the `models` Directory
+
+**Instruction:** Use single-line syntax for `@attr` declarations if they have one or fewer keys in their options object.
+
+* **DON'T:**
+    ```javascript
+    @attr('string', {
+      label: 'Client ID',
+    }) clientId;
+    ```
+* **DO:** `@attr('string', { label: 'Client ID' }) clientId;`
+
+**Instruction:** Do not add extra blank lines between consecutive single-line `@attr` declarations to maintain compactness.
+
+* **DON'T:**
+    ```javascript
+    @attr('string', { label: 'Client ID' }) clientId;
+
+    @attr('string', { label: 'Client Secret' }) clientSecret;
+    ```
+* **DO:**
+    ```javascript
+    @attr('string', { label: 'Client ID' }) clientId;
+    @attr('string', { label: 'Client Secret' }) clientSecret;
+    ```
+
+### For Files Ending in `.js` or `.ts`
+
+**Instruction:** Include JSDoc-style documentation (e.g., `/** @module ComponentName */` for modules, `/** ... */` for classes, methods, and properties) for all new files, especially components, helpers, services, and complex functions.
+
+**Instruction:** Remove all unused code, imports, or constants to keep the codebase clean and efficient.
+
+**Instruction:** Avoid using `console.error`. Instead, use Ember's `assert` for runtime checks or `debug` for logging during development.
+
+**Instruction:** Ensure all comments are up-to-date and accurately reflect the current code logic. Remove or update outdated comments.
+
+**Instruction:** Avoid using the `any` type in TypeScript files. Strive for strict typing to improve code predictability and maintainability.
+
+**Instruction:** Only use `@task` from `ember-concurrency` when you specifically need to leverage its advanced features like `isRunning`, `perform`, `cancel`, or task modifiers. Otherwise, prefer standard `async`/`await` with `try`/`catch` blocks for asynchronous operations.
+
+**Instruction:** If `setTimeout` is used, consider whether `requestAnimationFrame`, `@tracked` properties with getters, or other reactive Ember patterns might be more appropriate. `setTimeout` can lead to testing complexities and event loop management issues.
+
+**Instruction:** Do not use `new Date()` directly. To ensure consistent UTC date calculations across all environments, use `Date.UTC(...)` and `getUTCFullYear()`, `getUTCMonth()`, etc. for date manipulation.
+
+### For Files in the `tests` Directory
+
+**Instruction:** Replace `setTimeout` with Ember's `run.later` method within tests for better control over the Ember runloop.
+
+**Instruction:** When using `ember-cli-mirage`, place all `this.server` setup steps at the top of the `test` or `module` block for clarity and consistency.
+
+**Instruction:** Avoid using `assert.ok()`. Prefer `assert.true()` or `assert.false()` for clearer boolean assertions.
+
+**Instruction:** Provide clear, descriptive messages for all assertions to aid in debugging test failures.
+
+* **DON'T:** `assert.dom(GENERAL.messageError).hasText('Error');`
+* **DO:** `assert.dom(GENERAL.messageError).hasText('Error', "Verify that the error message is displayed correctly.");`
+
+**Instruction:** Use `data-test-*` selectors for all DOM interactions within tests. This decouples tests from presentational styles and markup changes.
+
+### For Files Ending in `.hbs` (Handlebars Templates)
+
+**Instruction:** Avoid using the `.length` property in logical operators within `{{if}}` or `{{unless}}` helpers for arrays. Empty arrays are already considered falsy in Ember templates.
+
+* **DON'T:** `{{#if (gt this.model.allowed_roles.length 0)}}`
+* **DO:** `{{#if this.model.allowed_roles}}`
+
+**Instruction:** Avoid using the `{{concat}}` helper. Prefer string interpolation directly within attributes for cleaner syntax.
+
+* **DON'T:** `@secret={{concat "role/" @model.id}}`
+* **DO:** `@secret="role/{{@model.id}}"`
+
+**Instruction:** Ensure that any links leading to `vaut/docs` are rendered using `Hds::Link::Inline` and not a standard `<button>`.
+
+**Instruction:** Do not use unnecessary quotation marks around double curly brace expressions when passing dynamic values to component arguments.
+
+* **DON'T:** `@user="{{@model.name}}"`
+* **DO:** `@user={{@model.name}}`
+
+**Instruction:** For `selected` attributes, the passed-in property should almost always be dynamic. If a static value (e.g., `true` or a fixed string) is used, suggest a review to confirm it is intentional and correct.
+
+* **DON'T:** `selected="true"`
+* **DO:** `selected={{eq this.selectedAuthMethod type}}`
+
+**Instruction:** If a conditional wraps an entire element, refactor it so the conditional wraps only the dynamic *content* within the element, improving readability and reducing HTML boilerplate.
+
+* **DON'T:**
+    ```handlebars
+    {{#if this.version.isEnterprise}}
+      <PH.Title>Enterprise things</PH.Title>
+    {{else}}
+      <PH.Title>Community things</PH.Title>
+    {{/if}}
+    ```
+* **DO:** `<PH.Title>{{if this.version.isEnterprise "Enterprise things" "Community things"}}</PH.Title>`
+
+**Instruction:** Avoid using the `style` attribute for inline styling. Define and use CSS classes within `.scss` files instead.
+
+* **DON'T:** (This is a corrected example you provided, but the original was missing the 'style' attribute to demonstrate the 'DONT'. Assuming your intention was to show moving test selectors.)
+
+* **DO:** (The example you gave previously for 'Correct' for `style` was already good, I'll clarify the `data-test` rule below. For `style` attribute, the `DO` would look like this if you had classes defined instead of inline styles.)
+
+**Instruction:** Place `data-test-*` selectors as the *last* attribute on an HTML element for consistency and ease of parsing.
+
+* **DON'T:** (The example you provided for this `data-test` rule appears to be the same as the previous one, where the `data-test-save` was inside the attributes, but not necessarily last. I'll modify the `DON'T` to make it more explicit for `data-test` position.)
+    ```handlebars
+    <Hds::Button
+      data-test-save
+      @text={{if (eq @mountType "secret") "Enable engine" "Enable method"}}
+      type="submit"
+    />
+    ```
+* **DO:**
+    ```handlebars
+    <Hds::Button
+      @text={{if (eq @mountType "secret") "Enable engine" "Enable method"}}
+      type="submit"
+      data-test-save
+    />
+    ```
+
+### For Files Ending in `.scss`
+
+**Instruction:** Avoid using `z-index`. Instead, manage element stacking order by adjusting their natural order in the template (DOM structure).
+
+* **DON'T:**
+    ```css
+    .modal {
+      position: absolute;
+      z-index: 10;
+    }
+    ```
+* **DO:** (This instruction implies the HTML change, so the SCSS `DO` is the absence of `z-index`).
+    ```css
+    /* Adjust HTML structure to control stacking instead of z-index */
+    .modal {
+      position: absolute;
+      /* no z-index needed if stacking context is managed by DOM order */
+    }
+    ```
+
+**Instruction:** Avoid using `!important`. Instead, achieve desired style overrides by increasing CSS specificity (e.g., by targeting elements with more specific selectors or by using component-scoped styles).
+
+* **DON'T:**
+    ```css
+    .button {
+      color: red !important;
+    }
+    ```
+* **DO:**
+    ```css
+    .namespace-picker .button { /* More specific selector */
+      color: red;
+    }
+    ```
+
+### For Changes to `package.json`
+
+**Instruction:** Ensure `package.json` changes are independent and minimal, relating only to the immediate feature or bug fix. The `yarn.lock` file is the only expected co-change.
+
+**Instruction:** When adding or modifying dependencies, prefer pinning exact versions or using the tilde (`~`) for patch-level updates. Avoid using the caret (`^`) operator for dependency versions.
+
+* **DON'T:** `"ansi-html": "^0.0.8"`
+* **DO:** `"ansi-html": "~0.0.8"` or `"ansi-html": "0.0.8"`
+
+**Instruction:** Dependencies within the `resolutions` block must always be pinned to an exact version (no `~` or `^`).
+
+## General Guidelines
+
+**Instruction:** Replace deprecated `Route.extend`, `Model.extend`, or `Component.extend` syntax with their modern Ember Octane class-based equivalents.
+
+**Instruction:** Place comments directly above the code lines or blocks they describe, not below or interspersed.
+
+**Instruction:** Use sentence case for all titles (e.g., for component arguments like `@title`).
+
+* **DON'T:** `@title="Upload Users'sProfile"`
+* **DO:** `@title="Upload user's profile"`
+
+**Instruction:** Ensure all subtitles and descriptive text follow proper grammar rules, including ending sentences with periods.
+
+**Instruction:** All new components (but not tests) should be co-located within their logical structure inside the `app/components` directory.
+
+**Instruction:** Adhere to Ember's built-in best practices for code structure and syntax, consulting the official Ember documentation for the specific version in use.
+
+**Instruction:** Prioritize creating reusable and maintainable code. Avoid overly complex or one-off component/route implementations without strong justification.
+
+**Instruction:** When referring to KV secret engines, use the precise terms "KVv2" or "KVv1". When space allows, prefer spelling out "KV version 2" or "KV version 1".
+
+* **DON'T:** `KV v2`
+* **DO:** `KV version 2` or `KVv2` (depending on space/context)
+
+## Debugging Tips (Informational, not for Copilot to "enforce")
+
+* **Tip:** When using `{{debugger}}` inside a template, you can inspect values in the browser console.
+    * **Example:**
+        ```handlebars
+        {{#each this.items as |item|}}
+          {{debugger}}
+        {{/each}}
+        ```
+    * **In the console:**
+        * Use `get('item.name')` to inspect an item's property.
+        * Use `context` to explore the current rendering context.

ui/package.json

@@ -11,6 +11,7 @@
   "scripts": {
     "build": "ember build --environment=production && cp metadata.json ../http/web_ui/metadata.json",
     "build:dev": "ember build",
+    "copilot": "echo \"To review your changes against our custom guidelines, do one of the following:\n\n1. In VS Code, open the files you've changed. Use Copilot Chat (Ctrl+Alt+I) and reference our guidelines in .github/copilot-instructions.md by typing '@workspace /review' and then specifically asking about your changes and our guidelines.\n2. When creating a Pull Request, ensure 'Request pull request review from Copilot' is enabled (if configured by your org/repo).\n\nRemember to consult .github/copilot-instructions.md for our project's common mistakes and best practices before committing!\"",
     "docs": "sh scripts/generate-docs.sh",
     "docfy-md": "node scripts/docfy-md.js",
     "lint:css": "stylelint \"**/*.css\"",