@matdata/yasgui 5.10.0 → 5.11.0

package/src/queryManagement/backends/WorkspaceBackend.ts

@@ -0,0 +1,41 @@
+import type { BackendType, FolderEntry, ReadResult, VersionInfo, WriteQueryOptions } from "../types";
+
+export interface WorkspaceBackend {
+  readonly type: BackendType;
+
+  validateAccess(): Promise<void>;
+
+  listFolder(folderId?: string): Promise<FolderEntry[]>;
+
+  searchByName?(query: string): Promise<FolderEntry[]>;
+
+  readQuery(queryId: string): Promise<ReadResult>;
+
+  writeQuery(queryId: string, queryText: string, options?: WriteQueryOptions): Promise<void>;
+
+  listVersions(queryId: string): Promise<VersionInfo[]>;
+
+  readVersion(queryId: string, versionId: string): Promise<ReadResult>;
+
+  /**
+   * Optional: Rename a query (typically renaming its label, not its ID).
+   * Implementations may not support this (e.g., some Git provider clients).
+   */
+  renameQuery?(queryId: string, newLabel: string): Promise<void>;
+
+  /**
+   * Optional: Delete a query and its version history.
+   * Implementations may not support this (e.g., some Git provider clients).
+   */
+  deleteQuery?(queryId: string): Promise<void>;
+
+  /**
+   * Optional: Rename a folder (typically renaming its label, not its ID).
+   */
+  renameFolder?(folderId: string, newLabel: string): Promise<void>;
+
+  /**
+   * Optional: Delete a folder and everything inside it (recursive).
+   */
+  deleteFolder?(folderId: string): Promise<void>;
+}

package/src/queryManagement/backends/errors.ts

@@ -0,0 +1,28 @@
+export type WorkspaceBackendErrorCode =
+  | "AUTH_FAILED"
+  | "FORBIDDEN"
+  | "NOT_FOUND"
+  | "NETWORK_ERROR"
+  | "RATE_LIMITED"
+  | "CONFLICT"
+  | "UNKNOWN";
+
+export class WorkspaceBackendError extends Error {
+  public readonly code: WorkspaceBackendErrorCode;
+
+  constructor(code: WorkspaceBackendErrorCode, message?: string) {
+    super(message || code);
+    this.name = "WorkspaceBackendError";
+    this.code = code;
+  }
+}
+
+export function isWorkspaceBackendError(error: unknown): error is WorkspaceBackendError {
+  return typeof error === "object" && error !== null && (error as any).name === "WorkspaceBackendError";
+}
+
+export function asWorkspaceBackendError(error: unknown): WorkspaceBackendError {
+  if (isWorkspaceBackendError(error)) return error;
+  if (error instanceof Error) return new WorkspaceBackendError("UNKNOWN", error.message);
+  return new WorkspaceBackendError("UNKNOWN", String(error));
+}

package/src/queryManagement/backends/getWorkspaceBackend.ts

@@ -0,0 +1,132 @@
+import type { WorkspaceConfig } from "../types";
+import type { WorkspaceBackend } from "./WorkspaceBackend";
+import GitWorkspaceBackend from "./GitWorkspaceBackend";
+import SparqlWorkspaceBackend from "./SparqlWorkspaceBackend";
+import { GithubProviderClient } from "./GithubProviderClient";
+import { GitlabProviderClient } from "./GitlabProviderClient";
+import { BitbucketProviderClient } from "./BitbucketProviderClient";
+import { GiteaProviderClient } from "./GiteaProviderClient";
+import type PersistentConfig from "../../PersistentConfig";
+import type { EndpointConfig } from "../../index";
+import * as OAuth2Utils from "../../OAuth2Utils";
+
+const registeredBackends = new Map<string, WorkspaceBackend>();
+
+export function registerWorkspaceBackend(workspaceId: string, backend: WorkspaceBackend) {
+  registeredBackends.set(workspaceId, backend);
+}
+
+export function unregisterWorkspaceBackend(workspaceId: string) {
+  registeredBackends.delete(workspaceId);
+}
+
+function base64Encode(value: string): string {
+  // Browser: btoa; Node: Buffer
+  if (typeof (globalThis as any).btoa === "function") return (globalThis as any).btoa(value);
+  const buf = (globalThis as any).Buffer;
+  if (buf && typeof buf.from === "function") return buf.from(value, "utf8").toString("base64");
+  throw new Error("Base64 encoding not available in this environment");
+}
+
+function resolveSparqlAuthHeaders(persistentConfig: PersistentConfig | undefined, endpoint: string) {
+  if (!persistentConfig) return undefined;
+  const cfg: EndpointConfig | undefined = persistentConfig.getEndpointConfig(endpoint);
+  const auth = cfg?.authentication;
+  if (!auth) return undefined;
+
+  if (auth.type === "basic") {
+    const token = base64Encode(`${auth.username}:${auth.password}`);
+    return { Authorization: `Basic ${token}` };
+  }
+
+  if (auth.type === "bearer") {
+    return { Authorization: `Bearer ${auth.token}` };
+  }
+
+  if (auth.type === "apiKey") {
+    return { [auth.headerName]: auth.apiKey };
+  }
+
+  if (auth.type === "oauth2") {
+    const token = auth.accessToken || auth.idToken;
+    if (!token) return undefined;
+    return { Authorization: `Bearer ${token}` };
+  }
+
+  return undefined;
+}
+
+async function resolveSparqlAuthHeadersWithRefresh(persistentConfig: PersistentConfig, endpoint: string) {
+  const cfg: EndpointConfig | undefined = persistentConfig.getEndpointConfig(endpoint);
+  const auth = cfg?.authentication;
+  if (!auth) return undefined;
+
+  if (auth.type === "oauth2") {
+    if (OAuth2Utils.isTokenExpired(auth.tokenExpiry)) {
+      if (auth.refreshToken) {
+        try {
+          const tokenResponse = await OAuth2Utils.refreshOAuth2Token(
+            {
+              clientId: auth.clientId,
+              tokenEndpoint: auth.tokenEndpoint,
+            },
+            auth.refreshToken,
+          );
+
+          const tokenExpiry = OAuth2Utils.calculateTokenExpiry(tokenResponse.expires_in);
+          persistentConfig.addOrUpdateEndpoint(endpoint, {
+            authentication: {
+              ...auth,
+              accessToken: tokenResponse.access_token,
+              idToken: tokenResponse.id_token,
+              refreshToken: tokenResponse.refresh_token || auth.refreshToken,
+              tokenExpiry,
+            },
+          });
+        } catch (e) {
+          console.error("Failed to refresh OAuth2 token for endpoint", endpoint, e);
+        }
+      }
+    }
+
+    const updated = persistentConfig.getEndpointConfig(endpoint)?.authentication;
+    if (updated && updated.type === "oauth2") {
+      const token = updated.accessToken || updated.idToken;
+      if (token) return { Authorization: `Bearer ${token}` };
+    }
+
+    return undefined;
+  }
+
+  return resolveSparqlAuthHeaders(persistentConfig, endpoint);
+}
+
+export function getWorkspaceBackend(
+  config: WorkspaceConfig,
+  options?: {
+    persistentConfig?: PersistentConfig;
+  },
+): WorkspaceBackend {
+  const registered = registeredBackends.get(config.id);
+  if (registered) return registered;
+  if (config.type === "git") {
+    const client =
+      (GithubProviderClient.canHandle(config) && new GithubProviderClient()) ||
+      (GitlabProviderClient.canHandle(config) && new GitlabProviderClient()) ||
+      (BitbucketProviderClient.canHandle(config) && new BitbucketProviderClient()) ||
+      (GiteaProviderClient.canHandle(config) && new GiteaProviderClient()) ||
+      undefined;
+
+    return new GitWorkspaceBackend(config, client);
+  }
+
+  const persistentConfig = options?.persistentConfig;
+  if (!persistentConfig) {
+    const authHeaders = resolveSparqlAuthHeaders(undefined, config.endpoint);
+    return new SparqlWorkspaceBackend(config, { authHeaders });
+  }
+
+  return new SparqlWorkspaceBackend(config, {
+    getAuthHeaders: () => resolveSparqlAuthHeadersWithRefresh(persistentConfig, config.endpoint),
+  });
+}

package/src/queryManagement/backends/gitRemote.ts

@@ -0,0 +1,54 @@
+export type ParsedGitRemote = {
+  host: string;
+  /** Repository path without leading slash, without trailing .git */
+  repoPath: string;
+};
+
+function stripDotGit(path: string): string {
+  return path.replace(/\.git$/i, "");
+}
+
+function stripLeadingSlash(path: string): string {
+  return path.replace(/^\/+/, "");
+}
+
+function stripTrailingSlash(path: string): string {
+  return path.replace(/\/+$/, "");
+}
+
+function parseHttpLike(remoteUrl: string): ParsedGitRemote {
+  const url = new URL(remoteUrl);
+  const host = url.hostname.toLowerCase();
+  const repoPath = stripDotGit(stripTrailingSlash(stripLeadingSlash(url.pathname)));
+  if (!repoPath) throw new Error("Invalid git remote URL (missing path)");
+  return { host, repoPath };
+}
+
+function parseScpLike(remoteUrl: string): ParsedGitRemote {
+  // e.g. git@github.com:owner/repo.git
+  const m = /^([^@]+)@([^:]+):(.+)$/.exec(remoteUrl);
+  if (!m || !m[2] || !m[3]) throw new Error("Invalid SCP-like git remote URL");
+  const host = String(m[2]).toLowerCase();
+  const repoPath = stripDotGit(stripTrailingSlash(stripLeadingSlash(String(m[3]))));
+  if (!repoPath) throw new Error("Invalid git remote URL (missing path)");
+  return { host, repoPath };
+}
+
+export function parseGitRemote(remoteUrl: string): ParsedGitRemote {
+  const trimmed = remoteUrl.trim();
+  if (!trimmed) throw new Error("Remote URL is empty");
+
+  // Handle common git remote formats.
+  if (/^(https?|ssh):\/\//i.test(trimmed)) {
+    // For ssh:// URLs, URL parsing works and pathname carries the repo path.
+    return parseHttpLike(trimmed);
+  }
+
+  // SCP-like syntax: git@host:org/repo.git
+  if (/^[^@]+@[^:]+:.+/.test(trimmed)) {
+    return parseScpLike(trimmed);
+  }
+
+  // Fallback: attempt URL parse (may throw)
+  return parseHttpLike(trimmed);
+}

package/src/queryManagement/browserFilter.ts

@@ -0,0 +1,8 @@
+import type { FolderEntry } from "./types";
+
+export function filterFolderEntriesByName(entries: FolderEntry[], query: string): FolderEntry[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return entries;
+
+  return entries.filter((e) => e.label.toLowerCase().includes(q));
+}

package/src/queryManagement/index.ts

@@ -0,0 +1,15 @@
+export * from "./types";
+
+export * from "./normalizeQueryFilename";
+export * from "./saveManagedQuery";
+export * from "./validateWorkspaceConfig";
+export * from "./textHash";
+export * from "./browserFilter";
+export * from "./openManagedQuery";
+export * from "./backends/WorkspaceBackend";
+export * from "./backends/errors";
+export * from "./backends/getWorkspaceBackend";
+
+export { default as InMemoryWorkspaceBackend } from "./backends/InMemoryWorkspaceBackend";
+export { default as GitWorkspaceBackend } from "./backends/GitWorkspaceBackend";
+export { default as SparqlWorkspaceBackend } from "./backends/SparqlWorkspaceBackend";

package/src/queryManagement/normalizeQueryFilename.ts

@@ -0,0 +1,8 @@
+export function normalizeQueryFilename(rawName: string): string {
+  const name = rawName.trim();
+  if (!name) throw new Error("Filename is required");
+
+  const lower = name.toLowerCase();
+  if (lower.endsWith(".sparql")) return name;
+  return `${name}.sparql`;
+}

package/src/queryManagement/openManagedQuery.ts

@@ -0,0 +1,31 @@
+import type { BackendType, ReadResult } from "./types";
+import type { WorkspaceBackend } from "./backends/WorkspaceBackend";
+
+export function getEndpointToAutoSwitch(backendType: BackendType, readResult: ReadResult): string | undefined {
+  if (backendType === "git") return undefined;
+  return readResult.associatedEndpoint;
+}
+
+type NewTabLike = {
+  setQuery(queryText: string): void;
+  setEndpoint(endpoint: string): void;
+  setName(name: string): void;
+};
+
+export async function openManagedQuery(options: {
+  backend: WorkspaceBackend;
+  queryId: string;
+  queryLabel?: string;
+  createNewTab: () => NewTabLike;
+}): Promise<void> {
+  const read = await options.backend.readQuery(options.queryId);
+
+  const newTab = options.createNewTab();
+
+  if (options.queryLabel) newTab.setName(options.queryLabel);
+
+  const endpoint = getEndpointToAutoSwitch(options.backend.type, read);
+  if (endpoint) newTab.setEndpoint(endpoint);
+
+  newTab.setQuery(read.queryText);
+}

package/src/queryManagement/saveManagedQuery.ts

@@ -0,0 +1,135 @@
+import type { WorkspaceBackend } from "./backends/WorkspaceBackend";
+import type { BackendType, ManagedTabMetadata, VersionRef } from "./types";
+import { asWorkspaceBackendError } from "./backends/errors";
+import { hashQueryText } from "./textHash";
+import { normalizeQueryFilename } from "./normalizeQueryFilename";
+
+export interface SaveManagedQueryInput {
+  backend: WorkspaceBackend;
+  backendType: BackendType;
+  workspaceId: string;
+  /** Required for SPARQL workspaces to mint immutable query/version IRIs. */
+  workspaceIri?: string;
+  queryText: string;
+  folderPath?: string;
+  /** Tab/query label (used as SPARQL rdfs:label). */
+  name?: string;
+  filename: string;
+  /** Optional SPARQL query execution endpoint to store on the version (sparql backends only). */
+  associatedEndpoint?: string;
+  message?: string;
+  expectedVersionTag?: string;
+}
+
+export interface SaveManagedQueryResult {
+  queryId: string;
+  managedMetadata: ManagedTabMetadata;
+}
+
+function normalizeFolderPath(folderPath: string | undefined): string {
+  if (!folderPath) return "";
+  const trimmed = folderPath.trim();
+  if (!trimmed) return "";
+  return trimmed.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+function buildQueryId(folderPath: string | undefined, filename: string): string {
+  const normalizedFolder = normalizeFolderPath(folderPath);
+  const normalizedFilename = normalizeQueryFilename(filename);
+  return normalizedFolder ? `${normalizedFolder}/${normalizedFilename}` : normalizedFilename;
+}
+
+function uuidV4(): string {
+  const cryptoObj = (globalThis as any).crypto as Crypto | undefined;
+  if (cryptoObj?.randomUUID) return cryptoObj.randomUUID();
+  // RFC4122 v4 fallback (best-effort)
+  const rnds = new Uint8Array(16);
+  if (cryptoObj?.getRandomValues) {
+    cryptoObj.getRandomValues(rnds);
+  } else {
+    for (let i = 0; i < rnds.length; i++) rnds[i] = Math.floor(Math.random() * 256);
+  }
+  rnds[6] = (rnds[6] & 0x0f) | 0x40;
+  rnds[8] = (rnds[8] & 0x3f) | 0x80;
+  const hex = Array.from(rnds, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function mintSparqlManagedQueryIri(workspaceIri: string): string {
+  return `${workspaceIri.trim()}_mq_${uuidV4()}`;
+}
+
+function versionRefFromVersionTag(backendType: BackendType, versionTag: string | undefined): VersionRef | undefined {
+  if (!versionTag) return undefined;
+  if (backendType === "git") return { commitSha: versionTag };
+  return { managedQueryVersionIri: versionTag };
+}
+
+export async function saveManagedQuery(input: SaveManagedQueryInput): Promise<SaveManagedQueryResult> {
+  const folderId = normalizeFolderPath(input.folderPath);
+  const queryId = input.backendType === "git" ? buildQueryId(input.folderPath, input.filename) : "";
+
+  if (input.backendType === "sparql" && !input.workspaceIri?.trim()) {
+    throw new Error("workspaceIri is required for SPARQL workspaces");
+  }
+
+  const label = (input.name || "").trim();
+  if (input.backendType === "sparql" && !label) {
+    throw new Error("name is required for SPARQL workspaces");
+  }
+
+  const resolvedQueryId = await (async () => {
+    if (input.backendType !== "sparql") return queryId;
+
+    // Overwrite behavior: if a query with the same label already exists in this folder,
+    // write a new version to that managed query instead of creating a duplicate.
+    try {
+      const entries = await input.backend.listFolder(folderId || undefined);
+      const existing = entries.find(
+        (e) => e.kind === "query" && e.label.trim().toLowerCase() === label.trim().toLowerCase(),
+      );
+      if (existing?.id) return existing.id;
+    } catch {
+      // If listing fails for any reason, fall back to creating a new managed query.
+    }
+
+    return mintSparqlManagedQueryIri(input.workspaceIri || "");
+  })();
+
+  try {
+    await input.backend.writeQuery(resolvedQueryId, input.queryText, {
+      message: input.message,
+      expectedVersionTag: input.expectedVersionTag,
+      ...(input.backendType === "sparql"
+        ? {
+            label: label || undefined,
+            folderId: folderId || undefined,
+            associatedEndpoint: input.associatedEndpoint || undefined,
+          }
+        : {}),
+    });
+  } catch (e) {
+    const err = asWorkspaceBackendError(e);
+    if (err.code === "CONFLICT") {
+      const extra =
+        input.backendType === "git"
+          ? " Resolve the conflict externally (e.g., pull/rebase/merge) and then try saving again."
+          : " Refresh the query and try again.";
+      throw new Error(`Save conflict.${extra}`);
+    }
+    throw err;
+  }
+
+  const read = await input.backend.readQuery(resolvedQueryId);
+  const lastSavedTextHash = hashQueryText(read.queryText);
+
+  const managedMetadata: ManagedTabMetadata = {
+    workspaceId: input.workspaceId,
+    backendType: input.backendType,
+    queryRef: input.backendType === "git" ? { path: resolvedQueryId } : { managedQueryIri: resolvedQueryId },
+    lastSavedVersionRef: versionRefFromVersionTag(input.backendType, read.versionTag),
+    lastSavedTextHash,
+  };
+
+  return { queryId: resolvedQueryId, managedMetadata };
+}

package/src/queryManagement/textHash.ts

@@ -0,0 +1,15 @@
+export function normalizeQueryText(queryText: string): string {
+  return queryText.replace(/\r\n/g, "\n").trim();
+}
+
+export function hashQueryText(queryText: string): string {
+  const text = normalizeQueryText(queryText);
+
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = (hash * 0x01000193) >>> 0;
+  }
+
+  return hash.toString(16).padStart(8, "0");
+}

package/src/queryManagement/types.ts

@@ -0,0 +1,85 @@
+export type BackendType = "git" | "sparql";
+
+export interface WorkspaceConfigBase {
+  id: string;
+  label: string;
+  description?: string;
+  type: BackendType;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface GitWorkspaceAuthPat {
+  type: "pat";
+  token: string;
+  username?: string;
+}
+
+export interface GitWorkspaceConfig extends WorkspaceConfigBase {
+  type: "git";
+  remoteUrl: string;
+  branch: string;
+  rootPath: string;
+  auth: GitWorkspaceAuthPat;
+  /** Optional hint for selecting a git provider client. Defaults to auto-detection. */
+  provider?: "auto" | "github" | "gitlab" | "bitbucket" | "gitea";
+  /** Optional override for provider API base URL (useful for self-hosted/enterprise instances). */
+  apiBaseUrl?: string;
+}
+
+export interface SparqlWorkspaceConfig extends WorkspaceConfigBase {
+  type: "sparql";
+  endpoint: string;
+  workspaceIri: string;
+  defaultGraph?: string;
+}
+
+export type WorkspaceConfig = GitWorkspaceConfig | SparqlWorkspaceConfig;
+
+export interface FolderEntry {
+  kind: "folder" | "query";
+  id: string;
+  label: string;
+  parentId?: string;
+}
+
+export interface ReadResult {
+  queryText: string;
+  versionTag?: string;
+  associatedEndpoint?: string;
+  description?: string;
+}
+
+export interface VersionInfo {
+  id: string;
+  createdAt: string;
+  author?: string;
+  message?: string;
+}
+
+export interface WriteQueryOptions {
+  message?: string;
+  expectedVersionTag?: string;
+  /** Optional label for backends where the query ID is not derived from the label (e.g., SPARQL workspace). */
+  label?: string;
+  /** Optional folder id/path for backends where folder is not encoded in the query ID (e.g., SPARQL workspace). */
+  folderId?: string;
+  /** Optional associated endpoint for this saved version (e.g., SPARQL query execution endpoint). */
+  associatedEndpoint?: string;
+}
+
+export type GitQueryRef = { path: string };
+export type SparqlQueryRef = { managedQueryIri: string };
+export type QueryRef = GitQueryRef | SparqlQueryRef;
+
+export type GitVersionRef = { commitSha?: string };
+export type SparqlVersionRef = { managedQueryVersionIri: string };
+export type VersionRef = GitVersionRef | SparqlVersionRef;
+
+export interface ManagedTabMetadata {
+  workspaceId: string;
+  backendType: BackendType;
+  queryRef: QueryRef;
+  lastSavedVersionRef?: VersionRef;
+  lastSavedTextHash?: string;
+}

package/src/queryManagement/validateWorkspaceConfig.ts

@@ -0,0 +1,40 @@
+import type { WorkspaceConfig } from "./types";
+
+export interface WorkspaceValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+function isNonEmpty(value: string | undefined): boolean {
+  return !!value && value.trim().length > 0;
+}
+
+export function validateWorkspaceConfig(config: WorkspaceConfig): WorkspaceValidationResult {
+  const errors: string[] = [];
+
+  if (!isNonEmpty(config.id)) errors.push("Workspace id is required");
+  if (!isNonEmpty(config.label)) errors.push("Workspace label is required");
+
+  if (config.type === "git") {
+    if (!isNonEmpty(config.remoteUrl)) errors.push("Git remote URL is required");
+    // rootPath can be empty string to mean repo root
+    if (typeof config.rootPath !== "string") errors.push("Git rootPath must be a string");
+    if (!config.auth || config.auth.type !== "pat") errors.push("Git auth is required");
+
+    const anyCfg = config as any;
+    if (anyCfg.provider && !["auto", "github", "gitlab", "bitbucket", "gitea"].includes(anyCfg.provider)) {
+      errors.push("Git provider must be one of: auto, github, gitlab, bitbucket, gitea");
+    }
+
+    if (anyCfg.apiBaseUrl && typeof anyCfg.apiBaseUrl !== "string") {
+      errors.push("Git apiBaseUrl must be a string");
+    }
+  }
+
+  if (config.type === "sparql") {
+    if (!isNonEmpty(config.endpoint)) errors.push("SPARQL endpoint is required");
+    if (!isNonEmpty(config.workspaceIri)) errors.push("Workspace IRI is required");
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/tab.scss

@@ -140,35 +140,25 @@
     padding: 6px;
     cursor: pointer;
     color: var(--yasgui-button-text, #505050);
-    fill: var(--yasgui-button-text, #505050);
     display: flex;
     align-items: center;
     justify-content: center;
     flex-shrink: 0;
 
-    .svgImg {
-      width: 15px;
-      height: 15px;
-      font-family: initial;
-    }
-
-    svg {
-      width: 20px;
-      height: 20px;
+    i {
+      font-size: 16px;
     }
 
     &:hover {
       color: var(--yasgui-button-hover, black);
-      fill: var(--yasgui-button-hover, black);
     }
 
     // Responsive spacing - reduce padding on smaller screens
     @media (max-width: 768px) {
       padding: 2px;
 
-      svg {
-        width: 18px;
-        height: 18px;
+      i {
+        font-size: 18px;
       }
     }
   }