@feralfile/cli 1.2.0 → 1.3.1

package/README.md

@@ -70,6 +70,30 @@ Sources: Art Blocks, Objkt, fxhash (canonical `/gentk/...`, live `/iteration/{sl
 - **Mainstream PFPs** (Azuki, BAYC, Pudgy Penguins) build a single-item playlist instead of a series — Raster's curation is effectively the series allowlist.
 - **Indexer 502s on burst load** are intermittent ([ff-indexer-v2#82](https://github.com/feral-file/ff-indexer-v2/issues/82)) — retry clears or use `--limit N`.
 
+## Use with Claude Code
+
+ff-cli ships a [Claude Code](https://docs.claude.com/en/docs/claude-code) skill at `skills/ff-control/SKILL.md`. Install it once:
+
+```bash
+git clone --depth=1 https://github.com/feral-file/ff-cli /tmp/ff-cli \
+  && mkdir -p ~/.claude/skills \
+  && cp -r /tmp/ff-cli/skills/ff-control ~/.claude/skills/
+```
+
+Claude Code will surface it when you ask to build a playlist, play an artwork or URL on an Art Computer, or publish to a feed. The skill validates config, builds, validates the playlist, and sends or publishes — reporting the failing command + exit code if anything breaks. Full prompt and exact flow: [`skills/ff-control/SKILL.md`](./skills/ff-control/SKILL.md).
+
+## Use with Codex
+
+ff-cli ships the same `ff-control` skill in Codex's native skill format. Install it once:
+
+```bash
+git clone --depth=1 https://github.com/feral-file/ff-cli /tmp/ff-cli \
+  && mkdir -p ~/.codex/skills \
+  && cp -r /tmp/ff-cli/skills/ff-control ~/.codex/skills/
+```
+
+Codex will surface it when you ask to build a playlist, play an artwork or URL on an Art Computer, or publish to a feed. The installed skill is `skills/ff-control/SKILL.md`, so the execution flow stays defined in one place. Codex metadata and exact flow: [`skills/ff-control/agents/openai.yaml`](./skills/ff-control/agents/openai.yaml), [`skills/ff-control/SKILL.md`](./skills/ff-control/SKILL.md).
+
 ## Dev Quick Start
 
 **Set your LLM API key first (default Claude):** `export ANTHROPIC_API_KEY='sk-ant-your-api-key-here'`

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "1.2.0",
+    "version": "1.3.1",
     "description": "CLI for building DP-1 playlists of digital art using AI (Claude, Grok, ChatGPT, Gemini)",
     "repository": {
         "type": "git",

package/dist/src/commands/find.js

@@ -49,6 +49,7 @@ const objkt_marketplace_1 = require("../utilities/objkt-marketplace");
 const ab_marketplace_1 = require("../utilities/ab-marketplace");
 const fxhash_marketplace_1 = require("../utilities/fxhash-marketplace");
 const neort_marketplace_1 = require("../utilities/neort-marketplace");
+const verse_marketplace_1 = require("../utilities/verse-marketplace");
 const raster_client_1 = require("../utilities/raster-client");
 const ff1_device_1 = require("../utilities/ff1-device");
 // nft-indexer + playlist-builder are still CommonJS; require keeps interop simple.
@@ -66,7 +67,7 @@ const DP1_MAX_ITEMS = 1024;
 const RASTER_PAGE_SIZE = 100;
 exports.findCommand = new commander_1.Command('find')
     .description('Find an artwork on the web and build a DP-1 playlist')
-    .argument('<input>', 'URL (Objkt / fxhash / Art Blocks / OpenSea / SuperRare / Feral File / Neort), `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, or a wallet address')
+    .argument('<input>', 'URL (Objkt / fxhash / Art Blocks / OpenSea / SuperRare / Feral File / Neort / Verse), `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, or a wallet address')
     .option('-o, --output <path>', 'Save the playlist to this file (default: ./<slug>.json)')
     .option('-l, --limit <n>', 'Max tokens to include from the series (default: all)')
     .option('-p, --play', 'Play the playlist on an FF1 device after building')
@@ -81,7 +82,7 @@ exports.findCommand = new commander_1.Command('find')
         const parsed = (0, marketplace_url_1.parseFindInput)(input);
         if (!parsed) {
             console.error(chalk_1.default.red('Could not understand input.'));
-            console.error(chalk_1.default.dim('Supported URLs: Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort. ' +
+            console.error(chalk_1.default.dim('Supported URLs: Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort, Verse. ' +
                 'Or: `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, ' +
                 'or a wallet address (`0x...` / `tz1.../tz2.../tz3...`).'));
             process.exit(1);
@@ -190,6 +191,10 @@ async function resolveTarget(parsed, skipPrompt) {
         const coords = await (0, fxhash_marketplace_1.resolveFxhashProject)(parsed.slug);
         return resolveCoords(coords);
     }
+    if (parsed.kind === 'verse-series') {
+        const coords = await (0, verse_marketplace_1.resolveVerseSeries)(parsed.slug);
+        return resolveCoords(coords);
+    }
     if (parsed.kind === 'address') {
         const artistId = await (0, raster_client_1.resolveAddressToArtist)(parsed.address);
         if (artistId === null) {

package/dist/src/commands/helpers/config-files.js

@@ -1,24 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isMissingConfigValue = isMissingConfigValue;
+exports.isMissingConfigValue = void 0;
 exports.readConfigFile = readConfigFile;
 exports.resolveExistingConfigPath = resolveExistingConfigPath;
 exports.ensureConfigFile = ensureConfigFile;
 const fs_1 = require("fs");
 const config_1 = require("../../config");
-// Treat any value containing the YOUR_/your_ placeholder pattern as missing,
-// since createSampleConfig writes those literal placeholders into new files
-// and we should not let the user proceed with an unfilled value.
-const placeholderPattern = /YOUR_|your_/;
-/**
- * Whether a config value is unset or still holds a sample placeholder.
- */
-function isMissingConfigValue(value) {
-    if (!value) {
-        return true;
-    }
-    return placeholderPattern.test(value);
-}
+var config_placeholders_1 = require("../../utilities/config-placeholders");
+Object.defineProperty(exports, "isMissingConfigValue", { enumerable: true, get: function () { return config_placeholders_1.isMissingConfigValue; } });
 /**
  * Read and parse a config.json file at the given path.
  */

package/dist/src/commands/setup.js

@@ -14,6 +14,7 @@ const config_1 = require("../config");
 const config_files_1 = require("./helpers/config-files");
 const device_discovery_1 = require("./helpers/device-discovery");
 const prompt_1 = require("./helpers/prompt");
+const config_placeholders_1 = require("../utilities/config-placeholders");
 const playlist_signing_role_1 = require("../utilities/playlist-signing-role");
 exports.setupCommand = new commander_1.Command('setup')
     .description('Guided setup for config, signing key, and device')
@@ -139,7 +140,12 @@ exports.setupCommand = new commander_1.Command('setup')
                 role: signingRole,
             };
         }
-        const existingDevices = config.ff1Devices?.devices || [];
+        const configuredDevices = (0, config_placeholders_1.configuredFF1Devices)(config.ff1Devices?.devices || []);
+        const existingDevices = configuredDevices;
+        // Drop bundled example rows before discovery. Otherwise setup sees the
+        // sample placeholder as an existing device and lets users skip the device
+        // prompt without ever configuring a usable FF1 host.
+        config.ff1Devices = { devices: configuredDevices };
         if (existingDevices.length > 0) {
             console.log(chalk_1.default.dim(`\nConfigured devices: ${existingDevices.map((d) => d.name || d.host).join(', ')}`));
         }
@@ -198,7 +204,7 @@ exports.setupCommand = new commander_1.Command('setup')
         console.log(chalk_1.default.dim(`   Config: ${configPath}`));
         const hasApiKey = !(0, config_files_1.isMissingConfigValue)(config.models[selectedModel]?.apiKey);
         const hasSigningKey = !(0, config_files_1.isMissingConfigValue)(config.playlist?.privateKey || '');
-        const hasDevice = Boolean(config.ff1Devices?.devices?.[0]?.host);
+        const hasDevice = (0, config_placeholders_1.configuredFF1Devices)(config.ff1Devices?.devices || []).length > 0;
         if (!hasSigningKey || !hasDevice) {
             console.log(chalk_1.default.yellow('\nNext steps:'));
             if (!hasSigningKey) {

package/dist/src/commands/status.js

@@ -10,6 +10,7 @@ const config_files_1 = require("./helpers/config-files");
 const config_1 = require("../config");
 const ed25519_key_derive_1 = require("../utilities/ed25519-key-derive");
 const playlist_signing_role_1 = require("../utilities/playlist-signing-role");
+const config_placeholders_1 = require("../utilities/config-placeholders");
 exports.statusCommand = new commander_1.Command('status')
     .description('Show configuration status')
     .action(async () => {
@@ -32,6 +33,7 @@ exports.statusCommand = new commander_1.Command('status')
         const playlistKeyMaterial = playlistConfig.privateKey?.trim() || '';
         const playlistKeyError = playlistKeyMaterial.length > 0 ? validatePlaylistPrivateKey(playlistKeyMaterial) : null;
         const hasPlaylistSigningKey = playlistKeyMaterial.length > 0 && playlistKeyError === null;
+        const configuredDevices = (0, config_placeholders_1.configuredFF1Devices)(config.ff1Devices?.devices || []);
         let hasValidPlaylistRole = false;
         let playlistRoleDetail;
         let playlistRoleError;
@@ -75,12 +77,10 @@ exports.statusCommand = new commander_1.Command('status')
                 hint: ' (used when signing playlists)',
             },
             {
-                label: `FF1 devices (${config.ff1Devices?.devices?.length || 0})`,
-                ok: (config.ff1Devices?.devices?.length || 0) > 0 &&
-                    (config.ff1Devices?.devices || []).every((d) => !(0, config_files_1.isMissingConfigValue)(d.host)),
-                detail: (config.ff1Devices?.devices || [])
-                    .map((d) => `${d.name || 'unnamed'} → ${d.host}`)
-                    .join(', ') || undefined,
+                label: `FF1 devices (${configuredDevices.length})`,
+                ok: configuredDevices.length > 0,
+                detail: configuredDevices.map((d) => `${d.name || 'unnamed'} → ${d.host}`).join(', ') ||
+                    undefined,
             },
         ];
         console.log(chalk_1.default.blue('\n🔎 FF1 Status\n'));

package/dist/src/config.js

@@ -18,6 +18,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const playlist_signing_role_1 = require("./utilities/playlist-signing-role");
+const config_placeholders_1 = require("./utilities/config-placeholders");
 // One-shot legacy config migration: copy `$XDG_CONFIG_HOME/ff1/config.json` to
 // `$XDG_CONFIG_HOME/ff-cli/config.json` on first read after upgrading from
 // `ff1-cli`. The check is cheap (two fs.existsSync calls) and the
@@ -285,7 +286,7 @@ function getFF1DeviceConfig() {
     const config = getConfig();
     const ff1Devices = config.ff1Devices || { devices: [] };
     return {
-        devices: ff1Devices.devices || [],
+        devices: (0, config_placeholders_1.configuredFF1Devices)(ff1Devices.devices || []),
     };
 }
 /**
@@ -338,7 +339,7 @@ function validateConfig(modelName) {
             return { valid: false, errors };
         }
         const modelConfig = config.models[selectedModel];
-        if (!modelConfig.apiKey || modelConfig.apiKey === 'your_api_key_here') {
+        if ((0, config_placeholders_1.isMissingConfigValue)(modelConfig.apiKey)) {
             errors.push(`API key for "${selectedModel}" is missing or not configured`);
         }
         if (!modelConfig.baseURL) {

package/dist/src/utilities/config-placeholders.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMissingConfigValue = isMissingConfigValue;
+exports.configuredFF1Devices = configuredFF1Devices;
+/**
+ * configPlaceholders identifies values copied from config.json.example.
+ *
+ * The sample file is useful for manual editing, but runtime flows must treat
+ * those literal placeholders as unset so setup cannot mistake example rows for
+ * configured devices.
+ */
+const CONFIG_PLACEHOLDER_PATTERN = /YOUR_|your_/;
+/**
+ * isMissingConfigValue reports whether a config string is empty or still a
+ * sample placeholder.
+ *
+ * @param {string | null | undefined} value - Config value to inspect.
+ * @returns {boolean} True when the value should be treated as unset.
+ */
+function isMissingConfigValue(value) {
+    if (!value) {
+        return true;
+    }
+    return CONFIG_PLACEHOLDER_PATTERN.test(value);
+}
+/**
+ * configuredFF1Devices returns only device rows with a real host.
+ *
+ * @param {T[]} devices - Device rows from config.json.
+ * @returns {T[]} Rows that can be used for FF1 network operations.
+ */
+function configuredFF1Devices(devices = []) {
+    return devices.filter((device) => !isMissingConfigValue(device.host));
+}

package/dist/src/utilities/marketplace-url.js

@@ -3,7 +3,7 @@
  * Marketplace URL parser for `ff-cli find`.
  *
  * Accepts user input in any of these forms and returns a normalized result:
- *  - Marketplace token URL (Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort)
+ *  - Marketplace token URL (Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort, Verse)
  *  - Raw on-chain coordinates: "ethereum:0xabc...:123" / "tezos:KT1...:456"
  *  - Wallet address: 0x{40-hex} (Ethereum) or tz1/tz2/tz3{33} (Tezos)
  *
@@ -25,6 +25,7 @@ exports.parseFxhash = parseFxhash;
 exports.parseOpenSea = parseOpenSea;
 exports.parseSuperRare = parseSuperRare;
 exports.parseNeort = parseNeort;
+exports.parseVerse = parseVerse;
 exports.parseFeralFile = parseFeralFile;
 const ETH_ADDR = /^0x[a-fA-F0-9]{40}$/;
 const TEZOS_ADDR = /^(tz1|tz2|tz3)[1-9A-HJ-NP-Za-km-z]{33}$/;
@@ -97,6 +98,9 @@ function parseMarketplaceUrl(url) {
     if (host === 'neort.io' || host.endsWith('.neort.io')) {
         return parseNeort(url);
     }
+    if (host === 'verse.works' || host.endsWith('.verse.works')) {
+        return parseVerse(url);
+    }
     return null;
 }
 /**
@@ -337,6 +341,43 @@ function parseNeort(url) {
         reason: `Neort URL not recognized: ${url.pathname}. Expected /art/{id}.`,
     };
 }
+/**
+ * Verse URL forms:
+ *   verse.works/items/ethereum/{contract}/{tokenId}  — direct Ethereum token
+ *   verse.works/series/{slug}                        — series page
+ *
+ * Verse item pages expose the on-chain coordinates directly in the path. Series
+ * pages do not include a JSON API in the public URL, but they render edition
+ * links with the same `/items/ethereum/...` shape; the async resolver fetches
+ * the series page and extracts a representative token for Raster enumeration.
+ */
+function parseVerse(url) {
+    let m = /^\/items\/ethereum\/(0x[a-fA-F0-9]{40})\/(\d+)\/?$/.exec(url.pathname);
+    if (m) {
+        return {
+            kind: 'token',
+            source: 'verse',
+            coords: { chain: 'ethereum', contract: m[1].toLowerCase(), tokenId: m[2] },
+        };
+    }
+    m = /^\/items\/([^/]+)\//.exec(url.pathname);
+    if (m) {
+        return {
+            kind: 'unsupported',
+            reason: `Verse ${m[1]} item URLs are not supported — ff-cli covers Ethereum and Tezos mainnet only. ` +
+                'Paste an Ethereum Verse item URL or raw `ethereum:{contract}:{tokenId}` coordinates.',
+        };
+    }
+    m = /^\/series\/([A-Za-z0-9][A-Za-z0-9_-]*)\/?$/.exec(url.pathname);
+    if (m) {
+        return { kind: 'verse-series', slug: m[1] };
+    }
+    return {
+        kind: 'unsupported',
+        reason: `Verse URL not recognized: ${url.pathname}. Expected ` +
+            '/items/ethereum/{contract}/{tokenId} or /series/{slug}.',
+    };
+}
 /**
  * Feral File URL forms (source of truth: feralfile-client app-routing
  * + collection-routing modules):

package/dist/src/utilities/nft-indexer.js

@@ -318,12 +318,14 @@ function mapIndexerDataToStandardFormat(indexerData, chain) {
     const artistName = extractArtistName(display.artists);
     const name = display.name || `Token #${indexerData.token_number}`;
     const description = display.description || '';
+    const standard = detectTokenStandard(chain, indexerData.contract_address);
     return {
         success: true,
         token: {
             chain,
             contractAddress: indexerData.contract_address,
             tokenId: indexerData.token_number,
+            standard,
             name,
             description,
             image: {
@@ -440,7 +442,7 @@ function convertToDP1Item(tokenData, duration = 10) {
             type: 'onChain',
             contract: {
                 chain: chainMap[token.chain.toLowerCase()] || 'other',
-                standard: 'other',
+                standard: token.standard || detectTokenStandard(token.chain, token.contractAddress),
                 address: token.contractAddress,
                 tokenId: String(token.tokenId),
             },

package/dist/src/utilities/verse-marketplace.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVerseSeries = resolveVerseSeries;
+/**
+ * Resolve a Verse series slug to representative Ethereum token coordinates.
+ *
+ * Verse series pages render edition links as
+ * `/items/ethereum/{contract}/{tokenId}`. Using the first rendered edition
+ * keeps the resolver independent of private frontend state while still handing
+ * Raster a token it can use to enumerate the full series.
+ *
+ * @param slug - Verse series slug from `/series/{slug}`
+ * @returns Representative Ethereum token coordinates
+ * @throws Error when the page cannot be fetched or no Ethereum edition link is present
+ */
+async function resolveVerseSeries(slug) {
+    const url = `https://verse.works/series/${encodeURIComponent(slug)}`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Verse series lookup failed for ${slug}: ${response.status}`);
+    }
+    const html = await response.text();
+    const match = /\/items\/ethereum\/(0x[a-fA-F0-9]{40})\/(\d+)/.exec(html);
+    if (!match) {
+        throw new Error(`Verse series ${slug} did not expose an Ethereum edition link. ` +
+            'Paste a specific Verse item URL or raw `ethereum:{contract}:{tokenId}` coordinates.');
+    }
+    return {
+        chain: 'ethereum',
+        contract: match[1].toLowerCase(),
+        tokenId: match[2],
+    };
+}

package/docs/README.md

@@ -18,7 +18,7 @@ npm i -g @feralfile/cli
 curl -fsSL https://feralfile.com/ff-cli-install | bash
 ```
 
-Installs a prebuilt binary for macOS/Linux (no Node.js required).
+Installs a prebuilt bundle for macOS/Linux. Node.js 22 or newer must still be available in `PATH`; the bundle avoids a global npm install, not the Node runtime requirement.
 
 ## Configure
 
@@ -146,6 +146,10 @@ Notes:
   - Options: `-k, --key <privateKey>`, `-r, --role <role>`, `-o, --output <file>`
 - `play <source>` – Play a playlist file, playlist URL, or media URL on an FF1 device (runs `verify` before sending; only the CLI-synthesized media URL fallback is auto-signed when a signing key is configured; use `--skip-verify` to bypass the gate)
   - Options: `-d, --device <name>`, `--skip-verify` (skip signature verification; not recommended)
+- `find <input>` – Resolve a marketplace URL, raw `chain:contract:tokenId`, or wallet address into a playable DP-1 playlist
+  - Sources: Art Blocks, Objkt, fxhash, OpenSea, SuperRare, Feral File, Neort, Verse, raw on-chain coordinates, and wallet addresses
+  - Verse forms: `/items/ethereum/{contract}/{tokenId}` and `/series/{slug}`
+  - Options: `-o, --output <path>`, `-l, --limit <n>`, `-p, --play`, `-d, --device <name>`, `--publish`, `-s, --server <index>`, `-y, --yes`, `--skip-verify`
 - `publish <file>` – Publish a playlist to a feed server (runs `verify` before upload and rejects unsigned or broken playlists)
   - Options: `-s, --server <index>` (server index if multiple configured)
 - `ssh <enable|disable>` – Manage SSH access on an FF1 device

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "CLI for building DP-1 playlists of digital art using AI (Claude, Grok, ChatGPT, Gemini)",
   "repository": {
     "type": "git",