wldx-admin-cli 1.1.0 → 1.2.1

package/README.md

@@ -1,6 +1,6 @@
 # wldx-admin-cli — `wx-admin`, an admin command line for the Wildix PBX
 
-**Version 1.1.0** · unofficial · MIT
+**Version 1.2.1** · unofficial · MIT
 
 `wx-admin` manages a Wildix PBX through its REST API (`https://<pbx>/api/v1`): the system and its settings, users,
 ACL, queues, dialplans and the objects they use (timetables, IVR, switches, paging, the dialplan database), trunks,
@@ -18,8 +18,9 @@ npx wldx-admin-cli --help                     # without installing
 
 Requires Node.js 22 or newer. One dependency: [`wldx-core`](https://github.com/gorets/wildix-cli/tree/main/packages/core), the core it shares with `wx`, from the
 same repository and of the same version.
-Unofficial: not made or supported by Wildix. It uses the PBX API as
-documented on the PBX (`https://<pbx>/api/v1/doc/`), which may change between WMS versions.
+
+Unofficial: not made or supported by Wildix. It uses the PBX API as documented on the PBX
+(`https://<pbx>/api/v1/doc/`), which may change between WMS versions.
 
 ## Access to a PBX
 
@@ -39,10 +40,6 @@ refused while it is set.
 
 ### Several PBX
 
-`--all-pbx` runs a command that only reads on every PBX (saved access, then the x-bees login's) and prints each
-result under its PBX: `wx-admin --all-pbx system info`, `wx-admin --all-pbx user registrations`.
-
-
 Which PBX a command works on:
 
 1. `--pbx PBX` (anywhere on the command line): `name.wildixin.com`, a bare `name` (= `name.wildixin.com`), an IP
@@ -54,6 +51,9 @@ Which PBX a command works on:
 `wx-admin pbx list` shows them (`*` is the default), `wx-admin pbx check` says which one a command would use and
 whether it accepts the access. Saved access lives in `~/.wildix/admin/pbx/<host>.json` (folder 0700, files 0600).
 
+`--all-pbx` runs a command that only reads on every PBX (saved access, then the x-bees login's) and prints each
+result under its PBX: `wx-admin --all-pbx system info`, `wx-admin --all-pbx user registrations`.
+
 ## Dialplans
 
 A dialplan (procedure) is `{name, description, numbers, includedDialplans}`; its rules are `numbers`, run in order,
@@ -76,6 +76,37 @@ ACL groups. Ids and runtime fields are left out and included dialplans are named
 in git; `wx-admin config diff DIR` shows what changed on the PBX since (`+` only on the PBX, `-` only in the folder,
 `~` changed, with the paths), `--with OTHERPBX` compares two PBX, `--all-pbx` compares every PBX with one folder.
 
+## Moving configuration to another PBX
+
+A WMS backup restored on another PBX carries LDAP and values bound to the serial of the first one, and breaks the
+second. `wx-admin` carries a chosen part of the configuration instead, with nothing bound to the source:
+
+```sh
+wx-admin config export --pbx old --to ./move          # tick what to carry (or --all, --only KIND:NAME,…; --users)
+wx-admin config import ./move --pbx new --dry-run      # the plan: new, the same, differs, blocked (and why)
+wx-admin config import ./move --pbx new                # tick, type the trunk passwords, confirm, write
+wx-admin config copy --from old --to new               # the same without the folder
+```
+
+- **What is carried:** dialplans (with included dialplans), general dialplan settings, timetables, IVR menus,
+  switches, paging groups, queues, dialplan database keys (the families the dialplans use; more with
+  `--db-family`), ACL groups, SIP trunks, trunk groups, price lists, and users with `--users` (portable fields
+  only). **Never:** devices, licenses, PSTN and FXO trunks, call history, recordings, voicemails, LDAP ids, jids,
+  passwords, system settings.
+- **References** between objects are kept by name (`{"$ref": "queues/Support", "as": "id"}`) and become the ids,
+  names or LDAP dns of the new PBX on import; ACL admin rules about the old PBX are about the new one. An object
+  where the serial or the host of the old PBX is still found is not carried (listed as bound).
+- **The folder** is one JSON Lines file per kind (`users.jsonl`: one object per line) and `manifest.json`; it holds
+  no password and not the serial.
+- **The import** compares every object with the new PBX by name: new ones are ticked, one that differs is
+  overwritten only when ticked (or `--overwrite`), blocked ones say why (a reference to nothing, no free license,
+  an extension taken). Passwords of the chosen trunks are typed hidden (or `--secrets FILE`). Objects are written in
+  the order they need each other; one that fails does not stop the rest, and running the same import again writes
+  only what is left.
+- **At the end**, a list of what is left to do on the new PBX (where in WMS, which `wx-admin` command), the blocking
+  ones first, and a log file `wx-admin-import-<host>-<time>.log` (here, or `--log DIR`), written every time, also
+  with `--dry-run`. Without a terminal: `--all` or `--only`, and `--yes` to write.
+
 ## Commands
 
 Every command has `-h`, takes `--pbx HOST` and `--profile EMAIL`, and prints text or, with `--output json`, JSON.
@@ -331,6 +362,9 @@ The configuration as files: back up a PBX to a folder, compare a folder or anoth
 | Command | What it does |
 | --- | --- |
 | `wx-admin config backup --to DIR [--only KIND,KIND…]` | write the configuration of the PBX to a new folder, one JSON file per object (passwords masked) |
+| `wx-admin config import <dir> [--all \| --only KIND:NAME,…] [--overwrite] [--secrets FILE] [--dry-run] [--yes] [--log DIR]` | write a config export to this PBX: a plan, what to write (chosen), the passwords, a log and what is left to do |
+| `wx-admin config copy --from PBX --to PBX [--all \| --only KIND:NAME,…] [--users] [--overwrite] [--secrets FILE] [--dry-run] [--yes] [--log DIR]` | carry the configuration of one PBX to another: export in memory, then import (plan, choice, log) |
+| `wx-admin config export --to DIR [--all \| --only KIND:NAME,…] [--users] [--db-family FAMILY]...` | choose what to carry to another PBX and write it to a new folder, without anything bound to this PBX |
 | `wx-admin config diff (<dir> \| --with PBX) [--only KIND,KIND…]` | what differs between a backup folder (or another PBX) and the PBX |
 
 ### wx-admin pbx
@@ -354,11 +388,16 @@ Your profiles (the e-mails you are logged in with) and the default one.
 | `wx-admin profile list` | your profiles; * marks the default one |
 | `wx-admin profile use <e-mail>` | make a profile the default one (used when no --profile is given) |
 
-### Login and profiles
+### wx-admin api
 
 | Command | What it does |
 | --- | --- |
 | `wx-admin api <method> <path> [--data JSON \| --data-file FILE\|-] [--query KEY=VALUE]... [--yes]` | call any PBX API operation (GET reads; other methods change the PBX and need --yes) |
+
+### Login and profiles
+
+| Command | What it does |
+| --- | --- |
 | `wx-admin login [<e-mail>] [--send-code \| --code CODE]` | log in with a one-time code sent to your e-mail |
 | `wx-admin logout [--profile EMAIL] [--everywhere]` | log out: revoke the session of this device, or of every device |
 | `wx-admin status [--profile EMAIL] [--check]` | who you are logged in as, until when, and the version of wx-admin |
@@ -371,6 +410,13 @@ As in the internal Wildix CLI: text for people by default, `--output json` for s
 PBX, `{"type":"result","result":X}` unwrapped to X), `--pretty`, `--no-color`; they may stand anywhere. Messages for
 people (notes, prompts) go to stderr.
 
+## Updates
+
+Once a day, while a command runs in a terminal, `wx-admin` asks npm for its latest version (in the background, never
+holding the command); when there is a newer one, a line after the output says so (`npm i -g wldx-admin-cli`).
+Nothing is installed by itself. Off in CI, under `npx`, without a terminal, with `--output json`, or with
+`WX_NO_UPDATE_CHECK=1`.
+
 ## Exit codes
 
 `0` done · `1` error (network, the PBX refused the request) · `2` not logged in, or the PBX refused the access ·
@@ -397,7 +443,9 @@ pnpm --filter wldx-admin-cli test           # node:test, no network (fake PBX)
 node packages/wx-admin/bin/wx-admin.mjs -h  # this checkout, without installing
 ```
 
-See [AGENTS.md](https://github.com/gorets/wildix-cli/blob/main/packages/wx-admin/AGENTS.md). After changing commands, regenerate the reference: `node tools/readme-commands.mjs`.
+See [AGENTS.md](https://github.com/gorets/wildix-cli/blob/main/packages/wx-admin/AGENTS.md). In `packages/wx-admin`: `node test/dev.mjs <module> <args>`
+runs a command module that is not listed yet; after changing commands, regenerate the reference with
+`node tools/readme-commands.mjs` and paste it between the markers.
 
 ## Releasing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wldx-admin-cli",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Unofficial admin command line for the Wildix PBX (dialplans and the PBX REST API), with an x-bees login or a Company API Key",
   "keywords": [
     "wildix",
@@ -31,7 +31,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "wldx-core": "1.1.0"
+    "wldx-core": "1.2.1"
   },
   "scripts": {
     "test": "node --test test/*.test.mjs"

package/src/commands/config.mjs

@@ -9,7 +9,14 @@ import path from 'node:path';
 import {UsageError} from 'wldx-core/errors';
 import {refuseUnsafeWrite} from 'wldx-core/files';
 import {oneLine, paint} from 'wldx-core/format';
-import {pbxClient} from '../pbx.mjs';
+import {select} from 'wldx-core/select';
+import {pbxClient, readSerial} from '../pbx.mjs';
+import {readExport, writeExport} from '../transfer/folder.mjs';
+import {readKinds, TRANSFER_KINDS} from '../transfer/kinds.mjs';
+import {shellArg} from '../transfer/next-steps.mjs';
+import {runImport} from '../transfer/run.mjs';
+import {toPortable} from '../transfer/refs.mjs';
+import {chooseExport, closure, dbFamiliesOf, selectFrom} from '../transfer/selection.mjs';
 import {maskSecrets} from './trunk.mjs';
 
 const listOf = (r) => (Array.isArray(r) ? r : (r?.records ?? []));
@@ -190,6 +197,115 @@ export function compare(left, right) {
 
 const short = (v) => (v === undefined ? '(none)' : oneLine(JSON.stringify(v), 60));
 
+const interactive = (ctx) => Boolean(ctx.stdin?.isTTY && ctx.stderr?.isTTY);
+
+// A PBX read for a transfer: its objects turned portable (markers instead of references), with where it is.
+export async function exportOf(ctx, client, {users, dbFamily = []}) {
+  const serial = await readSerial(client);
+  // The safety scan and the ACL admin rules need the serial: without it, nothing is carried.
+  if (!serial)
+    throw new UsageError(
+      `The serial of ${client.target.host} is not readable with this access (GET /PBX/settings/, scope pbx:read): it is needed to leave out everything bound to it. Use an access that can read it.`,
+    );
+  let wms;
+  try {
+    wms = (await client.call('GET', '/PBX/version/', undefined, {scope: 'info'}))?.version;
+  } catch {
+    wms = undefined;
+  }
+  const kinds = Object.keys(TRANSFER_KINDS).filter((k) => k !== 'dialplan-db' && (k !== 'users' || users));
+  const snap = await readKinds(client, kinds, {info: ctx.info});
+  const families = [...new Set([...dbFamiliesOf(Array.isArray(snap.dialplans) ? snap.dialplans : []), ...dbFamily])];
+  Object.assign(snap, await readKinds(client, ['dialplan-db'], {dbFamilies: families, info: ctx.info}));
+  return {
+    portable: toPortable(snap, {serial, host: client.target.host}),
+    source: {host: client.target.host, wms},
+    serial,
+  };
+}
+
+const CHOICE_OPTIONS = {
+  all: {type: 'boolean', description: 'everything (users only with --users)'},
+  only: {
+    type: 'string',
+    placeholder: 'KIND:NAME,…',
+    description: 'only these objects and what they need (NAME * for every one of a kind)',
+  },
+  users: {
+    type: 'boolean',
+    description: 'include the users (portable fields only: no ids, passwords or anything of the PBX)',
+  },
+  'db-family': {
+    type: 'string',
+    multiple: true,
+    placeholder: 'FAMILY',
+    description: 'a family of the dialplan database to carry (besides those the dialplans name)',
+  },
+};
+
+const IMPORT_OPTIONS = {
+  all: {type: 'boolean', description: 'every new object (and those that differ, with --overwrite)'},
+  only: CHOICE_OPTIONS.only,
+  overwrite: {type: 'boolean', description: 'without the list: overwrite the objects that differ (else they are left)'},
+  secrets: {
+    type: 'string',
+    placeholder: 'FILE',
+    description: 'without a terminal: the passwords, {"trunks-sip/<name>": {"password": "…"}}',
+  },
+  'dry-run': {type: 'boolean', description: 'the plan and the next steps only; nothing is written (the log is)'},
+  yes: {type: 'boolean', description: 'without a terminal: write without asking'},
+  log: {type: 'string', placeholder: 'DIR', description: 'where the log file goes (default: here)'},
+};
+
+function checkImportValues(ctx) {
+  const v = ctx.values;
+  if (v.all && v.only) throw new UsageError('Give --all or --only, not both', ctx.usage());
+  if (!v.all && !v.only && !interactive(ctx))
+    throw new UsageError(
+      'Without a terminal, choose what to import with --all or --only KIND:NAME,… (and --yes to write)',
+      ctx.usage(),
+    );
+}
+
+// The result printed; exit 1 when an object failed.
+function finish(ctx, r) {
+  if (!r.results.some((x) => x.action === 'failed')) return r;
+  ctx.emit(r);
+  const err = new Error(`${r.results.filter((x) => x.action === 'failed').length} objects failed (log: ${r.log})`);
+  err.exitCode = 1;
+  throw err;
+}
+
+function importText(r, ctx) {
+  const c = paint(ctx);
+  const lines = [];
+  const count = (a) => r.results.filter((x) => x.action === a).length;
+  if (r.dryRun) lines.push(c.bold(`Dry run: nothing was written to ${r.pbx}`));
+  else if (!r.written) lines.push(c.bold(`Nothing was written to ${r.pbx}`));
+  else
+    lines.push(
+      c.bold(
+        `Written to ${r.pbx}: ${count('create')} created, ${count('overwrite')} overwritten, ${count('skip')} skipped, ${count('failed')} failed`,
+      ),
+    );
+  lines.push(
+    `Plan from ${r.from}: ${Object.entries(r.plan.counts)
+      .map(([k, n]) => `${n} ${k}`)
+      .join(', ')}`,
+  );
+  for (const i of r.plan.items.filter((x) => x.state === 'blocked'))
+    lines.push(c.yellow(`  blocked ${i.key}: ${i.reason}`));
+  for (const x of r.results.filter((y) => y.action === 'failed')) lines.push(c.red(`  failed ${x.key}: ${x.error}`));
+  if (r.nextSteps.length) lines.push('', c.bold('Next steps:'));
+  for (const [n, s] of r.nextSteps.entries()) {
+    lines.push(`${n + 1}. ${s.blocking ? c.yellow('[needed] ') : ''}${s.what}`, `   ${c.dim(s.why)}`);
+    if (s.wms) lines.push(`   ${c.dim(`WMS: ${s.wms}`)}`);
+    if (s.command) lines.push(`   ${s.command}`);
+  }
+  lines.push('', `Log: ${r.log}`);
+  return lines;
+}
+
 export const groups = {
   config: {
     summary: 'the configuration as files: back up a PBX to a folder, compare a folder or another PBX with a PBX',
@@ -228,6 +344,137 @@ export const groups = {
           ...Object.entries(r.kinds).map(([k, n]) => `  ${k.padEnd(18)} ${n}`),
         ],
       },
+      import: {
+        summary:
+          'write a config export to this PBX: a plan, what to write (chosen), the passwords, a log and what is left to do',
+        usage:
+          'wx-admin config import <dir> [--all | --only KIND:NAME,…] [--overwrite] [--secrets FILE] [--dry-run] [--yes] [--log DIR]',
+        details: [
+          'Every object of the folder is compared with this PBX: new, the same, differs, or blocked (with the reason). In a',
+          'terminal, a list to tick opens (new ones ticked; ticking one that differs overwrites it), then the passwords',
+          'the chosen trunks need, then a confirmation. Objects are written in the order they need each other; one that',
+          'fails does not stop the rest. A log file is written every time (--log DIR, else here), also with --dry-run.',
+          'Without a terminal: --all or --only, and --yes to write.',
+        ].join('\n'),
+        options: IMPORT_OPTIONS,
+        args: [1, 1],
+        async run(ctx) {
+          checkImportValues(ctx);
+          const {manifest, kinds} = await readExport(ctx, ctx.positionals[0]);
+          const portable = {...manifest, kinds};
+          const client = await pbxClient(ctx);
+          const rerun = `wx-admin config import ${shellArg(ctx.positionals[0])} --pbx ${shellArg(client.target.host)}`;
+          return finish(
+            ctx,
+            await runImport(ctx, {
+              portable,
+              from: `${ctx.positionals[0]} (exported from ${manifest.source?.host ?? 'a PBX'})`,
+              client,
+              values: ctx.values,
+              rerun,
+            }),
+          );
+        },
+        text: importText,
+      },
+      copy: {
+        summary: 'carry the configuration of one PBX to another: export in memory, then import (plan, choice, log)',
+        usage:
+          'wx-admin config copy --from PBX --to PBX [--all | --only KIND:NAME,…] [--users] [--overwrite] [--secrets FILE] [--dry-run] [--yes] [--log DIR]',
+        details: 'As config export then config import, without a folder. --from and --to take what --pbx takes.',
+        options: {
+          from: {type: 'string', placeholder: 'PBX', description: 'the PBX to read', complete: 'pbxs'},
+          to: {type: 'string', placeholder: 'PBX', description: 'the PBX to write', complete: 'pbxs'},
+          users: CHOICE_OPTIONS.users,
+          'db-family': CHOICE_OPTIONS['db-family'],
+          ...IMPORT_OPTIONS,
+        },
+        args: [0, 0],
+        async run(ctx) {
+          const v = ctx.values;
+          if (!v.from || !v.to) throw new UsageError('--from and --to are needed', ctx.usage());
+          if (ctx.pbx) throw new UsageError('copy takes --from and --to, not --pbx', ctx.usage());
+          checkImportValues(ctx);
+          const source = await pbxClient({...ctx, pbx: v.from});
+          const client = await pbxClient({...ctx, pbx: v.to});
+          if (source.target.host === client.target.host)
+            throw new UsageError(`--from and --to are the same PBX: ${client.target.host}`);
+          const [a, b] = [await readSerial(source), await readSerial(client)];
+          if (a && b && a === b) throw new UsageError(`--from and --to are the same PBX (serial ${a})`);
+          const {portable} = await exportOf(ctx, source, {users: v.users, dbFamily: v['db-family']});
+          const bound = new Set(portable.bound.map((x) => `${x.kind}/${x.name}`));
+          const all = Object.entries(portable.kinds).flatMap(([kind, list]) => list.map((o) => `${kind}/${o.name}`));
+          const carried = selectFrom(portable, new Set([...closure(portable, all)].filter((k) => !bound.has(k))));
+          for (const x of portable.bound)
+            ctx.info(`not carried, bound to ${source.target.host}: ${x.kind}/${x.name} (${x.found} in ${x.path})`);
+          const rerun = `wx-admin config copy --from ${shellArg(v.from)} --to ${shellArg(v.to)}${v.users ? ' --users' : ''}`;
+          return finish(
+            ctx,
+            await runImport(ctx, {portable: carried, from: source.target.host, client, values: v, rerun}),
+          );
+        },
+        text: importText,
+      },
+      export: {
+        summary: 'choose what to carry to another PBX and write it to a new folder, without anything bound to this PBX',
+        usage: 'wx-admin config export --to DIR [--all | --only KIND:NAME,…] [--users] [--db-family FAMILY]...',
+        details: [
+          'In a terminal, a list to tick opens (an object brings what it needs). References between objects are kept by',
+          'name; ids, LDAP dns, the serial and passwords of this PBX are left out. An object where the serial or the host',
+          `of this PBX is still found is not exported (listed as bound). Kinds: ${Object.keys(TRANSFER_KINDS).join(', ')}.`,
+          'Then: wx-admin config import DIR --pbx OTHER.',
+        ].join('\n'),
+        options: {to: {type: 'string', placeholder: 'DIR', description: 'a new or empty folder'}, ...CHOICE_OPTIONS},
+        args: [0, 0],
+        async run(ctx) {
+          const v = ctx.values;
+          if (!v.to) throw new UsageError('--to is needed', ctx.usage());
+          if (v.all && v.only) throw new UsageError('Give --all or --only, not both', ctx.usage());
+          if (!v.all && !v.only && !interactive(ctx))
+            throw new UsageError(
+              'Without a terminal, choose what to export with --all or --only KIND:NAME,…',
+              ctx.usage(),
+            );
+          const target = path.resolve(ctx.cwd ?? process.cwd(), v.to);
+          refuseUnsafeWrite(target, ctx.env);
+          if (fs.existsSync(target) && fs.readdirSync(target).length)
+            throw new UsageError(`${v.to} is not empty: export into a new or empty folder (nothing was overwritten)`);
+          const client = await pbxClient(ctx);
+          const usersAsked = v.users || (v.only && /(^|,)\s*users(:|,|$)/.test(v.only));
+          const {portable, source} = await exportOf(ctx, client, {users: usersAsked, dbFamily: v['db-family']});
+          const keys = await chooseExport(portable, v, {interactive: interactive(ctx), select: (o) => select(ctx, o)});
+          const chosen = selectFrom(portable, keys);
+          const {dir, counts} = writeExport(ctx, target, {source, portable: chosen});
+          return {
+            dir,
+            pbx: source.host,
+            kinds: counts,
+            bound: portable.bound,
+            external: chosen.external,
+            unresolved: chosen.unresolved,
+            errors: portable.errors,
+          };
+        },
+        text(r, ctx) {
+          const c = paint(ctx);
+          const lines = [
+            `Exported from ${r.pbx} to ${r.dir}`,
+            ...Object.entries(r.kinds).map(([k, n]) => `  ${k.padEnd(18)} ${n}`),
+          ];
+          for (const [k, e] of Object.entries(r.errors ?? {}))
+            lines.push(c.yellow(`  ${k}: not read (${oneLine(e, 100)})`));
+          for (const b of r.bound)
+            lines.push(c.red(`  not exported, bound to ${r.pbx}: ${b.kind}/${b.name} (${b.found} in ${b.path})`));
+          for (const x of r.external)
+            lines.push(c.yellow(`  outside the PBX, kept as it is: ${x.kind}/${x.name} ${x.path} (${x.what})`));
+          for (const x of r.unresolved)
+            lines.push(
+              c.yellow(`  a reference to nothing on ${r.pbx}, kept: ${x.kind}/${x.name} ${x.path} = ${x.value}`),
+            );
+          lines.push(`Next: wx-admin config import ${r.dir} --pbx OTHER`);
+          return lines;
+        },
+      },
       diff: {
         summary: 'what differs between a backup folder (or another PBX) and the PBX',
         usage: 'wx-admin config diff (<dir> | --with PBX) [--only KIND,KIND…]',

package/src/commands/pbx.mjs

@@ -18,7 +18,7 @@ import {
   savedPbxs,
   setDefaultPbx,
 } from '../pbx.mjs';
-import {readSecret} from '../secret.mjs';
+import {readSecret} from 'wldx-core/secret';
 
 const KINDS = {
   apikey: 'a Company API Key (wsk-v1-…), the access Wildix recommends',

package/src/commands/system.mjs

@@ -15,7 +15,7 @@ import {UsageError} from 'wldx-core/errors';
 import {localTime, oneLine, paint, table} from 'wldx-core/format';
 import {apiPath} from 'wldx-core/http';
 import {pbxClient} from '../pbx.mjs';
-import {readSecret} from '../secret.mjs';
+import {readSecret} from 'wldx-core/secret';
 
 // The features PUT /PBX/settings/ takes (one per request).
 export const FEATURES = [

package/src/commands/trunk.mjs

@@ -18,7 +18,7 @@ import {readForUpload, refuseUnsafeWrite} from 'wldx-core/files';
 import {oneLine, paint, table} from 'wldx-core/format';
 import {apiPath} from 'wldx-core/http';
 import {pbxClient} from '../pbx.mjs';
-import {readSecret} from '../secret.mjs';
+import {readSecret} from 'wldx-core/secret';
 import {findRecord, readJsonInput, wholeNumber} from './routing.mjs';
 
 const SCOPE = {scope: 'trunks'};

package/src/transfer/apply.mjs

@@ -0,0 +1,109 @@
+// Writing a config import: the chosen objects of a plan, in the order of TRANSFER_KINDS (what others point at
+// first). ACL groups and dialplans point at each other (in cycles too), so the new ones are first made bare and get
+// their content in their turn. Every marker becomes the value of the target (ids of objects made in this run
+// included); an object that fails is `failed`, and everything that needs it `skip`ped with it as `because`.
+import {TRANSFER_KINDS} from './kinds.mjs';
+import {fromPortable, keyOf, MissingValue} from './refs.mjs';
+
+const TWO_PASS = ['acl-groups', 'dialplans'];
+
+// plan: makePlan(); chosen: Set of keys; secrets: {[key]: {[path]: value}}; selfDn: "pbxid=<serial of the target>,…"
+// (or null when not readable); onEvent(result) after each result. Returns [{key, action, id?, error?, because?}].
+export async function applyPlan(client, plan, chosen, {secrets = {}, selfDn, onEvent = () => {}} = {}) {
+  const table = {};
+  for (const [key, t] of Object.entries(plan.target)) table[key] = {...t};
+  const results = [];
+  const done = new Map(); // key → result of this run
+  const bare = new Set(); // made bare in pass 1, content not written yet
+  const report = (r) => {
+    // An object made bare whose content was not written stays on the target empty: said so, to be finished.
+    if (bare.has(r.key) && (r.action === 'skip' || r.action === 'failed')) r.bare = true;
+    results.push(r);
+    done.set(r.key, r);
+    onEvent(r);
+  };
+  const items = plan.items.filter((i) => chosen.has(i.key) && (i.state === 'new' || i.state === 'differs'));
+  const order = Object.keys(TRANSFER_KINDS);
+  items.sort((a, b) => order.indexOf(a.kind) - order.indexOf(b.kind));
+
+  const resolveFor = (it) => {
+    const resolve = ({kind, name, as}) => {
+      const t = table[keyOf(kind, name)];
+      if (!t) return undefined;
+      if (as === 'id') return t.id;
+      if (as === 'dn') return t.dn;
+      if (as === 'login') return t.login;
+      return name;
+    };
+    resolve.self = () => {
+      if (!selfDn) throw new MissingValue('the serial of the target PBX is not readable');
+      return selfDn;
+    };
+    resolve.secret = (path) => secrets[it.key]?.[path];
+    return resolve;
+  };
+  const failedNeed = (it) => it.needs.find((n) => ['failed', 'skip'].includes(done.get(n)?.action));
+  const remember = (it, id) => {
+    table[it.key] = {...table[it.key], id: String(id), name: it.name};
+    if (it.kind === 'trunks-sip' && typeof it.data.name === 'string') table[it.key].login = it.data.name;
+  };
+
+  // Pass 1: the new ACL groups and dialplans, bare, so that everything can point at them.
+  for (const it of items.filter((i) => i.state === 'new' && TWO_PASS.includes(i.kind))) {
+    const empty = it.kind === 'acl-groups' ? {name: it.name} : {name: it.name, description: it.data.description ?? ''};
+    try {
+      remember(it, await TRANSFER_KINDS[it.kind].create(client, empty, it.name));
+      bare.add(it.key);
+    } catch (e) {
+      report({key: it.key, action: 'failed', error: e.message});
+    }
+  }
+  // The dns of the ACL groups just made (rules and users point at groups by dn).
+  if (items.some((i) => i.kind === 'acl-groups' && i.state === 'new')) {
+    for (const g of await TRANSFER_KINDS['acl-groups'].read(client)) {
+      const key = keyOf('acl-groups', g.name);
+      table[key] = {...table[key], id: g.id, dn: g.dn, name: g.name};
+    }
+  }
+
+  // Pass 2: every object, whole, in order.
+  for (const it of items) {
+    if (done.has(it.key)) continue;
+    const blocker = failedNeed(it);
+    if (blocker) {
+      report({key: it.key, action: 'skip', because: blocker});
+      continue;
+    }
+    let data;
+    try {
+      data = fromPortable(it.kind, it.data, resolveFor(it));
+    } catch (e) {
+      if (!(e instanceof MissingValue)) throw e;
+      const secret = /the secret (\S+) was not given/.exec(e.message);
+      const missing = /: (\S+) is not on the target/.exec(e.message);
+      report({
+        key: it.key,
+        action: 'skip',
+        because: secret ? `no password: ${secret[1]}` : (missing?.[1] ?? e.message),
+      });
+      continue;
+    }
+    const kind = TRANSFER_KINDS[it.kind];
+    const existing = table[it.key]?.id;
+    try {
+      if (it.state === 'differs' || (TWO_PASS.includes(it.kind) && existing)) {
+        await kind.update(client, existing, data);
+        remember(it, existing);
+        bare.delete(it.key);
+        report({key: it.key, action: it.state === 'differs' ? 'overwrite' : 'create', id: existing});
+      } else {
+        const id = await kind.create(client, data, it.name);
+        remember(it, id);
+        report({key: it.key, action: 'create', id: String(id)});
+      }
+    } catch (e) {
+      report({key: it.key, action: 'failed', error: e.message});
+    }
+  }
+  return results;
+}

package/src/transfer/folder.mjs

@@ -0,0 +1,77 @@
+// The folder of a config export: one JSON Lines file per kind (<kind>.jsonl, one {"name", "data"} per line) and
+// manifest.json (the format, where it comes from, the counts, what the safety scan and the references found). A
+// transport, not something to edit: the serial of the source is never in it.
+import fs from 'node:fs';
+import path from 'node:path';
+import {UsageError} from 'wldx-core/errors';
+import {readForUpload, refuseUnsafeWrite} from 'wldx-core/files';
+import {TRANSFER_KINDS} from './kinds.mjs';
+
+export const FORMAT = 'wx-admin-export/1';
+
+export function writeExport(ctx, dir, {source, portable}) {
+  const target = path.resolve(ctx.cwd ?? process.cwd(), dir);
+  refuseUnsafeWrite(target, ctx.env); // before anything is made
+  fs.mkdirSync(target, {recursive: true, mode: 0o700});
+  if (fs.readdirSync(target).length)
+    throw new UsageError(`${dir} is not empty: export into a new or empty folder (nothing was overwritten)`);
+  const counts = {};
+  for (const [kind, objects] of Object.entries(portable.kinds)) {
+    if (!Object.hasOwn(TRANSFER_KINDS, kind)) throw new UsageError(`Unknown kind: ${kind}`);
+    const text = objects.map((o) => JSON.stringify({name: o.name, data: o.data})).join('\n');
+    fs.writeFileSync(path.join(target, `${kind}.jsonl`), objects.length ? `${text}\n` : '', {flag: 'wx', mode: 0o600});
+    counts[kind] = objects.length;
+  }
+  const manifest = {
+    format: FORMAT,
+    source: {host: source.host, wms: source.wms, exportedAt: new Date(ctx.clock?.() ?? Date.now()).toISOString()},
+    kinds: counts,
+    errors: portable.errors ?? {},
+    bound: portable.bound ?? [],
+    external: portable.external ?? [],
+    unresolved: portable.unresolved ?? [],
+    outside: portable.outside ?? [],
+    needs: portable.needs ?? {},
+    soft: portable.soft ?? {},
+  };
+  fs.writeFileSync(path.join(target, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, {
+    flag: 'wx',
+    mode: 0o600,
+  });
+  return {dir: target, counts};
+}
+
+// The folder read back: {manifest, kinds: {[kind]: [{name, data}]}}. Each file goes through the checks of anything
+// read to be sent (no credentials, nothing hidden in the home folder); a line that is not JSON is named by its number,
+// never by its content.
+export async function readExport(ctx, dir) {
+  const base = path.resolve(ctx.cwd ?? process.cwd(), dir);
+  let manifest;
+  try {
+    manifest = JSON.parse(readForUpload(path.join(base, 'manifest.json'), ctx.env).toString('utf8'));
+  } catch (e) {
+    if (e instanceof UsageError && !/File not found/.test(e.message)) throw e;
+    manifest = undefined;
+  }
+  if (manifest?.format !== FORMAT) throw new UsageError(`${dir} is not a folder of wx-admin config export (${FORMAT})`);
+  const kinds = {};
+  for (const kind of Object.keys(manifest.kinds ?? {})) {
+    if (!Object.hasOwn(TRANSFER_KINDS, kind)) throw new UsageError(`Unknown kind in ${dir}: ${kind}`);
+    const file = `${kind}.jsonl`;
+    const lines = readForUpload(path.join(base, file), ctx.env).toString('utf8').split('\n');
+    kinds[kind] = [];
+    for (const [i, line] of lines.entries()) {
+      if (!line.trim()) continue;
+      let o;
+      try {
+        o = JSON.parse(line);
+      } catch {
+        throw new UsageError(`${file}:${i + 1} is not JSON`);
+      }
+      if (typeof o?.name !== 'string' || !o.data || typeof o.data !== 'object')
+        throw new UsageError(`${file}:${i + 1} is not an object of the export ({"name", "data"})`);
+      kinds[kind].push({name: o.name, data: o.data});
+    }
+  }
+  return {manifest, kinds};
+}