@artblocks/abx-cli 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/main.js

@@ -34,13 +34,14 @@
  *   abx storage backup-key   copy the managed Turbo/Arweave key (holds credits) to a safe path
  *   abx status               list indexed projects + node info
  *   abx doctor               check environment (key, RPC, balance, factory, storage)
- *   abx skill install        install the abx agent skill into your agent (.claude/skills; --global)
+ *   abx skill install        install the version-locked abx agent skill into your agent(s)
+ *                            (default: Claude Code + the neutral .agents/skills; --agent/--global)
  *
  * Every write picks a signing lane: default hot (env key signs), `--sign` (a human
  * approves in their own wallet via a one-shot localhost page), `--unsigned` (print
  * the tx for a multisig / offline signer). The agent picks the lane; the CLI signs.
  */
-import { appendFileSync, copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { basename, extname, join as joinPath, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -54,7 +55,7 @@ import { DEP_RESOLUTION, deploySeedSource, deploySeriesCodeFactory, prepareCodeS
 import { checkRegistryDeps, dependencySetupCalls, parseDepFlag, resolveDepRegistryPointer } from './deps.js';
 import { composeParamsKeys, expectedChainComplete, hasOnChainUriLane, onchainUriSetupCalls, onChainUriReport } from './onchain-uri.js';
 import { parseFlags, unknownFlags } from './flags.js';
-import { checkForCliUpdate, compareVersions, installedSkillVersions, readCliVersion, SKILL_VERSION_MARKER } from './update-check.js';
+import { AGENT_SKILL_PARENTS, checkForCliUpdate, compareVersions, installedSkillVersions, readCliVersion, readSkillVersion, SKILL_DIR_NAME, } from './update-check.js';
 import { analyzeScript, recommendLane } from './inspect.js';
 import { parseSchemaSpecs, describeSchema } from './schema.js';
 import { parseSeriesTraits, looksPerTokenAttributes, parseSeriesTraitsById } from './series-traits.js';
@@ -133,7 +134,7 @@ async function maybeNotifyUpdate(flags) {
         const latest = await checkForCliUpdate(current);
         if (latest) {
             console.error(`\n    ${c.orange}⚠${c.reset}  update available: ${bold('abx')} ${dim(current)} → ${g(latest)}\n` +
-                `       upgrade: ${g('npm i -g @artblocks/abx-cli@latest')} ${dim('· or invoke:')} ${g('npx abx@latest <command>')}\n` +
+                `       upgrade: ${g('npm i -g @artblocks/abx-cli@latest')} ${dim('· or invoke:')} ${g('npx @artblocks/abx-cli@latest <command>')}\n` +
                 `       release notes: https://github.com/ArtBlocks/abx/releases ${dim('· silence: ABX_NO_UPDATE_CHECK=1')}\n`);
         }
     }
@@ -4166,99 +4167,109 @@ async function cmdMigrate(address, flags) {
 }
 // ── doctor ────────────────────────────────────────────────────────────────--
 async function cmdDoctor(flags) {
-    console.log(bold('\n  abx doctor\n'));
-    const check = (label, pass, detail = '') => console.log(`  ${pass ? g('✓') : `${c.red}✗${c.reset}`} ${label}${detail ? dim('  ' + detail) : ''}`);
+    console.log(bold('\n  abx doctor') + dim(`  ·  ${CHAIN}`) + '\n');
+    // Two visual tiers: PASS/FAIL checks (✓/✗) for things that are either working or broken, and an
+    // "Optional" block (·) for path-dependent setup that is fine to be unset. We deliberately do NOT
+    // use ⚠ for "unset but often fine" — that read as noise; ⚠ is reserved for a real gotcha (a
+    // range-capped RPC). Labels are padded so both tiers align.
+    const CONT = ' '.repeat(17); // continuation indent: aligns under a check/opt detail column
+    const check = (label, pass, detail = '') => console.log(`  ${pass ? g('✓') : `${c.red}✗${c.reset}`} ${label.padEnd(13)}${detail ? dim(detail) : ''}`);
+    const opt = (label, detail) => console.log(`  ${dim('·')} ${label.padEnd(13)}${dim(detail)}`);
     const hasKey = !!(process.env.ABX_DEPLOYER_PK ?? process.env.SEPOLIA_FUNDED_PK ?? process.env.SEPOLIA_WALLET_PK);
-    // Not having an env key is NOT fatal: the wallet lane (`--sign`) signs in the user's own wallet,
-    // key-free. Only flag it as a soft note + point at the lanes — never imply "paste a private key."
-    if (hasKey)
-        check('signing key in env', true, 'hot lane ready (env key signs unattended)');
-    else
-        console.log(`  ${c.orange}⚠${c.reset} signing key in env${dim('  none — fine if you sign in your own wallet (`--sign`; the key never touches the CLI). Only set ABX_DEPLOYER_PK / SEPOLIA_FUNDED_PK / SEPOLIA_WALLET_PK for hot/unattended signing.')}`);
+    // 1. Agent skill — FIRST and prominent. The primary way to use abx is to let a coding agent drive
+    //    it, so a missing/stale skill is a ✗: not broken infra, but the main UX isn't set up. Its
+    //    version lives in SKILL.md frontmatter (version-locked to this CLI). Notify-only — no exit code.
+    const cliVersion = readCliVersion();
+    const skillVersions = installedSkillVersions();
+    const staleSkills = skillVersions.filter((v) => compareVersions(cliVersion, v) > 0);
+    if (skillVersions.length === 0) {
+        check('agent skill', false, `not installed — run ${g('abx skill install')}`);
+        console.log(`${CONT}${dim('(recommended: let a coding agent drive abx)')}`);
+    }
+    else if (staleSkills.length > 0) {
+        check('agent skill', false, `v${staleSkills.join(', v')} behind CLI v${cliVersion} — run ${g('abx skill install')}`);
+    }
+    else {
+        check('agent skill', true, `in sync (v${cliVersion})`);
+    }
+    console.log('');
+    // 2. Core environment (✓/✗). Signing-wallet balances are computed here (they need the RPC) but
+    //    printed in the Optional block below, so buffer them.
+    let signingOpt = null;
+    let forOpt = null;
     try {
         const publicClient = makePublicClient({ chainKey: CHAIN });
         const bn = await publicClient.getBlockNumber();
-        check(`RPC reachable (${CHAIN})`, true, `head block ${bn}`);
-        // RPC endpoints — probe each for reachability, getLogs range, and archive depth,
-        // so the toolkit uses (and recommends) the one fit for the job — and says so if none are.
+        // Collapse the RPC report to one line (best endpoint + head), and only add a ⚠ when there is a
+        // genuine problem — a range-capped-only set that will grind a resolver under load.
         const probes = await probeRpcEndpoints({ chainKey: CHAIN });
         const usable = probes.filter((pr) => pr.verdict !== 'unusable');
         const best = probes.find((pr) => pr.verdict === 'best') ?? usable[0];
-        check(`RPC endpoints for ${CHAIN} (${probes.length})`, usable.length > 0, usable.length > 0
-            ? `best for reconstruction: ${best.label} (${best.verdict === 'best' ? 'wide range + archive' : 'usable, range-capped'})`
-            : 'none usable for reconstruction');
-        for (const pr of probes) {
-            const glyph = pr.verdict === 'best' ? g('✓') : pr.verdict === 'capped' ? `${c.orange}⚠${c.reset}` : `${c.red}✗${c.reset}`;
-            console.log(`      ${glyph} ${pr.label} ${dim('— ' + (pr.verdict === 'best' ? 'wide getLogs range + archive' : pr.reason ?? pr.verdict))}`);
-        }
-        if (usable.length === 0) {
-            console.log(`  ${c.orange}↳${c.reset} ${dim('research a current free archive RPC with a wide getLogs range and add it to ABX_RPC_URLS — see the skill’s “Choosing an RPC”')}`);
-        }
-        else if (!probes.some((pr) => pr.verdict === 'best')) {
-            // Every usable endpoint is range-capped. Indexing still works (chunking), but a first
-            // reconstruction — and a resolver under marketplace load — is slow + rate-limit-prone. That's
-            // a serious infra signal, NOT "a paid plan is required": flag it. A normal deploy→index only
-            // scans from the deploy block, so this bites first reconstructions and busy resolvers most.
-            console.log(`  ${c.orange}⚠ every usable RPC is getLogs-range-capped${c.reset} ${dim('— add a wide-range archive endpoint to ABX_RPC_URLS before running a resolver under load; capped ones grind on wide scans (skill → “Choosing an RPC”).')}`);
-        }
-        if (hasKey) {
-            const { account } = makeWalletClient({ chainKey: CHAIN });
-            const bal = await publicClient.getBalance({ address: account.address });
-            check('deployer funded', bal > 0n, `${account.address} · ${formatEther(bal)} ETH`);
-        }
-        // Wallet lane has no env key — let a creator preflight THEIR OWN signing wallet's balance,
-        // the one gap where an unfunded wallet otherwise only surfaces at the signing step.
-        if (flags.for) {
-            const bal = await publicClient.getBalance({ address: flags.for });
-            check('wallet funded (--for)', bal > 0n, `${flags.for} · ${formatEther(bal)} ETH${bal > 0n ? '' : ` — ${faucetHint(CHAIN)}`}`);
+        if (usable.length > 0) {
+            check('RPC', true, `${best.label} · head ${bn} · ${best.verdict === 'best' ? 'wide range + archive' : 'range-capped'}`);
+            if (!probes.some((pr) => pr.verdict === 'best')) {
+                console.log(`${CONT}${c.orange}⚠${c.reset}${dim(' every endpoint is getLogs-range-capped — add a wide-range archive RPC to ABX_RPC_URLS before running a resolver under load')}`);
+            }
         }
-        else if (!hasKey) {
-            console.log(`  ${dim('↳ wallet lane: run `abx doctor --for 0x<your wallet>` to check your signing wallet is funded')}`);
+        else {
+            check('RPC', false, `${CHAIN} — no endpoint usable for reconstruction; add a wide-range archive RPC to ABX_RPC_URLS`);
         }
         const factory = factoryAddress();
         if (factory) {
             const code = await publicClient.getCode({ address: factory });
-            if (!code || code === '0x') {
-                check('canonical factory deployed', false, `${factory} — no code on ${CHAIN}; \`abx deploy\` redeploys`);
-            }
-            else if (await isCurrentFactory(publicClient, factory)) {
-                check('canonical factory deployed', true, factory);
-            }
-            else {
-                check('canonical factory deployed', false, `${factory} — older/incompatible version; \`abx deploy\` redeploys`);
-            }
+            if (!code || code === '0x')
+                check('factory', false, `${factory} — no code on ${CHAIN}; \`abx deploy\` redeploys`);
+            else if (await isCurrentFactory(publicClient, factory))
+                check('factory', true, factory);
+            else
+                check('factory', false, `${factory} — older/incompatible; \`abx deploy\` redeploys`);
         }
         else {
-            check('canonical factory deployed', false, 'none yet — `abx demo` deploys one');
+            check('factory', false, 'none yet — `abx demo` deploys one');
+        }
+        if (hasKey) {
+            const { account } = makeWalletClient({ chainKey: CHAIN });
+            const bal = await publicClient.getBalance({ address: account.address });
+            signingOpt = `env key ${account.address} · ${bal > 0n ? `funded ${formatEther(bal)} ETH` : `empty — fund it (${faucetHint(CHAIN)})`}`;
+        }
+        if (flags.for) {
+            const bal = await publicClient.getBalance({ address: flags.for });
+            forOpt = `${flags.for} · ${bal > 0n ? `funded ${formatEther(bal)} ETH` : `empty — ${faucetHint(CHAIN)}`}`;
         }
     }
     catch (err) {
-        check('RPC reachable', false, err.message);
+        check('RPC', false, err.message);
     }
-    // public base URL — baked into on-chain URIs at deploy; unset is fine for a demo
-    // but a silent footgun for a real launch, so surface it explicitly.
-    const baseUrl = process.env.ABX_PUBLIC_BASE_URL;
-    if (baseUrl)
-        check('public base URL set (baked into on-chain URIs)', true, baseUrl);
-    else
-        console.log(`  ${c.orange}⚠${c.reset} public base URL${dim('  ABX_PUBLIC_BASE_URL unset → resolver-served deploys REFUSE (localhost on-chain resolves for no one). Set it (or --public-base-url) for a hosted resolver. IRRELEVANT if you go fully on-chain: --onchain-image (1/1) or --onchain-uri (code project) bake no resolver base.')}`);
     // storage backend — resolve it (catches missing config), then probe liveness/creds
     const backendId = activeBackendId();
     try {
         const backend = resolveBackend(storageOptions());
         const h = await backend.health?.();
         if (h)
-            check(`storage backend '${backend.id}' reachable`, h.ok, h.detail ?? '');
+            check('storage', h.ok, `${backend.id} · ${h.detail ?? ''}`);
         else
-            check(`storage backend '${backend.id}' configured`, true);
+            check('storage', true, `${backend.id} · configured`);
     }
     catch (err) {
-        check(`storage backend '${backendId}' configured`, false, err.message);
+        check('storage', false, `${backendId} · ${err.message}`);
     }
-    // Managed Turbo/Arweave key — if it exists, it holds prepaid credits, so remind them to back it up.
+    // 3. Optional — path-dependent setup. Unset is fine; these say WHEN you'll need each, so an unset
+    //    value never reads as a warning.
+    console.log(`\n  ${dim('Optional — depends how you deploy:')}`);
+    if (signingOpt)
+        opt('signing', signingOpt);
+    else
+        opt('signing', 'no env key → sign in your browser wallet (--sign). Preflight yours: `abx doctor --for 0x<addr>`. Set ABX_DEPLOYER_PK for the unattended hot lane.');
+    if (forOpt)
+        opt('wallet --for', forOpt);
+    const baseUrl = process.env.ABX_PUBLIC_BASE_URL;
+    if (baseUrl)
+        opt('resolver URL', baseUrl);
+    else
+        opt('resolver URL', 'ABX_PUBLIC_BASE_URL unset → needed for off-chain/resolver-served deploys; skip if fully on-chain (--onchain-image / --onchain-uri).');
     if (!process.env.ARWEAVE_JWK && existsSync(arweaveKeyFilePath())) {
         const jwk = loadArweaveJwk();
-        console.log(`  ${dim('↳ Turbo/Arweave key ' + (jwk ? arweaveAddress(jwk) + ' ' : '') + 'holds your upload credits — back it up: `abx storage backup-key --out <path>`')}`);
+        opt('arweave key', `${jwk ? arweaveAddress(jwk) + ' ' : ''}holds upload credits — back it up: \`abx storage backup-key --out <path>\``);
     }
     console.log('');
 }
@@ -4558,12 +4569,15 @@ function keepAlive() {
 // ── per-command usage (printed by `<cmd> --help` / `abx help <cmd>`; read-only) ──
 const COMMAND_HELP = {
     skill: `
-  ${bold('abx skill')} ${dim('— install the abx agent skill so your coding agent can drive abx')}
-    ${g('abx skill install')}     copy the skill into ${bold('.claude/skills/abx-self-host')} in the current project
-                          ${g('--global')}          install into your home dir (~/.claude/skills) instead of the project
-                          ${g('--target <dir>')}    install under a different base dir (writes <dir>/.claude/skills/abx-self-host)
+  ${bold('abx skill')} ${dim('— install the version-locked abx agent skill so your coding agent can drive abx')}
+    ${g('abx skill install')}     copy the bundled skill (version-locked to this CLI) into your agent(s)
+                          ${dim('default: both')} ${bold('.claude/skills')} ${dim('(Claude Code) and')} ${bold('.agents/skills')} ${dim('(Cursor · Codex · Gemini · Copilot)')}
+                          ${g('--agent <name>')}    only one agent: ${dim('claude | cursor | codex | gemini | copilot')}
+                          ${g('--global')}          install into your home dir (~) instead of the current project
+                          ${g('--target <dir>')}    install the skill folder straight under <dir> (writes <dir>/abx-self-host)
     ${g('abx skill path')}        print the absolute path to the bundled skill (for ${g('npx skills add <path>')} or manual copy)
-    ${dim('Restart your agent after installing so it picks up the skill. Cross-agent install:')} ${g('npx skills add ArtBlocks/abx')}`,
+    ${dim('Restart your agent after installing so it picks up the skill. Once the repo is public, the git-based')}
+    ${dim('cross-agent installer also works (not version-locked):')} ${g('npx skills add ArtBlocks/abx --skill abx-self-host')}`,
     deploy: `
   ${bold('abx deploy')} ${dim('— deploy + index a 1/1 (no server). Sends a tx in the chosen lane.')}
     --image <path>        custody your own image (png · jpg · gif · svg · webp); else generative demo art
@@ -5019,7 +5033,7 @@ function help() {
     ${g('abx forget')} <address>    drop a project's local registration + projection (on-chain untouched)
     ${g('abx status')}              list indexed projects + node info
     ${g('abx doctor')}              check environment (key, RPC, balance, factory, storage)
-    ${g('abx skill install')}       install the abx agent skill into your agent   [--global] [--target <dir>]  ·  ${g('abx skill path')} prints the bundled skill
+    ${g('abx skill install')}       install the version-locked abx skill into your agent(s)   [--agent <name>] [--global] [--target <dir>]  ·  ${g('abx skill path')} prints the bundled skill
     ${g('abx version')}             print the installed CLI version
 
   ${dim('Run')} ${g('abx <command> --help')} ${dim('for per-command usage. --help / -h never executes — it only prints usage.')}
@@ -5041,8 +5055,13 @@ function parseSaltFlag(raw) {
 // ── skill: install the abx agent skill into the user's coding agent ───────────────────────
 // The skill is the agentic half of the toolkit — the CLI is only useful once an agent knows how
 // to drive it. It ships bundled inside the published package (packages/cli/skill/, created at
-// prepack); in dev the same command reads the canonical copy straight from the repo. A separate
-// cross-agent channel is `npx skills add ArtBlocks/abx` (the Agent Skills standard, git-based).
+// prepack); in dev the same command reads the canonical copy straight from the repo. This is the
+// CANONICAL install path precisely because the bundle is version-locked to the CLI it ships inside
+// (the version lives in SKILL.md frontmatter — see update-check.ts). By default it writes to BOTH
+// `.claude/skills` (Claude Code) and the neutral `.agents/skills` (Cursor · Codex · Gemini ·
+// Copilot all read it), so one command covers the whole ecosystem; `--agent` narrows it. A separate
+// git-based channel, `npx skills add ArtBlocks/abx --skill abx-self-host`, works once the repo is public but is NOT
+// version-locked to a local CLI — prefer `abx skill install`.
 /** Locate the skill folder: the bundled copy beside the compiled CLI (published), else the
  *  canonical repo copy (dev). Returns null if neither is present. */
 function resolveBundledSkill() {
@@ -5106,37 +5125,71 @@ function cmdScaffoldRenderer(rest, flags) {
     console.log(`    ${g('abx deploy-code --image-renderer <MyRenderer> --attributes-renderer <MyTraits> --onchain-uri --schema palette:HexColor:TokenOwner --name "…" --symbol …')}`);
     info(`full walkthrough: ${bold(`${basename(dir)}/README.md`)} · interface + invariants: https://abx.docs.artblocks.io/protocol/renderers/`);
 }
+/** Human label for each skills-parent dir — which agents pick the skill up from there. */
+const SKILL_PARENT_LABELS = {
+    '.claude/skills': 'Claude Code',
+    '.agents/skills': 'Cursor · Codex · Gemini · Copilot',
+};
+/** Resolve which skills-parent dirs `install` should write to. No `--agent` → the whole-ecosystem
+ *  default (Claude Code + the neutral `.agents/skills` everyone else reads). `--agent a,b` narrows
+ *  to those agents' dirs (de-duped, since several share `.agents/skills`). */
+function resolveInstallParents(agentFlag) {
+    if (!agentFlag || agentFlag === 'true')
+        return ['.claude/skills', '.agents/skills'];
+    const parents = new Set();
+    for (const raw of agentFlag.split(',')) {
+        const a = raw.trim().toLowerCase();
+        const parent = AGENT_SKILL_PARENTS[a];
+        if (!parent) {
+            throw new Error(`unknown --agent '${a}'. Use one of: ${Object.keys(AGENT_SKILL_PARENTS).join(', ')} (or omit --agent to install for every agent).`);
+        }
+        parents.add(parent);
+    }
+    return [...parents];
+}
+/** Copy the bundled skill folder to `dest`, replacing any prior copy so a re-install after an
+ *  upgrade never leaves stale reference files behind. */
+function installSkillTo(src, dest) {
+    mkdirSync(joinPath(dest, '..'), { recursive: true });
+    rmSync(dest, { recursive: true, force: true });
+    cpSync(src, dest, { recursive: true });
+}
 async function cmdSkill(rest, flags) {
     const sub = rest[0] ?? 'install';
     const src = resolveBundledSkill();
     if (!src) {
         throw new Error('bundled skill not found (expected <pkg>/skill or .claude/skills/abx-self-host). ' +
-            'Reinstall @artblocks/abx-cli, or install cross-agent with: npx skills add ArtBlocks/abx');
+            'Reinstall @artblocks/abx-cli, or install cross-agent with: npx skills add ArtBlocks/abx --skill abx-self-host');
     }
     if (sub === 'path') {
         console.log(src);
         return;
     }
     if (sub === 'install') {
-        const base = flags.global !== undefined ? homedir() : flags.target ?? process.cwd();
-        const destParent = joinPath(base, '.claude', 'skills');
-        const dest = joinPath(destParent, 'abx-self-host');
-        mkdirSync(destParent, { recursive: true });
-        cpSync(src, dest, { recursive: true });
-        // Stamp the CLI version so a later run can notice the skill has drifted behind an upgraded CLI
-        // (the two are co-versioned). Best-effort — a missing marker just means "no drift nudge".
-        try {
-            writeFileSync(joinPath(dest, SKILL_VERSION_MARKER), readCliVersion());
-        }
-        catch {
-            /* non-fatal */
+        const version = readSkillVersion(joinPath(src, 'SKILL.md')) ?? readCliVersion();
+        // Escape hatch: --target <dir> writes the skill folder straight under <dir> (for an agent
+        // whose skills dir we don't special-case, or a bespoke location).
+        if (typeof flags.target === 'string' && flags.target !== 'true') {
+            const dest = joinPath(resolvePath(flags.target), SKILL_DIR_NAME);
+            installSkillTo(src, dest);
+            ok(`installed the abx skill v${version} → ${dest}`);
+            info('restart your agent so it loads the skill, then ask it to launch an NFT with abx.');
+            return;
         }
-        ok(`installed the abx skill → ${dest}`);
-        info('restart your agent (Claude Code / Cursor) so it loads the skill, then ask it to launch an NFT with abx.');
-        info('cross-agent alternative (git-based): npx skills add ArtBlocks/abx');
+        const base = flags.global !== undefined ? homedir() : process.cwd();
+        const parents = resolveInstallParents(flags.agent);
+        ok(`installed the abx skill v${version}${flags.global !== undefined ? ' (global, ~)' : ''}:`);
+        for (const parent of parents) {
+            const dest = joinPath(base, parent, SKILL_DIR_NAME);
+            installSkillTo(src, dest);
+            const label = SKILL_PARENT_LABELS[parent];
+            console.log(`    ${g(joinPath(parent, SKILL_DIR_NAME))}${label ? dim('  → ' + label) : ''}`);
+        }
+        info('restart your agent so it loads the skill, then ask it to launch an NFT with abx.');
+        info(`the skill is version-locked to this CLI (v${version}); re-run ${g('abx skill install')} after upgrading so the two stay in sync.`);
         return;
     }
-    throw new Error('usage: abx skill <install|path> [--global] [--target <dir>]');
+    throw new Error('usage: abx skill <install|path> [--agent claude|cursor|codex|gemini|copilot] [--global] [--target <dir>]');
 }
 main().catch((err) => {
     // Keep the actionable message; strip viem's verbose boilerplate trailer (Docs:/Version: lines) so