v0.156.1
Release plain 0.156.1
2f1c4ad
·
1d ago
plain-dev changelog
0.66.0 (2026-08-02)
What's changed
- Per-checkout state now lives outside the working tree, keyed by the checkout's resolved path under
~/.cache/plain/checkouts/<name>-<hash>/. The database pointer (plain db use), the cached Postgres URL, and the dev/services pidfiles all moved there from .plain/dev/. A working tree is exactly what gets symlinked, copied, or mounted into containers — state keyed by location was eventually read by the wrong reader, so two checkouts sharing a .plain/ could silently share a database or block each other's dev server. .plain/ now holds only rebuildable artifacts: logs, compiled assets, certificates. (737707b6f7)
- New
plain.dev.state module centralizes the definitions of "this checkout" (checkout_id), where its facts live (checkout_state_path), and find_project_root (moved from postgres.identity), so the CLI, setup(), and the supervisors can't disagree about which checkout they're in. (737707b6f7)
Upgrade instructions
- No changes required. Existing
.plain/dev/ pointer and cache files are simply ignored in their old location — if you had repointed a checkout with plain db use, run it once more to re-record the pointer in the new location.
0.65.0 (2026-07-22)
What's changed
- The downloaded
mkcert binary now lives in the machine-level cache at ~/.cache/plain/mkcert/ instead of ~/.plain/dev/, alongside the other cached tool binaries. (This only applies when mkcert isn't already installed system-wide.) (0cc0500f63)
- The mkcert download now writes to a temporary file and atomically moves it into place, so an interrupted download can't leave a partial binary that later fails to execute. (0cc0500f63)
- The
p alias prompt marker moved from ~/.plain/dev/.alias_prompted to the cache directory as well. (0cc0500f63)
MkcertManager.setup_mkcert() no longer takes an install_path argument — the cache location is now fixed. (0cc0500f63)
- The shipped
plain-dev agent rule now documents that .plain/ is disposable per-checkout state and must never be symlinked or shared between checkouts — shared pid files block plain dev, and shared assets or db pointers cross-contaminate. With binaries cached machine-wide and worktree databases forked automatically, there's nothing left in .plain/ worth sharing. (0cc0500f63)
Upgrade instructions
- No changes required.
mkcert re-downloads to the new location on the next plain dev; ~/.plain/dev/mkcert can be deleted. You will be prompted about the p alias once more, since the marker file moved.
0.64.0 (2026-07-21)
What's changed
- Managed development databases. When
plain.postgres is installed and no database URL is configured, plain.dev now provides Postgres automatically — one server per project (Docker if available, otherwise a compatible local Postgres on 127.0.0.1:5432) and one database per checkout, created and migrated on plain dev. Setting PLAIN_POSTGRES_URL (or POSTGRES_URL in settings) means "use this" and turns all of it off. (94f30fc73e, 977fed7576, 6328f19902)
- A database per checkout, forked with data. Each checkout's database is derived from its directory name, so worktrees never share data, and a new worktree's database starts as a copy of the project's main database — data included — using
CREATE DATABASE ... TEMPLATE when the source is idle, or a streaming dump/restore when it's busy. Test databases derive from the checkout's name too, so parallel test runs don't collide. (977fed7576)
- New
plain db command group for managing the databases: status, list, fork, use, create, reset, drop, clean (drop databases whose checkout is gone), and url (script-safe, prints only the URL). status and list take --json. Server lifecycle is handled by plain db server list|stop|remove. (977fed7576, 6328f19902)
- Branch-awareness guards. Sharing one database across checkouts via
plain db use is supported — if plain dev sees branch-only migrations about to hit a shared database, it forks a private copy instead and says so. After a branch switch, a database carrying tables from migrations the branch doesn't have is reported rather than silently mismatched. (6328f19902)
- The managed server is configurable via
[tool.plain.dev.postgres] in pyproject.toml: backend = "auto" | "docker" | "local" | "off" and image for any Postgres image (e.g. pgvector/pgvector:pg16). Data lives in a Docker named volume, never inside the checkout. (6328f19902)
plain dev backups has been removed. Forks are the everyday safety copy (plain db fork), and for a file backup, pg_dump -Fc "$(plain db url)" works directly. The automatic pre-migration backup is gone with it. (6328f19902)
- The shipped agents rule now covers dev databases and tells agents to prefer the tunnel URL (when one is running) for browser navigation and screenshots. (8f6dd0d67e, 74a9daf75d)
Upgrade instructions
- If you ran Postgres as a
[tool.plain.dev.services] entry (e.g. the previously recommended Docker command), you can delete that service and let plain.dev manage Postgres instead — or keep your setup by leaving PLAIN_POSTGRES_URL/POSTGRES_URL configured, which disables the managed database entirely.
- If you used
plain dev backups, switch to plain db fork for quick safety copies or pg_dump -Fc "$(plain db url)" > myapp.backup for file backups. Existing .plain/backups/ files are untouched but no longer managed.
- The managed database features require plain-postgres 0.112.0+ (they use its new cluster-level database helpers) — upgrade both packages together.
0.63.2 (2026-07-15)
What's changed
plain dev now prints the server URL (and the tunnel URL, when running) as plain log lines at startup, in addition to the status bar — so the URLs are visible in piped output and the dev log file, where the status bar isn't. (c3f47658cb)
- Dropped the unused
inotify and requests dependencies from plain.dev. (66dde7d39d, 17570d71cf)
Upgrade instructions
0.63.1 (2026-06-08)
What's changed
plain dev single-instance locking reworked to be crash-safe. Instead of writing a pidfile and trusting whatever it says, the supervisor now holds an exclusive advisory flock on the pidfile for its entire lifetime. A second plain dev (or plain dev services) fails to take the lock and exits with the "already running" notice, and the kernel drops the lock automatically when the holder exits — so a killed or crashed supervisor no longer leaves a stale pidfile that wrongly blocks the next start. The pid is still recorded so --stop can find and signal the running process, but the lock (not the pid) is what prevents duplicates; --stop now only signals when a live owner actually holds the lock, so it can't kill an unrelated process that happened to reuse the pid. (0d5e8ed95f)
- Internal: renamed
ProcessManager → Supervisor, DevProcess → DevSupervisor, and ServicesProcess → ServicesSupervisor.
Upgrade instructions
0.63.0 (2026-05-21)
What's changed
plain.dev now owns all dotenv code. The bash-compatible parser (load_dotenv, parse_dotenv) moved here from plain.utils.dotenv, joined by a new ladder loader (load_dotenv_files). Production deployments without plain.dev installed no longer ship any dotenv code. (9932738450)
- New Next.js / Vite–style
.env precedence ladder. Files load in this order (first to bind a key wins): .env.{PLAIN_ENV}.local, .env.local, .env.{PLAIN_ENV}, .env. Under PLAIN_ENV=test, .env.local is skipped so CI runs stay deterministic. (9932738450)
PLAIN_ENV is auto-set by the CLI dispatcher in plain.cli.core — plain dev → dev, plain test → test — so the right .env.{env}* files load without users having to export PLAIN_ENV themselves. Export it yourself to override (e.g., PLAIN_ENV=staging plain shell). Requires plain>=0.147.0. (9932738450)
PLAIN_ENV values are validated against ^[a-zA-Z][a-zA-Z0-9_-]*$, so typos like PLAIN_ENV=staging/prod fail fast with a clear error instead of silently loading nothing.
- Load notices ("Loading .env.test...") now go to stderr instead of stdout, so commands like
plain preflight --format json keep stdout clean for parsing. The loader is idempotent within a process.
Upgrade instructions
- If you imported
load_dotenv or parse_dotenv from plain.utils.dotenv, switch to from plain.dev.dotenv import load_dotenv, parse_dotenv.
- If you relied on
PLAIN_ENV=prod loading only .env.prod (the old behavior loaded a single file), the new ladder also loads .env.local and .env as baselines. Either gitignore .env.local and move dev-only values out of .env, or stop using a PLAIN_ENV value on machines where you didn't intend the local/baseline files to apply.
0.62.0 (2026-05-12)
What's changed
plain pre-commit now invokes plain assets compile (renamed from plain assets build — see plain-assets 0.3.0). Pins plain.assets>=0.3.0. (3b30b62309)
Upgrade instructions
- No changes required if you upgrade
plain.assets to 0.3.0+ in the same step.
0.61.0 (2026-05-12)
What's changed
plain pre-commit now runs plain assets build instead of plain build (which has been removed from plain core in 0.142.0 and now lives in the new plain.assets package). (844f46e428)
- Adds explicit
plain.assets>=0.1.0,<1.0.0 and bumps the plain minimum to >=0.142.0,<1.0.0 to match.
Upgrade instructions
- Install
plain.assets if you don't already — plain pre-commit needs it for the build step. See the plain 0.142.0 release notes for the full migration.
0.60.4 (2026-05-05)
What's changed
- Exposes
__version__ from importlib.metadata on plain.dev for version probes that don't want to scrape pip metadata. (c6cf6edb)
Upgrade instructions
0.60.3 (2026-04-23)
What's changed
PostgresBackupClient now imports postgres_cli_args / postgres_cli_env lazily inside its methods so projects without plain.postgres installed can still load plain.dev without an ImportError. (0583d1da5602)
Upgrade instructions
0.60.2 (2026-04-22)
What's changed
- Moved the backup client's psql connection-argument and environment construction onto the shared
postgres_cli_args / postgres_cli_env helpers in plain.postgres.database_url, so plain dev backups and plain postgres shell build their psql/pg_dump invocations from the same place. (5b4a488)
Upgrade instructions
0.60.1 (2026-04-13)
What's changed
- Migrated type suppression comments to
ty: ignore for the new ty checker version. (4ec631a7ef51)
Upgrade instructions
0.60.0 (2026-03-29)
What's changed
- Database backups moved here from
plain-postgres. Available as plain dev backups (list, create, restore, delete, clear). Backups are automatically created before syncing when pending changes are detected. (50773a50f674)
- Dev server now uses
postgres sync instead of migrate --backup. Creates a backup first if sync would make changes, then runs sync (migrations + convergence) in one step. (adf021688bf3)
Upgrade instructions
- If you used
plain postgres backups, use plain dev backups instead. Requires plain>=0.130.0.
0.59.2 (2026-03-25)
What's changed
- Updated internal references from
plain db to plain postgres to match the CLI rename — affects the database wait command during plain dev startup and the auto-start services list (a639aeacbf8d)
Upgrade instructions
0.59.1 (2026-03-16)
What's changed
- Fixed Ctrl+C shutdown reliability — a second Ctrl+C now forces immediate shutdown instead of being ignored, and the kill-after-timeout logic no longer races with the initial terminate signal (a96bd2a9563e)
Upgrade instructions
0.59.0 (2026-03-12)
What's changed
- Updated database availability check from
plain.models to plain.postgres spec detection.
Upgrade instructions
0.58.4 (2026-03-10)
What's changed
- Renamed env vars to avoid preflight settings warnings:
PLAIN_DEV_SERVICES_AUTO → DEV_SERVICES_AUTO, PLAIN_DEV_URL → DEV_URL, and removed the unused PLAIN_DEV variable (4ce989e42ece)
Upgrade instructions
- If you reference
PLAIN_DEV_URL in custom dev process commands (e.g. pyproject.toml [tool.plain.dev.run]), rename it to DEV_URL.
- If you check
PLAIN_DEV_SERVICES_AUTO, rename it to DEV_SERVICES_AUTO.
0.58.3 (2026-03-10)
What's changed
- Removed redundant "Pre-commit Checks" section from AI rules (772345d4e1f1)
Upgrade instructions
0.58.2 (2026-03-10)
What's changed
- Fixed
AliasManager.is_installed_in_shell() crashing when self.shell is None (f56c6454b164)
- Used
signal.Signals enum for signal name lookup in poncho manager instead of raw int keys (f56c6454b164)
Upgrade instructions
0.58.1 (2026-03-04)
What's changed
- Added minimum
plain>=0.113.0 version constraint in dependencies (217751b866)
Upgrade instructions
0.58.0 (2026-03-04)
What's changed
- Dev server now sets
PLAIN_SERVER_ACCESS_LOG_FIELDS to show a compact set of fields (method, url, status, duration_ms, size) by default (72a905fbe1c3)
- Removed logging CLI options (
--log-level, --log-format, --access-log-format) from dev server invocation, matching the server's new settings-based configuration (d00dc098b32d)
Upgrade instructions
- Requires plain >= 0.113.0.
0.57.1 (2026-02-28)
What's changed
- Fixed dev server crash on macOS where Tailwind would exit immediately after compiling instead of watching for changes, bringing down all other processes (5b7db81a43da)
Upgrade instructions
0.57.0 (2026-02-28)
What's changed
plain dev no longer prompts for sudo to modify /etc/hosts on systems where *.localhost already resolves to loopback (e.g., modern macOS and Linux with systemd-resolved) (a97e244091)
Upgrade instructions
0.56.0 (2026-02-25)
What's changed
- Renamed
PLAIN_DEV_TUNNEL_URL environment variable to DEV_TUNNEL_URL for displaying the tunnel URL in the dev server header (6154e6ef8693)
- Removed unused
default_settings.py (73a51a723c64)
Upgrade instructions
- Rename
PLAIN_DEV_TUNNEL_URL to DEV_TUNNEL_URL in your .env file.
0.55.1 (2026-02-24)
What's changed
- Dev server now explicitly passes
--workers 1 to keep single-process behavior after the core server default changed to auto (c38ee93de5b4)
Upgrade instructions
0.55.0 (2026-02-12)
What's changed
- Refactored pre-commit to use the new
plain check command, removing duplicated check logic (430268a12ae2)
- Custom pre-commit commands configuration moved from
tool.plain.pre-commit.run to tool.plain.check.run in pyproject.toml (430268a12ae2)
Upgrade instructions
- If you have custom commands in
[tool.plain.pre-commit.run], move them to [tool.plain.check.run].
0.54.2 (2026-01-28)
What's changed
- Converted
plain-dev and plain-pre-commit skills to a single passive .claude/rules/ file (512040ac51)
Upgrade instructions
- Run
plain agent install to update your .claude/ directory.
0.54.1 (2026-01-28)
What's changed
- Added
dev to the service auto-start allow-list so that database services start automatically when running plain dev, which runs preflight checks internally (4b146a0ae2)
- Added Settings section to README (803fee1ad5)
Upgrade instructions
0.54.0 (2026-01-22)
What's changed
- The development server now shows
DeprecationWarning and PendingDeprecationWarning messages by default, helping you catch deprecated code before it breaks in future versions. You can override this by setting your own PYTHONWARNINGS environment variable. (2ca42c6f96)
Upgrade instructions
0.53.0 (2026-01-15)
What's changed
- Service auto-start now uses an allow-list instead of deny-list, only starting services for commands that need the database (
db, makemigrations, migrate, migrations, preflight, request, run, shell, test) (0b11c79656)
- The
plain dev command now runs plain agent install instead of plain skills --install to set up AI agent skills and hooks (fac8673436)
Upgrade instructions
0.52.0 (2026-01-15)
What's changed
- Removed the
plain dev debug command and custom remote pdb debugger since Python 3.14 provides native remote debugging via python -m pdb -p <pid> (db19b5ef00)
- Replaced
python-dotenv dependency with a custom bash-compatible .env parser that supports variable expansion ($VAR), command substitution ($(command)), and multiline values (a9b2dc3e16)
Upgrade instructions
- If you were using
plain dev debug for remote debugging, use Python's native python -m pdb -p <pid> command instead
0.51.0 (2026-01-13)
What's changed
- Dev services auto-start now runs via the runtime setup hook instead of at CLI load time, which prevents services from starting unnecessarily for commands that don't need the runtime like
plain code, plain fix, and plain scan (fc1c8624b6)
- Added new
plain-pre-commit skill for AI assistants to run pre-commit checks when finishing code changes (d51294ace1)
- Renamed the
plain-check skill to plain-lint to better describe its purpose (d51294ace1)
- Pre-commit install now uses
uv run plain instead of just plain for better environment consistency (8104c9b29f)
Upgrade instructions
0.50.0 (2026-01-13)
What's changed
- Added
--reinstall-ssl flag to plain dev command that redownloads the mkcert binary, reinstalls the CA into the system trust store, and regenerates domain certificates (04579b74d7)
- Fixed mkcert CA detection to check for CA file existence instead of using the non-existent
mkcert -check command (04579b74d7)
- Improved migration output during
plain dev startup - now shows "✔ Up to date" when no migrations are needed, or "applying" when migrations are being run (006efae92d)
- Converted package-specific AGENTS.md to skills system -
plain dev now installs skills to .claude/agents/ instead of generating .plain/AGENTS.md (b592c32cb9)
Upgrade instructions
0.49.1 (2025-12-22)
What's changed
- Updated type ignore comments for improved compatibility with the ty type checker (539a706760)
Upgrade instructions
0.49.0 (2025-12-04)
What's changed
- Improved type annotations in
mkcert.py and pdb.py for better type checker compatibility (ac1eeb0ea0)
Upgrade instructions
0.48.0 (2025-12-01)
What's changed
- Pre-commit checks now preserve colored output from subprocesses by setting
FORCE_COLOR=1 (a56158394b)
- Simplified and streamlined the pre-commit check output formatting for improved readability (b09edfd2a1)
Upgrade instructions
0.47.1 (2025-11-17)
What's changed
- The
plain pre-commit install command is now a separate subcommand that uses @without_runtime_setup to avoid loading the full Plain runtime, improving performance and reliability during installation (cfa4ed2)
Upgrade instructions
- Update any scripts or documentation that use
plain pre-commit --install to use plain pre-commit install instead
0.47.0 (2025-11-12)
What's changed
- Fixed type errors and warnings for improved type checker compatibility (f4dbcef)
Upgrade instructions
0.46.0 (2025-11-10)
What's changed
- The
plain dev command now separates stdout and stderr output with distinct visual indicators - stderr uses a red pipe (┃) while stdout uses a dimmed pipe (|) to make error messages more visible (ea78a6d)
- The
FORCE_COLOR environment variable is now automatically set in the development server and services to ensure consistent color output across all processes (2a63270)
Upgrade instructions
0.45.1 (2025-11-03)
What's changed
- Fixed the database wait command call in the dev server startup to use the updated
plain db wait command instead of the deprecated plain models db-wait (b293750)
- Fixed the pre-commit database connection check to use the updated
plain migrations list command instead of the deprecated plain models show-migrations (b293750)
Upgrade instructions
0.45.0 (2025-11-03)
What's changed
- The
plain dev command now automatically generates and persists .plain/AGENTS.md during startup, ensuring AI coding assistants have up-to-date package documentation (786b7a0)
- CLI command descriptions have been updated to be more concise and consistent across all
plain dev subcommands (fdb9e80)
- The
plain dev command is now marked as a "common command" in the CLI for better discoverability (73d3a48)
Upgrade instructions
0.44.0 (2025-10-29)
What's changed
- The
plain preflight check command has been simplified back to plain preflight throughout the development workflow, including pre-commit hooks and the dev server startup (40c2c45)
Upgrade instructions
0.43.1 (2025-10-27)
What's changed
- The
plain precommit command output has been redesigned with improved styling and clearer labels for each check that runs (b45011c)
Upgrade instructions
0.43.0 (2025-10-22)
What's changed
- The
plain contrib command now uses @without_runtime_setup decorator to avoid loading the full Plain runtime, improving performance and reliability (8b8cc2d)
- Removed the standalone
plain-contrib command-line script as it is no longer needed with the runtime setup improvements (8b8cc2d)
Upgrade instructions
0.42.0 (2025-10-13)
What's changed
- The development server now uses
watchfiles for file watching and auto-reloading instead of gunicorn's built-in reloader, providing more reliable and efficient file change detection (92e95c5032)
- Removed manual
.env file watching configuration from plain dev as this is now handled automatically by the server's reloader (92e95c5032)
Upgrade instructions
0.41.0 (2025-10-12)
What's changed
- The
plain dev command now uses the new plain server command instead of gunicorn for running the development server (f9dc2867c7)
- Removed
gunicorn as a dependency - the development server now uses Plain's built-in HTTP server (f9dc2867c7)
- Removed gunicorn-specific logging configuration file in favor of simplified log formatting (fb8a00ca73)
Upgrade instructions
0.40.0 (2025-10-10)
What's changed
- Updated documentation to reference
plain-jobs instead of the deprecated plain-worker package name (24219856e0)
Upgrade instructions
0.39.1 (2025-10-06)
What's changed
- Added comprehensive type annotations across the entire package to improve IDE support and type checking (1d00e9f)
Upgrade instructions
0.39.0 (2025-09-30)
What's changed
- The
plain dev command now sets both PLAIN_LOG_LEVEL and PLAIN_FRAMEWORK_LOG_LEVEL environment variables when a log level is specified, replacing the previous APP_LOG_LEVEL setting (4c5f216)
Upgrade instructions
0.38.0 (2025-09-30)
What's changed
- Added an
AGENTS.md file with package-specific agent instructions for the plain dev logs command (5841a3f)
Upgrade instructions
0.37.0 (2025-09-29)
What's changed
- Added a
p alias prompt that suggests setting up a shell alias for uv run plain to make command execution faster (d913b44, 6632529)
Upgrade instructions
0.36.0 (2025-09-25)
What's changed
- The
plain preflight command has been updated to use plain preflight check with a --quiet flag for cleaner output in development workflows (b0b610d)
- Pre-commit hooks now use the updated preflight check syntax (b0b610d)
Upgrade instructions
0.35.0 (2025-09-22)
What's changed
- Removed automatic
PLAIN_ALLOWED_HOSTS configuration from the dev server as this is now handled by the core Plain framework (d3cb771)
Upgrade instructions
0.34.0 (2025-09-19)
What's changed
- Minimum Python version requirement increased from 3.11 to 3.13 (d86e307)
Upgrade instructions
- Upgrade your Python environment to Python 3.13 or later
0.33.3 (2025-09-03)
What's changed
- Added retries to background service startup to improve reliability when services take longer to initialize (e2b3a42)
Upgrade instructions
0.33.2 (2025-08-22)
What's changed
- The development localhost hostname is now automatically lowercased when generated from the pyproject.toml name (4454f01)
- Updated README with improved structure, table of contents, and better installation instructions (4ebecd1)
Upgrade instructions
0.33.1 (2025-07-18)
What's changed
- Dev services are no longer automatically started when running in CI environments unless explicitly enabled with
PLAIN_DEV_SERVICES_AUTO=true (b8452bae74)
- The
plain dev logs command now skips automatic service startup to avoid conflicts (ff65428bca)
Upgrade instructions
0.33.0 (2025-07-18)
What's changed
- Added automatic background startup of dev services when running
plain dev commands. Services defined in pyproject.toml will now start automatically (0a5ffc6de5).
- Added
plain dev logs command to view output from recent plain dev runs. Supports options like --follow, --pid, --path, and --services to manage and view different log outputs (0a5ffc6de5).
- Added
--start and --stop flags to both plain dev and plain dev services commands for running processes in the background. Use plain dev --start to launch the dev server in background mode and plain dev --stop to terminate it (0a5ffc6de5).
- Improved process management with better PID tracking and graceful shutdown handling for both dev server and services (0a5ffc6de5).
- Improved CLI error handling by using
click.UsageError instead of manual error printing and sys.exit() (88f06c5184).
- Removed
psycopg[binary] dependency from plain-dev as database drivers should be installed separately based on project needs (63224001c9).
Upgrade instructions
0.32.1 (2025-06-27)
What's changed
- Fixed an error when running
plain dev precommit (or the plain precommit helper) that passed an extra default argument to plain preflight --database. The flag now correctly aligns with the current plain preflight CLI (db65930).
Upgrade instructions
0.32.0 (2025-06-23)
What's changed
plain dev now writes a PID file and will refuse to start if it detects that another plain dev instance is already running in the same project (75b7a50).
- When no
--port is provided, plain dev now checks if port 8443 is available and, if not, automatically selects the next free port. Supplying --port will error if that port is already in use (3f5141f).
- The development request-log UI has been removed for now, along with its related endpoints and templates (8ac6f71).
plain contrib --all skips any installed plainx-* packages instead of erroring when it can’t locate their repository (3a26aee).
Upgrade instructions