@notis_ai/cli 0.2.0-beta.19.1 → 0.2.0-beta.196.1

package/dist/sdk/src/hooks/useViewerReads.ts

@@ -0,0 +1,129 @@
+'use client';
+
+import { useNotisRuntime } from '../provider';
+import { useQuery, type UseQueryResult } from './useQuery';
+import {
+  SPACE_VIEWER_READ_OPERATIONS,
+  type SpaceViewerDatabase,
+  type SpaceViewerReadFamily,
+  type SpaceViewerReadInput,
+  type SpaceViewerReadOperation,
+  type SpaceViewerReadResult,
+  type SpaceViewerSkill,
+} from '../space';
+
+export interface UseViewerReadOptions {
+  enabled?: boolean;
+  staleTimeMs?: number;
+}
+
+// Bounded crawl of the viewer's Skill inventory: 50 pages of 100.
+const MAX_SKILL_PAGES = 50;
+
+/**
+ * True when this page may read what the signed-in viewer can open: the Space declares
+ * `viewerReads` for this family and the host offers it (never on a Site or anonymous link).
+ * Render a fallback when false.
+ */
+export function useViewerReadAvailable(family: SpaceViewerReadFamily): boolean {
+  const runtime = useNotisRuntime();
+  return runtime?.resource?.kind === 'space' && typeof runtime.viewerRead === 'function'
+    && Boolean(runtime.space?.viewerReads?.includes(family));
+}
+
+/** One cached, read-only viewer read. Results are scoped to the current viewer by the host cache scope. */
+export function useViewerRead<TOperation extends SpaceViewerReadOperation>(operation: TOperation,
+  input: SpaceViewerReadInput[TOperation], options: UseViewerReadOptions = {}): UseQueryResult<SpaceViewerReadResult[TOperation]> {
+  const runtime = useNotisRuntime();
+  const available = useViewerReadAvailable(SPACE_VIEWER_READ_OPERATIONS[operation]);
+  return useQuery(['viewer-read', operation, input], async () => {
+    if (!runtime?.viewerRead) throw new Error('Viewer reads are unavailable here.');
+    return runtime.viewerRead<SpaceViewerReadResult[TOperation]>(operation, input as Record<string, unknown>);
+  }, { readOnly: true, enabled: available && options.enabled !== false, staleTimeMs: options.staleTimeMs });
+}
+
+/** Every database the signed-in viewer can open, with its available links and read target. */
+export function useViewerDatabases(options: UseViewerReadOptions = {}): UseQueryResult<SpaceViewerDatabase[]> {
+  const runtime = useNotisRuntime();
+  const available = useViewerReadAvailable('databases');
+  return useQuery(['viewer-databases'], async () => {
+    if (!runtime?.viewerRead) throw new Error('Viewer reads are unavailable here.');
+    const result = await runtime.viewerRead<SpaceViewerReadResult['list_databases']>('list_databases', {});
+    if (!Array.isArray(result?.databases)) throw new Error('The database list is incomplete.');
+    return result.databases;
+  }, { readOnly: true, enabled: available && options.enabled !== false, staleTimeMs: options.staleTimeMs });
+}
+
+type ListSkillsRead = (input: SpaceViewerReadInput['list_skills']) => Promise<SpaceViewerReadResult['list_skills']>;
+
+// Content pages read at once. Each one holds an API worker while its snapshots are read, and the API
+// has only a few, so a large inventory never takes them all: two pages, plus one quick cursor read.
+export const SKILL_CONTENT_PAGES_AT_ONCE = 2;
+
+/**
+ * Every Skill page, in order. Pages with instructions are slow (each reads its snapshots), so the next
+ * page's cursor comes from a quick read without them and that page starts while the previous one is
+ * still read, at most SKILL_CONTENT_PAGES_AT_ONCE content pages at a time. A cursor that no longer
+ * matches (the list changed meanwhile) drops the pages started from it, waits for them to end and
+ * continues from the real cursor.
+ */
+export async function readAllViewerSkills(read: ListSkillsRead,
+  { includeContent, includeDisabled }: { includeContent: boolean; includeDisabled: boolean }): Promise<SpaceViewerSkill[]> {
+  const page = (after: string | null, content: boolean) => read({ limit: 100, include_content: content,
+    include_disabled: includeDisabled, ...(after ? { after } : {}) }).then(result => {
+    if (!Array.isArray(result?.skills)) throw new Error('The Skill list is incomplete.');
+    return result;
+  });
+  const skills: SpaceViewerSkill[] = [];
+  // The pages started and not read yet, in order, each with the cursor it started from.
+  const started: { after: string | null; result: Promise<SpaceViewerReadResult['list_skills']> }[] = [];
+  // Where the next page to start begins, and whether a quick read (or the last page read) says it exists.
+  let cursor: string | null = null;
+  let known = true;
+  let pages = 0;
+  for (;;) {
+    if (known && started.length < (includeContent ? SKILL_CONTENT_PAGES_AT_ONCE : 1) && pages + started.length < MAX_SKILL_PAGES) {
+      const current = { after: cursor, result: page(cursor, includeContent) };
+      void current.result.catch(() => {});
+      started.push(current);
+      known = false;
+      if (includeContent) {
+        const probe = await page(cursor, false);
+        known = Boolean(probe.has_more && probe.next);
+        cursor = probe.next ?? null;
+      }
+      continue;
+    }
+    const head = started.shift();
+    if (!head) break;
+    const result = await head.result;
+    skills.push(...result.skills);
+    pages += 1;
+    if (!result.has_more || !result.next) return skills;
+    // A page started ahead is kept only when it continues exactly where this one ended; otherwise (and
+    // when none was started) the next page starts from this page's own cursor.
+    if (started[0]?.after !== result.next) {
+      const dropped = started.splice(0);
+      await Promise.allSettled(dropped.map(entry => entry.result));
+      cursor = result.next;
+      known = true;
+    }
+  }
+  throw new Error('This account has more Skills than a page can read at once.');
+}
+
+/**
+ * Every Skill the signed-in viewer can see, all pages. With `includeContent`, `skill_md`
+ * is present where the viewer holds content access and null elsewhere (curated, legacy).
+ */
+export function useViewerSkills(options: UseViewerReadOptions & { includeContent?: boolean; includeDisabled?: boolean } = {}):
+  UseQueryResult<SpaceViewerSkill[]> {
+  const runtime = useNotisRuntime();
+  const available = useViewerReadAvailable('skills');
+  const includeContent = options.includeContent === true, includeDisabled = options.includeDisabled === true;
+  return useQuery(['viewer-skills', includeContent, includeDisabled], async () => {
+    if (!runtime?.viewerRead) throw new Error('Viewer reads are unavailable here.');
+    return readAllViewerSkills((input: SpaceViewerReadInput['list_skills']) => runtime.viewerRead!('list_skills', input),
+      { includeContent, includeDisabled });
+  }, { readOnly: true, enabled: available && options.enabled !== false, staleTimeMs: options.staleTimeMs });
+}

package/dist/sdk/src/index.ts

@@ -0,0 +1,200 @@
+/**
+ * @notis/sdk - The Notis App SDK
+ *
+ * Public API for building Notis apps. Import hooks and the provider from
+ * this entrypoint. For configuration, use `@notis/sdk/config`. For the
+ * Vite config builder, use `@notis/sdk/vite`.
+ */
+
+// Provider
+export { NotisProvider, useNotisRuntime } from './provider';
+
+// Hooks
+export { useAction, useActionQuery } from './hooks/useAction';
+export { useNativeDocuments, useNativeMutation } from './hooks/useNativeDocuments';
+export type { NativeField, NativeFilter, NativeQuery, NativeInsert, NativeUpdate, NativeDelete, NativeMutationReceipt } from './nativeData';
+export type { SpaceDatabaseCreate, SpaceResourceReference } from './space';
+export type { SpaceActionTemplate, SpaceActionDescriptor, SpaceRuntimeDescriptor, SpaceActionOptions } from './space';
+export type { SpaceDocumentBodyRequest, SpaceDocumentBodyRead, SpaceDocumentBodySave, SpaceDocumentBodyResult } from './space';
+export { useNativeDocumentBody } from './hooks/useNativeDocumentBody';
+export { useViewerRead, useViewerReadAvailable, useViewerDatabases, useViewerSkills } from './hooks/useViewerReads';
+export type { UseViewerReadOptions } from './hooks/useViewerReads';
+export { useViewParams, useShown, useShownAvailable, parseViewParams } from './hooks/useViewParams';
+export type { ViewParams, ViewParamsOf, UseShownOptions } from './hooks/useViewParams';
+export { SPACE_VIEW_SPEC_VERSION } from './space';
+export type { SpaceViewParam, SpaceViewParamType, SpaceShows, SpaceShownDescriptor, SpaceShownOptions, SpaceShownResult,
+  SpaceMemoryPolicy, SpaceMemorySnapshot, SpaceChrome, SpaceMarkdownInput } from './space';
+export { SPACE_VIEWER_READ_OPERATIONS } from './space';
+export { SPACE_CLOUD_COMPUTER_OPERATIONS, spaceCloudComputerAllows } from './space';
+export type { SpaceCloudComputerLevel, SpaceCloudComputerOperation, SpaceCloudComputerStatus, SpaceCloudComputerRelease, SpaceCloudComputerRunInput,
+  SpaceCloudComputerRunResult, SpaceCloudComputerUploadInput, SpaceCloudComputerUploadResult, SpaceCloudComputerTransport } from './space';
+export type { SpaceViewerReadFamily, SpaceViewerReadOperation, SpaceViewerReadInput, SpaceViewerReadResult, SpaceViewerLink,
+  SpaceViewerDatabase, SpaceViewerDatabaseSchema, SpaceViewerSkill, SpaceViewerSkillPage } from './space';
+export { SpaceActionError, SpaceNavigationCancelled, isSpaceNavigationCancelled } from './space';
+export type { SpaceActionFailureDetails } from './space';
+export { useQuery, useQueryClient } from './hooks/useQuery';
+export type { UseQueryOptions, UseQueryResult } from './hooks/useQuery';
+export { createQueryClient, createPrefetchQueue, queryKey } from './queryCache';
+export type { NotisQueryClient, QuerySnapshot, QueryFetchOptions } from './queryCache';
+export { useNotis } from './hooks/useNotis';
+export { useDocuments } from './hooks/useDocuments';
+export type { UseDocumentsOptions, UseDocumentsResult } from './hooks/useDocuments';
+export { useDatabaseSubscription } from './hooks/useDatabaseSubscription';
+export type {
+  UseDatabaseSubscriptionOptions,
+  UseDatabaseSubscriptionResult,
+} from './hooks/useDatabaseSubscription';
+export { useDocument } from './hooks/useDocument';
+export type { UseDocumentOptions, UseDocumentResult } from './hooks/useDocument';
+export { useUpsertDocument } from './hooks/useUpsertDocument';
+export type { UpsertDocumentArgs, UseUpsertDocumentResult } from './hooks/useUpsertDocument';
+export { useDatabaseSchema } from './hooks/useDatabaseSchema';
+export type { UseDatabaseSchemaResult } from './hooks/useDatabaseSchema';
+export { useTool } from './hooks/useTool';
+export type { ToolCallState, UseToolResult } from './hooks/useTool';
+export { useTools } from './hooks/useTools';
+export { useHandover } from './hooks/useHandover';
+export type { UseHandoverResult } from './hooks/useHandover';
+export { useCloudComputer } from './hooks/useCloudComputer';
+export type { UseCloudComputerResult } from './hooks/useCloudComputer';
+export { useCloudComputerShell } from './hooks/useCloudComputerShell';
+export type { UseCloudComputerShellResult } from './hooks/useCloudComputerShell';
+export { useNotisNavigation } from './hooks/useNotisNavigation';
+export { useTopBarSearch } from './hooks/useTopBarSearch';
+export { useBackend } from './hooks/useBackend';
+export { useMultiSelect } from './hooks/useMultiSelect';
+export { useCollectionInteractions, COLLECTION_ITEM_ATTRIBUTE } from './hooks/useCollectionInteractions';
+export { useActiveResource } from './hooks/useActiveResource';
+export {
+  ShortcutProvider,
+  SHORTCUT_SCOPE_PRIORITY,
+  isEditableShortcutEvent,
+  shortcutDisplay,
+  useShortcuts,
+} from './interactions/shortcuts';
+
+// Documents & markdown
+export { Markdown } from './components/Markdown';
+export type { MarkdownProps } from './components/Markdown';
+export { DocumentEditor } from './components/DocumentEditor';
+export { DocumentPage, DocumentPageSkeleton, usePrefetchRecord } from './components/DocumentPage';
+export { RecordProperties, HtmlFrame, ReportFrame, ShareControl } from './components/RecordComponents';
+export { RenderChartData } from './components/RenderChartData';
+export { MarkdownEditor } from './components/MarkdownEditor';
+export { NotisSelectionBoundary, NOTIS_CONTEXT_CLIPBOARD_TYPE } from './components/NotisSelectionBoundary';
+export type { NotisSelectionBoundaryProps } from './components/NotisSelectionBoundary';
+export {
+  asRecord,
+  blockNoteToPlainText,
+  extractRichText,
+  getDocumentPreview,
+  getRelationIds,
+  getSecretValue,
+  isPresentString,
+  markdownToPlainText,
+  normalizeDatabaseProperty,
+  normalizeDocumentRecord,
+  normalizePropertyValue,
+  optionalString,
+} from './documents';
+
+// Multi-select components
+export { Dialog } from './components/Dialog';
+export type { DialogProps } from './components/Dialog';
+export { MultiSelectActionBar } from './components/MultiSelectActionBar';
+export { MultiSelectCheckbox, MultiSelectCheckbox as SelectionCheckbox } from './components/MultiSelectCheckbox';
+export { MultiSelectDragOverlay, MultiSelectDragOverlay as SelectionMarquee } from './components/MultiSelectDragOverlay';
+export { ShortcutHints } from './components/ShortcutHints';
+export type {
+  DragRect,
+  MultiSelectController,
+  UseMultiSelectOptions,
+} from './hooks/useMultiSelect';
+export type {
+  MultiSelectAction,
+  MultiSelectActionBarProps,
+} from './components/MultiSelectActionBar';
+export type { MultiSelectCheckboxProps } from './components/MultiSelectCheckbox';
+export type { MultiSelectDragOverlayProps } from './components/MultiSelectDragOverlay';
+export type { MultiSelectCheckboxProps as SelectionCheckboxProps } from './components/MultiSelectCheckbox';
+export type { MultiSelectDragOverlayProps as SelectionMarqueeProps } from './components/MultiSelectDragOverlay';
+export type { ShortcutHint, ShortcutHintsProps } from './components/ShortcutHints';
+export type {
+  CollectionInteractionController,
+  CollectionInteractionReason,
+  CollectionKeyboardShortcuts,
+  CollectionNavigationContext,
+  CollectionNavigationDirection,
+  CollectionSelectionChange,
+  SelectionMarqueeRect,
+  UseCollectionInteractionsOptions,
+} from './hooks/useCollectionInteractions';
+export type {
+  ShortcutDefinition,
+  ShortcutHelpEntry,
+  ShortcutScope,
+  UseShortcutsOptions,
+} from './interactions/shortcuts';
+export type {
+  CollectionAction,
+  CollectionActionContext,
+  CollectionActionIntent,
+  ResolvedCollectionAction,
+} from './interactions/actions';
+
+// Types (re-exported for convenience)
+export type {
+  AppDescriptor,
+  CloudComputerCliAuthFacts,
+  CloudComputerFacts,
+  CloudComputerSandboxFacts,
+  ContextAttributeValue,
+  ContextResource,
+  ContextSelection,
+  CollectionItem,
+  CollectionItemDetail,
+  DatabaseDescriptor,
+  DatabaseProperty,
+  DatabasePropertyOption,
+  DatabasePropertyType,
+  DocumentContentType,
+  DocumentRecord,
+  HandoverPayload,
+  HandoverResult,
+  NotisDocumentEditorProps,
+  NotisDocumentPageProps,
+  NotisDocumentPageCrumb,
+  NotisDocumentPageMenuItem,
+  NotisDocumentPageParts,
+  NotisRecordProps,
+  NotisRecordPropertiesProps,
+  NotisHtmlFrameProps,
+  NotisReportFrameProps,
+  NotisShareControlProps,
+  NotisMarkdownEditorProps,
+  NotisMarkdownEditorSavePayload,
+  NotisMarkdownEditorSaveResult,
+  NotisRuntime,
+  RuntimeResource,
+  NotisRuntimeContext,
+  NotisRuntimeUI,
+  QueryFilter,
+  RouteDescriptor,
+  SecretPropertyValue,
+  SubscribeDatabaseOptions,
+  ToolDescriptor,
+  ToolCallOptions,
+  ToolInputSchema,
+} from './runtime';
+
+export { useToolQuery } from './hooks/useToolQuery';
+
+export { Skeleton, ViewSkeleton } from './components/Skeleton';
+
+export { useLongPressSelection } from './hooks/useLongPressSelection';
+export { isInteractionElementVisible } from './interactions/visibility';
+
+export type { AgentContextContent, AgentContextItem, ContextAttachment } from './agentContext';
+export { useAgentContext } from './hooks/useAgentContext';
+export { NotisCommentBoundary, NotisCommentBox } from './components/NotisCommentBoundary';
+export type { NotisCommentBoundaryProps, NotisCommentBoxProps } from './components/NotisCommentBoundary';

package/dist/sdk/src/interactions/actions.ts

@@ -0,0 +1,59 @@
+import type { ReactNode } from 'react';
+
+export type CollectionActionIntent =
+  | 'archive' | 'star' | 'delete'
+  | 'enable' | 'disable' | 'pause' | 'resume'
+  | 'move' | 'add-to-folder' | 'complete' | 'start-progress'
+  | 'custom';
+
+export interface CollectionActionContext<T> {
+  selectedIds: string[];
+  selectedItems: T[];
+  clearSelection: () => void;
+}
+
+export interface CollectionAction<T> {
+  id: string;
+  intent?: CollectionActionIntent;
+  label?: string;
+  icon?: ReactNode;
+  /** Omit to use the intent default, supply a key to override, or false to remove it. */
+  shortcut?: string | false;
+  destructive?: boolean;
+  disabled?: boolean | ((context: CollectionActionContext<T>) => boolean);
+  pending?: boolean;
+  onRun: (context: CollectionActionContext<T>) => void | Promise<void>;
+}
+
+export interface ResolvedCollectionAction {
+  id: string;
+  label: string;
+  icon?: ReactNode;
+  shortcut?: string;
+  destructive?: boolean;
+  disabled?: boolean;
+  pending?: boolean;
+  onRun: () => void | Promise<void>;
+}
+
+const ACTION_DEFAULTS: Record<Exclude<CollectionActionIntent, 'custom'>, { label: string; shortcut: string }> = {
+  archive: { label: 'Archive', shortcut: 'E' },
+  star: { label: 'Star', shortcut: 'S' },
+  delete: { label: 'Delete', shortcut: '#' },
+  enable: { label: 'Enable', shortcut: 'E' },
+  disable: { label: 'Disable', shortcut: 'D' },
+  pause: { label: 'Pause', shortcut: 'P' },
+  resume: { label: 'Resume', shortcut: 'R' },
+  move: { label: 'Move', shortcut: 'M' },
+  'add-to-folder': { label: 'Add to folder', shortcut: 'F' },
+  complete: { label: 'Mark complete', shortcut: 'C' },
+  'start-progress': { label: 'Start progress', shortcut: 'P' },
+};
+
+export function collectionActionDefaults(intent: CollectionActionIntent | undefined): {
+  label?: string;
+  shortcut?: string;
+} {
+  if (!intent || intent === 'custom') return {};
+  return ACTION_DEFAULTS[intent];
+}