From 8448d532c98ae9657f9aa6aa0aa2a85f80c1ec89 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:16:04 +0200 Subject: [PATCH 01/29] docs(agent): add runtime-shadow API widget creation skill --- .../skills/runtime-shadow-api-widget/SKILL.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 .agents/skills/runtime-shadow-api-widget/SKILL.md diff --git a/.agents/skills/runtime-shadow-api-widget/SKILL.md b/.agents/skills/runtime-shadow-api-widget/SKILL.md new file mode 100644 index 00000000..5fc8ae1a --- /dev/null +++ b/.agents/skills/runtime-shadow-api-widget/SKILL.md @@ -0,0 +1,40 @@ +--- +name: runtime-shadow-api-widget +description: Scaffold and validate a ReactEdge runtime-shadow widget that consumes an API through the runtime contract instead of the default GraphQL integration. +--- + +# Runtime-shadow API widget + +Use this skill when asked to create or convert a `runtime-shadow` widget to consume an API rather than GraphQL. + +## Mandatory repository context + +1. Read `AGENTS.md` and `packages/docs/widget-spec.md` before creating widgets. +2. Reuse `packages/widget-build/shared-resources` as required by repository conventions. +3. Locate and inspect the current runtime contract and its API dependency; do not guess interface names or import paths. +4. Locate and inspect the Google Review widget (including its repository if external) to establish the existing system state provider pattern. If unavailable, report the missing reference and do not invent its behavior. +5. Inspect existing widget lifecycle, mount, observability, and test conventions. + +## Procedure + +1. Collect the widget name, API endpoint or API contract, expected response shape, and rendering requirements. Ask only for missing details that cannot be inferred from the repository. +2. Discover the ReactEdge MCP `create widget` operation and inspect its actual schema. Invoke it with widget type `runtime-shadow` and the required widget parameters. Do not invent MCP argument names. +3. Invoke the MCP `validate widget` operation on the untouched scaffold. Fix structural failures before modifying the integration. If MCP is unavailable, report this explicitly; do not claim MCP validation occurred. +4. Inspect the generated GraphQL dependencies, data access, and runtime wiring. Identify the corresponding API dependency anchored in the runtime contract, including request context, authentication, response typing, and error handling. +5. Replace GraphQL-specific imports, queries, and data access with the runtime-provided API dependency. Remove unused GraphQL dependencies only when safe; avoid introducing an independent HTTP client when the runtime already provides one. +6. Integrate the system state provider using the same access, subscription, state-update, and cleanup conventions as the Google Review widget. Adapt only widget-specific behavior. Avoid introducing parallel state infrastructure. +7. Implement typed API data flow with loading, success, empty, and failure states. Handle cancellation or stale responses and cleanup across unmount/remount. Preserve existing widget registration, mount lifecycle, and observability. +8. Run MCP `validate widget` again. Run relevant strict TypeScript, lint, unit, integration, and widget e2e checks as available. Where supported, validate deployed runtime behavior separately from scaffold structure. + +## Architectural constraints + +- Preserve separation of responsibilities between widget code, runtime orchestration, mounting, and observability. +- Follow the actual runtime contract; do not change it without a clearly justified and separately reviewed need. +- Never embed credentials or leak sensitive system state. +- Preserve repository naming, layout, contract schema, and test conventions. +- Do not claim structural validation proves API requests or widget mounting work. +- Do not fabricate MCP operations, runtime interfaces, Google Review behavior, or test outcomes. + +## Completion report + +Report widget path, runtime API dependency used, GraphQL integration removed, system state provider pattern followed, initial/final MCP validation, lint, strict TypeScript, tests, runtime verification, and any unverified behavior. Mark checks not executed as **not run**, not passed. From 9239511f053ba959c254c24cb156a7ba3412fb29 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:24:38 +0200 Subject: [PATCH 02/29] docs(agent): use MCP widget template as scaffold source of truth --- .agents/skills/runtime-shadow-api-widget/SKILL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.agents/skills/runtime-shadow-api-widget/SKILL.md b/.agents/skills/runtime-shadow-api-widget/SKILL.md index 5fc8ae1a..44ccb467 100644 --- a/.agents/skills/runtime-shadow-api-widget/SKILL.md +++ b/.agents/skills/runtime-shadow-api-widget/SKILL.md @@ -9,8 +9,8 @@ Use this skill when asked to create or convert a `runtime-shadow` widget to cons ## Mandatory repository context -1. Read `AGENTS.md` and `packages/docs/widget-spec.md` before creating widgets. -2. Reuse `packages/widget-build/shared-resources` as required by repository conventions. +1. Inspect `packages/widget-template` as the authoritative widget scaffold and structure. Do not use `packages/docs/widget-spec.md` or `packages/widget-build/shared-resources` as the source of truth for creation. +2. Use the ReactEdge MCP `create widget` operation to generate widgets from `packages/widget-template`; do not manually copy the template or create an alternative scaffold. 3. Locate and inspect the current runtime contract and its API dependency; do not guess interface names or import paths. 4. Locate and inspect the Google Review widget (including its repository if external) to establish the existing system state provider pattern. If unavailable, report the missing reference and do not invent its behavior. 5. Inspect existing widget lifecycle, mount, observability, and test conventions. @@ -18,7 +18,7 @@ Use this skill when asked to create or convert a `runtime-shadow` widget to cons ## Procedure 1. Collect the widget name, API endpoint or API contract, expected response shape, and rendering requirements. Ask only for missing details that cannot be inferred from the repository. -2. Discover the ReactEdge MCP `create widget` operation and inspect its actual schema. Invoke it with widget type `runtime-shadow` and the required widget parameters. Do not invent MCP argument names. +2. Discover the ReactEdge MCP `create widget` operation and inspect its actual schema. Invoke it with widget type `runtime-shadow` and the required widget parameters. The MCP operation owns scaffolding from `packages/widget-template`; do not manually reproduce that process or invent MCP argument names. 3. Invoke the MCP `validate widget` operation on the untouched scaffold. Fix structural failures before modifying the integration. If MCP is unavailable, report this explicitly; do not claim MCP validation occurred. 4. Inspect the generated GraphQL dependencies, data access, and runtime wiring. Identify the corresponding API dependency anchored in the runtime contract, including request context, authentication, response typing, and error handling. 5. Replace GraphQL-specific imports, queries, and data access with the runtime-provided API dependency. Remove unused GraphQL dependencies only when safe; avoid introducing an independent HTTP client when the runtime already provides one. @@ -31,7 +31,7 @@ Use this skill when asked to create or convert a `runtime-shadow` widget to cons - Preserve separation of responsibilities between widget code, runtime orchestration, mounting, and observability. - Follow the actual runtime contract; do not change it without a clearly justified and separately reviewed need. - Never embed credentials or leak sensitive system state. -- Preserve repository naming, layout, contract schema, and test conventions. +- Treat `packages/widget-template` and the MCP scaffold operation as the source of truth for widget creation; preserve repository naming, layout, contract schema, and test conventions. - Do not claim structural validation proves API requests or widget mounting work. - Do not fabricate MCP operations, runtime interfaces, Google Review behavior, or test outcomes. From ff93ffc90b7877b9a90d8d2c7eda8ad63f70bc15 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:27:41 +0200 Subject: [PATCH 03/29] docs(agent): remove obsolete widget spec reference from skill --- .agents/skills/runtime-shadow-api-widget/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/runtime-shadow-api-widget/SKILL.md b/.agents/skills/runtime-shadow-api-widget/SKILL.md index 44ccb467..5246f4ac 100644 --- a/.agents/skills/runtime-shadow-api-widget/SKILL.md +++ b/.agents/skills/runtime-shadow-api-widget/SKILL.md @@ -9,7 +9,7 @@ Use this skill when asked to create or convert a `runtime-shadow` widget to cons ## Mandatory repository context -1. Inspect `packages/widget-template` as the authoritative widget scaffold and structure. Do not use `packages/docs/widget-spec.md` or `packages/widget-build/shared-resources` as the source of truth for creation. +1. Inspect `packages/widget-template` as the authoritative widget scaffold and structure. Use the MCP widget creation operation rather than legacy manual scaffolding. 2. Use the ReactEdge MCP `create widget` operation to generate widgets from `packages/widget-template`; do not manually copy the template or create an alternative scaffold. 3. Locate and inspect the current runtime contract and its API dependency; do not guess interface names or import paths. 4. Locate and inspect the Google Review widget (including its repository if external) to establish the existing system state provider pattern. If unavailable, report the missing reference and do not invent its behavior. From 5dc05779c1b3d4abd65dc65b574ccd6a131526b2 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:27:44 +0200 Subject: [PATCH 04/29] docs(agent): align root instructions with MCP widget template --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9f4142e7..9d66fbaf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,5 +2,6 @@ Before creating a widget: -- Read `packages/docs/widget-spec.md`. -- Reuse components from `packages/widget-build/shared-resources`. +- Treat `packages/widget-template` as the source of truth for widget scaffolding. +- Use the ReactEdge MCP `create widget` operation to scaffold from the template; do not manually copy or recreate the scaffold. +- Use the MCP `validate widget` operation to validate the generated structure. From 3011a43da76e6c4ea3e7bbc028a6a40006adeecc Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:27:47 +0200 Subject: [PATCH 05/29] docs: remove obsolete widget specification --- packages/docs/widget-spec.md | 33 --------------------------------- 1 file changed, 33 deletions(-) delete mode 100644 packages/docs/widget-spec.md diff --git a/packages/docs/widget-spec.md b/packages/docs/widget-spec.md deleted file mode 100644 index c8a24352..00000000 --- a/packages/docs/widget-spec.md +++ /dev/null @@ -1,33 +0,0 @@ -# Creating a new widget - -To create a new widget called ``: - -1. Create a new Vite environment named `` using: - - ```json - { - "vite": "^7.2.4" - } - ``` - -2. Copy the contents of: - - ```text - packages/widget-build/shared-resources/vite_project - ``` - - into the root of the new Vite environment. - -3. In the new Vite environment, remove any `.ts` and `.tsx` files that exist in the default Vite project but do not exist in the shared resources. - -4. Replace every occurrence of `usp` with ``. - -At this stage, the goal is not to generate widget-specific code. The goal is simply to create a widget that follows the platform conventions and reuses the shared resources. - -5. Replace the `UspWidget` component with a React component that is relevant to the new widget. - -6. Ensure the React component replacing UspWidget is added in a components folder - -7. Can you update the widget to ensure the zod contract aligns with the json file of the public folder and the widget echo the title from the contract - -8. can you adjust the e2e test in the tests folder to validate the title h1 is visible \ No newline at end of file From 2129efec0faac1d0192b2138df2ae396f3f1395e Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:55:04 +0200 Subject: [PATCH 06/29] docs(agent): add Operational Intelligence MCP Express service skill --- .agents/skills/express-service/SKILL.md | 39 +++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 .agents/skills/express-service/SKILL.md diff --git a/.agents/skills/express-service/SKILL.md b/.agents/skills/express-service/SKILL.md new file mode 100644 index 00000000..53949d90 --- /dev/null +++ b/.agents/skills/express-service/SKILL.md @@ -0,0 +1,39 @@ +--- +name: express-service +description: Create a ReactEdge platform Express service under services/ using the Operational Intelligence MCP scaffold, then validate and implement it according to platform conventions. +--- + +# Express service creation + +Use this skill when asked to create a new Express service in the ReactEdge platform repository. + +## Sources of truth + +1. The destination is `reactedge/platform/services/`. +2. The authoritative service scaffold is the **Operational Intelligence MCP create-service operation** associated with `reactedge/operational-intelligence`. Discover the actual MCP tool and its schema; do not assume its exact tool name, parameters, or output. +3. Inspect `reactedge/operational-intelligence` for its Express service architecture and conventions. Existing services such as `cache-warmer` and `sitemap-planner` may provide useful references, but do not blindly copy their domain logic. +4. Inspect `reactedge/platform/services` for naming, dependency management, scripts, TypeScript/lint configuration, health endpoints, telemetry, deployment, and testing conventions. Respect the platform's actual integration requirements. + +## Workflow + +1. Establish service name, responsibility, API routes/contracts, external dependencies, configuration, and desired behavior. Clarify essential missing requirements. +2. Discover the Operational Intelligence MCP operation that scaffolds an Express server. Inspect its input schema and confirm how its generated files are targeted to `reactedge/platform/services/`. Do not invent MCP arguments or manually substitute a scaffold. +3. Run the MCP scaffold operation. Confirm that the generated service is placed under `services/`, without overwriting existing services or unrelated files. +4. Discover and run the MCP service-structure validation operation **if available**. If the MCP provides no validator, inspect the generated structure against its documented contract and explicitly report that MCP structural validation was unavailable. +5. Inspect the scaffolded routes, application/server separation, middleware, error handling, configuration, and dependencies. Implement the requested service behavior while retaining the generated architectural boundaries. +6. Reuse established platform service patterns for configuration, logging, OpenTelemetry/trace propagation, health checks, shutdown, and dependency injection where relevant. Do not add new infrastructure or dependencies when existing platform facilities meet the need. +7. Add or adjust typed request/response contracts, input validation, failure handling, and tests. Avoid embedding secrets, hardcoded environment-specific endpoints, or unsafe defaults. +8. Re-run MCP validation if supported. Run applicable lint, strict TypeScript, unit/integration tests, build checks, and service health/startup verification. Confirm routes and actual behavior separately from scaffold validity. + +## Constraints + +- Create the service **only** under `reactedge/platform/services/` unless the user explicitly requests a different destination. +- Let the Operational Intelligence MCP own Express scaffolding; do not copy service files manually in place of its generator. +- Preserve the platform's existing separation of responsibilities and integration conventions. +- Do not import widget-specific GraphQL, runtime-shadow, or system state provider requirements into Express services. +- Do not claim that the MCP supports a validator, or that tests and runtime health passed, without verifying them. +- Avoid changing unrelated services or repository-wide configuration unless required and justified. + +## Completion report + +Report the service path, MCP scaffold operation and result, any structural validation operation and result, implemented routes and contracts, dependency/configuration changes, lint, strict TypeScript, tests, build, startup/health checks, and outstanding limitations. Mark unexecuted checks as **not run**. From 60b6edcba81d4fab9930cd19bdbe31624c00679e Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:55:12 +0200 Subject: [PATCH 07/29] docs(agent): route Express service creation through MCP skill --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 9d66fbaf..7881c9bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,3 +5,9 @@ Before creating a widget: - Treat `packages/widget-template` as the source of truth for widget scaffolding. - Use the ReactEdge MCP `create widget` operation to scaffold from the template; do not manually copy or recreate the scaffold. - Use the MCP `validate widget` operation to validate the generated structure. + +Before creating an Express service: + +- Create services under `services/`. +- Use the Operational Intelligence MCP Express scaffold operation, following `.agents/skills/express-service/SKILL.md`. +- Validate the generated service structure with MCP if a validator exists, then run the applicable platform checks. From 196672e9cc08eecfc241649e3336d2e44864ac87 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:59:51 +0200 Subject: [PATCH 08/29] docs(agent): scope Express service conventions to existing services --- .agents/skills/express-service/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/express-service/SKILL.md b/.agents/skills/express-service/SKILL.md index 53949d90..992a7aa7 100644 --- a/.agents/skills/express-service/SKILL.md +++ b/.agents/skills/express-service/SKILL.md @@ -30,7 +30,7 @@ Use this skill when asked to create a new Express service in the ReactEdge platf - Create the service **only** under `reactedge/platform/services/` unless the user explicitly requests a different destination. - Let the Operational Intelligence MCP own Express scaffolding; do not copy service files manually in place of its generator. - Preserve the platform's existing separation of responsibilities and integration conventions. -- Do not import widget-specific GraphQL, runtime-shadow, or system state provider requirements into Express services. +- Use only the established service patterns in `reactedge/platform/services/` when adapting the generated scaffold; do not apply conventions from unrelated platform areas. - Do not claim that the MCP supports a validator, or that tests and runtime health passed, without verifying them. - Avoid changing unrelated services or repository-wide configuration unless required and justified. From e28a5afb76031303172b3ccca8dd8bb3f757c04b Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:07:07 +0200 Subject: [PATCH 09/29] docs(agent): enforce complexity, widget contracts and deployment validation --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 7881c9bd..7411029f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,3 +11,9 @@ Before creating an Express service: - Create services under `services/`. - Use the Operational Intelligence MCP Express scaffold operation, following `.agents/skills/express-service/SKILL.md`. - Validate the generated service structure with MCP if a validator exists, then run the applicable platform checks. + +Platform-wide quality gates: + +- Enforce a maximum Lizard cyclomatic complexity (CCN) of **10 per function** in authored or modified platform source code. Run Lizard on the relevant code; refactor any function above 10. Do not treat a project-wide average as sufficient. Exclude generated, vendored, and dependency files from this source-code gate. +- For every new widget, verify that the widget build and tests pass and that both `public/default.json` and `public/reactedge-runtime.json` exist as contracts. Check that the contracts are valid and consistent with the widget's runtime schema. +- After every completed deployment, run the platform MCP workspace-structure validation operation and report its result. Discover the actual operation/schema; never invent a command or report an unexecuted check as passed. From e87493bce51936b790176ea3250bcad57339b250 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:07:10 +0200 Subject: [PATCH 10/29] docs(agent): enforce complexity, widget contracts and deployment validation --- .agents/skills/runtime-shadow-api-widget/SKILL.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.agents/skills/runtime-shadow-api-widget/SKILL.md b/.agents/skills/runtime-shadow-api-widget/SKILL.md index 5246f4ac..6461275e 100644 --- a/.agents/skills/runtime-shadow-api-widget/SKILL.md +++ b/.agents/skills/runtime-shadow-api-widget/SKILL.md @@ -24,7 +24,8 @@ Use this skill when asked to create or convert a `runtime-shadow` widget to cons 5. Replace GraphQL-specific imports, queries, and data access with the runtime-provided API dependency. Remove unused GraphQL dependencies only when safe; avoid introducing an independent HTTP client when the runtime already provides one. 6. Integrate the system state provider using the same access, subscription, state-update, and cleanup conventions as the Google Review widget. Adapt only widget-specific behavior. Avoid introducing parallel state infrastructure. 7. Implement typed API data flow with loading, success, empty, and failure states. Handle cancellation or stale responses and cleanup across unmount/remount. Preserve existing widget registration, mount lifecycle, and observability. -8. Run MCP `validate widget` again. Run relevant strict TypeScript, lint, unit, integration, and widget e2e checks as available. Where supported, validate deployed runtime behavior separately from scaffold structure. +8. Confirm `public/default.json` and `public/reactedge-runtime.json` exist in the generated widget and validate their JSON and alignment with the runtime/schema contracts. Run the widget build and tests; both must pass before completion. Run MCP `validate widget` again, plus relevant strict TypeScript, lint, integration, and widget e2e checks. Run Lizard on authored/modified source and ensure every function has CCN <= 10. Where supported, validate deployed runtime behavior separately from scaffold structure. +9. After deployment completes, run the platform MCP workspace-structure validation operation. Discover its real schema and report the result; a successful build or widget validation does not substitute for workspace validation. ## Architectural constraints @@ -33,8 +34,9 @@ Use this skill when asked to create or convert a `runtime-shadow` widget to cons - Never embed credentials or leak sensitive system state. - Treat `packages/widget-template` and the MCP scaffold operation as the source of truth for widget creation; preserve repository naming, layout, contract schema, and test conventions. - Do not claim structural validation proves API requests or widget mounting work. +- Do not accept a Lizard CCN above 10 in authored or modified source; refactor complex functions rather than averaging complexity across files. - Do not fabricate MCP operations, runtime interfaces, Google Review behavior, or test outcomes. ## Completion report -Report widget path, runtime API dependency used, GraphQL integration removed, system state provider pattern followed, initial/final MCP validation, lint, strict TypeScript, tests, runtime verification, and any unverified behavior. Mark checks not executed as **not run**, not passed. +Report widget path, runtime API dependency used, GraphQL integration removed, system state provider pattern followed, initial/final MCP validation, lint, strict TypeScript, Lizard maximum CCN, widget build, tests, presence and validity of both public contracts, runtime verification, post-deployment MCP workspace validation (when deployment occurred), and any unverified behavior. Mark checks not executed as **not run**, not passed. From 453027216d1c323805a3abd81f719f0de3fdeec8 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:07:24 +0200 Subject: [PATCH 11/29] docs(agent): enforce complexity, widget contracts and deployment validation --- .agents/skills/express-service/SKILL.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.agents/skills/express-service/SKILL.md b/.agents/skills/express-service/SKILL.md index 992a7aa7..e7d1e96b 100644 --- a/.agents/skills/express-service/SKILL.md +++ b/.agents/skills/express-service/SKILL.md @@ -23,7 +23,8 @@ Use this skill when asked to create a new Express service in the ReactEdge platf 5. Inspect the scaffolded routes, application/server separation, middleware, error handling, configuration, and dependencies. Implement the requested service behavior while retaining the generated architectural boundaries. 6. Reuse established platform service patterns for configuration, logging, OpenTelemetry/trace propagation, health checks, shutdown, and dependency injection where relevant. Do not add new infrastructure or dependencies when existing platform facilities meet the need. 7. Add or adjust typed request/response contracts, input validation, failure handling, and tests. Avoid embedding secrets, hardcoded environment-specific endpoints, or unsafe defaults. -8. Re-run MCP validation if supported. Run applicable lint, strict TypeScript, unit/integration tests, build checks, and service health/startup verification. Confirm routes and actual behavior separately from scaffold validity. +8. Re-run MCP validation if supported. Run applicable lint, strict TypeScript, unit/integration tests, build checks, and service health/startup verification. Run Lizard on authored/modified source; refactor every function with CCN above 10. Confirm routes and actual behavior separately from scaffold validity. +9. After deployment completes, run the platform MCP workspace-structure validation operation and report its result. Discover the actual MCP schema; do not assume the operation name. ## Constraints @@ -33,7 +34,8 @@ Use this skill when asked to create a new Express service in the ReactEdge platf - Use only the established service patterns in `reactedge/platform/services/` when adapting the generated scaffold; do not apply conventions from unrelated platform areas. - Do not claim that the MCP supports a validator, or that tests and runtime health passed, without verifying them. - Avoid changing unrelated services or repository-wide configuration unless required and justified. +- Enforce Lizard CCN <= 10 per function in authored or modified source. ## Completion report -Report the service path, MCP scaffold operation and result, any structural validation operation and result, implemented routes and contracts, dependency/configuration changes, lint, strict TypeScript, tests, build, startup/health checks, and outstanding limitations. Mark unexecuted checks as **not run**. +Report the service path, MCP scaffold operation and result, any structural validation operation and result, implemented routes and contracts, dependency/configuration changes, lint, strict TypeScript, tests, build, maximum Lizard CCN, startup/health checks, post-deployment MCP workspace validation (if deployed), and outstanding limitations. Mark unexecuted checks as **not run**. From f63977cae367b005999c14039eba79b2ac323f41 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:10:15 +0200 Subject: [PATCH 12/29] docs: centralize widget engineering standards --- .../widget-template/ENGINEERING_STANDARDS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 packages/widget-template/ENGINEERING_STANDARDS.md diff --git a/packages/widget-template/ENGINEERING_STANDARDS.md b/packages/widget-template/ENGINEERING_STANDARDS.md new file mode 100644 index 00000000..739918e3 --- /dev/null +++ b/packages/widget-template/ENGINEERING_STANDARDS.md @@ -0,0 +1,18 @@ +# Widget engineering standards + +Applies to every newly created or modified widget in `reactedge/platform`, regardless of which agent or skill performs the work. + +## Scaffold and contracts + +- `packages/widget-template` is the authoritative scaffold. Create widgets through the ReactEdge MCP widget creation operation. +- Each widget must contain `public/default.json` and `public/reactedge-runtime.json`. +- Both files must parse as valid JSON and conform to the applicable widget/runtime contract schemas. Confirm consistency with the widget implementation; existence alone is insufficient. +- Validate the widget structure using the MCP widget validator. + +## Required verification + +- Run the widget's applicable build and test commands. Both must pass; a scaffold validation alone is not enough. +- Run applicable lint and strict TypeScript checks. +- Apply the platform-wide Lizard CCN limit defined in the root `AGENTS.md`. +- If deployment occurs, apply the post-deployment MCP workspace validation rule in `AGENTS.md`. +- Record command results and failures. Do not mark unexecuted checks as passed. From e8ea91f2a46e7168c5adf7c92af196b8c19ec806 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:10:26 +0200 Subject: [PATCH 13/29] docs(agent): separate mandatory standards from skill workflows --- AGENTS.md | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7411029f..eb4fcc79 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,19 +1,10 @@ -# AI Instructions +# ReactEdge engineering standards -Before creating a widget: +These mandatory rules apply to all platform changes, regardless of agent, skill, or workflow. -- Treat `packages/widget-template` as the source of truth for widget scaffolding. -- Use the ReactEdge MCP `create widget` operation to scaffold from the template; do not manually copy or recreate the scaffold. -- Use the MCP `validate widget` operation to validate the generated structure. +- **Complexity:** Run Lizard on authored or modified platform source code. Every checked function must have cyclomatic complexity (CCN) **at most 10**; refactor any function above 10. A project average is not sufficient. Exclude generated, vendored, and dependency files. +- **Quality:** Run applicable lint, strict TypeScript, build, and test checks for changed components; report actual results and do not treat unexecuted checks as passing. +- **Widgets:** Follow `packages/widget-template/ENGINEERING_STANDARDS.md` for widget contracts, scaffolding, builds, tests, and validation. +- **Deployment:** After every completed deployment, run the platform MCP workspace-structure validation operation and report its result. Discover the actual tool/schema rather than inventing an operation. A successful build is not a substitute for post-deployment workspace validation. -Before creating an Express service: - -- Create services under `services/`. -- Use the Operational Intelligence MCP Express scaffold operation, following `.agents/skills/express-service/SKILL.md`. -- Validate the generated service structure with MCP if a validator exists, then run the applicable platform checks. - -Platform-wide quality gates: - -- Enforce a maximum Lizard cyclomatic complexity (CCN) of **10 per function** in authored or modified platform source code. Run Lizard on the relevant code; refactor any function above 10. Do not treat a project-wide average as sufficient. Exclude generated, vendored, and dependency files from this source-code gate. -- For every new widget, verify that the widget build and tests pass and that both `public/default.json` and `public/reactedge-runtime.json` exist as contracts. Check that the contracts are valid and consistent with the widget's runtime schema. -- After every completed deployment, run the platform MCP workspace-structure validation operation and report its result. Discover the actual operation/schema; never invent a command or report an unexecuted check as passed. +Task procedures are documented separately in `.agents/skills/runtime-shadow-api-widget/SKILL.md` and `.agents/skills/express-service/SKILL.md`. From b6e6192d6507a824e3ca1af104496e306d834e7d Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:10:29 +0200 Subject: [PATCH 14/29] docs(agent): separate mandatory standards from skill workflows --- .../skills/runtime-shadow-api-widget/SKILL.md | 41 ++++++------------- 1 file changed, 12 insertions(+), 29 deletions(-) diff --git a/.agents/skills/runtime-shadow-api-widget/SKILL.md b/.agents/skills/runtime-shadow-api-widget/SKILL.md index 6461275e..8f291334 100644 --- a/.agents/skills/runtime-shadow-api-widget/SKILL.md +++ b/.agents/skills/runtime-shadow-api-widget/SKILL.md @@ -1,42 +1,25 @@ --- name: runtime-shadow-api-widget -description: Scaffold and validate a ReactEdge runtime-shadow widget that consumes an API through the runtime contract instead of the default GraphQL integration. +description: Scaffold a runtime-shadow widget using ReactEdge MCP and replace its default GraphQL integration with the runtime-contract API dependency. --- # Runtime-shadow API widget -Use this skill when asked to create or convert a `runtime-shadow` widget to consume an API rather than GraphQL. +Use when creating or converting a `runtime-shadow` widget to consume an API instead of GraphQL. -## Mandatory repository context - -1. Inspect `packages/widget-template` as the authoritative widget scaffold and structure. Use the MCP widget creation operation rather than legacy manual scaffolding. -2. Use the ReactEdge MCP `create widget` operation to generate widgets from `packages/widget-template`; do not manually copy the template or create an alternative scaffold. -3. Locate and inspect the current runtime contract and its API dependency; do not guess interface names or import paths. -4. Locate and inspect the Google Review widget (including its repository if external) to establish the existing system state provider pattern. If unavailable, report the missing reference and do not invent its behavior. -5. Inspect existing widget lifecycle, mount, observability, and test conventions. +Follow the mandatory root `AGENTS.md` and `packages/widget-template/ENGINEERING_STANDARDS.md` standards. This skill describes the task procedure, not the quality gates. ## Procedure -1. Collect the widget name, API endpoint or API contract, expected response shape, and rendering requirements. Ask only for missing details that cannot be inferred from the repository. -2. Discover the ReactEdge MCP `create widget` operation and inspect its actual schema. Invoke it with widget type `runtime-shadow` and the required widget parameters. The MCP operation owns scaffolding from `packages/widget-template`; do not manually reproduce that process or invent MCP argument names. -3. Invoke the MCP `validate widget` operation on the untouched scaffold. Fix structural failures before modifying the integration. If MCP is unavailable, report this explicitly; do not claim MCP validation occurred. -4. Inspect the generated GraphQL dependencies, data access, and runtime wiring. Identify the corresponding API dependency anchored in the runtime contract, including request context, authentication, response typing, and error handling. -5. Replace GraphQL-specific imports, queries, and data access with the runtime-provided API dependency. Remove unused GraphQL dependencies only when safe; avoid introducing an independent HTTP client when the runtime already provides one. -6. Integrate the system state provider using the same access, subscription, state-update, and cleanup conventions as the Google Review widget. Adapt only widget-specific behavior. Avoid introducing parallel state infrastructure. -7. Implement typed API data flow with loading, success, empty, and failure states. Handle cancellation or stale responses and cleanup across unmount/remount. Preserve existing widget registration, mount lifecycle, and observability. -8. Confirm `public/default.json` and `public/reactedge-runtime.json` exist in the generated widget and validate their JSON and alignment with the runtime/schema contracts. Run the widget build and tests; both must pass before completion. Run MCP `validate widget` again, plus relevant strict TypeScript, lint, integration, and widget e2e checks. Run Lizard on authored/modified source and ensure every function has CCN <= 10. Where supported, validate deployed runtime behavior separately from scaffold structure. -9. After deployment completes, run the platform MCP workspace-structure validation operation. Discover its real schema and report the result; a successful build or widget validation does not substitute for workspace validation. - -## Architectural constraints - -- Preserve separation of responsibilities between widget code, runtime orchestration, mounting, and observability. -- Follow the actual runtime contract; do not change it without a clearly justified and separately reviewed need. -- Never embed credentials or leak sensitive system state. -- Treat `packages/widget-template` and the MCP scaffold operation as the source of truth for widget creation; preserve repository naming, layout, contract schema, and test conventions. -- Do not claim structural validation proves API requests or widget mounting work. -- Do not accept a Lizard CCN above 10 in authored or modified source; refactor complex functions rather than averaging complexity across files. -- Do not fabricate MCP operations, runtime interfaces, Google Review behavior, or test outcomes. +1. Collect the widget name, API endpoint or contract, expected response shape, and rendering requirements. +2. Inspect `packages/widget-template` and discover the actual ReactEdge MCP `create widget` operation/schema. Scaffold with type `runtime-shadow`; let MCP own generation. +3. Run the MCP `validate widget` operation on the scaffold; resolve structural failures before adapting it. +4. Inspect the runtime contract and identify its API dependency, request context, authentication, typing, and error behavior. Do not invent interfaces. +5. Inspect the Google Review widget to understand its system state provider access, updates, and cleanup. If the reference cannot be located, report this rather than guessing. +6. Replace generated GraphQL imports, queries, and data access with the runtime-provided API dependency. Preserve widget registration, mount/unmount lifecycle, and observability. +7. Implement typed API data flow and loading, empty, success, and error behavior. Handle stale requests and cleanup; reuse the system state provider pattern. +8. Run MCP widget validation again, then satisfy the widget standards and global engineering gates. If deployed, satisfy the post-deployment workspace validation gate. ## Completion report -Report widget path, runtime API dependency used, GraphQL integration removed, system state provider pattern followed, initial/final MCP validation, lint, strict TypeScript, Lizard maximum CCN, widget build, tests, presence and validity of both public contracts, runtime verification, post-deployment MCP workspace validation (when deployment occurred), and any unverified behavior. Mark checks not executed as **not run**, not passed. +Report widget path, API dependency used, GraphQL integration removed, state provider pattern, MCP validation outcomes, and the verification results required by the referenced standards. Distinguish not-run checks from passes. From 94187fd229df07c2b32984489c5f797d693711cb Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:10:32 +0200 Subject: [PATCH 15/29] docs(agent): separate mandatory standards from skill workflows --- .agents/skills/express-service/SKILL.md | 48 ++++++++++--------------- 1 file changed, 19 insertions(+), 29 deletions(-) diff --git a/.agents/skills/express-service/SKILL.md b/.agents/skills/express-service/SKILL.md index e7d1e96b..483f9c24 100644 --- a/.agents/skills/express-service/SKILL.md +++ b/.agents/skills/express-service/SKILL.md @@ -1,41 +1,31 @@ --- name: express-service -description: Create a ReactEdge platform Express service under services/ using the Operational Intelligence MCP scaffold, then validate and implement it according to platform conventions. +description: Create an Express service under ReactEdge platform services/ using the Operational Intelligence MCP scaffold. --- # Express service creation -Use this skill when asked to create a new Express service in the ReactEdge platform repository. +Use when creating a new Express service in `reactedge/platform/services/`. + +Follow the mandatory root `AGENTS.md` standards. This skill describes the task procedure, not the quality gates. ## Sources of truth -1. The destination is `reactedge/platform/services/`. -2. The authoritative service scaffold is the **Operational Intelligence MCP create-service operation** associated with `reactedge/operational-intelligence`. Discover the actual MCP tool and its schema; do not assume its exact tool name, parameters, or output. -3. Inspect `reactedge/operational-intelligence` for its Express service architecture and conventions. Existing services such as `cache-warmer` and `sitemap-planner` may provide useful references, but do not blindly copy their domain logic. -4. Inspect `reactedge/platform/services` for naming, dependency management, scripts, TypeScript/lint configuration, health endpoints, telemetry, deployment, and testing conventions. Respect the platform's actual integration requirements. - -## Workflow - -1. Establish service name, responsibility, API routes/contracts, external dependencies, configuration, and desired behavior. Clarify essential missing requirements. -2. Discover the Operational Intelligence MCP operation that scaffolds an Express server. Inspect its input schema and confirm how its generated files are targeted to `reactedge/platform/services/`. Do not invent MCP arguments or manually substitute a scaffold. -3. Run the MCP scaffold operation. Confirm that the generated service is placed under `services/`, without overwriting existing services or unrelated files. -4. Discover and run the MCP service-structure validation operation **if available**. If the MCP provides no validator, inspect the generated structure against its documented contract and explicitly report that MCP structural validation was unavailable. -5. Inspect the scaffolded routes, application/server separation, middleware, error handling, configuration, and dependencies. Implement the requested service behavior while retaining the generated architectural boundaries. -6. Reuse established platform service patterns for configuration, logging, OpenTelemetry/trace propagation, health checks, shutdown, and dependency injection where relevant. Do not add new infrastructure or dependencies when existing platform facilities meet the need. -7. Add or adjust typed request/response contracts, input validation, failure handling, and tests. Avoid embedding secrets, hardcoded environment-specific endpoints, or unsafe defaults. -8. Re-run MCP validation if supported. Run applicable lint, strict TypeScript, unit/integration tests, build checks, and service health/startup verification. Run Lizard on authored/modified source; refactor every function with CCN above 10. Confirm routes and actual behavior separately from scaffold validity. -9. After deployment completes, run the platform MCP workspace-structure validation operation and report its result. Discover the actual MCP schema; do not assume the operation name. - -## Constraints - -- Create the service **only** under `reactedge/platform/services/` unless the user explicitly requests a different destination. -- Let the Operational Intelligence MCP own Express scaffolding; do not copy service files manually in place of its generator. -- Preserve the platform's existing separation of responsibilities and integration conventions. -- Use only the established service patterns in `reactedge/platform/services/` when adapting the generated scaffold; do not apply conventions from unrelated platform areas. -- Do not claim that the MCP supports a validator, or that tests and runtime health passed, without verifying them. -- Avoid changing unrelated services or repository-wide configuration unless required and justified. -- Enforce Lizard CCN <= 10 per function in authored or modified source. +- Destination: `reactedge/platform/services/`. +- Scaffold: the Express service creation operation exposed by the Operational Intelligence MCP associated with `reactedge/operational-intelligence`. Discover its real schema and output; do not invent tool names or parameters. +- Implementation conventions: established patterns in `reactedge/platform/services/`. Do not substitute conventions from unrelated platform areas. + +## Procedure + +1. Establish service name, responsibility, API routes/contracts, dependencies, configuration, and expected behavior. +2. Inspect existing platform services and discover the Operational Intelligence MCP Express scaffold operation and its arguments. +3. Invoke MCP to scaffold under `services/`; verify the target and avoid overwriting unrelated files. Do not manually recreate the scaffold. +4. Run an MCP service-structure validator if available. If not, inspect against the documented scaffold contract and explicitly report that MCP validation was unavailable. +5. Implement service behavior while retaining the scaffold's route, middleware, error handling, configuration, and lifecycle separation. +6. Follow existing `services/` patterns for logging, telemetry, health checks, shutdown, and dependency injection where applicable. +7. Add typed request/response contracts, input validation, error handling, and tests without embedding credentials or environment-specific endpoints. +8. Re-run MCP validation if supported and satisfy the global engineering standards. Verify actual service startup and endpoint behavior where applicable; if deployed, satisfy the post-deployment workspace validation gate. ## Completion report -Report the service path, MCP scaffold operation and result, any structural validation operation and result, implemented routes and contracts, dependency/configuration changes, lint, strict TypeScript, tests, build, maximum Lizard CCN, startup/health checks, post-deployment MCP workspace validation (if deployed), and outstanding limitations. Mark unexecuted checks as **not run**. +Report service path, MCP scaffold and validation results, implemented routes/contracts, configuration changes, and verification outcomes required by `AGENTS.md`. Mark unexecuted checks as not run. From 439628e2e636f9e3dd41bce1f58140c3a5dd3656 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:17:17 +0200 Subject: [PATCH 16/29] feat(codex): add focused Express service sub-agent --- .codex/agents/service-agent.toml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .codex/agents/service-agent.toml diff --git a/.codex/agents/service-agent.toml b/.codex/agents/service-agent.toml new file mode 100644 index 00000000..af37955c --- /dev/null +++ b/.codex/agents/service-agent.toml @@ -0,0 +1,19 @@ +name = "service-agent" +description = "Specialist in creating and maintaining Express services in the ReactEdge platform." + +developer_instructions = """ +You are the ReactEdge Service Agent. + +Your responsibility is to implement and maintain services under +reactedge/platform/services/. + +For new Express services, follow: +.agents/skills/express-service/SKILL.md + +Follow the mandatory engineering standards in: +AGENTS.md + +Use the established patterns in the existing services/ folder. +Stay within service-related responsibilities. +Report completed work and validation results. +""" From 9a9529122996eaec8e271553d3f3114383412f1b Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:18:26 +0200 Subject: [PATCH 17/29] feat(codex): add focused widget sub-agent --- .codex/agents/widget-agent.toml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .codex/agents/widget-agent.toml diff --git a/.codex/agents/widget-agent.toml b/.codex/agents/widget-agent.toml new file mode 100644 index 00000000..0cff316f --- /dev/null +++ b/.codex/agents/widget-agent.toml @@ -0,0 +1,19 @@ +name = "widget-agent" +description = "Specialist in creating and maintaining ReactEdge widgets." + +developer_instructions = """ +You are the ReactEdge Widget Agent. + +Your responsibility is to implement and maintain widgets +in the ReactEdge platform. + +For API-backed runtime-shadow widgets, follow: +.agents/skills/runtime-shadow-api-widget/SKILL.md + +Follow the mandatory engineering standards in: +AGENTS.md +packages/widget-template/ENGINEERING_STANDARDS.md + +Stay within widget-related responsibilities. +Report completed work and validation results. +""" From ce943edfce67556f1dcc1b066e04efe0df75c881 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:43:24 +0200 Subject: [PATCH 18/29] feat(codex): register widget and service subagents for delegation --- .codex/config.toml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .codex/config.toml diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 00000000..61fc99ee --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,16 @@ +# ReactEdge Codex sub-agent launcher configuration. +# Codex uses these registered roles when the main agent delegates work. + +[features] +multi_agent = true + +[agents] +enabled = true + +[agents.widget-agent] +description = "Create and maintain ReactEdge widgets; follow the widget skill and engineering standards." +config_file = "agents/widget-agent.toml" + +[agents.service-agent] +description = "Create and maintain Express services under services/; follow the service skill and engineering standards." +config_file = "agents/service-agent.toml" From d84352be27b6b495af4adf5903fa8b8cf34c3950 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:43:30 +0200 Subject: [PATCH 19/29] docs(agent): define Codex delegation routing for widget and service agents --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index eb4fcc79..bb0d42f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,3 +8,13 @@ These mandatory rules apply to all platform changes, regardless of agent, skill, - **Deployment:** After every completed deployment, run the platform MCP workspace-structure validation operation and report its result. Discover the actual tool/schema rather than inventing an operation. A successful build is not a substitute for post-deployment workspace validation. Task procedures are documented separately in `.agents/skills/runtime-shadow-api-widget/SKILL.md` and `.agents/skills/express-service/SKILL.md`. + +## Codex sub-agent delegation + +When the user requests delegated implementation work, the main Codex agent acts as the launcher using the roles registered in `.codex/config.toml`: + +- Delegate widget creation or maintenance to `widget-agent`. +- Delegate Express service creation or maintenance under `services/` to `service-agent`. +- For mixed tasks, delegate separable widget and service work to their respective agents, coordinate shared interfaces, and integrate their results. Avoid simultaneous edits to the same files. +- Keep architecture decisions, cross-cutting changes, and final verification coordinated by the main agent. Do not claim a delegation or tool run occurred unless it actually did. +- Each sub-agent follows its existing skill and the mandatory standards above; do not restate the skill workflow in the launcher. From 6faccba4f9db3bb933271f9130a8b118afc9efda Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:48:16 +0200 Subject: [PATCH 20/29] feat(codex): add executable specialist agent CLI launcher --- scripts/agent-launcher.py | 78 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 scripts/agent-launcher.py diff --git a/scripts/agent-launcher.py b/scripts/agent-launcher.py new file mode 100644 index 00000000..d2084886 --- /dev/null +++ b/scripts/agent-launcher.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python3 +"""Launch a ReactEdge specialist in a separate Codex CLI session. + +This is a subprocess launcher, not Codex's native spawn-agent tool. +Run from any directory inside the platform checkout. +""" +from __future__ import annotations + +import argparse +import shutil +import subprocess +import sys +import tomllib +from pathlib import Path + +ROLES = { + "widget": "widget-agent", + "service": "service-agent", +} + + +def repository_root() -> Path: + return Path(__file__).resolve().parent.parent + + +def build_prompt(root: Path, role: str, task: str) -> str: + agent_file = root / ".codex" / "agents" / f"{ROLES[role]}.toml" + with agent_file.open("rb") as handle: + agent = tomllib.load(handle) + instructions = agent.get("developer_instructions") + if not isinstance(instructions, str) or not instructions.strip(): + raise ValueError(f"Missing developer_instructions: {agent_file}") + return ( + f"You are acting as the ReactEdge {ROLES[role]} specialist.\n" + "The following are repository-maintained role instructions. " + "Apply them alongside all higher-priority Codex instructions.\n\n" + f"{instructions.strip()}\n\n" + "User task:\n" + f"{task.strip()}\n" + ) + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("role", choices=sorted(ROLES)) + parser.add_argument("task", nargs="+", help="Task for the selected specialist") + parser.add_argument("--dry-run", action="store_true", help="Print the invocation without running Codex") + args = parser.parse_args() + + root = repository_root() + if not (root / "AGENTS.md").is_file(): + parser.error("Cannot find ReactEdge platform AGENTS.md") + prompt = build_prompt(root, args.role, " ".join(args.task)) + command = ["codex", "exec", "-C", str(root), "-"] + + if args.dry_run: + print("Command:", " ".join(command)) + print("Role:", ROLES[args.role]) + print("Working directory:", root) + print("Prompt:\n" + prompt) + return 0 + + if shutil.which("codex") is None: + print("Codex CLI not found on PATH. Install/configure Codex CLI first.", file=sys.stderr) + return 127 + + print(f"Launching {ROLES[args.role]} via Codex CLI...", flush=True) + try: + return subprocess.run(command, input=prompt, text=True, cwd=root, check=False).returncode + except KeyboardInterrupt: + return 130 + except OSError as exc: + print(f"Unable to launch Codex: {exc}", file=sys.stderr) + return 1 + + +if __name__ == "__main__": + raise SystemExit(main()) From 04110a99b02031112c5a288468e2ff2a3a243ee3 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:49:57 +0200 Subject: [PATCH 21/29] refactor(codex): separate launcher responsibilities and simplify control flow --- scripts/agent-launcher.py | 80 ++++++++++++++++++++------------------- 1 file changed, 41 insertions(+), 39 deletions(-) diff --git a/scripts/agent-launcher.py b/scripts/agent-launcher.py index d2084886..6301ffd4 100644 --- a/scripts/agent-launcher.py +++ b/scripts/agent-launcher.py @@ -1,8 +1,7 @@ #!/usr/bin/env python3 -"""Launch a ReactEdge specialist in a separate Codex CLI session. +"""Launch a ReactEdge specialist in a separate Codex CLI process. -This is a subprocess launcher, not Codex's native spawn-agent tool. -Run from any directory inside the platform checkout. +This is not Codex's native sub-agent delegation API. """ from __future__ import annotations @@ -13,66 +12,69 @@ import tomllib from pathlib import Path -ROLES = { - "widget": "widget-agent", - "service": "service-agent", -} +ROLES = {"widget": "widget-agent", "service": "service-agent"} def repository_root() -> Path: return Path(__file__).resolve().parent.parent -def build_prompt(root: Path, role: str, task: str) -> str: - agent_file = root / ".codex" / "agents" / f"{ROLES[role]}.toml" - with agent_file.open("rb") as handle: - agent = tomllib.load(handle) - instructions = agent.get("developer_instructions") +def role_instructions(root: Path, role: str) -> str: + path = root / ".codex" / "agents" / f"{ROLES[role]}.toml" + with path.open("rb") as stream: + instructions = tomllib.load(stream).get("developer_instructions") if not isinstance(instructions, str) or not instructions.strip(): - raise ValueError(f"Missing developer_instructions: {agent_file}") + raise ValueError(f"Missing developer_instructions in {path}") + return instructions.strip() + + +def build_prompt(root: Path, role: str, task: str) -> str: return ( - f"You are acting as the ReactEdge {ROLES[role]} specialist.\n" - "The following are repository-maintained role instructions. " - "Apply them alongside all higher-priority Codex instructions.\n\n" - f"{instructions.strip()}\n\n" - "User task:\n" - f"{task.strip()}\n" + f"Act as the ReactEdge {ROLES[role]} specialist.\n" + "Follow repository instructions and engineering standards.\n\n" + f"{role_instructions(root, role)}\n\n" + f"User task:\n{task.strip()}\n" ) -def main() -> int: +def parse_arguments() -> argparse.Namespace: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("role", choices=sorted(ROLES)) parser.add_argument("task", nargs="+", help="Task for the selected specialist") - parser.add_argument("--dry-run", action="store_true", help="Print the invocation without running Codex") - args = parser.parse_args() + parser.add_argument("--dry-run", action="store_true") + return parser.parse_args() - root = repository_root() - if not (root / "AGENTS.md").is_file(): - parser.error("Cannot find ReactEdge platform AGENTS.md") - prompt = build_prompt(root, args.role, " ".join(args.task)) - command = ["codex", "exec", "-C", str(root), "-"] - - if args.dry_run: - print("Command:", " ".join(command)) - print("Role:", ROLES[args.role]) - print("Working directory:", root) - print("Prompt:\n" + prompt) - return 0 +def launch(command: list[str], prompt: str, root: Path) -> int: if shutil.which("codex") is None: - print("Codex CLI not found on PATH. Install/configure Codex CLI first.", file=sys.stderr) + print("Codex CLI not found on PATH.", file=sys.stderr) return 127 - - print(f"Launching {ROLES[args.role]} via Codex CLI...", flush=True) try: return subprocess.run(command, input=prompt, text=True, cwd=root, check=False).returncode except KeyboardInterrupt: return 130 - except OSError as exc: - print(f"Unable to launch Codex: {exc}", file=sys.stderr) + except OSError as error: + print(f"Unable to launch Codex: {error}", file=sys.stderr) return 1 +def main() -> int: + args = parse_arguments() + root = repository_root() + if not (root / "AGENTS.md").is_file(): + print("ReactEdge AGENTS.md not found.", file=sys.stderr) + return 2 + try: + prompt = build_prompt(root, args.role, " ".join(args.task)) + except (OSError, ValueError, tomllib.TOMLDecodeError) as error: + print(f"Invalid agent definition: {error}", file=sys.stderr) + return 2 + command = ["codex", "exec", "-C", str(root), "-"] + if args.dry_run: + print(f"Command: {' '.join(command)}\nPrompt:\n{prompt}") + return 0 + return launch(command, prompt, root) + + if __name__ == "__main__": raise SystemExit(main()) From 1656d0a8f4e2f955a6ac4bc703bc7498286cf2da Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:08:29 +0200 Subject: [PATCH 22/29] docs(agent): index canonical widget template in shared knowledge --- .agents/knowledge/widget-template.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 .agents/knowledge/widget-template.md diff --git a/.agents/knowledge/widget-template.md b/.agents/knowledge/widget-template.md new file mode 100644 index 00000000..6095cac0 --- /dev/null +++ b/.agents/knowledge/widget-template.md @@ -0,0 +1,26 @@ +# Widget template knowledge + +## Purpose + +This entry helps ReactEdge agents discover the authoritative widget scaffold and understand when to inspect it. + +## Canonical source + +- **Scaffold:** `packages/widget-template/` +- **Engineering standards:** `packages/widget-template/ENGINEERING_STANDARDS.md` +- **Widget creation workflow:** `.agents/skills/runtime-shadow-api-widget/SKILL.md` (for API-backed runtime-shadow widgets) +- **Global engineering standards:** `AGENTS.md` + +The template directory is the source of truth. This knowledge entry is an index, **not a second template**. Do not copy the template into the knowledge base or rely on snapshots that can become stale. + +## Discovery workflow + +1. Before creating or changing a widget, inspect the current contents of `packages/widget-template/` to learn its structure, dependencies, contract conventions, and tests. +2. Read its `ENGINEERING_STANDARDS.md` and the root `AGENTS.md`. +3. For creation, use the ReactEdge MCP widget scaffold operation that consumes `packages/widget-template/`; do not manually reproduce the scaffold. +4. Validate the generated widget using the MCP widget validation operation, then perform the build, tests, and contract checks required by the standards. +5. If template structure or MCP behavior changes, re-inspect the live source instead of treating this index as an implementation specification. + +## Audience + +The main Codex agent, widget-agent, and any future agent implementing widgets. From bdc06eaa0e7104c00f022081fb2935a82a568629 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:08:35 +0200 Subject: [PATCH 23/29] docs(agent): make widget template knowledge discoverable --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index bb0d42f3..fc6a2e73 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ These mandatory rules apply to all platform changes, regardless of agent, skill, - **Complexity:** Run Lizard on authored or modified platform source code. Every checked function must have cyclomatic complexity (CCN) **at most 10**; refactor any function above 10. A project average is not sufficient. Exclude generated, vendored, and dependency files. - **Quality:** Run applicable lint, strict TypeScript, build, and test checks for changed components; report actual results and do not treat unexecuted checks as passing. -- **Widgets:** Follow `packages/widget-template/ENGINEERING_STANDARDS.md` for widget contracts, scaffolding, builds, tests, and validation. +- **Widgets:** Discover the canonical widget template through `.agents/knowledge/widget-template.md`; follow `packages/widget-template/ENGINEERING_STANDARDS.md` for widget contracts, scaffolding, builds, tests, and validation. - **Deployment:** After every completed deployment, run the platform MCP workspace-structure validation operation and report its result. Discover the actual tool/schema rather than inventing an operation. A successful build is not a substitute for post-deployment workspace validation. Task procedures are documented separately in `.agents/skills/runtime-shadow-api-widget/SKILL.md` and `.agents/skills/express-service/SKILL.md`. From 55ff67794bb0e0ea51c46a2f449a47aa70f84db2 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:08:38 +0200 Subject: [PATCH 24/29] docs(agent): make widget template knowledge discoverable --- .codex/agents/widget-agent.toml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.codex/agents/widget-agent.toml b/.codex/agents/widget-agent.toml index 0cff316f..cd3b11ad 100644 --- a/.codex/agents/widget-agent.toml +++ b/.codex/agents/widget-agent.toml @@ -7,6 +7,9 @@ You are the ReactEdge Widget Agent. Your responsibility is to implement and maintain widgets in the ReactEdge platform. +Discover the widget template through: +.agents/knowledge/widget-template.md + For API-backed runtime-shadow widgets, follow: .agents/skills/runtime-shadow-api-widget/SKILL.md From d10f96df2c7ee93f3cb11d7080fd5a9d09a50039 Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:11:28 +0200 Subject: [PATCH 25/29] docs(agent): reference canonical widget template directly --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index fc6a2e73..d556435c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ These mandatory rules apply to all platform changes, regardless of agent, skill, - **Complexity:** Run Lizard on authored or modified platform source code. Every checked function must have cyclomatic complexity (CCN) **at most 10**; refactor any function above 10. A project average is not sufficient. Exclude generated, vendored, and dependency files. - **Quality:** Run applicable lint, strict TypeScript, build, and test checks for changed components; report actual results and do not treat unexecuted checks as passing. -- **Widgets:** Discover the canonical widget template through `.agents/knowledge/widget-template.md`; follow `packages/widget-template/ENGINEERING_STANDARDS.md` for widget contracts, scaffolding, builds, tests, and validation. +- **Widgets:** Use `packages/widget-template/` as the canonical widget template; follow `packages/widget-template/ENGINEERING_STANDARDS.md` for widget contracts, scaffolding, builds, tests, and validation. - **Deployment:** After every completed deployment, run the platform MCP workspace-structure validation operation and report its result. Discover the actual tool/schema rather than inventing an operation. A successful build is not a substitute for post-deployment workspace validation. Task procedures are documented separately in `.agents/skills/runtime-shadow-api-widget/SKILL.md` and `.agents/skills/express-service/SKILL.md`. From 9ecf0e8f17fb57d5a803ff1a7043c27d686a967d Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:11:31 +0200 Subject: [PATCH 26/29] docs(codex): remove redundant widget knowledge pointer --- .codex/agents/widget-agent.toml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.codex/agents/widget-agent.toml b/.codex/agents/widget-agent.toml index cd3b11ad..0cff316f 100644 --- a/.codex/agents/widget-agent.toml +++ b/.codex/agents/widget-agent.toml @@ -7,9 +7,6 @@ You are the ReactEdge Widget Agent. Your responsibility is to implement and maintain widgets in the ReactEdge platform. -Discover the widget template through: -.agents/knowledge/widget-template.md - For API-backed runtime-shadow widgets, follow: .agents/skills/runtime-shadow-api-widget/SKILL.md From 8e6264f579f14b021180fa88fb60d240d57d23ef Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy <166377039+digitalrisedorset@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:11:35 +0200 Subject: [PATCH 27/29] docs(agent): remove redundant widget template knowledge entry --- .agents/knowledge/widget-template.md | 26 -------------------------- 1 file changed, 26 deletions(-) delete mode 100644 .agents/knowledge/widget-template.md diff --git a/.agents/knowledge/widget-template.md b/.agents/knowledge/widget-template.md deleted file mode 100644 index 6095cac0..00000000 --- a/.agents/knowledge/widget-template.md +++ /dev/null @@ -1,26 +0,0 @@ -# Widget template knowledge - -## Purpose - -This entry helps ReactEdge agents discover the authoritative widget scaffold and understand when to inspect it. - -## Canonical source - -- **Scaffold:** `packages/widget-template/` -- **Engineering standards:** `packages/widget-template/ENGINEERING_STANDARDS.md` -- **Widget creation workflow:** `.agents/skills/runtime-shadow-api-widget/SKILL.md` (for API-backed runtime-shadow widgets) -- **Global engineering standards:** `AGENTS.md` - -The template directory is the source of truth. This knowledge entry is an index, **not a second template**. Do not copy the template into the knowledge base or rely on snapshots that can become stale. - -## Discovery workflow - -1. Before creating or changing a widget, inspect the current contents of `packages/widget-template/` to learn its structure, dependencies, contract conventions, and tests. -2. Read its `ENGINEERING_STANDARDS.md` and the root `AGENTS.md`. -3. For creation, use the ReactEdge MCP widget scaffold operation that consumes `packages/widget-template/`; do not manually reproduce the scaffold. -4. Validate the generated widget using the MCP widget validation operation, then perform the build, tests, and contract checks required by the standards. -5. If template structure or MCP behavior changes, re-inspect the live source instead of treating this index as an implementation specification. - -## Audience - -The main Codex agent, widget-agent, and any future agent implementing widgets. From d07c70c53eb79e69c9079673a04715c3bf1a2d6b Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy Date: Mon, 19 Oct 2026 18:30:22 +0100 Subject: [PATCH 28/29] feat: add Beach Finder service and widget --- mcp/tests/structure.behavior.test.ts | 20 + .../widget-template/package.json.template | 3 +- .../public/reactedge-runtime.json | 11 + .../runtime/public/reactedge-runtime.json | 11 + .../src/WidgetStructureValidator.ts | 6 +- services/beachfinder/.env.sample | 6 + services/beachfinder/README.md | 41 + services/beachfinder/package-lock.json | 1960 +++++++++++++++++ services/beachfinder/package.json | 31 + services/beachfinder/src/access/index.ts | 6 + services/beachfinder/src/access/jsonParser.ts | 9 + services/beachfinder/src/config.ts | 34 + .../src/controller/status-handler.ts | 18 + services/beachfinder/src/index.ts | 3 + services/beachfinder/src/lib/cors-setup.ts | 22 + .../beachfinder/src/lib/initilisers/index.ts | 12 + services/beachfinder/src/lib/server.ts | 36 + services/beachfinder/src/lib/url.ts | 26 + services/beachfinder/src/model/beachfinder.ts | 87 + .../beachfinder/src/observability/activity.ts | 46 + .../src/observability/operation.ts | 59 + .../request-operation-middleware.ts | 32 + .../beachfinder/src/observability/tracing.ts | 6 + .../beachfinder/src/routes/beach-router.ts | 55 + services/beachfinder/src/routes/index.ts | 8 + .../beachfinder/src/routes/status-router.ts | 20 + services/beachfinder/test/beachfinder.test.ts | 33 + services/beachfinder/tsconfig.json | 13 + widgets/beachfinder/README.md | 13 + widgets/beachfinder/api/index.ts | 1 + .../beachfinder/api/runtime-shadow-widget.tsx | 37 + widgets/beachfinder/capability.json | 15 + widgets/beachfinder/index.html | 31 + widgets/beachfinder/package.json | 40 + widgets/beachfinder/postcss.config.cjs | 15 + widgets/beachfinder/public/default.json | 6 + .../beachfinder/public/reactedge-runtime.json | 7 + widgets/beachfinder/src/Config.ts | 37 + widgets/beachfinder/src/ConfigSchema.ts | 14 + .../beachfinder/src/ConfigSchemaRuntime.ts | 20 + widgets/beachfinder/src/Widget.tsx | 21 + .../src/activity/Context/ActivityContext.tsx | 4 + .../Context/ActivityContextProvider.tsx | 31 + .../activity/Context/useActivityContext.ts | 11 + .../src/bootstrap/WidgetWrapper.tsx | 15 + .../beachfinder/src/bootstrap/widget-root.tsx | 26 + .../src/components/WidgetBeachfinder.tsx | 123 ++ .../src/components/global/Circle.tsx | 37 + .../src/components/global/SpinnerOverlay.tsx | 8 + .../src/components/global/StandardSpinner.tsx | 14 + widgets/beachfinder/src/entrypoints/npm.tsx | 47 + .../services/beachfinder/BeachFinderApi.ts | 81 + .../src/state/System/SystemState.tsx | 4 + .../src/state/System/SystemStateProvider.tsx | 22 + widgets/beachfinder/src/state/System/type.ts | 5 + .../src/state/System/useSystemState.ts | 11 + widgets/beachfinder/src/styles/entry.ts | 5 + widgets/beachfinder/src/styles/main.css | 97 + widgets/beachfinder/src/types/global.d.ts | 9 + widgets/beachfinder/tests/beachfinder.spec.ts | 57 + widgets/beachfinder/tests/beachfinder.test.ts | 78 + widgets/beachfinder/tsconfig.app.json | 7 + widgets/beachfinder/tsconfig.json | 8 + widgets/beachfinder/tsconfig.node.json | 10 + widgets/beachfinder/vite.config.ts | 49 + widgets/beachfinder/vite.npm.config.ts | 31 + 66 files changed, 3657 insertions(+), 4 deletions(-) create mode 100644 packages/widget-template/runtime-shadow/public/reactedge-runtime.json create mode 100644 packages/widget-template/runtime/public/reactedge-runtime.json create mode 100644 services/beachfinder/.env.sample create mode 100644 services/beachfinder/README.md create mode 100644 services/beachfinder/package-lock.json create mode 100644 services/beachfinder/package.json create mode 100644 services/beachfinder/src/access/index.ts create mode 100644 services/beachfinder/src/access/jsonParser.ts create mode 100644 services/beachfinder/src/config.ts create mode 100644 services/beachfinder/src/controller/status-handler.ts create mode 100644 services/beachfinder/src/index.ts create mode 100644 services/beachfinder/src/lib/cors-setup.ts create mode 100644 services/beachfinder/src/lib/initilisers/index.ts create mode 100644 services/beachfinder/src/lib/server.ts create mode 100644 services/beachfinder/src/lib/url.ts create mode 100644 services/beachfinder/src/model/beachfinder.ts create mode 100644 services/beachfinder/src/observability/activity.ts create mode 100644 services/beachfinder/src/observability/operation.ts create mode 100644 services/beachfinder/src/observability/request-operation-middleware.ts create mode 100644 services/beachfinder/src/observability/tracing.ts create mode 100644 services/beachfinder/src/routes/beach-router.ts create mode 100644 services/beachfinder/src/routes/index.ts create mode 100644 services/beachfinder/src/routes/status-router.ts create mode 100644 services/beachfinder/test/beachfinder.test.ts create mode 100644 services/beachfinder/tsconfig.json create mode 100644 widgets/beachfinder/README.md create mode 100644 widgets/beachfinder/api/index.ts create mode 100644 widgets/beachfinder/api/runtime-shadow-widget.tsx create mode 100644 widgets/beachfinder/capability.json create mode 100644 widgets/beachfinder/index.html create mode 100644 widgets/beachfinder/package.json create mode 100644 widgets/beachfinder/postcss.config.cjs create mode 100644 widgets/beachfinder/public/default.json create mode 100644 widgets/beachfinder/public/reactedge-runtime.json create mode 100644 widgets/beachfinder/src/Config.ts create mode 100644 widgets/beachfinder/src/ConfigSchema.ts create mode 100644 widgets/beachfinder/src/ConfigSchemaRuntime.ts create mode 100644 widgets/beachfinder/src/Widget.tsx create mode 100644 widgets/beachfinder/src/activity/Context/ActivityContext.tsx create mode 100644 widgets/beachfinder/src/activity/Context/ActivityContextProvider.tsx create mode 100644 widgets/beachfinder/src/activity/Context/useActivityContext.ts create mode 100644 widgets/beachfinder/src/bootstrap/WidgetWrapper.tsx create mode 100644 widgets/beachfinder/src/bootstrap/widget-root.tsx create mode 100644 widgets/beachfinder/src/components/WidgetBeachfinder.tsx create mode 100644 widgets/beachfinder/src/components/global/Circle.tsx create mode 100644 widgets/beachfinder/src/components/global/SpinnerOverlay.tsx create mode 100644 widgets/beachfinder/src/components/global/StandardSpinner.tsx create mode 100644 widgets/beachfinder/src/entrypoints/npm.tsx create mode 100644 widgets/beachfinder/src/services/beachfinder/BeachFinderApi.ts create mode 100644 widgets/beachfinder/src/state/System/SystemState.tsx create mode 100644 widgets/beachfinder/src/state/System/SystemStateProvider.tsx create mode 100644 widgets/beachfinder/src/state/System/type.ts create mode 100644 widgets/beachfinder/src/state/System/useSystemState.ts create mode 100644 widgets/beachfinder/src/styles/entry.ts create mode 100644 widgets/beachfinder/src/styles/main.css create mode 100644 widgets/beachfinder/src/types/global.d.ts create mode 100644 widgets/beachfinder/tests/beachfinder.spec.ts create mode 100644 widgets/beachfinder/tests/beachfinder.test.ts create mode 100644 widgets/beachfinder/tsconfig.app.json create mode 100644 widgets/beachfinder/tsconfig.json create mode 100644 widgets/beachfinder/tsconfig.node.json create mode 100644 widgets/beachfinder/vite.config.ts create mode 100644 widgets/beachfinder/vite.npm.config.ts diff --git a/mcp/tests/structure.behavior.test.ts b/mcp/tests/structure.behavior.test.ts index b9a4101a..da11cc6f 100644 --- a/mcp/tests/structure.behavior.test.ts +++ b/mcp/tests/structure.behavior.test.ts @@ -205,6 +205,26 @@ test("validate_structure flags a missing runtime-shadow runtime manifest", async }); }); +test("validate_structure accepts a widget-specific runtime manifest", async () => { + await withTemporaryReactEdgeRoot(async root => { + const widget = "fixture-shadow-custom-runtime-manifest"; + const widgetRoot = await createWidgetFixture(root, "runtime-shadow", widget); + + await writeFile( + resolve(widgetRoot, "public/reactedge-runtime.json"), + JSON.stringify({ integrations: { beachfinderApi: { api: "http://127.0.0.1:4185" } } }), + "utf8", + ); + + const result = await validate(widget); + + assert.equal(result.valid, true); + assert.deepEqual(result.missing, []); + assert.deepEqual(result.canonicalMissing, []); + assert.deepEqual(result.modified, []); + }); +}); + test("validate_structure currently rejects a widget when its API entrypoint no longer identifies a variant", async () => { await withTemporaryReactEdgeRoot(async root => { const widget = "fixture-shadow-missing-entrypoint"; diff --git a/packages/widget-template/package.json.template b/packages/widget-template/package.json.template index a4b886f5..1daf7497 100644 --- a/packages/widget-template/package.json.template +++ b/packages/widget-template/package.json.template @@ -26,6 +26,7 @@ "globals": "^16.5.0", "postcss": "^8.5.6", "postcss-prefix-selector": "^2.1.1", + "rollup": "^4.62.4", "rollup-plugin-visualizer": "^7.0.1", "tsx": "^4.21.0", "typescript": "~5.9.3", @@ -36,4 +37,4 @@ "react": "^19.2.0", "react-dom": "^19.2.0" } -} \ No newline at end of file +} diff --git a/packages/widget-template/runtime-shadow/public/reactedge-runtime.json b/packages/widget-template/runtime-shadow/public/reactedge-runtime.json new file mode 100644 index 00000000..f3f4ecf8 --- /dev/null +++ b/packages/widget-template/runtime-shadow/public/reactedge-runtime.json @@ -0,0 +1,11 @@ +{ + "integrations": { + "magentoGraphql": { + "api": "https://example.com/graphql" + } + }, + "context": { + "storeCode": "default", + "sku": "EXAMPLE" + } +} diff --git a/packages/widget-template/runtime/public/reactedge-runtime.json b/packages/widget-template/runtime/public/reactedge-runtime.json new file mode 100644 index 00000000..f3f4ecf8 --- /dev/null +++ b/packages/widget-template/runtime/public/reactedge-runtime.json @@ -0,0 +1,11 @@ +{ + "integrations": { + "magentoGraphql": { + "api": "https://example.com/graphql" + } + }, + "context": { + "storeCode": "default", + "sku": "EXAMPLE" + } +} diff --git a/packages/widget-validation/src/WidgetStructureValidator.ts b/packages/widget-validation/src/WidgetStructureValidator.ts index 59d401a2..69f84b26 100644 --- a/packages/widget-validation/src/WidgetStructureValidator.ts +++ b/packages/widget-validation/src/WidgetStructureValidator.ts @@ -37,6 +37,7 @@ const requiredFiles = { "src/Config.ts", "src/ConfigSchema.ts", "src/ConfigSchemaRuntime.ts", + "public/reactedge-runtime.json", "src/WidgetView.tsx", "src/bootstrap/WidgetWrapper.tsx", "src/entrypoints/ssr.tsx", @@ -46,6 +47,7 @@ const requiredFiles = { "src/Config.ts", "src/ConfigSchema.ts", "src/ConfigSchemaRuntime.ts", + "public/reactedge-runtime.json", "src/bootstrap/WidgetWrapper.tsx", ], } as const; @@ -92,11 +94,9 @@ const variantFiles = { ], runtime: [ "api/runtime-widget.tsx", - "public/reactedge-runtime.json", ], "runtime-shadow": [ "api/runtime-shadow-widget.tsx", - "public/reactedge-runtime.json", ] } as const; @@ -235,4 +235,4 @@ export class WidgetStructureValidator { return readFileSync(actual) .equals(readFileSync(canonical)); } -} \ No newline at end of file +} diff --git a/services/beachfinder/.env.sample b/services/beachfinder/.env.sample new file mode 100644 index 00000000..58f9a483 --- /dev/null +++ b/services/beachfinder/.env.sample @@ -0,0 +1,6 @@ +PORT=4185 +FRONTEND_URL=http://localhost:3000 +OTEL_HOST=http://localhost:4318 +OTEL_SERVICE_NAME=reactedge-beachfinder +POSTCODE_API_URL=https://api.postcodes.io/postcodes +OVERPASS_API_URL=https://overpass-api.de/api/interpreter diff --git a/services/beachfinder/README.md b/services/beachfinder/README.md new file mode 100644 index 00000000..23b30b58 --- /dev/null +++ b/services/beachfinder/README.md @@ -0,0 +1,41 @@ +# Beach Finder + +Express service with request-scoped OpenTelemetry tracing. `GET /beachfinder/beaches` +accepts a UK postcode and search radius in miles, then returns named and unnamed +OpenStreetMap beach features in range. Distances are straight-line distances. + +## Search contract + +```http +GET /beachfinder/beaches?postcode=BN1%201AA&radiusMiles=10 +``` + +Successful responses have `{postcode, radiusMiles, beaches}`. Each beach has +`id`, `name`, `latitude`, `longitude`, and `distanceMiles`. Invalid query values +return `400`, unknown postcodes return `404`, and upstream failures return +`502`. Radius must be greater than 0 and at most 100 miles. + +Postcode coordinates come from Postcodes.io. Beach features come from the +OpenStreetMap Overpass API; the provider URLs can be changed with +`POSTCODE_API_URL` and `OVERPASS_API_URL`. Results reflect OpenStreetMap data +and may be incomplete. The widget should display the returned distance and +attribute map data to OpenStreetMap. + +## Run + +```bash +cp .env.sample .env +npm install +npm start +``` + +Verify the example route: + +```bash +curl --fail http://localhost:4185/beachfinder/status +``` + +Run checks with `npm test`, `npm run typecheck`, and `npm run build`. + +The trace contains a `beachfinder.request` parent span and a +`beachfinder.status` route span. diff --git a/services/beachfinder/package-lock.json b/services/beachfinder/package-lock.json new file mode 100644 index 00000000..b690f4b8 --- /dev/null +++ b/services/beachfinder/package-lock.json @@ -0,0 +1,1960 @@ +{ + "name": "@reactedge/beachfinder", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@reactedge/beachfinder", + "version": "0.1.0", + "dependencies": { + "@opentelemetry/api": "^1.9.1", + "@opentelemetry/exporter-trace-otlp-http": "^0.219.0", + "@opentelemetry/resources": "^2.8.0", + "@opentelemetry/sdk-trace-base": "^2.8.0", + "@opentelemetry/sdk-trace-node": "^2.8.0", + "cors": "^2.8.6", + "dotenv": "^17.4.2", + "express": "^5.2.1" + }, + "devDependencies": { + "@types/cors": "^2.8.19", + "@types/express": "^5.0.6", + "@types/node": "^26.0.0", + "tsx": "^4.22.4", + "typescript": "^6.0.3" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz", + "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz", + "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz", + "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz", + "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz", + "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz", + "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz", + "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz", + "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz", + "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz", + "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz", + "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz", + "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz", + "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz", + "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz", + "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz", + "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz", + "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz", + "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz", + "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz", + "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz", + "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz", + "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz", + "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz", + "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz", + "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz", + "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@opentelemetry/api": { + "version": "1.9.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.1.tgz", + "integrity": "sha512-gLyJlPHPZYdAk1JENA9LeHejZe1Ti77/pTeFm/nMXmQH/HFZlcS/O2XJB+L8fkbrNSqhdtlvjBVjxwUYanNH5Q==", + "license": "Apache-2.0", + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/@opentelemetry/api-logs": { + "version": "0.219.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/api-logs/-/api-logs-0.219.0.tgz", + "integrity": "sha512-FFx7YnaYJlIjqWW/AG/yAZ0L/NEY724PipXXXQLdtZPbLwBGbUMTGL1i/esI56TWfTUXxhLfpgrnWJCG8aUJyg==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/api": "^1.3.0" + }, + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/@opentelemetry/context-async-hooks": { + "version": "2.11.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/context-async-hooks/-/context-async-hooks-2.11.0.tgz", + "integrity": "sha512-Tr79DyWI8itsBdg+jH+opjfrwLzX+erk1/ExkIwhWoAVjVrJIn2y5+cGjTC0Vy8fyNIA/y8wuJPZwr1T3xCZeQ==", + "license": "Apache-2.0", + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/core": { + "version": "2.8.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-2.8.0.tgz", + "integrity": "sha512-hd1Lfh8p545nNz+jq1Ejfz+Mn1hyLuxYn1YzTfFNrxr8urEWMNQLPf1Th8kjOH+HxwawCrtgBp8JpBUR4ZSgww==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/exporter-trace-otlp-http": { + "version": "0.219.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/exporter-trace-otlp-http/-/exporter-trace-otlp-http-0.219.0.tgz", + "integrity": "sha512-9t6SvBXXBEjOBcIzgozvBbd3jWrv3Gt3ngGhl1fhdZ/zRc7oZDVOFEqbi2zlBpW9BXhgDMKv422J0DL/3iQWfw==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "2.8.0", + "@opentelemetry/otlp-exporter-base": "0.219.0", + "@opentelemetry/otlp-transformer": "0.219.0", + "@opentelemetry/resources": "2.8.0", + "@opentelemetry/sdk-trace-base": "2.8.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": "^1.3.0" + } + }, + "node_modules/@opentelemetry/exporter-trace-otlp-http/node_modules/@opentelemetry/resources": { + "version": "2.8.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/resources/-/resources-2.8.0.tgz", + "integrity": "sha512-qmXQ27ilDbUK/vGMqwL8D4/rhn76C+sherM4wTbjlfknR8Nvfc/hCxjRJPhkzZzUsPiNg16SA31NxMabwttRjg==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "2.8.0", + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.3.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/exporter-trace-otlp-http/node_modules/@opentelemetry/sdk-trace-base": { + "version": "2.8.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace-base/-/sdk-trace-base-2.8.0.tgz", + "integrity": "sha512-mhU4jp+vW0mGbFRd+GeXHvmfA4aDqWjBjLC3pE5XMpLs0IE2ryYb019Ts2AQrOq67gaTF25D91+fgvEHDZEnuQ==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "2.8.0", + "@opentelemetry/resources": "2.8.0", + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.3.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/otlp-exporter-base": { + "version": "0.219.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/otlp-exporter-base/-/otlp-exporter-base-0.219.0.tgz", + "integrity": "sha512-zvIxQX/AZUVKDU+hCuYx+7UkiP7GRdnk1ZbFQRYzHvYp47cAWR4j3IhoPhV9KaeXEv2xdGq3IA6PnpzDmLcmSA==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "2.8.0", + "@opentelemetry/otlp-transformer": "0.219.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": "^1.3.0" + } + }, + "node_modules/@opentelemetry/otlp-transformer": { + "version": "0.219.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/otlp-transformer/-/otlp-transformer-0.219.0.tgz", + "integrity": "sha512-aaYKAyXhw9VchKZVGOopD3Gw/kPsyrX2c6IQ0AW32mTjqmZOh5Y6Gf5OYqTNqVktAeBjmFinhyFaCwW6GYK9YQ==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/api-logs": "0.219.0", + "@opentelemetry/core": "2.8.0", + "@opentelemetry/resources": "2.8.0", + "@opentelemetry/sdk-logs": "0.219.0", + "@opentelemetry/sdk-metrics": "2.8.0", + "@opentelemetry/sdk-trace-base": "2.8.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": "^1.3.0" + } + }, + "node_modules/@opentelemetry/otlp-transformer/node_modules/@opentelemetry/resources": { + "version": "2.8.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/resources/-/resources-2.8.0.tgz", + "integrity": "sha512-qmXQ27ilDbUK/vGMqwL8D4/rhn76C+sherM4wTbjlfknR8Nvfc/hCxjRJPhkzZzUsPiNg16SA31NxMabwttRjg==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "2.8.0", + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.3.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/otlp-transformer/node_modules/@opentelemetry/sdk-trace-base": { + "version": "2.8.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace-base/-/sdk-trace-base-2.8.0.tgz", + "integrity": "sha512-mhU4jp+vW0mGbFRd+GeXHvmfA4aDqWjBjLC3pE5XMpLs0IE2ryYb019Ts2AQrOq67gaTF25D91+fgvEHDZEnuQ==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "2.8.0", + "@opentelemetry/resources": "2.8.0", + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.3.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/resources": { + "version": "2.11.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/resources/-/resources-2.11.0.tgz", + "integrity": "sha512-Ie7+8q8MDF4FAEQCKVMTx3ReUvxiIAgIiiW3c9JdmP8+HMcDy20puT+AHjexnExgnbvBxjQ9fjkFDWrikJ2jQA==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "2.11.0", + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.3.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/resources/node_modules/@opentelemetry/core": { + "version": "2.11.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-2.11.0.tgz", + "integrity": "sha512-7YP44XH0tV6+Mb54x2YGf84i7yi+31MBZlE8JwvozkxyTvXbSp10X7cI7YE49ChJ3shMJoBmCJF3+1QFBJctGA==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/sdk-logs": { + "version": "0.219.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-logs/-/sdk-logs-0.219.0.tgz", + "integrity": "sha512-s6lTKRakaPClvKoWHRChxnXjDMkM/TQ30ff78jN6EBGf7MI7VzANE5PU3f4z9qDUudWjvZjOLHG0rBnBKYvoXA==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/api-logs": "0.219.0", + "@opentelemetry/core": "2.8.0", + "@opentelemetry/resources": "2.8.0", + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.4.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/sdk-logs/node_modules/@opentelemetry/resources": { + "version": "2.8.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/resources/-/resources-2.8.0.tgz", + "integrity": "sha512-qmXQ27ilDbUK/vGMqwL8D4/rhn76C+sherM4wTbjlfknR8Nvfc/hCxjRJPhkzZzUsPiNg16SA31NxMabwttRjg==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "2.8.0", + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.3.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/sdk-metrics": { + "version": "2.8.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-metrics/-/sdk-metrics-2.8.0.tgz", + "integrity": "sha512-UDBGaj6W0Rgy5rTTaoxs8gVGF/aGkAKyjurJv7se6wjRxJu7FoquTLT/vt54DZfo4crbprYfhX/SOK9+BPw1qg==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "2.8.0", + "@opentelemetry/resources": "2.8.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.9.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/sdk-metrics/node_modules/@opentelemetry/resources": { + "version": "2.8.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/resources/-/resources-2.8.0.tgz", + "integrity": "sha512-qmXQ27ilDbUK/vGMqwL8D4/rhn76C+sherM4wTbjlfknR8Nvfc/hCxjRJPhkzZzUsPiNg16SA31NxMabwttRjg==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "2.8.0", + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.3.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/sdk-trace": { + "version": "2.11.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace/-/sdk-trace-2.11.0.tgz", + "integrity": "sha512-fFnTqGm8/G73GQVnxYi7LXa1ZVYEUvgL6XI1LpvV0bPC7WQ/ZGgKxCSl8FnlZBKto9JHHEFTO6s6CUpvvtwFrA==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "2.11.0", + "@opentelemetry/resources": "2.11.0", + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.3.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/sdk-trace-base": { + "version": "2.11.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace-base/-/sdk-trace-base-2.11.0.tgz", + "integrity": "sha512-H19x/TX/LZdqiYOjM7fqtSxwlplC5pgelavqbQdHbhdq0q/AI/TGkM2dfGuuynTXmJPeF2HoZVoPDu+TGoW78A==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "2.11.0", + "@opentelemetry/resources": "2.11.0", + "@opentelemetry/sdk-trace": "2.11.0", + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.3.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/sdk-trace-base/node_modules/@opentelemetry/core": { + "version": "2.11.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-2.11.0.tgz", + "integrity": "sha512-7YP44XH0tV6+Mb54x2YGf84i7yi+31MBZlE8JwvozkxyTvXbSp10X7cI7YE49ChJ3shMJoBmCJF3+1QFBJctGA==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/sdk-trace-node": { + "version": "2.11.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace-node/-/sdk-trace-node-2.11.0.tgz", + "integrity": "sha512-CuvCMJmZxswhNLlM2LfuLOW3h3fZujA4hsG4B+Sz4dX2zvaXO8Ng74cnDHWD64gLszTlhiG3c0iNUjj4g+0/sA==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/context-async-hooks": "2.11.0", + "@opentelemetry/core": "2.11.0", + "@opentelemetry/sdk-trace-base": "2.11.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/sdk-trace-node/node_modules/@opentelemetry/core": { + "version": "2.11.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-2.11.0.tgz", + "integrity": "sha512-7YP44XH0tV6+Mb54x2YGf84i7yi+31MBZlE8JwvozkxyTvXbSp10X7cI7YE49ChJ3shMJoBmCJF3+1QFBJctGA==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/sdk-trace/node_modules/@opentelemetry/core": { + "version": "2.11.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-2.11.0.tgz", + "integrity": "sha512-7YP44XH0tV6+Mb54x2YGf84i7yi+31MBZlE8JwvozkxyTvXbSp10X7cI7YE49ChJ3shMJoBmCJF3+1QFBJctGA==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, + "node_modules/@opentelemetry/semantic-conventions": { + "version": "1.43.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.43.0.tgz", + "integrity": "sha512-eSYWTm620tTk45EKSedaUL8MFYI8hW164hIXsgIHyxu3VobUB3fFCu5t0hQby6OoWRPsG1KkKUG2M5UadiLiVg==", + "license": "Apache-2.0", + "engines": { + "node": ">=14" + } + }, + "node_modules/@types/body-parser": { + "version": "1.19.6", + "resolved": "https://registry.npmjs.org/@types/body-parser/-/body-parser-1.19.6.tgz", + "integrity": "sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/connect": "*", + "@types/node": "*" + } + }, + "node_modules/@types/connect": { + "version": "3.4.38", + "resolved": "https://registry.npmjs.org/@types/connect/-/connect-3.4.38.tgz", + "integrity": "sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/cors": { + "version": "2.8.19", + "resolved": "https://registry.npmjs.org/@types/cors/-/cors-2.8.19.tgz", + "integrity": "sha512-mFNylyeyqN93lfe/9CSxOGREz8cpzAhH+E93xJ4xWQf62V8sQ/24reV2nyzUWM6H6Xji+GGHpkbLe7pVoUEskg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/express": { + "version": "5.0.6", + "resolved": "https://registry.npmjs.org/@types/express/-/express-5.0.6.tgz", + "integrity": "sha512-sKYVuV7Sv9fbPIt/442koC7+IIwK5olP1KWeD88e/idgoJqDm3JV/YUiPwkoKK92ylff2MGxSz1CSjsXelx0YA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/body-parser": "*", + "@types/express-serve-static-core": "^5.0.0", + "@types/serve-static": "^2" + } + }, + "node_modules/@types/express-serve-static-core": { + "version": "5.1.3", + "resolved": "https://registry.npmjs.org/@types/express-serve-static-core/-/express-serve-static-core-5.1.3.tgz", + "integrity": "sha512-dPfW8NFiOF4wOHc7+N/QSxlY9cfSsenewGbAz8C8U/MULPd/YZ27LvJUIlzaXie7e6Ove9YunJGgC9tbHD2cKw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/node": "*", + "@types/qs": "*", + "@types/range-parser": "*", + "@types/send": "*" + } + }, + "node_modules/@types/http-errors": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@types/http-errors/-/http-errors-2.0.5.tgz", + "integrity": "sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/node": { + "version": "26.6.2", + "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.2.tgz", + "integrity": "sha512-X1P21scMv4zGKLYqjdGjaKa7COa0RKVYYZZN/NfvLQ1JegxFhdhpZG/Lyn8AXx6CDUavKAd11v6BvfpkDByK8g==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": "~8.9.0" + } + }, + "node_modules/@types/node/node_modules/undici-types": { + "version": "8.9.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.9.0.tgz", + "integrity": "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/qs": { + "version": "6.15.1", + "resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.15.1.tgz", + "integrity": "sha512-GZHUBZR9hckSUhrxmp1nG6NwdpM9fCunJwyThLW1X3AyHgd9IlHb6VANpQQqDr2o/qQp6McZ3y/IA2rVzKzSbw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/range-parser": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/@types/range-parser/-/range-parser-1.2.7.tgz", + "integrity": "sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/send": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@types/send/-/send-1.2.1.tgz", + "integrity": "sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/serve-static": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@types/serve-static/-/serve-static-2.2.0.tgz", + "integrity": "sha512-8mam4H1NHLtu7nmtalF7eyBH14QyOASmcxHhSfEoRyr0nP/YdoesEtU+uSRvMe96TW/HPTtkoKqQLl53N7UXMQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/http-errors": "*", + "@types/node": "*" + } + }, + "node_modules/accepts": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz", + "integrity": "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==", + "license": "MIT", + "dependencies": { + "mime-types": "^3.0.0", + "negotiator": "^1.0.0" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/body-parser": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.3.0.tgz", + "integrity": "sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw==", + "license": "MIT", + "dependencies": { + "bytes": "^3.1.2", + "content-type": "^2.0.0", + "debug": "^4.4.3", + "http-errors": "^2.0.1", + "iconv-lite": "^0.7.2", + "on-finished": "^2.4.1", + "qs": "^6.15.2", + "raw-body": "^3.0.2", + "type-is": "^2.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/body-parser/node_modules/content-type": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz", + "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/bytes": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", + "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/call-bind-apply-helpers": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz", + "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/call-bound": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz", + "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "get-intrinsic": "^1.3.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/content-disposition": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.1.0.tgz", + "integrity": "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/content-type": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz", + "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/cookie": { + "version": "0.7.2", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz", + "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/cookie-signature": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz", + "integrity": "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==", + "license": "MIT", + "engines": { + "node": ">=6.6.0" + } + }, + "node_modules/cors": { + "version": "2.8.6", + "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz", + "integrity": "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==", + "license": "MIT", + "dependencies": { + "object-assign": "^4", + "vary": "^1" + }, + "engines": { + "node": ">= 0.10" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/depd": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", + "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/dotenv": { + "version": "17.4.2", + "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-17.4.2.tgz", + "integrity": "sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==", + "license": "BSD-2-Clause", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://dotenvx.com" + } + }, + "node_modules/dunder-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz", + "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.1", + "es-errors": "^1.3.0", + "gopd": "^1.2.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/ee-first": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz", + "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==", + "license": "MIT" + }, + "node_modules/encodeurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz", + "integrity": "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/es-define-property": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz", + "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-errors": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz", + "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-object-atoms": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.2.tgz", + "integrity": "sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/esbuild": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz", + "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.28.2", + "@esbuild/android-arm": "0.28.2", + "@esbuild/android-arm64": "0.28.2", + "@esbuild/android-x64": "0.28.2", + "@esbuild/darwin-arm64": "0.28.2", + "@esbuild/darwin-x64": "0.28.2", + "@esbuild/freebsd-arm64": "0.28.2", + "@esbuild/freebsd-x64": "0.28.2", + "@esbuild/linux-arm": "0.28.2", + "@esbuild/linux-arm64": "0.28.2", + "@esbuild/linux-ia32": "0.28.2", + "@esbuild/linux-loong64": "0.28.2", + "@esbuild/linux-mips64el": "0.28.2", + "@esbuild/linux-ppc64": "0.28.2", + "@esbuild/linux-riscv64": "0.28.2", + "@esbuild/linux-s390x": "0.28.2", + "@esbuild/linux-x64": "0.28.2", + "@esbuild/netbsd-arm64": "0.28.2", + "@esbuild/netbsd-x64": "0.28.2", + "@esbuild/openbsd-arm64": "0.28.2", + "@esbuild/openbsd-x64": "0.28.2", + "@esbuild/openharmony-arm64": "0.28.2", + "@esbuild/sunos-x64": "0.28.2", + "@esbuild/win32-arm64": "0.28.2", + "@esbuild/win32-ia32": "0.28.2", + "@esbuild/win32-x64": "0.28.2" + } + }, + "node_modules/escape-html": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz", + "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==", + "license": "MIT" + }, + "node_modules/etag": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz", + "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/express": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz", + "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==", + "license": "MIT", + "dependencies": { + "accepts": "^2.0.0", + "body-parser": "^2.2.1", + "content-disposition": "^1.0.0", + "content-type": "^1.0.5", + "cookie": "^0.7.1", + "cookie-signature": "^1.2.1", + "debug": "^4.4.0", + "depd": "^2.0.0", + "encodeurl": "^2.0.0", + "escape-html": "^1.0.3", + "etag": "^1.8.1", + "finalhandler": "^2.1.0", + "fresh": "^2.0.0", + "http-errors": "^2.0.0", + "merge-descriptors": "^2.0.0", + "mime-types": "^3.0.0", + "on-finished": "^2.4.1", + "once": "^1.4.0", + "parseurl": "^1.3.3", + "proxy-addr": "^2.0.7", + "qs": "^6.14.0", + "range-parser": "^1.2.1", + "router": "^2.2.0", + "send": "^1.1.0", + "serve-static": "^2.2.0", + "statuses": "^2.0.1", + "type-is": "^2.0.1", + "vary": "^1.1.2" + }, + "engines": { + "node": ">= 18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/finalhandler": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz", + "integrity": "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==", + "license": "MIT", + "dependencies": { + "debug": "^4.4.0", + "encodeurl": "^2.0.0", + "escape-html": "^1.0.3", + "on-finished": "^2.4.1", + "parseurl": "^1.3.3", + "statuses": "^2.0.1" + }, + "engines": { + "node": ">= 18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/forwarded": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz", + "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/fresh": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/fresh/-/fresh-2.0.0.tgz", + "integrity": "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/fsevents": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", + "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/function-bind": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz", + "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-intrinsic": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz", + "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "es-define-property": "^1.0.1", + "es-errors": "^1.3.0", + "es-object-atoms": "^1.1.1", + "function-bind": "^1.1.2", + "get-proto": "^1.0.1", + "gopd": "^1.2.0", + "has-symbols": "^1.1.0", + "hasown": "^2.0.2", + "math-intrinsics": "^1.1.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz", + "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==", + "license": "MIT", + "dependencies": { + "dunder-proto": "^1.0.1", + "es-object-atoms": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/gopd": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz", + "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-symbols": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz", + "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/hasown": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.4.tgz", + "integrity": "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==", + "license": "MIT", + "dependencies": { + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/http-errors": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz", + "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==", + "license": "MIT", + "dependencies": { + "depd": "~2.0.0", + "inherits": "~2.0.4", + "setprototypeof": "~1.2.0", + "statuses": "~2.0.2", + "toidentifier": "~1.0.1" + }, + "engines": { + "node": ">= 0.8" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/iconv-lite": { + "version": "0.7.3", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.3.tgz", + "integrity": "sha512-IKXpvIzjnC9XTAUbVBcMfGS0EPaIXtW6v+zr+RRp+hqULEpo0owZax6wyRwPOJbWbzjYspQwusTsfVr0ifh4uQ==", + "license": "MIT", + "dependencies": { + "safer-buffer": ">= 2.1.2 < 3.0.0" + }, + "engines": { + "node": ">=0.10.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/inherits": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", + "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", + "license": "ISC" + }, + "node_modules/ipaddr.js": { + "version": "1.9.1", + "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz", + "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==", + "license": "MIT", + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/is-promise": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz", + "integrity": "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==", + "license": "MIT" + }, + "node_modules/math-intrinsics": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz", + "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/media-typer": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.1.tgz", + "integrity": "sha512-yz3xRaG20c6/BOzvYoDaGtPmGscs7YivItZEEqe6GbwNfHuxu9YNmvnEkMzKldAGY4/80pRcQRZSEnhquk9XuQ==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/merge-descriptors": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-2.0.0.tgz", + "integrity": "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/mime-db": { + "version": "1.54.0", + "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz", + "integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mime-types": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz", + "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==", + "license": "MIT", + "dependencies": { + "mime-db": "^1.54.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "license": "MIT" + }, + "node_modules/negotiator": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.1.0.tgz", + "integrity": "sha512-NMPBRMJgiQHjbd8phG3Vebdx4kZ1H121rbl5IkMqeOsahptB9BKo/d7oJ3zTXqTgagn2bWlNSXkh0QUGM31RYg==", + "license": "MIT", + "dependencies": { + "content-type": "^2.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/negotiator/node_modules/content-type": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz", + "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/object-assign": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", + "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/object-inspect": { + "version": "1.13.4", + "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz", + "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/on-finished": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz", + "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==", + "license": "MIT", + "dependencies": { + "ee-first": "1.1.1" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/once": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", + "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==", + "license": "ISC", + "dependencies": { + "wrappy": "1" + } + }, + "node_modules/parseurl": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz", + "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/path-to-regexp": { + "version": "8.4.2", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz", + "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/proxy-addr": { + "version": "2.0.8", + "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.8.tgz", + "integrity": "sha512-5nnx0yGyVUcY6t9RnWcARWtwT9F1D8O9rt08htPvnd49W1IgZtmLkhu9WfMzQj1cFxjHIO6connUNVW5k7AVyQ==", + "license": "MIT", + "dependencies": { + "forwarded": "0.2.0", + "ipaddr.js": "1.9.1" + }, + "engines": { + "node": ">= 0.10" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/qs": { + "version": "6.16.0", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.16.0.tgz", + "integrity": "sha512-h6fhOIaRrID2CbEY2fqs+7t+UXZo+MLAnU5gRIq85uFtdiUPCdsApMlHhXogKVM4HM2DVbIjGNTTYH2OcmP1vA==", + "license": "BSD-3-Clause", + "dependencies": { + "es-define-property": "^1.0.1", + "side-channel": "^1.1.1" + }, + "engines": { + "node": ">=0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/range-parser": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.3.0.tgz", + "integrity": "sha512-hek2mFQpPuI4E1BBKrSto+BU3e3x4xuarsbiwr3+lf7p44juvFMV0XFWQAP3xUyqXA4RrXLIoaSUGbSt056ZMw==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/raw-body": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.2.tgz", + "integrity": "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==", + "license": "MIT", + "dependencies": { + "bytes": "~3.1.2", + "http-errors": "~2.0.1", + "iconv-lite": "~0.7.0", + "unpipe": "~1.0.0" + }, + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/router": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz", + "integrity": "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==", + "license": "MIT", + "dependencies": { + "debug": "^4.4.0", + "depd": "^2.0.0", + "is-promise": "^4.0.0", + "parseurl": "^1.3.3", + "path-to-regexp": "^8.0.0" + }, + "engines": { + "node": ">= 18" + } + }, + "node_modules/safer-buffer": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", + "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", + "license": "MIT" + }, + "node_modules/send": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/send/-/send-1.2.1.tgz", + "integrity": "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==", + "license": "MIT", + "dependencies": { + "debug": "^4.4.3", + "encodeurl": "^2.0.0", + "escape-html": "^1.0.3", + "etag": "^1.8.1", + "fresh": "^2.0.0", + "http-errors": "^2.0.1", + "mime-types": "^3.0.2", + "ms": "^2.1.3", + "on-finished": "^2.4.1", + "range-parser": "^1.2.1", + "statuses": "^2.0.2" + }, + "engines": { + "node": ">= 18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/serve-static": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-2.2.1.tgz", + "integrity": "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==", + "license": "MIT", + "dependencies": { + "encodeurl": "^2.0.0", + "escape-html": "^1.0.3", + "parseurl": "^1.3.3", + "send": "^1.2.0" + }, + "engines": { + "node": ">= 18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/setprototypeof": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz", + "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==", + "license": "ISC" + }, + "node_modules/side-channel": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.1.tgz", + "integrity": "sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "object-inspect": "^1.13.4", + "side-channel-list": "^1.0.1", + "side-channel-map": "^1.0.1", + "side-channel-weakmap": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-list": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz", + "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "object-inspect": "^1.13.4" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-map": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz", + "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==", + "license": "MIT", + "dependencies": { + "call-bound": "^1.0.2", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.5", + "object-inspect": "^1.13.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-weakmap": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz", + "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==", + "license": "MIT", + "dependencies": { + "call-bound": "^1.0.2", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.5", + "object-inspect": "^1.13.3", + "side-channel-map": "^1.0.1" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/statuses": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz", + "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/toidentifier": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz", + "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==", + "license": "MIT", + "engines": { + "node": ">=0.6" + } + }, + "node_modules/tsx": { + "version": "4.23.15", + "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.23.15.tgz", + "integrity": "sha512-Yiex1Ovn8z2xPpOWckIiysV1SSyRMY9BkLF++q0yKiDxCqRhosKfMg3janKkiLBwZ5c/YryloKwGZcrEmtwxKw==", + "dev": true, + "license": "MIT", + "dependencies": { + "esbuild": "~0.28.0" + }, + "bin": { + "tsx": "dist/cli.mjs" + }, + "engines": { + "node": ">=18.0.0" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + } + }, + "node_modules/type-is": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.1.0.tgz", + "integrity": "sha512-faYHw0anBbc/kWF3zFTEnxSFOAGUX9GFbOBthvDdLsIlEoWOFOtS0zgCiQYwIskL9iGXZL3kAXD8OoZ4GmMATA==", + "license": "MIT", + "dependencies": { + "content-type": "^2.0.0", + "media-typer": "^1.1.0", + "mime-types": "^3.0.0" + }, + "engines": { + "node": ">= 18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/type-is/node_modules/content-type": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz", + "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/typescript": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz", + "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/unpipe": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz", + "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/vary": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz", + "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/wrappy": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", + "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==", + "license": "ISC" + } + } +} diff --git a/services/beachfinder/package.json b/services/beachfinder/package.json new file mode 100644 index 00000000..408d5e07 --- /dev/null +++ b/services/beachfinder/package.json @@ -0,0 +1,31 @@ +{ + "name": "@reactedge/beachfinder", + "version": "0.1.0", + "private": true, + "description": "Beachfinder Express service", + "type": "module", + "scripts": { + "dev": "tsx watch src/index.ts", + "start": "node --import tsx src/index.ts", + "typecheck": "tsc --noEmit", + "test": "node --import tsx --test test/*.test.ts", + "build": "tsc" + }, + "dependencies": { + "@opentelemetry/api": "^1.9.1", + "@opentelemetry/exporter-trace-otlp-http": "^0.219.0", + "@opentelemetry/resources": "^2.8.0", + "@opentelemetry/sdk-trace-base": "^2.8.0", + "@opentelemetry/sdk-trace-node": "^2.8.0", + "cors": "^2.8.6", + "dotenv": "^17.4.2", + "express": "^5.2.1" + }, + "devDependencies": { + "@types/cors": "^2.8.19", + "@types/express": "^5.0.6", + "@types/node": "^26.0.0", + "tsx": "^4.22.4", + "typescript": "^6.0.3" + } +} diff --git a/services/beachfinder/src/access/index.ts b/services/beachfinder/src/access/index.ts new file mode 100644 index 00000000..3fef1d80 --- /dev/null +++ b/services/beachfinder/src/access/index.ts @@ -0,0 +1,6 @@ +import {setupJsonBodyParse} from "./jsonParser.js"; +import type {Application} from "express"; + +export default (app: Application) => { + setupJsonBodyParse(app) +} diff --git a/services/beachfinder/src/access/jsonParser.ts b/services/beachfinder/src/access/jsonParser.ts new file mode 100644 index 00000000..6b0bc09f --- /dev/null +++ b/services/beachfinder/src/access/jsonParser.ts @@ -0,0 +1,9 @@ +import type {Application} from "express"; +import express from "express"; + +export const setupJsonBodyParse = (app: Application) => { + app.use(express.json()) + app.use(express.urlencoded({ + extended: true + })) +} diff --git a/services/beachfinder/src/config.ts b/services/beachfinder/src/config.ts new file mode 100644 index 00000000..181e5b6a --- /dev/null +++ b/services/beachfinder/src/config.ts @@ -0,0 +1,34 @@ +import dotenv from 'dotenv'; +dotenv.config({quiet: true}); + +export type Config = { + port: number; + frontendUrl: string; + route: { + servicePrefix: string; + }; + observability: { + otelHost: string; + serviceName: string; + }; + providers: { + postcodeApiUrl: string; + overpassApiUrl: string; + }; +}; + +export const config: Config = { + port: Number(process.env.PORT ?? '4185'), + frontendUrl: process.env.FRONTEND_URL ?? 'http://localhost:3000', + route: { + servicePrefix: '/beachfinder' + }, + observability: { + otelHost: process.env.OTEL_HOST ?? 'http://localhost:4318', + serviceName: process.env.OTEL_SERVICE_NAME ?? 'reactedge-beachfinder' + }, + providers: { + postcodeApiUrl: process.env.POSTCODE_API_URL ?? 'https://api.postcodes.io/postcodes', + overpassApiUrl: process.env.OVERPASS_API_URL ?? 'https://overpass-api.de/api/interpreter' + } +}; diff --git a/services/beachfinder/src/controller/status-handler.ts b/services/beachfinder/src/controller/status-handler.ts new file mode 100644 index 00000000..b22552ec --- /dev/null +++ b/services/beachfinder/src/controller/status-handler.ts @@ -0,0 +1,18 @@ +import type {Request, Response} from "express"; +import type {Operation} from "../observability/operation"; + +export class StatusHandler { + status = async (_req: Request, res: Response): Promise => { + const operation = res.locals.routeOperation as Operation; + + try { + operation.succeed(); + res.json({status: 'ok'}); + } catch (error) { + operation.fail(error); + res.status(500).json({ + error: error instanceof Error ? error.message : 'Unknown error' + }); + } + }; +} diff --git a/services/beachfinder/src/index.ts b/services/beachfinder/src/index.ts new file mode 100644 index 00000000..f411561e --- /dev/null +++ b/services/beachfinder/src/index.ts @@ -0,0 +1,3 @@ +import {startServer} from "./lib/server"; + +startServer() \ No newline at end of file diff --git a/services/beachfinder/src/lib/cors-setup.ts b/services/beachfinder/src/lib/cors-setup.ts new file mode 100644 index 00000000..f59b809f --- /dev/null +++ b/services/beachfinder/src/lib/cors-setup.ts @@ -0,0 +1,22 @@ +import {config} from "../config"; +import cors from "cors" + +// https://brianflove.com/posts/2017-03-22-express-cors-typescript/ +export const corsOptions = () => { + const allowedOrigins = config.frontendUrl + .split(',') + .map(origin => origin.trim()) + + const options = { + allowedHeaders: [ + 'Origin', + 'Accept' + ], + credentials: true, + methods: 'GET,HEAD,OPTIONS,PUT,PATCH,POST,DELETE', + origin: allowedOrigins, + preflightContinue: false, + }; + + return cors(options) +} \ No newline at end of file diff --git a/services/beachfinder/src/lib/initilisers/index.ts b/services/beachfinder/src/lib/initilisers/index.ts new file mode 100644 index 00000000..0f3f5b05 --- /dev/null +++ b/services/beachfinder/src/lib/initilisers/index.ts @@ -0,0 +1,12 @@ +import type {Application} from "express"; +import access from "../../access/index" +import routes from "../../routes/index.js"; +import {setupTelemetry} from "../../observability/tracing"; +import {createRequestOperationMiddleware} from "../../observability/request-operation-middleware"; + +export const initialiseApp = async (app: Application) => { + setupTelemetry(app) + app.use(createRequestOperationMiddleware('beachfinder.request')) + access(app) + routes(app) +} diff --git a/services/beachfinder/src/lib/server.ts b/services/beachfinder/src/lib/server.ts new file mode 100644 index 00000000..d99d95f6 --- /dev/null +++ b/services/beachfinder/src/lib/server.ts @@ -0,0 +1,36 @@ +import type {Application} from 'express'; +import express from 'express' +import {config} from "../config"; +import {initialiseApp} from "./initilisers"; +import type {OpenTelemetryObserver} from "../observability/activity"; + +export const startServer = async () => { + const app: Application = express() + const port = config.port + + await initialiseApp(app) + const telemetry = app.locals.telemetry as OpenTelemetryObserver; + + try { + await new Promise((resolve, reject) => { + const server = app.listen(port, (error?: Error) => { + if (error) { + reject(error); + return; + } + resolve(); + }); + server.once('error', reject); + }); + telemetry.logObservation('beachfinder.server.started', { + 'server.port': port + }); + } catch (error) { + const operation = telemetry.startOperation( + 'beachfinder.server.failed', + {'server.port': port} + ); + operation.fail(error); + throw error; + } +} diff --git a/services/beachfinder/src/lib/url.ts b/services/beachfinder/src/lib/url.ts new file mode 100644 index 00000000..0bfc11da --- /dev/null +++ b/services/beachfinder/src/lib/url.ts @@ -0,0 +1,26 @@ +import { URL } from 'url'; + +export const normalizeUrl = (rawUrl: string) => { + const url = new URL(rawUrl); + + // Normalize pathname by collapsing multiple slashes + url.pathname = url.pathname.replace(/\/{2,}/g, '/'); + + // Also clean search parameters and hash if needed (optional) + // url.search = decodeURIComponent(url.search); + // url.hash = decodeURIComponent(url.hash); + + return url.toString(); +} + +export const sanitiseUrl = (rawUrl: string) => { + const dummyHost = 'https://localurl.com' + const url = new URL(`${dummyHost}${rawUrl}`); + + // Obscure each query parameter's value + url.searchParams.forEach((value, key) => { + url.searchParams.set(key, '***'); + }); + + return `${url.pathname}${url.search}` +} \ No newline at end of file diff --git a/services/beachfinder/src/model/beachfinder.ts b/services/beachfinder/src/model/beachfinder.ts new file mode 100644 index 00000000..329f9029 --- /dev/null +++ b/services/beachfinder/src/model/beachfinder.ts @@ -0,0 +1,87 @@ +import {config} from '../config'; + +export type Beach = { + id: string; + name: string; + latitude: number; + longitude: number; + distanceMiles: number; +}; + +type Coordinates = {latitude: number; longitude: number}; +type PostcodeResponse = {status: number; result?: {latitude: number; longitude: number}}; +type OverpassElement = { + type: string; + id: number; + lat?: number; + lon?: number; + center?: {lat: number; lon: number}; + tags?: {name?: string}; +}; + +export class BeachFinder { + constructor( + private readonly fetcher: typeof fetch = fetch, + private readonly postcodeApiUrl = config.providers.postcodeApiUrl, + private readonly overpassApiUrl = config.providers.overpassApiUrl + ) {} + + async search(postcode: string, radiusMiles: number): Promise { + const origin = await this.lookupPostcode(postcode); + const elements = await this.lookupBeaches(origin, radiusMiles); + return elements.map(element => this.toBeach(element, origin)) + .filter((beach): beach is Beach => beach !== null) + .filter(beach => beach.distanceMiles <= radiusMiles) + .sort((left, right) => left.distanceMiles - right.distanceMiles); + } + + private async lookupPostcode(postcode: string): Promise { + const response = await this.fetcher( + `${this.postcodeApiUrl}/${encodeURIComponent(postcode.replace(/\s+/g, ' ').trim())}` + ); + if (response.status === 404) throw new PostcodeNotFoundError(); + if (!response.ok) throw new ProviderError('Postcode lookup failed.'); + const payload = await response.json() as PostcodeResponse; + if (!payload.result) throw new PostcodeNotFoundError(); + return {latitude: payload.result.latitude, longitude: payload.result.longitude}; + } + + private async lookupBeaches(origin: Coordinates, radiusMiles: number): Promise { + const radiusMeters = Math.round(radiusMiles * 1609.344); + const query = `[out:json][timeout:20];(node["natural"="beach"](around:${radiusMeters},${origin.latitude},${origin.longitude});way["natural"="beach"](around:${radiusMeters},${origin.latitude},${origin.longitude}););out center tags;`; + const response = await this.fetcher(this.overpassApiUrl, { + method: 'POST', + headers: {'content-type': 'application/x-www-form-urlencoded'}, + body: new URLSearchParams({data: query}) + }); + if (!response.ok) throw new ProviderError('Beach search failed.'); + const payload = await response.json() as {elements?: OverpassElement[]}; + return payload.elements ?? []; + } + + private toBeach(element: OverpassElement, origin: Coordinates): Beach | null { + const latitude = element.lat ?? element.center?.lat; + const longitude = element.lon ?? element.center?.lon; + if (latitude === undefined || longitude === undefined) return null; + return { + id: `${element.type}/${element.id}`, + name: element.tags?.name ?? 'Unnamed beach', + latitude, + longitude, + distanceMiles: Math.round(distanceMiles(origin, {latitude, longitude}) * 10) / 10 + }; + } +} + +export class PostcodeNotFoundError extends Error {} +export class ProviderError extends Error {} + +function distanceMiles(from: Coordinates, to: Coordinates): number { + const radians = (degrees: number) => degrees * Math.PI / 180; + const latitudeDelta = radians(to.latitude - from.latitude); + const longitudeDelta = radians(to.longitude - from.longitude); + const haversine = Math.sin(latitudeDelta / 2) ** 2 + + Math.cos(radians(from.latitude)) * Math.cos(radians(to.latitude)) + * Math.sin(longitudeDelta / 2) ** 2; + return 3958.7613 * 2 * Math.atan2(Math.sqrt(haversine), Math.sqrt(1 - haversine)); +} diff --git a/services/beachfinder/src/observability/activity.ts b/services/beachfinder/src/observability/activity.ts new file mode 100644 index 00000000..da5212b5 --- /dev/null +++ b/services/beachfinder/src/observability/activity.ts @@ -0,0 +1,46 @@ +import type { Attributes} from "@opentelemetry/api"; +import {trace, type Tracer} from "@opentelemetry/api"; +import {OTLPTraceExporter} from '@opentelemetry/exporter-trace-otlp-http'; +import {resourceFromAttributes} from '@opentelemetry/resources'; +import {BatchSpanProcessor} from '@opentelemetry/sdk-trace-base'; +import {NodeTracerProvider} from '@opentelemetry/sdk-trace-node'; +import {config} from "../config"; +import {Operation} from "./operation"; + +export class OpenTelemetryObserver { + private readonly tracer: Tracer + + constructor() { + const exporter = new OTLPTraceExporter({ + url: `${config.observability.otelHost}/v1/traces` + }); + const provider = new NodeTracerProvider({ + resource: resourceFromAttributes({ + 'service.name': config.observability.serviceName, + 'service.version': '1.0.0' + }), + spanProcessors: [new BatchSpanProcessor(exporter)] + }); + + provider.register(); + this.tracer = trace.getTracer(config.observability.serviceName); + } + + startOperation(name: string, attributes: Attributes = {}): Operation { + return new Operation(this.tracer.startSpan(name, {attributes})); + } + + startChildOperation( + parent: Operation, + name: string, + attributes: Attributes = {} + ): Operation { + return new Operation( + this.tracer.startSpan(name, {attributes}, parent.getContext()) + ); + } + + logObservation(name: string, attributes: Attributes = {}): void { + this.startOperation(name, attributes).end(); + } +} diff --git a/services/beachfinder/src/observability/operation.ts b/services/beachfinder/src/observability/operation.ts new file mode 100644 index 00000000..0e503e02 --- /dev/null +++ b/services/beachfinder/src/observability/operation.ts @@ -0,0 +1,59 @@ +import type { + Attributes, + AttributeValue, + Span} from "@opentelemetry/api"; +import { + context, + type Context, + SpanStatusCode, + trace +} from "@opentelemetry/api"; + +export class Operation { + private ended = false; + + constructor(private readonly span: Span) {} + + addEvent(name: string, attributes: Attributes = {}): void { + this.span.addEvent(name, attributes); + } + + setAttribute(key: string, value: AttributeValue): void { + this.span.setAttribute(key, value); + } + + getContext(): Context { + return trace.setSpan(context.active(), this.span); + } + + end(): void { + if (this.ended) return; + this.ended = true; + this.span.end(); + } + + succeed(): void { + if (this.ended) return; + this.span.setStatus({code: SpanStatusCode.OK}); + this.end(); + } + + complete(statusCode: number): void { + if (this.ended) return; + this.span.setAttribute('http.response.status_code', statusCode); + this.span.setStatus({ + code: statusCode >= 400 ? SpanStatusCode.ERROR : SpanStatusCode.OK, + message: statusCode >= 400 ? `HTTP ${statusCode}` : undefined + }); + this.end(); + } + + fail(error: unknown): void { + if (this.ended) return; + this.ended = true; + const err = error instanceof Error ? error : new Error(String(error)); + this.span.recordException(err); + this.span.setStatus({code: SpanStatusCode.ERROR, message: err.message}); + this.span.end(); + } +} diff --git a/services/beachfinder/src/observability/request-operation-middleware.ts b/services/beachfinder/src/observability/request-operation-middleware.ts new file mode 100644 index 00000000..57dca058 --- /dev/null +++ b/services/beachfinder/src/observability/request-operation-middleware.ts @@ -0,0 +1,32 @@ +import type {NextFunction, Request, RequestHandler, Response} from "express"; +import {sanitiseUrl} from "../lib/url"; +import type {OpenTelemetryObserver} from "./activity"; +import type {Operation} from "./operation"; + +export const createRequestOperationMiddleware = ( + operationName: string +): RequestHandler => (req: Request, res: Response, next: NextFunction): void => { + const telemetry = req.app.locals.telemetry as OpenTelemetryObserver; + const operation = telemetry.startOperation(operationName, { + 'http.request.method': req.method, + 'url.path': sanitiseUrl(req.originalUrl) + }); + + res.locals.requestOperation = operation; + res.once('finish', () => operation.complete(res.statusCode)); + res.once('close', () => { + if (!res.writableFinished) { + operation.fail(new Error('Response closed before completion.')); + } + }); + next(); +}; + +export const createRouteOperationMiddleware = ( + operationName: string +): RequestHandler => (req: Request, res: Response, next: NextFunction): void => { + const telemetry = req.app.locals.telemetry as OpenTelemetryObserver; + const parent = res.locals.requestOperation as Operation; + res.locals.routeOperation = telemetry.startChildOperation(parent, operationName); + next(); +}; diff --git a/services/beachfinder/src/observability/tracing.ts b/services/beachfinder/src/observability/tracing.ts new file mode 100644 index 00000000..96252632 --- /dev/null +++ b/services/beachfinder/src/observability/tracing.ts @@ -0,0 +1,6 @@ +import type {Application} from "express"; +import {OpenTelemetryObserver} from "./activity"; + +export function setupTelemetry(app: Application) { + app.locals.telemetry = new OpenTelemetryObserver(); +} \ No newline at end of file diff --git a/services/beachfinder/src/routes/beach-router.ts b/services/beachfinder/src/routes/beach-router.ts new file mode 100644 index 00000000..34a02800 --- /dev/null +++ b/services/beachfinder/src/routes/beach-router.ts @@ -0,0 +1,55 @@ +import type {Application, Request, Response} from 'express'; +import express from 'express'; +import {config} from '../config'; +import {BeachFinder, PostcodeNotFoundError, ProviderError} from '../model/beachfinder'; +import {createRouteOperationMiddleware} from '../observability/request-operation-middleware'; + +const postcodePattern = /^[A-Z]{1,2}\d[A-Z\d]?\s*\d[A-Z]{2}$/i; + +export function parseBeachSearchQuery(postcodeValue: unknown, radiusValue: unknown): { + postcode: string; + radiusMiles: number; +} | null { + const postcode = String(postcodeValue ?? '').trim(); + const radiusMiles = Number(radiusValue); + if (!postcodePattern.test(postcode) || !Number.isFinite(radiusMiles) || radiusMiles <= 0 || radiusMiles > 100) { + return null; + } + return {postcode, radiusMiles}; +} + +export function setupBeachRoutes(app: Application, finder = new BeachFinder()): void { + const router = express.Router(); + router.get( + '/beaches', + createRouteOperationMiddleware('beachfinder.search'), + async (request: Request, response: Response) => handleBeachSearch(request, response, finder) + ); + app.use(config.route.servicePrefix, router); +} + +async function handleBeachSearch( + request: Request, + response: Response, + finder: BeachFinder +): Promise { + const query = parseBeachSearchQuery(request.query.postcode, request.query.radiusMiles); + if (!query) { + response.status(400).json({error: 'Provide a valid UK postcode and radiusMiles from 0 to 100.'}); + return; + } + try { + const beaches = await finder.search(query.postcode, query.radiusMiles); + response.json({postcode: query.postcode.toUpperCase(), radiusMiles: query.radiusMiles, beaches}); + } catch (error) { + if (error instanceof PostcodeNotFoundError) { + response.status(404).json({error: 'UK postcode was not found.'}); + return; + } + if (error instanceof ProviderError) { + response.status(502).json({error: error.message}); + return; + } + response.status(500).json({error: 'Beach search failed.'}); + } +} diff --git a/services/beachfinder/src/routes/index.ts b/services/beachfinder/src/routes/index.ts new file mode 100644 index 00000000..f44624b2 --- /dev/null +++ b/services/beachfinder/src/routes/index.ts @@ -0,0 +1,8 @@ +import type {Application} from "express"; +import {setupStatusRoutes} from "./status-router"; +import {setupBeachRoutes} from "./beach-router"; + +export default (app: Application) => { + setupStatusRoutes(app); + setupBeachRoutes(app); +} diff --git a/services/beachfinder/src/routes/status-router.ts b/services/beachfinder/src/routes/status-router.ts new file mode 100644 index 00000000..f8cc09a4 --- /dev/null +++ b/services/beachfinder/src/routes/status-router.ts @@ -0,0 +1,20 @@ +import type {Application} from 'express'; +import express from 'express' +import {config} from "../config"; +import {StatusHandler} from "../controller/status-handler" +import {corsOptions} from '../lib/cors-setup' +import {createRouteOperationMiddleware} from "../observability/request-operation-middleware"; + +export const setupStatusRoutes = (app: Application) => { + const router = express.Router() + router.use(corsOptions()) + + const statusHandler = new StatusHandler() + router.get( + "/status", + createRouteOperationMiddleware('beachfinder.status'), + statusHandler.status + ) + + app.use(config.route.servicePrefix, router) +} diff --git a/services/beachfinder/test/beachfinder.test.ts b/services/beachfinder/test/beachfinder.test.ts new file mode 100644 index 00000000..07519d94 --- /dev/null +++ b/services/beachfinder/test/beachfinder.test.ts @@ -0,0 +1,33 @@ +import assert from 'node:assert/strict'; +import {test} from 'node:test'; +import {BeachFinder} from '../src/model/beachfinder'; +import {parseBeachSearchQuery} from '../src/routes/beach-router'; + +test('finds and sorts beaches within radius, including way centers', async () => { + const calls: RequestInfo[] = []; + const fetcher: typeof fetch = async (input) => { + calls.push(input); + if (String(input).includes('postcodes.io')) { + return Response.json({status: 200, result: {latitude: 50, longitude: 0}}); + } + return Response.json({elements: [ + {type: 'node', id: 2, lat: 50.01, lon: 0, tags: {name: 'Near Beach'}}, + {type: 'way', id: 3, center: {lat: 50.05, lon: 0}, tags: {name: 'Farther Beach'}}, + {type: 'node', id: 4, lat: 51, lon: 0} + ]}); + }; + const finder = new BeachFinder(fetcher); + const beaches = await finder.search('BN1 1AA', 10); + assert.deepEqual(beaches.map(beach => beach.name), ['Near Beach', 'Farther Beach']); + assert.equal(beaches[0].id, 'node/2'); + assert.ok(beaches[0].distanceMiles < beaches[1].distanceMiles); + assert.equal(calls.length, 2); +}); + +test('validates UK postcodes and search radius values', () => { + assert.deepEqual(parseBeachSearchQuery('BN1 1AA', '4'), { + postcode: 'BN1 1AA', radiusMiles: 4 + }); + assert.equal(parseBeachSearchQuery('nope', '4'), null); + assert.equal(parseBeachSearchQuery('BN1 1AA', '101'), null); +}); diff --git a/services/beachfinder/tsconfig.json b/services/beachfinder/tsconfig.json new file mode 100644 index 00000000..cd6cba8a --- /dev/null +++ b/services/beachfinder/tsconfig.json @@ -0,0 +1,13 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "ESNext", + "moduleResolution": "Bundler", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "noEmit": true, + "types": ["node"] + }, + "include": ["src/**/*.ts"] +} diff --git a/widgets/beachfinder/README.md b/widgets/beachfinder/README.md new file mode 100644 index 00000000..30e7557c --- /dev/null +++ b/widgets/beachfinder/README.md @@ -0,0 +1,13 @@ +# Beach Finder widget + +The runtime configuration must provide the Beach Finder service base URL as +`integrations.beachfinderApi.api`. For local service development, the checked-in +runtime example points to `http://127.0.0.1:4185`; set the production service URL +in the environment's runtime configuration. + +The widget calls `GET /beachfinder/beaches` with `postcode` and `radiusMiles`, +shows loading, no-results, validation, unknown-postcode, and service-error states, +and links each result to OpenStreetMap. Map data attribution is shown in the +widget footer. + +Run `npm test`, `npm run build`, and `npm run lint` from this directory. diff --git a/widgets/beachfinder/api/index.ts b/widgets/beachfinder/api/index.ts new file mode 100644 index 00000000..76da1c21 --- /dev/null +++ b/widgets/beachfinder/api/index.ts @@ -0,0 +1 @@ +export { Widget } from "../src/Widget"; diff --git a/widgets/beachfinder/api/runtime-shadow-widget.tsx b/widgets/beachfinder/api/runtime-shadow-widget.tsx new file mode 100644 index 00000000..e6c221fa --- /dev/null +++ b/widgets/beachfinder/api/runtime-shadow-widget.tsx @@ -0,0 +1,37 @@ +import { WIDGET_ID } from "../src/Config.ts"; + +import type { WidgetApi } from "@reactedge/public-api/widget"; +import type {ReactEdgeRuntimeConfig} from "@reactedge/public-api/runtime.ts"; + +import {ShadowHostProvider} from "@reactedge/framework/host.ts"; +import {createRoot} from "react-dom/client"; +import {WidgetRoot} from "../src/bootstrap/widget-root.tsx" +import {styles} from "../src/styles/entry.ts"; + +const mount = ( + el: HTMLElement, + contract: unknown, + bootstrap: unknown, + runtime: ReactEdgeRuntimeConfig +) => { + const hostProvider = new ShadowHostProvider(styles) + + createRoot(hostProvider.getMountedHost(el)).render( + + ) +}; + +const api: WidgetApi = { + mount, +}; + +if (typeof window !== "undefined") { + window[`ReactEdge_${WIDGET_ID}`] = api; +} + +export { mount }; \ No newline at end of file diff --git a/widgets/beachfinder/capability.json b/widgets/beachfinder/capability.json new file mode 100644 index 00000000..ce31e632 --- /dev/null +++ b/widgets/beachfinder/capability.json @@ -0,0 +1,15 @@ +{ + "id": "beachfinder", + "widget": "beachfinder", + "description": "Search for nearby beaches by UK postcode and radius.", + "signals": { + "consumes": [], + "emits": [] + }, + "runtime": { + "rendering": [ + "client", + "ssr" + ] + } +} diff --git a/widgets/beachfinder/index.html b/widgets/beachfinder/index.html new file mode 100644 index 00000000..e74fcab0 --- /dev/null +++ b/widgets/beachfinder/index.html @@ -0,0 +1,31 @@ + + + + + + + + + + \ No newline at end of file diff --git a/widgets/beachfinder/package.json b/widgets/beachfinder/package.json new file mode 100644 index 00000000..1af2f8f5 --- /dev/null +++ b/widgets/beachfinder/package.json @@ -0,0 +1,40 @@ +{ + "name": "widget-beachfinder", + "private": true, + "version": "0.0.1", + "type": "module", + "scripts": { + "dev": "vite", + "build": "tsc -b && vite build", + "build:ssr": "vite build -c vite.npm.config.ts", + "test": "node --import tsx --test tests/*.test.ts", + "analyze": "ANALYZE=true vite build", + "lint": "eslint .", + "preview": "vite preview" + }, + "dependencies": { + "zod": "^4.4.3" + }, + "devDependencies": { + "@eslint/js": "^9.39.1", + "@types/node": "^24.10.1", + "@types/react": "^19.2.5", + "@types/react-dom": "^19.2.3", + "@vitejs/plugin-react-swc": "^4.2.2", + "eslint": "^9.39.1", + "eslint-plugin-react-hooks": "^7.0.1", + "eslint-plugin-react-refresh": "^0.4.24", + "globals": "^16.5.0", + "postcss": "^8.5.6", + "postcss-prefix-selector": "^2.1.1", + "rollup-plugin-visualizer": "^7.0.1", + "tsx": "^4.21.0", + "typescript": "~5.9.3", + "typescript-eslint": "^8.46.4", + "vite": "^8.3.0" + }, + "peerDependencies": { + "react": "^19.2.0", + "react-dom": "^19.2.0" + } +} diff --git a/widgets/beachfinder/postcss.config.cjs b/widgets/beachfinder/postcss.config.cjs new file mode 100644 index 00000000..75354599 --- /dev/null +++ b/widgets/beachfinder/postcss.config.cjs @@ -0,0 +1,15 @@ +const prefixSelector = require('postcss-prefix-selector'); + +module.exports = { + plugins: [ + prefixSelector({ + prefix: '.reactedge-beachfinder', + transform(prefix, selector, prefixedSelector) { + if (selector.startsWith('html') || selector.startsWith('body')) { + return selector; + } + return prefixedSelector; + }, + }), + ], +}; diff --git a/widgets/beachfinder/public/default.json b/widgets/beachfinder/public/default.json new file mode 100644 index 00000000..c238fb8f --- /dev/null +++ b/widgets/beachfinder/public/default.json @@ -0,0 +1,6 @@ +{ + "data": { + "title": "Find a beach near you", + "description": "Enter a UK postcode to discover nearby beaches." + } +} diff --git a/widgets/beachfinder/public/reactedge-runtime.json b/widgets/beachfinder/public/reactedge-runtime.json new file mode 100644 index 00000000..942043fb --- /dev/null +++ b/widgets/beachfinder/public/reactedge-runtime.json @@ -0,0 +1,7 @@ +{ + "integrations": { + "beachfinderApi": { + "api": "http://127.0.0.1:4185" + } + } +} diff --git a/widgets/beachfinder/src/Config.ts b/widgets/beachfinder/src/Config.ts new file mode 100644 index 00000000..ddba4301 --- /dev/null +++ b/widgets/beachfinder/src/Config.ts @@ -0,0 +1,37 @@ +import type { WidgetActivity } from "@reactedge/framework/activity"; +import { parseConfig, type SchemaWidgetConfig } from "./ConfigSchema.ts"; +import { parseRuntimeConfig, type SchemaRuntimeConfig } from "./ConfigSchemaRuntime.ts"; + +export interface WidgetConfig { + readonly data: SchemaWidgetConfig["data"]; + readonly integrations: SchemaRuntimeConfig["integrations"]; +} + +export const WIDGET_ID = "beachfinder"; + +export function readWidgetConfig( + contract: unknown, + runtime: unknown, + activity?: WidgetActivity +): WidgetConfig { + try { + const config = resolveConfig(parseConfig(contract), parseRuntimeConfig(runtime)); + activity?.log("bootstrap", "Config resolved", config); + return Object.freeze(config); + } catch (error) { + activity?.log( + "bootstrap", + "Invalid widget contract or runtime configuration", + error instanceof Error ? error.message : error, + "error" + ); + throw error; + } +} + +export function resolveConfig( + widget: SchemaWidgetConfig, + runtime: SchemaRuntimeConfig +): WidgetConfig { + return { data: widget.data, integrations: runtime.integrations }; +} diff --git a/widgets/beachfinder/src/ConfigSchema.ts b/widgets/beachfinder/src/ConfigSchema.ts new file mode 100644 index 00000000..06ba478b --- /dev/null +++ b/widgets/beachfinder/src/ConfigSchema.ts @@ -0,0 +1,14 @@ +import { z } from "zod"; + +export const WidgetConfigSchema = z.object({ + data: z.object({ + title: z.string().trim().min(1).max(100), + description: z.string().max(300).optional(), + }).strict(), +}).strict(); + +export type SchemaWidgetConfig = z.infer; + +export function parseConfig(input: unknown): SchemaWidgetConfig { + return WidgetConfigSchema.parse(input); +} diff --git a/widgets/beachfinder/src/ConfigSchemaRuntime.ts b/widgets/beachfinder/src/ConfigSchemaRuntime.ts new file mode 100644 index 00000000..eecb8b75 --- /dev/null +++ b/widgets/beachfinder/src/ConfigSchemaRuntime.ts @@ -0,0 +1,20 @@ +import { z } from "zod"; + +export const SchemaRuntimeConfig = z.object({ + integrations: z.object({ + beachfinderApi: z.object({ api: z.string().url() }).strict(), + }).passthrough(), +}).passthrough(); + +export type SchemaRuntimeConfig = z.infer; + +export function parseRuntimeConfig(input: unknown): SchemaRuntimeConfig { + const parsed = SchemaRuntimeConfig.safeParse(input); + if (!parsed.success) { + const details = parsed.error.issues + .map((issue) => `${issue.path.join(".") || ""}: ${issue.message}`) + .join("; "); + throw new Error(`Invalid Beach Finder runtime config: ${details}`); + } + return parsed.data; +} diff --git a/widgets/beachfinder/src/Widget.tsx b/widgets/beachfinder/src/Widget.tsx new file mode 100644 index 00000000..abd70ca0 --- /dev/null +++ b/widgets/beachfinder/src/Widget.tsx @@ -0,0 +1,21 @@ +import {WidgetRoot} from "./bootstrap/widget-root.tsx"; +import {createRoot} from "react-dom/client"; +import type {RuntimeWidgetOptions} from "@reactedge/public-api/WidgetOptions.ts"; +import {ShadowHostProvider} from "@reactedge/framework/host.ts"; +import { styles } from "./styles/entry.ts"; + +export function Widget({ + container, + contract, + runtime +}: RuntimeWidgetOptions) { + const hostProvider = new ShadowHostProvider(styles); + const host = hostProvider.getMountedHost(container); + + createRoot(host).render( + + ); +} \ No newline at end of file diff --git a/widgets/beachfinder/src/activity/Context/ActivityContext.tsx b/widgets/beachfinder/src/activity/Context/ActivityContext.tsx new file mode 100644 index 00000000..81be6cc3 --- /dev/null +++ b/widgets/beachfinder/src/activity/Context/ActivityContext.tsx @@ -0,0 +1,4 @@ +import {createContext} from "react"; +import type {WidgetActivity} from "@reactedge/framework/activity"; + +export const LocalInstanceStateContext = createContext(undefined); \ No newline at end of file diff --git a/widgets/beachfinder/src/activity/Context/ActivityContextProvider.tsx b/widgets/beachfinder/src/activity/Context/ActivityContextProvider.tsx new file mode 100644 index 00000000..e1afaf74 --- /dev/null +++ b/widgets/beachfinder/src/activity/Context/ActivityContextProvider.tsx @@ -0,0 +1,31 @@ +import {type ReactNode} from "react"; +import {WIDGET_ID} from "../../Config.ts"; +import {LocalInstanceStateContext} from "./ActivityContext.tsx"; +import {WidgetActivity} from "@reactedge/framework/activity"; + +interface InstanceStateProviderProps { + children: ReactNode; + hostElement?: HTMLElement; +} + +const LocalStateProvider = LocalInstanceStateContext.Provider; + +export const ActivityContextProvider: React.FC = ({ + children, + hostElement + }) => { + + const host = hostElement ?? document.documentElement; + + const activity = new WidgetActivity(WIDGET_ID, host.dataset.instance) + + return ( + + {children} + + ); +}; diff --git a/widgets/beachfinder/src/activity/Context/useActivityContext.ts b/widgets/beachfinder/src/activity/Context/useActivityContext.ts new file mode 100644 index 00000000..7a61a77d --- /dev/null +++ b/widgets/beachfinder/src/activity/Context/useActivityContext.ts @@ -0,0 +1,11 @@ +import {useContext} from "react"; +import {LocalInstanceStateContext} from "./ActivityContext.tsx"; +import type {WidgetActivity} from "@reactedge/framework/activity"; + +export function useActivityContext(): WidgetActivity { + const context = useContext(LocalInstanceStateContext); + if (!context) { + throw new Error("useInstanceState must be used within InstanceStateProvider"); + } + return context; +} \ No newline at end of file diff --git a/widgets/beachfinder/src/bootstrap/WidgetWrapper.tsx b/widgets/beachfinder/src/bootstrap/WidgetWrapper.tsx new file mode 100644 index 00000000..9b1ccae9 --- /dev/null +++ b/widgets/beachfinder/src/bootstrap/WidgetWrapper.tsx @@ -0,0 +1,15 @@ +import { useActivityContext } from "../activity/Context/useActivityContext.ts"; +import { readWidgetConfig } from "../Config.ts"; +import { SystemStateProvider } from "../state/System/SystemStateProvider.tsx"; +import { WidgetBeachfinder } from "../components/WidgetBeachfinder.tsx"; + +type Props = { contract: unknown; runtime: unknown }; + +export default function WidgetWrapper({ contract, runtime }: Props) { + const config = readWidgetConfig(contract, runtime, useActivityContext()); + return ( + + + + ); +} diff --git a/widgets/beachfinder/src/bootstrap/widget-root.tsx b/widgets/beachfinder/src/bootstrap/widget-root.tsx new file mode 100644 index 00000000..4ba810f9 --- /dev/null +++ b/widgets/beachfinder/src/bootstrap/widget-root.tsx @@ -0,0 +1,26 @@ +import {WIDGET_ID} from "../Config.ts"; +import {ActivityContextProvider} from "../activity/Context/ActivityContextProvider.tsx"; +import WidgetWrapper from "./WidgetWrapper.tsx"; + +interface WidgetRootProps { + contract: unknown; + runtime: unknown; + bootstrap?: unknown; + hostElement?: HTMLElement; +} + +export function WidgetRoot({ + contract, + runtime, + hostElement, +}: WidgetRootProps) { + return ( +
+ + + +
+ ); +} \ No newline at end of file diff --git a/widgets/beachfinder/src/components/WidgetBeachfinder.tsx b/widgets/beachfinder/src/components/WidgetBeachfinder.tsx new file mode 100644 index 00000000..5bcd22c6 --- /dev/null +++ b/widgets/beachfinder/src/components/WidgetBeachfinder.tsx @@ -0,0 +1,123 @@ +import { useEffect, useRef, useState, type FormEvent } from "react"; +import type { WidgetConfig } from "../Config.ts"; +import { BeachFinderApiError, type BeachSearchResponse } from "../services/beachfinder/BeachFinderApi.ts"; +import { useSystemState } from "../state/System/useSystemState.ts"; + +type Props = { config: WidgetConfig }; + +type SearchOutputProps = { + loading: boolean; + error: string; + results: BeachSearchResponse | null; +}; + +function SearchOutput({ loading, error, results }: SearchOutputProps) { + if (loading) return

Searching for nearby beaches…

; + if (error) return

{error}

; + if (!results) return null; + if (results.beaches.length === 0) { + return

No beaches found within {results.radiusMiles} miles of {results.postcode}.

; + } + return ( + <> +

Beaches near {results.postcode}

+

{results.beaches.length} found within {results.radiusMiles} miles

+
    + {results.beaches.map((beach) => ( +
  • +
    +

    {beach.name || "Unnamed beach"}

    +

    {beach.distanceMiles.toFixed(1)} miles away

    +
    + Map +
  • + ))} +
+ + ); +} + +export function WidgetBeachfinder({ config }: Props) { + const { beachFinderApi } = useSystemState(); + const [postcode, setPostcode] = useState(""); + const [radiusMiles, setRadiusMiles] = useState(10); + const [results, setResults] = useState(null); + const [error, setError] = useState(""); + const [loading, setLoading] = useState(false); + const request = useRef(null); + + useEffect(() => () => request.current?.abort(), []); + + async function submitSearch(event: FormEvent) { + event.preventDefault(); + setError(""); + setResults(null); + setLoading(true); + request.current?.abort(); + const controller = new AbortController(); + request.current = controller; + try { + const response = await beachFinderApi.search(postcode, radiusMiles, controller.signal); + if (!controller.signal.aborted) setResults(response); + } catch (cause) { + if (controller.signal.aborted) return; + setError(cause instanceof BeachFinderApiError + ? cause.message + : "Beach search is temporarily unavailable. Please try again."); + } finally { + if (!controller.signal.aborted) setLoading(false); + } + } + + return ( +
+
+

Find your coast

+

{config.data.title}

+ {config.data.description &&

{config.data.description}

} +
+
+ + setPostcode(event.currentTarget.value)} + /> + +
+ setRadiusMiles(Number(event.currentTarget.value))} + /> + miles +
+ +
+
+ +
+ +
+ ); +} diff --git a/widgets/beachfinder/src/components/global/Circle.tsx b/widgets/beachfinder/src/components/global/Circle.tsx new file mode 100644 index 00000000..6f01f52f --- /dev/null +++ b/widgets/beachfinder/src/components/global/Circle.tsx @@ -0,0 +1,37 @@ + + +type SpinnerProps = { + size?: number; +}; + +export function Circle({ size = 40 }: SpinnerProps) { + + return ( + + ); +} diff --git a/widgets/beachfinder/src/components/global/SpinnerOverlay.tsx b/widgets/beachfinder/src/components/global/SpinnerOverlay.tsx new file mode 100644 index 00000000..51b2ee01 --- /dev/null +++ b/widgets/beachfinder/src/components/global/SpinnerOverlay.tsx @@ -0,0 +1,8 @@ +import {StandardSpinner} from "./StandardSpinner.tsx"; + +export const SpinnerOverlay = () => { + + return ( + + ) +} \ No newline at end of file diff --git a/widgets/beachfinder/src/components/global/StandardSpinner.tsx b/widgets/beachfinder/src/components/global/StandardSpinner.tsx new file mode 100644 index 00000000..6c006762 --- /dev/null +++ b/widgets/beachfinder/src/components/global/StandardSpinner.tsx @@ -0,0 +1,14 @@ +import {Circle} from "./Circle.tsx"; + +type SpinnerProps = { + size?: number; +}; + +export function StandardSpinner({ size = 40 }: SpinnerProps) { + + return ( +
+ +
+ ); +} diff --git a/widgets/beachfinder/src/entrypoints/npm.tsx b/widgets/beachfinder/src/entrypoints/npm.tsx new file mode 100644 index 00000000..4be4eb57 --- /dev/null +++ b/widgets/beachfinder/src/entrypoints/npm.tsx @@ -0,0 +1,47 @@ +import {Widget} from "../Widget.tsx"; +import {ResourceLoader} from "@reactedge/framework/contract.ts"; +import {WidgetActivity} from "@reactedge/framework/activity"; +import {WIDGET_ID} from "../Config.ts"; + +async function main() { + const loader = new ResourceLoader(); + const activity = new WidgetActivity(WIDGET_ID) + const contract = await loader.loadContract("default.json"); + const bootstrap = await loader.loadContract("data.json"); + const runtime = await loader.loadRuntime(); + + const container = document.getElementById("root")!; + + const mode = __REACTEDGE_MODE__; + + if (mode === "hydrate") { + activity.debug("Hydrating existing HTML", { + contract, + bootstrap, + runtime, + html: container.innerHTML + }); + } else { + activity.debug("Rendering from scratch"); + } + + if (mode === "hydrate") { + Widget({ + container, + contract, + bootstrap, + runtime, + hydrate: true + }); + } else { + Widget({ + container, + contract, + bootstrap, + runtime, + hydrate: false + }); + } +} + +main(); \ No newline at end of file diff --git a/widgets/beachfinder/src/services/beachfinder/BeachFinderApi.ts b/widgets/beachfinder/src/services/beachfinder/BeachFinderApi.ts new file mode 100644 index 00000000..f8fcf098 --- /dev/null +++ b/widgets/beachfinder/src/services/beachfinder/BeachFinderApi.ts @@ -0,0 +1,81 @@ +import { z } from "zod"; + +const BeachSchema = z.object({ + id: z.union([z.string(), z.number()]), + name: z.string(), + latitude: z.number().min(-90).max(90), + longitude: z.number().min(-180).max(180), + distanceMiles: z.number().nonnegative(), +}).strict(); + +const SearchResponseSchema = z.object({ + postcode: z.string(), + radiusMiles: z.number().positive(), + beaches: z.array(BeachSchema), +}).strict(); + +export type Beach = z.infer; +export type BeachSearchResponse = z.infer; + +export class BeachFinderApiError extends Error { + readonly status: number; + + constructor(status: number, message: string) { + super(message); + this.name = "BeachFinderApiError"; + this.status = status; + } +} + +export interface BeachFinderApiClient { + search(postcode: string, radiusMiles: number, signal?: AbortSignal): Promise; +} + +type FetchLike = typeof fetch; + +export function createBeachFinderApiClient( + apiUrl: string, + fetcher: FetchLike = fetch +): BeachFinderApiClient { + const endpoint = `${apiUrl.replace(/\/+$/, "")}/beachfinder/beaches`; + return { + async search(postcode, radiusMiles, signal) { + const url = new URL(endpoint); + url.searchParams.set("postcode", postcode.trim()); + url.searchParams.set("radiusMiles", String(radiusMiles)); + + let response: Response; + try { + response = await fetcher(url, { + method: "GET", + ...(signal ? { signal } : {}), + headers: { Accept: "application/json" }, + }); + } catch (error) { + if (signal?.aborted) throw error; + throw new BeachFinderApiError(0, "The beach search service could not be reached."); + } + + if (!response.ok) { + const message = response.status === 400 + ? "Enter a valid UK postcode and a radius up to 100 miles." + : response.status === 404 + ? "That postcode could not be found. Check it and try again." + : "Beach search is temporarily unavailable. Please try again."; + throw new BeachFinderApiError(response.status, message); + } + + let payload: unknown; + try { + payload = await response.json(); + } catch { + throw new BeachFinderApiError(502, "The beach search service returned an invalid response."); + } + const parsed = SearchResponseSchema.safeParse(payload); + if (!parsed.success) { + throw new BeachFinderApiError(502, "The beach search service returned an invalid response."); + } + return parsed.data; + }, + }; +} diff --git a/widgets/beachfinder/src/state/System/SystemState.tsx b/widgets/beachfinder/src/state/System/SystemState.tsx new file mode 100644 index 00000000..00462f2c --- /dev/null +++ b/widgets/beachfinder/src/state/System/SystemState.tsx @@ -0,0 +1,4 @@ +import {createContext} from "react"; +import type {SystemState} from "./type.ts"; + +export const LocalSystemStateContext = createContext(undefined); \ No newline at end of file diff --git a/widgets/beachfinder/src/state/System/SystemStateProvider.tsx b/widgets/beachfinder/src/state/System/SystemStateProvider.tsx new file mode 100644 index 00000000..33e58c24 --- /dev/null +++ b/widgets/beachfinder/src/state/System/SystemStateProvider.tsx @@ -0,0 +1,22 @@ +import { useMemo, type ReactNode } from "react"; +import type { SchemaRuntimeConfig } from "../../ConfigSchemaRuntime.ts"; +import { createBeachFinderApiClient } from "../../services/beachfinder/BeachFinderApi.ts"; +import { LocalSystemStateContext } from "./SystemState.tsx"; + +type Props = { + children: ReactNode; + config: SchemaRuntimeConfig["integrations"]; +}; + +export function SystemStateProvider({ children, config }: Props) { + const apiUrl = config.beachfinderApi.api; + const beachFinderApi = useMemo( + () => createBeachFinderApiClient(apiUrl), + [apiUrl] + ); + return ( + + {children} + + ); +} diff --git a/widgets/beachfinder/src/state/System/type.ts b/widgets/beachfinder/src/state/System/type.ts new file mode 100644 index 00000000..b51de2f3 --- /dev/null +++ b/widgets/beachfinder/src/state/System/type.ts @@ -0,0 +1,5 @@ +import type { BeachFinderApiClient } from "../../services/beachfinder/BeachFinderApi.ts"; + +export interface SystemState { + beachFinderApi: BeachFinderApiClient; +} diff --git a/widgets/beachfinder/src/state/System/useSystemState.ts b/widgets/beachfinder/src/state/System/useSystemState.ts new file mode 100644 index 00000000..cb883c49 --- /dev/null +++ b/widgets/beachfinder/src/state/System/useSystemState.ts @@ -0,0 +1,11 @@ +import {useContext} from "react"; +import type {SystemState} from "./type.ts"; +import {LocalSystemStateContext} from "./SystemState.tsx"; + +export function useSystemState(): SystemState { + const context = useContext(LocalSystemStateContext); + if (!context) { + throw new Error("useSystemState must be used within SystemStateProvider"); + } + return context; +} \ No newline at end of file diff --git a/widgets/beachfinder/src/styles/entry.ts b/widgets/beachfinder/src/styles/entry.ts new file mode 100644 index 00000000..c960ab03 --- /dev/null +++ b/widgets/beachfinder/src/styles/entry.ts @@ -0,0 +1,5 @@ +import main from "./main.css?inline"; + +export const styles = [ + main, +]; \ No newline at end of file diff --git a/widgets/beachfinder/src/styles/main.css b/widgets/beachfinder/src/styles/main.css new file mode 100644 index 00000000..374f6f83 --- /dev/null +++ b/widgets/beachfinder/src/styles/main.css @@ -0,0 +1,97 @@ +.beachfinder { + --beachfinder-ink: #123347; + --beachfinder-muted: #58717e; + --beachfinder-sea: #087f8c; + --beachfinder-sand: #fff8ec; + box-sizing: border-box; + max-width: 42rem; + margin: 0 auto; + padding: clamp(1.25rem, 4vw, 2rem); + border: 1px solid #dce8e8; + border-radius: 1rem; + background: white; + color: var(--beachfinder-ink); + font-family: system-ui, sans-serif; + box-shadow: 0 0.75rem 2.5rem rgb(18 51 71 / 8%); +} + +.beachfinder *, +.beachfinder *::before, +.beachfinder *::after { box-sizing: inherit; } + +.beachfinder__header { margin-bottom: 1.5rem; } +.beachfinder__eyebrow { + margin: 0 0 0.25rem; + color: var(--beachfinder-sea); + font-size: 0.75rem; + font-weight: 750; + letter-spacing: 0.12em; + text-transform: uppercase; +} +.beachfinder h2 { margin: 0; font-size: clamp(1.5rem, 4vw, 2rem); } +.beachfinder__header > p:last-child { margin: 0.5rem 0 0; color: var(--beachfinder-muted); } + +.beachfinder__form { + display: grid; + grid-template-columns: minmax(0, 1fr) minmax(7rem, 9rem) auto; + align-items: end; + gap: 0.55rem 0.75rem; +} +.beachfinder__form label { grid-row: 1; font-size: 0.82rem; font-weight: 650; } +.beachfinder__form label:first-child { grid-column: 1; } +.beachfinder__form label:nth-of-type(2) { grid-column: 2; } +.beachfinder__form input { + min-width: 0; + height: 2.9rem; + padding: 0 0.8rem; + border: 1px solid #b7c9cd; + border-radius: 0.5rem; + color: inherit; + font: inherit; +} +.beachfinder__form input:focus-visible, +.beachfinder__form button:focus-visible, +.beachfinder a:focus-visible { outline: 3px solid #f4b942; outline-offset: 2px; } +.beachfinder__form > input { grid-column: 1; } +.beachfinder__radius { grid-column: 2; display: flex; align-items: center; gap: 0.45rem; } +.beachfinder__radius input { width: 5rem; } +.beachfinder__radius span { color: var(--beachfinder-muted); font-size: 0.9rem; } +.beachfinder__form button { + grid-column: 3; + grid-row: 2; + min-height: 2.9rem; + padding: 0 1rem; + border: 0; + border-radius: 0.5rem; + background: var(--beachfinder-sea); + color: white; + font: inherit; + font-weight: 700; + cursor: pointer; +} +.beachfinder__form button:disabled { cursor: wait; opacity: 0.65; } +.beachfinder__output { min-height: 2rem; margin-top: 1.5rem; } +.beachfinder__output h3 { margin: 0; font-size: 1.15rem; } +.beachfinder__summary, .beachfinder__notice { color: var(--beachfinder-muted); } +.beachfinder__notice { margin: 0; padding: 0.9rem 1rem; border-radius: 0.5rem; background: var(--beachfinder-sand); } +.beachfinder__notice--error { background: #fff0ef; color: #9a3028; } +.beachfinder__list { display: grid; gap: 0.65rem; margin: 1rem 0 0; padding: 0; list-style: none; } +.beachfinder__beach { + display: flex; + align-items: center; + justify-content: space-between; + gap: 1rem; + padding: 0.85rem 1rem; + border: 1px solid #e1ebeb; + border-radius: 0.65rem; +} +.beachfinder__beach h4 { margin: 0; font-size: 1rem; } +.beachfinder__beach p { margin: 0.2rem 0 0; color: var(--beachfinder-muted); font-size: 0.9rem; } +.beachfinder__beach a { color: var(--beachfinder-sea); font-weight: 700; text-decoration-thickness: 0.08em; text-underline-offset: 0.15em; } +.beachfinder__attribution { margin-top: 1.5rem; color: var(--beachfinder-muted); font-size: 0.75rem; } +.beachfinder__attribution a { color: inherit; } + +@media (max-width: 36rem) { + .beachfinder__form { grid-template-columns: minmax(0, 1fr) minmax(7rem, 0.55fr); } + .beachfinder__form button { grid-column: 1 / -1; grid-row: 4; } +} diff --git a/widgets/beachfinder/src/types/global.d.ts b/widgets/beachfinder/src/types/global.d.ts new file mode 100644 index 00000000..99c9f6c7 --- /dev/null +++ b/widgets/beachfinder/src/types/global.d.ts @@ -0,0 +1,9 @@ +export {}; + +declare global { + interface Window { + __REACTEDGE_DEBUG__?: boolean; + [key: `ReactEdge_${string}`]: WidgetApi; + } + const __REACTEDGE_MODE__: "render" | "hydrate"; +} diff --git a/widgets/beachfinder/tests/beachfinder.spec.ts b/widgets/beachfinder/tests/beachfinder.spec.ts new file mode 100644 index 00000000..c0541122 --- /dev/null +++ b/widgets/beachfinder/tests/beachfinder.spec.ts @@ -0,0 +1,57 @@ +import { expect, test } from "@playwright/test"; + +const beachResults = { + postcode: "BN1 1AA", + radiusMiles: 10, + beaches: [{ + id: "node-7", + name: "Brighton Beach", + latitude: 50.8198, + longitude: -0.1367, + distanceMiles: 0.8, + }], +}; + +test.describe("Beach Finder widget", () => { + test("searches by postcode and radius and displays beach details", async ({ page }) => { + let requestUrl = ""; + await page.route("**/beachfinder/beaches?*", async (route) => { + requestUrl = route.request().url(); + await route.fulfill({ json: beachResults }); + }); + await page.goto("/?reactedge_debug=eager"); + + const widget = page.locator("beachfinder-widget"); + await expect(widget.locator("[data-beachfinder-title]")).toHaveText("Find a beach near you"); + await widget.getByLabel("UK postcode").fill("BN1 1AA"); + await widget.getByLabel("Search radius").fill("10"); + await widget.getByRole("button", { name: "Find beaches" }).click(); + + await expect(widget.getByRole("heading", { name: "Beaches near BN1 1AA" })).toBeVisible(); + await expect(widget.getByRole("heading", { name: "Brighton Beach" })).toBeVisible(); + await expect(widget.getByText("0.8 miles away")).toBeVisible(); + expect(requestUrl).toContain("postcode=BN1+1AA"); + expect(requestUrl).toContain("radiusMiles=10"); + await expect(widget.getByText("OpenStreetMap contributors")).toBeVisible(); + }); + + test("shows a useful message when the postcode is unknown", async ({ page }) => { + await page.route("**/beachfinder/beaches?*", (route) => route.fulfill({ status: 404 })); + await page.goto("/?reactedge_debug=eager"); + const widget = page.locator("beachfinder-widget"); + await widget.getByLabel("UK postcode").fill("ZZ1 1ZZ"); + await widget.getByRole("button", { name: "Find beaches" }).click(); + await expect(widget.getByRole("alert")).toHaveText("That postcode could not be found. Check it and try again."); + }); + + test("shows an empty state when the service finds no beaches", async ({ page }) => { + await page.route("**/beachfinder/beaches?*", (route) => route.fulfill({ + json: { postcode: "BN1 1AA", radiusMiles: 10, beaches: [] }, + })); + await page.goto("/?reactedge_debug=eager"); + const widget = page.locator("beachfinder-widget"); + await widget.getByLabel("UK postcode").fill("BN1 1AA"); + await widget.getByRole("button", { name: "Find beaches" }).click(); + await expect(widget.getByText("No beaches found within 10 miles of BN1 1AA.")).toBeVisible(); + }); +}); diff --git a/widgets/beachfinder/tests/beachfinder.test.ts b/widgets/beachfinder/tests/beachfinder.test.ts new file mode 100644 index 00000000..bbe56e16 --- /dev/null +++ b/widgets/beachfinder/tests/beachfinder.test.ts @@ -0,0 +1,78 @@ +import assert from "node:assert/strict"; +import { readFile } from "node:fs/promises"; +import { test } from "node:test"; +import { parseConfig } from "../src/ConfigSchema.ts"; +import { parseRuntimeConfig } from "../src/ConfigSchemaRuntime.ts"; +import { + BeachFinderApiError, + createBeachFinderApiClient, +} from "../src/services/beachfinder/BeachFinderApi.ts"; + +const sample = { + postcode: "BN1 1AA", + radiusMiles: 10, + beaches: [{ + id: "node-7", + name: "Brighton Beach", + latitude: 50.8198, + longitude: -0.1367, + distanceMiles: 0.8, + }], +}; + +test("public widget and runtime JSON satisfy their schemas", async () => { + const contract = JSON.parse(await readFile(new URL("../public/default.json", import.meta.url), "utf8")); + const runtime = JSON.parse(await readFile(new URL("../public/reactedge-runtime.json", import.meta.url), "utf8")); + + assert.equal(parseConfig(contract).data.title, "Find a beach near you"); + assert.equal(parseRuntimeConfig(runtime).integrations.beachfinderApi.api, "http://127.0.0.1:4185"); +}); + +test("search sends encoded postcode and radius to the configured service", async () => { + let requestedUrl = ""; + const client = createBeachFinderApiClient("https://beaches.example.test/", async (input) => { + requestedUrl = String(input); + return Response.json(sample); + }); + + assert.deepEqual(await client.search(" BN1 1AA ", 10), sample); + assert.equal(requestedUrl, "https://beaches.example.test/beachfinder/beaches?postcode=BN1+1AA&radiusMiles=10"); +}); + +test("search presents distinct invalid postcode, unknown postcode and service errors", async (context) => { + const cases = [ + { status: 400, message: "Enter a valid UK postcode and a radius up to 100 miles." }, + { status: 404, message: "That postcode could not be found. Check it and try again." }, + { status: 502, message: "Beach search is temporarily unavailable. Please try again." }, + ]; + for (const scenario of cases) { + await context.test(`HTTP ${scenario.status}`, async () => { + const client = createBeachFinderApiClient("http://localhost:4185", async () => + new Response(null, { status: scenario.status }) + ); + await assert.rejects( + client.search("BN1 1AA", 10), + (error: unknown) => error instanceof BeachFinderApiError + && error.status === scenario.status + && error.message === scenario.message + ); + }); + } +}); + +test("search rejects malformed successful payloads", async () => { + const client = createBeachFinderApiClient("http://localhost:4185", async () => + Response.json({ ...sample, beaches: [{ id: "bad", latitude: 0 }] }) + ); + await assert.rejects(client.search("BN1 1AA", 10), { status: 502 }); +}); + +test("aborted requests retain cancellation for the caller", async () => { + const controller = new AbortController(); + controller.abort(); + const client = createBeachFinderApiClient("http://localhost:4185", async (_input, init) => { + assert.equal(init?.signal?.aborted, true); + throw new DOMException("Aborted", "AbortError"); + }); + await assert.rejects(client.search("BN1 1AA", 10, controller.signal), { name: "AbortError" }); +}); diff --git a/widgets/beachfinder/tsconfig.app.json b/widgets/beachfinder/tsconfig.app.json new file mode 100644 index 00000000..705ab148 --- /dev/null +++ b/widgets/beachfinder/tsconfig.app.json @@ -0,0 +1,7 @@ +{ + "extends": "../../packages/widget-build/shared-resources/tsconfig.app.widget.json", + "compilerOptions": { + "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo" + }, + "include": ["src", "api"] +} \ No newline at end of file diff --git a/widgets/beachfinder/tsconfig.json b/widgets/beachfinder/tsconfig.json new file mode 100644 index 00000000..4ebbbc80 --- /dev/null +++ b/widgets/beachfinder/tsconfig.json @@ -0,0 +1,8 @@ +{ + "files": [], + "references": [ + { "path": "./tsconfig.app.json" }, + { "path": "./tsconfig.node.json" } + ], + "extends": "../../tsconfig.json" +} diff --git a/widgets/beachfinder/tsconfig.node.json b/widgets/beachfinder/tsconfig.node.json new file mode 100644 index 00000000..620f3ec4 --- /dev/null +++ b/widgets/beachfinder/tsconfig.node.json @@ -0,0 +1,10 @@ +{ + "extends": "../../packages/widget-build/shared-resources/tsconfig.node.widget.json", + "compilerOptions": { + "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo" + }, + "include": [ + "vite.config.ts", + "vite.npm.config.ts" + ] +} diff --git a/widgets/beachfinder/vite.config.ts b/widgets/beachfinder/vite.config.ts new file mode 100644 index 00000000..a24d7915 --- /dev/null +++ b/widgets/beachfinder/vite.config.ts @@ -0,0 +1,49 @@ +import { defineConfig } from "vite"; +import react from "@vitejs/plugin-react-swc"; +import pkg from "./package.json" with { type: "json" }; +import { fileURLToPath } from "node:url"; +import { dirname, resolve } from "node:path"; + +import { manifestPlugin } from "../../packages/widget-build/shared-resources/widget-preset/manifestPlugin.ts"; +import { createWidgetBuildDefaults } from "../../packages/widget-build/shared-resources/widget-preset/createReactEdgeConfig.ts"; +import { reactEdgeVisualizer } from "../../packages/widget-build/shared-resources/widget-preset/reactEdgeVisualizer.ts"; + +const isAnalyze = process.env.ANALYZE === "true"; +const widgetName = pkg.name.replace(/^widget-/, ""); +const widgetDir = dirname(fileURLToPath(import.meta.url)); + +export default defineConfig({ + resolve: { + alias: { + "@reactedge": resolve( + widgetDir, + "../../packages/widget-build/shared-resources" + ), + }, + }, + + plugins: [ + react(), + reactEdgeVisualizer(isAnalyze), + manifestPlugin({ + widgetName, + version: pkg.version, + }), + ], + + define: { + "process.env.NODE_ENV": JSON.stringify("production"), + }, + + build: createWidgetBuildDefaults({ + widgetName, + version: pkg.version, + entry: resolve(widgetDir, "api/runtime-shadow-widget.tsx"), + outDir: resolve( + widgetDir, + `../../workspace/release/source/${widgetName}` + ), + emitCss: false, + sourcemap: false + }), +}); \ No newline at end of file diff --git a/widgets/beachfinder/vite.npm.config.ts b/widgets/beachfinder/vite.npm.config.ts new file mode 100644 index 00000000..71f83cc3 --- /dev/null +++ b/widgets/beachfinder/vite.npm.config.ts @@ -0,0 +1,31 @@ +import { defineConfig} from "vite"; +import type { BuildOptions } from "vite" +import react from "@vitejs/plugin-react-swc"; +import pkg from "./package.json" with { type: "json" }; +import {dirname, resolve} from "node:path"; +import {createNpmBuildDefaults} from "../../packages/widget-build/shared-resources/widget-preset/createReactEdgeConfig.ts"; +import {fileURLToPath} from "node:url"; + +const widgetName = pkg.name.replace(/^widget-/, ""); +const widgetDir = dirname(fileURLToPath(import.meta.url)); + +export default defineConfig({ + resolve: { + alias: { + "@reactedge": resolve( + widgetDir, + "../../packages/widget-build/shared-resources" + ), + }, + }, + publicDir: resolve(import.meta.dirname, "public"), + plugins: [react(), ], + define: { + __REACTEDGE_MODE__: JSON.stringify( + process.env.REACTEDGE_MODE ?? "render" + ), + }, + build: createNpmBuildDefaults({ + widgetName + }), +}); \ No newline at end of file From aafafe9a7416ca752733f2b342764d6c433b33fe Mon Sep 17 00:00:00 2001 From: Herve Tribouilloy Date: Mon, 19 Oct 2026 18:36:38 +0100 Subject: [PATCH 29/29] fix: align Beach Finder service routes with conventions --- services/beachfinder/.env.sample | 2 +- services/beachfinder/src/config.ts | 2 +- .../src/controller/beachfinder-handler.ts | 51 ++++++++++++++++ services/beachfinder/src/lib/cors-setup.ts | 5 +- .../beach-finder.ts} | 2 +- .../beachfinder/src/routes/beach-router.ts | 50 +++------------ services/beachfinder/src/routes/index.ts | 5 +- services/beachfinder/test/beachfinder.test.ts | 61 ++++++++++++++++++- 8 files changed, 126 insertions(+), 52 deletions(-) create mode 100644 services/beachfinder/src/controller/beachfinder-handler.ts rename services/beachfinder/src/model/{beachfinder.ts => beachfinder/beach-finder.ts} (99%) diff --git a/services/beachfinder/.env.sample b/services/beachfinder/.env.sample index 58f9a483..71709a87 100644 --- a/services/beachfinder/.env.sample +++ b/services/beachfinder/.env.sample @@ -1,5 +1,5 @@ PORT=4185 -FRONTEND_URL=http://localhost:3000 +FRONTEND_URL=http://localhost:5173,http://127.0.0.1:5173 OTEL_HOST=http://localhost:4318 OTEL_SERVICE_NAME=reactedge-beachfinder POSTCODE_API_URL=https://api.postcodes.io/postcodes diff --git a/services/beachfinder/src/config.ts b/services/beachfinder/src/config.ts index 181e5b6a..5ff14d21 100644 --- a/services/beachfinder/src/config.ts +++ b/services/beachfinder/src/config.ts @@ -19,7 +19,7 @@ export type Config = { export const config: Config = { port: Number(process.env.PORT ?? '4185'), - frontendUrl: process.env.FRONTEND_URL ?? 'http://localhost:3000', + frontendUrl: process.env.FRONTEND_URL ?? 'http://localhost:5173,http://127.0.0.1:5173', route: { servicePrefix: '/beachfinder' }, diff --git a/services/beachfinder/src/controller/beachfinder-handler.ts b/services/beachfinder/src/controller/beachfinder-handler.ts new file mode 100644 index 00000000..3772e38b --- /dev/null +++ b/services/beachfinder/src/controller/beachfinder-handler.ts @@ -0,0 +1,51 @@ +import type {Request, Response} from 'express'; +import {BeachFinder, PostcodeNotFoundError, ProviderError} from '../model/beachfinder/beach-finder'; +import type {Operation} from '../observability/operation'; + +const postcodePattern = /^[A-Z]{1,2}\d[A-Z\d]?\s*\d[A-Z]{2}$/i; + +export function parseBeachSearchQuery(postcodeValue: unknown, radiusValue: unknown): { + postcode: string; + radiusMiles: number; +} | null { + const postcode = String(postcodeValue ?? '').trim(); + const radiusMiles = Number(radiusValue); + if (!postcodePattern.test(postcode) || !Number.isFinite(radiusMiles) || radiusMiles <= 0 || radiusMiles > 100) { + return null; + } + return {postcode, radiusMiles}; +} + +export class BeachFinderHandler { + constructor(private readonly finder = new BeachFinder()) {} + + search = async (request: Request, response: Response): Promise => { + const operation = response.locals.routeOperation as Operation; + const query = parseBeachSearchQuery(request.query.postcode, request.query.radiusMiles); + if (!query) { + const error = new Error('Provide a valid UK postcode and radiusMiles from 0 to 100.'); + operation.fail(error); + response.status(400).json({error: error.message}); + return; + } + + try { + const beaches = await this.finder.search(query.postcode, query.radiusMiles); + operation.succeed(); + response.json({postcode: query.postcode.toUpperCase(), radiusMiles: query.radiusMiles, beaches}); + } catch (error) { + if (error instanceof PostcodeNotFoundError) { + operation.fail(error); + response.status(404).json({error: 'UK postcode was not found.'}); + return; + } + if (error instanceof ProviderError) { + operation.fail(error); + response.status(502).json({error: error.message}); + return; + } + operation.fail(error); + response.status(500).json({error: 'Beach search failed.'}); + } + }; +} diff --git a/services/beachfinder/src/lib/cors-setup.ts b/services/beachfinder/src/lib/cors-setup.ts index f59b809f..0b019d9a 100644 --- a/services/beachfinder/src/lib/cors-setup.ts +++ b/services/beachfinder/src/lib/cors-setup.ts @@ -10,7 +10,8 @@ export const corsOptions = () => { const options = { allowedHeaders: [ 'Origin', - 'Accept' + 'Accept', + 'Content-Type' ], credentials: true, methods: 'GET,HEAD,OPTIONS,PUT,PATCH,POST,DELETE', @@ -19,4 +20,4 @@ export const corsOptions = () => { }; return cors(options) -} \ No newline at end of file +} diff --git a/services/beachfinder/src/model/beachfinder.ts b/services/beachfinder/src/model/beachfinder/beach-finder.ts similarity index 99% rename from services/beachfinder/src/model/beachfinder.ts rename to services/beachfinder/src/model/beachfinder/beach-finder.ts index 329f9029..eb55393e 100644 --- a/services/beachfinder/src/model/beachfinder.ts +++ b/services/beachfinder/src/model/beachfinder/beach-finder.ts @@ -1,4 +1,4 @@ -import {config} from '../config'; +import {config} from '../../config'; export type Beach = { id: string; diff --git a/services/beachfinder/src/routes/beach-router.ts b/services/beachfinder/src/routes/beach-router.ts index 34a02800..5e011692 100644 --- a/services/beachfinder/src/routes/beach-router.ts +++ b/services/beachfinder/src/routes/beach-router.ts @@ -1,55 +1,19 @@ -import type {Application, Request, Response} from 'express'; +import type {Application} from 'express'; import express from 'express'; import {config} from '../config'; -import {BeachFinder, PostcodeNotFoundError, ProviderError} from '../model/beachfinder'; +import {BeachFinder} from '../model/beachfinder/beach-finder'; +import {BeachFinderHandler} from '../controller/beachfinder-handler'; +import {corsOptions} from '../lib/cors-setup'; import {createRouteOperationMiddleware} from '../observability/request-operation-middleware'; -const postcodePattern = /^[A-Z]{1,2}\d[A-Z\d]?\s*\d[A-Z]{2}$/i; - -export function parseBeachSearchQuery(postcodeValue: unknown, radiusValue: unknown): { - postcode: string; - radiusMiles: number; -} | null { - const postcode = String(postcodeValue ?? '').trim(); - const radiusMiles = Number(radiusValue); - if (!postcodePattern.test(postcode) || !Number.isFinite(radiusMiles) || radiusMiles <= 0 || radiusMiles > 100) { - return null; - } - return {postcode, radiusMiles}; -} - export function setupBeachRoutes(app: Application, finder = new BeachFinder()): void { const router = express.Router(); + const handler = new BeachFinderHandler(finder); + router.use(corsOptions()); router.get( '/beaches', createRouteOperationMiddleware('beachfinder.search'), - async (request: Request, response: Response) => handleBeachSearch(request, response, finder) + handler.search ); app.use(config.route.servicePrefix, router); } - -async function handleBeachSearch( - request: Request, - response: Response, - finder: BeachFinder -): Promise { - const query = parseBeachSearchQuery(request.query.postcode, request.query.radiusMiles); - if (!query) { - response.status(400).json({error: 'Provide a valid UK postcode and radiusMiles from 0 to 100.'}); - return; - } - try { - const beaches = await finder.search(query.postcode, query.radiusMiles); - response.json({postcode: query.postcode.toUpperCase(), radiusMiles: query.radiusMiles, beaches}); - } catch (error) { - if (error instanceof PostcodeNotFoundError) { - response.status(404).json({error: 'UK postcode was not found.'}); - return; - } - if (error instanceof ProviderError) { - response.status(502).json({error: error.message}); - return; - } - response.status(500).json({error: 'Beach search failed.'}); - } -} diff --git a/services/beachfinder/src/routes/index.ts b/services/beachfinder/src/routes/index.ts index f44624b2..bc46b017 100644 --- a/services/beachfinder/src/routes/index.ts +++ b/services/beachfinder/src/routes/index.ts @@ -1,8 +1,9 @@ import type {Application} from "express"; import {setupStatusRoutes} from "./status-router"; import {setupBeachRoutes} from "./beach-router"; +import {BeachFinder} from "../model/beachfinder/beach-finder"; -export default (app: Application) => { +export default (app: Application, finder = new BeachFinder()) => { setupStatusRoutes(app); - setupBeachRoutes(app); + setupBeachRoutes(app, finder); } diff --git a/services/beachfinder/test/beachfinder.test.ts b/services/beachfinder/test/beachfinder.test.ts index 07519d94..4e9c19fa 100644 --- a/services/beachfinder/test/beachfinder.test.ts +++ b/services/beachfinder/test/beachfinder.test.ts @@ -1,7 +1,10 @@ import assert from 'node:assert/strict'; +import express from 'express'; +import type {Request, Response} from 'express'; import {test} from 'node:test'; -import {BeachFinder} from '../src/model/beachfinder'; -import {parseBeachSearchQuery} from '../src/routes/beach-router'; +import {BeachFinderHandler, parseBeachSearchQuery} from '../src/controller/beachfinder-handler'; +import {BeachFinder} from '../src/model/beachfinder/beach-finder'; +import routes from '../src/routes/index'; test('finds and sorts beaches within radius, including way centers', async () => { const calls: RequestInfo[] = []; @@ -31,3 +34,57 @@ test('validates UK postcodes and search radius values', () => { assert.equal(parseBeachSearchQuery('nope', '4'), null); assert.equal(parseBeachSearchQuery('BN1 1AA', '101'), null); }); + +test('mounts status and beach search routes under the service router', () => { + const app = express(); + routes(app, new BeachFinder(async () => Response.json({status: 200, result: {latitude: 50, longitude: 0}}))); + const routerStack = (app as unknown as { + router: {stack: Array<{handle?: {stack?: Array<{route?: {path: string}}>} }>}; + }).router.stack; + const registeredPaths = routerStack.flatMap(layer => + layer.handle?.stack?.flatMap(entry => entry.route ? [entry.route.path] : []) ?? [] + ); + + assert.deepEqual(registeredPaths, ['/status', '/beaches']); +}); + +test('search handler returns beaches and records success', async () => { + let succeeded = false; + let responseBody: unknown; + const finder = {search: async () => [{ + id: 'node/1', name: 'Test Beach', latitude: 50, longitude: 0, distanceMiles: 0 + }]}; + const handler = new BeachFinderHandler(finder as unknown as BeachFinder); + const response = { + locals: {routeOperation: {succeed: () => { succeeded = true; }, fail: () => undefined}}, + json: (body: unknown) => { responseBody = body; return response; }, + status: () => response, + } as unknown as Response; + + await handler.search({query: {postcode: 'BN1 1AA', radiusMiles: '5'}} as unknown as Request, response); + + assert.equal(succeeded, true); + assert.deepEqual(responseBody, { + postcode: 'BN1 1AA', radiusMiles: 5, + beaches: [{id: 'node/1', name: 'Test Beach', latitude: 50, longitude: 0, distanceMiles: 0}], + }); +}); + +test('search handler responds with 400 for an invalid query without provider calls', async () => { + let statusCode = 0; + let responseBody: unknown; + let failed = false; + const finder = {search: async () => { throw new Error('should not run'); }}; + const handler = new BeachFinderHandler(finder as unknown as BeachFinder); + const response = { + locals: {routeOperation: {succeed: () => undefined, fail: () => { failed = true; }}}, + json: (body: unknown) => { responseBody = body; return response; }, + status: (status: number) => { statusCode = status; return response; }, + } as unknown as Response; + + await handler.search({query: {postcode: 'not-a-postcode', radiusMiles: '5'}} as unknown as Request, response); + + assert.equal(statusCode, 400); + assert.equal(failed, true); + assert.deepEqual(responseBody, {error: 'Provide a valid UK postcode and radiusMiles from 0 to 100.'}); +});