octwin-cli 0.1.5 → 0.1.7

package/dist/index.js

@@ -7,6 +7,7 @@
  * tenant. Standalone: no platform checkout, no build step for the developer —
  * `npx octwin-cli <cmd>` (published as `octwin-cli`, command `octwin`).
  *
+ *   octwin --version | -v           # print the CLI version (+ any upgrade notice)
  *   octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
  *   octwin validate [--dir .] [--remote]   # --remote → the platform's FULL schema check, all errors at once
  *   octwin login   --url <platformUrl> --token oct_…
@@ -37,6 +38,17 @@ import { validatePackBundle } from './lib/validate.js';
 // level under the package root), so `../templates/starter` resolves for the
 // built CLI and `tsx` dev alike.
 const TEMPLATE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'templates', 'starter');
+/** This CLI's version — read from its own package.json (one level up from dist/,
+ *  always shipped in the npm tarball). Falls back to '0.0.0' if unreadable. */
+const VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+        return typeof pkg?.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
 function parseFlags(argv) {
     const f = { _: [] };
     for (let i = 0; i < argv.length; i++) {
@@ -119,6 +131,67 @@ function writeCreds(map) {
     mkdirSync(join(homedir(), '.octwin'), { recursive: true });
     writeFileSync(credsPath(), JSON.stringify(map, null, 2), 'utf8');
 }
+// ── update check (daily, fail-silent, TTY-only) ──────────────────────────────
+function updateCachePath() { return join(homedir(), '.octwin', 'update-check.json'); }
+/** True when semver `a` is strictly greater than `b` (simple x.y.z compare). */
+function isNewer(a, b) {
+    const pa = a.split('.').map(n => parseInt(n, 10));
+    const pb = b.split('.').map(n => parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        const x = pa[i] ?? 0, y = pb[i] ?? 0;
+        if (Number.isNaN(x) || Number.isNaN(y))
+            return false;
+        if (x !== y)
+            return x > y;
+    }
+    return false;
+}
+/** The latest published `octwin-cli` version, cached for a day. Fail-silent:
+ *  returns null on any error / offline — a version check must never break a command. */
+async function latestPublishedVersion() {
+    const DAY = 24 * 60 * 60 * 1000;
+    try {
+        const cache = JSON.parse(readFileSync(updateCachePath(), 'utf8'));
+        if (cache.latest && typeof cache.checkedAt === 'number' && Date.now() - cache.checkedAt < DAY)
+            return cache.latest;
+    }
+    catch { /* no / stale cache → fetch below */ }
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), 1500);
+        const res = await fetch('https://registry.npmjs.org/octwin-cli/latest', { signal: ctrl.signal });
+        clearTimeout(timer);
+        if (!res.ok)
+            return null;
+        const latest = (await res.json()).version;
+        if (typeof latest !== 'string')
+            return null;
+        try {
+            mkdirSync(join(homedir(), '.octwin'), { recursive: true });
+            writeFileSync(updateCachePath(), JSON.stringify({ checkedAt: Date.now(), latest }), 'utf8');
+        }
+        catch { /* cache is best-effort */ }
+        return latest;
+    }
+    catch {
+        return null;
+    }
+}
+/** Print a one-line upgrade notice (to stderr) when a newer octwin-cli is published.
+ *  Skipped when not attached to a TTY (CI / piped) so it never adds noise to scripts.
+ *  Never throws. */
+async function notifyIfOutdated() {
+    if (!process.stdout.isTTY)
+        return;
+    try {
+        const latest = await latestPublishedVersion();
+        if (latest && isNewer(latest, VERSION)) {
+            console.error(`\n⬆ octwin-cli ${latest} is available (you have ${VERSION}).`);
+            console.error('  Upgrade: npm i -g octwin-cli@latest   (or just use npx octwin-cli@latest)');
+        }
+    }
+    catch { /* a version check must never break the CLI */ }
+}
 // ── commands ────────────────────────────────────────────────────────────────
 function cmdInit(flags) {
     const target = flags._[0] ?? die('usage: octwin init <dir> [--id my-pack]');
@@ -148,7 +221,7 @@ function cmdInit(flags) {
     }, null, 2) + '\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');
+        writeFileSync(join(dir, 'README.md'), `# ${id}\n\nA pure-YAML pack for the Octwin platform.\n\n- \`flows/tools/home.flow.yaml\` — the menu hub (your front door); add a row + tool per journey\n- Edit \`manifest.yaml\`, \`prompts/identity.md\`\n- \`octwin validate --remote\` — full platform check before deploy\n- \`octwin deploy\` — deploy + install onto your tenant\n`, 'utf8');
     }
     console.log(`✓ Scaffolded pure-YAML pack '${id}' at ${dir}`);
     console.log('\nNext:');
@@ -643,8 +716,9 @@ async function cmdChat(flags) {
     }
 }
 function help() {
-    console.log(`octwin — Octwin external-pack developer CLI (by CEQUENS)
+    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
 
+  octwin --version                                      # print the CLI version (+ any upgrade notice)
   octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
   octwin validate [--dir .] [--remote]                  # --remote runs the platform's FULL schema check (all errors at once)
   octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
@@ -698,6 +772,11 @@ async function main() {
         case 'test':
             await cmdValidate({ ...flags, remote: true });
             break; // A6: `test` = the full remote validate, not a validate-clone
+        case '-v':
+        case '--version':
+        case 'version':
+            console.log(`octwin-cli ${VERSION}`);
+            break;
         case undefined:
         case 'help':
         case '--help':
@@ -706,5 +785,6 @@ async function main() {
             break;
         default: die(`unknown command '${command}' — run \`octwin help\``);
     }
+    await notifyIfOutdated(); // trailing, fail-silent, TTY-only "newer version available" notice
 }
 main().catch((err) => die(err?.message ?? String(err)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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/flows/tools/browse.flow.yaml

@@ -0,0 +1,24 @@
+# An example capability the home hub invokes. Replace this with your real tool
+# (record_list + a carousel, a collect: intake, a case_open, …). Kept trivial here
+# so the scaffold is chattable end-to-end: home menu → tap "browse" → this renders.
+flow_id:     browse
+version:     1
+description: An example capability, reached from the home menu. Replace with your real tool.
+
+input:
+  message:
+    type:     string
+    optional: true
+    describe: 'Optional note from the user.'
+
+entry:
+  - else: true
+    goto: show
+
+steps:
+  show:
+    - render:
+        render_intent: text_card
+        body: '{$t("browse.body")}'
+      memory_note: '{$t("browse.memory_note")}'
+    - end: applied

package/templates/starter/flows/tools/browse.locale.ar.yaml

@@ -0,0 +1,5 @@
+flow_id: browse
+
+strings:
+  body:        'هنا يظهر المحتوى ✨ عدّل أداة "browse" لتبني ميزتك الحقيقية.'
+  memory_note: 'Showed the browse example.'

package/templates/starter/flows/tools/home.flow.yaml

@@ -0,0 +1,32 @@
+# The HOME hub — your pack's front door / menu, and the FIRST tool the agent calls
+# on a greeting or an unclear message. A pure-render `list_picker`: one row per
+# primary capability, each routing a tap STRAIGHT to that tool via `on_select.invoke`
+# (no LLM turn). Add a row as you add each journey. Every shipped reference pack
+# ships a home flow like this — see references/ux-patterns.md in the octwin-pack skill.
+flow_id:     home
+version:     1
+description: Main menu / welcome. Call on a greeting, an unclear or off-topic message, or "what can you do?".
+
+input:
+  message:
+    type:     string
+    optional: true
+    describe: 'Optional ONE short greeting line YOU compose for this user (e.g. greet them by name).'
+
+entry:
+  - else: true
+    goto: show
+
+steps:
+  show:
+    - render:
+        render_intent: list_picker              # the universal chooser (WhatsApp list / web menu)
+        header: '{$t("home.header")}'
+        body:   '$coalesce($input.message, $t("home.greeting"))'   # agent line if given, else the default
+        cta:    '{$t("home.cta")}'               # the WhatsApp list-button label (required for list_picker)
+        items:                                   # ONE row per capability — the tap routes via on_select
+          - { title: '{$t("home.row_browse")}', on_select: { invoke: 'browse' } }
+          # Add a row per tool as you build them, e.g.:
+          # - { title: '{$t("home.row_x")}', on_select: { invoke: 'some-tool', with: { mode: x } } }
+      memory_note: 'Showed the home menu.'       # English breadcrumb — surfaced to the agent next turn
+    - end: applied

package/templates/starter/flows/tools/home.locale.ar.yaml

@@ -0,0 +1,9 @@
+# Every user-visible string for the home flow, keyed by `$t("home.<key>")`.
+# Lead labels with an emoji — it makes the menu scannable (all reference packs do this).
+flow_id: home
+
+strings:
+  header:     'القائمة الرئيسية'
+  greeting:   'أهلاً بك 👋 اختر من القائمة:'
+  cta:        'اختر'
+  row_browse: '📦 تصفّح'

package/templates/starter/manifest.yaml

@@ -17,10 +17,12 @@ required_adapters:  [messaging]
 default_settings:
   locale: ar
 
-# Agent-callable flow tools. Each id maps to
-# `flows/tools/<id>.flow.yaml` + `<id>.primitives.ts`.
+# Agent-callable flow tools. Each id maps to `flows/tools/<id>.flow.yaml`
+# (+ its `<id>.locale.<lang>.yaml`). List the HOME hub first — it's the pack's
+# front door; add each new tool here as you build it.
 flows:
-  - main
+  - home      # the menu / navigation hub (see references/ux-patterns.md)
+  - browse    # an example tool the hub invokes — replace with your real capability
 
 # One agent. The platform's universal agent protocol is auto-appended by
 # `createPackAgents` — `instructions:` carries only pack-supplied parts.
@@ -30,9 +32,10 @@ agents:
     # `openrouter/` prefix routes via OpenRouter. Operators override the
     # model per-project from the console.
     default_model:     'openrouter/google/gemini-3.1-flash-lite-preview'
-    # Flow tools this agent can call (subset of `flows:` above).
+    # Flow tools this agent can call (subset of `flows:` above; hub first).
     tools:
-      - main
+      - home
+      - browse
     include_platform_protocol: true
     # Instruction parts, joined with '\n\n'. `file:` paths are pack-root
     # relative; `.md` files may use built-in placeholders like {{pack.id}}.

package/templates/starter/prompts/identity.md

@@ -1,5 +1,5 @@
-You are the Starter Assistant — a tiny example bot that ships with the platform as a reference pack.
-
-For any user message, call the `main` tool to greet them. Pass the user's message as the `message` argument when they say something specific you can echo back; otherwise call `main` with no arguments.
-
-Keep replies short and friendly. This pack exists to be copied and customized — once you scaffold your own pack, replace this prompt and the `main` flow with your real domain.
+You are the Starter Assistant — a tiny example bot that ships as a reference pack.
+
+On a greeting, an unclear or off-topic message, or "what can you do?", call the `home` tool — it shows the menu (the pack's front door). Pass a short one-line greeting as `message` when you can personalize it (e.g. greet the user by name); otherwise call `home` with no arguments.
+
+`browse` is an example capability reached from the menu — replace it, and add a row + tool per journey as you build your domain (see the home flow's comments). Keep replies short and friendly.

package/templates/starter/flows/tools/main.flow.yaml

@@ -1,39 +0,0 @@
-# main — the starter greeting flow.
-#
-# The canonical pack-author shape, in miniature — PURE YAML, no TypeScript:
-#   • input:  the tool's schema (drives the LLM tool catalogue + validation)
-#   • entry:  routing rules (here: always go to `greet`)
-#   • steps:  compute the card body with an `assign` expr → render → end
-#   • all user-visible copy lives in main.locale.ar.yaml (never inline here)
-#
-# Conventions worth copying:
-#   • Build data with expr builtins (`$trim`/`$coalesce`/`$t`) — reach for a
-#     pack TS primitive only for logic the expr grammar genuinely can't express.
-#   • `{$body}` interpolates the assigned value into the card.
-#   • `memory_note` leaves the agent a breadcrumb of what the user saw.
-
-flow_id:     main
-version:     1
-description: Greet the user. Call for any message while building out this pack.
-
-input:
-  message:
-    type:     string
-    optional: true
-    describe: 'Optional note from the user to echo back in the greeting.'
-
-entry:
-  - else: true
-    goto: greet
-
-steps:
-  greet:
-    # Echo the user's note when present, else the default greeting — a ternary
-    # over `$trim` + `$t(key, { … })`. (Was a `build_greeting` primitive.)
-    - assign:
-        body: '$trim($coalesce($input.message, "")) != "" ? $t("main.body_with_note", { note: $trim($input.message) }) : $t("main.body_default")'
-    - render:
-        render_intent: text_card
-        body: '{$body}'
-      memory_note: '{$t("main.memory_note")}'
-    - end: applied

package/templates/starter/flows/tools/main.locale.ar.yaml

@@ -1,16 +0,0 @@
-# main — Arabic copy.
-#
-# Every user-facing string for the `main` flow lives here, keyed by a stable
-# name. The flow YAML references each via `$t("main.<key>", { … })`.
-# Placeholder syntax: `{var}` — substituted from the second arg of `$t()`.
-# Adding a new locale = drop a sibling `main.locale.<lang>.yaml` with the same
-# keys translated.
-
-flow_id: main
-
-strings:
-  body_default:   'أهلاً بك 👋 أنا بوت البداية. اكتب أي رسالة لنبدأ.'
-  body_with_note: 'أهلاً بك 👋 قلت: "{note}". أنا بوت البداية — جاهز نبدأ.'
-
-  # Agent breadcrumb (kept in English like other packs' memory notes).
-  memory_note: 'Showed starter greeting card'