@smartdoca/plugin-contracts 0.1.0

package/dist/LICENSING.md

@@ -0,0 +1,57 @@
+# Licensing
+
+[简体中文](LICENSING.zh-CN.md)
+
+Doca uses a dual-licensing model for code owned by the Doca copyright holders.
+
+## Open-source license
+
+Unless a file or package says otherwise, Doca-owned code in this repository is
+available under the GNU Affero General Public License version 3 only
+(`AGPL-3.0-only`). The full license text is in [LICENSE](LICENSE).
+
+The AGPL permits commercial use. When its conditions apply, it requires the
+corresponding source to remain available under the AGPL, including for modified
+versions offered to users over a network. “Open source” and “free of charge” are
+not the same thing, and the AGPL obligations do not depend on whether an operator
+charges money.
+
+## Commercial license
+
+Organizations that want to use Doca-owned code in a proprietary product without
+the AGPL obligations may obtain a separate commercial license from the Doca
+copyright holders. A commercial license exists only when both parties have
+entered into a written agreement. This repository does not itself grant that
+alternative license.
+
+## Packages and editors
+
+The same licensing direction applies to Doca-owned packages and editors,
+including the Doca plugin SDK and the Slate, presentation, spreadsheet,
+Markdown, and canvas editor packages. Each released npm artifact must:
+
+- carry an accurate license field and license notice;
+- link to the public source repository and the exact source tag for that version;
+- include the build scripts and dependency lock needed to produce the artifact;
+- preserve all notices and license obligations of third-party components.
+
+The historical archives under `vendor/` are development and recovery inputs.
+They are not the long-term public distribution channel. Before the public
+release, active editor dependencies must be rebuilt from their public tagged
+sources, published to npm, and consumed by Doca through registry versions.
+
+## Third-party software and assets
+
+The dual license covers only material for which the Doca copyright holders can
+grant these rights. Third-party libraries, fonts, media, generated artifacts,
+and other bundled material retain their own licenses. Their notices and source
+or attribution requirements must be followed independently.
+
+No trademark rights are granted by either the AGPL or this licensing summary.
+
+## Contributions
+
+Dual licensing requires the project to retain the rights needed to offer future
+commercial licenses. See [CONTRIBUTING.md](CONTRIBUTING.md) before submitting
+code. This document is a project policy summary, not a substitute for the
+license text or legal advice.

package/dist/LICENSING.zh-CN.md

@@ -0,0 +1,48 @@
+# 许可说明
+
+[English](LICENSING.md)
+
+Doca 对其版权所有者拥有权利的代码采用双许可模式。
+
+## 开源许可证
+
+除非文件或包中另有说明，本仓库内由 Doca 版权所有者拥有的代码默认采用
+GNU Affero General Public License version 3 only（`AGPL-3.0-only`）。完整条款见
+[LICENSE](LICENSE)。
+
+AGPL 允许商业使用。当其条件适用时，分发软件或将修改后的版本作为网络服务提供给
+用户，需要继续按 AGPL 提供对应源码。是否收费并不是 AGPL 义务的判断条件，“开源”
+也不等于“免费”。
+
+## 商业许可证
+
+希望在闭源产品中使用 Doca 自研代码、且不希望承担 AGPL 义务的组织，可以向 Doca
+版权所有者申请单独的商业许可证。只有双方签署书面协议后，商业许可证才成立；本仓库
+本身不授予该替代许可证。
+
+## 子包与编辑器
+
+同一许可方向适用于 Doca 自研的子包和编辑器，包括插件 SDK，以及 Slate 富文本、
+演示文稿、表格、Markdown 和画板编辑器。每个正式发布的 npm 制品必须：
+
+- 使用准确的许可证字段并携带许可证说明；
+- 链接公开源码仓库以及与该版本精确对应的 Git tag；
+- 提供生成该制品所需的构建脚本和依赖锁文件；
+- 保留所有第三方组件要求的许可证及声明。
+
+`vendor/` 中的历史压缩包是开发和恢复输入，不作为长期公开分发渠道。正式开源前，
+当前使用的编辑器依赖应从公开且已打 tag 的源码重新构建并发布到 npm，Doca 再改为
+使用 registry 版本。
+
+## 第三方软件与素材
+
+双许可只覆盖 Doca 版权所有者有权授予许可的内容。第三方库、字体、媒体、生成产物及
+其他随附内容继续适用各自许可证，其声明、源码提供或署名要求需要独立履行。
+
+AGPL 和本文均不授予商标使用权。
+
+## 外部贡献
+
+双许可要求项目持续保有提供商业许可证所需的权利。提交代码前请阅读
+[CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)。本文只是项目政策摘要，不能替代
+许可证原文或专业法律意见。

package/dist/index.d.ts

@@ -0,0 +1,167 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+export type PluginRuntimePhase = "discover" | "initialize" | "mount" | "ready" | "dispose";
+export type PluginRuntimeErrorCode = "INVALID_MANIFEST" | "INVALID_CONFIG" | "DUPLICATE_PLUGIN" | "MISSING_DEPENDENCY" | "INCOMPATIBLE_DEPENDENCY" | "DEPENDENCY_CYCLE" | "MISSING_INJECTION" | "DUPLICATE_PROVIDER" | "CONTRIBUTION_COLLISION" | "CONTEXT_DISPOSED" | "LIFECYCLE_FAILED";
+export declare class PluginContractError extends Error {
+    readonly code: PluginRuntimeErrorCode;
+    readonly path: string;
+    readonly name = "PluginContractError";
+    constructor(code: PluginRuntimeErrorCode, message: string, path?: string);
+}
+export interface StringConfigSchema {
+    readonly type: "string";
+    readonly description?: string;
+    readonly default?: string;
+    readonly enum?: readonly string[];
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+}
+export interface NumberConfigSchema {
+    readonly type: "number" | "integer";
+    readonly description?: string;
+    readonly default?: number;
+    readonly minimum?: number;
+    readonly maximum?: number;
+}
+export interface BooleanConfigSchema {
+    readonly type: "boolean";
+    readonly description?: string;
+    readonly default?: boolean;
+}
+export interface NullConfigSchema {
+    readonly type: "null";
+    readonly description?: string;
+    readonly default?: null;
+}
+export interface ArrayConfigSchema {
+    readonly type: "array";
+    readonly description?: string;
+    readonly default?: readonly JsonValue[];
+    readonly items: DocaConfigSchema;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+}
+export interface ObjectConfigSchema {
+    readonly type: "object";
+    readonly description?: string;
+    readonly default?: JsonObject;
+    readonly properties?: Readonly<Record<string, DocaConfigSchema>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean;
+}
+/**
+ * The deliberately small configuration schema understood by the Doca runtime.
+ * It is not JSON Schema; unsupported keywords are rejected.
+ */
+export type DocaConfigSchema = StringConfigSchema | NumberConfigSchema | BooleanConfigSchema | NullConfigSchema | ArrayConfigSchema | ObjectConfigSchema;
+export interface PluginDependency {
+    readonly id: string;
+    /** Supported forms are `*`, an exact semver, `^x.y.z`, or `~x.y.z`. */
+    readonly range: string;
+    readonly optional?: boolean;
+}
+export interface PluginManifest {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly version: string;
+    /** Doca SDK versions supported by this package. Uses the same range subset as dependencies. */
+    readonly sdkRange?: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly dependencies?: readonly PluginDependency[];
+    readonly config?: ObjectConfigSchema;
+    readonly contributions?: readonly PluginContributionDeclaration[];
+}
+export interface PluginContributionDeclaration {
+    readonly id: string;
+    readonly kind: string;
+    readonly target?: "server" | "web" | "mobile";
+}
+export interface DocaPluginPackage {
+    readonly package: string;
+    readonly enabled?: boolean;
+    readonly config?: JsonObject;
+    readonly targets?: readonly ("server" | "web" | "mobile")[];
+}
+export interface DocaSystemConfig {
+    readonly plugins: readonly DocaPluginPackage[];
+}
+export declare function validatePluginManifest(input: unknown): PluginManifest;
+export declare function validatePluginConfig<T extends JsonObject = JsonObject>(manifest: PluginManifest, input: unknown): T;
+export declare function satisfiesPluginVersion(version: string, range: string): boolean;
+export type MaybePromise<T> = T | Promise<T>;
+export type EffectCleanup = () => MaybePromise<void>;
+export type EffectDisposer = () => Promise<void>;
+declare const serviceType: unique symbol;
+export interface ServiceToken<T> {
+    readonly id: string;
+    readonly [serviceType]?: T;
+}
+export type DispatchMode = "emit" | "parallel" | "serial" | "bail" | "waterfall";
+export type NonWaterfallDispatchMode = Exclude<DispatchMode, "waterfall">;
+export type WaterfallNext<Result> = () => Result;
+declare const eventPayload: unique symbol;
+declare const eventResult: unique symbol;
+export interface EventToken<Payload, Result = void, Mode extends DispatchMode = "emit"> {
+    readonly id: string;
+    readonly mode: Mode;
+    readonly [eventPayload]?: Payload;
+    readonly [eventResult]?: Result;
+}
+export type EventHandler<Payload, Result, Mode extends DispatchMode> = Mode extends "waterfall" ? (payload: Payload, next: WaterfallNext<Result>) => Result : Mode extends "bail" ? (payload: Payload) => Result | false | null | undefined : Mode extends "serial" ? (payload: Payload) => MaybePromise<Result | false | null | undefined> : (payload: Payload) => MaybePromise<Result>;
+export type DispatchResult<Result, Mode extends DispatchMode> = Mode extends "emit" ? void : Mode extends "parallel" ? Promise<void> : Mode extends "serial" ? Promise<Awaited<Result> | undefined> : Mode extends "bail" ? Result | undefined : Result;
+declare const contributionType: unique symbol;
+export interface ContributionPoint<T> {
+    readonly id: string;
+    readonly [contributionType]?: T;
+}
+export interface ContributionRecord<T> {
+    readonly point: string;
+    readonly id: string;
+    readonly pluginId: string;
+    readonly value: T;
+}
+export interface DocaContributionRegistry {
+    register<T>(point: ContributionPoint<T>, id: string, value: T): EffectDisposer;
+    get<T>(point: ContributionPoint<T>, id: string): ContributionRecord<T> | undefined;
+    list<T>(point: ContributionPoint<T>): readonly ContributionRecord<T>[];
+}
+export interface DocaContext {
+    readonly scopeId: string;
+    readonly disposed: boolean;
+    provide<T>(token: ServiceToken<T>, value: T): EffectDisposer;
+    inject<T>(token: ServiceToken<T>): T;
+    injectOptional<T>(token: ServiceToken<T>): T | undefined;
+    has(token: ServiceToken<unknown>): boolean;
+    effect(setup: () => EffectCleanup | void): EffectDisposer;
+    effectAsync(setup: () => Promise<EffectCleanup | void>): Promise<EffectDisposer>;
+    child(scopeId?: string): DocaContext;
+    on<Payload, Result, Mode extends DispatchMode>(event: EventToken<Payload, Result, Mode>, handler: EventHandler<Payload, Result, Mode>): EffectDisposer;
+    dispatch<Payload, Result>(event: EventToken<Payload, Result, "waterfall">, payload: Payload, next: WaterfallNext<Result>): Result;
+    dispatch<Payload, Result, Mode extends NonWaterfallDispatchMode>(event: EventToken<Payload, Result, Mode>, payload: Payload): DispatchResult<Result, Mode>;
+    dispose(): Promise<void>;
+}
+export interface PluginLifecycleContext<Config extends JsonObject = JsonObject> extends DocaContext {
+    readonly manifest: PluginManifest;
+    readonly config: Config;
+    readonly contributions: DocaContributionRegistry;
+}
+export interface PluginInjections {
+    readonly required?: readonly ServiceToken<unknown>[];
+    readonly optional?: readonly ServiceToken<unknown>[];
+}
+export interface DocaPlugin<Config extends JsonObject = JsonObject> {
+    readonly manifest: PluginManifest;
+    readonly injections?: PluginInjections;
+    discover?(context: PluginLifecycleContext<Config>): MaybePromise<void>;
+    /** Runs on every start, including when the package version has not changed. */
+    initialize?(context: PluginLifecycleContext<Config>): MaybePromise<void>;
+    mount?(context: PluginLifecycleContext<Config>): MaybePromise<void>;
+    ready?(context: PluginLifecycleContext<Config>): MaybePromise<void>;
+    dispose?(context: PluginLifecycleContext<Config>): MaybePromise<void>;
+}
+export {};