@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.
- package/dist/theme-app.css +2 -5
- package/dist/types/shared/plugin/components.d.ts +2 -0
- package/dist/types/shared/plugin/contributions.d.ts +3 -2
- package/dist/vite.js +3 -2
- package/docs/README.md +24 -0
- package/docs/config.md +132 -0
- package/docs/context.md +417 -0
- package/docs/package.md +116 -0
- package/docs/publishing.md +71 -0
- package/docs/session.md +205 -0
- package/docs/start.md +173 -0
- package/docs/trust.md +51 -0
- package/docs/ui.md +145 -0
- package/docs/versions.md +33 -0
- package/package.json +3 -2
package/docs/package.md
ADDED
|
@@ -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.
|
package/docs/session.md
ADDED
|
@@ -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.)
|