@lambdot/console 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.0
+
+### Patch Changes
+
+- Updated dependencies [[`71e5732`](https://github.com/Embers-of-the-Fire/lambdot/commit/71e57321ad4ec7d1aef3651d104123f8167ec2e7), [`71e5732`](https://github.com/Embers-of-the-Fire/lambdot/commit/71e57321ad4ec7d1aef3651d104123f8167ec2e7)]:
+  - @lambdot/core@0.2.0
+
+## 0.1.1
+
+### Patch Changes
+
+- [#10](https://github.com/Embers-of-the-Fire/lambdot/pull/10) [`19d37e4`](https://github.com/Embers-of-the-Fire/lambdot/commit/19d37e42c7a5514fb62c8f31c65e1aa01916d355) Thanks [@Embers-of-the-Fire](https://github.com/Embers-of-the-Fire)! - Switch inter-package dependency pins from exact versions to `workspace:*` so workspace members always resolve against local sources during development; pnpm rewrites the protocol to exact versions at pack/publish time.
+- Updated dependencies [[`19d37e4`](https://github.com/Embers-of-the-Fire/lambdot/commit/19d37e42c7a5514fb62c8f31c65e1aa01916d355)]:
+  - @lambdot/core@0.1.1
+
 ## [0.1.0](https://github.com/Embers-of-the-Fire/lambdot/compare/console-v0.0.1...console-v0.1.0) (2026-08-29)
 
 

package/README.md

@@ -0,0 +1,84 @@
+# @lambdot/console
+
+The reference chat platform: a terminal needs no external service, so the
+console is where the framework's contracts are exercised first. It exposes
+the `consolePlatform` bundle — an input plugin that turns stdin lines into
+a message stream and an output plugin that consumes a reply stream and
+writes plain text back to the terminal.
+
+## What it provides
+
+- **A line stream.** `consoleLines()` emits a `Stream<ConsoleLine>`, where
+  `ConsoleLine` is `Message<string, ConsoleAddress>` — one message per line
+  read from stdin, payload the line text, minted with `message(line, ...)`.
+  The address is `{ platform: "console", target: "stdout" }`. The stream is
+  shared (broadcast), so several consumers may each subscribe to it.
+- **An address type.** `ConsoleAddress extends Address<"console">` adds one
+  field, `target: "stdout" | "stderr"`. Replying to `message.address` writes
+  to stdout; constructing `{ platform: "console", target: "stderr" }`
+  redirects a reply to stderr.
+- **A reply contract.** `ConsoleReply` is `Command<ConsoleAddress, string>`
+  — content is plain text, written with a trailing newline. The printer
+  consumes a `Stream<ConsoleReply>`; because streams broadcast, one reply
+  stream can feed the printer and a logger side by side.
+
+## Usage
+
+```ts
+import { consolePlatform, type ConsoleLine } from "@lambdot/console";
+import type { Stream } from "@lambdot/core";
+import { createKernel, definePlugin, mapStream } from "@lambdot/core";
+
+const echo = definePlugin({
+    name: "echo",
+    apply(input: { "console/lines": Stream<ConsoleLine> }) {
+        return mapStream(input["console/lines"], (event) => ({
+            address: event.address,
+            content: `echo: ${event.payload}`,
+        }));
+    },
+});
+
+const cli = consolePlatform();
+
+const kernel = createKernel()
+    .use(cli.lines)
+    // identity wiring: echo's input keys already match the visible ctx
+    .use(echo)
+    .bind(cli.printer, { mapping: (ctx) => ({ replies: ctx.echo }) });
+
+await kernel.start();
+```
+
+The printer is terminal — it consumes a reply stream produced by later
+feature plugins — so it is wired last with an explicit `mapping` from the
+feature's namespace (`ctx.echo`) to the printer's declared input
+(`{ replies }`). Wiring the printer before the feature is a compile error:
+the `mapping` parameter is typed as the namespaces visible so far.
+
+## API
+
+- `consolePlatform(): ConsolePlatform` — builds both halves as
+  `{ lines, printer }`. The pair stays separate (rather than one fused
+  plugin) so feature plugins can be wired between them: the line source
+  first, the features next, the printer last.
+- `consoleLines()` — the input half, a `Plugin<void, Stream<ConsoleLine>, void, "console/lines">`.
+  Reads stdin through `node:readline/promises` with `terminal: false` (line
+  mode, no TTY echo handling); its disposer closes the readline interface
+  and the stream.
+- `consolePrinter()` — the output half, a
+  `Plugin<{ replies: Stream<ConsoleReply> }, void, void, "console/printer">`.
+  Pumps `replies` in the background; each command picks `process.stderr` or
+  `process.stdout` by `address.target` and writes `${content}\n`.
+- Types: `ConsoleAddress`, `ConsoleLine`, `ConsoleReply`, `ConsolePlatform`.
+
+## Examples
+
+- [echo-bot](../../../examples/echo-bot) — the echo bot above, plus
+  compile-time type tests for the composition wiring.
+- [multi-echo-bot](../../../examples/multi-echo-bot) — one echo feature
+  serving the console and a websocket platform side by side.
+
+## License
+
+Dual-licensed under [Apache-2.0](../../../LICENSE-APACHE) and [MIT](../../../LICENSE-MIT).

package/package.json

@@ -1,14 +1,19 @@
 {
-    "name": "@lambdot/console",
-    "version": "0.1.0",
-    "type": "module",
-    "exports": {
-        ".": "./src/index.ts"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "@lambdot/core": "workspace:*"
-    }
-}
+  "name": "@lambdot/console",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Embers-of-the-Fire/lambdot",
+    "directory": "packages/core/console"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lambdot/core": "0.2.0"
+  }
+}

package/src/index.ts

@@ -1,88 +1,90 @@
 import { createInterface } from "node:readline/promises";
 
-import type { Address, EventDef, InputPlugin, OutputContract, OutputPlugin } from "@lambdot/core";
+import type { Address, Command, Message, Plugin, Stream } from "@lambdot/core";
+import { channel, definePlugin, message, pumpStream, shareStream } from "@lambdot/core";
 
 /**
- * Where a console message goes. Owned by the output half of the console
- * platform pair — outputs consume addresses, inputs produce them.
+ * Where a console message goes. Owned by the printer half of the console
+ * platform — printers consume addresses, line sources produce them.
  */
 export interface ConsoleAddress extends Address<"console"> {
     readonly target: "stdout" | "stderr";
 }
 
-/** The console platform's output contract: plain text. */
-export type ConsoleOutputs = {
-    console: OutputContract<ConsoleAddress, string>;
-};
+/** One line read from stdin. */
+export type ConsoleLine = Message<string, ConsoleAddress>;
 
-/**
- * Events produced by the console input: one per line read from stdin.
- * A type alias (not an interface extending `EventMap`) so `keyof` stays
- * exactly these kinds — an interface extending `Record` would inherit a
- * string index signature and make every kind subscribable.
- */
-export type ConsoleEvents = {
-    "console.line": EventDef<string, ConsoleAddress>;
-};
+/** One line to print: plain text to a console target. */
+export type ConsoleReply = Command<ConsoleAddress, string>;
 
-/** The input half of the console platform: one `console.line` event per line read from stdin. */
-export function consoleInput(): InputPlugin<ConsoleEvents, void, "console-input"> {
-    return {
-        role: "input",
-        name: "console-input",
-        apply(ctx) {
+/** The input half of the console platform: a stream of lines read from stdin. */
+export function consoleLines(): Plugin<void, Stream<ConsoleLine>, void, "console/lines"> {
+    return definePlugin({
+        name: "console/lines",
+        apply(_input, scope) {
+            const lines = channel<ConsoleLine>();
             const rl = createInterface({ input: process.stdin, terminal: false });
             rl.on("line", (line) => {
-                void ctx.ingest("console.line", line, { platform: "console", target: "stdout" });
+                lines.push(message(line, { platform: "console", target: "stdout" }));
             });
-            return () => {
+            scope.onDispose(() => {
                 rl.close();
-            };
+                lines.close();
+            });
+            // Shared: several consumers (features, loggers, supervisors) may
+            // each subscribe to the line stream.
+            return shareStream(lines.stream);
         },
-    };
+    });
 }
 
-/** The output half of the console platform: writes plain text to stdout or stderr. */
-export function consoleOutput(): OutputPlugin<
-    "console",
-    ConsoleAddress,
-    string,
+/** The output half of the console platform: prints a reply stream to stdout/stderr. */
+export function consolePrinter(): Plugin<
+    { replies: Stream<ConsoleReply> },
     void,
-    "console-output"
+    void,
+    "console/printer"
 > {
-    return {
-        role: "output",
-        name: "console-output",
-        platform: "console",
-        send(to, content) {
-            const stream = to.target === "stderr" ? process.stderr : process.stdout;
-            stream.write(`${content}\n`);
+    return definePlugin({
+        name: "console/printer",
+        apply(input, scope) {
+            scope.onDispose(
+                pumpStream(
+                    input.replies,
+                    ({ address, content }) => {
+                        const stream =
+                            address.target === "stderr" ? process.stderr : process.stdout;
+                        stream.write(`${content}\n`);
+                    },
+                    (error) => scope.onError(error),
+                ),
+            );
         },
-    };
+    });
 }
 
 /**
- * One console platform, bundled: the stdin input and stdout/stderr output
- * halves. The pair stays separate (rather than one fused plugin) so the
- * type fold can keep enforcing registration order — input and output before
- * the feature plugins that consume them.
- *
+ * One console platform, bundled: the stdin line source and the stdout/stderr
+ * printer. The printer is terminal — it consumes a reply stream produced by
+ * later feature plugins, so it is wired last with a mapping:
+
  * ```ts
  * const cli = consolePlatform();
  * createKernel()
- *     .use(cli.input)
- *     .use(cli.output);
+ *     .use(cli.lines)
+ *     .use(echo)
+ *     .use(cli.printer, { mapping: (ctx) => ({ replies: ctx.echo }) });
  * ```
  */
 export interface ConsolePlatform {
-    readonly input: InputPlugin<ConsoleEvents, void, "console-input">;
-    readonly output: OutputPlugin<"console", ConsoleAddress, string, void, "console-output">;
+    readonly lines: Plugin<void, Stream<ConsoleLine>, void, "console/lines">;
+    readonly printer: Plugin<{ replies: Stream<ConsoleReply> }, void, void, "console/printer">;
 }
 
-/** Build a whole console platform (stdin input + stdout/stderr output). */
+/** Build a whole console platform (stdin lines + stdout/stderr printer). */
 export function consolePlatform(): ConsolePlatform {
     return {
-        input: consoleInput(),
-        output: consoleOutput(),
+        lines: consoleLines(),
+        printer: consolePrinter(),
     };
 }