@oalo-ai/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OALO
+
+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,393 @@
-# Temporary Holding Version
+# @oalo-ai/cli
 
-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.
+Work on an OALO workspace from your terminal: edit chat flows, loops and code
+tools as files and push them back safely, run test conversations with a bot,
+generate typed bindings for your own app, and serve all of it to a coding agent
+over MCP.
+
+## Install
+
+Node 18 or newer:
+
+```sh
+npm install -g @oalo-ai/cli
+oalo --version
+```
+
+`man oalo` documents every command and every bot setting. `oalo coord` (agent
+coordination) also needs [Bun](https://bun.sh); everything else runs on Node.
+
+## Start
+
+```sh
+oalo login <workspace>                            # <workspace>.oalo.ai: approve this machine in the browser
+oalo link --server https://<workspace>.oalo.ai    # this project; installs the skill for coding agents
+oalo typegen                                      # types for your models, workflows and helpers
+oalo link --status
+```
+
+## Discovering what it does
+
+```sh
+oalo --help              # overview
+oalo help typegen        # one command: flags, notes, exit codes
+oalo help --json         # machine-readable, for an agent driving the CLI
+```
+
+`help --json` describes every command, flag, exit code, token kind and
+environment variable in one object. Human and JSON forms come from the same
+registry, so they cannot disagree, and a test asserts the documented commands
+are exactly the dispatchable ones.
+
+Explicit help exits 0. Only an invalid invocation is non-zero (2 for an unknown
+command, 1 for no command at all).
+
+## Two token kinds
+
+They are not interchangeable, and `link` verifies each against the thing it is
+actually for, so a mix-up fails immediately instead of surfacing later as a
+confusing auth error.
+
+| kind | from | plane | used by |
+|---|---|---|---|
+| **sync** | `oalo login` (read-only), or Account → CLI & agents | data (`/api/sync/v1`) | `link`, `typegen`, `tail` |
+| **CLI** | `oalo login`, or Account → CLI & agents | the build surface | everything else, `mcp` included |
+
+`oalo login` gets you both as one **connection**, and so does "Create
+connection" on the dashboard's Account → CLI & agents page. A connection is
+listed as one row there and revoked as one.
+
+## Connecting a machine
+
+```sh
+oalo login <workspace>
+```
+
+It prints a short code and opens the dashboard on Account → CLI & agents.
+Check that the page shows the same code, then approve. The CLI saves both
+tokens to `~/.oalo/credentials.json` (mode `0600`, never in a project), and
+every command finds them by workspace URL. The code lasts 10 minutes and
+nothing is created until you approve. `--no-browser` prints the URL without
+opening it, for a remote shell. `oalo logout` revokes the connection on the
+server and forgets the tokens.
+
+On a machine with no browser (a server, a container), click **Create
+connection** on that page instead. It shows one `oalo link` command with both
+tokens filled in, plus the MCP config block. Those tokens are shown once.
+
+The login's data token is **read-only**: the CLI never writes through the sync
+API. Data tokens for an app's own servers, with write access or limited to some
+tables, are separate. Make those under **Sync API** in the dashboard.
+
+> **Server-side only.** A sync token carries no end-user identity, so it reads
+> and writes *every* member's rows. Never ship one inside a mobile or web app:
+> those authenticate their own users instead. See `tokens-and-credentials` in
+> the knowledge base.
+
+## What `link` writes
+
+| | |
+|---|---|
+| `.oalo/config.json` | project-local: workspace, app, env, last-seen schema version. **Safe to commit.** |
+| `~/.oalo/credentials.json` | the token, mode `0600`. **Never** in the project tree. |
+
+The token is written at user level by design, not by convention, so it cannot
+be committed by accident. `link` also adds `.oalo/credentials*` to `.gitignore`
+as a second line of defence. Set `OALO_HOME` to relocate the store (CI,
+containers, tests).
+
+`link` verifies the token against the workspace **before** saving anything. A
+link that reports success and then fails on first use is the worst outcome: you
+have no reason to suspect the credential, so you go looking for the bug in your
+own code.
+
+## dev vs prod
+
+App data lives in a `dev` and a `prod` schema, and `--env` decides which one
+every later command touches. It defaults to `dev` and is recorded in the config
+so it is explicit rather than ambient.
+
+## Linking also configures the MCP server
+
+`@oalo-ai/cli` falls back to the same credential store when `OALO_URL` /
+`OALO_CLI_TOKEN` are not set, so one `link` can serve both. (The two use
+different token kinds: the CLI uses a **sync** token for data, the MCP server a
+**CLI/MCP** token for the build surface.)
+
+## `oalo typegen`
+
+```sh
+oalo typegen                 # writes oalo.generated.ts
+oalo typegen --out src/oalo.ts
+oalo typegen --check         # non-zero if stale; use this in CI
+```
+
+Generates TypeScript from the workspace's own manifest, so the bindings describe
+*your* schema rather than a generic API. Commit the output.
+
+```ts
+import type { RowOf, DocumentOf, ModelName } from "./oalo.generated";
+import { MODELS } from "./oalo.generated";
+
+const row: RowOf<"clients"> = await loadSomehow();
+const id: number | undefined = row.document.user_id;   // typed
+const pk = MODELS.clients.primaryKey;                  // narrows to "id"
+```
+
+Three things worth knowing about the output:
+
+- **Document interfaces are open.** The manifest is a partial description, not a
+  closed schema: `clients` may declare only `user_id` while real rows also carry
+  `email`, `name` and `phone`. Declared fields are typed; the rest stay
+  reachable through an index signature. Closing them would make correct code
+  fail to compile.
+- **Types are named `<Table>Doc`** (`ClientsDoc`, `CatalogProductsDoc`) rather
+  than singularised. Singularising is a bug farm (quizzes, measurements,
+  stages), and the suffix says what the type is: the document body, not the
+  whole row.
+- **The env is stamped in the header.** `dev` and `prod` are separate schemas,
+  so bindings generated against one are not a promise about the other.
+
+Field types mirror `mix sync.gen.model` exactly, so the TypeScript and Dart
+generators cannot drift. Note `datetime` is an **epoch number**, not a string.
+
+If your token is table-scoped, typegen describes only the tables it can read.
+That is intended: the bindings then cover exactly what the caller can use.
+
+## `oalo tail`
+
+Watch the workspace while you work.
+
+```sh
+oalo tail                      # readable lines
+oalo tail --filter loop        # only events matching some text
+oalo tail --json | jq .        # one JSON object per line
+oalo tail --all                # include streaming chunk events
+```
+
+```
+19:09:01  jobs:update            running=0
+19:09:04  activity:event         phil saved "Onboarding"
+19:09:04  activity:event         phil deleted flow
+```
+
+This answers "I did a thing, did the thing I expected happen?" A flow that never
+fired shows up as silence rather than as a mystery.
+
+**What it shows:** loop and job state, builds and previews, team chat, and the
+activity stream (who changed what). It intercepts *every* push rather than a
+fixed list, so event types added later appear without a client update.
+
+**What it does not show:** direct writes through the Sync REST API. Those do
+not broadcast on this channel. You see their *consequences*: the loop a write
+triggered, the job it queued.
+
+Events go to stdout and the banner to stderr, so `oalo tail | grep ...` and
+`oalo tail --json | jq` both behave. Needs a **CLI** token, not a sync token.
+
+## `oalo run` and `oalo call`
+
+```sh
+oalo run loop Nurture --watch          # fire a loop, stream its nodes
+oalo run bot bot_5t0v… "hello"         # send a bot a test message
+oalo call jobs:snapshot | jq .          # any build-surface event
+oalo call loops:run_now '{"name":"Nurture"}'
+oalo call --list                        # events you can call, by namespace
+oalo call --list loops:                 # one namespace, with each event's params
+oalo emit form.submitted --dry-run      # which loops an event would fire
+oalo whoami                             # who and where the CLI acts, tokens checked
+```
+
+```
+started loop_hello (run 1750)
+19:37:54  loop_node_status       running step_1
+19:38:04  loop_node_status       done step_1
+19:38:04  loop_run_status        success
+```
+
+`run` stops as soon as the run reaches a terminal status, so `--timeout` is a
+ceiling rather than a wait. A loop that parks on a durable wait reports
+`waiting` and stops watching, because it may resume hours later.
+
+**`run loop` fires the loop directly and does NOT exercise its trigger.**
+Triggers come from the event bus (a real form submission, a real inbound
+message). So this proves the loop *body* works. To test the trigger, use
+`oalo emit`.
+
+`call` is the escape hatch. The build surface is ~500 events, and wrapping each
+as its own command would be a lot of surface for little gain, so first-class
+commands cover the common paths and `call` reaches the rest. Params are a JSON
+object; org and user identity always come from your token, never the params, so
+a call can never exceed what you can do.
+
+`call --list` asks the workspace which events you may call. The list comes from
+the server's own handlers, so it can't go stale, and it leaves out what your
+access would refuse. Give it text (`oalo call --list template`) to see the
+matching events with the param shapes each accepts. An unknown event says so;
+an event that exists but gets the wrong params says which params it takes; a
+wrong kind of id (`"nope"` where a number goes) says that, instead of a database
+error.
+
+## `oalo emit`
+
+```sh
+oalo emit --list                                         # events a trigger can listen for
+oalo emit form.submitted --payload '{"form":"quote"}' --dry-run
+oalo emit form.submitted --payload '{"form":"quote"}' --contact <contact id>
+```
+
+Fires a domain event through the real event bus, as if a form had been
+submitted or an order placed, so you can check that a loop's trigger and its
+payload filter are wired. `--dry-run` lists the loops it would fire and changes
+nothing; start there, because a real emit fires those loops for real, and they
+may email or message real contacts.
+
+The workspace keeps it safe to have around:
+
+- Only admins, and members an admin gave **Developer** access (Team panel), can
+  emit.
+- The type must be one a trigger can listen for. A typo gets "did you mean"
+  instead of an event nothing hears.
+- `--contact` must be an existing contact. emit never creates one.
+- Each event is stored tagged `cli:<you>` and posted to the team feed, so
+  nobody mistakes a test for a real customer.
+
+## `oalo whoami`
+
+Shows the workspace, who the CLI acts as (role, Developer access), the
+connection's name and last use, whether the data token works, and the
+workspace's API version. Run it first when a command is refused: it says which
+token is the problem. The CLI checks the workspace's version before commands
+that need newer server code, and says which side to update instead of failing
+halfway.
+
+## Editing flows, loops and tools: `pull`, `lint`, `push`, `status`
+
+```sh
+oalo pull                      # into .oalo/: flows, loops, code tools, node catalogs
+oalo lint                      # check edited files; nothing is saved
+oalo push                      # lint, then save each edited file
+oalo status                    # new / clean / modified / behind / conflict / gone
+```
+
+`pull` writes `.oalo/flows/<bot>/<flow>.json`, `.oalo/loops/<loop>.json`
+(app-pinned loops under `loops/apps/<app>/`), `.oalo/tools/<tool>.js` with its
+`.json`, and the node contracts `.oalo/catalog/flow.json` and `loop.json`. Each
+file keeps what you edit (`flow`, `loop`, `tool`, and a tool's `.js`) apart from
+the CLI's bookkeeping (`id`, `version`, `base_hash`).
+
+`push` is guarded three ways:
+
+- **Concurrent edits.** It sends the version you pulled. If someone saved in
+  between, the push is refused as a conflict and their copy is written next to
+  yours (`*.server.json`, or `*.server.js` for a tool) to merge from. `--force`
+  overwrites instead.
+- **Lint.** Saves are strict: a file with error-level findings is refused, and
+  each finding says what to fix. `--no-strict` saves anyway, but a graph that is
+  structurally broken (unknown node type, node without an id) is always refused.
+- **New files.** A file without a version creates a flow, loop or tool, unless
+  one with that name already exists, in which case it is refused rather than
+  replaced.
+
+`pull` never overwrites a file you have edited unless you pass `--force`.
+
+## Test conversations: `oalo qa`
+
+```sh
+oalo qa bot_xxx "hola" "busco un sofá" --channel whatsapp
+oalo qa bot_xxx --script quote.json --json
+```
+
+Sends each message, waits until the bot settles, and prints its replies, where
+any flow is (and what it waits for), the path of flow steps, and the cost.
+`--channel` makes the bot behave as on that channel: WhatsApp, Instagram and SMS
+run in text mode.
+
+The conversation is a hidden preview with no phone number, so nothing reaches a
+customer. Everything else is real: tools and flows run, contact details are
+saved, handoffs happen.
+
+## Teaching your coding agent: `oalo skill`
+
+`oalo skill` installs `.claude/skills/oalo/SKILL.md`, which Claude Code loads on
+its own: the pull, lint, push, qa loop and the rules that keep a live workspace
+safe. `--agents` writes the same rules into `AGENTS.md` for other agents.
+
+### As a Claude Code plugin
+
+The `plugin/` folder is a Claude Code plugin: the same skill plus the MCP server
+(`npx -y @oalo-ai/cli mcp`), and `.claude-plugin/marketplace.json` lists it. From
+a clone, or once this package's repository is public:
+
+```sh
+/plugin marketplace add <path or owner/repo>
+/plugin install oalo@oalo
+```
+
+## `oalo mcp`
+
+Serves this workspace over MCP so Claude Code, Cursor, or any MCP client can
+build flows, bots, tools and knowledge in it.
+
+```json
+{
+  "mcpServers": {
+    "oalo": {
+      "command": "npx",
+      "args": ["-y", "@oalo-ai/cli", "mcp"],
+      "env": {
+        "OALO_URL": "https://<workspace>.oalo.ai",
+        "OALO_CLI_TOKEN": "oalo_cli_..."
+      }
+    }
+  }
+}
+```
+
+The dashboard hands you this exact block when you create a connection. If you
+have already run `oalo login` (or `oalo link --cli-token`), the `env` entries
+are optional: the server falls back to the stored credential.
+
+The build surface is a channel with ~442 events, so the server exposes a
+**curated** subset as tools plus an `oalo_call` passthrough for the long tail.
+Mapping all of them would flood an agent's context and wreck tool selection.
+
+A CLI token **acts as you**: it inherits your permissions exactly and there is
+no read-only mode. Treat it like a password. Running the server does not disturb
+your dashboard session; both can be open at once.
+
+### Editing a flow safely
+
+`oalo_save_flow` has two traps, both encoded in its schema:
+
+- **`graph` replaces what is stored.** Not a patch. Read the flow first and send
+  every node and edge you want to keep.
+- **The read side calls it `version`; the write side wants `base_version`.**
+  Echo it back so a concurrent edit is rejected rather than silently
+  overwritten. (The server now also accepts `version`, but being explicit is
+  clearer.)
+
+## Development
+
+```sh
+npm run test:unit   # offline: the flow/loop/tool file format
+npm run smoke       # link + typegen + help contract, against a live server
+npm run smoke:mcp   # the MCP server, over the real protocol
+npm run smoke:mcp -- --write   # also exercises save_flow against a throwaway flow
+OALO_SMOKE_QA_BOT=bot_xxx npm run smoke:mcp   # also a real test conversation (spends model money)
+```
+
+`OALO_DEBUG=1` turns on transport logging (stderr).
+
+
+
+```sh
+OALO_URL=http://localhost:4242 OALO_SYNC_TOKEN=... npm run smoke
+```
+
+The suite runs entirely in a temp directory with `OALO_HOME` redirected, so it
+never touches the repo or a real credential store, and exits non-zero on
+failure. Set `OALO_TABLE_TOKEN` to a per-table token to also cover the regression where
+a table-scoped token could read rows but not the manifest, and
+`OALO_SMOKE_TSC` to a `tsc` binary to assert the generated bindings actually
+compile under `--strict`.