orzarua 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# orzarua: the Or Zarua Congregations command line
 
-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.
+Every Congregations action is a command: `orzarua <area> <action>`, for people at a terminal, scripts and pipelines, and AI agents (through MCP). It is one file, `dist/orzarua.mjs`, that needs Node 24 or later and nothing else installed beside it.
+
+```
+orzarua members list
+orzarua yahrzeits month --month 2026-11
+orzarua members update --member-id <memberId> --body member.json
+```
+
+## Install
+
+The package is `orzarua`. Run it without installing, or install it globally:
+
+```
+npx orzarua@latest start
+yarn global add orzarua@latest
+```
+
+From this repository, build it and run the file:
+
+```
+cd congregations/cli
+yarn install
+yarn build
+node dist/orzarua.mjs start
+```
+
+`dist/orzarua.mjs` has a `#!/usr/bin/env node` line and is the package's `bin`, so `yarn link` (or an alias) makes it `orzarua`.
+
+## First steps
+
+```
+orzarua start        # the primer: how it works, in one screen
+orzarua login        # a code is emailed; type it in
+orzarua whoami       # who you are, and what you may do in each congregation
+orzarua use <slug>   # only if you belong to more than one congregation
+orzarua members      # the actions in an area
+orzarua search "move a yahrzeit"
+orzarua how undo a change
+```
+
+The guides, recipes and a reference page for every command are inside the CLI (`orzarua docs`, `orzarua how <words>`, `orzarua describe <command>`, `orzarua examples <command>`). `orzarua doctor` checks the sign-in, the connection and the version; when a check fails it answers `ok: false` with `doctor-failed` (exit 9) and every check in `details`. Output is JSON when it is piped (or with `--json`), and tables and plain text at a terminal.
+
+### Changes go through a plan
+
+A command that deletes, overwrites, reaches people or costs money never runs on the first call. It answers a plan and exits 7. Someone looks at the plan and says yes; then the same command runs with `--confirm <planId>`:
+
+```
+orzarua members update --member-id <memberId> --body member.json      # exit 7: the plan
+orzarua members update --confirm <planId>                              # runs it
+```
+
+Before a confirmed change the CLI saves a backup, and `orzarua backups` and `orzarua restore <backup>` put records back. Exit codes: 0 done, 2 invalid input, 3 not signed in, 4 forbidden, 5 not found, 6 conflict, 7 plan made (needs a yes), 8 rate-limited or locked, 9 network or server. `orzarua docs errors` has the rest.
+
+## In a pipeline
+
+Make an API token from a signed-in machine, give it only the permissions the job needs, and keep its secret in the pipeline's secret store:
+
+```
+orzarua tokens create --name "GitHub Actions: weekly member list" --capabilities member.contact.view --expires-in-days 90
+```
+
+Then set `ORZARUA_TOKEN` (and `ORZARUA_ENV`, `prod` by default). No sign-in, no prompt, no profile (plans, backups and the version cache are still written, in the state and data folders). `orzarua how use in github actions` shows a whole job, with the plan and the confirm as two steps.
+
+## With Claude Code and other agents
+
+`orzarua mcp` runs a local MCP server over the same tools, on standard input and output. It signs in as you, with the same files, and it never confirms a plan on the agent's own say: `apply` runs only a stored plan, and asks the person directly when the MCP client supports elicitation; otherwise the client's own tool-permission prompt is the yes. Never put `apply` on an auto-approve or "always allow" list.
+
+```
+claude mcp add orzarua -- orzarua mcp
+```
+
+Any other MCP client takes the same command: `orzarua mcp`. `--env local` picks the environment, as it does for every command (`orzarua mcp --env local`). An agent that only has a shell can use the CLI directly; `orzarua start` is written for it.
+
+## Against the local stack
+
+`--env local` (or `ORZARUA_ENV=local`) points the CLI at the Compose dev stack: the Congregations API at `http://localhost:8788`, sign-in at `http://localhost:8787`, and the app at `http://localhost:5173`. Its sign-in emails go to LocalStack, so read the code from there:
+
+```
+yarn dev                                                             # from the repository's root: the whole stack
+yarn --cwd ../backend dev:e2e-congregation e2e-try noa-try@example.test
+orzarua login --env local --email noa-try@example.test               # asks for a code
+curl -s localhost:4566/_aws/ses                                      # the email is in `messages`
+orzarua login --env local --email noa-try@example.test --code "123 456"
+```
+
+A profile, its plans and its backups are kept apart for `prod` and `local`, and a plan made against one never runs against the other. `ORZARUA_HOME` puts all of the CLI's files under one directory instead of the usual XDG ones.
+
+## The tested examples
+
+Every command has examples in `examples/` (one file per area), and every recipe in `docs/recipes/` names its steps by example id in `examples/recipes.ts`. They are run for real, by a program that drives `dist/orzarua.mjs` against the local stack:
+
+```
+yarn build
+node scripts/run-examples.ts                  # every recipe, then a sweep of every command
+node scripts/run-examples.ts --recipe undo-a-change
+node scripts/run-examples.ts --sweep
+```
+
+For each recipe, and for the sweep, it makes a fresh congregation (`dev:e2e-congregation`), signs the admin in through the real `orzarua login`, reading the emailed code from LocalStack's SES (parsed by the backend's own `parseSesMessages`, `backend/scripts/dev/lib.ts`, which Node 24 runs as it is, so the backend's dependencies must be installed but nothing else), and runs each example as its own process in its own `ORZARUA_HOME`. An example that answers a plan (exit 7) is followed by the example that confirms it. The runner prints a table and exits non-zero on any failure.
+
+An example is `{ id, command, title, argv, stdin?, as, expect, saves? }`. `expect.json` is a partial match on paths (`"data.firstName": "Ruth"`), and `saves` keeps values for later lines, which write them as `{memberId}`. `as: "member"` runs the example as an API token that holds only what any member may do. The pure parts of the runner (placeholders, paths, the sign-in code, the order of plan and confirm) are in `scripts/run-core.ts` and tested without Docker; the unit tests also check that every command has examples, that every risky command shows its plan and its confirm, and that every example's line reads against its command:
+
+```
+yarn tsc --noEmit
+yarn build        # the MCP stdio test starts the built file
+yarn vitest run
+```
+
+CI's `congregations-cli` job runs all of this, the examples against the Compose stack.
+
+## Releasing
+
+`orzarua` is published to npm from the owner's account (`danp3d`) by npm trusted publishing: GitHub Actions proves its identity with OIDC, so there is no npm token. A version bump is the release. CI (`congregations-cli-version`) refuses a pull request that changes anything the package is made from without raising `version` in `package.json`, and merging a raised version to `main` runs `.github/workflows/release-cli.yml`, which tests, publishes, and pushes the tag `cli-v<version>`. That workflow is the one place the repo uses npm instead of yarn (`npm publish`, which trusted publishing needs).
+
+One-time setup, in this order:
+
+1. Publish the first version by hand, from the owner's account. Trusted publishing can only be set up for a package that already exists.
+   ```
+   cd congregations/cli
+   yarn build
+   npm login
+   npm publish --access public
+   ```
+2. Add the trusted publisher on npmjs.com: Package, Settings, Trusted publishing, GitHub Actions. User `danp3d`, repository `or_zarua`, workflow `release-cli.yml` (the file name only, matched exactly and case-sensitively).
+3. Confirm it within 2 days by merging a pull request that bumps the version; the workflow publishes it. npm expires a new trusted-publisher configuration that has not completed a successful publish within 2 days, and it must then be recreated.
+
+After the first release by OIDC works, optionally harden the package: Package, Settings, Publishing access, "Require two-factor authentication and disallow tokens".
+
+Every release after that: bump `version` in `package.json` in the pull request that changes the CLI, then merge. "Changes the CLI" is decided from what the bundle is built from (`yarn build` writes `dist/meta.json`, and `scripts/check-version-bump.ts` reads it), so it covers the CLI's source and guides, `package.json` (other than its version), this README, `yarn.lock` and, because they are bundled in, the backend contracts and the core files they import. Only tests, examples and scripts can change without a bump. The repository is private, so npm records no provenance.
+
+To run the check yourself: `yarn build && node scripts/check-version-bump.ts origin/main`.
+
+## Changing the backend contracts
+
+The contracts in `congregations/backend` ship inside the CLI, so a contract change needs a CLI version bump in the same pull request, and CI fails without one.