@venn-lang/io 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+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,105 @@
+# @venn-lang/io
+
+> The `io` namespace: standard output, standard error, standard input and the process arguments.
+
+A Venn file is a program as often as it is a suite, and a program talks to the outside world through
+its console. This plugin names the parts of it that need naming, on top of the `Console` port. Plain
+`print` is in the prelude and needs no import; everything else is here.
+
+## Install
+
+`@venn-lang/io` is part of the stdlib the `venn` CLI and the language server load, so there is nothing to
+install. A file that uses it says so:
+
+```ruby
+use "venn/io"
+```
+
+The plugin declares `requires: ["io"]`. A host that offers no console (the Web Worker host behind
+the editor offers `fs`, `clock`, `random`, `secrets` and `log`) refuses it at load time with
+`VN2010`, rather than failing with a `TypeError` halfway through a run.
+
+## Usage
+
+```ruby
+# greet.vn, run with `venn run greet.vn Ada`
+use "venn/io"
+
+const argv = io.args
+io.print "arguments: ${argv}"
+
+io.write "name? "
+const name = io.readLine
+if name == null {
+  io.eprint "no name on standard input"
+  exit 1
+}
+
+io.print "hello, ${name}"
+```
+
+## Verbs
+
+| Verb | Signature | What it does |
+| --- | --- | --- |
+| `io.print` | `(...dynamic) -> void` | Writes to standard output with a newline. The same as the prelude's `print`. |
+| `io.write` | `(dynamic) -> void` | Writes to standard output with nothing added after it. |
+| `io.eprint` | `(dynamic) -> void` | Writes to standard error, followed by a newline. |
+| `io.readLine` | `() -> string \| null` | The next line of standard input, or `null` at end of input. |
+| `io.args` | `() -> list<string>` | The command-line arguments passed to the script. |
+
+`io.print` takes as many values as you like and joins them with a space. Strings are written as
+they are; anything else is rendered as JSON, so a map never prints as `[object Object]`.
+
+`readLine` returns a union with `null` in its signature, not a bare `string`: end of input is a real
+answer and a caller has to face it. `args` returns a `list<string>` rather than a bare list, so
+`argv.len` and the rest of the list methods type correctly.
+
+Arguments reach `io.args` from the command line: `venn run greet.vn Ada` gives `["Ada"]`.
+
+## The Console port
+
+The verbs above are a thin layer over one port, which lives in
+[`@venn-lang/contracts`](../contracts) because a console is a host capability like the filesystem or the
+clock, not something this plugin owns.
+
+| | |
+| --- | --- |
+| Id | `venn.port.console` |
+| Version | `1` |
+| Requires | `io` |
+| Methods | `write`, `writeError`, `readLine`, `args` |
+
+Two implementations ship with it, and both pass the same conformance suite: `createNodeConsole` from
+`@venn-lang/contracts/node`, which writes to Node's real streams and opens stdin lazily on the first
+`readLine`, and `createMemoryConsole`, which records instead of printing and reads from a scripted
+input. `venn run` binds the real one, with the command line's arguments; a test binds the recorder
+and reads back exactly what the program wrote:
+
+```ts
+import { createMemoryConsole } from "@venn-lang/io";
+
+const console = createMemoryConsole({ input: ["Ada"], argv: ["--name", "ada"] });
+
+console.write(">");
+console.out; // ">"
+await console.readLine(); // "Ada"
+await console.readLine(); // null
+console.args(); // ["--name", "ada"]
+```
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `ioPlugin` (also the default export) | The `PluginDefinition`: namespace `io`, requires the `io` capability, five actions, no types. |
+| `consoleActions` | The five `ActionDefinition`s, in the order listed above. |
+| `ConsolePort` | The port descriptor, re-exported from `@venn-lang/contracts`. |
+| `Console` | The port's interface (type only). |
+| `createMemoryConsole` | The recording implementation, for tests. |
+
+## See also
+
+- [`@venn-lang/contracts`](../contracts) for the port, its Node implementation and the host capabilities.
+- [`@venn-lang/fmt`](../std-fmt) for turning a value into the text you print.
+- [`@venn-lang/cli`](../cli) for `venn run`, which binds the real console and passes the arguments in.

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { ActionDefinition, PluginDefinition } from "@venn-lang/sdk";
+import { Console, ConsolePort, createMemoryConsole } from "@venn-lang/contracts";
+//#region src/actions/console-actions.d.ts
+/**
+ * The verbs of the `io` namespace: standard output, standard error, standard
+ * input and the process arguments.
+ *
+ * Plain `print` is in the prelude and needs no import. `io.print` is the same
+ * verb under its full name, so a script that imports the namespace reads the
+ * same either way.
+ */
+declare const consoleActions: ActionDefinition[];
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `io` plugin: a script's standard input, standard output and arguments.
+ *
+ * Requires the host capability `io`. Where the host has no real console streams
+ * the plugin refuses to load with a readable diagnostic, rather than failing
+ * mid-run.
+ */
+declare const ioPlugin: PluginDefinition;
+//#endregion
+export { type Console, ConsolePort, consoleActions, createMemoryConsole, ioPlugin as default, ioPlugin };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/actions/console-actions.ts","../src/plugin.ts"],"mappings":";;;;;;;;;;;cA2Ba,gBAAgB;;;;;;;;;;cCjBhB,UAAU"}

package/dist/index.js

@@ -0,0 +1,80 @@
+import { arg, defineAction, definePlugin, restArg } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { ConsolePort, createMemoryConsole } from "@venn-lang/contracts";
+//#region src/actions/console-actions.ts
+/** How a printed value becomes text: strings as-is, everything else as JSON. */
+function display(value) {
+	if (typeof value === "string") return value;
+	if (value === null || typeof value !== "object") return String(value);
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+function line(args) {
+	return args.map(display).join(" ");
+}
+/**
+* The verbs of the `io` namespace: standard output, standard error, standard
+* input and the process arguments.
+*
+* Plain `print` is in the prelude and needs no import. `io.print` is the same
+* verb under its full name, so a script that imports the namespace reads the
+* same either way.
+*/
+const consoleActions = [
+	defineAction({
+		name: "print",
+		doc: "Write to standard output with a newline. Same as the prelude's `print`.",
+		args: [restArg("values", t.dynamic, "Anything, as many as you like.")],
+		result: t.void,
+		run: (ctx, input) => ctx.port(ConsolePort).write(`${line(input.args)}\n`)
+	}),
+	defineAction({
+		name: "write",
+		doc: "Write to standard output with no trailing newline.",
+		args: [arg("value", t.dynamic, "What to write. Nothing is added after it.")],
+		result: t.void,
+		run: (ctx, input) => ctx.port(ConsolePort).write(line(input.args))
+	}),
+	defineAction({
+		name: "eprint",
+		doc: "Write to standard error, followed by a newline.",
+		args: [arg("value", t.dynamic, "What to write to stderr.")],
+		result: t.void,
+		run: (ctx, input) => ctx.port(ConsolePort).writeError(`${line(input.args)}\n`)
+	}),
+	defineAction({
+		name: "readLine",
+		doc: "Read the next line from standard input, or null at end of input.",
+		result: t.union(t.string, t.null),
+		run: (ctx) => ctx.port(ConsolePort).readLine()
+	}),
+	defineAction({
+		name: "args",
+		doc: "The command-line arguments passed to the script.",
+		result: t.list(t.string),
+		run: (ctx) => [...ctx.port(ConsolePort).args()]
+	})
+];
+//#endregion
+//#region src/plugin.ts
+/**
+* The `io` plugin: a script's standard input, standard output and arguments.
+*
+* Requires the host capability `io`. Where the host has no real console streams
+* the plugin refuses to load with a readable diagnostic, rather than failing
+* mid-run.
+*/
+const ioPlugin = definePlugin({
+	name: "venn/io",
+	version: "0.0.0",
+	namespace: "io",
+	requires: ["io"],
+	actions: consoleActions
+});
+//#endregion
+export { ConsolePort, consoleActions, createMemoryConsole, ioPlugin as default, ioPlugin };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/actions/console-actions.ts","../src/plugin.ts"],"sourcesContent":["import { type ActionDefinition, arg, defineAction, restArg } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { ConsolePort } from \"../port/index.js\";\n\n/** How a printed value becomes text: strings as-is, everything else as JSON. */\nfunction display(value: unknown): string {\n  if (typeof value === \"string\") return value;\n  if (value === null || typeof value !== \"object\") return String(value);\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return String(value);\n  }\n}\n\nfunction line(args: readonly unknown[]): string {\n  return args.map(display).join(\" \");\n}\n\n/**\n * The verbs of the `io` namespace: standard output, standard error, standard\n * input and the process arguments.\n *\n * Plain `print` is in the prelude and needs no import. `io.print` is the same\n * verb under its full name, so a script that imports the namespace reads the\n * same either way.\n */\nexport const consoleActions: ActionDefinition[] = [\n  defineAction({\n    name: \"print\",\n    doc: \"Write to standard output with a newline. Same as the prelude's `print`.\",\n    args: [restArg(\"values\", t.dynamic, \"Anything, as many as you like.\")],\n    result: t.void,\n    run: (ctx, input) => ctx.port(ConsolePort).write(`${line(input.args)}\\n`),\n  }),\n  defineAction({\n    name: \"write\",\n    doc: \"Write to standard output with no trailing newline.\",\n    args: [arg(\"value\", t.dynamic, \"What to write. Nothing is added after it.\")],\n    result: t.void,\n    run: (ctx, input) => ctx.port(ConsolePort).write(line(input.args)),\n  }),\n  defineAction({\n    name: \"eprint\",\n    doc: \"Write to standard error, followed by a newline.\",\n    args: [arg(\"value\", t.dynamic, \"What to write to stderr.\")],\n    result: t.void,\n    run: (ctx, input) => ctx.port(ConsolePort).writeError(`${line(input.args)}\\n`),\n  }),\n  defineAction({\n    name: \"readLine\",\n    doc: \"Read the next line from standard input, or null at end of input.\",\n    result: t.union(t.string, t.null),\n    run: (ctx) => ctx.port(ConsolePort).readLine(),\n  }),\n  defineAction({\n    name: \"args\",\n    doc: \"The command-line arguments passed to the script.\",\n    result: t.list(t.string),\n    run: (ctx) => [...ctx.port(ConsolePort).args()],\n  }),\n];\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { consoleActions } from \"./actions/console-actions.js\";\n\n/**\n * The `io` plugin: a script's standard input, standard output and arguments.\n *\n * Requires the host capability `io`. Where the host has no real console streams\n * the plugin refuses to load with a readable diagnostic, rather than failing\n * mid-run.\n */\nexport const ioPlugin: PluginDefinition = definePlugin({\n  name: \"venn/io\",\n  version: \"0.0.0\",\n  namespace: \"io\",\n  requires: [\"io\"],\n  actions: consoleActions,\n});\n"],"mappings":";;;;;AAKA,SAAS,QAAQ,OAAwB;CACvC,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU,OAAO,OAAO,KAAK;CACpE,IAAI;EACF,OAAO,KAAK,UAAU,KAAK;CAC7B,QAAQ;EACN,OAAO,OAAO,KAAK;CACrB;AACF;AAEA,SAAS,KAAK,MAAkC;CAC9C,OAAO,KAAK,IAAI,OAAO,CAAC,CAAC,KAAK,GAAG;AACnC;;;;;;;;;AAUA,MAAa,iBAAqC;CAChD,aAAa;EACX,MAAM;EACN,KAAK;EACL,MAAM,CAAC,QAAQ,UAAU,EAAE,SAAS,gCAAgC,CAAC;EACrE,QAAQ,EAAE;EACV,MAAM,KAAK,UAAU,IAAI,KAAK,WAAW,CAAC,CAAC,MAAM,GAAG,KAAK,MAAM,IAAI,EAAE,GAAG;CAC1E,CAAC;CACD,aAAa;EACX,MAAM;EACN,KAAK;EACL,MAAM,CAAC,IAAI,SAAS,EAAE,SAAS,2CAA2C,CAAC;EAC3E,QAAQ,EAAE;EACV,MAAM,KAAK,UAAU,IAAI,KAAK,WAAW,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC;CACnE,CAAC;CACD,aAAa;EACX,MAAM;EACN,KAAK;EACL,MAAM,CAAC,IAAI,SAAS,EAAE,SAAS,0BAA0B,CAAC;EAC1D,QAAQ,EAAE;EACV,MAAM,KAAK,UAAU,IAAI,KAAK,WAAW,CAAC,CAAC,WAAW,GAAG,KAAK,MAAM,IAAI,EAAE,GAAG;CAC/E,CAAC;CACD,aAAa;EACX,MAAM;EACN,KAAK;EACL,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI;EAChC,MAAM,QAAQ,IAAI,KAAK,WAAW,CAAC,CAAC,SAAS;CAC/C,CAAC;CACD,aAAa;EACX,MAAM;EACN,KAAK;EACL,QAAQ,EAAE,KAAK,EAAE,MAAM;EACvB,MAAM,QAAQ,CAAC,GAAG,IAAI,KAAK,WAAW,CAAC,CAAC,KAAK,CAAC;CAChD,CAAC;AACH;;;;;;;;;;ACnDA,MAAa,WAA6B,aAAa;CACrD,MAAM;CACN,SAAS;CACT,WAAW;CACX,UAAU,CAAC,IAAI;CACf,SAAS;AACX,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@venn-lang/io",
+  "version": "0.1.0",
+  "description": "The io namespace: standard output, standard error, standard input and the process arguments.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "io"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-io#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-io"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/contracts": "0.1.0",
+    "@venn-lang/sdk": "0.1.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "@fast-check/vitest": "^0.4.1",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions/console-actions.ts

@@ -0,0 +1,62 @@
+import { type ActionDefinition, arg, defineAction, restArg } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { ConsolePort } from "../port/index.js";
+
+/** How a printed value becomes text: strings as-is, everything else as JSON. */
+function display(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === null || typeof value !== "object") return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function line(args: readonly unknown[]): string {
+  return args.map(display).join(" ");
+}
+
+/**
+ * The verbs of the `io` namespace: standard output, standard error, standard
+ * input and the process arguments.
+ *
+ * Plain `print` is in the prelude and needs no import. `io.print` is the same
+ * verb under its full name, so a script that imports the namespace reads the
+ * same either way.
+ */
+export const consoleActions: ActionDefinition[] = [
+  defineAction({
+    name: "print",
+    doc: "Write to standard output with a newline. Same as the prelude's `print`.",
+    args: [restArg("values", t.dynamic, "Anything, as many as you like.")],
+    result: t.void,
+    run: (ctx, input) => ctx.port(ConsolePort).write(`${line(input.args)}\n`),
+  }),
+  defineAction({
+    name: "write",
+    doc: "Write to standard output with no trailing newline.",
+    args: [arg("value", t.dynamic, "What to write. Nothing is added after it.")],
+    result: t.void,
+    run: (ctx, input) => ctx.port(ConsolePort).write(line(input.args)),
+  }),
+  defineAction({
+    name: "eprint",
+    doc: "Write to standard error, followed by a newline.",
+    args: [arg("value", t.dynamic, "What to write to stderr.")],
+    result: t.void,
+    run: (ctx, input) => ctx.port(ConsolePort).writeError(`${line(input.args)}\n`),
+  }),
+  defineAction({
+    name: "readLine",
+    doc: "Read the next line from standard input, or null at end of input.",
+    result: t.union(t.string, t.null),
+    run: (ctx) => ctx.port(ConsolePort).readLine(),
+  }),
+  defineAction({
+    name: "args",
+    doc: "The command-line arguments passed to the script.",
+    result: t.list(t.string),
+    run: (ctx) => [...ctx.port(ConsolePort).args()],
+  }),
+];

package/src/index.ts

@@ -0,0 +1,5 @@
+// The `io` namespace: standard input, standard error and process arguments.
+// Plain `print` needs no import: it is in the prelude.
+export { consoleActions } from "./actions/console-actions.js";
+export { ioPlugin, ioPlugin as default } from "./plugin.js";
+export { type Console, ConsolePort, createMemoryConsole } from "./port/index.js";

package/src/plugin.ts

@@ -0,0 +1,17 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { consoleActions } from "./actions/console-actions.js";
+
+/**
+ * The `io` plugin: a script's standard input, standard output and arguments.
+ *
+ * Requires the host capability `io`. Where the host has no real console streams
+ * the plugin refuses to load with a readable diagnostic, rather than failing
+ * mid-run.
+ */
+export const ioPlugin: PluginDefinition = definePlugin({
+  name: "venn/io",
+  version: "0.0.0",
+  namespace: "io",
+  requires: ["io"],
+  actions: consoleActions,
+});

package/src/port/index.ts

@@ -0,0 +1,3 @@
+// The Console port lives in @venn-lang/contracts: it is a host capability like the
+// file system or the clock, not something this plugin owns.
+export { type Console, ConsolePort, createMemoryConsole } from "@venn-lang/contracts";