@ama-work/plugin-contract 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ask-Me-Anything-dot-work
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @ama-work/plugin-contract
+
+Neutral TypeScript contract package shared between the Orchestrator core (`ama-agent-orchestrator`) and all mesh plugins.
+
+## Purpose
+
+This package defines the interface boundary between the Orchestrator and plugins. Neither side depends on the other — both depend only on this package. This property must be preserved; do not import from `ama-agent-orchestrator` or any specific plugin repo.
+
+## Install
+
+```bash
+bun add @ama-work/plugin-contract
+# or
+npm install @ama-work/plugin-contract
+```
+
+## Exported Types
+
+```typescript
+import {
+  PluginBridge,
+  IncomingEvent,
+  PluginManifest,
+  ConsolePanel,
+  OrchestratorPlugin,
+  Logger,
+} from "@ama-work/plugin-contract";
+```
+
+### PluginBridge
+
+The interface plugins use to interact with the orchestrator. Implement `PluginBridge` to receive events, mount routes, and manage config.
+
+### PluginManifest
+
+Plugin metadata. The `provides` field is `string[]` (open type) — any plugin can declare arbitrary capability strings without requiring changes to this contract.
+
+```typescript
+const manifest: PluginManifest = {
+  id: "my-plugin",
+  name: "My Plugin",
+  version: "1.0.0",
+  provides: ["connector", "custom-thing"],
+};
+```
+
+### ConsolePanel
+
+Console panel descriptor for UI integration:
+
+```typescript
+interface ConsolePanel {
+  id: string;
+  navLabel: string;
+  icon: string;
+  mixinUrl: string;
+  templateUrl: string;
+}
+```
+
+### OrchestratorPlugin
+
+Plugin lifecycle hooks:
+
+```typescript
+interface OrchestratorPlugin {
+  id: string;
+  onInstall?(bridge: PluginBridge): Promise<void>;
+  onStart(bridge: PluginBridge): Promise<void>;
+  onStop(): Promise<void>;
+}
+```
+
+## Testing with MockBridge
+
+```typescript
+import { MockBridge } from "@ama-work/plugin-contract/testing";
+```
+
+`MockBridge` is a full in-memory `PluginBridge` implementation for unit tests:
+
+- `submittedEvents` — array of events submitted via `submitEvent()`
+- `mountedPanels` — array of panels mounted via `mountConsolePanel()`
+- `mountRoutes(router)` — starts a local Hono server on configurable port
+- `getConfig()` / `saveConfig()` — round-trips in memory
+- All other methods are no-op stubs
+
+## Versioning Policy
+
+Any change to the exported interfaces is a **semver major** bump. This package is the stable dependency point for all downstream plugins — treat instability as a cost imposed on every plugin author.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { PluginBridge, IncomingEvent, OrchestratorPlugin, PluginManifest, ConsolePanel, Logger, } from "./plugin/types.js";
+export { MockBridge } from "./plugin/testing/mock-bridge.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { MockBridge } from "./plugin/testing/mock-bridge.js";

package/dist/plugin/testing/mock-bridge.d.ts

@@ -0,0 +1,19 @@
+import { Hono } from "hono";
+import type { PluginBridge, IncomingEvent, ConsolePanel, Logger } from "../types.js";
+export declare class MockBridge implements PluginBridge {
+    readonly submittedEvents: IncomingEvent[];
+    readonly mountedPanels: ConsolePanel[];
+    private config;
+    private server;
+    private port;
+    readonly logger: Logger;
+    constructor(port?: number);
+    submitEvent(event: IncomingEvent): Promise<void>;
+    mountRoutes(router: Hono): void;
+    mountConsolePanel(panel: ConsolePanel): void;
+    runMigrations(_migrationsDir: string): Promise<void>;
+    getConfig<T>(): Promise<T>;
+    saveConfig<T>(config: T): Promise<void>;
+    getPort(): number;
+    stop(): void;
+}

package/dist/plugin/testing/mock-bridge.js

@@ -0,0 +1,42 @@
+import { serve } from "@hono/node-server";
+export class MockBridge {
+    submittedEvents = [];
+    mountedPanels = [];
+    config = {};
+    server = null;
+    port;
+    logger = {
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+        debug: () => { },
+    };
+    constructor(port = 0) {
+        this.port = port;
+    }
+    async submitEvent(event) {
+        this.submittedEvents.push(event);
+    }
+    mountRoutes(router) {
+        this.server = serve({ fetch: router.fetch, port: this.port });
+    }
+    mountConsolePanel(panel) {
+        this.mountedPanels.push(panel);
+    }
+    async runMigrations(_migrationsDir) { }
+    async getConfig() {
+        return this.config;
+    }
+    async saveConfig(config) {
+        this.config = config;
+    }
+    getPort() {
+        return this.port;
+    }
+    stop() {
+        if (this.server) {
+            this.server.close();
+            this.server = null;
+        }
+    }
+}

package/dist/plugin/types.d.ts

@@ -0,0 +1,45 @@
+import type { Hono } from "hono";
+export interface PluginBridge {
+    submitEvent(event: IncomingEvent): Promise<void>;
+    mountRoutes(router: Hono): void;
+    mountConsolePanel(panel: ConsolePanel): void;
+    runMigrations(migrationsDir: string): Promise<void>;
+    getConfig<T>(): Promise<T>;
+    saveConfig<T>(config: T): Promise<void>;
+    logger: Logger;
+}
+export interface IncomingEvent {
+    source: string;
+    type: "issue_mention" | "project_status_change" | "push_to_main";
+    repo: string;
+    actor?: string;
+    payload: unknown;
+    receivedAt: Date;
+    deliveryId: string;
+}
+export interface OrchestratorPlugin {
+    id: string;
+    onInstall?(bridge: PluginBridge): Promise<void>;
+    onStart(bridge: PluginBridge): Promise<void>;
+    onStop(): Promise<void>;
+}
+export interface PluginManifest {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    provides: string[];
+}
+export interface ConsolePanel {
+    id: string;
+    navLabel: string;
+    icon: string;
+    mixinUrl: string;
+    templateUrl: string;
+}
+export interface Logger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+}

package/dist/plugin/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ama-work/plugin-contract",
+  "version": "1.0.0",
+  "description": "Neutral TypeScript contract package (PluginBridge, ConsolePanel, PluginManifest) shared between the orchestrator core and all mesh plugins",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "start": "bun src/index.ts",
+    "build": "tsc --project tsconfig.build.json",
+    "lint": "tsc --noEmit && knip && eslint .",
+    "test": "vitest run",
+    "release": "semantic-release",
+    "prepublishOnly": "bun run build",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "hono": "^4.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@hono/node-server": "^1.14.0",
+    "@commitlint/cli": "^21.2.0",
+    "@commitlint/config-conventional": "^21.2.0",
+    "@commitlint/types": "^21.2.0",
+    "@semantic-release/commit-analyzer": "12",
+    "conventional-changelog-conventionalcommits": "^9.0.0",
+    "@semantic-release/git": "10",
+    "@semantic-release/github": "^12.0.9",
+    "@semantic-release/npm": "12",
+    "@semantic-release/release-notes-generator": "12",
+    "@types/bun": "^1.3.13",
+    "eslint": "^9.0.0",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
+    "husky": "^9.1.7",
+    "knip": "^6.6.2",
+    "semantic-release": "24",
+    "tsx": "^4.19.1",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.59.3",
+    "vitest": "^2.0.5"
+  }
+}