@runneth/cli 0.0.0-sha.14f7fe073a12.production

package/README.md

@@ -0,0 +1,216 @@
+# runneth-cli
+
+`runneth-cli` gives local coding agents a fast persistent shell session.
+
+```bash
+npx @runneth/cli open
+runneth send 'cd ~/project && pnpm test'
+runneth send 'git status --short'
+runneth oauth login
+runneth chat --workspace <workspace-id>
+runneth conversation create --workspace <workspace-id> --json
+runneth ssh
+runneth close
+```
+
+## npm Usage
+
+Run the promoted production package from the npm `latest` channel:
+
+```bash
+npx @runneth/cli ssh
+```
+
+Use the npm `beta` channel to try the production build before it is promoted to
+`latest`:
+
+```bash
+npx @runneth/cli@beta ssh
+```
+
+The first command starts a small local daemon for the current user. Later `send`
+calls reuse the same shell process through a local socket, so `cd`, exported
+environment variables, and other shell state persist between commands.
+
+## Commands
+
+```bash
+runneth open [--name default] [--cwd <path>] [--shell <path>]
+runneth send [--name default] [--timeout-ms 600000] [--stdin] -- <command...>
+runneth status [--name default]
+runneth list
+runneth close [--name default]
+runneth oauth login [--resource <url>] [--client-name "Runneth MCP"] [--scope <scope>] [--no-open]
+runneth oauth status [--resource <url>]
+runneth oauth logout [--resource <url>]
+runneth chat --workspace <workspace-id> [--api <builder-url>] [--resource <url>] [--auth mondrian|builder] [--conversation <id>]
+runneth conversation create --workspace <workspace-id> --json [--title <title>]
+runneth conversation send --workspace <workspace-id> --conversation <id> --json (--message <text> | --stdin)
+runneth conversation state --workspace <workspace-id> --conversation <id> --json
+runneth conversation session --workspace <workspace-id> --jsonl
+runneth ssh target add <name> (--host <host> | --ssh-url <url>) [--resource <url>] [--default]
+runneth ssh target import <file>
+runneth ssh target list
+runneth ssh target use <name>
+runneth ssh [--target <name>] [--unique-key | --identity-file <path>] [-- remote-command]
+runneth ssh stdio [--target <name>] [--unique-key | --identity-file <path>]
+runneth skills install [--agent claude|codex|all]
+runneth shutdown
+```
+
+Use `--stdin` for multi-line commands:
+
+```bash
+cat <<'SCRIPT' | runneth send --stdin
+cd ~/project
+pnpm check
+SCRIPT
+```
+
+Runtime files live under `~/.runneth-cli` by default. Set `RUNNETH_CLI_HOME` to
+use a different state directory.
+
+## OAuth
+
+`runneth-cli oauth login` performs OAuth protected-resource discovery, dynamic
+client registration as a public MCP-style client, PKCE authorization, and token
+exchange through a local loopback callback.
+
+```bash
+runneth oauth login --resource http://localhost:4100/mcp
+runneth oauth status --resource http://localhost:4100/mcp
+```
+
+OAuth credentials are stored under `~/.runneth-cli/oauth` with user-only file
+permissions on Unix-like systems. Commands that need an access token refresh it
+internally when the server issued a refresh token.
+
+## Chat
+
+`runneth-cli chat` starts an interactive terminal conversation against Builder's
+canonical Runneth conversation API. Official environment builds carry the
+correct Builder URL in the package; use `--api` only for local or custom Builder
+deployments.
+
+```bash
+runneth chat --workspace "$MONDRIAN_WORKSPACE_ID"
+```
+
+If no stored OAuth credential exists, chat starts the same browser-based OAuth
+flow as SSH and stores the credential under `~/.runneth-cli/oauth`. Use
+`--token`, `RUNNETH_TOKEN`, `MONDRIAN_TOKEN`, or `BUILDER_AGENT_CHAT_TOKEN` only
+for automation and local API mocks that should bypass OAuth.
+
+Inside the terminal UI, use `/state` to redraw the current conversation and
+`/exit` to quit.
+
+## Conversation Commands
+
+`runneth-cli conversation` is the machine-oriented conversation interface for
+agents and scripts. It uses the same auth, workspace scoping, and conversation
+API as `runneth chat`, but avoids terminal banners and ANSI UI output.
+
+```bash
+runneth conversation create --workspace "$MONDRIAN_WORKSPACE_ID" --title "SSH routine setup" --json
+runneth conversation send --workspace "$MONDRIAN_WORKSPACE_ID" --conversation "$CONVERSATION_ID" --message "Create a routine" --json
+runneth conversation state --workspace "$MONDRIAN_WORKSPACE_ID" --conversation "$CONVERSATION_ID" --json
+```
+
+`send` waits for the assistant response by default. `send` and `state` require an
+explicit `--conversation`; the CLI does not track an implicit active
+conversation for machine commands.
+
+Long-lived agents can keep one authenticated process open with JSONL over
+stdin/stdout:
+
+```bash
+runneth conversation session --workspace "$MONDRIAN_WORKSPACE_ID" --jsonl
+```
+
+The session `ready` frame reports the resolved client target context, not a
+separate active conversation identity. Authoritative user and conversation
+identity comes from the `conversation` object returned by `create` and `state`.
+
+Typical requests:
+
+```jsonl
+{"id":"1","method":"create","params":{"title":"SSH routine setup"}}
+{"id":"2","method":"send","params":{"conversationId":"11111111-1111-4111-8111-111111111111","text":"Create a routine"}}
+{"id":"3","method":"state","params":{"conversationId":"11111111-1111-4111-8111-111111111111"}}
+{"id":"4","method":"close"}
+```
+
+Typical responses:
+
+```jsonl
+{"type":"ready","ok":true,"protocol":"runneth-conversation-stdio","version":1,"authMode":"mondrian","workspaceId":"65cbcb84095884aaf08dc76a"}
+{"id":"1","type":"created","ok":true,"conversation":{"id":"11111111-1111-4111-8111-111111111111"}}
+{"id":"2","type":"sent","ok":true,"send":{"assistantMessageId":"55555555-5555-4555-8555-555555555555"}}
+{"id":"2","type":"state","ok":true,"state":{"conversation":{"id":"11111111-1111-4111-8111-111111111111"}}}
+{"id":"2","type":"complete","ok":true,"assistantMessage":{"id":"55555555-5555-4555-8555-555555555555","status":"completed"}}
+```
+
+## SSH
+
+`runneth-cli ssh` uses the stored OAuth credential for the resource. If no
+credential exists yet, it starts the OAuth login flow first. The first SSH
+connection for a resource/app pair generates an ed25519 keypair, sends the
+public key to the Runneth SSH app, writes an isolated OpenSSH config, and then
+starts `ssh` through the app tunnel.
+
+```bash
+runneth ssh \
+  --resource https://projects.motionapp.com/mcp \
+  --host 93c7ca56-debe-4b95-8be2-a873afe72234.app.runneth.com
+```
+
+SSH keys, known hosts, and generated config files are stored under
+`~/.runneth-cli/ssh`. The generated OpenSSH config uses an internal
+`ProxyCommand` transport that attaches the OAuth bearer token to the SSH app
+HTTP tunnel.
+
+### SSH stdio
+
+Use `ssh stdio` when an agent needs to keep one authenticated SSH connection
+open and run multiple commands or remote processes without reconnecting:
+
+```bash
+runneth ssh stdio --target primary-vm
+```
+
+The command writes JSONL events to stdout and reads JSONL requests from stdin.
+Logs and setup messages are written to stderr.
+
+```jsonl
+{"id":"1","method":"exec","params":{"command":"pwd","timeoutMs":30000}}
+{"id":"2","method":"spawn","params":{"command":"cat"}}
+{"id":"2","method":"stdin","params":{"data":"hello\n"}}
+{"id":"2","method":"close"}
+```
+
+Typical responses:
+
+```jsonl
+{"type":"ready","ok":true,"protocol":"runneth-ssh-stdio","version":1,"hostAlias":"runneth-2735833d956e","targetName":"primary-vm"}
+{"id":"1","type":"stdout","data":"/agent\n"}
+{"id":"1","type":"exit","ok":true,"code":0,"signal":null}
+{"id":"2","type":"started","ok":true,"processId":"2","command":"cat"}
+```
+
+## Agent Skills
+
+Install or update the bundled Runneth skill for Claude Code and Codex:
+
+```bash
+runneth-cli skills install
+```
+
+Install or update only one agent skill:
+
+```bash
+runneth-cli skills install --agent claude
+runneth-cli skills install --agent codex
+```
+
+The command writes the same `runneth` skill to `~/.claude/skills/runneth` and/or
+`~/.codex/skills/runneth`. Re-running the command updates the existing skill.

package/dist/build-defaults.d.ts

@@ -0,0 +1,6 @@
+//#region src/build-defaults.d.ts
+declare const resolveBuildDefaultMcpResourceUrl: () => string | undefined;
+declare const resolveBuildDefaultMondrianApiUrl: () => string | undefined;
+declare const resolveBuildDefaultRunnethApiUrl: () => string | undefined;
+//#endregion
+export { resolveBuildDefaultMcpResourceUrl, resolveBuildDefaultMondrianApiUrl, resolveBuildDefaultRunnethApiUrl };

package/dist/build-defaults.js

@@ -0,0 +1,36 @@
+//#region src/build-defaults.ts
+const BUILD_DEFAULT_MONDRIAN_API_URL = "https://projects.motionapp.com/";
+const BUILD_DEFAULT_RUNNETH_API_URL = "https://build-be.runneth.com/";
+const appendMcpPath = (url) => {
+	url.pathname = `${url.pathname === "/" ? "" : url.pathname.replace(/\/+$/u, "")}/mcp`;
+};
+const resolveBuildDefaultMcpResourceUrl = () => {
+	const apiUrl = resolveBuildDefaultMondrianApiUrl();
+	if (apiUrl === void 0) return;
+	const url = new URL(apiUrl);
+	appendMcpPath(url);
+	return url.toString();
+};
+const normalizeBuildDefaultUrl = (input) => {
+	const rawApiUrl = input.value.trim();
+	if (rawApiUrl.length === 0 || rawApiUrl.startsWith("__RUNNETH_CLI_DEFAULT_") && rawApiUrl.endsWith("_API_URL__")) return;
+	const url = new URL(rawApiUrl);
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`Build default ${input.envName} must use http or https`);
+	url.hash = "";
+	url.search = "";
+	return url.toString().replace(/\/+$/u, "");
+};
+const resolveBuildDefaultMondrianApiUrl = () => {
+	return normalizeBuildDefaultUrl({
+		envName: "MONDRIAN_API_URL",
+		value: BUILD_DEFAULT_MONDRIAN_API_URL
+	});
+};
+const resolveBuildDefaultRunnethApiUrl = () => {
+	return normalizeBuildDefaultUrl({
+		envName: "BACKEND_URL",
+		value: BUILD_DEFAULT_RUNNETH_API_URL
+	});
+};
+//#endregion
+export { resolveBuildDefaultMcpResourceUrl, resolveBuildDefaultMondrianApiUrl, resolveBuildDefaultRunnethApiUrl };

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export { };