@notis_ai/cli 0.2.4 → 0.2.6

package/template/package.json

@@ -1,6 +1,7 @@
 {
   "name": "my-notis-app",
   "version": "0.1.0",
+  "notisAppVersion": "0.1.0",
   "private": true,
   "type": "module",
   "scripts": {

package/template/packages/sdk/package.json

@@ -17,6 +17,10 @@
   "scripts": {
     "type-check": "tsc --noEmit"
   },
+  "dependencies": {
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
+  },
   "peerDependencies": {
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",

package/template/packages/sdk/src/components/DocumentEditor.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import type { CSSProperties, ReactElement } from 'react';
+import { useNotisRuntime } from '../provider';
+import { useDocument } from '../hooks/useDocument';
+import { Markdown } from './Markdown';
+import type { NotisDocumentEditorProps } from '../runtime';
+
+const fallbackNoticeStyle: CSSProperties = {
+  marginTop: '0.75rem',
+  fontSize: '12px',
+  color: 'hsl(var(--muted-foreground))',
+};
+
+const fallbackFrameStyle: CSSProperties = {
+  borderRadius: '0.5rem',
+  border: '1px dashed hsl(var(--border))',
+  padding: '1rem',
+  fontSize: '13px',
+  color: 'hsl(var(--muted-foreground))',
+};
+
+const fallbackTitleStyle: CSSProperties = {
+  margin: '0 0 0.75rem',
+  fontSize: '1.5rem',
+  fontWeight: 700,
+  letterSpacing: '-0.01em',
+  color: 'hsl(var(--foreground))',
+};
+
+/**
+ * Read-only stand-in used when no host editor is available (standalone dev
+ * harness, snapshots). Markdown content renders via `Markdown`; other content
+ * types get a typed placeholder.
+ */
+function DocumentEditorFallback({ documentId, variant = 'full', className }: NotisDocumentEditorProps) {
+  const runtime = useNotisRuntime();
+  const { document, loading, error } = useDocument(documentId);
+  // Listing screenshots should show the app as it looks in the portal, so the
+  // harness-only editing notice stays out of scenario captures.
+  const isScreenshot = Boolean(runtime?.context?.screenshotScenario);
+
+  if (loading) {
+    return <div className={className} style={fallbackFrameStyle}>Loading document…</div>;
+  }
+  if (error || !document) {
+    return (
+      <div className={className} style={fallbackFrameStyle}>
+        {error?.message ?? 'Document not found.'}
+      </div>
+    );
+  }
+
+  const isMarkdown = document.contentType !== 'file';
+  return (
+    <div className={className}>
+      {variant === 'full' ? <h1 style={fallbackTitleStyle}>{document.title}</h1> : null}
+      {isMarkdown ? (
+        <>
+          <Markdown value={document.contentMarkdown ?? ''} />
+          {isScreenshot ? null : (
+            <p style={fallbackNoticeStyle}>Read-only preview — editing is available inside the Notis portal.</p>
+          )}
+        </>
+      ) : (
+        <div style={fallbackFrameStyle}>
+          {document.fileType ? `${document.fileType.toUpperCase()} document` : 'File document'} — open it in
+          the Notis portal to view.
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Embeds the document editor for a document anywhere in an app view. The host
+ * (portal) provides the implementation through `runtime.ui.DocumentEditor` and
+ * dispatches on the document's content type (markdown -> rich text editor,
+ * files -> matching viewer). Outside the portal this falls back to a read-only
+ * preview.
+ *
+ * ```tsx
+ * <DocumentEditor documentId={entry.id} variant="body" className="min-h-[320px]" />
+ * ```
+ */
+export function DocumentEditor(props: NotisDocumentEditorProps): ReactElement {
+  const runtime = useNotisRuntime();
+  const HostEditor = runtime?.ui?.DocumentEditor;
+  if (HostEditor) {
+    return <HostEditor {...props} />;
+  }
+  return <DocumentEditorFallback {...props} />;
+}

package/template/packages/sdk/src/components/Markdown.tsx

@@ -0,0 +1,60 @@
+'use client';
+
+import type { AnchorHTMLAttributes, ReactElement } from 'react';
+import ReactMarkdown, { type Components } from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+
+export interface MarkdownProps {
+  /** Markdown source to render. */
+  value: string;
+  /** Typography scale. 'sm' suits dense surfaces (cards, list rows). */
+  size?: 'sm' | 'base';
+  className?: string;
+  /** Per-element overrides, passed through to react-markdown. */
+  components?: Components;
+}
+
+function MarkdownLink({
+  href,
+  children,
+  node: _node,
+  ...rest
+}: AnchorHTMLAttributes<HTMLAnchorElement> & { node?: unknown }) {
+  const isExternal = typeof href === 'string' && /^https?:\/\//i.test(href);
+  return (
+    <a
+      href={href}
+      {...(isExternal ? { target: '_blank', rel: 'noreferrer noopener' } : {})}
+      {...rest}
+    >
+      {children}
+    </a>
+  );
+}
+
+const defaultComponents: Components = {
+  a: MarkdownLink,
+};
+
+/**
+ * Renders a markdown value with Notis typography. Markdown is a value type:
+ * use this anywhere markdown appears — document content, database fields,
+ * generated text. Styling comes from `.notis-markdown` rules in the SDK
+ * stylesheet and follows the portal theme variables.
+ */
+export function Markdown({ value, size = 'base', className, components }: MarkdownProps): ReactElement {
+  const classes = ['notis-markdown', size === 'sm' ? 'notis-markdown--sm' : null, className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <div className={classes}>
+      <ReactMarkdown
+        remarkPlugins={[remarkGfm]}
+        components={components ? { ...defaultComponents, ...components } : defaultComponents}
+      >
+        {value}
+      </ReactMarkdown>
+    </div>
+  );
+}

package/template/packages/sdk/src/components/MultiSelectActionBar.tsx

@@ -73,7 +73,12 @@ function shortcutMatches(shortcut: ParsedShortcut, event: KeyboardEvent): boolea
   return true;
 }
 
-function isEditableTarget(target: EventTarget | null): boolean {
+function isEditableEvent(event: Event): boolean {
+  // Notis apps mount inside a Shadow DOM, so a document-level listener sees
+  // `event.target` retargeted to the shadow host. `composedPath()[0]` pierces
+  // the shadow boundary to the real focused element, so action-bar shortcuts
+  // don't fire while the user is typing in an app input.
+  const target = event.composedPath?.()[0] ?? event.target;
   if (!(target instanceof HTMLElement)) return false;
   if (target.isContentEditable) return true;
   const tag = target.tagName;
@@ -193,7 +198,7 @@ export function MultiSelectActionBar({
     if (selectedCount === 0 || parsedShortcuts.length === 0) return;
 
     const handleKeyDown = (event: KeyboardEvent) => {
-      if (isEditableTarget(event.target)) return;
+      if (isEditableEvent(event)) return;
       for (const { action, parsed } of parsedShortcuts) {
         if (shortcutMatches(parsed, event)) {
           event.preventDefault();

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

@@ -52,13 +52,87 @@ export interface NotisRouteConfig {
   };
 }
 
+export const NOTIS_APP_CATEGORIES = [
+  'Productivity',
+  'Sales & Marketing',
+  'Operations',
+  'Product & Engineering',
+  'Personal',
+] as const;
+
+export type NotisAppCategory = typeof NOTIS_APP_CATEGORIES[number];
+
+export interface NotisAppAuthor {
+  name: string;
+  handle?: string;
+  url?: string;
+}
+
+export interface NotisAppSkillConfig {
+  key: string;
+  path: string;
+  name: string;
+  description?: string;
+}
+
+export interface NotisAppOnboardingConfig {
+  skill: string;
+  prompt: string;
+}
+
+export interface NotisAppScreenshotConfig {
+  path: string;
+  alt: string;
+  route?: string;
+  scenario?: string;
+  focus?: string;
+  theme?: 'light' | 'dark';
+}
+
+/**
+ * Named accent tokens for an app's avatar. Keep in sync with the portal
+ * `ACCENT_NAMES` and the server `ACCENT_TOKENS`.
+ */
+export const NOTIS_APP_ACCENTS = [
+  'blue',
+  'violet',
+  'emerald',
+  'amber',
+  'rose',
+  'sky',
+  'fuchsia',
+  'teal',
+] as const;
+
+export type NotisAppAccent = typeof NOTIS_APP_ACCENTS[number];
+
 export interface NotisAppConfig {
+  /** URL-safe app slug. Existing apps may still use a display name here. */
   name: string;
+  /** Human display title, Raycast-style. Falls back to `name`. */
+  title?: string;
   description?: string;
+  /**
+   * App icon. A `phosphor:<name>` value (e.g. `phosphor:dice-five`) or
+   * `metadata/icon.png`. When unset, the app shows its two-letter initials.
+   */
   icon?: string;
+  /**
+   * Optional accent color for the app avatar. One of {@link NOTIS_APP_ACCENTS}.
+   * When unset, a stable accent is derived automatically from the app id.
+   */
+  accent?: NotisAppAccent;
+  author?: NotisAppAuthor;
+  categories?: NotisAppCategory[];
+  tagline?: string;
+  /** @deprecated Add release entries to the root CHANGELOG.md instead. */
+  versionNotes?: string;
+  screenshots?: NotisAppScreenshotConfig[];
   databases?: string[];
   routes?: NotisRouteConfig[];
   tools?: string[];
+  skills?: NotisAppSkillConfig[];
+  onboarding?: NotisAppOnboardingConfig;
 }
 
 /**

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

@@ -0,0 +1,229 @@
+/**
+ * Document data helpers: normalize raw tool results (Notion-shaped property
+ * values, snake_case fields) into the SDK's `DocumentRecord`/`DatabaseProperty`
+ * shapes, and derive plain-text projections from typed content.
+ *
+ * These are pure functions — safe in any context (portal, dev harness, tests).
+ */
+
+import type {
+  DatabaseProperty,
+  DatabasePropertyOption,
+  DatabasePropertyType,
+  DocumentContentType,
+  DocumentRecord,
+} from './runtime';
+
+// ---------------------------------------------------------------------------
+// Value primitives
+// ---------------------------------------------------------------------------
+
+export function isPresentString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+export function optionalString(value: unknown): string | null {
+  return isPresentString(value) ? value.trim() : null;
+}
+
+/** Flattens a Notion-shaped rich_text array (or plain string) to text. */
+export function extractRichText(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (!Array.isArray(value)) return '';
+  return value
+    .map((item) => {
+      const record = asRecord(item);
+      const text = asRecord(record?.text);
+      return optionalString(text?.content) ?? optionalString(record?.plain_text) ?? '';
+    })
+    .join('');
+}
+
+/** Extracts the ids of a normalized relation property value. */
+export function getRelationIds(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => isPresentString(item));
+}
+
+// ---------------------------------------------------------------------------
+// Property + document normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Collapses a Notion-shaped property value ({type: 'select', select: {...}})
+ * into a plain JS value (string, string[], number, boolean, ...). Values that
+ * are already plain pass through unchanged.
+ */
+export function normalizePropertyValue(value: unknown): unknown {
+  const record = asRecord(value);
+  if (!record) return value;
+
+  const type = optionalString(record.type);
+  if (!type) return value;
+
+  if (type === 'title') return extractRichText(record.title);
+  if (type === 'rich_text') return extractRichText(record.rich_text);
+  if (type === 'select' || type === 'status') {
+    return optionalString(asRecord(record[type])?.name) ?? record[type] ?? null;
+  }
+  if (type === 'multi_select') {
+    const items = Array.isArray(record.multi_select) ? record.multi_select : [];
+    return items.map((item) => optionalString(asRecord(item)?.name) ?? item).filter(Boolean);
+  }
+  if (type === 'relation') {
+    const items = Array.isArray(record.relation) ? record.relation : [];
+    return items.map((item) => optionalString(asRecord(item)?.id) ?? item).filter(Boolean);
+  }
+  if (type === 'date') return optionalString(asRecord(record.date)?.start) ?? record.date ?? null;
+  if (type in record) return record[type];
+  return value;
+}
+
+function normalizeContentType(value: unknown): DocumentContentType | null {
+  return value === 'markdown' || value === 'file' ? value : null;
+}
+
+/**
+ * Normalizes a raw document from a Notis database tool result
+ * (LOCAL_NOTIS_DATABASE_QUERY / GET_DOCUMENT / UPSERT_*) into a
+ * `DocumentRecord`: camelCases fields and collapses property values.
+ */
+export function normalizeDocumentRecord(value: unknown): DocumentRecord {
+  const record = asRecord(value) ?? {};
+  const rawProperties = asRecord(record.properties) ?? {};
+  const properties: Record<string, unknown> = {};
+  for (const [key, propertyValue] of Object.entries(rawProperties)) {
+    properties[key] = normalizePropertyValue(propertyValue);
+  }
+
+  return {
+    id: optionalString(record.id) ?? '',
+    title: optionalString(record.title) ?? 'Untitled',
+    url: optionalString(record.url),
+    properties,
+    icon: optionalString(record.icon),
+    cover: optionalString(record.cover),
+    databaseSlug: optionalString(record.databaseSlug) ?? optionalString(record.database_slug) ?? undefined,
+    contentType: normalizeContentType(record.contentType ?? record.content_type),
+    fileType: optionalString(record.fileType) ?? optionalString(record.file_type),
+    contentBlocknote: Array.isArray(record.contentBlocknote)
+      ? (record.contentBlocknote as Array<Record<string, unknown>>)
+      : Array.isArray(record.content_blocknote)
+        ? (record.content_blocknote as Array<Record<string, unknown>>)
+        : null,
+    contentMarkdown: optionalString(record.contentMarkdown) ?? optionalString(record.content_markdown),
+    plainText: optionalString(record.plainText) ?? optionalString(record.plain_text),
+    createdAt:
+      optionalString(record.createdAt)
+      ?? optionalString(record.created_at)
+      ?? optionalString(record.created_time),
+    lastEditedTime:
+      optionalString(record.lastEditedTime)
+      ?? optionalString(record.last_edited_time)
+      ?? optionalString(record.updated_at),
+  };
+}
+
+/** Normalizes a raw schema property from LOCAL_NOTIS_DATABASE_GET_DATABASE. */
+export function normalizeDatabaseProperty(value: unknown): DatabaseProperty | null {
+  const record = asRecord(value);
+  const name = optionalString(record?.name);
+  if (!record || !name) return null;
+
+  const rawOptions = Array.isArray(record.options) ? record.options : [];
+  const options = rawOptions.flatMap((option): DatabasePropertyOption[] => {
+    const optionRecord = asRecord(option);
+    const optionName = optionalString(optionRecord?.name);
+    if (!optionRecord || !optionName) return [];
+    return [{
+      id: optionalString(optionRecord.id),
+      name: optionName,
+      color: optionalString(optionRecord.color),
+      order: typeof optionRecord.order === 'number' ? optionRecord.order : undefined,
+    }];
+  });
+
+  return {
+    id: optionalString(record.id),
+    name,
+    type: (optionalString(record.type) ?? 'rich_text') as DatabasePropertyType,
+    description: optionalString(record.description),
+    options,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Plain-text projections
+// ---------------------------------------------------------------------------
+
+/** Strips markdown syntax to readable plain text (previews, search). */
+export function markdownToPlainText(markdown: string): string {
+  return markdown
+    // fenced code blocks: keep the code, drop the fences
+    .replace(/```[^\n]*\n?/g, '')
+    // images: keep alt text
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+    // links: keep link text
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    // html tags
+    .replace(/<[^>]+>/g, ' ')
+    // headings, blockquotes, list markers, task boxes
+    .replace(/^\s{0,3}(#{1,6}\s+|>\s?|[-*+]\s+(\[[ xX]\]\s+)?|\d+\.\s+)/gm, '')
+    // emphasis / strikethrough / inline code
+    .replace(/(\*\*|__|[*_~`])/g, '')
+    // table separators and pipes
+    .replace(/^\s*\|?[-:| ]+\|?\s*$/gm, '')
+    .replace(/\|/g, ' ')
+    // horizontal rules
+    .replace(/^\s*([-*_]\s*){3,}$/gm, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** Flattens BlockNote block JSON to plain text. */
+export function blockNoteToPlainText(blocks: unknown): string {
+  const segments: string[] = [];
+
+  function visit(node: unknown): void {
+    if (typeof node === 'string') {
+      if (node.trim()) segments.push(node.trim());
+      return;
+    }
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    const record = asRecord(node);
+    if (!record) return;
+    if (typeof record.text === 'string' && record.text.trim()) {
+      segments.push(record.text.trim());
+    }
+    visit(record.content);
+    visit(record.children);
+  }
+
+  visit(blocks);
+  return segments.join(' ').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Best-available plain-text preview for a document:
+ * plainText -> contentMarkdown -> contentBlocknote -> title.
+ */
+export function getDocumentPreview(document: DocumentRecord): string {
+  if (isPresentString(document.plainText)) {
+    return document.plainText.replace(/\s+/g, ' ').trim();
+  }
+  if (isPresentString(document.contentMarkdown)) {
+    return markdownToPlainText(document.contentMarkdown);
+  }
+  const fromBlocks = blockNoteToPlainText(document.contentBlocknote);
+  if (fromBlocks) return fromBlocks;
+  return isPresentString(document.title) ? document.title : 'Untitled';
+}

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

@@ -0,0 +1,85 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { normalizeDatabaseProperty, optionalString } from '../documents';
+import type { DatabaseProperty } from '../runtime';
+
+interface GetDatabaseResult {
+  database?: {
+    name?: string;
+    description?: string | null;
+    schema?: {
+      properties?: unknown[];
+    };
+  };
+  message?: string;
+  error?: string;
+}
+
+export interface UseDatabaseSchemaResult {
+  name: string | null;
+  description: string | null;
+  properties: DatabaseProperty[];
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/** Fetch a database's schema (normalized properties + metadata). */
+export function useDatabaseSchema(databaseSlug: string): UseDatabaseSchemaResult {
+  const runtime = useNotisRuntime();
+  const [name, setName] = useState<string | null>(null);
+  const [description, setDescription] = useState<string | null>(null);
+  const [properties, setProperties] = useState<DatabaseProperty[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const refetch = useCallback(() => {
+    setFetchKey((key) => key + 1);
+  }, []);
+
+  useEffect(() => {
+    if (!runtime) {
+      setLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+
+    runtime
+      .callTool<GetDatabaseResult>('LOCAL_NOTIS_DATABASE_GET_DATABASE', {
+        database_slug: databaseSlug,
+      })
+      .then((result) => {
+        if (cancelled) return;
+        const message = result.error ?? result.message;
+        if (!result.database && message) {
+          throw new Error(message);
+        }
+        setName(optionalString(result.database?.name));
+        setDescription(optionalString(result.database?.description));
+        const rawProperties = result.database?.schema?.properties ?? [];
+        setProperties(
+          rawProperties
+            .map(normalizeDatabaseProperty)
+            .filter((property): property is DatabaseProperty => Boolean(property)),
+        );
+        setLoading(false);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [runtime, databaseSlug, fetchKey]);
+
+  return { name, description, properties, loading, error, refetch };
+}

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

@@ -0,0 +1,78 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { normalizeDocumentRecord } from '../documents';
+import type { DocumentRecord } from '../runtime';
+
+interface GetDocumentResult {
+  status?: string;
+  document?: unknown;
+  message?: string;
+  error?: string;
+}
+
+export interface UseDocumentOptions {
+  enabled?: boolean;
+}
+
+export interface UseDocumentResult {
+  document: DocumentRecord | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+/** Fetch a single document (with content) by id, normalized. */
+export function useDocument(
+  documentId: string | null | undefined,
+  options: UseDocumentOptions = {},
+): UseDocumentResult {
+  const runtime = useNotisRuntime();
+  const [document, setDocument] = useState<DocumentRecord | null>(null);
+  const [loading, setLoading] = useState(Boolean(documentId));
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const enabled = options.enabled !== false && Boolean(documentId);
+
+  const refetch = useCallback(() => {
+    setFetchKey((key) => key + 1);
+  }, []);
+
+  useEffect(() => {
+    if (!runtime || !enabled || !documentId) {
+      setDocument(null);
+      setLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+
+    runtime
+      .callTool<GetDocumentResult>('LOCAL_NOTIS_DATABASE_GET_DOCUMENT', {
+        document_id: documentId,
+      })
+      .then((result) => {
+        if (cancelled) return;
+        if (!result.document) {
+          throw new Error(result.error ?? result.message ?? 'Document not found');
+        }
+        setDocument(normalizeDocumentRecord(result.document));
+        setLoading(false);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [runtime, documentId, enabled, fetchKey]);
+
+  return { document, loading, error, refetch };
+}