@ijuantm/simpl-addon 2.8.4 → 2.8.7

package/README.md

@@ -1,38 +1,63 @@
 # Simpl Add-on Installer
 
-CLI tool for installing Simpl framework add-ons automatically using npx.
+CLI tool for installing Simpl framework add-ons with `npx`.
+
+## What it does
+
+- Downloads the selected Simpl add-on for your project version
+- Copies new files into the current project directory
+- Merges existing files using add-on markers
+- Keeps existing content when no merge markers are present
 
 ## Usage
 
-### List Available Add-ons
+Run the installer from the root of a Simpl project. The project must contain a `.simpl` file with a `version` field so the installer can match the add-on version to your Simpl framework version.
+
+Run the installer with no arguments to be prompted for the add-on:
 
 ```bash
-npx @ijuantm/simpl-addon --list
+npx @ijuantm/simpl-addon
 ```
 
-### Install an Add-on
-
-Navigate to your Simpl project directory and run the following command. For example, to install the "auth" add-on:
+Or provide the add-on name up front:
 
 ```bash
 npx @ijuantm/simpl-addon auth
 ```
 
-The installer will:
+You can also pass explicit options:
+
+```bash
+npx @ijuantm/simpl-addon --addon=auth
+```
+
+The first non-flag argument is treated as the add-on name. If you do not pass `--addon`, the installer will ask for it interactively.
+
+### Available options
+
+| Option                        | Description                                         |
+|-------------------------------|-----------------------------------------------------|
+| `--addon=<name>`, `-a=<name>` | Add-on to install.                                  |
+| `--list`, `-l`                | List all available add-ons for the current version. |
+| `--help`, `-h`                | Show the help message.                              |
+
+### Helpful commands
 
-1. Download the add-on
-2. Copy new files to your project
-3. Merge existing files using markers
+List available add-ons:
+
+```bash
+npx @ijuantm/simpl-addon --list
+```
 
-### Get Help
+Show help:
 
 ```bash
 npx @ijuantm/simpl-addon --help
 ```
 
-## How It Works
+## How it works
 
-The installer uses special markers in add-on files to safely merge content:
+The installer reads special markers in add-on files to safely merge content. Content for a marker is read from the marker line until `@addon-end`:
 
 ```php
 // @addon-insert:after('existing line')
@@ -40,22 +65,21 @@ new AuthController();
 // @addon-end
 ```
 
-**Supported Markers:**
+Supported markers:
 
-- `@addon-insert:after('text')` - Insert content after matching line
-- `@addon-insert:before('text')` - Insert content before matching line
-- `@addon-insert:replace('text')` - Replace matching line with content
+- `@addon-insert:after('text')` - Insert content after a matching line
+- `@addon-insert:before('text')` - Insert content before a matching line
+- `@addon-insert:replace('text')` - Replace a matching line with content
 - `@addon-insert:prepend` - Add content at the beginning of the file
 - `@addon-insert:append` - Add content at the end of the file
 
-The installer:
+The installer also:
 
-- Creates new files that don't exist
-- Merges files with markers automatically
-- Skips files without markers (no overwriting)
-- Detects duplicate content (won't add twice)
+- Creates new files that do not exist
+- Skips files without markers instead of overwriting them
+- Avoids adding the same content twice
 
 ## Requirements
 
-- **Node.js**: >= 22.x.x
-- **Simpl Framework**: A (preferably clean) installation of Simpl, if not clean, some manual merging may be required, or the installer may skip files or break things (you have been warned).
+- **Node.js**: >= 22
+- **Simpl Framework**: A Simpl project with a valid `.simpl` file in the project root

package/install.js

@@ -195,18 +195,19 @@ const promptAddon = async (addons, firstInput = null) => {
 };
 
 const showHelp = () => {
-  box('Simpl Add-on Installer');
-  line();
-  out(PAD + styled('Usage:', C.bold), C.blue);
-  out(PAD + styled('npx @ijuantm/simpl-addon', C.dim));
-  out(PAD + styled('npx @ijuantm/simpl-addon --addon=<name>', C.dim));
-  out(PAD + styled('npx @ijuantm/simpl-addon --help', C.dim));
+  box(`Simpl Add-on Installer ${C.dim}-${C.reset} ${C.blue}Help${C.reset}`);
   line();
   out(PAD + styled('Options:', C.bold), C.blue);
   out(PAD + styled('--addon=<name>, -a=<name>', C.dim) + ' Add-on to install');
   out(PAD + styled('--list, -l', C.dim) + '              List available add-ons');
   out(PAD + styled('--help, -h', C.dim) + '              Show this help message');
   line();
+  out(PAD + styled('Usage:', C.bold), C.blue);
+  out(PAD + styled('npx @ijuantm/simpl-addon', C.dim));
+  out(PAD + styled('npx @ijuantm/simpl-addon --addon=<name>', C.dim));
+  out(PAD + styled('npx @ijuantm/simpl-addon --list', C.dim));
+  out(PAD + styled('npx @ijuantm/simpl-addon -h', C.dim));
+  line();
   out(PAD + styled('Note:', C.bold), C.blue);
   item('Run this command from the root of your Simpl project.');
   item('The add-on version will match your Simpl framework version.');
@@ -470,6 +471,43 @@ const mergeFiles = (toMerge) => {
   return {merged, failed, unchanged};
 };
 
+const loadAddons = async (version) => {
+  const {versions} = await getVersionsData();
+  const versionMeta = versions[version];
+
+  if (!versionMeta) {
+    line();
+    error(`Version ${styled(version, C.bold)} not found`);
+    line();
+    process.exit(1);
+  }
+
+  if (versionMeta['script-compatible'] === false) {
+    line();
+    error(`Version ${styled(version, C.bold)} is not compatible with this installer`);
+    line();
+    out(PAD + styled('Manual download:', C.bold), C.blue);
+    item(`${C.cyan}${CDN_BASE}/${version}/add-ons/`);
+    line();
+    out(PAD + styled('Available add-ons for this version:', C.bold), C.blue);
+    const addons = versionMeta['add-ons'] || [];
+    if (!addons.length) info('No add-ons available');
+    else for (const name of addons) item(`${name}: ${styled(`${CDN_BASE}/${version}/add-ons/${name}.zip`, C.dim)}`);
+    line();
+    process.exit(1);
+  }
+
+  try {
+    return await getAvailableAddons(version);
+  } catch {
+    line();
+    error('Failed to fetch add-ons');
+    info('The CDN server is currently unavailable. Please try again later.');
+    line();
+    process.exit(1);
+  }
+};
+
 const main = async () => {
   const parsed = parseArgs(process.argv.slice(2));
 
@@ -502,48 +540,25 @@ const main = async () => {
     process.exit(1);
   }
 
-  box(`Simpl Add-on Installer ${C.dim}(v${version})${C.reset}`);
-
-  const {versions} = await getVersionsData();
-
-  const versionMeta = versions[version];
-  if (!versionMeta) {
+  if (parsed.list) {
+    const addons = await loadAddons(version);
+    box(`Simpl Add-on Installer ${C.dim}-${C.reset} ${C.blue}Available Add-ons${C.reset}`);
     line();
-    error(`Version ${styled(version, C.bold)} not found`);
+    out(PAD + styled('Available add-ons:', C.bold), C.blue);
+    if (!addons.length) info('No add-ons available for this version');
+    else listAddons(addons);
     line();
-    process.exit(1);
+    process.exit(0);
   }
 
-  if (versionMeta['script-compatible'] === false) {
-    line();
-    error(`Version ${styled(version, C.bold)} is not compatible with this installer`);
-    line();
-    out(PAD + styled('Manual download:', C.bold), C.blue);
-    item(`${C.cyan}${CDN_BASE}/${version}/add-ons/`);
-    line();
-    out(PAD + styled('Available add-ons for this version:', C.bold), C.blue);
-    const addons = versionMeta['add-ons'] || [];
-    if (!addons.length) info('No add-ons available');
-    else for (const name of addons) item(`${name}: ${styled(`${CDN_BASE}/${version}/add-ons/${name}.zip`, C.dim)}`);
-    line();
-    process.exit(1);
-  }
+  box(`Simpl Add-on Installer ${C.dim}(v${version})${C.reset}`);
 
   if (!parsed.addon) {
     line();
     task('🗄️ Fetching available add-ons...');
   }
 
-  let addons;
-  try {
-    addons = await getAvailableAddons(version);
-  } catch {
-    line();
-    error('Failed to fetch add-ons');
-    info('The CDN server is currently unavailable. Please try again later.');
-    line();
-    process.exit(1);
-  }
+  const addons = await loadAddons(version);
 
   if (!addons.length) {
     line();
@@ -552,17 +567,11 @@ const main = async () => {
     process.exit(0);
   }
 
-  if (parsed.list) {
-    line();
-    out(PAD + styled('Available add-ons:', C.bold), C.blue);
-    listAddons(addons);
-    line();
-    process.exit(0);
-  }
-
   let addonName;
   if (parsed.addon) {
     addonName = await promptAddon(addons, parsed.addon);
+
+    line();
     printAnswer(PAD + 'Add-on to install', addonName);
   } else {
     line();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ijuantm/simpl-addon",
   "description": "CLI tool to install Simpl framework add-ons.",
-  "version": "2.8.4",
+  "version": "2.8.7",
   "scripts": {
     "link": "npm link",
     "unlink": "npm unlink -g @ijuantm/simpl-addon"