spyne-cli 0.6.8 → 0.7.0

package/README.md

@@ -5,10 +5,10 @@
 
 ## Features
 
-- Create a new SpyneJS application with a single command.
-- Generate `ViewStream`, `DomElement`, `Channel`, and `SpyneTrait` classes via interactive prompts.
-- Easily extend and customize applications.
-- Built-in support for channel-driven development.
+- Create a new SpyneJS application from either of two templates.
+- Generate `ViewStream`, `DomElement`, `Channel`, and `SpyneTrait` classes, interactively or from flags.
+- Register generated channels in your application's `src/index.js`.
+- Run every command non-interactively, with `--json` output for tooling.
 
 ## Installation
 
@@ -20,62 +20,112 @@ To install the `spyne-cli`, you need to have Node.js and npm installed on your s
    npm install -g spyne-cli
    ```
 
+## Requirements
+
+Node.js 18 or newer.
+
 ## Usage
 
-### Creating a New SpyneJS Application
+### Interactive
 
-To create a new SpyneJS application, run:
+Run with no arguments for the picker:
 
 ```bash
-npx spyne-cli new <app-name>
+npx spyne-cli
 ```
 
-This will generate a fully structured SpyneJS SPA in the specified `<app-name>` directory.
+```
+? What would you like to create?
+> App          - Create a new SpyneJS application
+  ViewStream
+  DomElement
+  Channel
+  SpyneTrait
+```
 
----
+Selecting **App** prompts for a template and an application name. Selecting any
+of the four module types prompts for a file name, class name, and output
+directory, then writes the file into your project.
 
-### Generating Components (Interactive CLI)
+### Creating an application
 
-To generate SpyneJS components, simply run:
+```bash
+npx spyne-cli create-app my-app
+```
+
+Prompts for a template when one is not supplied. To choose one directly:
 
 ```bash
-npx spyne-cli
+npx spyne-cli create-app my-app --template shell
 ```
 
-You’ll be presented with an interactive menu where you can select the file type:
+| Template | Contents |
+| --- | --- |
+| `starter` (default) | `app.js` and a hello-world view |
+| `shell` | pages, navigation, and UI components |
+
+Options: `-t, --template`, `--no-install` to skip dependency installation,
+`--no-git` to skip git initialisation.
+
+### Generating modules
 
-- `ViewStream`
-- `DomElement`
-- `Channel`
-- `SpyneTrait`
+Each module type is also a direct command, usable inside an existing project:
 
-Use the arrow keys to make a selection, and follow the prompts to name and configure your file.
+```bash
+npx spyne-cli create-viewstream my-widget-view
+npx spyne-cli create-domelement my-element
+npx spyne-cli create-channel channel-cart
+npx spyne-cli create-trait my-form-trait
+```
 
-This interface is ideal for developers who want fast, zero-config scaffolding during development.
+Options: `--className`, `-d, --fileDirectory`. `create-channel` also accepts
+`--channelName` and `--replayLastPayload`; `create-trait` accepts
+`--methodPrefix`. Anything not supplied is derived from the file name.
 
----
+`create-channel` also registers the channel in your `src/index.js`.
 
-### Example Workflow
+### Non-interactive use
 
-1. Create a new application:
+Every command runs from flags alone and never prompts when stdin is not a TTY,
+so invocations are safe in CI. Add `--json` for machine-readable output:
 
 ```bash
-npx spyne-cli new my-spyne-app
+npx spyne-cli create-app my-app -t starter --json
 ```
 
-2. Navigate to the project and start the application:
+Exit codes: `0` success, `1` the command ran and failed, `2` usage error.
 
-```bash
-cd my-spyne-app && npm start
+### Programmatic use
+
+The command registry is exported as data, so tooling can enumerate every
+generation target and its arguments:
+
+```javascript
+import { describeCommands } from 'spyne-cli/registry';
+
+describeCommands(); // [{ name, summary, kind, args }, ...]
 ```
 
-3. Run the interactive generator:
+### Scaffolding from a fork
+
+`create-app` clones from the published SpyneJS templates. To point it somewhere
+else — a fork, or a local mirror — set the matching environment variable:
 
 ```bash
-npx spyne-cli
+SPYNE_CLI_STARTER_REPO=https://github.com/you/your-starter.git \
+  npx spyne-cli create-app my-app
 ```
 
-4. Select the file type (e.g., `ViewStream`), and follow the prompts to generate a new component.
+`SPYNE_CLI_STARTER_REPO` overrides the `starter` template;
+`SPYNE_CLI_SHELL_REPO` overrides `shell`.
+
+### Deprecated and removed
+
+`spyne-cli new <app-name>` still works and now runs `create-app`. It prints a
+deprecation notice and will be removed in a future release.
+
+The `--spa` flag was removed in 0.7.0. Choose a template with
+`--template starter` or `--template shell` instead.
 
 ## Contributing
 
@@ -83,4 +133,4 @@ Contributions are welcome! Please feel free to submit a Pull Request or open an
 
 ## License
 
-This project is licensed under the MIT License.
+This project is licensed under the AGPL-3.0-or-later License.

package/index.js

@@ -1,33 +1,135 @@
 #!/usr/bin/env node
 
-import { SpyneCliUI } from './src/ui.js';
+import {readFileSync} from 'fs';
 import clear from 'clear';
-import { createNewApp } from './src/spyne-starter-app-create.js';
+import c from 'ansi-colors';
+import enquirer from 'enquirer';
+
+import {SpyneCliUI} from './src/ui.js';
 import SpyneFilePrompt from './src/spyne-file-prompt.js';
+import {parseArgs, validateArgs} from './src/cli/args.js';
+import {
+  appNamePrompt,
+  createProgressReporter,
+  renderAppResult,
+  renderCommandHelp,
+  renderError,
+  renderHelp,
+  renderModuleResult,
+  templatePrompt,
+} from './src/cli/render.js';
+
+const {prompt} = enquirer;
+const {version} = JSON.parse(
+    readFileSync(new URL('./package.json', import.meta.url), 'utf-8'));
+
+const EXIT = {ok: 0, usage: 2, failed: 1};
+
+const parsed = parseArgs(process.argv.slice(2));
+const {command, commandName, alias, args, provided, globals, errors} = parsed;
 
-const command = process.argv[2];
-const appName = process.argv[3];
+// --json implies machine consumption; a non-TTY stdin means nothing can answer
+// a prompt. Either way we must never block.
+const isInteractive = !globals.json && process.stdin.isTTY === true;
 
-// Simple check if user included "-spa" or "--spa" anywhere in the process.argv
-const isSPA = process.argv.includes('-spa') || process.argv.includes('--spa');
+const emitJson = (payload, exitCode) => {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  process.exit(exitCode);
+};
+
+const fail = (error, exitCode = EXIT.failed) => {
+  if (globals.json) emitJson({ok: false, error}, exitCode);
+  console.error(renderError(error));
+  process.exit(exitCode);
+};
 
-const startPromptFn = async () => {
+const succeed = (result, render) => {
+  if (globals.json) emitJson({ok: true, ...result}, EXIT.ok);
+  console.log(render(result));
+  process.exit(EXIT.ok);
+};
+
+if (globals.version) {
+  if (globals.json) emitJson({ok: true, version}, EXIT.ok);
+  console.log(version);
+  process.exit(EXIT.ok);
+}
+
+if (globals.help || (commandName && !command)) {
+  const unknown = commandName && !command;
+  if (unknown && globals.json) {
+    emitJson({
+      ok: false,
+      error: {code: 'UNKNOWN_COMMAND', message: `Unknown command "${commandName}".`},
+    }, EXIT.usage);
+  }
+  if (unknown) console.error(renderError({message: `Unknown command "${commandName}".`}));
+  console.log(command ? renderCommandHelp(command) : renderHelp(version));
+  process.exit(unknown ? EXIT.usage : EXIT.ok);
+}
+
+// Bare invocation keeps the 0.6.8 front door: banner, then the picker.
+if (!commandName) {
   clear();
   SpyneCliUI.title();
-  const spyneFilePrompt = new SpyneFilePrompt();
-  await spyneFilePrompt.startPrompt();
-};
+  new SpyneFilePrompt().startPrompt().catch((err) => {
+    console.error(renderError({message: err.message}));
+    process.exit(EXIT.failed);
+  });
+} else {
+  run().catch((err) => fail({code: 'UNEXPECTED', message: err.message}));
+}
+
+async function run() {
+  if (errors.length) fail(errors[0], EXIT.usage);
+
+  if (alias && alias.deprecated) {
+    console.error(c.yellow(
+        `"${commandName}" is deprecated and will be removed in a future release. Use "${alias.command}" instead.`));
+  }
+
+  // Fill required args interactively; in non-interactive mode a missing
+  // required arg is a usage error rather than a hang.
+  if (command.kind === 'app') await resolveAppArgs();
+
+  const missing = validateArgs(command, args);
+  if (missing.length) fail(missing[0], EXIT.usage);
+
+  const handlerArgs = command.kind === 'app'
+      ? {...args, onProgress: globals.json ? () => {} : createProgressReporter()}
+      : args;
+
+  const result = await command.handler(handlerArgs);
 
-if (command === 'new' && appName) {
-  (async () => {
-    try {
-      // Pass the isSPA boolean to createNewApp
-      await createNewApp(appName, isSPA);
-    } catch (err) {
-      console.error('Failed to create new application:', err.message);
-      process.exit(1);
+  if (!result.ok) {
+    // Module write failures still print the generated source for copy-paste.
+    if (command.kind === 'module' && result.fileString && !globals.json) {
+      console.log(renderModuleResult(result));
+      process.exit(EXIT.failed);
     }
-  })();
-} else {
-  startPromptFn();
+    fail(result.error);
+  }
+
+  succeed(result,
+      command.kind === 'app' ? renderAppResult : renderModuleResult);
+}
+
+async function resolveAppArgs() {
+  if (!isInteractive) {
+    // Never prompt in CI. Announce the default rather than failing, but only
+    // once the invocation is otherwise viable.
+    if (args.appName && !provided.has('template')) {
+      console.error(c.dim(`Using template: ${args.template}`));
+    }
+    return;
+  }
+
+  // Template first: the general choice before the specific one.
+  if (!provided.has('template')) {
+    ({template: args.template} = await prompt(templatePrompt()));
+  }
+
+  if (!args.appName) {
+    ({appName: args.appName} = await prompt(appNamePrompt()));
+  }
 }

package/package.json

@@ -4,9 +4,31 @@
     "spyne-cli": "index.js"
   },
   "type": "module",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "description": "Generates spyne objects and saves them to standard spyne.",
-  "main": "index.js",
+  "main": "src/registry.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "src/cli/",
+    "src/core/",
+    "src/templates/",
+    "src/utils/",
+    "src/registry.js",
+    "src/spyne-file-prompt.js",
+    "src/spyne-template-prompts.js",
+    "src/ui.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/registry.js",
+    "./registry": "./src/registry.js",
+    "./core/create-app": "./src/core/create-app.js",
+    "./core/generate-module": "./src/core/generate-module.js"
+  },
   "scripts": {
     "debug": "nodemon --no-stdin index.js",
     "start": "node index.js",
@@ -30,13 +52,9 @@
     "clear": "^0.1.0",
     "enquirer": "^2.4.1",
     "figlet": "^1.8.0",
-    "fs-extra": "^11.2.0",
     "json-stringify-safe": "^5.0.1",
     "ora": "^8.1.1",
-    "package-up": "^5.0.0",
-    "pkg-dir": "^8.0.0",
     "ramda": "^0.30.1",
-    "read-pkg": "^9.0.1",
     "recast": "^0.23.9",
     "simple-git": "^3.27.0"
   },

package/src/cli/args.js

@@ -0,0 +1,197 @@
+// Registry-driven argv parsing. The registry defines what a command accepts;
+// this file only knows how to read argv against a schema.
+
+import {getAlias, getCommand, removedFlags} from '../registry.js';
+
+const removedFlagError = (name) => {
+  const removed = removedFlags[name];
+  return removed
+      ? {code: 'REMOVED_FLAG', flag: name, message: removed.message}
+      : undefined;
+};
+
+const GLOBAL_FLAGS = ['json', 'help', 'version'];
+
+const findByAlias = (schema, alias) => Object.entries(schema).
+    find(([, def]) => def.alias === alias);
+
+const coerce = (def, raw) => {
+  if (def.type === 'boolean') {
+    if (raw === undefined) return true;
+    return raw !== 'false' && raw !== '0';
+  }
+  if (def.type === 'number') {
+    const n = Number(raw);
+    return Number.isNaN(n) ? raw : n;
+  }
+  return raw;
+};
+
+/**
+ * @param {string[]} argv typically process.argv.slice(2)
+ */
+export function parseArgs(argv = []) {
+  const tokens = [...argv];
+  const globals = {json: false, help: false, version: false};
+  const errors = [];
+
+  const commandName = tokens[0] && !tokens[0].startsWith('-')
+      ? tokens.shift()
+      : undefined;
+
+  const command = getCommand(commandName);
+  const alias = getAlias(commandName);
+  const schema = command ? command.args : {};
+  const args = {};
+  const positionals = [];
+
+  while (tokens.length) {
+    const token = tokens.shift();
+
+    if (token === '--') {
+      positionals.push(...tokens);
+      break;
+    }
+
+    if (token.startsWith('--')) {
+      let [flag, inlineValue] = token.slice(2).split(/=(.*)/s);
+
+      if (GLOBAL_FLAGS.includes(flag)) {
+        globals[flag] = true;
+        continue;
+      }
+
+      // --no-install style negation for negatable booleans
+      if (flag.startsWith('no-')) {
+        const positive = flag.slice(3);
+        if (schema[positive] && schema[positive].type === 'boolean') {
+          args[positive] = false;
+          continue;
+        }
+      }
+
+      const def = schema[flag];
+      if (!def) {
+        errors.push(removedFlagError(flag) || {
+          code: 'UNKNOWN_FLAG',
+          message: `Unknown option "--${flag}".`,
+        });
+        continue;
+      }
+
+      if (def.type === 'boolean' && inlineValue === undefined) {
+        args[flag] = true;
+        continue;
+      }
+
+      const value = inlineValue !== undefined
+          ? inlineValue
+          : (tokens[0] && !tokens[0].startsWith('-') ? tokens.shift() : undefined);
+
+      if (value === undefined && def.type !== 'boolean') {
+        errors.push({
+          code: 'MISSING_VALUE',
+          message: `Option "--${flag}" expects a value.`,
+        });
+        continue;
+      }
+
+      args[flag] = coerce(def, value);
+      continue;
+    }
+
+    if (token.startsWith('-') && token.length > 1) {
+      const short = token.slice(1);
+
+      if (short === 'h') { globals.help = true; continue; }
+      if (short === 'v') { globals.version = true; continue; }
+
+      const entry = findByAlias(schema, short);
+      if (!entry) {
+        // 0.6.x accepted both -spa and --spa, so catch the short form too.
+        errors.push(removedFlagError(short) ||
+            {code: 'UNKNOWN_FLAG', message: `Unknown option "-${short}".`});
+        continue;
+      }
+
+      const [flagName, def] = entry;
+      if (def.type === 'boolean') {
+        args[flagName] = true;
+        continue;
+      }
+
+      const value = tokens[0] && !tokens[0].startsWith('-')
+          ? tokens.shift()
+          : undefined;
+      if (value === undefined) {
+        errors.push({
+          code: 'MISSING_VALUE',
+          message: `Option "-${short}" expects a value.`,
+        });
+        continue;
+      }
+      args[flagName] = coerce(def, value);
+      continue;
+    }
+
+    positionals.push(token);
+  }
+
+  // Map remaining bare tokens onto positional slots.
+  Object.entries(schema).
+      filter(([, def]) => typeof def.positional === 'number').
+      sort((a, b) => a[1].positional - b[1].positional).
+      forEach(([name, def]) => {
+        if (args[name] === undefined && positionals.length) {
+          args[name] = coerce(def, positionals.shift());
+        }
+      });
+
+  // Everything set so far came from argv; record it before defaults land, so
+  // callers can tell "user chose starter" from "starter is the default".
+  const provided = new Set(Object.keys(args));
+
+  // Defaults last, so an explicit flag always wins.
+  Object.entries(schema).forEach(([name, def]) => {
+    if (args[name] === undefined && def.default !== undefined) {
+      args[name] = def.default;
+    }
+  });
+
+  return {
+    commandName,
+    command,
+    alias,
+    args,
+    provided,
+    globals,
+    errors,
+    extraPositionals: positionals,
+  };
+}
+
+/**
+ * Validate parsed args against the schema. Returns an array of errors so a
+ * non-interactive caller can fail deterministically instead of prompting.
+ */
+export function validateArgs(command, args) {
+  if (!command) return [];
+  return Object.entries(command.args).flatMap(([name, def]) => {
+    const value = args[name];
+    if (def.required && (value === undefined || value === '')) {
+      return [{
+        code: 'MISSING_REQUIRED_ARG',
+        arg: name,
+        message: `"${name}" is required.`,
+      }];
+    }
+    if (def.enum && value !== undefined && !def.enum.includes(value)) {
+      return [{
+        code: 'INVALID_ARG_VALUE',
+        arg: name,
+        message: `"${name}" must be one of: ${def.enum.join(', ')}.`,
+      }];
+    }
+    return [];
+  });
+}