sf veles CLI plugin

@beyondthecloud/sf-veles adds one command to the Salesforce CLI: sf veles setup. It sets up Veles on an existing scratch org or sandbox and connects it to your Hub.

sf plugins install @beyondthecloud/sf-veles
sf veles setup --target-org <alias> [--target-dev-hub <hub>] [--group <name>]... [--installation-key <key>]

Prerequisites

• The target org exists and is authorised in the CLI. The command does not create orgs.
• Veles 0.110.0 or later on the Hub. The command checks both versions before changing anything.
• Your Hub user holds Veles Developer (included in Veles Admin).
• Scratch org: a group marked Scratch Org Group exists on the Hub, or you pass --group.
• Sandbox: its environment row already exists on the Hub (New Environment > From Sandbox). --group is refused for a sandbox; it takes its groups from that row.

Flags

Flag	Short	Meaning
--target-org	-o	The scratch org or sandbox to set up. Required.
--target-dev-hub	-v	The Hub. Defaults to the CLI's default Dev Hub.
--group	-g	Environment group on the Hub. Repeatable, first wins. Scratch orgs only.
--installation-key	-k	Installation key for the package, if it has one.
--integration-permset		Name of the unmanaged clone of Veles Hub Integration to create and assign. Default VelesIntegration.
--integration-user		Username in the target org to set up as the integration user. Default: the CLI user.
--verbose		Sub-steps, warnings and a summary.
--json		Machine-readable result; exit code reflects success.

What it does

1. Resolving org & Hub: registers the org on the Hub (environment row and connection token).
2. Installing Veles package: installs the Hub's version if Veles is missing.
3. Deploying connection metadata: the Remote Site Setting for the Hub.
4. Configuring Hub connection: Hub URL, Hub integration username, the org's own environment row.
5. Pre-authorizing integration user: clones the permission set, assigns it, grants a seat if needed, pre-authorises it on the ECA. Problems here are warnings, not failures.
6. Connecting to Hub.
7. Setting up environment (RSS): waits up to 3 minutes for the Hub's Remote Site Setting and for the Hub to sign in to the org.

Success ends with Veles setup complete. A failed step prints ✖, the reason as Error (1): ... with a Try this: hint, and exits 1.

Errors you may see

Error	Meaning
VelesDev permission set not assigned.	Assign Veles Developer or Veles Admin to your user on the Hub.
No Environment Group is marked as a Scratch Org Group.	Create one on the Hub, or pass --group.
Sandbox not found on this Hub	Add the sandbox on the Hub first.
The Hub <url> refused to connect this org: ...	Usually the connected-orgs limit of your plan. The text says so.
The Hub cannot sign in to this org as <user>: ...	The integration user is not pre-authorised in the target org. Finish Step 1 of its Setup tab.
Connecting to Hub did not finish within 3 minutes	Run the command again; it skips what is done.