@notis_ai/cli 0.2.0-beta.21.1 → 0.2.0-beta.35.1

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/index.ts

@@ -0,0 +1,46 @@
+/**
+ * @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 } from './provider';
+
+// Hooks
+export { useNotis } from './hooks/useNotis';
+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,
+  NotisRuntime,
+  NotisRuntimeContext,
+  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,80 @@
+/**
+ * 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.
+ */
+
+// ---------------------------------------------------------------------------
+// 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?: Record<string, unknown> | null;
+}
+
+// ---------------------------------------------------------------------------
+// App descriptor
+// ---------------------------------------------------------------------------
+
+export interface AppDescriptor {
+  id: string;
+  name: string;
+  icon?: string | null;
+  description?: string | null;
+}
+
+export type NotisRuntimeContext = Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// NotisRuntime
+// ---------------------------------------------------------------------------
+
+export interface NotisRuntime {
+  app: AppDescriptor;
+  route: RouteDescriptor;
+  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>;
+
+  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/src/command-specs/auth.js

@@ -1,178 +0,0 @@
-import { CliError, EXIT_CODES } from '../runtime/errors.js';
-import {
-  clearStoredJwt,
-  probeAuth,
-  promptForJwt,
-  updateStoredProfile,
-} from './helpers.js';
-
-async function authLoginHandler(ctx) {
-  let jwt = ctx.options.jwt || process.env.NOTIS_JWT;
-  if (!jwt) {
-    if (ctx.runtime.nonInteractive) {
-      throw new CliError({
-        code: 'auth_missing',
-        message: `No JWT configured for profile ${ctx.runtime.profileName}`,
-        exitCode: EXIT_CODES.auth,
-        hints: [
-          {
-            command: 'notis auth login --jwt <token>',
-            reason: 'Provide a token explicitly in non-interactive mode',
-          },
-        ],
-      });
-    }
-    jwt = await promptForJwt();
-  }
-
-  updateStoredProfile({
-    profileName: ctx.runtime.profileName,
-    jwt,
-    apiBase: ctx.globalOptions.apiBase,
-    setCurrent: true,
-  });
-
-  return ctx.output.emitSuccess({
-    command: ctx.spec.command_path.join(' '),
-    data: {
-      profile: ctx.runtime.profileName,
-      api_base: ctx.globalOptions.apiBase || ctx.runtime.apiBase,
-    },
-    humanSummary: `Stored credentials for profile ${ctx.runtime.profileName}`,
-    hints: [
-      { command: 'notis whoami', reason: 'Verify your identity and available toolkits' },
-    ],
-    meta: { mutating: true },
-  });
-}
-
-async function authLogoutHandler(ctx) {
-  clearStoredJwt(ctx.runtime.profileName);
-  return ctx.output.emitSuccess({
-    command: ctx.spec.command_path.join(' '),
-    data: { profile: ctx.runtime.profileName },
-    humanSummary: `Removed stored JWT for profile ${ctx.runtime.profileName}`,
-    meta: { mutating: true },
-  });
-}
-
-async function authStatusHandler(ctx) {
-  const hasJwt = Boolean(ctx.runtime.jwt);
-  let verified = false;
-  let toolkits = [];
-  if (hasJwt && ctx.options.verify) {
-    const payload = await probeAuth(ctx.runtime);
-    toolkits = payload.toolkits || [];
-    verified = true;
-  }
-
-  return ctx.output.emitSuccess({
-    command: ctx.spec.command_path.join(' '),
-    data: {
-      profile: ctx.runtime.profileName,
-      api_base: ctx.runtime.apiBase,
-      has_jwt: hasJwt,
-      verified,
-      toolkits,
-    },
-    humanSummary: hasJwt
-      ? `Profile ${ctx.runtime.profileName} is configured`
-      : `Profile ${ctx.runtime.profileName} is missing a JWT`,
-    hints: hasJwt
-      ? []
-      : [{ command: 'notis auth login --jwt <token>', reason: 'Configure credentials for this profile' }],
-    meta: { mutating: false },
-  });
-}
-
-export const authCommandSpecs = [
-  {
-    command_path: ['auth', 'login'],
-    summary: 'Store credentials for a named CLI profile.',
-    when_to_use: 'Use this before authenticated commands, especially in fresh environments or CI profiles.',
-    args_schema: {
-      arguments: [],
-      options: [
-        { flags: '--jwt <token>', description: 'JWT token to store for the profile.' },
-      ],
-    },
-    examples: ['notis auth login --jwt <token>', 'notis auth login --profile staging --api-base http://localhost:3001'],
-    output_schema: 'Returns the active profile name and API base.',
-    mutates: true,
-    idempotent: true,
-    require_auth: false,
-    related_commands: ['notis auth status --verify', 'notis auth logout'],
-    backend_call: { type: 'local' },
-    handler: authLoginHandler,
-  },
-  {
-    command_path: ['auth', 'logout'],
-    summary: 'Remove the stored JWT for the active profile.',
-    when_to_use: 'Use this to clear local credentials without touching other profiles.',
-    args_schema: { arguments: [], options: [] },
-    examples: ['notis auth logout', 'notis auth logout --profile staging'],
-    output_schema: 'Returns the profile that was updated.',
-    mutates: true,
-    idempotent: true,
-    require_auth: false,
-    related_commands: ['notis auth login --jwt <token>', 'notis auth status'],
-    backend_call: { type: 'local' },
-    handler: authLogoutHandler,
-  },
-  {
-    command_path: ['auth', 'status'],
-    summary: 'Inspect local auth configuration and optionally verify it against the API.',
-    when_to_use: 'Use this before automating commands to confirm the active profile and token health.',
-    args_schema: {
-      arguments: [],
-      options: [
-        { flags: '--verify', description: 'Perform a live authenticated roundtrip to the API.' },
-      ],
-    },
-    examples: ['notis auth status', 'notis auth status --verify --json'],
-    output_schema: 'Returns profile, api_base, local auth presence, and optional verification data.',
-    mutates: false,
-    idempotent: true,
-    require_auth: false,
-    related_commands: ['notis doctor', 'notis auth login --jwt <token>'],
-    backend_call: { type: 'notis_find_toolkits' },
-    handler: authStatusHandler,
-  },
-  {
-    command_path: ['login'],
-    display_name: 'login',
-    summary: 'Deprecated alias for `notis auth login`.',
-    when_to_use: 'Use only for backward compatibility with older scripts.',
-    args_schema: {
-      arguments: [],
-      options: [
-        { flags: '--jwt <token>', description: 'JWT token to store for the profile.' },
-      ],
-    },
-    examples: ['notis login --jwt <token>'],
-    output_schema: 'Same output as `notis auth login`.',
-    mutates: true,
-    idempotent: true,
-    require_auth: false,
-    related_commands: ['notis auth login --jwt <token>'],
-    backend_call: { type: 'local', alias_for: 'auth login' },
-    deprecated_alias_for: 'notis auth login',
-    handler: authLoginHandler,
-  },
-  {
-    command_path: ['logout'],
-    display_name: 'logout',
-    summary: 'Deprecated alias for `notis auth logout`.',
-    when_to_use: 'Use only for backward compatibility with older scripts.',
-    args_schema: { arguments: [], options: [] },
-    examples: ['notis logout'],
-    output_schema: 'Same output as `notis auth logout`.',
-    mutates: true,
-    idempotent: true,
-    require_auth: false,
-    related_commands: ['notis auth logout'],
-    backend_call: { type: 'local', alias_for: 'auth logout' },
-    deprecated_alias_for: 'notis auth logout',
-    handler: authLogoutHandler,
-  },
-];

package/src/command-specs/db.js

@@ -1,163 +0,0 @@
-import { formatTable } from '../runtime/output.js';
-import { nextIdempotencyKey, parseMaybeJson, runToolCommand } from './helpers.js';
-
-async function dbListHandler(ctx) {
-  const result = await runToolCommand({
-    runtime: ctx.runtime,
-    toolName: 'notis_list_databases',
-  });
-  const databases = result.payload.databases || [];
-  const firstSlug = databases[0]?.slug;
-  return ctx.output.emitSuccess({
-    command: ctx.spec.command_path.join(' '),
-    data: { databases },
-    humanSummary: databases.length ? `Found ${databases.length} databases` : 'No databases found.',
-    hints: firstSlug
-      ? [{ command: `notis db query ${firstSlug}`, reason: 'Query this database' }]
-      : [{ command: 'notis db upsert --operation create --title "My DB"', reason: 'Create a new database' }],
-    renderHuman: () =>
-      databases.length
-        ? formatTable(databases, [
-            { label: 'ID', value: (database) => database.id || '' },
-            { label: 'Name', value: (database) => database.name || 'Untitled' },
-            { label: 'Slug', value: (database) => database.slug || '-' },
-          ])
-        : 'No databases found.',
-  });
-}
-
-async function dbUpsertHandler(ctx) {
-  const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
-  const payload = {
-    operation: ctx.options.operation,
-  };
-  if (ctx.options.databaseId) {
-    payload.database_id = ctx.options.databaseId;
-  }
-  if (ctx.options.title) {
-    payload.title = ctx.options.title;
-  }
-  if (ctx.options.description) {
-    payload.description = ctx.options.description;
-  }
-  if (ctx.options.icon) {
-    const v = ctx.options.icon;
-    payload.icon = v.startsWith('lucide:') ? v : `lucide:${v}`;
-  }
-  if (ctx.options.properties) {
-    payload.properties = parseMaybeJson(ctx.options.properties, 'properties');
-  }
-
-  const result = await runToolCommand({
-    runtime: ctx.runtime,
-    toolName: 'notis_upsert_database',
-    arguments_: payload,
-    mutating: true,
-    idempotencyKey,
-  });
-  return ctx.output.emitSuccess({
-    command: ctx.spec.command_path.join(' '),
-    data: result.payload,
-    humanSummary: `Database ${ctx.options.operation} completed`,
-    meta: { mutating: true, idempotency_key: idempotencyKey || null },
-  });
-}
-
-async function dbQueryHandler(ctx) {
-  const query = {};
-  if (ctx.options.filter) {
-    query.filter = parseMaybeJson(ctx.options.filter, 'filter');
-  }
-  if (ctx.options.sort) {
-    const parsedSorts = parseMaybeJson(ctx.options.sort, 'sort');
-    query.sorts = Array.isArray(parsedSorts) ? parsedSorts : [parsedSorts];
-  }
-  if (ctx.options.pageSize) {
-    query.page_size = Number.parseInt(ctx.options.pageSize, 10);
-  }
-
-  const payload = {
-    database_slug: ctx.args.databaseSlug,
-    query,
-  };
-  if (ctx.options.offset) {
-    payload.offset = Number.parseInt(ctx.options.offset, 10);
-  }
-  if (ctx.options.cursor) {
-    payload.start_cursor = ctx.options.cursor;
-  }
-
-  const result = await runToolCommand({
-    runtime: ctx.runtime,
-    toolName: 'notis_query',
-    arguments_: payload,
-  });
-
-  return ctx.output.emitSuccess({
-    command: ctx.spec.command_path.join(' '),
-    data: result.payload,
-    humanSummary: `Queried database ${ctx.args.databaseSlug}`,
-    renderHuman: () => JSON.stringify(result.payload, null, 2),
-  });
-}
-
-export const dbCommandSpecs = [
-  {
-    command_path: ['db', 'list'],
-    summary: 'List native Notis databases.',
-    when_to_use: 'Use this to find database ids and slugs before querying or updating schemas.',
-    args_schema: { arguments: [], options: [] },
-    examples: ['notis db list', 'notis db list --json'],
-    output_schema: 'Returns an array of native database records.',
-    mutates: false,
-    idempotent: true,
-    related_commands: ['notis db query <database-slug>', 'notis db upsert'],
-    backend_call: { type: 'tool', name: 'notis_list_databases' },
-    handler: dbListHandler,
-  },
-  {
-    command_path: ['db', 'upsert'],
-    summary: 'Create or update a native database schema.',
-    when_to_use: 'Use this when you need to provision a new database or adjust an existing schema.',
-    args_schema: {
-      arguments: [],
-      options: [
-        { flags: '--operation <create|update>', description: 'Create a new database or update an existing one.' },
-        { flags: '--database-id <id>', description: 'Database id for update operations.' },
-        { flags: '--title <text>', description: 'Database title.' },
-        { flags: '--description <text>', description: 'Database description.' },
-        { flags: '--icon <lucide-icon-name>', description: 'Database icon (Lucide icon name, e.g. database).' },
-        { flags: '--properties <json>', description: 'JSON array of property definitions.' },
-      ],
-    },
-    examples: ['notis db upsert --operation create --title "Tasks"', 'notis db upsert --operation update --database-id db_123 --title "Tasks V2"'],
-    output_schema: 'Returns the backend database upsert payload.',
-    mutates: true,
-    idempotent: true,
-    related_commands: ['notis db list', 'notis db query <database-slug>'],
-    backend_call: { type: 'tool', name: 'notis_upsert_database' },
-    handler: dbUpsertHandler,
-  },
-  {
-    command_path: ['db', 'query'],
-    summary: 'Run a structured query against a native Notis database.',
-    when_to_use: 'Use this when the database slug is known and you need direct filters, sorts, or pagination.',
-    args_schema: {
-      arguments: [{ token: '<database-slug>', description: 'Slug of the native database to query.' }],
-      options: [
-        { flags: '--filter <json>', description: 'Structured query filter JSON.' },
-        { flags: '--sort <json>', description: 'Sort JSON object or array.' },
-        { flags: '--page-size <n>', description: 'Page size between 1 and 100.' },
-        { flags: '--offset <n>', description: 'Zero-based offset.' },
-        { flags: '--cursor <value>', description: 'Pagination cursor alias for next_offset.' },
-      ],
-    },
-    examples: ['notis db query tasks --page-size 50', 'notis db query tasks --filter \'{"property":"Status"}\''],
-    output_schema: 'Returns the native database query payload from `notis_query`.',
-    mutates: false,
-    idempotent: true,
-    related_commands: ['notis db list', 'notis db upsert'],
-    backend_call: { type: 'tool', name: 'notis_query' },
-    handler: dbQueryHandler,
-  },
-];