@andesine/extensions 0.0.0-stage → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+## 0.6.0
+
+- `Button` and `IconButton` take one `variant`: `primary`, `secondary`, `ghost`, `link`, or
+  `danger` (`color` is removed). Buttons default to `secondary` and icon buttons to `ghost`.
+  `Input` renders with the outlined look of Andesine's own fields.
+- Remove `settingsSections` from the manifest: the host-rendered configuration form
+  covers settings, and custom extension UI belongs in panels.
+- Add `description` and `icon` to element views; Andesine shows them in the editor's
+  slash menu and in the extension's settings.
+- Block action views decide their UI: a view that renders nothing runs without UI
+  (the block menu shows a spinner until it closes), and one root `Dialog` or
+  `Menu` opens a modal or a menu where the block menu was.
+- Add `Dialog` and `Menu` for any view. `Menu` is a dropdown menu with
+  `MenuTrigger` (or a right-click area with `contextMenu`), `MenuItem` (with
+  submenus and a `loading` spinner), `MenuGroup`, `MenuSeparator`, and custom
+  `MenuContent` items. Outside block actions, a dialog needs a recent interaction.
+- Add `notify(text, type?)`, a host action that shows a short notification.
+- Block action edits accept elements as `{ type: "element", attrs: { name, props } }`;
+  Andesine derives their tag.
+- Fix block action and element view edits built from view props: `editor.replace`,
+  `editor.insertAfter`, and `editor.setElementProps` now send plain JSON instead of
+  store proxies, which could not be sent and stopped the extension.
+
+## 0.5.0
+
+- First release, versioned with `@andesine/sdk` and the `andesine` CLI.
+- Add the root entry for `andesine.config.ts`: `defineExtension` (the manifest; a Zod
+  `configuration` becomes its JSON Schema subset) and `defineBuild` (the frontend module
+  and custom icon sets for `andesine extensions build`).
+- Add `@andesine/extensions/solid`: the worker runtime for extension frontends
+  (`startExtension`), a `solid-js/universal` renderer that sends serialized view
+  patches to Andesine, and the host components: layout (`Stack`, `Grid`, `Box`,
+  `Divider`, `ScrollArea`), text (`Text`, `Heading`, `Code`, `Link`, `Badge`,
+  `Icon`), controls (`Button`, `IconButton`, `Input`, `Textarea`, `Select`,
+  `Combobox`, `Checkbox`, `Toggle`, `ToggleGroup`, `ColorInput`, `Tooltip`),
+  settings (`Setting`, `List`), and data display (`Card`, `Tree`, `Tabs`, `Tab`,
+  `Disclosure`, `Callout`, `Steps`, `Step`, `Figure`, `CodeBlock`, `TimeAgo`,
+  `Spinner`, `Skeleton`).
+- Layout and text components (`Stack`, `Grid`, `Box`, `Text`, `Heading`) accept
+  `class` with utility classes of the Andesine UnoCSS preset. Icons are icon
+  classes (`i-lucide:rocket`; `?bg` for colored icons) from the default Lucide
+  and Tabler sets, installed Iconify sets, or custom sets.
+- Add `ContentSlot` for element views: it shows the element's editable content,
+  which Andesine owns. Element views receive `{ element, props }` with the
+  element name and its props.
+- Add host actions: `copyText`, `downloadFile`, and `openURL`. They run shortly
+  after a user interaction in the extension's view and reject with
+  `ExtensionRequestError` (`code`) otherwise.
+- Add `useEditor()` for views: block action views can `replace` the selected
+  blocks, `insertAfter` them, and `close`; element views can `setElementProps`.
+  Andesine validates each edit and applies it as the member's edit.
+- Add `usePermissions()` and `hasPermission()` for the member's effective
+  permissions, `apiFetch` and `EXTENSION_API_URL` to use the Andesine SDK from
+  the frontend (requests go through Andesine with the member's session), and
+  `backend.fetch` for the extension's own backend with a session token.
+- Add `useConfiguration()` for the configuration's non-secret values, with
+  defaults for unset fields. It updates when a manager saves the configuration.
+- Add `storage` for the extension's JSON key-value storage, which its backend
+  shares: `get`, `set`, `delete`, and `list` (in key order, with an optional
+  prefix).
+- `backend.fetch` also sends the `Andesine-Extension` and `Andesine-Instance`
+  headers, which `verifySession` from `@andesine/sdk/extensions` needs. The
+  backend's CORS configuration must allow them with `Authorization`.

package/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/README.md

@@ -1,4 +1,105 @@
-# Temporary Holding Version
+# @andesine/extensions
 
-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.
-If no other versions are published within 30 days, this package and version will be deleted.
+Authoring tools for Andesine extensions. Extension frontends are Solid components
+that run in a sandboxed worker. Andesine renders its own components from the
+serialized view tree; extension code has no DOM access.
+
+## Solid entry
+
+Compile extension JSX for the universal renderer:
+
+```js
+// babel-preset-solid options
+{ generate: "universal", moduleName: "@andesine/extensions/solid" }
+```
+
+Bundle for the `browser` export condition (Solid's `worker` condition selects its
+non-reactive server build). Then register the views that the manifest names:
+
+```tsx
+import { createSignal } from "solid-js";
+import { Button, Stack, Text, startExtension } from "@andesine/extensions/solid";
+
+const Counter = () => {
+  const [count, setCount] = createSignal(0);
+
+  return (
+    <Stack direction="row" gap="small">
+      <Text>{count()}</Text>
+      <Button onClick={() => setCount(count() + 1)}>Add</Button>
+    </Stack>
+  );
+};
+
+startExtension({ Counter });
+```
+
+Only the exported host components render. Props must be JSON values; functions
+become callbacks that the host calls with plain values.
+
+## Element views
+
+An element view renders a document element (for example `<Accordion>`) and
+receives `{ element, props }`. `ContentSlot` shows the element's editable
+content; Andesine keeps that content when the slot is hidden. A view's CSS does
+not apply inside its slot.
+
+## Host actions
+
+`copyText(text)`, `downloadFile(name, text, type?)`, and `openURL(url)` ask
+Andesine to act for the extension. Call them from an interaction, for example a
+button's `onClick`; otherwise they reject with `ExtensionRequestError` and the
+code `user_interaction_required`. `openURL` asks the member to confirm URLs
+outside the manifest's declared URLs. `notify(text, type?)` shows a short
+notification with the extension's name and needs no interaction.
+
+## Block actions and edits
+
+A block action view receives `{ blocks }`: the selected blocks as editor JSON.
+`useEditor()` returns `replace(content)`, `insertAfter(content)`, and `close()`
+for block action views, and `setElementProps(props)` for element views (call it
+from an interaction). Content must be blocks that are allowed where the
+selection is; edits fail when the selected blocks changed meanwhile. Elements
+are `{ type: "element", attrs: { name, props }, content }`; Andesine derives
+their tag.
+
+The view decides its UI at its root. A view that renders nothing runs without
+UI: the block menu shows a spinner until the view calls `close()`, and Andesine
+stops it after 30 seconds. One root `<Dialog title>` opens a modal, and one root
+`<Menu>` opens a menu where the block menu was; anything else at the root stops
+the action with an error. Escape, an outside click, or the close button close
+them like `close()`; after a menu choice, the action runs on until it closes.
+Choosing the action counts as an interaction, so host actions work right away.
+
+## Dialogs and menus
+
+`Dialog` and `Menu` work in any view. A dialog is shown while it is rendered and
+calls `onClose` when dismissed; outside block actions, render it right after an
+interaction, e.g. from `onClick`, otherwise it is not shown. A `Menu` is a
+dropdown menu: `MenuTrigger` holds its trigger (with `contextMenu`, the area
+that opens it on a right click), and its items are `MenuItem` (nested items
+make a submenu; `loading` shows a spinner), `MenuGroup`, `MenuSeparator`, and
+custom `MenuContent` with any content. `opened` and `onOpenChange` control it.
+
+## API, permissions, and backend
+
+```ts
+import { createClient } from "@andesine/sdk";
+import { EXTENSION_API_URL, apiFetch, backend, hasPermission } from "@andesine/extensions/solid";
+
+const client = createClient({ baseURL: EXTENSION_API_URL, fetch: apiFetch });
+const entries = hasPermission("read:entries") ? await client.entries.list({}) : [];
+const response = await backend.fetch("/publish", { method: "POST" });
+```
+
+API requests use the member's session and are limited to the member's
+permissions that the extension was granted (`usePermissions()`); other
+operations answer with HTTP 403. `backend.fetch` calls paths of the manifest's
+backend URL with a short-lived session token in `Authorization: Bearer`, which
+the backend verifies with Andesine.
+
+## Examples
+
+`npx andesine extensions init` creates a project with samples of the main features: element
+views, a block action, a panel that calls its backend, settings, and webhooks. Published
+extensions in the public registry show complete projects.

package/dist/index.d.ts

@@ -0,0 +1,289 @@
+import * as z from "zod";
+//#region ../../private/contracts/src/extensions/configuration.d.ts
+type ExtensionConfiguration = z.output<typeof extensionConfigurationType>;
+/** Flat JSON Schema 2020-12 subset; the host validates it without running extension code. */
+declare const extensionConfigurationType: z.ZodObject<{
+  $schema: z.ZodOptional<z.ZodLiteral<"https://json-schema.org/draft/2020-12/schema">>;
+  type: z.ZodLiteral<"object">;
+  properties: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"string">;
+    minLength: z.ZodOptional<z.ZodInt>;
+    maxLength: z.ZodOptional<z.ZodInt>;
+    pattern: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<{
+      uri: "uri";
+      email: "email";
+    }>>;
+    default: z.ZodOptional<z.ZodString>;
+    secret: z.ZodOptional<z.ZodLiteral<true>>;
+    control: z.ZodOptional<z.ZodLiteral<"textarea">>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"string">;
+    enum: z.ZodArray<z.ZodString>;
+    default: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, z.ZodObject<{
+    type: z.ZodEnum<{
+      number: "number";
+      integer: "integer";
+    }>;
+    minimum: z.ZodOptional<z.ZodNumber>;
+    maximum: z.ZodOptional<z.ZodNumber>;
+    exclusiveMinimum: z.ZodOptional<z.ZodNumber>;
+    exclusiveMaximum: z.ZodOptional<z.ZodNumber>;
+    multipleOf: z.ZodOptional<z.ZodNumber>;
+    default: z.ZodOptional<z.ZodNumber>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+    default: z.ZodOptional<z.ZodBoolean>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"array">;
+    items: z.ZodUnion<readonly [z.ZodObject<{
+      type: z.ZodLiteral<"string">;
+      minLength: z.ZodOptional<z.ZodInt>;
+      maxLength: z.ZodOptional<z.ZodInt>;
+      pattern: z.ZodOptional<z.ZodString>;
+      format: z.ZodOptional<z.ZodEnum<{
+        uri: "uri";
+        email: "email";
+      }>>;
+    }, z.core.$strict>, z.ZodObject<{
+      type: z.ZodLiteral<"string">;
+      enum: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+      type: z.ZodEnum<{
+        number: "number";
+        integer: "integer";
+      }>;
+      minimum: z.ZodOptional<z.ZodNumber>;
+      maximum: z.ZodOptional<z.ZodNumber>;
+      exclusiveMinimum: z.ZodOptional<z.ZodNumber>;
+      exclusiveMaximum: z.ZodOptional<z.ZodNumber>;
+      multipleOf: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+      type: z.ZodLiteral<"boolean">;
+    }, z.core.$strict>]>;
+    minItems: z.ZodOptional<z.ZodInt>;
+    maxItems: z.ZodOptional<z.ZodInt>;
+    uniqueItems: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>]>>;
+  required: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  additionalProperties: z.ZodLiteral<false>;
+}, z.core.$strict>;
+//#endregion
+//#region ../../private/contracts/src/extensions/manifest.d.ts
+declare const extensionManifestType: z.ZodObject<{
+  elementViews: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    element: z.ZodString;
+    entry: z.ZodString;
+    descendants: z.ZodDefault<z.ZodArray<z.ZodObject<{
+      element: z.ZodString;
+      entry: z.ZodString;
+    }, z.core.$strict>>>;
+  }, z.core.$strict>>>;
+  blockActions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    icon: z.ZodOptional<z.ZodString>;
+    blocks: z.ZodArray<z.ZodString>;
+    entry: z.ZodString;
+  }, z.core.$strict>>>;
+  panels: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    side: z.ZodLiteral<"left">;
+    entry: z.ZodString;
+    id: z.ZodString;
+    name: z.ZodString;
+    icon: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    side: z.ZodLiteral<"right">;
+    context: z.ZodEnum<{
+      entry: "entry";
+      workspace: "workspace";
+      collection: "collection";
+    }>;
+    entry: z.ZodString;
+    id: z.ZodString;
+    name: z.ZodString;
+    icon: z.ZodString;
+  }, z.core.$strict>], "side">>>;
+  name: z.ZodString;
+  version: z.ZodString;
+  displayName: z.ZodString;
+  description: z.ZodString;
+  icon: z.ZodOptional<z.ZodString>;
+  apiVersion: z.ZodLiteral<1>;
+  permissions: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+    "read:restricted_collections": "read:restricted_collections";
+    entries: "entries";
+    "read:entries": "read:entries";
+    versions: "versions";
+    "read:versions": "read:versions";
+    publishing: "publishing";
+    "read:publishing": "read:publishing";
+    collections: "collections";
+    "read:collections": "read:collections";
+    memberships: "memberships";
+    "read:memberships": "read:memberships";
+    roles: "roles";
+    "read:roles": "read:roles";
+    webhooks: "webhooks";
+    "read:webhooks": "read:webhooks";
+    "ai-answers": "ai-answers";
+  }>>>;
+  requests: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  backend: z.ZodOptional<z.ZodObject<{
+    url: z.ZodString;
+    keys: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+      kid: z.ZodString;
+      kty: z.ZodLiteral<"OKP">;
+      alg: z.ZodLiteral<"EdDSA">;
+      crv: z.ZodLiteral<"Ed25519">;
+      x: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      kid: z.ZodString;
+      kty: z.ZodLiteral<"EC">;
+      alg: z.ZodLiteral<"ES256">;
+      crv: z.ZodLiteral<"P-256">;
+      x: z.ZodString;
+      y: z.ZodString;
+    }, z.core.$strict>], "alg">>;
+  }, z.core.$strict>>;
+  webhooks: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+    events: z.ZodArray<z.ZodEnum<{
+      "entry.created": "entry.created";
+      "entry.updated": "entry.updated";
+      "entry.content_saved": "entry.content_saved";
+      "entry.moved": "entry.moved";
+      "entry.deleted": "entry.deleted";
+      "entry.restored": "entry.restored";
+      "collection.created": "collection.created";
+      "collection.updated": "collection.updated";
+      "collection.moved": "collection.moved";
+      "collection.deleted": "collection.deleted";
+      "collection.restored": "collection.restored";
+      "publishing.channel_advanced": "publishing.channel_advanced";
+      "publishing.channel_created": "publishing.channel_created";
+      "publishing.channel_deleted": "publishing.channel_deleted";
+      "extension.installed": "extension.installed";
+      "extension.enabled": "extension.enabled";
+      "extension.disabled": "extension.disabled";
+      "extension.updated": "extension.updated";
+      "extension.configured": "extension.configured";
+      "extension.uninstalled": "extension.uninstalled";
+    }>>;
+    path: z.ZodString;
+    channels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>>>;
+  configuration: z.ZodOptional<z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodLiteral<"https://json-schema.org/draft/2020-12/schema">>;
+    type: z.ZodLiteral<"object">;
+    properties: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+      type: z.ZodLiteral<"string">;
+      minLength: z.ZodOptional<z.ZodInt>;
+      maxLength: z.ZodOptional<z.ZodInt>;
+      pattern: z.ZodOptional<z.ZodString>;
+      format: z.ZodOptional<z.ZodEnum<{
+        uri: "uri";
+        email: "email";
+      }>>;
+      default: z.ZodOptional<z.ZodString>;
+      secret: z.ZodOptional<z.ZodLiteral<true>>;
+      control: z.ZodOptional<z.ZodLiteral<"textarea">>;
+      title: z.ZodOptional<z.ZodString>;
+      description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+      type: z.ZodLiteral<"string">;
+      enum: z.ZodArray<z.ZodString>;
+      default: z.ZodOptional<z.ZodString>;
+      title: z.ZodOptional<z.ZodString>;
+      description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+      type: z.ZodEnum<{
+        number: "number";
+        integer: "integer";
+      }>;
+      minimum: z.ZodOptional<z.ZodNumber>;
+      maximum: z.ZodOptional<z.ZodNumber>;
+      exclusiveMinimum: z.ZodOptional<z.ZodNumber>;
+      exclusiveMaximum: z.ZodOptional<z.ZodNumber>;
+      multipleOf: z.ZodOptional<z.ZodNumber>;
+      default: z.ZodOptional<z.ZodNumber>;
+      title: z.ZodOptional<z.ZodString>;
+      description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+      type: z.ZodLiteral<"boolean">;
+      default: z.ZodOptional<z.ZodBoolean>;
+      title: z.ZodOptional<z.ZodString>;
+      description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+      type: z.ZodLiteral<"array">;
+      items: z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"string">;
+        minLength: z.ZodOptional<z.ZodInt>;
+        maxLength: z.ZodOptional<z.ZodInt>;
+        pattern: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodEnum<{
+          uri: "uri";
+          email: "email";
+        }>>;
+      }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"string">;
+        enum: z.ZodArray<z.ZodString>;
+      }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodEnum<{
+          number: "number";
+          integer: "integer";
+        }>;
+        minimum: z.ZodOptional<z.ZodNumber>;
+        maximum: z.ZodOptional<z.ZodNumber>;
+        exclusiveMinimum: z.ZodOptional<z.ZodNumber>;
+        exclusiveMaximum: z.ZodOptional<z.ZodNumber>;
+        multipleOf: z.ZodOptional<z.ZodNumber>;
+      }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"boolean">;
+      }, z.core.$strict>]>;
+      minItems: z.ZodOptional<z.ZodInt>;
+      maxItems: z.ZodOptional<z.ZodInt>;
+      uniqueItems: z.ZodOptional<z.ZodBoolean>;
+      default: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+      title: z.ZodOptional<z.ZodString>;
+      description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>;
+    required: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    additionalProperties: z.ZodLiteral<false>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+//#endregion
+//#region src/index.d.ts
+interface ExtensionDefinition extends Omit<ExtensionManifestInput, "configuration"> {
+  /** A Zod object of flat fields, or the configuration schema it converts to. */
+  configuration?: z.ZodObject | ExtensionConfiguration;
+}
+/** Options of `andesine extensions build`, exported from the config file as `build`. */
+interface ExtensionBuildOptions {
+  /** The module exporting the manifest's view entries (default: `src/frontend/index.tsx`). */
+  frontend?: string;
+  /** Custom icon sets: a set prefix and a directory of SVG files, e.g. `{ acme: "./icons" }`. */
+  icons?: Record<string, string>;
+}
+type ExtensionManifestInput = z.input<typeof extensionManifestType>;
+/** Defines the `andesine.config.ts` manifest; a Zod configuration becomes JSON Schema. */
+declare const defineExtension: (definition: ExtensionDefinition) => ExtensionManifestInput;
+declare const defineBuild: (options: ExtensionBuildOptions) => ExtensionBuildOptions;
+//#endregion
+export { type ExtensionBuildOptions, type ExtensionDefinition, type ExtensionManifestInput, defineBuild, defineExtension };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,173 @@
+import * as z from "zod";
+//#region ../../private/contracts/src/primitives/unique.ts
+const uniqueItems = (values) => new Set(values).size === values.length;
+//#endregion
+//#region ../../private/contracts/src/extensions/configuration.ts
+const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+const MAX_CONFIGURATION_STRING_LENGTH = 1e4;
+const MAX_CONFIGURATION_ARRAY_ITEMS = 100;
+const MAX_CONFIGURATION_ENUM_VALUES = 100;
+const MAX_CONFIGURATION_PATTERN_LENGTH = 500;
+const isValidPattern = (pattern) => {
+	try {
+		new RegExp(pattern);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const fieldKeyType = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/, "Use a letter, then letters, digits, or underscores");
+const lengthType = z.int().min(0).max(MAX_CONFIGURATION_STRING_LENGTH);
+const metadata = {
+	title: z.string().min(1).max(100).optional(),
+	description: z.string().min(1).max(500).optional()
+};
+const stringItemType = z.strictObject({
+	type: z.literal("string"),
+	minLength: lengthType.optional(),
+	maxLength: lengthType.optional(),
+	pattern: z.string().min(1).max(MAX_CONFIGURATION_PATTERN_LENGTH).refine(isValidPattern, "Use a valid regular expression").optional(),
+	format: z.enum(["uri", "email"]).optional()
+});
+const enumItemType = z.strictObject({
+	type: z.literal("string"),
+	enum: z.array(z.string().min(1).max(200)).min(1).max(MAX_CONFIGURATION_ENUM_VALUES).refine(uniqueItems, "Options must be unique")
+});
+const numberItemType = z.strictObject({
+	type: z.enum(["number", "integer"]),
+	minimum: z.number().optional(),
+	maximum: z.number().optional(),
+	exclusiveMinimum: z.number().optional(),
+	exclusiveMaximum: z.number().optional(),
+	multipleOf: z.number().positive().optional()
+});
+const booleanItemType = z.strictObject({ type: z.literal("boolean") });
+const stringFormatTypes = {
+	uri: z.url(),
+	email: z.email()
+};
+const itemType = z.union([
+	stringItemType,
+	enumItemType,
+	numberItemType,
+	booleanItemType
+]);
+const fieldType = z.union([
+	stringItemType.extend({
+		...metadata,
+		default: z.string().optional(),
+		secret: z.literal(true).optional(),
+		control: z.literal("textarea").optional()
+	}),
+	enumItemType.extend({
+		...metadata,
+		default: z.string().optional()
+	}),
+	numberItemType.extend({
+		...metadata,
+		default: z.number().optional()
+	}),
+	booleanItemType.extend({
+		...metadata,
+		default: z.boolean().optional()
+	}),
+	z.strictObject({
+		...metadata,
+		type: z.literal("array"),
+		items: itemType,
+		minItems: z.int().min(0).max(MAX_CONFIGURATION_ARRAY_ITEMS).optional(),
+		maxItems: z.int().min(0).max(MAX_CONFIGURATION_ARRAY_ITEMS).optional(),
+		uniqueItems: z.boolean().optional(),
+		default: z.array(z.union([
+			z.string(),
+			z.number(),
+			z.boolean()
+		])).optional()
+	})
+]);
+/** Flat JSON Schema 2020-12 subset; the host validates it without running extension code. */
+const extensionConfigurationType = z.strictObject({
+	$schema: z.literal(JSON_SCHEMA_DIALECT).optional(),
+	type: z.literal("object"),
+	properties: z.record(fieldKeyType, fieldType).refine((properties) => Object.keys(properties).length <= 50, `Use at most 50 fields`),
+	required: z.array(fieldKeyType).refine(uniqueItems, "Fields must be unique").optional(),
+	additionalProperties: z.literal(false)
+}).superRefine((configuration, context) => {
+	for (const [index, key] of (configuration.required || []).entries()) if (!configuration.properties[key]) context.addIssue({
+		code: "custom",
+		path: ["required", index],
+		message: "Unknown field"
+	});
+	for (const [key, field] of Object.entries(configuration.properties)) if ("secret" in field && field.secret && field.default !== void 0) context.addIssue({
+		code: "custom",
+		path: [
+			"properties",
+			key,
+			"default"
+		],
+		message: "Secret fields cannot have defaults"
+	});
+	else if (field.default !== void 0) {
+		if (!createConfigurationValueType(field).safeParse(field.default).success) context.addIssue({
+			code: "custom",
+			path: [
+				"properties",
+				key,
+				"default"
+			],
+			message: "The default does not match the field"
+		});
+	}
+});
+const createConfigurationValueType = (field) => {
+	if (field.type === "boolean") return z.boolean();
+	if (field.type === "array") {
+		const maxItems = Math.min(field.maxItems ?? MAX_CONFIGURATION_ARRAY_ITEMS, MAX_CONFIGURATION_ARRAY_ITEMS);
+		const items = z.array(createConfigurationValueType(field.items)).min(field.minItems ?? 0).max(maxItems);
+		return field.uniqueItems ? items.refine(uniqueItems, "Values must be unique") : items;
+	}
+	if ("enum" in field) return z.enum(field.enum);
+	if (field.type === "string") {
+		const maxLength = Math.min(field.maxLength ?? MAX_CONFIGURATION_STRING_LENGTH, MAX_CONFIGURATION_STRING_LENGTH);
+		const value = (field.format ? stringFormatTypes[field.format] : z.string()).min(field.minLength ?? 0).max(maxLength);
+		return field.pattern ? value.regex(new RegExp(field.pattern)) : value;
+	}
+	let value = field.type === "integer" ? z.int() : z.number();
+	if (field.minimum !== void 0) value = value.gte(field.minimum);
+	if (field.maximum !== void 0) value = value.lte(field.maximum);
+	if (field.exclusiveMinimum !== void 0) value = value.gt(field.exclusiveMinimum);
+	if (field.exclusiveMaximum !== void 0) value = value.lt(field.exclusiveMaximum);
+	if (field.multipleOf !== void 0) value = value.multipleOf(field.multipleOf);
+	return value;
+};
+/** Converts an authoring Zod object to the configuration subset; unsupported constructs throw. */
+const toExtensionConfiguration = (schema) => {
+	const jsonSchema = z.toJSONSchema(schema, {
+		io: "input",
+		target: "draft-2020-12",
+		unrepresentable: "throw"
+	});
+	const result = extensionConfigurationType.safeParse({
+		additionalProperties: false,
+		...jsonSchema
+	});
+	if (!result.success) throw new Error(`Unsupported configuration schema:\n${z.prettifyError(result.error)}`);
+	return result.data;
+};
+//#endregion
+//#region src/index.ts
+const isZodObject = (value) => "_zod" in value;
+/** Defines the `andesine.config.ts` manifest; a Zod configuration becomes JSON Schema. */
+const defineExtension = (definition) => {
+	const { configuration, ...manifest } = definition;
+	if (!configuration) return manifest;
+	return {
+		...manifest,
+		configuration: isZodObject(configuration) ? toExtensionConfiguration(configuration) : configuration
+	};
+};
+const defineBuild = (options) => options;
+//#endregion
+export { defineBuild, defineExtension };
+
+//# sourceMappingURL=index.js.map