neutrinos-cli 1.0.2 → 2.0.0-beta.1

package/README.md

@@ -1,173 +1,139 @@
 # neutrinos CLI
 
-neutrinos CLI is a command-line interface for managing, developing and publishing the packages.
+A command-line interface for managing, developing, and publishing alpha plugin packages.
 
-### Installation
+**Requires Node.js 22+**
 
-To install neutrinos CLI, use the following command:
+## Installation
 
 ```sh
+# Stable
 npm i -g neutrinos-cli
+
+# Beta
+npm i -g neutrinos-cli@beta
 ```
 
-### Usage
+## Quick Start
 
 ```sh
-    neutrinos command [options]
+neutrinos new my-workspace
+cd my-workspace
+neutrinos generate component my-button
+neutrinos build plugins
+neutrinos start
 ```
 
-### Commands
-
-- `new <name>` Create a new project
-- `generate` | `g` Generate a new plugin. Run "help generate" for more information.
-- `auth` Perform authentication tasks like login, logout, or status
-- `publish [options] [packageName]` Bundle and publish the plugin
-- `build <type> [pluginName]` Build the plugin
-- `start [options]` Start the live server for the plugin
-- `serve` Start the express server that serves the plugins
-
-### Options
-
-- `-v, --version` Output the version number
-- `-h, --help` Display help for command
-
----
-
 ## Commands
 
----
-
-### `new <name>`
+```
+neutrinos <command> [options]
+```
 
-##### Description
+| Command | Description |
+|---------|-------------|
+| `new <name>` | Create a new plugin workspace |
+| `generate\|g` | Generate a component, module, or attribute |
+| `build <type> [name]` | Build plugins (`plugins` or `docker`) |
+| `start` | Start the Vite dev server |
+| `serve` | Start the Express plugins server |
+| `publish [name]` | Bundle and publish a package |
+| `deprecate [name]` | Deprecate a published package |
+| `auth` | Login or check auth state |
+| `completion <shell>` | Output shell completion script (`bash` or `zsh`) |
 
-- Create a new project with the given name. The project will be created in the current directory.
+### `new <name>`
 
-##### Usage
+Create a new workspace with scaffold files, plugin.json, git init, and npm install.
 
 ```sh
-    neutrinos new <name>
+neutrinos new my-workspace
 ```
 
-##### Arguments
-
-- `<name>` project or workspace name
-
----
-
 ### `generate` | `g`
 
-##### Description
-
-- Generate a new component or module
-
-##### Usage
-
 ```sh
-    neutrinos generate [command] [argument] || neutrinos g [command] [argument]
+neutrinos generate component <name> [-d <description>]
+neutrinos generate module <name> [-d <description>]
+neutrinos generate attribute [componentName] [options]
 ```
 
-##### commands
-
-- `component <name>` | `c <name>` Component is a package enabling drag and drop functionality within the canvas
-- `module <name>` | `m <name>` Module is a globally accessible package, available throughout the entire project on `alpha.plugins` | `ap`.
-- `attribute [command] [options]` | `a [command] [options]` Generate an Attribute for a component, Read the `ATTRIBUTE.md` file in projetc/workspcae directory for more help
-
-##### Arguments
-
-- `<name>` component or module name
-
----
+Aliases: `g`, `c`, `m`, `a`
 
-## `Build <type> [pluginName]`
+Attribute options: `-t` type, `-u` ui-type, `-l` label, `-e` event, `-c` category, `-p` placeholder, `-d` defaultValue, `-o` options, `-f` fieldMappings, `-n` validation. See `ATTRIBUTE.md` in your workspace for details.
 
-#### Description
-
-- Build the plugins
-
-#### Usage
+### `build <type> [pluginName]`
 
 ```sh
-    neutrinos build <type> [pluginName]
+neutrinos build plugins [name] [--module] [--all]
+neutrinos build docker [name]
 ```
 
-#### Arguments
-
-- `<type>` The type of build, it can be one of `plugin` or `docker`
-- `pluginName` package Name of the component/module to build, it is an optional argument and if not pluginName it will build every package in the current workspace
-
----
-
-## `start [options]`
+- `plugins` — Runs tsc + Vite build, copies output to plugins-server
+- `docker` — Builds plugins then runs `docker build`
+- `--module` — Skip tsc (for JS-only modules)
+- `--all` — Build all packages in the workspace
 
-#### Description
-
-- Start the live server for the workspace
-
-#### Usage
+### `start`
 
 ```sh
-    neutrinos start [options]
+neutrinos start [-p <port>]
 ```
 
-#### Options
-
-- `-p, --port <port>` Port to start the server on, default is 6969
+Starts a Vite dev server. Default port: 6969.
 
----
+### `serve`
 
-## `serve`
-
-#### Description
+```sh
+neutrinos serve [-p <port>]
+```
 
-- Start the express server that serves the plugins
+Starts the Express server that serves built plugins. Default port: 3000.
 
-#### Usage
+### `publish [packageName]`
 
 ```sh
-    neutrinos serve
+neutrinos publish [name] [-t <patch|minor|major>] [-d <displayName>] [-i <iconPath>] [-m <images...>] [--accept-defaults] [--all]
 ```
 
----
+Authenticates, builds, zips, and uploads the package to the marketplace. Prompts for missing metadata unless `--accept-defaults` is passed.
 
-### `auth [command]`
+### `deprecate [packageName]`
 
-#### Description
+```sh
+neutrinos deprecate [name] [-y] [--all]
+```
 
-- Perform authentication tasks like login or status
+Marks a published package as deprecated. Prompts for confirmation unless `-y` is passed.
 
-#### Usage
+### `auth`
 
 ```sh
-    neutrinos auth [command]
+neutrinos auth login    # Opens browser for OIDC login
+neutrinos auth state    # Shows current auth state
 ```
 
-#### Commands:
+### `completion`
 
-- `login` Authenticate with the server
-- `state` Get the current state of auth
-
----
+```sh
+# Bash
+neutrinos completion bash >> ~/.bashrc
 
-## `publish [PackageName] [options]`
+# Zsh
+neutrinos completion zsh >> ~/.zshrc
+```
 
-#### Description
+## Global Options
 
-- Publish a package to the server
+- `-v, --version` — Show version
+- `-h, --help` — Show help
 
-#### Usage
+## Development
 
 ```sh
-    neutrinos publish [PackageName] [Options]
+pnpm install
+pnpm build          # tsc
+pnpm test           # vitest
+pnpm publish:beta   # build + test + npm publish --tag beta
+pnpm publish:latest # build + test + npm publish --tag latest
 ```
-
-#### Arguments
-
-- `PackageName` The name of the component/module to publish, if not cli will show the list of packages inside the current workspace/project
-
-#### Options
-
-- `-t, --version-type <versionType>` Version type for verion up, it can be one of `patch`, `minor`, `major`
-- `-d, --display-name <displayName>` Display Name for the package
-- `-i, --icon <iconPath>` Path to the icon
-- `-m, --images <imagePaths...>` path to the image

package/{bin → dist/src/bin}/cli.js

@@ -1,20 +1,23 @@
 #! /usr/bin/env node
-//@ts-check
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const [major] = process.versions.node.split('.').map(Number);
+if (major < 22) {
+    console.error('neutrinos requires Node.js 22+. Current: ' + process.version);
+    process.exit(1);
+}
 import dotenv from 'dotenv';
+import { PACKAGE_ROOT } from '../utils/path-utils.js';
 dotenv.config({
-    path: join(__dirname, '../.env'),
+    path: join(PACKAGE_ROOT, '.env'),
 });
-////////////////////////////////////
 import { greenBright } from 'colorette';
-import { Command, InvalidArgumentError } from 'commander';
+import { Argument, Command, Option } from 'commander';
 import EventEmitter from 'node:events';
 import { cwd, env, exit } from 'node:process';
+import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import open from 'open';
-import { join } from 'path';
+import { join, resolve } from 'node:path';
 import { init } from '../cli-auth/server.js';
-import { publish as alphaPublish } from '../commands/alpha-publish.js';
 import { addAttribute } from '../commands/attribute.js';
 import { build } from '../commands/build.js';
 import { deprecate } from '../commands/deprecate.js';
@@ -23,25 +26,25 @@ import { generate } from '../commands/generate.js';
 import { createWorkspace } from '../commands/new-workspace.js';
 import { publish } from '../commands/publish.js';
 import { startPluginsServer } from '../commands/serve.js';
+import { completion } from '../commands/completion.js';
+import { getPackages } from '../utils/get-packages.js';
 import { validateWorkspace } from '../utils/check-valid-ws.js';
 import { done, failed, inprogress, log } from '../utils/logger.js';
 import { authConfigJson } from '../utils/path-utils.js';
+const { version: CLI_VERSION } = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf-8'));
 export const createProgram = () => {
     const program = new Command();
-
-    program.version('1.0.0', '-v, --version', 'Output the version number');
-
+    program.version(CLI_VERSION, '-v, --version', 'Output the version number');
     program
         .command('new <name>')
         .description('Create a new project')
         .action((name) => {
-            createWorkspace(join(cwd(), name), name);
-        });
+        createWorkspace(join(cwd(), name), name);
+    });
     const generateCmd = program
         .command('generate')
         .alias('g')
         .description('Generate a new plugin. Run "help generate" for more information.');
-
     generateCmd
         .command('component')
         .alias('c')
@@ -49,12 +52,12 @@ export const createProgram = () => {
         .option('-d,--description <description>', 'Description of the package')
         .description('Generate a new component plugin')
         .action(async (name, options) => {
-            await generate.component({
-                name,
-                dir: cwd(),
-                description: options.description,
-            });
+        await generate.component({
+            name,
+            dir: cwd(),
+            description: options.description,
         });
+    });
     generateCmd
         .command('module')
         .alias('m')
@@ -62,21 +65,18 @@ export const createProgram = () => {
         .option('-d,--description <description>', 'Description of the package')
         .description('Generate a new module plugin')
         .action(async (name, options) => {
-            await generate.module({
-                name,
-                dir: cwd(),
-                description: options.description,
-            });
+        await generate.module({
+            name,
+            dir: cwd(),
+            description: options.description,
         });
+    });
     generateCmd
         .command('attribute')
         .alias('a')
         .argument('[componentName]', 'Component name')
         .option('-t , --type <attributeType>', 'Type of attribute can be property, event, validation')
-        .option(
-            '-u , --ui-type <uiType>',
-            'Ui-type of attribute can be ===> input, toggle, dropdown, multi-select, typed-input, range, color-picker, data-source, data-set, table-actions, data-mapping',
-        )
+        .option('-u , --ui-type <uiType>', 'Ui-type of attribute can be ===> input, toggle, dropdown, multi-select, typed-input, range, color-picker, data-source, data-set, table-actions, data-mapping')
         .option('-l , --label <label>', 'Label for an attribute')
         .option('-e , --event <event>', 'Event name for an attribute if -t/--type is event')
         .option('-c , --category <category>', 'Category for an attribute')
@@ -87,86 +87,63 @@ export const createProgram = () => {
         .option('-n , --validation <validation>', 'Validation for an attribute')
         .description('Generate an Attribute for component')
         .action(async (componentName, options) => {
-            return await addAttribute(componentName, cwd(), options);
-        });
-
+        return await addAttribute(componentName, cwd(), options);
+    });
     const authCommand = program.command('auth').description('perform: login, logout, or status');
     authCommand
         .command('login')
         .description('authenticate with the server')
-        .action((action) => {
-            return new Promise(async (resolve, reject) => {
-                inprogress(`logging in...`);
-                const cliServer = await init({
-                    tokenSetPath: authConfigJson(),
-                });
-                if (!cliServer) {
-                    failed('Issuer not found');
-                    return;
-                }
-                const eventEmitter = new EventEmitter();
-                eventEmitter.on('cli-auth:login', () => {
-                    done('login successful');
-                    resolve();
-                    process.exit(0);
-                });
-                eventEmitter.on('cli-auth:login-failed', () => {
-                    failed('login failed');
-                    reject();
-                    process.exit(1);
-                });
-                process.on('SIGINT', () => {
-                    failed('exitting unexpectedly');
-                    cliServer.stop();
-                    exit(0);
-                });
-                process.on('SIGTERM', () => {
-                    failed('exitting unexpectedly');
-                    cliServer.stop();
-                    exit(0);
-                });
-                await cliServer.start(eventEmitter);
-                const url = `http://localhost:${env.PORT}/login`;
-                inprogress(`open to login ${greenBright(url)}`);
-                await open(url);
+        .action(() => {
+        return new Promise(async (resolve, reject) => {
+            inprogress('logging in...');
+            const cliServer = await init({
+                tokenSetPath: authConfigJson(),
+            });
+            if (!cliServer) {
+                failed('Issuer not found');
+                return;
+            }
+            const eventEmitter = new EventEmitter();
+            eventEmitter.on('cli-auth:login', () => {
+                done('login successful');
+                resolve();
+                process.exit(0);
+            });
+            eventEmitter.on('cli-auth:login-failed', () => {
+                failed('login failed');
+                reject();
+                process.exit(1);
+            });
+            process.on('SIGINT', () => {
+                failed('exiting unexpectedly');
+                void cliServer.stop();
+                exit(0);
+            });
+            process.on('SIGTERM', () => {
+                failed('exiting unexpectedly');
+                void cliServer.stop();
+                exit(0);
             });
+            await cliServer.start(eventEmitter);
+            const url = `http://localhost:${env.PORT}/login`;
+            inprogress(`open to login ${greenBright(url)}`);
+            await open(url);
         });
+    });
     authCommand
         .command('state')
         .description('get the current state of auth')
         .action(() => {
-            console.log('state');
-        });
-
+        console.log('state');
+    });
     program
         .command('publish')
         .argument('[packageName]', 'Component name')
-        .option(
-            '-t, --version-type <versionType>',
-            'Version type for verion up can be one of "patch", "minor", "major"',
-        )
-        .option('-d, --display-name <displayName>', 'Display Name for the package')
-        .option('-i, --icon <iconPath>', 'Icon path')
-        .option('-m, --images <imagePaths...>', 'Image paths')
-        .description('Bundle and publish the plugin')
-        .action(async (packageName, options) => {
-            if (
-                options.versionType &&
-                !['patch', 'minor', 'major'].includes((options.versionType || '').toLowerCase())
-            ) {
-                failed('Invalid version type should be one of "patch", "minor", "major"');
-                exit(0);
-            }
-            return await publish(packageName, cwd(), options);
-        });
-
-    program
-        .command('alpha:publish')
-        .argument('[packageName]', 'Component name')
-        .option(
-            '-t, --version-type <versionType>',
-            'Version type for version up can be one of "patch", "minor", "major"',
-        )
+        .addOption(new Option('-t, --version-type <versionType>', 'Version type for version up').choices([
+        'patch',
+        'minor',
+        'major',
+    ]))
         .option('-d, --display-name <displayName>', 'Display Name for the package')
         .option('-i, --icon <iconPath>', 'Icon path')
         .option('-m, --images <imagePaths...>', 'Image paths')
@@ -174,56 +151,65 @@ export const createProgram = () => {
         .option('--all', 'Select all the packages')
         .description('Bundle and publish the plugin')
         .action(async (packageName, options) => {
-            if (
-                options.versionType &&
-                !['patch', 'minor', 'major'].includes((options.versionType || '').toLowerCase())
-            ) {
-                failed('Invalid version type should be one of "patch", "minor", "major"');
-                exit(0);
-            }
-            return await alphaPublish(packageName, cwd(), options);
-        });
-
+        return await publish(packageName, cwd(), options);
+    });
     program
         .command('deprecate')
         .option('-y, --yes', 'Confirmation to deprecate a package')
         .option('--all', 'Select all the packages')
         .argument('[packageName]', 'Package name')
         .action(async (packageName, options) => {
-            return await deprecate(packageName, cwd(), options);
-        });
-
+        return await deprecate(packageName, cwd(), options);
+    });
     program
         .command('build')
-        .argument('<type>', 'Type of build: "plugins" or "docker"', (value, prevValue) => {
-            if (value !== 'plugins' && value !== 'docker') {
-                throw new InvalidArgumentError('"build" can be "plugins" or "docker"');
-            }
-            return value;
-        })
+        .addArgument(new Argument('<type>', 'Type of build').choices(['plugins', 'docker']))
         .argument('[pluginName]', 'Name of the plugin')
         .option('--module', 'Build the plugin as a module')
         .option('--all', 'Build all the plugin of the workspace')
         .description('Build the plugin')
         .action((type, pluginName, options) => {
-            build[type](cwd(), pluginName, options || {});
-        });
+        build[type](cwd(), pluginName ?? '', options ?? {});
+    });
     program
         .command('start')
         .option('-p, --port <port>', 'Port number for serving the plugin')
         .description('start the live server for the plugin')
         .action((options) => {
-            servePlugin(cwd(), options.port || 6969);
-        });
+        servePlugin(cwd(), Number(options.port) || 6969);
+    });
     program
         .command('serve')
+        .option('-p, --port <port>', 'Port number for serving the plugins', '3000')
         .description('Start the express server that serves the plugins')
+        .action((options) => {
+        startPluginsServer(cwd(), Number(options.port));
+    });
+    program
+        .command('completion')
+        .description('Output shell completion script')
+        .addArgument(new Argument('<shell>', 'Shell type').choices(['bash', 'zsh']))
+        .action((shell) => {
+        completion(program, shell);
+    });
+    program
+        .command('__list-packages', { hidden: true })
+        .description('List workspace package names (used by shell completion)')
         .action(() => {
-            startPluginsServer(cwd());
-        });
-    program.hook('preAction', async (thisCmd, actionCmd) => {
+        try {
+            const packages = getPackages(cwd());
+            for (const p of packages) {
+                const pkgJson = JSON.parse(readFileSync(join(p, 'package.json'), 'utf-8'));
+                process.stdout.write(pkgJson.name + '\n');
+            }
+        }
+        catch {
+            // Silently fail — completion should never error
+        }
+    });
+    program.hook('preAction', async (_thisCmd, actionCmd) => {
         const cmd = actionCmd.name();
-        if (cmd === 'new' || cmd === 'login') {
+        if (cmd === 'new' || cmd === 'login' || cmd === 'completion' || cmd === '__list-packages') {
             return;
         }
         if (!validateWorkspace(cwd())) {
@@ -231,9 +217,15 @@ export const createProgram = () => {
             exit(1);
         }
     });
-
     return program;
 };
-
-const program = createProgram();
-program.parse(process.argv);
+// Only parse when run directly (not when imported for testing/introspection)
+const self = realpathSync(fileURLToPath(import.meta.url));
+const entry = process.argv[1] ? realpathSync(resolve(process.argv[1])) : '';
+if (self === entry) {
+    const program = createProgram();
+    program.parseAsync(process.argv).catch((err) => {
+        failed(err.message || 'An unexpected error occurred');
+        exit(1);
+    });
+}

package/{cli-auth → dist/src/cli-auth}/auth.js

@@ -1,46 +1,25 @@
-import EventEmitter from 'node:events';
 import { existsSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { sep } from 'node:path';
 import { authUtils } from './services/auth-utils.js';
-
-/**
- * @param {import('openid-client').Client} client
- * @param {string} tokenSetPath
- */
 export const auth = (client, tokenSetPath) => {
     const authStateNonce = {
         state: '',
         nonce: '',
     };
-    /**
-     *
-     * @param {import('fastify').FastifyRequest} req
-     * @param {import('fastify').FastifyReply} reply
-     */
     return {
-        /**
-         * @param {import('fastify').FastifyInstance} server
-         * @param {EventEmitter} eventEmitter
-         */
         mount: (server, eventEmitter) => {
-            server.get('/login', async (request, reply) => {
+            server.get('/login', async (_request, reply) => {
                 const redirectUrl = await authUtils.login(client, authStateNonce);
                 reply.redirect(redirectUrl);
             });
             server.get('/login-callback', async (request, reply) => {
-                const { tokenSet } = await authUtils.loginCallback(
-                    client.callbackParams(request),
-                    client,
-                    authStateNonce,
-                );
+                const { tokenSet } = await authUtils.loginCallback(client.callbackParams(request.raw), client, authStateNonce);
                 const dirPath = tokenSetPath.substring(0, tokenSetPath.lastIndexOf(sep));
                 if (!existsSync(dirPath)) {
                     await mkdir(dirPath, { recursive: true });
                 }
-                await writeFile(tokenSetPath, JSON.stringify(tokenSet, null, 2), {
-                    encoding: 'utf-8',
-                });
+                await writeFile(tokenSetPath, JSON.stringify(tokenSet, null, 2), { encoding: 'utf-8' });
                 if (tokenSet) {
                     reply.send('Login successful');
                     eventEmitter.emit('cli-auth:login');