From 935241e1736137300fa398200a40d7f8ff7b1dec Mon Sep 17 00:00:00 2001 From: Matt Bodle Date: Wed, 11 Mar 2026 15:16:13 -0400 Subject: [PATCH 1/2] docs: Add AGENTS.md with repo conventions for AI agents Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 90 +++++++++++++------------------------------------------ 1 file changed, 21 insertions(+), 69 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2ab458b..ff60351 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,84 +1,36 @@ -# Rokt Web Kit - Agent Instructions +# Agent Guidelines -This file provides guidance for AI coding agents working with the Rokt web kit codebase. +Instructions for AI agents working on this repository. -## About This Kit +## Branch Naming and Commit Conventions -The Rokt web kit (`@mparticle/web-rokt-kit`) is an mParticle integration kit (forwarder) that bridges the mParticle Web SDK and the Rokt Web SDK. It receives events from mParticle and forwards them to Rokt for placement selection, user targeting, and attribution. +Branch names must use a conventional commit prefix (e.g., `feat/`, `fix/`, `chore/`). This is enforced by CI. See `CONTRIBUTING.md` for the full list of allowed types and commit message format. -**Module ID**: 181 +## Do Not Commit Build Artifacts -## Tech Stack +The `dist/` folder, `CHANGELOG.md`, and version bumps in `package.json`/`package-lock.json` are all generated by the CI/CD release process. Only commit changes to source (`src/`) and test (`test/`) files. -- **Language**: Plain JavaScript project — kit source is ES5-style; tests/tooling may use ES6. There is no TypeScript compilation step. -- **Build Tool**: Rollup (IIFE and CommonJS output) -- **Testing**: Karma + Mocha/Chai (real browser tests in Chrome and Firefox) -- **Package Manager**: npm -- **Code Quality**: ESLint +## Git Push (SAML SSO) -## Project Structure +The `mparticle-integrations` GitHub org enforces SAML SSO. SSH push will fail. To push: -``` -/ - src/ - Rokt-Kit.js # Single monolithic source file (~900 lines) - dist/ - Rokt-Kit.iife.js # Browser bundle (IIFE) - Rokt-Kit.common.js # npm bundle (CommonJS) - test/ - src/ - tests.js # Mocha/Chai test suite - config.js # Test mParticle configuration - karma.config.js # Karma test runner config - lib/ # Test utilities - end-to-end-testapp/ # E2E test app - rollup.config.js # Build configuration - package.json -``` +1. Run `gh auth setup-git` to configure the git credential helper. +2. Temporarily switch the remote to HTTPS: `git remote set-url origin https://github.com/mparticle-integrations/mparticle-javascript-integration-rokt.git` +3. Push the branch. +4. Restore the SSH remote: `git remote set-url origin git@github.com:mparticle-integrations/mparticle-javascript-integration-rokt.git` -## Key Commands +## Running Tests ```bash -npm run build # Build IIFE and CommonJS bundles -npm run build:test # Build test bundle -npm run lint # ESLint check (src/ and test/src/) -npm run lint:fix # ESLint autofix -npm run test # Build + build tests + run Karma -npm run test:debug # Non-headless Chrome for debugging -npm run watch # Watch and rebuild on changes +npm install +npm test -- --browsers ChromeHeadless # FirefoxHeadless may not be available ``` -## Code Conventions - -- **Single source file**: All kit logic lives in `src/Rokt-Kit.js` -- **Constructor function pattern**: `var constructor = function() { ... }` with `var self = this;` -- **var declarations**: The codebase uses `var` throughout — match this style -- **No TypeScript**: No type annotations, no interfaces, no generics -- **Module registration**: Kit self-registers via `window.mParticle.addForwarder()` at load time - -## Architecture - -- Kit is an mParticle forwarder that self-registers via `window.mParticle.addForwarder()` at load time -- Kit attaches to the Rokt manager: `window.mParticle.Rokt.attachKit(self)` -- Rokt launcher loads asynchronously — events are queued until it's ready -- Configuration comes from mParticle server-side kit settings - -## Testing Patterns +## Linting -- Tests use Mocha `describe`/`it` blocks with Chai `expect` assertions -- mParticle SDK is mocked in test config -- Rokt launcher is mocked with spy functions -- `beforeEach` resets kit state between tests -- Tests run in real browsers (Chrome, Firefox) via Karma - -## Common Gotchas - -1. **Single file**: All changes go in `src/Rokt-Kit.js` — there are no imports/modules -2. **Browser-only**: Code runs in browser context, `window` is always available -3. **Async launcher**: Rokt launcher loads asynchronously — events must be queued until ready -4. **var scope**: Use `var` not `let`/`const` to match existing style -5. **self reference**: Use `var self = this;` pattern for callback context - -## Available Skills +```bash +npm run lint # check +npm run lint:fix # auto-fix +``` -- **`/verify`**: Run lint, build, and tests to validate your changes. **You MUST run `/verify` before committing or opening a pull request.** Do not skip this step. See `.claude/skills/verify/skill.md`. +Always run lint before pushing. The CI enforces Prettier formatting. From 5fb52e12090648b634c79854eab4a70fb19797f0 Mon Sep 17 00:00:00 2001 From: Alexander Sapountzis Date: Wed, 25 Mar 2026 10:38:08 -0400 Subject: [PATCH 2/2] docs: add build artifacts rule and CLAUDE.md symlink MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extends the existing AGENTS.md with a "Build Artifacts — Do Not Commit" section and adds a CLAUDE.md symlink so Claude Code picks it up automatically. --- AGENTS.md | 94 ++++++++++++++++++++++++++++++++++++++++++------------- CLAUDE.md | 1 + 2 files changed, 74 insertions(+), 21 deletions(-) create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index ff60351..75755cf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,36 +1,88 @@ -# Agent Guidelines +# Rokt Web Kit - Agent Instructions -Instructions for AI agents working on this repository. +This file provides guidance for AI coding agents working with the Rokt web kit codebase. -## Branch Naming and Commit Conventions +## About This Kit -Branch names must use a conventional commit prefix (e.g., `feat/`, `fix/`, `chore/`). This is enforced by CI. See `CONTRIBUTING.md` for the full list of allowed types and commit message format. +The Rokt web kit (`@mparticle/web-rokt-kit`) is an mParticle integration kit (forwarder) that bridges the mParticle Web SDK and the Rokt Web SDK. It receives events from mParticle and forwards them to Rokt for placement selection, user targeting, and attribution. -## Do Not Commit Build Artifacts +**Module ID**: 181 -The `dist/` folder, `CHANGELOG.md`, and version bumps in `package.json`/`package-lock.json` are all generated by the CI/CD release process. Only commit changes to source (`src/`) and test (`test/`) files. +## Tech Stack -## Git Push (SAML SSO) +- **Language**: Plain JavaScript project — kit source is ES5-style; tests/tooling may use ES6. There is no TypeScript compilation step. +- **Build Tool**: Rollup (IIFE and CommonJS output) +- **Testing**: Karma + Mocha/Chai (real browser tests in Chrome and Firefox) +- **Package Manager**: npm +- **Code Quality**: ESLint -The `mparticle-integrations` GitHub org enforces SAML SSO. SSH push will fail. To push: +## Project Structure -1. Run `gh auth setup-git` to configure the git credential helper. -2. Temporarily switch the remote to HTTPS: `git remote set-url origin https://github.com/mparticle-integrations/mparticle-javascript-integration-rokt.git` -3. Push the branch. -4. Restore the SSH remote: `git remote set-url origin git@github.com:mparticle-integrations/mparticle-javascript-integration-rokt.git` +``` +/ + src/ + Rokt-Kit.js # Single monolithic source file (~900 lines) + dist/ + Rokt-Kit.iife.js # Browser bundle (IIFE) + Rokt-Kit.common.js # npm bundle (CommonJS) + test/ + src/ + tests.js # Mocha/Chai test suite + config.js # Test mParticle configuration + karma.config.js # Karma test runner config + lib/ # Test utilities + end-to-end-testapp/ # E2E test app + rollup.config.js # Build configuration + package.json +``` -## Running Tests +## Key Commands ```bash -npm install -npm test -- --browsers ChromeHeadless # FirefoxHeadless may not be available +npm run build # Build IIFE and CommonJS bundles +npm run build:test # Build test bundle +npm run lint # ESLint check (src/ and test/src/) +npm run lint:fix # ESLint autofix +npm run test # Build + build tests + run Karma +npm run test:debug # Non-headless Chrome for debugging +npm run watch # Watch and rebuild on changes ``` -## Linting +## Build Artifacts — Do Not Commit -```bash -npm run lint # check -npm run lint:fix # auto-fix -``` +The `dist/` folder, `CHANGELOG.md`, and version bumps in `package.json`/`package-lock.json` are all generated by the CI/CD release process. **Do not commit these manually.** Only commit changes to source (`src/`) and test (`test/`) files. + +## Code Conventions + +- **Single source file**: All kit logic lives in `src/Rokt-Kit.js` +- **Constructor function pattern**: `var constructor = function() { ... }` with `var self = this;` +- **var declarations**: The codebase uses `var` throughout — match this style +- **No TypeScript**: No type annotations, no interfaces, no generics +- **Module registration**: Kit self-registers via `window.mParticle.addForwarder()` at load time + +## Architecture + +- Kit is an mParticle forwarder that self-registers via `window.mParticle.addForwarder()` at load time +- Kit attaches to the Rokt manager: `window.mParticle.Rokt.attachKit(self)` +- Rokt launcher loads asynchronously — events are queued until it's ready +- Configuration comes from mParticle server-side kit settings + +## Testing Patterns + +- Tests use Mocha `describe`/`it` blocks with Chai `expect` assertions +- mParticle SDK is mocked in test config +- Rokt launcher is mocked with spy functions +- `beforeEach` resets kit state between tests +- Tests run in real browsers (Chrome, Firefox) via Karma + +## Common Gotchas + +1. **Single file**: All changes go in `src/Rokt-Kit.js` — there are no imports/modules +2. **Browser-only**: Code runs in browser context, `window` is always available +3. **Async launcher**: Rokt launcher loads asynchronously — events must be queued until ready +4. **var scope**: Use `var` not `let`/`const` to match existing style +5. **self reference**: Use `var self = this;` pattern for callback context + +## Available Skills -Always run lint before pushing. The CI enforces Prettier formatting. +- **`/verify`**: Run lint, build, and tests to validate your changes. **You MUST run `/verify` before committing or opening a pull request.** Do not skip this step. See `.claude/skills/verify/skill.md`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file