@getollie/cli 0.0.4 → 0.2.0

package/README.md

@@ -1,3 +1,152 @@
-# Ollie
+# @getollie/cli
 
-Ollie is an generic "Prompting" framework for Pochi to evaluate a website, it accepts a URL, and generates a report
+Ollie runs shell commands in a fresh `just-bash` sandbox and optionally provides a one-shot model agent. It also exports the sandbox primitives and a persistent NDJSON worker.
+
+> **Workspace writes persist.** Commands and model agents write directly to the configured host workspace.
+
+## Install
+
+```bash
+npm install --global @getollie/cli
+ollie doctor
+```
+
+For local development:
+
+```bash
+pnpm install
+pnpm ollie -- doctor
+```
+
+## CLI
+
+The root command executes shell source in a fresh sandbox:
+
+```bash
+ollie pwd
+ollie 'printf "generated\n" > generated.txt'
+ollie --cwd ./fixture --timeout 5000 'npm test'
+```
+
+Ollie options must appear before command text. Use `--` when command text starts with an option or with a reserved subcommand name:
+
+```bash
+ollie -- --help
+ollie -- agent --version
+ollie echo --verbose # passes --verbose to echo
+```
+
+A bare `ollie` invocation is an error. Complex shell source should be passed as one quoted argument so the host shell does not interpret it first.
+
+### Machine output
+
+`--ndjson` captures output and emits one newline-terminated result record:
+
+```bash
+ollie --ndjson 'printf "hello\n"'
+# {"exitCode":0,"stdout":"hello\n","stderr":"","durationMs":3,"timedOut":false,"truncated":false}
+```
+
+### Agent
+
+Model-backed behavior is available only through the `agent` subcommand:
+
+```bash
+ollie agent 'summarize this repository'
+ollie agent --ndjson 'fix the failing tests'
+ollie agent --executor local 'delegate the native build and fix any failures'
+DAYTONA_API_KEY=... ollie agent --executor daytona 'run the native test suite and fix failures'
+```
+
+Agent `--ndjson` emits one runner event per line. Agent workspace writes persist to the host.
+
+The agent remains in the restricted workspace environment by default. `--executor local` adds a `delegateTask` tool that can start fresh subagents with native `bash`, file, package-manager, build, and test access. The local executor shares the current workspace, runs with the current user's permissions, inherits the current process environment, and is **not isolated**. It must be selected explicitly.
+
+`--executor daytona` runs delegated agents in an isolated Daytona sandbox. Ollie uploads the complete workspace before each delegated task, synchronizes all files back afterward, stops the sandbox between tasks while preserving its filesystem, and deletes it when the run finishes. Configure the SDK with `DAYTONA_API_KEY` and optionally `DAYTONA_API_URL`, `DAYTONA_TARGET`, or `OLLIE_DAYTONA_SNAPSHOT`.
+
+### Persistent sandbox worker
+
+```bash
+ollie sandbox --cwd /path/to/workspace
+```
+
+The worker reserves stdout for newline-delimited request/response records and retains one sandbox until EOF, so in-session changes persist between requests. Its workspace writes persist to the host by default.
+
+### Diagnostics
+
+```bash
+ollie doctor
+ollie doctor --json
+```
+
+Doctor retains its single-document `--json` report; execution and agent machine output use `--ndjson`.
+
+## Configuration
+
+Configuration precedence is CLI flags, then environment variables, then defaults.
+
+- `OLLIE_CWD` / `--cwd`: defaults to the current directory.
+- `OLLIE_PROVIDER` / agent `--provider`: currently `openai` only.
+- `OLLIE_MODEL` / agent `--model`: defaults to `gpt-5.6`.
+- `OLLIE_EXECUTOR` / agent `--executor`: `none` (default), `local`, or `daytona`.
+- `OLLIE_DAYTONA_SNAPSHOT`: optional Daytona snapshot name used by the Daytona executor.
+- `DAYTONA_API_KEY`, `DAYTONA_API_URL`, `DAYTONA_TARGET`: standard Daytona SDK configuration.
+- `OLLIE_MAX_STEPS` / agent `--max-steps`: defaults to `20`.
+- `OLLIE_COMMAND_TIMEOUT_MS` / `--timeout`: defaults to `30000`.
+- `OLLIE_MAX_OUTPUT_BYTES` / `--max-output`: defaults to `65536`.
+- `OPENAI_API_KEY`: required for live model runs with the OpenAI provider.
+
+## Sandbox API
+
+```ts
+import { createJustBash, SANDBOX_WORKSPACE_PATH } from "@getollie/cli";
+
+const bash = createJustBash(process.cwd());
+const result = await bash.exec(`echo generated > ${SANDBOX_WORKSPACE_PATH}/output.txt`);
+```
+
+The configured host directory is mounted read-write at `/workspace`, so writes persist directly to it. Symlinks are disabled, and Python and JavaScript support are enabled.
+
+### Sandbox Git
+
+A sandbox-native `git` command is enabled by default. It is implemented with `isomorphic-git` and uses the sandbox filesystem. Supported commands are `init`, `clone`, `status`, `add`, `commit`, `log`, `diff`, `branch`, `checkout`, `remote`, `config`, `fetch`, `pull`, and `push`. Run `git help` for the concise command list.
+
+```bash
+git init -b main
+git config user.name "Ollie"
+git config user.email "ollie@example.com"
+git add .
+git commit -m "sandbox changes"
+```
+
+Remote operations accept HTTPS URLs only and pass through Just Bash's network policy. Git responses are buffered in memory and capped at 100 MiB; mounted host files retain the sandbox's 10 MiB per-file read limit. Large repositories or blobs fail cleanly rather than exhausting memory. Authenticated callers can inject credentials without exposing them to the shell:
+
+```ts
+const bash = createJustBash(process.cwd(), {
+  git: {
+    author: { name: "Ollie", email: "ollie@example.com" },
+    resolveAuth: async (url) =>
+      url.startsWith("https://github.com/")
+        ? { username: "token", password: process.env.GITHUB_TOKEN }
+        : undefined,
+  },
+});
+```
+
+Set `git: false` to disable the custom command. Git operations modify the mounted workspace, and a successful `git push` is a permanent external side effect. SSH remotes, hooks, submodules, signing, editors, pagers, and advanced pathspecs/options are intentionally unsupported.
+
+## Sandbox worker protocol
+
+Send one JSON request per line to `ollie sandbox`; receive one JSON response per line. Supported methods are `exec`, `readFile`, and `writeFile`.
+
+```bash
+printf '%s\n' \
+  '{"id":1,"method":"exec","params":{"command":"pwd && ls"}}' \
+  | ollie sandbox --cwd .
+```
+
+Operational failures are returned as structured errors without stopping subsequent requests.
+
+## Safety model
+
+Ollie is not a hardened isolation boundary for untrusted workloads. Workspace writes are host-backed and persistent, and network or Git operations can have permanent external side effects. Command timeouts, bounded agent steps, and output truncation provide additional constraints.

package/dist/cli.d.ts

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