@pptb/types 1.2.2 → 1.2.3-beta.0

package/README.md

@@ -119,6 +119,7 @@ In addition to `package.json`, the validator automatically checks a `pptb.config
 | Field                                   | Required | Rules                                                                                                                     |
 | --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
 | `invocation.version`                    | ✅\*\*   | Must be a valid **semantic version** string (e.g. `"1.0.0"`). Tool developers own this version and bump it when the invocation contract changes. |
+| `invocation.capabilities`               | ❌       | Array of non-empty string tags (e.g. `["entity-picker"]`). Used by callers to discover this tool via `findToolsByCapability`. |
 | `invocation.prefill`                    | ❌       | JSON-schema-style object describing data callers can pre-populate                                                         |
 | `invocation.prefill.properties`         | ❌       | Map of property names to `{ type?, enum?, items? }` descriptors                                                           |
 | `invocation.returnTopic`                | ❌       | JSON-schema-style object describing the data this tool returns to its caller                                              |
@@ -132,6 +133,7 @@ In addition to `package.json`, the validator automatically checks a `pptb.config
 {
     "invocation": {
         "version": "1.0.0",
+        "capabilities": ["entity-picker"],
         "prefill": {
             "properties": {
                 "entityName": { "type": "string" },
@@ -255,8 +257,8 @@ const terminal = await toolboxAPI.terminal.create({
     cwd: "/path/to/directory",
 });
 
-// Execute a command
-const result = await toolboxAPI.terminal.execute(terminal.id, "npm install");
+// Execute a command (most commands are allowed; shells and privilege-escalation tools are blocked)
+const result = await toolboxAPI.terminal.execute(terminal.id, "pac auth list");
 console.log("Exit code:", result.exitCode);
 console.log("Output:", result.output);
 
@@ -296,13 +298,29 @@ Tools can launch one another and pass data between them using the `invocation` n
 
 ```typescript
 // Tool A – launches the entity-picker tool and waits for a selection
+// The callee automatically inherits this tool's FXS connection
 const result = await toolboxAPI.invocation.launchTool(
     "@my-org/entity-picker",
     { entityName: "account", allowMultiSelect: false },
 );
 
-if (result) {
+if (result !== null) {
     console.log("Selected record id:", (result as { selectedId: string }).selectedId);
+} else {
+    // User dismissed the picker (closed window or clicked "Return to Caller" banner)
+}
+```
+
+> **One-at-a-time**: only one active callee per caller is supported. A second `launchTool` call while a callee is open throws `"A callee invocation is already in progress"`.
+
+#### Caller: tag-based capability discovery
+
+```typescript
+// Find all installed tools that declare the "entity-picker" capability
+const pickers = await toolboxAPI.invocation.findToolsByCapability("entity-picker");
+if (pickers.length > 0) {
+    const picker = pickers[0] as { id: string };
+    const result = await toolboxAPI.invocation.launchTool(picker.id, { entityName: "account" });
 }
 ```
 
@@ -317,12 +335,17 @@ if (ctx) {
 
     // When the user makes their selection:
     await toolboxAPI.invocation.returnData({ selectedId: "a1b2c3...", selectedName: "Contoso" });
+    // PPTB automatically closes this window after delivering the result
 }
 ```
 
 > **Tip:** A tool that was *not* launched by another tool receives `null` from `getLaunchContext()`.  
 > Use this to show a standalone UI or redirect accordingly.
 
+> **Auto-close**: after calling `returnData`, PPTB automatically closes the callee window. The callee does **not** need to close itself.
+
+> **Banner early-return**: PPTB injects a "Return to [CallerToolName]" banner in the callee window. If the user clicks it before `returnData` is called, the caller's Promise resolves with `null` and the callee window is closed.
+
 #### Declaring your invocation contract
 
 Add a `pptb.config.json` alongside your `package.json` to tell callers what data you expect and return:
@@ -331,6 +354,7 @@ Add a `pptb.config.json` alongside your `package.json` to tell callers what data
 {
     "invocation": {
         "version": "1.0.0",
+        "capabilities": ["entity-picker"],
         "prefill": {
             "properties": {
                 "entityName": { "type": "string" },
@@ -557,9 +581,13 @@ Core platform features organized into namespaces:
 
 - **create(options: TerminalOptions)**: Promise<Terminal>
     - Creates a new terminal attached to the tool (tool ID is auto-determined)
+    - Uses the preferred shell specified via `TerminalOptions.shell` if it is installed on the machine, otherwise falls back to the system default shell
 
 - **execute(terminalId: string, command: string)**: Promise<TerminalCommandResult>
     - Executes a command in the specified terminal and returns its result
+    - Only commands that are **not** on the blocked list are executed; blocked commands are shell interpreters (`bash`, `sh`, `powershell`, `cmd`, etc.) and privilege-escalation tools (`sudo`, `su`, `runas`, etc.)
+    - `npx --shell/-c` flags are blocked to prevent shell pivot via npx; unquoted command substitution (`$(…)` and backticks) is also rejected
+    - Compound commands using `&&`, `||`, `;`, or `|` are supported — each segment is individually validated against the blocklist
 
 - **close(terminalId: string)**: Promise<void>
     - Closes the specified terminal
@@ -602,12 +630,17 @@ Core platform features organized into namespaces:
     - Returns the prefill data passed by the tool that launched this tool, or `null` when not launched via inter-tool invocation
 
 - **returnData(returnData: Record\<string, unknown\>)**: Promise\<void\>
-    - Sends data back to the caller tool and signals completion; no-op if not launched by another tool
+    - Sends data back to the caller tool and signals completion; PPTB **automatically closes the callee window** after delivery; no-op if not launched by another tool
 
 - **launchTool(targetToolId, prefillData?, options?)**: Promise\<unknown\>
     - Launches the specified tool, optionally with prefill data
-    - Returns a Promise that resolves with the data returned by the callee (or `null` if it closes without returning)
-    - `options.primaryConnectionId` / `options.secondaryConnectionId` – override connection for the callee
+    - Returns a Promise that resolves with the data returned by the callee, or `null` if it closes without returning or the user clicks the "Return to Caller" banner
+    - The callee automatically inherits the caller's FXS connection; pass `options.primaryConnectionId` to override
+    - Only one active callee per caller is allowed; throws `"A callee invocation is already in progress"` if a callee is already open
+    - Pass `options.noReturn: true` for one-way "Send To" flows; the banner is suppressed entirely for the callee
+
+- **findToolsByCapability(tag: string)**: Promise\<unknown[]\>
+    - Returns all installed tools that declare the given capability tag in their `pptb.config.json`
 
 ### Dataverse API (`window.dataverseAPI`)
 

package/bin/pptb-validate.js

@@ -16,7 +16,7 @@
 
 const fs = require("fs");
 const path = require("path");
-const { validatePackageJson, validatePPTBConfig } = require("../lib/validate");
+const { validatePackageJson, validatePPTBConfig, KNOWN_CAPABILITY_TAGS } = require("../lib/validate");
 
 // ANSI colour helpers – gracefully degrade when colours are unsupported
 const NO_COLOR = !process.stdout.isTTY || process.env.NO_COLOR;
@@ -219,9 +219,15 @@ async function main() {
             console.log(`  Features    : multiConnection=${info.features.multiConnection}${info.features.minAPI ? `, minAPI=${info.features.minAPI}` : ""}`);
         }
         if (configResult !== null && configResult.packageInfo && configResult.packageInfo.invocation) {
-            console.log(`  Invocation  : version=${configResult.packageInfo.invocation.version}`);
+            const inv = configResult.packageInfo.invocation;
+            console.log(`  Invocation  : version=${inv.version}`);
+            if (Array.isArray(inv.capabilities) && inv.capabilities.length > 0) {
+                console.log(`  Capabilities: ${inv.capabilities.join(", ")}`);
+            }
         }
         console.log();
+        console.log(c.dim(`Known capability tags: ${KNOWN_CAPABILITY_TAGS.join(", ")}`));
+        console.log();
     } else {
         console.log(c.red(c.bold("✖ Validation failed")));
         console.log();

package/lib/validate.js

@@ -55,6 +55,30 @@ const VALID_MULTI_CONNECTION_VALUES = ["required", "optional", "none"];
 // Semver regex for minAPI validation
 const SEMVER_REGEX = /^\d+\.\d+\.\d+(-[0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*)?(\+[0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*)?$/;
 
+/**
+ * Built-in list of well-known capability tags.
+ * Mirrors the entries in the Supabase `capability_tags` table.
+ * New tags are added to Supabase first (configurable without a deploy) and are
+ * then reflected here in the next package release so offline validation stays current.
+ *
+ * When a tool declares a tag that is not in this list the validator emits a warning
+ * (not an error) so existing tools are not broken by registry updates.
+ *
+ * **Keep in sync with `BUILT_IN_CAPABILITY_TAGS` in
+ * `src/main/managers/toolRegistryManager.ts`.**  Because this file is a standalone
+ * Node.js module that cannot import from the Electron/TypeScript source tree, both
+ * lists must be updated together whenever a new tag is added.
+ */
+const KNOWN_CAPABILITY_TAGS = [
+    "fetchxml",
+    "entity-picker",
+    "record-selector",
+    "solution-selector",
+    "webresource-editor",
+    "plugin-inspector",
+    "pcf-control-builder",
+];
+
 /**
  * Checks if a string is a valid URL.
  * @param {string} url
@@ -334,7 +358,7 @@ async function validatePackageJson(packageJson, options = {}) {
     };
 }
 
-module.exports = { validatePackageJson, validatePPTBConfig, isValidUrl, APPROVED_LICENSES };
+module.exports = { validatePackageJson, validatePPTBConfig, isValidUrl, APPROVED_LICENSES, KNOWN_CAPABILITY_TAGS };
 
 /**
  * Validates a tool's pptb.config.json against the official review criteria.
@@ -390,6 +414,25 @@ function validatePPTBConfig(config) {
                     validateJsonSchemaProperties("invocation.returnTopic", inv.returnTopic.properties, errors);
                 }
             }
+
+            // invocation.capabilities – optional array of non-empty strings
+            if (inv.capabilities !== undefined) {
+                if (!Array.isArray(inv.capabilities)) {
+                    errors.push("invocation.capabilities must be an array");
+                } else {
+                    inv.capabilities.forEach((cap, idx) => {
+                        if (typeof cap !== "string" || cap.trim().length === 0) {
+                            errors.push(`invocation.capabilities[${idx}] must be a non-empty string`);
+                        } else if (!KNOWN_CAPABILITY_TAGS.includes(cap.trim())) {
+                            warnings.push(
+                                `invocation.capabilities[${idx}] "${cap}" is not a recognised capability tag. ` +
+                                    `Known tags: ${KNOWN_CAPABILITY_TAGS.join(", ")}. ` +
+                                    "If this is a new tag, ensure it has been added to the capability registry.",
+                            );
+                        }
+                    });
+                }
+            }
         }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pptb/types",
-  "version": "1.2.2",
+  "version": "1.2.3-beta.0",
   "description": "Type definitions for Power Platform ToolBox APIs and validity checks for tool packages",
   "main": "index.d.ts",
   "types": "index.d.ts",

package/pptbConfig.d.ts

@@ -11,6 +11,7 @@
  * {
  *   "invocation": {
  *     "version": "1.0.0",
+ *     "capabilities": ["fetchxml"],
  *     "prefill": {
  *       "properties": {
  *         "entityName": { "type": "string" },
@@ -29,6 +30,50 @@
  * ```
  */
 
+/**
+ * Well-known capability tags defined in the Power Platform ToolBox capability registry.
+ *
+ * Using one of these values provides IDE auto-complete and ensures compatibility with the
+ * official capability discovery system (`toolboxAPI.invocation.findToolsByCapability`).
+ * The authoritative list is maintained in the Supabase `capability_tags` table so new
+ * tags can be added without an app update. Fetch the current list at runtime via
+ * `toolboxAPI.invocation.getKnownCapabilityTags()`.
+ *
+ * | Tag                  | Description                                           |
+ * | -------------------- | ----------------------------------------------------- |
+ * | `fetchxml`           | Accept or process FetchXML queries                    |
+ * | `entity-picker`      | Browse and select a Dataverse entity (table)          |
+ * | `record-selector`    | Browse and select a Dataverse record                  |
+ * | `solution-selector`  | Pick a Power Platform solution                        |
+ * | `webresource-editor` | Edit or manage web resources                          |
+ * | `plugin-inspector`   | Inspect or manage plugins and assemblies              |
+ * | `pcf-control-builder`| Build or scaffold PCF controls                        |
+ */
+export type KnownCapabilityTag =
+    | "fetchxml"
+    | "entity-picker"
+    | "record-selector"
+    | "solution-selector"
+    | "webresource-editor"
+    | "plugin-inspector"
+    | "pcf-control-builder";
+
+/**
+ * A capability tag string accepted by `invocation.capabilities` and
+ * `toolboxAPI.invocation.findToolsByCapability()`.
+ *
+ * `KnownCapabilityTag` values offer IDE auto-complete and are validated by
+ * `pptb-validate`. Custom strings are permitted for organisation-internal tags,
+ * but will produce a validation warning unless the tag appears in the official
+ * capability registry.
+ *
+ * @example
+ * ```json
+ * { "invocation": { "version": "1.0.0", "capabilities": ["fetchxml", "entity-picker"] } }
+ * ```
+ */
+export type CapabilityTag = KnownCapabilityTag | (string & {});
+
 /** A JSON-schema-style property descriptor used inside invocation definitions. */
 export interface JsonSchemaProperty {
     /** The JSON type of the value (e.g. "string", "number", "boolean", "object", "array"). */
@@ -67,6 +112,24 @@ export interface InvocationConfig {
     prefill?: JsonSchemaObject;
     /** Schema of the data this tool returns to its caller on completion. */
     returnTopic?: JsonSchemaObject;
+    /**
+     * Capability tags declared by this tool.
+     *
+     * Callers use `toolboxAPI.invocation.findToolsByCapability(tag)` to discover tools
+     * that advertise a given capability. Prefer `KnownCapabilityTag` values for IDE
+     * auto-complete; custom strings are accepted but will produce a `pptb-validate`
+     * warning unless the tag is present in the official capability registry.
+     *
+     * Use `toolboxAPI.invocation.getKnownCapabilityTags()` at runtime to retrieve the
+     * full list from the registry (backed by a configurable Supabase table so new tags
+     * can be added without an app update).
+     *
+     * @example
+     * ```json
+     * { "invocation": { "version": "1.0.0", "capabilities": ["entity-picker", "fetchxml"] } }
+     * ```
+     */
+    capabilities?: CapabilityTag[];
 }
 
 /**

package/toolboxAPI.d.ts

@@ -82,7 +82,10 @@ declare namespace ToolBoxAPI {
         name: string;
         url: string;
         environment: "Dev" | "Test" | "UAT" | "Production";
-        createdAt: string;
+        category?: string;
+        environmentColor?: string;
+        categoryColor?: string;
+        createdAt?: string;
         lastUsedAt?: string;
         /**
          * @deprecated isActive is a legacy field that is no longer persisted.
@@ -109,9 +112,9 @@ declare namespace ToolBoxAPI {
      */
     export interface TerminalOptions {
         name: string;
-        shell?: string;
+        shell?: string; // Preferred shell executable (e.g. "pwsh", "/bin/zsh"). Falls back to the system default if the requested shell is not found on the machine.
         cwd?: string;
-        env?: Record<string, string>;
+        env?: Record<string, string>; // PATH-like and shell bootstrap variables are filtered for tool security
         visible?: boolean; // Whether terminal should be visible initially (default: true)
     }
 
@@ -455,9 +458,9 @@ declare namespace ToolBoxAPI {
          * Returns data back to the caller tool that launched this tool.
          *
          * The value resolves the `Promise` returned by the caller's
-         * `invocation.launchTool()` call.  After calling `returnData`, the PPTB host
-         * will notify the caller; it is the callee's responsibility to close itself (or
-         * update its UI) after the return.
+         * `invocation.launchTool()` call.  **After calling `returnData`, PPTB
+         * automatically closes the callee window** — the callee does not need to
+         * close itself.
          *
          * If this tool was not launched by another tool, the call is a no-op.
          *
@@ -469,17 +472,62 @@ declare namespace ToolBoxAPI {
          * Launch another tool from within this tool and (optionally) pass prefill data.
          *
          * Returns a Promise that resolves with the data the target tool sends via
-         * `invocation.returnData()`, or `null` if the target tool closes without
-         * returning any data.
+         * `invocation.returnData()`, or `null` if:
+         *  - the target tool closes without calling `returnData`, or
+         *  - the user clicks the "Return to [this tool]" banner before the callee finalises.
+         *
+         * **One-at-a-time**: only one active callee per caller is supported. A second
+         * call while a callee is active throws `"A callee invocation is already in progress"`.
+         *
+         * **Connection auto-inheritance**: when `options.primaryConnectionId` is omitted,
+         * the callee automatically inherits the caller's active FXS connection.
+         *
+         * **Multi-connection auto-prompt**: when the callee declares
+         * `features.multiConnection: "required"` or `"optional"` and
+         * `options.secondaryConnectionId` is not provided, PPTB automatically shows
+         * the multi-connection selector before launching the callee. The Promise rejects
+         * if the user cancels the selector.
          *
-         * The target tool must be installed and its `pptb.config.json` must declare an
-         * `invocation.prefill` schema that matches the shape of `prefillData`.
+         * **`noReturn`**: pass `true` when the caller does not expect the callee to
+         * return data (e.g. a "Send To" pattern where data is only sent one-way).
+         * When set, the "Return to [Caller]" banner is suppressed entirely for the callee.
+         * The invocation lifecycle is otherwise identical — the Promise still resolves
+         * with `null` when the callee closes.
          *
          * @param targetToolId The npm package name (toolId) of the tool to launch
          * @param prefillData  Data to pre-populate the target tool's state
-         * @param options      Optional connection overrides for the target tool
+         * @param options      Optional connection overrides and launch flags
+         */
+        launchTool: (targetToolId: string, prefillData?: Record<string, unknown>, options?: { primaryConnectionId?: string | null; secondaryConnectionId?: string | null; noReturn?: boolean }) => Promise<unknown>;
+
+        /**
+         * Find installed tools that declare a given capability tag in their
+         * `pptb.config.json` (`invocation.capabilities` array).
+         *
+         * Use a `KnownCapabilityTag` literal from `@pptb/types` for IDE auto-complete:
+         * ```ts
+         * import type { KnownCapabilityTag } from "@pptb/types/pptbConfig";
+         * const tools = await toolboxAPI.invocation.findToolsByCapability("fetchxml");
+         * ```
+         *
+         * @param tag  The capability tag to search for (e.g. `"entity-picker"`)
+         * @returns    Array of matching installed `ToolManifest` objects
+         */
+        findToolsByCapability: (tag: import("./pptbConfig").CapabilityTag) => Promise<unknown[]>;
+
+        /**
+         * Returns the list of known (registered) capability tags from the capability registry.
+         *
+         * The registry is stored in a Supabase `capability_tags` table and fetched at
+         * startup (cached for 5 minutes). When Supabase is unavailable a built-in
+         * fallback list is returned, so the result is never empty.
+         *
+         * Use this at runtime to populate a "capabilities" picker or to validate a tag
+         * before calling `findToolsByCapability`.
+         *
+         * @returns Array of `{ tag: string; description: string }` entries ordered by tag name.
          */
-        launchTool: (targetToolId: string, prefillData?: Record<string, unknown>, options?: { primaryConnectionId?: string | null; secondaryConnectionId?: string | null }) => Promise<unknown>;
+        getKnownCapabilityTags: () => Promise<Array<{ tag: string; description: string }>>;
     }
 
     /**