@silo-code/sdk 0.6.0

package/src/domain-types.ts

@@ -0,0 +1,252 @@
+/**
+ * Public domain types shared across the `ctx` services. These describe the
+ * persisted, user-facing shapes an extension sees through the consumer services
+ * (e.g. {@link WorkspaceService}, {@link TerminalService}, {@link ThemeService}).
+ * The host's internal state module re-exports these so app code names a single
+ * source of truth.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The kind of a terminal session.
+ *
+ * @category Core Types
+ * @public
+ */
+export type TerminalKind = "shell" | "claude" | "pi";
+
+/**
+ * A terminal tab record in a workspace.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface TerminalRecord {
+  id: string;
+  sessionId: string;
+  kind: TerminalKind;
+  title: string;
+  /**
+   * A user-assigned name (via the tab's "Rename…" menu). When set, it wins over
+   * the PTY-derived {@link TerminalRecord.title} and stays put until the user
+   * renames again or the terminal is closed. Cleared by renaming to an empty
+   * string, which hands the title back to PTY auto-derivation.
+   */
+  customName?: string;
+  /** Working directory override. Falls back to ws.folder when absent. */
+  cwd?: string;
+  /** ISO timestamp of the last output we observed; used to pick a workspace's "primary" terminal. */
+  lastActiveAt?: string;
+}
+
+/**
+ * The two modes of the one editor surface: a read-write text editor, or a
+ * read-only two-model diff. Absent on a record means `"text"`.
+ *
+ * @category Core Types
+ * @public
+ */
+export type EditorMode = "text" | "diff";
+
+/**
+ * An editor tab record in a workspace — a text editor or a diff.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface EditorRecord {
+  id: string;
+  /** null for an untitled buffer that hasn't been saved yet. */
+  filePath: string | null;
+  title: string;
+  /** When true, the tab is a temporary preview that gets replaced by the next single-click open. */
+  isPreview?: boolean;
+  /**
+   * Which mode this record renders in. Absent ⇒ `"text"`. A `"diff"` record
+   * additionally carries {@link EditorRecord.providerId}/{@link EditorRecord.args}
+   * and always has a non-null `filePath`.
+   */
+  mode?: EditorMode;
+  /**
+   * Diff mode only: which registered diff-content provider resolves the two
+   * sides (e.g. "silo.git"). The diff is content-agnostic — the provider owns
+   * what the two sides contain.
+   */
+  providerId?: string;
+  /**
+   * Diff mode only: serializable args the provider needs to (re)compute content
+   * on mount / restart.
+   */
+  args?: Record<string, unknown>;
+  /**
+   * The chosen editor *view* for this tab, referencing an {@link Editor.id}
+   * (e.g. `"text"`, `"silo.markdown-preview"`). Absent ⇒ the host renders the
+   * highest-priority matching editor (the default). Honored only when the
+   * referenced editor is still registered **and** still matches the file;
+   * otherwise the host falls back to priority resolution (so a stale value left
+   * by an uninstalled extension never breaks the tab). Orthogonal to
+   * {@link EditorRecord.mode}: `viewType` selects among `"text"`-mode editors; a
+   * `"diff"` record ignores it.
+   */
+  viewType?: string;
+}
+
+/**
+ * Which slot a side panel renders in.
+ *
+ * @category Core Types
+ * @public
+ */
+export type SidePanelSlot = "left" | "right" | "left-bottom" | "right-bottom";
+
+/**
+ * A workspace — the unit Silo switches between, keeping its terminals, editors,
+ * and layout alive. Read via {@link WorkspaceService}.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface Workspace {
+  id: string;
+  name: string;
+  folder: string;
+  /** Additional folders beyond the primary one. */
+  extraFolders?: string[];
+  createdAt: string;
+  lastOpenedAt: string;
+  terminals: TerminalRecord[];
+  /** Editor tabs — text editors and diffs alike (a diff is a record with `mode: "diff"`). */
+  editors: EditorRecord[];
+  dockLayout: unknown | null;
+  /** Scroll positions keyed by editor record ID: { top, left } in pixels. */
+  editorScrollPositions?: Record<string, { top: number; left: number }>;
+  /**
+   * ISO timestamp of when the workspace was soft-closed, or null/undefined
+   * if the workspace is open. Closed workspaces are hidden from the main
+   * list and surfaced in a "reopen" picker.
+   */
+  closedAt?: string | null;
+  /** Per-workspace side panel state — saved/restored on workspace switch. */
+  sidePanelLocations?: Record<string, SidePanelSlot>;
+  sidePanelOrder?: Record<string, number>;
+  activeSidePanelTabs?: Record<string, string>;
+  sidePanelScrollPositions?: Record<string, number>;
+  extensionState?: Record<string, Record<string, unknown>>;
+  leftPanelCollapsed?: boolean;
+  rightPanelCollapsed?: boolean;
+  /** ID of the current preview (temporary) editor, if any. */
+  previewEditorId?: string | null;
+}
+
+/**
+ * Light or dark theme base.
+ *
+ * @category Core Types
+ * @public
+ */
+export type ThemeBase = "dark" | "light";
+
+/**
+ * The full theme-override surface, in type form: every `--silo-*` token a theme
+ * preset's `vars` may recolor. Per the theming contract it spans **the design
+ * tokens' generic colors + font families** _and_ **all the component tokens**.
+ * The keys are the literal CSS custom-property names; renaming a key here
+ * renames the token in `theme.css` in lockstep. Font-sizes and the radius scale
+ * are intentionally absent (not theme-overridable).
+ *
+ * @see docs/architecture-audit/theming-contract.md
+ * @category Core Types
+ * @public
+ */
+export interface ThemeVars {
+  // ── Design tokens — generic colors (also consumable by extensions) ──
+  "--silo-color-bg": string;
+  "--silo-color-bg-hover": string;
+  "--silo-color-bg-active": string;
+  "--silo-color-text": string;
+  "--silo-color-text-hi": string;
+  "--silo-color-text-lo": string;
+  "--silo-color-accent": string;
+  "--silo-color-accent-2": string;
+  "--silo-color-border": string;
+  "--silo-color-border-strong": string;
+  "--silo-color-ok": string;
+  "--silo-color-warn": string;
+  "--silo-color-err": string;
+  "--silo-color-input-bg": string;
+  "--silo-color-input-text": string;
+  "--silo-color-button-bg": string;
+  "--silo-color-button-text": string;
+  // ── Design tokens — font families ──
+  "--silo-font-ui"?: string;
+  "--silo-font-mono"?: string;
+  // ── Component tokens — content (editor / terminal / tabs) colors ──
+  "--silo-content-text": string;
+  "--silo-content-terminal-bg": string;
+  "--silo-content-editor-bg": string;
+  "--silo-content-editor-selection": string;
+  "--silo-content-editor-selection-inactive": string;
+  "--silo-content-editor-text-dim": string;
+  "--silo-content-editor-text-faint": string;
+  "--silo-content-tab-bg": string;
+  "--silo-content-tab-tray-bg": string;
+  "--silo-content-tab-tray-text": string;
+  "--silo-content-tab-text": string;
+  "--silo-content-tab-text-inactive": string;
+  "--silo-content-tab-text-active": string;
+  // ── Component tokens — breadcrumb colors ──
+  "--silo-breadcrumb-bg": string;
+  "--silo-breadcrumb-text": string;
+  "--silo-breadcrumb-text-active": string;
+  "--silo-breadcrumb-icon": string;
+  // ── Component tokens — status bar colors ──
+  "--silo-statusbar-bg": string;
+  "--silo-statusbar-text": string;
+  "--silo-statusbar-bg-hover": string;
+  // ── Component tokens — side-tab colors ──
+  "--silo-tab-text": string;
+  "--silo-tab-text-active": string;
+  "--silo-tab-bg-hover": string;
+  "--silo-tab-border-active": string;
+  // ── Component tokens — menu / dropdown colors (the host <Menu> primitive) ──
+  "--silo-menu-bg": string;
+  "--silo-menu-text": string;
+  "--silo-menu-item-hover-bg": string;
+  "--silo-menu-border": string;
+  // ── Component tokens — modal shell (ctx.ui.confirm/prompt + the host Modal) ──
+  "--silo-modal-bg": string;
+  "--silo-modal-border": string;
+  // ── Component tokens — notify (toast) surface (ctx.ui.notify) ──
+  "--silo-notify-bg": string;
+  "--silo-notify-text": string;
+  "--silo-notify-text-hi": string;
+}
+
+/**
+ * A persisted custom theme.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface CustomTheme {
+  id: string;
+  /**
+   * `2` since the `--silo-*` token rename (theming-contract.md › Migration).
+   * v1 themes used the legacy bare names (`--bg`, `--text-hi`, …).
+   */
+  version: 2;
+  name: string;
+  base: ThemeBase;
+  colorScheme: "dark" | "light";
+  vars: Partial<ThemeVars>;
+}
+
+/**
+ * A {@link CustomTheme} without its `id` — the shape exported/imported as a
+ * shareable theme file.
+ *
+ * @category Core Types
+ * @public
+ */
+export type ThemeExport = Omit<CustomTheme, "id">;

package/src/editor-service.ts

@@ -0,0 +1,196 @@
+import type { Disposable } from "./types";
+
+// `ctx.editors` — the editor & document domain (public contract). Opening files
+// into editor tabs, the active-editor save/close commands, and the diff-content
+// provider registry. The host implementation lives in the extension host.
+
+/**
+ * Options for the editor open methods.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface OpenFileOptions {
+  /** Target workspace. Defaults to the active workspace. */
+  workspaceId?: string;
+  /**
+   * Open as a preview tab (single-click style — replaced by the next preview,
+   * italic title) instead of a permanent editor. Defaults to false.
+   */
+  preview?: boolean;
+  /**
+   * Open with a specific editor view — an {@link Editor.id}, e.g. from an
+   * "Open With" menu. Persisted on the tab as {@link EditorRecord.viewType}.
+   * Ignored if no registered editor with that id matches the path (the host
+   * falls back to the highest-priority match). When omitted the default view is
+   * used and any existing tab's view is left unchanged.
+   */
+  viewType?: string;
+}
+
+/**
+ * One editor view that can render a given file — its id, user-facing label, and
+ * whether it is the view the host would pick by default. Returned by
+ * {@link EditorService.editorsFor}; used to build "Open With" menus and the
+ * breadcrumb view-switcher.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface EditorViewInfo {
+  /** The editor's id (an {@link Editor.id}); pass back as `viewType`. */
+  id: string;
+  /** Human-facing label (falls back to {@link EditorViewInfo.id}). */
+  label: string;
+  /** True for the editor the host resolves by default (highest priority). */
+  isDefault: boolean;
+}
+
+/**
+ * Save callbacks an editor viewer registers via
+ * {@link EditorService.registerSaveHandler}, so the active-editor `save` /
+ * `saveAs` commands can dispatch to whichever editor is focused.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface EditorSaveHandlers {
+  /** Save the editor's contents. */
+  save: () => void | Promise<void>;
+  /** Save-as (prompt for a new path). Optional. */
+  saveAs?: () => void | Promise<void>;
+}
+
+/**
+ * What to open in a diff view, passed to {@link EditorService.openDiff}. The
+ * diff is **generic** — it renders two contents and knows nothing about where
+ * they come from. `providerId` names a {@link DiffContentProvider} (registered
+ * via {@link EditorService.registerDiffContentProvider}) that resolves the two
+ * sides; `args` is the serializable payload that provider needs (e.g. a git
+ * revision/mode) and is persisted so the content can be recomputed on restart.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface OpenDiffSpec {
+  /** The file the diff is OF — drives language detection, breadcrumb, title. */
+  filePath: string;
+  /** Id of the registered content provider that resolves the two sides. */
+  providerId: string;
+  /** Serializable args handed back to the provider to (re)compute content. */
+  args?: Record<string, unknown>;
+  /** Tab title. Defaults to the file's base name. */
+  title?: string;
+}
+
+/** The two sides of a diff, resolved by a {@link DiffContentProvider}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface DiffContent {
+  /** Left/original side. */
+  original: string;
+  /** Right/modified side. */
+  modified: string;
+}
+
+/**
+ * The request a {@link DiffContentProvider} receives to resolve a diff's two
+ * sides — the {@link OpenDiffSpec}'s `filePath`/`args` plus the folder of the
+ * workspace the diff lives in (the natural cwd for path-relative providers).
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface DiffContentRequest {
+  /** The file the diff is OF (from {@link OpenDiffSpec.filePath}). */
+  filePath: string;
+  /** The provider's args (from {@link OpenDiffSpec.args}). */
+  args?: Record<string, unknown>;
+  /** Folder of the workspace the diff lives in, or `null` if none. */
+  workspaceFolder: string | null;
+}
+
+/**
+ * Resolves the two sides of a diff on demand — called by the host whenever a
+ * diff panel mounts (open, tab switch, app restart), so content stays a pure
+ * computed view and never has to be persisted. Register one with
+ * {@link EditorService.registerDiffContentProvider}.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export type DiffContentProvider = (
+  request: DiffContentRequest,
+) => Promise<DiffContent>;
+
+/**
+ * The editor & document domain, exposed as {@link ExtensionContext.editors}.
+ * Open files into editor tabs, drive the active editor (save / close), and let
+ * editor viewers register save handlers. The single entry point for opening
+ * editors — prefer it over reaching into workspace/editor state.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface EditorService {
+  /**
+   * Open a file in an editor tab. Promotes an existing preview, focuses an
+   * already-open tab, or opens a new one.
+   */
+  open(path: string, opts?: OpenFileOptions): void;
+  /** Open a fresh untitled editor. */
+  openUntitled(opts?: OpenFileOptions): void;
+  /**
+   * Open a diff view. The content is supplied by the {@link OpenDiffSpec.providerId | provider}
+   * named in `spec` — the editor itself is content-agnostic.
+   */
+  openDiff(spec: OpenDiffSpec, opts?: OpenFileOptions): void;
+  /** Save the active editor. Returns false if there's no active saveable editor. */
+  save(): boolean;
+  /** Save-as the active editor. Returns false if unavailable. */
+  saveAs(): boolean;
+  /** Close the active dock panel. Returns false if there's nothing to close. */
+  closeActive(): boolean;
+  /**
+   * List the editor views that match `path` (or `null` for an untitled buffer),
+   * highest-priority first, each flagged whether it's the one the host resolves
+   * by default. Read-only enumeration for building "Open With" menus and the
+   * breadcrumb view-switcher. Returns `[]` only when nothing matches — in
+   * practice never empty for a real path, since the core text editor matches
+   * everything.
+   */
+  editorsFor(path: string | null): EditorViewInfo[];
+  /**
+   * Switch an already-open editor tab to a different view in place — without
+   * closing and reopening it — and persist the choice on the tab. No-op if the
+   * editor isn't found, `viewType` names no registered editor, or that editor
+   * doesn't match the tab's file. The panel remounts onto the new view, so
+   * per-instance state (scroll, selection) resets — expected, it's a different
+   * presenter.
+   */
+  setViewType(
+    editorId: string,
+    viewType: string,
+    opts?: { workspaceId?: string },
+  ): void;
+  /**
+   * Register save handlers for an editor instance (by its `editorId`), so the
+   * active-editor `save` / `saveAs` dispatch to it while it's focused. Dispose
+   * to unregister (do this when the editor unmounts).
+   */
+  registerSaveHandler(
+    editorId: string,
+    handlers: EditorSaveHandlers,
+  ): Disposable;
+  /**
+   * Register a {@link DiffContentProvider} under `providerId`. A diff opened
+   * with that `providerId` (see {@link OpenDiffSpec}) resolves its two sides
+   * through this provider, on every mount. Dispose to unregister.
+   */
+  registerDiffContentProvider(
+    providerId: string,
+    provider: DiffContentProvider,
+  ): Disposable;
+}

package/src/extension-storage.ts

@@ -0,0 +1,25 @@
+/**
+ * Namespaced, persisted key/value storage handed to side-panel components
+ * via `SidePanelProps.storage`. Each panel id gets its own bag; values are
+ * persisted alongside the rest of the app state.
+ *
+ * The store is hydrated asynchronously after the panels mount, so consumers
+ * that need to wait for restored values should check `props.hydrated` or
+ * use `subscribe` to re-read once it flips.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface ExtensionStorage {
+  /** Read a value. Returns `fallback` if the key is missing. */
+  get<T>(key: string): T | undefined;
+  get<T>(key: string, fallback: T): T;
+  /** Write a value. `undefined` deletes the key. */
+  set(key: string, value: unknown): void;
+  /**
+   * Subscribe to changes in this namespace. Called on any set within this
+   * namespace, and also whenever the underlying app state finishes hydrating
+   * (so callers can re-read after persisted state loads).
+   */
+  subscribe(listener: () => void): () => void;
+}

package/src/file-service.ts

@@ -0,0 +1,90 @@
+import type { Disposable } from "./types";
+
+// `ctx.files` — host-mediated filesystem access. The public contract; the host
+// implementation (a single chokepoint over the privileged Tauri fs/watch
+// commands) lives in the extension host.
+
+/**
+ * Metadata for a single directory entry, as returned by
+ * {@link FileService.readDir}.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface FileMeta {
+  /** The entry's base name (no path). */
+  name: string;
+  /** Absolute path to the entry. */
+  path: string;
+  /** True if the entry is a directory. */
+  isDir: boolean;
+  /** Size in bytes (0 for directories). */
+  size: number;
+  /** Last-modified time, milliseconds since the Unix epoch. */
+  modifiedMs: number;
+}
+
+/**
+ * A filesystem change event delivered to a {@link FileService.watch} listener,
+ * for changes under that watch's path.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface FileChangeEvent {
+  /** The paths that changed in this event. */
+  paths: string[];
+  /** The backend's change kind (e.g. `"create"`, `"modify"`, `"remove"`). */
+  kind: string;
+}
+
+/**
+ * The filesystem domain, exposed as {@link ExtensionContext.files}. All access
+ * is host-mediated: extensions read, write, and watch the filesystem through
+ * here rather than calling Tauri directly.
+ *
+ * **Paths are workspace-scoped.** A relative path resolves against the open
+ * workspace folder (`"src/index.ts"` → `<workspace>/src/index.ts`); an absolute
+ * path is allowed only if it falls inside a workspace folder. A path outside the
+ * workspace throws {@link PathDeniedError} unless the extension declared the
+ * matching {@link Permission} (`fs:read` for reads, `fs:write` for writes).
+ * First-party (bundled) extensions are unscoped. Prefer relative paths — they're
+ * portable across machines.
+ *
+ * Watching is host-owned: {@link FileService.watch} expresses intent — "tell me
+ * about changes under this path" — and the host owns the underlying OS
+ * watcher(s). Many in-workspace subscriptions are served from a single,
+ * ref-counted workspace watcher the host manages; extensions never start or
+ * stop watchers themselves, and each listener receives only events scoped to
+ * its path.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface FileService {
+  /** Read a file's contents as UTF-8 text. */
+  readText(path: string): Promise<string>;
+  /** Read a file's raw bytes. */
+  readBytes(path: string): Promise<ArrayBuffer>;
+  /** List a directory's immediate entries. */
+  readDir(path: string): Promise<FileMeta[]>;
+  /** Resolve true if a file or directory exists at `path`. */
+  pathExists(path: string): Promise<boolean>;
+  /** Write UTF-8 text to a file, creating or overwriting it. */
+  writeText(path: string, content: string): Promise<void>;
+  /** Create a directory (and any missing parents). */
+  createDir(path: string): Promise<void>;
+  /** Rename / move a file or directory. */
+  rename(oldPath: string, newPath: string): Promise<void>;
+  /** Delete a file or directory. */
+  delete(path: string): Promise<void>;
+  /** Reveal a path in the OS file manager (Finder / Explorer). */
+  reveal(path: string): Promise<void>;
+  /**
+   * Watch `path` recursively, invoking `listener` for each change under it.
+   * Returns a {@link Disposable} that stops listening when disposed. Watcher
+   * lifecycle is the host's concern — in-workspace paths ride the host's
+   * ref-counted workspace watcher rather than each spinning up its own.
+   */
+  watch(path: string, listener: (event: FileChangeEvent) => void): Disposable;
+}