@mifune/agro 0.9.0

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 2026 Ryan Eggleston, d/b/a Mifune Dev (mifune.dev)
+
+   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,27 @@
+Open Harness
+Copyright 2026 Ryan Eggleston, d/b/a Mifune Dev (mifune.dev)
+
+This product includes software developed at Mifune Dev (https://mifune.dev).
+
+This distribution is licensed under the Apache License, Version 2.0. A copy
+of the License is included in the LICENSE file.
+
+Third-Party Attributions
+=========================
+
+typescript (referenced in .oh/cli/package-lock.json) is the sole dependency
+in this repository declaring "license": "Apache-2.0". It is a devDependency
+(.oh/cli/package.json, "devDependencies") used only for type-checking and is
+excluded from the published package, whose "files" array is limited to
+"dist" (bundled output produced by esbuild, not the typescript package
+itself). It therefore carries no NOTICE obligation for consumers of this
+distribution.
+
+Trademarks
+==========
+
+Apache License, Version 2.0, Section 6 grants no permission to use the
+trade names, trademarks, service marks, or product names of the Licensor
+-- including "Mifune" and "Open Harness", their logos, or associated trade
+dress -- beyond the reasonable and customary use in describing the origin
+of the Work that Section 6 itself allows.

package/README.md

@@ -0,0 +1,182 @@
+# @mifune/agro
+
+The **AGRO CLI** (`agro`) — create an [Open Harness](https://oh.mifune.dev)
+Docker sandbox for coding agents and drive its lifecycle from the command line.
+
+Open Harness is a portable harness for running coding agents (Claude Code, Codex, Pi,
+and others) in an isolated Docker sandbox, with the agent's identity, skills, and crons
+versioned in git. This package is the standalone `agro` CLI that creates sandboxes and
+manages their lifecycle.
+
+## Install
+
+```bash
+npm install -g @mifune/agro
+```
+
+Then run it as `agro`:
+
+```bash
+agro --help
+```
+
+Or run it once without installing:
+
+```bash
+npx @mifune/agro sandbox install docker
+```
+
+Prefer a `curl | bash` bootstrap (also installs Node when missing)? `get-agro.sh`
+installs the prebuilt `agro` artifact from the latest GitHub release — it never
+clones or builds on your machine:
+
+```bash
+curl -fsSL https://github.com/mifunedev/openharness/releases/latest/download/get-agro.sh | bash
+```
+
+### Requirements
+
+- **Node.js ≥ 20** (22 recommended) on your `PATH`. Unlike the `get-agro.sh` bootstrap,
+  npm will not install Node for you.
+- **Docker** and **git** for the sandbox lifecycle commands (`agro sandbox install`, `agro shell`).
+
+## Compatibility: `oh`
+
+`oh` is the compatibility entry point for `agro`. It ships as the npm package
+[`@mifune/openharness`](https://www.npmjs.com/package/@mifune/openharness), which
+contains no CLI code of its own: its only file imports the `agro` bundle from an
+exact-pinned `@mifune/agro` dependency. The two packages expose disjoint executables
+(`agro` and `oh`), can be installed together, and removing either never removes the
+other's executable. `oh --help` ends with a line that names `agro` as the canonical
+CLI; everything else about `oh` — the `.oh/` control plane, `oh.json`, `OH_*`
+variables, `~/.oh/sandboxes` — is unchanged, and `agro` reads and writes exactly the
+same files.
+
+## Quick start
+
+Create a sandbox from any directory — no project checkout needed:
+
+```bash
+agro sandbox install docker   # wizard, then boot; writes ~/.oh/sandboxes/<name>/
+agro sandbox list             # name, runtime, status, repo
+agro shell <name>             # open a zsh shell in the running container
+```
+
+To bind one of your own checkouts into the sandbox, equip it and pass `--repo`:
+
+```bash
+cd your-project
+oh update                                       # vendor .oh/ + crons/ — and nothing else (compatibility window)
+agro sandbox install docker --repo "$PWD" --name your-project
+```
+
+Add an agent harness or a tool at any point — this needs no rebuild. The verb is
+the only door; nothing installs at boot:
+
+```bash
+agro harness list                 # what exists, and what is installed
+agro harness install opencode     # install into the running sandbox
+agro tool install herdr           # a fresh sandbox has no herdr
+```
+
+Everything else the sandbox ships — a headless browser, the GitHub CLI:
+
+```bash
+agro tool list                    # what is present, and what is installable
+agro tool install agent-browser   # asks before the ~1 GB Chromium download
+```
+
+`agro harness` and `agro tool` also run **inside** the sandbox, where they install
+into the current environment instead of driving the container over Docker
+Compose. Detection is automatic (`/.dockerenv` plus `SANDBOX_NAME`); override it
+with `OH_EXECUTION_TARGET=local` or `OH_EXECUTION_TARGET=docker-compose`.
+`agro sandbox install` remains host-only and says so.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `agro sandbox install <runtime>` | Create a sandbox: run the wizard, write the registry entry under `${OH_HOME:-~/.oh}/sandboxes/<name>/`, materialise the compose files and wrapper into it, and boot the container. Flags: `--name`, `--repo <dir>`, `--yes`, `--image[=<ref>]`, `--no-build`, `--print-argv`. `docker` is provisionable; `microsandbox` is planned and refuses with a pointer at the runtime RFC. |
+| `agro sandbox list [--json]` | List the registry entries with name, runtime, container status, and bound repo. |
+| `agro shell [name]` | Open a `zsh` shell in the running sandbox container. |
+| `agro stop [name]` | Stop the sandbox, preserving volumes. |
+| `agro restart [name]` | Restart the sandbox service. |
+| `agro logs [name]` | Tail the sandbox compose logs. |
+| `agro ps [name]` | Show sandbox service status. |
+| `agro destroy [name] [--yes]` | Remove the sandbox, wipe its named volumes (`docker compose down -v`), then delete the registry entry. Names the volumes, then requires you to type the sandbox name; refuses without a TTY unless `--yes` is passed. |
+| `agro update [--dry-run]` | Upgrade the installed `agro` executable and nothing else, through the mechanism that installed it: npm-managed (`npm view` + `npm install -g --prefix <owning prefix> @mifune/agro@<version>`) or standalone (download `AGRO_JS_URL`, falling back to `OH_JS_URL` and defaulting to the latest `agro.js` release asset; verify its shebang and `--version`; rename it over the file; keep `<path>.prev` until the new file verifies). Refuses image-shipped, source-checkout, legacy-package, unresolvable, read-only, PATH-shadowed, and downgrade cases with the supported procedure; never uses `sudo`; a no-op when current. Project payload vendoring is `oh update` — see the compatibility note below. |
+| `agro config show [--sandbox <name>]` | Print the resolved `oh.json` — every non-secret setting. |
+| `agro config set <field> <value> [--sandbox <name>]` | Set one dotted `oh.json` field (`access.sshPort 2200`), validated against the schema. A secret key is refused with a pointer at `agro secret set`. |
+| `agro config repo` | Create a repo on your GitHub account, keep the cloned-from upstream as the `openharness` remote, point `origin` at yours, and push. Asks first and defaults to no; never runs without an interactive yes. |
+| `agro config <integration>` | Configure an integration via an interactive wizard. |
+| `agro secret set <KEY> [--sandbox <name>]` | Prompt for the value with the input hidden and write it to the gitignored `.env` (mode `0600`). The value is never taken from the command line, where shell history would keep it. |
+| `agro secret list [--sandbox <name>]` | List the allow-listed keys that hold a value, with the values redacted. |
+| `agro compose config` | Print the resolved compose configuration. |
+| `agro harness <list\|install\|status>` | Install and inspect agent CLI harnesses. `install` is the only door: it probes the running sandbox, installs into the persistent home volume, and reports. It reads and writes no `oh.json` field, and needs no rebuild. |
+| `agro tool <list\|install\|status>` | Install and inspect sandbox tooling that is not an agent CLI. `herdr`, `cloudflared`, `agent-browser`, `microsandbox`, and `tailscale` are `installable`; `gh` and the Docker CLI are `baked-in` and cannot be installed. Nothing installs at boot. A large download is confirmed first, and `--yes` accepts it. |
+| `agro gateway <args…>` | Manage a messaging client session (Slack bridge for `pi`/`hermes`). |
+| `agro cloud <args…>` | Configure credentials and manage OpenHarness Cloud SSH keys and nodes. |
+| `agro --version` | Print the CLI version. |
+| `agro --help` | Show help; every subcommand also accepts `--help`. |
+
+`oh.json` and the `.env` beside it are the only two configuration surfaces: `oh.json`
+holds every non-secret setting, `.env` holds only the allow-listed secrets. Each has
+two homes — a sandbox's registry entry (`--sandbox <name>`) and the project root
+(no flag). See
+[configuration](https://github.com/mifunedev/openharness/blob/main/docs/configuration.md)
+for the field reference.
+
+`agro` (or `oh`) is the only lifecycle door, on the host and in the sandbox, and every verb
+runs `.oh/scripts/docker-compose.sh` — see
+[lifecycle commands](https://github.com/mifunedev/openharness/blob/main/docs/lifecycle-commands.md), which also
+states the confirmation policy `agro destroy` carries.
+
+`agro update` never touches a project. During the compatibility window `oh update` vendors
+`.oh/` + `crons/` into the current directory, equipping an empty checkout and upgrading an
+equipped one (`--from <dir>` / `--from-remote [--ref <ref>]`, `--dry-run`, `--force`); it
+writes nothing else and never prompts. `agro update` rejects those flags and points at
+`oh update`. `oh update` prefers the payload bundled into the CLI itself; with `--from-remote`
+(or no payload at all) it shallow-clones the public OpenHarness repo into a temp dir and
+removes it after the run (`--ref <ref>` pins it). Root `docs/` remains project-owned and is
+not part of that payload. Catalog and help output therefore links to the Open Harness source
+documentation instead of a path inside the equipped project.
+
+The CLI writes no scaffold. It creates no `AGENTS.md`, no provider configuration, and no
+`.gitignore` line beyond the `.env` line `agro secret set` adds inside a git checkout.
+
+## OpenHarness Cloud
+
+`agro cloud` is an Apache-2.0 licensed client that talks to a proprietary hosted service.
+Configure the Cloud API once, then use `agro cloud` instead of hand-writing authenticated HTTP
+requests:
+
+```bash
+agro cloud config  # securely prompts for the current provisioner key
+agro cloud ssh-keys create --name laptop --public-key-file ~/.ssh/openharness_node.pub
+agro cloud nodes create --name demo --ssh-key-id <ssh-key-id>
+agro cloud nodes watch <node-id>
+```
+
+Both settings are repository-local. `agro cloud config` writes the API base URL to `cloud.apiUrl`
+in the tracked `oh.json` and, until OpenHarness Cloud issues user API tokens, stores the
+user-provided provisioner key as `OH_CLOUD_PROVISION_KEY` in the gitignored root `.env`
+(mode `0600`). The key is never printed; `agro cloud config show` redacts it. Nothing is written
+under `$HOME`.
+
+`OH_CLOUD_API_URL` and `OH_CLOUD_PROVISION_KEY` (`OH_PROVISION_KEY` and `PROVISION_KEY` are
+still accepted) provide non-persistent overrides for automation. Because the settings live in
+the repository, `agro cloud` runs inside an OpenHarness-equipped repo; outside one, pass
+`--api-url` and `--provision-key`. On the first `agro cloud` run in a repo, a legacy
+`~/.config/openharness/cloud.json` is migrated into these two homes and then reported as no
+longer read — it is left on disk for you to delete. Run `agro cloud --help` for the complete
+SSH-key and node lifecycle command set.
+
+## Documentation
+
+- **Docs:** https://oh.mifune.dev
+- **Installation guide:** https://oh.mifune.dev/docs/installation
+- **Source & issues:** https://github.com/mifunedev/openharness
+
+## License
+
+[Apache-2.0](./LICENSE)