@notis_ai/cli 0.2.0 → 0.2.2

package/template/packages/sdk/src/hooks/useNotis.ts

@@ -0,0 +1,34 @@
+'use client';
+
+import { useNotisRuntime } from '../provider';
+import type { AppDescriptor, CollectionItemDetail, DatabaseDescriptor, RouteDescriptor } from '../runtime';
+
+interface NotisContext {
+  /** App metadata (id, name, icon, description). Null before runtime loads. */
+  app: AppDescriptor | null;
+  /** Current route descriptor. Null before runtime loads. */
+  route: RouteDescriptor | null;
+  /** Databases declared by this app. Empty before runtime loads. */
+  databases: DatabaseDescriptor[];
+  /** Selected collection item for the current route, when applicable. */
+  collectionItem: CollectionItemDetail | null;
+  /** Whether the runtime is loaded and available. */
+  ready: boolean;
+}
+
+/**
+ * Access app-level metadata, the current route, declared databases, and the
+ * selected collection item. Returns safe defaults when the portal runtime is
+ * not available.
+ */
+export function useNotis(): NotisContext {
+  const runtime = useNotisRuntime();
+
+  return {
+    app: runtime?.app ?? null,
+    route: runtime?.route ?? null,
+    databases: runtime?.databases ?? [],
+    collectionItem: runtime?.context?.collectionItem ?? null,
+    ready: runtime !== null,
+  };
+}

package/template/packages/sdk/src/hooks/useNotisNavigation.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import { useCallback } from 'react';
+import { useNotisRuntime } from '../provider';
+
+interface NavigationActions {
+  /** Navigate to a route within the app by its path. */
+  toRoute: (path: string) => void;
+  /** Navigate to a document detail view. */
+  toDocument: (documentId: string, title?: string | null) => void;
+  /** Navigate to the app's default route. */
+  toApp: () => void;
+}
+
+/**
+ * Navigation helpers for moving between routes and documents within the app.
+ * When rendered inside the portal, uses the runtime.navigate() bridge.
+ * Without a portal runtime, falls back to window.location for route navigation.
+ *
+ * ```tsx
+ * const nav = useNotisNavigation();
+ * nav.toRoute('/settings');
+ * ```
+ */
+export function useNotisNavigation(): NavigationActions {
+  const runtime = useNotisRuntime();
+
+  const toRoute = useCallback((path: string) => {
+    if (runtime?.navigate) {
+      runtime.navigate({ kind: 'route', path });
+    } else if (typeof window !== 'undefined') {
+      window.location.href = path;
+    }
+  }, [runtime]);
+
+  const toDocument = useCallback((documentId: string, title?: string | null) => {
+    if (runtime?.navigate) {
+      runtime.navigate({ kind: 'document', documentId, title: title ?? undefined });
+    }
+  }, [runtime]);
+
+  const toApp = useCallback(() => {
+    if (runtime?.navigate) {
+      runtime.navigate({ kind: 'app' });
+    }
+  }, [runtime]);
+
+  return { toRoute, toDocument, toApp };
+}

package/template/packages/sdk/src/hooks/useTool.ts

@@ -0,0 +1,64 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+
+type ToolArguments = Record<string, unknown>;
+
+type ToolCall<TArgs extends ToolArguments | undefined, TResult> = undefined extends TArgs
+  ? (args?: Exclude<TArgs, undefined>) => Promise<TResult>
+  : (args: TArgs) => Promise<TResult>;
+
+export interface ToolCallState {
+  loading: boolean;
+  error: Error | null;
+}
+
+export interface UseToolResult<
+  TArgs extends ToolArguments | undefined = ToolArguments | undefined,
+  TResult = unknown,
+> extends ToolCallState {
+  call: ToolCall<TArgs, TResult>;
+}
+
+/**
+ * Call a specific Notis tool by name.
+ *
+ * ```tsx
+ * const { call, loading } = useTool('notis-default-web_search');
+ * const result = await call({ query: 'latest news' });
+ * ```
+ */
+export function useTool<
+  TArgs extends ToolArguments | undefined = ToolArguments | undefined,
+  TResult = unknown,
+>(toolName: string): UseToolResult<TArgs, TResult> {
+  const runtime = useNotisRuntime();
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const call = useCallback(
+    async (args?: ToolArguments): Promise<TResult> => {
+      if (!runtime) {
+        throw new Error('Notis runtime not available. Ensure NotisProvider is mounted.');
+      }
+
+      setLoading(true);
+      setError(null);
+
+      try {
+        const result = await runtime.callTool<TResult>(toolName, args);
+        return result;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [runtime, toolName],
+  ) as ToolCall<TArgs, TResult>;
+
+  return { call, loading, error };
+}

package/template/packages/sdk/src/hooks/useTools.ts

@@ -0,0 +1,56 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { ToolDescriptor } from '../runtime';
+
+interface UseToolsResult {
+  tools: ToolDescriptor[];
+  loading: boolean;
+  error: Error | null;
+}
+
+/**
+ * List all tools available to this app.
+ *
+ * ```tsx
+ * const { tools, loading } = useTools();
+ * ```
+ */
+export function useTools(): UseToolsResult {
+  const runtime = useNotisRuntime();
+  const [tools, setTools] = useState<ToolDescriptor[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (!runtime) {
+      setLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    setLoading(true);
+
+    runtime
+      .listTools()
+      .then((result) => {
+        if (!cancelled) {
+          setTools(result);
+          setLoading(false);
+        }
+      })
+      .catch((err) => {
+        if (!cancelled) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+          setLoading(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [runtime]);
+
+  return { tools, loading, error };
+}

package/template/packages/sdk/src/hooks/useTopBarSearch.ts

@@ -0,0 +1,73 @@
+'use client';
+
+import { useCallback, useEffect } from 'react';
+import { useNotisRuntime } from '../provider';
+
+interface TopBarSearchOptions {
+  /** Current value shown in the top bar search input. */
+  value: string;
+  /** Called when the user types in the top bar. */
+  onChange: (value: string) => void;
+  /** Placeholder text for the input. Defaults to 'Search…'. */
+  placeholder?: string;
+  /** Called when the user presses Enter. May return a Promise. */
+  onSubmit?: () => void | Promise<void>;
+}
+
+interface TopBarSearchActions {
+  /** Toggle the loader that replaces the search icon in the top bar. */
+  setLoading: (loading: boolean) => void;
+}
+
+/**
+ * Registers this view's search binding with the portal's top bar search input.
+ * While the component is mounted, typing in the top bar calls `onChange`,
+ * pressing Enter calls `onSubmit`, and the `value` prop drives the input.
+ *
+ * Call `setLoading(true)` to show the standard spinner in the top bar while a
+ * query is running; `setLoading(false)` restores the search icon.
+ *
+ * Without a portal runtime, this hook is a safe no-op.
+ *
+ * ```tsx
+ * const [q, setQ] = useState('');
+ * const { setLoading } = useTopBarSearch({
+ *   value: q,
+ *   onChange: setQ,
+ *   placeholder: 'Search notes…',
+ *   onSubmit: async () => {
+ *     setLoading(true);
+ *     try { await runSearch(q); } finally { setLoading(false); }
+ *   },
+ * });
+ * ```
+ *
+ * Stabilize `onChange` and `onSubmit` with `useCallback` to avoid re-registering
+ * on every render.
+ */
+export function useTopBarSearch(opts: TopBarSearchOptions): TopBarSearchActions {
+  const runtime = useNotisRuntime();
+  const { value, onChange, placeholder, onSubmit } = opts;
+
+  useEffect(() => {
+    const register = runtime?.registerTopBarSearch;
+    if (!register) return;
+    register({ onChange, placeholder, onSubmit });
+    return () => {
+      register(null);
+    };
+  }, [runtime, onChange, placeholder, onSubmit]);
+
+  useEffect(() => {
+    runtime?.setTopBarSearchValue?.(value);
+  }, [runtime, value]);
+
+  const setLoading = useCallback(
+    (loading: boolean) => {
+      runtime?.setTopBarSearchLoading?.(loading);
+    },
+    [runtime],
+  );
+
+  return { setLoading };
+}

package/template/packages/sdk/src/hooks/useUpsertDocument.ts

@@ -0,0 +1,50 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { DocumentRecord } from '../runtime';
+
+interface UpsertArgs {
+  databaseSlug: string;
+  documentId?: string;
+  title?: string;
+  properties?: Record<string, unknown>;
+  contentBlocknote?: Array<Record<string, unknown>> | null;
+}
+
+interface UseUpsertDocumentResult {
+  upsert: (args: UpsertArgs) => Promise<DocumentRecord>;
+  loading: boolean;
+  error: Error | null;
+}
+
+export function useUpsertDocument(): UseUpsertDocumentResult {
+  const runtime = useNotisRuntime();
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const upsert = useCallback(
+    async (args: UpsertArgs): Promise<DocumentRecord> => {
+      if (!runtime) {
+        throw new Error('Notis runtime not available. Ensure NotisProvider is mounted.');
+      }
+
+      setLoading(true);
+      setError(null);
+
+      try {
+        const result = await runtime.upsertDocument(args);
+        return result.document;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [runtime],
+  );
+
+  return { upsert, loading, error };
+}

package/template/packages/sdk/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * @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 { useNotis } from './hooks/useNotis';
+export { useDatabase } from './hooks/useDatabase';
+export { useUpsertDocument } from './hooks/useUpsertDocument';
+export { useTool } from './hooks/useTool';
+export type { ToolCallState, UseToolResult } from './hooks/useTool';
+export { useTools } from './hooks/useTools';
+export { useNotisNavigation } from './hooks/useNotisNavigation';
+export { useTopBarSearch } from './hooks/useTopBarSearch';
+export { useBackend } from './hooks/useBackend';
+export { useMultiSelect } from './hooks/useMultiSelect';
+
+// Multi-select components
+export { MultiSelectActionBar } from './components/MultiSelectActionBar';
+export { MultiSelectCheckbox } from './components/MultiSelectCheckbox';
+export { MultiSelectDragOverlay } from './components/MultiSelectDragOverlay';
+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';
+
+// Types (re-exported for convenience)
+export type {
+  AppDescriptor,
+  CollectionItem,
+  CollectionItemDetail,
+  DatabaseDescriptor,
+  DatabaseProperty,
+  DocumentRecord,
+  NotisRuntime,
+  NotisRuntimeContext,
+  QueryFilter,
+  RouteDescriptor,
+  ToolDescriptor,
+  ToolInputSchema,
+} from './runtime';

package/template/packages/sdk/src/provider.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import React, { createContext, useContext, type Context, type ReactNode } from 'react';
+import type { NotisRuntime } from './runtime';
+
+const NOTIS_CONTEXT_SYMBOL = Symbol.for('notis.sdk.runtime_context');
+
+type NotisContextGlobal = typeof globalThis & {
+  [NOTIS_CONTEXT_SYMBOL]?: Context<NotisRuntime | null>;
+};
+
+function getNotisContext(): Context<NotisRuntime | null> {
+  const scope = globalThis as NotisContextGlobal;
+  if (!scope[NOTIS_CONTEXT_SYMBOL]) {
+    scope[NOTIS_CONTEXT_SYMBOL] = createContext<NotisRuntime | null>(null);
+  }
+  return scope[NOTIS_CONTEXT_SYMBOL]!;
+}
+
+const NotisContext = getNotisContext();
+
+/**
+ * Provides the Notis runtime context to all child components. The portal owns
+ * the runtime and injects it into the rendered app tree.
+ */
+export function NotisProvider({ children, runtime }: { children: ReactNode; runtime: NotisRuntime | null }) {
+  if (runtime === undefined) {
+    throw new Error('NotisProvider requires an explicit runtime prop.');
+  }
+  return (
+    <NotisContext.Provider value={runtime}>
+      {children}
+    </NotisContext.Provider>
+  );
+}
+
+/**
+ * Returns the raw NotisRuntime or null if not yet available.
+ * Prefer the typed hooks (useTool, useNotis, etc.) over this.
+ */
+export function useNotisRuntime(): NotisRuntime | null {
+  return useContext(NotisContext);
+}

package/template/packages/sdk/src/runtime.ts

@@ -0,0 +1,161 @@
+/**
+ * NotisRuntime is the bridge between app code running in the browser and the
+ * Notis platform. The portal owns the runtime and injects it through
+ * `NotisProvider` when the app is rendered.
+ *
+ * App code should never reach for globals. Use the hooks from `@notis/sdk`
+ * (useTool, useNotis, etc.) which read from the NotisProvider context.
+ */
+
+// ---------------------------------------------------------------------------
+// Database types
+// ---------------------------------------------------------------------------
+
+export interface DatabaseProperty {
+  name: string;
+  type: 'title' | 'rich_text' | 'number' | 'checkbox' | 'date' | 'select' | 'multi_select' | 'status' | 'relation' | 'formula' | 'files';
+  description?: string;
+  options?: Array<{ name: string; id?: string }>;
+}
+
+export interface DatabaseDescriptor {
+  slug: string;
+  title: string;
+  description?: string | null;
+  icon?: string | null;
+  properties: DatabaseProperty[];
+}
+
+export interface DocumentRecord {
+  id: string;
+  title: string;
+  properties: Record<string, unknown>;
+  icon?: string | null;
+  cover?: string | null;
+  databaseSlug?: string;
+  contentBlocknote?: Array<Record<string, unknown>> | null;
+  contentMarkdown?: string | null;
+  plainText?: string | null;
+  createdAt?: string | null;
+  lastEditedTime?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Tool types
+// ---------------------------------------------------------------------------
+
+export type ToolInputSchema = Record<string, unknown>;
+
+export interface ToolDescriptor {
+  name: string;
+  description?: string;
+  inputSchema?: ToolInputSchema;
+}
+
+// ---------------------------------------------------------------------------
+// Route types
+// ---------------------------------------------------------------------------
+
+export interface RouteDescriptor {
+  slug: string;
+  path: string;
+  name: string;
+  icon?: string | null;
+  parentSlug?: string | null;
+  default?: boolean;
+  collection?: {
+    database: string;
+    titleProperty: string;
+    parentProperty?: string | null;
+    sidebar?: {
+      mode: 'flat-list' | 'tree';
+      allowCreate: boolean;
+    } | null;
+  } | null;
+}
+
+export interface CollectionItem {
+  id: string;
+  title: string;
+  icon?: string | null;
+}
+
+export interface CollectionItemDetail extends CollectionItem {
+  properties: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// App descriptor
+// ---------------------------------------------------------------------------
+
+export interface AppDescriptor {
+  id: string;
+  name: string;
+  icon?: string | null;
+  description?: string | null;
+}
+
+export interface QueryFilter {
+  filters?: Array<{
+    property: string;
+    operator: string;
+    value: unknown;
+  }>;
+  sorts?: Array<{
+    property: string;
+    direction: 'asc' | 'desc';
+  }>;
+  page_size?: number;
+}
+
+export interface NotisRuntimeContext {
+  collectionItem?: CollectionItemDetail | null;
+}
+
+// ---------------------------------------------------------------------------
+// NotisRuntime
+// ---------------------------------------------------------------------------
+
+export interface NotisRuntime {
+  app: AppDescriptor;
+  route: RouteDescriptor;
+  databases: DatabaseDescriptor[];
+  context: NotisRuntimeContext;
+
+  navigate?: (payload: { kind: string; [key: string]: unknown }) => void;
+
+  registerTopBarSearch?: (
+    config:
+      | {
+          onChange: (value: string) => void;
+          placeholder?: string;
+          onSubmit?: () => void | Promise<void>;
+        }
+      | null,
+  ) => void;
+  setTopBarSearchValue?: (value: string) => void;
+  setTopBarSearchLoading?: (loading: boolean) => void;
+
+  listTools(): Promise<ToolDescriptor[]>;
+  callTool<TResult = unknown>(name: string, args?: Record<string, unknown>): Promise<TResult>;
+
+  queryDatabase(args: {
+    databaseSlug: string;
+    query?: QueryFilter;
+    offset?: number;
+  }): Promise<{ documents: DocumentRecord[] }>;
+
+  upsertDocument(args: {
+    databaseSlug: string;
+    documentId?: string;
+    title?: string;
+    properties?: Record<string, unknown>;
+    contentBlocknote?: Array<Record<string, unknown>> | null;
+  }): Promise<{ status: string; document: DocumentRecord }>;
+
+  request(path: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+  }): Promise<unknown>;
+}

package/template/packages/sdk/src/styles.css

@@ -0,0 +1,38 @@
+/**
+ * Notis theme CSS variables.
+ *
+ * Import this in your app layout:
+ *
+ *   import '@notis/sdk/styles.css';
+ *
+ * The portal injects the live Notis theme variables at render time.
+ */
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  [data-notis-app-root] {
+    color: hsl(var(--foreground));
+    display: block;
+    min-height: 100%;
+  }
+}
+
+@layer components {
+  .notis-app-shell {
+    @apply mx-auto w-full max-w-[var(--portal-page-max-width)] px-4 py-6 md:px-4 md:py-8;
+  }
+
+  .notis-app-surface {
+    @apply rounded-2xl border border-border bg-card text-card-foreground shadow-sm;
+  }
+
+  .notis-app-section {
+    @apply p-5 md:p-6;
+  }
+}

package/template/packages/sdk/src/ui.ts

@@ -0,0 +1,15 @@
+/**
+ * @notis/sdk/ui - Re-exported shadcn components for Notis apps.
+ *
+ * Apps include shadcn via their own `components.json` and `@/components/ui/*`
+ * imports. This entrypoint is provided as a convenience for apps that want to
+ * import directly from the SDK without setting up shadcn locally.
+ *
+ * For now, this is a placeholder. The scaffold template sets up shadcn
+ * directly in the app project, so components come from `@/components/ui/*`.
+ * This file can be expanded later to re-export a curated set of components
+ * pre-themed for Notis.
+ */
+
+// Placeholder -- apps use shadcn directly via their project's components/ui/
+export {};

package/template/packages/sdk/src/vite.ts

@@ -0,0 +1,56 @@
+/**
+ * Vite config builder for Notis apps.
+ *
+ * Usage:
+ * ```ts
+ * // vite.config.ts
+ * import { notisViteConfig } from '@notis/sdk/vite';
+ * import appConfig from './notis.config';
+ * export default notisViteConfig(appConfig);
+ * ```
+ *
+ * Produces a library-mode ES module bundle with React externalized.
+ * Output: .notis/output/bundle/app.js + app.css
+ */
+
+import type { NotisAppConfig } from './config';
+
+export function notisViteConfig(appConfig: NotisAppConfig) {
+  return {
+    plugins: [
+      // @vitejs/plugin-react is added by the consumer's vite.config.ts
+      // or auto-detected. We provide the config shape only.
+    ],
+    build: {
+      lib: {
+        entry: '.notis/_entry.tsx',
+        formats: ['es'] as const,
+        fileName: () => 'app.js',
+      },
+      rollupOptions: {
+        external: ['react', 'react-dom', 'react-dom/client', 'react/jsx-runtime', 'react/jsx-dev-runtime'],
+        output: {
+          globals: {
+            react: 'window.React',
+            'react-dom': 'window.ReactDOM',
+            'react-dom/client': 'window.ReactDOMClient',
+            'react/jsx-runtime': 'window.React',
+          },
+          assetFileNames: 'app[extname]',
+          inlineDynamicImports: true,
+        },
+      },
+      outDir: '.notis/output/bundle',
+      emptyOutDir: true,
+      cssCodeSplit: false,
+    },
+    resolve: {
+      alias: {
+        '@': process.cwd(),
+      },
+    },
+    define: {
+      'process.env.NODE_ENV': JSON.stringify('production'),
+    },
+  };
+}