@bendyline/docblocks-react 1.1.1 → 2.0.0

package/src/FileExplorer/useFileTree.ts

@@ -4,7 +4,54 @@
  */
 
 import { useState, useCallback, useEffect, useRef } from 'react';
-import type { FileSystemProvider, FileSystemEntry } from '@bendyline/docblocks/filesystem';
+import {
+  getFileSystemProviderV2,
+  moveFileSystemEntry,
+  parseWorkspacePath,
+  type FileSystemProvider,
+  type FileSystemEntry,
+} from '@bendyline/docblocks/filesystem';
+
+function normalisePath(path: string): string {
+  return parseWorkspacePath(path);
+}
+
+function relocatePath(path: string, oldPath: string, newPath: string): string {
+  const current = normalisePath(path);
+  const oldNormalised = normalisePath(oldPath);
+  if (current !== oldNormalised && !current.startsWith(`${oldNormalised}/`)) return path;
+  const suffix = current.slice(oldNormalised.length);
+  return `${newPath.replace(/\/+$/, '')}${suffix}`;
+}
+
+function ancestorPaths(path: string): string[] {
+  const canonical = normalisePath(path);
+  if (!canonical) return [];
+  const segments = canonical.split('/');
+  const prefix = /^[\\/]/u.test(path) ? '/' : '';
+  return segments
+    .slice(0, -1)
+    .map((_, index) => `${prefix}${segments.slice(0, index + 1).join('/')}`);
+}
+
+function equivalentPathKeys(path: string): string[] {
+  const canonical = normalisePath(path);
+  return canonical ? [path, canonical, `/${canonical}`] : [path, canonical];
+}
+
+function hasEquivalentPath(paths: ReadonlySet<string>, path: string): boolean {
+  return equivalentPathKeys(path).some((candidate) => paths.has(candidate));
+}
+
+async function readProviderDirectory(
+  provider: FileSystemProvider,
+  path: string,
+): Promise<FileSystemEntry[]> {
+  const providerV2 = getFileSystemProviderV2(provider);
+  if (!providerV2) return provider.readDirectory(path);
+  const entries = await providerV2.readDirectory(parseWorkspacePath(path));
+  return entries.map((entry) => ({ kind: entry.kind, name: entry.name, path: entry.path }));
+}
 
 export interface FileTreeState {
   /** Flat list of entries for the current directory view. */
@@ -24,14 +71,16 @@ export interface FileTreeActions {
   toggleExpand: (path: string) => void;
   /** Select a file or directory. */
   select: (path: string, kind: 'file' | 'directory') => void;
+  /** Select an entry and expand each directory needed to reveal it. */
+  reveal: (path: string, kind: 'file' | 'directory') => void;
   /** Create a new file with optional initial content. */
   createFile: (path: string, content?: string) => Promise<void>;
   /** Create a new directory. */
   createDirectory: (path: string) => Promise<void>;
   /** Delete a file or directory. */
   deleteEntry: (path: string) => Promise<void>;
-  /** Rename a file or directory. */
-  renameEntry: (oldPath: string, newPath: string) => Promise<void>;
+  /** Rename or move a file or directory, including a markdown companion folder. */
+  renameEntry: (oldPath: string, newPath: string, kind?: 'file' | 'directory') => Promise<void>;
   /** Force refresh the tree. */
   refresh: () => Promise<void>;
 }
@@ -56,7 +105,7 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
     }
     setLoading(true);
     try {
-      const root = await providerRef.current.readDirectory('');
+      const root = await readProviderDirectory(providerRef.current, '');
       setEntries(root);
     } finally {
       setLoading(false);
@@ -65,7 +114,7 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
 
   const loadChildren = useCallback(async (dirPath: string) => {
     if (!providerRef.current) return;
-    const children = await providerRef.current.readDirectory(dirPath);
+    const children = await readProviderDirectory(providerRef.current, dirPath);
     setChildEntries((prev) => {
       const next = new Map(prev);
       next.set(dirPath, children);
@@ -86,8 +135,8 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
     (path: string) => {
       setExpanded((prev) => {
         const next = new Set(prev);
-        if (next.has(path)) {
-          next.delete(path);
+        if (hasEquivalentPath(next, path)) {
+          for (const candidate of equivalentPathKeys(path)) next.delete(candidate);
         } else {
           next.add(path);
           // Load children when expanding
@@ -104,6 +153,25 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
     setSelectedKind(kind);
   }, []);
 
+  const reveal = useCallback(
+    (path: string, kind: 'file' | 'directory') => {
+      const ancestors = ancestorPaths(path);
+      setSelectedPath(path);
+      setSelectedKind(kind);
+      setExpanded((prev) => {
+        const next = new Set(prev);
+        for (const ancestor of ancestors) {
+          if (!hasEquivalentPath(next, ancestor)) next.add(ancestor);
+        }
+        return next;
+      });
+      for (const ancestor of ancestors) {
+        void loadChildren(ancestor);
+      }
+    },
+    [loadChildren],
+  );
+
   const refresh = useCallback(async () => {
     await loadRoot();
     // Reload all expanded directories
@@ -113,10 +181,82 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
     }
   }, [loadRoot, loadChildren, expanded]);
 
+  const refreshRef = useRef(refresh);
+  refreshRef.current = refresh;
+
+  // Keep the explorer synchronized with provider changes. Watch-capable
+  // providers (including Electron's chokidar-backed provider) update in real
+  // time. Calls are serialized and coalesced so event bursts cannot publish
+  // directory reads out of order.
+  useEffect(() => {
+    if (!provider) return;
+    const providerV2 = getFileSystemProviderV2(provider);
+    if (!providerV2?.capabilities.watch) return;
+
+    let disposed = false;
+    let refreshing = false;
+    let refreshAgain = false;
+
+    const requestRefresh = () => {
+      if (disposed) return;
+      if (refreshing) {
+        refreshAgain = true;
+        return;
+      }
+      refreshing = true;
+      void (async () => {
+        try {
+          do {
+            refreshAgain = false;
+            await refreshRef.current();
+          } while (refreshAgain && !disposed);
+        } catch {
+          // A later watcher event or window resume will retry the read.
+        } finally {
+          refreshing = false;
+          if (refreshAgain && !disposed) requestRefresh();
+        }
+      })();
+    };
+
+    const subscription = providerV2.watch(requestRefresh, { onError: requestRefresh });
+    void subscription.ready.catch(() => undefined);
+    return () => {
+      disposed = true;
+      void subscription.dispose();
+    };
+  }, [provider]);
+
+  // File System Access and IndexedDB do not expose a dependable external
+  // watcher. Refreshing on resume catches changes made while this surface was
+  // in the background without continuously polling the filesystem.
+  useEffect(() => {
+    if (!provider) return;
+    const refreshOnFocus = () => {
+      void refreshRef.current().catch(() => undefined);
+    };
+    const refreshOnVisibility = () => {
+      if (document.visibilityState === 'visible') refreshOnFocus();
+    };
+    window.addEventListener('focus', refreshOnFocus);
+    document.addEventListener('visibilitychange', refreshOnVisibility);
+    return () => {
+      window.removeEventListener('focus', refreshOnFocus);
+      document.removeEventListener('visibilitychange', refreshOnVisibility);
+    };
+  }, [provider]);
+
   const createFile = useCallback(
     async (path: string, content = '') => {
       if (!providerRef.current) return;
-      await providerRef.current.writeFile(path, content);
+      const providerV2 = getFileSystemProviderV2(providerRef.current);
+      if (providerV2) {
+        await providerV2.writeFile(parseWorkspacePath(path), new TextEncoder().encode(content), {
+          mode: 'create',
+        });
+      } else {
+        await providerRef.current.writeFile(path, content);
+      }
       await refresh();
     },
     [refresh],
@@ -125,7 +265,12 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
   const createDirectory = useCallback(
     async (path: string) => {
       if (!providerRef.current) return;
-      await providerRef.current.createDirectory(path);
+      const providerV2 = getFileSystemProviderV2(providerRef.current);
+      if (providerV2) {
+        await providerV2.createDirectory(parseWorkspacePath(path), { mode: 'create' });
+      } else {
+        await providerRef.current.createDirectory(path);
+      }
       await refresh();
     },
     [refresh],
@@ -134,7 +279,20 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
   const deleteEntry = useCallback(
     async (path: string) => {
       if (!providerRef.current) return;
-      await providerRef.current.delete(path);
+      const providerV2 = getFileSystemProviderV2(providerRef.current);
+      if (providerV2) {
+        const canonical = parseWorkspacePath(path);
+        const entry = await providerV2.stat(canonical);
+        if (entry) {
+          await providerV2.remove(canonical, {
+            recursive: entry.kind === 'directory',
+            missing: 'error',
+            expectedVersion: entry.version,
+          });
+        }
+      } else {
+        await providerRef.current.delete(path);
+      }
       if (selectedPath === path) {
         setSelectedPath(null);
         setSelectedKind(null);
@@ -145,15 +303,30 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
   );
 
   const renameEntry = useCallback(
-    async (oldPath: string, newPath: string) => {
+    async (oldPath: string, newPath: string, kind?: 'file' | 'directory') => {
       if (!providerRef.current) return;
-      await providerRef.current.rename(oldPath, newPath);
-      if (selectedPath === oldPath) {
-        setSelectedPath(newPath);
+      const oldNormalised = normalisePath(oldPath);
+      const knownEntry = [...entries, ...childEntries.values()]
+        .flat()
+        .find((entry) => normalisePath(entry.path) === oldNormalised);
+      const entryKind = kind ?? knownEntry?.kind ?? 'file';
+      await moveFileSystemEntry(providerRef.current, oldPath, newPath, entryKind);
+
+      if (selectedPath) {
+        setSelectedPath(relocatePath(selectedPath, oldPath, newPath));
+      }
+
+      const nextExpanded = new Set(
+        [...expanded].map((path) => relocatePath(path, oldPath, newPath)),
+      );
+      setExpanded(nextExpanded);
+      setChildEntries(new Map());
+      await loadRoot();
+      for (const dirPath of nextExpanded) {
+        await loadChildren(dirPath);
       }
-      await refresh();
     },
-    [refresh, selectedPath],
+    [selectedPath, entries, childEntries, expanded, loadRoot, loadChildren],
   );
 
   // Merge root entries with child entries for a flat tree representation
@@ -167,6 +340,7 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
     loading,
     toggleExpand,
     select,
+    reveal,
     createFile,
     createDirectory,
     deleteEntry,

package/src/Git/GitAuthGuidanceDialog.tsx

@@ -0,0 +1,84 @@
+/**
+ * GitAuthGuidanceDialog — shown when a git operation fails to authenticate.
+ *
+ * DocBlocks deliberately never collects or stores credentials, so this
+ * dialog only explains the three supported sign-in routes (credential
+ * helper, GitHub CLI, SSH key). The copy is exported as a standalone
+ * component so the clone dialog can embed it after an auth failure.
+ */
+
+import { maybeGetDocBlocksHost } from '@bendyline/docblocks/host';
+import { Dialog } from '../components/Dialog.js';
+
+const LEARN_MORE_URL =
+  'https://docs.github.com/en/get-started/getting-started-with-git/caching-your-github-credentials-in-git';
+
+const OPERATION_LABELS: Record<'push' | 'pull' | 'fetch' | 'clone' | 'pr', string> = {
+  push: 'push',
+  pull: 'pull',
+  fetch: 'fetch',
+  clone: 'clone',
+  pr: 'create the pull request',
+};
+
+/** The credential guidance copy, reusable outside this dialog (clone flow). */
+export function GitCredentialGuidance({ detail }: { detail?: string }) {
+  return (
+    <>
+      <p className="db-settings-hint">
+        DocBlocks never stores Git credentials. Sign in with one of these, then try again:
+      </p>
+      <ul className="db-git-hint">
+        <li>
+          A git credential helper (<code>git config credential.helper</code>)
+        </li>
+        <li>
+          The GitHub CLI (<code>gh auth login</code>)
+        </li>
+        <li>An SSH key registered with your remote</li>
+      </ul>
+      {detail && (
+        <details>
+          <summary>Details</summary>
+          <p className="db-git-hint">{detail}</p>
+        </details>
+      )}
+    </>
+  );
+}
+
+export function GitAuthGuidanceDialog({
+  operation,
+  detail,
+  onClose,
+}: {
+  operation: 'push' | 'pull' | 'fetch' | 'clone' | 'pr';
+  detail?: string;
+  onClose: () => void;
+}) {
+  return (
+    <Dialog
+      title="Git needs credentials"
+      onClose={onClose}
+      footer={
+        <>
+          <button
+            type="button"
+            className="db-git-secondary-btn"
+            onClick={() => void maybeGetDocBlocksHost()?.shell.openExternal(LEARN_MORE_URL)}
+          >
+            Learn more
+          </button>
+          <button type="button" className="db-git-primary-btn" onClick={onClose}>
+            Close
+          </button>
+        </>
+      }
+    >
+      <p className="db-settings-hint">
+        Git could not authenticate with the remote while trying to {OPERATION_LABELS[operation]}.
+      </p>
+      <GitCredentialGuidance detail={detail} />
+    </Dialog>
+  );
+}

package/src/Git/GitBranchesDialog.tsx

@@ -0,0 +1,144 @@
+/**
+ * GitBranchesDialog — switch between local branches or create a new one.
+ *
+ * Loads the branch list once from the host git API on mount. Remote
+ * branches are display-only in v1 (a collapsed disclosure); switching and
+ * creating go through the GitValue actions so errors (e.g. uncommitted
+ * changes blocking a checkout) surface inline via lastResult.
+ */
+
+import { useEffect, useRef, useState } from 'react';
+import type { GitBranchInfo } from '@bendyline/docblocks/host';
+import { Dialog } from '../components/Dialog.js';
+import { useGitContext } from './GitContext.js';
+
+export function GitBranchesDialog({
+  createFocus,
+  onClose,
+}: {
+  createFocus?: boolean;
+  onClose: () => void;
+}) {
+  const git = useGitContext();
+  const gitApi = git?.gitApi ?? null;
+  const repositoryId = git?.repositoryId ?? null;
+
+  const [branches, setBranches] = useState<GitBranchInfo[] | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [newName, setNewName] = useState('');
+  const createInputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    if (!gitApi || !repositoryId) return;
+    let cancelled = false;
+    void gitApi.listBranches(repositoryId).then((result) => {
+      if (cancelled) return;
+      if (result.ok) setBranches(result.value);
+      else setLoadError(result.error.message || 'Could not list branches');
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [gitApi, repositoryId]);
+
+  if (!git) return null;
+
+  const locals = branches?.filter((b) => b.kind === 'local') ?? [];
+  const remotes = branches?.filter((b) => b.kind === 'remote') ?? [];
+  const canCreate = newName.trim().length > 0 && git.busy === null;
+
+  const handleSwitch = async (name: string) => {
+    const ok = await git.switchBranch(name);
+    if (ok) onClose();
+  };
+
+  const handleCreate = async () => {
+    if (!canCreate) return;
+    const ok = await git.createBranch(newName.trim());
+    if (ok) onClose();
+  };
+
+  return (
+    <Dialog
+      title="Branches"
+      onClose={onClose}
+      initialFocusRef={createFocus ? createInputRef : undefined}
+    >
+      {branches === null && loadError === null && <p className="db-git-hint">Loading branches…</p>}
+      {loadError !== null && (
+        <p className="db-git-form-error" role="alert">
+          {loadError}
+        </p>
+      )}
+      {branches !== null && (
+        <div className="db-git-branch-list">
+          {locals.map((branch) =>
+            branch.current ? (
+              <span
+                key={branch.name}
+                className="db-git-branch-row db-git-branch-row--current"
+                aria-current="true"
+              >
+                {branch.name}
+              </span>
+            ) : (
+              <button
+                key={branch.name}
+                type="button"
+                className="db-git-branch-row"
+                disabled={git.busy !== null}
+                onClick={() => void handleSwitch(branch.name)}
+              >
+                {branch.name}
+              </button>
+            ),
+          )}
+        </div>
+      )}
+      {git.lastResult?.tone === 'error' && (
+        <p className="db-git-form-error" role="alert">
+          {git.lastResult.message}
+        </p>
+      )}
+      <hr />
+      <div className="db-git-form-row">
+        <label className="db-git-form-label" htmlFor="db-git-new-branch-name">
+          New branch
+        </label>
+        <input
+          id="db-git-new-branch-name"
+          ref={createInputRef}
+          className="db-git-form-input"
+          type="text"
+          value={newName}
+          onChange={(e) => setNewName(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') void handleCreate();
+          }}
+          placeholder="feature/my-branch"
+          spellCheck={false}
+        />
+        <button
+          type="button"
+          className="db-git-primary-btn"
+          disabled={!canCreate}
+          onClick={() => void handleCreate()}
+        >
+          Create
+        </button>
+      </div>
+      {remotes.length > 0 && (
+        <details>
+          <summary>Remote branches ({remotes.length})</summary>
+          <div className="db-git-branch-list">
+            {remotes.map((branch) => (
+              <span key={branch.name} className="db-git-branch-row">
+                {branch.name}
+              </span>
+            ))}
+          </div>
+        </details>
+      )}
+    </Dialog>
+  );
+}