Update numpy-documentation-search extension

extensions/numpy-documentation-search/CHANGELOG.md

@@ -1,6 +1,16 @@
 # NumPy Documentation Search Changelog
 
-## [1.2.3] - 2025-10-09
+## [1.3.0] - {PR_MERGE_DATE}
+
+### Added
+- Add guided recovery when live access to `numpy.org` fails, including in-app setup steps for downloaded local docs
+- Add configurable documentation source preferences for auto and local directory modes
+
+### Changed
+- Fall back to local documentation when remote inventory loading fails
+- Load inline documentation previews from a configured local docs directory when network access is unavailable
+
+## [1.2.3] - {PR_MERGE_DATE}
 
 ### Changed
 - Refresh README to focus on a concise Raycast user overview with key in-app features

extensions/numpy-documentation-search/README.md

@@ -8,3 +8,17 @@ A Raycast extension that lets you search the NumPy API reference and preview det
 - **Rich previews**: See inline call signatures, parameter tables, return values, and version notes without leaving Raycast.
 - **Doc deep links**: Open the exact section on numpy.org in your browser when you need the full documentation context.
 - **Copy-ready snippets**: Copy function signatures or doc URLs directly from the command for fast handoff into notebooks, scripts, or PRs.
+
+## Certificate-Restricted Networks
+
+If your work network blocks access to `https://numpy.org/doc/stable/`, the extension now shows a guided recovery state instead of only surfacing the fetch error.
+
+You can point the command at downloaded local documentation:
+
+1. Obtain a generated NumPy docs copy from [numpy/doc](https://github.com/numpy/doc) or from another machine that can reach `numpy.org`.
+2. Extract the download locally and select the downloaded docs folder in Raycast. The extension will load the documentation from its `stable` subfolder.
+3. Open the command preferences and set:
+   - `Documentation Source` to `Local Docs Directory`, or leave it on `Online`
+   - `Local Docs Directory` to the downloaded docs folder
+
+If no local docs are configured, the extension requires live access to `numpy.org`. Local HTML docs provide full inline previews without network access.

extensions/numpy-documentation-search/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.raycast.com/schemas/extension.json",
   "name": "numpy-documentation-search",
-  "title": "NumPy Documentation Search",
+  "title": "Numpy Documentation Search",
   "description": "Quickly search through official NumPy documentation",
   "icon": "extension-icon.png",
   "author": "FariaF22",
@@ -18,13 +18,38 @@
   "commands": [
     {
       "name": "numpy-docs",
-      "title": "NumPy Docs",
+      "title": "Numpy Docs",
       "subtitle": "Search through Numpy documentation",
       "description": "Search NumPy's API reference and preview documentation inside Raycast.",
       "mode": "view"
     }
   ],
   "preferences": [
+    {
+      "name": "documentationSourceMode",
+      "type": "dropdown",
+      "required": true,
+      "title": "Documentation Source",
+      "description": "Choose where the extension should load NumPy documentation from",
+      "default": "online",
+      "data": [
+        {
+          "title": "Online",
+          "value": "online"
+        },
+        {
+          "title": "Local Docs Directory",
+          "value": "local"
+        }
+      ]
+    },
+    {
+      "name": "localDocsDirectory",
+      "type": "directory",
+      "required": false,
+      "title": "Local Docs Directory",
+      "description": "Only used when Documentation Source is Local Docs Directory. Select the downloaded NumPy docs folder and the extension will load files from its stable subfolder"
+    },
     {
       "name": "useShortPrefix",
       "type": "checkbox",

extensions/numpy-documentation-search/src/__tests__/docs-source.test.ts

@@ -0,0 +1,110 @@
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { deflateSync } from "node:zlib";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { loadDocDetail, loadInventory } from "../lib/docs-source";
+import type { InventoryItem } from "../lib/inventory";
+
+const linspaceItem: InventoryItem = {
+  id: "numpy.linspace",
+  name: "numpy.linspace",
+  shortName: "linspace",
+  role: "py:function",
+  url: "https://numpy.org/doc/stable/reference/generated/numpy.linspace.html",
+  docPath: "reference/generated/numpy.linspace.html#numpy.linspace",
+  displayName: "numpy.linspace",
+};
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tempDirs) {
+    rmSync(dir, { force: true, recursive: true });
+  }
+  tempDirs.length = 0;
+});
+
+describe("loadInventory", () => {
+  it("falls back to local docs in online mode when remote loading fails", async () => {
+    const localDocsDirectory = createLocalDocsDirectory();
+    const stableDir = path.join(localDocsDirectory, "stable");
+    mkdirSync(stableDir, { recursive: true });
+    writeFileSync(path.join(stableDir, "objects.inv"), buildInventoryFixture());
+
+    const result = await loadInventory(
+      {
+        localDocsDirectory,
+        mode: "online",
+      },
+      {
+        fetchImpl: vi.fn(async () => {
+          throw new Error("certificate failure");
+        }) as typeof fetch,
+        readBinaryFileImpl: async (filePath) => readFileSync(filePath),
+        readTextFileImpl: async (filePath) => readFileSync(filePath, "utf8"),
+      },
+    );
+
+    expect(result.source).toBe("local");
+    expect(result.remoteError?.message).toBe("certificate failure");
+    expect(result.data.some((item) => item.id === "numpy.linspace")).toBe(true);
+  });
+
+  it("surfaces the remote error when online mode has no local docs fallback", async () => {
+    await expect(
+      loadInventory(
+        {
+          mode: "online",
+        },
+        {
+          fetchImpl: vi.fn(async () => {
+            throw new Error("certificate failure");
+          }) as typeof fetch,
+          readBinaryFileImpl: async (filePath) => readFileSync(filePath),
+          readTextFileImpl: async (filePath) => readFileSync(filePath, "utf8"),
+        },
+      ),
+    ).rejects.toThrow("certificate failure");
+  });
+});
+
+describe("loadDocDetail", () => {
+  it("loads documentation detail from a local docs directory", async () => {
+    const localDocsDirectory = createLocalDocsDirectory();
+    const referenceDir = path.join(localDocsDirectory, "stable/reference/generated");
+    mkdirSync(referenceDir, { recursive: true });
+    writeFileSync(
+      path.join(referenceDir, "numpy.linspace.html"),
+      readFileSync(path.join(process.cwd(), "src/__tests__/fixtures/numpy.linspace.html"), "utf8"),
+    );
+
+    const result = await loadDocDetail({
+      inventorySource: "local",
+      item: linspaceItem,
+      localDocsDirectory,
+      mode: "local",
+    });
+
+    expect(result.source).toBe("local");
+    expect(result.data?.signature).toContain("numpy.linspace");
+  });
+});
+
+function createLocalDocsDirectory(): string {
+  const dir = mkdtempSync(path.join(tmpdir(), "numpy-docs-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function buildInventoryFixture(): Buffer {
+  const header = [
+    "# Sphinx inventory version 2",
+    "# Project: NumPy",
+    "# Version: stable",
+    "# The remainder of this file is compressed using zlib.",
+  ].join("\n");
+  const body = "numpy.linspace py:function 1 reference/generated/numpy.linspace.html#numpy.linspace -";
+
+  return Buffer.concat([Buffer.from(`${header}\n`, "utf8"), deflateSync(`${body}\n`)]);
+}

extensions/numpy-documentation-search/src/hooks/useDocDetail.ts

@@ -1,27 +1,94 @@
-import { useFetch } from "@raycast/utils";
+import { useCallback, useEffect, useState } from "react";
+import { loadDocDetail, type DocumentationSourceMode, type ResolvedDocumentationSource } from "../lib/docs-source";
+import type { DocDetail } from "../lib/doc-detail";
 import type { InventoryItem } from "../lib/inventory";
-import { parseDocDetail, type DocDetail } from "../lib/doc-detail";
 
 interface UseDocDetailResult {
   data?: DocDetail;
   isLoading: boolean;
   error?: Error;
   revalidate: () => void;
+  source?: ResolvedDocumentationSource;
 }
 
-export function useDocDetail(item: InventoryItem | undefined): UseDocDetailResult {
-  const { data, isLoading, error, revalidate } = useFetch<DocDetail>(item?.url ?? "", {
-    execute: Boolean(item),
-    keepPreviousData: true,
-    parseResponse: async (response) => {
-      if (!response.ok) {
-        throw new Error(`Failed to load documentation: ${response.status} ${response.statusText}`);
-      }
-
-      const html = await response.text();
-      return parseDocDetail(html, item!);
-    },
+interface UseDocDetailOptions {
+  inventorySource?: ResolvedDocumentationSource;
+  item: InventoryItem | undefined;
+  localDocsDirectory?: string;
+  mode: DocumentationSourceMode;
+}
+
+export function useDocDetail(options: UseDocDetailOptions): UseDocDetailResult {
+  const [reloadToken, setReloadToken] = useState(0);
+
+  const revalidate = useCallback(() => {
+    setReloadToken((token) => token + 1);
+  }, []);
+
+  const [state, setState] = useState<UseDocDetailResult>({
+    isLoading: false,
+    revalidate,
   });
 
-  return { data, isLoading, error, revalidate };
+  useEffect(() => {
+    let cancelled = false;
+
+    if (!options.item || !options.inventorySource) {
+      setState({
+        data: undefined,
+        error: undefined,
+        isLoading: false,
+        revalidate,
+        source: undefined,
+      });
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    setState((current) => ({
+      ...current,
+      error: undefined,
+      isLoading: true,
+      revalidate,
+    }));
+
+    void loadDocDetail({
+      inventorySource: options.inventorySource,
+      item: options.item,
+      localDocsDirectory: options.localDocsDirectory,
+      mode: options.mode,
+    })
+      .then((result) => {
+        if (cancelled) {
+          return;
+        }
+
+        setState({
+          data: result.data,
+          error: undefined,
+          isLoading: false,
+          revalidate,
+          source: result.source,
+        });
+      })
+      .catch((error: unknown) => {
+        if (cancelled) {
+          return;
+        }
+
+        setState((current) => ({
+          ...current,
+          error: error instanceof Error ? error : new Error(String(error)),
+          isLoading: false,
+          revalidate,
+        }));
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [options.inventorySource, options.item, options.localDocsDirectory, options.mode, reloadToken, revalidate]);
+
+  return state;
 }