andesine 0.4.0 → 0.5.0

package/dist/templates/extension/.env.example

@@ -0,0 +1,5 @@
+# The private key from `andesine extensions keys generate` (a JSON Web Key on one line)
+ANDESINE_EXTENSION_KEY=
+# API URLs of the Andesine instances that the backend works with, separated by commas
+ANDESINE_INSTANCES=https://api.andesine.app
+PORT=3000

package/dist/templates/extension/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vrite, Inc.
+
+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/dist/templates/extension/README.md

@@ -0,0 +1,33 @@
+# Andesine extension
+
+An Andesine extension with a Solid frontend and a Node backend.
+
+- `andesine.config.ts` — the manifest: name, permissions, backend, webhooks, configuration, and views.
+- `andesine.keys.json` — the backend's public keys; `andesine extensions keys` maintains it.
+- `src/frontend` — the views, rendered by Andesine in a sandbox; `index.tsx` exports every view that the manifest names.
+- `src/backend` — the backend; it receives webhooks and verifies frontend sessions.
+
+## Samples
+
+Each frontend module shows one kind of contribution; remove the ones you do not need from the manifest and `index.tsx`.
+
+- `note-view.tsx` — element views: `<Note>` with its editable content in `ContentSlot`, a tone switch that edits the element's props, and a `<NoteTitle>` descendant view.
+- `shout-action.tsx` — a block action for paragraphs and headings that replaces the selection or inserts a paragraph after it.
+- `bookmarks-panel.tsx` — a left panel with a list kept in the extension storage, and a link to a declared URL.
+- `hello-panel.tsx` — a right panel for the open entry: configuration, an API call with the member's granted permissions, and a call to the backend.
+- `about-section.tsx` — a settings section with the granted permissions and host actions (copy, download, open a URL).
+- `src/backend/server.ts` — lifecycle and `entry.created` webhooks, session verification, and the secret `apiToken` field and storage, read with the extension's credentials.
+
+## Commands
+
+- `npm run build` — validate the manifest and build the frontend, its CSS, and the artifact metadata into `dist/`.
+- `npm run backend` — start the backend with the variables from `.env` (see `.env.example`).
+- `npm run dev` — run the extension on a local Andesine instance for you, reloading it on each change; Ctrl+C stops it and keeps its state. It needs `andesine auth login` against the local instance, points the extension at the local backend (`--backend`, port 3000 as in `.env.example`), and writes a development key to `.env`.
+- `npx andesine extensions test-event <webhook> <type>` — send a sample event to a webhook of the running development extension.
+- `npx andesine extensions keys generate` — create a key pair; the private key never leaves your machine.
+- `npx andesine extensions keys check` — compare the backend's private key with the manifest keys.
+- `npx andesine extensions keys revoke <kid>` — stop listing a key; publish a new version afterwards.
+
+Private keys stay in `.andesine/keys` and `.env`, which Git ignores.
+
+Publish a version through a pull request to the extension registry.

package/dist/templates/extension/andesine.config.ts

@@ -0,0 +1,79 @@
+import { defineBuild, defineExtension } from "@andesine/extensions";
+import * as z from "zod";
+// `andesine extensions keys generate` and `keys revoke` maintain this file.
+import backendKeys from "./andesine.keys.json" with { type: "json" };
+
+export default defineExtension({
+  // Your registry name, e.g. `acme/publish`.
+  name: "example/hello",
+  version: "0.1.0",
+  displayName: "Hello",
+  description:
+    "Samples of every extension feature: views, panels, actions, settings, and a backend.",
+  icon: "i-lucide:hand",
+  apiVersion: 1,
+  // The API permissions that members approve; the frontend gets them only where members have them.
+  permissions: ["read:entries"],
+  // Other URLs that the frontend can request, link to, and open without confirmation.
+  requests: ["https://andesine.app/"],
+  backend: {
+    // Where the backend in src/backend is deployed; it must use HTTPS. `npm run dev` uses the
+    // local backend instead (`--backend` in package.json).
+    url: "https://hello.example.com",
+    keys: backendKeys.keys
+  },
+  webhooks: {
+    lifecycle: { events: ["extension.installed", "extension.uninstalled"], path: "/webhooks" },
+    entries: { events: ["entry.created"], path: "/webhooks" }
+  },
+  // Managers fill it in Settings → Extensions; secret fields reach only the backend.
+  configuration: z.object({
+    greeting: z.string().min(1).max(100).default("Hello").meta({ title: "Greeting" }),
+    apiToken: z
+      .string()
+      .max(200)
+      .optional()
+      .meta({ title: "API token", description: "Only the backend reads it", secret: true })
+  }),
+  // Renders `<Note>` elements; `<NoteTitle>` inside a note uses its own view.
+  elementViews: [
+    {
+      id: "note",
+      name: "Note",
+      element: "Note",
+      entry: "NoteView",
+      descendants: [{ element: "NoteTitle", entry: "NoteTitleView" }]
+    }
+  ],
+  // Shown in the block menu of the listed block types.
+  blockActions: [
+    {
+      id: "shout",
+      label: "Shout",
+      icon: "i-lucide:megaphone",
+      blocks: ["paragraph", "heading"],
+      entry: "ShoutAction"
+    }
+  ],
+  panels: [
+    {
+      id: "bookmarks",
+      side: "left",
+      name: "Bookmarks",
+      icon: "i-lucide:bookmark",
+      entry: "BookmarksPanel"
+    },
+    {
+      id: "hello",
+      side: "right",
+      name: "Hello",
+      icon: "i-lucide:hand",
+      context: "entry",
+      entry: "HelloPanel"
+    }
+  ],
+  // Shown in the extension's settings, below the configuration form.
+  settingsSections: [{ id: "about", heading: "About", entry: "AboutSection" }]
+});
+
+export const build = defineBuild({ frontend: "src/frontend/index.tsx" });

package/dist/templates/extension/andesine.keys.json

@@ -0,0 +1,4 @@
+{
+  "keys": [],
+  "revokedKeys": []
+}

package/dist/templates/extension/gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.andesine
+.env

package/dist/templates/extension/package.template.json

@@ -0,0 +1,27 @@
+{
+  "name": "andesine-extension",
+  "version": "0.5.0",
+  "type": "module",
+  "license": "MIT",
+  "scripts": {
+    "build": "andesine extensions build",
+    "dev": "andesine extensions dev --backend http://localhost:3000",
+    "backend": "node --env-file-if-exists=.env --import tsx src/backend/server.ts",
+    "check": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "@andesine/extensions": "0.5.0",
+    "@andesine/sdk": "0.5.0",
+    "solid-js": "^1.9.14",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.2",
+    "andesine": "0.5.0",
+    "tsx": "^4.23.5",
+    "typescript": "6.0.3"
+  }
+}

package/dist/templates/extension/src/backend/server.ts

@@ -0,0 +1,85 @@
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import {
+  createExtensionBackend,
+  ExtensionNotificationError,
+  ExtensionSessionError
+} from "@andesine/sdk/extensions";
+
+const extension = createExtensionBackend({
+  name: "example/hello",
+  // The private key from `andesine extensions keys generate`, as a JSON Web Key.
+  privateKey: process.env.ANDESINE_EXTENSION_KEY ?? "",
+  // API URLs of the Andesine instances that this backend works with.
+  trustedInstances: (process.env.ANDESINE_INSTANCES ?? "https://api.andesine.app").split(",")
+});
+
+const readBody = async (request: IncomingMessage): Promise<string> => {
+  const chunks: Buffer[] = [];
+
+  for await (const chunk of request) chunks.push(chunk as Buffer);
+
+  return Buffer.concat(chunks).toString("utf8");
+};
+const send = (response: ServerResponse, status: number, body?: unknown): void => {
+  response.writeHead(status, body === undefined ? {} : { "content-type": "application/json" });
+  response.end(body === undefined ? undefined : JSON.stringify(body));
+};
+// The extension frontend calls the backend from the browser, so it needs CORS.
+const allowFrontend = (response: ServerResponse): void => {
+  response.setHeader("access-control-allow-origin", "*");
+  response.setHeader("access-control-allow-methods", "POST, OPTIONS");
+  response.setHeader(
+    "access-control-allow-headers",
+    "authorization, content-type, andesine-extension, andesine-instance"
+  );
+};
+const server = createServer(async (request, response) => {
+  allowFrontend(response);
+
+  try {
+    if (request.method === "OPTIONS") {
+      send(response, 204);
+    } else if (request.method === "POST" && request.url === "/webhooks") {
+      // Fetching the delivery with the extension's key confirms the notification.
+      const { event, client } = await extension.receive(await readBody(request));
+
+      if (event.type === "entry.created") {
+        // The client acts for the installation, with the extension's permissions.
+        const entry = await client.entries.get({ id: event.subject.id });
+
+        console.log(`Entry created: ${entry.name}`);
+      } else {
+        console.log(`Received ${event.type}`);
+      }
+
+      send(response, 204);
+    } else if (request.method === "POST" && request.url === "/hello") {
+      const session = await extension.verifySession(request.headers);
+      // Secret fields are readable only here, with the extension's own credentials.
+      const { values } = await session.client.extensions.getSelfConfiguration();
+      // The frontend's storage entries, e.g. the bookmarks panel.
+      const bookmarks = await session.client.extensions
+        .getSelfStorageEntry({ key: "bookmarks" })
+        .catch(() => null);
+
+      console.log(`API token ${values.apiToken ? "set" : "not set"}`);
+      console.log(`Bookmarks: ${JSON.stringify(bookmarks?.value ?? [])}`);
+      send(response, 200, {
+        name: session.member.profile.name ?? session.member.profile.email ?? "member"
+      });
+    } else {
+      send(response, 404);
+    }
+  } catch (error) {
+    const isRejected =
+      error instanceof ExtensionSessionError || error instanceof ExtensionNotificationError;
+
+    if (!isRejected) console.error(error);
+
+    send(response, isRejected ? 401 : 500);
+  }
+});
+
+server.listen(Number(process.env.PORT ?? 3000), () => {
+  console.log(`Backend listening on port ${process.env.PORT ?? 3000}`);
+});

package/dist/templates/extension/src/frontend/about-section.tsx

@@ -0,0 +1,47 @@
+import {
+  Badge,
+  Button,
+  copyText,
+  downloadFile,
+  openURL,
+  Setting,
+  Stack,
+  storage,
+  usePermissions
+} from "@andesine/extensions/solid";
+import { For } from "solid-js";
+
+/** A settings section: the granted permissions and the host actions. */
+export const AboutSection = () => {
+  const permissions = usePermissions();
+  const exportStorage = async () => {
+    const { data } = await storage.list();
+
+    await downloadFile("hello-storage.json", JSON.stringify(data, null, 2), "application/json");
+  };
+
+  return (
+    <Stack gap="small">
+      <Setting label="Permissions" description="What the extension can do for you">
+        <Stack direction="row" gap="small" wrap>
+          <For each={permissions()}>{(permission) => <Badge>{permission}</Badge>}</For>
+        </Stack>
+      </Setting>
+      <Setting label="Storage" description="Download the extension's stored data">
+        <Button variant="outlined" size="small" onClick={exportStorage}>
+          Download
+        </Button>
+      </Setting>
+      <Setting label="Share" description="Host actions need a click in the view">
+        <Stack direction="row" gap="small">
+          <Button variant="text" size="small" onClick={() => copyText("example/hello")}>
+            Copy name
+          </Button>
+          <Button variant="text" size="small" onClick={() => openURL("https://andesine.app/")}>
+            Open site
+          </Button>
+        </Stack>
+      </Setting>
+    </Stack>
+  );
+};

package/dist/templates/extension/src/frontend/bookmarks-panel.tsx

@@ -0,0 +1,67 @@
+import {
+  Button,
+  Icon,
+  IconButton,
+  Input,
+  Link,
+  List,
+  Stack,
+  storage,
+  Text,
+  TimeAgo
+} from "@andesine/extensions/solid";
+import { createResource, createSignal, For, Show } from "solid-js";
+
+const KEY = "bookmarks";
+
+/** The left panel: a workspace list kept in the extension storage, which its backend shares. */
+export const BookmarksPanel = () => {
+  const [title, setTitle] = createSignal("");
+  const [entry, { mutate }] = createResource(() => {
+    return storage.get<string[]>(KEY).catch(() => null);
+  });
+  const bookmarks = () => entry()?.value ?? [];
+  const save = async (next: string[]) => {
+    const { updatedAt } = await storage.set(KEY, next);
+
+    mutate({ key: KEY, value: next, updatedAt });
+  };
+  const add = () => {
+    if (!title().trim()) return;
+
+    void save([...bookmarks(), title().trim()]);
+    setTitle("");
+  };
+
+  return (
+    <Stack gap="small">
+      <Stack direction="row" gap="small" align="center">
+        <Icon name="i-lucide:bookmark" size="small" tone="muted" />
+        <Text weight="semibold">Bookmarks</Text>
+      </Stack>
+      <List
+        emptyLabel="No bookmarks yet"
+        onRemove={(index) => save(bookmarks().filter((_, item) => item !== index))}
+      >
+        <For each={bookmarks()}>{(bookmark) => <Text>{bookmark}</Text>}</For>
+      </List>
+      <Stack direction="row" gap="small">
+        <Input value={title()} placeholder="Title" onInput={setTitle} onEnter={add} />
+        <IconButton icon="i-lucide:plus" label="Add bookmark" onClick={add} />
+      </Stack>
+      <Show when={entry()}>
+        {(saved) => (
+          <Text size="xs" tone="muted">
+            Saved <TimeAgo date={saved().updatedAt} />
+          </Text>
+        )}
+      </Show>
+      <Stack direction="row" justify="between" align="center">
+        <Link href="https://andesine.app/">Andesine</Link>
+        <Button variant="text" size="small" onClick={() => save([])}>
+          Clear
+        </Button>
+      </Stack>
+    </Stack>
+  );
+};

package/dist/templates/extension/src/frontend/hello-panel.tsx

@@ -0,0 +1,61 @@
+import { createClient } from "@andesine/sdk";
+import {
+  apiFetch,
+  backend,
+  Button,
+  EXTENSION_API_URL,
+  hasPermission,
+  Stack,
+  Text,
+  useConfiguration
+} from "@andesine/extensions/solid";
+import { createResource, createSignal, Show } from "solid-js";
+
+interface HelloPanelProps {
+  /** Right panels with the `entry` context get the open entry's ID. */
+  entryID?: string;
+}
+
+// API calls go through Andesine with the member's session, limited to the extension's grant.
+const client = createClient({ baseURL: EXTENSION_API_URL, fetch: apiFetch });
+
+/** The right panel: reads the open entry through the API, then asks the backend who you are. */
+export const HelloPanel = (props: HelloPanelProps) => {
+  const configuration = useConfiguration<{ greeting: string }>();
+  const [name, setName] = createSignal<string | null>(null);
+  const [failed, setFailed] = createSignal(false);
+  const [entry] = createResource(
+    () => (hasPermission("read:entries") ? props.entryID : undefined),
+    // A failed request would end the view, so the entry line stays hidden instead.
+    (id) => client.entries.get({ id }).catch(() => null)
+  );
+  const askBackend = async () => {
+    try {
+      const response = await backend.fetch("/hello", { method: "POST" });
+      const result = (await response.json()) as { name: string };
+
+      setName(result.name);
+    } catch {
+      setFailed(true);
+    }
+  };
+
+  return (
+    <Stack gap="small">
+      <Text>
+        {configuration().greeting ?? "Hello"}, {name() ?? "member"}!
+      </Text>
+      <Show when={entry()}>
+        {(loaded) => (
+          <Text size="sm" tone="muted">
+            Entry: {loaded().name}
+          </Text>
+        )}
+      </Show>
+      <Button onClick={askBackend}>Ask the backend</Button>
+      <Show when={failed()}>
+        <Text tone="danger">The backend did not answer.</Text>
+      </Show>
+    </Stack>
+  );
+};

package/dist/templates/extension/src/frontend/index.tsx

@@ -0,0 +1,6 @@
+// Every view entry of the manifest is a named export of this module.
+export { AboutSection } from "./about-section";
+export { BookmarksPanel } from "./bookmarks-panel";
+export { HelloPanel } from "./hello-panel";
+export { NoteTitleView, NoteView } from "./note-view";
+export { ShoutAction } from "./shout-action";

package/dist/templates/extension/src/frontend/note-view.tsx

@@ -0,0 +1,54 @@
+import {
+  Box,
+  ContentSlot,
+  Icon,
+  Stack,
+  Text,
+  ToggleGroup,
+  useEditor
+} from "@andesine/extensions/solid";
+
+interface ElementViewProps {
+  /** The element name, e.g. `Note`. */
+  element: string;
+  /** The element's props from the document. */
+  props: { tone?: string };
+}
+
+const tones = [
+  { value: "info", label: "Info" },
+  { value: "warning", label: "Warning" }
+];
+
+/**
+ * The view of `<Note>` elements. `ContentSlot` shows the element's editable content, which
+ * Andesine keeps; the toggle edits the element's props as the member's own edit.
+ */
+export const NoteView = (props: ElementViewProps) => {
+  const editor = useEditor();
+  const tone = () => props.props.tone ?? "info";
+
+  return (
+    <Box padding="medium" background="soft" border class="rounded-lg">
+      <Stack gap="small">
+        <Stack direction="row" justify="between" align="center">
+          <Icon name={tone() === "warning" ? "i-lucide:triangle-alert" : "i-lucide:info"} />
+          <ToggleGroup
+            value={tone()}
+            options={tones}
+            onChange={(value) => editor.setElementProps({ tone: value })}
+          />
+        </Stack>
+        <ContentSlot />
+      </Stack>
+    </Box>
+  );
+};
+/** The view of `<NoteTitle>` elements inside a note, from the note view's descendants. */
+export const NoteTitleView = () => {
+  return (
+    <Text weight="semibold" class="uppercase tracking-wide">
+      <ContentSlot />
+    </Text>
+  );
+};

package/dist/templates/extension/src/frontend/shout-action.tsx

@@ -0,0 +1,57 @@
+import { Button, type ContentNode, Stack, Text, useEditor } from "@andesine/extensions/solid";
+import { createSignal, Show } from "solid-js";
+
+interface BlockActionProps {
+  /** The selected blocks as editor JSON. */
+  blocks: ContentNode[];
+}
+
+const shout = (node: ContentNode): ContentNode => ({
+  ...node,
+  ...(node.text !== undefined && { text: node.text.toUpperCase() }),
+  ...(node.content && { content: node.content.map(shout) })
+});
+const countWords = (node: ContentNode): number => {
+  const own = node.text?.split(/\s+/).filter(Boolean).length ?? 0;
+
+  return own + (node.content ?? []).reduce((total, child) => total + countWords(child), 0);
+};
+
+/** The block action: replaces the selected blocks or inserts a paragraph after them. */
+export const ShoutAction = (props: BlockActionProps) => {
+  const editor = useEditor();
+  const [error, setError] = createSignal<string | null>(null);
+  const words = () => props.blocks.reduce((total, block) => total + countWords(block), 0);
+  const run = async (edit: () => Promise<void>) => {
+    try {
+      await edit();
+      await editor.close();
+    } catch (failure) {
+      setError(failure instanceof Error ? failure.message : "The edit failed");
+    }
+  };
+
+  return (
+    <Stack gap="small">
+      <Text size="sm">{words()} words selected.</Text>
+      <Stack direction="row" gap="small">
+        <Button color="primary" onClick={() => run(() => editor.replace(props.blocks.map(shout)))}>
+          Shout
+        </Button>
+        <Button
+          variant="outlined"
+          onClick={() => {
+            return run(() => {
+              return editor.insertAfter([
+                { type: "paragraph", content: [{ type: "text", text: `${words()} words.` }] }
+              ]);
+            });
+          }}
+        >
+          Count below
+        </Button>
+      </Stack>
+      <Show when={error()}>{(message) => <Text tone="danger">{message()}</Text>}</Show>
+    </Stack>
+  );
+};

package/dist/templates/extension/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["node"]
+  },
+  "include": ["andesine.config.ts", "src"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "andesine",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Command-line tools for Andesine",
   "type": "module",
   "license": "MIT",
@@ -24,22 +24,33 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
+    "@babel/core": "^7.29.7",
     "@clack/prompts": "1.7.0",
     "@commander-js/extra-typings": "15.0.0",
+    "@iconify-json/lucide": "^1.2.140",
+    "@iconify-json/tabler": "^1.2.41",
+    "@iconify/utils": "^3.1.4",
+    "@orpc/zod": "^1.14.14",
+    "babel-preset-solid": "^1.9.12",
+    "base-x": "^5.0.1",
     "commander": "15.0.0",
-    "zod": "4.5.4",
     "open": "11.0.0",
     "proper-lockfile": "4.1.2",
-    "@andesine/sdk": "0.4.0"
+    "rolldown": "^1.2.2",
+    "unocss": "^66.7.5",
+    "zod": "4.5.4",
+    "@andesine/sdk": "0.5.0"
   },
   "devDependencies": {
+    "@types/babel__core": "^7.20.5",
     "@types/node": "^26.1.2",
-    "publint": "0.3.24",
-    "rolldown": "^1.2.2",
-    "typescript": "6.0.3",
     "@types/proper-lockfile": "4.1.4",
+    "prettier": "^3.9.6",
+    "publint": "0.3.24",
     "tsx": "^4.23.5",
-    "prettier": "^3.9.6"
+    "typescript": "6.0.3",
+    "@andesine/contracts": "0.0.0",
+    "@andesine/uno-preset": "0.0.0"
   },
   "repository": {
     "type": "git",