@linkdesk/plugin-docs 0.1.0
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/README.md +58 -0
- package/docs/00-readme.md +189 -0
- package/docs/01-plugin-api-contract.md +171 -0
- package/docs/02-plugin-lifecycle.md +348 -0
- package/docs/03-contributes-spec.md +800 -0
- package/docs/04-distribution-format.md +172 -0
- package/docs/05-ui-conventions.md +549 -0
- package/docs/06-plugin-json-spec.md +640 -0
- package/docs/07-plugin-to-plugin-communication.md +299 -0
- package/docs/08-view-container-api.md +405 -0
- package/docs/09-plugin-directory-layout.md +301 -0
- package/docs/10-building-a-settings-plugin.md +164 -0
- package/docs/11-authoring-themes.md +173 -0
- package/docs/12-readme-media-contract.md +74 -0
- package/docs/13-development-guide.md +259 -0
- package/docs/14-data-pipeline-command-conventions.md +173 -0
- package/docs/15-multi-repo-and-local-workspace.md +86 -0
- package/docs/16-naming-conventions.md +77 -0
- package/docs/17-region-map.md +225 -0
- package/docs/18-cross-region-wiring.md +192 -0
- package/docs/19-component-cheatsheet.md +108 -0
- package/docs/20-adding-a-setting.md +159 -0
- package/docs/themes/01-build-a-theme-plugin.md +150 -0
- package/docs/themes/02-theme-field-index.md +145 -0
- package/docs/zh/00-README.md +189 -0
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +171 -0
- package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md +348 -0
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +800 -0
- package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +172 -0
- package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +549 -0
- package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +640 -0
- package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +299 -0
- package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +403 -0
- package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md +301 -0
- package/docs/zh/10-/345/246/202/344/275/225/351/200/240/344/270/200/344/270/252/350/256/276/347/275/256/346/217/222/344/273/266.md +164 -0
- package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +172 -0
- package/docs/zh/12-README/350/257/264/346/230/216/345/214/272/345/252/222/344/275/223/345/245/221/347/272/246.md +74 -0
- package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +259 -0
- package/docs/zh/14-/346/225/260/346/215/256/347/256/241/351/201/223/345/221/275/344/273/244/347/272/246/345/256/232.md +173 -0
- package/docs/zh/15-/345/244/232/344/273/223/345/274/200/345/217/221/344/270/216/346/234/254/345/234/260/345/267/245/344/275/234/345/214/272.md +86 -0
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +77 -0
- package/docs/zh/17-/345/214/272/345/237/237/345/234/260/345/233/276.md +225 -0
- package/docs/zh/18-/345/214/272/345/237/237/351/227/264/344/272/222/345/212/250.md +192 -0
- package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +108 -0
- package/docs/zh/20-/346/210/221/347/232/204/346/217/222/344/273/266/345/212/240/344/270/200/346/235/241/351/205/215/347/275/256/351/241/271.md +159 -0
- package/docs/zh/plugin.schema.json +687 -0
- package/docs/zh//344/270/273/351/242/230/01-/345/201/232/344/270/200/344/270/252/344/270/273/351/242/230/346/217/222/344/273/266.md +150 -0
- package/docs/zh//344/270/273/351/242/230/02-/344/270/273/351/242/230/345/255/227/346/256/265/351/200/237/346/237/245.md +145 -0
- package/package.json +20 -0
|
@@ -0,0 +1,348 @@
|
|
|
1
|
+
# 02 — Plugin Lifecycle
|
|
2
|
+
|
|
3
|
+
> 2026-07-24 · full rewrite 2026-08-21 · **2026-09-06 reconciled against the implementation** (flattened single root + zip distribution install/uninstall flow). **The complete state machine of a plugin, from existence to disappearance.**
|
|
4
|
+
> The foundation has been replaced: the early multi-process model (a dedicated render container per plugin) → **minimal Pool — 1 BrowserWindow + 1 WebContentsView, all plugin components render in the same renderer process**.
|
|
5
|
+
> Load/unload semantics are defined by the shell-side state machine + reversible registration + dependency orchestration (`src/pluginLoader/`). This page is all a third-party author needs to read.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Two load paths — repo source tree (HMR) and installed state (bundle)
|
|
10
|
+
|
|
11
|
+
Both startup scanning and file watching can discover plugins, and **both go through the single entry point `loadPlugin(pluginId, reason)`** (normalized — callers no longer decide for themselves "which path this takes"):
|
|
12
|
+
|
|
13
|
+
| Path | Source | How the manifest is read | How the JS entry is loaded |
|
|
14
|
+
|------|------|----------------|----------------|
|
|
15
|
+
| **repo source tree** (dev) | `<repo>/plugins/<id>/` (flattened single root, expanded with `import.meta.glob`) | Vite eager import | `loadPluginComponent` → Vite-built chunk (**HMR applies instantly**) |
|
|
16
|
+
| **installed state** | `{userData}/plugins/<id>/` (unpacked from a `.linkdesk-plugin` zip, `plugins.readManifest`) | `JSON.parse` | detect `index.bundle.js` → runtime dynamic import (in dev, `resolveUserDataBundles` points the react family back; in prod, `linkdesk://{id}`) — **prebuilt artifact: changing the package means rebuilding and reinstalling, no HMR** |
|
|
17
|
+
|
|
18
|
+
**One pipeline, `loadPlugin`, covers both paths**: repo goes through Vite modules, userData goes through a runtime bundle. Adding a capability only requires changing `loadPlugin` in one place.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 2. Startup load pipeline — `loadPlugin` step by step
|
|
23
|
+
|
|
24
|
+
Each `loadPlugin(pluginId, reason)` call executes in order (`reason` = `startup` | `install` | `reinstall` | `enable`):
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
markLoadStarted (PENDING → LOADING)
|
|
28
|
+
↓ ① read manifest (glob eager import / runtime IPC) — failure → markLoadFailed + toast
|
|
29
|
+
↓ ② minAppVersion check — versionGte not satisfied → markLoadFailed + toast
|
|
30
|
+
↓ ③ dependency check — cycle → fail-loud; missing → suspend to PENDING (see §4)
|
|
31
|
+
↓ ④ cache metadata (details stay browsable after unload)
|
|
32
|
+
↓ ⑤ load JS entry + statusBar (glob = chunk; runtime = dynamic import)
|
|
33
|
+
↓ ⑥ register views — runtime/entryless plugins use registerViewPlugin (see §2.2)
|
|
34
|
+
↓ ⑦ parse contributes → dispatch to each Registry (normalizeManifest → parseContributions, see §2.3)
|
|
35
|
+
↓ ⑧ themes / languages / i18n data files loaded asynchronously (fetch)
|
|
36
|
+
↓ ⑨ wrap up: loadedPluginIds.add + markLoadSuccess (→ ACTIVE) + sync theme/language enums + onDidInstall.fire
|
|
37
|
+
↓ ⑩ sweep the pending queue — load plugins whose dependencies are now satisfied (sweepPendingDependencies)
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**🔥 Hard constraint 13, race guard:** two concurrent `loadPlugin` calls → the second returns the first one's in-flight Promise (`_loadingPromises` Map). StrictMode double-mounts and watcher/startup-scan collisions are both safe.
|
|
41
|
+
|
|
42
|
+
### 2.1 Legacy format normalization + role derivation
|
|
43
|
+
|
|
44
|
+
- **`normalizeManifest` (a pure function — reads the manifest, never mutates it):** the legacy top-level `themes` / `languages` / `file` fields are folded into `contributes.themes` / `contributes.languages` automatically. New plugins write `contributes` directly and never deal with this layer.
|
|
45
|
+
- **Role derivation:** `pluginRole` is declared explicitly; when it is absent it is derived — `!manifest.entry && has contributes` → `"data"` (a pure data plugin: themes/language packs, no React components, component loading skipped). Plugins with `pluginRole: "data"` do not load a JS entry.
|
|
46
|
+
|
|
47
|
+
### 2.2 Entryless plugins — a view without an entry
|
|
48
|
+
|
|
49
|
+
**`entry` is not required.** Declaring `contributes.viewsContainers` (location defaults to sidebar) + `contributes.views` is enough — components are loaded from the path declared in `contributes.views[].render`, and `render` is a module path string, so no `index.tsx` entry is needed.
|
|
50
|
+
|
|
51
|
+
**Icon bar gap fix:** `!manifest.entry && hasSidebarContainers(manifest)` → the plugin also enters viewRegistry (metadata-only registration) — otherwise an entryless plugin declaring `appearsIn.iconBar` is silently dropped and no icon shows up in the icon bar. Components are loaded by ViewContainerService through the render path; the registry only acts as the metadata/icon entry point (component is empty, optional).
|
|
52
|
+
|
|
53
|
+
### 2.3 contributes → the registries
|
|
54
|
+
|
|
55
|
+
`parseContributions(pluginId, contributes)` checks each key and dispatches it to 12 consumption points (commands/menus/keybindings/configuration/configurationDefaults/themes/iconThemes/icons/languages/titleBar/viewsContainers/views/i18n) — **the full list is in `03-contributes-spec.md`**. Unrecognized keys are silently skipped — new contribution points work without changing the loader.
|
|
56
|
+
|
|
57
|
+
### 2.4 Load order (`initPluginLoader`)
|
|
58
|
+
|
|
59
|
+
1. Single-source discovery, `plugins:listAll` (the main process scans every subdirectory of plugins/ directly; dev and prod see the same surface) → the full entry list (including packaged/marketplace-installed plugins; glob has been retired)
|
|
60
|
+
2. `loadPlugin("startup")` one by one — **disabled plugins are skipped**; manifest/contributes are registered for everything, with **zero JS imports** (JS is lazily loaded by the pool per URL, see §5)
|
|
61
|
+
3. Ledger reconcile (two-way tombstones from the diff; entries are stamped, never deleted wholesale)
|
|
62
|
+
4. Error rollup → toast + diagnostic log (failed plugins and reasons go to the pluginLoader log channel)
|
|
63
|
+
5. Purge zombie cache entries (ghost entries with status="installed" that never actually loaded)
|
|
64
|
+
6. Boot sweep of `.disabled/` graveyard orphans (a graveyard copy surviving a restart = an ownerless copy whose same-session undo toast has expired → really delete it + clear the ghost `uninstalled` cache entry)
|
|
65
|
+
|
|
66
|
+
### 2.5 File watching (hot-plug)
|
|
67
|
+
|
|
68
|
+
`startPluginWatcher` polls `listDirs` every 2s:
|
|
69
|
+
- **A new directory appears** → `loadPlugin` loads it immediately (a repo source tree goes through the Vite chunk; userData goes through install discovery)
|
|
70
|
+
- **Loaded, but the directory was deleted manually** → `unloadPlugin(id, "uninstall")` removes the registrations automatically
|
|
71
|
+
- Skip conditions (`shouldWatcherSkip`): the state machine is `failed` / `pendingReason` has a value — this keeps the 2s poll from re-entering over and over and blowing up (a lesson from cycle-toast spam regressions)
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 3. State machine — `LOADING → ACTIVE / FAILED / PENDING`, unload `UNLOADING → DISPOSED`
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
PENDING ──loadPlugin──▶ LOADING ──all registrations live──▶ ACTIVE
|
|
79
|
+
▲ │ │ unload/disable
|
|
80
|
+
│ ▼ load throws ▼
|
|
81
|
+
└────────── FAILED ◀──record failureReason UNLOADING
|
|
82
|
+
(retry → LOADING) │ rollback complete
|
|
83
|
+
▼
|
|
84
|
+
DISPOSED
|
|
85
|
+
(reinstall/enable → LOADING)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
| State | Meaning |
|
|
89
|
+
|------|------|
|
|
90
|
+
| `pending` | Loading has not started. **Disabled plugins also sit at pending** — they never enter the state machine |
|
|
91
|
+
| `loading` | `loadPlugin` is running |
|
|
92
|
+
| `active` | All registrations are live and consumable |
|
|
93
|
+
| `unloading` | Unloading/disabling — the rollback window |
|
|
94
|
+
| `disposed` | Rollback complete, registrations cleared |
|
|
95
|
+
| `failed` | Load failed — inspectable through `failureReason` |
|
|
96
|
+
|
|
97
|
+
**A missing dependency suspends the plugin:** `loading → pending` is also a legal transition — `pendingReason` (e.g. `waiting for dependency: "a"`) records why, and the marketplace list shows "waiting for dependency".
|
|
98
|
+
|
|
99
|
+
**Transition rules (mechanically enforced):**
|
|
100
|
+
- **The unload side converges:** `pending/loading/failed → unloading` is always allowed — **an unload must always be able to finish at DISPOSED** (unloading while loading = race convergence; unloading a failed or never-loaded plugin = an honest clean-up), which stops plugins from getting stuck in an intermediate state.
|
|
101
|
+
- **The load side is strict:** illegal transitions such as `active → loading` (double load) only `console.warn` and do not take effect — this catches real bugs.
|
|
102
|
+
- **The state machine is a diagnostic surface, not a watchdog:** illegal transitions warn but never throw, and must never be allowed to take the load flow down. The diagnostic surface `getLoadDiagnostics(pluginId)` returns `loadState/failureReason/pendingReason/registeredEffects`.
|
|
103
|
+
|
|
104
|
+
**Three-way state boundary (do not conflate):**
|
|
105
|
+
|
|
106
|
+
| Layer | What it is | Who consumes it |
|
|
107
|
+
|------|------|------|
|
|
108
|
+
| **LoadState (this state machine)** | the diagnostic surface for "why is this plugin not active" | dev panel / diagnostic log |
|
|
109
|
+
| **CachedPluginMeta.status** | installation state: `installed` / `disabled` / `uninstalled` | marketplace (a disabled plugin sitting at PENDING does not conflict) |
|
|
110
|
+
| **PluginStateService** | plugin-private storage, not a state | the plugin itself, read/write |
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## 4. Dependency orchestration — `requires`
|
|
115
|
+
|
|
116
|
+
**`requires: string[]` declares a plugin-level activation-order dependency** (by pluginId: the dependency must be activated before this plugin). The old `extensionDependencies` field is merged in for compatibility (deprecated — use `requires` uniformly).
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"requires": ["file-tree", "editor"]
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**Three rules at load time:**
|
|
125
|
+
|
|
126
|
+
| Case | Behavior |
|
|
127
|
+
|------|------|
|
|
128
|
+
| **Dependency already active** | load normally |
|
|
129
|
+
| **Missing dependency** | **suspend to PENDING** (not a failure) — `pendingReason = "waiting for dependency: "xxx""`, the manifest stays in the pending registry; once the dependency is ready a sweep loads it automatically (topological activation order, so scan order no longer affects activation order) |
|
|
130
|
+
| **Dependency cycle** (self-cycle + transitive cycle A→B→C→A) | **fail-loud** — toast + `markLoadFailed`. Cycle detection is graph-level, not pairwise |
|
|
131
|
+
|
|
132
|
+
**Every plugin load that completes → sweep the pending queue** (load whatever now has its dependencies). Convergence: each round of the while loop continues only if it activated at least one pending plugin; a guard of 1000 is the backstop against extreme race-condition livelocks.
|
|
133
|
+
|
|
134
|
+
**Unload cascades when a dependency disappears:** when triggered by unload, disable, or directory deletion, first cascade-unload the **active consumers** of the plugin being removed (reverse topological order — during its rollback a consumer may query the dependency's registry contributions, so the dependency must go last):
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
unload plugin A
|
|
138
|
+
→ cascade-unload every active plugin whose requires contains A (recursively — their consumers go first too)
|
|
139
|
+
→ for each consumer: roll back all registrations + drop to PENDING (waiting for the dependency to return, not unloaded) + pendingReason
|
|
140
|
+
→ once the dependency returns, a sweep loads them automatically (automatic revival)
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
**Explicit user disable wins:** a disabled consumer plugin is never auto-activated by a dependency-appears event (disable intent outranks dependency orchestration, which stops a disabled plugin from "coming back to life").
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 5. When JS loads — zero shell imports, the pool activates on demand (settled; replaces activationEvents)
|
|
148
|
+
|
|
149
|
+
> 🔴 **Retired 2026-09-09: the `activationEvents` field has been removed entirely** (the shell-side deferred activation track is fully retired — activation.ts / loader defer / `activatePlugin` / the CommandRegistry pre-activation hook are all deleted, and the field is gone from the three copies of the schema). **The shell always registers the full metadata set at startup** (`loadPlugin(pluginId, "startup")`, zero JS imports); plugin **JS is lazily loaded by the pool per URL**. There is no field to write and nothing to declare — only the two on-demand tracks below remain.
|
|
150
|
+
|
|
151
|
+
**Metadata is registered at startup:** `initPluginLoader` discovers every plugin → the shell registers manifest/contributes (command display names/menus/config schemas/icon bar metadata are all visible) — **without importing any plugin JS** (hard constraint #17d: zero plugin source in the shell bundle).
|
|
152
|
+
|
|
153
|
+
**JS loading = the pool's two on-demand tracks (the plugin author's contract):**
|
|
154
|
+
|
|
155
|
+
| Track | Trigger | Mechanism | Applies to |
|
|
156
|
+
|------|---------|------|------|
|
|
157
|
+
| **① Surface mount** | a view opens (contributes.views / main-area tab) | the pool's `PluginComponent`/`PluginDetailViewHost` dynamically import the view URL through `resolvePluginViewLoader` (dev `/@fs`, prod `linkdesk://`) | plugins with views/an entry |
|
|
158
|
+
| **② on-command activation** | command miss — `window.linkdesk.commands.executeCommand` hits an unregistered command | the pool's preload callback calls back into the renderer → `import` the **owning plugin's entry** (top-level side effects register the command handler) → retry hits | **pure command plugins with no view to open** (the gap where the entry is never imported by any surface) |
|
|
159
|
+
|
|
160
|
+
**🔴 Contract for pure command-plugin authors: command handlers must live at the top level of the entry (module scope), not only inside a view component.** A `registerCommand` inside a view component only runs when that view mounts — if the plugin has no openable surface (or its surfaces never open), the entry is never imported and the command always misses. Top-level registration means a single import during on-command activation puts everything in place (`import()` module caching is idempotent, so repeated misses do not re-run it). View-style plugins (whose commands are mostly registered in view mount) are covered by track ① by nature and need no top-level duplicate.
|
|
161
|
+
|
|
162
|
+
**Entry import safety convention:** the entry's top level must not depend on "some DOM container already exists" in order not to crash (view rendering goes through component exports + pool mounting; do not createRoot at the entry top level) — the same as the current main-area tab behavior (the pool already imports the entry directly for main-area tabs).
|
|
163
|
+
|
|
164
|
+
> **Honest caveat:** track ② is shared by two miss paths — the pool preload's `executeLocal` (shell placeholder commands forwarded through executeRequest) and the pool's direct `executeCommand` call. After a hit it retries once; if the entry import completes and the command still misses (it really is registered only in a view component), the original semantics apply and it rejects with "command not registered in the pool". There is no event-level precision control like `activationEvents` — registering the full metadata set at startup + importing JS on demand is the current model.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## 6. Runtime contract — `isActive` + keep-alive + tabBehavior
|
|
169
|
+
|
|
170
|
+
**The `isActive` prop convention (entry component):**
|
|
171
|
+
|
|
172
|
+
| Scenario | `isActive` |
|
|
173
|
+
|------|:--:|
|
|
174
|
+
| Tab is in the foreground and its split panel is active | `true` |
|
|
175
|
+
| Tab is covered by another tab | `false` |
|
|
176
|
+
| The tab's panel is inactive (with a split, another panel is active) | `false` |
|
|
177
|
+
|
|
178
|
+
**keep-alive mechanism:** all tab content stays mounted; switching uses CSS `display`. Do not use conditional rendering such as `{isActive && <View/>}` — that destroys Monaco/Canvas state.
|
|
179
|
+
|
|
180
|
+
```tsx
|
|
181
|
+
// ✅ Correct — guard side effects with isActive (hard constraint 14)
|
|
182
|
+
useEffect(() => {
|
|
183
|
+
if (!isActive) return;
|
|
184
|
+
editorRef.current?.layout(); // re-layout Monaco
|
|
185
|
+
}, [isActive]);
|
|
186
|
+
|
|
187
|
+
// ❌ Wrong — destroys component state
|
|
188
|
+
if (!isActive) return null;
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
**`tabBehavior` (a top-level field) determines tab semantics:**
|
|
192
|
+
|
|
193
|
+
| Declaration | Behavior |
|
|
194
|
+
|------|------|
|
|
195
|
+
| default (nothing declared) | every click on the icon → creates a new tab |
|
|
196
|
+
| `singleton: true` | only one instance globally. Repeated clicks → focus the existing tab |
|
|
197
|
+
| `isFallback: true` | created automatically when no tab is open. Cannot be closed. Only the welcome page declares it |
|
|
198
|
+
| `confirmOnClose` | show a confirmation dialog before closing (the value = the prompt text) |
|
|
199
|
+
| `identityField` | tab identity field — the same name does not open twice (e.g. workspace declares `"workspaceName"`) |
|
|
200
|
+
|
|
201
|
+
```json
|
|
202
|
+
{
|
|
203
|
+
"tabBehavior": {
|
|
204
|
+
"singleton": true,
|
|
205
|
+
"confirmOnClose": "Close the settings page?"
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
> The `invokeBeforeClose` veto loop has been deactivated (that loop was deleted) — the declaration is kept for a future pool-side requests namespace; `confirmOnClose` still works.
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## 7. Reversible registration — registrationTracker
|
|
215
|
+
|
|
216
|
+
**Every registration returns a disposer, and unload rolls back in reverse order (LIFO — whatever registered last rolls back first).**
|
|
217
|
+
|
|
218
|
+
- **Recording:** each `register()` adds its entry to the table and then calls `trackRegistration(pluginId, disposer)` to record a "delete this one entry" disposer.
|
|
219
|
+
- **Trigger:** when the module loads it subscribes once to `PluginLifecycle.onWillUninstall` → any plugin with registrations is **rolled back in reverse order automatically** on unload/disable — no manual unregister* clean-up is needed (every per-entry manual clean-up consumer has been removed).
|
|
220
|
+
- **Idempotent:** the returned disposer carries a done guard — a manual dispose and a rollback running together do not clean up twice.
|
|
221
|
+
- **Fault-tolerant:** one disposer throwing does not interrupt the rest of the rollback (the error goes to the ErrorService diagnostic surface).
|
|
222
|
+
- **Coverage:** class-based registries (RegistryBase.track) and function-based registries (Command/Keybinding/Menu/Configuration…, which call trackRegistration directly) share the same mechanism.
|
|
223
|
+
|
|
224
|
+
**Plugin authors do not have to do anything** — when your component mounts, `registerCommand`/`window.linkdesk.*` registers on the pool side; on unload the shell rolls everything back in reverse order. Unloading is atomic and never leaves ghost registrations from half a plugin behind.
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## 8. Unload state machine — `unloadPlugin` (the single unload path)
|
|
229
|
+
|
|
230
|
+
**Three production flows share one unload entry point:** user uninstall, user disable, and the file watcher finding a deleted directory. The order is mechanically enforced by the transition graph (previously 5 lifecycle functions each maintained 5-6 side effects = 30 maintenance points, and 80 commits fixed the same missed spot):
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
unloadPlugin(pluginId, reason, displayName)
|
|
234
|
+
reason = "uninstall" | "disable"
|
|
235
|
+
① idempotency guard — already unloading/disposed → skip
|
|
236
|
+
② cascade-unload consumers (cascadeDependents, reverse topological order, see §4)
|
|
237
|
+
③ clear this plugin's pending registration
|
|
238
|
+
④ transition → UNLOADING
|
|
239
|
+
⑤ notifyPluginRemoved — CustomEvent PLUGIN_REMOVED → the shell closes the related tabs + sidebar views
|
|
240
|
+
🔥 must come before onWillUninstall: the shell's revert logic reads the manifest from viewRegistry,
|
|
241
|
+
and the tracker rollback deletes the viewRegistry entry synchronously inside fire — fire first and the revert silently fails
|
|
242
|
+
⑥ onWillUninstall.fire — the registrationTracker's reverse rollback runs synchronously here (all registrations cleared)
|
|
243
|
+
⑦ loadedPluginIds.delete + _deferredPlugins.delete
|
|
244
|
+
⑧ transition → DISPOSED
|
|
245
|
+
⑨ onDidUninstall.fire — toast (with an "Undo" button) + view refresh + IPC plugin:uninstalled broadcast
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
**Cascade unload (orphanPlugin) follows the same sequence but lands in PENDING:** `unloading → notifyPluginRemoved → onWillUninstall [tracker rollback] → clear collections → pending` — it does not fire onDidUninstall (not a user uninstall, so it is silent; the consequence toast is aggregated by the top-level unloadPlugin: "Plugin X moved to waiting because dependency A disappeared — it will be enabled automatically once the dependency returns").
|
|
249
|
+
|
|
250
|
+
**Lifecycle event overview (`PluginLifecycle` Emitter):**
|
|
251
|
+
|
|
252
|
+
| Event | Payload | When it fires |
|
|
253
|
+
|------|------|------|
|
|
254
|
+
| `onDidInstall` | `{ pluginId, manifest, reason: install/reinstall/enable/startup }` | after all registrations are live |
|
|
255
|
+
| `onWillUninstall` | `{ pluginId, reason: uninstall/disable, displayName }` | before rollback (the viewRegistry entry still exists) |
|
|
256
|
+
| `onDidUninstall` | same as above | after rollback completes (the viewRegistry entry is gone) |
|
|
257
|
+
|
|
258
|
+
Consumers (built into the shell; plugins do not care): icon ordering (install/reinstall appends at the end; uninstall removes; disable/enable keeps the position), toasts (silent for startup), view refresh, IPC `plugin:installed`/`plugin:uninstalled` broadcasts (install/reinstall/uninstall only).
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## 9. Lifecycle operations — install / enable / disable / uninstall / reinstall
|
|
263
|
+
|
|
264
|
+
### 9.1 Install `installPlugin(sourcePath)` (the zip distribution route)
|
|
265
|
+
|
|
266
|
+
`sourcePath` adapts to three forms (`isPackageSource`): a directory path / an `http(s)://` URL / an on-disk `.linkdesk-plugin` zip. **The primary distribution route is the zip / URL package source** (single-file zip); directory sources are only a dev convenience.
|
|
267
|
+
|
|
268
|
+
```
|
|
269
|
+
validating → package source: main process plugins:download / plugins:extract → validate before extracting
|
|
270
|
+
(locate the top-level plugin.json in the zip + JSONC parsing + pluginId resolution + zip-slip protection — never leave a half-installed directory)
|
|
271
|
+
→ directory source: plugin.json exists + parses as valid JSON
|
|
272
|
+
→ pluginId resolution (**manifest.pluginId wins**; the zip basename / source directory name is the fallback —
|
|
273
|
+
**the fallback exists only for legacy third-party plugins**; new plugins always declare it explicitly, see [16-naming-conventions](16-naming-conventions.md); it must pass the safe character set); version is required
|
|
274
|
+
→ the target {userData}/plugins/<id>/ already exists → compare versions from disk (resolveVersionConflict):
|
|
275
|
+
same version → skip (the package source removes the duplicate source); different version → reject (upgrades go through checkUpdates/update, no overwrite)
|
|
276
|
+
extracting → unzip into {userData}/plugins/<id>/ (wrapper stripped)
|
|
277
|
+
→ sanitize the manifest: leftover `distribution` fields are always normalized to user (after the 2026-09-05 flattening there is no builtin/user directory semantics)
|
|
278
|
+
→ main process notifyManifestChanged (rescan the LangDef/Protocol/FileAssociation tables)
|
|
279
|
+
loading → loadPlugin(pluginId, "install") (the installed bundle path loads immediately)
|
|
280
|
+
→ success toast "Installed: name v1.0.0"
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
**Version policy (settled): no overwrite-install** — the same version is skipped (no need to reinstall), a different version is rejected (upgrades go through the update flow, see [04-distribution-format §4](04-distribution-format.md)). A real upgrade = stage → atomic replace → revert to the old version on failure (`PluginUpdateService`).
|
|
284
|
+
|
|
285
|
+
### 9.2 Enable `enablePlugin(pluginId)`
|
|
286
|
+
|
|
287
|
+
Remove from the `disabledPlugins` list → `loadPlugin(pluginId, "enable")`. Takes effect immediately for a repo source tree; for installed (userData bundle) plugins, if runtime dynamic injection is not possible it returns `needRestart: true`.
|
|
288
|
+
|
|
289
|
+
### 9.3 Disable `disablePlugin(pluginId)`
|
|
290
|
+
|
|
291
|
+
Add to the `disabledPlugins` list + persist → mark the metadata cache `disabled` → **theme/language fallback** (if the current theme/language comes from this plugin → switch to a replacement) → `unloadPlugin(pluginId, "disable")`. **The plugin files are kept** and skipped on the next startup. Disable → iconOrder keeps the position (restored when re-enabled). Comparable to VS Code's "Disable Extension".
|
|
292
|
+
|
|
293
|
+
### 9.4 Uninstall `uninstallPlugin(pluginId)`
|
|
294
|
+
|
|
295
|
+
1. `core: true` guard first — for core:true plugins the uninstall button is not shown/disabled in the UI (**a mistaken-deletion flag, not a category**: the shell depends on such a plugin for basic interactions like the settings page and the marketplace)
|
|
296
|
+
2. **Two branches (after the 2026-09-05 flattening)**:
|
|
297
|
+
- the target lives in `{userData}/plugins/<id>/` (installed from a zip) → **really delete the directory + settle the account with `PluginInstallService.remove`** (writes a removed marker — boot sees the marker and does not restore it automatically)
|
|
298
|
+
- the target lives in the repo source tree (an app plugin) → move it to the `plugins/.disabled/<id>/` graveyard + it can be reinstalled (a lesson from Windows file locks on cross-directory rename: copy+remove, not rename)
|
|
299
|
+
3. mark the metadata cache `uninstalled` (the marketplace can still browse details after uninstall)
|
|
300
|
+
4. theme/language fallback → `unloadPlugin(pluginId, "uninstall")`
|
|
301
|
+
5. clear the disable list (uninstall outranks disable) → sync enums → toast "Uninstalled: name" → `notifyManifestChanged`
|
|
302
|
+
|
|
303
|
+
### 9.5 Reinstall `reinstallPlugin(pluginId)`
|
|
304
|
+
|
|
305
|
+
For source-tree app plugins: copy from `plugins/.disabled/<id>/` back to `plugins/<id>/` → `loadPlugin(pluginId, "reinstall")`. Reinstalling an installed plugin = running the install flow again (9.1). Comparable to VS Code keeping a local copy after uninstall for one-click reinstall — **any plugin that can be uninstalled must restore all of its contributions in the same session when reinstalled** (see 9.6).
|
|
306
|
+
|
|
307
|
+
### 9.6 🔥 The uninstallable ⇒ reinstallable contract
|
|
308
|
+
|
|
309
|
+
**For any plugin, if it can be uninstalled, reinstalling must restore all of its contributions immediately in the same session** — regardless of the plugin's shape: repo source tree or installed state, with or without an entry, core flag or not (core is only a mistaken-deletion flag, not a category exception).
|
|
310
|
+
|
|
311
|
+
**Implementation dependency:** the normalized plugin root URL entry `resolveRuntimePluginRoot` (the same one-liner `dev ? /@fs/{abs} : linkdesk://{id}`) — for entryless plugins (pure views/commands contributions) the `views` registration fallback chain depends on it for dynamic imports. It once broke because the pluginRoot assignment was hard-tied to `manifest.entry` (view loading failed after reinstalling an entryless plugin) — now fixed.
|
|
312
|
+
|
|
313
|
+
---
|
|
314
|
+
|
|
315
|
+
## 10. Error handling
|
|
316
|
+
|
|
317
|
+
| Error | Shell behavior | Plugin's responsibility |
|
|
318
|
+
|------|------|------|
|
|
319
|
+
| malformed plugin.json | skip the plugin + toast + `markLoadFailed` | validate the format (use `$schema` in your IDE for autocomplete) |
|
|
320
|
+
| `minAppVersion` not satisfied | toast "requires app version ≥X" + `markLoadFailed` | declare a conservative minAppVersion |
|
|
321
|
+
| dependency cycle | toast + `markLoadFailed` (fail-loud) | don't create cycles — check the requires topology |
|
|
322
|
+
| missing dependency | **suspend to PENDING** (not a failure) — loads automatically once the dependency is ready | install the dependency first |
|
|
323
|
+
| entry file not found | toast + `markLoadFailed` | make sure the entry path is correct |
|
|
324
|
+
| runtime JS load failure (possibly not built) | toast "possibly not built" — **does not block**: contributes are still registered | build before installing |
|
|
325
|
+
| React component throws | ErrorBoundary catches → ""Plugin name" crashed [Retry]" | don't write code that crashes |
|
|
326
|
+
| a disposer throws during unload | no interruption — registrationTracker tolerates errors per entry and sends them to the diagnostic surface | — |
|
|
327
|
+
| concurrent loadPlugin (StrictMode double-mount) | the second waits for the first Promise (hard constraint 13) | — |
|
|
328
|
+
|
|
329
|
+
---
|
|
330
|
+
|
|
331
|
+
## 11. Comparison with VS Code
|
|
332
|
+
|
|
333
|
+
| Dimension | VS Code | LinkDesk |
|
|
334
|
+
|------|---------|----------|
|
|
335
|
+
| Activation timing | many `activationEvents` (onLanguage/onCommand/workspaceContains…) | **no event field** (retired) — the full metadata set is registered at startup; JS is loaded by the pool on demand |
|
|
336
|
+
| Lazy loading | extension JS imported on demand | zero JS imports at shell startup (#17d); the pool is the only JS executor — a surface mount lazily loads the URL / a command miss imports the entry (on-command activation, §5) |
|
|
337
|
+
| Load scanning | scan `extensions/` at startup | single-source discovery, `plugins:listAll`, scanning directly in the main process (same surface in dev/prod) + 2s polling for hot-plug |
|
|
338
|
+
| Dependencies | `extensionDependencies` | `requires` (string array) + suspend to PENDING / cycle fails / cascade unload |
|
|
339
|
+
| Uninstall | Disable / Uninstall | installed state = really delete the directory + settle the account (a removed marker, boot does not revive it); repo source-tree app plugins = move to `.disabled/` as a **same-session** undo (orphans surviving a restart are cleaned automatically at boot) |
|
|
340
|
+
| Clean-up | manual unregister in onWillUninstall | **registrationTracker rolls back automatically in reverse order** (zero manual clean-up) |
|
|
341
|
+
| core plugins | cannot be uninstalled | `core: true` plugins have no uninstall entry in the detail UI (a pure mistaken-deletion flag — the API/command layer can still uninstall and disable them; after uninstall a removed tombstone is written and they do not come back) |
|
|
342
|
+
|
|
343
|
+
---
|
|
344
|
+
|
|
345
|
+
> **← Previous:** `01-plugin-api-contract.md`
|
|
346
|
+
> **→ Next:** `03-contributes-spec.md`
|
|
347
|
+
> **→ Related:** `04-distribution-format.md` (the file shapes of install/uninstall)
|
|
348
|
+
> **All documentation index:** `00-readme.md`
|