Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

17.7 KB
Raw Blame
// oxlint-disable ok/no-raw-error-toast -- pre-rule backlog: toasts here show raw error text; delete this line once the file maps each failure to written copy. See https://github.com/inkeep/open-knowledge/blob/main/lint-plugins/ok-rules/README.md#no-raw-error-toast
import type { ConfigBinding } from '@inkeep/open-knowledge-core/config/bind-config-doc';
import { humanFormat } from '@inkeep/open-knowledge-core/config/errors';
import { externalSkillLiveDocName } from '@inkeep/open-knowledge-core/constants/cc1';
import type { SkillScope, SkillsListEntry } from '@inkeep/open-knowledge-core/schemas/api';
import type { CatalogSkill } from '@inkeep/open-knowledge-core/skills-catalog/schema';
import { catalogRawScopeToOkScope } from '@inkeep/open-knowledge-core/skills-catalog/scope';
import { Trans, useLingui } from '@lingui/react/macro';
import { lazy, Suspense, useEffect, useLayoutEffect, useRef, useState } from 'react';
import { toast } from 'sonner';
import type { AddSkillTab } from '@/components/ImportSkillDialog';
import { NewSkillDialog } from '@/components/NewSkillDialog';
import { SkillsTree } from '@/components/SkillsTree';
import { useSkillActions } from '@/components/skill-actions';
import { SidebarGroup, SidebarGroupContent } from '@/components/ui/sidebar';
import { Spinner } from '@/components/ui/spinner';
import { useDocumentContext } from '@/editor/DocumentContext';
import { findLocalSkillPreviewTabId } from '@/editor/editor-tabs';
import { previewOpenDisposition } from '@/editor/preview-open-disposition';
import { useCreateBlankSkill } from '@/hooks/use-create-blank-skill';
import { useOpenSkill } from '@/hooks/use-open-skill';
import { useOpenSkillForEdit } from '@/hooks/use-open-skill-for-edit';
import { useSkills } from '@/hooks/use-skills';
import { useSettingsLoadingReason } from '@/lib/config-context';
import { useConfigContext } from '@/lib/config-provider';
import {
  hashFromDocName,
  hashFromSkillFile,
  hashFromSkillPreview,
  pushHashWithoutNavigation,
  type SkillPreviewHashTarget,
} from '@/lib/doc-hash';
import { subscribeToSkillScopeMoved, subscribeToSkillsChanged } from '@/lib/documents-events';
import { skillEntryFileLiveDocName, skillEntryLiveDocName } from '@/lib/managed-artifact-doc-name';
import { PIN_FIELD, readPins, togglePin } from '@/lib/skill-pins';
import {
  SKILL_SCOPE_ORDER,
  skillDir,
  skillNameSetsByScope,
  useSkillScopeDescriptions,
  useSkillScopeLabels,
} from '@/lib/skill-scope';
import { createSkillSortComparator, SKILL_MD_PATH } from '@/lib/skill-sort';
import { requestSkillTrackPrompt } from '@/lib/skill-track-prompt-store';
import { fetchSkillPreview, listDetectedSkills } from '@/lib/skills-api';
import { buildSkillsTreePaths, detectedId, isSkillDocActive } from '@/lib/skills-tree-paths';

const ImportSkillDialog = lazy(() =>
  import('@/components/ImportSkillDialog').then((m) => ({ default: m.ImportSkillDialog })),
);

export function SkillsSidebarSection({ dockExpanded = false }: { dockExpanded?: boolean } = {}) {
  const state = useSkills();
  const { t } = useLingui();
  const { openTarget, activeDocName, activeTarget, openTabs, activateTab } = useDocumentContext();
  const { merged, userBinding, userSynced, projectLocalBinding, projectLocalSynced } =
    useConfigContext();
  const previewTabsEnabled = merged?.editor?.previewTabs ?? true;
  const tabDisposition = previewOpenDisposition(previewTabsEnabled);
  const showSkillGroups = merged?.appearance?.sidebar?.showSkillGroups ?? true;
  const pinnedByScope = {
    project: readPins(merged, 'project'),
    global: readPins(merged, 'global'),
  };
  const pinBindingByScope: Record<SkillScope, ConfigBinding | null> = {
    global: userSynced ? userBinding : null,
    project: projectLocalSynced ? projectLocalBinding : null,
  };
  const pinningReadyByScope: Record<SkillScope, boolean> = {
    global: pinBindingByScope.global !== null,
    project: pinBindingByScope.project !== null,
  };
  const settingsLoadingReason = useSettingsLoadingReason();
  const togglePinned = (scope: SkillScope, name: string, pinned: boolean) => {
    const binding = pinBindingByScope[scope];
    if (binding === null) {
      toast.info(settingsLoadingReason, { id: `pin-not-ready-${scope}` });
      return;
    }
    const next = togglePin(pinnedByScope[scope], name, pinned);
    const result = binding.patch({ appearance: { sidebar: { [PIN_FIELD[scope]]: next } } });
    if (!result.ok) {
      toast.error(pinned ? t`Couldn't pin ${name}` : t`Couldn't unpin ${name}`, {
        description: humanFormat(result.error),
      });
    }
  };

  const openSkill = useOpenSkill();
  const openSkillForEdit = useOpenSkillForEdit();
  const actions = useSkillActions();
  const scopeLabel = useSkillScopeLabels();
  const scopeDescription = useSkillScopeDescriptions();

  const togglePinnedRef = useRef(togglePinned);
  useEffect(() => {
    togglePinnedRef.current = togglePinned;
  });
  const pinnedByScopeRef = useRef(pinnedByScope);
  useEffect(() => {
    pinnedByScopeRef.current = pinnedByScope;
  });
  const pinningReadyByScopeRef = useRef(pinningReadyByScope);
  useEffect(() => {
    pinningReadyByScopeRef.current = pinningReadyByScope;
  });
  useEffect(
    () =>
      subscribeToSkillScopeMoved(({ name, fromScope, toScope }) => {
        if (!pinnedByScopeRef.current[fromScope].has(name)) return;
        if (
          !pinningReadyByScopeRef.current[fromScope] ||
          !pinningReadyByScopeRef.current[toScope]
        ) {
          toast.info(
            t`${name} moved, but its pin did not. Pin it again after settings finish loading.`,
          );
          return;
        }
        togglePinnedRef.current(fromScope, name, false);
        togglePinnedRef.current(toScope, name, true);
      }),
    [t],
  );

  const skills = state.status === 'ready' ? state.data : [];
  const nameSets = skillNameSetsByScope(skills);
  const [userExpanded, setUserExpanded] = useState<ReadonlySet<string>>(() => new Set());
  const { createBlank, creating } = useCreateBlankSkill();
  const [addSkill, setAddSkill] = useState<{ scope: SkillScope; tab: AddSkillTab } | null>(null);
  const [newSkillScope, setNewSkillScope] = useState<SkillScope | null>(null);

  const [detected, setDetected] = useState<CatalogSkill[] | null>(null);
  const [detectedFilesById, setDetectedFilesById] = useState<Record<string, readonly string[]>>({});
  useEffect(() => {
    if (!dockExpanded) return;
    let alive = true;
    const load = () => {
      void listDetectedSkills().then((r) => {
        if (!alive) return;
        if (r.ok) setDetected(r.skills);
        else {
          console.warn('[skills-sidebar] listDetectedSkills failed:', r);
          setDetected([]);
        }
      });
    };
    load();
    const unsub = subscribeToSkillsChanged(load);
    return () => {
      alive = false;
      unsub();
    };
  }, [dockExpanded]);

  const sharedNameKeys = new Set<string>();
  {
    const seen = new Set<string>();
    for (const s of skills) {
      const k = `${s.scope}:${s.name}`;
      if (seen.has(k)) sharedNameKeys.add(k);
      seen.add(k);
    }
  }
  const hostQualifierOf = (s: SkillsListEntry): string | undefined =>
    sharedNameKeys.has(`${s.scope}:${s.name}`) ? s.hosts[0] : undefined;
  const skillRowKey = (s: SkillsListEntry): string =>
    `${s.scope}:${s.name}:${hostQualifierOf(s) ?? ''}`;

  const filesByKey: Record<string, readonly { path: string }[]> = Object.fromEntries(
    skills.map((s) => [skillRowKey(s), (s.filePaths ?? []).map((path) => ({ path }))]),
  );

  const sectionRef = useRef<HTMLDivElement | null>(null);
  const lastScrollTopRef = useRef(0);
  const restoringRef = useRef(false);
  useEffect(() => {
    if (!dockExpanded) return;
    const scroller = sectionRef.current?.closest<HTMLElement>(DOCK_SCROLLER_SELECTOR);
    if (!scroller) return;
    const onScroll = () => {
      if (!restoringRef.current) lastScrollTopRef.current = scroller.scrollTop;
    };
    scroller.addEventListener('scroll', onScroll, { passive: true });
    return () => scroller.removeEventListener('scroll', onScroll);
  }, [dockExpanded]);

  if (!dockExpanded) {
    return null;
  }

  const openSkillDoc = (docName: string) => {
    openTarget({ kind: 'doc', target: docName, docName }, { disposition: tabDisposition });
    pushHashWithoutNavigation(hashFromDocName(docName), tabDisposition);
  };
  const openSkillMd = (skill: SkillsListEntry) => {
    openSkill(skill.scope, skill.name, {
      replaceActive: previewTabsEnabled,
      ...(skill.path ? { path: skill.path } : {}),
      ...(skill.hostQualifier !== undefined ? { host: skill.hostQualifier } : {}),
    });
  };
  const openPreviewReplacing = (target: SkillPreviewHashTarget) => {
    if (target.flavor !== 'explore' && target.level) {
      const existing = findLocalSkillPreviewTabId(
        openTabs,
        target.flavor,
        target.name,
        target.subtitle ?? '',
        target.level,
      );
      if (existing) {
        activateTab(existing);
        pushHashWithoutNavigation(hashFromSkillPreview(target), tabDisposition);
        return;
      }
    }
    openTarget(
      {
        kind: 'skill-preview' as const,
        target: `${target.flavor}/${target.source}/${target.name}`,
        flavor: target.flavor,
        source: target.source,
        name: target.name,
        subtitle: target.subtitle,
        level: target.level,
        path: target.path,
      },
      { disposition: tabDisposition },
    );
    pushHashWithoutNavigation(hashFromSkillPreview(target), tabDisposition);
  };
  const openManaged = (skill: SkillsListEntry) => {
    openPreviewReplacing({
      flavor: 'builtin',
      source: skillDir(skill.absolutePath ?? ''),
      name: skill.name,
      subtitle: '',
      level: skill.scope,
    });
  };
  const openFile = (skill: SkillsListEntry, filePath: string) => {
    if (skill.ignored === true && !skill.managed) {
      requestSkillTrackPrompt({ scope: skill.scope, name: skill.name });
      return;
    }
    const dot = filePath.lastIndexOf('.');
    const ext = dot >= 0 ? filePath.slice(dot + 1).toLowerCase() : '';
    if (!skill.managed && (ext === 'md' || ext === 'mdx')) {
      openSkillDoc(skillEntryFileLiveDocName(skill, filePath));
      return;
    }
    const host = hostQualifierOf(skill);
    openTarget(
      {
        kind: 'skill-file' as const,
        target: `${skill.scope}/${skill.name}${host ? `:${host}` : ''}/${filePath}`,
        scope: skill.scope,
        name: skill.name,
        path: filePath,
        ...(host ? { host } : {}),
      },
      { disposition: tabDisposition },
    );
    pushHashWithoutNavigation(
      hashFromSkillFile({
        scope: skill.scope,
        name: skill.name,
        path: filePath,
        ...(host ? { host } : {}),
      }),
      tabDisposition,
    );
  };
  const isPreviewActiveFor = (name: string, scope: SkillScope, path?: string): boolean =>
    activeTarget?.kind === 'skill-preview' &&
    activeTarget.name === name &&
    activeTarget.level === scope &&
    activeTarget.path === path;
  const isFileActive = (skill: SkillsListEntry, filePath: string): boolean => {
    const ext = filePath.slice(filePath.lastIndexOf('.') + 1).toLowerCase();
    if (!skill.managed && (ext === 'md' || ext === 'mdx')) {
      return activeDocName === skillEntryFileLiveDocName(skill, filePath);
    }
    return (
      (activeTarget?.kind === 'skill-file' &&
        activeTarget.scope === skill.scope &&
        activeTarget.name === skill.name &&
        activeTarget.path === filePath) ||
      isPreviewActiveFor(skill.name, skill.scope, filePath)
    );
  };
  const isSkillMdActive = (skill: SkillsListEntry): boolean =>
    isSkillDocActive({
      activeTargetKind: activeTarget?.kind,
      activeDocName,
      openTabs,
      docName: skillEntryLiveDocName(skill),
    }) || isPreviewActiveFor(skill.name, skill.scope);

  const ensureDetectedFiles = (s: CatalogSkill, source: string) => {
    const id = detectedId(s);
    if (detectedFilesById[id] !== undefined) return;
    void fetchSkillPreview({ source, name: s.name }).then((r) => {
      if (!r.ok) return;
      setDetectedFilesById((prev) => ({ ...prev, [id]: r.files.map((f) => f.relPath) }));
    });
  };
  const openDetected = (s: CatalogSkill, sub?: string) => {
    const source = skillDir(s.files.skillMd);
    ensureDetectedFiles(s, source);
    const rel = sub && sub !== SKILL_MD_PATH ? sub : undefined;
    const trapped =
      s.provenance.plugin !== undefined ? 'detected' : s.outsideProject ? 'foreign' : null;
    if (trapped !== null) {
      openPreviewReplacing({
        flavor: trapped,
        source,
        name: s.name,
        subtitle: s.sourceHarness ?? '',
        level: catalogRawScopeToOkScope(s.provenance.scope),
        ...(rel !== undefined ? { path: sub } : {}),
      });
      return;
    }
    void openSkillForEdit(s.name, source, { replaceActive: previewTabsEnabled, rel }).then((r) => {
      if (!r.ok) toast.error(t`Couldn't open ${s.name} for editing: ${r.error}`);
    });
  };

  const labelToScope = new Map(SKILL_SCOPE_ORDER.map((s) => [scopeLabel[s], s] as const));
  const {
    paths,
    expanded,
    activePath,
    skillByPrefix,
    detectedByPrefix,
    groupByPrefix,
    pinnedPrefixes,
  } = buildSkillsTreePaths({
    skills,
    detected,
    scopeLabel,
    filesByKey,
    detectedFilesById,
    userExpanded,
    hostQualifierOf,
    rowKeyFor: skillRowKey,
    isSkillMdActive,
    isFileActive,
    isDetectedActive: (s) =>
      activeDocName === externalSkillLiveDocName(s.name) ||
      isPreviewActiveFor(s.name, catalogRawScopeToOkScope(s.provenance.scope)),
    showSkillGroups,
    pinnedByScope,
  });

  const skillSort = createSkillSortComparator(
    labelToScope,
    detectedByPrefix,
    groupByPrefix,
    skillByPrefix,
    pinnedPrefixes,
  );

  const stateKey = `${skills.map((s) => `${s.installed ? 1 : 0}`).join('')}|d${detectedByPrefix.size}`;

  const skillsLoading = state.status === 'loading';
  const treeKey = `${paths.join('|')}::${stateKey}::p${[...pinnedPrefixes].sort().join(',')}`;

  return (
    <SidebarGroup ref={sectionRef} className="px-0">
      <SidebarGroupContent>
        {skillsLoading ? (
          <div
            className="flex items-center gap-2 px-3 py-1.5 text-muted-foreground text-xs"
            data-testid="skills-loading"
            role="status"
            aria-live="polite"
          >
            <Spinner className="size-3.5" aria-hidden />
            <Trans>Loading skills</Trans>
          </div>
        ) : null}
        <TreeScrollKeeper
          key={`keep::${treeKey}`}
          sectionRef={sectionRef}
          lastScrollTopRef={lastScrollTopRef}
          restoringRef={restoringRef}
        />
        <SkillsTree
          key={treeKey}
          paths={paths}
          activePath={activePath}
          initialExpandedPaths={expanded}
          onExpandedChange={setUserExpanded}
          sort={skillSort}
          pinnedPrefixes={pinnedPrefixes}
          pinningReadyByScope={pinningReadyByScope}
          isPinned={(scope, name) => pinnedByScope[scope].has(name)}
          onTogglePin={togglePinned}
          skillByPrefix={skillByPrefix}
          detectedByPrefix={detectedByPrefix}
          groupByPrefix={groupByPrefix}
          labelToScope={labelToScope}
          scopeDescription={scopeDescription}
          existingNames={nameSets}
          actions={actions}
          onOpenSkillMd={openSkillMd}
          onOpenFile={openFile}
          onOpenDetected={openDetected}
          onOpenManaged={openManaged}
          onNewSkill={(scope) => setNewSkillScope(scope)}
          onAddSkill={(scope, tab) => setAddSkill({ scope, tab })}
        />
      </SidebarGroupContent>
      {newSkillScope !== null ? (
        <NewSkillDialog
          open
          scope={newSkillScope}
          existingNames={nameSets[newSkillScope]}
          busy={creating}
          onOpenChange={(open) => {
            if (!open) setNewSkillScope(null);
          }}
          onCreate={({ name, description }) => {
            const scope = newSkillScope;
            setNewSkillScope(null);
            void createBlank(scope, { name, description });
          }}
        />
      ) : null}
      {actions.dialogs}
      {addSkill !== null ? (
        <Suspense fallback={null}>
          <ImportSkillDialog
            defaultScope={addSkill.scope}
            defaultTab={addSkill.tab}
            open
            onOpenChange={(open) => {
              if (!open) setAddSkill(null);
            }}
            onImported={({ scope, name }) => {
              setAddSkill(null);
              openSkill(scope, name);
            }}
          />
        </Suspense>
      ) : null}
    </SidebarGroup>
  );
}

const DOCK_SCROLLER_SELECTOR = '[data-slot="collapsible-content"]';

function TreeScrollKeeper({
  sectionRef,
  lastScrollTopRef,
  restoringRef,
}: {
  sectionRef: React.RefObject<HTMLDivElement | null>;
  lastScrollTopRef: React.RefObject<number>;
  restoringRef: React.RefObject<boolean>;
}) {
  useLayoutEffect(() => {
    const saved = lastScrollTopRef.current;
    if (saved <= 0) return;
    const scroller = sectionRef.current?.closest<HTMLElement>(DOCK_SCROLLER_SELECTOR);
    if (!scroller) return;
    restoringRef.current = true;
    const deadline = Date.now() + 1000;
    let raf = 0;
    const tick = () => {
      if (scroller.scrollHeight - scroller.clientHeight >= saved) {
        scroller.scrollTop = saved;
        restoringRef.current = false;
        return;
      }
      if (Date.now() < deadline) {
        raf = requestAnimationFrame(tick);
        return;
      }
      lastScrollTopRef.current = Math.min(
        saved,
        Math.max(0, scroller.scrollHeight - scroller.clientHeight),
      );
      restoringRef.current = false;
    };
    tick();
    return () => {
      cancelAnimationFrame(raf);
      restoringRef.current = false;
    };
  }, [sectionRef, lastScrollTopRef, restoringRef]);
  return null;
}