zidane-ui 9.1.1 → 9.1.3

package/src/settings/headless/resource.ts

@@ -1,75 +0,0 @@
-/**
- * `createSettingsResource`: a {@link SettingsResource} over an async read,
- * for hosts with no cache of their own (zidane-server, the fixture). The
- * first subscriber starts the read; `refresh` reads again and keeps the last
- * good value through a failure. Only the latest read lands.
- */
-import { toSettingsError } from './host';
-import type { SettingsLoad, SettingsResource } from './sections-host';
-
-/** Options for {@link createSettingsResource}. */
-export interface SettingsResourceOptions<T> {
-  /** A value to show before the first read lands (no loading state). */
-  initial?: T;
-}
-
-/**
- * Creates a resource over `read`.
- *
- * @param read - Reads the value; a rejection lands in `error`.
- * @param options - An initial value.
- */
-export function createSettingsResource<T>(
-  read: () => Promise<T>,
-  options: SettingsResourceOptions<T> = {},
-): SettingsResource<T> {
-  let state: SettingsLoad<T> =
-    options.initial !== undefined
-      ? { data: options.initial, error: null, loading: false }
-      : { data: undefined, error: null, loading: true };
-  const listeners = new Set<() => void>();
-  let started = false;
-  let generation = 0;
-  const set = (next: SettingsLoad<T>) => {
-    state = next;
-    for (const listener of [...listeners]) listener();
-  };
-  const refresh = async () => {
-    started = true;
-    const mine = ++generation;
-    try {
-      const data = await read();
-      if (mine === generation) set({ data, error: null, loading: false });
-    } catch (error) {
-      if (mine === generation) set({ data: state.data, error: toSettingsError(error), loading: false });
-    }
-  };
-  return {
-    get: () => state,
-    subscribe(listener) {
-      listeners.add(listener);
-      if (!started) void refresh();
-      return () => listeners.delete(listener);
-    },
-    refresh,
-  };
-}
-
-/**
- * Keeps one resource per key (a folder, a skill), so every reader of the same
- * key shares one read.
- *
- * @param make - Builds the resource for a key.
- */
-export function keyedSettingsResources<K, T>(make: (key: K) => SettingsResource<T>): (key: K) => SettingsResource<T> {
-  const byKey = new Map<string, SettingsResource<T>>();
-  return (key) => {
-    const id = typeof key === 'string' ? key : JSON.stringify(key);
-    let resource = byKey.get(id);
-    if (!resource) {
-      resource = make(key);
-      byKey.set(id, resource);
-    }
-    return resource;
-  };
-}

package/src/settings/headless/search.ts

@@ -1,142 +0,0 @@
-/**
- * Settings search: the index and the match. Every whitespace-separated term
- * must appear in an entry's label, description, key or keywords (synonyms
- * such as "finder" for `openIn`, a choice's option labels),
- * case-insensitively.
- *
- * `sectionSearchHits` indexes whatever sections the shell holds;
- * `layoutSearchEntries` derives a layout page's entries (its catalog rows,
- * custom rows, panel entries and app actions) for a section's `search`.
- */
-import { settingKeywords } from 'zidane/chat/pure';
-
-import { SETTINGS_CHOICES, SETTINGS_TOGGLES } from './catalog';
-import { isPanelPage, shown, type SettingsActionId, type SettingsPage } from './layout';
-import type { SettingsSearchEntry, SettingsSection } from './registry';
-
-/** One search result: an entry and the section it lands on. */
-export interface SettingsSearchHit extends SettingsSearchEntry {
-  /** The section's id. */
-  section: string;
-}
-
-/** The catalog's toggles by key. */
-export const SETTINGS_TOGGLE_BY_KEY = new Map(SETTINGS_TOGGLES.map((row) => [row.key as string, row]));
-/** The catalog's choices by key. */
-export const SETTINGS_CHOICE_BY_KEY = new Map(SETTINGS_CHOICES.map((row) => [row.key as string, row]));
-
-/** What a layout page's entries depend on. */
-export interface LayoutSearchContext {
-  /** Editing a server: its `localOnly` parts are left out. */
-  server: boolean;
-  /** The app's spaces live in the server's settings (the web app's do): Spaces stays while `server`. */
-  spacesOnServer?: boolean;
-  /** The app actions wired in; a row for a missing one is skipped. */
-  actions: readonly { id: SettingsActionId; label: string; description: string }[];
-}
-
-/**
- * One entry per row a layout page shows: a catalog row with its keywords
- * and a choice's option labels, a custom row's or a panel's own entries, an
- * app action.
- *
- * @param page - The layout page.
- * @param ctx - Editing a server, and the actions wired in.
- * @returns The page's entries.
- */
-export function layoutSearchEntries(page: SettingsPage, ctx: LayoutSearchContext): SettingsSearchEntry[] {
-  const entries: SettingsSearchEntry[] = [];
-  const catalogEntry = (key: string) => {
-    const choice = SETTINGS_CHOICE_BY_KEY.get(key);
-    const row = SETTINGS_TOGGLE_BY_KEY.get(key) ?? choice;
-    if (row) {
-      const options = choice ? choice.options.map((o) => o.label) : [];
-      entries.push({
-        label: row.label,
-        description: row.description,
-        key,
-        keywords: [...settingKeywords(key), ...options],
-      });
-    }
-  };
-  if (isPanelPage(page)) {
-    for (const key of page.keys ?? []) catalogEntry(key);
-    entries.push(...page.search);
-    return entries;
-  }
-  for (const section of page.sections) {
-    if (!shown(section, ctx.server, ctx.spacesOnServer)) continue;
-    if ('panel' in section) {
-      entries.push(...section.search);
-      continue;
-    }
-    for (const row of section.rows) {
-      if ('key' in row) {
-        catalogEntry(row.key);
-      } else if ('custom' in row) {
-        if (shown(row, ctx.server)) entries.push(...(row.search ?? []));
-      } else {
-        const action = ctx.actions.find((a) => a.id === row.action);
-        if (action) entries.push({ label: action.label, description: action.description, key: action.id });
-      }
-    }
-  }
-  return entries;
-}
-
-/**
- * {@link layoutSearchEntries} for every page, each hit on its page.
- *
- * @param pages - The pages offered.
- * @param ctx - Editing a server, and the actions wired in.
- * @returns Every page's entries, in page order.
- */
-export function settingsSearchHits(pages: readonly SettingsPage[], ctx: LayoutSearchContext): SettingsSearchHit[] {
-  return pages.flatMap((page) => layoutSearchEntries(page, ctx).map((entry) => ({ section: page.id, ...entry })));
-}
-
-/**
- * The search index of the shell's sections: each section's `search`
- * entries, or the section itself (title, description, keywords) when it
- * has none, then `extra` (entries an app adds, e.g. extension options).
- *
- * @param sections - The shell's sections.
- * @param extra - More entries, after the sections'.
- * @returns The index.
- */
-export function sectionSearchHits(
-  sections: readonly SettingsSection[],
-  extra: readonly SettingsSearchHit[] = [],
-): SettingsSearchHit[] {
-  const hits: SettingsSearchHit[] = [];
-  for (const section of sections) {
-    if (section.search) {
-      for (const entry of section.search) hits.push({ section: section.id, ...entry });
-    } else {
-      hits.push({
-        section: section.id,
-        label: section.title,
-        description: section.description ?? '',
-        ...(section.keywords ? { keywords: section.keywords } : {}),
-      });
-    }
-  }
-  hits.push(...extra);
-  return hits;
-}
-
-/**
- * The entries every term of `query` matches, in index order; none for a blank query.
- *
- * @param hits - The index.
- * @param query - What the user typed.
- * @returns The matching entries.
- */
-export function searchSettings<H extends SettingsSearchEntry>(hits: readonly H[], query: string): H[] {
-  const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
-  if (terms.length === 0) return [];
-  return hits.filter((hit) => {
-    const corpus = [hit.label, hit.description, hit.key ?? '', ...(hit.keywords ?? [])].join(' ').toLowerCase();
-    return terms.every((term) => corpus.includes(term));
-  });
-}

package/src/settings/headless/sections-host.ts

@@ -1,340 +0,0 @@
-/**
- * The `SettingsHost` member groups the catalog and diagnostics sections read
- * (Skills, Extensions, Plugins, Instructions, Environments, Logs, a host's
- * catalog): each optional, and a section whose group the host leaves out
- * shows nothing to do. React-free.
- *
- * A list the section keeps on screen across visits comes as a
- * {@link SettingsResource} (a readable store with `refresh`), so an app
- * that caches its reads hands the cached value at once; a one-shot read or
- * an action is an async method. A rejection is a `SettingsError` (or
- * anything `toSettingsError` wraps), worded by the section's labels.
- */
-import type { SkillConfig, WireExtensionConfigSchema } from 'zidane';
-import type {
-  ContextSegmentsReport,
-  EnvironmentDescriptor,
-  EnvironmentSettingsChange,
-  EnvironmentVerifyResult,
-} from 'zidane/chat';
-import type { ExtensionInstallOrigin, ExtensionSourceListing, LogRecord, SkillSourceListing } from 'zidane/chat/pure';
-import type { HostCatalogExtension, HostCatalogMcp, HostCatalogPlugin, HostCatalogSkill } from 'zidane/ipc';
-
-import type { SettingsError } from './host';
-
-/** What a {@link SettingsResource} holds now. */
-export interface SettingsLoad<T> {
-  /** The last value read; `undefined` until the first read lands. */
-  data: T | undefined;
-  /** The last read failed (the last good `data` stays). */
-  error: SettingsError | null;
-  /** Nothing read yet and a read runs. */
-  loading: boolean;
-}
-
-/** A value the host reads and keeps current: `get` returns the same object until it changes. */
-export interface SettingsResource<T> {
-  /** What is held now. */
-  get(): SettingsLoad<T>;
-  /** Called after each change; returns its unsubscribe. */
-  subscribe(listener: () => void): () => void;
-  /** Reads again. Never rejects: a failure lands in `error`. */
-  refresh(): Promise<void>;
-}
-
-/** Where an install goes: the project's folder or the user's. */
-export type SettingsInstallScope = 'user' | 'project';
-
-/** A file the host reads and writes with a guard on its modification time. */
-export interface SettingsFile {
-  /** Its path on the host. */
-  path: string;
-  /** Its text. */
-  contents: string;
-  /** Its modification time when read. */
-  mtimeMs: number;
-}
-
-/** What a guarded write did. */
-export type SettingsFileWrite =
-  | { ok: true; mtimeMs: number }
-  /** `changed`: the file is newer than the time given; `missing` / `denied`: it can't be written. */
-  | { ok: false; reason: 'changed' | 'missing' | 'denied' };
-
-/** Skills to install from one source. */
-export interface SettingsSkillInstall {
-  /** The source spec (`owner/repo`, a URL, a path) the browser listed them from. */
-  source: string;
-  /** Where they go. */
-  scope: SettingsInstallScope;
-  /** The picked skills' paths in the source. */
-  skills: readonly string[];
-}
-
-/** Skills on the host's disk, for one folder (its project scope plus the user's). */
-export interface SettingsSkillsHost {
-  /** The skills found for `cwd`, unfiltered by the allowlist. */
-  catalog(cwd: string): SettingsResource<readonly SkillConfig[]>;
-  /** Lists what a source holds (a GitHub repo, a skills.sh URL). Absent: no source browser. */
-  browse?(input: string): Promise<SkillSourceListing>;
-  /**
-   * Installs picked skills; `onProgress` gets the installer's lines. Resolves `unmatched` when the
-   * installer could not find the picked skills in the source. Absent: no install.
-   */
-  install?(
-    cwd: string,
-    request: SettingsSkillInstall,
-    onProgress?: (line: string) => void,
-  ): Promise<'installed' | 'unmatched'>;
-  /** Deletes a skill's folder from disk. Absent: no delete. */
-  remove?(cwd: string, skill: SkillConfig): Promise<void>;
-  /** A skill's `SKILL.md` (`null`: it has no file). Absent: the skill shows its instructions, read-only. */
-  file?(cwd: string, name: string): SettingsResource<SettingsFile | null>;
-  /** Writes a skill's `SKILL.md` if it is still at `expectedMtimeMs`. Absent: read-only. */
-  write?(cwd: string, name: string, contents: string, expectedMtimeMs: number): Promise<SettingsFileWrite>;
-}
-
-/** An extension the host discovered. */
-export interface SettingsExtension {
-  /** Its name (the allowlist key). */
-  name: string;
-  /** Where it was found. */
-  source: 'user' | 'project' | 'inline' | 'builtin';
-  /** It contributes now. */
-  enabled: boolean;
-  /** Its manifest version. */
-  version?: string;
-  /** What it does. */
-  description?: string;
-  /** Its folder (disk extensions only). */
-  dir?: string;
-  /** Why it did not load. */
-  error?: string;
-  /** What it contributes: `tools`, `skills`, … */
-  capabilities?: readonly string[];
-  /** Its display name. Absent: `name`. */
-  displayName?: string;
-  /** Its own icon, the first thing `extensionMark` reads. */
-  icon?: { gui?: string; tui?: string };
-  /** The source it was installed from, which Update follows. Absent: not installed from a source. */
-  origin?: ExtensionInstallOrigin;
-}
-
-/** An extension to install. */
-export interface SettingsExtensionInstall {
-  /** A GitHub / npm spec or a local path. */
-  source: string;
-  /** Which extension, for a source with several. */
-  extension?: string;
-  /** Where it goes. */
-  scope: SettingsInstallScope;
-}
-
-/** Extensions on the host's disk, for one folder. */
-export interface SettingsExtensionsHost {
-  /** The extensions for `cwd`. Read again after each toggle (their state follows the allowlist). */
-  list(cwd: string): Promise<readonly SettingsExtension[]>;
-  /** Installs one; `onProgress` gets the installer's lines. Resolves with its name. Absent: no install. */
-  install?(
-    cwd: string,
-    request: SettingsExtensionInstall,
-    onProgress?: (line: string) => void,
-  ): Promise<{ name: string }>;
-  /** Runs its installer again. Resolves with what it said. Absent: no update. */
-  update?(cwd: string, extension: SettingsExtension): Promise<string>;
-  /**
-   * Lists what a source holds (a GitHub repo, an npm package), read from the manifests: nothing runs.
-   * Never rejects for an unreadable source: the listing carries `error`. Absent: no source browser.
-   */
-  browse?(input: string): Promise<ExtensionSourceListing>;
-  /**
-   * Installs `extension` again from `source`, which must hold an extension of the same name; later
-   * updates follow it. Its folder changes only on success. Resolves with what the installer said.
-   * Absent: no Change origin.
-   */
-  changeOrigin?(
-    cwd: string,
-    extension: SettingsExtension,
-    source: string,
-    onProgress?: (line: string) => void,
-  ): Promise<string>;
-  /** Deletes its folder. Absent: no remove. */
-  remove?(cwd: string, extension: SettingsExtension): Promise<void>;
-  /** The options the enabled extensions declare for `cwd` (values live on `Settings.extensionConfig`). Absent: none listed. */
-  configSchema?(cwd: string): SettingsResource<WireExtensionConfigSchema>;
-  /** The action rows the enabled extensions declare for `cwd`. Absent: none listed. */
-  actions?(cwd: string): SettingsResource<readonly SettingsExtensionAction[]>;
-  /** The actions' passive status probes, keyed `extension:key`. Absent: rows without a status line. */
-  actionStatuses?(cwd: string): Promise<Record<string, SettingsExtensionActionStatus>>;
-  /** Runs an action. Absent: no Run buttons. */
-  runAction?(cwd: string, extension: string, key: string): Promise<SettingsExtensionActionResult>;
-  /** Scaffolds a new extension. Absent: no create flow. */
-  create?(request: SettingsExtensionCreate): Promise<SettingsExtensionCreated>;
-}
-
-/** An action an extension declares (`registerConfigItem` type `'action'`); it runs on the host. */
-export interface SettingsExtensionAction {
-  /** The extension. */
-  extension: string;
-  /** The action's key. */
-  key: string;
-  /** Its name. */
-  label: string;
-  /** What it does. */
-  description?: string;
-  /** The category it sits in. */
-  category: string;
-  /** The category's name. */
-  categoryLabel: string;
-  /** It declares a passive `status()` probe. */
-  hasStatus: boolean;
-}
-
-/** An action's passive probe. */
-export interface SettingsExtensionActionStatus {
-  /** How it is. */
-  state: 'ok' | 'off' | 'error';
-  /** What it says. */
-  message: string;
-}
-
-/** What a run did: its message, and the config patch it set (already validated by the host). */
-export interface SettingsExtensionActionResult {
-  /** What to show. */
-  message: string;
-  /** The accepted config patch, to store under `Settings.extensionConfig[extension]`. */
-  config?: Record<string, boolean | number | string>;
-}
-
-/** An extension to scaffold. */
-export interface SettingsExtensionCreate {
-  /** Its name. */
-  name: string;
-  /** Where it goes. */
-  scope: SettingsInstallScope;
-  /** The project folder, for the project scope. */
-  cwd?: string;
-}
-
-/** A scaffolded extension. */
-export interface SettingsExtensionCreated {
-  /** Its folder. */
-  dir: string;
-  /** Its name. */
-  name: string;
-  /** A project extension stays unloaded until the project is trusted. */
-  needsTrust?: boolean;
-}
-
-/** An Agent Plugin the host discovered. */
-export interface SettingsPlugin {
-  /** Its name (the allowlist key). */
-  name: string;
-  /** Whose config it comes from. */
-  source: 'project' | 'user';
-  /** Its folder. */
-  path: string;
-  /** `false`: its manifest was rejected, it adds nothing. */
-  ok: boolean;
-  /** What it does. */
-  description: string | null;
-  /** Its manifest version. */
-  version: string | null;
-  /** The skills it adds. */
-  skillCount: number;
-  /** The MCP servers it adds. */
-  mcpCount: number;
-  /** The extension that loads it (its switch governs the plugin). Absent: found on disk. */
-  loadedBy?: string;
-}
-
-/** Agent Plugins on the host's disk, for one folder. */
-export interface SettingsPluginsHost {
-  /** The plugins for `cwd`, unfiltered by the allowlist. */
-  catalog(cwd: string): SettingsResource<readonly SettingsPlugin[]>;
-}
-
-/** What a session's agent is loaded with. */
-export interface SettingsInstructionsHost {
-  /** Every chunk of the session's system prompt with provenance (`null`: no live agent). */
-  segments(sessionId: string): Promise<ContextSegmentsReport | null>;
-  /** Seeds a user `SYSTEM.md` from the session's prompt. Absent: no "Create SYSTEM.md". */
-  createSystemOverride?(sessionId: string): Promise<void>;
-  /** Opens an instruction file of the session in an editor. Absent: no open button. */
-  openFile?(sessionId: string, path: string): Promise<void>;
-}
-
-/** Where new sessions run: the environment kinds and their settings. */
-export interface SettingsEnvironmentsHost {
-  /** Every kind, described for a new session in `cwd` (`''`: none). */
-  list(cwd: string): Promise<readonly EnvironmentDescriptor[]>;
-  /** Applies one edit (on, default, an option, a secret). Absent: read-only. */
-  update?(change: EnvironmentSettingsChange): Promise<void>;
-  /** Tests a kind's connection. Absent: no test button. */
-  verify?(kind: string): Promise<EnvironmentVerifyResult>;
-}
-
-/** The host's log funnel. */
-export interface SettingsLogsHost {
-  /** The records held now (a ring buffer). */
-  list(): Promise<readonly LogRecord[]>;
-  /** Gets each new record; returns its unsubscribe. */
-  follow(onRecord: (record: LogRecord) => void): () => void;
-}
-
-/** Which of a host's catalogs. */
-export type SettingsCatalogKind = 'skills' | 'mcps' | 'extensions' | 'plugins';
-
-/** One catalog's entries. */
-export interface SettingsCatalogEntries {
-  /** A skill, with where it comes from. */
-  skills: HostCatalogSkill;
-  /** An MCP server, its secrets redacted. */
-  mcps: HostCatalogMcp;
-  /** An extension, with why it failed to load. */
-  extensions: HostCatalogExtension;
-  /** A plugin, with what it contributes. */
-  plugins: HostCatalogPlugin;
-}
-
-/** What can be installed from a spec on a host. */
-export type SettingsCatalogInstallKind = 'skill' | 'extension';
-
-/**
- * A host's catalogs as the host itself reports them (a zidane-server's
- * `catalog.*`), each entry with the host's enabled state; the enabled lists
- * are its settings (`update`). Its MCP servers are the `mcp` group's.
- */
-export interface SettingsHostCatalog {
-  /** One catalog, with `cwd`'s project scope (none: the host user's). `null`: the host can't list it. */
-  list<K extends SettingsCatalogKind>(kind: K, cwd?: string): Promise<SettingsCatalogEntries[K][] | null>;
-  /** Called when a catalog changed there (an install from any client); returns its unsubscribe. */
-  onChanged?(listener: (kind: SettingsCatalogKind) => void): () => void;
-  /** Whether the host takes installs and removals from this connection. Absent: never. */
-  installs?(): Promise<boolean>;
-  /** Installs a skill or an extension from a GitHub / npm spec into the host user's scope; `extension` picks one of a source's. */
-  install?(kind: SettingsCatalogInstallKind, spec: string, options?: { extension?: string }): Promise<void>;
-  /**
-   * Lists the extensions a source holds, read by the host from their manifests (as
-   * `SettingsExtensionsHost.browse`). Absent: the Install form instead of the source browser.
-   */
-  browse?(input: string): Promise<ExtensionSourceListing>;
-  /**
-   * Installs a user-scope extension again from `source`, which must hold one of the same name (else a
-   * `SettingsError` with the names it holds in `found`); its updates follow it. Resolves with what the
-   * host said. Absent: no Change origin.
-   */
-  changeOrigin?(name: string, source: string): Promise<string>;
-  /** Removes a user-scope skill or extension. */
-  remove?(kind: SettingsCatalogInstallKind, name: string): Promise<void>;
-  /** Updates a user-scope extension installed from a source. */
-  update?(kind: SettingsCatalogInstallKind, name: string): Promise<void>;
-}
-
-/** Opening a path of the host in another app. */
-export interface SettingsPaths {
-  /** Shows the file or folder in the system file manager. Absent: no reveal buttons. */
-  reveal?(path: string): Promise<void>;
-  /** Opens the file in the user's editor. Absent: no open buttons. */
-  open?(path: string): Promise<void>;
-}

package/src/settings/index.ts

@@ -1,32 +0,0 @@
-/**
- * `zidane-ui/settings`: the settings screen. `SettingsProvider` puts a
- * `SettingsHost` in context; `SettingsShell` draws the nav, search and the
- * open section of whatever sections an app lists (`SettingsSection`);
- * `SettingsHostSwitcher` picks which host's settings it shows;
- * `SettingsRowsPage` draws a page of zidane's settings rows; the section
- * chrome (`SettingsPanel`, `SettingsPanelBody`, `SettingsPanelActions`,
- * `SettingFocus`, `useSettingsSection`) and the catalog rows (`ToggleRow`,
- * `ChoiceRow`, `ValueChip`) build an app's own sections.
- */
-export * from './SettingsProvider';
-export * from './SettingsShell';
-export * from './SettingsHostSwitcher';
-export * from './SettingsNav';
-export * from './SettingsRowsPage';
-export * from './SettingsHeadingText';
-export * from './SettingsTutorial';
-export * from './rows';
-export {
-  SettingFocus,
-  SettingsPanel,
-  SettingsPanelBody,
-  SettingsPanelActions,
-  useSettingsSection,
-  type SettingFocusProps,
-  type SettingsPanelProps,
-  type SettingsPanelBodyProps,
-  type SettingsPanelActionsProps,
-  type SettingsSectionState,
-} from './section';
-export type { SettingsSection, SettingsSearchEntry } from './headless/registry';
-export * from './sections';