@venn-lang/contracts 0.1.0

package/src/ports/manifest-provider/toml/parse-toml.ts

@@ -0,0 +1,52 @@
+import { cursor, readValue } from "./read-value.js";
+import { enterSection, enterTableArray } from "./sections.js";
+
+/**
+ * A TOML reader for `venn.toml`: sections, nested `[a.b]`, arrays of tables
+ * (`[[bin]]`), `key = value`, strings, numbers, bools, arrays and inline tables.
+ *
+ * Not a full TOML parser. No dates, no multi-line strings, no dotted keys.
+ * `venn.toml` is our own format, so the subset is a decision rather than a
+ * shortfall.
+ *
+ * @returns the root table. Malformed lines are skipped, never thrown on.
+ */
+export function parseToml(content: string): Record<string, unknown> {
+  const root: Record<string, unknown> = {};
+  let section = root;
+  for (const raw of content.split(/\r?\n/)) {
+    const line = stripComment(raw).trim();
+    if (line === "") continue;
+    if (line.startsWith("[")) section = openSection(root, line);
+    else assign(section, line);
+  }
+  return root;
+}
+
+/** `[[bin]]` appends another table, `[bin]` opens the one and only. */
+function openSection(root: Record<string, unknown>, line: string): Record<string, unknown> {
+  if (line.startsWith("[[")) {
+    return enterTableArray(root, line.slice(2, line.indexOf("]]")));
+  }
+  return enterSection(root, line.slice(1, line.indexOf("]")));
+}
+
+function stripComment(line: string): string {
+  let quote: string | undefined;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '"' || ch === "'") quote = quote === ch ? undefined : (quote ?? ch);
+    else if (ch === "#" && !quote) return line.slice(0, i);
+  }
+  return line;
+}
+
+function assign(section: Record<string, unknown>, line: string): void {
+  const eq = line.indexOf("=");
+  if (eq < 0) return;
+  const key = line
+    .slice(0, eq)
+    .trim()
+    .replace(/^["']|["']$/g, "");
+  section[key] = readValue(cursor(line.slice(eq + 1)));
+}

package/src/ports/manifest-provider/toml/read-value.ts

@@ -0,0 +1,104 @@
+/** A position in the text being read. Mutable, because reading advances it. */
+export interface Cursor {
+  readonly text: string;
+  index: number;
+}
+
+/** A cursor over `text`, positioned at the start. */
+export function cursor(text: string): Cursor {
+  return { text, index: 0 };
+}
+
+/**
+ * One TOML value: a string, a number, a bool, an array, or an inline table.
+ *
+ * Reads by walking rather than by splitting, because a comma can sit inside a
+ * value: splitting turns `["a,b"]` into two items and leaves
+ * `{ version = "^4" }` as the text it was written in.
+ */
+export function readValue(cur: Cursor): unknown {
+  skipSpace(cur);
+  const ch = cur.text[cur.index];
+  if (ch === '"' || ch === "'") return readString(cur);
+  if (ch === "[") return readArray(cur);
+  if (ch === "{") return readInlineTable(cur);
+  return readBare(cur);
+}
+
+export function skipSpace(cur: Cursor): void {
+  while (/\s/.test(cur.text[cur.index] ?? "")) cur.index++;
+}
+
+/** A basic string reads escapes; a literal one, in single quotes, does not. */
+function readString(cur: Cursor): string {
+  const quote = cur.text[cur.index];
+  cur.index++;
+  let out = "";
+  while (cur.index < cur.text.length && cur.text[cur.index] !== quote) {
+    if (quote === '"' && cur.text[cur.index] === "\\") out += unescaped(cur);
+    else out += cur.text[cur.index++];
+  }
+  cur.index++;
+  return out;
+}
+
+const ESCAPES: Record<string, string> = { n: "\n", t: "\t", r: "\r", "\\": "\\", '"': '"' };
+
+function unescaped(cur: Cursor): string {
+  const code = cur.text[cur.index + 1] ?? "";
+  cur.index += 2;
+  return ESCAPES[code] ?? code;
+}
+
+function readArray(cur: Cursor): unknown[] {
+  cur.index++;
+  const out: unknown[] = [];
+  while (!atClose(cur, "]")) {
+    out.push(readValue(cur));
+    skipSeparator(cur);
+  }
+  cur.index++;
+  return out;
+}
+
+function readInlineTable(cur: Cursor): Record<string, unknown> {
+  cur.index++;
+  const out: Record<string, unknown> = {};
+  while (!atClose(cur, "}")) {
+    const key = readKey(cur);
+    if (key === undefined) break;
+    out[key] = readValue(cur);
+    skipSeparator(cur);
+  }
+  cur.index++;
+  return out;
+}
+
+function readKey(cur: Cursor): string | undefined {
+  skipSpace(cur);
+  const equals = cur.text.indexOf("=", cur.index);
+  if (equals < 0) return undefined;
+  const raw = cur.text.slice(cur.index, equals).trim();
+  cur.index = equals + 1;
+  return raw.replace(/^["']|["']$/g, "");
+}
+
+function atClose(cur: Cursor, close: string): boolean {
+  skipSpace(cur);
+  return cur.index >= cur.text.length || cur.text[cur.index] === close;
+}
+
+function skipSeparator(cur: Cursor): void {
+  skipSpace(cur);
+  if (cur.text[cur.index] === ",") cur.index++;
+}
+
+/** Anything unquoted: `true`, `12`, `1.5`, or a word the manifest gives meaning. */
+function readBare(cur: Cursor): unknown {
+  const start = cur.index;
+  while (cur.index < cur.text.length && !",]}".includes(cur.text[cur.index] ?? "")) cur.index++;
+  const raw = cur.text.slice(start, cur.index).trim();
+  if (raw === "true" || raw === "false") return raw === "true";
+  const num = Number(raw);
+  return raw !== "" && !Number.isNaN(num) ? num : raw;
+}

package/src/ports/manifest-provider/toml/sections.ts

@@ -0,0 +1,39 @@
+// Opening `[a.b]` or `[[a.b]]`: working out where the keys that follow go.
+
+/** The table `[path]` names, created along the way if it is not there yet. */
+export function enterSection(root: Record<string, unknown>, path: string): Record<string, unknown> {
+  let node = root;
+  for (const key of keysOf(path)) {
+    node[key] ??= {};
+    node = node[key] as Record<string, unknown>;
+  }
+  return node;
+}
+
+/**
+ * `[[bin]]`: one more of something there may be several of.
+ *
+ * Returns the table just appended, so two `[[bin]]` sections give two bins
+ * rather than one bin written twice.
+ */
+export function enterTableArray(
+  root: Record<string, unknown>,
+  path: string,
+): Record<string, unknown> {
+  const keys = keysOf(path);
+  const last = keys.pop();
+  if (!last) return root;
+  const parent = enterSection(root, keys.join("."));
+  const found = Array.isArray(parent[last]) ? (parent[last] as unknown[]) : [];
+  parent[last] = found;
+  const table: Record<string, unknown> = {};
+  found.push(table);
+  return table;
+}
+
+function keysOf(path: string): string[] {
+  return path
+    .split(".")
+    .map((part) => part.trim().replace(/^["']|["']$/g, ""))
+    .filter((part) => part !== "");
+}

package/src/ports/manifest-provider/toml-docs.ts

@@ -0,0 +1,27 @@
+const COMMENT = /^\s*#\s?(.*)$/;
+const KEY = /^\s*([A-Za-z_][\w-]*)\s*=/;
+
+/**
+ * The comment block written directly above a key, read as that key's
+ * documentation. The same idea as `##` above a declaration in a `.vn`.
+ *
+ * A blank line breaks the block, so a comment separated from a key belongs to
+ * nobody and is never attributed to the next one down.
+ *
+ * @returns documentation keyed by the key it sits above.
+ */
+export function tomlDocs(content: string): Record<string, string> {
+  const docs: Record<string, string> = {};
+  let block: string[] = [];
+  for (const line of content.split(/\r?\n/)) {
+    const comment = COMMENT.exec(line);
+    if (comment) {
+      block.push(comment[1] ?? "");
+      continue;
+    }
+    const key = KEY.exec(line)?.[1];
+    if (key && block.length > 0) docs[key] = block.join("\n").trim();
+    block = [];
+  }
+  return docs;
+}

package/src/ports/manifest-provider/toml-manifest.ts

@@ -0,0 +1,41 @@
+import type { Manifest, ManifestProvider } from "./manifest.types.js";
+import {
+  readDependencies,
+  readPackage,
+  readProfiles,
+  readTargets,
+  readTooling,
+  readWorkspace,
+} from "./read/index.js";
+import { readRunSettings } from "./read-run-settings.js";
+import { parseToml } from "./toml/index.js";
+
+/**
+ * The real one: parse `venn.toml` into a {@link Manifest}.
+ *
+ * Parsing happens once, at construction, so repeated `load()` calls are free
+ * and always agree.
+ *
+ * @param args.content - the manifest as written.
+ */
+export function createTomlManifest(args: { content: string }): ManifestProvider {
+  const manifest = toManifest(parseToml(args.content));
+  return { load: () => manifest };
+}
+
+function toManifest(data: Record<string, unknown>): Manifest {
+  const pkg = readPackage(data);
+  return {
+    name: pkg.name,
+    version: pkg.version ?? "0.0.0",
+    package: pkg,
+    targets: readTargets(data, pkg.name),
+    dependencies: readDependencies(data.dependencies),
+    devDependencies: readDependencies(data["dev-dependencies"]),
+    patch: readDependencies(data.patch),
+    profiles: readProfiles(data),
+    tooling: readTooling(data),
+    workspace: readWorkspace(data),
+    ...readRunSettings(data),
+  };
+}

package/src/ports/process-provider/fake-process.ts

@@ -0,0 +1,32 @@
+import type { ProcessHandle, ProcessProvider } from "./process-provider.types.js";
+
+/**
+ * The double: a scripted process that never touches the OS.
+ *
+ * Output is streamed before the wait resolves, exactly as the real one does it,
+ * so a caller that shows progress is exercised here and not only against a real
+ * machine.
+ *
+ * @param args.exitCode - what every run reports. Defaults to 0.
+ * @param args.output - what every run writes. Defaults to nothing.
+ */
+export function createFakeProcess(
+  args: { exitCode?: number; output?: string } = {},
+): ProcessProvider {
+  const code = args.exitCode ?? 0;
+  const output = args.output ?? "";
+  return {
+    spawn: (spawned) => {
+      if (output !== "") spawned.onOutput?.(output);
+      return handle(code, output);
+    },
+  };
+}
+
+function handle(code: number, output: string): ProcessHandle {
+  return {
+    pid: 0,
+    wait: async () => ({ code, output }),
+    kill: () => {},
+  };
+}

package/src/ports/process-provider/index.ts

@@ -0,0 +1,10 @@
+export { createFakeProcess } from "./fake-process.js";
+export { ProcessProviderPort } from "./process-provider.port.js";
+export type {
+  ProcessHandle,
+  ProcessProvider,
+  ProcessResult,
+  SpawnArgs,
+} from "./process-provider.types.js";
+// node-spawn is deliberately absent: like node-fs it lives behind
+// @venn-lang/contracts/node, so this barrel stays Worker-safe.

package/src/ports/process-provider/node-spawn.ts

@@ -0,0 +1,52 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import type {
+  ProcessHandle,
+  ProcessProvider,
+  ProcessResult,
+  SpawnArgs,
+} from "./process-provider.types.js";
+
+/**
+ * The real one, on `node:child_process`.
+ *
+ * Output is streamed to whoever asked and kept at the same time: a package
+ * manager needs watching while it works and reading once it is done, and only
+ * one of the two would leave either a command that looks hung or a result
+ * nobody can inspect.
+ */
+export function createNodeSpawn(): ProcessProvider {
+  return { spawn: (args) => start(args) };
+}
+
+function start(args: SpawnArgs): ProcessHandle {
+  const child = spawn(args.command, [...(args.args ?? [])], {
+    cwd: args.cwd,
+    env: args.env ? { ...process.env, ...args.env } : process.env,
+    shell: args.shell ?? false,
+  });
+  const chunks: string[] = [];
+  listen(child, chunks, args.onOutput);
+  return { pid: child.pid ?? 0, wait: () => ended(child, chunks), kill: () => void child.kill() };
+}
+
+function listen(child: ChildProcess, into: string[], onOutput?: (chunk: string) => void): void {
+  for (const stream of [child.stdout, child.stderr]) {
+    stream?.on("data", (chunk: Buffer) => {
+      const text = chunk.toString("utf8");
+      into.push(text);
+      onOutput?.(text);
+    });
+  }
+}
+
+/**
+ * A command that could never start reads as one that ran and failed, with the
+ * reason as its output, because that is what a caller can act on. `127` is what
+ * a shell says for "no such command", and it means the same here.
+ */
+function ended(child: ChildProcess, chunks: string[]): Promise<ProcessResult> {
+  return new Promise((resolve) => {
+    child.on("error", (err) => resolve({ code: 127, output: `${chunks.join("")}${err.message}` }));
+    child.on("close", (code) => resolve({ code: code ?? 0, output: chunks.join("") }));
+  });
+}

package/src/ports/process-provider/process-provider.port.ts

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

package/src/ports/process-provider/process-provider.types.ts

@@ -0,0 +1,47 @@
+/** What to run, where, and how to hear from it while it runs. */
+export interface SpawnArgs {
+  command: string;
+  args?: readonly string[];
+  /** Where it runs. The current directory unless this says otherwise. */
+  cwd?: string;
+  /** Added to the environment the host was started with. */
+  env?: Record<string, string>;
+  /**
+   * Whether to go through the platform shell.
+   *
+   * Needed for a command that is a script rather than an executable: on Windows
+   * `pnpm` is a `.cmd`, and nothing runs it without one. Off by default,
+   * because a shell re-reads the arguments and a quote that meant one thing to
+   * the caller means another to `cmd.exe`. Only the caller knows which of the
+   * two it is holding.
+   */
+  shell?: boolean;
+  /**
+   * Called with each chunk the command writes, as it writes it.
+   *
+   * A package manager installing a hundred packages takes half a minute, and a
+   * command silent for half a minute reads as one that has hung. What is
+   * streamed here is kept as well, so a caller can show it and read it after.
+   */
+  onOutput?: (chunk: string) => void;
+}
+
+/** How a run ended. */
+export interface ProcessResult {
+  code: number;
+  /** Everything it wrote, stdout and stderr together, in the order written. */
+  output: string;
+}
+
+/** A spawned subprocess. */
+export interface ProcessHandle {
+  readonly pid: number;
+  /** Resolves when the command ends. Never rejects: a failure is a result. */
+  wait(): Promise<ProcessResult>;
+  kill(): void;
+}
+
+/** Spawn subprocesses: a package manager, a driver, anything the host allows. */
+export interface ProcessProvider {
+  spawn(args: SpawnArgs): ProcessHandle;
+}

package/src/ports/random/fixed-random.ts

@@ -0,0 +1,10 @@
+import type { Random } from "./random.types.js";
+
+/** The double: always the same value, and always `min` from `int`. */
+export function createFixedRandom(args: { value?: number } = {}): Random {
+  const value = args.value ?? 0;
+  return {
+    next: () => value,
+    int: (min) => min,
+  };
+}

package/src/ports/random/index.ts

@@ -0,0 +1,4 @@
+export { createFixedRandom } from "./fixed-random.js";
+export { RandomPort } from "./random.port.js";
+export type { Random } from "./random.types.js";
+export { createSeededRandom } from "./seeded-random.js";

package/src/ports/random/random.port.ts

@@ -0,0 +1,13 @@
+import type { Port } from "../../port/index.js";
+import type { Random } from "./random.types.js";
+
+/**
+ * The {@link Random} contract. Implementations: `seeded-random`,
+ * `fixed-random`.
+ */
+export const RandomPort: Port<Random> = {
+  id: "venn.port.random",
+  version: 1,
+  requires: ["random"],
+  methods: ["next", "int"],
+};

package/src/ports/random/random.types.ts

@@ -0,0 +1,10 @@
+/**
+ * A source of randomness. Every implementation is reproducible, so a failing
+ * run can be replayed.
+ */
+export interface Random {
+  /** Uniform float in [0, 1). */
+  next(): number;
+  /** Uniform integer in the inclusive range [min, max]. */
+  int(min: number, max: number): number;
+}

package/src/ports/random/seeded-random.ts

@@ -0,0 +1,19 @@
+import type { Random } from "./random.types.js";
+
+/**
+ * The real one: a mulberry32 PRNG, seeded once per worker. Same seed, same
+ * sequence, so a run reproduces.
+ */
+export function createSeededRandom(args: { seed: number }): Random {
+  let state = args.seed >>> 0;
+  const next = (): number => {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  return {
+    next,
+    int: (min, max) => min + Math.floor(next() * (max - min + 1)),
+  };
+}

package/src/ports/secret-provider/env-secrets.ts

@@ -0,0 +1,19 @@
+import { makeSecret } from "./secret.js";
+import type { SecretProvider } from "./secret-provider.types.js";
+
+/**
+ * The real one: secrets from `process.env`.
+ *
+ * The `process` global is probed rather than imported, so this file stays
+ * neutral and reports every name as absent in a Worker instead of throwing.
+ */
+export function createEnvSecrets(): SecretProvider {
+  const env: Record<string, string | undefined> = typeof process === "undefined" ? {} : process.env;
+  return {
+    get: (name) => {
+      const value = env[name];
+      return value === undefined ? undefined : makeSecret({ reveal: value });
+    },
+    has: (name) => env[name] !== undefined,
+  };
+}

package/src/ports/secret-provider/index.ts

@@ -0,0 +1,6 @@
+export { createEnvSecrets } from "./env-secrets.js";
+export { createMemorySecrets } from "./memory-secrets.js";
+export { makeSecret, REDACTED } from "./secret.js";
+export { SecretProviderPort } from "./secret-provider.port.js";
+export type { KnownSecret } from "./secret-provider.suite.js";
+export type { Secret, SecretProvider } from "./secret-provider.types.js";

package/src/ports/secret-provider/memory-secrets.ts

@@ -0,0 +1,15 @@
+import { makeSecret } from "./secret.js";
+import type { SecretProvider } from "./secret-provider.types.js";
+
+/**
+ * The double: secrets given by name, wrapped so they still redact.
+ *
+ * @param args.values - the raw values, keyed by secret name.
+ */
+export function createMemorySecrets(args: { values: Record<string, string> }): SecretProvider {
+  const values = args.values;
+  return {
+    get: (name) => (name in values ? makeSecret({ reveal: values[name] as string }) : undefined),
+    has: (name) => name in values,
+  };
+}

package/src/ports/secret-provider/secret-provider.port.ts

@@ -0,0 +1,13 @@
+import type { Port } from "../../port/index.js";
+import type { SecretProvider } from "./secret-provider.types.js";
+
+/**
+ * The {@link SecretProvider} contract. Implementations: `env-secrets`,
+ * `memory-secrets`.
+ */
+export const SecretProviderPort: Port<SecretProvider> = {
+  id: "venn.port.secrets",
+  version: 1,
+  requires: ["secrets"],
+  methods: ["get", "has"],
+};

package/src/ports/secret-provider/secret-provider.types.ts

@@ -0,0 +1,17 @@
+/**
+ * A value that redacts itself. Serialising one, by any route, yields the
+ * redaction marker: redaction happens at the producer, because redacting in the
+ * UI is already too late.
+ */
+export interface Secret {
+  /** The only way to the raw value, and deliberately something you must ask for. */
+  reveal(): string;
+  toString(): string;
+  toJSON(): string;
+}
+
+/** Resolves `secrets.*` names to redaction-marked values. */
+export interface SecretProvider {
+  get(name: string): Secret | undefined;
+  has(name: string): boolean;
+}

package/src/ports/secret-provider/secret.ts

@@ -0,0 +1,17 @@
+import type { Secret } from "./secret-provider.types.js";
+
+/** What every serialised secret collapses to. */
+export const REDACTED = "‹redigido›";
+
+/**
+ * Wrap a raw value so it cannot leak through `toString` or `toJSON`.
+ *
+ * @param args.reveal - the raw value, reachable only via `Secret.reveal()`.
+ */
+export function makeSecret(args: { reveal: string }): Secret {
+  return {
+    reveal: () => args.reveal,
+    toString: () => REDACTED,
+    toJSON: () => REDACTED,
+  };
+}

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

@@ -0,0 +1,44 @@
+import type {
+  SignalHandler,
+  SignalSource,
+  SystemSignal,
+  Unsubscribe,
+} from "./signal-source.types.js";
+
+/** A {@link SignalSource} with the bell a test rings. */
+export interface FakeSignals extends SignalSource {
+  /** Deliver `signal` to everyone still listening for it. */
+  raise(signal: SystemSignal): void;
+  /** Which signals are currently being listened for, for assertions. */
+  readonly listening: readonly SystemSignal[];
+}
+
+/**
+ * The double: a signal arrives because a test said so. No process, no operating
+ * system, no risk of stopping the test runner along with the code under test.
+ */
+export function createFakeSignals(): FakeSignals {
+  const handlers = new Map<SystemSignal, Set<SignalHandler>>();
+  return {
+    get listening() {
+      return [...handlers].filter(([, set]) => set.size > 0).map(([signal]) => signal);
+    },
+    on: (signal, handler) => subscribe({ handlers, signal, handler }),
+    raise: (signal) => {
+      for (const handler of [...(handlers.get(signal) ?? [])]) handler(signal);
+    },
+  };
+}
+
+function subscribe(args: {
+  handlers: Map<SystemSignal, Set<SignalHandler>>;
+  signal: SystemSignal;
+  handler: SignalHandler;
+}): Unsubscribe {
+  const set = args.handlers.get(args.signal) ?? new Set<SignalHandler>();
+  set.add(args.handler);
+  args.handlers.set(args.signal, set);
+  return () => {
+    set.delete(args.handler);
+  };
+}

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

@@ -0,0 +1,11 @@
+export { createFakeSignals, type FakeSignals } from "./fake-signals.js";
+export { SignalSourcePort } from "./signal-source.port.js";
+export {
+  ALL_SIGNALS,
+  type SignalHandler,
+  type SignalSource,
+  type SystemSignal,
+  type Unsubscribe,
+} from "./signal-source.types.js";
+// node-signals is deliberately absent: it lives behind @venn-lang/contracts/node, so
+// this barrel stays Worker-safe.