Merge pull request #753 from nasirkhan/dev

Dev

Author: nasirkhan

README.md

@@ -32,6 +32,26 @@ Pass: secret
 
 We have created a number of custom commands for the project. The commands are listed below with a brief about their use of it.
 
+## Install / Setup
+
+Run the interactive setup wizard for a fresh project. It copies `.env`, generates an app key, configures the database, runs migrations, seeds data, creates the storage link, and builds frontend assets.
+
+```bash
+php artisan starter:install
+```
+
+Use `--skip-npm` to skip the frontend build, `--demo` to seed demo data without prompting, or `--skip-db` if the database is already set up.
+
+## Update
+
+After pulling changes from the repository, run:
+
+```bash
+php artisan starter:update
+```
+
+This runs `composer update`, checks for new module migrations, runs outstanding migrations, and clears all caches.
+
 ## Create New module
 
 To create a project use the following command, you have to replace the MODULE_NAME with the name of the module.
@@ -140,18 +160,61 @@ It is a modular application, and some modules are installed by default. It will
 
 Follow the steps mentioned below to install and run the project. You may find more details about the installation in [Installation Wiki](https://github.com/nasirkhan/laravel-starter/wiki/Installation).
 
-1. Open the terminal and run the following command, this will download and install the `Laravel Starter` and run the post-installation commands. 
+### From GitHub Template (recommended)
+
+If you created a new repository from this GitHub template, or cloned it directly:
+
+```bash
+# 1. Install PHP dependencies
+composer install
+
+# 2. Run the interactive setup wizard — handles .env, database, migrations, seeding, and npm assets
+php artisan starter:install
+```
+
+Or as a single shortcut after `composer install`:
+
+```bash
+composer setup
+```
+
+For a true one-liner from a fresh clone, convenience scripts are included:
+
+```bash
+# Linux / macOS
+bash setup.sh
+
+# Windows (PowerShell)
+.\setup.ps1
+```
+
+Both scripts run `composer install` and then launch `php artisan starter:install`.
+Pass any `starter:install` flags through, e.g. `bash setup.sh --demo`.
+
+The setup wizard will guide you through environment configuration, database selection, migrations, seeding, and building frontend assets. When finished it prints the app URL and default login credentials.
+
+**Available options:**
+
+| Option | Description |
+|---|---|
+| `--skip-db` | Skip database setup |
+| `--skip-seed` | Skip database seeding |
+| `--skip-npm` | Skip `npm install` and asset build |
+| `--demo` | Seed with demo data (no prompt) |
+
+### Via Composer create-project
+
 ```bash
 composer create-project nasirkhan/laravel-starter
 ```
-2. The default database is `sqlite`, if you want to change please update the database settings at `.env` file
-3. To create a link from the storage directory, run the following command from the project root:
-```php
-php artisan storage:link
+
+This runs migrations automatically. Afterwards run the setup wizard to seed and build assets:
+
+```bash
+php artisan starter:install --skip-db
 ```
-4. If you run the `create-project` command from `Laravel Hard` then the site will be available at [http://laravel-starter.test](http://laravel-starter.test). You may create a virtualhost entry to access the application or run `php artisan serve` from the project root and visit `http://127.0.0.1:8000`
 
-*After creating the new permissions use the following commands to update cashed permissions.*
+*After creating the new permissions use the following commands to update cached permissions.*
 
 `php artisan cache:forget spatie.permission.cache`
 

app/Console/Commands/SeedEssentialData.php

@@ -85,10 +85,7 @@ protected function seedMenuModule(): void
         }
 
         try {
-            $this->call('db:seed', [
-                '--class' => 'Modules\\Menu\\database\\seeders\\MenuDatabaseSeeder',
-                '--force' => $this->option('force'),
-            ]);
+            $this->call('menu:seed');
             $this->info('Menu module seeded successfully.');
         } catch (\Exception $e) {
             $this->error("Failed to seed Menu module: {$e->getMessage()}");

app/Console/Commands/StarterInstallCommand.php

@@ -16,6 +16,8 @@ class StarterInstallCommand extends Command
     protected $signature = 'starter:install
                             {--skip-db : Skip database setup}
                             {--skip-seed : Skip database seeding}
+                            {--skip-npm : Skip npm install and asset build}
+                            {--fresh : Reset the database (migrate:fresh) before seeding}
                             {--demo : Install with demo data}';
 
     /**
@@ -40,8 +42,8 @@ public function handle(): int
         if ($this->setupEnvironment()) {
             // Step 2: Database Setup
             if ($this->option('skip-db') || $this->setupDatabase()) {
-                // Step 3: Run Migrations
-                if ($this->runMigrations()) {
+                // Step 3: Run Migrations (skip entirely when --skip-db is passed)
+                if ($this->option('skip-db') || $this->runMigrations()) {
                     // Step 4: Seed Database
                     if (! $this->option('skip-seed')) {
                         $this->seedDatabase();
@@ -50,6 +52,11 @@ public function handle(): int
                     // Step 5: Final Steps
                     $this->finalizeInstallation();
 
+                    // Step 6: Install npm dependencies & build assets
+                    if (! $this->option('skip-npm')) {
+                        $this->installNpmDependencies();
+                    }
+
                     $this->displaySuccessMessage();
 
                     return self::SUCCESS;
@@ -161,8 +168,12 @@ protected function setupSQLite(): bool
                 File::put($dbPath, '');
             }
 
+            // Use forward slashes — dotenv treats backslashes as escape characters
+            // and spaces in the path cause parse errors unless the path is normalised.
+            $dotenvSafePath = str_replace('\\', '/', $dbPath);
+
             $this->updateEnvFile('DB_CONNECTION', 'sqlite');
-            $this->updateEnvFile('DB_DATABASE', $dbPath);
+            $this->updateEnvFile('DB_DATABASE', $dotenvSafePath);
 
             return true;
         });
@@ -172,18 +183,62 @@ protected function setupSQLite(): bool
 
     /**
      * Run database migrations.
+     *
+     * Returns false only when the user explicitly skips migrations.
      */
     protected function runMigrations(): bool
     {
         $this->newLine();
 
-        if (! $this->confirm('Run database migrations?', true)) {
+        // --fresh flag skips the interactive prompt
+        if ($this->option('fresh')) {
+            return $this->runFreshMigrations();
+        }
+
+        $choice = $this->choice(
+            'How would you like to set up the database?',
+            [
+                'fresh' => 'Fresh install — drop all tables and re-run all migrations (⚠️  destroys existing data)',
+                'migrate' => 'Run new migrations only — safe for existing data',
+                'skip' => 'Skip migrations',
+            ],
+            'fresh'
+        );
+
+        if ($choice === 'skip') {
             $this->components->warn('Skipping migrations. Run manually: php artisan migrate');
 
             return false;
         }
 
-        return $this->components->task('Running migrations', function () {
+        if ($choice === 'fresh') {
+            return $this->runFreshMigrations();
+        }
+
+        // migrate only
+        return (bool) $this->components->task('Running migrations', function () {
+            Artisan::call('migrate', ['--force' => true], $this->output);
+
+            return true;
+        });
+    }
+
+    /**
+     * Drop all tables and re-run every migration.
+     */
+    protected function runFreshMigrations(): bool
+    {
+        $this->newLine();
+        $this->components->warn('⚠️  This will drop ALL tables and delete ALL existing data.');
+
+        // Skip confirmation if the user explicitly passed --fresh
+        if (! $this->option('fresh') && ! $this->confirm('Are you sure you want to reset the database?', false)) {
+            $this->components->info('Database reset cancelled.');
+
+            return false;
+        }
+
+        return (bool) $this->components->task('Resetting database (migrate:fresh)', function () {
             Artisan::call('migrate:fresh', ['--force' => true], $this->output);
 
             return true;
@@ -192,21 +247,30 @@ protected function runMigrations(): bool
 
     /**
      * Seed database.
+     *
+     * Always seeds essential data (users, roles, permissions, menus).
+     * Optionally seeds demo data (posts, categories, tags) on top.
      */
     protected function seedDatabase(): void
     {
         $this->newLine();
 
-        $seedDemo = $this->option('demo') || $this->confirm('Seed database with demo data?', true);
+        // Seed essential data via db:seed-essential
+        $this->components->task('Seeding essential data (users, roles, permissions, menus)', function () {
+            Artisan::call('db:seed-essential', ['--force' => true], $this->output);
+
+            return true;
+        });
+
+        // Optionally seed demo data on top
+        $seedDemo = $this->option('demo') || $this->confirm('Also seed demo data (posts, categories, tags)?', false);
 
         if ($seedDemo) {
-            $this->components->task('Seeding database', function () {
+            $this->components->task('Seeding demo data', function () {
                 Artisan::call('db:seed', ['--force' => true], $this->output);
 
                 return true;
             });
-        } else {
-            $this->components->warn('Skipping seeding. Run manually: php artisan db:seed');
         }
     }
 
@@ -236,6 +300,36 @@ protected function finalizeInstallation(): void
         });
     }
 
+    /**
+     * Install npm dependencies and build frontend assets.
+     */
+    protected function installNpmDependencies(): void
+    {
+        $this->newLine();
+
+        if (! $this->confirm('Install npm dependencies and build frontend assets?', true)) {
+            $this->components->warn('Skipping npm. Run manually: npm install && npm run build');
+
+            return;
+        }
+
+        $this->components->task('Installing npm dependencies', function () {
+            $output = [];
+            $exitCode = 0;
+            exec('npm install --no-audit --no-fund 2>&1', $output, $exitCode);
+
+            return $exitCode === 0;
+        });
+
+        $this->components->task('Building frontend assets', function () {
+            $output = [];
+            $exitCode = 0;
+            exec('npm run build 2>&1', $output, $exitCode);
+
+            return $exitCode === 0;
+        });
+    }
+
     /**
      * Display success message.
      */
@@ -251,10 +345,17 @@ protected function displaySuccessMessage(): void
         $this->newLine();
 
         $this->components->twoColumnDetail('<fg=bright-blue>Next Steps</>', '');
-        $this->line('  1. <fg=green>npm install && npm run dev</> - Build frontend assets');
-        $this->line('  2. <fg=green>php artisan serve</> - Start development server');
-        $this->line('  3. Visit <fg=cyan>http://localhost:8000</> in your browser');
-        $this->line('  4. Login with credentials above');
+
+        $step = 1;
+
+        if ($this->option('skip-npm')) {
+            $this->line("  {$step}. <fg=green>npm install && npm run build</> - Build frontend assets");
+            $step++;
+        }
+
+        $this->line("  {$step}. <fg=green>php artisan serve</> - Start development server (or visit your Herd/Valet URL)");
+        $step++;
+        $this->line("  {$step}. Login with the credentials above");
         $this->newLine();
 
         $this->components->twoColumnDetail('<fg=bright-blue>Useful Commands</>', '');
@@ -282,6 +383,11 @@ protected function updateEnvFile(string $key, string $value): void
         $escapedValue = str_replace(['\\', '$'], ['\\\\', '\\$'], $value);
         $replacement = "{$key}={$escapedValue}";
 
+        // Quote values that contain spaces so dotenv can parse them
+        if (str_contains($value, ' ')) {
+            $replacement = "{$key}=\"{$escapedValue}\"";
+        }
+
         if (preg_match($pattern, $content)) {
             $content = preg_replace($pattern, $replacement, $content);
         } else {

composer.json

@@ -58,6 +58,9 @@
         }
     },
     "scripts": {
+        "setup": [
+            "@php artisan starter:install"
+        ],
         "post-autoload-dump": [
             "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
             "@php artisan package:discover --ansi"