@notis_ai/cli 0.2.18 → 0.2.20

package/dist/sdk/src/components/Skeleton.tsx

@@ -0,0 +1,38 @@
+import type { CSSProperties } from 'react';
+import { useNotisRuntime } from '../provider';
+import { pick, type Locale, type Words } from '../words/types';
+
+/** What a loading placeholder says to screen readers. */
+export const SKELETON_WORDS = Object.freeze({
+  loading: { en: 'Loading content', fr: 'Chargement du contenu' },
+}) satisfies Readonly<Record<string, Words>>;
+
+/** Content-shaped placeholder. Never use it to replace a successful cached result. */
+export function Skeleton({ className, style }: { className?: string; style?: CSSProperties }) {
+  return <span aria-hidden="true" className={className} style={{ display: 'block', height: 16,
+    // Apps may define --muted as HSL channels or a complete CSS color. A
+    // neutral default remains visible with either token format and no theme.
+    borderRadius: 6, background: 'rgba(128,128,128,.18)', ...style }} />;
+}
+
+/** A whole view loading: a title bar and table, cards, graph or detail placeholders, named for screen readers in the Space's language. */
+export function ViewSkeleton({ variant = 'table', rows = 5, label, locale }: {
+  variant?: 'table' | 'cards' | 'graph' | 'detail'; rows?: number;
+  /** What loads, said to screen readers ("Loading meetings"). Default "Loading content". */
+  label?: Words | string;
+  /** Default the Space's locale. */
+  locale?: Locale;
+}) {
+  const runtimeLocale = useNotisRuntime()?.context?.locale;
+  const shown = locale ?? (runtimeLocale === 'fr' ? 'fr' : 'en');
+  return <div role="status" aria-label={pick(label ?? SKELETON_WORDS.loading, shown)} aria-busy="true" data-notis-content-skeleton
+    style={{ width: '100%', display: 'grid', gap: 16, padding: 24 }}>
+    <Skeleton style={{ width: '32%', height: 28 }} />
+    {variant === 'graph' ? <Skeleton style={{ height: 420 }} /> :
+      <div style={{ display: 'grid', gap: 12, gridTemplateColumns: variant === 'cards' ? 'repeat(auto-fit,minmax(180px,1fr))' : '1fr' }}>
+        {Array.from({ length: rows }, (_, index) => <Skeleton key={index}
+          style={{ height: variant === 'cards' ? 112 : variant === 'detail' ? 20 : 44,
+            width: variant === 'detail' && index === rows - 1 ? '65%' : '100%' }} />)}
+      </div>}
+  </div>;
+}

package/dist/sdk/src/config.ts

@@ -0,0 +1,31 @@
+export { defineSpace, defineSpaces } from './space';
+export type { SpaceDefinition, SpacesWorkspace, SpaceActionTemplate, SpaceResourceReference, SpaceDatabaseCreate } from './space';
+export type { SpaceViewParam, SpaceViewParamType, SpaceShows, SpaceMemoryPolicy, SpaceMemorySnapshot, SpaceChrome, SpaceMarkdownInput } from './space';
+
+/**
+ * Configuration utilities for notis.config.ts and Space definitions.
+ *
+ * Usage:
+ * ```ts
+ * // notis.config.ts
+ * import { defineSpaces } from '@notis/sdk/config';
+ *
+ * export default defineSpaces({
+ *   spaces: { notes: { definition: 'spaces/notes/space.config.ts' } },
+ * });
+ * ```
+ *
+ * Each definition file exports `defineSpace({ ... })`. `notis spaces build`
+ * reads only these two shapes.
+ */
+
+/**
+ * Identity helper kept so older sources whose configuration files still import
+ * it keep loading and bundling. It accepts any object and returns it unchanged;
+ * `notis spaces build` never reads that shape.
+ *
+ * @deprecated Use `defineSpaces` for the workspace index and `defineSpace` for each Space.
+ */
+export function defineNotisApp<T extends object>(config: T): T {
+  return config;
+}

package/{template/packages → dist}/sdk/src/documents.ts

@@ -14,6 +14,17 @@ import type {
   DocumentRecord,
   SecretPropertyValue,
 } from './runtime';
+import { pick, type Locale, type Words } from './words/types';
+
+/** The words the document helpers fall back on. */
+export const DOCUMENT_WORDS = Object.freeze({
+  untitled: { en: 'Untitled', fr: 'Sans titre' },
+}) satisfies Readonly<Record<string, Words>>;
+
+/** The locale of the fallback words ("Untitled"). Default English; the SDK hooks pass the Space's locale. */
+export interface DocumentWordsOptions {
+  locale?: Locale;
+}
 
 // ---------------------------------------------------------------------------
 // Value primitives
@@ -113,9 +124,10 @@ function normalizeContentType(value: unknown): DocumentContentType | 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.
+ * `DocumentRecord`: camelCases fields and collapses property values. A
+ * document with no title is titled "Untitled" in `options.locale`.
  */
-export function normalizeDocumentRecord(value: unknown): DocumentRecord {
+export function normalizeDocumentRecord(value: unknown, options: DocumentWordsOptions = {}): DocumentRecord {
   const record = asRecord(value) ?? {};
   const rawProperties = asRecord(record.properties) ?? {};
   const properties: Record<string, unknown> = {};
@@ -125,7 +137,9 @@ export function normalizeDocumentRecord(value: unknown): DocumentRecord {
 
   return {
     id: optionalString(record.id) ?? '',
-    title: optionalString(record.title) ?? 'Untitled',
+    recordKey: optionalString(record.recordKey) ?? optionalString(record.record_key) ?? undefined,
+    revision: typeof record.revision === 'number' ? record.revision : undefined,
+    title: optionalString(record.title) ?? pick(DOCUMENT_WORDS.untitled, options.locale ?? 'en'),
     url: optionalString(record.url),
     properties,
     icon: optionalString(record.icon),
@@ -241,9 +255,10 @@ export function blockNoteToPlainText(blocks: unknown): string {
 
 /**
  * Best-available plain-text preview for a document:
- * plainText -> contentMarkdown -> contentBlocknote -> title.
+ * plainText -> contentMarkdown -> contentBlocknote -> title, else "Untitled"
+ * in `options.locale`.
  */
-export function getDocumentPreview(document: DocumentRecord): string {
+export function getDocumentPreview(document: DocumentRecord, options: DocumentWordsOptions = {}): string {
   if (isPresentString(document.plainText)) {
     return document.plainText.replace(/\s+/g, ' ').trim();
   }
@@ -252,5 +267,5 @@ export function getDocumentPreview(document: DocumentRecord): string {
   }
   const fromBlocks = blockNoteToPlainText(document.contentBlocknote);
   if (fromBlocks) return fromBlocks;
-  return isPresentString(document.title) ? document.title : 'Untitled';
+  return isPresentString(document.title) ? document.title : pick(DOCUMENT_WORDS.untitled, options.locale ?? 'en');
 }

package/dist/sdk/src/hooks/useAction.ts

@@ -0,0 +1,28 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { useQuery, type UseQueryOptions, type UseQueryResult } from './useQuery';
+import type { SpaceActionOptions } from '../space';
+
+export function useAction<TInput extends Record<string, unknown> = Record<string, unknown>, TResult = unknown>(actionId: string): {
+  call: (inputs: TInput, options?: SpaceActionOptions) => Promise<TResult>; loading: boolean; error: Error | null;
+} {
+  const runtime = useNotisRuntime();
+  const [pending, setPending] = useState(0);
+  const [error, setError] = useState<Error | null>(null);
+  const call = useCallback(async (inputs: TInput, options?: SpaceActionOptions) => {
+    if (runtime?.resource?.kind !== 'space' || !runtime.callAction) throw new Error('A Space action runtime is required.');
+    setPending((value) => value + 1); setError(null);
+    try { return await runtime.callAction<TResult>(actionId, inputs, options); }
+    catch (cause) { const failure = cause instanceof Error ? cause : new Error(String(cause)); setError(failure); throw failure; }
+    finally { setPending((value) => value - 1); }
+  }, [runtime, actionId]);
+  return { call, loading: pending > 0, error };
+}
+
+export function useActionQuery<TResult = unknown>(actionId: string, inputs: Record<string, unknown>,
+  options: UseQueryOptions = { readOnly: true }): UseQueryResult<TResult> {
+  const { call } = useAction<Record<string, unknown>, TResult>(actionId);
+  return useQuery(['action', actionId, inputs], () => call(inputs, { readOnly: true, dedupe: true }), options);
+}

package/dist/sdk/src/hooks/useAgentContext.ts

@@ -0,0 +1,23 @@
+'use client';
+import { useMemo } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { AgentContextItem } from '../agentContext';
+
+/** Share context without owning storage, opening a new thread, or sending a message. */
+export function useAgentContext() {
+  const runtime = useNotisRuntime();
+  return useMemo(() => ({
+    add(item: AgentContextItem): Promise<boolean> {
+      if (!runtime?.addContext) return Promise.reject(new Error('Chat context is unavailable in this host.'));
+      return runtime.addContext(item);
+    },
+    update(item: AgentContextItem): Promise<boolean> {
+      if (!runtime?.updateContext) return Promise.reject(new Error('Chat context is unavailable in this host.'));
+      return runtime.updateContext(item);
+    },
+    remove(id: string): Promise<boolean> {
+      if (!runtime?.removeContext) return Promise.reject(new Error('Chat context is unavailable in this host.'));
+      return runtime.removeContext(id);
+    },
+  }), [runtime]);
+}

package/{template/packages → dist}/sdk/src/hooks/useBackend.ts

@@ -6,7 +6,7 @@ import { useNotisRuntime } from '../provider';
 interface UseBackendResult {
   /**
    * Make an authenticated request to the Notis backend.
-   * The path should be an absolute backend path (e.g. `/portal_composio/actions`).
+   * The path should be an absolute backend path (e.g. `/portal_composio/toolkits`).
    */
   request: (path: string, options?: {
     method?: string;
@@ -18,10 +18,11 @@ interface UseBackendResult {
 /**
  * Raw backend request proxy. Use this for custom server endpoints or
  * integration APIs not covered by the typed hooks.
+ * Spaces deny raw requests; use useAction or useActionQuery for declared actions.
  *
  * ```tsx
  * const { request } = useBackend();
- * const data = await request('/portal_composio/actions', { method: 'POST', body: { ... } });
+ * const data = await request('/portal_composio/toolkits', { method: 'GET' });
  * ```
  */
 export function useBackend(): UseBackendResult {

package/dist/sdk/src/hooks/useCloudComputer.ts

@@ -0,0 +1,94 @@
+'use client';
+
+import { useCallback, useRef } from 'react';
+import { useQuery } from './useQuery';
+import { useNotisRuntime } from '../provider';
+import { queryKey } from '../queryCache';
+import { spaceQueryKey } from '../space';
+import type { CloudComputerFacts, NotisRuntime } from '../runtime';
+
+/** Cache key of the facts read; re-read once the viewer allows a Space to use the cloud computer. */
+export const CLOUD_COMPUTER_FACTS_KEY = ['cloud-computer-facts'] as const;
+
+/** Marks the facts stale in the host cache so every mounted `useCloudComputer()` reads them again. */
+export function invalidateCloudComputerFacts(runtime: NotisRuntime | null): void {
+  try {
+    runtime?.queryClient?.invalidate(queryKey(spaceQueryKey(runtime, CLOUD_COMPUTER_FACTS_KEY)));
+  } catch {
+    // A host without a Space access context has no shared facts cache to refresh.
+  }
+}
+
+export interface UseCloudComputerResult {
+  /**
+   * The facts, or null while the first read is in flight. `facts.available`
+   * is false when this host cannot answer — render the app's own fallback.
+   */
+  facts: CloudComputerFacts | null;
+  loading: boolean;
+  isFetching: boolean;
+  error: Error | null;
+  /** Re-read the facts. The platform caches them for a few minutes. */
+  refresh: () => Promise<void>;
+  /**
+   * Space only (`cloudComputer: 'read'` or `'shell'`): ask the host to show its approval prompt.
+   * Resolves true once the viewer allowed it (the facts are then read again), false when they did
+   * not, and null on hosts without the prompt (Beta Apps, Sites, previews offline).
+   */
+  requestApproval: () => Promise<boolean | null>;
+}
+
+const UNAVAILABLE: CloudComputerFacts = {
+  available: false,
+  reason: 'unsupported_host',
+  sandbox: null,
+  cli_auth: {
+    gh: { authenticated: null, account: null, checked_at: null, reason: 'unsupported_host' },
+  },
+};
+
+/**
+ * Read-only facts about the user's cloud computer.
+ *
+ * ```tsx
+ * const { facts } = useCloudComputer();
+ * const gh = facts?.available ? facts.cli_auth.gh : null;
+ *
+ * return gh?.authenticated
+ *   ? <p>Signed in as {gh.account}</p>
+ *   : <GithubConnect />;
+ * ```
+ *
+ * Requires `cloudComputer: 'read'` (or `'shell'`) in `defineSpace` and the
+ * viewer's approval; until the viewer allows it the facts answer
+ * unavailable, so offer `requestApproval()`. It answers with state the platform already
+ * holds: reading it never creates, resumes or commands a sandbox, and the GitHub
+ * probe only runs when the sandbox is already awake. `authenticated: null`
+ * therefore means *unknown*, not *signed out* — keep the app's own fallback for
+ * that case and for hosts that answer `{ available: false }` (the dev harness,
+ * the vite preview).
+ */
+export function useCloudComputer(): UseCloudComputerResult {
+  const runtime = useNotisRuntime();
+  const explicitRefresh = useRef(false);
+  const query = useQuery<CloudComputerFacts>(CLOUD_COMPUTER_FACTS_KEY, async () => {
+    const refresh = explicitRefresh.current;
+    explicitRefresh.current = false;
+    return runtime?.cloudComputerFacts ? runtime.cloudComputerFacts(refresh ? { refresh: true } : undefined) : UNAVAILABLE;
+  }, { readOnly: true });
+  const refresh = useCallback(async () => {
+    explicitRefresh.current = true;
+    await query.refetch();
+  }, [query.refetch]);
+  const transport = runtime?.spaceCloudComputer;
+  const requestApproval = useCallback(async () => {
+    if (!transport) return null;
+    const status = await transport.requestApproval();
+    if (status?.approved !== true) return false;
+    invalidateCloudComputerFacts(runtime);
+    await query.refetch();
+    return true;
+  }, [query.refetch, runtime, transport]);
+  return { facts: query.data ?? (query.error ? UNAVAILABLE : null), loading: query.loading,
+    isFetching: query.isFetching, error: query.error, refresh, requestApproval };
+}

package/dist/sdk/src/hooks/useCloudComputerShell.ts

@@ -0,0 +1,114 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { invalidateCloudComputerFacts } from './useCloudComputer';
+import type {
+  SpaceCloudComputerLevel,
+  SpaceCloudComputerRunResult,
+  SpaceCloudComputerStatus,
+  SpaceCloudComputerUploadInput,
+  SpaceCloudComputerUploadResult,
+} from '../space';
+
+export interface UseCloudComputerShellResult {
+  /**
+   * The level this Space declares (`'read'` or `'shell'`) when this host offers the cloud computer,
+   * else null (Sites, links, verification harnesses, older hosts): keep the page's own fallback.
+   */
+  level: SpaceCloudComputerLevel | null;
+  /** True when `run` and `upload` are offered: the host offers the cloud computer and the Space declares `'shell'`. */
+  available: boolean;
+  /** The viewer's approval for this Space's current code (either level), or null while it is read. */
+  status: SpaceCloudComputerStatus | null;
+  approved: boolean;
+  loading: boolean;
+  /**
+   * Run one non-interactive command on the viewer's own cloud computer. Same result as the shell tool.
+   * Pass the same `requestId` when the page retries this run itself: a run is never repeated for one key.
+   */
+  run(command: string, options?: RunOptions): Promise<SpaceCloudComputerRunResult>;
+  /** Write one file (at most 1 MiB) straight to the cloud computer; it never travels by URL or chat. */
+  upload(file: SpaceCloudComputerUploadInput): Promise<SpaceCloudComputerUploadResult>;
+  /**
+   * Ask the host to show its approval prompt, for either declared level. Only the person's click in
+   * that prompt approves; once allowed, every `useCloudComputer()` reads the facts again.
+   */
+  requestApproval(): Promise<SpaceCloudComputerStatus | null>;
+  refresh(): Promise<void>;
+}
+
+type RunOptions = { cwd?: string; timeoutMs?: number; maxOutputLength?: number; requestId?: string };
+
+const unavailable = async (): Promise<never> => {
+  throw new Error('The cloud computer is not available in this Space.');
+};
+
+/**
+ * The viewer's approval and, for `cloudComputer: 'shell'`, commands and file writes on the signed-in
+ * viewer's own cloud computer, from a Space page.
+ *
+ * ```tsx
+ * const shell = useCloudComputerShell();
+ * if (!shell.level) return <AskNotisFallback />;
+ * if (!shell.approved) return <Button onClick={() => shell.requestApproval()}>Allow</Button>;
+ * const result = await shell.run(`bash ${SCRIPTS}/workspace.sh sync ${quote(repo)} ${quote(name)}`);
+ * ```
+ *
+ * Requires `cloudComputer` in `defineSpace` and the viewer's approval, which the Portal asks for in
+ * its own prompt and which covers only the exact code the viewer allowed: any new release asks again.
+ */
+export function useCloudComputerShell(): UseCloudComputerShellResult {
+  const runtime = useNotisRuntime();
+  const transport = runtime?.spaceCloudComputer;
+  const declared = runtime?.space?.cloudComputer;
+  const level: SpaceCloudComputerLevel | null = transport && (declared === 'read' || declared === 'shell') ? declared : null;
+  const available = level === 'shell';
+  const [status, setStatus] = useState<SpaceCloudComputerStatus | null>(null);
+  const [loading, setLoading] = useState(Boolean(level));
+  const mounted = useRef(true);
+  useEffect(() => () => { mounted.current = false; }, []);
+
+  const refresh = useCallback(async () => {
+    if (!level || !transport) return;
+    setLoading(true);
+    try {
+      const next = await transport.status();
+      if (mounted.current) setStatus(next);
+    } catch {
+      if (mounted.current) setStatus(null);
+    } finally {
+      if (mounted.current) setLoading(false);
+    }
+  }, [level, transport]);
+
+  useEffect(() => {
+    mounted.current = true;
+    void refresh();
+  }, [refresh]);
+
+  const run = useCallback(async (command: string, options: RunOptions = {}) => {
+    if (!available || !transport) return unavailable();
+    return transport.run({ command, ...(options.cwd ? { cwd: options.cwd } : {}),
+      ...(options.timeoutMs ? { timeout_ms: options.timeoutMs } : {}),
+      ...(options.maxOutputLength ? { max_output_length: options.maxOutputLength } : {}),
+      ...(options.requestId ? { request_id: options.requestId } : {}) });
+  }, [available, transport]);
+
+  const upload = useCallback(async (file: SpaceCloudComputerUploadInput) => {
+    if (!available || !transport) return unavailable();
+    return transport.upload(file);
+  }, [available, transport]);
+
+  const requestApproval = useCallback(async () => {
+    if (!level || !transport) return null;
+    const next = await transport.requestApproval();
+    if (mounted.current) setStatus(next);
+    // A facts read refused before the approval must not keep showing "unavailable".
+    if (next?.approved === true) invalidateCloudComputerFacts(runtime);
+    return next;
+  }, [level, runtime, transport]);
+
+  return { level, available, status, approved: status?.approved === true, loading: Boolean(level) && loading,
+    run, upload, requestApproval, refresh };
+}