@feralfile/cli 1.1.4 → 1.3.0

package/docs/EXAMPLES.md

@@ -70,12 +70,35 @@ npm run dev -- build examples/params-example.json -o playlist.json
 cat examples/params-example.json | npm run dev -- build -o playlist.json
 ```
 
+Build from a Feral File public artwork id or artwork URL:
+
+```bash
+cat > /tmp/ff-artwork.json <<'JSON'
+{
+  "requirements": [
+    {
+      "type": "feral_file_artwork",
+      "artworkId": "https://feralfile.com/exhibitions/artwork/f0240e04d64717e319584957f6a83954b029254ad1260b6320472ea8c0c5b1cf"
+    }
+  ],
+  "playlistSettings": {
+    "title": "Feral File Artwork"
+  }
+}
+JSON
+
+npm run dev -- build /tmp/ff-artwork.json -o playlist.json
+```
+
 ## AI‑Orchestrated Deterministic Flow (prompts)
 
 ```bash
 # Show tool‑call progress and validation
 npm run dev -- chat "Build a playlist of my works from reas.eth plus 3 from Unsupervised" -v -o playlist.json
 
+# Build from a Feral File artwork URL
+npm run dev -- chat "Build a playlist from https://feralfile.com/exhibitions/artwork/f0240e04d64717e319584957f6a83954b029254ad1260b6320472ea8c0c5b1cf" -v -o playlist.json
+
 # Switch model if desired
 npm run dev -- chat "Build playlist from Ethereum address 0xaeE022552B539dB18297D7481b6D547C622488B3 and 2 from Unsupervised" --model gpt -v
 ```

package/docs/FUNCTION_CALLING.md

@@ -24,8 +24,9 @@ Key files:
 Defined in `src/ai-orchestrator/index.js` as tool schemas for OpenAI‑compatible clients.
 
 - `query_requirement(requirement, duration)`
-  - Types: `build_playlist`, `fetch_feed`, `query_address`
+  - Types: `build_playlist`, `feral_file_artwork`, `fetch_feed`, `query_address`
   - For `build_playlist`: requires `blockchain`, `contractAddress`, `tokenIds`, optional `quantity`
+  - For `feral_file_artwork`: requires `artworkId`, either a Feral File public artwork id or `/exhibitions/artwork/{id}` URL
   - For `query_address`: requires `ownerAddress`, optional `quantity` (random selection)
   - For `fetch_feed`: requires `playlistName`, `quantity`
 
@@ -65,6 +66,7 @@ Two options are available:
 {
   "requirements": [
     { "type": "fetch_feed", "playlistName": "Social Codes", "quantity": 3 },
+    { "type": "feral_file_artwork", "artworkId": "https://feralfile.com/exhibitions/artwork/..." },
     {
       "type": "build_playlist",
       "blockchain": "ethereum",

package/docs/README.md

@@ -144,9 +144,9 @@ Notes:
 - `verify <file-or-url>` – Validate structure and verify signatures. On failure, the CLI labels structure issues separately from signature verification. dp1-js uses `--public-key` (or a key derived from `playlist.privateKey` / `PLAYLIST_PRIVATE_KEY` when omitted) **only** for legacy flat `signature` verification; DP-1 v1.1.0 `signatures[]` envelopes are verified without relying on that argument. If deriving or normalizing key material fails, the CLI prints a warning on stderr and continues without it (legacy verification still requires a usable key when the playlist uses a flat `signature`). The derived key is emitted as PEM. Supported key forms: hex with optional `0x`, PEM, or 32-byte raw public key as hex or base64
 - `sign <file>` – Sign playlist with a DP-1 v1.1.0 multi-signature envelope (private key string is forwarded to **`dp1-js`**; same hex or base64 PKCS#8 DER forms as `playlist.privateKey` in `./CONFIGURATION.md`). The command verifies the final envelope before writing output and refuses to persist tampered or otherwise unverifiable `signatures[]`.
   - 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 `validate`-style structure checks before sending; use `verify` for signatures)
-  - Options: `-d, --device <name>`, `--skip-verify` (skip structure validation; not recommended)
-- `publish <file>` – Publish a playlist to a feed server (`validate`-style structure checks before upload; use `verify` for signatures)
+- `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)
+- `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
   - Options: `-d, --device <name>`, `--pubkey <path>`, `--ttl <duration>`
@@ -184,8 +184,8 @@ npm run dev -- chat "From Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f7
 How it works (at a glance):
 
 - 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 validate it.
-- If `deviceName` is present, the CLI will send the validated playlist to that FF1 device.
+- 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.
 
 Use `--model claude|grok|gpt|gemini` to switch models, or set `defaultModel` in `config.json`.
@@ -215,7 +215,7 @@ Publishing keywords: "publish", "publish to my feed", "push to feed", "send to f
 
 1. Detect the keyword and call `get_feed_servers`
 2. If multiple servers → ask which one to use
-3. Build → validate (structure) → publish automatically
+3. Build → verify → publish automatically
 4. Display playlist ID and server URL on success
 
 If all configured feed servers are unreachable, the CLI now reports a feed availability error instead of "playlist not found".
@@ -238,7 +238,7 @@ npm run dev -- validate playlist.json
 # Sign (uses key and role from config, or overrides via --key / --role)
 npm run dev -- sign playlist.json -o signed.json
 
-# Play on configured default device (validates DP-1 structure by default)
+# Play on configured default device (verifies playlists; only media URL fallbacks may be auto-signed)
 npm run dev -- play playlist.json
 
 # Play on a specific named device
@@ -256,7 +256,7 @@ npm run dev -- play "https://cdn.example.com/playlist.json"
 # Play a media URL directly
 npm run dev -- play "https://example.com/video.mp4"
 
-# Skip structure validation only if you must send a non-conformant payload (not recommended)
+# Skip signature verification only if you must send a non-conformant payload (not recommended)
 npm run dev -- play playlist.json --skip-verify
 ```
 
@@ -285,9 +285,10 @@ npm run dev -- publish playlist.json -s 1
 
 The `publish` command:
 
-- Validates playlist structure (same as `validate`; does not verify signatures)
+- Verifies playlist signatures before upload
+- Rejects unsigned or broken playlists
 - Shows interactive server selection if multiple are configured
-- Sends the validated playlist to the chosen feed server
+- Sends the verified playlist to the chosen feed server
 - Returns the playlist ID on success
 
 Configure feed servers in `config.json`:

package/docs/RELEASING.md

@@ -1,8 +1,57 @@
-# Releasing Binary Assets
+# Releasing ff-cli
 
-The curl installer downloads prebuilt binaries from GitHub Releases. Build one asset per OS/arch and upload both the archive and its `.sha256` checksum.
+How releases happen, how to cut one, and what to do when things go sideways.
 
-## Build a Release Asset (local)
+## Cut a release (day-to-day)
+
+1. **Bump `package.json` version** on `main` (or via a `chore: bump version to X.Y.Z` PR — the project has used both patterns).
+2. **Push to `main`** so the tag created in step 3 points at the bump commit.
+3. **Create a GitHub Release** with the tag equal to the version (e.g. tag `1.2.0` → `"version": "1.2.0"`). Use `gh release create 1.2.0 --title "v1.2.0" --notes "..."` or the web UI.
+4. **The `release.yml` workflow fires automatically**, verifies tag == `package.json` version, runs CI, publishes to npm via OIDC, builds binary assets, uploads them to the release, and verifies the package landed on npm.
+
+That's it. No tokens, no manual `npm publish`. The whole thing takes ~4 minutes end-to-end.
+
+### Beta releases
+
+For pre-release versions (e.g. `1.2.0-beta.0`):
+
+- Mark the GitHub Release as a **pre-release**, and the version string in `package.json` must contain `beta`. Publishes go to the `beta` dist-tag.
+- Or use **workflow dispatch** (Actions → Release → Run workflow) from `main` with a `version` input that contains `beta` and matches `package.json`.
+
+## How publishing actually works
+
+The `publish-npm` job in `release.yml` authenticates to npm via **GitHub Actions OIDC** (npm Trusted Publishing). Key pieces:
+
+| Piece | Why |
+|---|---|
+| `permissions: id-token: write` on the job | Lets GitHub Actions mint an OIDC token at runtime. |
+| `node-version: '24'` (only this job) | Node 22's bundled npm 10.x doesn't support OIDC publishing. Node 24 ships with npm 11.x. The package's `engines: node >=22` floor for consumers is unrelated. |
+| `npm publish --provenance` | Generates a SLSA provenance attestation signed via sigstore, then submits the package + attestation to npm. |
+| `package.json` `"repository": { "url": "git+https://github.com/feral-file/ff-cli.git" }` | npm cross-checks this against the provenance ("built from feral-file/ff-cli") and rejects the publish if it doesn't match. |
+| **No `NPM_TOKEN` secret** | OIDC replaces the token entirely. The old secret is deleted; do not re-add. |
+
+The trust relationship lives at https://www.npmjs.com/package/@feralfile/cli/access — publisher: GitHub Actions, org `feral-file`, repo `ff-cli`, workflow `release.yml`. Changing the workflow filename, repo, or org will break publishes until the trust config is updated.
+
+## Bootstrapping a brand-new npm package
+
+You will probably never do this again for `@feralfile/cli`, but if you ever publish a new scoped package (`@feralfile/something-else`), the chicken-and-egg sequence is:
+
+1. **First publish must come from a logged-in human** (npm Trusted Publishing can only be configured against an existing package). Run `npm publish --access public` locally as a user with publish rights to the org. If your account has 2FA, pass `--otp 123456` inline — the browser auth flow needs a real TTY that `gh`/Claude/CI doesn't provide.
+2. **Configure the trusted publisher** at `https://www.npmjs.com/package/<name>/access` once the package exists. Fields: Publisher = GitHub Actions, Organization = `feral-file`, Repository = `<repo>`, Workflow filename = `release.yml`.
+3. **Confirm `package.json` has a matching `repository.url`** before letting CI publish, or `--provenance` will 422.
+4. **Cut a small follow-up release through CI** to confirm the OIDC path works end-to-end before relying on it.
+5. **Optionally harden**: flip "Publishing access" to "Require 2FA and disallow tokens" so the only way to publish is via the trusted publisher in CI — no laptops, no automation tokens.
+
+## GitHub Actions workflows
+
+- **`ci.yml`** — formatting, lint, tests, build on Node 22 across ubuntu/macos/windows. Called by `release.yml` and runs on PRs / pushes to `main`.
+- **`build.yml`** — builds prebuilt binaries (macOS/Linux/Windows) and uploads them as workflow artifacts. Triggered manually or from `release.yml`.
+- **`release.yml`** — orchestrates a release. Verifies version, runs CI, publishes to npm (Node 24 + OIDC + provenance), builds binaries, uploads release assets, verifies the package and assets are live. Triggers on published GitHub Releases or manual dispatch (beta only).
+- **`codeql.yml`**, **`dependency-review.yml`** — security scanning.
+
+## Binary release assets
+
+The curl installer (`https://feralfile.com/ff-cli-install`) downloads prebuilt binaries from GitHub Releases. The release workflow builds and uploads them automatically. To build one locally:
 
 **macOS / Linux:**
 
@@ -16,28 +65,12 @@ The curl installer downloads prebuilt binaries from GitHub Releases. Build one a
 .\scripts\release\build-asset-windows.ps1
 ```
 
-This produces (names vary by OS/arch):
+Produces (names vary by OS/arch):
 
 - `release/ff-cli-darwin-arm64.tar.gz` (and `.sha256`) on macOS
 - `release/ff-cli-linux-x64.tar.gz` (and `.sha256`) on Linux
 - `release/ff-cli-windows-x64.zip` (and `.sha256`) on Windows
 
-Run the appropriate script on each target platform and upload each pair to the GitHub release.
-
-## GitHub Actions
-
-- **Build** (`build.yml`): Trigger manually (Actions → Build → Run workflow) or on pull requests. Builds binaries on macOS, Linux, and Windows and uploads them as workflow artifacts for download.
-- **Release** (`release.yml`): On **published** GitHub Releases, validates that `package.json` matches the tag, publishes to npm, then builds binaries and uploads assets. A GitHub Release marked as a pre-release publishes to the **`beta`** dist-tag; the version must also contain `beta`. A manual workflow dispatch can also publish a beta version when you need to bypass the normal release flow, but run it from `main`.
-
-## npm Publish Requirements
-
-- Publishes use **npm Trusted Publishing (OIDC)** — no `NPM_TOKEN` secret is required or used. The trust is configured at https://www.npmjs.com/package/@feralfile/cli/access (publisher: GitHub Actions, org: `feral-file`, repo: `ff-cli`, workflow: `release.yml`).
-- Ensure `package.json` version matches the release tag (e.g. tag `1.0.2` → `"version": "1.0.2"`). The release job fails fast when they differ.
-- A **regular** (non-prerelease) GitHub Release publishes with the default dist-tag **`latest`**.
-- A GitHub Release marked **Set as a pre-release** publishes to the **`beta`** dist-tag, and its version must contain `beta` so the package version stays aligned with the beta channel.
-- Manual workflow dispatch runs publish to the **`beta`** dist-tag too, and the `version` input must contain `beta`, match `package.json`, and be dispatched from `main`.
-- Example beta version: `1.0.18-beta.0`.
-
 ## Release notes and breaking changes
 
 GitHub Release text (and any user-facing summary you publish with the version) should state compatibility changes in plain language. **Do not rely on `package.json` `engines` alone**; npm and installers surface it inconsistently, and operators skim release notes first.
@@ -56,7 +89,7 @@ GitHub Release text (and any user-facing summary you publish with the version) s
 
 Later releases only need to repeat this block if the engine floor changes again.
 
-## Installer Redirect
+## Installer redirect
 
 `https://feralfile.com/ff-cli-install` should redirect to:
 
@@ -66,8 +99,45 @@ https://raw.githubusercontent.com/feral-file/ff-cli/main/scripts/install.sh
 
 The installer script then fetches the release assets from GitHub Releases.
 
-## Environment Overrides
+## Environment overrides
 
 - `FF_CLI_VERSION`: overrides the version label in logs
 - `FF_CLI_NODE_VERSION`: Reserved in script headers for future use; current CI, npm `engines`, and release wrappers assume **Node.js 22+** (required by `dp1-js`).
 - `FF_CLI_OUTPUT_DIR`: output directory (default: `./release`)
+
+## Troubleshooting
+
+### `404 Not Found - PUT https://registry.npmjs.org/@feralfile%2fcli`
+
+npm hides "you don't have publish access" as a 404. Check:
+
+1. The trusted publisher at https://www.npmjs.com/package/@feralfile/cli/access matches the *running* workflow: organization, repository, workflow filename, environment (or lack thereof).
+2. The job has `permissions: id-token: write`.
+3. You're not somehow still passing an `NPM_TOKEN` / `NODE_AUTH_TOKEN` env var — that flips npm into token-auth mode, and if the token isn't authorized for the scope you'll 404.
+
+### `422 Unprocessable Entity ... "repository.url" is "", expected to match "https://github.com/feral-file/ff-cli" from provenance`
+
+The SLSA provenance attestation records the source repo; npm requires `package.json`'s `repository.url` to match before accepting the publish. Add:
+
+```json
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/feral-file/ff-cli.git"
+}
+```
+
+### `npm error code MODULE_NOT_FOUND ... Cannot find module 'promise-retry'`
+
+You're trying to `npm install -g npm@latest` on top of a running npm. It overwrites its own files mid-execution and corrupts. Don't upgrade in place — use a Node version that already ships the npm you need. The `publish-npm` job runs Node 24 specifically for this reason.
+
+### `EOTP — This operation requires a one-time password`
+
+You're publishing manually from a laptop, and your npm account has 2FA enforced. Either pass `--otp 123456` inline (TOTP code from your authenticator), or run `npm publish` directly in a real terminal where the browser auth flow can complete. **CI never hits this** — OIDC is its own auth path and bypasses 2FA.
+
+### `Version mismatch: package.json is X but tag is Y`
+
+The `verify-version` job catches this. Fix `package.json` to match the tag and create a new release tag, or delete and recreate the release with the correct tag.
+
+### Release fired but never reached npm
+
+The tag is consumed even when publish fails (you can't republish the same version). Bump to the next patch version and cut a fresh release. Optionally `gh release delete <tag> --cleanup-tag` to remove the never-published tag from the release page.

package/package.json

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