@fnmoa/cli 0.3.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,31 @@
+fnMoa — Proprietary Licence
+
+Copyright (c) 2026 fnLog0. All rights reserved.
+
+This software, including its source code, compiled and minified code,
+container images, documentation and any other files distributed with it
+(the "Software"), is the property of fnLog0.
+
+1. No permission is granted to copy, modify, merge, distribute, publish,
+   sublicense, sell, or host the Software for others, in whole or in part,
+   except under a written licence or a paid licence key issued by fnLog0.
+
+2. You may use the Software only under the terms of a valid licence from
+   fnLog0, only for as long as that licence is valid, and only within the
+   limits it sets.
+
+3. Removing, altering or working around any licence check, notice or key in
+   the Software is not permitted.
+
+4. 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 NON-INFRINGEMENT.
+
+5. TO THE FULLEST EXTENT PERMITTED BY LAW, IN NO EVENT SHALL fnLog0 BE LIABLE
+   FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES,
+   OR FOR ANY LOSS OF DATA, PROFITS OR BUSINESS, ARISING FROM OR IN CONNECTION
+   WITH THE SOFTWARE OR ITS USE. fnLog0'S TOTAL LIABILITY UNDER OR IN
+   CONNECTION WITH THE SOFTWARE SHALL NOT EXCEED THE FEES PAID TO fnLog0 FOR
+   THE LICENCE IN THE TWELVE MONTHS BEFORE THE CLAIM.
+
+For a licence, contact fnLog0.

package/README.md

@@ -1,99 +1,302 @@
-# `@fnmoa/cli` — `moa`
+# @fnmoa/cli
 
-A terminal client for the Moa server — drives tasks and workflows over the same
-HTTP API the dashboard uses.
+`moa` is the command line for **fnMoa**: a workspace that runs coding agents
+(Claude Code, Codex and others) as a team on your GitHub repository. It
+triages issues, writes the change, reviews it, runs the checks, and merges.
 
-## Install
+You use the CLI to:
 
-```sh
-npm i -g @fnmoa/cli
+- **install** a fnMoa workspace on this machine, Vercel Sandbox or Cloudflare
+  (`moa setup`);
+- **look after it** afterwards: status, logs, updates, stop, remove;
+- **work with it**: give agents work, follow runs, talk to the Manager, ship an
+  issue to a merged pull request.
+
+```bash
+npx @fnmoa/cli setup        # or: npm install -g @fnmoa/cli, then `moa setup`
+```
+
+Node 22 or newer. fnMoa is proprietary software and needs a licence, which is
+free for one workspace on this machine. See [Licence](#licence).
+
+---
+
+## Quick start
+
+1. **Make an account.** Go to <https://fnmoa.locusgraph.com>, sign in with
+   GitHub, and choose **Start free** on Plan and billing.
+
+2. **Let Docker pull the image.** The workspace ships as a private image on
+   GitHub's registry. Log in with the image pull token you were given:
+
+   ```bash
+   docker login ghcr.io -u <your GitHub login> --password-stdin   # paste the token
+   ```
+
+3. **Run setup.**
+
+   ```bash
+   npx @fnmoa/cli setup
+   ```
+
+   Setup is seven screens, and it saves as it goes, so you can quit with `q`
+   and pick up later:
+
+   | Screen | What it does |
+   |---|---|
+   | Where | This machine, Vercel Sandbox or Cloudflare |
+   | 1 Checks & account | tools, Docker, and your licence: press **`c`** to connect your account in the browser |
+   | 2 GitHub | your `gh` login and the repository |
+   | 3 Memory & database | SQLite or Postgres, and LocusGraph memory if you have it |
+   | 4 Agent logins | your Claude or Codex login, or API key |
+   | 5 Console access | the GitHub App that signs people in to the web console, and who is on the list |
+   | 6 Deploy & done | a review of the plan and its cost, then Enter twice to deploy |
+
+   Every line on a screen is ✓, ✗ or …. Setup does not move past a ✗: the line
+   says how to fix it, and `r` checks again. `Esc` goes back. Secrets show as
+   `•••`, and are never written to setup's saved state.
+
+4. **Open the console.** Deploy prints the console's address (on this machine,
+   <http://localhost:3100>) and logs `moa` in to the new workspace, so every
+   command below talks to it.
+
+### Connecting your account
+
+On **Checks**, `c` prints a link and a code and opens your browser:
+
+```
+… licence   open https://fnmoa.locusgraph.com/device?code=WXZB-CDFG and check it shows WXZB-CDFG
 ```
 
-## Setup
+Sign in, check the page shows the same code, and approve. Setup gets a signed
+licence for this install and carries on. No licence key is copied or stored
+on your machine.
 
-Run `moa login` (it also starts automatically on first run) — an interactive
-onboarding that sets your server URL and API key:
+No browser on this machine, or running in CI? Use the key from the Licence key
+page instead:
 
-```sh
-moa login
+```bash
+moa setup licence --key                       # asks for it, hidden
+FNMOA_LICENCE_KEY=FNMOA-… moa setup licence     # or from the environment
+moa setup update                               # gives the new licence to the workspace
 ```
 
-It defaults to `https://api.fnmoa.com`; grab your API key from the Moa dashboard.
-Prefer non-interactive? `moa config set url <url>` and `moa config set key <key>`.
+### What each target needs
 
-Then use it:
+| Target | Needs | Notes |
+|---|---|---|
+| **This machine** | Docker | The workspace on :8787 and the console on :3100. Data stays in Docker volumes. |
+| **Vercel Sandbox** | a Vercel login (`vercel login`, or `VERCEL_TOKEN`) | One persistent sandbox per tenant. Checks shows the size and a cost estimate first. |
+| **Cloudflare** | a Cloudflare login (`wrangler login`), a domain on Cloudflare, Workers Paid | A Worker, D1 and a container on your own domain. |
 
-```sh
-moa status
-moa wf pending
-moa wf solve owner/repo 42 --watch
+The Free plan covers **This machine**. Vercel and Cloudflare need a paid plan
+(coming soon).
+
+---
+
+## After setup
+
+The same commands work for every target. With more than one deployed, add
+`--target local|vercel|cloudflare`.
+
+```bash
+moa setup status    # each piece ✓/✗, live; starts a stopped sandbox or container
+moa setup logs      # the workspace's and console's last lines [--lines n]
+moa setup update    # move to this CLI's version of fnMoa; data kept
+moa setup licence   # connect the account again, or replace the licence
+moa setup login     # add or replace the agent logins (owner only), then deploy
+moa setup rotate    # new owner token and secrets, then deploy
+moa setup stop      # stop it; data kept
+moa setup down      # delete everything setup made; asks first [--yes]
 ```
 
-## Commands
+`down` only deletes what setup recorded making, by id. A database, bucket or
+image that was there before is left alone.
+
+To update fnMoa, update the CLI, then run `update`:
 
+```bash
+npx @fnmoa/cli@latest setup update
 ```
-moa login                          connect: set server URL + API key (interactive)
-moa status                         overview snapshot
-moa setup                          connector (Claude/GitHub) status
-moa tasks | task <id>              list / show tasks
-moa run "<prompt>" [--dir D] [--autonomous] [--watch]
-moa cancel <taskId>
 
-moa wf                             list runs
-moa wf pending                     available issues/PRs
-moa wf get <id> [--watch]          one run + step timeline
-moa wf cancel <id>
-moa wf solve   <repo> <issue#> [--base B] [--watch]
-moa wf triage  <repo> <issue#> [--watch]
-moa wf review  <repo> <pr#>    [--watch]
-moa wf address <repo> <pr#>    [--watch]
-moa wf fix-ci  <repo> <pr#>    [--watch]
-moa wf merge   <repo> <pr#>    [--watch]
+---
+
+## Using a workspace
+
+### Log in to one
+
+`moa setup` logs you in to the workspace it deploys. To use one someone else
+runs:
+
+```bash
+moa login https://workspace.example.com --token <token>   # a token the owner gave you
+moa login https://workspace.example.com --github          # sign in with GitHub
+moa whoami                                                # which workspace, which tenant
+moa use <profile>                                         # switch between saved workspaces
+```
 
-moa oracle list                    list oracle domains
-moa oracle consult <domain> "<question>" [--watch]
-moa oracle history
+`--github` is for someone the owner has added on Console access. It prints a
+GitHub device code, waits while you approve it, and saves a token of your own,
+with your role and your daily spending cap. Removing you on Console access
+stops it at once.
 
-moa gh pulls | issues
+### Check it is ready
 
-moa config                         show effective URL/key + file path
-moa config set url <url>           persist the API URL (~/.moa/cli.json)
-moa config set key <key>           persist an API key
-moa config clear
+```bash
+moa doctor
+```
 
-moa skills                         list the bundled Moa skills
-moa skills show <name>             print a skill's SKILL.md
-moa skills install [name] [--tool claude|cursor|codex|all] [--dir D] [--force]
+```
+  ok  runs agents   sqlite, v0.4.0
+  ok  agent CLIs    claude, codex
+  NO  repository    none configured — pipelines need MOA_REPO
+  NO  github login  gh has no token there — run `gh auth login` where the workspace runs
 ```
 
-`moa help --json` emits the full command catalog (every command + sub-action,
-with `usage` and documented `args`) as JSON, so an agent can discover
-capabilities programmatically. `moa help` (text) is rendered from the same
-registry, so docs never drift.
+Exit 0 when it is ready, 2 when it is not.
 
-## Skills
+### Ship an issue
+
+```bash
+moa ship 41                        # issue #41 → pull request → reviewed → merged
+```
 
-The CLI bundles ready-to-use agent skills (setup, ship-issue, review-pr,
-triage-audit, run-task, oracle, profiles). Install them into your coding agent —
-each tool gets the right format:
+### Declare a team and give it work
 
-```sh
-moa skills                              # list them
-moa skills install --tool claude        # → ~/.claude/skills/<name>/SKILL.md
-moa skills install --tool cursor        # → ./.cursor/rules/<name>.mdc
-moa skills install --tool codex         # → ~/.codex/prompts/<name>.md  (use as /<name>)
-moa skills install --tool all           # all three
-moa skills install moa-setup --tool cursor   # just one skill
+```bash
+moa agent create planner  --cli claude --role "You scope the work. You never write code." --peers builder
+moa agent create builder  --cli claude --role "You write the code and its tests."         --peers reviewer
+moa agent create reviewer --cli codex  --role "You read diffs and name defects."
+
+moa run builder "fix the retry bug in src/http.ts" --watch
+moa team work planner,builder,reviewer --watch
+moa ask planner builder "which retry flag?"        # and wait for the answer
+moa delegate planner builder "implement the retry fix"
 ```
 
-## Config
+`--peers` is who an agent may open a thread with. Replying inside a thread it is
+already part of needs no permission.
+
+### Follow what is happening
+
+```bash
+moa watch                  # every job in the workspace, as it changes
+moa jobs                   # what is running now
+moa runs                   # what ran, newest first [--failed] [--state running]
+moa logs <runId> --watch   # every line a run produced, live
+moa spend --since 24h      # what it cost, and what asked for it
+moa inbox                  # who is waiting on an answer
+moa delegations --blocked  # what is stuck, and the command to unstick it
+```
+
+Ctrl-C stops the work the command started and waits for it to stop. Press it
+twice to leave the work running; `moa jobs` finds it again.
+
+### Talk to the Manager
+
+The Manager is the agent that plans and starts work for you, the same one as on
+the console's chat page.
+
+```bash
+moa manager say "start #41 with the core team"   # and wait for its answer
+moa manager proposals              # what it proposes, each with its id
+moa manager approve <id>           # say yes, and run it now
+moa manager dismiss <id>           # say no
+moa manager watch                  # what is running, and how it is going
+```
+
+`say` waits up to `--timeout <s>` (default 600). Past that it exits 2, and the
+Manager's answer is in the chat when it has one.
+
+---
+
+## For scripts
+
+### Exit codes
+
+```
+  0  it did what it was asked
+  1  it ran and failed — a red build, a CLI that would not start
+  2  a rule stopped it — a budget, a policy, a bounced message, a timeout
+  3  the command was typed wrong, or the token was refused
+```
+
+### JSON
+
+`--json` writes the answer to stdout and nothing else. Warnings go to stderr.
+
+```bash
+moa agent list --json | jq -r '.agents[] | "\(.name)\t\(.cli)\t\(.status)"'
+moa run builder "say ok" --json | jq '{result: .result.result, cost: .result.costUsd}'
+moa jobs --json | jq -r '.jobs[] | select(.state == "running") | .kind'
+moa ship 41 --json | jq -r '.result.outcome'
+moa doctor --json | jq -e '[.checks[] | select(.ok == false)] | length == 0'
+```
+
+The shapes those depend on are pinned by a test, so a script built on them
+does not break quietly:
+
+```
+  agent list     .agents[].name .agents[].cli .agents[].status .agents[].role
+  inbox          .waiting[].to .waiting[].unread .waiting[].oldest
+                 .waiting[].from
+  run            .result.runId .result.result .result.isError .result.costUsd
+  ask            .result.answered .result.answer .result.chain
+  runs           .runs[].id .runs[].cause .runs[].costUsd
+  delegations    .delegations[].from .delegations[].to .delegations[].task
+                 .delegations[].blockedBy.body
+  seats          .seats[].cli .seats[].used .seats[].hasCredential
+                 .seats[].installed
+  spend          .costUsd .byAgent[].agent .byCause[].cause
+  jobs           .jobs[].kind .jobs[].state .jobs[].subject .jobs[].agent
+                 .jobs[].progress.step
+  doctor         .tenant .checks[].name .checks[].ok .checks[].detail
+  ship           .result.outcome .result.reason .result.steps .result.costUsd
+```
+
+Exit codes still apply with `--json`: a bounced `moa send` exits 2 and prints
+the bounce.
+
+### Common flags
+
+```
+  --watch            print what the agent does, as it does it
+  --detach           start the work and return at once
+  --json             machine-readable output only
+  --profile <name>   a saved workspace other than the current one
+  --timeout <s>      stop waiting; the work carries on
+```
+
+Tab completion: `eval "$(moa completion zsh)"` (or `bash`) in your shell's rc file.
+
+---
+
+## Where it keeps things
+
+```
+  ~/.moa/config.json           saved workspaces and their tokens (mode 0600)
+  ~/.moa/setup.json            setup's answers and what it deployed; never a secret
+  ~/.moa/licence-<target>.json this install's id and signed licence (mode 0600)
+  ~/.moa/local/                logs and state of what setup started
+  MOA_HOME                     use another folder than ~/.moa
+  MOA_URL, MOA_TOKEN           talk to this workspace, ignoring the saved ones (CI)
+```
+
+---
+
+## Licence
+
+fnMoa is proprietary: Copyright (c) 2026 fnLog0, all rights reserved. See
+`LICENSE` in this package. Using it needs a licence from
+<https://fnmoa.locusgraph.com>:
+
+- **Free**: one workspace on This machine.
+- **Team** and **Business**: more workspaces, on Vercel and Cloudflare too.
+  Coming soon.
 
-URL/key resolve **env var → `~/.moa/cli.json` (`moa config`) → default**, so you
-can persist them once instead of exporting env vars.
+The workspace checks its licence once a day. If the plan lapses, there is a
+grace period. After that the workspace is read-only until the plan is paid
+again, and no data is deleted.
 
-| Env | Default | |
-| --- | --- | --- |
-| `MOA_API_URL` | `https://api.fnmoa.com` | Server base URL |
-| `MOA_API_KEY` | — | API key |
-| `MOA_CONFIG` | `~/.moa/cli.json` | Config file path |
-| `NO_COLOR` | — | Disable ANSI colors |
+Versions 0.1.0 to 0.3.0 of this package are an older, unrelated CLI and are
+deprecated.