@crowi/plugin-api 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { z } from 'zod/v3';
 import { Readable } from 'node:stream';
+import { Context } from 'hono';
 
 /**
  * The context object passed to every plugin callback. It is the only
@@ -29,6 +30,13 @@ interface PluginContext {
      * instead of duplicating the fields in their own configSchema.
      */
     dependencyConfig<T>(dependencyName: string): T;
+    /**
+     * Read core application info (the wiki name, …) — settings that live
+     * outside this plugin's own config namespace but that an integration
+     * may need (e.g. to brand an outbound manifest). Read live at call
+     * time, so it reflects admin edits made after boot.
+     */
+    appInfo(): AppInfo;
     /** Write a single config field, persisting to Mongo. */
     setConfig(key: string, value: unknown): Promise<void>;
     /** Per-Page metadata accessor for this plugin's namespace. */
@@ -48,6 +56,30 @@ interface PluginContext {
     /** Structured logger scoped to this plugin (auto-prefixed with name). */
     log: PluginLogger;
 }
+/**
+ * Read-only view of core application settings exposed to plugins via
+ * `ctx.appInfo()`. Intentionally a small, curated surface (not a generic
+ * "read any core config" escape hatch) — add fields here as concrete
+ * plugin needs appear.
+ */
+interface AppInfo {
+    /**
+     * The configured wiki name (core `app:title`), trimmed. Always a
+     * non-empty string: when the operator has not set a custom title it
+     * defaults to `'Crowi'` (the seed value), so consumers never have to
+     * handle an absent name.
+     */
+    title: string;
+    /**
+     * The wiki's public base origin (core `CLIENT_URL` / `getBaseUrl()`),
+     * e.g. `https://wiki.example.com`. An **empty string** when no public
+     * origin is configured — unlike `title` there is no sensible default,
+     * so a plugin that needs an absolute URL (outbound webhook / manifest)
+     * must handle the empty case. Plugins read this instead of
+     * `process.env.CLIENT_URL` directly.
+     */
+    baseUrl: string;
+}
 /**
  * Per-Page metadata read / write helper. Each plugin gets a private
  * namespace at `page.metadata['<plugin-name>']`; this accessor scopes
@@ -910,28 +942,65 @@ interface RendererRegistry {
 }
 
 /**
- * Scope passed to `registerRoutes`. The HTTP route contribution surface
- * for plugins is **not currently wired** to the runtime — it has never
- * been invoked end-to-end. RFC-0006 Phase 6 removed the framework
- * dependency that previously typed the contract argument; the API
- * surface is therefore a deliberate no-op stub until a follow-up RFC
- * redesigns plugin HTTP contribution on top of Hono.
+ * HTTP method a plugin route can be mounted on. Kept to the verbs the
+ * inbound-webhook + admin-action surface actually needs (RFC-0013 §4):
+ * `POST` for Slack events / slash / interactivity + `@action` targets,
+ * `GET` for OAuth callbacks + simple status endpoints.
+ */
+type PluginRouteMethod = 'GET' | 'POST';
+/**
+ * A plugin route handler. It receives the raw Hono `Context` and returns
+ * a `Response` (or a promise of one), exactly like a hand-written Hono
+ * handler — the scope does **not** wrap it in a typed-route/validator
+ * layer.
  *
- * Plugins that declare a `registerRoutes` callback today see it
- * receive this scope and call `scope.register(...)` with arbitrary
- * arguments — both arguments are accepted as `unknown` and the call
- * is silently dropped. The type fixture exists so the public surface
- * of `@crowi/plugin-api` keeps compiling against existing plugin
- * sources (including the in-tree `__fixtures__/example-plugin.ts`)
- * without forcing every plugin to be updated in lockstep with Phase 6.
+ * **Raw body invariant** (RFC-0013 §8, a Slack hard requirement): the
+ * route is a plain Hono route, NOT a `@hono/zod-openapi` route, so no
+ * body-consuming validator runs ahead of the handler. `c.req.text()` /
+ * `c.req.raw` therefore yield the *exact* bytes the client sent, which
+ * the Slack signature check (`HMAC-SHA256` over `v0:{ts}:{rawBody}`)
+ * depends on. `createJwtAuth` (installed on non-public routes) never
+ * reads the body, so the invariant holds for authed routes too.
+ */
+type PluginRouteHandler = (c: Context) => Response | Promise<Response>;
+/** Per-route options passed alongside the handler. */
+interface PluginRouteOptions {
+    /**
+     * When `true`, the route is mounted **without** `createJwtAuth`, so it
+     * is reachable by unauthenticated requests (Crowi-auth public). Use for
+     * inbound webhooks that authenticate themselves out-of-band — e.g. the
+     * Slack Events API endpoint, which is gated by Slack's request-signature
+     * check rather than a Crowi session (RFC-0013 §8).
+     *
+     * Omitted / `false` mounts the route under `createJwtAuth`, so it
+     * requires a valid Crowi JWT just like a core authenticated endpoint
+     * (admin "Test connection" / `@action` targets, OAuth callbacks).
+     */
+    public?: boolean;
+}
+/**
+ * Scope passed to `registerRoutes(scope, ctx)`. Lets a plugin contribute
+ * HTTP routes that the runtime mounts at
+ * `/api/v2/plugins/<plugin-name>/<path>` — the `<plugin-name>` path
+ * segment guarantees that core endpoints and other plugins cannot
+ * collide (RFC-0013 §4).
+ *
+ * The scope is built per-plugin inside `buildHonoApp` (the Hono app does
+ * not exist yet when plugins activate at boot), so `<plugin-name>` is
+ * already closed over — plugins only supply the sub-path.
  */
 interface PluginRouterScope {
     /**
-     * No-op register. Both arguments are typed as `unknown` because the
-     * runtime never reads them; concrete shapes are reserved for the
-     * follow-up RFC that wires plugin HTTP contribution onto Hono.
+     * Mount `handler` for `method` at `<path>` under this plugin's
+     * namespace. `path` is relative to `/api/v2/plugins/<plugin-name>` and
+     * should start with `/` (e.g. `route('POST', '/events', handler, {
+     * public: true })` → `POST /api/v2/plugins/<name>/events`).
+     *
+     * Pass `{ public: true }` to bypass `createJwtAuth` for self-
+     * authenticating inbound webhooks; omit it for routes that require a
+     * Crowi session.
      */
-    register(contract: unknown, implementation: unknown): void;
+    route(method: PluginRouteMethod, path: string, handler: PluginRouteHandler, opts?: PluginRouteOptions): void;
 }
 
 /**
@@ -1002,7 +1071,7 @@ interface CrowiPlugin {
      * from a fixed allow-list to keep the bundle small.
      */
     adminPlacement?: {
-        section?: 'settings' | 'shared' | 'storage' | 'mail' | 'notification' | 'auth' | 'search' | 'renderer';
+        section?: 'settings' | 'shared' | 'storage' | 'mail' | 'notification' | 'auth' | 'search' | 'renderer' | 'platform';
         label?: string;
         icon?: string;
     };
@@ -1052,13 +1121,24 @@ interface CrowiPlugin {
      */
     registerHooks?: (events: EventBus, ctx: PluginContext) => void;
     /**
-     * ts-rest contract that the plugin contributes. Mounted at
-     * `/api/v2/plugins/<name>/*` (the `<name>` path segment guarantees
+     * HTTP routes the plugin contributes, mounted at
+     * `/api/v2/plugins/<name>/<path>` (the `<name>` path segment guarantees
      * that core endpoints and other plugins cannot collide). Used for
-     * "Test connection" buttons, OAuth callbacks, custom admin views,
-     * etc. The contract surface uses ts-rest so the admin UI can call
-     * plugin endpoints with the same `apiClient.<plugin>.<method>` shape
-     * it uses for core endpoints.
+     * inbound webhooks (Slack events / slash / interactivity), "Test
+     * connection" buttons, `@action` targets, OAuth callbacks, etc.
+     *
+     * Each route is a plain Hono handler — `scope.route(method, path,
+     * (c) => Response, opts?)`. The handler receives the raw `Context`, so
+     * `c.req.text()` / `c.req.raw` give the exact request bytes (no
+     * validator consumes the body ahead of it — the Slack signature check
+     * relies on this). Pass `{ public: true }` to bypass `createJwtAuth`
+     * for self-authenticating webhooks; omit it for Crowi-session-gated
+     * routes.
+     *
+     * Called once at boot — but unlike the other `register*` hooks, this
+     * runs inside `buildHonoApp` (the Hono app does not exist yet when
+     * plugins activate), so a plugin's `registerRoutes` fires slightly
+     * later than its `registerStorage` / `registerNotifier` / etc.
      */
     registerRoutes?: (scope: PluginRouterScope, ctx: PluginContext) => void;
     /**
@@ -1156,4 +1236,4 @@ interface ActionAnnotation {
  */
 declare function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null;
 
-export { ACTION_FIELD_MARKER, type AuthContext, type AuthDriver, type AuthProfile, type AuthRegistry, type AuthVerifyResult, type CacheEntry, type CacheKey, type CacheStorage, type CodeBlockInfo, type CodeBlockRenderer, type CrowiPlugin, type EmailMessage, type EmbedFragment, type EmbedInput, type EmbedRenderer, type EventBus, type InlineExpansion, type MailSender, type MailSenderRegistry, type NodeRenderer, type NotificationPayload, type NotifierDriver, type NotifierRegistry, type PageMetadataAccessor, type PluginContext, type PluginCrypto, type PluginEvents, type PluginLogger, type PluginRouterScope, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type UrlInlineExpansionRule, getActionAnnotation, isSensitiveField };
+export { ACTION_FIELD_MARKER, type AppInfo, type AuthContext, type AuthDriver, type AuthProfile, type AuthRegistry, type AuthVerifyResult, type CacheEntry, type CacheKey, type CacheStorage, type CodeBlockInfo, type CodeBlockRenderer, type CrowiPlugin, type EmailMessage, type EmbedFragment, type EmbedInput, type EmbedRenderer, type EventBus, type InlineExpansion, type MailSender, type MailSenderRegistry, type NodeRenderer, type NotificationPayload, type NotifierDriver, type NotifierRegistry, type PageMetadataAccessor, type PluginContext, type PluginCrypto, type PluginEvents, type PluginLogger, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, type PluginRouterScope, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type UrlInlineExpansionRule, getActionAnnotation, isSensitiveField };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod/v3';
 import { Readable } from 'node:stream';
+import { Context } from 'hono';
 
 /**
  * The context object passed to every plugin callback. It is the only
@@ -29,6 +30,13 @@ interface PluginContext {
      * instead of duplicating the fields in their own configSchema.
      */
     dependencyConfig<T>(dependencyName: string): T;
+    /**
+     * Read core application info (the wiki name, …) — settings that live
+     * outside this plugin's own config namespace but that an integration
+     * may need (e.g. to brand an outbound manifest). Read live at call
+     * time, so it reflects admin edits made after boot.
+     */
+    appInfo(): AppInfo;
     /** Write a single config field, persisting to Mongo. */
     setConfig(key: string, value: unknown): Promise<void>;
     /** Per-Page metadata accessor for this plugin's namespace. */
@@ -48,6 +56,30 @@ interface PluginContext {
     /** Structured logger scoped to this plugin (auto-prefixed with name). */
     log: PluginLogger;
 }
+/**
+ * Read-only view of core application settings exposed to plugins via
+ * `ctx.appInfo()`. Intentionally a small, curated surface (not a generic
+ * "read any core config" escape hatch) — add fields here as concrete
+ * plugin needs appear.
+ */
+interface AppInfo {
+    /**
+     * The configured wiki name (core `app:title`), trimmed. Always a
+     * non-empty string: when the operator has not set a custom title it
+     * defaults to `'Crowi'` (the seed value), so consumers never have to
+     * handle an absent name.
+     */
+    title: string;
+    /**
+     * The wiki's public base origin (core `CLIENT_URL` / `getBaseUrl()`),
+     * e.g. `https://wiki.example.com`. An **empty string** when no public
+     * origin is configured — unlike `title` there is no sensible default,
+     * so a plugin that needs an absolute URL (outbound webhook / manifest)
+     * must handle the empty case. Plugins read this instead of
+     * `process.env.CLIENT_URL` directly.
+     */
+    baseUrl: string;
+}
 /**
  * Per-Page metadata read / write helper. Each plugin gets a private
  * namespace at `page.metadata['<plugin-name>']`; this accessor scopes
@@ -910,28 +942,65 @@ interface RendererRegistry {
 }
 
 /**
- * Scope passed to `registerRoutes`. The HTTP route contribution surface
- * for plugins is **not currently wired** to the runtime — it has never
- * been invoked end-to-end. RFC-0006 Phase 6 removed the framework
- * dependency that previously typed the contract argument; the API
- * surface is therefore a deliberate no-op stub until a follow-up RFC
- * redesigns plugin HTTP contribution on top of Hono.
+ * HTTP method a plugin route can be mounted on. Kept to the verbs the
+ * inbound-webhook + admin-action surface actually needs (RFC-0013 §4):
+ * `POST` for Slack events / slash / interactivity + `@action` targets,
+ * `GET` for OAuth callbacks + simple status endpoints.
+ */
+type PluginRouteMethod = 'GET' | 'POST';
+/**
+ * A plugin route handler. It receives the raw Hono `Context` and returns
+ * a `Response` (or a promise of one), exactly like a hand-written Hono
+ * handler — the scope does **not** wrap it in a typed-route/validator
+ * layer.
  *
- * Plugins that declare a `registerRoutes` callback today see it
- * receive this scope and call `scope.register(...)` with arbitrary
- * arguments — both arguments are accepted as `unknown` and the call
- * is silently dropped. The type fixture exists so the public surface
- * of `@crowi/plugin-api` keeps compiling against existing plugin
- * sources (including the in-tree `__fixtures__/example-plugin.ts`)
- * without forcing every plugin to be updated in lockstep with Phase 6.
+ * **Raw body invariant** (RFC-0013 §8, a Slack hard requirement): the
+ * route is a plain Hono route, NOT a `@hono/zod-openapi` route, so no
+ * body-consuming validator runs ahead of the handler. `c.req.text()` /
+ * `c.req.raw` therefore yield the *exact* bytes the client sent, which
+ * the Slack signature check (`HMAC-SHA256` over `v0:{ts}:{rawBody}`)
+ * depends on. `createJwtAuth` (installed on non-public routes) never
+ * reads the body, so the invariant holds for authed routes too.
+ */
+type PluginRouteHandler = (c: Context) => Response | Promise<Response>;
+/** Per-route options passed alongside the handler. */
+interface PluginRouteOptions {
+    /**
+     * When `true`, the route is mounted **without** `createJwtAuth`, so it
+     * is reachable by unauthenticated requests (Crowi-auth public). Use for
+     * inbound webhooks that authenticate themselves out-of-band — e.g. the
+     * Slack Events API endpoint, which is gated by Slack's request-signature
+     * check rather than a Crowi session (RFC-0013 §8).
+     *
+     * Omitted / `false` mounts the route under `createJwtAuth`, so it
+     * requires a valid Crowi JWT just like a core authenticated endpoint
+     * (admin "Test connection" / `@action` targets, OAuth callbacks).
+     */
+    public?: boolean;
+}
+/**
+ * Scope passed to `registerRoutes(scope, ctx)`. Lets a plugin contribute
+ * HTTP routes that the runtime mounts at
+ * `/api/v2/plugins/<plugin-name>/<path>` — the `<plugin-name>` path
+ * segment guarantees that core endpoints and other plugins cannot
+ * collide (RFC-0013 §4).
+ *
+ * The scope is built per-plugin inside `buildHonoApp` (the Hono app does
+ * not exist yet when plugins activate at boot), so `<plugin-name>` is
+ * already closed over — plugins only supply the sub-path.
  */
 interface PluginRouterScope {
     /**
-     * No-op register. Both arguments are typed as `unknown` because the
-     * runtime never reads them; concrete shapes are reserved for the
-     * follow-up RFC that wires plugin HTTP contribution onto Hono.
+     * Mount `handler` for `method` at `<path>` under this plugin's
+     * namespace. `path` is relative to `/api/v2/plugins/<plugin-name>` and
+     * should start with `/` (e.g. `route('POST', '/events', handler, {
+     * public: true })` → `POST /api/v2/plugins/<name>/events`).
+     *
+     * Pass `{ public: true }` to bypass `createJwtAuth` for self-
+     * authenticating inbound webhooks; omit it for routes that require a
+     * Crowi session.
      */
-    register(contract: unknown, implementation: unknown): void;
+    route(method: PluginRouteMethod, path: string, handler: PluginRouteHandler, opts?: PluginRouteOptions): void;
 }
 
 /**
@@ -1002,7 +1071,7 @@ interface CrowiPlugin {
      * from a fixed allow-list to keep the bundle small.
      */
     adminPlacement?: {
-        section?: 'settings' | 'shared' | 'storage' | 'mail' | 'notification' | 'auth' | 'search' | 'renderer';
+        section?: 'settings' | 'shared' | 'storage' | 'mail' | 'notification' | 'auth' | 'search' | 'renderer' | 'platform';
         label?: string;
         icon?: string;
     };
@@ -1052,13 +1121,24 @@ interface CrowiPlugin {
      */
     registerHooks?: (events: EventBus, ctx: PluginContext) => void;
     /**
-     * ts-rest contract that the plugin contributes. Mounted at
-     * `/api/v2/plugins/<name>/*` (the `<name>` path segment guarantees
+     * HTTP routes the plugin contributes, mounted at
+     * `/api/v2/plugins/<name>/<path>` (the `<name>` path segment guarantees
      * that core endpoints and other plugins cannot collide). Used for
-     * "Test connection" buttons, OAuth callbacks, custom admin views,
-     * etc. The contract surface uses ts-rest so the admin UI can call
-     * plugin endpoints with the same `apiClient.<plugin>.<method>` shape
-     * it uses for core endpoints.
+     * inbound webhooks (Slack events / slash / interactivity), "Test
+     * connection" buttons, `@action` targets, OAuth callbacks, etc.
+     *
+     * Each route is a plain Hono handler — `scope.route(method, path,
+     * (c) => Response, opts?)`. The handler receives the raw `Context`, so
+     * `c.req.text()` / `c.req.raw` give the exact request bytes (no
+     * validator consumes the body ahead of it — the Slack signature check
+     * relies on this). Pass `{ public: true }` to bypass `createJwtAuth`
+     * for self-authenticating webhooks; omit it for Crowi-session-gated
+     * routes.
+     *
+     * Called once at boot — but unlike the other `register*` hooks, this
+     * runs inside `buildHonoApp` (the Hono app does not exist yet when
+     * plugins activate), so a plugin's `registerRoutes` fires slightly
+     * later than its `registerStorage` / `registerNotifier` / etc.
      */
     registerRoutes?: (scope: PluginRouterScope, ctx: PluginContext) => void;
     /**
@@ -1156,4 +1236,4 @@ interface ActionAnnotation {
  */
 declare function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null;
 
-export { ACTION_FIELD_MARKER, type AuthContext, type AuthDriver, type AuthProfile, type AuthRegistry, type AuthVerifyResult, type CacheEntry, type CacheKey, type CacheStorage, type CodeBlockInfo, type CodeBlockRenderer, type CrowiPlugin, type EmailMessage, type EmbedFragment, type EmbedInput, type EmbedRenderer, type EventBus, type InlineExpansion, type MailSender, type MailSenderRegistry, type NodeRenderer, type NotificationPayload, type NotifierDriver, type NotifierRegistry, type PageMetadataAccessor, type PluginContext, type PluginCrypto, type PluginEvents, type PluginLogger, type PluginRouterScope, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type UrlInlineExpansionRule, getActionAnnotation, isSensitiveField };
+export { ACTION_FIELD_MARKER, type AppInfo, type AuthContext, type AuthDriver, type AuthProfile, type AuthRegistry, type AuthVerifyResult, type CacheEntry, type CacheKey, type CacheStorage, type CodeBlockInfo, type CodeBlockRenderer, type CrowiPlugin, type EmailMessage, type EmbedFragment, type EmbedInput, type EmbedRenderer, type EventBus, type InlineExpansion, type MailSender, type MailSenderRegistry, type NodeRenderer, type NotificationPayload, type NotifierDriver, type NotifierRegistry, type PageMetadataAccessor, type PluginContext, type PluginCrypto, type PluginEvents, type PluginLogger, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, type PluginRouterScope, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type UrlInlineExpansionRule, getActionAnnotation, isSensitiveField };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/schema-markers.ts"],"sourcesContent":["/**\n * @crowi/plugin-api — type-only contract for Crowi 2.0 plugins.\n *\n * Plugins author against this package. The runtime (@crowi/server) loads\n * plugins listed in `crowi.config.json`, calls each plugin's\n * `register*` callbacks, and routes all the side effects (storage,\n * search, auth, notifications) through the typed registries declared\n * here.\n *\n * For the design rationale see `docs/rfcs/0001-plugin-architecture.md`\n * in the Crowi monorepo.\n */\n\nexport type { CrowiPlugin } from './plugin';\n\nexport type { PluginContext, PageMetadataAccessor, PluginCrypto, PluginLogger } from './context';\n\nexport type { StorageDriver, StorageRegistry, StoragePutMeta, StoragePutResult } from './registries/storage';\n\nexport type {\n  SearchDriver,\n  SearchRegistry,\n  SearchableDoc,\n  SearchQuery,\n  SearchQueryViewer,\n  SearchQueryGrants,\n  SearchPageType,\n  SearchHits,\n  SearchHit,\n} from './registries/search';\n\nexport type { AuthDriver, AuthRegistry, AuthProfile, AuthVerifyResult } from './registries/auth';\n\nexport type { NotifierDriver, NotifierRegistry, NotificationPayload } from './registries/notifier';\n\nexport type { MailSender, MailSenderRegistry, EmailMessage } from './registries/mail';\n\nexport type {\n  RendererRegistry,\n  NodeRenderer,\n  CodeBlockRenderer,\n  CodeBlockInfo,\n  EmbedRenderer,\n  EmbedInput,\n  EmbedFragment,\n  UrlInlineExpansionRule,\n  InlineExpansion,\n  RenderContext,\n  RenderPhase,\n  RenderResult,\n  RenderError,\n  Reservation,\n  CacheStorage,\n  ScopedCacheStorage,\n  CacheKey,\n  CacheEntry,\n  AuthContext,\n} from './renderer';\n\nexport type { EventBus, PluginEvents } from './events';\n\nexport type { PluginRouterScope } from './routes';\n\nexport { SENSITIVE_FIELD_MARKER, ACTION_FIELD_MARKER, isSensitiveField, getActionAnnotation } from './schema-markers';\n","import type { z } from 'zod/v3';\n\n/**\n * `configSchema` description-string markers.\n *\n * The admin UI walks the schema and looks at each field's\n * `description` (set via `z.string().describe('@sensitive ...')`). A\n * description starting with one of these marker tokens unlocks special\n * UI behaviour without forcing every field to declare a custom Zod\n * type.\n */\n\n/**\n * Marker that flags a config field as sensitive (encrypted at rest).\n * Usage:\n *\n *   z.string().describe('@sensitive AWS secret access key')\n *\n * The runtime auto-encrypts on write and decrypts on read, using the\n * same KeyProvider as core sensitive Config. The admin UI renders the\n * field via `<SecretField>` (saved badge / clear pending / undo).\n */\nexport const SENSITIVE_FIELD_MARKER = '@sensitive';\n\n/**\n * Marker that adds an action button next to a config field. Usage:\n *\n *   z.string().describe('@action \"Test connection\" POST /test')\n *\n * The admin form renders a button with the given label that calls the\n * plugin's contributed endpoint at the given verb / path (relative to\n * `/api/v2/plugins/<name>/`). Useful for \"Test connection\",\n * \"Authorise with Google\", etc. without forcing every plugin to ship\n * its own React component.\n */\nexport const ACTION_FIELD_MARKER = '@action';\n\n/**\n * True if the schema field is marked `@sensitive`.\n *\n * `field` is `z.ZodTypeAny` (intentionally loose); call sites pass the\n * value type from `configSchema.shape[key]`.\n */\nexport function isSensitiveField(field: z.ZodTypeAny): boolean {\n  const description = field.description;\n  return typeof description === 'string' && description.trimStart().startsWith(SENSITIVE_FIELD_MARKER);\n}\n\n/**\n * Parsed `@action` annotation extracted from a field's `description`.\n */\nexport interface ActionAnnotation {\n  /** Visible button label, e.g. \"Test connection\". */\n  label: string;\n  /** HTTP verb of the plugin endpoint to call. */\n  method: 'GET' | 'POST' | 'PUT' | 'DELETE';\n  /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */\n  path: string;\n}\n\n/**\n * Parse an `@action` annotation off a field, or return null if absent.\n *\n * Format: `@action \"<label>\" <METHOD> <path>`\n *   e.g. `@action \"Test connection\" POST /test`\n *\n * The label may include spaces when wrapped in double quotes; the\n * method is one of `GET` / `POST` / `PUT` / `DELETE`; the path begins\n * with `/`.\n */\nexport function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null {\n  const description = field.description;\n  if (typeof description !== 'string') return null;\n  const trimmed = description.trimStart();\n  if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;\n\n  const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();\n  // `\"<label>\" <METHOD> <path>`\n  const match = rest.match(/^\"([^\"]+)\"\\s+(GET|POST|PUT|DELETE)\\s+(\\/\\S*)/);\n  if (!match) return null;\n\n  const [, label, method, path] = match;\n  return { label, method: method as ActionAnnotation['method'], path };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACsBO,IAAM,yBAAyB;AAa/B,IAAM,sBAAsB;AAQ5B,SAAS,iBAAiB,OAA8B;AAC7D,QAAM,cAAc,MAAM;AAC1B,SAAO,OAAO,gBAAgB,YAAY,YAAY,UAAU,EAAE,WAAW,sBAAsB;AACrG;AAwBO,SAAS,oBAAoB,OAA8C;AAChF,QAAM,cAAc,MAAM;AAC1B,MAAI,OAAO,gBAAgB,SAAU,QAAO;AAC5C,QAAM,UAAU,YAAY,UAAU;AACtC,MAAI,CAAC,QAAQ,WAAW,mBAAmB,EAAG,QAAO;AAErD,QAAM,OAAO,QAAQ,MAAM,oBAAoB,MAAM,EAAE,UAAU;AAEjE,QAAM,QAAQ,KAAK,MAAM,8CAA8C;AACvE,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,CAAC,EAAE,OAAO,QAAQ,IAAI,IAAI;AAChC,SAAO,EAAE,OAAO,QAA8C,KAAK;AACrE;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/schema-markers.ts"],"sourcesContent":["/**\n * @crowi/plugin-api — type-only contract for Crowi 2.0 plugins.\n *\n * Plugins author against this package. The runtime (@crowi/server) loads\n * plugins listed in `crowi.config.json`, calls each plugin's\n * `register*` callbacks, and routes all the side effects (storage,\n * search, auth, notifications) through the typed registries declared\n * here.\n *\n * For the design rationale see `docs/rfcs/0001-plugin-architecture.md`\n * in the Crowi monorepo.\n */\n\nexport type { CrowiPlugin } from './plugin';\n\nexport type { PluginContext, AppInfo, PageMetadataAccessor, PluginCrypto, PluginLogger } from './context';\n\nexport type { StorageDriver, StorageRegistry, StoragePutMeta, StoragePutResult } from './registries/storage';\n\nexport type {\n  SearchDriver,\n  SearchRegistry,\n  SearchableDoc,\n  SearchQuery,\n  SearchQueryViewer,\n  SearchQueryGrants,\n  SearchPageType,\n  SearchHits,\n  SearchHit,\n} from './registries/search';\n\nexport type { AuthDriver, AuthRegistry, AuthProfile, AuthVerifyResult } from './registries/auth';\n\nexport type { NotifierDriver, NotifierRegistry, NotificationPayload } from './registries/notifier';\n\nexport type { MailSender, MailSenderRegistry, EmailMessage } from './registries/mail';\n\nexport type {\n  RendererRegistry,\n  NodeRenderer,\n  CodeBlockRenderer,\n  CodeBlockInfo,\n  EmbedRenderer,\n  EmbedInput,\n  EmbedFragment,\n  UrlInlineExpansionRule,\n  InlineExpansion,\n  RenderContext,\n  RenderPhase,\n  RenderResult,\n  RenderError,\n  Reservation,\n  CacheStorage,\n  ScopedCacheStorage,\n  CacheKey,\n  CacheEntry,\n  AuthContext,\n} from './renderer';\n\nexport type { EventBus, PluginEvents } from './events';\n\nexport type { PluginRouterScope, PluginRouteHandler, PluginRouteMethod, PluginRouteOptions } from './routes';\n\nexport { SENSITIVE_FIELD_MARKER, ACTION_FIELD_MARKER, isSensitiveField, getActionAnnotation } from './schema-markers';\n","import type { z } from 'zod/v3';\n\n/**\n * `configSchema` description-string markers.\n *\n * The admin UI walks the schema and looks at each field's\n * `description` (set via `z.string().describe('@sensitive ...')`). A\n * description starting with one of these marker tokens unlocks special\n * UI behaviour without forcing every field to declare a custom Zod\n * type.\n */\n\n/**\n * Marker that flags a config field as sensitive (encrypted at rest).\n * Usage:\n *\n *   z.string().describe('@sensitive AWS secret access key')\n *\n * The runtime auto-encrypts on write and decrypts on read, using the\n * same KeyProvider as core sensitive Config. The admin UI renders the\n * field via `<SecretField>` (saved badge / clear pending / undo).\n */\nexport const SENSITIVE_FIELD_MARKER = '@sensitive';\n\n/**\n * Marker that adds an action button next to a config field. Usage:\n *\n *   z.string().describe('@action \"Test connection\" POST /test')\n *\n * The admin form renders a button with the given label that calls the\n * plugin's contributed endpoint at the given verb / path (relative to\n * `/api/v2/plugins/<name>/`). Useful for \"Test connection\",\n * \"Authorise with Google\", etc. without forcing every plugin to ship\n * its own React component.\n */\nexport const ACTION_FIELD_MARKER = '@action';\n\n/**\n * True if the schema field is marked `@sensitive`.\n *\n * `field` is `z.ZodTypeAny` (intentionally loose); call sites pass the\n * value type from `configSchema.shape[key]`.\n */\nexport function isSensitiveField(field: z.ZodTypeAny): boolean {\n  const description = field.description;\n  return typeof description === 'string' && description.trimStart().startsWith(SENSITIVE_FIELD_MARKER);\n}\n\n/**\n * Parsed `@action` annotation extracted from a field's `description`.\n */\nexport interface ActionAnnotation {\n  /** Visible button label, e.g. \"Test connection\". */\n  label: string;\n  /** HTTP verb of the plugin endpoint to call. */\n  method: 'GET' | 'POST' | 'PUT' | 'DELETE';\n  /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */\n  path: string;\n}\n\n/**\n * Parse an `@action` annotation off a field, or return null if absent.\n *\n * Format: `@action \"<label>\" <METHOD> <path>`\n *   e.g. `@action \"Test connection\" POST /test`\n *\n * The label may include spaces when wrapped in double quotes; the\n * method is one of `GET` / `POST` / `PUT` / `DELETE`; the path begins\n * with `/`.\n */\nexport function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null {\n  const description = field.description;\n  if (typeof description !== 'string') return null;\n  const trimmed = description.trimStart();\n  if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;\n\n  const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();\n  // `\"<label>\" <METHOD> <path>`\n  const match = rest.match(/^\"([^\"]+)\"\\s+(GET|POST|PUT|DELETE)\\s+(\\/\\S*)/);\n  if (!match) return null;\n\n  const [, label, method, path] = match;\n  return { label, method: method as ActionAnnotation['method'], path };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACsBO,IAAM,yBAAyB;AAa/B,IAAM,sBAAsB;AAQ5B,SAAS,iBAAiB,OAA8B;AAC7D,QAAM,cAAc,MAAM;AAC1B,SAAO,OAAO,gBAAgB,YAAY,YAAY,UAAU,EAAE,WAAW,sBAAsB;AACrG;AAwBO,SAAS,oBAAoB,OAA8C;AAChF,QAAM,cAAc,MAAM;AAC1B,MAAI,OAAO,gBAAgB,SAAU,QAAO;AAC5C,QAAM,UAAU,YAAY,UAAU;AACtC,MAAI,CAAC,QAAQ,WAAW,mBAAmB,EAAG,QAAO;AAErD,QAAM,OAAO,QAAQ,MAAM,oBAAoB,MAAM,EAAE,UAAU;AAEjE,QAAM,QAAQ,KAAK,MAAM,8CAA8C;AACvE,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,CAAC,EAAE,OAAO,QAAQ,IAAI,IAAI;AAChC,SAAO,EAAE,OAAO,QAA8C,KAAK;AACrE;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowi/plugin-api",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "Type-only contract for Crowi 2.0 plugins. See docs/rfcs/0001-plugin-architecture.md.",
   "repository": {
     "type": "git",
@@ -25,10 +25,12 @@
     "access": "public"
   },
   "peerDependencies": {
+    "hono": "^4.12.25",
     "zod": "^4"
   },
   "devDependencies": {
     "@types/node": "^24",
+    "hono": "^4.12.25",
     "tsup": "^8.3.5",
     "typescript": "^5.8.3",
     "zod": "^4.4.3",