Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

10.5 KB
Raw Blame
import { MANAGED_ARTIFACT_SCOPES } from '@inkeep/open-knowledge-core/constants/cc1';
import type { SkillScope } from '@inkeep/open-knowledge-core/schemas/api';
import type { TabOpenDisposition } from '@/editor/editor-panes';

function isSkillScope(value: string): value is SkillScope {
  return (MANAGED_ARTIFACT_SCOPES as readonly string[]).includes(value);
}

export function docNameFromHash(hash: string): string | null {
  if (hash.startsWith(ASSET_HASH_PREFIX)) return null;
  if (hash.startsWith(SKILL_FILE_HASH_PREFIX)) return null;
  if (hash.startsWith(SKILLS_HASH_PREFIX)) return null;
  if (hash.startsWith(SKILL_PREVIEW_HASH_PREFIX)) return null;
  if (!hash.startsWith('#/')) return null;
  const rest = hash.slice(2);
  const delimiter = firstRouteDelimiterIndex(rest);
  const encoded = delimiter >= 0 ? rest.slice(0, delimiter) : rest;
  if (!encoded) return null;
  try {
    return encoded.split('/').map(decodeURIComponent).join('/');
  } catch {
    return encoded;
  }
}

export function anchorFromHash(hash: string): string | null {
  if (hash.startsWith(ASSET_HASH_PREFIX)) return null;
  if (!hash.startsWith('#/')) return null;

  const rest = hash.slice(2);
  const fragment = rest.indexOf('#');
  if (fragment < 0) return null;
  const encoded = rest.slice(fragment + 1);
  if (!encoded) return null;
  try {
    return decodeURIComponent(encoded);
  } catch {
    return encoded;
  }
}

const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;

function encodeSegment(value: string): string {
  return encodeURIComponent(value.replace(LONE_SURROGATE, '\uFFFD'));
}

function encodeRoutePath(path: string): string {
  return path.split('/').map(encodeSegment).join('/');
}

export function hashFromDocName(docName: string, anchor?: string | null): string {
  const base = `#/${encodeRoutePath(docName)}`;
  return anchor ? `${base}#${encodeSegment(anchor)}` : base;
}

const MIRROR_SOURCE_ANCHOR_PREFIX = 'source:';

export function hashFromMirrorSource(docName: string, sourceName: string): string {
  return `${hashFromDocName(docName)}#${MIRROR_SOURCE_ANCHOR_PREFIX}${encodeSegment(sourceName)}`;
}

export function mirrorSourceNameFromAnchor(anchor: string): string | null {
  if (!anchor.startsWith(MIRROR_SOURCE_ANCHOR_PREFIX)) return null;
  const sourceName = anchor.slice(MIRROR_SOURCE_ANCHOR_PREFIX.length);
  return sourceName === '' ? null : sourceName;
}

export function isSameHash(a: string, b: string): boolean {
  return a === b || decodeHashForComparison(a) === decodeHashForComparison(b);
}

function decodeHashForComparison(hash: string): string {
  try {
    return decodeURIComponent(hash);
  } catch {
    return hash;
  }
}

const MANAGED_HASH_HISTORY_STATE_KEY = '__okHashHistoryEntry';
const MANAGED_HASH_HISTORY_DISPOSITION_KEY = '__okHashHistoryDisposition';

export interface ManagedHashHistoryEntry {
  disposition: TabOpenDisposition;
}

function managedHashHistoryState(
  state: unknown,
  entry?: ManagedHashHistoryEntry,
): Record<string, unknown> {
  const preservedState = typeof state === 'object' && state !== null ? state : {};
  const unmanagedState = { ...(preservedState as Record<string, unknown>) };
  delete unmanagedState[MANAGED_HASH_HISTORY_DISPOSITION_KEY];
  return {
    ...unmanagedState,
    [MANAGED_HASH_HISTORY_STATE_KEY]: true,
    ...(entry ? { [MANAGED_HASH_HISTORY_DISPOSITION_KEY]: entry.disposition } : {}),
  };
}

export function isManagedHashHistoryState(state: unknown): boolean {
  return (
    typeof state === 'object' &&
    state !== null &&
    (state as Record<string, unknown>)[MANAGED_HASH_HISTORY_STATE_KEY] === true
  );
}

export function readManagedHashHistoryEntry(state: unknown): ManagedHashHistoryEntry | null {
  if (!isManagedHashHistoryState(state)) return null;
  const disposition = (state as Record<string, unknown>)[MANAGED_HASH_HISTORY_DISPOSITION_KEY];
  if (disposition !== 'preview' && disposition !== 'permanent') return null;
  return { disposition };
}

export function markCurrentHashHistoryEntry(): void {
  if (isManagedHashHistoryState(window.history.state)) return;
  window.history.replaceState(managedHashHistoryState(window.history.state), '');
}

function replaceManagedHashEntry(hash: string, entry?: ManagedHashHistoryEntry): void {
  const { pathname, search } = window.location;
  window.history.replaceState(
    managedHashHistoryState(window.history.state, entry),
    '',
    `${pathname}${search}${hash}`,
  );
}

export function replaceHashWithoutNavigation(hash: string, disposition: TabOpenDisposition): void {
  replaceManagedHashEntry(hash, { disposition });
}

export function clearHashWithoutNavigation(): void {
  replaceManagedHashEntry('');
}

export function pushHashWithoutNavigation(hash: string, disposition: TabOpenDisposition): void {
  if (isSameHash(window.location.hash, hash)) return;
  const { pathname, search } = window.location;
  window.history.pushState(
    managedHashHistoryState(window.history.state, { disposition }),
    '',
    `${pathname}${search}${hash}`,
  );
}

export function filePathToDocName(filePath: string): string {
  const lower = filePath.toLowerCase();
  if (lower.endsWith('.mdx')) return filePath.slice(0, -4);
  if (lower.endsWith('.md')) return filePath.slice(0, -3);
  return filePath;
}

export function hashFromFolderPath(folderPath: string, anchor?: string | null): string {
  const normalized = folderPath.replace(/^\/+|\/+$/g, '');
  const base = normalized ? `#/${encodeRoutePath(normalized)}/` : '#/';
  return anchor ? `${base}#${encodeSegment(anchor)}` : base;
}

export function encodeShareTargetForHash(
  kind: 'doc' | 'folder',
  path: string,
  branch?: string | null,
): string {
  if (kind === 'folder') return hashFromFolderPath(path);
  const base = `#/${encodeSegment(path)}`;
  if (branch === undefined || branch === null || branch === '') return base;
  return `${base}?branch=${encodeSegment(branch)}`;
}

export function isContentRootHash(hash: string): boolean {
  if (hash === '#/') return true;
  if (!hash.startsWith('#/')) return false;
  const rest = hash.slice(2);
  return rest.length > 0 && rest[0] === '?';
}

const ASSET_HASH_PREFIX = '#/__asset__/';

function firstRouteDelimiterIndex(rest: string): number {
  const qmark = rest.indexOf('?');
  const fragment = rest.indexOf('#');
  if (qmark < 0) return fragment;
  if (fragment < 0) return qmark;
  return Math.min(qmark, fragment);
}

export function assetPathFromHash(hash: string): string | null {
  if (!hash.startsWith(ASSET_HASH_PREFIX)) return null;
  const encoded = hash.slice(ASSET_HASH_PREFIX.length);
  if (!encoded) return null;
  try {
    return encoded.split('/').map(decodeURIComponent).join('/');
  } catch {
    return encoded;
  }
}

export function hashFromAssetPath(assetPath: string): string {
  return `${ASSET_HASH_PREFIX}${encodeRoutePath(assetPath)}`;
}

const SKILL_FILE_HASH_PREFIX = '#/__skill-file__/';

const SKILLS_HASH_PREFIX = '#/__skills__';
export function skillsFromHash(hash: string): boolean {
  return hash === SKILLS_HASH_PREFIX || hash.startsWith(`${SKILLS_HASH_PREFIX}/`);
}

const SKILL_PREVIEW_HASH_PREFIX = '#/__skill-preview__/';
const SKILL_PREVIEW_FLAVORS = ['explore', 'detected', 'builtin', 'foreign', 'linked'] as const;
export type SkillPreviewFlavor = (typeof SKILL_PREVIEW_FLAVORS)[number];
function isSkillPreviewFlavor(v: string | undefined): v is SkillPreviewFlavor {
  return v !== undefined && (SKILL_PREVIEW_FLAVORS as readonly string[]).includes(v);
}
export interface SkillPreviewHashTarget {
  flavor: SkillPreviewFlavor;
  source: string;
  name: string;
  subtitle: string;
  level?: SkillScope;
  path?: string;
}

const DEFAULT_PREVIEW_LEVEL: SkillScope = 'project';

export function encodeSkillPreviewSegments(target: SkillPreviewHashTarget): string {
  return [
    target.flavor,
    target.source,
    target.name,
    target.subtitle,
    target.level ?? DEFAULT_PREVIEW_LEVEL,
  ]
    .map(encodeSegment)
    .join('/');
}

export function decodeSkillPreviewSegments(body: string): SkillPreviewHashTarget | null {
  if (!body) return null;
  let segments: string[];
  try {
    segments = body.split('/').map(decodeURIComponent);
  } catch {
    return null;
  }
  if (segments.length < 4 || segments.length > 6) return null;
  const [flavor, source, name, subtitle, level, path] = segments;
  if (!isSkillPreviewFlavor(flavor)) return null;
  if (!source || !name) return null;
  return {
    flavor,
    source,
    name,
    subtitle: subtitle ?? '',
    ...(level && isSkillScope(level) ? { level } : {}),
    ...(path ? { path } : {}),
  };
}

export function hashFromSkillPreview(target: SkillPreviewHashTarget): string {
  let body = encodeSkillPreviewSegments(target);
  if (target.path) body += `/${encodeSegment(target.path)}`;
  return `${SKILL_PREVIEW_HASH_PREFIX}${body}`;
}

export function skillPreviewFromHash(hash: string): SkillPreviewHashTarget | null {
  if (!hash.startsWith(SKILL_PREVIEW_HASH_PREFIX)) return null;
  return decodeSkillPreviewSegments(hash.slice(SKILL_PREVIEW_HASH_PREFIX.length));
}

export function selectedPathForSkillPreview(
  hash: string,
  target: SkillPreviewHashTarget,
): string | undefined {
  const hashTarget = skillPreviewFromHash(hash);
  if (!hashTarget) return undefined;
  return encodeSkillPreviewSegments(hashTarget) === encodeSkillPreviewSegments(target)
    ? hashTarget.path
    : undefined;
}

export interface SkillFileHashTarget {
  scope: SkillScope;
  name: string;
  path: string;
  host?: string;
}

const SKILL_FILE_HOST_SEP = ':';

export function hashFromSkillFile(target: SkillFileHashTarget): string {
  const named =
    target.host === undefined ? target.name : `${target.name}${SKILL_FILE_HOST_SEP}${target.host}`;
  const head = [target.scope, named].map(encodeSegment).join('/');
  const tail = encodeRoutePath(target.path);
  return `${SKILL_FILE_HASH_PREFIX}${head}/${tail}`;
}

export function skillFileFromHash(hash: string): SkillFileHashTarget | null {
  if (!hash.startsWith(SKILL_FILE_HASH_PREFIX)) return null;
  const encoded = hash.slice(SKILL_FILE_HASH_PREFIX.length);
  if (!encoded) return null;
  let segments: string[];
  try {
    segments = encoded.split('/').map(decodeURIComponent);
  } catch {
    return null;
  }
  if (segments.length < 3) return null;
  const [scope, named, ...rest] = segments;
  const path = rest.join('/');
  if (!scope || !named || !path || !isSkillScope(scope)) return null;
  const sep = named.indexOf(SKILL_FILE_HOST_SEP);
  const name = sep === -1 ? named : named.slice(0, sep);
  const host = sep === -1 ? undefined : named.slice(sep + 1);
  if (!name) return null;
  return { scope, name, path, ...(host ? { host } : {}) };
}