The Squeak Shell

squeak is the dedicated terminal companion utility built specifically for mouse-php.

Unlike traditional CLI tools that require you to memorize complex command flags, squeak operates as an interactive REPL shell. You launch it from your terminal, and it guides you through development server management, real-time SQLite log tailing, and step-by-step Terminal UI (TUI) scaffolding wizards.

The Interactive REPL & Recommended Workflow

Because long-running routines (such as hosting the dev server or streaming live logs) block the shell prompt while active, squeak is best used in a multi-tab or split-pane terminal environment:

┌─────────────────────────────────────────────────────────────┐
│                 RECOMMENDED TERMINAL WORKFLOW               │
├──────────────────────────────┬──────────────────────────────┤
│ Terminal Tab 1: Server/Logs  │ Terminal Tab 2: Development  │
│ $ php squeak                 │ $ php squeak                 │
│ > serve                      │ > add-route                  │
├──────────────────────────────┼──────────────────────────────┤
│ • Runs local dev server      │ • Interactive REPL prompt    │
│ • Watches ./core & ./public  │ • Runs scaffolding wizards   │
│ • Hot-reloads on file save   │ • `add-controller`, `add-...`│
└──────────────────────────────┴──────────────────────────────┘

Core Execution Commands

To start using squeak, launch the interactive shell from your project root:

php squeak

This opens the interactive prompt (>), where you can issue server controls or launch scaffolding workflows.

A. Development Server (serve)

Inside the squeak prompt, run serve to launch the local development environment:

> serve

• Behavior: Blocks the active terminal tab while the server process runs.
• Hot Reloading: Automatically watches files in ./core/ and ./public_html/ to refresh execution state whenever changes are saved.

B. Live SQLite Log Tailing (tail)

Inside the squeak prompt, run tail to stream application events in real time:

> tail

• Behavior: Blocks the active terminal tab while streaming structured log entries directly from mouse.db as they are written by Log_Handler.
• Output: Displays status codes, execution latency, log levels (INFO, WARN, ERROR), and associated user IDs in real time.

Guided TUI Scaffolding

squeak eliminates the friction of remembering long command-line flags (e.g., --controller --resource --middleware=auth).

Instead, squeak uses guided Terminal UI (TUI) wizards:

• Single-Word Commands: Memorable triggers like add-route, add-controller, or add-middleware.
• Arrow-Key Selection: Navigate menus, HTTP methods, and module lists using arrow keys (↑ / ↓) and Enter.
• Guided Prompts: Step-by-step prompts ask for required information, ensuring you never misspell file paths or omit required configuration keys.

Scaffolding Command Overview

Command	Interactive Wizard Action
add-route	Prompts for URI path, HTTP method, target Controller/method, and if the route is protected. Automatically wires the entry into Api_Routes.php or Web_routes.php.
add-controller	Scaffolds a new Controller class in ./core/controllers/ pre-injected with $DB, $SQLITE, and $REQUEST_DATA.
add-model	Scaffolds a query pipeline class in ./core/models/ containing prepared statement signatures for $db->make_query().
add-middleware	Scaffolds a middleware module in ./core/middleware/modules/ implementing the run() contract.
add-utility	Scaffolds a helper class in ./core/utilities/ assigned to the utils namespace.

If you'd like to see the full list of commands, check the Squeak Commands page.

Non-Destructive Safety Rules & Collision Protection

squeak adheres strictly to a "No Destructive Commands" safety policy:

• Business Logic Protection: squeak will never delete, overwrite, or clobber source files (Controllers, Models, Middleware Modules, Utilities) that contain developer-written business logic.
• Collision Guards: If a target file already exists on disk, squeak will not let you overwrite it from the terminal.
• Reversible Wiring: squeak is only permitted to modify connective tissue,such as appending or unhooking route entries in Api_Routes.php or updating group mappings in Middleware_Route_Groups.php. The underlying implementation files remain intact on disk for manual cleanup.

Interactive Scaffolding Example

Here is an example of creating a protected endpoint using the add-route wizard inside squeak:

The route has now been created, run the show-routes command to check that it's been added:

In less than 10 seconds, squeak generates the controller file, and hooks up the route definition.