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

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';
@@ -4260,6 +4261,21 @@ async function cmdDoctor(flags) {
         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>`')}`);
     }
+    // Agent skill co-versioning — the skill drives this CLI and is version-locked to it (its version
+    // lives in SKILL.md frontmatter). Report any installed copy and flag drift; notify-only, so a
+    // stale/absent skill never fails doctor (`abx skill install` resyncs).
+    const cliVersion = readCliVersion();
+    const skillVersions = installedSkillVersions();
+    const staleSkills = skillVersions.filter((v) => compareVersions(cliVersion, v) > 0);
+    if (skillVersions.length === 0) {
+        console.log(`  ${dim('↳ agent skill: not installed here — `abx skill install` so a coding agent can drive abx')}`);
+    }
+    else if (staleSkills.length > 0) {
+        console.log(`  ${c.orange}⚠${c.reset} agent skill behind CLI${dim(`  installed v${staleSkills.join(', v')} · CLI v${cliVersion} — refresh: `)}${g('abx skill install')}`);
+    }
+    else {
+        check(`agent skill in sync (v${cliVersion})`, true);
+    }
     console.log('');
 }
 // ── shared output ─────────────────────────────────────────────────────────--
@@ -4558,12 +4574,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 +5038,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 +5060,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 +5130,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