@phoundry/phials-plugin-sdk 1.0.0

package/file-types.generated.d.ts

@@ -0,0 +1,239 @@
+// @generated from phials - do not edit
+// Source graph: phials/scripts/lib/public-sdk-manifest.mjs
+
+/**
+ * File type categories for plugin matching and UI display
+ * Format: 'broad-category' or 'broad-category - specific'
+ */
+type FileCategory =
+	// Images
+	| "image"
+	| "image - vector"
+	| "image - raw"
+	// Video
+	| "video"
+	// Audio
+	| "audio - lossless"
+	| "audio - lossy"
+	| "audio - midi"
+	// Documents
+	| "document"
+	| "ebook"
+	| "spreadsheet"
+	| "presentation"
+	// Code & Data
+	| "code"
+	| "code - data"
+	| "code - config"
+	| "code - markup"
+	// 3D & CAD
+	| "model"
+	| "cad"
+	// Archives & Packages
+	| "archive"
+	| "archive - disk"
+	| "archive - package"
+	// System
+	| "executable"
+	| "database"
+	| "font"
+	| "folder"
+	| "unknown";
+
+/**
+ * Core file entry interface - file-type agnostic
+ * Represents a file or directory in the filesystem
+ */
+interface FileEntry {
+	name: string;
+	path: string;
+	/**
+	 * Host-resolved Iconify glyph. Public directory-listing APIs populate this
+	 * so plugins share Phials' canonical file and folder icon policy.
+	 */
+	icon?: string;
+	is_file: boolean;
+	is_dir: boolean;
+	is_vial: boolean;
+	/** Nested vial folder when listing inside a parent vial */
+	isChildVial?: boolean;
+	/** Listing node is a symlink or Windows directory junction */
+	is_symlink?: boolean;
+	/** Resolved absolute target when healthy; stored link text when broken */
+	symlink_target?: string | null;
+	symlink_broken?: boolean;
+	size: number;
+	created?: number | null;
+	modified?: number | null;
+	/** Raw metadata from filesystem/EXIF - parsed lazily by plugins */
+	exif_data: Record<string, string> | null;
+	/** Computed lazily based on extension */
+	mimeType?: string;
+	/** Computed lazily based on extension */
+	category?: FileCategory;
+}
+
+/**
+ * Sort modes available for file listings.
+ * Can be a standard property ('name', 'created', 'modified', 'size')
+ * or a collection property ID.
+ */
+type SortMode = string;
+
+/**
+ * Sort order direction
+ */
+type SortOrder = "asc" | "desc";
+
+/**
+ * View modes for file browser
+ */
+type ViewMode =
+	| "details"
+	| "thumbnails"
+	| "column"
+	| "tree"
+	| "boards"
+	| "gallery"
+	| "calendar";
+
+/** Calendar view zoom level */
+type CalendarScope = "year" | "month" | "week" | "3day" | "day";
+
+/** Built-in calendar date sources (`created`, `modified`) or a vial property id */
+type CalendarDateSourceId = "created" | "modified" | (string & {});
+
+/**
+ * Filter scope for directory listing (current folder vs flatten-with-filters).
+ */
+type FilterScope = "current" | "flatten";
+
+// ─── Multi-Sort Types ─────────────────────────────────────────────────────────
+
+/**
+ * A single sort criterion for multi-level sorting
+ */
+interface SortCriteria {
+	/** Property to sort by: 'name', 'size', 'created', 'modified', 'type', 'extension', or collection property ID */
+	property: string;
+	/** Sort direction */
+	order: SortOrder;
+}
+
+// ─── Multi-Filter Types ───────────────────────────────────────────────────────
+
+/**
+ * Filter operators for text properties
+ */
+type TextFilterOp =
+	| "contains"
+	| "not_contains"
+	| "equals"
+	| "not_equals"
+	| "starts_with"
+	| "ends_with"
+	| "is_empty"
+	| "is_not_empty";
+
+/**
+ * Filter operators for number properties
+ */
+type NumberFilterOp =
+	"eq" | "neq" | "lt" | "gt" | "lte" | "gte" | "is_empty" | "is_not_empty";
+
+/**
+ * Filter operators for date properties
+ */
+type DateFilterOp =
+	| "is"
+	| "is_not"
+	| "is_before"
+	| "is_after"
+	| "is_on_or_before"
+	| "is_on_or_after"
+	| "is_empty"
+	| "is_not_empty";
+
+/**
+ * Filter operators for select/status properties
+ */
+type SelectFilterOp = "is" | "is_not" | "is_empty" | "is_not_empty";
+
+/**
+ * Filter operators for multi-select properties
+ */
+type MultiSelectFilterOp =
+	"contains" | "not_contains" | "is_empty" | "is_not_empty";
+
+/**
+ * Filter operators for boolean properties
+ */
+type BooleanFilterOp = "is" | "is_not";
+
+/** @deprecated Migrated to `is` + `true` on load */
+type LegacyBooleanFilterOp = "is_true" | "is_false";
+
+/**
+ * Union of all filter operators
+ */
+type FilterOperator =
+	| TextFilterOp
+	| NumberFilterOp
+	| DateFilterOp
+	| SelectFilterOp
+	| MultiSelectFilterOp
+	| BooleanFilterOp
+	| LegacyBooleanFilterOp;
+
+/**
+ * Size unit for file size filters
+ */
+type SizeUnit = "B" | "KB" | "MB" | "GB";
+
+/**
+ * A single filter condition
+ */
+interface FilterCondition {
+	/** Unique identifier for the condition */
+	id: string;
+	/** Property to filter by: 'name', 'extension', 'size', 'created', 'modified', or collection property ID */
+	property: string;
+	/** Filter operator */
+	operator: FilterOperator;
+	/** Filter value (type depends on property type) */
+	value?: string | number | boolean | string[];
+	/** Size unit for file size filters (default: MB) */
+	sizeUnit?: SizeUnit;
+}
+
+/** Leaf node in a filter tree */
+interface FilterConditionNode extends FilterCondition {
+	type: "condition";
+}
+
+/** Nested filter sub-group node */
+interface FilterSubGroupNode {
+	type: "group";
+	/** Unique identifier for the sub-group */
+	id: string;
+	/** Logic operator for combining direct children */
+	logic: "and" | "or";
+	/** Child conditions and nested sub-groups */
+	children: FilterNode[];
+}
+
+/** Discriminated node in a filter tree */
+type FilterNode = FilterConditionNode | FilterSubGroupNode;
+
+/** Root filter group id sentinel - `null` means the root group in tree APIs */
+type FilterGroupId = string | null;
+
+/**
+ * Filter tree root: conditions and nested sub-groups combined with AND/OR logic
+ */
+interface FilterGroup {
+	/** Logic operator for combining direct children */
+	logic: "and" | "or";
+	/** Child conditions and nested sub-groups */
+	children: FilterNode[];
+}

package/manifest-schema.js

@@ -0,0 +1,307 @@
+// @generated from phials - do not edit
+// Source graph: phials/scripts/lib/public-sdk-manifest.mjs
+/**
+ * Human-readable descriptions for each permission
+ */
+export const PERMISSION_DESCRIPTIONS = {
+    "filesystem.read": "Read files from your filesystem",
+    "filesystem.write": "Write and delete files on your filesystem",
+    "clipboard.read": "Read content from your clipboard",
+    "clipboard.write": "Write content to your clipboard",
+    "network.fetch": "Make network requests to external servers",
+    "workspace-folders.read": "Read Workspace Folder schemas and values",
+    "workspace-folders.write": "Change Workspace Folder schemas and values",
+};
+/**
+ * Risk level for each permission (for UI display)
+ */
+export const PERMISSION_RISK = {
+    "filesystem.read": "low",
+    "filesystem.write": "high",
+    "clipboard.read": "medium",
+    "clipboard.write": "low",
+    "network.fetch": "medium",
+    "workspace-folders.read": "medium",
+    "workspace-folders.write": "high",
+};
+const MANIFEST_FIELDS = new Set([
+    "id",
+    "name",
+    "version",
+    "minAppVersion",
+    "pluginApiVersion",
+    "author",
+    "description",
+    "authorUrl",
+    "repository",
+    "icons",
+    "permissions",
+]);
+const VALID_PERMISSIONS = new Set([
+    "filesystem.read",
+    "filesystem.write",
+    "clipboard.read",
+    "clipboard.write",
+    "network.fetch",
+    "workspace-folders.read",
+    "workspace-folders.write",
+]);
+const IMPLIED_PERMISSION_PAIRS = [
+    ["filesystem.write", "filesystem.read"],
+    ["workspace-folders.write", "workspace-folders.read"],
+];
+const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const ICONIFY_ICON_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+/**
+ * Validate a plugin ID format
+ * Must be in format: vendor.plugin-name (lowercase, alphanumeric with hyphens)
+ */
+export function validatePluginId(id) {
+    const pattern = /^[a-z][a-z0-9]*\.[a-z][a-z0-9-]*[a-z0-9]$/;
+    return pattern.test(id) && !id.startsWith("phials.");
+}
+/**
+ * Validate complete SemVer 2.0.0 syntax.
+ */
+export function validateSemver(version) {
+    return SEMVER_PATTERN.test(version);
+}
+/**
+ * Compare two semver versions
+ * Returns: -1 if a < b, 0 if a == b, 1 if a > b
+ */
+export function compareSemver(a, b) {
+    if (!validateSemver(a) || !validateSemver(b)) {
+        throw new Error("compareSemver requires valid SemVer values");
+    }
+    const parseVersion = (value) => {
+        const match = SEMVER_PATTERN.exec(value);
+        return {
+            core: [Number(match[1]), Number(match[2]), Number(match[3])],
+            pre: match[4]?.split(".") ?? [],
+        };
+    };
+    const left = parseVersion(a);
+    const right = parseVersion(b);
+    for (let i = 0; i < 3; i++) {
+        const aVal = left.core[i] ?? 0;
+        const bVal = right.core[i] ?? 0;
+        if (aVal < bVal)
+            return -1;
+        if (aVal > bVal)
+            return 1;
+    }
+    if (left.pre.length === 0 && right.pre.length === 0)
+        return 0;
+    if (left.pre.length === 0)
+        return 1;
+    if (right.pre.length === 0)
+        return -1;
+    for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i++) {
+        const aPart = left.pre[i];
+        const bPart = right.pre[i];
+        if (aPart === undefined)
+            return -1;
+        if (bPart === undefined)
+            return 1;
+        if (aPart === bPart)
+            continue;
+        const aNumeric = /^\d+$/.test(aPart);
+        const bNumeric = /^\d+$/.test(bPart);
+        if (aNumeric && bNumeric) {
+            return Number(aPart) < Number(bPart) ? -1 : 1;
+        }
+        if (aNumeric !== bNumeric)
+            return aNumeric ? -1 : 1;
+        return aPart < bPart ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * Check if a version satisfies a minimum version requirement
+ */
+export function satisfiesMinVersion(version, minVersion) {
+    return compareSemver(version, minVersion) >= 0;
+}
+export function definePluginManifest(manifest) {
+    const result = validateManifest(manifest);
+    if (!result.valid) {
+        throw new Error(`Invalid plugin manifest: ${result.errors.join("; ")}`);
+    }
+    return Object.freeze({
+        ...manifest,
+        permissions: manifest.permissions ?
+            Object.freeze([...manifest.permissions])
+            : undefined,
+        icons: manifest.icons ? Object.freeze([...manifest.icons]) : undefined,
+    });
+}
+export function manifestIdentity(manifest) {
+    return {
+        id: manifest.id,
+        version: manifest.version,
+        minAppVersion: manifest.minAppVersion,
+        pluginApiVersion: manifest.pluginApiVersion,
+    };
+}
+export function validateIdentityProjections(identity, projections) {
+    const errors = [];
+    for (const projection of projections) {
+        for (const field of [
+            "id",
+            "version",
+            "minAppVersion",
+            "pluginApiVersion",
+        ]) {
+            const value = projection[field];
+            if (value !== undefined && value !== identity[field]) {
+                errors.push(`${projection.source}.${field} "${value}" does not match manifest "${identity[field]}"`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+export function definePlugin(manifest, definition) {
+    const validManifest = definePluginManifest(manifest);
+    return Object.freeze({
+        ...definition,
+        id: validManifest.id,
+        name: validManifest.name,
+        version: validManifest.version,
+    });
+}
+/**
+ * Supported public plugin API contract for this app build.
+ * Keep in sync with `SUPPORTED_PLUGIN_API_VERSION` in `src-tauri/src/lib.rs`.
+ */
+export const SUPPORTED_PLUGIN_API_VERSION = "1.0.0";
+/**
+ * Validate a plugin manifest
+ */
+export function validateManifest(manifest) {
+    const errors = [];
+    if (!manifest || typeof manifest !== "object") {
+        return { valid: false, errors: ["Manifest must be an object"] };
+    }
+    const m = manifest;
+    const unknownFields = Object.keys(m).filter((field) => !MANIFEST_FIELDS.has(field));
+    if (unknownFields.length > 0) {
+        errors.push(`Unknown manifest field(s): ${unknownFields.join(", ")}`);
+    }
+    // Required fields
+    if (typeof m.id !== "string" || !m.id.trim()) {
+        errors.push('Missing or invalid "id" field');
+    }
+    else if (!validatePluginId(m.id)) {
+        errors.push('Invalid or reserved "id". Use lowercase vendor.plugin-name and do not use the "phials." namespace');
+    }
+    if (typeof m.name !== "string" || !m.name.trim()) {
+        errors.push('Missing or invalid "name" field');
+    }
+    if (typeof m.version !== "string" || !m.version.trim()) {
+        errors.push('Missing or invalid "version" field');
+    }
+    else if (!validateSemver(m.version)) {
+        errors.push('Invalid "version" format. Must be semver (e.g., "1.0.0")');
+    }
+    if (typeof m.minAppVersion !== "string" || !m.minAppVersion.trim()) {
+        errors.push('Missing or invalid "minAppVersion" field');
+    }
+    else if (!validateSemver(m.minAppVersion)) {
+        errors.push('Invalid "minAppVersion" format. Must be semver (e.g., "0.1.0")');
+    }
+    if (typeof m.pluginApiVersion !== "string" || !m.pluginApiVersion.trim()) {
+        errors.push('Missing or invalid "pluginApiVersion" field');
+    }
+    else if (m.pluginApiVersion !== SUPPORTED_PLUGIN_API_VERSION) {
+        errors.push(`Invalid "pluginApiVersion": expected exactly "${SUPPORTED_PLUGIN_API_VERSION}"`);
+    }
+    if (typeof m.author !== "string" || !m.author.trim()) {
+        errors.push('Missing or invalid "author" field');
+    }
+    if (typeof m.description !== "string" || !m.description.trim()) {
+        errors.push('Missing or invalid "description" field');
+    }
+    // Optional fields
+    for (const field of ["authorUrl", "repository"]) {
+        const value = m[field];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "string" || !value.trim()) {
+            errors.push(`Invalid "${field}" field - must be a non-empty HTTPS URL`);
+            continue;
+        }
+        try {
+            const url = new URL(value);
+            if (url.protocol !== "https:" || url.username || url.password) {
+                errors.push(`Invalid "${field}" field - must be a public HTTPS URL`);
+            }
+        }
+        catch {
+            errors.push(`Invalid "${field}" field - must be a public HTTPS URL`);
+        }
+    }
+    if (m.icons !== undefined) {
+        if (!Array.isArray(m.icons)) {
+            errors.push('Invalid "icons" field - must be an array');
+        }
+        else {
+            const seen = new Set();
+            for (const icon of m.icons) {
+                if (typeof icon !== "string" ||
+                    !icon.trim() ||
+                    !ICONIFY_ICON_PATTERN.test(icon)) {
+                    errors.push(`Invalid icon: "${String(icon)}"`);
+                }
+                else if (seen.has(icon)) {
+                    errors.push(`Duplicate icon: "${icon}"`);
+                }
+                else {
+                    seen.add(icon);
+                }
+            }
+        }
+    }
+    if (m.permissions !== undefined) {
+        if (!Array.isArray(m.permissions)) {
+            errors.push('Invalid "permissions" field - must be an array');
+        }
+        else {
+            const seen = new Set();
+            for (const p of m.permissions) {
+                if (!VALID_PERMISSIONS.has(p)) {
+                    errors.push(`Invalid permission: "${p}"`);
+                }
+                else if (seen.has(p)) {
+                    errors.push(`Duplicate permission: "${p}"`);
+                }
+                else {
+                    seen.add(p);
+                }
+            }
+            for (const [write, read] of IMPLIED_PERMISSION_PAIRS) {
+                if (seen.has(write) && seen.has(read)) {
+                    errors.push(`Redundant permissions: "${write}" already implies "${read}"`);
+                }
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Parse and validate a manifest JSON string
+ */
+export function parseManifest(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return { manifest: null, errors: ["Invalid JSON"] };
+    }
+    const result = validateManifest(parsed);
+    if (!result.valid) {
+        return { manifest: null, errors: result.errors };
+    }
+    return { manifest: parsed, errors: [] };
+}