@notis_ai/cli 0.2.0-beta.16.1 → 0.2.0-beta.160.1

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

@@ -0,0 +1,451 @@
+import type { AgentContextContent, AgentContextItem, AgentContextSource } from './agentContext';
+/**
+ * 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.
+ */
+
+import type { ComponentType } from 'react';
+import type { NotisQueryClient } from './queryCache';
+
+// ---------------------------------------------------------------------------
+// Database types
+// ---------------------------------------------------------------------------
+
+export type DatabasePropertyType =
+  | 'title'
+  | 'rich_text'
+  | 'text'
+  | 'number'
+  | 'checkbox'
+  | 'date'
+  | 'select'
+  | 'multi_select'
+  | 'status'
+  | 'relation'
+  | 'formula'
+  | 'files'
+  | 'secret';
+
+/**
+ * The value of a `secret` property. The platform stores a pointer to a
+ * credential held elsewhere and never the credential itself, so there is
+ * deliberately nothing here to read the secret material from — only whether
+ * one is attached, which credential it is, and its lifecycle state.
+ */
+export interface SecretPropertyValue {
+  present: boolean;
+  reference: string | null;
+  status: string | null;
+  metadata: Record<string, unknown> | null;
+}
+
+export interface DatabasePropertyOption {
+  id?: string | null;
+  name: string;
+  color?: string | null;
+  order?: number;
+}
+
+export interface DatabaseProperty {
+  id?: string | null;
+  name: string;
+  type: DatabasePropertyType;
+  description?: string | null;
+  options?: DatabasePropertyOption[];
+}
+
+export interface DatabaseDescriptor {
+  slug: string;
+  title: string;
+  description?: string | null;
+  icon?: string | null;
+  properties: DatabaseProperty[];
+}
+
+/**
+ * A document's content is typed. `markdown` documents carry rich text as
+ * BlockNote JSON (canonical) with a derived markdown projection; `file`
+ * documents carry an uploaded file whose format is in `fileType`
+ * (pdf, xlsx, pptx, ...). Future content types (canvas, ...) extend this
+ * union without changing the component contracts.
+ */
+export type DocumentContentType = 'markdown' | 'file' | 'view';
+
+export interface DocumentRecord {
+  id: string;
+  title: string;
+  properties: Record<string, unknown>;
+  url?: string | null;
+  icon?: string | null;
+  cover?: string | null;
+  databaseSlug?: string;
+  contentType?: DocumentContentType | null;
+  fileType?: string | null;
+  contentBlocknote?: Array<Record<string, unknown>> | null;
+  contentMarkdown?: string | null;
+  plainText?: string | null;
+  viewType?: string | null;
+  viewState?: Record<string, unknown> | null;
+  viewRevision?: number | null;
+  createdAt?: string | null;
+  lastEditedTime?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Tool types
+// ---------------------------------------------------------------------------
+
+export type ToolInputSchema = Record<string, unknown>;
+
+export interface ToolDescriptor {
+  name: string;
+  description?: string;
+  inputSchema?: ToolInputSchema;
+}
+
+export interface ToolCallOptions {
+  /** Explicitly identifies an idempotent read; never set on a mutation. */
+  readOnly?: boolean;
+  /**
+   * Coalesce an identical in-flight call. Only opt in for idempotent reads;
+   * mutations must execute once per invocation.
+   */
+  dedupe?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Route types
+// ---------------------------------------------------------------------------
+
+export interface RouteDescriptor {
+  slug: string;
+  path: string;
+  name: string;
+  icon?: string | null;
+  parentSlug?: string | null;
+  default?: boolean;
+  resourceDeepLinks?: 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;
+    type?: string;
+    value: unknown;
+  }>;
+  sorts?: Array<{
+    property: string;
+    direction: 'asc' | 'desc';
+  }>;
+  page_size?: number;
+}
+
+export interface NotisRuntimeContext {
+  collectionItem?: CollectionItemDetail | null;
+  /** App-owned resource requested through the route's `?resource=<id>` link. */
+  resourceId?: string | null;
+  /**
+   * Set when the app is being rendered by the screenshot harness (`notis apps
+   * screenshot`) for the named listing scenario. Lets apps and SDK components
+   * hide dev-only chrome from listing images.
+   */
+  screenshotScenario?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// App context shared with Notis
+// ---------------------------------------------------------------------------
+
+export type ContextAttributeValue = string | number | boolean | null;
+
+/**
+ * The specific thing currently in focus inside an app view. The host stamps
+ * app/view provenance onto this value before it reaches chat, so apps only
+ * describe their own resource rather than impersonating another surface.
+ */
+export interface ContextResource extends AgentContextContent {
+  additionalContext?: Record<string, unknown>;
+  id: string;
+  kind: string;
+  label: string;
+  url?: string | null;
+  revision?: string | null;
+  attributes?: Record<string, ContextAttributeValue>;
+  snapshot?: {
+    format: 'text' | 'markdown';
+    content: string;
+  } | null;
+}
+
+/** A quote copied from an app, kept separate from the user's prompt. */
+export interface ContextSelection extends AgentContextContent {
+  source?: AgentContextSource;
+  id: string;
+  text: string;
+  resource?: ContextResource | null;
+}
+
+// ---------------------------------------------------------------------------
+// Host-provided UI
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for the host-provided document editor. The host implementation
+ * dispatches on the document's content type (markdown -> rich text editor,
+ * file -> matching viewer/editor), so this contract stays stable as new
+ * content types ship.
+ */
+export interface NotisDocumentEditorProps {
+  documentId: string;
+  /** 'full' renders icon/title/cover above the content; 'body' renders content only. */
+  variant?: 'full' | 'body';
+  readOnly?: boolean;
+  className?: string;
+  onDirtyChange?: (dirty: boolean) => void;
+  onSavingChange?: (saving: boolean) => void;
+}
+
+export interface NotisMarkdownEditorSavePayload {
+  markdown: string;
+  expectedRevision?: string | null;
+}
+
+export interface NotisMarkdownEditorSaveResult {
+  revision?: string | null;
+}
+
+/**
+ * Storage-neutral host markdown editor. The app owns persistence through
+ * `onSave`; the host only supplies Notis' editing experience.
+ */
+export interface NotisMarkdownEditorProps {
+  /** Stable identity of the edited resource. Changing it starts a fresh editor. */
+  resourceKey?: string;
+  value: string;
+  revision?: string | null;
+  readOnly?: boolean;
+  autosaveMs?: number;
+  placeholder?: string;
+  className?: string;
+  onChange?: (markdown: string) => void;
+  /** Persist an uploaded media/file block and return its durable URL. */
+  onUploadFile?: (file: File) => Promise<string>;
+  onSave?: (
+    payload: NotisMarkdownEditorSavePayload,
+  ) => Promise<NotisMarkdownEditorSaveResult | void>;
+  onDirtyChange?: (dirty: boolean) => void;
+  onSavingChange?: (saving: boolean) => void;
+}
+
+/**
+ * Components the host (portal) injects through the runtime. Apps consume them
+ * via the SDK wrappers (e.g. `DocumentEditor`), which fall back gracefully
+ * when a host component is unavailable (standalone dev harness, snapshots).
+ */
+export interface NotisRuntimeUI {
+  DocumentEditor?: ComponentType<NotisDocumentEditorProps>;
+  MarkdownEditor?: ComponentType<NotisMarkdownEditorProps>;
+}
+
+// ---------------------------------------------------------------------------
+// NotisRuntime
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for `NotisRuntime.subscribeDatabase`.
+ */
+export interface SubscribeDatabaseOptions {
+  /**
+   * Called with `true` once a live change feed is attached, and with `false`
+   * when it drops or is torn down. Hosts without a change feed (dev harness,
+   * screenshot stub, vite preview) never call it, so `live` stays false there.
+   */
+  onStatusChange?: (live: boolean) => void;
+}
+
+/**
+ * Work an app hands to the Notis manager chat through `NotisRuntime.handover`.
+ */
+export interface HandoverPayload {
+  /** Optional starter message. Omit it to open a context-only composer. */
+  prompt?: string;
+  /**
+   * Key of a skill declared in `notis.config.ts` -> `skills[].key`. The host
+   * rejects a key this app does not declare. Omit to hand over plain work.
+   */
+  skill?: string;
+  /**
+   * Accepted for forward compatibility. The portal never submits a composer on
+   * the user's behalf today, so every handover resolves `drafted`; `sent` is
+   * reserved for a host that can genuinely dispatch the run.
+   */
+  autoSend?: boolean;
+}
+
+export interface HandoverResult {
+  /** `drafted` when the user still has to press send, `sent` when it went straight through. */
+  status: 'drafted' | 'sent';
+}
+
+/**
+ * The user's cloud computer, as far as an app may see it.
+ *
+ * `exists` is false when the user has never had a sandbox provisioned. A
+ * `status` of anything other than `'running'` means the VM is asleep; reading
+ * these facts never wakes it.
+ */
+export interface CloudComputerSandboxFacts {
+  exists: boolean;
+  status: string | null;
+  provider: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+/**
+ * Whether a CLI inside the cloud computer is signed in.
+ *
+ * `authenticated: null` means *unknown*, never *signed out*: the sandbox was
+ * not running, or the probe could not answer. `reason` says which
+ * (`'sandbox_not_running'`, `'no_sandbox'`, `'sandbox_status_unknown'`,
+ * `'probe_failed'`, `'not_signed_in'`).
+ */
+export interface CloudComputerCliAuthFacts {
+  authenticated: boolean | null;
+  account: string | null;
+  checked_at: string | null;
+  reason: string | null;
+}
+
+export interface CloudComputerFacts {
+  /**
+   * False when this host cannot answer at all — no cloud computer on the user's
+   * plan, or the platform could not resolve the facts. Render whatever the app
+   * did before rather than an error.
+   */
+  available: boolean;
+  reason?: string | null;
+  sandbox: CloudComputerSandboxFacts | null;
+  cli_auth: { gh: CloudComputerCliAuthFacts };
+}
+
+export interface NotisRuntime {
+  /** Optional host-scoped in-memory read cache. Older hosts remain supported. */
+  queryClient?: NotisQueryClient;
+  app: AppDescriptor;
+  route: RouteDescriptor;
+  databases: DatabaseDescriptor[];
+  context: NotisRuntimeContext;
+  ui?: NotisRuntimeUI;
+
+  /** Publish or clear the focused resource inside the current app view. */
+  contextSource?: AgentContextSource;
+  publishActiveResource?(resource: ContextResource | null): void;
+
+  /** Remember a copied quote so the host can recover it across iframe paste. */
+  captureContextSelection?(selection: ContextSelection): void;
+  addContext?(item: AgentContextItem): Promise<boolean>;
+  updateContext?(item: AgentContextItem): Promise<boolean>;
+  removeContext?(id: string): Promise<boolean>;
+
+  /**
+   * Subscribe to changes on an app-owned database. Returns an unsubscribe.
+   *
+   * The change notification is only a signal — it carries no rows. Consumers
+   * react by refetching through the normal tool path, so app scoping,
+   * permissions and billing are unchanged. Use the `useDatabaseSubscription`
+   * hook rather than calling this directly.
+   */
+  subscribeDatabase?(
+    slug: string,
+    onChange: () => void,
+    options?: SubscribeDatabaseOptions,
+  ): () => void;
+
+  /**
+   * Hand a piece of work to the Notis manager chat. The app cannot run an
+   * agent itself: it describes the job, and the manager surface owns progress,
+   * billing, cancellation and the transcript. Results come back to the app
+   * through its own databases (see `useDatabaseSubscription`).
+   *
+   * Use the `useHandover` hook rather than calling this directly. Hosts
+   * without a manager chat (the dev harness, the vite preview) leave it
+   * undefined, so keep whatever fallback the app already offers.
+   */
+  handover?(payload: HandoverPayload): Promise<HandoverResult>;
+
+  /**
+   * Read-only facts about the user's cloud computer. Requires
+   * `capabilities.cloudComputer: 'read'` in `notis.config.ts` plus the user's
+   * approval; resolving it never creates, resumes or commands a sandbox.
+   *
+   * Use the `useCloudComputer` hook rather than calling this directly. Hosts
+   * without a cloud computer (the dev harness, the vite preview) answer
+   * `{ available: false }`, so keep whatever fallback the app already has.
+   * `{ refresh: true }` bypasses the host's short answer cache — the hook's
+   * refresh() sends it so a just-completed sign-in becomes visible.
+   */
+  cloudComputerFacts?(options?: { refresh?: boolean }): Promise<CloudComputerFacts>;
+
+  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>,
+    options?: ToolCallOptions,
+  ): 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,213 @@
+/**
+ * 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;
+  }
+
+  /* Flat panel. No border, no shadow: the design bar allows a single hairline
+   * between sections and nothing around items. */
+  .notis-app-surface {
+    @apply rounded-2xl bg-muted text-card-foreground;
+  }
+
+  /* List rows: hover and selection are carried by background tint only. Rows
+   * read as tinted panels on mobile and as transparent rows on desktop. */
+  .list-row {
+    @apply rounded-xl bg-muted px-4 py-3 transition-colors lg:bg-transparent lg:hover:bg-muted/60;
+  }
+
+  .list-row-selected {
+    @apply bg-primary/[0.06] lg:bg-primary/[0.06] lg:hover:bg-primary/[0.06];
+  }
+
+  /* Split (list + detail) pages are full-bleed: use these instead of
+   * .notis-app-shell. The list pane is tinted and carries the one allowed
+   * hairline; the detail pane sits on the plain background. */
+  .notis-app-split {
+    @apply flex h-full min-h-0 w-full max-w-none flex-col lg:flex-row;
+  }
+
+  .notis-app-pane-list {
+    @apply w-full shrink-0 bg-muted/40 lg:w-80 lg:border-r lg:border-border xl:w-96;
+  }
+
+  .notis-app-pane-detail {
+    @apply min-w-0 flex-1 bg-background;
+  }
+
+  .notis-app-section {
+    @apply p-5 md:p-6;
+  }
+}
+
+/*
+ * Markdown value-type rendering (see the `Markdown` component). Plain CSS on
+ * theme variables so it works inside the portal shadow root and the dev
+ * harness without depending on the app's Tailwind content scan.
+ */
+.notis-markdown {
+  font-size: 14px;
+  line-height: 1.65;
+  color: hsl(var(--foreground));
+  overflow-wrap: break-word;
+}
+
+.notis-markdown--sm {
+  font-size: 13px;
+  line-height: 1.55;
+}
+
+.notis-markdown > :first-child {
+  margin-top: 0;
+}
+
+.notis-markdown > :last-child {
+  margin-bottom: 0;
+}
+
+.notis-markdown p {
+  margin: 0.625em 0;
+}
+
+.notis-markdown h1,
+.notis-markdown h2,
+.notis-markdown h3,
+.notis-markdown h4,
+.notis-markdown h5,
+.notis-markdown h6 {
+  margin: 1.25em 0 0.5em;
+  font-weight: 650;
+  letter-spacing: -0.01em;
+  line-height: 1.3;
+  color: hsl(var(--foreground));
+}
+
+.notis-markdown h1 { font-size: 1.5em; }
+.notis-markdown h2 { font-size: 1.25em; }
+.notis-markdown h3 { font-size: 1.1em; }
+.notis-markdown h4,
+.notis-markdown h5,
+.notis-markdown h6 { font-size: 1em; }
+
+.notis-markdown ul,
+.notis-markdown ol {
+  margin: 0.625em 0;
+  padding-left: 1.5em;
+}
+
+.notis-markdown ul { list-style-type: disc; }
+.notis-markdown ol { list-style-type: decimal; }
+
+.notis-markdown li {
+  margin: 0.25em 0;
+}
+
+.notis-markdown li > ul,
+.notis-markdown li > ol {
+  margin: 0.25em 0;
+}
+
+.notis-markdown ul.contains-task-list {
+  list-style: none;
+  padding-left: 0.375em;
+}
+
+.notis-markdown li.task-list-item input[type='checkbox'] {
+  margin-right: 0.5em;
+  accent-color: hsl(var(--primary));
+}
+
+.notis-markdown blockquote {
+  margin: 0.75em 0;
+  padding: 0.125em 0 0.125em 0.875em;
+  border-left: 3px solid hsl(var(--border));
+  color: hsl(var(--muted-foreground));
+}
+
+.notis-markdown a {
+  color: hsl(var(--primary));
+  text-decoration: underline;
+  text-decoration-color: hsl(var(--primary) / 0.35);
+  text-underline-offset: 2px;
+}
+
+.notis-markdown a:hover {
+  text-decoration-color: hsl(var(--primary));
+}
+
+.notis-markdown code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.875em;
+  padding: 0.125em 0.375em;
+  border-radius: 0.25rem;
+  background: hsl(var(--muted));
+  color: hsl(var(--foreground));
+}
+
+.notis-markdown pre {
+  margin: 0.75em 0;
+  padding: 0.75em 1em;
+  border-radius: 0.5rem;
+  background: hsl(var(--muted));
+  overflow-x: auto;
+}
+
+.notis-markdown pre code {
+  padding: 0;
+  background: transparent;
+  font-size: 0.875em;
+}
+
+.notis-markdown hr {
+  margin: 1.25em 0;
+  border: 0;
+  border-top: 1px solid hsl(var(--border));
+}
+
+.notis-markdown img {
+  max-width: 100%;
+  border-radius: 0.5rem;
+}
+
+.notis-markdown table {
+  margin: 0.75em 0;
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.95em;
+}
+
+.notis-markdown th,
+.notis-markdown td {
+  padding: 0.375em 0.75em;
+  border: 1px solid hsl(var(--border));
+  text-align: left;
+}
+
+.notis-markdown th {
+  background: hsl(var(--muted));
+  font-weight: 600;
+}