@tablestore/tablestore-agent-cli 0.2.11 → 0.4.0

package/dist/dashboard-runtime/dashboard/src/hooks/use-subspace-history.ts

@@ -1,75 +1,51 @@
 "use client";
 
 import { useCallback, useEffect, useState } from "react";
+import {
+  clearRecentSubspaces,
+  readRecentSubspaces,
+  rememberRecentSubspace,
+} from "@/lib/subspace-history";
 
-const MAX_HISTORY = 10;
-const HISTORY_KEY_PREFIX = "kb-subspace-history:";
-const ACTIVE_KEY_PREFIX = "kb-subspace-active:";
+type RecentSubspaceStorage = Pick<
+  Storage,
+  "getItem" | "setItem" | "removeItem"
+>;
 
-function getStorageKey(knowledgeBaseName: string): string {
-  return `${HISTORY_KEY_PREFIX}${knowledgeBaseName}`;
-}
+const unavailableLocalStorage: RecentSubspaceStorage = {
+  getItem: () => null,
+  setItem: () => {},
+  removeItem: () => {},
+};
 
-/**
- * Per-tab active subspace. Backed by sessionStorage so that two tabs viewing
- * the same KB can hold independent scopes without overwriting each other.
- */
-export function getActiveSubspace(knowledgeBaseName: string): string | null {
-  if (typeof window === "undefined") return null;
+export function getLocalStorage(): RecentSubspaceStorage {
   try {
-    return window.sessionStorage.getItem(ACTIVE_KEY_PREFIX + knowledgeBaseName);
+    return window.localStorage;
   } catch {
-    return null;
+    return unavailableLocalStorage;
   }
 }
 
-export function setActiveSubspace(
-  knowledgeBaseName: string,
-  subspace: string,
-): void {
-  if (typeof window === "undefined") return;
-  try {
-    window.sessionStorage.setItem(
-      ACTIVE_KEY_PREFIX + knowledgeBaseName,
-      subspace,
-    );
-  } catch {
-    // Quota exceeded / privacy mode — keep the in-memory state usable.
-  }
+export interface ScopedSubspaceHistory {
+  scopeId: string;
+  history: string[];
 }
 
-export function clearActiveSubspace(knowledgeBaseName: string): void {
-  if (typeof window === "undefined") return;
-  try {
-    window.sessionStorage.removeItem(ACTIVE_KEY_PREFIX + knowledgeBaseName);
-  } catch {
-    // Ignore.
-  }
-}
-
-function readHistory(knowledgeBaseName: string): string[] {
-  if (typeof window === "undefined") return [];
-  try {
-    const raw = window.localStorage.getItem(getStorageKey(knowledgeBaseName));
-    if (!raw) return [];
-    const parsed: unknown = JSON.parse(raw);
-    if (!Array.isArray(parsed)) return [];
-    return parsed.filter((item): item is string => typeof item === "string");
-  } catch {
-    return [];
-  }
+export function getSubspaceScopeId(
+  dataScopeKey: string,
+  knowledgeBaseName: string,
+): string {
+  return JSON.stringify([dataScopeKey, knowledgeBaseName]);
 }
 
-function writeHistory(knowledgeBaseName: string, history: string[]): void {
-  if (typeof window === "undefined") return;
-  try {
-    window.localStorage.setItem(
-      getStorageKey(knowledgeBaseName),
-      JSON.stringify(history),
-    );
-  } catch {
-    // Ignore quota / privacy mode errors silently.
-  }
+export function selectSubspaceHistory(
+  state: ScopedSubspaceHistory,
+  dataScopeKey: string,
+  knowledgeBaseName: string,
+): string[] {
+  return state.scopeId === getSubspaceScopeId(dataScopeKey, knowledgeBaseName)
+    ? state.history
+    : [];
 }
 
 /**
@@ -78,34 +54,47 @@ function writeHistory(knowledgeBaseName: string, history: string[]): void {
  * History is hydrated after mount to keep the SSR-rendered tree in sync
  * with the initial client tree.
  */
-export function useSubspaceHistory(knowledgeBaseName: string) {
-  const [history, setHistory] = useState<string[]>([]);
+export function useSubspaceHistory(
+  dataScopeKey: string,
+  knowledgeBaseName: string,
+) {
+  const scopeId = getSubspaceScopeId(dataScopeKey, knowledgeBaseName);
+  const [state, setState] = useState<ScopedSubspaceHistory>({
+    scopeId,
+    history: [],
+  });
+  const history = selectSubspaceHistory(state, dataScopeKey, knowledgeBaseName);
 
   useEffect(() => {
-    setHistory(readHistory(knowledgeBaseName));
-  }, [knowledgeBaseName]);
+    setState({
+      scopeId,
+      history: readRecentSubspaces(
+        getLocalStorage(),
+        dataScopeKey,
+        knowledgeBaseName,
+      ),
+    });
+  }, [scopeId, dataScopeKey, knowledgeBaseName]);
 
   const addToHistory = useCallback(
     (subspace: string) => {
-      if (!subspace) return;
-      setHistory((prev) => {
-        const next = [subspace, ...prev.filter((s) => s !== subspace)].slice(
-          0,
-          MAX_HISTORY,
-        );
-        writeHistory(knowledgeBaseName, next);
-        return next;
+      setState({
+        scopeId,
+        history: rememberRecentSubspace(
+          getLocalStorage(),
+          dataScopeKey,
+          knowledgeBaseName,
+          subspace,
+        ),
       });
     },
-    [knowledgeBaseName],
+    [scopeId, dataScopeKey, knowledgeBaseName],
   );
 
   const clearHistory = useCallback(() => {
-    if (typeof window !== "undefined") {
-      window.localStorage.removeItem(getStorageKey(knowledgeBaseName));
-    }
-    setHistory([]);
-  }, [knowledgeBaseName]);
+    clearRecentSubspaces(getLocalStorage(), dataScopeKey, knowledgeBaseName);
+    setState({ scopeId, history: [] });
+  }, [scopeId, dataScopeKey, knowledgeBaseName]);
 
   return { history, addToHistory, clearHistory };
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-wiki-build-polling.ts

@@ -0,0 +1,151 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+import type { WikiBuildStatus } from "@/types/wiki";
+
+const TERMINAL_BUILD_STATUSES = new Set<WikiBuildStatus>([
+  "ready",
+  "failed",
+  "conflict",
+]);
+
+export function wikiPollDelay(attempt: number): number {
+  return Math.min(2_000 * 2 ** Math.max(0, attempt), 10_000);
+}
+
+interface WikiBuildPollingOptions {
+  getVisibility: () => "hidden" | "visible";
+  subscribeVisibility: (listener: () => void) => () => void;
+  refetch: () => Promise<unknown>;
+}
+
+export interface WikiBuildPollingController {
+  update: (status: WikiBuildStatus | undefined, enabled: boolean) => void;
+  cleanup: () => void;
+}
+
+export function createWikiBuildPollingController({
+  getVisibility,
+  subscribeVisibility,
+  refetch,
+}: WikiBuildPollingOptions): WikiBuildPollingController {
+  let attempt = 0;
+  let status: WikiBuildStatus | undefined;
+  let enabled = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let epoch = 0;
+  let inFlightEpoch: number | undefined;
+  let disposed = false;
+
+  const isRunning = () =>
+    Boolean(enabled && status && !TERMINAL_BUILD_STATUSES.has(status));
+
+  const clearTimer = () => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+  };
+
+  const schedule = () => {
+    if (
+      disposed ||
+      timer !== undefined ||
+      inFlightEpoch === epoch ||
+      getVisibility() === "hidden" ||
+      !isRunning()
+    ) {
+      return;
+    }
+    const scheduledEpoch = epoch;
+    timer = setTimeout(() => {
+      timer = undefined;
+      if (scheduledEpoch !== epoch) return;
+      void performRefetch();
+    }, wikiPollDelay(attempt));
+  };
+
+  const performRefetch = async () => {
+    if (disposed || getVisibility() === "hidden" || !isRunning()) return;
+    const requestEpoch = epoch;
+    if (inFlightEpoch === requestEpoch) return;
+    inFlightEpoch = requestEpoch;
+    attempt += 1;
+    try {
+      await refetch();
+    } catch {
+      // A transient request failure must not stop observation of a live build.
+    } finally {
+      if (inFlightEpoch === requestEpoch) inFlightEpoch = undefined;
+      if (requestEpoch === epoch) schedule();
+    }
+  };
+
+  const unsubscribe = subscribeVisibility(() => {
+    clearTimer();
+    if (getVisibility() === "visible" && isRunning()) {
+      void performRefetch();
+    }
+  });
+
+  return {
+    update(nextStatus, nextEnabled) {
+      if (disposed) return;
+      const wasRunning = isRunning();
+      status = nextStatus;
+      enabled = nextEnabled;
+      const startsRunningCycle = !wasRunning && isRunning();
+      if (startsRunningCycle) {
+        epoch += 1;
+        attempt = 0;
+        clearTimer();
+      }
+      if (!isRunning() || getVisibility() === "hidden") {
+        clearTimer();
+        return;
+      }
+      schedule();
+    },
+    cleanup() {
+      disposed = true;
+      epoch += 1;
+      clearTimer();
+      unsubscribe();
+    },
+  };
+}
+
+export function useWikiBuildPolling(
+  status: WikiBuildStatus | undefined,
+  refetch: () => Promise<unknown>,
+  enabled = true,
+): void {
+  const refetchRef = useRef(refetch);
+  const controllerRef = useRef<WikiBuildPollingController | null>(null);
+  refetchRef.current = refetch;
+
+  useEffect(() => {
+    const controller = createWikiBuildPollingController({
+      getVisibility: () =>
+        typeof document === "undefined" ? "visible" : document.visibilityState,
+      subscribeVisibility: (listener) => {
+        if (typeof document === "undefined") return () => {};
+        document.addEventListener("visibilitychange", listener);
+        return () => document.removeEventListener("visibilitychange", listener);
+      },
+      refetch: () => refetchRef.current(),
+    });
+    controllerRef.current = controller;
+    controller.update(status, enabled);
+    return () => {
+      controller.cleanup();
+      controllerRef.current = null;
+    };
+    // The controller owns changing build state through update(), and the latest
+    // refetch callback is read from refetchRef to avoid timer churn.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    controllerRef.current?.update(status, enabled);
+  }, [enabled, status]);
+}

package/dist/dashboard-runtime/dashboard/src/hooks/use-wikis.ts

@@ -0,0 +1,291 @@
+import {
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from "@tanstack/react-query";
+
+import { wikiQueryKeys } from "@/lib/query-keys";
+import { useDataScopeKey } from "@/providers/runtime-context-provider";
+import { ApiClientError } from "@/services/api-client";
+import {
+  addWikiSources,
+  deleteWikiSource,
+  getWiki,
+  getWikiPage,
+  getWikiSource,
+  ingestWiki,
+  listWikiArtifacts,
+  listWikiPages,
+  listWikiSources,
+  searchWikiPages,
+  updateWiki,
+  updateWikiSource,
+} from "@/services/wiki";
+import type {
+  AddWikiSourcesRequest,
+  DeleteWikiSourceRequest,
+  GetWikiPageRequest,
+  IngestWikiRequest,
+  ListWikiArtifactsRequest,
+  ListWikiArtifactsResponse,
+  ListWikiPagesRequest,
+  ListWikiPagesResponse,
+  ListWikiSourcesRequest,
+  ListWikiSourcesResponse,
+  SearchWikiPagesRequest,
+  UpdateWikiRequest,
+  UpdateWikiSourceRequest,
+  Wiki,
+  WikiPage,
+  WikiRawSource,
+  WikiScope,
+} from "@/types/wiki";
+
+export { wikiQueryKeys };
+
+function hasValue(value: string | undefined): value is string {
+  return Boolean(value?.trim());
+}
+
+function isExactScope(scope: WikiScope | undefined): scope is WikiScope {
+  if (!scope) return false;
+  return [scope.appId, scope.tenantId, scope.agentId].every(
+    (segment) => hasValue(segment) && segment.trim() !== "*",
+  );
+}
+
+function isWikiQueryEnabled(
+  memoryStoreName: string | undefined,
+  scope: WikiScope | undefined,
+): boolean {
+  return hasValue(memoryStoreName) && isExactScope(scope);
+}
+
+export function useWiki(
+  memoryStoreName: string | undefined,
+  scope: WikiScope | undefined,
+) {
+  const dataScopeKey = useDataScopeKey();
+  return useQuery<Wiki, ApiClientError>({
+    queryKey: wikiQueryKeys.detail(dataScopeKey, memoryStoreName ?? "", scope!),
+    queryFn: () => getWiki(memoryStoreName!, scope!),
+    enabled: isWikiQueryEnabled(memoryStoreName, scope),
+  });
+}
+
+export function useWikiSources(
+  memoryStoreName: string | undefined,
+  scope: WikiScope | undefined,
+  options: Pick<ListWikiSourcesRequest, "limit"> & { enabled?: boolean } = {},
+) {
+  const dataScopeKey = useDataScopeKey();
+  return useInfiniteQuery<ListWikiSourcesResponse, ApiClientError>({
+    queryKey: wikiQueryKeys.sources(
+      dataScopeKey,
+      memoryStoreName ?? "",
+      scope!,
+      options.limit,
+    ),
+    queryFn: ({ pageParam }) =>
+      listWikiSources(memoryStoreName!, {
+        scope: scope!,
+        ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        ...(typeof pageParam === "string" ? { nextToken: pageParam } : {}),
+      }),
+    getNextPageParam: (last) => last.nextToken ?? undefined,
+    initialPageParam: undefined as string | undefined,
+    enabled:
+      options.enabled !== false && isWikiQueryEnabled(memoryStoreName, scope),
+  });
+}
+
+export function useWikiArtifacts(
+  memoryStoreName: string | undefined,
+  scope: WikiScope | undefined,
+  options: Pick<ListWikiArtifactsRequest, "kind" | "limit"> & {
+    enabled?: boolean;
+  },
+) {
+  const dataScopeKey = useDataScopeKey();
+  return useInfiniteQuery<ListWikiArtifactsResponse, ApiClientError>({
+    queryKey: wikiQueryKeys.artifacts(
+      dataScopeKey,
+      memoryStoreName ?? "",
+      scope!,
+      options.kind,
+      options.limit,
+    ),
+    queryFn: ({ pageParam }) =>
+      listWikiArtifacts(memoryStoreName!, {
+        scope: scope!,
+        kind: options.kind,
+        ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        ...(typeof pageParam === "string" ? { nextToken: pageParam } : {}),
+      }),
+    getNextPageParam: (last) => last.nextToken ?? undefined,
+    initialPageParam: undefined as string | undefined,
+    enabled:
+      options.enabled !== false && isWikiQueryEnabled(memoryStoreName, scope),
+  });
+}
+
+export function useWikiSource(
+  memoryStoreName: string | undefined,
+  scope: WikiScope | undefined,
+  path: string | undefined,
+) {
+  const dataScopeKey = useDataScopeKey();
+  return useQuery<WikiRawSource, ApiClientError>({
+    queryKey: wikiQueryKeys.source(
+      dataScopeKey,
+      memoryStoreName ?? "",
+      scope!,
+      path ?? "",
+    ),
+    queryFn: () =>
+      getWikiSource(memoryStoreName!, { scope: scope!, path: path! }),
+    enabled: isWikiQueryEnabled(memoryStoreName, scope) && hasValue(path),
+  });
+}
+
+export function useWikiPages(
+  memoryStoreName: string | undefined,
+  scope: WikiScope | undefined,
+  options: Pick<ListWikiPagesRequest, "limit"> & {
+    enabled?: boolean;
+  } = {},
+) {
+  const dataScopeKey = useDataScopeKey();
+  const queryClient = useQueryClient();
+  const queryKey = wikiQueryKeys.pages(
+    dataScopeKey,
+    memoryStoreName ?? "",
+    scope!,
+    options.limit,
+  );
+  const query = useInfiniteQuery<ListWikiPagesResponse, ApiClientError>({
+    queryKey,
+    queryFn: ({ pageParam }) =>
+      listWikiPages(memoryStoreName!, {
+        scope: scope!,
+        ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        ...(typeof pageParam === "string" ? { nextToken: pageParam } : {}),
+      }),
+    getNextPageParam: (last) => last.nextToken ?? undefined,
+    initialPageParam: undefined as string | undefined,
+    retry: false,
+    enabled:
+      options.enabled !== false && isWikiQueryEnabled(memoryStoreName, scope),
+  });
+  return {
+    ...query,
+    resetWikiPages: () => queryClient.resetQueries({ queryKey, exact: true }),
+  };
+}
+
+export function useWikiPage(
+  memoryStoreName: string | undefined,
+  scope: WikiScope | undefined,
+  request: Pick<GetWikiPageRequest, "path"> | undefined,
+) {
+  const dataScopeKey = useDataScopeKey();
+  return useQuery<WikiPage, ApiClientError>({
+    queryKey: wikiQueryKeys.page(
+      dataScopeKey,
+      memoryStoreName ?? "",
+      scope!,
+      request?.path ?? "",
+    ),
+    queryFn: () =>
+      getWikiPage(memoryStoreName!, {
+        scope: scope!,
+        path: request!.path,
+      }),
+    enabled:
+      isWikiQueryEnabled(memoryStoreName, scope) && hasValue(request?.path),
+  });
+}
+
+export function useSearchWikiPages(
+  memoryStoreName: string | undefined,
+  scope: WikiScope | undefined,
+  request: Pick<SearchWikiPagesRequest, "query" | "limit"> & {
+    enabled?: boolean;
+  },
+) {
+  const dataScopeKey = useDataScopeKey();
+  return useQuery<{ pages: WikiPage[] }, ApiClientError>({
+    queryKey: wikiQueryKeys.search(
+      dataScopeKey,
+      memoryStoreName ?? "",
+      scope!,
+      request.query,
+      request.limit,
+    ),
+    queryFn: () =>
+      searchWikiPages(memoryStoreName!, {
+        scope: scope!,
+        query: request.query,
+        ...(request.limit !== undefined ? { limit: request.limit } : {}),
+      }),
+    enabled:
+      request.enabled !== false &&
+      isWikiQueryEnabled(memoryStoreName, scope) &&
+      request.query.trim().length > 0,
+  });
+}
+
+type MutationVariables<TRequest> = TRequest & {
+  memoryStoreName: string;
+};
+
+function useWikiMutation<TRequest extends { scope: WikiScope }, TResult>(
+  mutate: (memoryStoreName: string, request: TRequest) => Promise<TResult>,
+) {
+  const dataScopeKey = useDataScopeKey();
+  const queryClient = useQueryClient();
+  return useMutation<TResult, ApiClientError, MutationVariables<TRequest>>({
+    mutationFn: ({
+      memoryStoreName,
+      ...request
+    }: MutationVariables<TRequest>) =>
+      mutate(memoryStoreName, request as unknown as TRequest),
+    onSuccess: (_data, variables) =>
+      queryClient.invalidateQueries({
+        queryKey: wikiQueryKeys.root(
+          dataScopeKey,
+          variables.memoryStoreName,
+          variables.scope,
+        ),
+      }),
+  });
+}
+
+export function useUpdateWiki() {
+  return useWikiMutation(updateWiki);
+}
+
+export function useIngestWiki() {
+  return useWikiMutation(ingestWiki);
+}
+
+export function useAddWikiSources() {
+  return useWikiMutation(addWikiSources);
+}
+
+export function useUpdateWikiSource() {
+  return useWikiMutation(updateWikiSource);
+}
+
+export function useRemoveWikiSource() {
+  return useWikiMutation(deleteWikiSource);
+}
+
+export type UpdateWikiVariables = MutationVariables<UpdateWikiRequest>;
+export type IngestWikiVariables = MutationVariables<IngestWikiRequest>;
+export type AddWikiSourcesVariables = MutationVariables<AddWikiSourcesRequest>;
+export type UpdateWikiSourceVariables =
+  MutationVariables<UpdateWikiSourceRequest>;
+export type DeleteWikiSourceVariables =
+  MutationVariables<DeleteWikiSourceRequest>;