@silo-code/sdk 0.21.0 → 0.23.0

package/src/path.ts

@@ -0,0 +1,188 @@
+// Pure path utilities for extensions. A cross-platform replacement for
+// `node:path`, which extensions are banned from importing (platform ban).
+// All outputs use forward-slash separators — the form FileService accepts on
+// every platform. Both "/" and "\" are accepted as inputs.
+
+/** Normalize all separators to forward-slash. */
+function normSep(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+/** Extract a Windows drive-letter prefix ("C:") from a forward-slash path, or null. */
+function parseDrive(p: string): string | null {
+  const m = /^([A-Za-z]):/.exec(p);
+  return m ? m[1].toUpperCase() + ":" : null;
+}
+
+/**
+ * Normalize segments of a forward-slash path: collapse duplicate slashes,
+ * resolve "." and ".." segments. Preserves leading "/" (POSIX absolute),
+ * "C:/" (Windows drive-letter), and "//" (UNC paths).
+ */
+function normSegments(s: string): string {
+  const drive = parseDrive(s);
+  const afterDrive = drive ? s.slice(2) : s;
+  const isUnc = afterDrive.startsWith("//");
+  const isAbs = isUnc || afterDrive.startsWith("/");
+
+  const stack: string[] = [];
+  for (const seg of afterDrive.split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      if (stack.length > 0 && stack[stack.length - 1] !== "..") {
+        stack.pop();
+      } else if (!isAbs) {
+        stack.push("..");
+      }
+    } else {
+      stack.push(seg);
+    }
+  }
+
+  let result = stack.join("/");
+  if (isUnc) result = "//" + result;
+  else if (isAbs) result = "/" + result;
+  if (drive) result = drive + result;
+  if (!result) return isAbs ? (drive ? drive + "/" : "/") : ".";
+  return result;
+}
+
+/**
+ * Path utilities for extensions — a cross-platform replacement for
+ * `node:path`, which extensions are banned from importing. All output paths
+ * use forward-slash separators (the form {@link FileService} accepts on every
+ * platform). Both `/` and `\` are accepted as input separators.
+ *
+ * @example
+ * ```ts
+ * import { path } from "@silo-code/sdk";
+ *
+ * const dir  = path.dirname(filePath);            // "/home/user/docs"
+ * const full = path.join(dir, "images/fig.png");  // "/home/user/docs/images/fig.png"
+ * const rel  = path.relative(dir, full);           // "images/fig.png"
+ * const ext  = path.extname(full);                 // ".png"
+ * ```
+ *
+ * @category Core Types
+ * @public
+ */
+export const path: {
+  /**
+   * Join path segments and normalize the result. Empty segments are ignored;
+   * `\` separators in any segment are treated as `/`.
+   */
+  join(...parts: string[]): string;
+  /**
+   * Return the directory portion of a path — everything up to (not including)
+   * the last `/`. Returns `"."` for a bare filename with no directory component.
+   */
+  dirname(p: string): string;
+  /**
+   * Return the final component of a path. If `ext` is supplied and the
+   * basename ends with that string, it is stripped from the result.
+   */
+  basename(p: string, ext?: string): string;
+  /**
+   * Return the extension of a path — the portion from the last `.` of the
+   * basename, including the dot. Returns `""` for paths with no extension and
+   * for dotfiles with no secondary extension (e.g. `".gitignore"` → `""`).
+   */
+  extname(p: string): string;
+  /**
+   * Compute the relative path from `from` to `to`. Both should be absolute
+   * paths on the same drive. When they are on different Windows drive letters,
+   * `to` (normalized) is returned unchanged — no relative path exists between
+   * drives.
+   */
+  relative(from: string, to: string): string;
+  /**
+   * Return `true` if `p` is an absolute path: starts with `/` (POSIX), has a
+   * drive letter followed by a slash (`C:/`, `C:\`), or is a UNC path
+   * (`\\server\share` / `//server/share`). Note: `C:foo` (drive-relative,
+   * no slash) is NOT absolute.
+   */
+  isAbsolute(p: string): boolean;
+  /**
+   * Normalize a path: convert `\` to `/`, collapse duplicate slashes, and
+   * resolve `.` and `..` segments.
+   */
+  normalize(p: string): string;
+} = {
+  normalize(p) {
+    return normSegments(normSep(p));
+  },
+
+  join(...parts) {
+    const nonEmpty = parts.filter((p) => p.length > 0);
+    if (nonEmpty.length === 0) return ".";
+    // Concatenate without adding "/" when adjacent parts already supply the
+    // boundary, so join("/", "rel") → "/rel" rather than "//rel" (UNC).
+    const raw = nonEmpty.map(normSep).reduce((a, b) => {
+      if (a.endsWith("/") || b.startsWith("/")) return a + b;
+      return a + "/" + b;
+    });
+    return normSegments(raw);
+  },
+
+  dirname(p) {
+    const n = normSegments(normSep(p));
+    const drive = parseDrive(n);
+    const rest = drive ? n.slice(2) : n;
+    const i = rest.lastIndexOf("/");
+    if (i < 0) return drive ? drive + "." : ".";
+    if (i === 0) return drive ? drive + "/" : "/";
+    return drive ? drive + rest.slice(0, i) : rest.slice(0, i);
+  },
+
+  basename(p, ext) {
+    const n = normSep(p);
+    const segs = n.split("/");
+    let name = segs[segs.length - 1] ?? "";
+    // Trailing slash: "foo/" → last segment is "" → fall back to prior segment
+    if (name === "" && segs.length > 1) name = segs[segs.length - 2] ?? "";
+    if (ext !== undefined && name.endsWith(ext)) {
+      name = name.slice(0, name.length - ext.length);
+    }
+    return name;
+  },
+
+  extname(p) {
+    const base = path.basename(normSep(p));
+    const i = base.lastIndexOf(".");
+    // i === 0 means a dotfile like ".gitignore" — no extension
+    if (i <= 0) return "";
+    return base.slice(i);
+  },
+
+  isAbsolute(p) {
+    const n = normSep(p);
+    if (n.startsWith("//")) return true; // UNC (\\server\share or //server/share)
+    if (/^[A-Za-z]:\//.test(n)) return true; // Windows drive with slash (C:/ or C:\)
+    return n.startsWith("/"); // POSIX
+  },
+
+  relative(from, to) {
+    const nFrom = normSegments(normSep(from));
+    const nTo = normSegments(normSep(to));
+    const driveFrom = parseDrive(nFrom);
+    const driveTo = parseDrive(nTo);
+    // Can't express a relative path across different drives
+    if (driveFrom !== driveTo) return nTo;
+    const segsFrom = (driveFrom ? nFrom.slice(2) : nFrom)
+      .split("/")
+      .filter(Boolean);
+    const segsTo = (driveTo ? nTo.slice(2) : nTo).split("/").filter(Boolean);
+    let common = 0;
+    while (
+      common < segsFrom.length &&
+      common < segsTo.length &&
+      segsFrom[common] === segsTo[common]
+    ) {
+      common++;
+    }
+    const ups = segsFrom.length - common;
+    const downs = segsTo.slice(common);
+    const parts = [...Array<string>(ups).fill(".."), ...downs];
+    return parts.join("/") || ".";
+  },
+};

package/src/process-service.ts

@@ -67,6 +67,24 @@ export interface ProcessExecOptions {
    * {@link Permission}. First-party (bundled) extensions are unscoped.
    */
   cwd?: string;
+  /**
+   * Extra environment variables, **merged over** the host's environment (the
+   * command inherits the host env; these keys add to or override it). Use it to
+   * set things like `GIT_PAGER=cat` or a locale without clobbering `PATH`.
+   */
+  env?: Record<string, string>;
+  /**
+   * Kill the process and reject after this many milliseconds. The whole process
+   * group is terminated (not just the direct child), so shell wrappers don't
+   * leak orphans. The rejection is an `Error` whose `name` is `"AbortError"`.
+   */
+  timeoutMs?: number;
+  /**
+   * Abort handle. Aborting kills the process (and its group) and rejects the
+   * `exec` promise with an `Error` whose `name` is `"AbortError"` — the same
+   * shape as a `timeoutMs` expiry, so callers branch on `err.name`.
+   */
+  signal?: AbortSignal;
 }
 
 /**
@@ -116,10 +134,12 @@ export interface ProcessService {
    * 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}.
+   * stutters the app. The returned promise rejects if the process could not be
+   * spawned (e.g. the command was not found), or if a
+   * {@link ProcessExecOptions.timeoutMs | timeout} / {@link ProcessExecOptions.signal | abort}
+   * fires (an `Error` with `name === "AbortError"`); a command that runs to
+   * completion 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

package/src/processes-service.ts

@@ -88,7 +88,7 @@ export interface ProcessInfo {
  * // Notify when all agents in the workspace are idle.
  * const sub = ctx.processes.subscribe((procs) => {
  *   const allIdle = procs.every((p) => p.atPrompt);
- *   if (allIdle) ctx.ui.notify({ title: "All agents finished" });
+ *   if (allIdle) ctx.ui.notify("info", "All agents finished");
  * });
  * ctx.subscriptions.push(sub);
  *

package/src/search-service.ts

@@ -43,6 +43,17 @@ export interface SearchOptions {
    * is hit, the search stops early and {@link SearchResponse.truncated} is true.
    */
   maxResults?: number;
+  /**
+   * Cancel the search. When the signal aborts, the promise returned by
+   * {@link SearchService.search} rejects with an `Error` whose `name` is
+   * `"AbortError"` (the `fetch` convention — branch on `err.name`).
+   *
+   * Cancellation is observable immediately, but the native search may still run
+   * to completion in the background — its result is simply discarded. Use this
+   * to abandon a stale query (e.g. superseded by the next keystroke) rather than
+   * to reclaim native CPU the instant you abort.
+   */
+  signal?: AbortSignal;
 }
 
 /**

package/src/system-service.ts

@@ -53,13 +53,13 @@ export interface SystemInfo {
  *       ctx.subscriptions.push(
  *         ctx.registerCommand({
  *           id: "my.reveal-in-finder",
- *           title: "Reveal in Finder",
+ *           label: "Reveal in Finder",
  *           run() { ... },
  *         }),
  *       );
  *     }
  *
- *     ctx.ui.notify({ title: `Running Silo ${siloVersion} on ${os}/${arch}` });
+ *     ctx.ui.notify("info", `Running Silo ${siloVersion} on ${os}/${arch}`);
  *   },
  * };
  * ```

package/src/terminal-service.ts

@@ -98,11 +98,51 @@ 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.
+   *
+   * Returns `undefined` only when `input.workspaceId` is not given and there is
+   * no active workspace at the time of the call — in normal use this does not
+   * happen because activating any workspace happens before extensions run.
    */
   create(input?: CreateTerminalInput): TerminalRecord | undefined;
   /** Close and kill every terminal in a workspace (e.g. on workspace delete). */
   closeWorkspace(workspaceId: string): void;
 
+  /**
+   * Write text to a terminal's PTY as if the user typed it. By default a
+   * carriage return is appended so the line executes; pass `addNewline: false`
+   * to stage text without running it.
+   *
+   * Works even if the terminal tab has never been shown: the PTY spawns lazily
+   * on first mount, and `sendText` force-spawns it on demand (a later mount then
+   * attaches to that same session). No-op for an unknown `terminalId`.
+   *
+   * @param terminalId - The {@link TerminalRecord.id} to write to.
+   * @param text - The text to send.
+   * @param addNewline - Append a carriage return to execute. Defaults to `true`.
+   *
+   * @example
+   * ```ts
+   * const term = ctx.terminals.create({ cwd: workspaceFolder });
+   * if (term) ctx.terminals.sendText(term.id, "npm run build");
+   * ```
+   */
+  sendText(terminalId: string, text: string, addNewline?: boolean): void;
+
+  /**
+   * Close one terminal tab and kill its PTY session. No-op if the id is unknown.
+   * To reap every terminal in a workspace at once use
+   * {@link TerminalService.closeWorkspace}.
+   */
+  close(terminalId: string): void;
+
+  /**
+   * Set a terminal's user-facing name ({@link TerminalRecord.customName}),
+   * shown on its tab and persisted across restarts. Passing an empty string
+   * clears the custom name, letting the PTY-derived title take over again.
+   * No-op for an unknown `terminalId`.
+   */
+  rename(terminalId: string, name: string): void;
+
   /**
    * Switch to the workspace containing this terminal and activate its tab in
    * the center dock. No-ops if the terminal id is unknown.
@@ -169,6 +209,39 @@ export interface TerminalService {
     handler: (event: OscEvent) => void,
   ): Disposable;
 
+  /**
+   * Subscribe to the raw PTY output stream of the terminal identified by
+   * `terminalId`. The `handler` is called with every chunk of bytes the PTY
+   * produces — including ANSI escape sequences, OSC sequences, and all other
+   * control characters — exactly as they arrive, with no parsing or filtering.
+   *
+   * This fires even when the terminal's panel is not visible, so it is suitable
+   * for background monitoring (e.g. detecting output activity to confirm an
+   * agent is still running). Keep handlers lightweight: they execute
+   * synchronously on every PTY chunk, which can be multiple times per second
+   * while a program is active.
+   *
+   * The subscription is keyed to the **terminal record id** (e.g. `"term_…"`),
+   * not the underlying PTY session id, so it survives terminal recreation within
+   * the same record.
+   *
+   * Returns a {@link Disposable} that cancels the subscription.
+   *
+   * @example
+   * ```ts
+   * // Track the last time any output arrived to confirm agent activity.
+   * let lastOutputAt = 0;
+   * const sub = ctx.terminals.subscribeOutput(terminalId, () => {
+   *   lastOutputAt = Date.now();
+   * });
+   * ctx.subscriptions.push(sub);
+   * ```
+   */
+  subscribeOutput(
+    terminalId: string,
+    handler: (data: string) => void,
+  ): Disposable;
+
   /**
    * The record id of the terminal tab that is currently active in the active
    * workspace's center dock, or `null` when an editor tab (or nothing) is

package/src/types.ts

@@ -1,5 +1,6 @@
 /**
- * The Silo extension API — types only.
+ * The Silo extension API — types-first contract plus a small set of blessed
+ * runtime helpers.
  *
  * Everything an extension author can see at compile time lives here (plus the
  * service interfaces in the sibling `*-service` files, which this module
@@ -8,6 +9,12 @@
  * never import the host. This is the VS Code (`vscode.d.ts`) / Obsidian
  * (`obsidian-api`) model.
  *
+ * **Runtime exports:** the SDK also ships a small set of blessed runtime
+ * helpers (`Tooltip`, `useFocusGroup`, `useServiceState`, `DND_MIME`,
+ * `PathDeniedError`, `NetworkError`) and peer-depends on React 19. Changes to
+ * these can be breaking even when the types are unchanged — treat them with
+ * the same care as the type surface.
+ *
  * Start with {@link Extension} (the unit you export) and
  * {@link ExtensionContext} (the `ctx` the host hands you).
  *
@@ -207,10 +214,10 @@ export interface NewFileTemplate {
 
 /**
  * Declarative metadata about a file extension — the open-ended counterpart to
- * Viewer (which is purely a renderer). A single source of truth that "New File"
- * surfaces (and, later, tab/explorer icons) can enumerate. Registering a
- * FileType does not register a viewer; the two are matched independently by
- * extension at dispatch time.
+ * {@link Editor} (which is purely a presenter/renderer). A single source of
+ * truth that "New File" surfaces (and, later, tab/explorer icons) can
+ * enumerate. Registering a FileType does not register an Editor; the two are
+ * matched independently by extension at dispatch time.
  *
  * @category Registration
  * @public

package/src/workspace-service.ts

@@ -170,6 +170,12 @@ export interface WorkspaceService {
   createFromFolderPicker(): Promise<Workspace | null>;
   create(input: CreateWorkspaceInput): Workspace;
   rename(id: string, name: string): void;
+  /**
+   * Move a workspace to a new position relative to a reference workspace.
+   * @param from - Id of the workspace being dragged / moved.
+   * @param to - Id of the reference workspace (the insertion anchor).
+   * @param position - Whether to place `from` before or after `to`.
+   */
   reorder(from: string, to: string, position: "before" | "after"): void;
   /** Activate (and reopen if closed). */
   activate(id: string): void;
@@ -263,6 +269,13 @@ export interface WorkspaceService {
    *
    * The Workspaces panel subscribes internally to re-render when providers
    * are added or removed.
+   *
+   * **No `invalidateSection` by design.** Unlike status rows and badges, a
+   * section is a live React component that re-renders on its own internal or
+   * context-driven state changes — it is not a snapshot returned from a
+   * `provide()` call, so there is nothing for the host to re-query. If a
+   * section needs to trigger a full workspace-panel refresh (rare), it should
+   * update its own state directly.
    */
   subscribeSection(listener: () => void): Disposable;