FDC3 For Web Browsers Implementation

.github/workflows/base-coverage.yml

@@ -0,0 +1,31 @@
+name: Test coverage for main branch
+
+on:
+  push:
+    branches:
+      - main
+      - fdc3-for-web-impl
+
+jobs:
+  test_and_upload_coverage:
+    runs-on: ubuntu-latest
+    name: Test and upload coverage
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          ref: ${{ github.event.ref }}
+          fetch-depth: 1000
+
+      - name: Run tests
+        run: |
+          npm i
+          npm run test
+          npm run merge
+          npm run report
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-coverage-output
+          path: nyc-coverage-report

.github/workflows/coverage.yml

@@ -0,0 +1,69 @@
+name: Node.js CI Tests and Coverage
+
+# Controls when the workflow will run on any branch
+on:
+  pull_request:
+
+# Allows Coverage to be written back as a PR comment
+permissions: 
+  pull-requests: write
+
+# Define the jobs for this workflow
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.pull_request.head.sha }}
+        fetch-depth: 1000
+
+    - name: Fetch base
+      run: git fetch origin ${{ github.event.pull_request.base.ref }} --depth=1000
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v3
+      with:
+        node-version: 20.x
+
+    - name: Install dependencies
+      run: npm install
+
+    - name: Run tests
+      run: npm run test
+
+    - name: Merge Results
+      run: npm run merge
+
+    - name: Create Report
+      run: npm run report
+
+    - name: Create test summary
+      uses: test-summary/action@dist
+      with:
+        paths: "**/test-results.xml"
+        show: "fail, skip"
+        output: test-summary.md
+      if: always()
+
+    - name: PR comment with file
+      uses: thollander/actions-comment-pull-request@v3
+      with:
+        file-path: test-summary.md
+
+    - name: Download previous coverage
+      uses: dawidd6/action-download-artifact@v7
+      with:
+        workflow: base-coverage.yml
+        name: 'test-coverage-output'
+        path: base-artifacts
+        search_artifacts: true
+
+    - name: Report Coverage
+      uses: sidx1024/[email protected]
+      with:
+        coverage_file: "nyc-coverage-report/coverage-summary.json"
+        base_coverage_file: "base-artifacts/coverage-summary.json"
+

.github/workflows/cve-scanning.yml

@@ -45,10 +45,6 @@ jobs:
 
       - run: npx --yes auditjs ossi --whitelist allow-list.json
         if: success() || failure()
-
-      - run: npx --yes auditjs ossi --whitelist ../../allow-list.json
-        working-directory: toolbox/fdc3-workbench
-        if: success() || failure()
 
       - run: npx --yes auditjs ossi --whitelist ../allow-list.json
         working-directory: website

.gitignore

@@ -13,9 +13,16 @@ website/build/
 website/static/toolbox
 website/node_modules
 website/i18n/*
-website/package-lock.json
-website/.docusaurus/**
+website/.docusaurus/
+website/static/schemas/next/*
+website/static/ui
+test-results.xml
+
 
 .idea/
 *.iml
-website/.yarn
+website/.yarn
+.nyc_output
+toolbox/fdc3-for-web/fdc3-web-impl/generated/
+cucumber-report.html
+nyc-coverage-report/

.husky/pre-commit

@@ -0,0 +1,2 @@
+#!/bin/sh
+npx lint-staged

.npmrc

@@ -0,0 +1,4 @@
+# Omit the registry url which can be an organization's internal npm mirror when generating package-lock.json file
+# see: https://github.com/npm/cli/pull/4874
+# and https://docs.npmjs.com/cli/v8/using-npm/config#omit-lockfile-registry-resolved
+omit-lockfile-registry-resolved = true

.prettierignore

@@ -9,3 +9,7 @@
 website
 dist
 src/app-directory/*/target
+node_modules
+coverage
+.nyc_output
+build

.semgrepignore

@@ -2,7 +2,10 @@ website/**
 
 # Just used for build so ignoring
 s2tQuicktypeUtil.js
-schemas/api/t2sQuicktypeUtil.js
+t2sQuicktypeUtil.js
 
 # API schema set for localhost gets picked up by semgrep rule
-schemas/bridgingAsyncAPI/bridgingAsyncAPI.json 
+schemas/bridgingAsyncAPI/bridgingAsyncAPI.json
+
+# demo apps get picked up for not having integrity headers
+toolbox/fdc3-for-web/demo/src/client/apps/**

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "typescript.tsdk": "node_modules/typescript/lib"
+}

CHANGELOG.md

@@ -23,7 +23,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added utility functions `isStandardContextType(contextType: string)`, `isStandardIntent(intent: string)`,`getPossibleContextsForIntent(intent: StandardIntent)`. ([#1139](https://github.com/finos/FDC3/pull/1139))
 * Added support for event listening outside of intent or context listnener. Added new function `addEventListener`, type `EventHandler`,  enum `FDC3EventType` and interfaces `FDC3Event` and `FDC3ChannelChangedEvent`. ([#1207](https://github.com/finos/FDC3/pull/1207))
 * Added new `CreateOrUpdateProfile` intent. ([#1359](https://github.com/finos/FDC3/pull/1359))
-* Added conformance tests into the FDC3 API documentation in the current version and backported into 2.0 and 2.1. Removed outdated 1.2 conformance tests (which are preserved in the older 2.0 and 2.1 versions). ([#1417](https://github.com/finos/FDC3/pull/1417)).
+* Added conformance tests into the FDC3 API documentation in the current version and backported into 2.0 and 2.1. Removed outdated 1.2 conformance tests (which are preserved in the older 2.0 and 2.1 versions). ([#1417](https://github.com/finos/FDC3/pull/1417))
+* Added separate `fdc3-commonjs` module for compatibility with older projects that use CommonJS. ([#1452](https://github.com/finos/FDC3/pull/1452))
+* Added testing policy to [Contributing](CONTRIBUTING) page to address ([810](https://github.com/finos/FDC3/issues/810))
+* Added the ability to control logging to the JS console from getAgent() and the DesktopAgentProxy via arguments to getAgent(). ([#1495](https://github.com/finos/FDC3/pull/1495))
+* Added the ability for a browser-based DesktopAgent to control the timeouts used in the DesktopAgentProxy when making calls to it, via properties in WCP3Handshake message. ([#1497](https://github.com/finos/FDC3/pull/1497))
+
 
 ### Changed
 
@@ -34,6 +39,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * FDC3 apps are now encouraged to instantiate their FDC3 interface (DesktopAgent) using the `getAgent()` function provided by the `@finos/fdc3` module. This will allow apps to interoperate in either traditional Preload DAs (i.e. Electron) as well as the new Browser-Resident DAs. ([#1191](https://github.com/finos/FDC3/pull/1191))
 * `ContextType` and `Intent` (`string`) types were created for use in DesktopAgent API signatures - they are unions of standardized values and `string`, enabling autocomplete/IntelliSense in IDEs when working with the FDC3 API. ([#1139](https://github.com/finos/FDC3/pull/1139))
 * SessionStorage use by `getAgent` was updated to scope the stored data by `window.name` and the app's `identityUrl`. ([#1442](https://github.com/finos/FDC3/pull/1442))
+* FDC3 Workbench updated to use `getAgent()` rather than `fdc3Ready()`
 
 ### Deprecated
 

CONTRIBUTING.md

@@ -80,6 +80,30 @@ The Working Group uses pull requests to track changes. To submit a change to the
 
 To contribute a patch for a New Intent, see the [Submit New Intent](docs/guides/submit-new-intent) guide.
 
+**3.6. Test Policy**
+
+- The FDC3 project takes very seriously code quality, especially with respect to production-grade sub-modules.  This includes:
+
+|Module | Test Policy |
+|---|---|
+|`packages/fdc3` | Code should not be added here - just `import` / `export` in `index.ts` |
+|`packages/fdc3-agent-proxy` | Contributions must improve or maintain coverage at the current level |
+|`packages/fdc3-commonjs` | Code should not be added here |
+|`packages/fdc3-context` | Must contain only JSON Schemas and source code generated from them |
+|`packages/fdc3-get-agent` |Contributions must improve or maintain coverage at the current level 
+|`packages/fdc3-schema` | Must contain only JSON Schemas and source code generated from them |
+|`packages/fdc3-standard` | Contributions must improve or maintain coverage at the current level |
+|`toolbox/fdc3-for-web/fdc3-web-impl` | Contributions must improve or maintain coverage at the current level |
+
+Please note that the FDC3 project uses the following test policy:
+
+  * Code should have tests (coverage is reported in the PR comments)
+  * All tests must pass. (checked automatically by the PR comments)
+  * All tests must be meaningful.
+  * All tests must be kept up-to-date.
+  * All tests must be run locally before submitting a PR.
+  * Finally, the `toolbox/fdc3-for-web/demo` project is expected to pass the FDC3 conformance framework prior to new FDC3 releases (not currently automated).
+
 ## 4.	Pull Request Workflow.
 
 The next section contains more information on the workflow followed for Pull Requests.

README.md

@@ -76,12 +76,47 @@ The specifications are informed by agreed [business use cases](https://fdc3.fino
 - All that is required is a "desktop agent" that supports the FDC3 standard, which is responsible for coordinating application interactions.
 - Get started using FDC3 on the web with TypeScript by reading the [supported platforms](https://fdc3.finos.org/docs/supported-platforms) page.
 
-### FDC3 npm module
+## FDC3 Project Structure
 
-The FDC3 npm package does NOT provide a Desktop Agent implementation. Rather, it can by used by web applications to target operations from the API Specification in a consistent way. Each FDC3-compliant desktop agent that the application runs in, can then provide an implementation of the FDC3 API operations.
+This project (the FDC3 Standard repo) is now a monorepo containing the following modules:
+
+| Directory                            | Release Coordinates                                    | Purpose                                                                                                                                                                                                                | Testing / Coverage    |
+|--------------------------------------|--------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|
+| `packages/fdc3-schema`               | `@finos/fdc3-schema` (npm)                             | Contains the FDC3 For The Web and Desktop Agent Bridging protocol schemas.   Generates `BridgingTypes.ts` and `BrowserTypes.ts` versions of those schemas for consumption in typescript code.                          | n/a                   |
+| `packages/fdc3-context`              | `@finos/fdc3-context` (npm)                            | Contains the schemas for standard FDC3 context types.  Generates the `ContextTypes.ts` typescript version of the schema for consumption in typescript/javascript.                                                      | n/a                   |
+| `packages/fdc3-standard`             | `@finos/fdc3-standard` (npm)                           | Interface definitions for the FDC3 standard in typescript (e.g. the `DesktopAgent` interface) and the app directory schema.                                                                                            | Jest, embedded NYC    |
+| `packages/fdc3-agent-proxy`          | `@finos/fdc3-agent-proxy` (npm)                        | Contains a complete implementation of the FDC3 DACP.  Written in a platform-agnostic manner.                                                                                                                            | Cucumber, NYC         |
+| `packages/fdc3-get-agent`            | `@finos/fdc3-get-agent` (npm)                          | Implements the `getAgent` and `fdc3Ready()` functions as well as the FDC3 Web Connection protocol to allow FDC3 to work on the web or in an electron container.                                                     | Cucumber, NYC         |
+| `packages/testing`                   | -not released-                                         | Contains testing tools used by the cucumber tests used within other modules of this project.                                                                                                                           |                       |
+| `toolbox/fdc3-conformance`           | -not released-                                         | Contains definitions of the FDC3 conformance test suite, implemented by the [FDC3 Conformance Framework](https://github.com/finos/FDC3-conformance-framework)                                                          | Test Definitions Only |
+| `toolbox/fdc3-workbench`             | [here](https://fdc3.finos.org/toolbox/fdc3-workbench/) | Contains an FDC3-For-Web ready version of the [FDC3 Workbench](toolbox/fdc3-workbench/README.md).                                                                                                                      |                       |
+| `toolbox/fdc3-explained`             | [Here](https://fdc3.finos.org/toolbox/fdc3-explained)  | [Readme Here](toolbox/fdc3-explained/README.md)                                                                                                                                                                        |                       |
+| `toolbox/fdc3-for-web/fdc3-web-impl` | `@finos/fdc3-web-impl` (npm)                           | Portable and reusable implementation of the FDC3 For-The-Web Desktop Agent-Side protocol,                                                                                                                              | Cucumber, NYC         |
+| `toolbox/fdc3-for-web/demo`          | -not released-                                         | A reference implementation of an FDC3-For-The-Web Desktop Agent, using the above implementation and conforming to FDC3 2.0 from the  [FDC3 Conformance Framework](https://github.com/finos/FDC3-conformance-framework) |                       |
+| `packages/fdc3`                      | `@finos/fdc3` (npm)                                    | Imports `fdc3-standard`, `fdc3-context`, `fdc3-schema` and `fdc3-get-agent` sub-modules.  This is intended to be the main entry point for typescript / javascript applications using FDC3         |                       |
+| `packages/fdc3-commonjs`                      | `@finos/fdc3-commonjs` (npm)                                    | A roll-up of the `fdc3` sub-module.  This is for **backwards compatibility where CommonJS is required**.  May not be provided in future versions of FDC3.         |                       |
+
+
+### Building and Running The FDC3 Modules
+
+From the root package, you can run `npm run build` to build all the modules, or `npm run test` to run all the tests.  `npm run dev` will start the `demo` and `fdc3-workbench` modules.
 
 For installation and usage instructions, see: <https://fdc3.finos.org/docs/supported-platforms#usage>
 
+### Bumping Version Numbers (for maintainers)
+
+It's important that all of the versions of the submodules stay on the same version, and that the references between them are consistent to that version.  To change the version number (say before or after a release) run the following:
+
+```
+// first, update version number in package.json
+npm login
+npm version <new version from package.json> --workspaces // changes the version number in all submodule package.json files
+npm run syncpack                          // sycnhronizes version numbers
+npm up                                    // fixes node_module references
+npm run build                             // builds all the modules against the new version
+npm publish --access=public --workspaces  // this step performs a manual release of the npm modules (not needed with GitHub actions releases)
+```
+
 ## Getting Involved
 
 ### Using the standard? Let us know
@@ -171,4 +206,6 @@ THIS STANDARD IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULA
 
 ## FDC3 Archive
 
-An archive of FDC3 documentation and meeting notes is available at <https://finosfoundation.atlassian.net/wiki/spaces/FDC3/overview>. The mailing list archive for [[email protected]](mailto:[email protected]) is available at <https://groups.google.com/a/finos.org/g/fdc>
+An archive of FDC3 documentation and meeting notes from the early days of FDC3 is available at <https://finosfoundation.atlassian.net/wiki/spaces/FDC3/overview>. Later meeting minutes cam be found in closed Github issues.
+
+The mailing list archive for [[email protected]](mailto:[email protected]) is available at <https://groups.google.com/a/finos.org/g/fdc3>

comment-template.md

@@ -0,0 +1,20 @@
+## Coverage Report
+
+Commit: [{{short_commit_sha}}]({{commit_link}})
+Base: [{{base_ref}}@{{base_short_commit_sha}}]({{base_commit_link}})
+
+| Type                      | Base                                       | This PR                                                                            |
+|---------------------------|--------------------------------------------|------------------------------------------------------------------------------------|
+| Total Statements Coverage | {{base_total_statements_coverage_percent}} | {{total_statements_coverage_percent}} ({{total_statements_coverage_percent_diff}}) |
+| Total Branches Coverage   | {{base_total_branches_coverage_percent}}   | {{total_branches_coverage_percent}} ({{total_branches_coverage_percent_diff}})     |
+| Total Functions Coverage  | {{base_total_functions_coverage_percent}}  | {{total_functions_coverage_percent}} ({{total_functions_coverage_percent_diff}})   |
+| Total Lines Coverage      | {{base_total_lines_coverage_percent}}      | {{total_lines_coverage_percent}} ({{total_lines_coverage_percent_diff}})           |
+
+<details>
+<summary>Details (changed files)</summary>
+{{changed_files_coverage_table}}
+</details>
+<details>
+<summary>Details (all files)</summary>
+{{files_coverage_table}}
+</details>

netlify.toml

@@ -1,5 +1,5 @@
 [build]
-  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../{toolbox,docs,src,test,website}/"
+  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../{packages,website,toolbox}/"
 
 [[headers]]
   # Define which paths this specific [[headers]] block will cover.