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

package/dist/update-check.d.ts

@@ -0,0 +1,58 @@
+/** Read the running CLI's own version from its package.json. Resolves the same in dev
+ *  (src/update-check.ts → packages/cli/package.json) and published (dist/update-check.js →
+ *  <pkg>/package.json) — npm always ships package.json regardless of the `files` allowlist.
+ *  Returns '0.0.0' if unreadable, so callers never throw on a self-version read. */
+export declare function readCliVersion(): string;
+/**
+ * Compare two semver strings. Returns -1 if a < b, 0 if equal, 1 if a > b. Handles the
+ * prerelease rule (1.0.0-alpha < 1.0.0) since our own versions are prereleases today
+ * (0.1.0-alpha.0). Build metadata (+…) is ignored per semver. Tolerant of a leading `v`.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/** True when `latest` is a strictly newer release than `current`. */
+export declare function isNewer(latest: string, current: string): boolean;
+/** GET the `latest` dist-tag's version from the npm registry. Aborts after {@link TIMEOUT_MS};
+ *  returns null on any failure (offline, timeout, non-200, malformed body) — never throws. */
+export declare function fetchLatestVersion(pkg?: string): Promise<string | null>;
+/**
+ * Resolve the latest published version IF it is newer than `current`, else null. Reads a disk
+ * cache first and only hits the network when the cache is older than {@link TTL_MS}. On a network
+ * failure it still stamps the cache (backing off a full TTL instead of retrying every command).
+ * Swallows every error — the update check must never break or slow a real command.
+ *
+ * `now` is injectable so tests can drive TTL behavior deterministically.
+ */
+export declare function checkForCliUpdate(current: string, now?: number): Promise<string | null>;
+/** The skill's folder name — matches SKILL.md `name`, per the Agent Skills rule that a skill
+ *  directory must be named for its `name` field. */
+export declare const SKILL_DIR_NAME = "abx-self-host";
+/**
+ * Every skills PARENT directory an ABX-capable agent scans for a `SKILL.md`, keyed by agent.
+ * These are the discovery locations the agents actually read (verified against each agent's docs):
+ *   • `.claude/skills`  — Claude Code (and Copilot also reads it)
+ *   • `.agents/skills`  — the near-universal neutral dir: Cursor, Codex, Gemini, and Copilot all
+ *                         read it (Gemini/Cursor treat it as the canonical alias over their own dir)
+ * `abx skill install` writes the version-locked bundle into these; the drift check reads it back.
+ */
+export declare const AGENT_SKILL_PARENTS: Record<string, string>;
+/** Distinct skills-parent dirs to scan for a possibly-installed copy — the union of every agent's
+ *  discovery dirs (including a few per-agent aliases), so drift detection finds the skill no matter
+ *  which agent (or install route) put it there. Missing dirs are simply skipped. */
+export declare const ALL_SKILL_PARENTS: string[];
+/**
+ * Parse `metadata.version` from a `SKILL.md`'s YAML frontmatter. Dependency-free on purpose: the
+ * frontmatter is the small, controlled block between the leading `---` fences, and the version is
+ * the only `version:` key we write there. Returns null if the file is missing/unreadable or
+ * declares no version.
+ */
+export declare function readSkillVersion(skillMdPath: string): string | null;
+/**
+ * Versions of any locally-installed skill copy (project-local under CWD, and global under HOME),
+ * read from each copy's own `SKILL.md` frontmatter. The skill and CLI are co-versioned, but a
+ * separately-installed skill copy does NOT move when the CLI upgrades — this lets the notifier
+ * catch that drift. Because the version travels INSIDE `SKILL.md`, this works for every install
+ * route (bundled `abx skill install`, git-based `npx skills add`, or a manual copy) — not just
+ * the CLI's own installer.
+ */
+export declare function installedSkillVersions(): string[];
+//# sourceMappingURL=update-check.d.ts.map

package/dist/update-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../src/update-check.ts"],"names":[],"mappings":"AAqBA;;;oFAGoF;AACpF,wBAAgB,cAAc,IAAI,MAAM,CAQvC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CA+B5D;AAED,qEAAqE;AACrE,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEhE;AAiBD;8FAC8F;AAC9F,wBAAsB,kBAAkB,CAAC,GAAG,SAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAc1E;AAMD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4BzG;AAED;oDACoD;AACpD,eAAO,MAAM,cAAc,kBAAkB,CAAC;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMtD,CAAC;AAEF;;oFAEoF;AACpF,eAAO,MAAM,iBAAiB,UAO7B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUnE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CASjD"}

package/dist/update-check.js

@@ -0,0 +1,231 @@
+/**
+ * Update check — a notify-only "you're behind" nudge, extracted from main.ts so the
+ * version comparison and cache logic are unit-testable (importing main executes the CLI).
+ *
+ * Policy (owner's call): NOTIFY, never self-mutate. The CLI checks npm at most once per
+ * {@link TTL_MS} (cached to disk), prints an upgrade one-liner to STDERR (so it never
+ * corrupts machine-readable stdout an agent may be parsing), and is a hard no-op when
+ * offline, in CI, or opted out (ABX_NO_UPDATE_CHECK / --no-update-check — see main.ts).
+ * The check lives in the CLI binary, so it fires no matter which agent (Claude, Codex,
+ * Cursor, …) drives `abx` — one implementation, every agent covered.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+const REGISTRY = 'https://registry.npmjs.org';
+const PKG = '@artblocks/abx-cli';
+const TTL_MS = 24 * 60 * 60 * 1000; // check npm at most once a day
+const TIMEOUT_MS = 1500; // never hang a command on a slow/offline network
+/** Read the running CLI's own version from its package.json. Resolves the same in dev
+ *  (src/update-check.ts → packages/cli/package.json) and published (dist/update-check.js →
+ *  <pkg>/package.json) — npm always ships package.json regardless of the `files` allowlist.
+ *  Returns '0.0.0' if unreadable, so callers never throw on a self-version read. */
+export function readCliVersion() {
+    try {
+        const pkgDir = resolve(fileURLToPath(import.meta.url), '..', '..');
+        const raw = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
+        return typeof raw.version === 'string' ? raw.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/**
+ * Compare two semver strings. Returns -1 if a < b, 0 if equal, 1 if a > b. Handles the
+ * prerelease rule (1.0.0-alpha < 1.0.0) since our own versions are prereleases today
+ * (0.1.0-alpha.0). Build metadata (+…) is ignored per semver. Tolerant of a leading `v`.
+ */
+export function compareVersions(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    for (let i = 0; i < 3; i++) {
+        if (pa.main[i] !== pb.main[i])
+            return pa.main[i] < pb.main[i] ? -1 : 1;
+    }
+    // A version WITH a prerelease is lower than the same version without one.
+    if (!pa.pre.length && !pb.pre.length)
+        return 0;
+    if (!pa.pre.length)
+        return 1;
+    if (!pb.pre.length)
+        return -1;
+    const n = Math.max(pa.pre.length, pb.pre.length);
+    for (let i = 0; i < n; i++) {
+        const x = pa.pre[i];
+        const y = pb.pre[i];
+        if (x === undefined)
+            return -1; // a shorter prerelease set is smaller (1.0.0-a < 1.0.0-a.1)
+        if (y === undefined)
+            return 1;
+        const xn = /^\d+$/.test(x);
+        const yn = /^\d+$/.test(y);
+        if (xn && yn) {
+            const dx = Number(x);
+            const dy = Number(y);
+            if (dx !== dy)
+                return dx < dy ? -1 : 1;
+        }
+        else if (xn) {
+            return -1; // numeric identifiers rank below alphanumeric ones
+        }
+        else if (yn) {
+            return 1;
+        }
+        else if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+    }
+    return 0;
+}
+/** True when `latest` is a strictly newer release than `current`. */
+export function isNewer(latest, current) {
+    return compareVersions(latest, current) > 0;
+}
+function parseSemver(v) {
+    const clean = String(v).trim().replace(/^v/, '').split('+')[0];
+    const dash = clean.indexOf('-');
+    const mainStr = dash === -1 ? clean : clean.slice(0, dash);
+    const preStr = dash === -1 ? '' : clean.slice(dash + 1);
+    const parts = mainStr.split('.').map((n) => {
+        const d = Number(n);
+        return Number.isFinite(d) ? d : 0;
+    });
+    return {
+        main: [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0],
+        pre: preStr ? preStr.split('.') : [],
+    };
+}
+/** GET the `latest` dist-tag's version from the npm registry. Aborts after {@link TIMEOUT_MS};
+ *  returns null on any failure (offline, timeout, non-200, malformed body) — never throws. */
+export async function fetchLatestVersion(pkg = PKG) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    try {
+        // Scoped packages encode the '/' as %2F; the /latest endpoint returns that version's document.
+        const res = await fetch(`${REGISTRY}/${pkg.replace('/', '%2F')}/latest`, { signal: ctrl.signal });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === 'string' ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function cachePath() {
+    return join(homedir(), '.cache', 'abx', 'update-check.json');
+}
+/**
+ * Resolve the latest published version IF it is newer than `current`, else null. Reads a disk
+ * cache first and only hits the network when the cache is older than {@link TTL_MS}. On a network
+ * failure it still stamps the cache (backing off a full TTL instead of retrying every command).
+ * Swallows every error — the update check must never break or slow a real command.
+ *
+ * `now` is injectable so tests can drive TTL behavior deterministically.
+ */
+export async function checkForCliUpdate(current, now = Date.now()) {
+    let latest = null;
+    try {
+        const path = cachePath();
+        let cache = {};
+        try {
+            if (existsSync(path))
+                cache = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            cache = {};
+        }
+        const fresh = typeof cache.checkedAt === 'number' && now - cache.checkedAt < TTL_MS;
+        if (fresh) {
+            latest = typeof cache.latest === 'string' ? cache.latest : null;
+        }
+        else {
+            const fetched = await fetchLatestVersion();
+            latest = fetched ?? (typeof cache.latest === 'string' ? cache.latest : null);
+            try {
+                mkdirSync(dirname(path), { recursive: true });
+                writeFileSync(path, JSON.stringify({ checkedAt: now, latest }));
+            }
+            catch {
+                /* a read-only HOME just means we re-check next run */
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    if (!latest)
+        return null;
+    return isNewer(latest, current) ? latest : null;
+}
+/** The skill's folder name — matches SKILL.md `name`, per the Agent Skills rule that a skill
+ *  directory must be named for its `name` field. */
+export const SKILL_DIR_NAME = 'abx-self-host';
+/**
+ * Every skills PARENT directory an ABX-capable agent scans for a `SKILL.md`, keyed by agent.
+ * These are the discovery locations the agents actually read (verified against each agent's docs):
+ *   • `.claude/skills`  — Claude Code (and Copilot also reads it)
+ *   • `.agents/skills`  — the near-universal neutral dir: Cursor, Codex, Gemini, and Copilot all
+ *                         read it (Gemini/Cursor treat it as the canonical alias over their own dir)
+ * `abx skill install` writes the version-locked bundle into these; the drift check reads it back.
+ */
+export const AGENT_SKILL_PARENTS = {
+    claude: '.claude/skills',
+    cursor: '.agents/skills',
+    codex: '.agents/skills',
+    gemini: '.agents/skills',
+    copilot: '.agents/skills',
+};
+/** Distinct skills-parent dirs to scan for a possibly-installed copy — the union of every agent's
+ *  discovery dirs (including a few per-agent aliases), so drift detection finds the skill no matter
+ *  which agent (or install route) put it there. Missing dirs are simply skipped. */
+export const ALL_SKILL_PARENTS = [
+    '.claude/skills',
+    '.agents/skills',
+    '.cursor/skills',
+    '.gemini/skills',
+    '.github/skills',
+    '.copilot/skills',
+];
+/**
+ * Parse `metadata.version` from a `SKILL.md`'s YAML frontmatter. Dependency-free on purpose: the
+ * frontmatter is the small, controlled block between the leading `---` fences, and the version is
+ * the only `version:` key we write there. Returns null if the file is missing/unreadable or
+ * declares no version.
+ */
+export function readSkillVersion(skillMdPath) {
+    try {
+        const raw = readFileSync(skillMdPath, 'utf8');
+        const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
+        const front = fm ? fm[1] : '';
+        const vm = /(?:^|\n)\s*version:\s*["']?([\w.+-]+)["']?/.exec(front);
+        return vm ? vm[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Versions of any locally-installed skill copy (project-local under CWD, and global under HOME),
+ * read from each copy's own `SKILL.md` frontmatter. The skill and CLI are co-versioned, but a
+ * separately-installed skill copy does NOT move when the CLI upgrades — this lets the notifier
+ * catch that drift. Because the version travels INSIDE `SKILL.md`, this works for every install
+ * route (bundled `abx skill install`, git-based `npx skills add`, or a manual copy) — not just
+ * the CLI's own installer.
+ */
+export function installedSkillVersions() {
+    const out = new Set();
+    for (const root of [process.cwd(), homedir()]) {
+        for (const parent of ALL_SKILL_PARENTS) {
+            const v = readSkillVersion(join(root, parent, SKILL_DIR_NAME, 'SKILL.md'));
+            if (v)
+                out.add(v);
+        }
+    }
+    return [...out];
+}
+//# sourceMappingURL=update-check.js.map

package/dist/update-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.js","sourceRoot":"","sources":["../src/update-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAC,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAC,MAAM,SAAS,CAAC;AAC3E,OAAO,EAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAC,MAAM,WAAW,CAAC;AACjD,OAAO,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AACvC,OAAO,EAAC,OAAO,EAAC,MAAM,SAAS,CAAC;AAEhC,MAAM,QAAQ,GAAG,4BAA4B,CAAC;AAC9C,MAAM,GAAG,GAAG,oBAAoB,CAAC;AACjC,MAAM,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,+BAA+B;AACnE,MAAM,UAAU,GAAG,IAAI,CAAC,CAAC,iDAAiD;AAE1E;;;oFAGoF;AACpF,MAAM,UAAU,cAAc;IAC5B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACnE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAuB,CAAC;QACjG,OAAO,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,CAAS,EAAE,CAAS;IAClD,MAAM,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,CAAC;IACD,0EAA0E;IAC1E,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IAC/C,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC,CAAC;IAC9B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACjD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,CAAC,CAAC,CAAC,CAAC,4DAA4D;QAC5F,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,CAAC,CAAC;QAC9B,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC3B,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;YACb,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YACrB,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YACrB,IAAI,EAAE,KAAK,EAAE;gBAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACzC,CAAC;aAAM,IAAI,EAAE,EAAE,CAAC;YACd,OAAO,CAAC,CAAC,CAAC,CAAC,mDAAmD;QAChE,CAAC;aAAM,IAAI,EAAE,EAAE,CAAC;YACd,OAAO,CAAC,CAAC;QACX,CAAC;aAAM,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,OAAO,CAAC,MAAc,EAAE,OAAe;IACrD,OAAO,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,WAAW,CAAC,CAAS;IAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACzC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IACH,OAAO;QACL,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACnD,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE;KACrC,CAAC;AACJ,CAAC;AAED;8FAC8F;AAC9F,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAG,GAAG,GAAG;IAChD,MAAM,IAAI,GAAG,IAAI,eAAe,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,UAAU,CAAC,CAAC;IACzD,IAAI,CAAC;QACH,+FAA+F;QAC/F,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,SAAS,EAAE,EAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAC,CAAC,CAAC;QAChG,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACzB,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuB,CAAC;QACtD,OAAO,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,SAAS,SAAS;IAChB,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAe,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IAC/E,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,SAAS,EAAE,CAAC;QACzB,IAAI,KAAK,GAAiD,EAAE,CAAC;QAC7D,IAAI,CAAC;YACH,IAAI,UAAU,CAAC,IAAI,CAAC;gBAAE,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACvE,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,GAAG,EAAE,CAAC;QACb,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC;QACpF,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,GAAG,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QAClE,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,GAAG,MAAM,kBAAkB,EAAE,CAAC;YAC3C,MAAM,GAAG,OAAO,IAAI,CAAC,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC7E,IAAI,CAAC;gBACH,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAC,SAAS,EAAE,IAAI,EAAC,CAAC,CAAC;gBAC5C,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAC,CAAC,CAAC,CAAC;YAChE,CAAC;YAAC,MAAM,CAAC;gBACP,sDAAsD;YACxD,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,OAAO,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAED;oDACoD;AACpD,MAAM,CAAC,MAAM,cAAc,GAAG,eAAe,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA2B;IACzD,MAAM,EAAE,gBAAgB;IACxB,MAAM,EAAE,gBAAgB;IACxB,KAAK,EAAE,gBAAgB;IACvB,MAAM,EAAE,gBAAgB;IACxB,OAAO,EAAE,gBAAgB;CAC1B,CAAC;AAEF;;oFAEoF;AACpF,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,iBAAiB;CAClB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAC9C,MAAM,EAAE,GAAG,6BAA6B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnD,MAAM,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9B,MAAM,EAAE,GAAG,4CAA4C,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAC9C,KAAK,MAAM,MAAM,IAAI,iBAAiB,EAAE,CAAC;YACvC,MAAM,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,UAAU,CAAC,CAAC,CAAC;YAC3E,IAAI,CAAC;gBAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;AAClB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artblocks/abx-cli",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "license": "MIT",
   "description": "ABX CLI ('abx') — the agentic UX surface of the Self-Host Toolkit (Layer 3). Deploy, index, serve, and demo a self-hosted ABX project end to end. Wraps the SDK; runs a different implementation and the protocol works identically.",
   "type": "module",
@@ -38,10 +38,10 @@
   },
   "dependencies": {
     "viem": "^2.21.0",
-    "@artblocks/abx-storage": "0.1.0-alpha.0",
     "@artblocks/abx-sdk": "0.1.0-alpha.0",
     "@artblocks/abx-indexer": "0.1.0-alpha.0",
-    "@artblocks/abx-token-api": "0.1.0-alpha.0"
+    "@artblocks/abx-token-api": "0.1.0-alpha.0",
+    "@artblocks/abx-storage": "0.1.0-alpha.0"
   },
   "optionalDependencies": {
     "@artblocks/abx-effects": "0.1.0-alpha.0"

package/skill/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: abx-self-host
 description: Launch and operate a self-hosted ABX NFT end to end with the ABX CLI (`abx`) on testnet — a 1/1 (`abx deploy`), a multi-token Series from a folder of media (`abx deploy-series`), or a generative/code drop (`abx deploy-code`). Covers on-chain vs off-chain metadata, storage custody (local disk, S3/R2, IPFS, Arweave), deploy + mint (now or pre-warmed at a predicted address), rendered thumbnails and on-chain traits for code art, primary sales via the shared fixed-price minter, and owner ops (transfer, refresh, re-point URIs, royalties, lock fields, pause/unpause, supply cap, delegate minting). Use when the user wants to self-host an ABX project, take an image to an NFT on testnet, deploy a collection from a folder of images, launch generative/code art, mint or run a primary sale, refresh a listing, operate a project they launched, choose a storage backend, or stand up hosting they own.
+compatibility: Drives the abx CLI (@artblocks/abx-cli). Co-versioned with it — install/refresh with `abx skill install` so this skill matches the CLI's `abx version`. Requires Node 22.5+.
+metadata:
+  version: "0.1.0-alpha.2"
 ---
 
 # ABX Self-Host Toolkit (`abx`)
@@ -12,6 +15,7 @@ L3 agentic surface: image → live self-hosted NFT the creator owns — a **1/1*
 ## Read first (every session)
 
 - **YOU run the `abx` commands — never tell the creator to run one.** You have a shell; use it. Run `doctor`, `ls`, `--dry-run`, `tokenuri`, `state`, `refresh`, `balance`, etc. yourself and read the output — don't paste a command and wait for them to run it or copy back results. The creator's *only* hands-on step is approving in their **browser wallet** (`--sign`) or giving you a value you asked for (their address, a name). Even "next steps" after a deploy: **run the read-only ones** (`tokenuri` to prove it resolves) and **offer to run** the actions (`refresh`, `unpause`, `mint`) — don't hand over a list of commands to run. Exceptions: a genuinely interactive/again-in-their-env command (an OS login, `gcloud auth`), and the **in-chain Solidity lane's Foundry step** (`forge build/test/deploy` a renderer — `abx` never compiles/deploys Solidity; see [Code projects](#code-projects-generative--code-based-drops)) — then run it if you have the tool, else hand it over.
+- **Skill ⇄ CLI version must match.** This skill is co-versioned with the `abx` CLI. Run `abx version` and compare it to this file's frontmatter `metadata.version` (top of SKILL.md). If they differ, this skill is stale for the installed CLI — run `abx skill install` to resync, then reload the skill before continuing. (`abx` also prints a drift nudge on its own when it notices.)
 - **`abx doctor` first, always** — full preflight (Node, pnpm, RPC, signing key, storage). Fix any ✗ before deploying ([Setup](#setup--environment)). A missing public-base-url is not a "set up IPFS" signal: for tiny art go on-chain, for larger art pick an off-chain backend — see [Quick start](#quick-start).
 - **Never collect secrets in chat.** Keys, `PINATA_JWT`, S3 secrets → the project's `.env`. The Arweave/Turbo key is a CLI-managed file (`.abx-self-host/arweave-key.json`) — never paste it. Name the var/file; never take the value.
 - **Testnet only today** — every launch is on a testnet: **Base Sepolia by default** (`ABX_CHAIN` unset), with **Sepolia** also shipped (`ABX_CHAIN=sepolia`). Say "testnet"; don't imply mainnet. **Testnet IS the preview + e2e environment**: it runs the *real* wiring (renderers, generator, on-chain tokenURI assembly), so a creator should deploy there, inspect the actual result (`abx tokenuri` / the live view / `abx verify`), confirm it looks right, and only *then* go to mainnet — no separate local "preview" is as faithful as the real testnet drop, and a testnet deploy is ~free + ~minutes. **One cross-chain gotcha: on-chain library deps (`--dep p5@…`) resolve to on-chain bytes only where an Art Blocks dependency registry exists — that's Sepolia, NOT Base Sepolia.** A no-dependency script (vanilla JS/GLSL) goes fully on-chain on either; a drop that needs a registry-hosted library on-chain must target `ABX_CHAIN=sepolia` (or run the resolver lane).

package/skill/reference/hosting.md

@@ -62,7 +62,7 @@ A failed upload is the #1 place an agent goes off the rails: it invents a cause
 
 For the large/mutable default. `abx deploy-resolver --provider <fly|render|vps> --domain <meta.you.xyz>` scaffolds the artifact and prints the exact next steps, the DNS record, and the bake reminder. Providers: **fly.io** / **render** (Docker PaaS, free tier, custom domain) and a **VPS** (compose + Caddy auto-TLS). The host is **read-only** — serves + accepts admin index-control, no signing key on it (writes are signed locally), so a compromised host can at worst serve wrong bytes (the keccak catches it). Prefer **a domain you control** (move = DNS, not a tx) — but without one the scaffold now bakes the **real platform hostname** (`<app>.fly.dev` / `<app>.onrender.com`) so the resolver works out of the box (add a custom domain later). It NO LONGER bakes a dead `<app>.example` placeholder, and the resolver **refuses to serve** an `.example`/placeholder base (or a localhost base in a hosted image, `ABX_HOSTED=1`) — a loud fail beats silently serving dead image/animation links. The one sub-decision is *which provider* (ask + recommend); you scaffold, the human owns the cloud account + domain.
 
-**The artifact is fully self-contained.** `deploy-resolver` writes `deploy/<provider>/` with its OWN `Dockerfile` + `.dockerignore` + config (a production image installs the published CLI: `npm i -g --no-optional @artblocks/abx-cli`). **Run every next step from that dir.** You never supply, copy, or hand-edit a Dockerfile. **If a step seems to need a file from elsewhere (`../Dockerfile`, a `packages/` dir, the repo), STOP — that's a scaffold bug, not something to work around.** Report it; don't MacGyver it. (Local pre-publish dev sets `ABX_RESOLVER_SOURCE=1` → a build-from-source artifact instead, still self-contained; you don't set this.)
+**The artifact is fully self-contained.** `deploy-resolver` writes `deploy/<provider>/` with its OWN `Dockerfile` + `.dockerignore` + config (a production image installs the published CLI: `npm i -g --no-optional @artblocks/abx-cli`). **Run every next step from that dir.** You never supply, copy, or hand-edit a Dockerfile. **If a step seems to need a file from elsewhere (`../Dockerfile`, a `packages/` dir, the repo), STOP — that's a scaffold bug, not something to work around.** Report it; don't MacGyver it. (Local from-source/contributor dev sets `ABX_RESOLVER_SOURCE=1` → a build-from-source artifact instead, still self-contained; you don't set this.)
 
 **Never inline a secret into a command.** The generated steps **source from `.env`** (`set -a; . ../../.env; set +a` then `fly secrets set ABX_RPC_URLS="$ABX_RPC_URLS"`) — keep that shape. Never substitute a literal secret into command text; it must never appear in output or shell history.