@frockbot/plugin-testkit 0.0.0 → 0.1.1

package/package.json

@@ -1,14 +1,29 @@
 {
   "name": "@frockbot/plugin-testkit",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/kernel-composition": "0.1.1",
+    "cordis": "4.0.0-rc.8"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-testkit"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/index.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, test } from "bun:test";
+import { type Context, Service, type Plugin } from "cordis";
+import { createPluginHarness, verifyPluginPackage } from "./index.js";
+
+class MarkerService extends Service {
+  constructor(ctx: Context) {
+    super(ctx, "marker");
+  }
+}
+
+declare module "cordis" {
+  interface Context {
+    marker: MarkerService;
+  }
+}
+
+const fixtureManifest = {
+  schemaVersion: 2,
+  id: "fixture",
+  displayName: "Fixture",
+  version: "1.2.3",
+  compatibility: { frockbot: ">=0.0.1" },
+  contributions: {
+    runtime: { entry: "./agent" },
+    desktop: {
+      entry: "./desktop",
+      execution: "sandboxed-renderer",
+      commands: ["fixture.read"],
+    },
+  },
+  permissions: ["fixture:read"],
+};
+
+const fixturePackage = {
+  name: "@frockbot/plugin-fixture",
+  version: "1.2.3",
+  private: true,
+  exports: {
+    ".": "./src/index.ts",
+    "./agent": "./src/agent.ts",
+    "./desktop": "./src/desktop.ts",
+    "./manifest": "./src/manifest.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./package.json": "./package.json",
+  },
+  frockbot: { manifest: "./frockbot.json" },
+};
+
+describe("verifyPluginPackage", () => {
+  test("verifies package identity and contribution exports", () => {
+    expect(
+      verifyPluginPackage({
+        packageJson: fixturePackage,
+        manifest: fixtureManifest,
+      }),
+    ).toMatchObject({
+      name: "@frockbot/plugin-fixture",
+      contributionKinds: ["runtime", "desktop"],
+      manifest: { id: "fixture", version: "1.2.3" },
+    });
+  });
+
+  test("reports all package-level compliance failures together", () => {
+    let failure: unknown;
+    try {
+      verifyPluginPackage({
+        packageJson: {
+          ...fixturePackage,
+          name: "fixture",
+          version: "9.0.0",
+          private: false,
+          exports: { ".": "./src/index.ts" },
+          frockbot: { manifest: "./other.json" },
+        },
+        manifest: {
+          ...fixtureManifest,
+          permissions: ["fixture:read", "fixture:read"],
+        },
+      });
+    } catch (error) {
+      failure = error;
+    }
+
+    expect(failure).toBeInstanceOf(AggregateError);
+    const message = failure instanceof Error ? failure.message : "";
+    expect(message).toContain("package name must be");
+    expect(message).toContain("versions must match");
+    expect(message).toContain("must be private");
+    expect(message).toContain("./manifest");
+    expect(message).toContain("must not contain duplicates");
+  });
+
+  test("verifies the mobile contribution export", () => {
+    expect(
+      verifyPluginPackage({
+        packageJson: {
+          ...fixturePackage,
+          exports: { ...fixturePackage.exports, "./mobile": "./src/mobile.ts" },
+        },
+        manifest: {
+          ...fixtureManifest,
+          contributions: {
+            ...fixtureManifest.contributions,
+            mobile: { entry: "./mobile" },
+          },
+        },
+      }),
+    ).toMatchObject({
+      contributionKinds: ["runtime", "desktop", "mobile"],
+    });
+  });
+
+  test("reports a missing mobile contribution export", () => {
+    let failure: unknown;
+    try {
+      verifyPluginPackage({
+        packageJson: fixturePackage,
+        manifest: {
+          ...fixtureManifest,
+          contributions: {
+            ...fixtureManifest.contributions,
+            mobile: { entry: "./mobile" },
+          },
+        },
+      });
+    } catch (error) {
+      failure = error;
+    }
+
+    expect(failure).toBeInstanceOf(AggregateError);
+    expect(failure instanceof Error ? failure.message : "").toContain(
+      'package exports must include "./mobile"',
+    );
+  });
+});
+
+describe("PluginHarness", () => {
+  test("mounts injected plugins and disposes their effects", async () => {
+    let active = false;
+    const dependent: Plugin.Function = () => {
+      active = true;
+      return () => {
+        active = false;
+      };
+    };
+    dependent.inject = ["marker"];
+    const harness = await createPluginHarness([MarkerService]);
+
+    await harness.mount(dependent);
+    expect(active).toBeTrue();
+
+    await harness.dispose();
+    expect(active).toBeFalse();
+  });
+
+  test("disposes setup plugins when later setup fails", async () => {
+    let cleaned = false;
+    const tracked: Plugin.Function = () => () => {
+      cleaned = true;
+    };
+    const failing: Plugin.Function = () => {
+      throw new Error("setup failed");
+    };
+    let failure: unknown;
+
+    try {
+      await createPluginHarness([tracked, failing]);
+    } catch (error) {
+      failure = error;
+    }
+
+    expect(failure).toBeInstanceOf(Error);
+    expect(cleaned).toBeTrue();
+  });
+});

package/src/index.ts

@@ -0,0 +1,128 @@
+import {
+  type ContributionKind,
+  decodeFrockBotManifest,
+  declaredContributionKinds,
+  type FrockBotManifest,
+} from "@frockbot/kernel-composition";
+import { Context, type Plugin } from "cordis";
+
+export interface PluginPackageFixture {
+  packageJson: unknown;
+  manifest: unknown;
+}
+
+export interface VerifiedPluginPackage {
+  name: string;
+  manifest: FrockBotManifest;
+  contributionKinds: ContributionKind[];
+}
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function nonEmptyString(value: unknown, label: string): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function requireExport(
+  exports: Record<string, unknown>,
+  key: string,
+  issues: string[],
+): void {
+  if (!(key in exports)) issues.push(`package exports must include "${key}"`);
+}
+
+export function verifyPluginPackage(
+  fixture: PluginPackageFixture,
+): VerifiedPluginPackage {
+  const manifest = decodeFrockBotManifest(fixture.manifest);
+  const packageJson = record(fixture.packageJson, "package.json");
+  const name = nonEmptyString(packageJson.name, "package.json name");
+  const version = nonEmptyString(packageJson.version, "package.json version");
+  const exports = record(packageJson.exports, "package.json exports");
+  const frockbot = record(packageJson.frockbot, "package.json frockbot field");
+  const issues: string[] = [];
+
+  const expectedName = `@frockbot/plugin-${manifest.id}`;
+  if (name !== expectedName) {
+    issues.push(`package name must be "${expectedName}"`);
+  }
+  if (version !== manifest.version) {
+    issues.push("package and manifest versions must match");
+  }
+  if (packageJson.private !== true) {
+    issues.push("plugin workspace packages must be private");
+  }
+  if (frockbot.manifest !== "./frockbot.json") {
+    issues.push('package.json frockbot.manifest must be "./frockbot.json"');
+  }
+
+  requireExport(exports, ".", issues);
+  requireExport(exports, "./manifest", issues);
+  requireExport(exports, "./frockbot.json", issues);
+  requireExport(exports, "./package.json", issues);
+  for (const contribution of [
+    manifest.contributions.runtime,
+    manifest.contributions.client,
+    manifest.contributions.desktop,
+    manifest.contributions.mobile,
+  ]) {
+    if (contribution) requireExport(exports, contribution.entry, issues);
+  }
+  if (new Set(manifest.permissions).size !== manifest.permissions.length) {
+    issues.push("manifest permissions must not contain duplicates");
+  }
+
+  if (issues.length > 0) {
+    throw new AggregateError(
+      issues.map((issue) => new Error(issue)),
+      `plugin package "${manifest.id}" is invalid:\n- ${issues.join("\n- ")}`,
+    );
+  }
+
+  return {
+    name,
+    manifest,
+    contributionKinds: declaredContributionKinds(manifest),
+  };
+}
+
+export class PluginHarness {
+  readonly root: Context;
+  private disposed = false;
+
+  constructor(root: Context = new Context()) {
+    this.root = root;
+  }
+
+  async mount(plugin: Plugin) {
+    if (this.disposed) throw new Error("plugin harness is disposed");
+    return await this.root.plugin(plugin);
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    await this.root.fiber.dispose();
+  }
+}
+
+export async function createPluginHarness(
+  setup: readonly Plugin[] = [],
+): Promise<PluginHarness> {
+  const harness = new PluginHarness();
+  try {
+    for (const plugin of setup) await harness.mount(plugin);
+    return harness;
+  } catch (error) {
+    await harness.dispose();
+    throw error;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM"],
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/plugin-testkit
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.