0.10.4

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:

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:

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:

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:

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.