@vrtmrz/livesync-commonlib 0.1.0-rc.0 → 0.1.0-rc.1

package/README.md

@@ -36,6 +36,20 @@ await storage.write('notes/example.md', '# Example');
 
 See [the platform storage contract](docs/platform-storage.md) for path, ownership, and permission details.
 
+## Standard input and output
+
+CLI hosts can inject the platform-neutral `StandardIo` contract from the context entry. The Node entry supplies the concrete stream adapter. This keeps command input and protocol output testable without treating logging or process lifecycle as standard I/O.
+
+```ts
+import type { StandardIo } from '@vrtmrz/livesync-commonlib/context';
+import { createNodeStandardIo } from '@vrtmrz/livesync-commonlib/node';
+
+const standardIo: StandardIo = createNodeStandardIo();
+standardIo.writeStdout('ready\n');
+```
+
+See [the standard-I/O contract](docs/platform-standard-io.md) for host composition and test-double examples.
+
 ## API status
 
 The package is currently an infrastructure and compatibility boundary. `DirectFileManipulator` is useful for existing integrations, but its enumeration, watch ownership, failure, conflict, concurrency, and disposal semantics are not yet a stable high-level SDK contract.

package/dist/context.d.ts

@@ -6,3 +6,4 @@
 export { ServiceContext, createServiceContext, type ServiceContextContract, type ServiceContextOptions, } from "./services/base/ServiceBase.js";
 export { createLiveSyncEventHub, type LiveSyncEventHub } from "./hub/hub.js";
 export { passthroughMessageTranslator, type MessageTranslator, type TranslationParameters, } from "./services/base/MessageTranslator.js";
+export type { StandardIo, StandardIoChunk } from "./platform/standardIo.js";

package/dist/platform/node/index.d.ts

@@ -21,3 +21,4 @@ export declare const builtinModules: readonly string[];
 /** Returns whether a module specifier refers to a Node built-in. */
 export declare const isBuiltin: typeof nodeIsBuiltin;
 export { NodeStorageAdapter, createNodeStorage, validateStoragePath, type CreateNodeStorageOptions, type NodeStorageStat, } from "./storage.js";
+export { createNodeStandardIo, type CreateNodeStandardIoOptions, type NodeStandardInput, type NodeStandardOutput, } from "./standardIo.js";

package/dist/platform/node/index.js

@@ -17,9 +17,13 @@ import {
   createNodeStorage,
   validateStoragePath
 } from "./storage.js";
+import {
+  createNodeStandardIo
+} from "./standardIo.js";
 export {
   NodeStorageAdapter,
   builtinModules,
+  createNodeStandardIo,
   createNodeStorage,
   fileURLToPath,
   fs,

package/dist/platform/node/standardIo.d.ts

@@ -0,0 +1,24 @@
+import type { StandardIo, StandardIoChunk } from "../standardIo.js";
+/** Minimal readable stream shape accepted by the Node standard-I/O adapter. */
+export type NodeStandardInput = AsyncIterable<unknown> & NodeJS.ReadableStream;
+/** Minimal writable stream shape accepted by the Node standard-I/O adapter. */
+export interface NodeStandardOutput extends NodeJS.WritableStream {
+    write(chunk: StandardIoChunk): boolean;
+}
+/** Streams used by {@link createNodeStandardIo}. */
+export interface CreateNodeStandardIoOptions {
+    /** Defaults to `process.stdin`. */
+    stdin?: NodeStandardInput;
+    /** Defaults to `process.stdout`. */
+    stdout?: NodeStandardOutput;
+    /** Defaults to `process.stderr`. */
+    stderr?: NodeStandardOutput;
+}
+/**
+ * Bind the host-neutral standard-I/O contract to Node streams.
+ *
+ * Supplying streams is useful for embedded command-line hosts and tests. The
+ * caller owns stream lifecycle; this adapter only closes the temporary
+ * readline interface created by {@link StandardIo.prompt}.
+ */
+export declare function createNodeStandardIo(options?: CreateNodeStandardIoOptions): StandardIo;

package/dist/platform/node/standardIo.js

@@ -0,0 +1,39 @@
+import * as nodeReadlinePromises from "node:readline/promises";
+function createNodeStandardIo(options = {}) {
+  const stdin = options.stdin ?? process.stdin;
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  return {
+    async readStdin() {
+      const decoder = new TextDecoder();
+      let content = "";
+      for await (const chunk of stdin) {
+        if (typeof chunk === "string") {
+          content += chunk;
+        } else if (chunk instanceof Uint8Array) {
+          content += decoder.decode(chunk, { stream: true });
+        } else {
+          throw new TypeError("Standard input yielded a value which is neither text nor binary data.");
+        }
+      }
+      return content + decoder.decode();
+    },
+    async prompt(question) {
+      const readline = nodeReadlinePromises.createInterface({ input: stdin, output: stdout });
+      try {
+        return await readline.question(question);
+      } finally {
+        readline.close();
+      }
+    },
+    writeStdout(chunk) {
+      stdout.write(chunk);
+    },
+    writeStderr(chunk) {
+      stderr.write(chunk);
+    }
+  };
+}
+export {
+  createNodeStandardIo
+};

package/dist/platform/standardIo.d.ts

@@ -0,0 +1,19 @@
+/** A chunk written to standard output or standard error. */
+export type StandardIoChunk = string | Uint8Array;
+/**
+ * Host-provided standard input and output for a command-line composition.
+ *
+ * The contract deliberately excludes process lifecycle, logging policy, and
+ * terminal capability detection. Hosts own those concerns separately. None of
+ * the write operations add a newline implicitly.
+ */
+export interface StandardIo {
+    /** Read standard input to completion and decode it as UTF-8 text. */
+    readStdin(): Promise<string>;
+    /** Ask one line-oriented question and return the entered text. */
+    prompt(question: string): Promise<string>;
+    /** Write a text or binary chunk to standard output. */
+    writeStdout(chunk: StandardIoChunk): void;
+    /** Write a text or binary chunk to standard error. */
+    writeStderr(chunk: StandardIoChunk): void;
+}

package/docs/development.md

@@ -18,7 +18,8 @@ npm run test:package
 `test:contracts` runs the host-neutral result contracts which are intended to be reusable while implementations move:
 
 - `test:contract:context` verifies event delivery, default instance isolation, translation results, and host extension of `ServiceContextContract`; and
-- `test:contract:platform-storage` runs one result table against Node storage and browser File System Access storage, including missing paths, text and binary round trips, append, listing, removal, root handling, and traversal rejection.
+- `test:contract:platform-storage` runs one result table against Node storage and browser File System Access storage, including missing paths, text and binary round trips, append, listing, removal, root handling, and traversal rejection; and
+- `test:contract:standard-io` verifies the injectable contract, UTF-8 decoding across chunks, text and binary output, and line-oriented prompting through injected Node streams.
 
 These scripts are deliberately available independently of CI. Add a focused result contract before moving another platform API; do not infer compatibility from matching TypeScript shapes alone. Platform-specific behaviour, such as timestamp fidelity, must remain documented outside the shared result set.
 

package/docs/platform-standard-io.md

@@ -0,0 +1,44 @@
+# Standard input and output
+
+Commonlib defines a narrow `StandardIo` contract for command-line hosts. The contract covers standard input, line-oriented prompting, standard output, and standard error. It does not own process arguments, exit codes, signals, logging levels, or log persistence.
+
+## Host composition
+
+The host chooses and constructs the implementation, then places it on its host-specific Context or passes it to the command composition which owns it. The base `ServiceContext` does not require standard I/O because Obsidian, browser, and headless service compositions do not all have terminal streams.
+
+```ts
+import type { StandardIo } from '@vrtmrz/livesync-commonlib/context';
+import { createNodeStandardIo } from '@vrtmrz/livesync-commonlib/node';
+
+class CliContext {
+    constructor(readonly standardIo: StandardIo) {}
+}
+
+const context = new CliContext(createNodeStandardIo());
+```
+
+`createNodeStandardIo()` binds to `process.stdin`, `process.stdout`, and `process.stderr` by default. An embedding host may supply alternative Node streams. The host remains responsible for those streams and their lifecycle.
+
+## Output contract
+
+`writeStdout()` and `writeStderr()` accept text or `Uint8Array` chunks and do not add a newline. Commands must add delimiters required by their own text protocol. Binary command output must use `writeStdout()` directly without conversion through a logger.
+
+Diagnostic logging remains a separate capability. A host can render selected logs to standard error, but Commonlib does not make a Logger part of `StandardIo` and does not interpret log levels in this adapter.
+
+## Tests and embedded hosts
+
+Consumers can inject a small memory implementation without replacing process globals:
+
+```ts
+import type { StandardIo, StandardIoChunk } from '@vrtmrz/livesync-commonlib/context';
+
+const stdout: StandardIoChunk[] = [];
+const io: StandardIo = {
+    readStdin: async () => 'input',
+    prompt: async () => 'answer',
+    writeStdout: (chunk) => stdout.push(chunk),
+    writeStderr: () => undefined,
+};
+```
+
+This boundary lets a command test assert exact protocol bytes, prompts, and errors while the real Node adapter is verified separately against injected streams.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.0-rc.0",
+  "version": "0.1.0-rc.1",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",