@muninmd/munin-sdk 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandr Eremin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,316 @@
-# Temporary Holding Version
+# @muninmd/munin-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Types and the packer for [Munin](https://munin.md) plugins — a local-first,
+Markdown note-taking app for the desktop and Android.
+
+```bash
+npm install --save-dev @muninmd/munin-sdk
+```
+
+```ts
+import type { PluginContext } from '@muninmd/munin-sdk'
+
+export default function activate(ctx: PluginContext): void {
+  ctx.commands.register({ id: 'hello', title: 'Say hello', run: () => ctx.ui.notice('Hello') })
+}
+```
+
+```bash
+npx munin-pack dist acme.hello-1.0.0.mnp
+```
+
+- `@muninmd/munin-sdk` — the whole plugin API as TypeScript types (`PluginContext`
+  and everything it hands you). Types only: at run time the app passes the
+  context in.
+- `@muninmd/munin-sdk/plugin-package` — the manifest and package rules, the same
+  code the app and the catalogue check packages with.
+- `munin-pack` (also `@muninmd/munin-sdk/pack`) — packs a plugin folder into one
+  `.mnp` file and checks it.
+
+The rest of this page is the guide to writing one.
+
+# Writing a Munin plugin
+
+A plugin is a folder with a `manifest.json` and a few text files. It is packed
+into one file, `.mnp`, and installed from the marketplace, or from the file.
+
+```
+my-plugin/
+  manifest.json
+  main.js          the entry point — an ES module
+  styles.css       optional
+  README.md        optional; shown on the plugin's card
+```
+
+## The manifest
+
+```json
+{
+  "id": "acme.word-count",
+  "name": "Word Count",
+  "version": "1.0.0",
+  "description": "Counts words in a note.",
+  "author": "acme",
+  "entry": "main.js",
+  "apiVersion": 1,
+  "minAppVersion": "0.4.1",
+  "platforms": ["desktop", "android"],
+  "permissions": ["vault:read"],
+  "tags": ["editor"]
+}
+```
+
+- `id` is `<author>.<name>`: lower case, digits, dashes. The part before the dot is
+  your **author handle**, which you register once (below), and it is the namespace
+  you own.
+- `permissions` are `vault:read`, `vault:write`, `network`. They are shown to the
+  person before they switch the plugin on. **They disclose what you intend; they
+  are not a sandbox** — see "Trust".
+- `platforms`: `desktop`, `android`, or both. One package runs on both.
+- `dependencies` (optional): other plugins yours needs, with the oldest version of
+  each that will do — `{ "munin.daily-notes": "1.1.0" }`. They start before yours
+  and stop after it. When one is missing, off or too old, your plugin waits
+  (shown as such, with a button to fix it) instead of starting without it, and
+  the catalogue offers to install it along with yours.
+
+## The code
+
+```js
+export default function activate(ctx) {
+  ctx.commands.register({
+    id: 'hello',
+    title: 'Say hello',
+    run: () => ctx.ui.notice('Hello')
+  })
+}
+
+export function deactivate() {} // optional
+```
+
+Everything you register through `ctx` is stamped with your plugin id and taken
+back when the plugin is switched off. See `plugin-api.d.ts` in this package for the
+whole surface, and `plugins/examples/todo-highlight` in the Munin repository for a
+plugin that uses all of it. For the editor, build extensions from `ctx.editor.libs` — the app's own copy
+of CodeMirror — and never from your own `@codemirror/*` import: two copies in one
+window do not recognise each other's objects.
+
+### Panels
+
+`ctx.views.register({ id, title, icon, mount })` adds a panel; `mount(el,
+instance)` fills `el` and may return a cleanup. `instance.state()` /
+`instance.setState(value)` keep a JSON value for _that_ panel — two open panels
+of your view keep two, and on a computer the value comes back with the layout.
+On a phone a view needs `mobile: 'sheet'` (a sheet from a button in the library)
+or `mobile: 'page'` (the whole screen, from the dock's menu) to be reachable at
+all. `ctx.views.open(id)` shows one of your views, on either platform.
+
+A view with `expandable: true` gets a control in its header that expands the panel
+over the whole workspace on a computer; Escape, or the same control, puts the layout
+back, and so does opening a note. It is never saved. `instance.expanded()` says
+whether it is expanded, `instance.setExpanded(on)` does it from code, and
+`instance.onExpandedChange(cb)` is called once the panel has its new size — to
+change what is drawn; a `ResizeObserver` already reports the size itself.
+
+### What notes mean
+
+`ctx.metadata` reads the app's own index (needs `vault:read`): `note(path)` —
+title, links, tags, aliases, headings, frontmatter properties — and
+`backlinks`, `resolve`, `graph`, `vaultGraph`, `tags`, `notesWithTag`. Listen to
+`metadata-updated` to know when to ask again. `plugins/bundled/graph` in the Munin repository is a whole
+panel built on it.
+
+### The open note
+
+`ctx.editor.active()` is the note in the active pane, as its editor has it —
+unsaved typing included — or null. `text()` and `selection()` read it
+(`vault:read`); `insert(text)` at the caret, `replace(from, to, text)` and
+`select(anchor, head)` change it through the editor, so the person can undo the
+change and it is saved like typing (`vault:write`). Positions are offsets into
+the text. In reading mode edits are refused.
+
+### Input
+
+- `ctx.keys.bind(commandId, 'Mod+Shift+D')` gives one of your commands a
+  shortcut (`Mod` is ⌘ on macOS, Ctrl elsewhere). A combination someone already
+  holds stays theirs, and your log says so.
+- `await ctx.ui.pick({ items, placeholder })` shows a list with a search field
+  on either platform. Items are `{ label, detail? }` plus anything of yours; you
+  get back the item chosen, or null.
+
+### Files
+
+- Events `file-created`, `file-modified`, `file-renamed` (with `oldPath`) and
+  `file-deleted`, each with `path`, `folder` and `origin` (`app` or `external`).
+- `vault.rename(path, newName)`, `vault.move(path, folder)`, `vault.delete(path)`
+  do what the person's own actions do — links are rewritten, tabs follow — and
+  throw when they cannot. `delete` asks nothing.
+- `vault.readBinary(path)` → `{ data: Uint8Array, mime }`;
+  `vault.saveAttachment(name, data)` puts a file in the attachments folder and
+  returns its path.
+
+### Menus and the status bar
+
+- `ctx.menus.file.add({ id, title, when?, run })` — the file tree and a tab's
+  right-click menu on a computer, the long-press actions on a phone; `when` and
+  `run` get `{ path, isFolder }`.
+- `ctx.menus.editor.add(…)` — a right click in the text (computer only); they get
+  `{ path, from, to, text }`.
+- `ctx.statusBar.add({ id, text, title?, onClick? })` → `{ set(patch), remove() }`.
+  Computer only; on a phone it is accepted and shows nothing.
+
+`when` runs while the menu is drawn: keep it quick, and synchronous.
+
+### The network
+
+Both need `network`, and both go out through the app rather than the window —
+on a phone through the system — so a server's CORS rules do not apply, and
+`http:` reaches machines on the local network (a model in Ollama or LM Studio)
+on a computer and a phone alike.
+
+- `await ctx.net.fetch(url, init?)` reads the answer whole (up to 10 MB):
+  `text()`, `json()`, `bytes()`.
+- `await ctx.net.stream(url, init?)` resolves as soon as the status and headers
+  are in, and hands the body over as it arrives — what a language model's answer
+  is read with. Read it once, by one of `chunks()` (bytes), `lines()` (UTF-8
+  lines, joined across parts — for server-sent events and NDJSON) or `text()`.
+  Leaving a `for await` early closes the connection.
+
+`init` is `{ method, headers, body, signal, timeoutMs }`. `signal` (an
+`AbortController`'s) stops the request; waiting then fails with an error named
+`AbortError`. `timeoutMs` is how long nothing may arrive — not how long the
+whole answer may take: 30 s by default for `fetch`, 120 s for `stream`, and an
+answer that keeps coming is never cut off; a quiet one fails as `TimeoutError`.
+Requests still running when the plugin is switched off are stopped.
+
+```js
+const res = await ctx.net.stream(`${base}/chat/completions`, {
+  method: 'POST',
+  headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+  body: JSON.stringify({ model, stream: true, messages }),
+  signal: controller.signal
+})
+if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`)
+for await (const line of res.lines()) {
+  if (!line.startsWith('data: ') || line === 'data: [DONE]') continue
+  write(JSON.parse(line.slice(6)).choices[0].delta.content ?? '')
+}
+```
+
+`plugins/examples/stream-chat` in the Munin repository is a whole plugin built this way.
+
+### Secrets
+
+`ctx.secrets.get(name)`, `set(name, value)`, `delete(name)` keep an access key or
+token apart from everything else — never in the settings file, the plugin's data
+or the vault. On a computer it is a file only the user can read (no keychain
+prompt); on Android it is encrypted by the keystore, and where that is missing
+`set` fails rather than keep the value in the clear. Plugins run with full
+trust, so this keeps secrets off the disk's shared places, not from other
+plugins.
+
+A settings field `{ kind: 'secret', id: 'apiKey', label: 'API key' }` is the
+person's way in: it shows whether the key is set, takes a new one and clears it,
+and keeps it as the secret named by its `id`. `settings.get` answers `''` for it
+and `onChange` is told `true` or `false`, never the value.
+
+### Storage by key
+
+`ctx.data` is one value, rewritten whole on every save. For many records that
+change one at a time — sessions, a cache — use `ctx.store.get(key)`,
+`set(key, value)`, `delete(key)` and `keys(prefix?)`: one file per key, beside
+the data and removed with it. A key is 1–128 of `A–Z a–z 0–9 . _ -`; a value is
+at most 5 MB written out; a save is whole — after a crash the key holds the old
+value or the new one.
+
+### Search
+
+`await ctx.search.query('postgres index', { limit: 10 })` → `[{ path, title,
+snippet }]`: the app's own search, with its operators and in its order
+(`vault:read`). `limit` defaults to 20, at most 200.
+
+### Settings you draw
+
+A section with `mount(el)` instead of `fields` is drawn by the plugin — for what
+is not a list of values, like a list of connections. As with a panel, return a
+cleanup. Draw with the app's colours so it sits well in both themes:
+`var(--text)`, `var(--text2)`, `var(--text3)`, `var(--island)`,
+`var(--island2)`, `var(--border-soft)`, `var(--accent)`, `var(--danger)`.
+
+`ctx.settings.open(sectionId?)` shows one of your sections — the first one
+without an id: the settings window on a computer, the plugin's settings page on a
+phone, where back returns to wherever you opened it from.
+
+### Building on another plugin
+
+A plugin publishes an API with `ctx.provide((client) => api)`; one that lists it
+in `dependencies` gets it with `ctx.plugins.get(id)`. The factory runs once per
+dependent, with `client.id`, `client.log(...)` (into the dependent's log) and
+`client.register(disposer)` — what a dependent adds through your API is undone
+when _it_ goes, so you never track its life yourself:
+
+```js
+// provider
+ctx.provide((client) => ({
+  addSource(source) {
+    sources.add(source)
+    const remove = () => sources.delete(source)
+    client.register(remove)
+    return remove
+  }
+}))
+
+// dependent — manifest: "dependencies": { "acme.provider": "1.0.0" }
+ctx.plugins.get('acme.provider')?.addSource({ … })
+```
+
+Daily notes publishes one: `addDayMarks({ id, label, marks(from, to) })` puts
+marks on calendar days — `marks` answers `[{ date: 'YYYY-MM-DD', items: [{
+title, time?, color? }] }]` for the month on screen, within three seconds — and
+`refresh()` asks the calendar to fetch them again. `color` is one of `accent`,
+`danger`, `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `gray`, or `#rgb`
+/ `#rrggbb`.
+
+## Pack it
+
+```bash
+npx munin-pack my-plugin                  # → acme.word-count-1.0.0.mnp
+npx munin-pack dist my-plugin.mnp         # a built folder, a name of your own
+```
+
+Bundle your code into the one `main.js` the manifest names (esbuild, Rollup…): a
+package holds text files, and nothing is resolved from `node_modules` at run time.
+The package is checked by the same rules the app and the registry use, so what
+packs here installs there.
+
+Try it before publishing: in the app, **Settings → Plugins → Install from a file**.
+It is treated as unverified — you will get the same warnings a user would.
+
+## Publish it
+
+```bash
+B=https://app.munin.md
+
+# once. The token is shown only here; keep it.
+curl -X POST -H 'Content-Type: application/json' -d '{"handle":"acme"}' $B/v1/authors
+
+# each version. A published version is never overwritten: fix it with a new one.
+curl -X PUT -H "Authorization: Bearer $TOKEN" --data-binary @acme.word-count-1.0.0.mnp \
+  $B/v1/plugins/acme.word-count/versions/1.0.0
+```
+
+The answer says `"state": "listed"` (it is in the catalogue now) or `"pending"`
+(the catalogue reviews new versions first, and yours is waiting). Either way it is
+**not verified** until the operator verifies it — people see "Not verified" and a
+warning when they install it.
+
+Handles containing `munin` (or look-alikes), and a few words like
+`admin`, are reserved.
+
+## Trust
+
+A plugin runs **inside the app, with no isolation**. It can read and change all
+your notes and reach whatever the app reaches. The permissions you declare are shown
+to the person and the context refuses calls you did not declare — but that is a
+guard against mistakes, not a wall, because nothing stops a plugin from going around
+the context. Treat the person's trust as what it is. Plugins that misbehave can be
+revoked, and the app switches revoked plugins off at its next start.

package/pack-plugin.d.mts

@@ -0,0 +1,4 @@
+import type { PluginManifest } from './plugin-package.js'
+
+/** Read a plugin folder and return the package text, or throw naming what is wrong. */
+export function packFolder(folder: string): Promise<{ text: string; manifest: PluginManifest }>

package/pack-plugin.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Pack a plugin folder into a .mnp file.
+//
+//   node plugins/sdk/pack-plugin.mjs <folder> [out.mnp]
+//
+// The folder holds manifest.json and the plugin's text files (main.js, styles.css,
+// README.md…). Every file other than the manifest goes into the package. The
+// result is checked by the same code the app and the registry use, so a package
+// that packs here installs there.
+//
+// The rules come from plugin-package.js, compiled from the app's own
+// src/shared/plugin-package.ts (`npm run plugins:sdk`).
+
+import { realpathSync } from 'node:fs'
+import { readdir, readFile, writeFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { join, relative, sep } from 'node:path'
+import { parsePackage } from './plugin-package.js'
+
+async function walk(dir, root, out = []) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules') continue
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) await walk(full, root, out)
+    else out.push(relative(root, full).split(sep).join('/'))
+  }
+  return out
+}
+
+/** Read a folder and return the package text, or throw naming what is wrong. */
+export async function packFolder(folder) {
+  let manifest
+  try {
+    manifest = JSON.parse(await readFile(join(folder, 'manifest.json'), 'utf8'))
+  } catch (err) {
+    throw new Error(`${folder}/manifest.json: ${err.message}`)
+  }
+  const files = {}
+  for (const path of await walk(folder, folder)) {
+    if (path === 'manifest.json') continue
+    files[path] = await readFile(join(folder, path), 'utf8')
+  }
+  const text = JSON.stringify({ manifest, files })
+  const parsed = parsePackage(text)
+  if (!parsed.ok) throw new Error(parsed.error.message)
+  return { text, manifest: parsed.pkg.manifest }
+}
+
+// Run as a command — directly, or through the `munin-pack` link npm makes, whose
+// path is not this file's until the link is followed.
+const invoked = process.argv[1] ? realpathSync(process.argv[1]) : null
+if (invoked === fileURLToPath(import.meta.url)) {
+  const [folder, out] = process.argv.slice(2)
+  if (!folder) {
+    console.error('usage: munin-pack <folder> [out.mnp]')
+    process.exit(2)
+  }
+  try {
+    const { text, manifest } = await packFolder(folder)
+    const target = out ?? `${manifest.id}-${manifest.version}.mnp`
+    await writeFile(target, text, 'utf8')
+    console.log(`${target}  (${Buffer.byteLength(text)} bytes)`)
+  } catch (err) {
+    console.error(`not packed: ${err.message}`)
+    process.exit(1)
+  }
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@muninmd/munin-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "TypeScript types and the packer for Munin plugins.",
+  "keywords": [
+    "munin",
+    "plugin",
+    "sdk",
+    "notes",
+    "markdown",
+    "typescript"
+  ],
+  "homepage": "https://munin.md",
+  "license": "MIT",
+  "author": "Aleksandr Eremin",
+  "type": "module",
+  "types": "./plugin-api.d.ts",
+  "exports": {
+    ".": {
+      "types": "./plugin-api.d.ts"
+    },
+    "./plugin-api": {
+      "types": "./plugin-api.d.ts"
+    },
+    "./plugin-package": {
+      "types": "./plugin-package.d.ts",
+      "default": "./plugin-package.js"
+    },
+    "./pack": {
+      "types": "./pack-plugin.d.mts",
+      "default": "./pack-plugin.mjs"
+    }
+  },
+  "bin": {
+    "munin-pack": "./pack-plugin.mjs"
+  },
+  "files": [
+    "plugin-api.d.ts",
+    "plugin-package.d.ts",
+    "plugin-package.js",
+    "pack-plugin.mjs",
+    "pack-plugin.d.mts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@codemirror/state": "^6.4.1",
+    "@codemirror/view": "^6.34.0"
+  },
+  "peerDependenciesMeta": {
+    "@codemirror/state": {
+      "optional": true
+    },
+    "@codemirror/view": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}