@researchdatabox/redbox-dev-tools 0.0.1 → 5.0.0-RC1

package/skills/redbox-feature-implementation-review/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: 'Redbox Feature Implementation Review'
+description: 'Review completed ReDBox feature implementations against a growing ruleset and emit structured issues for agent remediation.'
+---
+
+# Skill: Redbox Feature Implementation Review
+
+## Purpose
+
+Use this skill after a feature implementation lands (services, controllers, models, Angular app) to verify adherence to platform rules and report actionable issues that can be looped back into an agent for fixes.
+
+## Inputs
+
+- `implementation_plan.md` for expected schema, flows, and required components.
+- The feature’s code changes in core-types, app, and angular directories.
+
+## Review Workflow
+
+1. Read `implementation_plan.md` and list expected services, models, controllers, routes, and UI surfaces.
+2. Locate the implemented code and tests.
+3. Evaluate each rule below and record any violations as structured issues.
+4. Emit only violations; do not propose unrelated refactors.
+
+## Rule Checks
+
+### Type-safety / Any-casts
+
+1. Search the implementation for usages of `as any`, `(object as any)`, `as unknown as`, or other patterns that cast to `any` to bypass TypeScript types.
+   - Rationale: model and service code must adhere to declared Waterline model interfaces; casting to `any` hides mismatches and leads to runtime failures.
+   - Expected behavior: replace casts with proper interfaces, refine types, or add clear TODOs referencing a follow-up task (do not permanently use `as any`).
+   - Area mapping: set `area` to match the location of the cast (use `services` for service code, `models` for Waterline models, `controllers` for backend controllers, and `angular` for Angular/front-end code).
+     Example: `packages/redbox-core/src/services/FooService.ts` -> `area: services`.
+   - Severity: treat `as any` casts in model/service code as `blocker`; in controllers or angular code treat as `major` or `minor` depending on context but always report.
+   - Evidence: include the exact file, line range, and code snippet where the cast occurs, and ensure the reported `area` matches the file type where the cast appears.
+
+### Services
+
+1. Services extend `CoreService`.
+   - Expected location: `packages/redbox-core/src/services`.
+2. Each service has a unit test in `packages/redbox-core/test`.
+3. Each service has at least one integration test in `typescript/test/unit` (prefer `typescript/test/unit/services`).
+4. Avoid redundant local service declarations.
+   - Rationale: Sails places services on the global scope (and via `sails.services`), so declaring `declare const SomeService` or creating local service aliases in controllers or other modules (a common pattern added by debugging agents) is unnecessary and can cause confusion or type drift.
+   - Expected behavior: reference services via the canonical global (e.g. `SomeService`, `sails.services.someservice`, or via dependency access patterns used elsewhere in the repo) and remove local `declare const` statements or redundant `const X = globalThis.X` aliases.
+   - Area mapping: `controllers` or `angular` depending on where the declaration appears.
+   - Severity: `minor` for stylistic fixes, `major` if the declaration hides or masks a different service implementation.
+   - Evidence: include the exact file, line range, and snippet where the local declaration occurs (e.g., `declare const VocabularyService: ...`).
+   - Suggested fix: remove the local declaration and use the global service reference; update typings if necessary instead of duplicating runtime declarations.
+
+### Waterline Models
+
+1. The schema matches `implementation_plan.md`.
+2. Models are defined in `packages/redbox-core/src/waterline-models`.
+3. Avoid using `globalThis` to access Waterline models.
+   - Rationale: Waterline models are exposed as global variables (for example `Vocabulary`, `VocabularyEntry`) by Sails at runtime. Wrapping them again with `globalThis` lookups (e.g., `globalThis as typeof globalThis & { Vocabulary?: ... }`) is unnecessary and noisy; prefer referencing the global model by name and, if needed, cast to the appropriate model interface for typing only (e.g., `const VocabularyModel = Vocabulary as unknown as VocabularyWaterlineModel`).
+   - Expected behavior: use direct global model references in service/controller code instead of building `globalThis` accessor objects.
+   - Area mapping: `services`, `controllers` where Waterline models are used.
+   - Severity: `minor` for stylistic/clarity fixes, `major` if the `globalThis` indirection caused incorrect model resolution.
+   - Evidence: include file path, line range, and snippet where `globalThis` is used to access models.
+   - Suggested fix: replace `globalThis` lookups with direct model names and add a local typed alias only for TypeScript typing (see example above).
+
+### Controllers
+
+1. Controllers extend `CoreController`.
+2. All controller actions use `this.sendResp` for responses.
+   - Never use `res.json`, `res.send`, `this.apiRespond`, or `this.ajaxRespond`.
+3. Routing includes both:
+   - CSRF-secured routes on `/:branding/:portal/<path>`.
+   - Non-CSRF routes on `/:branding/:portal/api/<path>`.
+4. Navigation configuration is set for any new pages or menus.
+   - Check core-types config models (for example `packages/redbox-core/src/configmodels/MenuConfig.ts`) and any branding defaults touched by the feature.
+5. Controllers include unit tests.
+   - Expected location: `packages/redbox-core/test`.
+6. Controllers include integration tests for Bruno.
+   - Expected location: `test/bruno`.
+
+### Angular App
+
+1. Angular services use `HttpClientService`.
+2. The app does not define Angular routing (not an SPA).
+3. Angular apps include tests.
+   - Expected: unit tests for the app runnable via `ng test <app-name>` (located under `angular/projects/<app-name>/`), and any e2e or integration suites as appropriate.
+
+## Output Format
+
+If any issues are found: return a JSON payload with an `issues` array. Each issue must include:
+
+- `id`: short unique identifier (e.g., `svc-extends-core`).
+- `area`: `services`, `models`, `controllers`, or `angular`.
+- `rule`: the rule text that failed.
+- `severity`: `blocker`, `major`, or `minor`.
+- `message`: clear, actionable description.
+- `file`: path to the violating file.
+- `lines`: line range string (e.g., `L12-L40`) or `null` if unknown.
+- `evidence`: snippet or description pointing to the violation.
+- `suggested_fix`: concise change that resolves the issue.
+
+If no issues are found: output the exact ASCII string (without quotes):
+
+NO ISSUES FOUND
+
+Example payload when issues exist:
+{
+"issues": [
+{
+"id": "controller-sendresp",
+"area": "controllers",
+"rule": "All controller actions use this.sendResp for responses.",
+"severity": "major",
+"message": "Controller action uses res.json instead of this.sendResp.",
+"file": "packages/redbox-core/src/controllers/MyController.ts",
+"lines": "L88-L96",
+"evidence": "res.json({ ok: true })",
+"suggested_fix": "Replace res.json with this.sendResp(res, 200, payload)."
+}
+]
+}

package/skills/redbox-form-components/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: 'Redbox Form Components'
+description: 'Build or update ReDBox form field components end-to-end across Angular form rendering and sails-ng-common config typing/visitor infrastructure. Use when creating a new form component class/model, adding component config properties, wiring component dictionaries, handling config migration/template extraction, or adding form-component tests.'
+---
+
+# Skill: Redbox Form Components
+
+Use this workflow to add a new form component that is actually usable in form config, construct/migrate/template visitors, and Angular runtime.
+
+## Start With Generator
+
+- First run the hook-kit scaffold command:
+- `redbox-dev-tools generate form-component <name> --app form`
+- Optional companion service scaffold:
+- `redbox-dev-tools generate form-component <name> --app form --with-service`
+- Treat the generated files as the baseline, then implement component-specific config properties, rendering logic, and visitor custom behavior.
+
+## Canonical Example
+
+- Treat `CheckboxTreeComponent` as the reference implementation:
+- `angular/projects/researchdatabox/form/src/app/component/checkbox-tree.component.ts`
+- `packages/sails-ng-common/src/config/component/checkbox-tree.outline.ts`
+- `packages/sails-ng-common/src/config/component/checkbox-tree.model.ts`
+
+## Implementation Workflow
+
+1. Define component and model contracts in `sails-ng-common`.
+2. Register those contracts in dictionary/type unions.
+3. Add visitor methods everywhere (`base.*` plus concrete visitors).
+4. Implement Angular component/model and register them in the form app.
+5. Add/update supporting services only if the component needs API data.
+6. Add tests for runtime behavior and visitor behavior.
+
+## 1) Define the component contract (`sails-ng-common`)
+
+- Create `packages/sails-ng-common/src/config/component/<component>.outline.ts`.
+- Export component/model name constants (`<ComponentName>`, `<ModelName>`).
+- Define config frames/outlines for both field component and field model.
+- Define form component frame/outline and final `<Component>Types` union.
+- Create `packages/sails-ng-common/src/config/component/<component>.model.ts`.
+- Implement config/definition/model classes with `accept(visitor)` methods.
+- Export `<Component>Map` and `<Component>Defaults`.
+
+## 2) Register dictionary and exports
+
+- Add `<Component>Types` to `AllTypes` in `packages/sails-ng-common/src/config/dictionary.outline.ts`.
+- Add `<Component>Map` into `AllDefs` and `<Component>Defaults` into `RawDefaults` in `packages/sails-ng-common/src/config/dictionary.model.ts`.
+- Export the new outline/model files in `packages/sails-ng-common/src/index.ts`.
+
+## 3) Wire visitor infrastructure
+
+- Add methods to `packages/sails-ng-common/src/config/visitor/base.outline.ts`:
+- `visit<Component>FieldComponentDefinition`
+- `visit<Component>FieldModelDefinition`
+- `visit<Component>FormComponentDefinition`
+- Add default stubs in `packages/sails-ng-common/src/config/visitor/base.model.ts`.
+- Add pass-through/validation methods in:
+- `construct.visitor.ts` (usually includes config property overrides)
+- `client.visitor.ts`
+- `data-value.visitor.ts`
+- `json-type-def.visitor.ts`
+- `validator.visitor.ts`
+- `template.visitor.ts` (extract template-capable fields, if any)
+- `migrate-config-v4-v5.visitor.ts` (legacy class mapping + coercion/defaults/warnings as needed)
+
+If the component uses `inlineVocab`, update `packages/redbox-core/src/visitor/vocab-inline.visitor.ts` to resolve vocab data into the component config shape.
+
+## 4) Implement Angular form component
+
+- Create `angular/projects/researchdatabox/form/src/app/component/<component>.component.ts`.
+- Create `<Component>Model` extending `FormFieldModel<T>`.
+- Create `<Component>Component` extending `FormFieldBaseComponent<T>`.
+- Read component config in `setPropertiesFromComponentMapEntry`.
+- Do async bootstrapping in `initData` for remote data.
+- Keep model sync explicit (`formControl.setValue`, dirty/touched updates).
+- Include accessibility semantics for interactive components (`role`, `aria-*`, keyboard behavior).
+
+Register Angular wiring:
+
+- Add component to `declarations` in `angular/projects/researchdatabox/form/src/app/form.module.ts`.
+- Add component/model class maps in `angular/projects/researchdatabox/form/src/app/static-comp-field.dictionary.ts`.
+
+## 5) Add supporting service (if needed)
+
+- If component makes API calls, create `angular/projects/researchdatabox/form/src/app/service/<service>.service.ts`.
+- Prefer extending `HttpClientService`.
+- Enable CSRF context in `waitForInit()`.
+- Normalize old/new response shapes if backend compatibility is required.
+
+If new backend endpoints are needed, update `redbox-core` controller/service/routes and add tests there.
+
+## 6) Testing gates
+
+- Add component spec:
+- `angular/projects/researchdatabox/form/src/app/component/<component>.component.spec.ts`
+- Cover at least:
+- render/create
+- config-driven behavior
+- model update correctness
+- keyboard/accessibility behavior for interactive components
+- loading/error states for async branches
+- Add Angular service spec when service is introduced:
+- `angular/projects/researchdatabox/form/src/app/service/<service>.service.spec.ts`
+- Add visitor tests for:
+- construct visitor mapping
+- migration visitor mapping/coercion
+- template visitor extraction (if template fields exist)
+- vocab-inline behavior (if inline vocab is supported)
+
+## Quality Rules
+
+- Keep type safety strict; do not use `as any` to bypass type issues.
+- Keep selection/model semantics explicit; do not hide side effects.
+- Prefer deterministic config defaults and migration coercions with warnings for malformed legacy input.

package/skills/redbox-form-config/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: "Redbox Form Config"
+description: "ReDBox uses a JSON-based DSL for configuring record forms, workflows, and record types."
+---
+
+# Skill: Redbox Form Config
+
+## Context
+ReDBox uses a JSON-based DSL for configuring record forms, workflows, and record types.
+
+## Locations
+- Form configurations: `config/form.js`
+- Workflow configurations: `config/workflow.js`
+- Record type configurations: `config/recordtype.js`
+
+## Key Concepts
+- **Record Type**: Defines the entity (e.g., `rdmp`) and its search filters.
+- **Workflow**: Defines stages (e.g., `draft`, `review`), transitions, roles, and which form to use at each stage.
+- **Form**: Defines the layout and fields.
+- **Field**: Each field has a `class` (usually `Container`), a `compClass` (the Angular component name, e.g., `TextBlockComponent`), and a `definition`.
+
+## Generating Form Fields
+Use the `redbox-dev-tools` CLI generator `generate_form_field`:
+- `name`: Field name as an argument.
+- `--type <type>`: Record type (e.g., `rdmp`).
+
+## Form Expressions
+Dynamic behavior is handled via `expressions`:
+- Listen to events using JSON Pointer paths (e.g., `/form_tab/source_field::field.value.changed`).
+- Apply conditions and templates (using JSONata).
+- Target model or component properties.
+
+## Language Files
+Labels and messages should use keys (starting with `@`) that map to entries in `assets/locales/<language>/translation.json`.

package/skills/redbox-hook-development/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: 'Redbox Hook Development'
+description: 'ReDBox hooks are NPM packages that extend or customize ReDBox functionality. They are loaded during the Sails lift process.'
+---
+
+# Skill: Redbox Hook Development
+
+## Context
+
+ReDBox hooks are NPM packages that extend or customize ReDBox functionality. They are loaded during the Sails lift process.
+
+## Project Structure
+
+- `redbox-hook-[project-name]`
+- `typescript/`: TypeScript source code.
+- `assets/`: Custom assets.
+- `views/`: Custom EJS views.
+- `config/`: Configuration overrides.
+- `form-config/`: Form configuration overrides.
+
+## Hook Capabilities
+
+Declared in `package.json` under the `sails` key:
+
+- `hasModels`: Provides Waterline models.
+- `hasPolicies`: Provides Sails policies.
+- `hasServices`: Provides business logic services (can override core).
+- `hasControllers`: Provides internal/app controllers (Sails controllers used by the portal).
+- `hasWebserviceControllers`: Provides HTTP/webservice-facing controllers (API endpoints).
+- `hasBootstrap`: Provides a startup function.
+- `hasConfig`: Provides configuration object to merge.
+
+## Required Exports
+
+The hook's main entry point (usually `index.ts` compiled to `index.js`) must export registration functions **only** for the capabilities enabled in `package.json`:
+
+- `registerRedboxModels()` — required when `hasModels` is `true`.
+- `registerRedboxPolicies()` — required when `hasPolicies` is `true`.
+- `registerRedboxServices()` — required when `hasServices` is `true`.
+- `registerRedboxControllers()` — required when `hasControllers` is `true` (internal/app controllers).
+- `registerRedboxWebserviceControllers()` — required when `hasWebserviceControllers` is `true` (HTTP/webservice controllers).
+- `registerRedboxBootstrap()` — required when `hasBootstrap` is `true`.
+- `registerRedboxConfig()` — required when `hasConfig` is `true`.
+
+If a capability is disabled, its matching export must be omitted.
+
+## Development with Hook Kit
+
+The `redbox-dev-tools` CLI simplifies hook development:
+
+- Use `init` to scaffold a new project.
+- Use generators to add components (controllers, services, etc.).
+- Use `redbox-dev-tools generate model` to add Waterline models.
+
+## Generating Models
+
+Use the `redbox-dev-tools` CLI generator `generate model`:
+
+- `--identity <identity>`: Waterline identity (table name), defaults to lowercase name.
+- `--attrs <attrs>`: Comma-separated list of attributes (e.g. `name:string:required,age:number`).
+- `--belongs-to <associations>`: Comma-separated belongsTo associations (e.g. `owner:user`).
+- `--has-many <associations>`: Comma-separated hasMany associations (e.g. `pets:animal:owner`).
+
+## Overriding Core Components
+
+To override a core service or controller, register a component with the same name as the core one. It is recommended to extend the core class in your implementation.

package/skills/redbox-services/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: 'Redbox Services'
+description: 'ReDBox business logic is encapsulated in TypeScript services in `@researchdatabox/redbox-core`.'
+---
+
+# Skill: Redbox Services
+
+## Context
+
+ReDBox business logic is encapsulated in TypeScript services in `@researchdatabox/redbox-core`.
+
+## Locations
+
+- Services: `packages/redbox-core/src/services/`
+- Index: `packages/redbox-core/src/services/index.ts`
+
+## Patterns
+
+- Extend `Services.Core.Service`.
+- Implement `bootstrap()` for initialization.
+- Use `_exportedMethods` to define exposed methods.
+- Often use RxJS Observables for async operations.
+- Access Waterline models via globals (e.g., `declare var Record: Model;`).
+
+## Type Safety Guidance
+
+- Do not use `(object as any)`, `as any`, or other deliberate `any` casts to bypass TypeScript compilation errors. Fix the types, declare appropriate interfaces, or request guidance in the skill instead. Maintaining type safety helps prevent runtime errors and keeps the codebase maintainable.
+
+## Generating Services
+
+Use the `redbox-dev-tools` CLI generator `generate_service`:
+
+- `name`: Service name (e.g., `Records`) as an argument.
+- `--methods <list>`: Comma-separated initial methods.
+
+## Adding Methods
+
+Use `redbox-dev-tools generate method` to add methods to an existing service:
+
+- `--file <path>`: Path to the service file.
+- `--method <name>`: Method name.
+
+## Index Updates
+
+When adding a service, update `packages/redbox-core/src/services/index.ts`:
+
+- Import the service module.
+- Re-export the service.
+- Add to `ServiceExports` with a lazy getter.
+
+## Overriding Services in Hooks
+
+Hooks can override core services by registering them in `registerRedboxServices`.
+Override services should extend the core service they are replacing.

package/skills/redbox-test-verification/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: 'Redbox Test Verification'
+description: 'Ensure every new service or controller gets Mocha or Bruno coverage by analyzing the implemented code and writing integration tests.'
+---
+
+# Skill: Redbox Test Verification
+
+## Purpose
+
+Use this skill whenever new business logic or routes are merged so the functionality can be verified by automated tests before release.
+
+## Analyze first
+
+- Inspect the new/updated code in `packages/redbox-core/src/services` (for services) or `packages/redbox-core/src/controllers` plus `config/routes` (for routes) to understand the happy path, dependencies, and any edge cases the feature must cover.
+- Take notes on expected inputs, persisted entities, authorization requirements, and downstream effects; those points become the assertions in the new test.
+
+## Mocha service integration coverage
+
+- For every new/modified service in `packages/redbox-core/src/services`, add an integration test under `typescript/test/integration/services`. Prefer naming the file after the service (e.g., `MyService.test.ts`).
+- These are integration tests (no mocking, full-stack). The test should orchestrate creating real data (often via helper seed utilities), let the service execute against the database, and assert on the persisted state or returned payloads.
+- Import shared fixtures or helpers from `typescript/test/integration/services/helpers` as needed, but focus on exercising the whole service flow (setup data, call the method or endpoint, then read back the data it should have created/updated).
+- Keep the tests in TypeScript, run via Mocha inside the Docker test harness, and update any shared fixtures or `typescript/test/unit/services/index.ts` helpers if required.
+
+## Bruno route coverage
+
+- When a new controller or route is introduced (or an existing route grows new behavior), add a Bruno scenario under `test/bruno` that hits the HTTP endpoint through the normal request pipeline.
+- Reuse existing Bruno test patterns for authentication, parameter passing, and response validation; the new suite should cover the new route name/path plus potential role restrictions.
+- Keep suites grouped under the relevant Bruno folder (e.g., `test/bruno/general`) and ensure the new file is wired into the `test/bruno/run` scripts if needed.
+- Do not toggle CSRF headers/flags in route configs; the Bruno environments already disable CSRF globally in Sails config, so follow the default route definitions.
+
+## Verify by running the suites
+
+- After adding the tests, run the Mocha suite with `npm run test:mocha:mount` (local iteration) or `npm run test:mocha` (CI) to build confidence that the service behaves as expected.
+- For the Bruno scenarios, run `npm run test:bruno:general:mount` (or the appropriate profile) and ensure the new route passes before finishing.
+
+## Documentation
+
+- If the new tests uncover side effects or contract changes, document them in the wiki page that best fits (see `support/wiki/redbox-core.md` or `support/wiki/Redbox-Loader.md`).

package/skills/redbox-testing/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: "Redbox Testing"
+description: "ReDBox uses Mocha for integration testing and Bruno for API testing. All integration tests are run within Docker containers managed by docker-compose profiles."
+---
+
+# Skill: Redbox Testing
+
+## Context
+ReDBox uses Mocha for integration testing and Bruno for API testing. All integration tests are run within Docker containers managed by docker-compose profiles.
+
+## Mocha Tests
+Mocha tests are located in `packages/*/test`. To run them, they are executed within a Docker environment.
+
+### Commands
+- **Run all Mocha tests (Development):**
+  ```bash
+  npm run test:mocha:mount
+  ```
+  This mounts your local code into the test containers, allowing for faster iteration.
+
+- **Run selected Mocha tests (Development):**
+  ```bash
+  RBPORTAL_MOCHA_TESTS="test/unit/services/SolrSearchService.test.js" npm run test:mocha:mount
+  ```
+  Provide space-separated test file paths or glob patterns. The bootstrap test is always included.
+
+- **Run all Mocha tests (CI):**
+  ```bash
+  npm run test:mocha
+  ```
+  This runs the tests using the `portal` profile without mounting local code.
+
+- **Clean up Mocha test resources:**
+  ```bash
+  npm run test:mocha:clean
+  ```
+
+## Bruno Tests
+Bruno is used for API testing. Tests are located in `test/bruno`.
+
+### Commands
+- **Run Bruno OIDC tests (Development):**
+  ```bash
+  npm run test:bruno:oidc:mount
+  ```
+  This runs tests specifically for OIDC authentication flows with mounted code.
+
+- **Run Bruno General tests (Development):**
+  ```bash
+  npm run test:bruno:general:mount
+  ```
+  This runs a general suite of Bruno tests with mounted code.
+
+- **Run Bruno tests (CI):**
+  The non-mount variants (e.g. `npm run test:bruno:oidc`) are intended for CircleCI builds.
+
+- **Cleanup:**
+  Use the corresponding clean command for the test suite you ran:
+  - `npm run test:bruno:clean`
+  - `npm run test:bruno:oidc:clean`
+  - `npm run test:bruno:general:clean`
+
+## Docker Profiles
+These commands utilize Docker Compose profiles to start the necessary services (e.g., `redboxportal`, `keycloak`, `mongo`, `solr`). The `package.json` scripts define which profiles and compose files are used for each test suite.

package/skills/redbox-web-verification/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: 'Web Interface Verification'
+description: "This skill outlines the workflow for verifying the Redbox Portal web interface using the Agent's built-in browser capabilities and natural language test scripts."
+---
+
+# Skill: Web Interface Verification
+
+## Context
+
+This skill outlines the workflow for verifying the Redbox Portal web interface using the Agent's built-in browser capabilities and natural language test scripts.
+
+## Workflow
+
+### 1. Start the Application
+
+Start the application in development mode with the mount profile. The `dev:run` script applies the mount profile implicitly (no extra flags required).
+**Important:** Capture the `CommandId` returned by this command to monitor logs later. The `CommandId` is typically a UUID or numeric ID printed near startup; look for it before or around the "Sails lifted" readiness marker.
+
+```bash
+npm run dev:run
+```
+
+Example output (capture the value after `CommandId:`):
+
+```text
+CommandId: 9f2b5c3a-1d4e-4a6a-9e5b-0a1234567890
+...Sails lifted...
+```
+
+Extract it from the logs with a one-liner (or copy the `CommandId:` line directly):
+
+```bash
+grep -m 1 "CommandId:" .tmp/logs/dev-run.log
+```
+
+Wait for the application to be ready (look for "Sails lifted").
+
+### 2. Launch Browser
+
+Use the `browser_subagent` tool to launch a browser session.
+
+- **TaskName:** Web Verification
+- **Task:** "Open http://localhost:1500 and [Insert Natural Language Script Here]"
+
+### 3. Execute Natural Language Script
+
+Follow the natural language instructions provided by the user.
+**Example Script:**
+
+1. "Login to the system."
+2. "Expectation: You are navigated to `/researcher/home`."
+3. "Navigate to 'My Data'."
+4. "Verify the 'Create Record' button is visible."
+
+**Agent Responsibilities:**
+
+- translate high-level actions (e.g., "Login") into interaction steps (type username, type password, click login).
+- Verify URLs and UI elements match expectations.
+
+### 4. Monitor Logs
+
+While the browser session is active or after a step fails, check the logs of the running application using the `command_status` tool and the captured `CommandId`.
+
+- Look for server-side errors (500s, exceptions) that correlate with UI actions.
+
+### 5. Report Findings
+
+After completing the script or encountering a failure, report the results to the user.
+
+- **Success:** Confirm all steps passed.
+- **Failure:** Detail which step failed, the observed vs. expected behavior, and any relevant server logs.

package/skills/redbox-web-verification/redbox-angular-apps/SKILL.md

@@ -0,0 +1,48 @@
+# Skill: Redbox Angular Apps
+
+## Context
+
+ReDBox uses embedded Angular applications within EJS views instead of a single SPA. Each feature is often its own Angular project.
+
+## Locations
+
+- Angular projects: `angular/projects/researchdatabox/<app-name>/`
+- Output assets: `assets/angular/<app-name>/browser/`
+- EJS views: `views/default/default/admin/<app-name>.ejs`
+
+## Generating Angular Apps
+
+Use the `redbox-dev-tools` CLI generator `generate_angular_app`:
+
+- `name`: App name as an argument (lowercase).
+- `--ejs-view <view>`: EJS view name.
+- `--auth <roles>`: Roles for page access.
+
+## Patterns
+
+- Apps are scaffolded using `@angular-devkit/build-angular:application`.
+- EJS views include the Angular component tag and the hashed JS/CSS bundles.
+- Use `CacheService.getNgAppFileHash(appName, type, prefix)` for hashed asset names. `type` selects the asset category (for example `js`, `css`, `map`, or other build artifact names your bundler emits) and influences the lookup logic; `prefix` is an optional path or name prefix to scope the lookup (for example `vendor/`). If omitted, defaults are used by `CacheService` and an invalid type may fall back to the default asset group.
+  - Example: `CacheService.getNgAppFileHash("myApp", "js", "vendor/")` -> `"vendor/main.abc123.js"`.
+- Apps are usually served via `RenderViewController.render` with the view specified in `locals`.
+
+## angular.json
+
+New projects must be added to `angular.json` with appropriate `outputPath` and `baseHref`.
+Example `outputPath`: `../assets/angular/<name>` and `baseHref`: `/assets/angular/<name>/`
+
+## Testing
+
+To run tests for a specific Angular app:
+
+- `ng test <app-name>`
+- `npm test -- <app-name>`
+
+### Root Execution
+
+If running inside a container as root (e.g. Docker), you must use the `--browsers=ChromeHeadlessNoSandbox` flag:
+`ng test --browsers=ChromeHeadlessNoSandbox <app-name>`
+
+### Convenience Script
+
+A convenience script is available at `support/unit-testing/angular/testDevAngular.sh` which handles the browser flags logic automatically.

package/skills/redbox-web-verification/redbox-angular-services/SKILL.md

@@ -0,0 +1,30 @@
+# Skill: Redbox Angular Services
+
+## Context
+
+Angular services in ReDBox typically extend `HttpClientService` to handle base URLs, configuration, and CSRF protection.
+
+## Location
+
+- Within an Angular project: `angular/projects/researchdatabox/<app-name>/src/app/`
+
+## Patterns
+
+- Extend `HttpClientService` from `@researchdatabox/portal-ng-common`.
+- Inject `HttpClient`, `APP_BASE_HREF`, `UtilityService`, and `ConfigService`.
+- Override `waitForInit()` and call `this.enableCsrfHeader()`.
+- Use `this.brandingAndPortalUrl` for building API URLs.
+- Use `this.httpContext` in request options to include the CSRF token.
+
+## Generating Angular Services
+
+Use the `redbox-dev-tools` CLI generator `generate_angular_service`:
+
+- `name`: Service name as an argument.
+- `--app <app>`: Target Angular app name.
+- `--methods <methods>`: Comma-separated list of methods to generate (e.g. `get,save`).
+
+## CSRF Handling
+
+- `this.enableCsrfHeader()` sets the `RB_HTTP_INTERCEPTOR_AUTH_CSRF` context variable.
+- For `FormData` uploads (file/image uploads or any `multipart/form-data` request), set `RB_HTTP_INTERCEPTOR_SKIP_JSON_CONTENT_TYPE` to `true` so the interceptor does not force `application/json` and the browser can set the correct boundary. This is not needed for JSON payloads or requests that explicitly set `Content-Type: application/json`.