@moloodev/editor-sdk 0.0.0-stage → 0.1.0

package/src/commands/manifest/editor-document.ts

@@ -0,0 +1,501 @@
+import {
+  isQualifiedName,
+  isStorageMode,
+  type AssetTypeIcon,
+  type StorageMode,
+} from "@moloodev/platform";
+import { parseNetwork } from "@moloodev/platform/network";
+import type { ContributionManifest } from "./types";
+import { validateManifest } from "./validate-manifest";
+
+export const TABLER_ICON_URI_PREFIX = "tabler:";
+const TABLER_ICON_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
+
+export function parseTablerIconUri(value: string): string | null {
+  if (!value.startsWith(TABLER_ICON_URI_PREFIX)) return null;
+  const name = value.slice(TABLER_ICON_URI_PREFIX.length);
+  return TABLER_ICON_NAME.test(name) ? name : null;
+}
+
+export const EDITOR_CAPABILITIES = ["import", "download"] as const;
+
+export type EditorCapability = (typeof EDITOR_CAPABILITIES)[number];
+
+export type EditorContributes = Pick<
+  ContributionManifest,
+  "commands" | "menus" | "keybindings" | "configuration"
+>;
+
+export type EditorFileMatcher = {
+  /** File extensions with leading dot, supporting compound extensions (e.g. [".layout.json"], [".md", ".markdown"]). */
+  extensions?: string[];
+  /** MIME types or wildcard families (e.g. ["text/markdown"], ["application/json"]). */
+  mimeTypes?: string[];
+  /** Exact JSON $schema URI match (e.g. "https://moloo.dev/schemas/layout/v1.json"). */
+  schema?: string;
+  /** Storage mode required by this editor ("json" | "text" | "blob"). */
+  storageMode?: StorageMode;
+  /** Display label for this file type in the browser (e.g. "레이아웃", "마크다운"). */
+  label?: string;
+  /** Tabler icon URI (`tabler:{name}`) for files matching this rule. */
+  icon?: AssetTypeIcon;
+  /** Badge tint color (`#rrggbb`) for files matching this rule. */
+  color?: string;
+};
+
+/** Product editor document. Contributions live under `contributes`. */
+export type EditorManifest = {
+  id: string;
+  title: string;
+  description?: string;
+  path: string;
+  acceptedTypes: string[];
+  fileTypes?: EditorFileMatcher[];
+  templates?: EditorTemplate[];
+  categories?: string[];
+  /** Host-resolved Tabler icon URI (`tabler:{name}`). */
+  icon?: string;
+  /** Optional host I/O the editor implements (`editor.import` / `editor.download`). */
+  capabilities?: EditorCapability[];
+  importAccept?: string;
+  layoutVersion?: number;
+  /** HTTPS origins this document may contact. Omitted means none. */
+  network?: string[];
+  contributes?: EditorContributes;
+};
+
+const CONTRIBUTION_KEYS = [
+  "commands",
+  "menus",
+  "keybindings",
+  "configuration",
+] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Invalid editor manifest: ${field} is required`);
+  }
+  return value;
+}
+
+function requireEditorIdentifier(id: string): string {
+  if (!isQualifiedName(id)) {
+    throw new Error(
+      "Invalid editor id: must be publisher.name (VS Code extension identifier)",
+    );
+  }
+  return id;
+}
+
+export function parseEditorCapabilities(input: unknown): EditorCapability[] {
+  if (!Array.isArray(input)) {
+    throw new Error("Invalid editor manifest: capabilities must be an array");
+  }
+  return input.map((value, index) => {
+    const capability = EDITOR_CAPABILITIES.find((item) => item === value);
+    if (capability === undefined) {
+      throw new Error(
+        `Invalid editor manifest: capabilities.${index} is not a known capability`,
+      );
+    }
+    return capability;
+  });
+}
+
+function parseEditorFileMatchers(input: unknown): EditorFileMatcher[] {
+  if (!Array.isArray(input)) {
+    throw new Error("Invalid editor manifest: fileTypes must be an array");
+  }
+  return input.map((entry, index) => {
+    if (!isRecord(entry)) {
+      throw new Error(
+        `Invalid editor manifest: fileTypes.${index} must be an object`,
+      );
+    }
+    let extensions: string[] | undefined;
+    if (entry.extensions != null) {
+      if (!Array.isArray(entry.extensions) || entry.extensions.length === 0) {
+        throw new Error(
+          `Invalid editor manifest: fileTypes.${index}.extensions must be a non-empty array`,
+        );
+      }
+      extensions = entry.extensions.map((ext, extIdx) => {
+        const value = requireString(
+          ext,
+          `fileTypes.${index}.extensions.${extIdx}`,
+        );
+        if (!value.startsWith(".") || value.length < 2) {
+          throw new Error(
+            `Invalid editor manifest: fileTypes.${index}.extensions.${extIdx} must start with .`,
+          );
+        }
+        return value.toLowerCase();
+      });
+    }
+
+    let mimeTypes: string[] | undefined;
+    if (entry.mimeTypes != null) {
+      if (!Array.isArray(entry.mimeTypes) || entry.mimeTypes.length === 0) {
+        throw new Error(
+          `Invalid editor manifest: fileTypes.${index}.mimeTypes must be a non-empty array`,
+        );
+      }
+      mimeTypes = entry.mimeTypes.map((mime, mimeIdx) => {
+        const value = requireString(
+          mime,
+          `fileTypes.${index}.mimeTypes.${mimeIdx}`,
+        );
+        if (!value.includes("/")) {
+          throw new Error(
+            `Invalid editor manifest: fileTypes.${index}.mimeTypes.${mimeIdx} must be a MIME type`,
+          );
+        }
+        return value.toLowerCase();
+      });
+    }
+
+    let schema: string | undefined;
+    if (entry.schema != null) {
+      schema = requireString(entry.schema, `fileTypes.${index}.schema`);
+      try {
+        const parsed = new URL(schema);
+        if (parsed.protocol !== "https:") {
+          throw new Error("not https");
+        }
+      } catch {
+        throw new Error(
+          `Invalid editor manifest: fileTypes.${index}.schema must be an https URI`,
+        );
+      }
+    }
+
+    if (!extensions && !mimeTypes && !schema) {
+      throw new Error(
+        `Invalid editor manifest: fileTypes.${index} must declare at least one of extensions, mimeTypes, or schema`,
+      );
+    }
+
+    let storageMode: StorageMode | undefined;
+    if (entry.storageMode != null) {
+      if (!isStorageMode(entry.storageMode)) {
+        throw new Error(
+          `Invalid editor manifest: fileTypes.${index}.storageMode must be json, text, or blob`,
+        );
+      }
+      storageMode = entry.storageMode;
+    }
+
+    let label: string | undefined;
+    if (entry.label != null) {
+      label = requireString(entry.label, `fileTypes.${index}.label`);
+    }
+
+    let icon: AssetTypeIcon | undefined;
+    if (entry.icon != null) {
+      const rawIcon = requireString(entry.icon, `fileTypes.${index}.icon`);
+      if (parseTablerIconUri(rawIcon) === null) {
+        throw new Error(
+          `Invalid editor manifest: fileTypes.${index}.icon must be tabler:{name}`,
+        );
+      }
+      icon = rawIcon as AssetTypeIcon;
+    }
+
+    let color: string | undefined;
+    if (entry.color != null) {
+      const rawColor = requireString(entry.color, `fileTypes.${index}.color`);
+      if (!HEX_COLOR.test(rawColor)) {
+        throw new Error(
+          `Invalid editor manifest: fileTypes.${index}.color must be #rrggbb`,
+        );
+      }
+      color = rawColor.toLowerCase();
+    }
+
+    return {
+      ...(extensions ? { extensions } : {}),
+      ...(mimeTypes ? { mimeTypes } : {}),
+      ...(schema ? { schema } : {}),
+      ...(storageMode ? { storageMode } : {}),
+      ...(label ? { label } : {}),
+      ...(icon ? { icon } : {}),
+      ...(color ? { color } : {}),
+    };
+  });
+}
+
+
+function parseEditorTemplates(input: unknown): EditorTemplate[] {
+  if (!Array.isArray(input)) {
+    throw new Error("Invalid editor manifest: templates must be an array");
+  }
+  const ids = new Set<string>();
+  return input.map((entry, index) => {
+    if (!isRecord(entry)) {
+      throw new Error(`Invalid editor manifest: templates.${index} must be an object`);
+    }
+    const id = requireString(entry.id, `templates.${index}.id`);
+    if (ids.has(id)) {
+      throw new Error(`Invalid editor manifest: duplicate template ${id}`);
+    }
+    ids.add(id);
+    const label = requireString(entry.label, `templates.${index}.label`);
+    const description = requireString(entry.description, `templates.${index}.description`);
+    const type = requireString(entry.type, `templates.${index}.type`);
+    const defaultName = requireString(entry.defaultName, `templates.${index}.defaultName`);
+    let icon: string | undefined;
+    if (entry.icon != null) {
+      icon = requireString(entry.icon, `templates.${index}.icon`);
+      if (parseTablerIconUri(icon) === null) {
+        throw new Error(`Invalid editor manifest: templates.${index}.icon must be tabler:{name}`);
+      }
+    }
+    let previewClassName: string | undefined;
+    if (entry.previewClassName != null) {
+      previewClassName = requireString(entry.previewClassName, `templates.${index}.previewClassName`);
+    }
+    let storageMode: StorageMode | undefined;
+    if (entry.storageMode != null) {
+      if (!isStorageMode(entry.storageMode)) {
+        throw new Error(`Invalid editor manifest: templates.${index}.storageMode must be json, text, or blob`);
+      }
+      storageMode = entry.storageMode;
+    }
+    let contentType: string | undefined;
+    if (entry.contentType != null) {
+      contentType = requireString(entry.contentType, `templates.${index}.contentType`);
+    }
+    let schema: string | undefined;
+    if (entry.schema != null) {
+      schema = requireString(entry.schema, `templates.${index}.schema`);
+    }
+    let payload: Record<string, unknown> | undefined;
+    if (entry.payload != null) {
+      if (!isRecord(entry.payload)) {
+        throw new Error(`Invalid editor manifest: templates.${index}.payload must be an object`);
+      }
+      payload = entry.payload;
+    }
+    return {
+      id,
+      label,
+      description,
+      ...(icon ? { icon } : {}),
+      ...(previewClassName ? { previewClassName } : {}),
+      type,
+      defaultName,
+      ...(storageMode ? { storageMode } : {}),
+      ...(contentType ? { contentType } : {}),
+      ...(schema ? { schema } : {}),
+      ...(payload ? { payload } : {}),
+    };
+  });
+}
+
+/** Shape validation for editor documents. A missing `network` becomes []. Throws on failure. */
+export function validateEditorManifest(
+  input: unknown,
+): EditorManifest & { network: string[] } {
+  if (!isRecord(input)) {
+    throw new Error("Invalid editor manifest: expected an object");
+  }
+  if ("activation" in input) {
+    throw new Error(
+      "Invalid editor manifest: activation belongs on contribution packs, not editor documents",
+    );
+  }
+  if ("editor" in input) {
+    throw new Error(
+      "Invalid editor manifest: chrome fields belong at the top level, not under editor",
+    );
+  }
+  for (const key of CONTRIBUTION_KEYS) {
+    if (key in input) {
+      throw new Error(
+        `Invalid editor manifest: ${key} must live under contributes`,
+      );
+    }
+  }
+
+  const id = requireEditorIdentifier(requireString(input.id, "id"));
+  const title = requireString(input.title, "title");
+  const path = requireString(input.path, "path");
+  if (!path.startsWith("/")) {
+    throw new Error("Invalid editor manifest: path must start with /");
+  }
+  let fileTypes: EditorFileMatcher[] | undefined;
+  if (input.fileTypes != null) {
+    fileTypes = parseEditorFileMatchers(input.fileTypes);
+  }
+  let templates: EditorTemplate[] | undefined;
+  if (input.templates != null) {
+    templates = parseEditorTemplates(input.templates);
+  }
+
+  if (input.acceptedTypes == null && fileTypes === undefined) {
+    throw new Error("Invalid editor manifest: acceptedTypes is required");
+  }
+  if (input.acceptedTypes != null && !Array.isArray(input.acceptedTypes)) {
+    throw new Error("Invalid editor manifest: acceptedTypes is required");
+  }
+  const acceptedTypes = Array.isArray(input.acceptedTypes)
+    ? input.acceptedTypes.map((type, index) => {
+        if (typeof type !== "string" || type.length === 0) {
+          throw new Error(
+            `Invalid editor manifest: acceptedTypes.${index} must be a non-empty string`,
+          );
+        }
+        if (!isQualifiedName(type)) {
+          throw new Error(
+            `Invalid editor manifest: acceptedTypes.${index} must be publisher.name`,
+          );
+        }
+        return type;
+      })
+    : [];
+
+  let description: string | undefined;
+  if (input.description != null) {
+    description = requireString(input.description, "description");
+  }
+  let icon: string | undefined;
+  if (input.icon != null) {
+    icon = requireString(input.icon, "icon");
+    if (parseTablerIconUri(icon) === null) {
+      throw new Error("Invalid editor manifest: icon must be tabler:{name}");
+    }
+  }
+  if ("order" in input) {
+    throw new Error(
+      "Invalid editor manifest: order belongs on workspace favorites, not editor documents",
+    );
+  }
+
+  let categories: string[] | undefined;
+  if (input.categories != null) {
+    if (!Array.isArray(input.categories))
+      throw new Error("Invalid editor manifest: categories must be an array");
+    categories = input.categories.map((value, index) =>
+      requireString(value, `categories.${index}`),
+    );
+  }
+
+  let capabilities: EditorCapability[] | undefined;
+  if (input.capabilities != null) {
+    capabilities = parseEditorCapabilities(input.capabilities);
+  }
+
+  let importAccept: string | undefined;
+  if (input.importAccept != null) {
+    importAccept = requireString(input.importAccept, "importAccept");
+  }
+
+  let layoutVersion: number | undefined;
+  if (input.layoutVersion != null) {
+    if (
+      typeof input.layoutVersion !== "number" ||
+      !Number.isInteger(input.layoutVersion) ||
+      input.layoutVersion < 1
+    ) {
+      throw new Error(
+        "Invalid editor manifest: layoutVersion must be a positive integer",
+      );
+    }
+    layoutVersion = input.layoutVersion;
+  }
+
+  const network = parseNetwork("network" in input ? input.network : undefined);
+
+  let contributes: EditorContributes | undefined;
+  if (input.contributes != null) {
+    if (!isRecord(input.contributes)) {
+      throw new Error("Invalid editor manifest: contributes must be an object");
+    }
+    const contribution = validateManifest({
+      id,
+      activation: "exact",
+      ...input.contributes,
+    });
+    contributes = {
+      commands: contribution.commands,
+      menus: contribution.menus,
+      keybindings: contribution.keybindings,
+      configuration: contribution.configuration,
+    };
+  }
+
+  return {
+    id,
+    title,
+    ...(description ? { description } : {}),
+    path,
+    acceptedTypes,
+    ...(fileTypes ? { fileTypes } : {}),
+    ...(templates ? { templates } : {}),
+    ...(icon ? { icon } : {}),
+    ...(categories ? { categories } : {}),
+    ...(capabilities ? { capabilities } : {}),
+    ...(importAccept ? { importAccept } : {}),
+    ...(layoutVersion !== undefined ? { layoutVersion } : {}),
+    network,
+    ...(contributes ? { contributes } : {}),
+  };
+}
+
+export type EditorManifestInput = Omit<
+  EditorManifest,
+  "acceptedTypes" | "categories" | "capabilities" | "contributes"
+> & {
+  acceptedTypes?: string[];
+  fileTypes?: EditorFileMatcher[];
+  templates?: EditorTemplate[];
+  categories?: string[];
+  capabilities?: EditorCapability[];
+  contributes?: {
+    commands?: NonNullable<EditorContributes["commands"]>;
+    menus?: NonNullable<EditorContributes["menus"]>;
+    keybindings?: NonNullable<EditorContributes["keybindings"]>;
+    configuration?: EditorContributes["configuration"];
+  };
+};
+
+export function defineEditorManifest(input: EditorManifestInput) {
+  const manifest = {
+    ...input,
+    acceptedTypes: input.acceptedTypes ?? [],
+    ...(input.fileTypes ? { fileTypes: input.fileTypes } : {}),
+    ...(input.templates ? { templates: input.templates } : {}),
+    categories: input.categories ?? [],
+    capabilities: input.capabilities ?? [],
+    contributes: {
+      commands: input.contributes?.commands ?? [],
+      menus: input.contributes?.menus ?? [],
+      keybindings: input.contributes?.keybindings ?? [],
+      ...(input.contributes?.configuration
+        ? { configuration: input.contributes.configuration }
+        : {}),
+    },
+  };
+  validateEditorManifest(manifest);
+  return manifest;
+}
+
+export type EditorTemplate = {
+  id: string;
+  label: string;
+  description: string;
+  /** Tabler icon URI (`tabler:{name}`). */
+  icon?: string;
+  previewClassName?: string;
+  type: string;
+  defaultName: string;
+  storageMode?: StorageMode;
+  contentType?: string;
+  schema?: string;
+  payload?: Record<string, unknown>;
+};

package/src/commands/manifest/ids.ts

@@ -0,0 +1,2 @@
+/** Shell chrome contribution id (not a product service id). */
+export const SHELL_SERVICE_MANIFEST_ID = "service";