octwin-cli 0.1.1 → 0.1.3

package/README.md

@@ -1,65 +1,133 @@
 # 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 oct_…
-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 platform-kb pull` | Pull the platform's capability reference (built-ins, primitives, render intents, flow-DSL — as markdown + JSON) into `.octwin/platform-kb/`, for the **`octwin-pack`** Claude Code authoring plugin to consult. |
+| `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** (`oct_…`), 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

@@ -13,6 +13,7 @@
  *   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?
+ *   octwin platform-kb [pull] [--dir .]  # pull the platform capability reference for the authoring skill
  *   octwin test    [--dir .]        # local validate + how to chat on your tenant
  *
  * Config resolution (deploy): flags > pack.json (in the pack dir) > env
@@ -142,7 +143,7 @@ function cmdInit(flags) {
         tenant: 'your-tenant-slug',
         project: 'main',
     }, null, 2) + '\n', 'utf8');
-    writeFileSync(join(dir, '.gitignore'), 'node_modules/\n.pack-bundles/\n', 'utf8');
+    writeFileSync(join(dir, '.gitignore'), 'node_modules/\n.pack-bundles/\n.octwin/\n', 'utf8');
     if (!existsSync(join(dir, 'README.md'))) {
         writeFileSync(join(dir, 'README.md'), `# ${id}\n\nA pure-YAML pack for the Octwin platform.\n\n- Edit \`manifest.yaml\`, \`flows/tools/main.flow.yaml\`, \`prompts/identity.md\`\n- \`octwin validate\` — check it locally\n- \`octwin deploy\` — deploy + install onto your tenant\n`, 'utf8');
     }
@@ -284,6 +285,49 @@ async function cmdStatus(flags) {
         console.log(`  (local manifest is ${localVersion}; deployed is ${json.installed_version} — \`octwin deploy\` to push local edits.)`);
     }
 }
+async function cmdPlatformKb(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const { url, tenant, token } = resolveTarget(flags, packDir);
+    const res = await fetch(`${url}/api/admin/tenants/${tenant}/octwin-platform-kb`, {
+        headers: { authorization: `Bearer ${token}` },
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        let j;
+        try {
+            j = JSON.parse(text);
+        }
+        catch {
+            j = text;
+        }
+        console.error(`✗ platform-kb pull failed (HTTP ${res.status})`);
+        console.error(typeof j === 'string' ? j : JSON.stringify(j, null, 2));
+        process.exit(1);
+    }
+    const bundle = JSON.parse(text);
+    // Write the reference into <packDir>/.octwin/platform-kb/ — markdown docs (the
+    // skill reads these first) + JSON catalogs (precise field schemas). Gitignored.
+    const outDir = join(packDir, '.octwin', 'platform-kb');
+    mkdirSync(outDir, { recursive: true });
+    let mdCount = 0;
+    let jsonCount = 0;
+    for (const [key, val] of Object.entries(bundle.docs ?? {})) {
+        if (val == null)
+            continue;
+        writeFileSync(join(outDir, `${key}.md`), val, 'utf8');
+        mdCount++;
+    }
+    for (const [key, val] of Object.entries(bundle.sources ?? {})) {
+        if (val == null)
+            continue;
+        writeFileSync(join(outDir, `${key}.json`), JSON.stringify(val, null, 2) + '\n', 'utf8');
+        jsonCount++;
+    }
+    writeFileSync(join(outDir, 'index.json'), JSON.stringify({ version: bundle.version, generated_at: bundle.generated_at, index: bundle.index }, null, 2) + '\n', 'utf8');
+    console.log(`✓ Pulled the Octwin platform KB → ${outDir}`);
+    console.log(`  ${mdCount} markdown docs + ${jsonCount} JSON catalogs (reference version ${bundle.version ?? '?'})`);
+    console.log('  The octwin-pack authoring skill reads these as the source of truth for what the platform supports.');
+}
 function cmdTest(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const { id, version } = localValidate(packDir);
@@ -300,9 +344,11 @@ function help() {
   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>]
+  octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
   octwin test    [--dir .]
 
 Get a deploy token: console → your workspace → Settings → API tokens → Generate.
+octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
 Config (deploy): flags > pack.json > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login.`);
 }
 async function main() {
@@ -327,6 +373,9 @@ async function main() {
         case 'status':
             await cmdStatus(flags);
             break;
+        case 'platform-kb':
+            await cmdPlatformKb(flags);
+            break;
         case 'test':
             cmdTest(flags);
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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"
 }