From 63593e028741f03ee9889bf5c598536faf888cb7 Mon Sep 17 00:00:00 2001 From: Alex Shapalov Date: Mon, 26 Oct 2026 23:49:21 -0700 Subject: [PATCH] skill/plugin 0.1.3: address Anthropic directory validator findings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The developer-portal validation of pgrundev/pgx-plugin (main @ cc5c211) passed with 11 warnings and 4 policy holds. This addresses the ones the report's fix hints point at, without changing what the skill does: - Pin every package the skill installs or launches to an exact version: npm i -g pgxdb@0.1.2 and npx pgxdb@0.1.2 instead of unpinned or @latest (SKILL.md, installation.md, security.md, check-pgx.sh hints, plugin README). - The piped remote installer (curl … | sh) is no longer something the skill runs or tells Claude to run; it stays documented in installation.md as a command the user runs in their own shell, and the skill is told never to pipe a download into a shell on the user's behalf. - Plugin README discloses exactly what detect-project.sh reads on the machine (DATABASE_URL and .env* files, printing host/port/db only) and where the connection string goes (pgx copy on the local machine, never the conversation, never elsewhere). Reading the project's own database URL is inherent to the plugin and remains a reviewer hold. - Version 0.1.2 -> 0.1.3 for the plugin and the skill so installed users receive the change; the runtime requirement stays PGX 0.1.2 or newer. The skill version now moves independently of the runtime version. Not addressed here: the icon (no PGX logo asset exists in the repository; the directory fixes the icon at first save/submit) and the 'unknown field' warning, whose field name the summary did not include. Co-Authored-By: Claude Fable 5.1 --- docs/pgx/local-dev/claude-plugin.md | 9 +++--- plugins/pgx/.claude-plugin/plugin.json | 2 +- plugins/pgx/README.md | 32 ++++++++++++------- plugins/pgx/skills/pgx/SKILL.md | 14 ++++---- .../pgx/skills/pgx/references/installation.md | 21 ++++++------ plugins/pgx/skills/pgx/references/security.md | 6 ++-- plugins/pgx/skills/pgx/scripts/check-pgx.sh | 4 +-- skills/pgx/SKILL.md | 14 ++++---- skills/pgx/references/installation.md | 21 ++++++------ skills/pgx/references/security.md | 6 ++-- skills/pgx/scripts/check-pgx.sh | 4 +-- 11 files changed, 79 insertions(+), 54 deletions(-) diff --git a/docs/pgx/local-dev/claude-plugin.md b/docs/pgx/local-dev/claude-plugin.md index b092072a11..e2e9063b80 100644 --- a/docs/pgx/local-dev/claude-plugin.md +++ b/docs/pgx/local-dev/claude-plugin.md @@ -73,7 +73,7 @@ branch. See [agents.md](agents.md) for what that gives you. Check what is installed: ```sh -claude plugin list # pgx@pgx-plugin Version: 0.1.2 Status: enabled +claude plugin list # pgx@pgx-plugin Version: 0.1.3 Status: enabled claude plugin details pgx # Component inventory: Skills (1) pgx, Hooks (0), MCP servers (0) ``` @@ -81,8 +81,9 @@ claude plugin details pgx # Component inventory: Skills (1) pgx, Hooks (0), - `skills/pgx/`: the Skill, its eleven reference documents and two helper scripts, identical to `skills/pgx/` at the repository root. -- `.claude-plugin/plugin.json`: name `pgx`, version `0.1.2` (the Skill's - version), display name, links. +- `.claude-plugin/plugin.json`: name `pgx`, version `0.1.3` (the Skill's + version; it moves independently of the PGX runtime version, which the + skill requires to be 0.1.2 or newer), display name, links. - `README.md`. In `pgrundev/pgx-plugin` additionally `LICENSE` (the AGPL-3.0 text the @@ -254,7 +255,7 @@ CLI does not check and a security scan. Values for the form: | Plugin name / display name | `pgx` / "PGX — Postgres for Agents" (read from `plugin.json`) | | Description | PGX gives every Claude Code agent its own isolated, disposable PostgreSQL-compatible database. Agents can run migrations, tests, and experiments in parallel without database conflicts. No Docker or cloud account required. Built in Rust. | | Category | Developer tools, or Databases if the form offers it | -| Version | 0.1.2 | +| Version | 0.1.3 (plugin and skill); requires PGX runtime 0.1.2 or newer | | License | AGPL-3.0 (`LICENSE` in the repository, `license` in `plugin.json`) | | Documentation / support | https://github.com/pgrundev/pgx (`documentationUrl`, `supportUrl` in `plugin.json`) | | Icon | none yet; the directory takes the icon from the first submission only, so add a square PNG (512–2048 px) as `.claude-plugin/icon.png` in `plugins/pgx` before submitting if one is wanted | diff --git a/plugins/pgx/.claude-plugin/plugin.json b/plugins/pgx/.claude-plugin/plugin.json index 343a80ac44..7faa0c6aec 100644 --- a/plugins/pgx/.claude-plugin/plugin.json +++ b/plugins/pgx/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "pgx", "displayName": "PGX — Postgres for Agents", - "version": "0.1.2", + "version": "0.1.3", "description": "Isolated, disposable PostgreSQL-compatible databases for AI coding agents.", "author": { "name": "PGRunDev", diff --git a/plugins/pgx/README.md b/plugins/pgx/README.md index 3ede13e428..acaa5edeb8 100644 --- a/plugins/pgx/README.md +++ b/plugins/pgx/README.md @@ -61,8 +61,9 @@ or just describe database work ("run the pending migrations and the tests", "set up Postgres for my agents"); Claude selects the skill when it is relevant. The first activation in a project walks through detection of the existing -database setup, a check for the PGX runtime (offering `npm i -g pgxdb` or the -official installer if it is missing), a schema-only template copied from your +database setup, a check for the PGX runtime (offering `npm i -g pgxdb@0.1.2` +if it is missing, or telling you how to run the official installer yourself), +a schema-only template copied from your existing PostgreSQL or a fresh PGX database, and a one-time `pgx agent setup`. From then on every new Claude Code session in that project starts with `DATABASE_URL` pointing at its own branch, and every subagent that session @@ -82,15 +83,23 @@ automatically. Nothing in the plugin needs to be configured by hand. - No database engine. The `pgx` binary is installed separately when the skill first needs it. The skill asks before downloading anything. -## What runs on your machine +## What runs on your machine, and what it reads Everything is local. The skill runs the `pgx` CLI against the PGX runtime on -`127.0.0.1`; it does not call any network service of its own. Database -credentials for agent branches are generated by PGX, exported into the -session's environment by the hooks that `pgx agent setup` installs, and never -written into the conversation; your existing PostgreSQL is read with -`pg_dump --schema-only` to build a template, and its data is copied only when -you explicitly approve it. Branches expire on their own (idle TTL, then a +`127.0.0.1`; it does not call any network service of its own. The only +downloads are the ones you approve: `npm i -g pgxdb@0.1.2` (pinned) when +the runtime is missing, or the official installer that you run yourself. + +To find your project's database, `detect-project.sh` reads `DATABASE_URL` +from the environment and from `.env`, `.env.local`, `.env.development` and +`.env.test` if they exist, and prints only the host, port and database name +(never the password or the URL). When you ask for a template of that +database, the connection string is passed from your environment or file +straight to `pgx copy` on this machine, which runs `pg_dump --schema-only` +against it; it is never printed into the conversation and never sent +anywhere else. Its data is copied only when you explicitly approve it. +Credentials for agent branches are generated by PGX and exported into the +session's environment by the hooks that `pgx agent setup` installs. Branches expire on their own (idle TTL, then a short grace period after the session ends) and the PGX supervisor removes them. Removing the plugin (`/plugin uninstall pgx@pgx-plugin`) removes the skill only; databases, templates, `.pgx.toml` and the PGX runtime stay, and @@ -112,8 +121,9 @@ differ. Report issues and send changes to pgrundev/pgx. - `/pgx:pgx` is not offered: `claude plugin list` should show the plugin enabled; restart the session after installing. - "PGX not found" or "too old": install or upgrade the runtime - (`npm i -g pgxdb@latest` or `curl -fsSL https://pgx.dev/install | sh`), then - run the skill again. It needs 0.1.2 or newer for subagent isolation. + (`npm i -g pgxdb@0.1.2`, or run the installer from https://pgx.dev/install + in your own shell), then run the skill again. It needs 0.1.2 or newer for + subagent isolation. - A session's `DATABASE_URL` still points at your real database: the project has not run `pgx agent setup` yet, or the session started before it did. `pgx agent doctor` reports the project's state. diff --git a/plugins/pgx/skills/pgx/SKILL.md b/plugins/pgx/skills/pgx/SKILL.md index 52b51b46db..d458fee67b 100644 --- a/plugins/pgx/skills/pgx/SKILL.md +++ b/plugins/pgx/skills/pgx/SKILL.md @@ -14,7 +14,7 @@ description: > license: AGPL-3.0 metadata: author: pgrundev - version: "0.1.2" + version: "0.1.3" homepage: https://pgx.dev repository: https://github.com/pgrundev/pgx --- @@ -111,11 +111,13 @@ unreadable `pgx --json version`. It reads the structured version only: `pgx agent --help` prints the global help on every version and proves nothing. If `pgx` is missing or too old, follow [references/installation.md](references/installation.md): prefer an -installed binary, then `npm i -g pgxdb` (Node 18+), then the official -installer `curl -fsSL https://pgx.dev/install | sh`. Supported: macOS arm64, -Linux amd64, Linux arm64. PGX picks a free port and never disturbs a -PostgreSQL on 5432. Installing is a network download: follow the host's -approval flow and say what will be installed and where. +installed binary, then `npm i -g pgxdb@0.1.2` (Node 18+, pinned to the +version this skill needs). The official installer at https://pgx.dev/install +is something the user runs in their own shell; never pipe a download into a +shell on the user's behalf. Supported: macOS arm64, Linux amd64, Linux +arm64. PGX picks a free port and never disturbs a PostgreSQL on 5432. +Installing is a network download: follow the host's approval flow and say +what will be installed and where. ### 3. Prepare the source template diff --git a/plugins/pgx/skills/pgx/references/installation.md b/plugins/pgx/skills/pgx/references/installation.md index 8d83aa67ad..818907675e 100644 --- a/plugins/pgx/skills/pgx/references/installation.md +++ b/plugins/pgx/skills/pgx/references/installation.md @@ -17,7 +17,7 @@ malformed, always with one JSON line. It compares `pgx --json version` → `pgx_version` as semver (`PGX_MIN_VERSION` overrides the floor). Do not use `pgx agent --help` as the test: `--help` prints the global help on every version. An older binary: upgrade with the method it was installed with -(`npm i -g pgxdb@latest`, or the installer again) and run the check again; +(`npm i -g pgxdb@0.1.2`, or the installer again) and run the check again; if the upgrade still reports 0.1.0, the newer package is not yet on that channel and the user should install from the GitHub release. @@ -26,14 +26,17 @@ channel and the user should install from the GitHub release. 1. **A binary that is already on the machine** (a previous install under `~/.local/bin/pgx`, Homebrew, or `~/.pgx/dist//bin/pgx`). Prefer it; do not download twice. -2. **npm**, when Node.js 18+ is present: `npm i -g pgxdb` installs the - `pgxdb` and `pgx` commands; the first run downloads the native release - tarball into `~/.pgx/dist/`. `npx pgxdb@latest` works without a - global install but gives you `npx pgxdb …` instead of `pgx …`. -3. **The official installer**: `curl -fsSL https://pgx.dev/install | sh`. - Verified release assets from github.com/pgrundev/pgx; installs under - `~/.pgx/dist/` and links `pgx` into `~/.local/bin` (override with - `PGX_BIN_DIR`). No root. +2. **npm**, when Node.js 18+ is present: `npm i -g pgxdb@0.1.2` installs + the `pgxdb` and `pgx` commands; the first run downloads the native release + tarball into `~/.pgx/dist/`. Always pin the exact version (the + one `check-pgx.sh` asks for), never `@latest`. `npx pgxdb@0.1.2` works + without a global install but gives you `npx pgxdb …` instead of `pgx …`. +3. **The official installer**, run by the user in their own shell: + `curl -fsSL https://pgx.dev/install | sh`. Tell the user the command and + what it does; do not run it yourself and never pipe a download into a + shell on the user's behalf. Verified release assets from + github.com/pgrundev/pgx; installs under `~/.pgx/dist/` and links + `pgx` into `~/.local/bin` (override with `PGX_BIN_DIR`). No root. Nothing else. No third-party scripts, no building from source for a user who just wants a database (that is for contributors). diff --git a/plugins/pgx/skills/pgx/references/security.md b/plugins/pgx/skills/pgx/references/security.md index ce37249737..feb581c961 100644 --- a/plugins/pgx/skills/pgx/references/security.md +++ b/plugins/pgx/skills/pgx/references/security.md @@ -18,8 +18,10 @@ runs in real projects that hold real credentials and real data. 6. **No deletions of developer data.** Never drop databases you did not create in this task, never `pgx init --force`, never remove a PGX home, never `pgx stop --force` a runtime other sessions use. -7. **Only official installation channels.** `npm i -g pgxdb`, - `curl -fsSL https://pgx.dev/install | sh`, or an existing binary. +7. **Only official installation channels.** An existing binary, or + `npm i -g pgxdb@0.1.2` (always an exact version). The installer at + https://pgx.dev/install is for the user to run in their own shell; never + pipe a download into a shell on the user's behalf. 8. **Preserve the user's hooks and settings.** `pgx agent install` merges; `uninstall` removes only PGX entries. Do not hand-edit hook files. 9. **Never weaken sandboxes.** Explain the Codex network setting; do not set diff --git a/plugins/pgx/skills/pgx/scripts/check-pgx.sh b/plugins/pgx/skills/pgx/scripts/check-pgx.sh index 0e41b316be..508fef7fde 100755 --- a/plugins/pgx/skills/pgx/scripts/check-pgx.sh +++ b/plugins/pgx/skills/pgx/scripts/check-pgx.sh @@ -11,7 +11,7 @@ MIN=${PGX_MIN_VERSION:-0.1.2} esc() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; } path=$(command -v pgx 2>/dev/null || true) if [ -z "$path" ]; then - printf '{"ok":false,"reason":"missing","min":"%s","hint":"install PGX: npm i -g pgxdb (Node 18+) or curl -fsSL https://pgx.dev/install | sh"}\n' "$MIN"; exit 3 + printf '{"ok":false,"reason":"missing","min":"%s","hint":"install PGX: npm i -g pgxdb@%s (Node 18+), or run the installer from https://pgx.dev/install in your own shell"}\n' "$MIN" "$MIN"; exit 3 fi out=$(pgx --json version 2>/dev/null || true) ver=$(printf '%s' "$out" | sed -nE 's/.*"pgx_version":"([0-9]+\.[0-9]+\.[0-9]+)[^"]*".*/\1/p' | head -1) @@ -36,4 +36,4 @@ if vcmp "$ver" "0.1.1"; then else why="PGX $ver has no pgx agent" fi -printf '{"ok":false,"reason":"too_old","version":"%s","path":"%s","min":"%s","hint":"%s; upgrade to %s or newer with the method it was installed with (npm i -g pgxdb@latest, or the installer again)"}\n' "$ver" "$(esc "$path")" "$MIN" "$why" "$MIN"; exit 2 +printf '{"ok":false,"reason":"too_old","version":"%s","path":"%s","min":"%s","hint":"%s; upgrade to %s or newer with the method it was installed with (npm i -g pgxdb@%s, or the installer again)"}\n' "$ver" "$(esc "$path")" "$MIN" "$why" "$MIN" "$MIN"; exit 2 diff --git a/skills/pgx/SKILL.md b/skills/pgx/SKILL.md index 52b51b46db..d458fee67b 100644 --- a/skills/pgx/SKILL.md +++ b/skills/pgx/SKILL.md @@ -14,7 +14,7 @@ description: > license: AGPL-3.0 metadata: author: pgrundev - version: "0.1.2" + version: "0.1.3" homepage: https://pgx.dev repository: https://github.com/pgrundev/pgx --- @@ -111,11 +111,13 @@ unreadable `pgx --json version`. It reads the structured version only: `pgx agent --help` prints the global help on every version and proves nothing. If `pgx` is missing or too old, follow [references/installation.md](references/installation.md): prefer an -installed binary, then `npm i -g pgxdb` (Node 18+), then the official -installer `curl -fsSL https://pgx.dev/install | sh`. Supported: macOS arm64, -Linux amd64, Linux arm64. PGX picks a free port and never disturbs a -PostgreSQL on 5432. Installing is a network download: follow the host's -approval flow and say what will be installed and where. +installed binary, then `npm i -g pgxdb@0.1.2` (Node 18+, pinned to the +version this skill needs). The official installer at https://pgx.dev/install +is something the user runs in their own shell; never pipe a download into a +shell on the user's behalf. Supported: macOS arm64, Linux amd64, Linux +arm64. PGX picks a free port and never disturbs a PostgreSQL on 5432. +Installing is a network download: follow the host's approval flow and say +what will be installed and where. ### 3. Prepare the source template diff --git a/skills/pgx/references/installation.md b/skills/pgx/references/installation.md index 8d83aa67ad..818907675e 100644 --- a/skills/pgx/references/installation.md +++ b/skills/pgx/references/installation.md @@ -17,7 +17,7 @@ malformed, always with one JSON line. It compares `pgx --json version` → `pgx_version` as semver (`PGX_MIN_VERSION` overrides the floor). Do not use `pgx agent --help` as the test: `--help` prints the global help on every version. An older binary: upgrade with the method it was installed with -(`npm i -g pgxdb@latest`, or the installer again) and run the check again; +(`npm i -g pgxdb@0.1.2`, or the installer again) and run the check again; if the upgrade still reports 0.1.0, the newer package is not yet on that channel and the user should install from the GitHub release. @@ -26,14 +26,17 @@ channel and the user should install from the GitHub release. 1. **A binary that is already on the machine** (a previous install under `~/.local/bin/pgx`, Homebrew, or `~/.pgx/dist//bin/pgx`). Prefer it; do not download twice. -2. **npm**, when Node.js 18+ is present: `npm i -g pgxdb` installs the - `pgxdb` and `pgx` commands; the first run downloads the native release - tarball into `~/.pgx/dist/`. `npx pgxdb@latest` works without a - global install but gives you `npx pgxdb …` instead of `pgx …`. -3. **The official installer**: `curl -fsSL https://pgx.dev/install | sh`. - Verified release assets from github.com/pgrundev/pgx; installs under - `~/.pgx/dist/` and links `pgx` into `~/.local/bin` (override with - `PGX_BIN_DIR`). No root. +2. **npm**, when Node.js 18+ is present: `npm i -g pgxdb@0.1.2` installs + the `pgxdb` and `pgx` commands; the first run downloads the native release + tarball into `~/.pgx/dist/`. Always pin the exact version (the + one `check-pgx.sh` asks for), never `@latest`. `npx pgxdb@0.1.2` works + without a global install but gives you `npx pgxdb …` instead of `pgx …`. +3. **The official installer**, run by the user in their own shell: + `curl -fsSL https://pgx.dev/install | sh`. Tell the user the command and + what it does; do not run it yourself and never pipe a download into a + shell on the user's behalf. Verified release assets from + github.com/pgrundev/pgx; installs under `~/.pgx/dist/` and links + `pgx` into `~/.local/bin` (override with `PGX_BIN_DIR`). No root. Nothing else. No third-party scripts, no building from source for a user who just wants a database (that is for contributors). diff --git a/skills/pgx/references/security.md b/skills/pgx/references/security.md index ce37249737..feb581c961 100644 --- a/skills/pgx/references/security.md +++ b/skills/pgx/references/security.md @@ -18,8 +18,10 @@ runs in real projects that hold real credentials and real data. 6. **No deletions of developer data.** Never drop databases you did not create in this task, never `pgx init --force`, never remove a PGX home, never `pgx stop --force` a runtime other sessions use. -7. **Only official installation channels.** `npm i -g pgxdb`, - `curl -fsSL https://pgx.dev/install | sh`, or an existing binary. +7. **Only official installation channels.** An existing binary, or + `npm i -g pgxdb@0.1.2` (always an exact version). The installer at + https://pgx.dev/install is for the user to run in their own shell; never + pipe a download into a shell on the user's behalf. 8. **Preserve the user's hooks and settings.** `pgx agent install` merges; `uninstall` removes only PGX entries. Do not hand-edit hook files. 9. **Never weaken sandboxes.** Explain the Codex network setting; do not set diff --git a/skills/pgx/scripts/check-pgx.sh b/skills/pgx/scripts/check-pgx.sh index 0e41b316be..508fef7fde 100755 --- a/skills/pgx/scripts/check-pgx.sh +++ b/skills/pgx/scripts/check-pgx.sh @@ -11,7 +11,7 @@ MIN=${PGX_MIN_VERSION:-0.1.2} esc() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; } path=$(command -v pgx 2>/dev/null || true) if [ -z "$path" ]; then - printf '{"ok":false,"reason":"missing","min":"%s","hint":"install PGX: npm i -g pgxdb (Node 18+) or curl -fsSL https://pgx.dev/install | sh"}\n' "$MIN"; exit 3 + printf '{"ok":false,"reason":"missing","min":"%s","hint":"install PGX: npm i -g pgxdb@%s (Node 18+), or run the installer from https://pgx.dev/install in your own shell"}\n' "$MIN" "$MIN"; exit 3 fi out=$(pgx --json version 2>/dev/null || true) ver=$(printf '%s' "$out" | sed -nE 's/.*"pgx_version":"([0-9]+\.[0-9]+\.[0-9]+)[^"]*".*/\1/p' | head -1) @@ -36,4 +36,4 @@ if vcmp "$ver" "0.1.1"; then else why="PGX $ver has no pgx agent" fi -printf '{"ok":false,"reason":"too_old","version":"%s","path":"%s","min":"%s","hint":"%s; upgrade to %s or newer with the method it was installed with (npm i -g pgxdb@latest, or the installer again)"}\n' "$ver" "$(esc "$path")" "$MIN" "$why" "$MIN"; exit 2 +printf '{"ok":false,"reason":"too_old","version":"%s","path":"%s","min":"%s","hint":"%s; upgrade to %s or newer with the method it was installed with (npm i -g pgxdb@%s, or the installer again)"}\n' "$ver" "$(esc "$path")" "$MIN" "$why" "$MIN" "$MIN"; exit 2