@cookiepal-oss/agent 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cookiepal-oss
+
+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

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @cookiepal-oss/agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The local steps of the CookiePal agent plugin. An AI coding agent (Claude Code, Codex or Cursor) runs them on the user's machine around the CookiePal MCP server's tools: preparing a page for `plan_check`, loading it in a fresh browser profile, crawling a site for `start_scan`, and checking what goes back to the server. Nothing here is meant to be typed by hand.
+
+In Codex and Cursor, the plugin's skills run it through npx, pinned to the exact version the plugin was built with:
+
+```bash
+npx -y @cookiepal-oss/agent@<version> prepare <<'URL'
+https://example.com/
+URL
+```
+
+npx needs no plugin folder, which is the point: Codex and Cursor never tell a skill where a plugin lives. Claude Code runs the copy the plugin carries in its `dist/`, from both its skills and its hooks, so it works offline and never calls npx.
+
+## Where it keeps its files
+
+In Claude Code, `COOKIEPAL_DATA_DIR`, which the plugin sets to its data folder; the check refuses to run without it. Codex's hooks always use `~/.cookiepal/plugin-data`, whatever `COOKIEPAL_DATA_DIR` says, so they share one folder with the skills. Everywhere else, `COOKIEPAL_DATA_DIR` when it is set, and `~/.cookiepal/plugin-data` when it is empty or unset.
+
+## Cursor's hooks
+
+Cursor never runs a plugin's hooks, so `cursor-hooks install` adds two user hooks to `~/.cursor/hooks.json`, after the user agrees. Install copies `dist/` to `~/.cookiepal/agent/<version>/`, and writes a small launcher next to `hooks.json`: `cookiepal-hook.sh`, or `cookiepal-hook.cmd` on Windows. Each hook runs the launcher. It starts the copy with the Node that ran the install, or else with the first Node 18 or later it finds on `PATH` or in the usual install places. If it finds no usable Node, or the copy is gone, it refuses calls to CookiePal's server and allows every other server's. `cursor-hooks status` reports whether the hooks are installed for the running version and Node. `cursor-hooks uninstall` removes the hooks, the launcher and the copy, and keeps every other hook.
+
+## What it bundles
+
+`pnpm build` writes `dist/check.mjs` (the command), `dist/scan.mjs` (the detached crawl), `dist/tldts.mjs` and the `@cookiepal-oss/cookie-db` catalogue as `dist/cookies.json`. The package has no runtime dependencies. A scan installs `@cookiepal-oss/cli`'s crawl engine into the data folder on first use rather than bundling Crawlee or Puppeteer.
+
+## Tests
+
+```bash
+pnpm --filter @cookiepal-oss/agent test
+```
+
+Building and testing need Node 22.18 or later: the build script is TypeScript run directly by Node, and the tests spawn the built `dist/check.mjs`, so `test` builds first. The published package runs on Node 18 or later.