@notis_ai/cli 0.2.0-beta.19.1 → 0.2.0-beta.196.1

package/dist/sdk/src/config.ts

@@ -0,0 +1,239 @@
+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.
+ *
+ * Usage:
+ * ```ts
+ * // notis.config.ts
+ * import { defineNotisApp } from '@notis/sdk/config';
+ *
+ * export default defineNotisApp({
+ *   name: 'My App',
+ *   description: 'Does things',
+ *   icon: 'phosphor:squares-four',
+ *   databases: ['tasks'],
+ *   routes: [
+ *     {
+ *       path: '/',
+ *       slug: 'notes',
+ *       name: 'Notes',
+ *       default: true,
+ *       collection: {
+ *         database: 'notes',
+ *         titleProperty: 'Name',
+ *         parentProperty: 'Parent',
+ *         sidebar: {
+ *           mode: 'tree',
+ *           allowCreate: true,
+ *         },
+ *       },
+ *     },
+ *   ],
+ *   tools: [...],
+ * });
+ * ```
+ */
+
+export interface NotisRouteConfig {
+  path: string;
+  slug: string;
+  name: string;
+  icon?: string;
+  parentSlug?: string | null;
+  default?: boolean;
+  /**
+   * Allow the host to address an app-owned resource on this route through the
+   * canonical `?resource=<id>` deep link. Read the incoming id with
+   * `useNotis().resourceId`.
+   */
+  resourceDeepLinks?: boolean;
+  exportName?: string;
+  collection?: {
+    database: string;
+    titleProperty: string;
+    parentProperty?: string | null;
+    sidebar?: {
+      mode: 'flat-list' | 'tree';
+      allowCreate: boolean;
+    };
+  };
+}
+
+export const NOTIS_APP_CATEGORIES = [
+  'Productivity',
+  'Sales & Marketing',
+  'Operations',
+  'Product & Engineering',
+  'Personal',
+] as const;
+
+export type NotisAppCategory = typeof NOTIS_APP_CATEGORIES[number];
+
+export interface NotisAppDatabaseConfig {
+  /** Database slug, as declared by the app. */
+  slug: string;
+  /**
+   * Ship this database's rows to everyone who installs the app.
+   *
+   * Off by default: declaring a database publishes its STRUCTURE, never its
+   * content. Turn it on only for starter content that every installer should
+   * receive - a default folder tree, a set of templates - and never for a
+   * database that accumulates the author's own data.
+   */
+  seedDocuments?: boolean;
+}
+
+export interface NotisAppAuthor {
+  name: string;
+  handle?: string;
+  url?: string;
+}
+
+export interface NotisAppScreenshotConfig {
+  /** Conventional metadata/screenshot-N.png source path. */
+  path: string;
+  /** Meaningful description used by the Store gallery and assistive technology. */
+  alt: string;
+  /** Route slug captured by `notis apps screenshot`. */
+  route?: string;
+  /**
+   * Named scenario from metadata/screenshot-fixtures.json. Its `tools` and
+   * `requests` override the file-level ones key by key for this capture, and
+   * its `actions` run once the route has mounted -- so one route can be shown
+   * in several states (populated, empty, a panel opened) without the states
+   * leaking into each other.
+   */
+  scenario?: string;
+  /** Optional CSS selector captured as the truthful focal region for this Store image. */
+  focus?: string;
+  /** Portal color scheme used while rendering this screenshot. Defaults to light. */
+  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 NotisAppCapabilities {
+  /**
+   * Read every database in the workspace, not only the ones this app declares
+   * in `databases` or created itself.
+   *
+   * An app runtime is otherwise sandboxed to its own databases, so a catalog or
+   * explorer app sees an empty list without this. `'read'` is the only accepted
+   * value and it never grants writes: `LOCAL_NOTIS_DATABASE_UPSERT_*` stays
+   * bound to the app's own databases.
+   */
+  workspaceDatabases?: 'read';
+
+  /**
+   * Read a few facts about the user's cloud computer: whether a sandbox exists
+   * and is running, and whether the GitHub CLI is signed in there.
+   *
+   * Without this an app has to infer them — the Workspaces app treated a
+   * configured repository as proof that `gh auth login` had happened, which
+   * cannot show an account name and cannot notice a revoked credential.
+   * `'read'` never creates, resumes or commands a sandbox. Read it with
+   * `useCloudComputer()`.
+   *
+   * `'shell'` additionally asks to command the cloud computer: it unlocks
+   * `LOCAL_NOTIS_RUN_SANDBOX_SHELL` and the sandbox file tools from this app's
+   * views (they are denied to every view otherwise), and implies the read
+   * facts. This is the same authority the user's own agent has on the sandbox,
+   * so the user is asked for it explicitly at install or in the Store grant
+   * step; declare it only when the app's core actions genuinely run there.
+   */
+  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 {
+  /** Standalone reports share the view engine without app installation. */
+  kind?: 'app' | 'report';
+  /** Existing data sources, never owned or materialized by a report. */
+  databaseAccess?: Array<{ id: string; access: 'read' | 'write' }>;
+  /** 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;
+  /** Editorial screenshot order and capture scenarios for the Store listing. */
+  screenshots?: NotisAppScreenshotConfig[];
+  /**
+   * Databases this app owns. A bare string publishes structure only; use the
+   * object form to opt a database into shipping its rows to installers.
+   */
+  databases?: (string | NotisAppDatabaseConfig)[];
+  /**
+   * Extra permissions the app asks for at install time. Everything here widens
+   * what the app can reach beyond its own data, so each one is surfaced to the
+   * user before they install.
+   */
+  capabilities?: NotisAppCapabilities;
+  routes?: NotisRouteConfig[];
+  /**
+   * Final tool names this app can call at runtime, enforced server-side. Use
+   * names returned by shared discovery, including native `LOCAL_NOTIS_*`,
+   * connected-service names such as `GMAIL_SEND_EMAIL`,
+   * `LOCAL_POSTFORME_*`, and `LOCAL_MCP_<SERVER>_<TOOL>`. App code calls
+   * each declared name directly with `useTool`; metered calls use the shared
+   * credit-cap and usage-billing path.
+   */
+  tools?: string[];
+  /** Optional execution bindings for provider-generated tool names. */
+  toolBindings?: NotisAppToolBinding[];
+}
+
+/**
+ * Identity function that provides type checking and autocomplete for the
+ * Notis app configuration. The returned object is read at build time by
+ * `notis apps build` to generate the manifest.
+ */
+export function defineNotisApp(config: NotisAppConfig): NotisAppConfig {
+  return config;
+}

package/dist/sdk/src/documents.ts

@@ -0,0 +1,258 @@
+/**
+ * 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,
+  SecretPropertyValue,
+} 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('');
+}
+
+/**
+ * Reads a `secret` property value. The platform only ever sends the pointer
+ * ({present, reference, status, metadata}), so this rebuilds it field by field
+ * rather than passing the payload through — an app can never surface secret
+ * material through this helper, whatever the server sent.
+ */
+export function getSecretValue(value: unknown): SecretPropertyValue {
+  const record = asRecord(value);
+  const metadata = asRecord(record?.metadata);
+  return {
+    present: record?.present === true,
+    reference: optionalString(record?.reference),
+    status: optionalString(record?.status),
+    metadata,
+  };
+}
+
+/** 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;
+  // Before the `type in record` fallthrough: a secret value has no `secret`
+  // key, so passing it through would hand the caller the raw payload.
+  if (type === 'secret') return getSecretValue(record);
+  if (type in record) return record[type];
+  return value;
+}
+
+function normalizeContentType(value: unknown): DocumentContentType | null {
+  return value === 'markdown' || value === 'file' || value === 'view' ? 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) ?? '',
+    recordKey: optionalString(record.recordKey) ?? optionalString(record.record_key) ?? undefined,
+    revision: typeof record.revision === 'number' ? record.revision : undefined,
+    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),
+    viewType: optionalString(record.viewType) ?? optionalString(record.view_type),
+    viewState: asRecord(record.viewState) ?? asRecord(record.view_state),
+    viewRevision:
+      typeof (record.viewRevision ?? record.view_revision) === 'number'
+        ? Number(record.viewRevision ?? record.view_revision)
+        : null,
+    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/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/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]);
+}

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/dist/sdk/src/hooks/useCloudComputer.ts

@@ -0,0 +1,95 @@
+'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 `capabilities.cloudComputer: 'read'` in `notis.config.ts` and the
+ * user's approval at install time. In a Space, declare `cloudComputer: 'read'`
+ * (or `'shell'`) in `defineSpace`; 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 };
+}