ultravisor-beacon-capability 1.0.0

package/docs/api/build-action-map.md

@@ -0,0 +1,88 @@
+# buildActionMap
+
+Discovers action methods on a capability instance by walking its prototype chain. This is an internal function used by `UltravisorBeaconCapability.connect()`, but it is exported for testing and advanced use cases.
+
+## Import
+
+```javascript
+const { buildActionMap } = require('ultravisor-beacon-capability/source/Ultravisor-Beacon-Capability-ActionMap.cjs');
+```
+
+## Signature
+
+```javascript
+buildActionMap(pInstance) => object
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pInstance` | `object` | A capability instance to inspect |
+
+### Returns
+
+An object mapping action names to action definitions:
+
+```javascript
+{
+	'ActionName':
+	{
+		Description: 'Human-readable description',
+		SettingsSchema: [{ Name: 'Param', DataType: 'String', Required: true }],
+		Handler: function (pWorkItem, pContext, fCallback, fReportProgress) { ... }
+	}
+}
+```
+
+The `Handler` function uses the raw `ultravisor-beacon` signature (not the convention signature). It wraps the bound action method with Settings pre-extraction.
+
+## Example
+
+```javascript
+const libFable = require('fable');
+const libBeaconCapability = require('ultravisor-beacon-capability');
+const { buildActionMap } = require('ultravisor-beacon-capability/source/Ultravisor-Beacon-Capability-ActionMap.cjs');
+
+class MyCapability extends libBeaconCapability
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.capabilityName = 'Test';
+	}
+
+	get actionPing_Description() { return 'Respond with pong'; }
+	actionPing(pSettings, pWorkItem, fCallback)
+	{
+		return fCallback(null, { Outputs: { Response: 'pong' } });
+	}
+}
+
+let tmpFable = new libFable({});
+let tmpCap = new MyCapability(tmpFable, {}, 'test');
+let tmpMap = buildActionMap(tmpCap);
+
+console.log(Object.keys(tmpMap));
+// ['Ping']
+
+console.log(tmpMap.Ping.Description);
+// 'Respond with pong'
+```
+
+## Algorithm
+
+1. Get the first prototype of the instance
+2. While the prototype is not `Object.prototype`:
+   a. For each own property name on the prototype:
+      - Skip if already visited (subclass overrides win)
+      - Skip if not starting with `action` or too short
+      - Skip if ending with `_Schema` or `_Description`
+      - Skip if not a function (via `Object.getOwnPropertyDescriptor`)
+      - Strip `action` prefix to get the action name
+      - Resolve `_Schema` companion (getter, value, or method)
+      - Resolve `_Description` companion
+      - Create bound handler with Settings extraction wrapper
+      - Add to the action map
+   b. Move to the next prototype in the chain
+3. Return the action map

package/docs/api/connect.md

@@ -0,0 +1,81 @@
+# connect()
+
+Connect to an Ultravisor server, discover and register actions, and begin accepting work items.
+
+## Signature
+
+```javascript
+connect(pBeaconConfig, fCallback)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pBeaconConfig` | `object` | Connection configuration (see below) |
+| `fCallback` | `function` | `function(pError, pBeaconInfo)` -- called when connection completes or fails |
+
+### Configuration
+
+| Property | Type | Default | Required | Description |
+|----------|------|---------|----------|-------------|
+| `ServerURL` | `string` | -- | Yes | Ultravisor server URL (e.g. `http://localhost:54321`) |
+| `Name` | `string` | `capabilityName` | No | Beacon worker name for registration |
+| `Password` | `string` | `''` | No | Authentication password |
+| `MaxConcurrent` | `number` | `1` | No | Maximum number of work items to execute in parallel |
+| `StagingPath` | `string` | `process.cwd()` | No | Directory for file transfer staging |
+| `Tags` | `object` | `{}` | No | Metadata tags sent to the coordinator |
+| `BindAddresses` | `array` | `[]` | No | Network addresses to advertise for direct access |
+
+### Callback
+
+On success, `fCallback` receives `(null, pBeaconInfo)` where `pBeaconInfo` contains:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `BeaconID` | `string` | Unique identifier assigned by the server |
+
+On failure, `fCallback` receives `(pError)`.
+
+## Behavior
+
+1. Validates that `ServerURL` is present in the config
+2. Validates that `capabilityName` is set on the instance
+3. Discovers action methods via `buildActionMap()`
+4. Merges any explicitly registered actions (from `addAction()`)
+5. Builds a capability descriptor
+6. Registers the `UltravisorBeacon` service type with Fable (if not already registered)
+7. Instantiates a beacon service with the provided config
+8. Registers the capability descriptor with the beacon service
+9. Enables the beacon (authenticates, registers with server, begins polling)
+
+## Example
+
+```javascript
+tmpCapability.connect(
+	{
+		ServerURL: 'http://ultravisor.local:54321',
+		Name: 'my-worker',
+		Password: 'secret',
+		MaxConcurrent: 4,
+		Tags: { environment: 'production', host: require('os').hostname() }
+	},
+	(pError, pBeaconInfo) =>
+	{
+		if (pError)
+		{
+			console.error('Failed to connect:', pError.message);
+			return;
+		}
+		console.log('Beacon online:', pBeaconInfo.BeaconID);
+	});
+```
+
+## Error Cases
+
+| Error | Cause |
+|-------|-------|
+| `ServerURL is required` | `pBeaconConfig.ServerURL` is missing or falsy |
+| `capabilityName must be set` | `this.capabilityName` is empty |
+| Authentication failure | Server rejected credentials |
+| Network error | Server unreachable (beacon will auto-reconnect) |

package/docs/api/disconnect.md

@@ -0,0 +1,50 @@
+# disconnect()
+
+Disconnect from the Ultravisor server. Deregisters the beacon and cleans up the connection.
+
+## Signature
+
+```javascript
+disconnect(fCallback)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | `function` | `function(pError)` -- called when disconnection completes |
+
+## Behavior
+
+1. If not currently connected, calls `fCallback(null)` immediately
+2. Calls `disable()` on the underlying beacon service, which:
+   - Sends a deregistration message to the server
+   - Closes the WebSocket connection (if open)
+   - Stops HTTP polling (if active)
+   - Calls `onShutdown()` on the capability
+3. Clears the internal beacon service reference
+4. Calls `fCallback`
+
+## Example
+
+```javascript
+// Graceful shutdown on SIGTERM
+process.on('SIGTERM', () =>
+{
+	tmpCapability.disconnect((pError) =>
+	{
+		if (pError)
+		{
+			console.error('Disconnect error:', pError.message);
+		}
+		console.log('Beacon disconnected.');
+		process.exit(0);
+	});
+});
+```
+
+## Notes
+
+- Safe to call when not connected -- it is a no-op
+- Safe to call without a callback -- errors are silently ignored
+- After disconnecting, you can call `connect()` again to reconnect

package/docs/api/is-connected.md

@@ -0,0 +1,33 @@
+# isConnected()
+
+Check whether the beacon is currently connected to an Ultravisor server.
+
+## Signature
+
+```javascript
+isConnected() => boolean
+```
+
+### Returns
+
+`true` if the beacon service exists and is enabled; `false` otherwise.
+
+## Example
+
+```javascript
+if (tmpCapability.isConnected())
+{
+	console.log('Beacon is online and accepting work items');
+}
+else
+{
+	console.log('Beacon is offline');
+	tmpCapability.connect({ ServerURL: 'http://ultravisor:54321' }, (pError) => { });
+}
+```
+
+## Notes
+
+- Returns `false` before `connect()` is called
+- Returns `false` after `disconnect()` completes
+- During auto-reconnection (after a connection drop), the beacon service remains enabled internally, so this may return `true` even while reconnecting

package/docs/api/lifecycle-hooks.md

@@ -0,0 +1,115 @@
+# onInitialize / onShutdown
+
+Lifecycle hooks for resource management. Override these methods in your subclass to set up and tear down resources that your actions depend on.
+
+## onInitialize
+
+Called after the beacon connects to the Ultravisor server, before it begins accepting work items.
+
+### Signature
+
+```javascript
+onInitialize(fCallback)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | `function` | `function(pError)` -- call with `null` on success, or an error to abort |
+
+### Default
+
+No-op -- calls `fCallback(null)` immediately.
+
+### Example
+
+```javascript
+onInitialize(fCallback)
+{
+	// Create a database connection pool
+	this._Pool = require('mysql2').createPool({
+		host: this.fable.settings.DatabaseHost || 'localhost',
+		user: this.fable.settings.DatabaseUser || 'root',
+		database: this.fable.settings.DatabaseName || 'mydb'
+	});
+
+	// Verify the connection
+	this._Pool.query('SELECT 1', (pError) =>
+	{
+		if (pError)
+		{
+			this.log.error('Database connection failed:', pError.message);
+			return fCallback(pError);
+		}
+		this.log.info('Database connection pool ready');
+		return fCallback(null);
+	});
+}
+```
+
+## onShutdown
+
+Called when the beacon disconnects from the Ultravisor server.
+
+### Signature
+
+```javascript
+onShutdown(fCallback)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | `function` | `function(pError)` -- call with `null` on success |
+
+### Default
+
+No-op -- calls `fCallback(null)` immediately.
+
+### Example
+
+```javascript
+onShutdown(fCallback)
+{
+	if (this._Pool)
+	{
+		this._Pool.end((pError) =>
+		{
+			if (pError)
+			{
+				this.log.warn('Error closing database pool:', pError.message);
+			}
+			this.log.info('Database connection pool closed');
+			return fCallback(null);
+		});
+	}
+	else
+	{
+		return fCallback(null);
+	}
+}
+```
+
+## Lifecycle Sequence
+
+```
+connect() called
+  -> Beacon authenticates with Ultravisor server
+  -> Beacon registers capabilities
+  -> onInitialize() called
+  -> Beacon begins accepting work items
+  -> ... actions execute ...
+disconnect() called
+  -> Beacon stops accepting work items
+  -> onShutdown() called
+  -> Beacon deregisters from server
+  -> Connection closed
+```
+
+## Common Use Cases
+
+| Resource | onInitialize | onShutdown |
+|----------|-------------|------------|
+| Database connection pool | Create pool, test connection | Close pool |
+| HTTP client / API token | Fetch auth token, create client | Revoke token |
+| Temporary directory | Create staging directory | Remove directory |
+| File handle / stream | Open file | Close file |
+| External service handle | Connect to service | Disconnect |

package/docs/architecture.md

@@ -0,0 +1,237 @@
+# Architecture
+
+Ultravisor Beacon Capability is a thin convention layer on top of `ultravisor-beacon`. It discovers action methods on your subclass, builds the capability descriptor that `ultravisor-beacon` expects, and delegates all transport and execution to the underlying beacon service.
+
+## Class Hierarchy
+
+```mermaid
+graph TD
+    FSPB[fable-serviceproviderbase<br/><small>Fable service base class</small>]
+    UBC[UltravisorBeaconCapability<br/><small>Convention-based base class</small>]
+    YOUR[YourCapability<br/><small>Your subclass with action methods</small>]
+
+    AM[ActionMap<br/><small>Prototype chain walker</small>]
+    UBS[UltravisorBeaconService<br/><small>ultravisor-beacon</small>]
+
+    CM[CapabilityManager<br/><small>Descriptor store</small>]
+    BC[BeaconClient<br/><small>Transport + polling</small>]
+    PR[ProviderRegistry<br/><small>Provider index</small>]
+    CA[CapabilityAdapter<br/><small>Descriptor to provider bridge</small>]
+
+    FSPB -->|extends| UBC
+    UBC -->|extends| YOUR
+    UBC -->|uses| AM
+    UBC -->|composes| UBS
+
+    UBS --> CM
+    UBS --> BC
+    CM -->|buildProviderDescriptors| CA
+    CA -->|registerProvider| PR
+    BC --> PR
+
+    style UBC fill:#e1f5fe
+    style YOUR fill:#c8e6c9
+    style AM fill:#fff3e0
+```
+
+## Module Composition
+
+The capability base class composes three internal concerns:
+
+| Component | Source | Responsibility |
+|-----------|--------|----------------|
+| **ActionMap** | `Ultravisor-Beacon-Capability-ActionMap.cjs` | Discovers `action*` methods on the prototype chain; resolves companion `_Schema` and `_Description` properties; builds bound handlers |
+| **UltravisorBeaconCapability** | `Ultravisor-Beacon-Capability.cjs` | Base class; merges discovered and explicit actions; builds the capability descriptor; manages beacon lifecycle |
+| **UltravisorBeaconService** | `ultravisor-beacon` (external) | Handles authentication, transport negotiation, polling, heartbeat, work item execution |
+
+## Connect Flow
+
+When you call `connect()`, the following sequence executes:
+
+```mermaid
+sequenceDiagram
+    participant Dev as Your Code
+    participant Cap as BeaconCapability
+    participant AM as ActionMap
+    participant BS as BeaconService
+    participant UV as Ultravisor Server
+
+    Dev->>Cap: connect({ ServerURL, Name, ... })
+    Cap->>AM: buildActionMap(this)
+    AM-->>Cap: { ActionName: { Handler, Schema, Description } }
+    Cap->>Cap: Merge explicit actions (addAction)
+    Cap->>Cap: Build capability descriptor
+    Cap->>BS: new UltravisorBeaconService(config)
+    Cap->>BS: registerCapability(descriptor)
+    Cap->>BS: enable()
+    BS->>UV: POST /1.0/Authenticate
+    UV-->>BS: session cookie
+    BS->>UV: POST /Beacon/Register
+    UV-->>BS: { BeaconID }
+    UV->>UV: Create task types for each action
+    BS-->>Cap: callback(null, beaconInfo)
+    Cap-->>Dev: callback(null, beaconInfo)
+
+    Note over UV: Task types now available:<br/>beacon-{capability}-{action}
+```
+
+## Action Discovery
+
+The `buildActionMap()` function walks the prototype chain of your capability instance to find action methods:
+
+```mermaid
+flowchart TD
+    START([Start]) --> PROTO[Get prototype of instance]
+    PROTO --> CHECK{prototype !== Object.prototype?}
+    CHECK -->|No| DONE([Return action map])
+    CHECK -->|Yes| PROPS[Get own property names]
+    PROPS --> EACH{Next property name}
+    EACH -->|None left| NEXT[Get parent prototype]
+    NEXT --> CHECK
+
+    EACH -->|Has name| VISITED{Already visited?}
+    VISITED -->|Yes| EACH
+    VISITED -->|No| PREFIX{Starts with 'action'?}
+    PREFIX -->|No| EACH
+    PREFIX -->|Yes| SUFFIX{Ends with '_Schema' or '_Description'?}
+    SUFFIX -->|Yes| EACH
+    SUFFIX -->|No| FUNC{Is a function?}
+    FUNC -->|No| EACH
+    FUNC -->|Yes| EXTRACT[Strip 'action' prefix to get action name]
+    EXTRACT --> SCHEMA[Resolve companion _Schema]
+    SCHEMA --> DESC[Resolve companion _Description]
+    DESC --> HANDLER[Create bound handler with Settings extraction]
+    HANDLER --> ADD[Add to action map]
+    ADD --> EACH
+
+    style EXTRACT fill:#c8e6c9
+    style HANDLER fill:#c8e6c9
+```
+
+Key behaviors:
+- **Subclass wins** -- If a method name is seen on a derived class, the base class version is skipped
+- **Getters supported** -- `_Schema` and `_Description` companions can be ES class getters, plain properties, or methods
+- **Bound handlers** -- Each handler is bound to the instance, preserving `this` context for access to services, connections, and state
+
+## Handler Wrapping
+
+The convention-based handler signature differs from the raw `ultravisor-beacon` handler signature. The ActionMap creates a wrapper that bridges the two:
+
+```
+Convention (your code):
+  actionDoWork(pSettings, pWorkItem, fCallback, fReportProgress)
+
+Raw beacon (what ultravisor-beacon expects):
+  Handler(pWorkItem, pContext, fCallback, fReportProgress)
+
+Wrapper (created by ActionMap):
+  function(pWorkItem, pContext, fCallback, fReportProgress)
+  {
+      let tmpSettings = (pWorkItem && pWorkItem.Settings) ? pWorkItem.Settings : {};
+      return boundMethod(tmpSettings, pWorkItem, fCallback, fReportProgress);
+  }
+```
+
+The `pContext` parameter (containing `{ StagingPath }`) is not forwarded because it is unused in practice. If needed, it is available via `this.options.StagingPath` on the capability instance.
+
+## Capability Descriptor
+
+The base class produces a descriptor matching the shape documented in `ultravisor-beacon`'s `CapabilityManager`:
+
+```javascript
+{
+    Capability: 'YourCapabilityName',
+    Name: 'YourCapabilityNameProvider',
+    actions:
+    {
+        'ActionOne':
+        {
+            Description: 'What it does',
+            SettingsSchema: [{ Name: 'Param', DataType: 'String', Required: true }],
+            Handler: function (pWorkItem, pContext, fCallback, fReportProgress) { ... }
+        },
+        'ActionTwo': { ... }
+    },
+    initialize: function (fCallback) { /* delegates to onInitialize */ },
+    shutdown: function (fCallback) { /* delegates to onShutdown */ }
+}
+```
+
+The `initialize` and `shutdown` functions delegate to `onInitialize()` and `onShutdown()` on your subclass.
+
+## Server-Side Task Registration
+
+When the Ultravisor server receives the beacon registration, its coordinator automatically creates task types for each action:
+
+```mermaid
+graph LR
+    REG[Beacon registers<br/>Capability: DBMaint<br/>Actions: PurgeOld, Vacuum] --> COORD[Coordinator]
+    COORD --> T1[Task Type:<br/>beacon-dbmaint-purgeold]
+    COORD --> T2[Task Type:<br/>beacon-dbmaint-vacuum]
+
+    T1 --> UI[Ultravisor Dashboard]
+    T2 --> UI
+    T1 --> SCHED[Scheduler]
+    T2 --> SCHED
+    T1 --> GRAPH[Operation Graphs]
+    T2 --> GRAPH
+
+    style T1 fill:#e1f5fe
+    style T2 fill:#e1f5fe
+```
+
+Each task type includes:
+- **SettingsInputs** derived from the action's `SettingsSchema`
+- **EventInputs/Outputs** for graph wiring (Trigger, Complete, Error)
+- **StateOutputs** for capturing results (Result, StdOut)
+
+## Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Created: new YourCapability(fable, options)
+    Created --> Connecting: connect(config)
+    Connecting --> Initializing: onInitialize()
+    Initializing --> Connected: Beacon enabled
+    Connected --> Executing: Work item received
+    Executing --> Connected: Work item complete
+    Connected --> ShuttingDown: disconnect()
+    ShuttingDown --> Disconnected: onShutdown()
+    Disconnected --> [*]
+
+    Connected --> Reconnecting: Connection lost
+    Reconnecting --> Connected: Auto-reconnect
+
+    note right of Initializing
+        Override onInitialize() to set up
+        database connections, service handles,
+        or other resources your actions need
+    end note
+
+    note right of ShuttingDown
+        Override onShutdown() to close
+        connections and release resources
+    end note
+```
+
+## File Layout
+
+```
+ultravisor-beacon-capability/
+  package.json
+  README.md
+  source/
+    Ultravisor-Beacon-Capability.cjs          # Base class (main export)
+    Ultravisor-Beacon-Capability-ActionMap.cjs # Action discovery helper
+  test/
+    Ultravisor-Beacon-Capability_tests.js     # Mocha TDD tests
+  docs/
+    README.md                                  # Overview
+    _cover.md                                  # Landing page
+    _sidebar.md                                # Navigation
+    _topbar.md                                 # Top bar
+    quickstart.md                              # Step-by-step guide
+    architecture.md                            # This file
+    api/                                       # API reference
+    examples/                                  # Real-world examples
+```