From af757a68fcd0ad098e3e51fcb8265eaf080039a9 Mon Sep 17 00:00:00 2001 From: Andrew Masiye Date: Sat, 5 Sep 2026 15:40:34 +0200 Subject: [PATCH] docs(release): draft Console 0.10.4 notes --- docs/releases/0.10.4.md | 65 +++++++++++++++++++++++++++++++++++++ docs/releases/unreleased.md | 9 ----- 2 files changed, 65 insertions(+), 9 deletions(-) create mode 100644 docs/releases/0.10.4.md delete mode 100644 docs/releases/unreleased.md diff --git a/docs/releases/0.10.4.md b/docs/releases/0.10.4.md new file mode 100644 index 0000000..ccbacc4 --- /dev/null +++ b/docs/releases/0.10.4.md @@ -0,0 +1,65 @@ +# Assegai Console 0.10.4 + +Draft release notes. Publication is pending. + +Console 0.10.4 adds a standalone command for initializing and rotating `APP_SECRET_KEY`, completing the setup flow for cloned Assegai applications. + +## Initialize a cloned project + +Keep `.env.example` in Git with placeholder values and keep each environment's `.env` private. After cloning, run: + +```bash +composer install +assegai key:generate +``` + +The command: + +- creates a missing `.env` from `.env.example` +- initializes a missing, empty, or recognized scaffold-placeholder `APP_SECRET_KEY` +- generates 32 cryptographically random bytes, encoded as 64 hexadecimal characters +- preserves other dotenv settings and leaves `.env.example` unchanged +- writes the key to `.env` without printing it + +The command also works before installing project dependencies. If neither environment file exists, create `.env` first. Use `--directory` (`-d`) to select another workspace: + +```bash +assegai key:generate --directory /path/to/project +``` + +## Rotate an existing key deliberately + +Running `assegai key:generate` with an existing non-placeholder key asks for confirmation. Non-interactive runs refuse replacement unless `--force` is supplied: + +```bash +assegai key:generate --force --no-interaction +``` + +Rotation may invalidate tokens or encrypted data that depend on the old key. Retain the old key where recovery requires it, restart long-running application processes after a change, and use the same key across instances of one environment. Do not regenerate keys on every installation, update, or deployment. + +The command manages a local `.env` file. It does not update secrets injected through the process environment or a secret manager, and it refuses to modify a symlinked `.env`. + +## File handling and project creation + +New `.env` files use owner-only permissions. Updates to existing files preserve their inode, ownership, group, permissions, and access-control metadata. Writes use an exclusive lock and a private recovery copy; if writing fails, the generator attempts to restore the original contents. If restoration also fails, it retains the recovery copy and reports its filename. + +Duplicate key assignments and unterminated quoted values are rejected. The generator also checks for content changes made while confirmation was pending. + +`assegai new` uses the same generator and now reports failure if it cannot create the initial key. Generated-project setup instructions include `key:generate` for subsequent clones. Installation and update hooks do not rotate keys. + +## Compatibility and upgrade + +PHP 8.4+ and Composer 2.x remain required. The generated README now correctly states PHP 8.4+; this corrects the documentation rather than raising the minimum in this patch. Dependency constraints and the existing hexadecimal key format are unchanged from 0.10.3. + +After 0.10.4 is published, update an existing Console 0.10.x global installation and verify its version: + +```bash +assegai global update +assegai --version +``` + +`assegai -g update` is the equivalent shorthand. Existing applications with a valid key do not need to regenerate it when upgrading the CLI. + +## Validation + +The implementation passed 202 tests with 819 assertions and one existing skip, PHPStan level 8, and CI on PHP 8.4 and the latest PHP version. Coverage includes initial generation, confirmation and forced rotation, dotenv formatting, file access metadata, write permissions, and detection of edits during confirmation. The CLI was also exercised against a fresh starter export without installed project dependencies. diff --git a/docs/releases/unreleased.md b/docs/releases/unreleased.md deleted file mode 100644 index f62a103..0000000 --- a/docs/releases/unreleased.md +++ /dev/null @@ -1,9 +0,0 @@ -# Unreleased - -## Application key generation - -`assegai key:generate` initializes or rotates `APP_SECRET_KEY` independently of project creation. It creates a missing `.env` from `.env.example`, generates a 32-byte random key encoded as 64 hexadecimal characters, and preserves other dotenv settings. The generated key is never printed. - -Existing non-placeholder keys require interactive confirmation or `--force`. Use `--directory` (`-d`) to select a workspace. Rotation may invalidate tokens or encrypted data that depend on the old key; restart long-running application processes after a change. Instances of the same environment must share a key. - -`assegai new` uses the same generator and reports a failure if it cannot create the initial key. Generated-project and starter setup instructions now include the key command for cloned applications. Installation and update hooks do not rotate keys.