octwin-cli 0.1.21 → 0.3.0

package/dist/lib/args-check.js

@@ -27,13 +27,20 @@
  *     platform's expander. `octwin validate --remote` covers that case; this
  *     covers everything written directly in the flow.
  */
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-/** Load `primitive -> ArgSpec` from the pulled KB, or null when absent. */
+import { lookupKbSubdir } from './kb-path.js';
+/**
+ * Load `primitive -> ArgSpec` from the pulled KB.
+ *
+ * Three-state, like its sibling in `render-check.ts` — the caller must be able to
+ * distinguish "checked and clean" from "could not check". See `kb-path.ts`.
+ */
 export function loadPrimitiveArgSpecs(packDir) {
-    const dir = join(packDir, '.octwin', 'platform-kb', 'primitives');
-    if (!existsSync(dir))
-        return null;
+    const lookup = lookupKbSubdir(packDir, 'primitives', dir => readdirSync(dir).some(f => f.endsWith('.json')));
+    if (lookup.state !== 'ok')
+        return { lookup, specs: null };
+    const dir = lookup.dir;
     const out = new Map();
     try {
         for (const file of readdirSync(dir)) {
@@ -50,13 +57,17 @@ export function loadPrimitiveArgSpecs(packDir) {
                 keys: Object.keys(schema.properties),
                 required: Array.isArray(schema.required) ? schema.required : [],
                 open: ap !== undefined && ap !== false,
+                requiresOneOf: Array.isArray(entry.requiresOneOf) ? entry.requiresOneOf : [],
             });
         }
     }
-    catch {
-        return null;
+    catch (err) {
+        return { lookup: { state: 'malformed', dir, reason: String(err?.message ?? err) }, specs: null };
     }
-    return out.size ? out : null;
+    if (out.size === 0) {
+        return { lookup: { state: 'malformed', dir, reason: 'no primitive entries parsed' }, specs: null };
+    }
+    return { lookup, specs: out };
 }
 /**
  * Walk parsed YAML for `do:` nodes and report `args:` keys outside the
@@ -84,8 +95,9 @@ export function findArgViolations(doc, file, specs) {
                     : {};
                 const unknown = Object.keys(args).filter(k => !spec.keys.includes(k));
                 const missing = spec.required.filter(k => !(k in args));
-                if (unknown.length || missing.length) {
-                    findings.push({ file, primitive: obj.do, unknown, missing, declared: [...spec.keys].sort() });
+                const unscoped = spec.requiresOneOf.filter(g => !g.some(k => k in args));
+                if (unknown.length || missing.length || unscoped.length) {
+                    findings.push({ file, primitive: obj.do, unknown, missing, unscoped, declared: [...spec.keys].sort() });
                 }
             }
         }
@@ -106,5 +118,10 @@ export function describeArgFinding(f) {
         const plural = f.missing.length === 1 ? 'argument' : 'arguments';
         parts.push(`missing required ${plural} ${f.missing.map(k => `'${k}'`).join(', ')}`);
     }
+    for (const g of f.unscoped) {
+        // Worth its own sentence rather than a key list: the reader's question is
+        // "so what?", and for the scope groups the answer is a data leak.
+        parts.push(`no ${g.map(k => `'${k}'`).join(' or ')} — the read is project-wide and returns other contacts' records`);
+    }
     return `${f.file}: \`${f.primitive}\` has ${parts.join('; ')}. It takes: ${f.declared.join(', ') || 'no arguments'}`;
 }

package/dist/lib/kb-path.js

@@ -0,0 +1,76 @@
+/**
+ * Locate the pulled platform KB — the one resolver for all three readers.
+ *
+ * ## Why a walk-up
+ *
+ * `octwin platform-kb pull` writes `<cwd>/.octwin/platform-kb/`. Authors pull once
+ * at a repo root and then work inside `packs/<name>/`, which is how every other
+ * `.<tool>` directory behaves (`.git`, `node_modules`, `.env`). The readers used to
+ * join `.octwin` onto `packDir` exactly, so a repo-root pull covered no pack at
+ * all — and the failure was invisible, because a missing KB made each check
+ * silently return "nothing to check".
+ *
+ * ## Why three states and not `T | null`
+ *
+ * `catch { return null }` collapses *never pulled*, *corrupt* and *interrupted
+ * mid-pull* into one answer, and the advice attached to that answer ("run
+ * `octwin platform-kb pull`") is right for the first and only accidentally right
+ * for the others. A half-written pull that reads as "you haven't pulled yet" is
+ * how an author re-runs the same broken command twice. The reader tells the
+ * caller which of the three it found; the caller decides what to print.
+ */
+import { existsSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** How far up to look. Deep enough for a monorepo, shallow enough to stay local. */
+const MAX_HOPS = 12;
+/**
+ * Walk up from `packDir` looking for `.octwin/platform-kb/`.
+ *
+ * Stops at the filesystem root — `dirname(x) === x` is the fixed point on both
+ * POSIX (`/`) and Windows (`C:\`), and without that guard this loops forever.
+ * `MAX_HOPS` is the belt to that braces: a path that is neither absolute nor
+ * rooted the way we expect still terminates.
+ */
+export function findPlatformKbDir(packDir) {
+    let dir = packDir;
+    for (let hop = 0; hop < MAX_HOPS; hop++) {
+        const candidate = join(dir, '.octwin', 'platform-kb');
+        if (existsSync(candidate) && statSync(candidate).isDirectory())
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Resolve one KB SUBDIRECTORY (`primitives`, `render-intents`) to a three-state
+ * answer. `readEntries` is the caller's parse; throwing from it means malformed,
+ * returning an empty result means the directory is there but has no usable
+ * entries — which is also malformed, not absent.
+ */
+export function lookupKbSubdir(packDir, subdir, isUsable) {
+    const kb = findPlatformKbDir(packDir);
+    if (!kb)
+        return { state: 'absent' };
+    const dir = join(kb, subdir);
+    if (!existsSync(dir)) {
+        return { state: 'malformed', dir: kb, reason: `'${subdir}/' is missing from the pulled KB` };
+    }
+    try {
+        if (!isUsable(dir)) {
+            return { state: 'malformed', dir: kb, reason: `'${subdir}/' has no readable entries` };
+        }
+    }
+    catch (err) {
+        return { state: 'malformed', dir: kb, reason: `'${subdir}/' could not be read — ${err?.message ?? err}` };
+    }
+    return { state: 'ok', dir };
+}
+/** The line to print when a check could not run. Same wording for all three. */
+export function describeKbLookup(l, what) {
+    return l.state === 'absent'
+        ? `${what} SKIPPED — no capability reference found. Run \`octwin platform-kb pull\` (a pull at your repo root covers every pack under it).`
+        : `${what} SKIPPED — the capability reference at ${l.dir} is unusable: ${l.reason}. Re-run \`octwin platform-kb pull\`.`;
+}

package/dist/lib/page.js

@@ -0,0 +1,61 @@
+/**
+ * page.ts — read the platform's ONE page envelope.
+ *
+ * Every list route returns `Page<T>` (`src/platform/core/utils/paging.ts`):
+ * `{ rows, total, offset, limit, has_more, next_offset }`. `rows` is deliberately
+ * the collection key for every domain, so a client needs exactly one reader.
+ *
+ * ## Why this file exists
+ *
+ * It did not, and the CLI paid for it. Four commands each hand-copied a
+ * per-domain collection noun — `json.records`, `json.cases`, `json.orders`,
+ * `json.products` — from the days when every route invented its own envelope.
+ * When the platform collapsed those into `Page`, the CLI kept reading keys that
+ * no longer existed, and `.records ?? []` degraded to an empty array instead of
+ * failing. The result shipped: `octwin records doctor` printed
+ * "5 record(s)" and then "(none — check your token)", blaming the user's
+ * credentials for a key rename.
+ *
+ * A `?? []` fallback on a response you do not control is a silent-wrong
+ * generator. Reading the envelope in ONE place, with a test pinned to the real
+ * shape, is the actual fix — a future rename breaks one function loudly rather
+ * than four commands quietly.
+ *
+ * `assets` (media) and `agents` are NOT `Page`-shaped — those routes predate it
+ * and return their own envelopes. Do not force them through here; they have no
+ * `total` semantics to honour.
+ */
+/**
+ * Read a `Page` envelope defensively.
+ *
+ * Returns an empty view for a non-object or a body with no `rows` ARRAY, so a
+ * degraded read (`{ has_xrm: false, ...emptyPage() }`) and an error body both
+ * land on "no rows" without throwing. `total` stays **null** when absent rather
+ * than defaulting to 0 — a caller that prints "0 of 0" when the server said
+ * nothing is inventing a fact.
+ */
+export function readPage(json) {
+    const body = (json ?? {});
+    const rows = Array.isArray(body.rows) ? body.rows : [];
+    return {
+        rows,
+        total: typeof body.total === 'number' ? body.total : null,
+        hasMore: body.has_more === true,
+        nextOffset: typeof body.next_offset === 'number' ? body.next_offset : null,
+    };
+}
+/**
+ * One line telling the author the list was cut short and how to see the rest —
+ * `has_more` existed on every response and no command surfaced it, so a
+ * truncated list was indistinguishable from a complete one.
+ *
+ * Empty string when there is nothing to say, so callers can print it
+ * unconditionally.
+ */
+export function morePageHint(page, command) {
+    if (!page.hasMore || page.nextOffset == null)
+        return '';
+    const shown = page.rows.length;
+    const of = page.total != null ? ` of ${page.total}` : '';
+    return `  … showing ${shown}${of} — next page: ${command} --offset ${page.nextOffset}`;
+}

package/dist/lib/render-check.js

@@ -17,14 +17,23 @@
  *
  * Degrades to a no-op when the KB has not been pulled — never invents a rule it
  * cannot source, and never blocks `validate` for an author who hasn't pulled yet.
+ * It SAYS SO when it does: the caller gets a `KbLookup`, not a bare null, so a
+ * skipped check can never be reported as a passed one.
  */
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-/** Load `render_intent -> allowed_keys` from the pulled KB, or null when absent. */
+import { lookupKbSubdir } from './kb-path.js';
+/**
+ * Load `render_intent -> allowed_keys` from the pulled KB.
+ *
+ * Returns the three-state lookup alongside the map so the caller can tell
+ * "checked, nothing wrong" from "could not check". See `kb-path.ts`.
+ */
 export function loadAllowedRenderKeys(packDir) {
-    const dir = join(packDir, '.octwin', 'platform-kb', 'render-intents');
-    if (!existsSync(dir))
-        return null;
+    const lookup = lookupKbSubdir(packDir, 'render-intents', dir => readdirSync(dir).some(f => f.endsWith('.json')));
+    if (lookup.state !== 'ok')
+        return { lookup, keys: null };
+    const dir = lookup.dir;
     const out = new Map();
     try {
         for (const file of readdirSync(dir)) {
@@ -36,10 +45,13 @@ export function loadAllowedRenderKeys(packDir) {
             }
         }
     }
-    catch {
-        return null;
+    catch (err) {
+        return { lookup: { state: 'malformed', dir, reason: String(err?.message ?? err) }, keys: null };
+    }
+    if (out.size === 0) {
+        return { lookup: { state: 'malformed', dir, reason: 'no render-intent entries parsed' }, keys: null };
     }
-    return out.size ? out : null;
+    return { lookup, keys: out };
 }
 /**
  * Walk parsed YAML for objects carrying `render_intent` and report keys outside

package/dist/lib/validate.js

@@ -15,7 +15,7 @@
  * locally but the deploy rejected it".
  */
 /** Declarative TEXT extensions a pure-YAML pack may contain. */
-const ALLOWED_EXT = new Set(['yaml', 'yml', 'md', 'sql', 'json']);
+const ALLOWED_EXT = new Set(['yaml', 'yml', 'md', 'json']);
 /** Binary extensions that travel as artifact BLOBS (base64 on the wire, bytea in
  *  storage). No `svg` — it is script-capable and these are served to browsers. */
 const ALLOWED_BINARY_EXT = new Set(['jpg', 'jpeg', 'png', 'webp', 'gif', 'pdf']);
@@ -70,6 +70,15 @@ blobs = {}) {
             errors.push(`'${p}': pack primitives are not allowed (pure-YAML packs only)`);
             continue;
         }
+        // `.sql` used to be allowed and was executed VERBATIM by the pack migration
+        // runner. Packs no longer own a database, so there is nothing for it to run
+        // against — and rejecting it here is finally enforceable, which is what this
+        // module's header has always claimed. Named explicitly so the author gets a
+        // reason instead of a bare "not an allowed pack file type".
+        if (ext(p) === 'sql') {
+            errors.push(`'${p}': packs have no database — SQL is not allowed. Model the data in \`xrm.yaml\`, which is first-class platform storage.`);
+            continue;
+        }
         const e = ext(p);
         if (CODE_EXT.has(e)) {
             errors.push(`'${p}': executable code is not allowed (pure-YAML packs only)`);
@@ -80,7 +89,7 @@ blobs = {}) {
             continue;
         }
         if (!ALLOWED_EXT.has(e)) {
-            errors.push(`'${p}': not an allowed pack file type (.yaml/.yml/.md/.sql/.json, or an image: ${[...ALLOWED_BINARY_EXT].join('/')})`);
+            errors.push(`'${p}': not an allowed pack file type (.yaml/.yml/.md/.json, or an image: ${[...ALLOWED_BINARY_EXT].join('/')})`);
             continue;
         }
     }

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "octwin-cli",
-  "version": "0.1.21",
-  "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
-  "type": "module",
-  "bin": {
-    "octwin": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "templates",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "yaml": "^2.6.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.7.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": ["octwin", "cequens", "cli", "whatsapp", "chatbot", "pack", "conversational-ai", "yaml"],
-  "author": "CEQUENS",
-  "homepage": "https://www.npmjs.com/package/octwin-cli",
-  "license": "MIT"
-}
+{
+  "name": "octwin-cli",
+  "version": "0.3.0",
+  "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
+  "type": "module",
+  "bin": {
+    "octwin": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["octwin", "cequens", "cli", "whatsapp", "chatbot", "pack", "conversational-ai", "yaml"],
+  "author": "CEQUENS",
+  "homepage": "https://www.npmjs.com/package/octwin-cli",
+  "license": "MIT"
+}

package/templates/starter/manifest.yaml

@@ -1,54 +1,55 @@
-# manifest.yaml — your pack is declared entirely by this one file. Required:
-# id, version (a STRING, e.g. '1.0.0'), description. Everything else is optional
-# and grows with your domain. `octwin validate` checks it locally; the platform
-# re-validates the full schema on `octwin deploy`.
-
-id:          starter-kit
-version:     1.0.0
-description: 'A hello bot — edit this to build your pack.'
-
-# Channels this pack supports + platform capabilities it needs. A pack with
-# no database reads only needs `messaging`. Add data-store / embedding /
-# vision / storage as your domain grows (see real-estate's manifest).
-supported_channels: [whatsapp, web]
-required_adapters:  [messaging]
-
-# Default locale for platform-emitted copy + this pack's `$t()` lookups.
-default_settings:
-  locale: ar
-
-# 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:
-  - 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.
-agents:
-  - id:                assistant
-    display_name:      'Starter Assistant'
-    # `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; hub first).
-    tools:
-      - 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}}.
-    instructions:
-      - file: prompts/identity.md
-    # No working_memory block — deliberate, and you should keep it that way.
-    # Declaring one makes the platform add Mastra's updateWorkingMemory tool +
-    # a "call it every turn" instruction: an extra LLM generation on most turns,
-    # and small models (like the lite default above) parrot the
-    # <working_memory_data> envelope straight into user-visible replies. Session
-    # identity (name/lang/phone) already reaches the model via the platform's
-    # first-turn [ctx: …] header, and tools read it from the request context —
-    # so you gain nothing here. Leave it off unless you're on a large model and
-    # have a concrete slot schema to maintain.
-    default_memory:
-      lastMessages: 10   # size of the recalled message window
+# manifest.yaml — your pack is declared entirely by this one file. Required:
+# id, version (a STRING, e.g. '1.0.0'), description. Everything else is optional
+# and grows with your domain. `octwin validate` checks it locally; the platform
+# re-validates the full schema on `octwin deploy`.
+
+id:          starter-kit
+version:     1.0.0
+description: 'A hello bot — edit this to build your pack.'
+
+# Channels this pack supports + platform capabilities it needs. A pack with
+# no media or search only needs `messaging`. Add embedding / vision / storage
+# as your domain grows. (Your data model goes in `xrm.yaml` — packs have no
+# database of their own.)
+supported_channels: [whatsapp, web]
+required_adapters:  [messaging]
+
+# Default locale for platform-emitted copy + this pack's `$t()` lookups.
+default_settings:
+  locale: ar
+
+# 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:
+  - 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.
+agents:
+  - id:                assistant
+    display_name:      'Starter Assistant'
+    # `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; hub first).
+    tools:
+      - 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}}.
+    instructions:
+      - file: prompts/identity.md
+    # No working_memory block — deliberate, and you should keep it that way.
+    # Declaring one makes the platform add Mastra's updateWorkingMemory tool +
+    # a "call it every turn" instruction: an extra LLM generation on most turns,
+    # and small models (like the lite default above) parrot the
+    # <working_memory_data> envelope straight into user-visible replies. Session
+    # identity (name/lang/phone) already reaches the model via the platform's
+    # first-turn [ctx: …] header, and tools read it from the request context —
+    # so you gain nothing here. Leave it off unless you're on a large model and
+    # have a concrete slot schema to maintain.
+    default_memory:
+      lastMessages: 10   # size of the recalled message window