@termix-ssh/plugin-sdk 1.0.12 → 1.0.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +16 -0
- package/PLUGIN-GUIDE.md +91 -59
- package/dist/backend.d.ts +404 -0
- package/dist/capabilities.js +5 -0
- package/dist/db.js +1 -0
- package/dist/desktop.d.ts +0 -243
- package/dist/frontend.d.ts +23 -2
- package/dist/host/{PluginsTab-EV4MSGY6.js → PluginsTab-OXQQ7M4I.js} +511 -178
- package/dist/host/{chunk-X4QZKO5G.js → chunk-54KCK6IZ.js} +52 -5
- package/dist/host/{chunk-XKA3DBB2.js → chunk-CALNJCHN.js} +114 -54
- package/dist/host/{chunk-RUPLD6RF.js → chunk-CN5UBTBP.js} +2 -86
- package/dist/host/{chunk-AWR6FYDO.js → chunk-ERGN4YW6.js} +5552 -5550
- package/dist/host/{chunk-VEWOYAMZ.js → chunk-T2PZWXFJ.js} +1 -1
- package/dist/host/core-classes.json +1 -1
- package/dist/host/{linked-server-B4NEG4MA.js → linked-server-5VFO4XQB.js} +1 -1
- package/dist/host/{rbac-api-OUO3LUOC.js → rbac-api-5YMBJAO5.js} +1 -1
- package/dist/host/testing-host.js +4 -4
- package/dist/host/types/src/types/onboarding.d.ts +0 -2
- package/dist/host/types/src/ui/api/audit-log-api.d.ts +0 -10
- package/dist/host/types/src/ui/api/credentials-api.d.ts +0 -22
- package/dist/host/types/src/ui/api/plugins-api.d.ts +4 -0
- package/dist/host/types/src/ui/api/settings-api.d.ts +0 -6
- package/dist/host/types/src/ui/api/ssh-host-management-api.d.ts +0 -28
- package/dist/host/types/src/ui/main-axios.d.ts +2 -2
- package/dist/host/types/src/ui/onboarding/onboarding-registry.d.ts +3 -1
- package/dist/host/types/src/ui/plugin-host/sdk-ui.d.ts +5 -6
- package/dist/host/types/src/ui/plugins/plugin-model.d.ts +20 -0
- package/dist/host/types/src/ui/plugins/use-plugins-manager.d.ts +3 -0
- package/dist/host/types/src/ui/sidebar/host-contributions.d.ts +10 -0
- package/dist/host/ui.js +14 -205
- package/dist/host/{use-permissions-6VSHHUMB.js → use-permissions-ISEDRY3J.js} +1 -1
- package/dist/manifest.d.ts +10 -1
- package/dist/manifest.js +16 -1
- package/dist/ssh-keys.d.ts +29 -0
- package/dist/ssh-keys.js +85 -0
- package/dist/testing.d.ts +32 -15
- package/dist/testing.js +218 -1
- package/package.json +5 -1
- package/schema/manifest.schema.json +10 -0
- package/dist/host/types/src/ui/sidebar/host-export-payload.d.ts +0 -30
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,21 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.0.13
|
|
4
|
+
|
|
5
|
+
Plugin API 1.5.0.
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- `runtime: "desktop"` in the manifest for a plugin that only loads on the desktop app
|
|
10
|
+
- `desktop:local` and `ctx.desktop.local`: file system, local shell and machine info on the desktop app's own backend
|
|
11
|
+
- `ctx.audit.subscribe`, `ctx.audit.list` and `ctx.audit.exportBatches` under `audit:read`
|
|
12
|
+
- `ctx.hosts.importMany`, `importSshConfig`, `exportMany` and `registerImportNormalizer`, with the `hosts:export` capability
|
|
13
|
+
- `ctx.credentials.publicKey` and `resolveKeyRefs`, `ctx.ssh.exec`, and `@termix-ssh/plugin-sdk/ssh-keys`
|
|
14
|
+
- `ctx.hosts.status.provide` and `ctx.hosts.activity.provide` so a plugin can own host status and recent activity, with `ctx.network.tcpProbe`, `ctx.ssh.probe`, `ctx.hosts.probeTargets` and `ctx.hosts.sessionActive`
|
|
15
|
+
- `registerHostStatusIndicator` and `registerHostEditorToolbarItem`, and `order` for host badges
|
|
16
|
+
- Onboarding steps can sit in a `start` section, take a `position` and `replaces` a core step
|
|
17
|
+
- A plugin can provide the app name, tagline and logo through the `<id>.brandingProvider` registry key
|
|
18
|
+
|
|
3
19
|
## 1.0.12
|
|
4
20
|
|
|
5
21
|
Plugin API 1.4.0.
|
package/PLUGIN-GUIDE.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Termix plugin guide
|
|
2
2
|
|
|
3
|
-
SDK 1.0.
|
|
3
|
+
SDK 1.0.13 | Plugin API 1.5.0
|
|
4
4
|
|
|
5
5
|
This guide is for anyone, person or AI coding tool, building a Termix plugin. It ships inside
|
|
6
6
|
`@termix-ssh/plugin-sdk`, so the copy in your `node_modules` always matches the SDK you have installed.
|
|
@@ -164,7 +164,7 @@ Unknown fields are refused at every level, so a typo fails validation. The schem
|
|
|
164
164
|
| `icon` | A [Lucide](https://lucide.dev/icons/) icon name, like `Hand`. |
|
|
165
165
|
| `features` | Up to 20 short lines shown on the plugin's page. |
|
|
166
166
|
| `docs` | An https link to your docs. |
|
|
167
|
-
| `engine.termix` | Termix versions you work with, like `>=26.10.0`.
|
|
167
|
+
| `engine.termix` | Termix versions you work with, like `>=26.10.0`. Older Termix builds don't list a release they can't run. |
|
|
168
168
|
| `engine.api` | Plugin API range, like `^1.2`. A major bump of the API is breaking. |
|
|
169
169
|
| `capabilities` | What your code may do. See the reference at the end. |
|
|
170
170
|
| `dependencies`, `optionalDependencies` | Other plugins, `{ "snippets": "^1.0.0" }`. You must keep working without optional ones. |
|
|
@@ -325,6 +325,24 @@ try {
|
|
|
325
325
|
commands. `@termix-ssh/plugin-sdk/host-commands` has helpers to detect the OS and run package manager and
|
|
326
326
|
sudo commands. Hosts from `ctx.hosts` never carry secrets. Pass the host or its id to `ctx.ssh`.
|
|
327
327
|
|
|
328
|
+
### The desktop app
|
|
329
|
+
|
|
330
|
+
Set `"runtime": "desktop"` in the manifest for a plugin that only makes sense on a desktop app. It never
|
|
331
|
+
loads on a server, ignores server sync and may declare `desktop:local`. Any plugin can declare
|
|
332
|
+
`desktop:local` and check `ctx.desktop.local.available()` at runtime.
|
|
333
|
+
|
|
334
|
+
`ctx.desktop.local` works on the desktop app's own backend only:
|
|
335
|
+
|
|
336
|
+
- `info()`: home folder, platform, user data folder, backend port and the linked server (url and token) or null
|
|
337
|
+
- `fs`: `list`, `mkdir`, `createFile`, `rename`, `ensureDir`, `exists`, `walk`, `trash`, `reveal`, `open`,
|
|
338
|
+
`openRead` and `openDownload`. Downloads stay inside the folder the user picked, links in it are refused and
|
|
339
|
+
an existing file is never replaced by accident
|
|
340
|
+
- `pty.spawn()`: a local shell, stopped when the plugin stops
|
|
341
|
+
- `pluginFetch(origin, subPath, init)`: calls this plugin's own routes on the desktop's backend ("local") or the linked server ("remote") as the acting user. Bodies can be streams, so a plugin can move big files without the renderer
|
|
342
|
+
|
|
343
|
+
Use `ctx.audit.subscribe`, `list` and `exportBatches` (`audit:read`) to read the audit trail. Subscribers
|
|
344
|
+
are called after a line is accepted and never delay the action that wrote it.
|
|
345
|
+
|
|
328
346
|
### Events, timers, alerts, services
|
|
329
347
|
|
|
330
348
|
```ts
|
|
@@ -470,13 +488,15 @@ your plugin's error boundary and Suspense.
|
|
|
470
488
|
| `registerHostEditorSection` | Your own host editor section (host settings get one for free) |
|
|
471
489
|
| `registerHostProtocol` | A connection protocol next to SSH |
|
|
472
490
|
| `registerHostBadge`, `registerHostContextMenuItem` | Badges and menu items on host rows |
|
|
491
|
+
| `registerHostStatusIndicator` | The status dot or stripe on a host row (a layout draws it) |
|
|
492
|
+
| `registerHostEditorToolbarItem` | A control in the host editor toolbar (a layout draws it) |
|
|
473
493
|
| `registerPaletteEntry`, `registerPaletteGroup` | Command palette entries |
|
|
474
494
|
| `registerKeybindingAction`, `registerKeybindingDefault` | Bindable actions |
|
|
475
495
|
| `registerSettingsComponent` | A component for a `custom` settings field |
|
|
476
496
|
| `registerAction`, `invokeAction` | Actions across plugins |
|
|
477
497
|
| `registerSlotContribution`, `declareActionSlot` | Fill or own a UI slot |
|
|
478
498
|
| `registerComponent`, `registerExtension` | Offer a component by id, add to an extension point |
|
|
479
|
-
| `registerOnboardingStep` | A first run setup step
|
|
499
|
+
| `registerOnboardingStep` | A first run setup step (`section`, `position`, `replaces`) |
|
|
480
500
|
| `registerLoginMethod`, `registerSecondFactorUI`, `registerSshAuthEditor` | Sign in UI |
|
|
481
501
|
| `registerLayout` | A whole-app layout (`contributes.layouts`, API 1.4) |
|
|
482
502
|
| `api` | Axios client for your `/plugin-api/<id>/` routes, auth included |
|
|
@@ -484,6 +504,16 @@ your plugin's error boundary and Suspense.
|
|
|
484
504
|
| `docs`, `tabs`, `confirm`, `listHosts`, `getHost`, `t`, `hasPermission`, `desktop` | Helpers |
|
|
485
505
|
| `onSettingsChanged`, `onDispose` | Hooks |
|
|
486
506
|
|
|
507
|
+
Badges, status indicators and toolbar items take `{ id, when(host), component, order? }`; lower `order`
|
|
508
|
+
comes first. An onboarding step sits in a section (`start`, `setup`, `explore`, `security`) or at an exact
|
|
509
|
+
`position` from 1 to 99. `replaces: ["preset"]` lists older step keys the step took over, so people who saw
|
|
510
|
+
those are not shown it again.
|
|
511
|
+
|
|
512
|
+
Branding: a plugin that owns the app name, tagline and logo provides
|
|
513
|
+
`ctx.registry.provide("<id>.brandingProvider", async () => ({ appName, tagline, logo }))` in its backend.
|
|
514
|
+
Core reads it for `GET /users/branding` (the login page, the browser tab and the sync server name) and falls
|
|
515
|
+
back to "Termix" with no logo when no plugin provides one. `logo` is a PNG data URL or null.
|
|
516
|
+
|
|
487
517
|
Hooks from `@termix-ssh/plugin-sdk/frontend`: `useTranslation`, `usePermission`, `useSettings`, `useHost`,
|
|
488
518
|
`useHosts`, `usePluginApi`, `useCurrentUser`, `useTheme`, `useToast`, `useDocsUrl`, `useTabs`,
|
|
489
519
|
`useSlotContributions`, `useSshAuthTypes`, `useExtensions`, `useShell`.
|
|
@@ -563,8 +593,6 @@ export function activate(app: TermixApp) {
|
|
|
563
593
|
`classic-layout.hostTree` and `classic-layout.dashboard` for other plugins to place with `PluginComponent`.
|
|
564
594
|
It reads the shell with `useShellController()` from `@termix-ssh/plugin-sdk/ui`, which exposes more than
|
|
565
595
|
`useShell()` and may change with Termix. A third party layout should start from `useShell()`.
|
|
566
|
-
- Example Top Bar Layout (https://github.com/Termix-SSH/Plugin-Example-Topbar-Layout) is a small third party
|
|
567
|
-
style layout built only on `useShell()`, `TabStage` and `@termix-ssh/plugin-sdk/ui`, with a phone version.
|
|
568
596
|
|
|
569
597
|
A theme is CSS only. Declare it in `contributes.themes` (`id`, `label`, `mode` light or dark, `css` path,
|
|
570
598
|
optional `swatch` colors for the picker) with the `ui:theme` capability. The id becomes a class on `<html>`,
|
|
@@ -582,9 +610,7 @@ A plugin that only holds themes needs no code. Leave out `src/`: `termix-plugin
|
|
|
582
610
|
- Themes show in the picker in the order core lists its own, then the plugin's order.
|
|
583
611
|
- A theme someone saved that no longer exists shows as System. It comes back when the plugin does.
|
|
584
612
|
- Accent color, UI font, font size and density are not part of a theme. Core applies them on top.
|
|
585
|
-
- Bundled Classic Themes (https://github.com/Termix-SSH/Plugin-Classic-Themes) is a full example
|
|
586
|
-
Example Theme (https://github.com/Termix-SSH/Plugin-Example-Theme) a small one with one light and one dark
|
|
587
|
-
theme.
|
|
613
|
+
- Bundled Classic Themes (https://github.com/Termix-SSH/Plugin-Classic-Themes) is a full example.
|
|
588
614
|
|
|
589
615
|
## Looking native
|
|
590
616
|
|
|
@@ -832,60 +858,66 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
|
|
|
832
858
|
|
|
833
859
|
## SDK entry points
|
|
834
860
|
|
|
835
|
-
| Import | What it is
|
|
836
|
-
| -------------------------------------------------------------------- |
|
|
837
|
-
| `@termix-ssh/plugin-sdk/backend` | `PluginContext` and the backend types
|
|
838
|
-
| `@termix-ssh/plugin-sdk/frontend` | `TermixApp`, `TabProps` and the hooks
|
|
839
|
-
| `@termix-ssh/plugin-sdk/ui` | The UI kit, served by Termix at runtime
|
|
840
|
-
| `@termix-ssh/plugin-sdk/db` | `defineTable` and column builders
|
|
841
|
-
| `@termix-ssh/plugin-sdk/manifest` | `PluginManifest` type and manifest checks
|
|
842
|
-
| `@termix-ssh/plugin-sdk/capabilities` | The capability catalog
|
|
843
|
-
| `@termix-ssh/plugin-sdk/settings` | Settings field validation
|
|
844
|
-
| `@termix-ssh/plugin-sdk/testing` | `createMockCtx`, `createTestDb`, `renderWithApp`, `createFakeContext`
|
|
845
|
-
| `@termix-ssh/plugin-sdk/vitest-preset` | `pluginVitestConfig`
|
|
846
|
-
| `@termix-ssh/plugin-sdk/host-commands` | OS detection, package manager and sudo helpers over ssh2
|
|
847
|
-
| `@termix-ssh/plugin-sdk/ssh-certs` | `applyCertificateAuth()` for certificate based SSH auth
|
|
848
|
-
| `@termix-ssh/plugin-sdk/
|
|
849
|
-
| `@termix-ssh/plugin-sdk/
|
|
850
|
-
| `@termix-ssh/plugin-sdk/
|
|
851
|
-
| `@termix-ssh/plugin-sdk/
|
|
852
|
-
| `@termix-ssh/plugin-sdk/
|
|
861
|
+
| Import | What it is |
|
|
862
|
+
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
863
|
+
| `@termix-ssh/plugin-sdk/backend` | `PluginContext` and the backend types |
|
|
864
|
+
| `@termix-ssh/plugin-sdk/frontend` | `TermixApp`, `TabProps` and the hooks |
|
|
865
|
+
| `@termix-ssh/plugin-sdk/ui` | The UI kit, served by Termix at runtime |
|
|
866
|
+
| `@termix-ssh/plugin-sdk/db` | `defineTable` and column builders |
|
|
867
|
+
| `@termix-ssh/plugin-sdk/manifest` | `PluginManifest` type and manifest checks |
|
|
868
|
+
| `@termix-ssh/plugin-sdk/capabilities` | The capability catalog |
|
|
869
|
+
| `@termix-ssh/plugin-sdk/settings` | Settings field validation |
|
|
870
|
+
| `@termix-ssh/plugin-sdk/testing` | `createMockCtx`, `createTestDb`, `renderWithApp`, `createFakeContext` |
|
|
871
|
+
| `@termix-ssh/plugin-sdk/vitest-preset` | `pluginVitestConfig` |
|
|
872
|
+
| `@termix-ssh/plugin-sdk/host-commands` | OS detection, package manager and sudo helpers over ssh2 |
|
|
873
|
+
| `@termix-ssh/plugin-sdk/ssh-certs` | `applyCertificateAuth()` for certificate based SSH auth |
|
|
874
|
+
| `@termix-ssh/plugin-sdk/ssh-keys` | `generateSshKeyPair()`, `detectSshKeyType()`, `publicKeyFromPrivate()`, `validateSshKeyPair()` |
|
|
875
|
+
| `@termix-ssh/plugin-sdk/desktop` | The desktop app bridge, typed. Check it exists before use |
|
|
876
|
+
| `@termix-ssh/plugin-sdk/openapi` | `buildOpenApi()` |
|
|
877
|
+
| `@termix-ssh/plugin-sdk/changelog` | Changelog parsing and checks |
|
|
878
|
+
| `@termix-ssh/plugin-sdk/docs` | Docs link and env var helpers |
|
|
879
|
+
| `@termix-ssh/plugin-sdk/ddl`, `@termix-ssh/plugin-sdk/table-builder` | Table to SQL and Drizzle mapping. You rarely need these |
|
|
853
880
|
|
|
854
881
|
## Capabilities
|
|
855
882
|
|
|
856
|
-
| Capability
|
|
857
|
-
|
|
|
858
|
-
| `credentials:read`
|
|
859
|
-
| `system:tls`
|
|
860
|
-
| `ssh:connect`
|
|
861
|
-
| `process:spawn`
|
|
862
|
-
| `users:write`
|
|
863
|
-
| `users:impersonate`
|
|
864
|
-
| `db:core-refs`
|
|
865
|
-
| `auth:provide`
|
|
866
|
-
| `device:serial`
|
|
867
|
-
| `
|
|
868
|
-
| `
|
|
869
|
-
| `
|
|
870
|
-
| `
|
|
871
|
-
| `
|
|
872
|
-
| `
|
|
873
|
-
| `
|
|
874
|
-
| `network:
|
|
875
|
-
| `
|
|
876
|
-
| `
|
|
877
|
-
| `
|
|
878
|
-
| `
|
|
879
|
-
| `
|
|
880
|
-
| `
|
|
881
|
-
| `
|
|
882
|
-
| `
|
|
883
|
-
| `
|
|
884
|
-
| `
|
|
885
|
-
| `
|
|
886
|
-
| `
|
|
887
|
-
| `
|
|
888
|
-
| `
|
|
883
|
+
| Capability | Risk | What it allows |
|
|
884
|
+
| ------------------------ | -------- | ------------------------------------------------------- |
|
|
885
|
+
| `credentials:read` | critical | Read stored secrets for hosts the user can reach |
|
|
886
|
+
| `system:tls` | critical | Replace the HTTPS certificate, answer CA domain checks |
|
|
887
|
+
| `ssh:connect` | high | Run any command on hosts, with the user's access |
|
|
888
|
+
| `process:spawn` | high | Run programs on the Termix server |
|
|
889
|
+
| `users:write` | high | Add users and change their roles |
|
|
890
|
+
| `users:impersonate` | high | Act as another user, or get a session for them, audited |
|
|
891
|
+
| `db:core-refs` | high | Query core users, roles and hosts tables (read only) |
|
|
892
|
+
| `auth:provide` | high | Add login methods, second factors, SSH auth types |
|
|
893
|
+
| `device:serial` | high | Open serial and USB ports on the server |
|
|
894
|
+
| `desktop:local` | high | Use the user's own computer, desktop app only |
|
|
895
|
+
| `hosts:export` | high | Export hosts with their saved logins |
|
|
896
|
+
| `notify:hub` | high | Receive every alert (the alerts hub only) |
|
|
897
|
+
| `ui:layout` | high | Replace the whole app layout |
|
|
898
|
+
| `hosts:write` | medium | Add and edit hosts |
|
|
899
|
+
| `hosts:status-provide` | medium | Be the source of host status dots |
|
|
900
|
+
| `hosts:activity-provide` | medium | Be the source of the recent activity list |
|
|
901
|
+
| `network:probe` | medium | Check that a host answers on a TCP port |
|
|
902
|
+
| `credentials:use` | medium | Connect with saved credentials without seeing them |
|
|
903
|
+
| `credentials:write` | medium | Save new credentials |
|
|
904
|
+
| `network:outbound` | medium | Outbound HTTP through `ctx.fetch` |
|
|
905
|
+
| `network:serve` | medium | HTTP routes and sockets |
|
|
906
|
+
| `network:broadcast` | medium | Local network broadcasts, like Wake-on-LAN |
|
|
907
|
+
| `users:read` | medium | Usernames, roles and UI language |
|
|
908
|
+
| `events:core` | medium | Listen to core events |
|
|
909
|
+
| `notify:send` | medium | Send alerts |
|
|
910
|
+
| `audit:read` | medium | Read the audit log |
|
|
911
|
+
| `desktop:window` | medium | Open windows in the desktop app |
|
|
912
|
+
| `hosts:read` | low | Read hosts the user can see |
|
|
913
|
+
| `db:own` | low | Your own tables |
|
|
914
|
+
| `kv:own` | low | Small key value state |
|
|
915
|
+
| `files:own` | low | Your own folder on disk |
|
|
916
|
+
| `secrets:own` | low | Your own encrypted secrets |
|
|
917
|
+
| `settings:read-core` | low | Read Termix server settings |
|
|
918
|
+
| `plugins:read` | low | See installed plugins |
|
|
919
|
+
| `ui:surface` | low | Add tabs, panels and settings |
|
|
920
|
+
| `ui:theme` | low | Add color themes, CSS only |
|
|
889
921
|
|
|
890
922
|
An update that adds a capability waits for an admin to approve it.
|
|
891
923
|
|