Extension API (version 1)

import { shellaro, type ExtensionContext } from "@shellaro/extension-sdk";

export function activate(context: ExtensionContext) { /* register commands and views */ }
export function deactivate() { /* optional */ }

The module is CommonJS at run time (shellaro ext build produces it). activate runs when the extension is first needed; push disposables into context.subscriptions and they are disposed on deactivate. Types: packages/extension-sdk/index.d.ts (copied into new projects as types/shellaro.d.ts).

Every method is asynchronous: it is a message to Shellaro, which checks the permission, does the work and returns plain data. Errors are thrown as Error with a readable message. Values passed in and out are copied (JSON).

shellaro

commands (ui.commands)

registerCommand(id, handler): Disposable registers the handler for a command declared in contributes.commands. The handler receives the arguments of the tree item action that ran it (none from the palette) and may return a value.

views (ui.sidebar)

registerTreeDataProvider(viewId, { getChildren(parent?) }) supplies the items of a view declared in contributes.views. getChildren() returns the top level; it is called with an item when that item is expanded. refresh(viewId) asks Shellaro to read the items again (expanded groups stay open).

interface TreeItem {
  id: string;               // stable within its parent
  label: string;
  description?: string;     // dimmed text after the label
  tooltip?: string;
  icon?: IconName;          // fixed set, see manifest.md
  status?: "ok" | "warning" | "error" | "info" | "muted";   // colored dot
  collapsible?: boolean;
  expanded?: boolean;       // initially expanded
  command?: ItemAction;     // runs on click / Enter
  actions?: ItemAction[];   // first three as hover buttons, all in the right-click menu
  data?: unknown;
}
interface ItemAction { command: string; title: string; icon?: IconName; args?: unknown[] }

Shellaro shows at most 2000 items per level and trims long strings.

window (no permission)

sessions (sessions.read)

list(): SessionInfo[], getActive(): SessionInfo | null, onDidChangeActive(listener): Disposable.

SessionInfo: id, name, host, port, username, environment, group, connected.

context (context.read)

get(): ShellaroContext, onDidChange(listener): Disposable (fires when the active terminal, its connection state or its context changes).

ShellaroContext: sessionId, sessionName, environment, connected, hostname, user, root, os, cwd, git: { branch, root } | null, kubernetes: { context, namespace, cluster } | null, tools.

terminal (terminal.execute)

execute(command, { sessionId?, target?: "active" | "splitRight" | "splitDown" | "newTab", wait? })

Runs one command line in a visible terminal of the active session (or of sessionId). With a split or new tab target, Shellaro opens the session there and waits until it is connected. Command Safety checks the command first. With wait: true (default) the result has the exit code and output lines (from shell integration); use wait: false for interactive programs (a shell in a pod, tail -f).

Result: { status: "done" | "cancelled" | "blocked", exitCode, output, reason }.

remote (remote.exec)

exec(command, { sessionId?, timeoutMs? }): { exitCode, stdout, stderr, truncated, timedOut }

Runs a command on the connected server of the active terminal (or sessionId) on its own SSH exec channel, without a terminal. The first time on each server the user is asked; Command Safety checks every command. Up to 4 run at a time per extension; default timeout 30 s, at most 5 minutes; stdout and stderr are each cut at 4 MB (truncated).

sftp (sftp.read, sftp.write)

list(path), readText(path), writeText(path, content) on the active session's SFTP connection (or { sessionId }).

storage (storage)

get(key), set(key, value), delete(key), keys(): JSON values, 1 MB in total, stored in %APPDATA%\com.shellaro.app\extensions\storage\<id>.json.

runbooks (runbooks.read, runbooks.run)

list(): RunbookInfo[] (the user's runbooks and installed Command Packs), start(id): boolean opens it for the active terminal; the user runs each step.

localCluster (local.cluster, Shellaro 0.8)

Shellaro's one-click local Kubernetes cluster (docs).

network (network)

fetch(url, { method?, headers?, body? }): { status, contentType, body, json() }: https only, and only to hosts in the manifest's network.hosts. Requests go through Shellaro (not the worker), so the page's network rules stay in force.

log (no permission)

log.info / warn / error(...args) and console.* appear in Developer Mode (Settings > Developer) for that extension.

Not available

The worker has no DOM, no fetch, XMLHttpRequest, WebSocket, importScripts, nested workers or IndexedDB, and no access to Shellaro's internals. require() only resolves @shellaro/extension-sdk; bundle everything else into main.