@venn-lang/contracts 0.1.0

package/src/ports/signal-source/node-signals.ts

@@ -0,0 +1,33 @@
+import { constants } from "node:os";
+import process from "node:process";
+import type { SignalSource, SystemSignal, Unsubscribe } from "./signal-source.types.js";
+
+/**
+ * Whether this platform knows the signal.
+ *
+ * Not every name exists everywhere: `SIGBREAK` is Windows only, and subscribing
+ * to an unknown one throws. Asking first turns a crash at start up into a
+ * subscription that never fires.
+ */
+export function isKnownSignal(signal: SystemSignal): boolean {
+  return signal in constants.signals;
+}
+
+/**
+ * The real one: the signals this process receives.
+ *
+ * Lives behind `@venn-lang/contracts/node` because it touches `node:process`, so the
+ * main entry stays neutral and still runs in the editor's worker.
+ */
+export function createNodeSignals(): SignalSource {
+  return {
+    on: (signal, handler): Unsubscribe => {
+      if (!isKnownSignal(signal)) return () => {};
+      const listener = () => handler(signal);
+      process.on(signal, listener);
+      return () => {
+        process.off(signal, listener);
+      };
+    },
+  };
+}

package/src/ports/signal-source/signal-source.port.ts

@@ -0,0 +1,13 @@
+import type { Port } from "../../port/index.js";
+import type { SignalSource } from "./signal-source.types.js";
+
+/**
+ * The {@link SignalSource} contract. Implementations: `node-signals`,
+ * `fake-signals`.
+ */
+export const SignalSourcePort: Port<SignalSource> = {
+  id: "venn.port.signals",
+  version: 1,
+  requires: ["process"],
+  methods: ["on"],
+};

package/src/ports/signal-source/signal-source.types.ts

@@ -0,0 +1,24 @@
+/**
+ * The ways a system asks a program to stop. `SIGBREAK` is Windows' Ctrl+Break,
+ * `SIGHUP` is the terminal itself going away.
+ */
+export const ALL_SIGNALS = ["SIGINT", "SIGTERM", "SIGBREAK", "SIGHUP"] as const;
+
+/** One signal name, drawn from {@link ALL_SIGNALS}. */
+export type SystemSignal = (typeof ALL_SIGNALS)[number];
+
+/** Called on every delivery of the signal it was registered for. */
+export type SignalHandler = (signal: SystemSignal) => void;
+
+/** Drops a subscription. Calling it more than once is harmless. */
+export type Unsubscribe = () => void;
+
+/**
+ * Where a program hears the system asking it to stop.
+ *
+ * The double matters more than usual here: raising a true SIGINT inside a test
+ * run stops the test runner, not the code under test.
+ */
+export interface SignalSource {
+  on(signal: SystemSignal, handler: SignalHandler): Unsubscribe;
+}

package/src/testing.ts

@@ -0,0 +1,16 @@
+// @venn-lang/contracts/testing: the conformance harness (TCK). It imports vitest and
+// fast-check, so it stays out of the runtime bundle. Any package can run these
+// suites against its own implementation.
+export type { ConformanceSpec, PortFactory } from "./conformance/index.js";
+export { expectVennError } from "./conformance/index.js";
+export { clockConformance } from "./ports/clock/clock.suite.js";
+export { fileSystemConformance } from "./ports/file-system/file-system.suite.js";
+export { lockProviderConformance } from "./ports/lock-provider/lock-provider.suite.js";
+export { manifestProviderConformance } from "./ports/manifest-provider/manifest.suite.js";
+export { processProviderConformance } from "./ports/process-provider/process-provider.suite.js";
+export { randomConformance } from "./ports/random/random.suite.js";
+export { secretProviderConformance } from "./ports/secret-provider/secret-provider.suite.js";
+export {
+  type SignalSpec,
+  signalSourceConformance,
+} from "./ports/signal-source/signal-source.suite.js";