@rynt/sdk 0.9.53

package/src/extensions/resolve-extensions.ts

@@ -0,0 +1,245 @@
+import semver from 'semver';
+
+import type { RyntExtensionManifestParsed } from './manifest-types';
+import { topoSortExtensions } from './graph';
+import {
+  applyValidatedRyntContributesToManifest,
+  flattenExtendsRegistries,
+  getRyntContributesFromManifest,
+  KNOWN_CORE_REGISTRY_IDS,
+} from './registries/manifest-rynt';
+import { checkExtensionApi } from './version';
+
+export interface RyntDiscoveredExtensionLike {
+  manifest: RyntExtensionManifestParsed;
+}
+
+export interface ExtensionManifestIndex {
+  /** registryId → manifest.id владельца */
+  declaredBy: Map<string, string>;
+  /** `${registryId}\0${key}` → manifest.id[] */
+  slotClaims: Map<string, string[]>;
+}
+
+function slotClaimKey(registryId: string, key: string): string {
+  return `${registryId}\0${key}`;
+}
+
+export function buildExtensionManifestIndex(
+  byId: Map<string, RyntExtensionManifestParsed>,
+): { ok: true; index: ExtensionManifestIndex } | { ok: false; error: string } {
+  const declaredBy = new Map<string, string>();
+  const slotClaims = new Map<string, string[]>();
+
+  for (const [extId, manifest] of byId) {
+    const contributes = getRyntContributesFromManifest(manifest);
+
+    for (const decl of contributes?.declaresRegistries ?? []) {
+      const prev = declaredBy.get(decl.id);
+      if (prev !== undefined && prev !== extId) {
+        return {
+          ok: false,
+          error: `Registry "${decl.id}" declared by both "${prev}" and "${extId}"`,
+        };
+      }
+      declaredBy.set(decl.id, extId);
+    }
+
+    for (const { registryId, key } of flattenExtendsRegistries(contributes)) {
+      const sk = slotClaimKey(registryId, key);
+      const list = slotClaims.get(sk) ?? [];
+      list.push(extId);
+      slotClaims.set(sk, list);
+    }
+  }
+
+  return { ok: true, index: { declaredBy, slotClaims } };
+}
+
+function mergeImpliedDependencies(
+  byId: Map<string, RyntExtensionManifestParsed>,
+  index: ExtensionManifestIndex,
+): Map<string, Record<string, string>> {
+  const graph = new Map<string, Record<string, string>>();
+
+  for (const [id, manifest] of byId) {
+    graph.set(id, { ...(manifest.extensionDependencies ?? {}) });
+  }
+
+  for (const [extId, manifest] of byId) {
+    const contributes = getRyntContributesFromManifest(manifest);
+    for (const { registryId } of flattenExtendsRegistries(contributes)) {
+      if (KNOWN_CORE_REGISTRY_IDS.has(registryId)) {
+        continue;
+      }
+      const owner = index.declaredBy.get(registryId);
+      if (!owner) {
+        continue;
+      }
+      if (owner === extId) {
+        continue;
+      }
+      const deps = graph.get(extId) ?? {};
+      if (!(owner in deps)) {
+        deps[owner] = '*';
+        graph.set(extId, deps);
+        if (process.env.NODE_ENV !== 'production') {
+          console.info(
+            `[rynt/extensions] Implied dependency: «${extId}» → «${owner}» (registry ${registryId})`,
+          );
+        }
+      }
+    }
+  }
+
+  return graph;
+}
+
+export function validateExtensionDependencyVersions(
+  byId: Map<string, RyntExtensionManifestParsed>,
+  mergedDeps: Map<string, Record<string, string>>,
+): Record<string, string> {
+  const errors: Record<string, string> = {};
+
+  for (const [extId, deps] of mergedDeps) {
+    for (const [depId, range] of Object.entries(deps)) {
+      const dep = byId.get(depId);
+      if (!dep) {
+        continue;
+      }
+      const ver = semver.coerce(dep.version)?.version ?? dep.version;
+      if (!semver.validRange(range)) {
+        errors[extId] =
+          errors[extId] ??
+          `extensionDependencies["${depId}"]: invalid range "${range}"`;
+        continue;
+      }
+      if (!semver.satisfies(ver, range)) {
+        let msg = `extensionDependencies["${depId}"]: installed v${dep.version} does not satisfy ${range}`;
+        if (/^\^0\.0\.\d+$/u.test(range.trim())) {
+          msg +=
+            ' (для 0.0.x диапазон ^0.0.N не включает 0.0.(N+1); укажите >=0.0.N или ^0.0.M с нужным M)';
+        }
+        errors[extId] = errors[extId] ? `${errors[extId]}; ${msg}` : msg;
+      }
+    }
+  }
+
+  return errors;
+}
+
+export interface ResolveExtensionsResult {
+  order: string[];
+  errors: Record<string, string>;
+  index: ExtensionManifestIndex;
+}
+
+export type ResolveExtensionsLoadResult =
+  | ({ ok: true } & ResolveExtensionsResult)
+  | { ok: false; error: string };
+
+export function resolveExtensionsForLoad(
+  extensions: RyntDiscoveredExtensionLike[],
+  options?: {
+    launcherVersion?: string;
+    strictExtensionApi?: boolean;
+  },
+): ResolveExtensionsLoadResult {
+  const errors: Record<string, string> = {};
+  const byId = new Map<string, RyntExtensionManifestParsed>();
+
+  for (const item of extensions) {
+    const id = item.manifest.id;
+    if (byId.has(id)) {
+      errors[id] = 'Duplicate extension id';
+      continue;
+    }
+    const manifest = { ...item.manifest };
+    const contribErr = applyContributesOrSkip(manifest);
+    if (contribErr) {
+      errors[id] = contribErr;
+      continue;
+    }
+    byId.set(id, manifest);
+  }
+
+  const indexResult = buildExtensionManifestIndex(byId);
+  if (!indexResult.ok) {
+    return { ok: false, error: indexResult.error };
+  }
+  const index = indexResult.index;
+
+  for (const [extId, manifest] of byId) {
+    const contributes = getRyntContributesFromManifest(manifest);
+    for (const { registryId } of flattenExtendsRegistries(contributes)) {
+      if (KNOWN_CORE_REGISTRY_IDS.has(registryId)) {
+        continue;
+      }
+      if (!index.declaredBy.has(registryId)) {
+        const msg = `extendsRegistries: registry "${registryId}" is not declared by any enabled extension`;
+        errors[extId] = errors[extId] ? `${errors[extId]}; ${msg}` : msg;
+      }
+    }
+  }
+
+  for (const [extId, manifest] of byId) {
+    const api = checkExtensionApi(manifest, {
+      strict: options?.strictExtensionApi,
+    });
+    if (!api.ok && api.message) {
+      errors[extId] = errors[extId]
+        ? `${errors[extId]}; ${api.message}`
+        : api.message;
+      if (api.blocking) {
+        byId.delete(extId);
+      }
+    }
+  }
+
+  if (options?.launcherVersion) {
+    for (const [extId, manifest] of byId) {
+      if (manifest.engines?.rynt) {
+        const v =
+          semver.coerce(options.launcherVersion)?.version ??
+          options.launcherVersion;
+        if (!semver.satisfies(v, manifest.engines.rynt)) {
+          const msg = `engines.rynt: host ${options.launcherVersion} does not satisfy ${manifest.engines.rynt}`;
+          errors[extId] = errors[extId] ? `${errors[extId]}; ${msg}` : msg;
+          byId.delete(extId);
+        }
+      }
+    }
+  }
+
+  const mergedDeps = mergeImpliedDependencies(byId, index);
+  const depVersionErrors = validateExtensionDependencyVersions(byId, mergedDeps);
+  for (const [id, msg] of Object.entries(depVersionErrors)) {
+    errors[id] = errors[id] ? `${errors[id]}; ${msg}` : msg;
+  }
+
+  const topoInput = new Map(
+    [...byId.keys()].map((id) => [
+      id,
+      {
+        id,
+        extensionDependencies: mergedDeps.get(id) ?? {},
+      },
+    ]),
+  );
+
+  const topo = topoSortExtensions(topoInput);
+  if (!topo.ok) {
+    return { ok: false, error: topo.error };
+  }
+
+  return {
+    ok: true,
+    order: topo.order.filter((id) => byId.has(id)),
+    errors,
+    index,
+  };
+}
+
+function applyContributesOrSkip(manifest: RyntExtensionManifestParsed): string | null {
+  return applyValidatedRyntContributesToManifest(manifest);
+}

package/src/extensions/router-bridge.ts

@@ -0,0 +1,103 @@
+import type { Router, RouteRecordRaw } from 'vue-router';
+
+import ExtensionRoutePage from './ExtensionRoutePage.vue';
+import { useExtensionPageRegistry } from './registries/builtins/page';
+
+export const EXTENSION_ROUTE_NAME_PREFIX = 'ext-route-';
+
+export function isExtensionRouteName(name: unknown): name is string {
+  return typeof name === 'string' && name.startsWith(EXTENSION_ROUTE_NAME_PREFIX);
+}
+
+export function routeHasExtensionMeta(meta: unknown): boolean {
+  return (
+    meta !== null &&
+    typeof meta === 'object' &&
+    typeof (meta as { extensionId?: unknown }).extensionId === 'string'
+  );
+}
+
+const EXT_ROUTE_NAME_PREFIX = EXTENSION_ROUTE_NAME_PREFIX;
+
+export function detachExtensionRoutes(router: Router): void {
+  detachExtensionRoutesForExtensions(router, null);
+}
+
+export function detachExtensionRoutesForExtensions(
+  router: Router,
+  extensionIds: string[] | null,
+): void {
+  const idFilter =
+    extensionIds && extensionIds.length > 0 ? new Set(extensionIds) : null;
+  const names = new Set<string>();
+  for (const r of router.getRoutes()) {
+    const n = r.name;
+    if (typeof n !== 'string' || !n.startsWith(EXT_ROUTE_NAME_PREFIX)) {
+      continue;
+    }
+    if (idFilter && routeHasExtensionMeta(r.meta)) {
+      const extId = (r.meta as { extensionId: string }).extensionId;
+      if (!idFilter.has(extId)) {
+        continue;
+      }
+    }
+    names.add(n);
+  }
+  for (const name of names) {
+    if (router.hasRoute(name)) {
+      router.removeRoute(name);
+    }
+  }
+}
+
+/** Маршруты из реестра `core.page` (после загрузки расширений). */
+export function attachExtensionRoutes(router: Router): void {
+  attachExtensionRoutesForExtensions(router, null);
+}
+
+function buildExtensionRouteRecords(
+  extensionIds: string[] | null,
+): RouteRecordRaw[] {
+  const idFilter =
+    extensionIds && extensionIds.length > 0 ? new Set(extensionIds) : null;
+  const additions: RouteRecordRaw[] = [];
+  for (const { registryKey, value: page, extensionId: extId } of useExtensionPageRegistry().entries()) {
+    if (idFilter && !idFilter.has(extId)) {
+      continue;
+    }
+    additions.push({
+      path: page.resolvedRoutePath,
+      name: `${EXT_ROUTE_NAME_PREFIX}${encodeURIComponent(extId)}-${encodeURIComponent(registryKey)}`,
+      component: ExtensionRoutePage,
+      props: {
+        pageComponent: page.component,
+        extensionId: extId,
+        registryKey,
+      },
+      meta: { extensionId: extId },
+    });
+  }
+  return additions;
+}
+
+export function attachExtensionRoutesForExtensions(
+  router: Router,
+  extensionIds: string[] | null,
+): void {
+  for (const r of buildExtensionRouteRecords(extensionIds)) {
+    router.addRoute(r);
+  }
+}
+
+export function syncExtensionRoutesForExtensions(
+  router: Router,
+  extensionIds: string[],
+): void {
+  detachExtensionRoutesForExtensions(router, extensionIds);
+  attachExtensionRoutesForExtensions(router, extensionIds);
+}
+
+export function syncExtensionRoutes(router: Router): void {
+  detachExtensionRoutes(router);
+  attachExtensionRoutes(router);
+}

package/src/extensions/session.ts

@@ -0,0 +1,6 @@
+/**
+ * Токен сессии лаунчера для HTTP/WS из расширений.
+ * Отдельный entry (не корень `@rynt/sdk`): при сборке расширения `@rynt/sdk` остаётся external,
+ * bare specifier в браузере не резолвится — подставляется шим `@rynt/sdk/session`.
+ */
+export { getSessionToken } from '../shared/api/graphql';

package/src/extensions/slug.ts

@@ -0,0 +1,23 @@
+/** Стабильный сегмент URL для расширения (без спец-символов). */
+export function extensionRouteSlug(extensionId: string): string {
+  return extensionId
+    .replace(/^@/, '')
+    .replace(/\//g, '__')
+    .replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+export function normalizeExtensionSubpath(fragment: string): string {
+  const t = fragment.replace(/^\/+/u, '').replace(/\\/gu, '/');
+  if (t.includes('..') || (t.startsWith('.') && t !== '.')) {
+    throw new Error(
+      'Extension navigation path must not escape its directory (. or ..)',
+    );
+  }
+  return t || 'page';
+}
+
+export function resolvedNavigationPath(extensionId: string, pathFragment: string) {
+  const slug = extensionRouteSlug(extensionId);
+  const tail = normalizeExtensionSubpath(pathFragment);
+  return `/ext/${slug}/${tail}`;
+}

package/src/extensions/version.ts

@@ -0,0 +1,147 @@
+import semver from 'semver';
+
+/**
+ * Текущая major-версия Extension API (манифест `extensionApi`: `"1"`).
+ * API только расширяется; старые расширения совместимы с новым хостом.
+ */
+export const EXTENSION_API_VERSION = 1;
+
+/**
+ * Разбирает `manifest.extensionApi` в целое major.
+ * Поддерживает `"1"`, `1`, legacy `"^1.0.0"` / `"1.0.0"` (берётся major).
+ */
+export function parseExtensionApiMajor(value: unknown): number | null {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
+    return value;
+  }
+  const s = String(value).trim();
+  if (!s) {
+    return null;
+  }
+  if (/^\d+$/u.test(s)) {
+    return Number.parseInt(s, 10);
+  }
+  const coerced = semver.coerce(s);
+  return coerced ? coerced.major : null;
+}
+
+export interface CheckExtensionApiOptions {
+  /** При `true` и `required > host` возвращает blocking-сообщение. */
+  strict?: boolean;
+}
+
+export interface CheckExtensionApiResult {
+  ok: boolean;
+  /** Сообщение для `errors[id]` или лога. */
+  message?: string;
+  /** Блокировать загрузку расширения. */
+  blocking?: boolean;
+  /** Фактически используемая major (если поле опущено — 1). */
+  effectiveMajor: number;
+}
+
+/**
+ * Мягкая проверка Extension API: `required <= host` всегда OK;
+ * `required > host` — предупреждение, загрузка по умолчанию не блокируется.
+ */
+export function checkExtensionApi(
+  manifest: { extensionApi?: string },
+  options?: CheckExtensionApiOptions,
+): CheckExtensionApiResult {
+  const host = EXTENSION_API_VERSION;
+  const parsed = parseExtensionApiMajor(manifest.extensionApi);
+
+  if (parsed === null) {
+    if (manifest.extensionApi !== undefined && manifest.extensionApi !== '') {
+      const legacy = String(manifest.extensionApi);
+      if (/[\^~<>=]/.test(legacy) || legacy.includes('.')) {
+        console.warn(
+          `[rynt/extensions] extensionApi «${legacy}» — устаревший semver-формат; используйте целое «${host}»`,
+        );
+      } else {
+        console.warn(
+          `[rynt/extensions] extensionApi «${legacy}» не распознан; считаем API ${host}`,
+        );
+      }
+    } else if (process.env.NODE_ENV !== 'production') {
+      console.warn(
+        `[rynt/extensions] extensionApi не указан; считаем API ${host}`,
+      );
+    }
+    return { ok: true, effectiveMajor: host };
+  }
+
+  if (parsed <= host) {
+    return { ok: true, effectiveMajor: parsed };
+  }
+
+  const message = `extensionApi: требуется API ${parsed}, лаунчер поддерживает ${host} — обновите лаунчер`;
+  const blocking = options?.strict === true;
+  if (!blocking) {
+    console.warn(`[rynt/extensions] ${message}`);
+  }
+  return {
+    ok: false,
+    message,
+    blocking,
+    effectiveMajor: parsed,
+  };
+}
+
+export interface NormalizeExtensionApiOptions {
+  /** Ошибка вместо приведения legacy semver к `"1"`. */
+  strict?: boolean;
+  extensionId?: string;
+}
+
+/**
+ * Приводит `manifest.extensionApi` к строке major (`"1"`).
+ * Возвращает текст ошибки или `null`.
+ */
+export function normalizeExtensionApiInManifest(
+  manifest: { extensionApi?: string; id?: string },
+  options?: NormalizeExtensionApiOptions,
+): string | null {
+  const host = EXTENSION_API_VERSION;
+  const raw = manifest.extensionApi;
+  const label = options?.extensionId ?? manifest.id ?? 'extension';
+
+  if (raw === undefined || raw === null || String(raw).trim() === '') {
+    manifest.extensionApi = String(host);
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn(
+        `[rynt/extensions] «${label}»: extensionApi не указан — подставлено «${host}»`,
+      );
+    }
+    return null;
+  }
+
+  const parsed = parseExtensionApiMajor(raw);
+  if (parsed === null) {
+    const msg = `extensionApi: не удалось разобрать значение «${String(raw)}»`;
+    if (options?.strict) {
+      return msg;
+    }
+    manifest.extensionApi = String(host);
+    console.warn(`[rynt/extensions] «${label}»: ${msg}; подставлено «${host}»`);
+    return null;
+  }
+
+  const legacy =
+    typeof raw === 'string' &&
+    (/[\^~<>=]/.test(raw) || (raw.includes('.') && !/^\d+$/u.test(raw.trim())));
+
+  if (legacy) {
+    const msg = `extensionApi «${raw}» — устаревший semver-формат, используйте «${parsed}»`;
+    if (options?.strict) {
+      return msg;
+    }
+    console.warn(`[rynt/extensions] «${label}»: ${msg}`);
+  }
+
+  manifest.extensionApi = String(parsed);
+  return null;
+}

package/src/host/extensions-composables.ts

@@ -0,0 +1,33 @@
+import { ref, type Ref } from 'vue';
+
+import type { RyntExtensionHostOptions } from './extensions-init';
+import { initializeRyntExtensions as runInitialize } from './extensions-init';
+
+export function useRyntExtensionLoader(): {
+  isLoading: Ref<boolean>;
+  loadErrors: Ref<Record<string, string>>;
+  initializeRyntExtensions: (
+    options: RyntExtensionHostOptions,
+  ) => Promise<void>;
+} {
+  const isLoading = ref(false);
+  const loadErrors = ref<Record<string, string>>({});
+
+  async function initializeRyntExtensions(
+    options: RyntExtensionHostOptions,
+  ): Promise<void> {
+    isLoading.value = true;
+    loadErrors.value = {};
+    try {
+      loadErrors.value = await runInitialize(options);
+    } finally {
+      isLoading.value = false;
+    }
+  }
+
+  return {
+    isLoading,
+    loadErrors,
+    initializeRyntExtensions,
+  };
+}