@feralfile/cli 1.6.0 → 2.0.1

package/docs/PROJECT_SPEC.md

@@ -15,7 +15,9 @@ It is derived from the behavior and interfaces implemented in this repository as
 - Project: `ff-cli`
 - Type: Node.js CLI
 - System role: a control and integration surface for FF1 and DP-1 workflows
-- Primary purpose: turn user intent or structured parameters into valid DP-1 playlists, then validate them and optionally sign, publish, and send them through FF1 and feed paths
+- Primary purpose: turn resolved sources or structured parameters into valid DP-1 playlists deterministically, then validate them and optionally sign, publish, and play them through FF1 and feed paths
+
+There is no built-in natural-language interface and no model orchestration. Natural language belongs in the user's coding agent (Claude Code, Codex), which drives ff-cli's deterministic commands via the `ff-control` skill. ff-cli requires no LLM API key.
 
 In the Feral File architecture bands, `ff-cli` sits primarily in the presentation and control layer. It is not the canonical source of truth for exhibitions, ownership, device runtime, or protocol evolution. It is a practical operator and developer surface that bridges those systems.
 
@@ -28,7 +30,7 @@ Its value is reducing friction in the publish-to-play path:
 - assemble playlists quickly
 - keep outputs DP-1 conformant
 - make FF1 playback and feed publishing easier to exercise
-- provide deterministic tooling around model-assisted workflows
+- provide deterministic tooling that agents and scripts can drive reliably
 
 The CLI should strengthen the Gold Path, not invent a parallel product model.
 
@@ -44,11 +46,11 @@ Current likely users:
 Primary use cases:
 
 - build a playlist from structured JSON inputs
-- build a playlist from natural-language prompts using model orchestration plus deterministic tools
+- resolve a marketplace URL, on-chain coordinates, or a wallet address into a playlist (`find`)
 - validate or verify a local or hosted DP-1 playlist
 - sign a playlist with an Ed25519 key
 - publish a validated playlist to a configured feed server
-- send a playlist or direct media URL to a configured FF1 device
+- play a playlist or direct media URL on a configured FF1 device
 - manage local config and FF1 SSH access
 - exercise compatibility checks against FF1 OS versions before risky commands
 
@@ -100,9 +102,9 @@ Long-term interoperability should continue to reduce hard infrastructure couplin
 Based on the code today, the CLI is responsible for:
 
 - loading configuration from `config.json`, `.env`, and defaults, with `config.json` taking precedence
-- parsing natural-language requests into structured playlist requirements and settings
-- orchestrating tool calls for feed fetches, address queries, contract-based NFT queries, domain resolution, playlist building, verification, publishing, and sending
-- supporting a deterministic non-AI build path from structured JSON
+- resolving marketplace URLs, on-chain coordinates, and wallet addresses into playlists (`find`)
+- running feed fetches, address queries, contract-based NFT queries, domain resolution, playlist building, verification, publishing, and playback
+- supporting a deterministic build path from structured JSON (`build`)
 - building DP-1 playlist envelopes from NFT metadata or direct media URLs
 - validating and verifying playlist structure and signatures
 - signing playlists when a private key is configured
@@ -116,7 +118,7 @@ Based on the code today, the CLI is responsible for:
 
 - command-line UX and command routing
 - local config loading and validation
-- intent parsing and orchestration glue
+- source resolution (`find`) and structured-params handling (`build`)
 - deterministic playlist assembly, verification, and signing helpers
 - device and feed integration calls from the client side
 
@@ -132,8 +134,8 @@ Based on the code today, the CLI is responsible for:
 
 - The CLI may assemble, validate, and transmit DP-1 objects, but it should not silently fork the protocol.
 - The CLI may call feed and device endpoints, but it should not become their compatibility abstraction layer of last resort.
-- The CLI may use models for orchestration, but deterministic utilities remain the source of truth for output correctness.
-- Trust-sensitive correctness must stay vendor-neutral and portable. The CLI can use cloud APIs for model orchestration, but the trust path cannot depend on cloud-specific guarantees.
+- Deterministic utilities remain the source of truth for output correctness; the CLI does not interpret natural language or orchestrate models.
+- Trust-sensitive correctness must stay vendor-neutral and portable; the trust path cannot depend on cloud-specific guarantees.
 - Current implementation note: some retrieval paths still use Feral File-operated services directly, so portability here is an intended direction rather than a fully achieved property.
 
 ## Functional shape
@@ -146,9 +148,9 @@ Today the CLI groups into these workflow areas:
 - `status`
 - `config init|show|validate`
 
-### Build and orchestration
+### Build
 
-- `chat`
+- `find`
 - `build`
 
 ### DP-1 output integrity
@@ -168,11 +170,11 @@ Today the CLI groups into these workflow areas:
 
 ## Deterministic-first behavior
 
-The CLI supports model-assisted workflows, but the implementation posture should remain deterministic-first:
+The CLI is deterministic end to end. There is no natural-language interface; any natural-language layer lives in the user's coding agent, which drives these commands:
 
-- models interpret intent
-- utilities perform the real data fetching, playlist building, validation, signing, and delivery work
-- invalid or malformed outputs should fail validation rather than being accepted because they were model-produced
+- commands map directly to source resolution, data fetching, playlist building, validation, signing, and delivery
+- utilities perform the real work and are the source of truth for output correctness
+- invalid or malformed outputs fail validation rather than being passed through
 
 ## Trust, protocol, and rights assumptions
 
@@ -216,8 +218,8 @@ The current repo verification path is:
 npm run lint:fix
 npm test
 npm run build
-ANTHROPIC_API_KEY=dummy node dist/index.js validate examples/sample-playlist.json
-ANTHROPIC_API_KEY=dummy node dist/index.js config validate
+node dist/index.js validate examples/sample-playlist.json
+node dist/index.js config validate
 ```
 
 ## Open questions

package/docs/README.md

@@ -1,6 +1,6 @@
 # ff-cli Documentation
 
-Build DP-1 (Display Protocol 1) playlists from NFT data with either natural language (AI‑driven) or deterministic parameters. This doc covers install, config, and day‑to‑day usage.
+ff-cli is a set of deterministic commands for building DP-1 (Display Protocol 1) playlists and playing them on an Art Computer. There's no built-in chat — natural language belongs in your coding agent (Claude Code, Codex), which drives ff-cli through the `ff-control` skill. No LLM API key required. This doc covers install, config, and day‑to‑day usage.
 
 For project-level planning and future agentic work, see `./PROJECT_SPEC.md`.
 
@@ -42,33 +42,6 @@ ff-cli config validate
 
 ```json
 {
-  "defaultModel": "claude",
-  "models": {
-    "claude": {
-      "apiKey": "sk-ant-your-api-key-here",
-      "baseURL": "https://api.anthropic.com/v1/",
-      "model": "claude-sonnet-4-6",
-      "supportsFunctionCalling": true
-    },
-    "grok": {
-      "apiKey": "xai-your-api-key-here",
-      "baseURL": "https://api.x.ai/v1",
-      "model": "grok-beta",
-      "supportsFunctionCalling": true
-    },
-    "gpt": {
-      "apiKey": "sk-your-openai-key-here",
-      "baseURL": "https://api.openai.com/v1",
-      "model": "gpt-4o",
-      "supportsFunctionCalling": true
-    },
-    "gemini": {
-      "apiKey": "your-gemini-key-here",
-      "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai/",
-      "model": "gemini-2.5-flash",
-      "supportsFunctionCalling": true
-    }
-  },
   "defaultDuration": 10,
   "playlist": {
     "privateKey": "your_ed25519_private_key_hex_or_base64_here"
@@ -92,13 +65,13 @@ See `./CONFIGURATION.md` for environment variable mappings.
 ## Quick Start
 
 ```bash
-# Chat
-ff-cli chat
+# Resolve a URL, on-chain coords, or wallet and build a playlist
+ff-cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak -o playlist.json
 
-# Or natural language in one shot
-ff-cli chat "Get 3 works from reas.eth" -o playlist.json
+# Build and play it on your FF1 in one step
+ff-cli find https://objkt.com/tokens/hicetnunc/111068 --play
 
-# Deterministic (no AI)
+# Build from pre-structured params (JSON file or stdin)
 ff-cli build examples/params-example.json -o playlist.json
 ```
 
@@ -106,38 +79,26 @@ For development in this repo:
 
 ```bash
 npm run build
-node dist/index.js chat
+node dist/index.js find https://objkt.com/tokens/hicetnunc/111068 --play
 ```
 
 If you're running from source without a build, use:
 
 ```bash
-npm run dev -- chat
+npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --play
 ```
 
-## Recommended Deterministic Flow (LLM + Tools)
-
-The model orchestrates; deterministic tools keep us honest and DP1‑conformant.
+## Two ways to build a playlist
 
-1. Input: Share the essentials (contract + token IDs, or feed/URL names).
-2. Orchestration: The LLM parses your prompt and calls tools that:
-   - Fetch NFT metadata via OSS libs (`viem` for Ethereum, `@taquito/taquito` for Tezos)
-   - Validate DP1 schema with `dp1-js`
-   - Build a DP1 playlist envelope deterministically
-   - Optionally sign with Ed25519 (canonical JSON via `dp1-js`)
-3. Preview/send: Send to an FF1 on your LAN over HTTP (recommended). Point `ff1Devices.devices[].host` at a local relay if needed.
-4. Publish: Optional feed/registry publishing via the `publish` command.
+ff-cli is deterministic: no chat, no model orchestration. There are two entry points for assembling a playlist.
 
-Notes:
+1. **`ff-cli find "<input>"`** — resolve a marketplace URL, raw `chain:contract:tokenId`, or wallet address into a playable DP-1 playlist. Add `--play` to build and play in one step. This is the fastest path for a single artwork, a collection/series, or a wallet.
+2. **`ff-cli build <params.json>`** — build from pre-structured `requirements` and `playlistSettings` (JSON file or stdin). Use this when you already have the contract, token IDs, feed names, or artwork ids and want explicit control over ordering, durations, and title.
 
-- **Deterministic by design**: Validation rejects bad or hallucinated data; we loop until it's valid or stop.
-- **OSS‑first**: `viem` and `@taquito/taquito`, with room for local caching.
-- **Relay**: Swap the example host for a local Node/Hono relay; avoid vendor lock‑in.
+Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1 envelope, and validate it. Validation rejects malformed data rather than passing it through. Natural language lives in your coding agent (Claude Code, Codex) via the `ff-control` skill, which translates a request into one of these two commands.
 
 ## Commands (cheat sheet)
 
-- `chat [content]` – AI-driven natural language playlists
-  - Options: `-o, --output <file>`, `-m, --model <name>`, `-d, --device <name>`, `-v, --verbose`
 - `build [params.json]` – Deterministic build from JSON or stdin
   - Options: `-o, --output <file>`, `-v, --verbose`
 - `validate <file-or-url>` – Validate playlist structure only
@@ -164,76 +125,63 @@ Notes:
 
 ## Usage Highlights
 
-### Natural language (AI)
+### Find an artwork
 
-```bash
-npm run dev -- chat "Get 3 works from reas.eth"
-npm run dev -- chat "Get 3 works from einstein-rosen.tez"
-npm run dev -- chat "Get tokens 52932,52457 from Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0" -o playlist.json
-```
-
-Feed playlists (for example `Unsupervised`, `Social Codes`) depend on your configured feed servers and network reachability.
-Use exact or near-exact playlist titles for best results.
-
-If you prompt with a bare EVM address (for example `from 0x...`), the CLI now tries owner-address lookup first, then automatically falls back to contract lookup when no owned tokens are found.
-
-### One-shot complex prompt
-
-The model reads your request via the intent parser and turns it into structured `requirements` and `playlistSettings` (including shuffle, durations, and device). You can do everything in one line:
+`ff-cli find` resolves a URL, raw `chain:contract:tokenId`, or wallet address into a playable DP-1 playlist.
 
 ```bash
-# Mix sources, shuffle order, set per-item duration, and send to a named device
-npm run dev -- chat "From Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 get tokens 52932,52457 and from reas.eth get 2 works; shuffle the order; 7 seconds per item; send to device 'Living Room Display'." -o playlist.json -v
-```
+# Paste a URL and play it on your FF1
+ff-cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --play
 
-How it works (at a glance):
+# Tezos / hic et nunc via Objkt (the alias resolves to a KT1 contract)
+ff-cli find https://objkt.com/tokens/hicetnunc/111068 --play
 
-- The intent parser maps your text to `requirements` (what to fetch) and `playlistSettings` (e.g., `durationPerItem`, `preserveOrder=false` for shuffle, `deviceName`, `feedServer`).
-- Deterministic tools fetch NFT metadata, build a DP‑1 playlist, and verify it.
-- If `deviceName` is present, the CLI will send the verified playlist to that FF1 device.
-- If `feedServer` is present (via "publish to my feed"), the CLI will publish the playlist to the selected feed server.
+# Save without playing
+ff-cli find ethereum:0xababababab20053426ad1c782de9ea8444358070:5001410 -o send-receive.json
 
-Use `--model claude|grok|gpt|gemini` to switch models, or set `defaultModel` in `config.json`.
+# Wallet address (owner lookup); cap the number of tokens with --limit
+ff-cli find 0xaeE022552B539dB18297D7481b6D547C622488B3 -l 10 -o wallet.json
 
-### Natural language publishing
-
-The intent parser recognizes publishing keywords and can both display and publish in one command:
-
-```bash
-# Build and publish
-npm run dev -- chat "Build playlist from Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 with tokens 52932 and 52457; publish to my feed" -o playlist.json -v
-
-# Display on Art Computer AND publish to feed
-npm run dev -- chat "Get 3 from Unsupervised; shuffle; send to my Art Computer and publish to feed" -o playlist.json -v
+# Build and publish to a configured feed server
+ff-cli find https://objkt.com/tokens/hicetnunc/111068 --publish
 ```
 
-For Feral File built playlists, you can reference titles listed in the repository:
-`https://github.com/feral-file/dp1-feed/tree/main/playlists`
+Sources: Art Blocks, Objkt, fxhash, OpenSea, SuperRare, Feral File, Neort, Verse, raw on-chain coordinates, and wallet addresses. Run `ff-cli find --help` for the full input list.
 
-Example:
+### Build from structured params
 
 ```bash
-npm run dev -- chat "Get 3 from Unsupervised"
+ff-cli build params.json -o playlist.json
+cat params.json | ff-cli build -o playlist.json
 ```
 
-Publishing keywords: "publish", "publish to my feed", "push to feed", "send to feed". The CLI will:
+`params.json` should include `requirements` and optional `playlistSettings`. See `examples/params-example.json`. Each requirement has a `type`:
 
-1. Detect the keyword and call `get_feed_servers`
-2. If multiple servers → ask which one to use
-3. Build → verify → publish automatically
-4. Display playlist ID and server URL on success
+- `build_playlist` — `blockchain`, `contractAddress`, `tokenIds`, optional `quantity`
+- `feral_file_artwork` — `artworkId` (a Feral File public artwork id or `/exhibitions/artwork/{id}` URL)
+- `query_address` — `ownerAddress`, optional `quantity` (random selection)
+- `fetch_feed` — `playlistName`, `quantity`
 
-If all configured feed servers are unreachable, the CLI now reports a feed availability error instead of "playlist not found".
+`playlistSettings` may set `title`, `durationPerItem`, `preserveOrder` (set `false` to shuffle), and `deviceName`. Feed playlists (for example `Unsupervised`, `Social Codes`) depend on your configured feed servers and network reachability; use exact or near-exact playlist titles for best results.
 
-### Deterministic (no AI)
-
-```bash
-npm run dev -- build params.json -o playlist.json
-cat params.json | npm run dev -- build -o playlist.json
+```json
+{
+  "requirements": [
+    {
+      "type": "build_playlist",
+      "blockchain": "ethereum",
+      "contractAddress": "0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0",
+      "tokenIds": ["52932", "52457"]
+    }
+  ],
+  "playlistSettings": {
+    "title": "My Mix",
+    "preserveOrder": false,
+    "durationPerItem": 7
+  }
+}
 ```
 
-`params.json` should include `requirements` and optional `playlistSettings`. See `examples/params-example.json`.
-
 ### Validate, sign, and play
 
 ```bash
@@ -348,7 +296,6 @@ Setup preserves existing devices when adding new ones. See selection rules and e
 
 ## Links
 
-- Function calling details: `./FUNCTION_CALLING.md`
 - Examples: `./EXAMPLES.md`
 - Release assets: `./RELEASING.md`
 - DP1 spec: `https://github.com/display-protocol/dp1`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@feralfile/cli",
-  "version": "1.6.0",
-  "description": "CLI for building DP-1 playlists of digital art using AI (Claude, Grok, ChatGPT, Gemini)",
+  "version": "2.0.1",
+  "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/feral-file/ff-cli.git"
@@ -51,7 +51,7 @@
     "nft",
     "playlist",
     "dp1",
-    "grok",
+    "feralfile",
     "cli"
   ],
   "author": "",
@@ -65,7 +65,6 @@
     "dp1-js": "2.0.0",
     "ff1": "^1.0.0",
     "fuzzysort": "^3.1.0",
-    "openai": "^4.58.1",
     "viem": "^2.38.2"
   },
   "devDependencies": {