@notis_ai/cli 0.2.0-beta.139.1 → 0.2.0-beta.145.1

package/src/runtime/output.js

@@ -108,6 +108,13 @@ export class OutputManager {
     process.stderr.write(`${message}\n`);
   }
 
+  notice(message) {
+    // Some pre-result instructions are required to make progress. They belong
+    // on stderr so stdout stays one valid machine envelope, but unlike ordinary
+    // table notes they must remain visible in JSON/YAML/NDJSON modes.
+    process.stderr.write(`${message}\n`);
+  }
+
   emitProgress({ phase, message, requestId = null }) {
     if (this.runtime.quiet) {
       return;

package/src/runtime/ports.js

@@ -1,5 +1,21 @@
 import { createServer } from 'node:http';
 
+export async function getAvailablePortPreferring(preferredPort) {
+  if (Number.isInteger(preferredPort) && preferredPort > 0 && preferredPort <= 65535) {
+    const preferredIsFree = await new Promise((resolvePromise) => {
+      const server = createServer();
+      server.once('error', () => resolvePromise(false));
+      server.listen(preferredPort, '127.0.0.1', () => {
+        server.close(() => resolvePromise(true));
+      });
+    });
+    if (preferredIsFree) {
+      return preferredPort;
+    }
+  }
+  return getAvailablePort();
+}
+
 export async function getAvailablePort() {
   const server = createServer();
   await new Promise((resolvePromise, rejectPromise) => {

package/src/runtime/profiles.js

@@ -267,10 +267,6 @@ export function resolveWorktreeRuntime(startDir = process.cwd()) {
   const profile = typeof runtime?.profile === 'string' ? runtime.profile.trim() : '';
   const devAccessToken =
     typeof runtime?.dev_access_token === 'string' ? runtime.dev_access_token.trim() : '';
-  const appDevSessionsFile =
-    typeof runtime?.app_dev_sessions_file === 'string' && runtime.app_dev_sessions_file.trim()
-      ? runtime.app_dev_sessions_file.trim()
-      : join(dirname(runtimePath), 'app-dev-sessions.json');
   const desktopDeepLinkScheme =
     typeof runtime?.desktop_deep_link_scheme === 'string'
       ? runtime.desktop_deep_link_scheme.trim()
@@ -306,7 +302,6 @@ export function resolveWorktreeRuntime(startDir = process.cwd()) {
     api_base: apiBase,
     profile,
     dev_access_token: devAccessToken,
-    app_dev_sessions_file: resolve(dirname(runtimePath), appDevSessionsFile),
     desktop_deep_link_scheme: desktopDeepLinkScheme || undefined,
     runtime_path: runtimePath,
     routing_path: routingPath,

package/template/app/layout.tsx

@@ -1,6 +1,10 @@
 import '@notis/sdk/styles.css';
+import { ShortcutProvider } from '@notis/sdk/interactions';
 import './globals.css';
 
 export default function AppShell({ children }: { children: React.ReactNode }) {
-  return children;
+  // NotisProvider supplies this in the product host. Keeping the shell-level
+  // provider makes the same scope arbitration available in the local harness;
+  // ShortcutProvider is nesting-safe, so the hosted app still has one registry.
+  return <ShortcutProvider>{children}</ShortcutProvider>;
 }

package/template/notis.config.ts

@@ -2,6 +2,7 @@ import { defineNotisApp } from '@notis/sdk/config';
 
 export default defineNotisApp({
   name: 'my-notis-app',
+  devSlug: 'my-notis-app',
   title: 'My Notis App',
   description: 'A focused Notis app with one route and one database-backed workflow.',
   icon: 'phosphor:squares-four',

package/template/packages/sdk/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@notis/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./interactions": "./src/interactions.ts",
     "./config": "./src/config.ts",
     "./vite": "./src/vite.ts",
     "./ui": "./src/ui.ts",

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

@@ -0,0 +1,121 @@
+import type { ChangeEvent, KeyboardEvent, ReactElement } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { NotisMarkdownEditorProps } from '../runtime';
+
+function MarkdownEditorFallback({
+  value,
+  revision,
+  readOnly,
+  autosaveMs = 1500,
+  placeholder = 'Write in Markdown…',
+  className,
+  onChange,
+  onSave,
+  onDirtyChange,
+  onSavingChange,
+}: NotisMarkdownEditorProps) {
+  const [draft, setDraft] = useState(value);
+  const [saveAttempt, setSaveAttempt] = useState(0);
+  const draftRef = useRef(value);
+  const dirtyRef = useRef(false);
+  const savingRef = useRef(false);
+  const revisionRef = useRef(revision);
+  const onSaveRef = useRef(onSave);
+  const readOnlyRef = useRef(readOnly);
+  const unmountedRef = useRef(false);
+  const saveRef = useRef<() => Promise<void>>(async () => undefined);
+
+  useEffect(() => {
+    onSaveRef.current = onSave;
+    readOnlyRef.current = readOnly;
+  }, [onSave, readOnly]);
+
+  useEffect(() => {
+    if (dirtyRef.current) return;
+    draftRef.current = value;
+    revisionRef.current = revision;
+    setDraft(value);
+  }, [revision, value]);
+
+  const save = useCallback(async () => {
+    if (!onSave || !dirtyRef.current || readOnly || savingRef.current) return;
+    const markdown = draftRef.current;
+    savingRef.current = true;
+    if (!unmountedRef.current) onSavingChange?.(true);
+    try {
+      const result = await onSave({ markdown, expectedRevision: revisionRef.current });
+      if (result?.revision) revisionRef.current = result.revision;
+      if (draftRef.current === markdown) {
+        dirtyRef.current = false;
+        if (!unmountedRef.current) onDirtyChange?.(false);
+      }
+    } finally {
+      savingRef.current = false;
+      if (!unmountedRef.current) onSavingChange?.(false);
+      if (dirtyRef.current && draftRef.current !== markdown) {
+        if (unmountedRef.current) {
+          void saveRef.current().catch((error) => console.error('Could not save Markdown on unmount', error));
+        } else {
+          setSaveAttempt((attempt) => attempt + 1);
+        }
+      }
+    }
+  }, [onDirtyChange, onSave, onSavingChange, readOnly]);
+  saveRef.current = save;
+
+  useEffect(() => {
+    unmountedRef.current = false;
+    return () => {
+      unmountedRef.current = true;
+      if (!savingRef.current) {
+        void saveRef.current().catch((error) => console.error('Could not save Markdown on unmount', error));
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!dirtyRef.current || !onSave || readOnly) return;
+    const timer = window.setTimeout(() => void save(), Math.max(250, autosaveMs));
+    return () => window.clearTimeout(timer);
+  }, [autosaveMs, draft, onSave, readOnly, save, saveAttempt]);
+
+  const handleChange = (event: ChangeEvent<HTMLTextAreaElement>) => {
+    const next = event.currentTarget.value;
+    draftRef.current = next;
+    setDraft(next);
+    if (!dirtyRef.current) {
+      dirtyRef.current = true;
+      onDirtyChange?.(true);
+    }
+    onChange?.(next);
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
+    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 's') {
+      event.preventDefault();
+      void save();
+    }
+  };
+
+  return (
+    <textarea
+      value={draft}
+      readOnly={readOnly}
+      placeholder={placeholder}
+      className={className}
+      onChange={handleChange}
+      onKeyDown={handleKeyDown}
+      style={{ minHeight: 360, width: '100%', resize: 'vertical' }}
+    />
+  );
+}
+
+/** Use Notis' editor while leaving persistence entirely under app control. */
+export function MarkdownEditor(props: NotisMarkdownEditorProps): ReactElement {
+  const runtime = useNotisRuntime();
+  const HostEditor = runtime?.ui?.MarkdownEditor;
+  return HostEditor
+    ? <HostEditor key={props.resourceKey} {...props} />
+    : <MarkdownEditorFallback key={props.resourceKey} {...props} />;
+}

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

@@ -1,25 +1,16 @@
 'use client';
 
-import {
-  useEffect,
+import React, {
   useMemo,
-  useRef,
   useState,
   type CSSProperties,
   type ReactElement,
-  type ReactNode,
 } from 'react';
+import type { ResolvedCollectionAction } from '../interactions/actions';
+import { shortcutDisplay, useShortcuts, type ShortcutDefinition } from '../interactions/shortcuts';
+import type { ShortcutScope } from '../interactions/shortcuts';
 
-export interface MultiSelectAction {
-  id: string;
-  label: string;
-  icon: ReactNode;
-  /** Single-key (e.g. "E", "#") or "Mod+K" shortcut. Bound while the bar is mounted with count > 0. */
-  shortcut?: string;
-  onRun: () => void | Promise<void>;
-  /** Hint for future destructive styling. Currently unused visually. */
-  destructive?: boolean;
-}
+export type MultiSelectAction = ResolvedCollectionAction;
 
 export interface MultiSelectActionBarProps {
   selectedCount: number;
@@ -30,73 +21,10 @@ export interface MultiSelectActionBarProps {
   className?: string;
   /** Optional override for the bar's positioning style. Defaults to bottom-center floating. */
   style?: CSSProperties;
-}
-
-interface ParsedShortcut {
-  key: string;
-  needsMod: boolean;
-  needsShift: boolean;
-}
-
-function parseShortcut(raw: string): ParsedShortcut | null {
-  const parts = raw.split('+').map((p) => p.trim()).filter(Boolean);
-  if (parts.length === 0) return null;
-  let needsMod = false;
-  let needsShift = false;
-  let key = '';
-  for (const part of parts) {
-    const lower = part.toLowerCase();
-    if (lower === 'mod' || lower === 'cmd' || lower === 'ctrl' || lower === 'meta') {
-      needsMod = true;
-    } else if (lower === 'shift') {
-      needsShift = true;
-    } else {
-      key = lower;
-    }
-  }
-  if (!key) return null;
-  return { key, needsMod, needsShift };
-}
-
-function shortcutMatches(shortcut: ParsedShortcut, event: KeyboardEvent): boolean {
-  const eventKey = event.key.toLowerCase();
-  // Special-case "#" so Shift+3 matches without the consumer specifying Shift.
-  if (shortcut.key === '#') {
-    if (eventKey === '#') return true;
-    if (event.shiftKey && eventKey === '3') return true;
-    return false;
-  }
-  if (eventKey !== shortcut.key) return false;
-  if (shortcut.needsMod !== Boolean(event.metaKey || event.ctrlKey)) return false;
-  if (shortcut.needsShift !== event.shiftKey) return false;
-  if (event.altKey) return false;
-  return true;
-}
-
-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;
-  return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
-}
-
-function shortcutDisplay(raw: string): string {
-  const parts = raw.split('+').map((p) => p.trim()).filter(Boolean);
-  return parts
-    .map((part) => {
-      const lower = part.toLowerCase();
-      if (lower === 'mod' || lower === 'cmd' || lower === 'meta') return '⌘';
-      if (lower === 'ctrl') return '⌃';
-      if (lower === 'shift') return '⇧';
-      if (lower === 'alt' || lower === 'option') return '⌥';
-      return part.length === 1 ? part.toUpperCase() : part;
-    })
-    .join('');
+  /** Disable action key bindings while leaving the visible toolbar mounted. */
+  shortcutsEnabled?: boolean;
+  /** Override the default collection shortcut scope. */
+  shortcutScope?: ShortcutScope;
 }
 
 const containerBaseStyle: CSSProperties = {
@@ -180,43 +108,25 @@ export function MultiSelectActionBar({
   itemLabel,
   className,
   style,
+  shortcutsEnabled = true,
+  shortcutScope = 'collection',
 }: MultiSelectActionBarProps): ReactElement | null {
-  const actionsRef = useRef(actions);
-  actionsRef.current = actions;
-
-  const parsedShortcuts = useMemo(() => {
-    return actions
-      .map((action) => {
-        if (!action.shortcut) return null;
-        const parsed = parseShortcut(action.shortcut);
-        return parsed ? { action, parsed } : null;
-      })
-      .filter((entry): entry is { action: MultiSelectAction; parsed: ParsedShortcut } => entry !== null);
+  const actionShortcuts = useMemo<ShortcutDefinition[]>(() => {
+    return actions.flatMap((action): ShortcutDefinition[] => {
+        if (!action.shortcut || action.disabled || action.pending) return [];
+        return [{
+          id: `collection.action.${action.id}`,
+          keys: action.shortcut,
+          label: action.label,
+          onTrigger: () => action.onRun(),
+        }];
+      });
   }, [actions]);
-
-  useEffect(() => {
-    if (selectedCount === 0 || parsedShortcuts.length === 0) return;
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (isEditableEvent(event)) return;
-      for (const { action, parsed } of parsedShortcuts) {
-        if (shortcutMatches(parsed, event)) {
-          event.preventDefault();
-          event.stopPropagation();
-          if (typeof event.stopImmediatePropagation === 'function') {
-            event.stopImmediatePropagation();
-          }
-          void action.onRun();
-          return;
-        }
-      }
-    };
-
-    document.addEventListener('keydown', handleKeyDown, true);
-    return () => {
-      document.removeEventListener('keydown', handleKeyDown, true);
-    };
-  }, [parsedShortcuts, selectedCount]);
+  useShortcuts(actionShortcuts, {
+    enabled: shortcutsEnabled && selectedCount > 0,
+    scope: shortcutScope,
+    priority: 25,
+  });
 
   if (selectedCount === 0) return null;
 
@@ -258,21 +168,29 @@ function ActionButton({ action }: { action: MultiSelectAction }) {
     color: hover
       ? 'hsl(var(--background))'
       : baseButtonStyle.color,
+    opacity: action.disabled ? 0.45 : 1,
+    cursor: action.disabled || action.pending ? 'not-allowed' : 'pointer',
   };
 
   return (
     <button
       type="button"
-      onClick={() => void action.onRun()}
+      onClick={() => {
+        if (!action.disabled && !action.pending) void action.onRun();
+      }}
+      disabled={action.disabled || action.pending}
+      aria-busy={action.pending || undefined}
+      aria-keyshortcuts={action.shortcut || undefined}
+      data-destructive={action.destructive ? 'true' : 'false'}
       onMouseEnter={() => setHover(true)}
       onMouseLeave={() => setHover(false)}
       onFocus={() => setHover(true)}
       onBlur={() => setHover(false)}
       style={buttonStyle}
     >
-      <span aria-hidden style={iconSlotStyle}>{action.icon}</span>
+      {action.icon ? <span aria-hidden style={iconSlotStyle}>{action.icon}</span> : null}
       {display ? <kbd aria-hidden style={keycapStyle}>{display}</kbd> : null}
-      <span>{action.label}</span>
+      <span>{action.pending ? `${action.label}…` : action.label}</span>
     </button>
   );
 }

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

@@ -1,10 +1,11 @@
 'use client';
 
-import { type CSSProperties, type MouseEvent as ReactMouseEvent, type ReactElement } from 'react';
+import React, { type CSSProperties, type MouseEvent as ReactMouseEvent, type ReactElement } from 'react';
 
 export interface MultiSelectCheckboxProps {
   isSelected: boolean;
   onClick: (event: ReactMouseEvent) => void;
+  disabled?: boolean;
   /** When true, the checkbox is always visible. Default false (hover/focus reveal via the parent's :hover state). */
   alwaysVisible?: boolean;
   /** Optional aria-label override. Defaults to "Select item" / "Deselect item". */
@@ -40,6 +41,7 @@ const checkPath = 'M3.5 7.5l2.5 2.5 6.5-6.5';
 export function MultiSelectCheckbox({
   isSelected,
   onClick,
+  disabled = false,
   alwaysVisible = false,
   ariaLabel,
   className,
@@ -49,6 +51,7 @@ export function MultiSelectCheckbox({
     ...baseStyle,
     ...(isSelected ? selectedStyle : null),
     ...(alwaysVisible || isSelected ? { opacity: 1 } : null),
+    ...(disabled ? { opacity: 0.45, cursor: 'not-allowed' } : null),
     ...(style || null),
   };
 
@@ -62,6 +65,7 @@ export function MultiSelectCheckbox({
       type="button"
       role="checkbox"
       aria-checked={isSelected}
+      disabled={disabled}
       aria-label={ariaLabel ?? (isSelected ? 'Deselect item' : 'Select item')}
       onClick={onClick}
       onMouseDown={(e) => e.stopPropagation()}

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { type CSSProperties, type ReactElement } from 'react';
+import React, { type CSSProperties, type ReactElement } from 'react';
 import type { DragRect } from '../hooks/useMultiSelect';
 
 export interface MultiSelectDragOverlayProps {

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

@@ -0,0 +1,55 @@
+import type { CSSProperties, ClipboardEvent, ReactNode } from 'react';
+import { useCallback } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { ContextResource, ContextSelection } from '../runtime';
+
+export const NOTIS_CONTEXT_CLIPBOARD_TYPE = 'application/x-notis-context+json';
+
+export interface NotisSelectionBoundaryProps {
+  resource?: ContextResource | null;
+  children: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+function selectionId(): string {
+  return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : `selection-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+/**
+ * Adds structured provenance to ordinary copied text. Pasting still works in
+ * every app because `text/plain` is preserved; Notis chat additionally reads
+ * the custom MIME payload and renders a separate quote pill.
+ */
+export function NotisSelectionBoundary({
+  resource,
+  children,
+  className,
+  style,
+}: NotisSelectionBoundaryProps) {
+  const runtime = useNotisRuntime();
+  const onCopy = useCallback((event: ClipboardEvent<HTMLDivElement>) => {
+    const selection = window.getSelection();
+    const text = selection?.toString().trim() ?? '';
+    if (
+      !text
+      || !selection
+      || !event.currentTarget.contains(selection.anchorNode)
+      || !event.currentTarget.contains(selection.focusNode)
+    ) return;
+
+    const payload: ContextSelection = {
+      id: selectionId(),
+      text: text.slice(0, 12_000),
+      ...(resource ? { resource: { ...resource, snapshot: undefined } } : {}),
+    };
+    event.clipboardData.setData('text/plain', text);
+    event.clipboardData.setData(NOTIS_CONTEXT_CLIPBOARD_TYPE, JSON.stringify(payload));
+    event.preventDefault();
+    runtime?.captureContextSelection?.(payload);
+  }, [resource, runtime]);
+
+  return <div className={className} style={style} onCopy={onCopy}>{children}</div>;
+}

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

@@ -0,0 +1,56 @@
+'use client';
+
+import React, { type CSSProperties, type ReactElement } from 'react';
+import { shortcutDisplay } from '../interactions/shortcuts';
+
+export interface ShortcutHint {
+  id: string;
+  keys: string;
+  label: string;
+}
+
+export interface ShortcutHintsProps {
+  shortcuts: ShortcutHint[];
+  className?: string;
+  style?: CSSProperties;
+}
+
+const listStyle: CSSProperties = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: '0.75rem',
+  color: 'hsl(var(--muted-foreground))',
+  fontSize: '12px',
+};
+
+const hintStyle: CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: '0.35rem',
+};
+
+const keyStyle: CSSProperties = {
+  minWidth: '20px',
+  border: '1px solid hsl(var(--border))',
+  borderRadius: '4px',
+  background: 'hsl(var(--muted))',
+  color: 'hsl(var(--foreground))',
+  padding: '1px 5px',
+  textAlign: 'center',
+  font: 'inherit',
+};
+
+export function ShortcutHints({ shortcuts, className, style }: ShortcutHintsProps): ReactElement | null {
+  if (shortcuts.length === 0) return null;
+  return (
+    <div aria-label="Keyboard shortcuts" className={className} style={{ ...listStyle, ...style }}>
+      {shortcuts.map((shortcut) => (
+        <span key={shortcut.id} style={hintStyle}>
+          <kbd style={keyStyle}>{shortcutDisplay(shortcut.keys)}</kbd>
+          <span>{shortcut.label}</span>
+        </span>
+      ))}
+    </div>
+  );
+}

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

@@ -174,9 +174,26 @@ export interface NotisAppCapabilities {
   cloudComputer?: 'read' | 'shell';
 }
 
+/**
+ * Execution hint for a tool whose public name is generated by a provider.
+ *
+ * MCP public names may be truncated or deduplicated, so the upstream action
+ * cannot always be reconstructed from the final `LOCAL_MCP_*` name. Binding
+ * the two lets the host skip provider schema discovery on direct calls while
+ * the public name remains the user-approved permission boundary.
+ */
+export interface NotisAppToolBinding {
+  /** Exact final name also present in `tools`. */
+  name: string;
+  /** Exact upstream MCP action name, for example `execute_sql`. */
+  providerToolName: string;
+}
+
 export interface NotisAppConfig {
   /** URL-safe app slug. Existing apps may still use a display name here. */
   name: string;
+  /** Stable local-development slug. Defaults to a slug derived from `name`. */
+  devSlug?: string;
   /** Human display title, Raycast-style. Falls back to `name`. */
   title?: string;
   description?: string;
@@ -218,6 +235,8 @@ export interface NotisAppConfig {
    * credit-cap and usage-billing path.
    */
   tools?: string[];
+  /** Optional execution bindings for provider-generated tool names. */
+  toolBindings?: NotisAppToolBinding[];
   /** Skills shipped from this app's source tree. */
   skills?: NotisAppSkillConfig[];
   /** Optional onboarding entrypoint exposed from the app sidebar. */

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

@@ -0,0 +1,19 @@
+import { useEffect, useMemo } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { ContextResource } from '../runtime';
+
+function stableResource(resource: ContextResource | null): string {
+  return JSON.stringify(resource);
+}
+
+/** Keep Notis aware of the resource currently open inside an app view. */
+export function useActiveResource(resource: ContextResource | null): void {
+  const runtime = useNotisRuntime();
+  const signature = stableResource(resource);
+  const stable = useMemo(() => resource, [signature]);
+
+  useEffect(() => {
+    runtime?.publishActiveResource?.(stable);
+    return () => runtime?.publishActiveResource?.(null);
+  }, [runtime, stable]);
+}