@crowi/plugin-api 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,55 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ACTION_FIELD_MARKER: () => ACTION_FIELD_MARKER,
+  SENSITIVE_FIELD_MARKER: () => SENSITIVE_FIELD_MARKER,
+  getActionAnnotation: () => getActionAnnotation,
+  isSensitiveField: () => isSensitiveField
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/schema-markers.ts
+var SENSITIVE_FIELD_MARKER = "@sensitive";
+var ACTION_FIELD_MARKER = "@action";
+function isSensitiveField(field) {
+  const description = field.description;
+  return typeof description === "string" && description.trimStart().startsWith(SENSITIVE_FIELD_MARKER);
+}
+function getActionAnnotation(field) {
+  const description = field.description;
+  if (typeof description !== "string") return null;
+  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*)/);
+  if (!match) return null;
+  const [, label, method, path] = match;
+  return { label, method, path };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ACTION_FIELD_MARKER,
+  SENSITIVE_FIELD_MARKER,
+  getActionAnnotation,
+  isSensitiveField
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/dist/index.mjs

@@ -0,0 +1,25 @@
+// src/schema-markers.ts
+var SENSITIVE_FIELD_MARKER = "@sensitive";
+var ACTION_FIELD_MARKER = "@action";
+function isSensitiveField(field) {
+  const description = field.description;
+  return typeof description === "string" && description.trimStart().startsWith(SENSITIVE_FIELD_MARKER);
+}
+function getActionAnnotation(field) {
+  const description = field.description;
+  if (typeof description !== "string") return null;
+  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*)/);
+  if (!match) return null;
+  const [, label, method, path] = match;
+  return { label, method, path };
+}
+export {
+  ACTION_FIELD_MARKER,
+  SENSITIVE_FIELD_MARKER,
+  getActionAnnotation,
+  isSensitiveField
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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":[]}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@crowi/plugin-api",
+  "version": "0.1.0-alpha.0",
+  "description": "Type-only contract for Crowi 2.0 plugins. See docs/rfcs/0001-plugin-architecture.md.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "tsup": "^8.3.5",
+    "typescript": "^5.8.3",
+    "zod": "^4.4.3",
+    "@crowi/tsconfig": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch --no-clean",
+    "type-check": "tsc --noEmit"
+  }
+}