diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 26831c6..a360ba0 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "diffbot", - "version": "1.2.3", + "version": "1.3.0", "description": "Structured web knowledge tools for development and research. Enables querying of Diffbot’s Knowledge Graph (for organizations, people, and news articles) as well as web extraction, crawling, entity resolution, and web search.", "author": { "name": "Diffbot", diff --git a/.cortex-plugin/plugin.json b/.cortex-plugin/plugin.json index 26831c6..a360ba0 100644 --- a/.cortex-plugin/plugin.json +++ b/.cortex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "diffbot", - "version": "1.2.3", + "version": "1.3.0", "description": "Structured web knowledge tools for development and research. Enables querying of Diffbot’s Knowledge Graph (for organizations, people, and news articles) as well as web extraction, crawling, entity resolution, and web search.", "author": { "name": "Diffbot", diff --git a/.factory-plugin/plugin.json b/.factory-plugin/plugin.json index 26831c6..a360ba0 100644 --- a/.factory-plugin/plugin.json +++ b/.factory-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "diffbot", - "version": "1.2.3", + "version": "1.3.0", "description": "Structured web knowledge tools for development and research. Enables querying of Diffbot’s Knowledge Graph (for organizations, people, and news articles) as well as web extraction, crawling, entity resolution, and web search.", "author": { "name": "Diffbot", diff --git a/.github/plugin/plugin.json b/.github/plugin/plugin.json index 26831c6..a360ba0 100644 --- a/.github/plugin/plugin.json +++ b/.github/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "diffbot", - "version": "1.2.3", + "version": "1.3.0", "description": "Structured web knowledge tools for development and research. Enables querying of Diffbot’s Knowledge Graph (for organizations, people, and news articles) as well as web extraction, crawling, entity resolution, and web search.", "author": { "name": "Diffbot", diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..9623ddd --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,135 @@ +name: CI + +# Checks for the plugin itself. The repo ships no scripts (directory policy), +# so every check lives inline here. No secrets are used: nothing calls the +# Diffbot API. +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +jobs: + manifests: + name: Manifests and skills + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v4 + + - name: Plugin manifests parse and agree on one version + run: | + set -euo pipefail + for f in .claude-plugin/marketplace.json .claude-plugin/plugin.json \ + .cortex-plugin/plugin.json .factory-plugin/plugin.json \ + .grok-plugin/plugin.json .github/plugin/plugin.json \ + docs/listing/*/marketplace-entry.json; do + jq empty "$f" || { echo "::error file=$f::invalid JSON"; exit 1; } + done + want=$(jq -r .version .claude-plugin/plugin.json) + echo "plugin version ${want}" + for f in .cortex-plugin/plugin.json .factory-plugin/plugin.json \ + .grok-plugin/plugin.json .github/plugin/plugin.json; do + got=$(jq -r .version "$f") + if [ "$got" != "$want" ]; then + echo "::error file=$f::version ${got} does not match .claude-plugin/plugin.json ${want}" + exit 1 + fi + done + if [ -f CHANGELOG.md ] && ! grep -Eq "^## \[?${want//./\\.}\]?" CHANGELOG.md; then + echo "::error file=CHANGELOG.md::no section for ${want}" + exit 1 + fi + + - name: SKILL.md frontmatter + run: | + set -euo pipefail + fail=0 + for f in skills/*/SKILL.md; do + dir=$(basename "$(dirname "$f")") + fm=$(awk 'NR==1 && $0!="---"{exit 1} NR>1 && $0=="---"{exit} NR>1{print}' "$f") || { + echo "::error file=$f::missing YAML frontmatter"; fail=1; continue; } + name=$(printf '%s\n' "$fm" | sed -n 's/^name:[[:space:]]*//p' | tr -d '"'"'") + desc=$(printf '%s\n' "$fm" | sed -n 's/^description:[[:space:]]*//p') + if [ "$name" != "$dir" ]; then + echo "::error file=$f::name '${name}' does not match directory '${dir}'"; fail=1 + fi + if [ -z "$desc" ]; then + echo "::error file=$f::empty description"; fail=1 + fi + # Since 1.2.3 nothing is pre-approved (Anthropic directory policy). + if printf '%s\n' "$fm" | grep -q '^allowed-tools:'; then + echo "::error file=$f::allowed-tools is not allowed (see docs/CLAUDE.md)"; fail=1 + fi + echo "ok ${f}" + done + exit "$fail" + + claude-validate: + name: claude plugin validate --strict + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - run: npm install -g @anthropic-ai/claude-code + - run: claude --version + - run: claude plugin validate --strict . + + cli: + name: diffbot CLI install lines resolve + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Every documented install line uses one specifier + id: spec + run: | + set -euo pipefail + specs=$(grep -rhoE "pip install( -U| --force-reinstall --no-deps)? '[^']+'" skills README.md \ + | grep -oE "'[^']+'" | tr -d "'" | sort -u) + echo "specifiers found:"; printf ' %s\n' $specs + count=$(printf '%s\n' "$specs" | grep -c .) + if [ "$count" -ne 1 ]; then + echo "::error::expected one diffbot specifier across skills and README, found ${count}" + exit 1 + fi + echo "spec=${specs}" >> "$GITHUB_OUTPUT" + + - name: Install exactly as documented + run: | + set -euo pipefail + python3 -m venv ~/.diffbot/venv + ~/.diffbot/venv/bin/pip install --quiet '${{ steps.spec.outputs.spec }}' + ~/.diffbot/venv/bin/pip show diffbot | sed -n '1,2p' + ~/.diffbot/venv/bin/db --version + + - name: Every db subcommand the skills call exists + run: | + set -euo pipefail + cmds=$(grep -rhoE "venv/bin/db [a-z][a-z-]*( [a-z][a-z-]*)?" skills README.md \ + | awk '{ if ($2 == "dql" && $3 != "") print $2" "$3; else print $2 }' | sort -u) + fail=0 + while IFS= read -r c; do + [ -z "$c" ] && continue + if ~/.diffbot/venv/bin/db $c --help >/dev/null 2>&1; then + echo "ok db ${c}" + else + echo "::error::'db ${c} --help' failed; a skill calls a subcommand this CLI does not have" + fail=1 + fi + done <<< "$cmds" + exit "$fail" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..3fb3d85 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,64 @@ +name: Release + +# diffbot-skills is not an npm or PyPI package. Pushing a version tag creates +# the GitHub Release for that tag. There is no registry token and no GitHub +# environment. github.token is the workflow's built-in token, not a stored secret. +on: + push: + tags: ["v*"] + workflow_dispatch: + +permissions: + contents: read + +# Never cancel an in-flight release. A re-push of the same tag queues. +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +jobs: + release: + name: GitHub Release + if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + + - name: Check tag matches plugin versions + run: | + set -euo pipefail + tag="${GITHUB_REF_NAME#v}" + for f in \ + .claude-plugin/plugin.json \ + .cortex-plugin/plugin.json \ + .factory-plugin/plugin.json \ + .grok-plugin/plugin.json \ + .github/plugin/plugin.json + do + version=$(node -p "require('./${f}').version") + if [ "$version" != "$tag" ]; then + echo "::error::${f} version ${version} does not match tag v${tag}." + exit 1 + fi + echo "${f} ${version}" + done + + - name: Publish GitHub Release + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + repo="${GITHUB_REPOSITORY}" + tag="${GITHUB_REF_NAME}" + if gh release view "$tag" --repo "$repo" >/dev/null 2>&1; then + echo "Release $tag already exists; leaving it." + else + gh release create "$tag" \ + --repo "$repo" \ + --title "$tag" \ + --generate-notes \ + --verify-tag + fi diff --git a/.grok-plugin/plugin.json b/.grok-plugin/plugin.json index 7b40a7e..dc26ba7 100644 --- a/.grok-plugin/plugin.json +++ b/.grok-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "diffbot", - "version": "1.2.3", + "version": "1.3.0", "description": "Structured web knowledge tools for development and research. Enables querying of Diffbot’s Knowledge Graph (for organizations, people, and news articles) as well as web extraction, crawling, entity resolution, and web search.", "author": { "name": "Diffbot", diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..5a80e0c --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,12 @@ +# Changelog + +## 1.3.0 - 2026-11-17 + +### Changed + +- Built on 1.2.3. Skills still omit `allowed-tools`, and exports stay in `.diffbot/tmp/` in the working directory. +- Install lines require `diffbot>=3.4.0,<4`. 3.1.x and 3.2.x are not new enough. +- The DQL skill states `POST https://kg.diffbot.com/kg/v3/dql` with a JSON body. The token stays the `token` query parameter. GET is the low-level escape hatch. Agents keep using `~/.diffbot/venv/bin/db`. +- Plugin manifests are 1.3.0. Tag this release `v1.3.0`. + +There is no npm or PyPI package. The tag-triggered workflow creates the GitHub Release only. Marketplace SHA bumps (xAI and others) stay a separate step. diff --git a/README.md b/README.md index 70de603..b32e697 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,8 @@ npx skills add diffbot/diffbot-skills -g --all npx skills add diffbot/diffbot-skills -g -a claude-code -a cursor -a pi -y # Pin a release tag (git ref via URL or #fragment — @name selects a skill, not a tag) -npx skills add https://github.com/diffbot/diffbot-skills/tree/v1.2.3 -npx skills add diffbot/diffbot-skills#v1.2.3 +npx skills add https://github.com/diffbot/diffbot-skills/tree/v1.3.0 +npx skills add diffbot/diffbot-skills#v1.3.0 ``` Supported agents include Claude Code, Cursor, GitHub Copilot, Codex, Pi, Factory (Droid), Snowflake Cortex Code, ForgeCode, Gemini CLI, OpenCode, and [many more](https://github.com/vercel-labs/skills#supported-agents). Discover packages at [skills.sh](https://skills.sh). @@ -72,12 +72,12 @@ cortex plugin install diffbot/diffbot-skills Pin the release tag: ```bash -cortex plugin install github:diffbot/diffbot-skills@v1.2.3 +cortex plugin install github:diffbot/diffbot-skills@v1.3.0 ``` #### Cortex Code Desktop -Agent Settings → Plugins → Add from GitHub → `diffbot/diffbot-skills` (append `#v1.2.3` to pin the tag). +Agent Settings → Plugins → Add from GitHub → `diffbot/diffbot-skills` (append `#v1.3.0` to pin the tag). ### Factory.ai (Droid) @@ -129,7 +129,7 @@ echo "DIFFBOT_API_TOKEN=YOUR_TOKEN_HERE" > ~/.diffbot/credentials && chmod 600 ~ 3. Install the `db` CLI once, into the virtualenv every skill reads: ```bash -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` This is a one-time user install, the same as putting `gh` or `wrangler` on your machine. @@ -141,14 +141,16 @@ python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1 ### Upgrading the `db` CLI -If a skill reports a version below 3.1.1, `db --version` fails with `No such option +These skills require `diffbot>=3.4.0,<4`. If a skill reports a lower version, `db --version` fails with `No such option '--version'` (an old `diffbot-python` install), or `db` warns about the `diffbot-python` rename, upgrade in place: ```bash -~/.diffbot/venv/bin/pip install -U 'diffbot>=3.1.1' +~/.diffbot/venv/bin/pip install -U 'diffbot>=3.4.0,<4' ``` +3.1.0 added `--version` and the rename from `diffbot-python`. 3.2.0 switched DQL to `POST https://kg.diffbot.com/kg/v3/dql` with a JSON body (the token stays the `token` query parameter; GET remains a low-level escape hatch). 3.4.0 is the cumulative release to install. 3.1.x and 3.2.x are not new enough and must be upgraded. The CLI sends that request; do not call the endpoint yourself. + The package was renamed from `diffbot-python` to [`diffbot`](https://pypi.org/project/diffbot/) at 3.0.0. If a leftover `diffbot-python` is still in the venv, remove it and reinstall — in this order, because uninstalling the shim deletes the shared module files and a plain @@ -156,7 +158,7 @@ install afterwards no-ops on the surviving dist-info: ```bash ~/.diffbot/venv/bin/pip uninstall -y diffbot-python -~/.diffbot/venv/bin/pip install --force-reinstall --no-deps 'diffbot>=3.1.1' +~/.diffbot/venv/bin/pip install --force-reinstall --no-deps 'diffbot>=3.4.0,<4' ``` ## Skills @@ -296,7 +298,7 @@ This is structured knowledge querying — not page fetching, not generic web sea ## Requirements - **Python 3.10+** (used to create `~/.diffbot/venv`) -- **`diffbot` >= 3.1.1** (formerly `diffbot-python`), installed once by you — see [Setup](#setup) +- **`diffbot` >= 3.4.0** (formerly `diffbot-python`), installed once by you — see [Setup](#setup). 3.1.x must be upgraded. - **Diffbot API token** (free tier available) - A supported agent (see Install) diff --git a/docs/listing/anthropic/README.md b/docs/listing/anthropic/README.md index 898e773..07fad4c 100644 --- a/docs/listing/anthropic/README.md +++ b/docs/listing/anthropic/README.md @@ -64,7 +64,7 @@ home-directory `Read` allowlist tweak). Nothing had landed on main since Saturda | *BLOCKING: `allowed-tools` beyond Read, Grep, Glob, and LS* | every skill | `Bash` and `jq` removed from all ten. Nine skills keep only a `Read` entry scoped to a scratch folder under `~/.diffbot` (itself refused later; removed in 1.2.3). `diffbot-web-search` omits the `allowed-tools` key. No `${...}` paths, no `//` or `\\` paths, no URLs. `db` and `jq` prompt the user. | | *Pre-approves broad shell access (Bash)* | 10 | Resolved by the same Bash removal. | | *An image or font file the plugin's code could run* | 2 | Audited, files left as-is. The only image or font in the tree is `.claude-plugin/icon.png`, which the report already marked Info/passed. No hooks, scripts, commands, or skill instructions load or execute an image or font as code. No `icon` field added — it is not in the schema and `claude plugin validate --strict` fails on it. | -| *Download-and-run commands* (`curl \| sh`, `uvx`/`npx` of a remote URL, `pip install` from a URL) | 3 | Left as documentation. The plugin itself does not run them: there is no hook, script, command, or `` !`…` `` line, and no bundled installer was added. The README install / upgrade / `npx skills add` sections stay. Each skill's Step 1 block still shows `python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.0'` for the user to run or approve, and still says the skill never installs, upgrades, or uninstalls the CLI. 1.2.1's note that installing was "documented in the README only" was incomplete — the line also lives in those Step 1 blocks, as documentation. | +| *Download-and-run commands* (`curl \| sh`, `uvx`/`npx` of a remote URL, `pip install` from a URL) | 3 | Left as documentation. The plugin itself does not run them: there is no hook, script, command, or `` !`…` `` line, and no bundled installer was added. The README install / upgrade / `npx skills add` sections stay. Each skill's Step 1 block still shows `python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4'` for the user to run or approve, and still says the skill never installs, upgrades, or uninstalls the CLI. As of 1.3.0 that floor is 3.4.0; 3.1.x must be upgraded. 1.2.1's note that installing was "documented in the README only" was incomplete — the line also lives in those Step 1 blocks, as documentation. | ## Directory review refusal after v1.2.2 diff --git a/docs/listing/anthropic/validation-proof.md b/docs/listing/anthropic/validation-proof.md index b6cffd6..d1e79dd 100644 --- a/docs/listing/anthropic/validation-proof.md +++ b/docs/listing/anthropic/validation-proof.md @@ -99,13 +99,15 @@ observation, not assumption: ## Dependency floor -The install line in the README pins `diffbot>=3.1.1` (at the time of this -capture, `diffbot-python>=0.2.1`; the package has since been renamed) rather than +The install line in the README pins a minimum (at the time of this +capture, `diffbot-python>=0.2.1`, later `diffbot>=3.1.0`; the package has since been renamed) rather than the bare package name. This is deliberate: `pip install ` with no constraint is a no-op when *any* version is already present, so a venv created against 0.1.0 would never upgrade. 0.1.0 sent the wrong query parameter for web-search `-n`, silently returning 10 results regardless — the version floor is what guarantees the documented flag -behaves as described. +behaves as described. As of plugin 1.3.0 the install and upgrade lines require +`diffbot>=3.4.0,<4`. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST +with a JSON body (token stays the `token` query parameter); users on 3.1.x must upgrade. ## Permissions summary diff --git a/docs/listing/xai/xai-pr.md b/docs/listing/xai/xai-pr.md index 9ad945c..6de526e 100644 --- a/docs/listing/xai/xai-pr.md +++ b/docs/listing/xai/xai-pr.md @@ -33,8 +33,8 @@ Adds the **diffbot** plugin: ten skills for Diffbot's structured web knowledge A - [x] No reading/exfiltration of secrets, tokens, `.env`, or env vars. - [x] Hooks and MCP scope are least-privilege — the plugin has no hooks and no MCP servers. - Network endpoints this plugin calls (and why): - - `pypi.org` / `files.pythonhosted.org` — the user runs one documented line to create `~/.diffbot/venv` and `pip install` [`diffbot`](https://pypi.org/project/diffbot/) (>= 3.1.1, formerly `diffbot-python`), the `db` CLI every skill shells out to. The skills never install it themselves. Source: https://github.com/diffbot/diffbot-python. - - `kg.diffbot.com` — Knowledge Graph: DQL queries (`/kg/v3/dql`) and the ontology (`/kg/ontology`). + - `pypi.org` / `files.pythonhosted.org` — the user runs one documented line to create `~/.diffbot/venv` and `pip install` [`diffbot`](https://pypi.org/project/diffbot/) (>= 3.4.0, formerly `diffbot-python`; 3.1.x must be upgraded), the `db` CLI every skill shells out to. The skills never install it themselves. Source: https://github.com/diffbot/diffbot-python. + - `kg.diffbot.com` — Knowledge Graph: DQL queries (`POST /kg/v3/dql` with a JSON body; the token stays the `token` query parameter; GET is only a low-level escape hatch) and the ontology (`/kg/ontology`). The skills do not call these URLs themselves. - `api.diffbot.com` — Extract (`/v3/*`) and Crawl (`/v3/crawl`). - `llm.diffbot.com` — web search (`/api/v1/web_search`). - `nl.diffbot.com` — entity recognition and linking (`/v1/`). diff --git a/skills/diffbot-crawl/SKILL.md b/skills/diffbot-crawl/SKILL.md index 02c1e56..7a4d331 100644 --- a/skills/diffbot-crawl/SKILL.md +++ b/skills/diffbot-crawl/SKILL.md @@ -50,13 +50,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. Always tell the user where an export was saved. diff --git a/skills/diffbot-deals/SKILL.md b/skills/diffbot-deals/SKILL.md index 94ba4cb..a1b03d5 100644 --- a/skills/diffbot-deals/SKILL.md +++ b/skills/diffbot-deals/SKILL.md @@ -26,13 +26,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. diff --git a/skills/diffbot-dql/SKILL.md b/skills/diffbot-dql/SKILL.md index 3bdbdab..5c872ab 100644 --- a/skills/diffbot-dql/SKILL.md +++ b/skills/diffbot-dql/SKILL.md @@ -9,7 +9,7 @@ Query the Diffbot Knowledge Graph via the DQL API. Translate the user's plain-te ## The `db dql` CLI -All work in this skill is driven by the `db` CLI from the [`diffbot`](https://github.com/diffbot/diffbot-python) library. It owns token loading, URL encoding, HTTP, ontology lookup, and parallel probing. +All work in this skill is driven by the `db` CLI from the [`diffbot`](https://github.com/diffbot/diffbot-python) library. It owns token loading, the DQL HTTP call, ontology lookup, and parallel probing. DQL is `POST https://kg.diffbot.com/kg/v3/dql` with a JSON body (`query`, `size`, and any `from`, `format`, `filter`, `exportspec`, and other fields). The token stays the `token` query parameter; any other placement is rejected. GET still works as a low-level escape hatch, and the query is not put in the URL. Always use `~/.diffbot/venv/bin/db` — do not call the endpoint yourself. **The CLI lives in a dedicated virtualenv at `~/.diffbot/venv`, which the user installs once** — the skill does not assume `db` is on `PATH` or that any other venv exists, and it never installs the library itself. Step 1 checks that the CLI is there. **Always invoke with the fixed path `~/.diffbot/venv/bin/db`** — never bare `db` and never another venv's `db`, so no `PATH` assumption is made. `db` is not pre-approved; Claude will ask before each run. Throughout this document `db` is shorthand for `~/.diffbot/venv/bin/db`; expand it to the full path in every actual bash command. @@ -46,13 +46,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. diff --git a/skills/diffbot-entities/SKILL.md b/skills/diffbot-entities/SKILL.md index aba7368..42b34ae 100644 --- a/skills/diffbot-entities/SKILL.md +++ b/skills/diffbot-entities/SKILL.md @@ -37,13 +37,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. Always tell the user where an export was saved. diff --git a/skills/diffbot-extract/SKILL.md b/skills/diffbot-extract/SKILL.md index 3816c1d..3f336cc 100644 --- a/skills/diffbot-extract/SKILL.md +++ b/skills/diffbot-extract/SKILL.md @@ -61,13 +61,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. Always tell the user where an export was saved. diff --git a/skills/diffbot-news/SKILL.md b/skills/diffbot-news/SKILL.md index 3f3b14b..6ed7f43 100644 --- a/skills/diffbot-news/SKILL.md +++ b/skills/diffbot-news/SKILL.md @@ -26,13 +26,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. diff --git a/skills/diffbot-organizations/SKILL.md b/skills/diffbot-organizations/SKILL.md index 884a087..ab74412 100644 --- a/skills/diffbot-organizations/SKILL.md +++ b/skills/diffbot-organizations/SKILL.md @@ -26,13 +26,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. diff --git a/skills/diffbot-people/SKILL.md b/skills/diffbot-people/SKILL.md index 6078cff..5750cdd 100644 --- a/skills/diffbot-people/SKILL.md +++ b/skills/diffbot-people/SKILL.md @@ -33,13 +33,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. diff --git a/skills/diffbot-places/SKILL.md b/skills/diffbot-places/SKILL.md index f0f0e79..33c35f0 100644 --- a/skills/diffbot-places/SKILL.md +++ b/skills/diffbot-places/SKILL.md @@ -26,13 +26,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. Save output files under `.diffbot/tmp/` in the working directory. `db` creates that folder itself, so don't `mkdir` it first. `db`, `jq`, and `cat` are not pre-approved — Claude will ask before running them. diff --git a/skills/diffbot-web-search/SKILL.md b/skills/diffbot-web-search/SKILL.md index 7be5be9..59d64bf 100644 --- a/skills/diffbot-web-search/SKILL.md +++ b/skills/diffbot-web-search/SKILL.md @@ -100,11 +100,12 @@ the index does not have, or for a page whose current state matters. | `-m`, `--max-tokens` | none | Caps total response tokens — trims from the bottom of the ranking | | `-f`, `--format` | `list` | Output format: `list` (rich terminal), `json` (raw API), `text` (plain/agent-friendly) | -**Requires `diffbot` >= 3.1.1** (`-s` was added in 3.1.0; the package was formerly +**Requires `diffbot` >= 3.4.0** (`-s` was added in 3.1.0; the package was formerly `diffbot-python`, whose final release 0.3.0 lacks it). The Step 1 check reports the installed version. If `-s` is rejected as an unknown option, or `db` prints a -`FutureWarning` about the rename, the venv is older than 3.1.0 — point the user at -**Upgrading the `db` CLI** in the plugin README and stop. Don't upgrade it yourself. +`FutureWarning` about the rename, the venv is older than 3.1.0. Any install below +3.4.0, including 3.1.x, has to be upgraded — point the user at **Upgrading the `db` +CLI** in the plugin README and stop. Don't upgrade it yourself. `-m` is the other way to shrink a response, and it degrades sharply: measured on one query, 5000 → 10 results, 2000 → 5, 1000 → 1, and **200 → zero**. Below roughly 1000 @@ -126,13 +127,13 @@ fails with `No such file or directory`, stop and show the user this line to run themselves (it is deliberately not pre-approved): ``` -python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.1.1' +python3 -m venv ~/.diffbot/venv && ~/.diffbot/venv/bin/pip install 'diffbot>=3.4.0,<4' ``` -If it prints a version below 3.1.1, fails with `No such option '--version'` (an old +If it prints a version below 3.4.0 (including 3.1.x and 3.2.x — upgrade them), fails with `No such option '--version'` (an old `diffbot-python` install, which predates the flag), or warns about the `diffbot-python` rename, point the user at **Upgrading the `db` CLI** in the plugin README and stop. Never run an install, -upgrade, or uninstall line yourself. +upgrade, or uninstall line yourself. 3.1.0 added `--version` and the rename; 3.2.0 switched DQL to POST; 3.4.0 is the release these skills require. The token is read from `DIFFBOT_API_TOKEN` env var or `~/.diffbot/credentials`. If missing: