@picteus/extension-sdk 0.17.0 → 0.19.0

package/dist/generated/frontEndIntents.js

@@ -0,0 +1,97 @@
+/**
+ * Target layout anchor where an embedded extension user interface should be integrated.
+ *
+ * @remarks
+ * The selected anchor is the discriminator for the supported integration surface. Its string value is part of the serialized intent contract and must match one of these declared choices.
+ */
+var UiAnchor;
+(function (UiAnchor) {
+    /** Rendered inside a centered or full-screen modal dialog. */
+    UiAnchor["Modal"] = "modal";
+    /** Docked within the collateral sidebar navigation. */
+    UiAnchor["Sidebar"] = "sidebar";
+    /** Rendered inside an independent floating desktop window. */
+    UiAnchor["Window"] = "window";
+    /** Embedded within the image detail inspection view. */
+    UiAnchor["ImageDetail"] = "imageDetail";
+    /** Displayed within a dedicated tab. */
+    UiAnchor["Tab"] = "tab";
+})(UiAnchor || (UiAnchor = {}));
+/**
+ * Target layout anchor where an embedded extension user interface should be integrated.
+ *
+ * @remarks
+ * The selected anchor is the discriminator for the supported integration surface. Its string value is part of the serialized intent contract and must match one of these declared choices.
+ */
+export const IntentUiAnchor = UiAnchor;
+/** Semantic classification and visual styling category of a modal dialog. */
+var DialogType;
+(function (DialogType) {
+    /** Error notice dialog indicating a failure or critical condition. */
+    DialogType["Error"] = "error";
+    /** Informational dialog displaying status, instructions, or notices. */
+    DialogType["Info"] = "info";
+    /** Question or confirmation prompt requiring explicit user decision. */
+    DialogType["Question"] = "question";
+})(DialogType || (DialogType = {}));
+/** Semantic classification and visual styling category of a modal dialog. */
+export const IntentDialogType = DialogType;
+/** Target view or entity type to display in the front-end. */
+var ShowType;
+(function (ShowType) {
+    /** Registered collateral sidebar panel. */
+    ShowType["Sidebar"] = "sidebar";
+    /** Extension settings configuration modal. */
+    ShowType["ExtensionSettings"] = "extensionSettings";
+    /** Full-screen image detail inspection view. */
+    ShowType["Image"] = "image";
+    /** Repository details and contents view. */
+    ShowType["Repository"] = "repository";
+})(ShowType || (ShowType = {}));
+/** Target view or entity type to display in the front-end. */
+export const IntentShowType = ShowType;
+/** Visual style and severity variant for toast notifications. */
+var ToastType;
+(function (ToastType) {
+    /** Informational toast indicating general status or successful completion. */
+    ToastType["Info"] = "info";
+    /** Cancellation toast indicating an operation was aborted or cancelled. */
+    ToastType["Cancel"] = "cancel";
+    /** Error toast indicating a failure or warning condition. */
+    ToastType["Error"] = "error";
+})(ToastType || (ToastType = {}));
+/** Visual style and severity variant for toast notifications. */
+export const IntentToastType = ToastType;
+function hasIntentProperty(intent, propertyName) {
+    return typeof intent === "object" && intent !== null && Reflect.get(intent, propertyName) !== undefined;
+}
+export function isFormIntent(intent) {
+    return hasIntentProperty(intent, "form");
+}
+export function isUiIntent(intent) {
+    return hasIntentProperty(intent, "ui");
+}
+export function isOpenBrowserIntent(intent) {
+    return hasIntentProperty(intent, "openBrowser");
+}
+export function isDialogIntent(intent) {
+    return hasIntentProperty(intent, "dialog");
+}
+export function isImagesIntent(intent) {
+    return hasIntentProperty(intent, "images");
+}
+export function isShowIntent(intent) {
+    return hasIntentProperty(intent, "show");
+}
+export function isToastIntent(intent) {
+    return hasIntentProperty(intent, "toast");
+}
+export function isNotificationIntent(intent) {
+    return hasIntentProperty(intent, "notification");
+}
+export function isProcessCommandIntent(intent) {
+    return hasIntentProperty(intent, "processCommand");
+}
+export function isActionIntent(intent) {
+    return hasIntentProperty(intent, "action");
+}

package/dist/generated/intentValidator.d.ts

@@ -0,0 +1,49 @@
+export interface IntentTypeDescription {
+    readonly kind: "string" | "number" | "boolean" | "bytes" | "enum" | "model" | "array" | "record" | "union" | "literal";
+    readonly name: string;
+    readonly literalValue?: string | number | boolean;
+    readonly elementType?: IntentTypeDescription;
+    readonly unionTypes?: readonly IntentTypeDescription[];
+}
+export interface IntentPropertyDescription {
+    readonly name: string;
+    readonly optional: boolean;
+    readonly type: IntentTypeDescription;
+    readonly format?: string;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly minValue?: number;
+    readonly maxValue?: number;
+    readonly pattern?: string;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+}
+export interface IntentModelDescription {
+    readonly baseModelName?: string;
+    readonly properties: readonly IntentPropertyDescription[];
+}
+export interface IntentSchemaDescription {
+    readonly enums: Readonly<Record<string, readonly string[]>>;
+    readonly models: Readonly<Record<string, IntentModelDescription>>;
+    readonly unions: Readonly<Record<string, readonly IntentTypeDescription[]>>;
+    readonly intents: readonly string[];
+}
+export interface ValidationIssue {
+    readonly path: string;
+    readonly message: string;
+}
+export interface ValidationSuccess<T = unknown> {
+    readonly success: true;
+    readonly data: T;
+}
+export interface ValidationFailure {
+    readonly success: false;
+    readonly error: {
+        readonly message: string;
+        readonly issues: readonly ValidationIssue[];
+    };
+    readonly issues: readonly ValidationIssue[];
+}
+export type ValidationResult<T = unknown> = ValidationSuccess<T> | ValidationFailure;
+export declare function validateModel<T = unknown>(value: unknown, modelName: string, schema?: IntentSchemaDescription): ValidationResult<T>;
+export declare function validateIntent<T = unknown>(value: unknown, schema?: IntentSchemaDescription): ValidationResult<T>;

package/dist/generated/intentValidator.js

@@ -0,0 +1,363 @@
+// ---------------------------------------------------------------------------
+// Auto-generated by @picteus/specification-factory. Do not edit directly.
+// ---------------------------------------------------------------------------
+import { INTENT_SCHEMA_DESCRIPTION } from "./frontEndIntents.js";
+function isValidUrl(candidate) {
+    try {
+        new URL(candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isByteBuffer(candidate) {
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(candidate)) {
+        return true;
+    }
+    return candidate instanceof Uint8Array;
+}
+function collectModelProperties(modelName, schema) {
+    const model = schema.models[modelName];
+    if (!model) {
+        return [];
+    }
+    const properties = [];
+    if (model.baseModelName) {
+        properties.push(...collectModelProperties(model.baseModelName, schema));
+    }
+    properties.push(...model.properties);
+    return properties;
+}
+function validateValue(value, type, schema, path, propertyConstraints) {
+    switch (type.kind) {
+        case "string":
+            {
+                if (typeof value !== "string") {
+                    return [
+                        {
+                            path,
+                            message: `Expected string, received ${typeof value}`
+                        }
+                    ];
+                }
+                if (propertyConstraints?.format === "url" && isValidUrl(value) === false) {
+                    return [
+                        {
+                            path,
+                            message: `Invalid url: "${value}"`
+                        }
+                    ];
+                }
+                if (propertyConstraints?.minLength !== undefined && value.length < propertyConstraints.minLength) {
+                    return [
+                        {
+                            path,
+                            message: `String must contain at least ${propertyConstraints.minLength} character(s)`
+                        }
+                    ];
+                }
+                if (propertyConstraints?.maxLength !== undefined && value.length > propertyConstraints.maxLength) {
+                    return [
+                        {
+                            path,
+                            message: `String must contain at most ${propertyConstraints.maxLength} character(s)`
+                        }
+                    ];
+                }
+                if (propertyConstraints?.pattern !== undefined) {
+                    const regularExpression = new RegExp(propertyConstraints.pattern);
+                    if (regularExpression.test(value) === false) {
+                        return [
+                            {
+                                path,
+                                message: `String does not match required pattern "${propertyConstraints.pattern}"`
+                            }
+                        ];
+                    }
+                }
+                return [];
+            }
+        case "number":
+            {
+                if (typeof value !== "number" || Number.isNaN(value) === true) {
+                    return [
+                        {
+                            path,
+                            message: `Expected number, received ${typeof value}`
+                        }
+                    ];
+                }
+                if ((type.name === "int32" || type.name === "integer" || type.name === "int64") && Number.isInteger(value) === false) {
+                    return [
+                        {
+                            path,
+                            message: `Expected integer for ${type.name}, received float ${value}`
+                        }
+                    ];
+                }
+                if (propertyConstraints?.minValue !== undefined && value < propertyConstraints.minValue) {
+                    return [
+                        {
+                            path,
+                            message: `Number must be greater than or equal to ${propertyConstraints.minValue}`
+                        }
+                    ];
+                }
+                if (propertyConstraints?.maxValue !== undefined && value > propertyConstraints.maxValue) {
+                    return [
+                        {
+                            path,
+                            message: `Number must be less than or equal to ${propertyConstraints.maxValue}`
+                        }
+                    ];
+                }
+                return [];
+            }
+        case "boolean":
+            {
+                if (typeof value !== "boolean") {
+                    return [
+                        {
+                            path,
+                            message: `Expected boolean, received ${typeof value}`
+                        }
+                    ];
+                }
+                return [];
+            }
+        case "bytes":
+            {
+                if (isByteBuffer(value) === false) {
+                    return [
+                        {
+                            path,
+                            message: `Expected Buffer or Uint8Array, received ${typeof value}`
+                        }
+                    ];
+                }
+                return [];
+            }
+        case "literal":
+            {
+                if (value !== type.literalValue) {
+                    return [
+                        {
+                            path,
+                            message: `Expected literal ${JSON.stringify(type.literalValue)}, received ${JSON.stringify(value)}`
+                        }
+                    ];
+                }
+                return [];
+            }
+        case "enum":
+            {
+                const allowedMembers = schema.enums[type.name];
+                if (!allowedMembers) {
+                    return [
+                        {
+                            path,
+                            message: `Unknown enum "${type.name}" in schema`
+                        }
+                    ];
+                }
+                if (typeof value !== "string" || allowedMembers.includes(value) === false) {
+                    return [
+                        {
+                            path,
+                            message: `Invalid value ${JSON.stringify(value)} for enum ${type.name}. Expected one of: ${allowedMembers.map((member) => JSON.stringify(member)).join(", ")}`
+                        }
+                    ];
+                }
+                return [];
+            }
+        case "record":
+            {
+                if (typeof value !== "object" || value === null || Array.isArray(value) === true) {
+                    return [
+                        {
+                            path,
+                            message: `Expected object, received ${value === null ? "null" : Array.isArray(value) ? "array" : typeof value}`
+                        }
+                    ];
+                }
+                return [];
+            }
+        case "array":
+            {
+                if (Array.isArray(value) === false) {
+                    return [
+                        {
+                            path,
+                            message: `Expected array, received ${typeof value}`
+                        }
+                    ];
+                }
+                if (propertyConstraints?.minItems !== undefined && value.length < propertyConstraints.minItems) {
+                    return [
+                        {
+                            path,
+                            message: `Array must contain at least ${propertyConstraints.minItems} item(s)`
+                        }
+                    ];
+                }
+                if (propertyConstraints?.maxItems !== undefined && value.length > propertyConstraints.maxItems) {
+                    return [
+                        {
+                            path,
+                            message: `Array must contain at most ${propertyConstraints.maxItems} item(s)`
+                        }
+                    ];
+                }
+                if (type.elementType) {
+                    const collectedIssues = [];
+                    for (let itemIndex = 0; itemIndex < value.length; itemIndex++) {
+                        const itemPath = `${path}[${itemIndex}]`;
+                        const itemIssues = validateValue(value[itemIndex], type.elementType, schema, itemPath);
+                        collectedIssues.push(...itemIssues);
+                    }
+                    return collectedIssues;
+                }
+                return [];
+            }
+        case "union":
+            {
+                const variantTypes = type.unionTypes ?? [];
+                let bestCandidateIssues = [];
+                let hasMatchedVariant = false;
+                for (const variant of variantTypes) {
+                    const variantIssues = validateValue(value, variant, schema, path);
+                    if (variantIssues.length === 0) {
+                        hasMatchedVariant = true;
+                        break;
+                    }
+                    if (bestCandidateIssues.length === 0 || variantIssues.length < bestCandidateIssues.length) {
+                        bestCandidateIssues = variantIssues;
+                    }
+                }
+                if (hasMatchedVariant === false) {
+                    const failureDetail = bestCandidateIssues[0]?.message ?? "no variant matched";
+                    return [
+                        {
+                            path,
+                            message: `Value does not match any union variant for "${type.name}". Reason: ${failureDetail}`
+                        }
+                    ];
+                }
+                return [];
+            }
+        case "model":
+            {
+                if (schema.unions[type.name]) {
+                    const namedUnionVariants = schema.unions[type.name];
+                    return validateValue(value, {
+                        kind: "union",
+                        name: type.name,
+                        unionTypes: namedUnionVariants
+                    }, schema, path);
+                }
+                const model = schema.models[type.name];
+                if (!model) {
+                    return [
+                        {
+                            path,
+                            message: `Unknown model "${type.name}" in schema`
+                        }
+                    ];
+                }
+                if (typeof value !== "object" || value === null || Array.isArray(value) === true) {
+                    return [
+                        {
+                            path,
+                            message: `Expected object for model "${type.name}", received ${value === null ? "null" : Array.isArray(value) ? "array" : typeof value}`
+                        }
+                    ];
+                }
+                const recordValue = value;
+                const allProperties = collectModelProperties(type.name, schema);
+                const modelIssues = [];
+                for (const property of allProperties) {
+                    const propertyPath = path.length > 0 ? `${path}.${property.name}` : property.name;
+                    const propertyValue = recordValue[property.name];
+                    if (propertyValue === undefined) {
+                        if (property.optional === false) {
+                            modelIssues.push({
+                                path: propertyPath,
+                                message: `Missing required property "${property.name}"`
+                            });
+                        }
+                        continue;
+                    }
+                    const propertyIssues = validateValue(propertyValue, property.type, schema, propertyPath, property);
+                    modelIssues.push(...propertyIssues);
+                }
+                return modelIssues;
+            }
+    }
+}
+function createValidationSuccess(data) {
+    return {
+        success: true,
+        data
+    };
+}
+function createValidationFailure(issues) {
+    const firstIssueMessage = issues[0]?.message ?? "Validation failed";
+    return {
+        success: false,
+        error: {
+            message: firstIssueMessage,
+            issues
+        },
+        issues
+    };
+}
+export function validateModel(value, modelName, schema = INTENT_SCHEMA_DESCRIPTION) {
+    const issues = validateValue(value, { kind: "model", name: modelName }, schema, "");
+    if (issues.length === 0) {
+        return createValidationSuccess(value);
+    }
+    return createValidationFailure(issues);
+}
+export function validateIntent(value, schema = INTENT_SCHEMA_DESCRIPTION) {
+    if (typeof value !== "object" || value === null || Array.isArray(value) === true) {
+        return createValidationFailure([
+            {
+                path: "",
+                message: `Expected intent object, received ${value === null ? "null" : Array.isArray(value) ? "array" : typeof value}`
+            }
+        ]);
+    }
+    const recordValue = value;
+    const candidateIntentNames = schema.intents.filter((candidateName) => {
+        const model = schema.models[candidateName];
+        if (!model) {
+            return false;
+        }
+        return model.properties.some((property) => property.optional === false && property.name in recordValue);
+    });
+    if (candidateIntentNames.length === 0) {
+        return createValidationFailure([
+            {
+                path: "",
+                message: "Object does not match any recognized intent structure"
+            }
+        ]);
+    }
+    let bestFailureResult = null;
+    for (const candidateName of candidateIntentNames) {
+        const candidateResult = validateModel(value, candidateName, schema);
+        if (candidateResult.success === true) {
+            return candidateResult;
+        }
+        if (bestFailureResult === null || candidateResult.issues.length < bestFailureResult.issues.length) {
+            bestFailureResult = candidateResult;
+        }
+    }
+    return bestFailureResult ?? createValidationFailure([
+        {
+            path: "",
+            message: "Intent validation failed"
+        }
+    ]);
+}