@silo-code/sdk 0.6.0

package/src/index.ts

@@ -0,0 +1,151 @@
+/**
+ * The public Silo extension API surface — the single curated entry point an
+ * extension author imports from. This is the seed of the future `@silo-code/sdk`
+ * package: it re-exports **only** the blessed, permanently supported types.
+ * Anything not re-exported here is host-internal and may change without notice.
+ *
+ * It is also the entry point the API-reference generator (TypeDoc) reads, so
+ * the published reference is exactly this surface — no more, no less.
+ *
+ * @packageDocumentation
+ */
+
+// Core contract + contribution-point types.
+export type {
+  Disposable,
+  DockPanelApi,
+  EditorProps,
+  EditorCapabilities,
+  Editor,
+  NewFileTemplate,
+  FileType,
+  Command,
+  MenuId,
+  MenuItemContribution,
+  Keybinding,
+  SidePanelProps,
+  SidePanel,
+  DockPanelKind,
+  StatusItem,
+  SettingsPage,
+  ExtensionContext,
+  Extension,
+  ExtensionHandle,
+} from "./types";
+
+// Public domain types (the persisted shapes surfaced through the services).
+// TerminalKind/TerminalRecord and the theme types are re-exported via their
+// service modules below; these are the remaining ones consumers can name.
+export type {
+  Workspace,
+  EditorMode,
+  EditorRecord,
+  SidePanelSlot,
+} from "./domain-types";
+
+// Consumer services exposed on the ExtensionContext.
+export type {
+  WorkspaceService,
+  WorkspaceState,
+  CreateWorkspaceInput,
+} from "./workspace-service";
+export type {
+  EditorService,
+  EditorSaveHandlers,
+  OpenFileOptions,
+  EditorViewInfo,
+  OpenDiffSpec,
+  DiffContent,
+  DiffContentRequest,
+  DiffContentProvider,
+} from "./editor-service";
+export type {
+  LayoutService,
+  LayoutState,
+  SidePanelColumnState,
+  SideLocation,
+} from "./layout-service";
+export type {
+  ProcessService,
+  ProcessSession,
+  ProcessSpawnOptions,
+  ProcessExecOptions,
+  ProcessExecResult,
+} from "./process-service";
+export type {
+  TerminalService,
+  CreateTerminalInput,
+  TerminalKind,
+  TerminalRecord,
+} from "./terminal-service";
+export type { FileService, FileMeta, FileChangeEvent } from "./file-service";
+// The permission surface: the capability vocabulary an extension declares, and
+// the error the host throws when an extension reaches outside the workspace
+// without the matching grant. `PathDeniedError` is a class (a runtime value).
+export type { Permission } from "./permissions";
+export { PathDeniedError } from "./permissions";
+// The theme domain: the consumer service + its state/resolve shapes, the
+// `ThemePreset` contribution type (registered via ctx.registerThemePreset), and
+// the underlying theme types (re-exported from ./domain-types via theme-service).
+export type {
+  ThemeService,
+  ThemeState,
+  ThemePreset,
+  ResolvedTheme,
+  ThemeBase,
+  ThemeVars,
+  CustomTheme,
+  ThemeExport,
+} from "./theme-service";
+export type { ExtensionStorage } from "./extension-storage";
+// The drag-and-drop domain: the consumer service + its payload/handler shapes.
+// DND_MIME is a value (the well-known MIME vocabulary), so it's a runtime export.
+export type {
+  DndService,
+  DndItem,
+  DndMime,
+  DragInit,
+  DndMode,
+  DropContext,
+  DropTargetHandlers,
+} from "./dnd-service";
+export { DND_MIME } from "./dnd-service";
+// The user-interaction domain: native pickers + toast notifications + menus,
+// plus the file-filter shape the pickers accept, the menu item/entry shapes
+// `showMenu` accepts, and the modal-chrome options `showModal` accepts.
+export type {
+  UiService,
+  FileFilter,
+  MenuItem,
+  MenuItemTrailing,
+  MenuSeparator,
+  MenuHeader,
+  MenuEntry,
+  ShowMenuOptions,
+  ConfirmOptions,
+  PromptOptions,
+  ModalOptions,
+  NotifyAction,
+  NotifyOptions,
+} from "./ui-service";
+
+// Context keys referenced by `when` predicates on menu items / keybindings.
+export type { ContextKeys } from "./context-keys";
+
+// Runtime helpers. The one blessed way for an extension to read a `ctx`
+// service's reactive state in React — replaces hand-rolled useSyncExternalStore.
+export { useServiceState } from "./use-service-state";
+export type { ReactiveService } from "./use-service-state";
+// Headless keyboard navigation for a focus group (list / menu / toolbar / …):
+// one tab stop, arrow/Home/End movement, the WebKit-safe keyboard ring. The
+// `focusGroupNextIndex` helper is the pure roving-index core for widgets that
+// can't use the focus-driven hook (e.g. menus driven by a document listener).
+export { useFocusGroup, focusGroupNextIndex } from "./use-focus-group";
+export type {
+  FocusGroup,
+  FocusGroupOptions,
+  FocusGroupContainerProps,
+  FocusGroupItemProps,
+  FocusGroupOrientation,
+  FocusGroupNavQuery,
+} from "./use-focus-group";

package/src/layout-service.ts

@@ -0,0 +1,49 @@
+import type { Disposable } from "./types";
+
+/**
+ * Which side column a layout operation targets.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type SideLocation = "left" | "right";
+
+/**
+ * Collapse state for one side column.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface SidePanelColumnState {
+  /** True when the column is collapsed (hidden). */
+  collapsed: boolean;
+}
+
+/**
+ * An immutable view of side-column layout state.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface LayoutState {
+  left: SidePanelColumnState;
+  right: SidePanelColumnState;
+}
+
+/**
+ * Consumer API for app layout, exposed as {@link ExtensionContext.layout}.
+ * Read side-panel collapse state and drive it.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface LayoutService {
+  /** Current frozen layout state. */
+  getState(): LayoutState;
+  /** Subscribe to layout changes; dispose to stop. */
+  subscribe(listener: (s: LayoutState) => void): Disposable;
+  /** Toggle a side column between collapsed and expanded. */
+  toggleSidePanel(location: SideLocation): void;
+  /** Set a side column's collapsed state explicitly. */
+  setSidePanelCollapsed(location: SideLocation, collapsed: boolean): void;
+}

package/src/permissions.ts

@@ -0,0 +1,55 @@
+// The extension permission surface — what an extension may declare it needs
+// (`silo.permissions` in its manifest) and the error the host throws when an
+// extension reaches outside the workspace without the matching grant. See the
+// "Permissions & access" guide and ADR 0015 (phased security model).
+
+/**
+ * A capability an extension declares in its manifest (`silo.permissions`) to
+ * request access **beyond the open workspace**. With none declared, an
+ * extension's {@link FileService} / {@link ProcessService} access is confined to
+ * the workspace folder(s); each permission lifts one part of that confinement,
+ * and the user consents to the set at install.
+ *
+ * - `fs:read` — read files outside the workspace.
+ * - `fs:write` — write files outside the workspace.
+ * - `process` — run commands with a working directory outside the workspace.
+ * - `network` — make outbound network requests. Declarative consent only until
+ *   sandboxed execution lands (in-process code can reach the network directly);
+ *   declare it so the capability is reviewable and shown at install.
+ *
+ * @category Extension Contract
+ * @public
+ */
+export type Permission = "fs:read" | "fs:write" | "process" | "network";
+
+/**
+ * Thrown by {@link FileService} and {@link ProcessService} when an extension
+ * touches a path — or runs a process with a working directory — outside the open
+ * workspace without the matching {@link Permission}. Catch it and degrade
+ * gracefully, the same way you'd handle a missing file:
+ *
+ * ```ts
+ * try {
+ *   const text = await ctx.files.readText(path);
+ * } catch (err) {
+ *   if (err instanceof PathDeniedError) showMessage("That file is outside the workspace.");
+ * }
+ * ```
+ *
+ * @category Core Types
+ * @public
+ */
+export class PathDeniedError extends Error {
+  /** The offending path, exactly as the extension passed it. */
+  readonly path: string;
+
+  constructor(path: string, message?: string) {
+    super(message ?? `Path is outside the workspace: ${path}`);
+    this.name = "PathDeniedError";
+    this.path = path;
+    // Restore the prototype chain so `instanceof` works across the down-leveled
+    // class output the SDK ships (and across the host↔extension boundary, where
+    // there's a single shared SDK instance).
+    Object.setPrototypeOf(this, PathDeniedError.prototype);
+  }
+}

package/src/process-service.ts

@@ -0,0 +1,143 @@
+import type { Disposable } from "./types";
+
+// `ctx.process` — persistent process / PTY sessions that survive app restarts.
+// The core primitive under the terminal (and future task runners / REPLs).
+
+/**
+ * Options for spawning a process session. Today sessions are shell PTYs, so
+ * `cwd` is required (the webview has no ambient working directory).
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface ProcessSpawnOptions {
+  /**
+   * Working directory the session starts in. Must resolve inside the open
+   * workspace unless the extension declared the `process` {@link Permission}
+   * (first-party extensions are unscoped); otherwise throws
+   * {@link PathDeniedError}.
+   */
+  cwd: string;
+  /** Initial column count. */
+  cols?: number;
+  /** Initial row count. */
+  rows?: number;
+}
+
+/**
+ * A live handle to one persistent process session, returned by
+ * {@link ProcessService.spawn} / {@link ProcessService.attach}. The underlying
+ * session **survives app restarts** — re-`attach` by {@link ProcessSession.id}
+ * to reconnect to a still-running session.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface ProcessSession {
+  /** Stable session id; pass to {@link ProcessService.attach} to reconnect. */
+  readonly id: string;
+  /** Write input to the session (e.g. keystrokes). */
+  write(data: string): void;
+  /** Notify the session its viewport size changed. */
+  resize(cols: number, rows: number): void;
+  /** Terminate the session and release it. */
+  kill(): Promise<void>;
+  /** Fetch the persisted output buffer (to restore a view after re-attach). */
+  getBuffer(): Promise<string>;
+  /** Persist an output buffer for later restore. */
+  saveBuffer(data: string): Promise<void>;
+  /** Subscribe to output data. Dispose to stop listening. */
+  onData(listener: (data: string) => void): Disposable;
+  /** Subscribe to session exit. Dispose to stop listening. */
+  onExit(listener: (exitCode: number) => void): Disposable;
+}
+
+/**
+ * Options for {@link ProcessService.exec}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface ProcessExecOptions {
+  /**
+   * Working directory to run the command in. Defaults to the open **workspace
+   * folder** when omitted — the right cwd for CLI tools (git, formatters,
+   * linters) that operate on a repo. A `cwd` outside the workspace throws
+   * {@link PathDeniedError} unless the extension declared the `process`
+   * {@link Permission}. First-party (bundled) extensions are unscoped.
+   */
+  cwd?: string;
+}
+
+/**
+ * The captured result of a one-shot subprocess, returned by
+ * {@link ProcessService.exec}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface ProcessExecResult {
+  /** Everything the command wrote to standard output. */
+  stdout: string;
+  /** Everything the command wrote to standard error. */
+  stderr: string;
+  /**
+   * The process exit code (`0` conventionally means success), or `-1` if the
+   * process was terminated by a signal. A non-zero `code` is **not** an error —
+   * `exec` resolves regardless; inspect `code`/`stderr` to decide.
+   */
+  code: number;
+}
+
+/**
+ * Persistent process / PTY sessions that **survive app restarts** — the core
+ * primitive under the terminal (and future task runners, REPLs) — plus one-shot
+ * {@link ProcessService.exec | exec} for fire-and-forget subprocess execution.
+ * Exposed as {@link ExtensionContext.process}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface ProcessService {
+  /** Spawn a new session in `opts.cwd`. */
+  spawn(opts: ProcessSpawnOptions): Promise<ProcessSession>;
+  /**
+   * Re-attach to an existing session by id (e.g. after an app restart). Rejects
+   * with a 404-style error if the session no longer exists.
+   */
+  attach(
+    id: string,
+    opts?: { cols?: number; rows?: number },
+  ): Promise<ProcessSession>;
+  /**
+   * Run a one-shot command and resolve with its captured output — for
+   * extensions that wrap a CLI (git, formatters, linters) rather than drive an
+   * interactive shell. Use {@link ProcessService.spawn | spawn} for long-lived
+   * interactive sessions instead.
+   *
+   * Runs **off the UI thread**, so a slow or network-bound command never
+   * stutters the app. The returned promise rejects only if the process could
+   * not be spawned (e.g. the command was not found); a command that runs but
+   * exits non-zero **resolves** — check {@link ProcessExecResult.code} and
+   * {@link ProcessExecResult.stderr}.
+   *
+   * @param command - Executable to run (resolved via `PATH`), e.g. `"git"`.
+   * @param args - Arguments passed verbatim — not shell-interpreted, so no
+   *   quoting/escaping concerns and no shell-injection surface.
+   * @param options - Optional {@link ProcessExecOptions} (e.g. `cwd`).
+   * @example
+   * ```ts
+   * const { stdout, code } = await ctx.process.exec(
+   *   "git",
+   *   ["status", "--porcelain=v2"],
+   *   { cwd: workspaceFolder },
+   * );
+   * if (code === 0) parseStatus(stdout);
+   * ```
+   */
+  exec(
+    command: string,
+    args: string[],
+    options?: ProcessExecOptions,
+  ): Promise<ProcessExecResult>;
+}

package/src/terminal-service.ts

@@ -0,0 +1,41 @@
+import type { TerminalKind, TerminalRecord } from "./domain-types";
+
+// Re-export the terminal domain types so consumers can name them from the SDK.
+export type { TerminalKind, TerminalRecord } from "./domain-types";
+
+/**
+ * Input for {@link TerminalService.create}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface CreateTerminalInput {
+  /** Terminal kind — `"shell"` (default), `"claude"`, or `"pi"`. */
+  kind?: TerminalKind;
+  /** Working directory; falls back to the workspace folder when absent. */
+  cwd?: string;
+  /** Target workspace; defaults to the active workspace. */
+  workspaceId?: string;
+}
+
+/**
+ * Consumer API for the terminal domain, exposed as
+ * {@link ExtensionContext.terminals}. The terminal is a core feature — a
+ * built-in DockKind like the editor — so this mirrors {@link EditorService}:
+ * `create` opens a terminal tab in a workspace, and `closeWorkspace` reaps a
+ * workspace's terminals (used when a workspace is deleted). The tab itself is
+ * rendered by the core dock from the workspace's terminal records.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface TerminalService {
+  /**
+   * Open a new terminal in a workspace (defaults to the active one). Returns the
+   * created {@link TerminalRecord}; the PTY session spawns lazily when its tab
+   * mounts.
+   */
+  create(input?: CreateTerminalInput): TerminalRecord | undefined;
+  /** Close and kill every terminal in a workspace (e.g. on workspace delete). */
+  closeWorkspace(workspaceId: string): void;
+}

package/src/theme-service.ts

@@ -0,0 +1,102 @@
+import type { Disposable } from "./types";
+import type {
+  ThemeBase,
+  ThemeVars,
+  CustomTheme,
+  ThemeExport,
+} from "./domain-types";
+
+// Re-export the theme domain types so consumers can name them from the SDK.
+export type {
+  ThemeBase,
+  ThemeVars,
+  CustomTheme,
+  ThemeExport,
+} from "./domain-types";
+
+/**
+ * A selectable theme contributed via
+ * {@link ExtensionContext.registerThemePreset}. Built-in presets (Tokyo Night,
+ * Solarized Light, Gruvbox Dark, …) are registered by the `theme-presets`
+ * extension; core ships only Dark and Light. A preset's {@link ThemePreset.vars}
+ * are injected as CSS custom properties when it is the active theme.
+ *
+ * @category Registration
+ * @public
+ */
+export interface ThemePreset {
+  /** Unique id (also the persisted `activeThemeId` when selected). */
+  id: string;
+  /** Display name shown in the theme picker. */
+  name: string;
+  /** Dark or light — drives the Monaco/xterm base and the `data-theme` attribute. */
+  base: ThemeBase;
+  /** The CSS `color-scheme` for native controls. */
+  colorScheme: "dark" | "light";
+  /** CSS variable overrides applied on top of the base palette in `theme.css`. */
+  vars: Partial<ThemeVars>;
+}
+
+/**
+ * A theme id resolved to its base + effective variables — what the theme picker
+ * renders swatches from, returned by {@link ThemeService.resolve}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface ResolvedTheme {
+  base: ThemeBase;
+  colorScheme: "dark" | "light";
+  vars: Partial<ThemeVars>;
+}
+
+/**
+ * An immutable, frozen view of theme state, returned by
+ * {@link ThemeService.getState} and delivered to subscribers — read access
+ * without a Valtio dependency. `presets` is part of the state (not a static
+ * read) because presets are dynamic: extensions register and unregister them at
+ * runtime.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface ThemeState {
+  /** The active theme's id (a preset id or a custom theme id). */
+  activeId: string;
+  /** Core Dark/Light followed by every registered preset, in registration order. */
+  presets: readonly ThemePreset[];
+  /** The user's custom themes, loaded from disk. */
+  customThemes: readonly CustomTheme[];
+}
+
+/**
+ * Consumer API for the theme domain, exposed as {@link ExtensionContext.theme}.
+ * Read via {@link ThemeService.getState | getState} /
+ * {@link ThemeService.subscribe | subscribe} (e.g. with `useSyncExternalStore`);
+ * drive via {@link ThemeService.setActive | setActive} and the custom-theme
+ * methods. Contributing a *new* preset is a separate concern —
+ * {@link ExtensionContext.registerThemePreset}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface ThemeService {
+  /** Current frozen view of theme state. */
+  getState(): ThemeState;
+  /** Subscribe to theme-state changes (active theme, custom themes, or presets). */
+  subscribe(listener: (s: ThemeState) => void): Disposable;
+  /** Set the active theme by id (a built-in preset, registered preset, or custom). */
+  setActive(id: string): void;
+  /** Resolve a theme id to its base + effective vars (for previews/swatches). */
+  resolve(id: string): ResolvedTheme;
+  /** Persist a custom theme to disk and refresh the in-memory list. */
+  saveCustom(theme: CustomTheme): Promise<void>;
+  /** Delete a custom theme from disk and refresh the in-memory list. */
+  deleteCustom(id: string): Promise<void>;
+  /** Reload custom themes from disk into the store. */
+  reloadCustom(): Promise<void>;
+  /** Strip the id from a custom theme for sharing/serialization. */
+  exportTheme(theme: CustomTheme): ThemeExport;
+  /** Validate/parse imported JSON into a custom theme (assigns a fresh id). */
+  importTheme(data: unknown): CustomTheme;
+}