release: v0.14.0 — shimkit framework symfony

Sibling framework recipe under the existing `framework` parent.
Modelled on the Laravel recipe (v0.7.0), adjusted for Symfony's
conventions:

  Aspect          Laravel                    Symfony
  ─────────────────────────────────────────────────────────────────
  Writable tree   storage + bootstrap/cache  var
  App secret      APP_KEY=base64:... (32B)   APP_SECRET=<64 hex>
  Env file        .env (refuses overwrite)   .env.local (preserves
                                              the framework .env)
  Console         root-level artisan         bin/console
  Scheduler       schedule:run every minute  no built-in scheduler

Surface (one fewer command than Laravel — no cron-install since
Symfony has no built-in scheduler):

    shimkit framework symfony perms PATH [--group G] (MODERATE)
    shimkit framework symfony env PATH
        [--name N] [--env E] [--db D] (MODERATE)
    shimkit framework symfony cache-clear PATH [--env E]
    shimkit framework symfony console
        --project PATH [--in-container [--stack NAME]] -- <args>

Application-specific Symfony cron entries go via `shimkit cron
add` directly. If Symfony Scheduler (the messenger-based
approach) gains broad adoption, a cron-install command may land
later.

`env` writes to `.env.local` rather than `.env` because Symfony's
convention is that `.env` ships framework defaults (checked in)
and `.env.local` holds gitignored secrets + per-host tweaks.
APP_SECRET is hex(32) = 64 chars per the Symfony reference.
DATABASE_URL targets shimkit dev DBs by default, with the right
URL prefix + serverVersion query parameter for each engine
(mysql / mariadb / postgres). Pair with `shimkit db <engine> up`
for a working dev setup.

`cache-clear` is a thin wrapper around `php bin/console
cache:clear --env <env>` for the common case. `console` is the
generic passthrough for everything else.

Implementation:

- New `tools/framework/symfony/` sub-tree (manager + commands +
  __init__) mirroring `tools/framework/laravel/`.
- `framework_app` registers `symfony_app` alongside `laravel_app`.
  Sub-app surface unchanged for Laravel users.
- `FrameworkSymfonyConfig` pydantic model + corresponding
  `tools.framework.symfony` defaults.json block with `web_group`,
  `file_mode`, `dir_mode`, `writable_dirs`, `default_env`.

Tests: 26 new in test_tools_framework_symfony.py (1044 → 1070
total). Platform gating, perms (path refusal / dry-run / var/
targeting / chgrp skip on missing group / --group override /
failed-step JSON), env (overwrite refusal / 64-hex APP_SECRET /
default APP_ENV / --env override / DATABASE_URL shape for all
three DB engines / dry-run no-write / uniqueness across
scaffolds), console (host happy path / missing-php exits 69 /
no-args refusal / missing-bin/console refusal / --in-container
delegates to StackManager), cache-clear (runs console with
--env=<env>), command surface (framework --help lists both
recipes; symfony --help lists all four subcommands).

Gates: pytest 1070 passed, ruff clean, mypy strict clean. No new
optional dependency extras.

Author: imanimanyara

CHANGELOG.md

@@ -6,6 +6,60 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.14.0] — 2026-05-16
+
+### Added
+
+- `shimkit framework symfony` — sibling framework recipe under the
+  existing `framework` parent. Four commands:
+  - `perms PATH [--group G]` (MODERATE) — cross-distro group
+    detection (same chain as Laravel: `getent` / `dscl` / `grp`);
+    targets `var/` rather than Laravel's `storage` +
+    `bootstrap/cache`.
+  - `env PATH [--name N] [--env E] [--db D]` (MODERATE) —
+    scaffolds `.env.local` with a generated `APP_SECRET`
+    (hex(32) — Symfony's documented form). Refuses to overwrite
+    an existing file. `DATABASE_URL` targets shimkit dev DBs
+    by default; supports mysql / mariadb / postgres.
+  - `cache-clear PATH [--env E]` — wraps `php bin/console
+    cache:clear --env <env>`. Defaults to `dev`.
+  - `console -- <args>` — passthrough to `php bin/console`. Host
+    execution by default; `--in-container` routes through
+    `shimkit stack lemp`.
+
+  Symfony has no built-in scheduler like Laravel's
+  `schedule:run`, so there's no `cron-install` command —
+  application-specific cron entries go via `shimkit cron add`
+  directly.
+
+- `tools.framework.symfony` config block with the same shape as
+  `tools.framework.laravel` plus a `default_env` field (`dev` /
+  `test` / `prod`).
+
+### Tests
+
+- 26 new tests in `tests/test_tools_framework_symfony.py` (1044 →
+  1070 total). Platform gating, perms (path refusal / dry-run /
+  var/ targeting / chgrp skip on missing group / --group override
+  / failed-step JSON output), env scaffold (overwrite refusal /
+  APP_SECRET 64-hex-char shape / default APP_ENV / `--env`
+  override / DATABASE_URL for all three DB engines including
+  serverVersion query parameter / dry-run no-write / uniqueness
+  across two scaffolds), console (host happy path runs `php
+  bin/console` / missing-php exits 69 / no-args refusal / missing-
+  bin/console refusal / --in-container delegates to StackManager),
+  cache-clear (runs console with --env flag), command surface
+  (framework --help lists symfony alongside laravel; symfony
+  --help lists all four subcommands).
+
+### Notes
+
+Second framework recipe under the `framework` parent. Future
+siblings (`rails`, `django`, `nextjs`) follow the same pattern.
+
+Gates: pytest 1070 passed, ruff clean, mypy strict clean. No new
+optional dependency extras.
+
 ## [0.13.0] — 2026-05-16
 
 ### Added

docs/README.md

@@ -58,6 +58,9 @@ shimkit is a collection. Each tool gets its own page:
 - **[`shimkit framework laravel`](tools/framework-laravel.md)** —
   Laravel helpers: perms, `.env` scaffold, scheduler cron-install,
   artisan passthrough (host or LEMP container).
+- **[`shimkit framework symfony`](tools/framework-symfony.md)** —
+  Symfony helpers: perms (`var/`), `.env.local` scaffold with
+  `APP_SECRET`, cache-clear, `bin/console` passthrough.
 
 Top-level utilities (not tools):
 
@@ -91,6 +94,8 @@ Top-level utilities (not tools):
 
 Per-version, user-facing summaries (newest first):
 
+- **[`v0.14.0`](release-notes/v0.14.0.md)** — `shimkit framework
+  symfony` sibling recipe under the `framework` parent.
 - **[`v0.13.0`](release-notes/v0.13.0.md)** — `shimkit tls --method
   dns-cloudflare` for DNS-01 + wildcard certs.
 - **[`v0.12.0`](release-notes/v0.12.0.md)** — stale-doc cleanup +

docs/release-notes/v0.14.0.md

@@ -0,0 +1,117 @@
+# shimkit 0.14.0
+
+`shimkit framework symfony` — sibling recipe under the existing
+`framework` parent. Modelled on Laravel (v0.7.0); adjusted for
+Symfony's conventions.
+
+For the full machine-readable changelog, see
+[`CHANGELOG.md`](../../CHANGELOG.md).
+
+---
+
+## TL;DR
+
+```
+shimkit framework symfony perms PATH [--group G]              # MODERATE
+shimkit framework symfony env PATH [--name N] [--env E] [--db D]  # MODERATE
+shimkit framework symfony cache-clear PATH [--env E]
+shimkit framework symfony console -- <args>
+```
+
+Same shape as `framework laravel`, swapping in Symfony's
+conventions: writable `var/` (not `storage/` + `bootstrap/cache`),
+`APP_SECRET` hex (not `APP_KEY` base64), `bin/console` (not root
+`artisan`).
+
+---
+
+## Differences from Laravel
+
+| Aspect | Laravel (v0.7.0) | Symfony (v0.14.0) |
+|--------|------------------|-------------------|
+| Writable tree | `storage/` + `bootstrap/cache/` | `var/` |
+| App secret | `APP_KEY=base64:...` (32 bytes) | `APP_SECRET=...` (hex(32) = 64 chars) |
+| Env file | `.env` (gitignored typically) | `.env.local` (gitignored by convention; framework defaults stay in `.env`) |
+| Console binary | root-level `artisan` | `bin/console` |
+| Scheduler | `php artisan schedule:run` every minute | No built-in scheduler — use `shimkit cron add` directly |
+
+The Symfony recipe is **smaller by one command** (no `cron-install`)
+because Symfony doesn't ship a scheduler analogous to Laravel's.
+
+---
+
+## `env` shape
+
+`.env.local` is the gitignored override file; the framework-shipped
+`.env` is preserved. Default contents:
+
+```ini
+# Symfony local environment overrides (gitignored).
+# Framework defaults live in .env; secrets and per-host
+# tweaks belong here.
+
+APP_ENV=dev
+APP_SECRET=<64 hex chars>
+
+DATABASE_URL="mysql://root:shimkit-dev@127.0.0.1:13306/<dirname>?serverVersion=8.0"
+
+# Mailer — defaults to in-memory; override in prod.
+MAILER_DSN=null://null
+```
+
+`DATABASE_URL` is engine-aware:
+
+```bash
+shimkit framework symfony env --yes --db mysql ./my-app
+# →  mysql://root:shimkit-dev@127.0.0.1:13306/my-app?serverVersion=8.0
+
+shimkit framework symfony env --yes --db postgres ./my-app
+# →  postgresql://root:shimkit-dev@127.0.0.1:15432/my-app?serverVersion=16
+
+shimkit framework symfony env --yes --db mariadb ./my-app
+# →  mysql://root:shimkit-dev@127.0.0.1:13307/my-app?serverVersion=mariadb-10.11
+```
+
+Pair with `shimkit db <engine> up` for an end-to-end dev stack.
+
+---
+
+## End-to-end example
+
+```bash
+# 1. Start a database
+shimkit db postgres up
+
+# 2. Create / clone the Symfony project at ./my-app
+
+# 3. Scaffold env + fix perms
+shimkit framework symfony env  --yes --db postgres ./my-app
+shimkit framework symfony perms --yes ./my-app
+
+# 4. Run migrations + clear cache
+shimkit framework symfony console --project ./my-app \
+    -- doctrine:database:create
+shimkit framework symfony console --project ./my-app \
+    -- doctrine:migrations:migrate --no-interaction
+shimkit framework symfony cache-clear --env dev ./my-app
+```
+
+---
+
+## Stats
+
+- Tests: 1044 → 1070 (+26)
+- Gates: pytest, ruff, mypy strict — all green
+- New optional extras: 0
+
+---
+
+## Upgrading
+
+```bash
+uv tool upgrade shimkit
+pipx upgrade shimkit
+```
+
+Laravel users see no behavioural change. To start using the
+Symfony recipe, just invoke `shimkit framework symfony --help`.

docs/tools/framework-symfony.md

@@ -0,0 +1,163 @@
+# shimkit framework symfony
+
+Symfony-specific helpers. Four commands today. Modelled on the
+Laravel recipe — same parent sub-app, same builder pattern, same
+host-or-container console passthrough — adjusted for Symfony's
+conventions: writable `var/` (not `storage/`), `APP_SECRET` hex
+(not `APP_KEY` base64), `bin/console` (not root `artisan`).
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `shimkit framework symfony`                                  | Menu. |
+| `shimkit framework symfony perms PATH [--group G]`           | MODERATE. Fix `var/` permissions. |
+| `shimkit framework symfony env PATH [--name N] [--env E] [--db D]` | MODERATE. Scaffold `.env.local` with a generated `APP_SECRET`. |
+| `shimkit framework symfony cache-clear PATH [--env E]`       | Wraps `php bin/console cache:clear --env <env>`. |
+| `shimkit framework symfony console -- <args>`                | Passthrough to `bin/console` — host or LEMP container. |
+
+Universal flags before the subcommand (`--quiet`, `--verbose`,
+`--log-file`, `--no-color`, `--color`, `--no-input`); per-command
+flags after (`--json`, `--dry-run`, `--yes`, `--force`).
+
+## perms
+
+`var/` is the standard Symfony writable tree (covers `cache/`,
+`log/`, `sessions/`). Set `tools.framework.symfony.writable_dirs`
+in your user config to extend (e.g. `["var", "public/uploads"]`).
+
+```bash
+# Default www-data group on Linux
+shimkit framework symfony perms --yes ./my-symfony-app
+
+# macOS-friendly group
+shimkit framework symfony perms --yes --group staff ./my-symfony-app
+
+# Dry-run plan
+shimkit framework symfony perms --dry-run ./my-symfony-app
+
+# JSON (CI / monitoring)
+shimkit framework symfony perms --yes --json ./my-symfony-app
+```
+
+Group detection: `getent group <name>` on Linux, `dscl . -read
+/Groups/<name>` on macOS, `grp.getgrnam()` Python fallback. When
+the group doesn't exist on the host, the global `chmod 664` /
+`chmod 775` passes still run but `chgrp` is skipped (UI.dim
+explains).
+
+## env
+
+Writes `.env.local` with a freshly generated `APP_SECRET`. Symfony's
+convention is that **`.env` (checked in) holds framework defaults**
+and **`.env.local` (gitignored) holds secrets + per-host tweaks**.
+shimkit writes to `.env.local` so the framework-provided `.env`
+stays intact.
+
+`APP_SECRET` is `secrets.token_hex(32)` = 64 hex chars — the
+[Symfony reference](https://symfony.com/doc/current/reference/configuration/framework.html#secret)
+recommends a long random hex.
+
+`DATABASE_URL` defaults target the shimkit dev DBs:
+
+| `--db`     | URL prefix | Port | `?serverVersion=` |
+|------------|------------|-----:|-------------------|
+| `mysql`    | `mysql://`     | 13306 | `8.0`         |
+| `mariadb`  | `mysql://`     | 13307 | `mariadb-10.11` |
+| `postgres` | `postgresql://`| 15432 | `16`          |
+
+```bash
+shimkit db postgres up
+shimkit framework symfony env --yes --db postgres ./my-app
+shimkit framework symfony console --project ./my-app -- doctrine:migrations:migrate
+```
+
+## cache-clear
+
+Wraps `php bin/console cache:clear --env <env>`:
+
+```bash
+shimkit framework symfony cache-clear --env dev ./my-app
+shimkit framework symfony cache-clear --env prod --in-container --stack myapp ./my-app
+```
+
+Default env is `dev` (configurable via
+`tools.framework.symfony.default_env`).
+
+## console
+
+Generic passthrough to `bin/console`. Host execution is the
+default — preflights `php` via `shimkit.core.version.preflight`,
+exits 69 with the remediation hint when `php` is missing.
+`--in-container` routes through `shimkit stack lemp`'s php-fpm
+container.
+
+```bash
+# Host
+shimkit framework symfony console --project ./my-app -- about
+shimkit framework symfony console --project ./my-app -- doctrine:database:create
+
+# Inside a running LEMP stack
+shimkit stack lemp up --project myapp ./my-app
+shimkit framework symfony console \
+    --project ./my-app --in-container --stack myapp \
+    -- doctrine:migrations:migrate
+```
+
+`--project` defaults to the current working directory.
+
+## No cron-install
+
+Symfony doesn't ship a built-in scheduler analogous to Laravel's
+`schedule:run`. Application-specific cron entries can be installed
+via `shimkit cron add` directly:
+
+```bash
+shimkit cron add --yes \
+    --name my-symfony-nightly \
+    --schedule "0 3 * * *" \
+    --cmd "cd /var/www/my-app && php bin/console app:nightly-job >> /dev/null 2>&1"
+```
+
+If Symfony Scheduler (the messenger-based approach) gains broad
+adoption, a `cron-install` command may land later.
+
+## Configuration
+
+```json
+{
+  "tools": {
+    "framework": {
+      "symfony": {
+        "web_group": "www-data",
+        "file_mode": "664",
+        "dir_mode": "775",
+        "writable_dirs": ["var"],
+        "default_env": "dev"
+      }
+    }
+  }
+}
+```
+
+Override `web_group` per host. Add `writable_dirs` entries if your
+app writes outside `var/` (e.g. `public/uploads/`).
+
+## Exit codes
+
+| Code | Meaning |
+|-----:|---------|
+| 0    | success |
+| 1    | bad path, missing `bin/console`, refusing overwrite, prompt cancelled |
+| 2    | Typer usage error |
+| 69   | `EX_UNAVAILABLE` — wrong platform or missing `php` for `console`/`cache-clear` |
+| 130  | SIGINT |
+
+## Platform support
+
+| Platform | Status |
+|----------|--------|
+| macOS    | full. Dev account typically owns the project, so `chgrp` is no-op'd unless `--group` is passed. |
+| Linux    | full. Targets `www-data` by default; override with `--group`. |
+| WSL      | works (Linux path). |
+| Windows  | out of charter (use WSL). |

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shimkit"
-version = "0.13.0"
+version = "0.14.0"
 description = "A toolkit of developer utilities — Java version manager, shell upgrader, and more. Python tools, shimmed by bash."
 readme = "README.md"
 license = { file = "LICENSE" }

src/shimkit/__init__.py

@@ -3,5 +3,5 @@
 Python tools, shimmed by bash.
 """
 
-__version__ = "0.13.0"
+__version__ = "0.14.0"
 __all__ = ["__version__"]

src/shimkit/config/defaults.json

@@ -207,6 +207,13 @@
         "dir_mode": "775",
         "writable_dirs": ["storage", "bootstrap/cache"],
         "default_cron_schedule": "* * * * *"
+      },
+      "symfony": {
+        "web_group": "www-data",
+        "file_mode": "664",
+        "dir_mode": "775",
+        "writable_dirs": ["var"],
+        "default_env": "dev"
       }
     },
     "versions": {