Skip to content

Commit 3fac4a4

Browse files
acidlakeacidlake
committed
improved forge package manager documentation
1 parent ae9c6c7 commit 3fac4a4

2 files changed

Lines changed: 104 additions & 15 deletions

File tree

‎forge-package-manager.html‎

Lines changed: 91 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -821,6 +821,7 @@ <h3 class="text-lg font-semibold mb-3">Basic Configuration</h3>
821821
'url' => 'https://github.com/forge-engine/modules',
822822
'branch' => 'main',
823823
'private' => false,
824+
'description' => 'Forge Kernel Official Modules', // Optional: shown in wizard
824825
'personal_token' => env('GITHUB_TOKEN') // Only needed for private repos
825826
],
826827
// Custom private registry example
@@ -830,13 +831,20 @@ <h3 class="text-lg font-semibold mb-3">Basic Configuration</h3>
830831
'url' => 'https://github.com/mycompany/private-modules',
831832
'branch' => 'main',
832833
'private' => true,
834+
'description' => 'Company Internal Modules', // Optional: shown in wizard
833835
'personal_token' => env('GITHUB_TOKEN')
834836
],
835837
],
836838
'cache_ttl' => 3600, // Cache time-to-live in seconds
837839
];</code></pre>
838840
</div>
839841

842+
<div class="bg-blue-50 border-l-4 border-blue-400 p-4 mb-6">
843+
<p class="text-sm text-blue-700">
844+
<strong>Registry Descriptions:</strong> You can add an optional <code class="bg-blue-100 px-2 py-1 rounded">description</code> field to each registry entry. This description will be displayed in the interactive wizard when selecting registries, helping users identify the purpose of each registry (e.g., "Forge Kernel Official Modules", "Company Internal Modules").
845+
</p>
846+
</div>
847+
840848
<h3 class="text-lg font-semibold mb-3">Supported Source Types</h3>
841849
<p class="text-gray-600 mb-4">
842850
The package manager supports multiple source types:
@@ -916,29 +924,80 @@ <h2 class="text-2xl font-bold text-gray-900 mb-4">
916924

917925
<h3 class="text-lg font-semibold mb-3">Installing Capabilities</h3>
918926
<p class="text-gray-600 mb-3">
919-
Commands use interactive wizards by default. Use the <code class="bg-gray-100 px-2 py-1 rounded">--module=</code> parameter to skip the wizard and specify the module directly.
927+
The <code class="bg-gray-100 px-2 py-1 rounded">package:install-module</code> command features an interactive wizard that guides you through the installation process. Use the <code class="bg-gray-100 px-2 py-1 rounded">--module=</code> parameter to skip the wizard and specify the module directly.
920928
</p>
929+
930+
<h4 class="text-md font-semibold mb-2 mt-4">Interactive Wizard</h4>
931+
<p class="text-gray-600 mb-3">
932+
When you run <code class="bg-gray-100 px-2 py-1 rounded">package:install-module</code> without arguments, an interactive wizard starts:
933+
</p>
934+
<ol class="list-decimal list-inside space-y-2 text-gray-600 mb-4">
935+
<li><strong>Choose installation method:</strong> Select "Enter module name manually" or "Browse available modules"</li>
936+
<li><strong>If browsing:</strong>
937+
<ul class="list-disc list-inside ml-6 mt-2 space-y-1">
938+
<li>Select a registry from the list (registries show descriptions if configured)</li>
939+
<li>Select a module from the chosen registry</li>
940+
<li>Select a version (shows commit messages for git-based registries when available)</li>
941+
<li>Choose whether to force download (bypass cache)</li>
942+
</ul>
943+
</li>
944+
<li><strong>If manual entry:</strong>
945+
<ul class="list-disc list-inside ml-6 mt-2 space-y-1">
946+
<li>Enter the module name (with optional version, e.g., <code class="bg-gray-100 px-2 py-1 rounded">forge-welcome@1.0.0</code>)</li>
947+
<li>If no version specified, select from available versions</li>
948+
<li>Choose whether to force download (bypass cache)</li>
949+
</ul>
950+
</li>
951+
</ol>
952+
921953
<div class="code-block p-6 text-white rounded-lg mb-6">
922-
<pre><code class="language-bash"># Install with wizard (interactive - prompts for module name)
954+
<pre><code class="language-bash"># Install with wizard (interactive)
923955
php forge.php package:install-module
924956

925957
# Install latest version (skip wizard)
926-
php forge.php package:install-module --module=ForgeAuth
958+
php forge.php package:install-module --module=forge-auth
927959

928960
# Install specific version (skip wizard)
929-
php forge.php package:install-module --module=ForgeAuth@1.2.0
961+
php forge.php package:install-module --module=forge-auth@1.2.0
962+
963+
# Force download bypassing cache (skip wizard)
964+
php forge.php package:install-module --module=forge-auth --force
930965

931966
# Install all capabilities from lock file and scaffold app structure
932967
php forge.php package:install-project</code></pre>
933968
</div>
934969

970+
<div class="bg-blue-50 border-l-4 border-blue-400 p-4 mb-6">
971+
<p class="text-sm text-blue-700">
972+
<strong>Version Selection:</strong> When browsing modules from git-based registries, version options display commit messages (truncated to 80 characters) to help you understand what changed in each version, similar to <code class="bg-blue-100 px-2 py-1 rounded">dev:modules:list</code>.
973+
</p>
974+
</div>
975+
935976
<h3 class="text-lg font-semibold mb-3">Removing Capabilities</h3>
977+
<p class="text-gray-600 mb-3">
978+
The <code class="bg-gray-100 px-2 py-1 rounded">package:remove-module</code> command features an interactive wizard that displays all installed modules with their descriptions, making it easy to select which module to remove.
979+
</p>
980+
981+
<h4 class="text-md font-semibold mb-2 mt-4">Interactive Wizard</h4>
982+
<p class="text-gray-600 mb-3">
983+
When you run <code class="bg-gray-100 px-2 py-1 rounded">package:remove-module</code> without arguments:
984+
</p>
985+
<ol class="list-decimal list-inside space-y-2 text-gray-600 mb-4">
986+
<li>A list of all installed modules is displayed</li>
987+
<li>Modules show their descriptions (from their <code class="bg-gray-100 px-2 py-1 rounded">forge.json</code>) if available</li>
988+
<li>Select the module you want to remove</li>
989+
<li>Confirm the removal (with warnings if the module has migrations, seeders, or assets)</li>
990+
</ol>
991+
936992
<div class="code-block p-6 text-white rounded-lg mb-6">
937-
<pre><code class="language-bash"># Remove with wizard (interactive)
993+
<pre><code class="language-bash"># Remove with wizard (interactive - shows installed modules with descriptions)
938994
php forge.php package:remove-module
939995

940996
# Remove a capability (skip wizard)
941-
php forge.php package:remove-module --module=ForgeAuth</code></pre>
997+
php forge.php package:remove-module --module=forge-auth
998+
999+
# Skip confirmation prompts (skip wizard)
1000+
php forge.php package:remove-module --module=forge-auth --force</code></pre>
9421001
</div>
9431002

9441003
<h3 class="text-lg font-semibold mb-3">Listing Capabilities</h3>
@@ -1109,17 +1168,28 @@ <h2 class="text-2xl font-bold text-gray-900 mb-4">
11091168
<h3 class="font-semibold text-lg mb-2">
11101169
<code class="bg-gray-100 px-2 py-1 rounded text-sm">package:install-module</code>
11111170
</h3>
1112-
<p class="text-gray-600 text-sm mb-3">Install a module from the configured registries. Uses an interactive wizard by default. Use <code class="bg-gray-100 px-2 py-1 rounded">--module=</code> to skip the wizard.
1171+
<p class="text-gray-600 text-sm mb-3">Install a module from the configured registries. Features an interactive wizard that allows you to browse registries, select modules, choose versions (with commit messages for git-based registries), and configure installation options. Use <code class="bg-gray-100 px-2 py-1 rounded">--module=</code> to skip the wizard.
11131172
</p>
11141173
<div class="code-block p-4 text-white rounded-lg">
11151174
<pre><code class="language-bash">php forge.php package:install-module [--module=&lt;module-name[@version]&gt;] [--force]</code></pre>
11161175
</div>
1176+
<div class="mt-3 text-xs text-gray-500">
1177+
<strong>Wizard Features:</strong>
1178+
<ul class="mt-1 space-y-1">
1179+
<li>• Choose between manual entry or browsing available modules</li>
1180+
<li>• Select from configured registries (with descriptions if available)</li>
1181+
<li>• Browse and select modules from chosen registry</li>
1182+
<li>• View versions with commit messages (for git-based registries)</li>
1183+
<li>• Option to force download (bypass cache)</li>
1184+
</ul>
1185+
</div>
11171186
<div class="mt-3 text-xs text-gray-500">
11181187
<strong>Examples:</strong>
11191188
<ul class="mt-1 space-y-1">
11201189
<li>• <code>php forge.php package:install-module</code> (interactive wizard)</li>
1121-
<li>• <code>php forge.php package:install-module --module=ForgeAuth</code></li>
1122-
<li>• <code>php forge.php package:install-module --module=ForgeAuth@1.2.0</code></li>
1190+
<li>• <code>php forge.php package:install-module --module=forge-auth</code></li>
1191+
<li>• <code>php forge.php package:install-module --module=forge-auth@1.2.0</code></li>
1192+
<li>• <code>php forge.php package:install-module --module=forge-auth --force</code></li>
11231193
</ul>
11241194
</div>
11251195
</div>
@@ -1128,16 +1198,26 @@ <h3 class="font-semibold text-lg mb-2">
11281198
<h3 class="font-semibold text-lg mb-2">
11291199
<code class="bg-gray-100 px-2 py-1 rounded text-sm">package:remove-module</code>
11301200
</h3>
1131-
<p class="text-gray-600 text-sm mb-3">Remove an installed module from your application. Uses an interactive wizard by default. Use <code class="bg-gray-100 px-2 py-1 rounded">--module=</code> to skip the wizard.
1201+
<p class="text-gray-600 text-sm mb-3">Remove an installed module from your application. Features an interactive wizard that displays all installed modules with their descriptions, making it easy to identify and select the module to remove. Use <code class="bg-gray-100 px-2 py-1 rounded">--module=</code> to skip the wizard.
11321202
</p>
11331203
<div class="code-block p-4 text-white rounded-lg">
11341204
<pre><code class="language-bash">php forge.php package:remove-module [--module=&lt;module-name&gt;] [--force]</code></pre>
11351205
</div>
1206+
<div class="mt-3 text-xs text-gray-500">
1207+
<strong>Wizard Features:</strong>
1208+
<ul class="mt-1 space-y-1">
1209+
<li>• Displays all installed modules in an interactive list</li>
1210+
<li>• Shows module descriptions (from <code>forge.json</code>) when available</li>
1211+
<li>• Format: "Module Name (Description)" or just "Module Name"</li>
1212+
<li>• Confirmation prompts for modules with migrations, seeders, or assets</li>
1213+
</ul>
1214+
</div>
11361215
<div class="mt-3 text-xs text-gray-500">
11371216
<strong>Examples:</strong>
11381217
<ul class="mt-1 space-y-1">
11391218
<li>• <code>php forge.php package:remove-module</code> (interactive wizard)</li>
1140-
<li>• <code>php forge.php package:remove-module --module=ForgeAuth</code></li>
1219+
<li>• <code>php forge.php package:remove-module --module=forge-auth</code></li>
1220+
<li>• <code>php forge.php package:remove-module --module=forge-auth --force</code></li>
11411221
</ul>
11421222
</div>
11431223
</div>

‎modules.html‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -709,24 +709,33 @@ <h3 class="text-lg font-semibold mb-3">Using Forge CLI</h3>
709709
<p class="text-gray-600 mb-4">
710710
Commands use an interactive wizard by default. You can skip the wizard by providing the <code class="bg-gray-100 px-2 py-1 rounded">--module=</code> flag.
711711
</p>
712+
<p class="text-gray-600 mb-3">
713+
<strong>Installation Wizard:</strong> When installing, you can choose to enter the module name manually or browse available modules. When browsing, you'll select a registry, then a module, then a version (with commit messages for git-based registries), and finally choose whether to force download.
714+
</p>
715+
<p class="text-gray-600 mb-3">
716+
<strong>Removal Wizard:</strong> When removing, you'll see a list of all installed modules with their descriptions, making it easy to identify which module to remove.
717+
</p>
712718
<div class="code-block p-6 text-white rounded-lg mb-6">
713719
<pre><code class="language-bash"># Install a capability (wizard-based, interactive)
714720
php forge.php package:install-module
715721

716722
# Skip wizard and install directly
717-
php forge.php package:install-module --module=ForgeAuth
723+
php forge.php package:install-module --module=forge-auth
718724

719725
# Install a specific version (skips version selection in wizard)
720-
php forge.php package:install-module --module=ForgeAuth@1.2.0
726+
php forge.php package:install-module --module=forge-auth@1.2.0
727+
728+
# Force download bypassing cache
729+
php forge.php package:install-module --module=forge-auth --force
721730

722731
# List available capabilities
723732
php forge.php package:list-modules
724733

725-
# Remove a capability (wizard-based)
734+
# Remove a capability (wizard-based, shows installed modules with descriptions)
726735
php forge.php package:remove-module
727736

728737
# Skip wizard and remove directly
729-
php forge.php package:remove-module --module=ForgeAuth</code></pre>
738+
php forge.php package:remove-module --module=forge-auth</code></pre>
730739
</div>
731740

732741
<h3 class="text-lg font-semibold mb-3">Manual Installation</h3>

0 commit comments

Comments
 (0)