octwin-cli 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +104 -37
  2. package/package.json +4 -2
package/README.md CHANGED
@@ -1,65 +1,132 @@
1
1
  # octwin-cli
2
2
 
3
- The **Octwin** external-pack developer CLI, by **CEQUENS**. Scaffold a pure-YAML
4
- pack in your own repo, validate it offline, and deploy it to a running Octwin
5
- platform to test on your own tenant — no platform checkout, no build step.
3
+ > The **Octwin** external-pack developer CLI — scaffold, validate, deploy, and manage pure-YAML packs on your own tenant. By **CEQUENS**.
6
4
 
7
- The package is `octwin-cli`; the command it installs is `octwin`.
5
+ [![npm version](https://img.shields.io/npm/v/octwin-cli.svg)](https://www.npmjs.com/package/octwin-cli)
6
+ [![license](https://img.shields.io/npm/l/octwin-cli.svg)](https://www.npmjs.com/package/octwin-cli)
7
+ [![node](https://img.shields.io/node/v/octwin-cli.svg)](https://nodejs.org)
8
+
9
+ Octwin is a pack-pluggable conversational-agent platform for WhatsApp and web. A **pack** is a
10
+ self-contained bot domain — its agent, conversation flows, prompts, and data model — declared
11
+ entirely in YAML. `octwin-cli` lets you build a **pure-YAML pack** in your own repo and deploy it
12
+ to a running Octwin platform to test live on your own tenant: no platform checkout, no build step,
13
+ and nothing untrusted to run (a pure-YAML pack is declarative data, so the platform can safely run
14
+ it alongside other tenants).
15
+
16
+ > The npm package is **`octwin-cli`**; the command it installs is **`octwin`**.
17
+
18
+ ## Requirements
19
+
20
+ - **Node.js ≥ 20**
21
+ - Access to an **Octwin platform** (its base URL), a **tenant** (your workspace) on it, and a
22
+ **deploy token** (generated in the Octwin console — see [Authentication](#authentication)).
8
23
 
9
24
  ## Install
10
25
 
11
26
  ```bash
12
- # zero-install (recommended)
13
- npx octwin-cli <command>
27
+ # zero-install — always the latest version
28
+ npx octwin-cli@latest <command>
14
29
 
15
- # or install the command globally
16
- npm i -g octwin-cli
30
+ # …or install the `octwin` command globally
31
+ npm install -g octwin-cli
17
32
  octwin <command>
18
33
  ```
19
34
 
20
- ## The loop
35
+ ## Quick start
21
36
 
22
37
  ```bash
23
- # 1. Scaffold a standalone pure-YAML pack (yours)
38
+ # 1. Scaffold a standalone pure-YAML pack (this is your repo)
24
39
  octwin init ./my-pack --id my-pack --description "My business bot"
25
- cd ./my-pack && git init && git add -A && git commit -m "init pack"
40
+ cd ./my-pack
41
+ git init && git add -A && git commit -m "init pack"
26
42
 
27
- # 2. Author: edit manifest.yaml, flows/tools/main.flow.yaml (+ locale),
28
- # prompts/identity.md. Everything is pure YAML/SQL — no TypeScript.
43
+ # 2. Author it — edit manifest.yaml, flows/tools/main.flow.yaml (+ its locale),
44
+ # and prompts/identity.md. Everything is pure YAML.
29
45
 
30
- # 3. Validate locally (same structural gate the server runs)
46
+ # 3. Point it at your platform: edit pack.json, then log in with a deploy token
47
+ # (Octwin console → your workspace → API tokens → Generate)
48
+ octwin login --url https://your-octwin.example.com --token oct_…
49
+
50
+ # 4. Validate → deploy → confirm it's live
31
51
  octwin validate
52
+ octwin deploy --seed # --seed also loads any demo data the pack declares
53
+ octwin status # "✓ live and current" once it's warm
32
54
 
33
- # 4. Log in with a DEPLOY TOKEN from the console (Workspace → API tokens →
34
- # Generate), then deploy. Point pack.json at your platform + tenant first.
35
- octwin login --url https://platform.example.com --token oct_…
36
- octwin whoami --tenant my-tenant
37
- octwin deploy --tenant my-tenant --project main # add --seed to seed demo data
55
+ # 5. Chat with it on your tenant (web widget / console test page). Edit and
56
+ # `octwin deploy` again — a redeploy hot-loads with no restart.
57
+ ```
38
58
 
39
- # 5. Confirm it landed — which version is live?
40
- octwin status --tenant my-tenant --project main
59
+ ## Commands
60
+
61
+ | Command | What it does |
62
+ | --- | --- |
63
+ | `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`. |
64
+ | `octwin validate` | Check the pack locally (structure + pure-YAML rules). The platform re-validates the full manifest/flow schema on deploy. |
65
+ | `octwin login` | Save a deploy token for a platform URL (stored in `~/.octwin/credentials.json`). `--url`, `--token`. |
66
+ | `octwin whoami` | Verify the saved/passed token is valid for a tenant. `--url`, `--tenant`. |
67
+ | `octwin deploy` | Upload + install the pack onto your tenant's project. `--seed` also runs the pack's demo seed. |
68
+ | `octwin status` | Report what the platform has live for this pack — installed vs. loaded version, and its flows. |
69
+ | `octwin test` | Validate locally and print how to try the pack on your tenant. |
70
+ | `octwin help` | Show usage. |
71
+
72
+ Every command that talks to the platform accepts `--dir <path>` (the pack directory; defaults to
73
+ the current directory) plus the target overrides `--url` / `--tenant` / `--project` / `--token`.
74
+
75
+ ## Configuration
76
+
77
+ The deploy target has four settings. Three live in a committed **`pack.json`** at the root of your
78
+ pack; the **token is a secret** and is kept out of `pack.json` (set it with `octwin login`).
79
+
80
+ ```jsonc
81
+ // pack.json — created by `octwin init`
82
+ {
83
+ "platform_url": "https://your-octwin.example.com", // your Octwin platform
84
+ "tenant": "my-tenant-slug", // your workspace (required)
85
+ "project": "main" // defaults to "main"
86
+ }
87
+ ```
41
88
 
42
- # 6. Chat on your tenant (web widget / console test page). Edit → deploy again:
43
- # a redeploy hot-loads with no restart; re-run `octwin status` to confirm.
89
+ ```bash
90
+ octwin login --url https://your-octwin.example.com --token oct_… # saves the token once
44
91
  ```
45
92
 
46
- ## Auth — the deploy token
93
+ Each setting resolves in this order — **flag → environment variable → `pack.json` → default**:
94
+
95
+ | Setting | Flag | Env var | `pack.json` key |
96
+ | --- | --- | --- | --- |
97
+ | Platform URL | `--url` | `PACK_PLATFORM_URL` | `platform_url` |
98
+ | Tenant slug | `--tenant` | `PACK_TENANT` | `tenant` |
99
+ | Project slug | `--project` | `PACK_PROJECT` | `project` (default `main`) |
100
+ | Deploy token | `--token` | `PACK_TOKEN` | — *(use `octwin login`)* |
47
101
 
48
- You authenticate with a tenant-scoped **deploy token** (`oct_…`), not a password
49
- and not an operator token. It is least-privilege (scope `pack:deploy`) and
50
- revocable in the console. Add the **`media:generate`** scope to let a `--seed`
51
- deploy AI-generate seed images (a demo field `photo: 'generate:<prompt>'`).
102
+ For **CI**, skip `pack.json`/`login` entirely and pass `PACK_PLATFORM_URL`, `PACK_TENANT`,
103
+ `PACK_PROJECT`, and `PACK_TOKEN` as environment variables.
52
104
 
53
- ## Config resolution (deploy/status)
105
+ ## Authentication
54
106
 
55
- `flags` > `pack.json` (in the pack dir) > env (`PACK_PLATFORM_URL`, `PACK_TENANT`,
56
- `PACK_PROJECT`, `PACK_TOKEN`) > saved login (`~/.octwin/credentials.json`).
107
+ You authenticate with a tenant-scoped **deploy token** (prefixed `oct_…`) — not a password and not
108
+ an operator token. Generate it in the Octwin console (**your workspace → API tokens → Generate**).
109
+ It is **least-privilege** (scope `pack:deploy`): it can deploy packs to your tenant but cannot
110
+ manage members, billing, or other tenants, and it is revocable at any time.
111
+
112
+ Add the optional **`media:generate`** scope to let a `--seed` deploy AI-generate seed images
113
+ (for a demo record field like `photo: "generate:<prompt>"`); without it, such fields are seeded as
114
+ text only.
57
115
 
58
116
  ## What a pack may contain
59
117
 
60
- Pure declarative data only — YAML + SQL (`.yaml`/`.yml`/`.md`/`.sql`/`.json`).
61
- No `.ts`/`.js`, no `routes/`, no `db/client.*`, no `*.primitives.*`. This is what
62
- makes an external pack safe to run on the shared platform; the server enforces it
63
- on deploy. Persist domain records with the platform's first-class **XRM** /
64
- **catalog** / **casework** modules (declared in `xrm.yaml` / `cases.yaml`) — no
65
- pack database required.
118
+ A pack is **pure declarative data** — `.yaml` / `.yml` / `.md` / `.sql` / `.json` only. Executable
119
+ code (`.ts`/`.js`), HTTP routes, DB clients, and custom primitives are **not** allowed (this is what
120
+ makes an external pack safe to run on a shared platform; the server enforces it on deploy). For
121
+ domain records, use Octwin's first-class storage modules — **XRM** (records with stage pipelines),
122
+ **catalog** (products), or **casework** (tickets) — declared in `xrm.yaml` / `cases.yaml`, so a pack
123
+ needs **no database of its own**.
124
+
125
+ ## Links
126
+
127
+ - **npm:** <https://www.npmjs.com/package/octwin-cli>
128
+ - **Command help:** `octwin help`
129
+
130
+ ## License
131
+
132
+ [MIT](./LICENSE) © CEQUENS
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "octwin-cli",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -29,6 +29,8 @@
29
29
  "publishConfig": {
30
30
  "access": "public"
31
31
  },
32
- "keywords": ["octwin", "cequens", "cli", "whatsapp", "chatbot", "pack"],
32
+ "keywords": ["octwin", "cequens", "cli", "whatsapp", "chatbot", "pack", "conversational-ai", "yaml"],
33
+ "author": "CEQUENS",
34
+ "homepage": "https://www.npmjs.com/package/octwin-cli",
33
35
  "license": "MIT"
34
36
  }