octwin-cli 0.1.2 → 0.1.4

package/README.md

@@ -66,6 +66,7 @@ octwin status               # "✓ live and current" once it's warm
 | `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. |
 

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');
     }
@@ -209,17 +210,91 @@ async function cmdWhoami(flags) {
             : await res.text();
     die(`token check failed for '${tenant}' (HTTP ${res.status}) — ${why}`);
 }
+/**
+ * Read the deploy SSE stream, printing each progress frame's message live, and
+ * return the terminal `done`/`error` event (or null if the stream ended without
+ * one). The platform emits `data: {json}\n\n` frames — install + seed progress,
+ * with per-record / per-image lines during a `--seed` (image generation is slow).
+ */
+async function readDeployProgress(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    let terminal = null;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buf += decoder.decode(value, { stream: true });
+        let idx;
+        while ((idx = buf.indexOf('\n\n')) >= 0) {
+            const frame = buf.slice(0, idx);
+            buf = buf.slice(idx + 2);
+            const dataLine = frame.split('\n').find((l) => l.startsWith('data:'));
+            if (!dataLine)
+                continue;
+            let ev;
+            try {
+                ev = JSON.parse(dataLine.slice(5).trim());
+            }
+            catch {
+                continue;
+            }
+            if (ev.stage === 'done' || ev.stage === 'error') {
+                terminal = ev;
+                continue;
+            }
+            if (ev.message)
+                console.log(`   ${ev.status === 'error' ? '⚠' : '·'} ${ev.message}`);
+        }
+    }
+    return terminal;
+}
+function printDeploySuccess(id, version, tenant, project, r) {
+    console.log(`✓ Deployed ${id}@${version} and installed onto ${tenant}/${project}`);
+    if (r?.warning)
+        console.log(`  ⚠ ${r.warning}`);
+    const s = r?.summary;
+    if (s) {
+        const parts = [];
+        if (s.records != null)
+            parts.push(`${s.records} record(s) created`);
+        if (s.updated)
+            parts.push(`${s.updated} updated`);
+        if (s.images)
+            parts.push(`${s.images} image(s) generated`);
+        if (s.rules)
+            parts.push(`${s.rules} availability rule(s)`);
+        if (parts.length)
+            console.log(`  Seeded: ${parts.join(', ')}`);
+    }
+    console.log(`\nChat with it on your tenant (web widget / console test page for ${tenant}/${project}).`);
+}
 async function cmdDeploy(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const { url, tenant, project, token } = resolveTarget(flags, packDir);
     const { id, version, files } = localValidate(packDir);
     const endpoint = `${url}/api/admin/tenants/${tenant}/projects/${project}/packs/deploy`;
-    console.log(`→ Deploying ${id}@${version} (${Object.keys(files).length} files) to ${tenant}/${project} …`);
+    const seed = flags.seed === true;
+    console.log(`→ Deploying ${id}@${version} (${Object.keys(files).length} files) to ${tenant}/${project}${seed ? ' — with demo seed' : ''} …`);
     const res = await fetch(endpoint, {
         method: 'POST',
-        headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
-        body: JSON.stringify({ files, seed: flags.seed === true }),
+        // Ask for a progress stream; the platform falls back to plain JSON if it
+        // (or an error before any progress) can't stream — handled below.
+        headers: { 'content-type': 'application/json', accept: 'text/event-stream', authorization: `Bearer ${token}` },
+        body: JSON.stringify({ files, seed }),
     });
+    // Streaming path — live install + seed progress (image generation can take a
+    // while, so `--seed` prints per-record / per-image lines as they happen).
+    if (res.ok && (res.headers.get('content-type') ?? '').includes('text/event-stream') && res.body) {
+        const final = await readDeployProgress(res.body);
+        if (!final || final.stage === 'error')
+            die(`deploy failed${final?.message ? `: ${final.message}` : ' (stream ended early)'}`);
+        printDeploySuccess(id, version, tenant, project, final);
+        return;
+    }
+    // Non-streaming path — plain JSON (older platform, or an error thrown before
+    // any progress frame, which the platform returns as clean JSON).
     const text = await res.text();
     let json;
     try {
@@ -233,10 +308,7 @@ async function cmdDeploy(flags) {
         console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
         process.exit(1);
     }
-    console.log(`✓ Deployed ${id}@${version} and installed onto ${tenant}/${project}`);
-    if (json?.warning)
-        console.log(`  ⚠ ${json.warning}`);
-    console.log(`\nChat with it on your tenant (web widget / console test page for ${tenant}/${project}).`);
+    printDeploySuccess(id, version, tenant, project, json);
 }
 async function cmdStatus(flags) {
     const packDir = resolve(flags.dir ?? '.');
@@ -284,6 +356,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 +415,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 +444,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.2",
+  "version": "0.1.4",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {

package/templates/starter/commands.yaml

@@ -10,5 +10,5 @@
 
 - match:    '/clear'
   action:   close_conversation
-  reply_ar: 'تم مسح المحادثة ✅ تقدر تبدأ من جديد.'
+  reply: 'تم مسح المحادثة ✅ تقدر تبدأ من جديد.'
   source:   '/clear'