octwin-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CEQUENS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# 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 package is `octwin-cli`; the command it installs is `octwin`.
+
+## Install
+
+```bash
+# zero-install (recommended)
+npx octwin-cli <command>
+
+# or install the command globally
+npm i -g octwin-cli
+octwin <command>
+```
+
+## The loop
+
+```bash
+# 1. Scaffold a standalone pure-YAML pack (yours)
+octwin init ./my-pack --id my-pack --description "My business bot"
+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.
+
+# 3. Validate locally (same structural gate the server runs)
+octwin validate
+
+# 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 cqp_…
+octwin whoami --tenant my-tenant
+octwin deploy --tenant my-tenant --project main          # add --seed to seed demo data
+
+# 5. Confirm it landed — which version is live?
+octwin status --tenant my-tenant --project 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.
+```
+
+## Auth — the deploy token
+
+You authenticate with a tenant-scoped **deploy token** (`cqp_…`), 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>'`).
+
+## Config resolution (deploy/status)
+
+`flags` > `pack.json` (in the pack dir) > env (`PACK_PLATFORM_URL`, `PACK_TENANT`,
+`PACK_PROJECT`, `PACK_TOKEN`) > saved login (`~/.octwin/credentials.json`).
+
+## 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.

package/dist/index.js

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+/**
+ * octwin — the Octwin external-pack developer CLI (by CEQUENS).
+ *
+ * A developer scaffolds a pure-YAML pack in their own repo, validates it
+ * locally, and deploys it to a running Octwin platform to test on their own
+ * tenant. Standalone: no platform checkout, no build step for the developer —
+ * `npx octwin-cli <cmd>` (published as `octwin-cli`, command `octwin`).
+ *
+ *   octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+ *   octwin validate [--dir .]
+ *   octwin login   --url <platformUrl> --token cqp_…
+ *   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 test    [--dir .]        # local validate + how to chat on your tenant
+ *
+ * Config resolution (deploy): flags > pack.json (in the pack dir) > env
+ * (PACK_PLATFORM_URL / PACK_TENANT / PACK_PROJECT / PACK_TOKEN) > saved login.
+ *
+ * The bundle uploaded is every file under the pack dir EXCEPT pack.json, dot
+ * files/dirs, node_modules, and build output. The platform re-validates it
+ * (pure-YAML enforcement + manifest/flow Zod) and installs it onto the project.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, cpSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import { applyRenames } from './lib/rename.js';
+import { validatePackBundle } from './lib/validate.js';
+// The in-package starter template ships alongside `dist/` and `src/` (both one
+// 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');
+function parseFlags(argv) {
+    const f = { _: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--'))
+                f[key] = true;
+            else {
+                f[key] = next;
+                i++;
+            }
+        }
+        else
+            f._.push(a);
+    }
+    return f;
+}
+function die(msg) {
+    console.error(`✗ ${msg}`);
+    process.exit(1);
+}
+// ── bundle collection ───────────────────────────────────────────────────────
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.pack-bundles', 'dist', '.mastra']);
+/** Collect every text file under `packDir` into a `{ relPath: content }` map. */
+function collectBundleFiles(packDir) {
+    const files = {};
+    const walk = (dir, prefix) => {
+        for (const name of readdirSync(dir)) {
+            const full = join(dir, name);
+            const rel = prefix ? `${prefix}/${name}` : name;
+            if (statSync(full).isDirectory()) {
+                if (SKIP_DIRS.has(name) || name.startsWith('.'))
+                    continue;
+                walk(full, rel);
+                continue;
+            }
+            if (name === 'pack.json')
+                continue; // deploy config, not part of the pack
+            if (name.startsWith('.'))
+                continue; // .gitignore etc. — not pack content
+            files[rel] = readFileSync(full, 'utf8');
+        }
+    };
+    walk(packDir, '');
+    return files;
+}
+function readManifestIdVersion(files) {
+    const raw = files['manifest.yaml'];
+    if (!raw)
+        die('no manifest.yaml found in the pack directory');
+    const doc = parseYaml(raw);
+    if (typeof doc?.id !== 'string' || typeof doc?.version !== 'string') {
+        die('manifest.yaml must declare string `id` and `version`');
+    }
+    return { id: doc.id, version: doc.version };
+}
+function readPackConfig(packDir) {
+    const p = join(packDir, 'pack.json');
+    if (!existsSync(p))
+        return {};
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function credsPath() { return join(homedir(), '.octwin', 'credentials.json'); }
+function readCreds() {
+    try {
+        return JSON.parse(readFileSync(credsPath(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeCreds(map) {
+    mkdirSync(join(homedir(), '.octwin'), { recursive: true });
+    writeFileSync(credsPath(), JSON.stringify(map, null, 2), 'utf8');
+}
+// ── commands ────────────────────────────────────────────────────────────────
+function cmdInit(flags) {
+    const target = flags._[0] ?? die('usage: octwin init <dir> [--id my-pack]');
+    const dir = resolve(target);
+    const id = flags.id ?? target.replace(/[/\\]/g, '').replace(/[^a-z0-9-]/gi, '-').toLowerCase();
+    if (!/^[a-z][a-z0-9-]*$/.test(id))
+        die(`pack id '${id}' must be lowercase ASCII with hyphens — pass --id`);
+    if (existsSync(dir) && readdirSync(dir).length > 0)
+        die(`target '${dir}' is not empty`);
+    if (!existsSync(TEMPLATE_DIR))
+        die(`starter template missing at ${TEMPLATE_DIR} (broken install?)`);
+    // Copy the pure-YAML starter template, then rename it into a fresh pack.
+    mkdirSync(dir, { recursive: true });
+    cpSync(TEMPLATE_DIR, dir, { recursive: true });
+    applyRenames(dir, {
+        packId: id,
+        flowId: 'main',
+        agentId: 'assistant',
+        description: flags.description ?? undefined,
+        displayName: flags['display-name'] ?? undefined,
+    });
+    // Deploy config + repo hygiene + a README.
+    writeFileSync(join(dir, 'pack.json'), JSON.stringify({
+        platform_url: 'http://localhost:3000',
+        tenant: 'your-tenant-slug',
+        project: 'main',
+    }, null, 2) + '\n', 'utf8');
+    writeFileSync(join(dir, '.gitignore'), 'node_modules/\n.pack-bundles/\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');
+    }
+    console.log(`✓ Scaffolded pure-YAML pack '${id}' at ${dir}`);
+    console.log('\nNext:');
+    console.log(`  cd ${target}`);
+    console.log('  git init && git add -A && git commit -m "init pack"');
+    console.log('  # edit manifest.yaml / flows / prompts, then:');
+    console.log('  octwin validate');
+    console.log('  # set platform_url + tenant + project in pack.json, then:');
+    console.log('  octwin login --url <platformUrl> --token <deploy-token>');
+    console.log('  octwin deploy');
+}
+function localValidate(packDir) {
+    const files = collectBundleFiles(packDir);
+    const { id, version } = readManifestIdVersion(files);
+    const r = validatePackBundle(id, files);
+    if (!r.ok) {
+        for (const e of r.errors)
+            console.error(`  ✗ ${e}`);
+        die(`bundle validation failed (${r.errors.length} error${r.errors.length === 1 ? '' : 's'})`);
+    }
+    return { id, version, files };
+}
+function cmdValidate(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const { id, version, files } = localValidate(packDir);
+    console.log(`✓ ${id}@${version} is a valid pure-YAML pack (${Object.keys(files).length} files)`);
+    console.log('  (the platform re-validates manifest + flows against the full schema on deploy)');
+}
+function cmdLogin(flags) {
+    const url = flags.url ?? process.env.PACK_PLATFORM_URL ?? die('usage: octwin login --url <platformUrl> --token <t>');
+    const token = flags.token ?? process.env.PACK_TOKEN ?? die('missing --token');
+    const creds = readCreds();
+    creds[url.replace(/\/$/, '')] = token;
+    writeCreds(creds);
+    console.log(`✓ Saved token for ${url}`);
+}
+/** Resolve platform url + tenant + project + token: flags > pack.json > env > saved login. */
+function resolveTarget(flags, packDir) {
+    const cfg = readPackConfig(packDir);
+    const url = (flags.url ?? process.env.PACK_PLATFORM_URL ?? cfg.platform_url ?? '').replace(/\/$/, '');
+    const tenant = flags.tenant ?? process.env.PACK_TENANT ?? cfg.tenant ?? '';
+    const project = flags.project ?? process.env.PACK_PROJECT ?? cfg.project ?? 'main';
+    const token = flags.token ?? process.env.PACK_TOKEN ?? readCreds()[url] ?? '';
+    if (!url)
+        die('no platform url — set it in pack.json, --url, or PACK_PLATFORM_URL');
+    if (!tenant)
+        die('no tenant — set it in pack.json, --tenant, or PACK_TENANT');
+    if (!token)
+        die('no token — generate a deploy token in the console (Settings → API tokens), then `octwin login --url <url> --token cqp_…` or pass --token');
+    return { url, tenant, project, token };
+}
+async function cmdWhoami(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const { url, tenant, token } = resolveTarget(flags, packDir);
+    const res = await fetch(`${url}/api/admin/tenants/${tenant}/packs`, { headers: { authorization: `Bearer ${token}` } });
+    if (res.ok) {
+        console.log(`✓ Token valid for tenant '${tenant}' at ${url} (${token.startsWith('cqp_') ? 'deploy token' : 'session token'})`);
+        return;
+    }
+    const why = res.status === 401 ? 'invalid / expired / revoked token'
+        : res.status === 403 ? 'token not authorized for this tenant'
+            : await res.text();
+    die(`token check failed for '${tenant}' (HTTP ${res.status}) — ${why}`);
+}
+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 res = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+        body: JSON.stringify({ files, seed: flags.seed === true }),
+    });
+    const text = await res.text();
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        json = text;
+    }
+    if (!res.ok) {
+        console.error(`✗ deploy failed (HTTP ${res.status})`);
+        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}).`);
+}
+async function cmdStatus(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const { url, tenant, project, token } = resolveTarget(flags, packDir);
+    const manifestPath = join(packDir, 'manifest.yaml');
+    if (!existsSync(manifestPath))
+        die('no manifest.yaml in the pack directory (run from your pack dir or pass --dir)');
+    const doc = parseYaml(readFileSync(manifestPath, 'utf8'));
+    if (typeof doc?.id !== 'string')
+        die('manifest.yaml must declare a string `id`');
+    const id = doc.id;
+    const localVersion = typeof doc?.version === 'string' ? doc.version : '?';
+    const res = await fetch(`${url}/api/admin/tenants/${tenant}/projects/${project}/packs/${id}/runtime`, {
+        headers: { authorization: `Bearer ${token}` },
+    });
+    const text = await res.text();
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        json = text;
+    }
+    if (!res.ok) {
+        if (res.status === 404)
+            die(`'${id}' is not installed on ${tenant}/${project} yet — run \`octwin deploy\` first`);
+        console.error(`✗ status check failed (HTTP ${res.status})`);
+        console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
+        process.exit(1);
+    }
+    console.log(`${id} on ${tenant}/${project} @ ${url}`);
+    console.log(`  installed version : ${json.installed_version}`);
+    console.log(`  live on instance  : registered=${json.registered}  source=${json.source}  loaded=${json.loaded_version ?? '(none)'}`);
+    console.log(`  flows             : ${(json.flows ?? []).join(', ') || '(none)'}`);
+    if (!json.registered) {
+        console.log('\n… not warm on the instance you hit yet — it loads on the next inbound (chat once, then re-check).');
+    }
+    else if (json.loaded_version && json.installed_version && json.loaded_version !== json.installed_version) {
+        console.log(`\n⚠ instance has ${json.loaded_version} but the project is bound to ${json.installed_version} — a redeploy lands on the next turn.`);
+    }
+    else {
+        console.log('\n✓ live and current.');
+    }
+    if (localVersion !== '?' && localVersion !== json.installed_version) {
+        console.log(`  (local manifest is ${localVersion}; deployed is ${json.installed_version} — \`octwin deploy\` to push local edits.)`);
+    }
+}
+function cmdTest(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const { id, version } = localValidate(packDir);
+    console.log(`✓ ${id}@${version} validates locally.`);
+    console.log('  Deploy it (`octwin deploy`), then chat on your tenant via the web widget /');
+    console.log('  console test page, and `octwin status` to confirm the live version.');
+}
+function help() {
+    console.log(`octwin — Octwin external-pack developer CLI (by CEQUENS)
+
+  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+  octwin validate [--dir .]
+  octwin login   --url <platformUrl> --token cqp_…      # a deploy token from the console
+  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 test    [--dir .]
+
+Get a deploy token: console → your workspace → Settings → API tokens → Generate.
+Config (deploy): flags > pack.json > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login.`);
+}
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    const flags = parseFlags(rest);
+    switch (command) {
+        case 'init':
+            cmdInit(flags);
+            break;
+        case 'validate':
+            cmdValidate(flags);
+            break;
+        case 'login':
+            cmdLogin(flags);
+            break;
+        case 'whoami':
+            await cmdWhoami(flags);
+            break;
+        case 'deploy':
+            await cmdDeploy(flags);
+            break;
+        case 'status':
+            await cmdStatus(flags);
+            break;
+        case 'test':
+            cmdTest(flags);
+            break;
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            help();
+            break;
+        default: die(`unknown command '${command}' — run \`octwin help\``);
+    }
+}
+main().catch((err) => die(err?.message ?? String(err)));

package/dist/lib/rename.js

@@ -0,0 +1,107 @@
+/**
+ * rename.ts — rename map + safe substitution over a copied starter tree.
+ *
+ * A VENDORED, platform-free copy of the platform scaffolder's rename module
+ * (`scripts/pack-scaffold/rename.ts`). `octwin init` copies the in-package
+ * `templates/starter/` tree (packId `starter-kit`, flow `main`, agent
+ * `assistant`) then this rewrites the copy into a fresh pack:
+ *   • `starter-kit` → <pack-id>            (manifest id, comments, README)
+ *   • agent display name + id              (when --display-name / --agent given)
+ *   • manifest description                 (when --description given)
+ *   • the `main` flow → <flow-id>          (when --flow given): file renames + scoped edits
+ *
+ * Flow renaming is scoped to the exact syntactic forms the template uses
+ * (flow_id, manifest flows/tools entries, `$t("main.…")` / `'main.…'` locale
+ * namespaces) — never a blind `main` substring replace.
+ */
+import { readdirSync, statSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+const TEXT_EXT = /\.(ya?ml|md|sql|json)$/;
+function walkFiles(dir) {
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        const full = join(dir, name);
+        if (statSync(full).isDirectory())
+            out.push(...walkFiles(full));
+        else
+            out.push(full);
+    }
+    return out;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Build the ordered list of [pattern, replacement] content edits. */
+function contentReplacements(opts) {
+    const global = []; // applied to every text file
+    const manifestOnly = []; // applied to manifest.yaml only
+    const edits = global; // alias — most edits are global
+    // 1. Pack id — every literal `starter-kit` becomes the new id.
+    edits.push([new RegExp(escapeRegExp('starter-kit'), 'g'), opts.packId]);
+    // 2. Manifest description value — manifest.yaml ONLY (a flow's own
+    //    `description:` line must not be overwritten with the pack description).
+    if (opts.description) {
+        const safe = opts.description.replace(/'/g, "''");
+        manifestOnly.push([/^description:.*$/m, `description: '${safe}'`]);
+    }
+    // 3. Agent display name (single-quoted scalar on `display_name:`).
+    if (opts.displayName) {
+        const safe = opts.displayName.replace(/'/g, "''");
+        edits.push([/^(\s*display_name:\s*).*$/m, `$1'${safe}'`]);
+    }
+    // 4. Agent id — the manifest agents[] list item and the messages.<lang>.yaml key.
+    if (opts.agentId !== 'assistant') {
+        edits.push([/^(\s*-\s*id:\s+)assistant\s*$/m, `$1${opts.agentId}`]); // manifest agents[].id
+        edits.push([/^(\s+)assistant:(\s*)$/m, `$1${opts.agentId}:$2`]); // messages.<lang>.yaml agents.<id>
+    }
+    // 5. Flow id — scoped forms only (never a blind `main` substring replace).
+    if (opts.flowId !== 'main') {
+        const f = opts.flowId;
+        edits.push([/^flow_id:(\s*)main\s*$/m, `flow_id:$1${f}`]); // flow + locale headers
+        edits.push([/^(\s*-\s*)main\s*$/gm, `$1${f}`]); // manifest flows: + tools: entries
+        edits.push([new RegExp(`(\\$t\\(["'])main\\.`, 'g'), `$1${f}.`]); // $t("main.…")
+    }
+    return { global, manifestOnly };
+}
+/** File-basename prefix renames (e.g. `main.flow.yaml` → `<flow>.flow.yaml`). */
+function fileRenames(opts) {
+    if (opts.flowId === 'main')
+        return [];
+    return [['main.', `${opts.flowId}.`]];
+}
+/**
+ * Apply all renames in-place to a freshly-copied pack tree at `destDir`.
+ * Content edits run first, then file renames (so edits see original names).
+ */
+export function applyRenames(destDir, opts) {
+    const { global, manifestOnly } = contentReplacements(opts);
+    for (const file of walkFiles(destDir)) {
+        if (!TEXT_EXT.test(file))
+            continue;
+        const edits = basename(file) === 'manifest.yaml' ? [...global, ...manifestOnly] : global;
+        let text = readFileSync(file, 'utf8');
+        let changed = false;
+        for (const [pattern, replacement] of edits) {
+            const next = text.replace(pattern, replacement);
+            if (next !== text) {
+                text = next;
+                changed = true;
+            }
+        }
+        if (changed)
+            writeFileSync(file, text, 'utf8');
+    }
+    for (const [fromPrefix, toPrefix] of fileRenames(opts)) {
+        for (const file of walkFiles(destDir)) {
+            const dir = file.slice(0, file.length - basename(file).length);
+            const base = basename(file);
+            if (base.startsWith(fromPrefix)) {
+                renameSync(file, join(dir, toPrefix + base.slice(fromPrefix.length)));
+            }
+        }
+    }
+}
+function basename(p) {
+    const i = Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\'));
+    return i < 0 ? p : p.slice(i + 1);
+}

package/dist/lib/validate.js

@@ -0,0 +1,71 @@
+/**
+ * Structural bundle validation — the pure-YAML/SQL gate, client side.
+ *
+ * A VENDORED, platform-free copy of the server's structural validator
+ * (`src/platform/provisioning/bundle-validate.ts`). It runs `octwin validate`
+ * offline so a developer catches the obvious rejections (executable code,
+ * routes, primitives, path traversal, non-declarative file types) before
+ * uploading. The **server re-validates authoritatively** on deploy — this local
+ * copy is a fast pre-check, not the source of truth — and it omits the server's
+ * in-repo shadow check (there is no `src/packs` in a developer's own repo).
+ */
+/** Declarative file extensions a pure-YAML pack may contain. */
+const ALLOWED_EXT = new Set(['yaml', 'yml', 'md', 'sql', 'json']);
+/** Extensions/paths that mean executable code or a non-YAML capability — rejected. */
+const CODE_EXT = new Set(['ts', 'js', 'mjs', 'cjs', 'jsx', 'tsx', 'node', 'wasm', 'sh', 'bash', 'exe', 'py', 'rb']);
+/** Normalize to forward slashes + strip a leading `./`. */
+function norm(p) {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+function ext(p) {
+    const base = p.slice(p.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    return dot >= 0 ? base.slice(dot + 1).toLowerCase() : '';
+}
+/**
+ * Validate an uploaded bundle file-map (`{ "<relPath>": "<body>" }`).
+ * Enforces: a `manifest.yaml` at root, no executable code / capability files,
+ * no path traversal or absolute paths, declarative extensions only. Returns all
+ * violations at once.
+ */
+export function validatePackBundle(packId, files) {
+    const errors = [];
+    if (!/^[a-z][a-z0-9-]*$/.test(packId)) {
+        errors.push(`pack id '${packId}' must be lowercase ASCII with hyphens (e.g. 'my-pack')`);
+    }
+    const paths = Object.keys(files);
+    if (paths.length === 0)
+        errors.push('bundle is empty');
+    if (!paths.some(p => norm(p) === 'manifest.yaml')) {
+        errors.push('bundle is missing manifest.yaml at its root');
+    }
+    for (const raw of paths) {
+        const p = norm(raw);
+        if (p.startsWith('/') || /^[a-zA-Z]:/.test(p) || p.split('/').includes('..')) {
+            errors.push(`unsafe path '${raw}' (absolute or traversal)`);
+            continue;
+        }
+        if (p.startsWith('routes/')) {
+            errors.push(`'${p}': pack HTTP routes are not allowed (pure-YAML packs only)`);
+            continue;
+        }
+        if (/^db\/client\./.test(p)) {
+            errors.push(`'${p}': a pack DB client is not allowed (pure-YAML packs only)`);
+            continue;
+        }
+        if (p.includes('.primitives.')) {
+            errors.push(`'${p}': pack primitives are not allowed (pure-YAML packs only)`);
+            continue;
+        }
+        const e = ext(p);
+        if (CODE_EXT.has(e)) {
+            errors.push(`'${p}': executable code is not allowed (pure-YAML packs only)`);
+            continue;
+        }
+        if (!ALLOWED_EXT.has(e)) {
+            errors.push(`'${p}': not an allowed pack file type (.yaml/.yml/.md/.sql only)`);
+            continue;
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "octwin-cli",
+  "version": "0.1.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",
+    "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"],
+  "license": "MIT"
+}

package/templates/starter/commands.yaml

@@ -0,0 +1,14 @@
+# Pack-level slash-command declarations (OPTIONAL but recommended).
+#
+# The platform's default `systemCommand` matches inbound text against these
+# BEFORE normal agent dispatch. Without a `commands.yaml`, a pack has NO slash
+# commands — e.g. `/clear` silently does nothing (it just goes to the agent as
+# text). Ship this file if you want `/clear` (and friends) to work like the
+# other packs.
+#
+# action: `close_conversation` (reset the conversation) | `noop` (reply only).
+
+- match:    '/clear'
+  action:   close_conversation
+  reply_ar: 'تم مسح المحادثة ✅ تقدر تبدأ من جديد.'
+  source:   '/clear'

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

@@ -0,0 +1,39 @@
+# 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

@@ -0,0 +1,16 @@
+# 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'

package/templates/starter/locale.ar.yaml

@@ -0,0 +1,13 @@
+# starter-kit — pack-wide Arabic strings.
+#
+# Entries here are shared across ALL flows in this pack (cross-flow labels,
+# common error messages, status verbs). Flow-specific strings live in
+# `flows/tools/<flow>.locale.ar.yaml`. Reference these via `$t("starter-kit.<key>")`
+# — every key is namespaced (pack-level by `pack_id`; flow-level by `flow_id`).
+# A bare `$t("<key>")` does NOT resolve (returns the raw key); the flow linter's
+# `locale-key-not-namespaced` rule fails the build on a bare key.
+
+pack_id: starter-kit
+strings:
+  # Example pack-level string — reference as `$t("starter-kit.greeting")`.
+  greeting: 'أهلاً! إزاي أقدر أساعدك؟'

package/templates/starter/manifest.yaml

@@ -0,0 +1,40 @@
+# 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` + `<id>.primitives.ts`.
+flows:
+  - main
+
+# 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).
+    tools:
+      - main
+    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

package/templates/starter/messages.ar.yaml

@@ -0,0 +1,26 @@
+# starter-kit — platform-emitted envelope copy (Arabic).
+#
+# Two blocks, both auto-loaded by definePack (lang from default_settings.locale):
+#   • errors:  copy the PLATFORM emits on failure paths (tool throw, workflow
+#              plumbing). Optional, but worth having so users never sit in
+#              silence. Schema: src/platform/manifest/messages.ts.
+#   • agents:  per-agent loop copy, keyed by the manifest agent id. OPTIONAL —
+#              the platform ships default copy; resolveMessages merges this block
+#              (whole or partial) over it at turn start. Shown here as an example.
+
+errors:
+  failed:
+    failure: { body: 'عذراً، حدث خطأ غير متوقع. حاول مرة أخرى.' }
+  unhandled_tool_error:
+    failure: { body: 'عذراً، حدث خطأ غير متوقع. حاول مرة أخرى بعد لحظة. 🙏' }
+
+# Per-agent envelope copy — keyed by manifest agent id (`assistant`).
+agents:
+  assistant:
+    agentDisabled:    'الخدمة الذكية غير متاحة مؤقتاً. حاول مرة أخرى لاحقاً. 🙏'
+    transientError:   'عذراً، حدث خطأ مؤقت. حاول مرة أخرى بعد لحظة. 🙏'
+    workflowExpired:  'عذراً، انتهت الجلسة. ابدأ من جديد.'
+    workflowError:    'عذراً، حدث خطأ أثناء استكمال العملية. حاول مرة أخرى.'
+    workflowDisabled: 'هذه الميزة غير مفعّلة في الوقت الحالي.'
+    toolDisabled:     'هذه الميزة غير مفعّلة في الوقت الحالي.'
+    directTapError:   'عذراً، حدث خطأ. حاول مرة أخرى.'

package/templates/starter/prompts/identity.md

@@ -0,0 +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.