@pptb/types 1.0.20 → 1.1.3-beta.1

package/README.md

@@ -1,10 +1,14 @@
 # @pptb/types
 
-TypeScript type definitions for Power Platform ToolBox APIs.
+TypeScript type definitions for Power Platform ToolBox APIs, plus a built-in CLI validator that checks your tool's `package.json` against the official review criteria before you publish to npm.
 
 - [@pptb/types](#pptbtypes)
     - [Installation](#installation)
     - [Overview](#overview)
+    - [Tool Validation](#tool-validation)
+        - [Quick start](#quick-start)
+        - [CLI options](#cli-options)
+        - [What is validated](#what-is-validated)
     - [Usage](#usage)
         - [Include all type definitions](#include-all-type-definitions)
         - [Include specific API types](#include-specific-api-types)
@@ -18,6 +22,7 @@ TypeScript type definitions for Power Platform ToolBox APIs.
         - [FetchXML Queries](#fetchxml-queries)
         - [Metadata Operations](#metadata-operations)
         - [Execute Actions/Functions](#execute-actionsfunctions)
+        - [Deploy Solutions](#deploy-solutions)
     - [API Reference](#api-reference)
         - [ToolBox API (`window.toolboxAPI`)](#toolbox-api-windowtoolboxapi)
             - [Connections](#connections-1)
@@ -39,6 +44,71 @@ TypeScript type definitions for Power Platform ToolBox APIs.
 npm install --save-dev @pptb/types
 ```
 
+## Tool Validation
+
+The `@pptb/types` package ships with a `pptb-validate` binary that validates your tool's `package.json` against the **same rules** used by the official Power Platform ToolBox review process. Running it before publishing helps you catch configuration problems early, reduces failed reviews, and avoids publishing unnecessary npm versions.
+
+### Quick start
+
+Add a script to your tool's `package.json`:
+
+```json
+{
+    "scripts": {
+        "pptb-validate": "pptb-validate"
+    }
+}
+```
+
+Then run:
+
+```bash
+npm run pptb-validate
+```
+
+You can also run it directly (no script entry needed once `@pptb/types` is installed):
+
+```bash
+npx pptb-validate
+```
+
+Or point it at a specific file:
+
+```bash
+npx pptb-validate path/to/package.json
+```
+
+### CLI options
+
+| Option | Description |
+|---|---|
+| `--skip-url-checks` | Skip URL reachability checks (faster, works offline) |
+| `--json` | Print results as a JSON object (suitable for CI pipelines) |
+| `--help`, `-h` | Show help information |
+
+### What is validated
+
+The validator checks every field that the official review pipeline inspects:
+
+| Field | Required | Rules |
+|---|---|---|
+| `name` | ✅ | Must be a string |
+| `version` | ✅ | Must be a string |
+| `displayName` | ✅ | Must be a string |
+| `description` | ✅ | Must be a string |
+| `license` | ✅ | Must be one of the approved OSS licenses (MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, GPL-2.0, GPL-3.0, LGPL-3.0, ISC, AGPL-3.0-only) |
+| `contributors` | ✅ | Non-empty array; each entry needs a `name` |
+| `configurations.repository` | ✅ | Valid, reachable URL |
+| `configurations.readmeUrl` | ✅ | Valid URL; must **not** be hosted on `github.com` (use `raw.githubusercontent.com`) |
+| `configurations.website` | ❌ | Valid, reachable URL when provided |
+| `configurations.funding` | ❌ | Valid, reachable URL when provided |
+| `icon` | ❌ | Relative path to a `.svg` file bundled under `dist/`; must not be an HTTP URL or an absolute path |
+| `cspExceptions` | ❌ | When present: must not be empty; only recognised directives; each directive must be a non-empty array |
+| `features.multiConnection` | ❌* | Required when `features` is present; must be `"required"`, `"optional"`, or `"none"` |
+| `features.minAPI` | ❌ | Valid semver string when provided |
+
+> \* Required only when the `features` object is present.
+
 ## Overview
 
 The `@pptb/types` package provides TypeScript definitions for two main APIs:

package/bin/pptb-validate.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// @ts-check
+"use strict";
+
+/**
+ * pptb-validate - CLI tool for validating Power Platform ToolBox tool packages
+ *
+ * Usage:
+ *   pptb-validate [options] [path/to/package.json]
+ *
+ * Options:
+ *   --skip-url-checks   Skip URL accessibility checks (faster, offline-friendly)
+ *   --json              Output results as JSON
+ *   --help, -h          Show help information
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { validatePackageJson } = require("../lib/validate");
+
+// ANSI colour helpers – gracefully degrade when colours are unsupported
+const NO_COLOR = !process.stdout.isTTY || process.env.NO_COLOR;
+const c = {
+    red: (s) => (NO_COLOR ? s : `\x1b[31m${s}\x1b[0m`),
+    yellow: (s) => (NO_COLOR ? s : `\x1b[33m${s}\x1b[0m`),
+    green: (s) => (NO_COLOR ? s : `\x1b[32m${s}\x1b[0m`),
+    cyan: (s) => (NO_COLOR ? s : `\x1b[36m${s}\x1b[0m`),
+    bold: (s) => (NO_COLOR ? s : `\x1b[1m${s}\x1b[0m`),
+    dim: (s) => (NO_COLOR ? s : `\x1b[2m${s}\x1b[0m`),
+};
+
+function printHelp() {
+    console.log(`
+${c.bold("pptb-validate")} – Power Platform ToolBox tool validator
+
+${c.bold("USAGE")}
+  pptb-validate [options] [path/to/package.json]
+
+  When no path is given the tool looks for ${c.cyan("package.json")} in the current
+  working directory.
+
+${c.bold("OPTIONS")}
+  ${c.cyan("--skip-url-checks")}   Skip URL reachability checks (faster, works offline)
+  ${c.cyan("--json")}              Print results as a JSON object instead of human-readable text
+  ${c.cyan("--help")}, ${c.cyan("-h")}          Show this help message
+
+${c.bold("ADD TO YOUR TOOL'S package.json")}
+  ${c.dim(`"scripts": {
+    "validate": "pptb-validate"
+  }`)}
+
+  Then run: ${c.cyan("npm run validate")}
+
+${c.bold("EXAMPLES")}
+  npm run validate
+  npm run validate ./my-tool/package.json
+  npm run validate --skip-url-checks
+  npm run validate --json
+`);
+}
+
+async function main() {
+    const args = process.argv.slice(2);
+
+    if (args.includes("--help") || args.includes("-h")) {
+        printHelp();
+        process.exit(0);
+    }
+
+    const skipUrlChecks = args.includes("--skip-url-checks");
+    const jsonOutput = args.includes("--json");
+
+    // Find the package.json path from positional args (skip flags)
+    const positional = args.filter((a) => !a.startsWith("-"));
+    let packageJsonPath = positional[0] || path.join(process.cwd(), "package.json");
+
+    // Resolve to absolute path
+    if (!path.isAbsolute(packageJsonPath)) {
+        packageJsonPath = path.resolve(process.cwd(), packageJsonPath);
+    }
+
+    // --- Load package.json ---
+    if (!fs.existsSync(packageJsonPath)) {
+        if (jsonOutput) {
+            console.log(JSON.stringify({ valid: false, errors: [`package.json not found at: ${packageJsonPath}`], warnings: [] }, null, 2));
+        } else {
+            console.error(c.red(`✖ package.json not found at: ${packageJsonPath}`));
+        }
+        process.exit(1);
+    }
+
+    let packageJson;
+    try {
+        packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (jsonOutput) {
+            console.log(JSON.stringify({ valid: false, errors: [`Failed to parse package.json: ${message}`], warnings: [] }, null, 2));
+        } else {
+            console.error(c.red(`✖ Failed to parse package.json: ${message}`));
+        }
+        process.exit(1);
+    }
+
+    // --- Run validation ---
+    if (!jsonOutput) {
+        console.log();
+        console.log(c.bold("Power Platform ToolBox – Tool Validator"));
+        console.log(c.dim("─".repeat(45)));
+        console.log(c.dim(`File: ${packageJsonPath}`));
+        if (skipUrlChecks) {
+            console.log(c.yellow("⚠  URL reachability checks are skipped"));
+        }
+        console.log();
+    }
+
+    let result;
+    try {
+        result = await validatePackageJson(packageJson, { skipUrlChecks });
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (jsonOutput) {
+            console.log(JSON.stringify({ valid: false, errors: [`Unexpected validation error: ${message}`], warnings: [] }, null, 2));
+        } else {
+            console.error(c.red(`✖ Unexpected validation error: ${message}`));
+        }
+        process.exit(1);
+    }
+
+    // --- Output results ---
+    if (jsonOutput) {
+        console.log(JSON.stringify(result, null, 2));
+        process.exit(result.valid ? 0 : 1);
+    }
+
+    // Human-readable output
+    if (result.errors.length > 0) {
+        console.log(c.bold(c.red(`Errors (${result.errors.length})`)));
+        result.errors.forEach((e) => console.log(`  ${c.red("✖")} ${e}`));
+        console.log();
+    }
+
+    if (result.warnings.length > 0) {
+        console.log(c.bold(c.yellow(`Warnings (${result.warnings.length})`)));
+        result.warnings.forEach((w) => console.log(`  ${c.yellow("⚠")} ${w}`));
+        console.log();
+    }
+
+    if (result.valid) {
+        const info = result.packageInfo;
+        console.log(c.green(c.bold("✔ Validation passed")));
+        console.log();
+        console.log(c.bold("Package summary"));
+        console.log(c.dim("─".repeat(45)));
+        console.log(`  Name        : ${info.name}`);
+        console.log(`  Version     : ${info.version}`);
+        console.log(`  Display name: ${info.displayName}`);
+        console.log(`  Description : ${info.description}`);
+        console.log(`  License     : ${info.license}`);
+        console.log(`  Contributors: ${info.contributors.map((c) => c.name).join(", ")}`);
+        if (info.icon) {
+            console.log(`  Icon        : ${info.icon}`);
+        }
+        if (info.features) {
+            console.log(`  Features    : multiConnection=${info.features.multiConnection}${info.features.minAPI ? `, minAPI=${info.features.minAPI}` : ""}`);
+        }
+        console.log();
+    } else {
+        console.log(c.red(c.bold("✖ Validation failed")));
+        console.log();
+        console.log(c.dim("Fix the errors listed above and re-run pptb-validate before publishing."));
+        console.log();
+    }
+
+    process.exit(result.valid ? 0 : 1);
+}
+
+main().catch((err) => {
+    console.error(c.red(`✖ Fatal error: ${err instanceof Error ? err.message : String(err)}`));
+    process.exit(1);
+});

package/lib/validate.js

@@ -0,0 +1,302 @@
+// @ts-check
+"use strict";
+
+/**
+ * Tool validation logic for Power Platform ToolBox tools.
+ * Mirrors the validation rules used during the official review process.
+ */
+
+/** @typedef {{ name: string; url?: string }} Contributor */
+/** @typedef {{ "connect-src"?: string[]; "script-src"?: string[]; "style-src"?: string[]; "img-src"?: string[]; "font-src"?: string[]; "frame-src"?: string[] }} CspExceptions */
+/** @typedef {{ repository?: string; website?: string; funding?: string; readmeUrl?: string }} Configurations */
+/** @typedef {{ multiConnection?: "required" | "optional" | "none"; minAPI?: string }} Features */
+/**
+ * @typedef {{
+ *   name: string;
+ *   version: string;
+ *   displayName?: string;
+ *   description?: string;
+ *   contributors?: Contributor[];
+ *   cspExceptions?: CspExceptions;
+ *   license?: string;
+ *   icon?: string;
+ *   configurations?: Configurations;
+ *   features?: Features;
+ * }} ToolPackageJson
+ */
+/**
+ * @typedef {{
+ *   valid: boolean;
+ *   errors: string[];
+ *   warnings: string[];
+ *   packageInfo?: object;
+ * }} ValidationResult
+ */
+
+// List of approved open source licenses
+const APPROVED_LICENSES = ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "GPL-2.0", "GPL-3.0", "LGPL-3.0", "ISC", "AGPL-3.0-only"];
+
+// Valid multiConnection values
+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-]+)*)?$/;
+
+/**
+ * Checks if a string is a valid URL.
+ * @param {string} url
+ * @returns {boolean}
+ */
+function isValidUrl(url) {
+    try {
+        new URL(url);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Checks if a URL hostname is a GitHub domain.
+ * @param {string} url
+ * @returns {boolean}
+ */
+function isGithubDomain(url) {
+    try {
+        const hostname = new URL(url).hostname.toLowerCase();
+        return hostname === "github.com" || hostname.endsWith(".github.com");
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Validates an icon path string.
+ * @param {string} fieldName
+ * @param {string} iconPath
+ * @param {string[]} errors
+ */
+function validateIconPath(fieldName, iconPath, errors) {
+    if (iconPath.startsWith("http://") || iconPath.startsWith("https://")) {
+        errors.push(`${fieldName} cannot be an HTTP(S) URL - icons must be bundled under dist`);
+        return;
+    }
+    if (iconPath.startsWith("/")) {
+        errors.push(`${fieldName} must be a relative path (e.g., 'icon.svg' or 'icons/icon.svg')`);
+        return;
+    }
+    if (iconPath.includes("..")) {
+        errors.push(`${fieldName} cannot contain '..' (path traversal not allowed)`);
+        return;
+    }
+    if (!iconPath.toLowerCase().endsWith(".svg")) {
+        errors.push(`${fieldName} must be an SVG file with .svg extension`);
+    }
+}
+
+/**
+ * Checks if a URL is accessible by making a HEAD request.
+ * @param {string} url
+ * @returns {Promise<boolean>}
+ */
+async function isUrlAccessible(url) {
+    try {
+        const response = await fetch(url, { method: "HEAD", redirect: "follow" });
+        return response.ok;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Validates a tool's package.json against the official review criteria.
+ *
+ * @param {ToolPackageJson} packageJson - The parsed package.json object.
+ * @param {{ skipUrlChecks?: boolean }} [options] - Validation options.
+ * @returns {Promise<ValidationResult>}
+ */
+async function validatePackageJson(packageJson, options = {}) {
+    const { skipUrlChecks = false } = options;
+    const errors = /** @type {string[]} */ ([]);
+    const warnings = /** @type {string[]} */ ([]);
+
+    // Required fields
+    if (!packageJson.name || typeof packageJson.name !== "string") {
+        errors.push("Package name is required and must be a string");
+    }
+
+    if (!packageJson.version || typeof packageJson.version !== "string") {
+        errors.push("Package version is required and must be a string");
+    }
+
+    if (!packageJson.displayName || typeof packageJson.displayName !== "string") {
+        errors.push("displayName is required and must be a string");
+    }
+
+    if (!packageJson.description || typeof packageJson.description !== "string") {
+        errors.push("description is required and must be a string");
+    }
+
+    // License validation
+    if (!packageJson.license) {
+        errors.push("license is required");
+    } else if (!APPROVED_LICENSES.includes(packageJson.license)) {
+        errors.push(`License "${packageJson.license}" is not in the approved list. Approved licenses: ${APPROVED_LICENSES.join(", ")}`);
+    }
+
+    // Icon validation (optional, but must be a relative SVG path if provided)
+    if (packageJson.icon !== undefined && packageJson.icon !== null) {
+        if (typeof packageJson.icon !== "string") {
+            errors.push("icon must be a string (relative path to bundled SVG under dist)");
+        } else {
+            validateIconPath("icon", packageJson.icon, errors);
+        }
+    }
+
+    // Contributors validation
+    if (!packageJson.contributors || !Array.isArray(packageJson.contributors)) {
+        errors.push("contributors is required and must be an array");
+    } else if (packageJson.contributors.length === 0) {
+        errors.push("At least one contributor is required");
+    } else {
+        packageJson.contributors.forEach((contributor, index) => {
+            if (!contributor.name || typeof contributor.name !== "string") {
+                errors.push(`Contributor at index ${index} must have a name`);
+            }
+            if (contributor.url && !isValidUrl(contributor.url)) {
+                warnings.push(`Contributor "${contributor.name}" has an invalid URL`);
+            }
+        });
+    }
+
+    // Configurations validation
+    if (!packageJson.configurations || typeof packageJson.configurations !== "object") {
+        errors.push("configurations is required and must include repository and readmeUrl");
+    } else {
+        const configs = packageJson.configurations;
+
+        // configurations.iconUrl is no longer supported
+        if (/** @type {Record<string, unknown>} */ (configs).iconUrl !== undefined) {
+            errors.push("configurations.iconUrl is no longer supported; use top-level 'icon' for bundled SVG path");
+        }
+
+        // Repository validation
+        if (!configs.repository || typeof configs.repository !== "string") {
+            errors.push("configurations.repository is required and must be a URL");
+        } else if (!isValidUrl(configs.repository)) {
+            errors.push("configurations.repository has an invalid URL format");
+        } else if (!skipUrlChecks) {
+            const accessible = await isUrlAccessible(configs.repository);
+            if (!accessible) {
+                errors.push("configurations.repository URL is not accessible");
+            }
+        }
+
+        // Website validation (optional)
+        if (configs.website) {
+            if (!isValidUrl(configs.website)) {
+                warnings.push("configurations.website has an invalid URL format");
+            } else if (!skipUrlChecks) {
+                const accessible = await isUrlAccessible(configs.website);
+                if (!accessible) {
+                    warnings.push("configurations.website URL is not accessible");
+                }
+            }
+        }
+
+        // Funding validation (optional)
+        if (configs.funding) {
+            if (!isValidUrl(configs.funding)) {
+                warnings.push("configurations.funding has an invalid URL format");
+            } else if (!skipUrlChecks) {
+                const accessible = await isUrlAccessible(configs.funding);
+                if (!accessible) {
+                    warnings.push("configurations.funding URL is not accessible");
+                }
+            }
+        }
+
+        // ReadmeUrl validation
+        if (!configs.readmeUrl || typeof configs.readmeUrl !== "string") {
+            errors.push("configurations.readmeUrl is required and must be a URL");
+        } else if (!isValidUrl(configs.readmeUrl)) {
+            errors.push("configurations.readmeUrl has an invalid URL format");
+        } else if (isGithubDomain(configs.readmeUrl)) {
+            errors.push("configurations.readmeUrl cannot be hosted on github.com; use raw.githubusercontent.com or another domain");
+        } else if (!skipUrlChecks) {
+            const accessible = await isUrlAccessible(configs.readmeUrl);
+            if (!accessible) {
+                errors.push("configurations.readmeUrl is not accessible");
+            }
+        }
+    }
+
+    // CSP Exceptions validation (optional, but validated if present)
+    if (packageJson.cspExceptions) {
+        const validCspDirectives = ["connect-src", "script-src", "style-src", "img-src", "font-src", "frame-src"];
+
+        const hasAnyDirectives = Object.keys(packageJson.cspExceptions).length > 0;
+        if (!hasAnyDirectives) {
+            errors.push("cspExceptions cannot be empty. If CSP exceptions are not needed, remove the cspExceptions field");
+        }
+
+        Object.keys(packageJson.cspExceptions).forEach((directive) => {
+            if (!validCspDirectives.includes(directive)) {
+                warnings.push(`Unknown CSP directive: ${directive}`);
+            }
+            const values = packageJson.cspExceptions?.[/** @type {keyof CspExceptions} */ (directive)];
+            if (values && !Array.isArray(values)) {
+                errors.push(`CSP directive "${directive}" must be an array of strings`);
+            } else if (values && values.length === 0) {
+                errors.push(`CSP directive "${directive}" cannot be an empty array`);
+            }
+        });
+    }
+
+    // Features validation (optional, but validated if present)
+    if (packageJson.features) {
+        const VALID_FEATURE_KEYS = ["multiConnection", "minAPI"];
+        const featureKeys = Object.keys(packageJson.features);
+        const invalidKeys = featureKeys.filter((key) => !VALID_FEATURE_KEYS.includes(key));
+
+        if (invalidKeys.length > 0) {
+            errors.push(`features can only contain ${VALID_FEATURE_KEYS.map((k) => `'${k}'`).join(", ")} properties. Invalid properties: ${invalidKeys.join(", ")}`);
+        }
+
+        if (packageJson.features.multiConnection === undefined) {
+            errors.push("features.multiConnection is required when features object is provided");
+        } else if (!VALID_MULTI_CONNECTION_VALUES.includes(packageJson.features.multiConnection)) {
+            errors.push(`features.multiConnection must be one of: ${VALID_MULTI_CONNECTION_VALUES.join(", ")}`);
+        }
+
+        if (packageJson.features.minAPI !== undefined) {
+            if (typeof packageJson.features.minAPI !== "string" || !SEMVER_REGEX.test(packageJson.features.minAPI)) {
+                errors.push("features.minAPI must be a valid semantic version string (e.g., '1.0.0')");
+            }
+        }
+    }
+
+    const valid = errors.length === 0;
+
+    return {
+        valid,
+        errors,
+        warnings,
+        packageInfo: valid
+            ? {
+                  name: packageJson.name,
+                  version: packageJson.version,
+                  displayName: packageJson.displayName,
+                  description: packageJson.description,
+                  license: packageJson.license,
+                  contributors: packageJson.contributors,
+                  cspExceptions: packageJson.cspExceptions,
+                  icon: packageJson.icon,
+                  configurations: packageJson.configurations,
+                  features: packageJson.features,
+              }
+            : undefined,
+    };
+}
+
+module.exports = { validatePackageJson, isValidUrl, APPROVED_LICENSES };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pptb/types",
-  "version": "1.0.20",
-  "description": "TypeScript type definitions for Power Platform ToolBox API",
+  "version": "1.1.3-beta.1",
+  "description": "Type definitions for Power Platform ToolBox APIs and validity checks for tool packages",
   "main": "index.d.ts",
   "types": "index.d.ts",
   "keywords": [
@@ -19,6 +19,17 @@
     "url": "https://github.com/PowerPlatformToolBox/desktop-app.git",
     "directory": "packages"
   },
+  "bin": {
+    "pptb-validate": "./bin/pptb-validate.js"
+  },
+  "files": [
+    "index.d.ts",
+    "toolboxAPI.d.ts",
+    "dataverseAPI.d.ts",
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
   "scripts": {
     "version:beta": "pnpm version prerelease --preid beta --no-git-tag-version",
     "version:stable": "pnpm version patch --no-git-tag-version",