@pencere/cli 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@pencere/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Run an MCP server written in any language as a pencere program, so its MCP App view opens in the terminal pane",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/bateri/pencere/tree/main/cli#readme",
+  "bugs": "https://github.com/bateri/pencere/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bateri/pencere.git",
+    "directory": "cli"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-apps",
+    "terminal",
+    "pencere",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "pencere": "./dist/main.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "NOTICE"
+  ],
+  "scripts": {
+    "prepack": "rm -rf dist tsconfig.tsbuildinfo && tsc -b"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@modelcontextprotocol/server": "^2.3.1",
+    "@pencere/sdk": "^0.1.0"
+  }
+}

package/src/args.ts

@@ -0,0 +1,158 @@
+/**
+ * The command line: `pencere run [options] -- <command> [args...]` and
+ * `pencere dev [options] -- <command> [args...]`.
+ *
+ * Everything after the first `--` is the server's command, taken as it is: a
+ * server's own flags are not pencere's to read. What comes before it is read with
+ * `node:util`'s `parseArgs`, strictly, so a mistyped option is an error and not a
+ * flag handed to nobody.
+ */
+
+import { parseArgs } from "node:util";
+
+export const USAGE = `\
+usage: pencere run [options] -- <command> [args...]
+       pencere dev [options] -- <command> [args...]
+
+run: runs <command>, an MCP server that speaks stdio and is written in any
+language, and shows its view in this terminal pane. The server is started as an
+MCP client would start it, so it is the same server an MCP Apps host runs.
+
+  pencere run -- python server.py
+  pencere run --tool list_containers --view ./view -- node dist/server.js
+
+dev: the same, and the view is shown again when its files change (--view) or
+when the server's own files do (--watch): the view closes, the server is
+started again and the view opens again, with only the files that changed sent.
+
+  pencere dev --view dist/view -- node dist/server.js
+  pencere dev --watch server.py -- python server.py
+
+A server that ends while dev runs (a mistake saved in it) is told of, with the end
+of what it wrote to stderr, and tried again at the next change; ^C ends dev.
+
+options:
+  --tool <name>   the tool whose view to show; without it, the one tool of the
+                  server that names a view (_meta.ui.resourceUri)
+  --args <json>   the arguments the tool is called with, a JSON object
+  --view <dir>    show the view from the files in <dir> (sent to the terminal
+                  once, then kept by content) instead of the server's own
+                  ui:// resource
+  --watch <path>  dev only, repeatable: a file or directory whose change starts
+                  the server and the view again; --view's directory is watched
+                  already, and one of --view and --watch is needed
+  -h, --help      this text
+  -v, --version   the version of pencere
+
+exit status: 0 the view ran and closed; 1 it could not run (the server failed to
+start or ended, the terminal refused or ended the view, or stopped answering
+while the view was shown again); 2 a mistake in the command line; 3 this terminal
+does not show pencere views; 130, 143 and 129 after ^C, SIGTERM and a hangup.
+`;
+
+/** The server to run and the view to show, which `run` and `dev` are both given. */
+export interface Launch {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly tool?: string;
+  readonly arguments?: Record<string, unknown>;
+  readonly view?: string;
+}
+
+/** What the command line asks for. */
+export type Command =
+  | { readonly kind: "help" }
+  | { readonly kind: "version" }
+  | ({ readonly kind: "run" } & Launch)
+  | ({
+      readonly kind: "dev";
+      /** The files whose change starts the server and the view again, besides the view's directory. */
+      readonly watch: readonly string[];
+    } & Launch);
+
+/** A mistake in the command line: what it is, so that the person can fix it. */
+export class UsageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UsageError";
+  }
+}
+
+/** The arguments of a tool call: one JSON object. */
+function toolArguments(text: string): Record<string, unknown> {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new UsageError(`--args is not JSON: ${error instanceof Error ? error.message : error}`);
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new UsageError("--args must be a JSON object");
+  return value as Record<string, unknown>;
+}
+
+const COMMANDS = "use `pencere run [options] -- <command> [args...]` or `pencere dev ...`";
+
+/** @throws {UsageError} for anything that is not a command of pencere. */
+export function parse(argv: readonly string[]): Command {
+  const [name, ...rest] = argv;
+  if (name === undefined) throw new UsageError(`no command: ${COMMANDS}`);
+  if (name === "-h" || name === "--help" || name === "help") return { kind: "help" };
+  if (name === "-v" || name === "--version") return { kind: "version" };
+  if (name !== "run" && name !== "dev")
+    throw new UsageError(`unknown command "${name}": ${COMMANDS}`);
+
+  // The server's command is everything after the first `--`.
+  const dash = rest.indexOf("--");
+  const own = dash === -1 ? rest : rest.slice(0, dash);
+  let parsed: ReturnType<typeof parseOwn>;
+  try {
+    parsed = parseOwn(own);
+  } catch (error) {
+    throw new UsageError(error instanceof Error ? error.message : String(error));
+  }
+  const { values, positionals } = parsed;
+  if (values.help === true) return { kind: "help" };
+  const [stray] = positionals;
+  if (stray !== undefined)
+    throw new UsageError(`unexpected "${stray}": the server's command goes after --`);
+  if (dash === -1) throw new UsageError("no command: put the server's command after --");
+  const [command, ...args] = rest.slice(dash + 1);
+  if (command === undefined || command === "") throw new UsageError("no command after --");
+  for (const option of ["tool", "view"] as const)
+    if (values[option] === "") throw new UsageError(`--${option} needs a value`);
+  const watch = values.watch ?? [];
+  if (watch.includes("")) throw new UsageError("--watch needs a value");
+  const launch: Launch = {
+    command,
+    args,
+    ...(values.tool === undefined ? {} : { tool: values.tool }),
+    ...(values.args === undefined ? {} : { arguments: toolArguments(values.args) }),
+    ...(values.view === undefined ? {} : { view: values.view }),
+  };
+  if (name === "run") {
+    if (values.watch !== undefined)
+      throw new UsageError("--watch is for `pencere dev`: `pencere run` shows the view once");
+    return { kind: "run", ...launch };
+  }
+  if (launch.view === undefined && watch.length === 0)
+    throw new UsageError(
+      "nothing to watch: give --view <dir> for the view's files, or --watch <path> for the server's own",
+    );
+  return { kind: "dev", watch, ...launch };
+}
+
+function parseOwn(args: readonly string[]) {
+  return parseArgs({
+    args: [...args],
+    options: {
+      tool: { type: "string" },
+      args: { type: "string" },
+      view: { type: "string" },
+      watch: { type: "string", multiple: true },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: true,
+  });
+}

package/src/connector.ts

@@ -0,0 +1,107 @@
+/**
+ * The program's MCP server, stood in for by a process.
+ *
+ * `serve` of the SDK takes anything that can `connect` a transport and `close`
+ * the session, and does everything else of a pencere program: the question to the
+ * terminal, the token, the bundle, ⌃C and `bye`, the host starting the view again
+ * (§10.7) and the program reopening it (§10.8). It connects once for each view it
+ * opens. This is that server for a program that has none of its own: it starts the
+ * command for each connection and carries the JSON-RPC messages between the
+ * terminal's stream and the command's stdio, line by line, untouched. A server
+ * that has been connected to a view once has done its `initialize`; the next view
+ * is a new session, and so a new process, which is also what a stdio server
+ * expects: one `initialize` for the life of the process.
+ */
+
+import type { Transport } from "@modelcontextprotocol/server";
+import type { Connectable } from "@pencere/sdk";
+
+import { CLOSE_TIMING, ServerProcess } from "./server-process.js";
+import type { CloseTiming, Exit, ServerCommand } from "./server-process.js";
+import type { Tail } from "./tail.js";
+
+export interface ConnectorOptions {
+  /** What the server writes to stderr goes here, as do the connector's own notes on the stream. */
+  readonly tail: Tail;
+  /**
+   * The server's process ended, and the connector had not asked it to. The view
+   * has nothing to talk to any more: the caller ends it.
+   */
+  readonly unexpectedExit: (exit: Exit) => void;
+  readonly timing?: CloseTiming;
+}
+
+export class ProcessConnector implements Connectable {
+  readonly #spec: ServerCommand;
+  readonly #options: ConnectorOptions;
+  #current: { readonly server: ServerProcess; readonly transport: Transport } | undefined;
+  readonly #ending = new Set<Promise<void>>();
+  #starts = 0;
+
+  constructor(spec: ServerCommand, options: ConnectorOptions) {
+    this.#spec = spec;
+    this.#options = options;
+  }
+
+  /** How many processes this connector has started: one for each view that was opened. */
+  get starts(): number {
+    return this.#starts;
+  }
+
+  /** @throws {StartError} when the command cannot be started. */
+  async connect(transport: Transport): Promise<void> {
+    // One process for one session: the last is gone before the next begins.
+    await this.close();
+    const { tail, unexpectedExit, timing } = this.#options;
+    const server = new ServerProcess(this.#spec, tail, timing ?? CLOSE_TIMING);
+    server.onmessage = (message) => {
+      // A view that is gone has no use for the answer, and says so by failing here.
+      transport.send(message).catch(() => {});
+    };
+    server.onerror = (error) => tail.push(`pencere: ${error.message}\n`);
+    server.onexit = (exit) => {
+      if (!exit.expected) unexpectedExit(exit);
+    };
+    transport.onmessage = (message) => {
+      // A server that is gone cannot be written to, and says so by ending (`unexpectedExit`).
+      server.send(message).catch(() => {});
+    };
+    transport.onclose = () => {
+      void server.close();
+    };
+    try {
+      await transport.start();
+      await server.start();
+      this.#starts += 1;
+    } catch (error) {
+      transport.onmessage = undefined;
+      transport.onclose = undefined;
+      throw error;
+    }
+    this.#current = { server, transport };
+  }
+
+  /** Ends the process of the session that is connected, if there is one, and resolves when it is gone. */
+  async close(): Promise<void> {
+    const current = this.#current;
+    this.#current = undefined;
+    if (current === undefined) return;
+    const ending = current.server.close().then(() => current.transport.close());
+    this.#ending.add(ending);
+    try {
+      await ending;
+    } finally {
+      this.#ending.delete(ending);
+    }
+  }
+
+  /**
+   * Resolves when every process this connector started has ended. `serve` lets go of
+   * a session without waiting for it (a signal must not wait for a stubborn server),
+   * and a program that is about to leave has to.
+   */
+  async drain(): Promise<void> {
+    await this.close();
+    while (this.#ending.size > 0) await Promise.all([...this.#ending]);
+  }
+}

package/src/dev.ts

@@ -0,0 +1,303 @@
+/**
+ * `pencere dev`: what a change to the files comes to.
+ *
+ * `pencere run` shows a view once. `pencere dev` watches the files of the view and
+ * the files the server reads, and when they change it has the SDK close the view
+ * and open it again (`ViewControl.reopen`, specification §10.8): the old view and
+ * the server of its session are gone, the server is started again as for any view,
+ * and the new view's files are checked against what the terminal already holds,
+ * so only the files that changed cross the stream. Nothing of that is this file's:
+ * what is, is deciding *when*.
+ *
+ * - **A burst is one reopening.** A build writes many files; the change is acted
+ *   on once the files have been quiet for a moment (`settle`), and a change that
+ *   comes while a reopening is under way is acted on after it, again after a
+ *   moment of quiet.
+ * - **Only what changed.** A change to the view's directory is a reopening when
+ *   the files it holds are different from what the view shows (a file saved as it
+ *   was, or one that is not part of a view, changes nothing). A change to
+ *   `--watch`'s paths is a reopening when what the paths hold has moved (their
+ *   size or modification time): the events of one write that arrive late are not
+ *   a second write.
+ * - **A half-built view waits.** A build that has emptied its output directory
+ *   leaves something that is not a view; that is not shown, and the next change,
+ *   which is the build writing more, is looked at in its turn.
+ * - **A view that is not there yet waits too.** A change that comes before the
+ *   first view is up is asked again a few times, a moment apart.
+ *
+ * What the person gets to know is said after the view has closed (`notes`): the
+ * screen is the view's while it is up. A `serve` that ended because the program ended it
+ * (its server fell) is not the end of the reloading: the program starts `serve` again, and
+ * the next change is what it waits for.
+ */
+
+import { BundleError, bundleFromDirectory } from "@pencere/sdk";
+import type { Bundle, ReopenOptions, ReopenResult } from "@pencere/sdk";
+
+/** How long `Reloader` waits, and how often it asks again. */
+export interface ReloadTiming {
+  /** The quiet, in milliseconds, after which the changes so far are acted on. */
+  readonly settle: number;
+  /** How long to wait, in milliseconds, before asking again for a view that is not up yet. */
+  readonly retry: number;
+  /** How many times to ask again before leaving the change for the next one to carry. */
+  readonly tries: number;
+}
+
+/** What `Reloader` needs of the program's hand on its view: `ViewControl`'s `reopen`. */
+export interface Reopener {
+  reopen(next: ReopenOptions): Promise<ReopenResult>;
+}
+
+export interface ReloaderOptions {
+  readonly control: Reopener;
+  /** The directory the view's files are in (`--view`), absent when the terminal reads the server's own resource. */
+  readonly view?: string;
+  /** What the view was first opened with. */
+  readonly bundle?: Bundle;
+  /** What the server's own files (`--watch`) hold, in a form that changes when they do. Without it every change to them counts. */
+  readonly fingerprint?: () => Promise<string>;
+  readonly timing: ReloadTiming;
+  /** Reads the view's files. `bundleFromDirectory`, unless a test lends another. */
+  readonly load?: (directory: string) => Promise<Bundle>;
+}
+
+/** What has changed since the last reopening. */
+interface Change {
+  /** Something under the view's directory. */
+  readonly view: boolean;
+  /** Something of the server's own files. */
+  readonly server: boolean;
+}
+
+function merged(a: Change | undefined, b: Change): Change {
+  return a === undefined ? b : { view: a.view || b.view, server: a.server || b.server };
+}
+
+/** Whether `bundle` holds the files `shown` does, byte for byte, under the same entry. */
+function sameFiles(bundle: Bundle, shown: Bundle | undefined): boolean {
+  return shown !== undefined && JSON.stringify(bundle.manifest) === JSON.stringify(shown.manifest);
+}
+
+function why(error: unknown): string {
+  if (error instanceof BundleError) return error.message;
+  const code = (error as NodeJS.ErrnoException | undefined)?.code;
+  if (code === "ENOENT") return "a file went away while it was read";
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Closes the view and opens it again when what it is made of, or the server, changed. */
+export class Reloader {
+  readonly #options: ReloaderOptions;
+  readonly #notes: string[] = [];
+  readonly #waiting: (() => void)[] = [];
+  /** The files the view shows now. */
+  #shown: Bundle | undefined;
+  /** What the server's files held when the view was last opened. */
+  #serverPrint: string | undefined;
+  /** Changes to act on once the files are quiet. */
+  #pending: Change | undefined;
+  /** Changes that could not be acted on, which the next change carries along. */
+  #held: Change | undefined;
+  #timer: ReturnType<typeof setTimeout> | undefined;
+  #running: Promise<void> | undefined;
+  #stopped = false;
+  #tries = 0;
+  /** Why the view's files could not be read at the last change, while that is so. */
+  #problem: string | undefined;
+  #reopened = 0;
+
+  constructor(options: ReloaderOptions) {
+    this.#options = options;
+    this.#shown = options.bundle;
+  }
+
+  /**
+   * Notes what the view's files and the server's own hold now, as the view that is about to open
+   * sees them, and says which view's files those are. Call once the files are being watched: what
+   * was saved before is in what is read, and what is saved after tells of itself, but a save in
+   * between, with the files read first and the watching begun after, would be neither. A view
+   * directory that cannot be read just then (a build that is half done) leaves what the reloader
+   * was given, and the change that made it unreadable is looked at in its turn.
+   */
+  async start(): Promise<Bundle | undefined> {
+    this.#serverPrint = await this.#options.fingerprint?.();
+    const { view } = this.#options;
+    if (view !== undefined) {
+      try {
+        this.#shown = await (this.#options.load ?? bundleFromDirectory)(view);
+      } catch {
+        // What it was given stays, and the next change looks again.
+      }
+    }
+    return this.#shown;
+  }
+
+  /** How many times the view has been reopened. */
+  get reopened(): number {
+    return this.#reopened;
+  }
+
+  /** What to tell the person once the view has closed. */
+  get notes(): readonly string[] {
+    const notes = [...this.#notes];
+    if (this.#problem !== undefined)
+      notes.push(
+        `the last change to the view's files could not be shown (${this.#problem}); the view is as the change before it left it`,
+      );
+    else if (this.#held !== undefined)
+      notes.push("the last change was not shown, because there was no view to show it in");
+    return notes;
+  }
+
+  /** Something under the view's directory changed. */
+  viewChanged(): void {
+    this.#note({ view: true, server: false });
+  }
+
+  /** Something of the server's own files changed. */
+  serverChanged(): void {
+    this.#note({ view: false, server: true });
+  }
+
+  /** Something to tell the person afterwards that is not a change: a watcher that failed. */
+  warn(text: string): void {
+    this.#notes.push(text);
+  }
+
+  /** No more reopenings: the view has ended, or cannot be reopened. */
+  stop(): void {
+    this.#stopped = true;
+    this.#disarm();
+    this.#pending = undefined;
+    this.#release();
+  }
+
+  /** Resolves when nothing is waiting to be acted on and nothing is being acted on. */
+  settled(): Promise<void> {
+    if (this.#idle()) return Promise.resolve();
+    return new Promise((resolve) => this.#waiting.push(resolve));
+  }
+
+  #idle(): boolean {
+    return this.#timer === undefined && this.#running === undefined && this.#pending === undefined;
+  }
+
+  #release(): void {
+    if (!this.#idle()) return;
+    for (const resolve of this.#waiting.splice(0)) resolve();
+  }
+
+  #note(change: Change): void {
+    if (this.#stopped) return;
+    // What could not be acted on before is carried along with this one.
+    const carried = merged(this.#pending, change);
+    this.#pending = this.#held === undefined ? carried : merged(carried, this.#held);
+    this.#held = undefined;
+    this.#tries = 0;
+    this.#arm(this.#options.timing.settle);
+  }
+
+  #arm(delay: number): void {
+    this.#disarm();
+    this.#timer = setTimeout(() => {
+      this.#timer = undefined;
+      this.#kick();
+    }, delay);
+  }
+
+  #disarm(): void {
+    if (this.#timer !== undefined) clearTimeout(this.#timer);
+    this.#timer = undefined;
+  }
+
+  #kick(): void {
+    if (this.#running !== undefined || this.#stopped) return;
+    this.#running = this.#pass().finally(() => {
+      this.#running = undefined;
+      // What came while this ran has had its moment of quiet only if nothing came since.
+      if (!this.#stopped && this.#pending !== undefined && this.#timer === undefined)
+        this.#arm(this.#options.timing.settle);
+      this.#release();
+    });
+  }
+
+  async #pass(): Promise<void> {
+    const change = this.#pending;
+    this.#pending = undefined;
+    if (change === undefined) return;
+    try {
+      await this.#act(change);
+    } catch (error) {
+      // Looking at the files must not end the view the person is looking at.
+      this.#notes.push(`could not look at the files: ${why(error)}`);
+    }
+  }
+
+  async #act(change: Change): Promise<void> {
+    const { view, fingerprint } = this.#options;
+
+    let serverPrint: string | undefined;
+    let serverMoved = false;
+    if (change.server) {
+      serverPrint = await fingerprint?.();
+      serverMoved = serverPrint === undefined || serverPrint !== this.#serverPrint;
+    }
+
+    let bundle: Bundle | undefined;
+    let viewMoved = false;
+    if (change.view && view !== undefined) {
+      try {
+        bundle = await (this.#options.load ?? bundleFromDirectory)(view);
+      } catch (error) {
+        // A build that is half done: the next change is the rest of it.
+        this.#problem = why(error);
+        this.#held = merged(this.#held, change);
+        return;
+      }
+      this.#problem = undefined;
+      viewMoved = !sameFiles(bundle, this.#shown);
+    }
+    if (!viewMoved && !serverMoved) return;
+
+    const result = await this.#options.control.reopen(
+      viewMoved && bundle !== undefined ? { bundle } : {},
+    );
+    switch (result.kind) {
+      case "reopened":
+        this.#reopened += 1;
+        if (viewMoved) this.#shown = bundle;
+        if (serverMoved) this.#serverPrint = serverPrint;
+        return;
+      case "unsupported":
+        this.#notes.push(
+          "this terminal does not reopen a view when asked, so `pencere dev` ran the view as `pencere run` does and the changes were not shown: close it and run it again to see them",
+        );
+        this.stop();
+        return;
+      case "no-view":
+        if (result.reason === "aborted") {
+          // `serve` was ended by the program's own hand, which is not the terminal refusing:
+          // the server fell, and what comes next is the program's to decide. The files that
+          // were asked for are what came of it, and the same files are not tried again.
+          if (viewMoved) this.#shown = bundle;
+          if (serverMoved) this.#serverPrint = serverPrint;
+          return;
+        }
+        // The new view was refused or could not start: `serve` says why as it ends.
+        this.stop();
+        return;
+      case "unavailable": {
+        const { retry, tries } = this.#options.timing;
+        if (this.#tries < tries) {
+          this.#tries += 1;
+          this.#pending = merged(this.#pending, change);
+          this.#arm(retry);
+        } else {
+          this.#held = merged(this.#held, change);
+        }
+        return;
+      }
+    }
+  }
+}