@prowl-ai/prowl-skill 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+## v0.4.0 — 2026-08-13
+
+Package `@prowl-ai/prowl-skill` 0.4.0 · plugins `prowl` 0.3.0, `prowl-cli` 0.1.1
+(unchanged — the package gained an installer, the plugins did not change).
+
+### Added
+
+- **`npx @prowl-ai/prowl-skill`** — one command that adds the marketplace, installs
+  both plugins and says what to do next. Verbs: `install`, `update`, `statusline`,
+  `token`, `status`, `plain`. Every one takes `--dry-run`, which prints what it would
+  do and changes nothing. Zero dependencies: it runs through `npx` on a machine that
+  has agreed to nothing yet.
+
+  **It installs the plugin rather than copying the skill**, and that is the design
+  decision worth stating. The obvious shape — copy `skills/prowl/` into
+  `~/.claude/skills/` — delivers the text and silently drops everything the text is
+  about: the hooks and the MCP server. Worse, a plain copy of the same name shadows an
+  installed plugin and serves its frozen version forever. `plain` exists for agents
+  with no plugin channel and refuses to run where the plugin is installed.
+
+  Two things it will not do quietly: it never replaces a `statusLine` somebody else
+  set without `--force`, and it never writes to `~/.claude/settings.json` without
+  taking a backup first and reading it back — a copy that cannot be verified cancels
+  the write.
+
+- **`release.yml`** — tag-driven publication, off by default behind the repository
+  variables `RELEASE_ENABLED` and `PUBLISH_NPMJS`. A `v*` tag runs the suite and every
+  guard **on the tag**, validates both plugins and the marketplace with
+  `claude plugin validate --strict`, checks that the tag matches `package.json`,
+  extracts the CHANGELOG section, cuts the GitHub release, packs the tarball and runs
+  the installer out of it the way `npx` would, then publishes with provenance.
+
+  A tag rather than a push to main: every commit publishing would make every
+  work-in-progress state a release somebody's `npx` picks up.
+
+- **`test/version_sync_test.js`** — the version lives in seven places. The two plugins
+  are versioned independently, so the rule is agreement *within* a plugin plus
+  `package.json` matching the tag. It also asserts both marketplace manifests list
+  exactly the plugin directories on disk, and that the CHANGELOG has a heading the
+  release workflow's pattern can find.
+
+### Fixed
+
+- **The CHANGELOG heading could not be extracted**, and nothing would have said so
+  until after the tag was public — the class that cost a sibling project three
+  releases. Found offline by the new check, before any tag existed.
+
+- **`scripts/` shipped inside the npm tarball.** `negative-self-test.js` rewrites
+  source files by design; inside a published package that is a script capable of
+  mangling somebody's `node_modules`, and no consumer has any use for it.
+
+## v0.3.0 — 2026-08-13
+
+Package `@prowl-ai/prowl-skill` 0.3.0 · plugins `prowl` 0.3.0, `prowl-cli` 0.1.1.
+
+### Added
+
+- **The status widget.** A `prowl_analyze` call runs 30 seconds to 5 minutes and an
+  async session runs longer; until now the terminal showed a spinner and the cost
+  appeared only inside a response body nobody reads.
+
+  The plugin now ships three observing hooks. A call opens a record keyed by its
+  `tool_use_id` and closes it when the response arrives, carrying the debit the server
+  reported in `billing.actual_cost_usd`. A fraction from `prowl_session_status` becomes
+  a dock/taskbar progress bar, taken down when the session reports a terminal status
+  rather than when a poll happens to end. A failed call and a wallet gate are said
+  once per kind of failure — an agent retrying five times must not produce five
+  notices — to the operator as a message and to the agent as context, so it stops
+  retrying.
+
+  **It calls no API.** Every figure was already in a response the agent received.
+
+- **An opt-in status line**, wired by the operator in two documented commands, showing
+  the in-flight call and its elapsed time, calls / ok / failed, spend, context usage,
+  and the last five tools with their verdicts. A plugin cannot ship one: no plugin
+  manifest declares `statusLine`. The script finds its library whether it runs inside
+  the plugin or copied to a stable path, and prints nothing when it finds neither.
+
+- **Tests and CI**, which this repository had none of. 89 checks across six suites,
+  including end-to-end fixtures that run the real hook scripts as processes against
+  empty, malformed and absent payloads — a hook that throws breaks the turn of every
+  session that installed the plugin. Plus `scripts/negative-self-test.js`: six guards,
+  each disarmed in turn, with the suite required to go red and the tree byte-compared
+  on restore.
+
+### Fixed
+
+- **The tool count was 408 in eight files while the server served 448** — restated
+  twenty times and with nothing keeping it true. Corrected, and
+  `scripts/check-tool-count.js` now compares the repository's figure against
+  `prowl.chat/mcp/skill.md` on every CI run. A network failure is reported as
+  *unknown*, never as drift: a check that could not reach the server has learned
+  nothing, and saying otherwise trains people to ignore it.
+
+- **The adapter could not have found a single debit.** The live server double-encodes:
+  `prowl_get_stats` and `prowl_list_tools` both answer `{"result": "<a JSON string>"}`.
+  The walker treated `result` as a leaf and stopped there, so every metered call would
+  have rendered `$—` forever — with the whole suite green, because the fixtures were
+  written from the documentation and the documentation describes the inner shape.
+  Found by calling a free tool and reading the response. `test/live_shapes_test.js` now
+  holds the captured bodies, and the envelope-following is planted against.
+
+- **A negative self-test that fired on a coin flip.** The lock guard proved itself on
+  Node 18 and not on Node 22, and CI is what said so: the fixture detected the lost
+  update probabilistically, because eight processes launched in sequence can also
+  finish in sequence. A start barrier and five writes per writer make it deterministic
+  — verified three times in each direction.
+
+- **The widget said `1 calls`.** Eighteen render fixtures, every one of them using a
+  plural count. Found by driving the installed plugin by hand and reading the line.
+
+### Notes
+
+- State lives in `~/.prowl/status/<session_id>.json`, beside the token file, and is
+  pruned after seven days. The plugin writes nothing to `~/.claude/settings.json`.
+- Known gap, recorded rather than hidden: this repository states `22 MCP tools` and
+  tabulates 20 of them. `prowl_list_sessions`, `prowl_test_tool` and the
+  `prowl_get_tool_info` alias are served but appear in no table here.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prowl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# Prowl Plugin
+
+**One MCP. 448 market-intelligence tools for your agent.**
+
+[![Live](https://img.shields.io/badge/prowl.chat-live-00c853?style=flat-square)](https://prowl.chat)
+[![MCP](https://img.shields.io/badge/MCP-prowl.chat%2Fmcp-6e40c9?style=flat-square)](https://prowl.chat/mcp)
+[![Tools](https://img.shields.io/badge/tools-448-0969da?style=flat-square)](https://prowl.chat/mcp/skill.md)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+[Prowl](https://prowl.chat) is a single MCP endpoint that gives any AI agent (Cursor, Claude Code, Codex, or your own stack) **448 market-intelligence tools across 15 providers** — SEO & backlinks, 60+ SERP engines, ad libraries, web scraping, reviews, AI/LLM mention tracking — plus the full Prowl research pipeline. Your agent calls real data instead of guessing, billed pay-as-you-go from a USD wallet.
+
+This repo is the **installable plugin**: a namespaced `/prowl:*` skill plus a ready-made MCP config. Install it and your coding agent wires up the rest itself.
+
+- MCP URL: `https://prowl.chat/mcp` (Streamable HTTP)
+- Auth: `Authorization: Bearer prowl_<your_key>`
+- Hosted install playbook: <https://prowl.chat/mcp/install.md>
+- Full tool reference: <https://prowl.chat/mcp/skill.md>
+
+## Plugins included
+
+| Plugin | Skill | What it covers |
+|--------|-------|----------------|
+| `prowl` | `/prowl` | Install and use the Prowl **MCP**: token setup, core tools (`prowl_list_tools`, `prowl_search_tools`, `prowl_tool_info`, `prowl_call_tool`, `prowl_analyze`, async sessions, schedules), tiers, playbooks, verification, and billing. Ships the `.mcp.json`. |
+| `prowl-cli` | `/prowl-cli` | Drive the same catalog from the **shell** with [`@prowl-ai/cli`](https://github.com/PROWL-AI/prowl-cli): catalog commands, metered calls, `analyze` tiers and their cost caps, playbooks, `--json` output, exit codes. No MCP server required. |
+
+Install either or both — the MCP plugin for agent tool calls, the CLI plugin for scripts, CI and terminal work.
+
+## Setup
+
+### 1. Get a token (human, one time)
+
+1. Sign up at <https://prowl.chat> ($5 starter credit, no card).
+2. Optionally top up the wallet.
+3. Generate a `prowl_...` API key under **MCP Home → API keys & config** (shown once).
+
+### 2. Provide the token to the plugin
+
+Either export `PROWL_MCP_TOKEN`, or write a token file:
+
+```bash
+mkdir -p ~/.prowl
+printf '%s' "prowl_YOUR_KEY" > ~/.prowl/prowl_mcp_token
+chmod 600 ~/.prowl/prowl_mcp_token
+```
+
+### 3. Install the plugin
+
+**One command, any machine with Node 18+:**
+
+```bash
+npx @prowl-ai/prowl-skill
+```
+
+It adds the marketplace, installs both plugins, and tells you what to do next. Then:
+
+```bash
+npx @prowl-ai/prowl-skill update       # refresh after a new release
+npx @prowl-ai/prowl-skill statusline   # wire the status line (backs up settings first)
+npx @prowl-ai/prowl-skill status       # what is installed, what is missing
+```
+
+Pipe the key in so it never reaches your shell history:
+
+```bash
+printf %s "prowl_YOUR_KEY" | npx @prowl-ai/prowl-skill token
+```
+
+Every command takes `--dry-run`, which prints what it would do and changes nothing.
+
+**By hand, if you prefer:**
+
+```bash
+claude plugin marketplace add https://github.com/PROWL-AI/prowl-skill
+claude plugin install prowl@prowl
+claude plugin install prowl-cli@prowl   # optional: the shell client skill
+```
+
+**Agents with no plugin channel** (Cursor, and others that read plain skills):
+
+```bash
+npx @prowl-ai/prowl-skill plain
+```
+
+That copies the skills and nothing else — no hooks, no status widget, no MCP server.
+It refuses to run where the plugin is installed, because a plain copy of the same name
+shadows a plugin and serves its frozen version forever.
+
+**Codex**
+
+```bash
+codex plugin marketplace add https://github.com/PROWL-AI/prowl-skill
+```
+
+Then ensure `[plugins."prowl@prowl"] enabled = true` in `${CODEX_HOME:-$HOME/.codex}/config.toml` and restart.
+
+The bundled `.mcp.json` connects to `https://prowl.chat/mcp` via `mcp-remote`, reading the token from `PROWL_MCP_TOKEN` or `~/.prowl/prowl_mcp_token`.
+
+### Manual MCP config (any client)
+
+Configure a Streamable HTTP MCP server at `https://prowl.chat/mcp` with header `Authorization: Bearer prowl_YOUR_KEY`. See <https://prowl.chat/mcp/install.md> for per-client snippets (Cursor, Claude Code, Codex, generic).
+
+## Verify
+
+```bash
+curl https://prowl.chat/mcp/health
+```
+
+Then, from your agent, run `prowl_list_tools` (free) → 448 tools grouped by category.
+
+## The status widget
+
+A `prowl_analyze` call runs 30 seconds to 5 minutes and an async session runs longer.
+For all of that time the terminal shows a spinner, and what it cost appears only
+inside a response body nobody reads. The `prowl` plugin ships hooks that fix both.
+
+**It calls no API.** Every figure it shows was already in a response your agent
+received, so the widget costs nothing and cannot spend your wallet to draw itself.
+
+On by default, once the plugin is installed:
+
+- a **progress bar in the dock/taskbar** when `prowl_session_status` reports a
+  fraction, taken down when the session reports a terminal status
+- a **one-time notice** when a call fails or the wallet blocks one — once per kind of
+  failure, so an agent retrying five times does not produce five notices
+
+Opt-in, one edit to `~/.claude/settings.json` (a plugin cannot ship a status line):
+
+```
+prowl · ⟳ analyze 1:12 · 12 calls 11✓ 1✗ · $0.31 · ctx 42% · ▸ call_tool✓ tool_info✓ search_tools✓
+```
+
+See the [`prowl` skill](plugins/prowl/skills/prowl/SKILL.md#the-status-widget) for the
+two commands. State lives in `~/.prowl/status/<session_id>.json` beside your token, is
+pruned after seven days, and the plugin never writes to your Claude Code settings.
+
+## What your agent gets
+
+- **22 MCP tools** front the whole catalog — discovery and schema lookup are free; only data calls are metered.
+- **3 tiers** for `prowl_analyze` — `basic` / `deep` / `max`, each with a hard provider-cost cap ($2.50 / $8.00 / $18.00). You are never billed more than the reserved hold.
+- **8 playbooks** — `geo-visibility-audit`, `competitor-teardown`, `content-engine`, `local-and-reputation`, `mobile-aso`, `amazon-marketplace`, `idea-validation`, `channel-economics-audit`.
+- **Verified reports** — a typed evidence ledger extracts claims, attacks them adversarially, then gap-fills what survives. Contradictions and refuted claims ship inside the report.
+- **Exports** — Markdown, PDF, PPTX, audio brief, video.
+
+Prefer a terminal? Install the `prowl-cli` plugin above, or use [`@prowl-ai/cli`](https://github.com/PROWL-AI/prowl-cli) directly.
+
+## Security
+
+`prowl_...` keys are billing-bearing — every metered tool call debits your USD wallet. Treat the key as a secret. Token files and `.env` are git-ignored; never commit a key to a public repo.
+
+## License
+
+MIT — see [LICENSE](LICENSE).