@flowscripter/example-host-application 1.0.0

package/.github/workflows/check-bun-dependencies.yml

@@ -0,0 +1,12 @@
+name: check-bun-dependencies
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * *"
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  call-check-bun-dependencies:
+    uses: flowscripter/.github/.github/workflows/check-bun-dependencies.yml@v1
+    secrets: inherit

package/.github/workflows/lint-pr-message.yml

@@ -0,0 +1,13 @@
+name: lint-pr-message
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+permissions:
+  contents: read
+jobs:
+  call-lint-pr-message:
+    uses: flowscripter/.github/.github/workflows/lint-pr-message.yml@v1
+    secrets: inherit

package/.github/workflows/release-bun-executable.yml

@@ -0,0 +1,16 @@
+name: release-bun-executable
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  id-token: write
+  pages: write
+jobs:
+  call-release-bun-executable:
+    uses: flowscripter/.github/.github/workflows/release-bun-executable.yml@v1
+    secrets: inherit
+    with:
+      executable-name: "example-host-application"

package/.github/workflows/validate-bun-executable-pr.yml

@@ -0,0 +1,10 @@
+name: validate-bun-executable-pr
+on:
+  pull_request:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  call-validate-bun-executable-pr:
+    uses: flowscripter/.github/.github/workflows/validate-bun-executable-pr.yml@v1
+    secrets: inherit

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Flowscripter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# example-host-application
+
+[![version](https://img.shields.io/github/v/release/flowscripter/example-host-application?sort=semver)](https://github.com/flowscripter/example-host-application/releases)
+[![build](https://img.shields.io/github/actions/workflow/status/flowscripter/example-host-application/release-bun-executable.yml)](https://github.com/flowscripter/example-host-application/actions/workflows/release-bun-executable.yml)
+[![coverage](https://codecov.io/gh/flowscripter/example-host-application/branch/main/graph/badge.svg?token=EMFT2938ZF)](https://codecov.io/gh/flowscripter/example-host-application)
+[![docs](https://img.shields.io/badge/docs-API-blue)](https://flowscripter.github.io/example-host-application/index.html)
+[![license: MIT](https://img.shields.io/github/license/flowscripter/example-host-application)](https://github.com/flowscripter/example-host-application/blob/main/LICENSE)
+
+> Example host application executable for the
+> [dynamic-plugin-framework](https://github.com/flowscripter/dynamic-plugin-framework)
+
+## Binary Executable Usage
+
+**NOTE**: The binaries are 10's of megabytes in size as the entire Bun runtime
+is included.
+
+#### MacOS
+
+Via [Homebrew](https://brew.sh/):
+
+`brew install flowscripter/tap/example-host-application`
+
+#### Linux
+
+In a terminal:
+
+`curl -fsSL https://raw.githubusercontent.com/flowscripter/example-host-application/main/script/install.sh | sh`
+
+#### Windows
+
+Via [Winget](https://github.com/microsoft/winget-cli):
+
+`winget install Flowscripter.example-host-application`
+
+#### Manual Install
+
+You can download and extract the binary zip files from the
+[releases](https://github.com/flowscripter/example-host-application/releases)
+page.
+
+## Functional Tests
+
+Refer to [functional_tests/README.md](functional_tests/README.md)
+
+## Development
+
+Install dependencies:
+
+`bun install`
+
+Test:
+
+`bun test`
+
+Run:
+
+`bun run index.ts`
+
+Compile binary:
+
+`bun build index.ts --compile --outfile /tmp/example-host-application`
+
+**NOTE**: The following tasks use Deno as it excels at these and Bun does not
+currently provide such functionality:
+
+Format:
+
+`deno fmt`
+
+Lint:
+
+`deno lint index.ts src/ tests/`
+
+Generate HTML API Documentation:
+
+`deno doc --html --name=example-host-application index.ts`
+
+## Documentation
+
+### Framework API
+
+Refer to the
+[dynamic-plugin-framework](https://github.com/flowscripter/dynamic-plugin-framework)
+for an overview of what this example is demonstrating.
+
+### API
+
+Link to auto-generated API docs:
+
+[API Documentation](https://flowscripter.github.io/example-host-application/index.html)
+
+## License
+
+MIT © Flowscripter

package/bun.lock

@@ -0,0 +1,33 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@flowscripter/example-host-application",
+      "dependencies": {
+        "@flowscripter/dynamic-plugin-framework": "^1.3.18",
+        "@flowscripter/example-plugin-api": "^1.0.8",
+      },
+      "devDependencies": {
+        "@types/bun": "^1.2.10",
+      },
+      "peerDependencies": {
+        "typescript": "^5.8.3",
+      },
+    },
+  },
+  "packages": {
+    "@flowscripter/dynamic-plugin-framework": ["@flowscripter/dynamic-plugin-framework@1.3.18", "", { "peerDependencies": { "typescript": "^5.8.3" } }, "sha512-OjH8O4MWXU/Wt1so49ef6OnnHlJkHuKKya8zVLR3nkxXhHbR3jHf2VmWl+mOR6liRyN9YN5IyeCvKonnAG6jTQ=="],
+
+    "@flowscripter/example-plugin-api": ["@flowscripter/example-plugin-api@1.0.8", "", { "peerDependencies": { "typescript": "^5.8.2" } }, "sha512-hRF0DRg+8aKmnAwLDQyA7phjRbET0yD9bBYdny2csL2N5JiV/KLFdfwtJSSSL/LlMdkwtl0VKAVroVc78eWAsw=="],
+
+    "@types/bun": ["@types/bun@1.2.10", "", { "dependencies": { "bun-types": "1.2.10" } }, "sha512-eilv6WFM3M0c9ztJt7/g80BDusK98z/FrFwseZgT4bXCq2vPhXD4z8R3oddmAn+R/Nmz9vBn4kweJKmGTZj+lg=="],
+
+    "@types/node": ["@types/node@22.13.9", "", { "dependencies": { "undici-types": "~6.20.0" } }, "sha512-acBjXdRJ3A6Pb3tqnw9HZmyR3Fiol3aGxRCK1x3d+6CDAMjl7I649wpSd+yNURCjbOUGu9tqtLKnTGxmK6CyGw=="],
+
+    "bun-types": ["bun-types@1.2.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-b5ITZMnVdf3m1gMvJHG+gIfeJHiQPJak0f7925Hxu6ZN5VKA8AGy4GZ4lM+Xkn6jtWxg5S3ldWvfmXdvnkp3GQ=="],
+
+    "typescript": ["typescript@5.8.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ=="],
+
+    "undici-types": ["undici-types@6.20.0", "", {}, "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg=="],
+  }
+}

package/functional_tests/README.md

@@ -0,0 +1,23 @@
+## Executable Functional Tests
+
+#### Setup
+
+Ensure the executable is built:
+
+    bun build ../index.ts --compile --outfile /tmp/example-host-application
+
+Install requirements:
+
+    pip3 install -r pip-requirements.txt
+
+#### Testing
+
+Run the functional tests:
+
+    export EXECUTABLE=/tmp/example-host-application
+    behave
+
+To run with logging output from the test steps (this is the best set of
+arguments I can find):
+
+    behave --no-logcapture --no-color --logging-level=DEBUG

package/functional_tests/features/environment.py

@@ -0,0 +1,9 @@
+import os
+
+from support.pexpect_wrapper import PExpectWrapper
+
+
+def before_scenario(context, scenario):
+
+    context.config.setup_logging()
+    context.pexpect_wrapper = PExpectWrapper(os.environ.get('EXECUTABLE'))

package/functional_tests/features/executable.feature

@@ -0,0 +1,7 @@
+Feature: Executable
+
+  Scenario: Executable success
+    When the executable is launched
+    Then the executable should complete successfully
+    And the executable should have output "Invoking extension"
+    And the executable should have output "hello world"

package/functional_tests/features/steps/executable.py

@@ -0,0 +1,18 @@
+from behave import when, then
+
+
+@when('the executable is launched')
+def step_impl(context):
+    context.pexpect_wrapper.start()
+
+
+@then('the executable should complete successfully')
+def step_impl(context):
+    context.pexpect_wrapper.expect_eof()
+    status = context.pexpect_wrapper.complete()
+    assert status == 0, 'unexpected exit status: {}'.format(status)
+
+
+@then('the executable should have output "{message}"')
+def step_impl(context, message):
+    context.pexpect_wrapper.expect(message)

package/functional_tests/features/support/pexpect_wrapper.py

@@ -0,0 +1,45 @@
+from pexpect.popen_spawn import PopenSpawn
+from pexpect import EOF
+import logging
+log = logging.getLogger("pexpect_wrapper")
+
+
+class PExpectWrapper:
+
+    def __init__(self, executable):
+        self.executable = executable
+        self.child = None
+        self.output = None
+
+    def start(self):
+        assert self.child is None
+
+        self.child = PopenSpawn(self.executable, encoding='utf-8')
+
+    def expect(self, message):
+        assert self.child is not None
+
+        found = ''
+        while len(self.output) > 0:
+            next_line = self.output.pop(0)
+            log.debug('looking for "{}" in "{}"'.format(message, next_line))
+            if message in next_line:
+                found = next_line
+                break
+
+        assert found != '', 'expected {} in output'.format(message)
+
+
+    def expect_eof(self):
+        assert self.child is not None
+
+        self.child.expect(EOF)
+
+    def complete(self):
+        assert self.child is not None
+
+        exit_status = self.child.wait()
+
+        self.output = self.child.before.split('\n')
+
+        return exit_status

package/functional_tests/pip-requirements.txt

@@ -0,0 +1,2 @@
+pexpect
+behave

package/index.ts

@@ -0,0 +1,3 @@
+import { exampleHostApplication } from "./src/ExampleHostApplication.ts";
+
+await exampleHostApplication();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@flowscripter/example-host-application",
+  "homepage": "https://github.com/flowscripter/example-host-application#readme",
+  "description": "Example host application for the https://github.com/flowscripter/dynamic-plugin-framework",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flowscripter/example-host-application.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "bun",
+    "example",
+    "plugin",
+    "framework",
+    "dynamic",
+    "import",
+    "executable",
+    "cli"
+  ],
+  "module": "index.ts",
+  "type": "module",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.10"
+  },
+  "peerDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@flowscripter/dynamic-plugin-framework": "^1.3.18",
+    "@flowscripter/example-plugin-api": "^1.0.8"
+  }
+}

package/script/install.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+
+set -e  # Exit on error
+
+# Define the download URL
+URL="https://github.com/flowscripter/example-host-application/releases/latest/download/example-host-application_Linux_x86_64.zip"
+
+# Create a temporary directory
+TMP_DIR=$(mktemp -d)
+cd "$TMP_DIR"
+
+# Download and extract
+echo "Downloading example-host-application..."
+curl -fsSL "$URL" -o executable.zip
+unzip executable.zip
+
+# Install
+chmod +x example-host-application
+sudo mv example-host-application /usr/local/bin/
+
+# Clean up
+cd -
+rm -rf "$TMP_DIR"
+
+echo "✅ Installation complete! Run 'example-host-application' to get started."

package/src/ExampleHostApplication.ts

@@ -0,0 +1,75 @@
+import {
+  EXTENSION_POINT_1,
+  type ExtensionPoint1,
+} from "@flowscripter/example-plugin-api";
+import {
+  DefaultPluginManager,
+  type ExtensionInfo,
+  UrlListPluginRepository,
+} from "@flowscripter/dynamic-plugin-framework";
+
+/**
+ * Searches for an extension, instantiates it and invokes it.
+ */
+export async function exampleHostApplication(): Promise<void> {
+  const pluginRepository = new UrlListPluginRepository(
+    new Set([
+      {
+        url: "https://unpkg.com/@flowscripter/example-plugin/dist/bundle.js",
+        extensionPoints: [EXTENSION_POINT_1],
+      },
+    ]),
+  );
+
+  const pluginManager = new DefaultPluginManager([pluginRepository]);
+
+  console.info(
+    `Registering extensions for ${EXTENSION_POINT_1} extension point`,
+  );
+
+  await pluginManager.registerExtensions(EXTENSION_POINT_1);
+
+  console.info("Registered extensions:");
+
+  const extensionInfos = await pluginManager.getRegisteredExtensions(
+    EXTENSION_POINT_1,
+  );
+
+  extensionInfos.forEach((extensionInfo: ExtensionInfo) => {
+    let extensionInfoString =
+      `extensionHandle: ${extensionInfo.extensionHandle}\n`;
+
+    if (extensionInfo.extensionData) {
+      extensionInfoString += `extensionData:\n`;
+      for (const entry of extensionInfo.extensionData.entries()) {
+        extensionInfoString += `\t${entry[0]} => ${entry[1]}\n`;
+      }
+    }
+    if (extensionInfo.pluginData) {
+      extensionInfoString += `pluginData:\n`;
+      for (const entry of extensionInfo.pluginData.entries()) {
+        extensionInfoString += `\t${entry[0]} => ${entry[1]}\n`;
+      }
+    }
+
+    console.info(extensionInfoString);
+  });
+
+  if (extensionInfos.length > 0) {
+    console.info("Instantiating first extension");
+
+    const extension = await pluginManager.instantiate(
+      extensionInfos[0].extensionHandle,
+      new Map([[
+        "host_foo",
+        "host_bar",
+      ]]),
+    ) as ExtensionPoint1;
+
+    console.info("Invoking extension");
+
+    extension.sayHello();
+  } else {
+    throw new Error("No extensions found");
+  }
+}

package/tests/hello_test.ts

@@ -0,0 +1,8 @@
+import { describe, test } from "bun:test";
+import { exampleHostApplication } from "../src/ExampleHostApplication.ts";
+
+describe("ExampleHostApplication Tests", () => {
+  test("Invoke example host application", async () => {
+    await exampleHostApplication();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    // Enable latest features
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}