@crowi/plugin-api 1.0.0-alpha.5 → 1.0.0-alpha.6

package/dist/index.d.mts

@@ -1323,6 +1323,32 @@ interface PluginRouterScope {
     route(method: PluginRouteMethod, path: string, handler: PluginRouteHandler, opts?: PluginRouteOptions): void;
 }
 
+/**
+ * Declares that, when a specific driver from a specific registry is
+ * selected (`crowi.config.json:<registry>.driver === driver`), this
+ * plugin's own config becomes required to actually work at runtime —
+ * even though the `configSchema` field itself is optional / defaults to
+ * `''` so `configSchema.parse()` alone can't detect "present but
+ * unusable" (see `@crowi/plugin-storage-aws-s3`'s `bucket` and
+ * `@crowi/plugin-search-elasticsearch` / `@crowi/plugin-search-opensearch`'s
+ * `url`, both `z.string().default('')`).
+ *
+ * This is metadata only — it never carries an actual config value.
+ * `registry` / `driver` / every name in `requiredConfigFields` must be
+ * non-empty. The runtime (`PluginManager.getReadinessIssues()`) reads
+ * this once per admin readiness check, cross-references it against the
+ * currently selected driver and the plugin's current config namespace,
+ * and reports which declared fields are still empty — never the values
+ * themselves. See RFC-none / feature-plugin-config-readiness.
+ */
+interface PluginReadinessDeclaration {
+    /** Which driver registry this declaration is scoped to. */
+    registry: 'storage' | 'search' | 'mail';
+    /** The driver name (as registered via `registry.register(name, …)`) this declaration applies to. */
+    driver: string;
+    /** `configSchema` field names that must be non-empty for `driver` to actually work once selected. */
+    requiredConfigFields: string[];
+}
 /**
  * The contract every Crowi plugin satisfies. Plugins export their
  * `CrowiPlugin` object as the package's default export; the runtime
@@ -1457,6 +1483,14 @@ interface CrowiPlugin {
         label?: string;
         description?: string;
     }>>;
+    /**
+     * Declares which of this plugin's own `configSchema` fields must be
+     * non-empty for a specific driver selection to actually work at
+     * runtime (see {@link PluginReadinessDeclaration}). Optional — a
+     * plugin with no readiness declaration is never surfaced by the
+     * admin readiness check, same as before this field existed.
+     */
+    readiness?: PluginReadinessDeclaration;
     /** Storage driver registration. Called once at boot. */
     registerStorage?: (registry: StorageRegistry, ctx: PluginContext) => void;
     /** Search backend registration. Called once at boot. */
@@ -1729,4 +1763,4 @@ type SanitizeSvgResult = {
  */
 declare function sanitizeSvg(input: string, policy: SanitizeSvgPolicy): SanitizeSvgResult;
 
-export { ACTION_FIELD_MARKER, type AdmissionControlConfig, 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 PluginEvents, type PluginLogger, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, type PluginRouterScope, type RenderActor, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type SanitizeSvgPolicy, type SanitizeSvgResult, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StateCell, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type StructuredRenderPayload, type UrlInlineExpansionRule, escapeHtml, extractSvgDimensions, getActionAnnotation, isSensitiveField, sanitizeSvg };
+export { ACTION_FIELD_MARKER, type AdmissionControlConfig, 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 PluginEvents, type PluginLogger, type PluginReadinessDeclaration, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, type PluginRouterScope, type RenderActor, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type SanitizeSvgPolicy, type SanitizeSvgResult, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StateCell, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type StructuredRenderPayload, type UrlInlineExpansionRule, escapeHtml, extractSvgDimensions, getActionAnnotation, isSensitiveField, sanitizeSvg };

package/dist/index.d.ts

@@ -1323,6 +1323,32 @@ interface PluginRouterScope {
     route(method: PluginRouteMethod, path: string, handler: PluginRouteHandler, opts?: PluginRouteOptions): void;
 }
 
+/**
+ * Declares that, when a specific driver from a specific registry is
+ * selected (`crowi.config.json:<registry>.driver === driver`), this
+ * plugin's own config becomes required to actually work at runtime —
+ * even though the `configSchema` field itself is optional / defaults to
+ * `''` so `configSchema.parse()` alone can't detect "present but
+ * unusable" (see `@crowi/plugin-storage-aws-s3`'s `bucket` and
+ * `@crowi/plugin-search-elasticsearch` / `@crowi/plugin-search-opensearch`'s
+ * `url`, both `z.string().default('')`).
+ *
+ * This is metadata only — it never carries an actual config value.
+ * `registry` / `driver` / every name in `requiredConfigFields` must be
+ * non-empty. The runtime (`PluginManager.getReadinessIssues()`) reads
+ * this once per admin readiness check, cross-references it against the
+ * currently selected driver and the plugin's current config namespace,
+ * and reports which declared fields are still empty — never the values
+ * themselves. See RFC-none / feature-plugin-config-readiness.
+ */
+interface PluginReadinessDeclaration {
+    /** Which driver registry this declaration is scoped to. */
+    registry: 'storage' | 'search' | 'mail';
+    /** The driver name (as registered via `registry.register(name, …)`) this declaration applies to. */
+    driver: string;
+    /** `configSchema` field names that must be non-empty for `driver` to actually work once selected. */
+    requiredConfigFields: string[];
+}
 /**
  * The contract every Crowi plugin satisfies. Plugins export their
  * `CrowiPlugin` object as the package's default export; the runtime
@@ -1457,6 +1483,14 @@ interface CrowiPlugin {
         label?: string;
         description?: string;
     }>>;
+    /**
+     * Declares which of this plugin's own `configSchema` fields must be
+     * non-empty for a specific driver selection to actually work at
+     * runtime (see {@link PluginReadinessDeclaration}). Optional — a
+     * plugin with no readiness declaration is never surfaced by the
+     * admin readiness check, same as before this field existed.
+     */
+    readiness?: PluginReadinessDeclaration;
     /** Storage driver registration. Called once at boot. */
     registerStorage?: (registry: StorageRegistry, ctx: PluginContext) => void;
     /** Search backend registration. Called once at boot. */
@@ -1729,4 +1763,4 @@ type SanitizeSvgResult = {
  */
 declare function sanitizeSvg(input: string, policy: SanitizeSvgPolicy): SanitizeSvgResult;
 
-export { ACTION_FIELD_MARKER, type AdmissionControlConfig, 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 PluginEvents, type PluginLogger, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, type PluginRouterScope, type RenderActor, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type SanitizeSvgPolicy, type SanitizeSvgResult, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StateCell, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type StructuredRenderPayload, type UrlInlineExpansionRule, escapeHtml, extractSvgDimensions, getActionAnnotation, isSensitiveField, sanitizeSvg };
+export { ACTION_FIELD_MARKER, type AdmissionControlConfig, 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 PluginEvents, type PluginLogger, type PluginReadinessDeclaration, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, type PluginRouterScope, type RenderActor, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type SanitizeSvgPolicy, type SanitizeSvgResult, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StateCell, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type StructuredRenderPayload, type UrlInlineExpansionRule, escapeHtml, extractSvgDimensions, getActionAnnotation, isSensitiveField, sanitizeSvg };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowi/plugin-api",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.6",
   "description": "Type-only contract for Crowi 2.0 plugins. See docs/rfcs/0001-plugin-architecture.md.",
   "repository": {
     "type": "git",
@@ -25,13 +25,13 @@
     "access": "public"
   },
   "peerDependencies": {
-    "hono": "^4.12.25",
+    "hono": "^4.12.34",
     "zod": "^4"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",
     "@types/node": "^24",
-    "hono": "^4.12.31",
+    "hono": "^4.12.34",
     "jest": "^29.7.0",
     "ts-jest": "^29.3.4",
     "tsup": "^8.3.5",