npm package: @srcnexus/ext-sdk
Description: SDK for building Source Nexus Code Editor extensions
Author: SrcNexus
Latest version: 0.1.8

# @srcnexus/ext-sdk

SDK for building [SrcNexus](https://srcnexus.com) Code Editor extensions.

## Install

```bash
npm install @srcnexus/ext-sdk
```

## Quick Start

```typescript
import editor from "@srcnexus/ext-sdk";

editor.onLoad(() => {
  editor.commands.registerCommand("myExt.greet", async () => {
    const name = await editor.window.showInputBox({ prompt: "Your name:" });
    if (name) editor.window.showToast(`Hello, ${name}!`);
  });
});

editor.onDispose(() => {
  // cleanup
});
```

## API Reference

### Lifecycle

| Function | Description |
|---|---|
| `onLoad(callback)` | Runs when the extension activates |
| `onDispose(callback)` | Runs when the extension deactivates |

### Commands (`editor.commands`)

| Function | Description |
|---|---|
| `registerCommand(id, handler, options?)` | Register a command |
| `execute(id, args?)` | Execute a command by ID |
| `list(options?)` | List commands (filter by `category`, `extensionId`) |
| `registerHook(options, handler)` | Hook into `before` or `after` a command |

### Window (`editor.window`)

| Function | Description |
|---|---|
| `showToast(message)` | Show a notification toast |
| `showInputBox(options)` | Prompt for text input |
| `showConfirm(options)` | Show a yes/no confirmation dialog |
| `showPicker(options)` | Show a searchable item picker |
| `showProgress(message)` | Show a progress indicator |
| `hideProgress(progressId)` | Hide a progress indicator |
| `setStatusBarText(id, text)` | Update a status bar item |
| `openWebviewTab(options)` | Open a webview tab (`url` or `html`) |
| `showBottomSheet(options)` | Show a draggable bottom sheet |
| `closeBottomSheet(id)` | Close a bottom sheet |
| `showPopup(options)` | Show a modal popup (webview, markdown, or terminal) |
| `closePopup(id)` | Close a popup |
| `showDirectoryPicker()` | Pick a directory |
| `showFilePicker()` | Pick a file |
| `showCommandPalette()` | Open the command palette |
| `showThemePicker()` | Open the theme picker |

### File System (`editor.workspace.fs`)

| Function | Description |
|---|---|
| `read(uri)` | Read file contents |
| `write(uri, content)` | Write to a file |
| `create(parentUri, name)` | Create a new file |
| `list(uri, options?)` | List directory contents |
| `delete_(uri)` | Delete a file or directory |
| `exists(uri)` | Check if a path exists |
| `createDirectory(parentUri, name)` | Create a directory |
| `rename(uri, newName)` | Rename a file or directory |
| `move(uri, destinationUri)` | Move a file or directory |
| `copy(uri, destinationUri)` | Copy a file |
| `zip(uri, options?)` | Create a ZIP archive |
| `share(uri)` | Share via system share sheet |
| `openExternal(uri)` | Open with the default app |

### Workspace (`editor.workspace`)

| Function | Description |
|---|---|
| `getProjectRoot()` | Get the project root URI |
| `getActiveFile()` | Get info about the active tab |
| `getOpenTabs()` | Get all open tabs |
| `openFile(uri)` | Open a file in the editor |
| `getTheme()` | Get the current theme colors |
| `getAppVersion()` | Get the app version |
| `getEngineVersion()` | Get the SDK engine version |
| `getCurrentScreen()` | Get the active screen name |
| `getConfiguration(section)` | Get a configuration value |

### Project (`editor.workspace.project`)

| Function | Description |
|---|---|
| `create(options)` | Create a new project (`name`, `parentUri?`, `files?`) |

### Terminal (`editor.terminal`)

| Function | Description |
|---|---|
| `isSetup()` | Check if the terminal server is configured |
| `open(options?)` | Open a terminal tab |
| `sendInput(tabKey, text)` | Send text to a terminal |
| `readOutput(tabKey)` | Read terminal output |
| `close(tabKey)` | Close a terminal tab |

### Storage (`editor.storage`)

| Function | Description |
|---|---|
| `kv.setItem(key, value)` | Store a value |
| `kv.getItem(key)` | Retrieve a value |
| `kv.removeItem(key)` | Delete a key |
| `kv.clear()` | Clear all data |
| `kv.getAll()` | Get all key-value pairs |
| `getDataDir()` | Get the persistent data directory |
| `getCacheDir()` | Get the cache directory |

### Network (`editor.network`)

| Function | Description |
|---|---|
| `fetch(url, options?)` | Make an HTTP request |
| `createWebSocket(url)` | Open a WebSocket connection |

The global `fetch()` function is also available and routed through the app's network layer.

### Editor (`editor.editor`)

| Function | Description |
|---|---|
| `openDiff(options)` | Open a diff editor tab |

### Snippets (`editor.snippets`)

| Function | Description |
|---|---|
| `add(options)` | Add a code snippet (supports `$1`, `$2` tab stops) |
| `delete_(options)` | Delete a snippet |
| `list(options?)` | List snippets (filter by `fileExtension`) |

### Formatters (`editor.formatters`)

| Function | Description |
|---|---|
| `register(options)` | Register a code formatter for given languages |
| `unregister(options)` | Unregister a formatter |

### CodeMirror Extensions (`editor.extensions`)

| Function | Description |
|---|---|
| `registerCodeMirrorExtension(id, jsCode, options?)` | Register an inline CM6 extension |
| `registerCodeMirrorExtension(id, fileOptions)` | Register a CM6 extension from a bundled file |

### Events (`editor.events`)

| Event | Fires when |
|---|---|
| `onThemeChange` | Theme changes |
| `onActiveEditorChange` | Active tab changes |
| `onFileOpen` | A file is opened |
| `onFileSave` | A file is saved |
| `onFileCreated` | A file is created |
| `onFolderCreated` | A folder is created |
| `onFileDeleted` | A file is deleted |
| `onFileRenamed` | A file is renamed |
| `onFileMoved` | A file is moved |
| `onConfigChange` | Configuration changes |
| `onConfigReset` | Settings are reset |
| `onTabOpen` | A tab is opened |
| `onTabClose` | A tab is closed |
| `onFileClose` | A file tab is closed |

### Messaging (global)

| Function | Description |
|---|---|
| `listen(id, callback)` | Subscribe to a message channel |
| `post(id, message)` | Publish to a message channel |

## Permissions

Extensions declare required permissions in `manifest.json`. Available permissions: `fs`, `terminal`, `network`, `storage`, `projectCreate`.

## License

MIT