@lushly-dev/fast-element 3.0.1-preview.0 → 3.0.1-preview.2

package/dist/esm/command/schema-validation.js

@@ -0,0 +1,194 @@
+/**
+ * A small, dependency-free JSON Schema validator for command `parameters`.
+ *
+ * @remarks
+ * Deliberately limited to the keywords agents and command palettes actually
+ * rely on: `type`, `enum`, `const`, `required`, `properties`,
+ * `additionalProperties`, `items`, `minimum`/`maximum` (plus the numeric
+ * exclusive forms), `minLength`/`maxLength` and `minItems`/`maxItems`.
+ * Unknown keywords (including `pattern`, `$ref`, `oneOf`, ...) are ignored, so a
+ * schema that uses them is validated on a best-effort basis rather than rejected.
+ *
+ * @internal
+ */
+const MAX_ISSUES = 20;
+const hasOwn = (target, key) => Object.prototype.hasOwnProperty.call(target, key);
+function typeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "integer" : "number";
+    return typeof value;
+}
+function matchesType(value, type) {
+    switch (type) {
+        case "string":
+        case "boolean":
+        case "undefined":
+            return typeof value === type;
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "null":
+            return value === null;
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value);
+        default:
+            // Unknown type names are not enforced.
+            return true;
+    }
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) {
+        return false;
+    }
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const aKeys = Object.keys(a);
+    if (aKeys.length !== Object.keys(b).length)
+        return false;
+    return aKeys.every(key => hasOwn(b, key) &&
+        deepEqual(a[key], b[key]));
+}
+function validateInto(issues, value, schema, path) {
+    if (issues.length >= MAX_ISSUES)
+        return;
+    const report = (at, message) => {
+        if (issues.length < MAX_ISSUES)
+            issues.push({ path: at, message });
+    };
+    const add = (message) => report(path, message);
+    const type = schema.type;
+    if (type !== void 0) {
+        const types = Array.isArray(type) ? type : [type];
+        if (!types.some(t => matchesType(value, t))) {
+            add(`expected ${types.join(" or ")} but received ${typeOf(value)}`);
+            return;
+        }
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.some(v => deepEqual(v, value))) {
+        add(`must be one of ${JSON.stringify(schema.enum)}`);
+    }
+    if (hasOwn(schema, "const") && !deepEqual(schema.const, value)) {
+        add(`must equal ${JSON.stringify(schema.const)}`);
+    }
+    if (typeof value === "number") {
+        const { minimum, maximum, exclusiveMinimum, exclusiveMaximum } = schema;
+        if (typeof minimum === "number" && value < minimum) {
+            add(`must be >= ${minimum}`);
+        }
+        if (typeof maximum === "number" && value > maximum) {
+            add(`must be <= ${maximum}`);
+        }
+        if (typeof exclusiveMinimum === "number" && value <= exclusiveMinimum) {
+            add(`must be > ${exclusiveMinimum}`);
+        }
+        if (typeof exclusiveMaximum === "number" && value >= exclusiveMaximum) {
+            add(`must be < ${exclusiveMaximum}`);
+        }
+    }
+    if (typeof value === "string") {
+        if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+            add(`must be at least ${schema.minLength} character(s)`);
+        }
+        if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+            add(`must be at most ${schema.maxLength} character(s)`);
+        }
+    }
+    if (Array.isArray(value)) {
+        if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+            add(`must contain at least ${schema.minItems} item(s)`);
+        }
+        if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+            add(`must contain at most ${schema.maxItems} item(s)`);
+        }
+        const items = schema.items;
+        if (items !== null && typeof items === "object" && !Array.isArray(items)) {
+            for (let i = 0; i < value.length && issues.length < MAX_ISSUES; i++) {
+                validateInto(issues, value[i], items, `${path}[${i}]`);
+            }
+        }
+    }
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const record = value;
+        const properties = schema.properties !== null && typeof schema.properties === "object"
+            ? schema.properties
+            : {};
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                if (!hasOwn(record, key) || record[key] === void 0) {
+                    report(`${path}.${key}`, "is required");
+                }
+            }
+        }
+        for (const key of Object.keys(properties)) {
+            const propertySchema = properties[key];
+            if (hasOwn(record, key) &&
+                record[key] !== void 0 &&
+                propertySchema !== null &&
+                typeof propertySchema === "object") {
+                validateInto(issues, record[key], propertySchema, `${path}.${key}`);
+            }
+        }
+        const additional = schema.additionalProperties;
+        if (additional === false) {
+            for (const key of Object.keys(record)) {
+                if (!hasOwn(properties, key)) {
+                    report(`${path}.${key}`, "is not an allowed property");
+                }
+            }
+        }
+        else if (additional !== null && typeof additional === "object") {
+            for (const key of Object.keys(record)) {
+                if (!hasOwn(properties, key)) {
+                    validateInto(issues, record[key], additional, `${path}.${key}`);
+                }
+            }
+        }
+    }
+}
+/**
+ * Validates a value against a (basic) JSON Schema.
+ * @param value - The value to validate.
+ * @param schema - The JSON Schema.
+ * @returns The list of problems; empty when the value is valid.
+ * @internal
+ */
+export function validateSchema(value, schema) {
+    const issues = [];
+    validateInto(issues, value, schema, "$");
+    return issues;
+}
+/**
+ * Validates the arguments of a command invocation against the command's
+ * `parameters` schema.
+ *
+ * @remarks
+ * Command arguments are positional (`execute(...args)`), but the `parameters`
+ * schema describes a single structured argument, which is how every built-in
+ * command (and agent tool call) consumes input. The schema is therefore applied to
+ * `args[0]`. When no argument is supplied and the schema describes an object,
+ * an empty object is validated so `required` still fires.
+ *
+ * @internal
+ */
+export function validateCommandArguments(args, schema) {
+    let value = args[0];
+    if (value === void 0) {
+        const describesObject = schema.type === "object" ||
+            schema.properties !== void 0 ||
+            schema.required !== void 0;
+        if (!describesObject) {
+            return [{ path: "$", message: "a value is required" }];
+        }
+        value = {};
+    }
+    return validateSchema(value, schema);
+}

package/dist/esm/command/types.js

@@ -0,0 +1,86 @@
+/**
+ * Type definitions for the `command` decorator system.
+ * Enables AI agents to interact with FASTElement components through structured commands.
+ *
+ * @remarks
+ * This module contains types only - no runtime code.
+ * Re-exports AFD core types for ecosystem alignment.
+ * FAST-AF is an "agent runtime for Web Components".
+ */
+/**
+ * Standard error codes for command failures.
+ * @public
+ */
+export const ErrorCodes = {
+    /** Command ID not found in registry */
+    COMMAND_NOT_FOUND: "COMMAND_NOT_FOUND",
+    /** Command is currently disabled */
+    COMMAND_DISABLED: "COMMAND_DISABLED",
+    /** Command is not exposed to the interface that invoked it */
+    COMMAND_NOT_EXPOSED: "COMMAND_NOT_EXPOSED",
+    /** Invalid parameters provided */
+    INVALID_PARAMETERS: "INVALID_PARAMETERS",
+    /** Destructive command requires confirmation but no confirmation handler is installed */
+    CONFIRMATION_REQUIRED: "CONFIRMATION_REQUIRED",
+    /** Command execution failed */
+    EXECUTION_FAILED: "EXECUTION_FAILED",
+    /** Operation timed out */
+    TIMEOUT: "TIMEOUT",
+    /** Generic internal error */
+    INTERNAL_ERROR: "INTERNAL_ERROR",
+};
+/**
+ * Create a successful command result.
+ * @param data - The result data
+ * @param metadata - Optional metadata
+ * @public
+ */
+export function success(data, metadata) {
+    return { success: true, data, metadata };
+}
+/**
+ * Create a failed command result.
+ * @param error - The error information
+ * @param metadata - Optional metadata
+ * @public
+ */
+export function failure(error, metadata) {
+    return { success: false, error, metadata };
+}
+/**
+ * Type guard for successful results.
+ * @param result - The result to check
+ * @public
+ */
+export function isSuccess(result) {
+    return result.success === true;
+}
+/**
+ * Type guard for failed results.
+ * @param result - The result to check
+ * @public
+ */
+export function isFailure(result) {
+    return result.success === false;
+}
+/**
+ * Create a CommandError object.
+ * @param code - Error code
+ * @param message - Error message
+ * @param options - Additional error options
+ * @public
+ */
+export function createError(code, message, options) {
+    return Object.assign({ code, message }, options);
+}
+/**
+ * Default expose configuration.
+ * Secure defaults: palette and agent are enabled, mcp and cli require opt-in.
+ * @public
+ */
+export const DEFAULT_EXPOSE_CONFIG = {
+    palette: true,
+    agent: true,
+    mcp: false,
+    cli: false,
+};