@workser/cli 0.1.0

package/AGENTS.md

@@ -0,0 +1,177 @@
+# Workser tools (for AI agents)
+
+> This file is the portable instruction layer for agents **without** native Skills
+> (Codex, Gemini CLI, Cursor, etc.). For Claude Code, the same content ships as a
+> Skill at `skills/workser/SKILL.md`. Workser Orbit drops the right one per agent.
+
+You have the `workser` CLI installed. Use it to **run** software on the user's
+behalf — provision infrastructure, deploy, and manage live apps on Workser. The
+agent thinks on the user's tokens; `workser` is how you act (DevOps + platform).
+
+## Use it for the "last mile"
+Writing code → your normal tools. Putting it online, databases, env vars, domains,
+deploy status, logs → `workser`.
+
+## What you can and can't do
+You are scoped to **one project** — the one Orbit linked to this directory. Within it
+you operate on the project's **own infrastructure**: provision and use its Neon
+Postgres database (`db create`, read its connection string, browse tables / schema /
+rows, run SQL), provision its bucket + auth, deploy, read/set env vars, manage files,
+read logs. Sensitive actions are **gated**: the daemon may return
+`error.code = "awaiting_approval"` (exit 5) and wait for the user to approve in Orbit
+— ask them to approve, then retry.
+
+What you **cannot** do is administer the project set or destroy config: creating or
+switching which project is pinned, deleting env vars, or attaching a custom domain.
+Those are **owner actions** — you get `error.code = "owner_only"` (exit 6). Don't
+retry or look for a workaround; tell the user it's an owner action and continue with
+what you *can* do.
+
+## Rules
+- **Always add `--json`.** Output is `{"ok":true,"data":...}` or `{"ok":false,"error":{...}}`.
+- Run `workser status --json` first to orient. The project is already selected for
+  you (Orbit pinned it); you don't pick or switch projects.
+- `error.code = "owner_only"` (exit 6) → an owner-only action. Tell the user to do
+  it in Orbit; never try to bypass it.
+- `error.code = "awaiting_approval"` (exit 5) → the user must approve in Orbit. Ask
+  them to approve, then retry. Never attempt to bypass approvals.
+- You never handle credentials — Orbit owns auth.
+
+## Commands
+```
+workser status | whoami                       # orient (read)
+workser project show | list                   # your pinned project + the workspace
+workser env set KEY=VALUE… | list | get KEY   # env vars
+workser db create                             # provision the Neon Postgres database
+workser db url | list                         # DB connection string + status
+workser db tables                             # list tables in the database
+workser db schema <table>                     # a table's columns
+workser db data <table> [-n N] [--offset N]   # read rows
+workser db query "<sql>"                      # run SQL (writes are approval-gated)
+workser auth enable | status                  # provision + inspect auth
+workser storage create [name] | list          # provision + show the bucket
+workser storage ls [prefix]                   # list objects in the bucket
+workser storage put <local> <key>             # upload a file into the bucket
+workser storage get <key> [dest]              # download (or print the object URL)
+workser deploy [--prod] [--watch] | deploy status [id]
+workser logs [-n N] [-f] | versions
+workser domain list                           # custom domains (read)
+workser open
+workser agent list | run <role> "<task>" | main
+workser workflow list | create <name> [--body <json>] | get <id>
+workser workflow activate <id> | deactivate <id> | run <id> [--wait] [--body <json>]
+workser workflow runs <id>                    # past executions of a workflow
+workser workflow nodes [query]                # search the node-type catalog
+workser app list [--toolkit <slug>]           # connectable + connected third-party apps
+workser app connect <toolkit> | disconnect <connectionId>
+workser app tools <toolkit>                   # a connected app's callable actions
+workser app run <toolSlug> [--body <json>]    # execute one action (e.g. GOOGLESHEETS_APPEND_ROW)
+
+workser tool list                             # computer-use tools available to you now
+workser tool run <name> [--body <json>]       # filesystem/shell/screenshot/input/clipboard/browser
+
+workser memory add "<content>" [--metadata <json>]  # remember something across future conversations
+workser memory search "<query>" [--limit N]         # recall what you (or a cloud agent) learned before
+workser memory forget <memoryId>                    # soft-delete an outdated/incorrect memory
+
+workser artifact add <path> [--kind <k>] [-d <text>]  # record a finished deliverable
+workser artifact add --url <url> --kind app          # record a deployed app
+workser artifact run                                 # which task you're attached to
+
+workser ask "<question>" [--type <t>] [--option <o>] # ask the user, WAIT for the answer
+
+# owner-only (will return owner_only / exit 6 — ask the user to do these in Orbit):
+#   project create, project use, env rm, domain set
+```
+
+## Memory (remember across conversations, not just this one)
+Every conversation you run is otherwise a fresh start — no memory of what you or the
+user decided last time. `workser memory add "<content>"` fixes that: it stores durable,
+searchable memory for the CURRENT PROJECT, and it's the SAME memory space Workser's own
+cloud agents write to for this project — add something here and a cloud agent (or your
+own next conversation) can `workser memory search` and find it. Use it for things worth
+remembering past this one conversation: user preferences, decisions made, important
+context, requirements — not routine chatter. Before assuming you don't know something
+about this project, `workser memory search "<topic>"` first; it may already be recorded.
+`forget` soft-deletes a specific memory if it's wrong or outdated.
+
+## Record what you produced (deliverables)
+Workser shows the user a **Deliverables** list on the task. If you don't say what you
+made, it has to guess — it watches your file edits and treats any path it sees as a
+deliverable, so scratch files and half-finished drafts show up next to the real output,
+and things that aren't files at all (a folder of results, an app you deployed) can't
+show up correctly. Fix that by declaring finished output:
+```
+workser artifact add ./report.pdf -d "Q3 sales summary"
+workser artifact add ./exports --kind folder -d "generated CSVs"
+workser artifact add --url https://acme.workser.app --kind app -t "Storefront"
+```
+Only register FINISHED output the user should get — not temp files, not intermediate
+steps. `--kind` is inferred from the path when you omit it (directories are detected
+automatically); pass it explicitly for `app` / `url`. `workser artifact run` shows which
+task you're currently attached to.
+
+To publish an app: `workser deploy` (preview) or `workser deploy --prod` (live), then
+register the URL it returns as an `app` artifact so the user can open it from the task.
+
+## Ask the user something (and get an answer back)
+When you're blocked — a missing value, an ambiguous requirement, permission for
+something consequential — don't guess and don't just write the question into your
+final message. Run:
+```
+workser ask "Which email should order confirmations come from?"
+workser ask "Which plan should I wire up?" --option Free --option Pro --option Team
+workser ask "Delete the 1,240 archived rows?" --type approval
+```
+This shows the user a real card in the conversation and **blocks until they answer**,
+then prints their answer — so you ask, read the reply, and keep working in the same
+turn. Types: `input` (default, free text), `choice` (with `--option`), `approval`
+(permission), `confirmation` (check an assumption), `information` (FYI, no answer
+needed). It times out (default 10 min) rather than hanging forever; if it does, carry
+on and state clearly what you assumed.
+
+**Never ask for a secret value this way** — the answer is stored and displayed. Ask
+where a key should go, then have the user set it (`workser env set` writes it without
+you ever seeing it).
+
+## Computer-use tools (your hands on this machine)
+`workser tool list` shows what's available — filesystem (read/write/list/delete/move),
+shell (run a command/Python/Node), screenshots and screen info, mouse/keyboard input,
+clipboard, notifications, and basic browser control (open a URL, read the page, click/
+fill/type, screenshot). This is the SAME engine Workser's cloud Computer Use agent uses
+when it controls a user's machine remotely — you get it locally, gated by the same
+safety policy (blocked paths like `~/.ssh`, blocked destructive commands, rate limits).
+Sensitive actions (writing/deleting files, running a shell command, clicking/typing) may
+return `awaiting_approval` (exit 5) — handle it the same as any other gated action: tell
+the user to approve in Orbit, then retry. This is a curated subset, not full desktop
+automation — check `workser tool list` rather than assuming a capability exists.
+
+## Workflow automation & app integrations
+Beyond one-shot code, you can wire up **automations** that keep running after you're
+done: `workser workflow create` builds an event-driven, multi-step automation (the
+same engine Workser's own web Workflow tab uses) — nodes, connections, and triggers go
+in `--body` as JSON; browse `workser workflow nodes` first to see what's available.
+Before an automation can use a third-party app (Gmail, Slack, Stripe, Google Sheets,
+...), the user connects it once via `workser app connect <toolkit>` (this opens an
+OAuth link — ask the user to complete it, then continue); after that, `workser app
+run <toolSlug> --body '{"...":...}'` calls any of its actions directly, and a workflow
+node can call the same toolkit. Use `workser app list` to see what's already
+connected before assuming you need to ask the user to connect something new.
+
+## Delegate to roles
+The user can configure **roles** — named specialists each backed by a local CLI agent
+(e.g. `qa` → codex, `designer` → claude_code). Delegate a focused subtask with
+`workser agent run <role> "<task>" --json`; the role runs as an **isolated local
+subagent** (own context) and returns `{role, agent, output, exitCode}`. Run
+`workser agent list --json` first to see the configured, runnable roles. Use this to
+keep your own context lean and get a specialized second perspective; a non-zero
+`exitCode` means the role's run failed — surface it.
+
+## Example
+```bash
+workser status --json                  # orient: which project, last deploy
+workser env set STRIPE_KEY=sk_live_… --json
+# … you write the app code with your normal tools …
+workser deploy --prod --watch --json   # -> .data.url is the live URL
+```
+Report results to the user in plain language, not raw JSON.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Workser
+
+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

@@ -0,0 +1,178 @@
+# @workser/cli — `workser`
+
+**The center of Workser Orbit.** `workser` is the command-line surface that lets a
+local AI agent use Workser infrastructure natively — as the user's DevOps engineer.
+The agent runs `workser deploy`, `workser env set`, `workser status`, etc. through
+its own shell to ship and operate the app on Workser.
+
+## Install
+
+```bash
+npm install -g @workser/cli
+workser --version
+```
+
+Node 20+. If you use **Workser Desktop**, it installs and updates this for you —
+you only need the manual install to use `workser` on its own, alongside Claude
+Code, Codex, Cursor or any other agent.
+
+### Using it standalone
+
+Inside Workser Desktop the CLI talks to the local Orbit daemon, so every call
+flows through the app's approval gates. On its own it talks to the Workser cloud
+API instead:
+
+```bash
+workser login            # paste an API token, or pass --token
+workser status           # confirm the connection and the linked project
+workser doctor           # resolved endpoint, mode, token presence (masked)
+```
+
+Point your agent at it by telling it the command exists. For Claude Code, the
+package ships a skill at `skills/workser/SKILL.md`; for Codex, Gemini, Kimi and
+others, `AGENTS.md` covers the same ground. Copy whichever your agent reads:
+
+```bash
+# Claude Code (global)
+mkdir -p ~/.claude/skills/workser
+cp "$(npm root -g)/@workser/cli/skills/workser/SKILL.md" ~/.claude/skills/workser/
+
+# Codex / Gemini / Kimi / opencode / Grok — merge into your project's AGENTS.md
+cat "$(npm root -g)/@workser/cli/AGENTS.md" >> AGENTS.md
+```
+
+Agents should always pass `--json`.
+
+
+
+### Scope: one project, operate within it
+
+The CLI is the **agent-facing** surface, and it is deliberately small. It is bound
+to the **single project** Orbit linked to the working directory. Within that project
+the agent can **operate on the project's own infrastructure** — provision and use its
+Neon Postgres database (create it, read its least-privilege connection string, browse
+tables / schema / rows / run SQL), provision its bucket + auth, deploy, read/set env
+vars, manage objects, read logs. The daemon **gates the sensitive actions** with an
+approval prompt in the Orbit UI (`awaiting_approval`, exit 5), so the user stays in
+the loop without the CLI having to refuse outright.
+
+What stays **owner-only** (refuses with `error.code = "owner_only"`, exit 6, no
+network call) is **administering the project set or destroying config**: creating or
+switching which project is pinned, deleting env vars, and attaching custom domains.
+This is the first of two gates — the daemon + core-api enforce the boundary
+server-side too. See `src/capabilities.ts`.
+
+It's designed to be the **token-lean** primary integration (vs. injecting MCP tool
+schemas into the agent's context on every turn): a shell call costs almost nothing,
+and the agent is taught *when* to use it via a Skill (Claude) or `AGENTS.md`
+(other agents). MCP stays available, but only inside a scoped subagent — see the
+platform plans in `workser-agents-platform/`.
+
+## How it connects
+
+`workser` is a thin client of one endpoint contract, resolved in this order:
+
+| Resolves | Precedence |
+|---|---|
+| **endpoint** | `--endpoint` → `$WORKSER_DAEMON_URL` → `~/.workser/session.json` → cloud default |
+| **token** | `--token` → `$WORKSER_TOKEN` → session file |
+| **project** | `--project` → `<cwd>/.workser/project.json` → session default |
+
+- **Inside Workser Orbit (primary):** the app writes `~/.workser/session.json`
+  pointing at its **local daemon** (`http://127.0.0.1:<port>`). Calls flow through
+  the cockpit, which handles **auth (bridge JWT), approval gates, and live progress
+  in the UI**. This is how the user *sees* what the agent does.
+- **Standalone / CI:** `workser login --token <t>` saves a session against the
+  **cloud API** (`https://api.workser.ai`). Same commands, no desktop app.
+
+Both speak the same `/v1/...` contract (see `src/client.ts`).
+
+## Install (dev)
+
+```bash
+npm install
+npm run build
+npm link          # makes `workser` available globally for local testing
+workser --help
+```
+
+### Packaging (single self-contained file)
+
+`npm run build` produces **one** self-contained executable: `dist/index.js`. tsup
+bundles every runtime dependency (`commander`, `picocolors`) inline, keeps the
+`#!/usr/bin/env node` shebang, and inlines the version — so the file runs under the
+system `node` from any directory, with **no `node_modules`** alongside it.
+
+The Orbit desktop connector relies on this: it copies exactly that one file to
+`~/.workser/bin/workser` (and `chmod +x`) to install the CLI on the agent's PATH
+during onboarding — no `npm install`, no dependency tree to ship. The binary is also
+published as `@workser/cli`.
+
+## Command surface
+
+```
+workser status | whoami | login | logout
+workser project show | list                       # the pinned project + workspace (read)
+workser db create                                 # provision Neon Postgres (idempotent)
+workser db url | list                             # connection string + status
+workser db tables | schema <t> | data <t> | query <sql>   # browse the Neon database
+workser auth enable | status                      # provision + inspect auth
+workser env set KEY=VALUE… | get KEY | list       # env vars
+workser storage create [name] | list | ls [prefix]     # bucket + its objects
+workser storage put <local> <key> | get <key> [dest]   # objects in the bucket
+workser deploy [--prod] [--watch] | deploy status [id]
+workser logs [-n N] [-f] | versions
+workser domain list                               # custom domains (read)
+workser open | verify | doctor
+workser agent list | run <role> "<task>" | main
+
+# owner-only — refuse with owner_only (exit 6), no network call:
+workser project create · project use · env rm · domain set
+```
+
+Global flags: `--json`, `-q/--quiet`, `-p/--project <id>`, `-C/--cwd <dir>`,
+`--endpoint <url>`, `--token <token>`.
+
+## Design principles (the contract)
+
+1. **Agent-first output.** Every command supports `--json`, returning a single
+   stable line: `{"ok":true,"data":...}` or `{"ok":false,"error":{code,message,...}}`.
+   Human text output is terse and colorized.
+2. **Stable exit codes.** `0` ok · `1` generic · `3` unauthorized · `4` not connected
+   · `5` awaiting approval · `6` owner-only.
+3. **Least privilege by construction.** One project; the agent operates on *that*
+   project's own infra (sensitive actions daemon-gated). Administering the project
+   set or destroying config is owner-only (`owner_only`, exit 6); it refuses locally
+   and is also unreachable with the agent's scoped key server-side.
+4. **Approvals belong to the daemon.** Allowed-but-gated calls can return
+   `awaiting_approval`; the user approves in Orbit. The CLI never bypasses gates.
+5. **No credential handling.** Auth lives in Orbit / the session token; the agent
+   never sees raw keys.
+
+## Layout
+
+```
+src/
+  index.ts          # program + global flags, registers commands
+  run.ts            # action() wrapper: builds context, funnels errors
+  context.ts        # resolve endpoint/token/project (daemon vs cloud)
+  client.ts         # the single fetch() entrypoint + /v1 contract docs
+  capabilities.ts   # the owner-only boundary (what the agent may NOT do)
+  config.ts         # ~/.workser/session.json + <cwd>/.workser/project.json
+  output.ts         # ok()/fail()/line() — text & --json rendering
+  errors.ts         # WorkserError (code + status)
+  commands/         # one file per command group
+skills/workser/SKILL.md   # Claude Code Skill (progressive disclosure)
+AGENTS.md                 # portable instructions for non-Skill agents
+```
+
+## Status
+
+v0.1. The `/v1/...` endpoints are the contract implemented by the Orbit local daemon
+(which proxies `workser-core-api-service`'s `orbit` controller and wraps replies in
+`{ok,data}`); commands are aligned to that contract — including the Neon Postgres
+browser (`db tables|schema|data|query`) — and verified live against the running
+daemon. The suite (`npm test`) exercises every command against an in-process daemon
+stub: request shapes, provisioning, the Neon browser, the storage object flow, exit
+codes, nested-error normalization, and the owner-only boundary. Next: enforce the same
+owner-only boundary server-side on the agent's project-scoped key (the second gate).