chore(cli): release 0.2.0

Author: github-actions[bot]

CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to `polygres-cli` are documented in this file.
+
+## 0.2.0 - 2026-07-31
+
+### Added
+
+- Added the complete `polygres context` namespace for pgContext capabilities,
+  discovery, preflight, collection lifecycle, filters, points, durable
+  operations, aggregates, dense retrieval, text hybrid, graph composition,
+  rank fusion, coupled Joint retrieval, grouping, and recall checks.
+- Added strict shared-contract validation, file and standard-input request
+  handling, mutation idempotency, adaptive durable-operation waiting, exact
+  JSON envelopes, and Context-specific human output.
+- Added `polygres api routes` and `polygres api request` with a bundled,
+  versioned OpenAPI snapshot, strict route and method selection, declared
+  parameters, JSON-schema body validation, schema inspection, dry runs, and
+  JSON output.
+- Added FastAPI schema generation and drift validation for the bundled CLI
+  OpenAPI snapshot.
+- Added server-controlled CLI notices with a public API endpoint, 10-hour local
+  cache, ETag revalidation, version and platform targeting, safe plain-text
+  stderr rendering, `once`/`daily`/`always` display policies, and the static
+  `polygres notices` command.
+- Added `polygres vector configs set-default <config-id>` for selecting the
+  default vector configuration without using the web console.
+- Added direct Runtime API graph access support for graph discovery,
+  configuration, builds, and status checks when
+  `CLI_DIRECT_RUNTIME_GRAPH_ENABLED` is enabled and the control plane grants
+  access.
+
+### Changed
+
+- Graph status output now includes activation failure reasons and a concise
+  summary of configuration differences.
+- Graph configuration export and apply flows now canonicalize table identifiers
+  as `id_columns`, while continuing to accept legacy `id_column` input.
+- Authentication contracts are vendored into the package so standalone CLI
+  exports do not depend on an external `polygres-lib` installation.
+
+### Fixed
+
+- Graph and vector activation verification failures now return nonzero CLI exit
+  codes instead of appearing successful to automation.
+- Authentication errors no longer expose internal identity-provider details.
+
+## 0.1.2 - 2026-07-14
+
+### Changed
+
+- CSV imports now upload directly to blob staging for improved reliability.
+- CSV upload limits now follow the storage allowance of the selected project
+  tier.
+
+## 0.1.1 - 2026-07-14
+
+### Changed
+
+- Added Python 3.10 to release validation for the standalone CLI package.
+
+## 0.1.0 - 2026-07-09
+
+### Added
+
+- Initial standalone `polygres-cli` package.
+- Added browser authentication, project management, connection information,
+  Runtime API key management, CSV imports, migrations, graph/vector/text
+  configuration, readiness checks, JSON output, and stable exit codes.

CONTRIBUTING.md

@@ -18,12 +18,46 @@ ruff check .
 python -m build
 ```
 
+## OpenAPI snapshot
+
+The generic `polygres api` surface reads
+`src/polygres_cli/openapi/control-plane-v1.json`. Generate it from the
+monorepo's FastAPI application after changing routes or schemas:
+
+```bash
+python packages/python-cli/tools/generate_openapi_snapshot.py
+python packages/python-cli/tools/generate_openapi_snapshot.py --check
+```
+
+Run these commands from the monorepo root in an environment containing the
+`services/api` dependencies. The API test suite compares the committed
+snapshot with `create_app().openapi()`, while the CLI tests validate the
+bundled resource and request behavior.
+
+The public `GET /v1/cli/notices` operation is part of that snapshot. Any notice
+response-schema or targeting change therefore requires regenerating the
+snapshot and running both the API and CLI notice tests. Publishing notice rows
+does not require regenerating the snapshot or releasing the CLI. See
+`services/api/CLI_NOTICES.md` in the monorepo for the operational workflow.
+
 ## Publishing
 
 Publishing uses GitHub Actions Trusted Publishing. Validate first through
 TestPyPI, then publish a matching `python-cli-vX.Y.Z` tag from the public CLI
 repository. Do not add PyPI API tokens to GitHub secrets.
 
+Before syncing a release to the public CLI repository:
+
+1. Add the release notes and date to `CHANGELOG.md`.
+2. Update the version in `pyproject.toml` and
+   `src/polygres_cli/cli_client.py`.
+3. Update version assertions in the test suite and public installation
+   documentation.
+4. Run `pytest`, `ruff check .`, `python -m build`, and
+   `python -m twine check dist/*`.
+5. Validate the release through TestPyPI before creating the matching
+   production tag.
+
 ## Scope
 
 This repository contains the public command-line client. Keep control-plane

README.md

@@ -16,6 +16,16 @@ For an isolated global installation:
 pipx install polygres-cli
 ```
 
+From the repository root, create an isolated development environment and
+install the CLI in editable mode:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+sfw pip install -e packages/python-cli
+polygres context capabilities --help
+```
+
 The command remains `polygres`:
 
 ```bash
@@ -40,9 +50,91 @@ polygres migrations apply --file ./001_create_documents.sql
 polygres graph discover --json > graph.json
 polygres graph config apply --file graph.json
 polygres vector configs list
+polygres vector configs set-default <config-id>
 polygres text configs list
+polygres context capabilities
+polygres context collections list
+polygres api routes
+polygres notices
+```
+
+AI Search commands use the existing login and selected-project workflow:
+
+```bash
+polygres login
+polygres projects use <project-id-or-exact-name>
+polygres context sources discover
+polygres context collections create support_docs \
+  --source new-table \
+  --table support_docs \
+  --dimensions 768
+polygres context search support_docs --embedding-file query-embedding.json
+polygres context joint support_docs \
+  --embedding-file query-embedding.json \
+  --query "current guidance" \
+  --semantic-weight 0.6 \
+  --lexical-weight 0.1 \
+  --graph-weight 0.3
+```
+
+Context is the pgContext-backed collection namespace. It does not reuse
+pgvector configurations. Mutations send an idempotency key and wait for their
+durable operation by default; use `--no-wait` to return after acceptance.
+Global `--json`, `--project`, `--quiet`, and `--verbose` flags must precede
+`context`.
+
+## Generic API routes
+
+The `api` namespace exposes control-plane routes from the versioned OpenAPI
+snapshot bundled with the CLI. It supplements the stable high-level commands;
+those commands and their handlers remain registered in Python.
+
+List routes, inspect one operation, validate a dry run, and execute it:
+
+```bash
+polygres api routes
+polygres --json api routes --method GET
+polygres --json api request /projects/{project_id} --method GET --schema
+polygres --json --project <project-id> api request /projects/{project_id} \
+  --method GET \
+  --dry-run
+polygres --json api request /projects \
+  --method POST \
+  --body '{"name":"Support Search"}'
 ```
 
+Use repeatable `--param NAME=VALUE` options for declared path and query
+parameters. Prefix an ambiguous name with `path:`, `query:`, or `header:`.
+Use `--body-file <path>` for a UTF-8 JSON document, or `--body-file -` to read
+one from standard input.
+
+Only route templates and HTTP methods in the bundled snapshot can execute.
+Full URLs, query strings in the route argument, undeclared parameters,
+unsupported methods, unsafe path values, and bodies that do not satisfy the
+declared JSON schema are rejected before a request is sent.
+
+## CLI notices
+
+After a command succeeds, the CLI checks the configured Polygres API for
+applicable service and release notices. Notice text is written only to standard
+error, so standard output and `--json` remain safe for automation. The response
+is cached for up to 10 hours at `~/.config/polygres/notices.json`. Running
+`polygres --version` forces a conditional refresh, and `polygres notices`
+refreshes and displays all currently applicable notices regardless of their
+normal `once` or `daily` display policy.
+
+The check uses a two-second timeout and never changes a command's exit status.
+Network failures, offline operation, malformed responses, and an unavailable
+notice service are silent. Requests go only to the fixed `/cli/notices` path at
+the configured Polygres API origin. The CLI sends its version, derived release
+channel, operating system, and architecture for targeting. It does not send
+command arguments or command output.
+
+Remote notices are plain text. The CLI strips control and ANSI characters,
+limits title and message lengths, accepts only validated HTTPS links, and uses
+a fixed local renderer. Notices cannot define commands, handlers, formatting,
+or endpoints.
+
 Run `polygres --help` for the full command reference. Exit codes distinguish
 validation (`2`), authentication (`3`), permission (`4`), not found (`5`),
 conflict (`6`), rate limiting (`7`), remote availability (`8`), and missing
@@ -57,3 +149,5 @@ control-plane client and does not require the SDK.
 
 Users of the former combined `polygres` package should install `polygres-cli`
 and `polygres-sdk` separately.
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes.

SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Reporting a vulnerability
 
-Report suspected vulnerabilities privately by emailing support@evokoa.com.
+Report suspected vulnerabilities privately by emailing support@polygres.com.
 Include the affected CLI version, a clear description, reproduction steps, and
 known impact. Do not open a public issue for a security vulnerability.
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "polygres-cli"
-version = "0.1.2"
+version = "0.2.0"
 description = "Command-line interface for Polygres"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -9,7 +9,7 @@ authors = [
   { name = "Polygres" }
 ]
 maintainers = [
-  { name = "Polygres", email = "support@evokoa.com" }
+  { name = "Polygres", email = "support@polygres.com" }
 ]
 keywords = ["polygres", "postgres", "postgresql", "cli"]
 classifiers = [
@@ -26,7 +26,7 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14"
 ]
-dependencies = ["httpx>=0.28.1"]
+dependencies = ["httpx>=0.28.1", "pydantic>=2.7,<3"]
 
 [project.scripts]
 polygres = "polygres_cli.cli:main"
@@ -35,6 +35,7 @@ polygres = "polygres_cli.cli:main"
 Homepage = "https://polygres.com"
 Documentation = "https://docs.evokoa.com/polygres"
 Repository = "https://github.com/Evokoa/polygres-cli"
+Changelog = "https://github.com/Evokoa/polygres-cli/blob/main/CHANGELOG.md"
 Issues = "https://github.com/Evokoa/polygres-cli/issues"
 Support = "https://polygres.com"
 

src/polygres_cli/_vendor/__init__.py

@@ -0,0 +1 @@
+"""Generated private dependencies. Do not edit by hand."""

src/polygres_cli/_vendor/polygres_lib/__init__.py

@@ -0,0 +1 @@
+"""Generated private subset of polygres-lib. Do not edit by hand."""

src/polygres_cli/_vendor/polygres_lib/auth/__init__.py

@@ -0,0 +1,41 @@
+"""Generated private auth subset. Do not edit by hand."""
+
+from ..core.types import SecretCredential
+from .api_keys import ProjectApiKeyService
+from .errors import (
+    AUTH_ERROR_CATALOG,
+    AuthError,
+    AuthErrorCode,
+    AuthErrorDescriptor,
+    PolygresError,
+)
+from .models import (
+    CliClientInfo,
+    CliLoginPollApproved,
+    CliLoginPollRequest,
+    CliLoginPollResponse,
+    CliLoginStartRequest,
+    CliLoginStartResponse,
+    CliSessionRefreshRequest,
+    CliSessionRefreshResponse,
+    CliSessionRevokeRequest,
+)
+
+__all__ = [
+    "AUTH_ERROR_CATALOG",
+    "AuthError",
+    "AuthErrorCode",
+    "AuthErrorDescriptor",
+    "CliClientInfo",
+    "CliLoginPollApproved",
+    "CliLoginPollRequest",
+    "CliLoginPollResponse",
+    "CliLoginStartRequest",
+    "CliLoginStartResponse",
+    "CliSessionRefreshRequest",
+    "CliSessionRefreshResponse",
+    "CliSessionRevokeRequest",
+    "PolygresError",
+    "ProjectApiKeyService",
+    "SecretCredential",
+]