@silo-code/sdk 0.21.0 → 0.23.0

package/src/editor-service.ts

@@ -1,8 +1,11 @@
 import type { Disposable } from "./types";
+import type { Event } from "./event";
+import type { EditorMode } from "./domain-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.
+// into editor tabs, the active-editor save/close commands, the diff-content
+// provider registry, and reactive active-editor state. The host implementation
+// lives in the extension host.
 
 /**
  * Options for the editor open methods.
@@ -65,7 +68,7 @@ export interface EditorViewInfo {
 }
 
 /**
- * Save callbacks an editor viewer registers via
+ * Save callbacks an editor registers via
  * {@link EditorService.registerSaveHandler}, so the active-editor `save` /
  * `saveAs` commands can dispatch to whichever editor is focused.
  *
@@ -143,11 +146,78 @@ export type DiffContentProvider = (
   request: DiffContentRequest,
 ) => Promise<DiffContent>;
 
+/**
+ * A point-in-time snapshot of the focused editor tab. Part of
+ * {@link EditorsState}, returned by {@link EditorService.getState} and
+ * delivered to {@link EditorService.subscribe} listeners.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface ActiveEditorInfo {
+  /** The focused editor tab's record id — matches {@link EditorRecord.id}. */
+  editorId: string;
+  /**
+   * The absolute file path of the focused tab, or `null` for an untitled
+   * buffer.
+   */
+  filePath: string | null;
+  /**
+   * The {@link Editor.id} of the presenter rendering the tab
+   * (e.g. `"core.text-editor"`, `"silo.markdown-preview"`). Empty string
+   * when the presenter could not be resolved (rare: editor registered after
+   * the tab was opened).
+   */
+  viewId: string;
+  /** Whether the tab is in text or diff mode. */
+  mode: EditorMode;
+}
+
+/**
+ * A frozen, referentially-stable snapshot of editor domain state. Returned by
+ * {@link EditorService.getState} and delivered to
+ * {@link EditorService.subscribe} listeners.
+ *
+ * Compatible with `useServiceState` — just pass `ctx.editors` directly.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface EditorsState {
+  /**
+   * The focused editor tab, or `null` when the active dock panel is not an
+   * editor tab (e.g. a terminal, a dock panel kind, or nothing at all).
+   */
+  active: ActiveEditorInfo | null;
+  /**
+   * `true` once the persisted workspace state has loaded from disk. Matches
+   * `WorkspaceState.hydrated` — guard state-restoring code on this flag.
+   */
+  hydrated: boolean;
+}
+
+/**
+ * Payload delivered to {@link EditorService.onDidSave} listeners after an
+ * editor tab's contents are written to disk.
+ *
+ * @category Consumer Services
+ * @public
+ */
+export interface EditorSaveEvent {
+  /** The saved tab's editor record id — matches {@link EditorRecord.id}. */
+  editorId: string;
+  /**
+   * Absolute path the contents were written to. For a save-as (or first save
+   * of an untitled buffer) this is the newly chosen path, not the old one.
+   */
+  filePath: string;
+}
+
 /**
  * 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.
+ * editors register save handlers. The single entry point for opening editors —
+ * prefer it over reaching into workspace/editor state.
  *
  * @category Consumer Services
  * @public
@@ -211,4 +281,70 @@ export interface EditorService {
     providerId: string,
     provider: DiffContentProvider,
   ): Disposable;
+  /**
+   * The current buffer text of an open editor tab, including unsaved edits.
+   *
+   * Resolves `undefined` when the tab isn't text-backed (e.g. the image
+   * viewer) or hasn't mounted yet — a lazy-mounted dock panel is **not**
+   * force-mounted to read its text. It is async precisely because the text
+   * lives in the mounted editor component, not in host state.
+   *
+   * @example
+   * ```ts
+   * const text = await ctx.editors.getText(editorId);
+   * if (text !== undefined) ctx.log.info(`${text.length} chars`);
+   * ```
+   */
+  getText(editorId: string): Promise<string | undefined>;
+  /**
+   * Whether an open editor tab has unsaved changes. Returns `false` for an
+   * unknown id or a tab that isn't mounted / text-backed.
+   */
+  isDirty(editorId: string): boolean;
+  /**
+   * Fires after an editor tab's contents are saved to disk — a formatter,
+   * linter, or build-on-save extension's entry point. See {@link Event}.
+   *
+   * @example
+   * ```ts
+   * ctx.subscriptions.push(
+   *   ctx.editors.onDidSave(({ editorId, filePath }) => {
+   *     ctx.log.info(`saved ${filePath}`);
+   *   }),
+   * );
+   * ```
+   */
+  onDidSave: Event<EditorSaveEvent>;
+  /**
+   * Current frozen snapshot of editor state. The returned object is
+   * referentially stable between renders — `getState() === getState()` when
+   * nothing has changed, which satisfies `useSyncExternalStore`'s contract and
+   * means `useServiceState(ctx.editors)` works without extra memoization.
+   *
+   * @example
+   * ```ts
+   * const { active } = ctx.editors.getState();
+   * if (active) ctx.log.info(`Active file: ${active.filePath ?? "(untitled)"}`);
+   * ```
+   */
+  getState(): EditorsState;
+  /**
+   * Subscribe to changes in the active editor. The listener is called whenever
+   * `active` changes (tab focus moves, workspace switches, editor opens or
+   * closes) or `hydrated` flips. Returns a {@link Disposable} that cancels the
+   * subscription.
+   *
+   * Use `useServiceState(ctx.editors)` in React components instead of calling
+   * `subscribe` directly — it wraps `getState` + `subscribe` for you.
+   *
+   * @example
+   * ```ts
+   * ctx.subscriptions.push(
+   *   ctx.editors.subscribe(({ active }) => {
+   *     statusItem.setTitle(active?.filePath ?? "No file");
+   *   }),
+   * );
+   * ```
+   */
+  subscribe(listener: (state: EditorsState) => void): Disposable;
 }

package/src/event.ts

@@ -0,0 +1,28 @@
+import type { Disposable } from "./types";
+
+/**
+ * A subscribable event: call it with a listener and receive a
+ * {@link Disposable} that cancels the subscription. Modeled on VS Code's
+ * `Event<T>` convention.
+ *
+ * Services that emit events expose a member typed as `Event<T>` — the
+ * consuming extension calls it directly and pushes the returned disposable
+ * onto `ctx.subscriptions`:
+ *
+ * @example
+ * ```ts
+ * ctx.subscriptions.push(
+ *   ctx.editors.onDidSave(({ editorId, filePath }) => {
+ *     console.log("saved", filePath);
+ *   }),
+ * );
+ * ```
+ *
+ * **Host-side:** the matching emitter (`EventEmitter<T>`) lives in the
+ * extension-host package (not the SDK). Only the subscribable `Event<T>` type
+ * is public — extensions never construct emitters.
+ *
+ * @category Core Types
+ * @public
+ */
+export type Event<T> = (listener: (e: T) => void) => Disposable;

package/src/file-service.ts

@@ -82,15 +82,46 @@ export interface FileService {
   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`. */
+  /**
+   * Resolve true if a file or directory exists at `path`. Prefer
+   * {@link FileService.stat} when you also need the entry's metadata — `stat`
+   * returning non-`null` subsumes this check in one call.
+   */
   pathExists(path: string): Promise<boolean>;
+  /**
+   * Metadata for a single path, following symlinks, or `null` if nothing
+   * exists there. Resolving `null` (rather than rejecting) for an absent path
+   * is deliberate — it makes `stat` a one-call replacement for
+   * {@link FileService.pathExists} that also returns size / mtime / type.
+   * Rejects only on a real I/O error (e.g. a permission failure).
+   */
+  stat(path: string): Promise<FileMeta | null>;
   /** Write UTF-8 text to a file, creating or overwriting it. */
   writeText(path: string, content: string): Promise<void>;
+  /**
+   * Write raw bytes to a file, creating or overwriting it (and creating any
+   * missing parent directories). The byte-oriented counterpart to
+   * {@link FileService.writeText} / {@link FileService.readBytes} — use it for
+   * binary assets (images, archives) where `writeText` would corrupt the data.
+   */
+  writeBytes(path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
   /** Create a directory (and any missing parents). */
   createDir(path: string): Promise<void>;
+  /**
+   * Copy a file or directory from `src` to `dest`, recursively for
+   * directories, creating any missing parent directories. Requires read access
+   * to `src` and write access to `dest` (both are workspace-scoped). Overwrites
+   * existing files at the destination.
+   */
+  copy(src: string, dest: string): Promise<void>;
   /** Rename / move a file or directory. */
   rename(oldPath: string, newPath: string): Promise<void>;
-  /** Delete a file or directory. */
+  /**
+   * **Permanently** delete a file or directory (directories are removed
+   * recursively). This does **not** move the entry to the OS trash/recycle
+   * bin — the delete is irreversible, so confirm destructive removals with the
+   * user first. Rejects if the path does not exist.
+   */
   delete(path: string): Promise<void>;
   /** Reveal a path in the OS file manager (Finder / Explorer). */
   reveal(path: string): Promise<void>;

package/src/index.ts

@@ -1,10 +1,16 @@
 /**
- * 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.
+ * The `@silo-code/sdk` public surface — the single curated entry point an
+ * extension author imports from. Re-exports **only** the blessed, permanently
+ * supported types and runtime helpers. 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
+ * **What's here:** the types-first extension contract (see `types.ts`) plus a
+ * small set of blessed runtime helpers (`Tooltip`, `useFocusGroup`,
+ * `useServiceState`, `DND_MIME`, `PathDeniedError`, `NetworkError`). The SDK
+ * peer-depends on React 19; changes to the runtime helpers can be breaking
+ * even when the types are unchanged.
+ *
+ * This is also the entry point the API-reference generator (TypeDoc) reads, so
  * the published reference is exactly this surface — no more, no less.
  *
  * @packageDocumentation
@@ -66,6 +72,9 @@ export type {
   DiffContent,
   DiffContentRequest,
   DiffContentProvider,
+  ActiveEditorInfo,
+  EditorsState,
+  EditorSaveEvent,
 } from "./editor-service";
 export type {
   LayoutService,
@@ -167,6 +176,7 @@ export type {
   NetworkService,
   NetworkRequestOptions,
   NetworkResponse,
+  NetworkBytesResponse,
 } from "./network-service";
 
 // Static host-platform metadata: OS, CPU arch, and Silo version.
@@ -180,6 +190,15 @@ export type { LogService, LogLevel } from "./output-service";
 // Context keys referenced by `when` predicates on menu items / keybindings.
 export type { ContextKeys } from "./context-keys";
 
+// Typed event primitive: a subscribable Event<T> that returns a Disposable.
+// The matching host-side emitter is internal to the extension-host package.
+export type { Event } from "./event";
+
+// Pure path utilities — cross-platform replacement for `node:path` (banned in
+// extensions). All outputs use forward-slash separators. Both "/" and "\" are
+// accepted as input. Exported as a namespaced `path` object.
+export { path } from "./path";
+
 // Tooltip — the same styled hover popup the host uses in the status bar.
 // Extensions use this instead of native `title` attributes to match host chrome.
 export { Tooltip } from "./Tooltip";

package/src/network-service.ts

@@ -44,8 +44,12 @@ export interface NetworkRequestOptions {
   method?: "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH";
   /** Request headers to send. */
   headers?: Record<string, string>;
-  /** Request body (string). Only meaningful for methods that carry a body. */
-  body?: string;
+  /**
+   * Request body. A string is sent as-is; an `ArrayBuffer` / `Uint8Array` is
+   * sent as raw bytes (e.g. uploading a file). Only meaningful for methods that
+   * carry a body.
+   */
+  body?: string | ArrayBuffer | Uint8Array;
   /** Follow HTTP redirects. Defaults to `true`. */
   followRedirects?: boolean;
   /** Request timeout in milliseconds. Omit for the platform default (~30 s). */
@@ -72,6 +76,24 @@ export interface NetworkResponse {
   finalUrl: string;
 }
 
+/**
+ * Response from {@link NetworkService.fetchBytes} — identical to
+ * {@link NetworkResponse} but with the body delivered as raw bytes.
+ *
+ * @category Core Types
+ * @public
+ */
+export interface NetworkBytesResponse {
+  /** HTTP status code. */
+  status: number;
+  /** Response headers, lowercased (multi-value joined with `", "`). */
+  headers: Record<string, string>;
+  /** Response body as raw bytes. */
+  body: ArrayBuffer;
+  /** Final URL after redirects. */
+  finalUrl: string;
+}
+
 /**
  * Server-side HTTP client exposed as {@link ExtensionContext.net}. Requests
  * run in the Rust backend via `reqwest`, so they bypass the browser's CORS
@@ -104,6 +126,33 @@ export interface NetworkService {
    */
   fetch(url: string, options?: NetworkRequestOptions): Promise<NetworkResponse>;
 
+  /**
+   * Like {@link NetworkService.fetch}, but resolves the response body as raw
+   * bytes ({@link NetworkBytesResponse}) instead of decoding it as UTF-8 text —
+   * for downloading images, archives, or any binary payload.
+   *
+   * @param url - The URL to fetch.
+   * @param options - Method, headers, body, redirect and timeout controls. The
+   *   body may itself be binary (`ArrayBuffer` / `Uint8Array`).
+   * @throws {@link NetworkError} if the request fails.
+   *
+   * @remarks
+   * The body rides Tauri's binary IPC channel (no base64), but the whole
+   * response is still buffered in memory on both sides — suitable for typical
+   * asset downloads (up to a few tens of MB), not for streaming multi-hundred-MB
+   * files.
+   *
+   * @example
+   * ```ts
+   * const { body } = await ctx.net.fetchBytes("https://example.com/logo.png");
+   * await ctx.files.writeBytes("logo.png", body);
+   * ```
+   */
+  fetchBytes(
+    url: string,
+    options?: NetworkRequestOptions,
+  ): Promise<NetworkBytesResponse>;
+
   /**
    * Send a `HEAD` request and return only the response headers — no body is
    * downloaded. More efficient than {@link NetworkService.fetch} when you only

package/src/path.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from "vitest";
+import { path } from "./path";
+
+describe("path.normalize", () => {
+  it("collapses dot segments", () =>
+    expect(path.normalize("a/./b")).toBe("a/b"));
+  it("resolves dot-dot segments", () =>
+    expect(path.normalize("a/b/../c")).toBe("a/c"));
+  it("converts backslash to forward-slash", () =>
+    expect(path.normalize("a\\b")).toBe("a/b"));
+  it("collapses duplicate slashes", () =>
+    expect(path.normalize("a//b")).toBe("a/b"));
+  it("preserves POSIX absolute", () =>
+    expect(path.normalize("/a/b")).toBe("/a/b"));
+  it("handles Windows drive", () =>
+    expect(path.normalize("C:\\a\\b")).toBe("C:/a/b"));
+  it("handles Windows drive with forward-slash", () =>
+    expect(path.normalize("C:/a/b")).toBe("C:/a/b"));
+  it("stays at root when dot-dot exceeds root", () =>
+    expect(path.normalize("/a/../..")).toBe("/"));
+  it("returns dot for empty-ish relative path", () =>
+    expect(path.normalize("a/..")).toBe("."));
+  it("UNC path is preserved", () =>
+    expect(path.normalize("\\\\server\\share\\foo")).toBe(
+      "//server/share/foo",
+    ));
+});
+
+describe("path.join", () => {
+  it("joins two segments", () => expect(path.join("a", "b")).toBe("a/b"));
+  it("joins many segments", () =>
+    expect(path.join("a", "b", "c")).toBe("a/b/c"));
+  it("resolves dot-dot across join", () =>
+    expect(path.join("a/b", "../c")).toBe("a/c"));
+  it("preserves leading slash from first segment", () =>
+    expect(path.join("/a", "b")).toBe("/a/b"));
+  it("converts backslash", () => expect(path.join("a\\b", "c")).toBe("a/b/c"));
+  it("returns dot for no arguments", () => expect(path.join()).toBe("."));
+  it("ignores empty string segments", () =>
+    expect(path.join("a", "", "b")).toBe("a/b"));
+  it("handles Windows drive", () =>
+    expect(path.join("C:\\a", "b")).toBe("C:/a/b"));
+  it('join("/", rel) produces "/rel" not "//rel" (UNC)', () =>
+    expect(path.join("/", "linked.md")).toBe("/linked.md"));
+  it("join of POSIX root with nested rel stays absolute", () =>
+    expect(path.join("/", "a/b/../c")).toBe("/a/c"));
+});
+
+describe("path.dirname", () => {
+  it("returns parent dir", () => expect(path.dirname("/a/b/c")).toBe("/a/b"));
+  it("returns slash for top-level file", () =>
+    expect(path.dirname("/a")).toBe("/"));
+  it("returns dot for bare filename", () =>
+    expect(path.dirname("a")).toBe("."));
+  it("handles Windows drive", () =>
+    expect(path.dirname("C:\\a\\b")).toBe("C:/a"));
+  it("returns drive root for top-level", () =>
+    expect(path.dirname("C:\\a")).toBe("C:/"));
+  it("resolves trailing slash before computing", () =>
+    expect(path.dirname("/a/b/")).toBe("/a"));
+  it("handles UNC path", () =>
+    expect(path.dirname("//server/share/foo")).toBe("//server/share"));
+  it("returns dot for relative bare name", () =>
+    expect(path.dirname("file.ts")).toBe("."));
+  it("returns relative parent", () => expect(path.dirname("a/b")).toBe("a"));
+});
+
+describe("path.basename", () => {
+  it("returns last segment", () =>
+    expect(path.basename("/a/b/file.ts")).toBe("file.ts"));
+  it("strips provided extension", () =>
+    expect(path.basename("file.ts", ".ts")).toBe("file"));
+  it("does not strip if extension doesn't match", () =>
+    expect(path.basename("file.ts", ".js")).toBe("file.ts"));
+  it("handles trailing slash", () => expect(path.basename("/a/b/")).toBe("b"));
+  it("handles Windows path", () =>
+    expect(path.basename("C:\\a\\b.txt")).toBe("b.txt"));
+  it("returns empty string for root", () =>
+    expect(path.basename("/")).toBe(""));
+  it("returns bare name", () =>
+    expect(path.basename("file.ts")).toBe("file.ts"));
+});
+
+describe("path.extname", () => {
+  it("returns extension with dot", () =>
+    expect(path.extname("file.ts")).toBe(".ts"));
+  it("returns last extension only", () =>
+    expect(path.extname("file.test.ts")).toBe(".ts"));
+  it("returns empty for no extension", () =>
+    expect(path.extname("file")).toBe(""));
+  it("returns empty for dotfile (dot at position 0)", () =>
+    expect(path.extname(".gitignore")).toBe(""));
+  it("returns dot for trailing dot", () =>
+    expect(path.extname("file.")).toBe("."));
+  it("handles full path", () =>
+    expect(path.extname("/a/b/file.md")).toBe(".md"));
+});
+
+describe("path.isAbsolute", () => {
+  it("true for POSIX absolute", () =>
+    expect(path.isAbsolute("/foo")).toBe(true));
+  it("true for Windows drive with backslash", () =>
+    expect(path.isAbsolute("C:\\foo")).toBe(true));
+  it("true for Windows drive with forward-slash", () =>
+    expect(path.isAbsolute("C:/foo")).toBe(true));
+  it("true for UNC backslash", () =>
+    expect(path.isAbsolute("\\\\server\\share")).toBe(true));
+  it("true for UNC forward-slash", () =>
+    expect(path.isAbsolute("//server/share")).toBe(true));
+  it("false for relative path", () =>
+    expect(path.isAbsolute("foo/bar")).toBe(false));
+  it("false for drive-relative (no slash)", () =>
+    expect(path.isAbsolute("C:foo")).toBe(false));
+  it("false for bare filename", () =>
+    expect(path.isAbsolute("file.ts")).toBe(false));
+});
+
+describe("path.relative", () => {
+  it("computes sibling relative path", () =>
+    expect(path.relative("/a/b", "/a/c")).toBe("../c"));
+  it("returns dot for same path", () =>
+    expect(path.relative("/a/b", "/a/b")).toBe("."));
+  it("returns descendant path", () =>
+    expect(path.relative("/a", "/a/b/c")).toBe("b/c"));
+  it("returns parent path", () =>
+    expect(path.relative("/a/b/c", "/a")).toBe("../.."));
+  it("handles root to subpath", () =>
+    expect(path.relative("/", "/a/b")).toBe("a/b"));
+  it("returns normalized `to` for different Windows drives", () =>
+    expect(path.relative("C:/a", "D:/b")).toBe("D:/b"));
+  it("same drive computes relative", () =>
+    expect(path.relative("C:/a/b", "C:/a/c")).toBe("../c"));
+  it("handles backslash inputs", () =>
+    expect(path.relative("C:\\a\\b", "C:\\a\\c")).toBe("../c"));
+});