@crowi/plugin-api 0.1.0-alpha.2 → 1.0.0-alpha.4

package/dist/index.js

@@ -22,11 +22,32 @@ var index_exports = {};
 __export(index_exports, {
   ACTION_FIELD_MARKER: () => ACTION_FIELD_MARKER,
   SENSITIVE_FIELD_MARKER: () => SENSITIVE_FIELD_MARKER,
+  escapeHtml: () => escapeHtml,
   getActionAnnotation: () => getActionAnnotation,
   isSensitiveField: () => isSensitiveField
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/html.ts
+function escapeHtml(s) {
+  return s.replace(/[&<>"']/g, (c) => {
+    switch (c) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case '"':
+        return "&quot;";
+      case "'":
+        return "&#39;";
+      default:
+        return c;
+    }
+  });
+}
+
 // src/schema-markers.ts
 var SENSITIVE_FIELD_MARKER = "@sensitive";
 var ACTION_FIELD_MARKER = "@action";
@@ -40,7 +61,7 @@ function getActionAnnotation(field) {
   const trimmed = description.trimStart();
   if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;
   const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();
-  const match = rest.match(/^"([^"]+)"\s+(GET|POST|PUT|DELETE)\s+(\/\S*)/);
+  const match = rest.match(/^"([^"]+)"\s+(GET|POST)\s+(\/\S*)/);
   if (!match) return null;
   const [, label, method, path] = match;
   return { label, method, path };
@@ -49,6 +70,7 @@ function getActionAnnotation(field) {
 0 && (module.exports = {
   ACTION_FIELD_MARKER,
   SENSITIVE_FIELD_MARKER,
+  escapeHtml,
   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, 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":[]}
+{"version":3,"sources":["../src/index.ts","../src/html.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 { AppInfo, PageMetadataAccessor, PluginContext, PluginLogger, StateCell } from './context';\nexport type { EventBus, PluginEvents } from './events';\nexport { escapeHtml } from './html';\nexport type { CrowiPlugin } from './plugin';\n\nexport type { AuthDriver, AuthProfile, AuthRegistry, AuthVerifyResult } from './registries/auth';\nexport type { EmailMessage, MailSender, MailSenderRegistry } from './registries/mail';\nexport type { NotificationPayload, NotifierDriver, NotifierRegistry } from './registries/notifier';\nexport type {\n  SearchableDoc,\n  SearchDriver,\n  SearchHit,\n  SearchHits,\n  SearchPageType,\n  SearchQuery,\n  SearchQueryGrants,\n  SearchQueryViewer,\n  SearchRegistry,\n} from './registries/search';\nexport type { StorageDriver, StoragePutMeta, StoragePutResult, StorageRegistry } from './registries/storage';\nexport type {\n  AdmissionControlConfig,\n  AuthContext,\n  CacheEntry,\n  CacheKey,\n  CacheStorage,\n  CodeBlockInfo,\n  CodeBlockRenderer,\n  EmbedFragment,\n  EmbedInput,\n  EmbedRenderer,\n  InlineExpansion,\n  NodeRenderer,\n  RenderActor,\n  RenderContext,\n  RenderError,\n  RendererRegistry,\n  RenderPhase,\n  RenderResult,\n  Reservation,\n  ScopedCacheStorage,\n  UrlInlineExpansionRule,\n} from './renderer';\nexport type { PluginRouteHandler, PluginRouteMethod, PluginRouteOptions, PluginRouterScope } from './routes';\nexport { ACTION_FIELD_MARKER, getActionAnnotation, isSensitiveField, SENSITIVE_FIELD_MARKER } from './schema-markers';\n","/**\n * HTML-emitting helper for renderer plugins.\n *\n * A renderer plugin that builds HTML from author-controlled or external\n * strings (an OGP title, a math error message, …) must escape them, and\n * that escape is a security primitive — a hardening change has to reach\n * every plugin at once, not whichever local copies someone remembers.\n * This is the SDK's single copy (`@crowi/plugin-renderer-katex` and\n * `@crowi/plugin-renderer-link-card` each carried an identical local one\n * before it was hoisted here).\n */\n\n/** Escape `&` `<` `>` `\"` `'` for interpolation into HTML text or double/single-quoted attribute values. */\nexport function escapeHtml(s: string): string {\n  return s.replace(/[&<>\"']/g, (c) => {\n    switch (c) {\n      case '&':\n        return '&amp;';\n      case '<':\n        return '&lt;';\n      case '>':\n        return '&gt;';\n      case '\"':\n        return '&quot;';\n      case \"'\":\n        return '&#39;';\n      default:\n        return c;\n    }\n  });\n}\n","import type { z } from 'zod/v3';\n\nimport type { PluginRouteMethod } from './routes';\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: PluginRouteMethod;\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 method\n * must be one of `PluginRouteMethod` (`GET` / `POST` — the only verbs a\n * plugin route can actually be mounted on, see `routes.ts`); the path\n * begins with `/`. A description that starts with the `@action` marker\n * but declares an unsupported verb (e.g. `PUT` / `DELETE`) fails to match\n * and returns `null` here — callers that walk a plugin's `configSchema`\n * (e.g. `PluginManager.activate()`) are expected to warn on that case at\n * boot, since it would otherwise be a silent dead button.\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)\\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;AAAA;;;ACaO,SAAS,WAAW,GAAmB;AAC5C,SAAO,EAAE,QAAQ,YAAY,CAAC,MAAM;AAClC,YAAQ,GAAG;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT;AACE,eAAO;AAAA,IACX;AAAA,EACF,CAAC;AACH;;;ACNO,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;AA6BO,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,mCAAmC;AAC5D,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,CAAC,EAAE,OAAO,QAAQ,IAAI,IAAI;AAChC,SAAO,EAAE,OAAO,QAA8C,KAAK;AACrE;","names":[]}

package/dist/index.mjs

@@ -1,3 +1,23 @@
+// src/html.ts
+function escapeHtml(s) {
+  return s.replace(/[&<>"']/g, (c) => {
+    switch (c) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case '"':
+        return "&quot;";
+      case "'":
+        return "&#39;";
+      default:
+        return c;
+    }
+  });
+}
+
 // src/schema-markers.ts
 var SENSITIVE_FIELD_MARKER = "@sensitive";
 var ACTION_FIELD_MARKER = "@action";
@@ -11,7 +31,7 @@ function getActionAnnotation(field) {
   const trimmed = description.trimStart();
   if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;
   const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();
-  const match = rest.match(/^"([^"]+)"\s+(GET|POST|PUT|DELETE)\s+(\/\S*)/);
+  const match = rest.match(/^"([^"]+)"\s+(GET|POST)\s+(\/\S*)/);
   if (!match) return null;
   const [, label, method, path] = match;
   return { label, method, path };
@@ -19,6 +39,7 @@ function getActionAnnotation(field) {
 export {
   ACTION_FIELD_MARKER,
   SENSITIVE_FIELD_MARKER,
+  escapeHtml,
   getActionAnnotation,
   isSensitiveField
 };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/schema-markers.ts"],"sourcesContent":["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":";AAsBO,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/html.ts","../src/schema-markers.ts"],"sourcesContent":["/**\n * HTML-emitting helper for renderer plugins.\n *\n * A renderer plugin that builds HTML from author-controlled or external\n * strings (an OGP title, a math error message, …) must escape them, and\n * that escape is a security primitive — a hardening change has to reach\n * every plugin at once, not whichever local copies someone remembers.\n * This is the SDK's single copy (`@crowi/plugin-renderer-katex` and\n * `@crowi/plugin-renderer-link-card` each carried an identical local one\n * before it was hoisted here).\n */\n\n/** Escape `&` `<` `>` `\"` `'` for interpolation into HTML text or double/single-quoted attribute values. */\nexport function escapeHtml(s: string): string {\n  return s.replace(/[&<>\"']/g, (c) => {\n    switch (c) {\n      case '&':\n        return '&amp;';\n      case '<':\n        return '&lt;';\n      case '>':\n        return '&gt;';\n      case '\"':\n        return '&quot;';\n      case \"'\":\n        return '&#39;';\n      default:\n        return c;\n    }\n  });\n}\n","import type { z } from 'zod/v3';\n\nimport type { PluginRouteMethod } from './routes';\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: PluginRouteMethod;\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 method\n * must be one of `PluginRouteMethod` (`GET` / `POST` — the only verbs a\n * plugin route can actually be mounted on, see `routes.ts`); the path\n * begins with `/`. A description that starts with the `@action` marker\n * but declares an unsupported verb (e.g. `PUT` / `DELETE`) fails to match\n * and returns `null` here — callers that walk a plugin's `configSchema`\n * (e.g. `PluginManager.activate()`) are expected to warn on that case at\n * boot, since it would otherwise be a silent dead button.\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)\\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":";AAaO,SAAS,WAAW,GAAmB;AAC5C,SAAO,EAAE,QAAQ,YAAY,CAAC,MAAM;AAClC,YAAQ,GAAG;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT;AACE,eAAO;AAAA,IACX;AAAA,EACF,CAAC;AACH;;;ACNO,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;AA6BO,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,mCAAmC;AAC5D,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.2",
+  "version": "1.0.0-alpha.4",
   "description": "Type-only contract for Crowi 2.0 plugins. See docs/rfcs/0001-plugin-architecture.md.",
   "repository": {
     "type": "git",
@@ -29,8 +29,11 @@
     "zod": "^4"
   },
   "devDependencies": {
+    "@types/jest": "^29.5.14",
     "@types/node": "^24",
-    "hono": "^4.12.25",
+    "hono": "^4.12.31",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.3.4",
     "tsup": "^8.3.5",
     "typescript": "^5.8.3",
     "zod": "^4.4.3",
@@ -39,6 +42,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch --no-clean",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "test": "jest --passWithNoTests"
   }
 }