octwin-cli 0.1.0 → 0.1.2

package/README.md

@@ -1,65 +1,132 @@
 # octwin-cli
 
-The **Octwin** external-pack developer CLI, by **CEQUENS**. Scaffold a pure-YAML
-pack in your own repo, validate it offline, and deploy it to a running Octwin
-platform to test on your own tenant — no platform checkout, no build step.
+> The **Octwin** external-pack developer CLI — scaffold, validate, deploy, and manage pure-YAML packs on your own tenant. By **CEQUENS**.
 
-The package is `octwin-cli`; the command it installs is `octwin`.
+[![npm version](https://img.shields.io/npm/v/octwin-cli.svg)](https://www.npmjs.com/package/octwin-cli)
+[![license](https://img.shields.io/npm/l/octwin-cli.svg)](https://www.npmjs.com/package/octwin-cli)
+[![node](https://img.shields.io/node/v/octwin-cli.svg)](https://nodejs.org)
+
+Octwin is a pack-pluggable conversational-agent platform for WhatsApp and web. A **pack** is a
+self-contained bot domain — its agent, conversation flows, prompts, and data model — declared
+entirely in YAML. `octwin-cli` lets you build a **pure-YAML pack** in your own repo and deploy it
+to a running Octwin platform to test live on your own tenant: no platform checkout, no build step,
+and nothing untrusted to run (a pure-YAML pack is declarative data, so the platform can safely run
+it alongside other tenants).
+
+> The npm package is **`octwin-cli`**; the command it installs is **`octwin`**.
+
+## Requirements
+
+- **Node.js ≥ 20**
+- Access to an **Octwin platform** (its base URL), a **tenant** (your workspace) on it, and a
+  **deploy token** (generated in the Octwin console — see [Authentication](#authentication)).
 
 ## Install
 
 ```bash
-# zero-install (recommended)
-npx octwin-cli <command>
+# zero-install — always the latest version
+npx octwin-cli@latest <command>
 
-# or install the command globally
-npm i -g octwin-cli
+# …or install the `octwin` command globally
+npm install -g octwin-cli
 octwin <command>
 ```
 
-## The loop
+## Quick start
 
 ```bash
-# 1. Scaffold a standalone pure-YAML pack (yours)
+# 1. Scaffold a standalone pure-YAML pack (this is your repo)
 octwin init ./my-pack --id my-pack --description "My business bot"
-cd ./my-pack && git init && git add -A && git commit -m "init pack"
+cd ./my-pack
+git init && git add -A && git commit -m "init pack"
 
-# 2. Author: edit manifest.yaml, flows/tools/main.flow.yaml (+ locale),
-#    prompts/identity.md. Everything is pure YAML/SQL — no TypeScript.
+# 2. Author it — edit manifest.yaml, flows/tools/main.flow.yaml (+ its locale),
+#    and prompts/identity.md. Everything is pure YAML.
 
-# 3. Validate locally (same structural gate the server runs)
+# 3. Point it at your platform: edit pack.json, then log in with a deploy token
+#    (Octwin console → your workspace → API tokens → Generate)
+octwin login --url https://your-octwin.example.com --token oct_…
+
+# 4. Validate → deploy → confirm it's live
 octwin validate
+octwin deploy --seed        # --seed also loads any demo data the pack declares
+octwin status               # "✓ live and current" once it's warm
 
-# 4. Log in with a DEPLOY TOKEN from the console (Workspace → API tokens →
-#    Generate), then deploy. Point pack.json at your platform + tenant first.
-octwin login  --url https://platform.example.com --token cqp_…
-octwin whoami --tenant my-tenant
-octwin deploy --tenant my-tenant --project main          # add --seed to seed demo data
+# 5. Chat with it on your tenant (web widget / console test page). Edit and
+#    `octwin deploy` again — a redeploy hot-loads with no restart.
+```
 
-# 5. Confirm it landed — which version is live?
-octwin status --tenant my-tenant --project main
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `octwin init <dir>` | Scaffold a new pure-YAML pack into `<dir>` (writes a starter `manifest.yaml`, flow, prompt, and `pack.json`). Options: `--id`, `--description`, `--display-name`. |
+| `octwin validate` | Check the pack locally (structure + pure-YAML rules). The platform re-validates the full manifest/flow schema on deploy. |
+| `octwin login` | Save a deploy token for a platform URL (stored in `~/.octwin/credentials.json`). `--url`, `--token`. |
+| `octwin whoami` | Verify the saved/passed token is valid for a tenant. `--url`, `--tenant`. |
+| `octwin deploy` | Upload + install the pack onto your tenant's project. `--seed` also runs the pack's demo seed. |
+| `octwin status` | Report what the platform has live for this pack — installed vs. loaded version, and its flows. |
+| `octwin test` | Validate locally and print how to try the pack on your tenant. |
+| `octwin help` | Show usage. |
+
+Every command that talks to the platform accepts `--dir <path>` (the pack directory; defaults to
+the current directory) plus the target overrides `--url` / `--tenant` / `--project` / `--token`.
+
+## Configuration
+
+The deploy target has four settings. Three live in a committed **`pack.json`** at the root of your
+pack; the **token is a secret** and is kept out of `pack.json` (set it with `octwin login`).
+
+```jsonc
+// pack.json  — created by `octwin init`
+{
+  "platform_url": "https://your-octwin.example.com",  // your Octwin platform
+  "tenant":       "my-tenant-slug",                    // your workspace (required)
+  "project":      "main"                               // defaults to "main"
+}
+```
 
-# 6. Chat on your tenant (web widget / console test page). Edit → deploy again:
-#    a redeploy hot-loads with no restart; re-run `octwin status` to confirm.
+```bash
+octwin login --url https://your-octwin.example.com --token oct_…   # saves the token once
 ```
 
-## Auth — the deploy token
+Each setting resolves in this order — **flag → environment variable → `pack.json` → default**:
+
+| Setting | Flag | Env var | `pack.json` key |
+| --- | --- | --- | --- |
+| Platform URL | `--url` | `PACK_PLATFORM_URL` | `platform_url` |
+| Tenant slug | `--tenant` | `PACK_TENANT` | `tenant` |
+| Project slug | `--project` | `PACK_PROJECT` | `project` (default `main`) |
+| Deploy token | `--token` | `PACK_TOKEN` | — *(use `octwin login`)* |
 
-You authenticate with a tenant-scoped **deploy token** (`cqp_…`), not a password
-and not an operator token. It is least-privilege (scope `pack:deploy`) and
-revocable in the console. Add the **`media:generate`** scope to let a `--seed`
-deploy AI-generate seed images (a demo field `photo: 'generate:<prompt>'`).
+For **CI**, skip `pack.json`/`login` entirely and pass `PACK_PLATFORM_URL`, `PACK_TENANT`,
+`PACK_PROJECT`, and `PACK_TOKEN` as environment variables.
 
-## Config resolution (deploy/status)
+## Authentication
 
-`flags` > `pack.json` (in the pack dir) > env (`PACK_PLATFORM_URL`, `PACK_TENANT`,
-`PACK_PROJECT`, `PACK_TOKEN`) > saved login (`~/.octwin/credentials.json`).
+You authenticate with a tenant-scoped **deploy token** (prefixed `oct_…`) — not a password and not
+an operator token. Generate it in the Octwin console (**your workspace → API tokens → Generate**).
+It is **least-privilege** (scope `pack:deploy`): it can deploy packs to your tenant but cannot
+manage members, billing, or other tenants, and it is revocable at any time.
+
+Add the optional **`media:generate`** scope to let a `--seed` deploy AI-generate seed images
+(for a demo record field like `photo: "generate:<prompt>"`); without it, such fields are seeded as
+text only.
 
 ## What a pack may contain
 
-Pure declarative data only — YAML + SQL (`.yaml`/`.yml`/`.md`/`.sql`/`.json`).
-No `.ts`/`.js`, no `routes/`, no `db/client.*`, no `*.primitives.*`. This is what
-makes an external pack safe to run on the shared platform; the server enforces it
-on deploy. Persist domain records with the platform's first-class **XRM** /
-**catalog** / **casework** modules (declared in `xrm.yaml` / `cases.yaml`) — no
-pack database required.
+A pack is **pure declarative data** — `.yaml` / `.yml` / `.md` / `.sql` / `.json` only. Executable
+code (`.ts`/`.js`), HTTP routes, DB clients, and custom primitives are **not** allowed (this is what
+makes an external pack safe to run on a shared platform; the server enforces it on deploy). For
+domain records, use Octwin's first-class storage modules — **XRM** (records with stage pipelines),
+**catalog** (products), or **casework** (tickets) — declared in `xrm.yaml` / `cases.yaml`, so a pack
+needs **no database of its own**.
+
+## Links
+
+- **npm:** <https://www.npmjs.com/package/octwin-cli>
+- **Command help:** `octwin help`
+
+## License
+
+[MIT](./LICENSE) © CEQUENS

package/dist/index.js

@@ -9,7 +9,7 @@
  *
  *   octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
  *   octwin validate [--dir .]
- *   octwin login   --url <platformUrl> --token cqp_…
+ *   octwin login   --url <platformUrl> --token oct_…
  *   octwin whoami  [--url <url>] [--tenant <slug>]
  *   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
  *   octwin status  [--dir .]        # did my deploy land? which version is live?
@@ -193,7 +193,7 @@ function resolveTarget(flags, packDir) {
     if (!tenant)
         die('no tenant — set it in pack.json, --tenant, or PACK_TENANT');
     if (!token)
-        die('no token — generate a deploy token in the console (Settings → API tokens), then `octwin login --url <url> --token cqp_…` or pass --token');
+        die('no token — generate a deploy token in the console (Settings → API tokens), then `octwin login --url <url> --token oct_…` or pass --token');
     return { url, tenant, project, token };
 }
 async function cmdWhoami(flags) {
@@ -201,7 +201,7 @@ async function cmdWhoami(flags) {
     const { url, tenant, token } = resolveTarget(flags, packDir);
     const res = await fetch(`${url}/api/admin/tenants/${tenant}/packs`, { headers: { authorization: `Bearer ${token}` } });
     if (res.ok) {
-        console.log(`✓ Token valid for tenant '${tenant}' at ${url} (${token.startsWith('cqp_') ? 'deploy token' : 'session token'})`);
+        console.log(`✓ Token valid for tenant '${tenant}' at ${url} (${token.startsWith('oct_') ? 'deploy token' : 'session token'})`);
         return;
     }
     const why = res.status === 401 ? 'invalid / expired / revoked token'
@@ -296,7 +296,7 @@ function help() {
 
   octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
   octwin validate [--dir .]
-  octwin login   --url <platformUrl> --token cqp_…      # a deploy token from the console
+  octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
   octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
   octwin status  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {
@@ -29,6 +29,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "keywords": ["octwin", "cequens", "cli", "whatsapp", "chatbot", "pack"],
+  "keywords": ["octwin", "cequens", "cli", "whatsapp", "chatbot", "pack", "conversational-ai", "yaml"],
+  "author": "CEQUENS",
+  "homepage": "https://www.npmjs.com/package/octwin-cli",
   "license": "MIT"
 }