@type32/vertex-plugin 1.1.0 → 1.1.1

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.
@@ -0,0 +1,116 @@
1
+ # The package
2
+
3
+ ## What Vertex installs
4
+
5
+ A folder named by the plugin's id:
6
+
7
+ | File | |
8
+ | --- | --- |
9
+ | `plugin.json` | The manifest. |
10
+ | `main.js` | One ES module with no imports; its default export is `definePlugin({setup})`. |
11
+ | `styles.css` | Optional. Put in the page when the plugin loads, before its code runs. |
12
+ | `locales/<locale>.json` | Optional. The plugin's strings. |
13
+ | anything else | Assets, read through [`ctx.plugin.assetUrl`](context.md#ctxpluginid-ctxpluginversion-ctxpluginsource-ctxpluginasseturl). |
14
+
15
+ Vertex keeps it in its data folder (`plugins/<id>/`), or in a workspace's `.vertex/plugins/<id>/` for a workspace's
16
+ own ([Trust](trust.md#a-workspaces-plugins)), with `.install.json` beside, its record of where it came from.
17
+
18
+ ## `plugin.json`
19
+
20
+ Unknown keys are errors; the build lists every problem.
21
+
22
+ | Key | |
23
+ | --- | --- |
24
+ | `id` | Lowercase letters, digits and inner hyphens, at most 50 characters. The installed folder's name. It names the plugin's strings (`plugins.<id>`), settings (`plugins.config.<id>`), data and secrets, so it's for good. It can't be a core plugin's (`files`, `canvas`, `bases`, `git`, `chat`, `ai`…). |
25
+ | `name` | Shown in Settings and in messages ("Hello couldn't start"). Not translated. |
26
+ | `version` | Shown, compared for updates, and what a release's tag should be (`0.2.0` or `v0.2.0`). |
27
+ | `description` | Optional, one sentence, shown in Settings and the install dialog. |
28
+ | `icon` | Optional. An Iconify name (`i-lucide-hand`) for the plugin's rows and settings page. |
29
+ | `author` | Optional, shown. |
30
+ | `repository` | Optional. Its Git repository, `https://…`: where it says it lives. Vertex shows it, and records where it actually fetched the plugin from, which it uses for updates ([Publishing](publishing.md)). |
31
+ | `apiVersion` | `1`. Vertex refuses a plugin that asks for a newer one ([Versions](versions.md)). |
32
+ | `minAppVersion` | Optional. The oldest Vertex it runs in (`0.9.2`); an older one keeps it off. |
33
+ | `windows` | Optional. The kinds of window it runs in: `session` (a workspace or a file), `main` (the start page), `settings`. Default `["session"]`. A plugin with a settings page of its own runs in `settings` too. |
34
+ | `requires` | Optional. Plugin ids it needs (`["bases"]`); a trailing `?` marks one it uses when it's there (`"chat?"`). Without a required one, it's off and Settings says why. |
35
+ | `permissions` | Optional. `network`, `secrets`, `files-outside-workspace` ([what each grants](config.md#permissions)). |
36
+ | `enabledByDefault` | Optional. Ignored for a plugin someone installs, which the install turns on. |
37
+ | `config` | Optional. Its settings: `schema` (drawn by Settings), `overridable` (what a workspace may change) ([Config](config.md)). |
38
+
39
+ ## The build
40
+
41
+ `vertex(options)` from `@type32/vertex-plugin/vite`, in `vite.config.ts`:
42
+
43
+ - builds `options.entry` (default `src/main.ts`) as one `main.js`: everything it imports is bundled, dynamic imports
44
+ included (`main.js` is loaded from memory, where a second file can't be found), and `process.env.NODE_ENV` is
45
+ `production`;
46
+ - reads [the modules Vertex shares](#what-the-plugin-shares-with-vertex) from Vertex's own copies;
47
+ - runs Tailwind, and writes the plugin's CSS as `styles.css`;
48
+ - checks `plugin.json` and `locales/*.json` and copies them;
49
+ - copies `public/` (Vite's own rule) to the top of `dist/`;
50
+ - with `pack: true`, writes `plugin.zip` beside `dist/`, the asset a release carries ([Publishing](publishing.md)).
51
+ - with `vite build --watch`, builds again on each change of the source, never of its own output.
52
+
53
+ Add `@vitejs/plugin-vue` before it to write `.vue` files.
54
+
55
+ ## What the plugin shares with Vertex
56
+
57
+ Some imports aren't bundled: the build turns them into Vertex's own copies, so there's one Vue, one editor and one
58
+ Nuxt UI in a window, and a plugin's `ref` or toast is the app's:
59
+
60
+ - `vue`;
61
+ - `@codemirror/autocomplete`, `commands`, `lang-markdown`, `language`, `language-data`, `lint`, `search`, `state`,
62
+ `view`, and `@lezer/common`, `highlight`, `markdown`;
63
+ - `@type32/codemirror-rich-obsidian-editor`, `/kit`, `/ext` (Vertex's editor);
64
+ - `@nuxt/ui/composables` (`useToast`, `useOverlay`…). Nuxt UI's components aren't imported: they're there by name.
65
+ Any other import from `@nuxt/ui` fails the build;
66
+ - this package: `@type32/vertex-plugin` (`definePlugin`), `/ui` ([Vertex's components](ui.md#vertexs-components)),
67
+ `/vault`, `/links`, `/files`, `/text` (the helpers below).
68
+
69
+ Importing a name Vertex's copy doesn't export fails the build. These are the versions this package depends on; a new
70
+ major of one is a new `apiVersion`.
71
+
72
+ The helpers are Vertex's own, the ones its features use:
73
+
74
+ | Module | |
75
+ | --- | --- |
76
+ | `@type32/vertex-plugin/vault` | `Vault` (what [`session.files.vault`](session.md#sessionfilesvault) returns), path helpers, tags, patterns, frontmatter written as Obsidian writes it (`setFrontmatterProperty`). |
77
+ | `@type32/vertex-plugin/links` | Wiki links in Markdown text: `getInternalLinks`, `rewriteLinks`, `renameTargets` (for a [link extractor](context.md#ctxindexlinkextractor)). |
78
+ | `@type32/vertex-plugin/files` | File names and kinds: `fileNameFromPath`, `getFileExtensionFromPath`, `isImage`, `isPlainTextFile`, `IMAGE_TYPES`. |
79
+ | `@type32/vertex-plugin/text` | Line diffs: `lineDiff`, `diffCounts` (what `TextDiff` draws). |
80
+
81
+ ## Dependencies
82
+
83
+ Any other package is bundled into `main.js`: install it and import it (`d3-force`, `yaml`). Keep an eye on the size:
84
+ `main.js` is read whole when a window starts the plugin. A part used rarely can be a file in `public/`, loaded with
85
+ `import(ctx.plugin.assetUrl('part.js'))` when it's needed; it must be built as a module of its own, with no imports.
86
+
87
+ A dependency that imports `@vue/reactivity` or `@vue/runtime-core` itself (not `vue`) gets its own copy of them,
88
+ which doesn't react with Vertex's.
89
+
90
+ ## Strings
91
+
92
+ A plugin's strings are files, `locales/<locale>.json`, so Settings can show its labels without running it:
93
+
94
+ ```json
95
+ {"plugins": {"hello": {"view": "Hello", "count": "{n} notes"}}}
96
+ ```
97
+
98
+ - Everything is under `plugins.<id>`; Vertex reads nothing else from the file.
99
+ - `en.json` is required once there are strings. Any other locale has exactly its keys, each with the same `{params}`.
100
+ A language the plugin has no file for shows English.
101
+ - Every i18n key `plugin.json` names (its schema's labels, descriptions and options' labels) must be in `en.json`.
102
+ - The build checks all of it.
103
+
104
+ Where the contract says "i18n key" (a view's `label`, a command's, a file type's), give a key of the plugin's,
105
+ `plugins.<id>.…`, not text: Vertex translates it where it draws it, in the window's language, and follows a change of
106
+ language. Where it says "already translated" (a header button's label, a tab's `describe`), give text, from
107
+ [`ctx.i18n.t`](context.md#ctxi18nt-ctxi18nlocale). Vertex's languages are `en` and `zh-CN`.
108
+
109
+ ## What can't be done
110
+
111
+ - **Native code.** A plugin is JavaScript in Vertex's webview. What it can reach of the computer is what the contract
112
+ offers (files through the session, the network through `ctx.http`, the keychain through `ctx.secrets`).
113
+ - **Imports at run time**, besides its own files through `ctx.plugin.assetUrl`: `main.js` has none.
114
+ - **A sandbox.** A plugin runs as Vertex does; users are told so ([Trust](trust.md)).
115
+ - **Another community plugin's typed API.** `ctx.provide` works for any plugin, but `ctx.use` is typed for Vertex's own
116
+ plugins' APIs only ([`ctx.use`](context.md#ctxprovide-ctxuse-ctxwhenplugin)).
@@ -0,0 +1,71 @@
1
+ # Publishing
2
+
3
+ A plugin is published from a public Git repository on GitHub, GitLab, Gitea or Forgejo (self-hosted ones included).
4
+ Users install it with the repository's link (Settings → Plugins → Install…), and Vertex finds its updates there. It
5
+ needs no account and no forge API: it reads the repository's refs over HTTPS, as `git ls-remote` does.
6
+
7
+ Set `repository` in `plugin.json` to the repository's URL: Vertex shows it, and offers Use its repository to someone who
8
+ installed the plugin from elsewhere.
9
+
10
+ ## A release with `plugin.zip` (recommended)
11
+
12
+ A release whose tag is a version (`0.2.0` or `v0.2.0`, without a pre-release suffix) with an asset named `plugin.zip`:
13
+ the built plugin, its files at the top. `vertex({pack: true})` writes it beside `dist/`.
14
+
15
+ A workflow that releases on a tag, `.github/workflows/release.yml`:
16
+
17
+ ```yaml
18
+ name: Release
19
+
20
+ on:
21
+ push:
22
+ tags: ['v*']
23
+
24
+ permissions:
25
+ contents: write
26
+
27
+ jobs:
28
+ release:
29
+ runs-on: ubuntu-latest
30
+ steps:
31
+ - uses: actions/checkout@v5
32
+ - uses: oven-sh/setup-bun@v2
33
+ - run: bun install --frozen-lockfile
34
+ - run: bun run typecheck
35
+ - run: bun run build
36
+ - run: gh release create "$GITHUB_REF_NAME" plugin.zip --title "$GITHUB_REF_NAME" --generate-notes
37
+ env:
38
+ GH_TOKEN: ${{ github.token }}
39
+ ```
40
+
41
+ Then a release is: bump `version` in `plugin.json`, commit, `git tag v0.2.0`, `git push --tags`. Commit `bun.lock`.
42
+
43
+ Vertex picks the newest version tag whose release has a `plugin.zip` (the three newest are tried). On GitLab, the
44
+ asset is a release link whose direct path is `/plugin.zip`.
45
+
46
+ ## A branch of built files
47
+
48
+ A branch that holds the built plugin (`plugin.json` and `main.js` together) at its top or in `dist/`, followed as it
49
+ moves. A workflow can push `dist/` to a `dist` branch on each push to the main branch. A branch that holds only the
50
+ source is refused, with what to install instead.
51
+
52
+ ## What users can install
53
+
54
+ | They give | Vertex installs | Updates |
55
+ | --- | --- | --- |
56
+ | The repository's link | The newest release with `plugin.zip` | A newer release |
57
+ | A link to a branch (`…/tree/dist`) | That branch's files | A new commit |
58
+ | A link to a tag, or a commit | Those files | None: pinned |
59
+ | A `.zip` URL | The `.zip` | Other bytes at the URL |
60
+ | A `.zip` file or a folder | It | None (a folder is watched while developing) |
61
+
62
+ Users choose among the repository's latest release, its branches and its tags in the install dialog.
63
+
64
+ ## Updates
65
+
66
+ Vertex asks a plugin's source whether there's something newer when the user checks (Settings → Plugins → Check for
67
+ updates), and daily if they turned that on. A check sends one request per repository, carrying nothing about the user.
68
+ An update installs only when the user accepts it, through the same dialog, which shows what changed.
69
+
70
+ A workspace's copy of a plugin is pinned ([Trust](trust.md#a-workspaces-plugins)): an update installed from Settings is
71
+ pinned with it, and a copy changed any other way is off until the user accepts it again.
@@ -0,0 +1,205 @@
1
+ # The session
2
+
3
+ A session window shows a workspace (a folder) or a single file. Its `SessionContext` is what a plugin works with
4
+ there: the workspace's index and files, the tabs, the editors. Views, viewers, tabs, status items and overlays get it
5
+ as their `session` prop; [`ctx.onSession`](context.md#ctxonsession) gets it for work that isn't drawn.
6
+
7
+ Files are named three ways: by **uuid** (the index's id for a file, stable across renames while Vertex runs, also its
8
+ tab's id), by **absolute path**, and by **workspace-relative path** (`notes/a.md`; `''` is the top level). Each member
9
+ says which it takes. In a single-file window the index is empty.
10
+
11
+ ### `session.session`
12
+
13
+ The window's session (`ActiveSession`): its `uuid`, whether it's a workspace's (`workspaceSession`), and the
14
+ workspace's `rootPath`.
15
+
16
+ ## Views
17
+
18
+ ### `session.views.show`, `session.views.openInTab`
19
+
20
+ `show(id)` shows a panel view in its pane (out of Hidden, its area expanded), `false` when no pane can show it.
21
+ `openInTab(id)` opens a view registered with `tab: true` in a tab.
22
+
23
+ ## The index
24
+
25
+ The workspace's files and links, kept up to date as files change, by Vertex or outside it. Reactive: a `computed`
26
+ that reads it follows.
27
+
28
+ ### `session.index.files`, `session.index.byPath`, `session.index.byUuid`
29
+
30
+ Every file and folder (`ActiveWorkspaceFileIndex`: `uuid`, `fullPath`, `relativePath`, `fileName`, `fileExt`,
31
+ `isFolder`, `size`, `properties` (a note's frontmatter), `forelinks`, `backlinks` (uuids), `meta` (a note's tags, link
32
+ texts, embeds), `createdTime`, `modifiedTime`), and one by absolute path or uuid.
33
+
34
+ ### `session.index.tree`
35
+
36
+ Folders and files as Files shows them: the top level, each folder's `children`, sorted.
37
+
38
+ ### `session.index.resolveLink`
39
+
40
+ The file a link target finds (`resolveLink('Some note')` for `[[Some note]]`), as the editor resolves it.
41
+
42
+ ### `session.index.backlinks`, `session.index.forelinks`, `session.index.links`, `session.index.unresolved`
43
+
44
+ A file's backlinks and forelinks (uuids), every resolved link as `{from, to}` uuids (a graph's edges), and a file's
45
+ link targets that find no file.
46
+
47
+ ### `session.index.on`
48
+
49
+ ```ts
50
+ const off = session.index.on(event => {
51
+ if (event.type === 'rename') console.log(event.oldPath, '→', event.newPath)
52
+ })
53
+ ```
54
+
55
+ Files created (`create`), removed (`remove`, with every entry removed), renamed (`rename`), modified (`modify`), by
56
+ absolute path. Returns what stops listening; it stops with the session anyway.
57
+
58
+ ### `session.index.search`
59
+
60
+ ```ts
61
+ const {hits, more} = await session.index.search('todo', {folder: 'projects', context: 1, limit: 50})
62
+ ```
63
+
64
+ Notes (Markdown and text files) whose path or text matches, in path order, read from disk: each hit a workspace-relative
65
+ `path`, and for a line, its `line` and `snippet`. Plain text and case-insensitive unless `regex` or `caseSensitive`;
66
+ dot folders are skipped.
67
+
68
+ ## Commands
69
+
70
+ ### `session.commands.list`, `session.commands.paletteGroups`
71
+
72
+ Every registered command (with its plugin), and the palette's groups: what a command palette of one's own lists.
73
+
74
+ ## Files
75
+
76
+ What Files does, for a plugin: notes written through the index, files created, moved, copied and deleted with Files'
77
+ undo, dialogs and toasts. What a file browser needs is all here (menus, New, drags, drops, the clipboard).
78
+
79
+ ### `session.files.assetUrl`
80
+
81
+ A URL the webview can load an absolute path from (images, media).
82
+
83
+ ### `session.files.write`
84
+
85
+ Writes a file's text, by uuid, and updates the index: a plugin's save.
86
+
87
+ ### `session.files.create`
88
+
89
+ Creates an empty file `name` in a workspace-relative folder (made when missing) and indexes it; throws when the path
90
+ exists.
91
+
92
+ ### `session.files.edit`
93
+
94
+ New text for notes (`[{uuid, text}]`) as one step of Files' undo history named `label`; open tabs of them reload.
95
+
96
+ ### `session.files.move`, `session.files.relocate`, `session.files.duplicate`
97
+
98
+ `move(uuids, folder)` moves files into a folder, with Files' prompts when a name is taken, and undo. `relocate(items)`
99
+ moves and renames items to workspace-relative paths (`{uuid, to}`), and `duplicate(items)` copies them: one undo step
100
+ each, links to moved files updated as the user's setting says, nothing replaced (what can't go comes back in
101
+ `skipped` with why).
102
+
103
+ ### `session.files.undo`, `session.files.redo`
104
+
105
+ Files' undo history: the last file operation undone, or redone.
106
+
107
+ ### `session.files.remove`
108
+
109
+ Deletes files by uuid into the trash, with Undo; asks first when the user's deletes are for good.
110
+
111
+ ### `session.files.copy`, `session.files.paste`
112
+
113
+ `copy(uuids)` puts files on the system clipboard as files (Finder and Explorer paste them). `paste(folder)` copies the
114
+ clipboard's files into a folder; their new uuids.
115
+
116
+ ### `session.files.importAttachments`, `session.files.importDrop`, `session.files.outside`
117
+
118
+ Files from outside. `importAttachments(files)`: `File`s as workspace uuids, the workspace's own as they are, the rest
119
+ copied into the attachments folder. `importDrop(transfer, folder)`: a drop's OS files copied into a folder (moved when
120
+ they're the workspace's own; `{copy: true}` copies anyway); call it inside the `drop` event. `outside(source)` (a
121
+ drop, `'clipboard'`, or `File`s) describes them first (`own`, `items`, `folder`) and copies only what `import(chosen)`
122
+ is given, to ask the user before.
123
+
124
+ ### `session.files.pick`
125
+
126
+ Vertex's picker of the workspace's files or folders: workspace-relative paths, `undefined` when it's closed.
127
+
128
+ ```ts
129
+ const paths = await session.files.pick({title: 'Choose notes', kind: 'file', multiple: true, extensions: 'md'})
130
+ ```
131
+
132
+ ### `session.files.vault`
133
+
134
+ The workspace as a `Vault` (`@type32/vertex-plugin/vault`), over workspace-relative paths: `entries`, `entry`,
135
+ `linksTo`, `linksFrom`, `read`, `write`, `create`, `createFolder`, `move`; what it writes goes through the index as
136
+ Vertex's own edits do. The same module writes frontmatter as Obsidian does (`setFrontmatterProperty`). Throws in a
137
+ single-file window.
138
+
139
+ ### `session.files.iconFor`
140
+
141
+ The icon of a file name: its [file type's](context.md#ctxfilestype), or `undefined` for one Vertex draws itself.
142
+
143
+ ### `session.files.openFolders`
144
+
145
+ The folders a file browser shows open (uuids), a `Ref` saved and restored with the session.
146
+
147
+ ### `session.files.menuFor`, `session.files.newItems`
148
+
149
+ `menuFor(uuids, {added})` is Files' right-click menu for rows (one, a selection, or `[]` for the empty space), as
150
+ groups of `PluginMenuItem`s for a `UContextMenu`; plugins' items come first, and `added` gets the uuids Paste and
151
+ Duplicate made. `newItems(folder)` is New note, New folder and each file type's New, each asking for a name.
152
+
153
+ ### `session.files.drag.start`, `session.files.drag.rows`, `session.files.drag.carries`
154
+
155
+ `start(event, uuids, grab, ended)` inside a `dragstart` makes it Files' drag: its drag image, what the editor and chat
156
+ accept, and in Vertex a drag Finder and Explorer copy from; `ended` runs when it's over. `rows(transfer)` is the
157
+ workspace-relative paths of rows dragged from Files (a folder's ends with `/`), `undefined` for another drag;
158
+ `carries(transfer)` whether a drag carries files at all.
159
+
160
+ ### `session.files.openWithDefaultApp`, `session.files.reveal`
161
+
162
+ Opens a file in the app the system gives its kind; shows files in Finder or Explorer.
163
+
164
+ ## Properties
165
+
166
+ ### `session.properties.types`, `session.properties.setType`
167
+
168
+ The vault's property types (Obsidian's `types.json`: key → `text`, `multitext`, `number`, `checkbox`, `date`,
169
+ `datetime`…), reactive; `setType(key, type)` sets one, `null` back to Automatic.
170
+
171
+ ## Tabs
172
+
173
+ ### `session.tabs.open`, `session.tabs.close`, `session.tabs.active`, `session.tabs.list`
174
+
175
+ `open(uuid)` opens a file in a tab and shows it; `open(id, kind)` a tab of a [kind](context.md#ctxviewstabkind).
176
+ `active()` is the shown tab's id; `list()` every tab's `{kind, id}` (no `kind` for a file's).
177
+
178
+ ## Editors
179
+
180
+ ### `session.editor.viewOf`
181
+
182
+ The CodeMirror `EditorView` of a note's tab while it's shown (by the tab's id, the file's uuid), to read the cursor or
183
+ dispatch a change.
184
+
185
+ ### `session.editor.content`
186
+
187
+ A text tab's buffer as it is now, saved or not.
188
+
189
+ ### `session.editor.lastShownNote`
190
+
191
+ The note tab shown last: where an action from elsewhere (a chat) should go.
192
+
193
+ ### `session.editor.embedFor`
194
+
195
+ The embed registered for an extension: draw another plugin's `![[file]]` with `PluginMount` ([UI](ui.md)).
196
+
197
+ ## Outside the index
198
+
199
+ ### `session.watch`
200
+
201
+ ```ts
202
+ session.watch('.hello', paths => console.log(paths))
203
+ ```
204
+
205
+ Changes under a workspace-relative folder the index ignores (a dot folder), as absolute paths, a batch at a time.
package/docs/start.md ADDED
@@ -0,0 +1,173 @@
1
+ # Start
2
+
3
+ From an empty folder to a panel view running in Vertex. You need [Bun](https://bun.sh) (or Node with npm) and Vertex.
4
+
5
+ The quick way is the template, which holds the files below: **Use this template** on
6
+ [`Type-32/vertex-plugin-template`](https://github.com/Type-32/vertex-plugin-template) and skip to [Build](#build). By
7
+ hand:
8
+
9
+ ## The files
10
+
11
+ The plugin's id is `hello` here. An id is lowercase letters, digits and inner hyphens; it names the plugin's strings,
12
+ settings, data and secrets, so it doesn't change once people use the plugin.
13
+
14
+ `plugin.json`, what Vertex knows without running the plugin ([every key](package.md#pluginjson)):
15
+
16
+ ```json
17
+ {
18
+ "id": "hello",
19
+ "name": "Hello",
20
+ "version": "0.1.0",
21
+ "description": "Says hello.",
22
+ "icon": "i-lucide-hand",
23
+ "apiVersion": 1
24
+ }
25
+ ```
26
+
27
+ `package.json`:
28
+
29
+ ```json
30
+ {
31
+ "name": "hello",
32
+ "private": true,
33
+ "type": "module",
34
+ "scripts": {
35
+ "build": "vite build",
36
+ "typecheck": "vue-tsc -p ."
37
+ },
38
+ "devDependencies": {
39
+ "@type32/vertex-plugin": "^1.1.0",
40
+ "@vitejs/plugin-vue": "^6.0.0",
41
+ "typescript": "^6.0.3",
42
+ "vite": "^8.3.8",
43
+ "vue-tsc": "^3.3.14"
44
+ }
45
+ }
46
+ ```
47
+
48
+ `vite.config.ts`: `vertex()` builds `src/main.ts`, `plugin.json`, `locales/` and `public/` into `dist/`
49
+ ([what it does](package.md#the-build)):
50
+
51
+ ```ts
52
+ import vue from '@vitejs/plugin-vue'
53
+ import {vertex} from '@type32/vertex-plugin/vite'
54
+ import {defineConfig} from 'vite'
55
+
56
+ export default defineConfig({plugins: [vue(), vertex()]})
57
+ ```
58
+
59
+ `tsconfig.json`; the SDK's types include Nuxt UI's components, so `vue-tsc` checks `<UButton>` in a template:
60
+
61
+ ```json
62
+ {
63
+ "compilerOptions": {
64
+ "target": "ES2022",
65
+ "lib": ["ES2023", "DOM", "DOM.Iterable"],
66
+ "module": "ESNext",
67
+ "moduleResolution": "Bundler",
68
+ "strict": true,
69
+ "skipLibCheck": true,
70
+ "noEmit": true,
71
+ "types": ["vite/client", "@type32/vertex-plugin"]
72
+ },
73
+ "include": ["src"]
74
+ }
75
+ ```
76
+
77
+ `locales/en.json`, the plugin's strings, all under `plugins.<id>` ([strings](package.md#strings)). Add
78
+ `locales/zh-CN.json` with the same keys for Chinese:
79
+
80
+ ```json
81
+ {
82
+ "plugins": {
83
+ "hello": {
84
+ "view": "Hello",
85
+ "greeting": "Hello, {name}"
86
+ }
87
+ }
88
+ }
89
+ ```
90
+
91
+ `src/main.ts`, the entry. `setup` runs once in each window the plugin runs in and registers what it adds
92
+ ([`ctx`](context.md)):
93
+
94
+ ```ts
95
+ import {definePlugin} from '@type32/vertex-plugin'
96
+ import {h} from 'vue'
97
+ import View from './View.vue'
98
+ import './style.css'
99
+
100
+ export default definePlugin({
101
+ setup(ctx) {
102
+ ctx.views.panel({
103
+ id: 'hello',
104
+ label: 'plugins.hello.view',
105
+ icon: 'i-lucide-hand',
106
+ defaultArea: 'right',
107
+ component: async () => ({render: () => h(View, {ctx})}),
108
+ })
109
+ },
110
+ })
111
+ ```
112
+
113
+ `src/View.vue`, the panel. Nuxt UI's components are there by name, as in Vertex's own templates ([UI](ui.md)):
114
+
115
+ ```vue
116
+ <script setup lang="ts">
117
+ import type {PluginContext} from '@type32/vertex-plugin'
118
+
119
+ const props = defineProps<{ ctx: PluginContext }>()
120
+ const {t} = props.ctx.i18n
121
+ </script>
122
+
123
+ <template>
124
+ <div class="flex items-center gap-2 p-3 text-sm text-muted">
125
+ <span>{{ t('plugins.hello.greeting', {name: 'Vertex'}) }}</span>
126
+ <UButton size="xs" icon="i-lucide-sparkles" variant="soft"/>
127
+ </div>
128
+ </template>
129
+ ```
130
+
131
+ `src/style.css`, Tailwind's utilities against Vertex's theme ([styles](ui.md#styles)):
132
+
133
+ ```css
134
+ @import "@type32/vertex-plugin/tailwind.css";
135
+ ```
136
+
137
+ ## Build
138
+
139
+ ```sh
140
+ bun install
141
+ bun run build
142
+ bun run typecheck
143
+ ```
144
+
145
+ `dist/` now holds `plugin.json`, `main.js`, `styles.css` and `locales/`: the plugin as Vertex installs it. The build
146
+ fails with what's wrong when `plugin.json` or a locale file breaks a rule.
147
+
148
+ > If the build finds none of your Tailwind classes (`styles.css` nearly empty), a `.gitignore` in a folder above the
149
+ > project probably ignores it: Tailwind skips ignored files until the project is a Git repository of its own. Run
150
+ > `git init` in it.
151
+
152
+ ## Run it in Vertex
153
+
154
+ Settings → Plugins → the arrow beside **Install…** → **From a folder (development)…**, and pick `dist/`. The dialog
155
+ shows what the plugin is and asks; **Install** turns it on. In a workspace window, open the right sidebar (the button
156
+ at the window's top right): its header has the view's icon, the hand, and a click on it shows "Hello, Vertex".
157
+
158
+ Pick `dist/`, not the project: the folder you pick is copied as it is and watched.
159
+
160
+ ## The development loop
161
+
162
+ A plugin installed from a folder stays watched while that folder is its source: when its files change, Vertex copies
163
+ them again, and each window running the plugin saves its session and reloads. So keep a build running:
164
+
165
+ ```sh
166
+ bunx vite build --watch
167
+ ```
168
+
169
+ and each save of a source file shows in Vertex a moment later. An error in `setup` or in what the plugin draws shows
170
+ in Vertex as "Hello couldn't start" or in place of the view; the window's web inspector has the stack and the
171
+ console (on macOS, Safari → Develop → your Mac's name → the Vertex window).
172
+
173
+ To ship it, see [Publishing](publishing.md).
package/docs/trust.md ADDED
@@ -0,0 +1,51 @@
1
+ # Trust
2
+
3
+ A plugin runs as Vertex does: it can read and change the user's notes and files, and nothing sandboxes it. Users are
4
+ told so, and decide.
5
+
6
+ ## Installing
7
+
8
+ The install dialog shows what the plugin says of itself (`name`, `version`, `author`, `description`), where it was
9
+ fetched from (and where it says it's from, when that differs), the [permissions](config.md#permissions) it asks for,
10
+ and that it runs as Vertex does. An update shows what changed in its version, permissions, requirements and
11
+ `apiVersion`. A plugin from another repository than the copy it would replace (which would get that one's settings,
12
+ data and secrets) needs its own confirmation.
13
+
14
+ So: ask only for the permissions the plugin uses, name its `repository`, and release from that repository
15
+ ([Publishing](publishing.md)).
16
+
17
+ ## A workspace's plugins
18
+
19
+ A workspace can carry plugins in its `.vertex/plugins/<id>/`, which travel with it (sync, Git). They run only in that
20
+ workspace's windows, once its folder is trusted and each plugin is accepted: trusting the folder lists them first,
21
+ with what each asks for. Acceptance pins the plugin's `plugin.json`, `main.js`, `styles.css` and strings: when any of
22
+ them changes (an update on another device, a pull), the plugin is off there until the user accepts it again. A
23
+ workspace's copy replaces an installed plugin with its id in that workspace.
24
+
25
+ A workspace also names where its plugins come from (`plugins.sources` in its settings), so another device can install
26
+ the ones it lacks.
27
+
28
+ ## Programs in a vault
29
+
30
+ ### `ctx.trust.allows`, `ctx.trust.trustFile`, `ctx.trust.trustFolder`, `ctx.trust.followEdit`, `ctx.trust.format`
31
+
32
+ For a plugin that runs programs from the vault (a workflow, a script), so every such plugin asks the same way and the
33
+ user manages them in one place, Settings → Trust. Paths are absolute; `hash` names a program's content.
34
+
35
+ ```ts
36
+ ctx.trust.format({extensions: ['macro'], hash: async text => (await sha256(text))})
37
+
38
+ if (!await ctx.trust.allows(path, hash)) {
39
+ // Ask the user, then:
40
+ await ctx.trust.trustFile(path, hash)
41
+ }
42
+ ```
43
+
44
+ - `allows(path, hash)`: whether it may run without asking: the file is trusted, or a folder covering it is (with this
45
+ program, when trust remembers content).
46
+ - `trustFile(path, hash)`; `trustFolder(path, nested, pin?)`, its subfolders too with `nested`, `false` when the user
47
+ declines (a folder whose workspace has plugins asks about them first).
48
+ - `followEdit(path, before, after)`: an edit made in Vertex keeps the file's trust with its new program.
49
+ - `format({extensions, hash})`: the files whose programs a folder's trust pins.
50
+
51
+ (`sha256` stands for the plugin's own hashing, `crypto.subtle.digest` for one.)