@pencere/cli 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to `@pencere/cli` are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the package follows
+[semantic versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-21
+
+### Added
+
+- `pencere run [--tool <name>] [--args <json>] [--view <dir>] -- <command> [args...]`: run an MCP
+  server that speaks stdio, written in any language, as a pencere program. The view opens in the
+  terminal pane `pencere run` runs in, and closes with ⌃C or when the view or the terminal ends
+  it. Without `--tool` the server is started once to ask which tool names a view; `--view` shows
+  the view from a directory's files, sent to the terminal once.
+- The server runs with the program's environment, in a process group of its own so that the
+  terminal's ⌃C reaches `pencere run` and not the server, and is ended by closing its stdin, then
+  SIGTERM and SIGKILL to its group. What it wrote to stderr is shown on the screen the person gets
+  back when it failed.
+- `pencere dev [--view <dir>] [--watch <path>]... [--tool <name>] [--args <json>] -- <command>
+[args...]`: `pencere run`, and when the files of the view (`--view`) or the files the server reads
+  (`--watch`, a file or a directory, as often as needed) change, the view closes, the server is
+  started again and the view opens again in the same pane. Changes that come together are one
+  reopening. The terminal keeps the view's files by content, so only the files that changed cross
+  the stream. A change that leaves the files as they were, or a build that has not finished writing
+  the view, shows nothing; a terminal that cannot reopen a view is told of once, after the view has
+  closed, and the view runs as it does under `pencere run`.
+- Exit status: 0 the view ran and closed, 1 it could not run, 2 a mistake in the command line,
+  3 the terminal does not show pencere views; ⌃C, SIGTERM and a hangup (SIGHUP, ssh going away) end
+  the view and the server, and then the process by the same signal (130, 143, 129). A terminal that
+  stopped answering while the view was shown again is a 1 with a message of its own, not a 3.
+- A server that ends while `pencere dev` runs (a mistake saved in it) is not the end of `pencere
+dev`: the terminal is given back, the end of what the server wrote to stderr is shown with what
+  happened, and the next change starts the server and the view again; ⌃C ends it. `pencere run`
+  still ends with the server.
+- Which tool to show is found as the terminal would find it: a tool names a view by a `ui://`
+  resource only, and the tool list is read a page at a time up to the terminal's limit of 16 pages.
+  What a server wrote (tool names, an error message) is shown as text.
+- A server that leaves on its own, at the end of its stdin or by falling, leaves what it started
+  behind in its group, and that is ended too (SIGTERM, then SIGKILL).
+- A terminal that goes away (ssh dropped) fails what is written to and read from it: that is not an
+  error that ends `pencere`, which is busy letting go of the server.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+pencere
+Copyright 2026 The pencere Authors

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# @pencere/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run an MCP server written in any language as a pencere program, so its MCP App view opens
+in the terminal pane you ran it in.
+
+```sh
+npx @pencere/cli run -- python server.py
+npx @pencere/cli dev --view dist/view -- node dist/server.js
+```
+
+[pencere](https://github.com/bateri/pencere) shows an MCP App view in the terminal pane a
+program runs in, on your machine or on a server over plain ssh. The program is an MCP server,
+and `@pencere/sdk` is how a TypeScript one asks the terminal for a view. `pencere run` is for
+every other server: Python, Go, Rust, a shell script, anything that speaks MCP over stdio. It
+runs the server as an MCP client would, talks pencere's protocol with the terminal, and carries
+the messages between the two. The server is the one you would give Claude Desktop or VS Code,
+unchanged. `pencere dev` is the same while you work on the view or the server: when their files
+change, the view is shown again.
+
+## Use
+
+```
+pencere run [options] -- <command> [args...]
+```
+
+Everything after `--` is the server's command, taken as it is.
+
+| Option            | What it does                                                                                                                                                                                                   |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--tool <name>`   | The tool whose view to show. Without it, `pencere run` starts the server once to ask (`initialize` and `tools/list`) and takes the one tool whose `_meta.ui.resourceUri` names a view.                         |
+| `--args <json>`   | The arguments the tool is called with, a JSON object.                                                                                                                                                          |
+| `--view <dir>`    | Show the view from the files in `<dir>` (it needs an `index.html`). They cross the terminal's stream once and the terminal keeps them by content. Without it the terminal reads the server's `ui://` resource. |
+| `-h`, `--help`    | Usage.                                                                                                                                                                                                         |
+| `-v`, `--version` | The version.                                                                                                                                                                                                   |
+
+The same options and exit status are `pencere dev`'s, which adds `--watch` (see below).
+
+If the server has no tool with a view, or several, `pencere run` says which tools there are
+and, for several, asks you to choose one with `--tool`. A tool names a view by a `ui://`
+resource, as the terminal reads it, and the tool list is read a page at a time as far as the
+terminal reads it (16 pages). What the server wrote is shown as text.
+
+A terminal that does not host pencere is told so: `pencere run` says that the command is an MCP
+server, which an MCP client can take as it is, and ends. A server is not a text interface, so it
+is not attached to the terminal, and with `--tool` it is not started for it at all (without
+`--tool` it was started once, to ask which tool has a view).
+
+### Exit status
+
+| Status                  | Meaning                                                                                                                                                                                                   |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`                     | The view ran and closed (you closed it, the view did, or the program did).                                                                                                                                |
+| `1`                     | It could not run: the server did not start, did not answer as an MCP server, or ended while its view was up; the terminal refused or ended the view, or stopped answering while the view was shown again. |
+| `2`                     | A mistake in the command line, or a `--view` directory that is not a view, or several tools with a view and no `--tool`.                                                                                  |
+| `3`                     | This terminal does not show pencere views, or the input or output of `pencere run` is not a terminal.                                                                                                     |
+| ⌃C, `SIGTERM`, a hangup | The view and the server are ended first, then `pencere run` ends by the same signal, so the shell reads 130, 143 or 129 (the terminal went away, as when ssh does).                                       |
+
+When the server fails, what it wrote to stderr is shown on the screen you get back. While a
+view is up the screen is the view's, so the end of it is kept (the last 16 KiB) and printed
+after the view has closed, as text.
+
+## Reloading with `pencere dev`
+
+```
+pencere dev [options] -- <command> [args...]
+```
+
+```sh
+pencere dev --view dist/view -- node dist/server.js     # a view that is built into dist/view
+pencere dev --watch server.py -- python server.py        # a server whose own files are the work
+```
+
+`pencere dev` is `pencere run`, and it watches files. When they change, the view in the pane
+closes, the server is started again, and the view opens again, in the same pane and without
+leaving the alternate screen. What the view held in its own memory is gone, as it is when the
+terminal reconnects: its state is rebuilt from the server's tool results, as at the first open.
+
+| Option           | What it watches                                                                                                                                         |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--view <dir>`   | The view's files. A change that leaves the files as they were (a save that wrote the same bytes) shows nothing; the terminal is sent only what changed. |
+| `--watch <path>` | A file or directory the server reads, as often as needed. A change to what it holds (size or modification time) starts the server and the view again.   |
+
+One of the two is needed. Names that begin with a dot, `node_modules` and `__pycache__` are not
+watched under a directory: a server that writes into a directory it is watched through would end
+every run with a change.
+
+- **A burst is one reopening.** A build writes many files; the view is reopened once they have
+  been quiet for a moment, and a change that comes while it is reopening is shown after it.
+- **A half-built view is not shown.** A build that has emptied its output directory and not yet
+  written `index.html` leaves something that is not a view. The change is looked at again at the
+  next one, which is the build writing more.
+- **The terminal does the swap.** The view is closed and opened by the terminal's own messages
+  (`dismiss`; specification §10.8), which is why this works when the server runs over plain ssh
+  and the terminal is on the other side: the files cross the stream, not a port. A terminal that
+  does not list `dismiss` in its `welcome` cannot reopen a view: `pencere dev` runs the view as
+  `pencere run` would, and says after the view has closed that the changes were not shown.
+- **What it tells you is told after.** While the view is up the screen is the view's, so notes
+  (a view that could not be read at the last change, a watch that failed) are printed on the
+  screen you get back, as the server's stderr is.
+- **A server that ends is waited out.** If the server exits while its view is up or opening, as
+  after a syntax error is saved, the view goes with it and the terminal is yours again: `pencere dev`
+  says that the server ended, shows the end of what it wrote to stderr, and waits. The next change
+  to the files it watches starts the server and the view again, and nothing has to be run twice.
+  A change that leaves the files as they were is not another try. ⌃C ends `pencere dev` as ever.
+  `pencere run`, which watches nothing, ends with the server.
+
+## How the server is run
+
+- **As an MCP client runs it.** The command is started with your whole environment and working
+  directory, with pipes for stdin and stdout; stdout carries one JSON-RPC message to a line.
+  Each view is a new MCP session and so a new process: a stdio server expects one `initialize`
+  for the life of its process, and a view that the terminal starts again (after a reconnection)
+  or that the program reopens gets a server of its own.
+- **In a process group of its own.** ⌃C is the terminal's signal to the foreground group, which
+  is `pencere run`'s. The server must not take it: `pencere run` ends it, after telling the
+  terminal the program is done. It closes the server's stdin first, which every stdio server
+  takes as the end, then sends SIGTERM and SIGKILL to the whole group, which catches what a
+  wrapper (`npx`, `uv run`, `sh -c`) started. A server that leaves at the end of its stdin, or
+  falls, leaves what it started behind in the group, and that gets the same two signals.
+- **Nothing else is added.** What the terminal asks (the question, the token, the bundle's
+  files, ⌃C and `bye`, starting the view again) is done by `@pencere/sdk`'s `serve`, which this
+  package runs; `pencere run` does not parse the server's messages.
+
+Node 22 or later is needed, on a system with `stty` (macOS, Linux): the SDK sets the terminal's
+modes with it, so Windows has no host as far as it is concerned.
+
+## Versions
+
+This release speaks version 1 of the pencere wire (a draft), through `@pencere/sdk`. The package
+follows semantic versioning; [CHANGELOG.md](CHANGELOG.md) says what each release changed.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

package/dist/args.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+export declare const USAGE = "usage: pencere run [options] -- <command> [args...]\n       pencere dev [options] -- <command> [args...]\n\nrun: runs <command>, an MCP server that speaks stdio and is written in any\nlanguage, and shows its view in this terminal pane. The server is started as an\nMCP client would start it, so it is the same server an MCP Apps host runs.\n\n  pencere run -- python server.py\n  pencere run --tool list_containers --view ./view -- node dist/server.js\n\ndev: the same, and the view is shown again when its files change (--view) or\nwhen the server's own files do (--watch): the view closes, the server is\nstarted again and the view opens again, with only the files that changed sent.\n\n  pencere dev --view dist/view -- node dist/server.js\n  pencere dev --watch server.py -- python server.py\n\nA server that ends while dev runs (a mistake saved in it) is told of, with the end\nof what it wrote to stderr, and tried again at the next change; ^C ends dev.\n\noptions:\n  --tool <name>   the tool whose view to show; without it, the one tool of the\n                  server that names a view (_meta.ui.resourceUri)\n  --args <json>   the arguments the tool is called with, a JSON object\n  --view <dir>    show the view from the files in <dir> (sent to the terminal\n                  once, then kept by content) instead of the server's own\n                  ui:// resource\n  --watch <path>  dev only, repeatable: a file or directory whose change starts\n                  the server and the view again; --view's directory is watched\n                  already, and one of --view and --watch is needed\n  -h, --help      this text\n  -v, --version   the version of pencere\n\nexit status: 0 the view ran and closed; 1 it could not run (the server failed to\nstart or ended, the terminal refused or ended the view, or stopped answering\nwhile the view was shown again); 2 a mistake in the command line; 3 this terminal\ndoes not show pencere views; 130, 143 and 129 after ^C, SIGTERM and a hangup.\n";
+/** 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 declare class UsageError extends Error {
+    constructor(message: string);
+}
+/** @throws {UsageError} for anything that is not a command of pencere. */
+export declare function parse(argv: readonly string[]): Command;

package/dist/args.js

@@ -0,0 +1,139 @@
+/**
+ * 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.
+`;
+/** A mistake in the command line: what it is, so that the person can fix it. */
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UsageError";
+    }
+}
+/** The arguments of a tool call: one JSON object. */
+function toolArguments(text) {
+    let value;
+    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;
+}
+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) {
+    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;
+    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"])
+        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 = {
+        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) {
+    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,
+    });
+}
+//# sourceMappingURL=args.js.map

package/dist/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}

package/dist/connector.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 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 declare class ProcessConnector implements Connectable {
+    #private;
+    constructor(spec: ServerCommand, options: ConnectorOptions);
+    /** How many processes this connector has started: one for each view that was opened. */
+    get starts(): number;
+    /** @throws {StartError} when the command cannot be started. */
+    connect(transport: Transport): Promise<void>;
+    /** Ends the process of the session that is connected, if there is one, and resolves when it is gone. */
+    close(): Promise<void>;
+    /**
+     * 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.
+     */
+    drain(): Promise<void>;
+}