@xgamesfun/solana 0.0.0-stage → 0.20.1

package/js/client/pda.js

@@ -0,0 +1,110 @@
+// Every address the loot program derives, with the seeds the program uses. Each takes base58
+// addresses and numbers and returns a base58 address. Browser-safe.
+import { addressBytes } from '../chain/base58.js';
+import { intLE, utf8, uintLE } from '../chain/bytes.js';
+import { associatedTokenAddress, findProgramAddress, MPL_CORE_PROGRAM, TOKEN_PROGRAM } from '../chain/pda.js';
+import IDL from './idl/loot.js';
+
+export const LOOT_PROGRAM = IDL.address;
+/** MagicBlock's VRF program and its default queue, the only queue the program accepts. */
+export const VRF_PROGRAM = 'Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz';
+export const VRF_QUEUE = 'Cuj97ggrhhidhbu39TijNVqE74xvKJ69gDervRUXAxGh';
+export { MPL_CORE_PROGRAM };
+export const BPF_LOADER_UPGRADEABLE = 'BPFLoaderUpgradeab1e11111111111111111111111';
+/** Compressed NFTs: Bubblegum, and the account compression program and noop of its v2 trees. */
+export const BUBBLEGUM_PROGRAM = 'BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY';
+export const COMPRESSION_PROGRAM = 'mcmt6YrQEMKw8Mw43FmpRLmf7BqRnFMKmAcbxE3xkAW';
+export const NOOP_PROGRAM = 'mnoopTCrg4p8ry25e4bcWA9XZjbNjMTfgYVGGEdRsf3';
+
+const seed = (s) => utf8(s);
+const key = (a) => addressBytes(a);
+const u8 = (n) => uintLE(n, 1);
+const u16 = (n) => uintLE(n, 2);
+const u32 = (n) => uintLE(n, 4);
+const u64 = (n) => uintLE(n, 8);
+const i64 = (n) => intLE(n, 8);
+
+/** The PDA of these seeds under the loot program, with its bump. */
+export const lootAddress = (seeds, program = LOOT_PROGRAM) => findProgramAddress(seeds, program);
+const at = (...seeds) => lootAddress(seeds)[0];
+const keyReceipt = (grant, incarnation, voucherKey) => at(seed('code'), key(grant), u64(incarnation), key(voucherKey));
+
+export const pda = {
+  platform: () => at(seed('platform')),
+  /** A project: any wallet (its creator) opens as many as it likes, each with a number of its own (`id`, a u64). A
+   * new owner keeps the address. */
+  project: (creator, id = 0) => at(seed('project'), key(creator), u64(id)),
+  /** The project's fee box: where the platform's fees on its transactions wait. */
+  fees: (project) => at(seed('fees'), key(project)),
+  pool: (project, index) => at(seed('pool'), key(project), u8(index)),
+  item: (project, id) => at(seed('item'), key(project), u32(id)),
+  box: (project, id) => at(seed('box'), key(project), u32(id)),
+  /** NFTs the project holds to give away as prizes: a box entry of a stash gives one of them at random. */
+  stash: (project, id) => at(seed('stash'), key(project), u32(id)),
+  schedule: (project, id) => at(seed('schedule'), key(project), u32(id)),
+  lottery: (project, id) => at(seed('lottery'), key(project), u32(id)),
+  recipe: (project, id) => at(seed('recipe'), key(project), u32(id)),
+  contest: (project, id) => at(seed('contest'), key(project), u32(id)),
+  /** An auction: an id is its seller's own. Its bids wait in the project's vault for its mint (`vault`). */
+  auction: (project, seller, id) => at(seed('auction'), key(project), key(seller), u32(id)),
+  farm: (project, id) => at(seed('farm'), key(project), u32(id)),
+  grant: (project, id) => at(seed('grant'), key(project), u16(id)),
+  order: (project, player, nonce) => at(seed('order'), key(project), key(player), u64(nonce)),
+  /** Every collectible the program mints of its own accord (an order's, a prize's, an auction's lot): its address
+   * names its item and its serial, minted once at most. */
+  itemAsset: (item, serial) => at(seed('asset'), key(item), u32(serial)),
+  /** A contest's pot, or a lottery's: `["pot", contest or lottery]`. */
+  pot: (record) => at(seed('pot'), key(record)),
+  lotteryFunds: (lottery) => at(seed('lottery_funds'), key(lottery)),
+  lotteryReceipt: (lottery, incarnation, wallet) => at(seed('receipt'), key(lottery), u64(incarnation), key(wallet)),
+  /** One purchase of a lottery's tickets, at a nonce of its buyer's. */
+  contribution: (lottery, player, nonce) => at(seed('contribution'), key(lottery), key(player), u64(nonce)),
+  /** A wallet's entry in a contest: one, on one side (another side is `OtherSide`). */
+  entry: (contest, player) => at(seed('entry'), key(contest), key(player)),
+  /** A hold names its NFT and its end (Unix seconds): a release sent late never finds a later hold of the NFT. */
+  hold: (asset, freeAt) => at(seed('hold'), key(asset), i64(freeAt)),
+  /** An offer: an id is its maker's own. Its money waits in the project's vault for its mint (`vault`). */
+  offer: (project, maker, id) => at(seed('offer'), key(project), key(maker), u32(id)),
+  /** A lottery's own stash: the NFTs its places promise (`Prize::Held`), which leave only as its prizes. */
+  lotteryStash: (lottery) => at(seed('lottery_stash'), key(lottery)),
+  /** A contest's prize split by stake, set aside when it is decided: `["prize", contest]`. */
+  prizeVault: (contest) => at(seed('prize'), key(contest)),
+  /** A sealed schedule's own vault, which only its runs pay out of: `["vest", schedule]`. */
+  vest: (schedule) => at(seed('vest'), key(schedule)),
+  /** A listing of an NFT for sale or for rent: one per NFT a project holds, so its address names the NFT. */
+  listing: (project, asset) => at(seed('listing'), key(project), key(asset)),
+  staked: (farm) => at(seed('staked'), key(farm)),
+  rewards: (farm) => at(seed('rewards'), key(farm)),
+  /** A seat: a player's in a farm of tokens, a collectible's (its asset) in a farm of collectibles. */
+  seat: (farm, by) => at(seed('seat'), key(farm), key(by)),
+  /** What the project writes about an NFT it has no authority over (its Sheet): `nft` is a Core asset, a Token Metadata mint or a compressed NFT's asset id. */
+  sheet: (project, nft) => at(seed('sheet'), key(project), key(nft)),
+  /** A compressed NFT as last proven (`prove_leaf`), read while the leaf is unchanged and its root is still in the tree's change log. */
+  leaf: (asset) => at(seed('leaf'), key(asset)),
+  /** The root of the traits the project vouches for, under its own `key` (a collection's address, by convention). */
+  traits: (project, key_) => at(seed('traits'), key(project), key(key_)),
+  /** Bubblegum's config of a tree: `[tree]`. */
+  treeConfig: (tree) => findProgramAddress([key(tree)], BUBBLEGUM_PROGRAM)[0],
+  /** A compressed NFT's asset id: Bubblegum's `["asset", tree, nonce]`, `nonce` the count minted before it. */
+  compressedAsset: (tree, nonce) => findProgramAddress([seed('asset'), key(tree), u64(nonce)], BUBBLEGUM_PROGRAM)[0],
+  /** A wallet's counter on a box or recipe. Grants and lotteries also name their incarnation. */
+  receipt: (record, wallet) => at(seed('receipt'), key(record), key(wallet)),
+  grantReceipt: (grant, incarnation, wallet) => at(seed('receipt'), key(grant), u64(incarnation), key(wallet)),
+  person: (grant, incarnation, personHash) => at(seed('person'), key(grant), u64(incarnation), Uint8Array.from(personHash)),
+  /** How many times an NFT shown claimed an open grant its gate asks for one of: an address of its own, never a person's. */
+  badge: (grant, incarnation, nft) => at(seed('badge'), key(grant), u64(incarnation), key(nft)),
+  /** A voucher key's counter on a grant (a promo code's). */
+  code: keyReceipt,
+  /** The program's identity, which signs its requests to the oracle. */
+  identity: () => at(seed('identity')),
+  /** The identity the oracle signs callbacks with: the VRF program's PDA for this program. */
+  oracleIdentity: () => findProgramAddress([seed('identity'), key(LOOT_PROGRAM)], VRF_PROGRAM)[0],
+  /** The program's ProgramData account (its upgrade authority signs `init_platform`). */
+  programData: () => findProgramAddress([key(LOOT_PROGRAM)], BPF_LOADER_UPGRADEABLE)[0],
+};
+
+/** `owner`'s associated token account of `mint` (owner may be a PDA: a project's vault, a pool is not one). */
+export const ata = (owner, mint, tokenProgram = TOKEN_PROGRAM) => associatedTokenAddress(owner, mint, tokenProgram);
+
+/** A project's vault for `mint`: its associated token account, where every open order's payment is held. */
+export const vault = (project, mint, tokenProgram = TOKEN_PROGRAM) => ata(project, mint, tokenProgram);

package/js/client/policy.js

@@ -0,0 +1,48 @@
+// Lifecycle rules shared by browsers and optional keepers, read from the decoded accounts. The program still checks
+// every transition; these say when one is worth sending.
+import IDL from './idl/loot.js';
+
+const constant = name => BigInt(IDL.constants.find(value => value.name === name).value);
+export const STALE_SLOTS = constant('STALE_SLOTS');
+export const LOTTERY_TIMEOUT_SLOTS = constant('LOTTERY_TIMEOUT_SLOTS');
+const U64_MAX = (1n << 64n) - 1n;
+
+/**
+ * The earliest slot an order can be refunded in, or null when it never can be: a rolled order has an outcome anyone
+ * can carry out, and is settled, never refunded; a roll a mission or a recipe made waits for anyone to ask for it
+ * (`Waiting`), and once asked (`Asked`) is asked again if the oracle never answers (`rollAskable`).
+ */
+export function orderRefundSlot(order) {
+  let wait;
+  if (order.status === 'Failed') wait = 0n;
+  else if (order.status === 'Pending') wait = STALE_SLOTS;
+  else if (['Rolled', 'Waiting', 'Asked'].includes(order.status)) return null;
+  else throw new Error('Unknown order status.');
+  const deadline = BigInt(order.requested_slot) + wait;
+  // The program requires strictly greater than the saturating deadline; MAX + 1 is unreachable.
+  return (deadline > U64_MAX ? U64_MAX : deadline) + 1n;
+}
+
+/** Whether anyone may ask the oracle for a mission's or a recipe's roll at `slot`: never asked, or never answered. */
+export const rollAskable = (order, slot) => order.status === 'Waiting' || (order.status === 'Asked' && BigInt(slot) > BigInt(order.requested_slot) + STALE_SLOTS);
+
+/**
+ * Whether a contest is off at `now` (Unix seconds), as the program reads its verdict: called off, its result
+ * overdue, or short of its least pot once entries closed. Every entry of one that is off takes its money back.
+ */
+export function contestOff(contest, now) {
+  if (contest.verdict === 'Off') return true;
+  if (contest.verdict !== 'Open') return false;
+  const total = contest.sides.reduce((sum, side) => sum + BigInt(side), 0n);
+  return BigInt(now) > BigInt(contest.result_by) || (BigInt(now) >= BigInt(contest.closes_at) && total < BigInt(contest.min_pot ?? 0));
+}
+
+/** Whether a lottery's draw was asked for and the oracle has not answered within `STALE_SLOTS`: anyone may ask again. */
+export const lotteryDrawStuck = (lottery, slot) => lottery.status === 'Drawing' && BigInt(slot) > BigInt(lottery.asked_slot) + STALE_SLOTS;
+
+/**
+ * Whether a lottery's draw was asked for and the oracle has not answered within `LOTTERY_TIMEOUT_SLOTS` of the first
+ * ask (asking again doesn't move it): anyone may cancel the round and refund it. A round nobody asked to draw is never
+ * cancelled.
+ */
+export const lotteryCancellable = (lottery, slot) => lottery.status === 'Drawing' && BigInt(slot) > BigInt(lottery.asked_first) + LOTTERY_TIMEOUT_SLOTS;

package/js/client/sizes.js

@@ -0,0 +1,54 @@
+// Rent sizes from the current IDL. Fixed allocations reserve the largest enum and option forms,
+// matching Anchor InitSpace. Dynamic records use their actual encoded fields.
+import { encodeAccount } from '../chain/borsh.js';
+import IDL from './idl/loot.js';
+
+const scalar = { bool: 1, u8: 1, u16: 2, u32: 4, i32: 4, u64: 8, i64: 8, u128: 16, pubkey: 32 };
+// The most an order holds: its shares, and a roll's fate (`MAX_SHIFTS` numbers, each key at most 32 bytes).
+const bounds = { 'Order.shares': 4, 'Order.won': 3, 'Fate.shifts': 2, 'Project.collections': 8 };
+const strings = { 'Shift.key': 32 };
+function maximum(type, path) {
+  if (type === 'string') {
+    if (!(path in strings)) throw new Error(`No allocation bound for ${path}`);
+    return 4 + strings[path];
+  }
+  if (typeof type === 'string') {
+    if (!(type in scalar)) throw new Error(`Unbounded IDL type ${path}: ${type}`);
+    return scalar[type];
+  }
+  if (type.array) return type.array[1] * maximum(type.array[0], path);
+  if (type.option) return 1 + maximum(type.option, path);
+  if (type.vec) {
+    if (!(path in bounds)) throw new Error(`No allocation bound for ${path}`);
+    return 4 + bounds[path] * maximum(type.vec, path);
+  }
+  const name = type.defined.name;
+  const definition = IDL.types.find((entry) => entry.name === name)?.type;
+  if (!definition) throw new Error(`Missing current IDL type ${name}`);
+  const fields = (list) => (list ?? []).reduce((n, field) => n + maximum(field.type ?? field, `${name}.${field.name ?? ''}`), 0);
+  return definition.kind === 'enum' ? 1 + Math.max(...definition.variants.map((variant) => fields(variant.fields))) : fields(definition.fields);
+}
+
+/** The space reserved by a fixed-size account, including its discriminator. */
+export function allocationBytes(name) {
+  const account = IDL.accounts.find((entry) => entry.name === name);
+  if (!account) throw new Error(`Missing current IDL account ${name}`);
+  return account.discriminator.length + maximum({ defined: { name } }, name);
+}
+
+/** The exact bytes of a dynamically allocated account. */
+export const accountBytes = (name, value) => encodeAccount(IDL, name, value).length;
+export const ACCOUNT_BYTES = Object.freeze({ ...Object.fromEntries(['Order', 'Seat', 'Hold', 'Entry', 'LotteryContribution'].map((name) => [name, allocationBytes(name)])) });
+
+/** A project's bytes with `collections` collections, as the program sizes the account. */
+export const projectBytes = (collections = 0) => 153 + 32 * collections;
+
+// A receipt is not in the IDL and is read by hand: a 17-byte head (its tag, counts and how many rounds), then 8 bytes
+// for each round it holds (see docs/program.md).
+export const MAX_RECEIPT_ROUNDS = Number(IDL.constants.find((entry) => entry.name === 'MAX_RECEIPT_ROUNDS').value);
+export const RECEIPT_BASE_BYTES = 17;
+export const RECEIPT_ROUND_BYTES = 8;
+export function receiptBytes(rounds = 0) {
+  if (!Number.isInteger(rounds) || rounds < 0 || rounds > MAX_RECEIPT_ROUNDS) throw new RangeError(`A receipt retains at most ${MAX_RECEIPT_ROUNDS} distinct voucher rounds`);
+  return RECEIPT_BASE_BYTES + RECEIPT_ROUND_BYTES * rounds;
+}

package/js/client/traits.js

@@ -0,0 +1,44 @@
+// The traits a project vouches for (`set_traits`, `prove_traits`): a Merkle tree of what NFTs' off-chain metadata says
+// of them (a background, a class), whose root the project's owner or authority signs once. Anyone then writes an NFT's
+// traits into its Sheet with its proof. Leaves and nodes are hashed exactly as the program hashes them. Browser-safe.
+import { addressBytes } from '../chain/base58.js';
+import { compareBytes, concat, uintLE, utf8 } from '../chain/bytes.js';
+import { sha256 } from '../chain/sha256.js';
+
+const text = (s) => concat(uintLE(utf8(s).length, 4), utf8(s));
+
+/** A leaf: an NFT's address and its traits ([{ key, value }], in order). */
+export const traitsLeaf = (nft, attributes) =>
+  sha256(concat(Uint8Array.of(0), addressBytes(nft), uintLE(attributes.length, 4), ...attributes.map((a) => concat(text(a.key), text(a.value)))));
+
+/** Two nodes joined, the smaller first, so a proof needs no left or right. */
+export const traitsNode = (a, b) => (compareBytes(a, b) <= 0 ? sha256(concat(Uint8Array.of(1), a, b)) : sha256(concat(Uint8Array.of(1), b, a)));
+
+/**
+ * The tree of `entries` ([{ nft, attributes }]): { root, proof(nft) → [node, …] bottom up }. A node left without a pair
+ * at a level goes up as it is.
+ */
+export function traitsTree(entries) {
+  const levels = [entries.map((e) => traitsLeaf(e.nft, e.attributes))];
+  while (levels.at(-1).length > 1) {
+    const below = levels.at(-1);
+    const up = [];
+    for (let i = 0; i < below.length; i += 2) up.push(i + 1 < below.length ? traitsNode(below[i], below[i + 1]) : below[i]);
+    levels.push(up);
+  }
+  const at = new Map(entries.map((e, i) => [e.nft, i]));
+  return {
+    root: levels.at(-1)[0],
+    proof(nft) {
+      let i = at.get(nft);
+      if (i === undefined) throw new Error(`${nft} is not in this traits tree.`);
+      const out = [];
+      for (const level of levels.slice(0, -1)) {
+        const sibling = i ^ 1;
+        if (sibling < level.length) out.push(level[sibling]);
+        i >>= 1;
+      }
+      return out;
+    },
+  };
+}

package/js/connect/connect.mjs

@@ -0,0 +1,182 @@
+// `xsolana connect`: adds the xsolana MCP server and the xsolana-economy skill to the coding agents on this machine (Claude
+// Code, Codex), through each agent's own commands. It never edits an agent's config file and never reads a
+// credential. With `--local`, the server runs from this checkout (before the package is published); otherwise from npm.
+// `--scope user` (the default) adds them for every project of this user; `--scope project`, for the project folder
+// it runs in only.
+import { exec, execFile } from 'node:child_process';
+import { cp, mkdir, readFile, rm, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const NAME = 'xsolana';
+const SKILL = 'xsolana-economy';
+
+/** The scopes `xsolana connect` knows: every project of this user, or the one project folder it runs in. */
+export const SCOPES = ['user', 'project'];
+
+/**
+ * The agents xsolana connect to, as data: a new agent is a row. `scopes`: where the agent can register an MCP server
+ * from its command line. `skills(scope, cwd)`: the folder its skills are read from.
+ */
+export const AGENTS = {
+  claude: {
+    name: 'Claude Code',
+    bin: 'claude',
+    scopes: ['user', 'project'],
+    add: (command, args, scope) => ['mcp', 'add', '--transport', 'stdio', '--scope', scope, NAME, '--', command, ...args],
+    remove: (scope) => ['mcp', 'remove', '--scope', scope, NAME],
+    get: ['mcp', 'get', NAME],
+    skills: (scope, cwd) => (scope === 'project' ? path.join(cwd, '.claude', 'skills') : path.join(os.homedir(), '.claude', 'skills')),
+    plugin: 'Or install the plugin: /plugin marketplace add XGamesFun/solana-kit, then /plugin install xsolana@xgamesfun.',
+    next: 'Start a new Claude Code session (or /mcp) to load the xsolana tools.',
+  },
+  codex: {
+    name: 'Codex',
+    bin: 'codex',
+    scopes: ['user'],
+    add: (command, args) => ['mcp', 'add', NAME, '--', command, ...args],
+    remove: () => ['mcp', 'remove', NAME],
+    get: ['mcp', 'get', NAME],
+    skills: (scope, cwd) => (scope === 'project' ? path.join(cwd, '.agents', 'skills') : path.join(os.homedir(), '.agents', 'skills')),
+    plugin: 'Or install the plugin: codex plugin marketplace add XGamesFun/solana-kit, then codex plugin add xsolana@xgamesfun.',
+    next: 'Start a new Codex session so it picks up the xsolana tools.',
+  },
+};
+
+/** One word for cmd.exe: as it is when it is plain, else in double quotes (a quote inside doubled). */
+const winWord = (a) => (/^[\w@+=:,./\\-]+$/.test(a) ? a : `"${String(a).replace(/"/g, '""')}"`);
+
+/**
+ * Runs an agent's command and answers { code, out }. On Windows the agents are installed as .cmd shims, which only a
+ * shell can start: there the command goes to cmd.exe as one line, each word quoted as it needs.
+ */
+export function runAgent(bin, args, { platform = process.platform, execFileImpl = execFile, execImpl = exec } = {}) {
+  return new Promise((resolve) => {
+    const done = (error, stdout, stderr) => resolve({ code: error ? (typeof error.code === 'number' ? error.code : 1) : 0, out: `${stdout ?? ''}${stderr ?? ''}`.trim() });
+    if (platform === 'win32') execImpl([bin, ...args].map(winWord).join(' '), { timeout: 60_000, windowsHide: true }, done);
+    else execFileImpl(bin, args, { timeout: 60_000 }, done);
+  });
+}
+
+/**
+ * The command that starts the server: this checkout's (`local`), or the published package's. On Windows, npx is a
+ * .cmd shim that an agent can only start through cmd.exe.
+ */
+export async function serverCommand({ local = false, platform = process.platform } = {}) {
+  if (local) return { command: process.execPath, args: [path.join(ROOT, 'bin', 'xsolana.mjs'), 'mcp'] };
+  const { version } = JSON.parse(await readFile(path.join(ROOT, 'package.json'), 'utf8'));
+  const npx = ['-y', `--package=@xgamesfun/solana@${version}`, 'xsolana', 'mcp'];
+  return platform === 'win32' ? { command: 'cmd', args: ['/c', 'npx', ...npx] } : { command: 'npx', args: npx };
+}
+
+/**
+ * What is in a skill folder: 'none' (nothing there), 'ours' (xsolana's own skill: its SKILL.md names xsolana-economy in its
+ * frontmatter, so it may be replaced or removed), or 'other' (anything else, which xsolana never touches).
+ */
+export async function skillFolder(dir) {
+  try {
+    await stat(dir);
+  } catch {
+    return 'none';
+  }
+  try {
+    const text = await readFile(path.join(dir, 'SKILL.md'), 'utf8');
+    const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? '';
+    return /^name:\s*["']?xsolana-economy["']?\s*$/m.test(front) ? 'ours' : 'other';
+  } catch {
+    return 'other';
+  }
+}
+
+/** Connects (or with `remove`, disconnects) each agent found. Returns an exit code. */
+export async function connect({ agent, local = false, remove = false, dryRun = false, scope = 'user', cwd = process.cwd(), log = (...a) => console.log(...a), run = runAgent } = {}) {
+  if (!SCOPES.includes(scope)) {
+    log(`No scope called “${scope}” (${SCOPES.join(', ')}).`);
+    return 1;
+  }
+  if (agent && !AGENTS[agent]) {
+    log(`No agent called “${agent}” (${Object.keys(AGENTS).join(', ')}).`);
+    return 1;
+  }
+  const ids = agent ? [agent] : Object.keys(AGENTS);
+  const { command, args } = await serverCommand({ local });
+  let failed = 0;
+  let found = 0;
+  for (const id of ids) {
+    const a = AGENTS[id];
+    const version = await run(a.bin, ['--version']);
+    if (version.code !== 0) {
+      if (agent) log(`${a.name}: not found on this machine.`);
+      continue;
+    }
+    found++;
+    if (!a.scopes.includes(scope)) {
+      log(`${a.name}: adds MCP servers only for the whole user (--scope ${a.scopes.join(' or ')}), so it was left as it is. Run \`xsolana connect --agent ${id}\` for that.`);
+      if (agent) failed++;
+      continue;
+    }
+    // Registered already (at some scope): taken out at this scope first. Before an add that may fail (it is at the
+    // other scope); for --remove it is the whole point, so whether it worked is told.
+    const steps = [];
+    const had = await run(a.bin, a.get);
+    if (had.code === 0) steps.push({ args: a.remove(scope), optional: true, removal: true });
+    if (!remove) steps.push({ args: a.add(command, args, scope) });
+    let ok = true;
+    let removed = false;
+    for (const { args: s, optional, removal } of steps) {
+      if (dryRun) {
+        log(`${a.bin} ${s.join(' ')}`);
+        continue;
+      }
+      const r = await run(a.bin, s);
+      if (removal && r.code === 0) removed = true;
+      if (r.code !== 0 && !optional) {
+        log(`${a.name}: ${a.bin} ${s.slice(0, 3).join(' ')} failed: ${r.out.split('\n').at(-1)}`);
+        failed++;
+        ok = false;
+      }
+    }
+
+    // The skill: copied into the agent's skills folder for this scope. A folder of that name that is not xsolana's own
+    // skill is never replaced or removed.
+    const skills = a.skills(scope, cwd);
+    const skillDir = path.join(skills, SKILL);
+    const there = await skillFolder(skillDir);
+    let skillSaid;
+    if (there === 'other') {
+      log(`${a.name}: ${skillDir} is there already and is not xsolana's ${SKILL} skill, so it was left as it is${remove ? '' : ' and the skill was not copied'}. Move it away, then run \`xsolana connect\` again.`);
+      failed++;
+      ok = false;
+    } else if (remove) {
+      if (dryRun) log(there === 'ours' ? `remove ${skillDir}` : `(no skill at ${skillDir} to remove)`);
+      else if (there === 'ours') await rm(skillDir, { recursive: true, force: true });
+      skillSaid = there === 'ours' ? `; the ${SKILL} skill removed from ${skillDir}` : '';
+    } else {
+      if (dryRun) log(`${there === 'ours' ? 'replace the xsolana skill at' : 'copy skills/xsolana-economy to'} ${skillDir}`);
+      else {
+        await mkdir(skills, { recursive: true });
+        if (there === 'ours') await rm(skillDir, { recursive: true, force: true });
+        await cp(path.join(ROOT, 'skills', SKILL), skillDir, { recursive: true });
+      }
+      skillSaid = ` and the ${SKILL} skill copied to ${skillDir}`;
+    }
+    if (dryRun) continue;
+    if (remove) {
+      // Registered, but not at this scope: it is still there, and the person asked for it gone.
+      const stays = had.code === 0 && !removed;
+      if (stays) failed++;
+      const server = removed ? 'xsolana removed' : stays ? `xsolana’s server was not found at the ${scope} scope, so it was left where it is (\`${a.bin} mcp get ${NAME}\` shows where)` : 'xsolana’s server was not registered';
+      log(`${a.name}: ${server}${skillSaid ?? ''}.`);
+    } else if (ok) {
+      log(`${a.name}: xsolana tools added (${local ? 'from this checkout' : 'from npm'}, ${scope === 'project' ? `for ${cwd} only` : 'for every project'})${skillSaid}. ${a.next}`);
+      log(`  ${a.plugin}`);
+    }
+  }
+  if (!found) {
+    log('No coding agent found (Claude Code: npm install -g @anthropic-ai/claude-code; Codex: npm install -g @openai/codex).');
+    return 1;
+  }
+  return failed ? 1 : 0;
+}