Add AGENTS.md

AGENTS.md

@@ -0,0 +1,125 @@
+# AGENTS.md for Bot Framework Web Chat
+
+## Coding
+
+### Package management
+
+- When adding dependencies, use `npm install`
+   - Do not add it to workspace root
+   - If it is an existing package, must use consistent version: either use existing version for the package or consider bumping every dependents to latest
+- Production code must avoid packages from Node.js packages or polyfills
+   - Use `ReadableStream`, `WritableStream`, `TransformStream`, instead of Node.js `buffer`
+   - Use Web Cryptography instead of Node.js `crypto`
+   - Do not use `fs`-like or `net`-like packages
+   - Do not use any Browserify-like packages
+- When adding pacakges to the following packages, verify:
+   - `/packages/api/` and `/packages/core/`: Newly added packages and transient packages must be platform-neutral
+   - `/packages/test/`: Open to any packages
+   - `/packages/*/`: Newly added packages and transient packages must be either platform-neutral or targetting browser
+- Do not add external/publishing packages unless explicitly requested
+- Always prefix internal/non-publishing packages with `@msinternal/` to prevent package squatting
+
+### General
+
+- Unless stated otherwise, assume browser and React is available, avoid Node.js
+- Apply our latest coding style to every file changed
+- Avoid spaghetti code: on new feature with a similar existing feature, refactor existing one before writing new feature
+   - This does not applies to test code
+- Avoid global pollution, do not modify `window` object
+- Markdown are always space-indented with 3 spaces
+- Use `/prettierrc.yml` to format
+- Sort names in property bags
+- Avoid one-use variable, inline them instead
+- More new lines to separate code with different responsibilities
+   - Multiple lines of code that can run in random order, put them into a group, no need new line between them
+   - Otherwise, lines of code that depends on each other in a specific order, separate them with new line
+- Prefer `&&` over if-statement if it is a oneliner
+- Importing relative file should always include file extension
+- Prefer truthy/false check like `!array.length` over `array.length === 0`
+- Prefer `numValue` over `valueCount` for "how many values are there"
+- Prefer uppercase for acronyms instead of Pascal case, e.g. `getURL()` over `getUrl()`
+   - The only exception is `id`, e.g. `getId()` over `getID()`
+- Use fewer shorthands, only allow `min`, `max`, `num`
+
+### Design
+
+- Use immutability as much as possible, add `object.freeze()`
+- Follow W3C convention for API design
+   - Extends `EventTarget` when eventing is needed, do not use Node.js `on`/`off`
+   - Consider `IntersectionObserver`-like pattern for allow userland to subscribe to live changes
+- Allow ESNext code that is polyfilled by `core-js-pure` or `iter-fest` package
+
+### Typing
+
+- TypeScript is best-effort checking, use valibot for strict type checking
+- Use `valibot` for runtime type checker, never use `zod`
+   - Assume all externally exported functions will receive unsafe/invalid input, always check with `valibot`
+- Avoid `any`
+- Avoid `as`, use `valibot` instead
+   - If absolutely needed, use `satisifes X as Y` to make sure it is `X` before force casting to `Y`
+- Use as few `unknown` as possible
+- All optional properties must be `undefined`-able, i.e. use `value?: number | undefined` over `value?: number`
+- For functions exported outside of current file, make sure all arguments and return value are typed
+- If need to look inside the object to check for types, use `valibot`
+   - E.g. `if (obj && typeof obj === 'object' && 'value' in obj && typeof obj.value === 'string')` should be replaced with `safeParse(object({ value: string }), obj).success`
+- Use `{ readonly value: string }` instead of `Readonly<{ value: string }>`
+- Use as much `readonly` as possible
+
+### React template
+
+```tsx
+import { reactNode, validateProps } from '@msinternal/botframework-webchat-react-valibot';
+import React from 'react';
+import { number, object, pipe, readonly } from 'valibot';
+
+// Use valibot to validate props.
+const MyComponentPropsSchema = pipe(
+  object({
+    children: optional(reactNode())
+  }),
+  readonly()
+);
+
+type MyComponentProps = InferInput<typeof MyComponentPropsSchema>;
+
+// Use big function instead of arrow function.
+function MyComponent(props: MyComponentProps) {
+  // Call `validateProps` to get a validated props.
+  const { children } = validateProps(MyComponentPropsSchema, props);
+
+  // Use `<>` instead of `<Fragment>`.
+  // Never export `children` by itself, always wrap with `<>`.
+  return <>{children}</>;
+}
+
+// Set `displayName`.
+MyComponent.displayName = 'MyComponent';
+
+// Export as memoized/exotic component, export as default.
+export default memo(MyComponent);
+
+// Export both schema and typing.
+export { MyComponentPropsSchema, type MyComponentProps };
+```
+
+## Testing instructions
+
+- Practice test-driven development
+- Build and run Docker to host WebDriver-controlled browser instances
+   - Build container by `docker compose -f docker-compose-wsl2.yml build --build-arg REGISTRY=mcr.microsoft.com`
+   - Start container by `docker compose -f docker-compose-wsl2.yml up --detach --scale chrome=2`
+- Run `curl http://localhost:4444/wd/hub/status` and wait until `.value.ready` become `true`
+- Run `npm test`, or `npm test -- --testPathPattern test-html-file.html` to focus on one
+- Test files are HTML files under `/__tests__/html2/`, they are not JS
+- Follow other HTML files under the same folder on how to write tests
+- Page conditions, page elements, and page objects can be found at `/packages/test/page-object/src/globals`
+- Use `expect` instead of `assert`
+- Use `@testduet/given-when-then` package instead of xUnit style `describe`/`before`/`test`/`after`
+- Prefer integration/end-to-end testing than unit testing
+- Use as realistic setup as possible, such as using `msw` than mocking calls
+
+## PR instructions
+
+- Run new test and all of them must be green
+- Run `npm run precommit` to make sure it pass all linting process
+- Add changelog entry to `CHANGELOG.md`, follow our existing format

packages/api/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md for `botframework-webchat-api`
+
+## Coding
+
+- Allow browser technologies, but no Node.js nor React

packages/base/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md for `botframework-webchat-base`
+
+## Coding
+
+- Stay platform neutral, no browser technologies, no Node.js, no React

packages/core/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md for `botframework-webchat-core`
+
+## Coding
+
+- Stay platform neutral, no browser technologies, no Node.js, no React

packages/test/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md for test framework
+
+## Coding
+
+- All technologies are allowed, including Node.js