pptb-standard-sample-tool 1.7.3 → 1.7.5

package/README.md

@@ -56,6 +56,7 @@ This compiles the TypeScript source in `src/` to JavaScript in `dist/`.
 
 ```
 html-sample/
+├── dotnet/              # C# worker tool and shared Core project
 ├── src/
 │   ├── app.ts           # Main application logic (TypeScript)
 │   ├── features/        # UI feature modules (terminal, filesystem, etc.)
@@ -170,6 +171,142 @@ const dataverse: typeof window.dataverseAPI = window.dataverseAPI;
 3. **Rebuild:** Run `npm run build`
 4. **Reload Tool:** In Power Platform Tool Box, close and reopen the tool
 
+## .NET Worker Test
+
+The **.NET Worker Test (Account Summary)** section is beside Query Records. The
+worker summarizes up to ten accounts by country. The TypeScript callback builds
+the FetchXML and calls Dataverse; the C# worker groups the returned rows and
+returns `{ totalAccounts, countries: [{ country, count }] }`. The direct account
+query remains independent and continues to use saved `demo.fetchxml`. Start,
+summarize, cancel and stop are explicit; worker status/output is separate.
+Loading the tool does not start .NET. The headless entry point is unchanged and
+never starts a worker.
+
+The complete C# sample is in `dotnet/Worker`; it has no separate Core project.
+Workers run as the current OS user and **are not sandboxed**. No tokens, secrets
+or credential environment variables are sent by this tool.
+
+Tool code uses PPTB's worker session API rather than implementing a JSON-RPC
+transport:
+
+```typescript
+const worker = await toolboxAPI.workers.connect("sample", {
+    requests: {
+        "dataverse/getAccounts": (params, context) => {
+            const top = typeof params === "object" && params !== null && "top" in params ? params.top : undefined;
+            if (typeof top !== "number" || !Number.isSafeInteger(top) || top < 1 || top > 100) throw new Error("Expected an account limit from 1 to 100");
+            if (context.isCancellationRequested) throw new Error("Cancelled");
+            const fetchXml = `<fetch top="${top}"><entity name="account"><attribute name="name" /><attribute name="address1_country" /></entity></fetch>`;
+            return dataverseAPI.fetchXmlQuery(fetchXml).then((result) => ({ value: result.value }));
+        },
+    },
+    notifications: {
+        progress: (message) => showStatus(String(message)),
+    },
+});
+
+await worker.ready;
+const result = await worker.request("accounts/summarizeByCountry", { top: 10 });
+await worker.stop();
+```
+
+PPTB owns JSON-RPC framing, readiness buffering, request correlation,
+cancellation, and transport disposal. Tool authors provide only the
+worker-initiated callbacks they need and call named worker methods.
+
+### Build And Pack
+
+Use the PR7 desktop development build, Node.js, and a compatible installed .NET
+10 SDK/runtime. This sample pins `@pptb/types@1.2.7-beta.6`, the current npm
+beta tag, for `workers.connect()`. The shrinkwrap locks that exact release;
+dependency changes use npm and the existing shrinkwrap workflow (`npm run finalize-package`).
+The beta still depends on `@pptb/validate@1.0.4`, which warns that `workers` is
+unrecognized. That validator result is not worker-declaration validation; the
+current desktop worker validator remains authoritative.
+
+From this `html-sample` directory:
+
+```sh
+npm install
+npm test
+npm run pack:worker
+```
+
+The pack command writes `PPTB.Sample.Query.Worker.0.1.6.nupkg` to `dotnet/feed/`.
+The exact declaration is `PPTB.Sample.Query.Worker@0.1.6`, command
+`pptb-sample-query-worker`, targeting `net10.0`. Inspect the `.nupkg`: it must
+contain `Worker.dll`, managed dependencies, runtime/dependency manifests and
+`DotnetToolSettings.xml`. Changing package bytes requires a fresh
+worker version and a matching `packageVersion` update in `pptb.config.json`. Do
+not overwrite a version with new bytes. `platforms: ["all"]` is the PPTB support
+matrix, not qualification evidence.
+
+### Load Local Tool
+
+From the desktop-app repo in PowerShell, point to this repo's generated feed in
+the main-process environment:
+
+```powershell
+$env:PPTB_DOTNET_LOCAL_NUGET_FEED = (Resolve-Path "../sample-tools/new/html-sample/dotnet/feed").Path
+pnpm run dev
+```
+
+On macOS/Linux shells:
+
+```sh
+PPTB_DOTNET_LOCAL_NUGET_FEED="$(cd ../sample-tools/new/html-sample/dotnet/feed && pwd -P)" pnpm run dev
+```
+
+First run `npm run pack:worker` in `html-sample`. The feed must already exist
+and be a flat directory containing only regular files, with no symlink path
+components, subdirectories, symlink files or hard-linked files. On other OSes,
+choose an absolute canonical directory satisfying the same rules. Set the
+environment variable before launching PPTB; restart the development app after
+changing it. The previously packed package is accessible at the canonical path
+without moving or repacking it.
+
+The feed requires both the Vite development bundle's main-only
+`PPTB_DEVELOPER_BUILD=1` marker and an unpackaged app. Production-mode unpackaged
+and packaged builds reject it. Never add the feed to the tool manifest or
+renderer. Registry, marketplace and npm-debug installs remain nuget.org-only;
+only the exact local worker package ID is mapped to this feed, and dependencies
+remain on nuget.org. Source path/package digest changes require fresh consent.
+
+1. Use **Load Local Tool** to load `sample-tools/new/html-sample` and select an
+   authenticated primary Dataverse connection.
+2. Start worker, review native-code consent, and wait for Worker ready.
+3. Select **Summarize Accounts by Country (Top 10)**. TypeScript sends
+   `accounts/summarizeByCountry({ top: 10 })`; C# calls the registered
+   `dataverse/getAccounts({ top: 10 })` callback. TypeScript builds the bounded
+   FetchXML and returns only account names and country values; C# groups those
+   rows and returns `{ totalAccounts, countries: [{ country, count }] }`.
+4. Cancel a pending query, then stop explicitly. Cancellation is cooperative;
+   the existing Dataverse API does not abort an in-flight HTTP request. No request
+   is automatically replayed. A failed stop disables start/query until cleanup
+   is verified; Stop worker remains available to retry.
+5. Also check consent denial/revocation, tool close and app quit.
+
+### Verification Boundaries
+
+`npm test` builds the browser bundle and runs simulated worker transport tests;
+it does not launch C#. There were no pre-existing automated sample test scripts;
+the interactive security suites remain available in the UI.
+
+For an opt-in **real packaged C# stdio** test, extract the `.nupkg` into a temporary
+directory, then run from `new/html-sample` with absolute paths:
+
+```sh
+node tests/dotnetWorker.smoke.mjs /usr/local/share/dotnet/dotnet \
+  /absolute/path/to/extracted/tools/net10.0/any/Worker.dll
+```
+
+This launches native code explicitly with a minimal credential-free environment.
+It checks initialize, account summary, reverse callbacks with fixture data, progress,
+cancellation and EOF exit. It does **not** test live Dataverse, local-feed restore,
+PPTB consent/broker, or other OS/architecture targets. The full Load Local Tool
+smoke remains a separate manual gate; do not infer PR7 completion from either
+simulated transport tests or this real-stdio fixture.
+
 ## Security Testing Guidance
 
 Use the built-in **Run Security Probe** button in the Terminal section to validate terminal exposure with safe commands only.

package/dist/app.js

@@ -1,4 +1,5 @@
 /// <reference types="@pptb/types" />
+import { createDotnetWorkerFeature } from "./features/dotnetWorker.js";
 import { createFileSystemFeature } from "./features/filesystem.js";
 import { createTerminalFeature } from "./features/terminal.js";
 import { createSecuritySuites } from "./security/suites.js";
@@ -27,6 +28,7 @@ let preventCloseActive = false;
 let securitySuites = null;
 let terminalFeature = null;
 let fileSystemFeature = null;
+let dotnetWorkerFeature = null;
 let inputEntityName = null;
 let fetchXmlFromLaunchContext = null;
 const powerPlatformNamespaces = [
@@ -71,6 +73,12 @@ async function initialize() {
             log,
             getCurrentConnection: () => currentConnection,
         });
+        dotnetWorkerFeature = createDotnetWorkerFeature({
+            toolbox,
+            dataverse,
+            getCurrentConnection: () => currentConnection,
+            log,
+        });
         // Initialize security suites (used by UI buttons)
         securitySuites = createSecuritySuites({
             toolbox,
@@ -310,6 +318,10 @@ function setupEventHandlers() {
     document.getElementById("query-accounts-secondary-btn")?.addEventListener("click", queryAccountsSecondary);
     document.getElementById("query-accounts-third-btn")?.addEventListener("click", queryAccountsThird);
     document.getElementById("query-contacts-querydata-btn")?.addEventListener("click", queryContactQueryData);
+    document.getElementById("worker-start-btn")?.addEventListener("click", () => dotnetWorkerFeature?.start());
+    document.getElementById("worker-query-btn")?.addEventListener("click", () => dotnetWorkerFeature?.query());
+    document.getElementById("worker-cancel-btn")?.addEventListener("click", () => dotnetWorkerFeature?.cancel());
+    document.getElementById("worker-stop-btn")?.addEventListener("click", () => dotnetWorkerFeature?.stop());
     // CRUD buttons
     document.getElementById("create-contact-btn")?.addEventListener("click", createContact);
     document.getElementById("update-contact-btn")?.addEventListener("click", updateContact);
@@ -547,9 +559,20 @@ function handleTerminalOutput(data) {
 function handleCommandCompleted(data) {
     requireTerminalFeature().handleCommandCompleted(data);
 }
-/**
- * Query accounts from Dataverse
- */
+async function getAccountFetchXml() {
+    const saved = await getSetting("demo.fetchxml");
+    return saved && saved.trim().length > 0
+        ? saved
+        : `<fetch top="10">
+    <entity name="account">
+        <attribute name="name" />
+        <attribute name="accountid" />
+        <attribute name="emailaddress1" />
+        <attribute name="telephone1" />
+        <order attribute="name" />
+    </entity>
+</fetch>`;
+}
 async function queryAccounts() {
     if (!currentConnection) {
         await showNotification("No Connection", "Please connect to a Dataverse environment", "warning");
@@ -559,21 +582,7 @@ async function queryAccounts() {
         const output = document.getElementById("query-output");
         if (output)
             output.textContent = "Querying accounts...\n";
-        // If user saved a FetchXML in settings, prefer that; otherwise use default
-        const saved = await getSetting("demo.fetchxml");
-        const fetchXml = saved && saved.trim().length > 0
-            ? saved
-            : `
-<fetch top="10">
-    <entity name="account">
-        <attribute name="name" />
-        <attribute name="accountid" />
-        <attribute name="emailaddress1" />
-        <attribute name="telephone1" />
-        <order attribute="name" />
-    </entity>
-</fetch>
-                `.trim();
+        const fetchXml = await getAccountFetchXml();
         const result = await dataverse.fetchXmlQuery(fetchXml);
         if (output) {
             output.textContent = `Found ${result.value.length} account(s):\n\n`;

package/dist/features/dotnetWorker.js

@@ -0,0 +1,142 @@
+// src/features/dotnetWorker.ts
+function createDotnetWorkerFeature(deps) {
+  const startButton = document.getElementById("worker-start-btn");
+  const runButton = document.getElementById("worker-query-btn");
+  const cancelButton = document.getElementById("worker-cancel-btn");
+  const stopButton = document.getElementById("worker-stop-btn");
+  const status = document.getElementById("worker-status");
+  const output = document.getElementById("worker-output");
+  let worker;
+  let queryRunning = false;
+  let cancelRequested = false;
+  let state = "stopped";
+  function render() {
+    startButton.disabled = state !== "stopped" || !deps.toolbox.workers;
+    runButton.disabled = state !== "ready" || queryRunning;
+    cancelButton.disabled = state !== "ready" || !queryRunning;
+    stopButton.disabled = !worker || state === "stopping";
+  }
+  function report(error, prefix) {
+    const message = `${prefix}: ${error instanceof Error ? error.message : String(error)}`;
+    status.textContent = message;
+    deps.log(message, "error");
+  }
+  function clearWorker() {
+    worker?.dispose();
+    worker = void 0;
+    state = "stopped";
+    render();
+  }
+  async function start() {
+    if (state !== "stopped") return;
+    state = "starting";
+    render();
+    status.textContent = "Requesting native-code consent and starting worker...";
+    output.textContent = "";
+    try {
+      const started = await deps.toolbox.workers.connect("sample", {
+        requests: {
+          "dataverse/getAccounts": async (params, context) => {
+            const top = typeof params === "object" && params !== null && "top" in params ? params.top : void 0;
+            if (typeof top !== "number" || !Number.isSafeInteger(top) || top < 1 || top > 100) throw new Error("Expected an account limit from 1 to 100");
+            if (!deps.getCurrentConnection()) throw new Error("No active Dataverse connection");
+            if (context.isCancellationRequested) throw new Error("Request cancelled");
+            const fetchXml = `<fetch top="${top}"><entity name="account"><attribute name="name" /><attribute name="address1_country" /></entity></fetch>`;
+            const result = await deps.dataverse.fetchXmlQuery(fetchXml);
+            if (context.isCancellationRequested) throw new Error("Request cancelled");
+            return { value: result.value };
+          }
+        },
+        notifications: {
+          progress: (message) => {
+            if (state === "ready" && typeof message === "string") status.textContent = message;
+          }
+        },
+        onExit: (snapshot) => {
+          clearWorker();
+          status.textContent = snapshot.failure ? `Worker exited: ${snapshot.failure}` : "Worker exited";
+        }
+      });
+      worker = started;
+      void started.ready.catch(() => void 0);
+      await started.ready;
+      if (worker !== started || state !== "starting") return;
+      state = "ready";
+      status.textContent = "Worker ready";
+      render();
+    } catch (error) {
+      if (worker) {
+        try {
+          await worker.stop();
+          clearWorker();
+        } catch (stopError) {
+          state = "blocked";
+          render();
+          report(stopError, "Startup failed; cleanup unverified. Retry Stop worker");
+          return;
+        }
+      }
+      clearWorker();
+      report(error, "Worker startup failed");
+    }
+  }
+  async function query() {
+    if (state !== "ready" || !worker || queryRunning) return;
+    const activeWorker = worker;
+    queryRunning = true;
+    cancelRequested = false;
+    render();
+    output.textContent = "";
+    status.textContent = "Preparing account summary in worker...";
+    try {
+      if (!deps.getCurrentConnection()) throw new Error("No active Dataverse connection");
+      if (worker !== activeWorker || state !== "ready") return;
+      const result = await activeWorker.request("accounts/summarizeByCountry", { top: 10 });
+      if (worker !== activeWorker || state !== "ready") return;
+      if (cancelRequested) status.textContent = "Query cancelled";
+      else {
+        output.textContent = JSON.stringify(result, null, 2);
+        status.textContent = "Worker query completed";
+      }
+    } catch (error) {
+      if (worker === activeWorker && state === "ready") {
+        if (cancelRequested) status.textContent = "Query cancelled";
+        else report(error, "Worker query failed");
+      }
+    } finally {
+      queryRunning = false;
+      render();
+    }
+  }
+  function cancel() {
+    if (!worker || state !== "ready" || !queryRunning) return;
+    cancelRequested = true;
+    worker.cancel();
+    status.textContent = "Cancellation requested; an in-flight Dataverse call may still finish";
+    cancelButton.disabled = true;
+  }
+  async function stop() {
+    if (!worker || state === "stopping") return;
+    const stoppingWorker = worker;
+    state = "stopping";
+    stoppingWorker.cancel();
+    render();
+    status.textContent = "Stopping worker...";
+    try {
+      await stoppingWorker.stop();
+      if (worker === stoppingWorker) clearWorker();
+      status.textContent = "Worker stopped";
+    } catch (error) {
+      if (worker !== stoppingWorker) return;
+      state = "blocked";
+      render();
+      report(error, "Worker cleanup unverified. Retry Stop worker");
+    }
+  }
+  render();
+  if (!deps.toolbox.workers) status.textContent = "Worker API unavailable in this PPTB build";
+  return { start, query, cancel, stop };
+}
+export {
+  createDotnetWorkerFeature
+};

package/dist/features/workerRpcAdapter.js

@@ -0,0 +1,194 @@
+import { AbstractMessageReader, AbstractMessageWriter, CancellationTokenSource, createMessageConnection, Disposable, ResponseError } from "vscode-jsonrpc/browser";
+class WorkerMessageReader extends AbstractMessageReader {
+    maxQueuedMessages;
+    maxQueuedBytes;
+    callback;
+    queued = [];
+    queuedBytes = 0;
+    failed = false;
+    failure;
+    released = false;
+    constructor(maxQueuedMessages, maxQueuedBytes) {
+        super();
+        this.maxQueuedMessages = maxQueuedMessages;
+        this.maxQueuedBytes = maxQueuedBytes;
+    }
+    listen(callback) {
+        if (this.callback)
+            throw new Error("Worker RPC reader is already listening");
+        this.callback = callback;
+        return Disposable.create(() => {
+            this.callback = undefined;
+        });
+    }
+    flush() {
+        if (!this.callback)
+            return;
+        this.released = true;
+        for (const message of this.queued.splice(0))
+            this.callback(message);
+        this.queuedBytes = 0;
+        if (this.failure) {
+            this.fireError(this.failure);
+            this.fireClose();
+        }
+    }
+    accept(message) {
+        if (this.callback && this.released) {
+            this.callback(message);
+            return;
+        }
+        if (this.failed)
+            return;
+        let bytes;
+        try {
+            bytes = new TextEncoder().encode(JSON.stringify(message)).byteLength;
+        }
+        catch (error) {
+            this.failed = true;
+            this.failure = error instanceof Error ? error : new Error(String(error));
+            return;
+        }
+        if (this.queued.length >= this.maxQueuedMessages || this.queuedBytes + bytes > this.maxQueuedBytes) {
+            this.failed = true;
+            this.queued.length = 0;
+            this.queuedBytes = 0;
+            this.failure = new Error("Worker RPC startup message buffer limit exceeded");
+            return;
+        }
+        this.queued.push(message);
+        this.queuedBytes += bytes;
+    }
+    close() {
+        this.fireClose();
+    }
+    dispose() {
+        this.queued.length = 0;
+        this.queuedBytes = 0;
+        super.dispose();
+    }
+}
+class WorkerMessageWriter extends AbstractMessageWriter {
+    transport;
+    constructor(transport) {
+        super();
+        this.transport = transport;
+    }
+    async write(message) {
+        try {
+            await this.transport.send(message);
+        }
+        catch (error) {
+            this.fireError(error, message);
+            throw error;
+        }
+    }
+    end() {
+        this.fireClose();
+    }
+}
+export function createWorkerRpcClient(transport) {
+    const reader = new WorkerMessageReader(64, 4 * 1024 * 1024);
+    const writer = new WorkerMessageWriter(transport);
+    const connection = createMessageConnection(reader, writer);
+    connection.listen();
+    let disposed = false;
+    let unsubscribeMessage = () => undefined;
+    let unsubscribeExit = () => undefined;
+    const close = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        unsubscribeMessage();
+        unsubscribeExit();
+        reader.close();
+        writer.end();
+        connection.dispose();
+    };
+    unsubscribeMessage = transport.onMessage((message) => {
+        if (!disposed)
+            reader.accept(message);
+    });
+    unsubscribeExit = transport.onExit(close);
+    let listening = false;
+    return {
+        connection,
+        listen: () => {
+            if (disposed)
+                throw new Error("Worker RPC client is disposed");
+            if (listening)
+                return;
+            listening = true;
+            reader.flush();
+        },
+        dispose: close,
+    };
+}
+export async function startWorkerSession(options) {
+    const workers = options.toolbox.workers;
+    if (!workers)
+        throw new Error("This PPTB build does not expose the worker API");
+    const started = await workers.start(options.workerId);
+    const rpc = createWorkerRpcClient({
+        send: (message) => workers.send(started.handle, message),
+        onMessage: (listener) => workers.onMessage(started.handle, listener),
+        onExit: (listener) => workers.onExit(started.handle, listener),
+    });
+    let currentQuery;
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        currentQuery?.cancel();
+        currentQuery?.dispose();
+        currentQuery = undefined;
+        unsubscribeExit();
+        rpc.dispose();
+    };
+    rpc.connection.onRequest("dataverse/fetchXml", async (fetchXml, token) => {
+        if (typeof fetchXml !== "string" || !fetchXml.trim())
+            throw new ResponseError(-32602, "Expected FetchXML text");
+        const result = await options.fetchXmlQuery(fetchXml, token);
+        if (token.isCancellationRequested)
+            throw new ResponseError(-32800, "Request cancelled");
+        return JSON.parse(JSON.stringify({ value: result.value }));
+    });
+    rpc.connection.onNotification("progress", (message) => {
+        if (typeof message === "string")
+            options.onProgress?.(message);
+    });
+    const unsubscribeExit = workers.onExit(started.handle, (snapshot) => {
+        dispose();
+        options.onExit?.(snapshot);
+    });
+    rpc.listen();
+    return {
+        ready: started.ready,
+        query: async (fetchXml) => {
+            if (disposed)
+                throw new Error("Worker session has ended");
+            if (currentQuery)
+                throw new Error("A worker query is already running");
+            const query = new CancellationTokenSource();
+            currentQuery = query;
+            try {
+                return await rpc.connection.sendRequest("query", fetchXml, query.token);
+            }
+            finally {
+                query.dispose();
+                if (currentQuery === query)
+                    currentQuery = undefined;
+            }
+        },
+        cancel: () => currentQuery?.cancel(),
+        stop: async () => {
+            if (disposed)
+                return;
+            currentQuery?.cancel();
+            await workers.stop(started.handle);
+            dispose();
+        },
+        dispose,
+    };
+}

package/dist/index.html

@@ -161,6 +161,19 @@
                     <div id="query-output-third" class="output"></div>
                 </div>
 
+                <div class="example-group">
+                    <h3>.NET Worker Test (Account Summary)</h3>
+                    <p class="info-box warning">Native code runs as your OS user and is not sandboxed. The worker groups account rows by country.</p>
+                    <div class="button-group">
+                        <button id="worker-start-btn" class="btn">Start worker</button>
+                        <button id="worker-query-btn" class="btn btn-primary" disabled>Summarize Accounts by Country (Top 10)</button>
+                        <button id="worker-cancel-btn" class="btn btn-warning" disabled>Cancel summary</button>
+                        <button id="worker-stop-btn" class="btn btn-error" disabled>Stop worker</button>
+                    </div>
+                    <div id="worker-status" role="status" aria-live="polite">Worker stopped</div>
+                    <div id="worker-output" class="output"></div>
+                </div>
+
                 <div class="example-group">
                     <h3>CRUD Operations</h3>
                     <div class="input-group">