@notiamo/runner 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Veziro SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @notiamo/runner
 
-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.
+Runs your Notiamo agent runs on your own machine, with the Claude Code you already use there.
+
+```sh
+npx @notiamo/runner init
+```
+
+`init` asks for the runner token (made in Notiamo under Settings › Agent runs › Runners, shown once), Notiamo's host
+and a name for the runner. It checks that `claude --version` works, runs `claude auth login` into the runner's own config
+folder, then installs the service and starts it. When it ends, the runner is running and starts again by itself.
+
+Needs Node.js 22 or later and [Claude Code](https://docs.claude.com/en/docs/claude-code) installed on the machine.
+
+From a checkout of the Notiamo repository: `pnpm --filter @notiamo/runner build`, then
+`node packages/runner/dist/cli.js init`.
+
+## Commands
+
+| Command | What |
+| --- | --- |
+| `notiamo-runner init` | Set up: token, Claude Code sign-in, install and start the service. |
+| `notiamo-runner status` | Whether the service is installed and running, and the last log line. |
+| `notiamo-runner logs` | The last 50 lines of the log. |
+| `notiamo-runner stop` | Stop the service until the next login or boot. |
+| `notiamo-runner uninstall` | Remove the service (the runner's folder stays). |
+| `notiamo-runner start` | Run in the foreground. This is what the service runs; you rarely need it. |
+
+The service is a launchd agent `com.notiamo.runner` on macOS, a Scheduled Task "Notiamo runner" (at logon) on
+Windows, and a systemd user unit `notiamo-runner` on Linux. After `npx`, use `npx @notiamo/runner status` (or install
+the package globally to have `notiamo-runner` on the path).
+
+## What it is
+
+A small program that waits for agent runs your organization queues in Notiamo, then does each run here: it clones
+the repository (or connects to the WordPress site), starts Claude Code in print mode with the run's instructions and
+Notiamo's MCP server, sends Notiamo what the agent does, and reports when it ends.
+
+## What it is not
+
+- **It holds no Claude credential.** It starts the `claude` program already on the machine. `notiamo-runner init`
+  runs Claude Code's own sign-in with the runner's own config folder, so the runner's sessions stay apart from yours;
+  the sign-in itself is Claude Code's, kept by Claude Code.
+- **It is not a Claude login inside Notiamo.** Notiamo never sees or uses your Claude account. As Anthropic's Agent SDK
+  documentation puts it: "Unless previously approved, Anthropic does not allow third party developers to offer
+  claude.ai login or rate limits for their products." The runner only runs your own Claude Code, on your machine, for
+  your own work.
+
+## WordPress sites
+
+The connection is on the project's Website access card in Notiamo: an application password, and optionally SSH or
+FTP. A run goes like this:
+
+1. **Backup before.** With SSH the runner exports the database (`wp db export`, `mysqldump` as the fallback) and
+   uploads it gzipped to Notiamo (`runs/<id>/backup/db.sql.gz`, 200 MB at most). With FTP or the API only there is no
+   backup.
+2. The agent works through the allow-list below.
+3. **Site check after.** The runner opens the site and checks that it still answers.
+4. **Restore on failure.** If the check fails, the runner restores the dump.
+
+What the agent may run with wp-cli, per group (set on the project):
+
+- **content:** `post *`, `term *`, `menu *`, `media import`, `option get`, `option update`
+- **database:** `search-replace`, `cache flush`, `rewrite flush`, `transient delete`
+- **plugins:** `plugin` and `theme` with `list`, `activate`, `deactivate`, `update`
+- **info:** `core version`, `site list`, `db size`
+- **files:** no wp-cli command (the file tools)
+- **never, unless "Allow everything":** `eval`, `eval-file`, `shell`, `user *`, `db query|import|reset|drop|export`
+  (export is the runner's own backup), `plugin install`, `theme install`, `core update|download`
+
+Without "Allow everything", wp-cli must not read or write a file on the server for the agent: `post` takes numeric ids
+only, `media import` takes http(s) URLs only, flags that name a file (`--export*`, `--log`, `--file`, `--dir`,
+`--exec`, `--require`) are refused, and `option get|update` works only for `blogname`, `blogdescription`, `timezone_string`, `date_format`, `time_format`, `posts_per_page`, `show_on_front`, `page_on_front`, `page_for_posts`, `blog_public` and `permalink_structure`. `--ssh`, `--path`,
+`--url` and `--allow-root` are always refused, even with "Allow everything".
+
+## What is stored where
+
+Everything lives in `~/.notiamo-runner` (or the folder in `NOTIAMO_RUNNER_HOME`):
+
+| Path | What |
+| --- | --- |
+| `config.json` | Notiamo's address, the runner's name and the runner token (`ntr_…`), nothing else. Readable by you only (mode 0600). |
+| `claude/` | Claude Code's config folder for the runner (`CLAUDE_CONFIG_DIR`): its sign-in and sessions. |
+| `projects/` | The working copies of your projects, one folder per project. |
+| `runner.log` | What the runner did (no secrets), rotated at 10 MB. |
+| `state.json` | The run in progress, so a restart can carry on. |
+
+The secrets of a run (WordPress passwords, the run's MCP token) come from Notiamo with the run and
+live only in memory: the agent gets them as environment variables (the MCP config on its command line only names them),
+never in a file. The two MCP tokens are `NOTIAMO_RUN_TOKEN` and `NOTIAMO_WP_TOKEN`. What the agent prints is scrubbed
+of them before the transcript is uploaded.
+
+The runner never gets a GitHub token. The machine's own git credentials clone and push; Notiamo opens and merges the
+pull request through its GitHub App.
+
+The SSH host key of a WordPress server is not verified yet.
+
+Revoke the runner in Notiamo and its token stops working at once.