spyne-cli 0.6.8 → 0.7.0

package/src/cli/render.js

@@ -0,0 +1,184 @@
+// Thin presentation layer. Everything here is terminal chrome — no generation
+// logic lives in this file, and nothing in src/core imports it.
+
+import c from 'ansi-colors';
+import ora from 'ora';
+import {generatePromptOutput} from '../templates/generate-prompt-output.js';
+import {commands} from '../registry.js';
+import {TEMPLATES} from '../core/create-app.js';
+
+/**
+ * Rebuild the legacy shapes generatePromptOutput expects, so module output is
+ * identical to 0.6.8 whether it came from the picker or from flags.
+ */
+export const renderModuleResult = (result) => {
+  const answers = {
+    fileType: result.fileType,
+    fileName: result.fileName,
+    className: result.className,
+    fileDirectory: result.fileDirectory,
+    channelName: result.channelName,
+  };
+  const savedProps = {
+    fileExists: result.error?.code === 'FILE_ALREADY_EXISTS',
+    fileHasSaved: result.ok === true,
+    fileDirPath: result.filePath,
+    errorType: result.errorType,
+  };
+  return generatePromptOutput(answers, savedProps, result.fileString,
+      result.channelRegistered);
+};
+
+export const renderAppResult = (result) => {
+  const lines = [
+    '',
+    c.greenBright('Success!'),
+    `Created ${c.bold(result.appName)} at ${result.path}`,
+    `Template: ${result.template}`,
+    '',
+    'Next steps:',
+    ...result.nextSteps.map((step) => `  ${c.cyan(step)}`),
+  ];
+  return lines.join('\n');
+};
+
+export const renderError = (error) => `${c.red('Error:')} ${error.message}`;
+
+/**
+ * Enquirer clamps a select's visible rows with Math.min(limit, height), where
+ * height comes from options.rows and falls back to process.stdout.rows. When
+ * that reports 0 — short panes, some CI and multiplexer setups — height wins at
+ * 0 and the list renders as "No matching choices". Passing rows explicitly is
+ * the only way to raise the floor; a real terminal taller than the list keeps
+ * its own value, so this only ever kicks in when the default would break.
+ */
+export const selectSizing = (choiceCount) => {
+  const needed = choiceCount + 2;
+  const limit = choiceCount;
+  return {limit, rows: Math.max(process.stdout.rows || 0, needed)};
+};
+
+/**
+ * Template choices for the enquirer select. `name` must be the template key,
+ * not the label — it is what reaches createApp.
+ */
+export const templateChoices = () => Object.values(TEMPLATES).map((t) => ({
+  name: t.value,
+  message: c.greenBright(t.label),
+  hint: c.dim(`— ${t.description}`),
+}));
+
+export const templatePrompt = () => {
+  const choices = templateChoices();
+  return {
+    type: 'select',
+    name: 'template',
+    message: c.blueBright('Choose a template'),
+    choices,
+    ...selectSizing(choices.length),
+  };
+};
+
+export const appNamePrompt = () => ({
+  type: 'input',
+  name: 'appName',
+  message: c.blueBright('Enter the application name'),
+  initial: 'my-spyne-app',
+  validate: (value) => String(value).trim().length > 0 ||
+      'An app name is required.',
+});
+
+export const createProgressReporter = () => {
+  let spinner;
+  return ({status, message}) => {
+    if (status === 'start') {
+      spinner = ora({text: message, spinner: 'dots'}).start();
+      return;
+    }
+    if (!spinner) return;
+    if (status === 'success') spinner.succeed(message);
+    else if (status === 'fail') spinner.fail(message);
+    else spinner.info(message);
+    spinner = undefined;
+  };
+};
+
+const isPositional = (def) => typeof def.positional === 'number';
+
+const describeArg = (def) => {
+  const parts = [def.description];
+  if (def.enum) parts.push(`Values: ${def.enum.join(' | ')}.`);
+  if (def.default !== undefined && def.type !== 'boolean') {
+    parts.push(`Default: ${def.default}.`);
+  }
+  return parts.filter(Boolean).join(' ');
+};
+
+const formatOption = ([name, def]) => {
+  // A boolean that defaults true is only actionable in its --no- form, so that
+  // is what help shows. `description` stays true to the positive form for
+  // programmatic consumers of the registry.
+  const showNegated = def.type === 'boolean' && def.default === true;
+  const flag = showNegated
+      ? `--no-${name}`
+      : (def.alias ? `-${def.alias}, --${name}` : `--${name}`);
+  const description = showNegated
+      ? (def.negatedDescription || `Skip: ${def.description}`)
+      : describeArg(def);
+  return `    ${flag.padEnd(20)} ${description}`;
+};
+
+const formatPositional = ([name, def]) =>
+    `    ${`<${name}>`.padEnd(20)} ${describeArg(def)}`;
+
+export const renderCommandHelp = (command) => {
+  const entries = Object.entries(command.args);
+  const positionals = entries.filter(([, def]) => isPositional(def));
+  const options = entries.filter(([, def]) => !isPositional(def));
+  const usage = [
+    'spyne-cli',
+    command.name,
+    ...positionals.map(([name, def]) => def.required ? `<${name}>` : `[${name}]`),
+    options.length ? '[options]' : '',
+  ].filter(Boolean).join(' ');
+
+  return [
+    '',
+    `  ${c.bold(command.name)} — ${command.summary}`,
+    '',
+    '  Usage:',
+    `    ${usage}`,
+    ...(positionals.length
+        ? ['', '  Arguments:', ...positionals.map(formatPositional)]
+        : []),
+    ...(options.length ? ['', '  Options:', ...options.map(formatOption)] : []),
+    '',
+  ].join('\n');
+};
+
+export const renderHelp = (version) => {
+  const templateList = Object.values(TEMPLATES).
+      map((t) => `    ${t.value.padEnd(12)} ${t.description}`).
+      join('\n');
+
+  return [
+    '',
+    `  spyne-cli ${version}`,
+    '',
+    '  Usage:',
+    '    spyne-cli                      interactive picker',
+    '    spyne-cli <command> [options]',
+    '',
+    '  Commands:',
+    ...commands.map((cmd) => `    ${cmd.name.padEnd(20)} ${cmd.summary}`),
+    '',
+    '  Templates (create-app):',
+    templateList,
+    '',
+    '  Global options:',
+    '    --json                 machine-readable output, human chrome suppressed',
+    '    -h, --help             show help; pass a command name for its options',
+    '    -v, --version          print version',
+    '',
+  ].join('\n');
+};

package/src/core/create-app.js

@@ -0,0 +1,232 @@
+// Core app scaffolding. No terminal output — callers pass an optional
+// onProgress callback and render however they like.
+
+import fs from 'fs';
+import path from 'path';
+import {spawn} from 'child_process';
+import simpleGit from 'simple-git';
+
+// Template keys mirror the distinguishing suffix of their repo names:
+// spynejs/application-starter and spynejs/application-shell.
+export const TEMPLATES = {
+  starter: {
+    value: 'starter',
+    label: 'Application Starter',
+    description: 'minimal: app.js + a hello-world view',
+    repo: 'https://github.com/spynejs/application-starter.git',
+  },
+  shell: {
+    value: 'shell',
+    label: 'Application Shell',
+    description: 'pages, navigation, and UI components built in',
+    repo: 'https://github.com/spynejs/application-shell.git',
+  },
+};
+
+// Accepted silently; only the canonical values are documented.
+const TEMPLATE_ALIASES = {
+  'app-shell': 'shell',
+  'application-shell': 'shell',
+  'application-starter': 'starter',
+};
+
+export const DEFAULT_TEMPLATE = 'starter';
+
+export const resolveTemplate = (name) => {
+  if (!name) return DEFAULT_TEMPLATE;
+  const key = String(name).toLowerCase();
+  return TEMPLATE_ALIASES[key] || key;
+};
+
+/**
+ * Clone URL for a template. An env override lets a fork — or this repo before
+ * the templates are published — scaffold from somewhere else. Read at call
+ * time so it is settable per invocation.
+ *
+ *   SPYNE_CLI_STARTER_REPO, SPYNE_CLI_SHELL_REPO
+ */
+export const repoFor = (templateKey) => {
+  const envKey = `SPYNE_CLI_${templateKey.toUpperCase().replace(/-/g, '_')}_REPO`;
+  return process.env[envKey] || TEMPLATES[templateKey].repo;
+};
+
+export const sanitizePackageName = (appName) => String(appName).
+    toLowerCase().
+    replace(/\s+/g, '-').
+    replace(/[^a-z0-9\-_.]/g, '') || 'my-spyne-app';
+
+const run = (command, args, cwd) => new Promise((resolve) => {
+  const child = spawn(command, args, {cwd, stdio: 'ignore', shell: false});
+  child.on('close', (code) => resolve(code));
+  child.on('error', () => resolve(-1));
+});
+
+const updateIndexTitle = (targetDir, appName) => {
+  const indexFilePath = path.join(targetDir, 'src', 'index.tmpl.html');
+  if (!fs.existsSync(indexFilePath)) return;
+  const content = fs.readFileSync(indexFilePath, 'utf-8');
+  fs.writeFileSync(indexFilePath,
+      content.replace(/<title>.*<\/title>/, `<title>${appName}</title>`),
+      'utf-8');
+};
+
+const updatePackageName = (targetDir, appName) => {
+  const pkgPath = path.join(targetDir, 'package.json');
+  if (!fs.existsSync(pkgPath)) return;
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  pkg.name = sanitizePackageName(appName);
+  pkg.version = '0.1.0';
+  delete pkg.repository;
+  delete pkg.homepage;
+  fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf-8');
+};
+
+/**
+ * Rebrand a freshly cloned template as the user's app. Exported so the
+ * post-clone pipeline is testable without reaching the network.
+ */
+export const applyProjectIdentity = (targetDir, appName) => {
+  updateIndexTitle(targetDir, appName);
+  updatePackageName(targetDir, appName);
+};
+
+/**
+ * Detect whether cwd (or an ancestor) looks like a SpyneJS project.
+ * Used to guard `create-app` inside a project and module generation outside one.
+ */
+export const detectSpyneProject = (startDir = process.cwd()) => {
+  let dir = path.resolve(startDir);
+  while (true) {
+    const pkgPath = path.join(dir, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        const deps = {...pkg.dependencies, ...pkg.devDependencies};
+        if (deps && deps.spyne) return {isSpyneProject: true, root: dir};
+      } catch {
+        // unreadable package.json — keep walking up
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return {isSpyneProject: false, root: null};
+    dir = parent;
+  }
+};
+
+/**
+ * Create a new SpyneJS application.
+ *
+ * @param {Object} args
+ * @param {string} args.appName
+ * @param {string} [args.template] 'starter' | 'shell'
+ * @param {boolean} [args.install] install dependencies (default true)
+ * @param {boolean} [args.git] initialise a fresh git repo (default true)
+ * @param {Function} [args.onProgress] ({step, status, message}) => void
+ * @returns {Promise<Object>} structured result
+ */
+export async function createApp(args = {}) {
+  const {appName, onProgress = () => {}} = args;
+  const install = args.install !== false;
+  const initGit = args.git !== false;
+
+  if (!appName) {
+    return {
+      ok: false,
+      error: {code: 'MISSING_APP_NAME', message: 'An app name is required.'},
+    };
+  }
+
+  const templateKey = resolveTemplate(args.template);
+  const template = TEMPLATES[templateKey];
+
+  if (!template) {
+    return {
+      ok: false,
+      error: {
+        code: 'UNKNOWN_TEMPLATE',
+        message: `Unknown template "${args.template}". Expected one of: ${Object.keys(
+            TEMPLATES).join(', ')}.`,
+      },
+    };
+  }
+
+  const targetDir = path.resolve(process.cwd(), appName);
+
+  if (fs.existsSync(targetDir)) {
+    return {
+      ok: false,
+      error: {
+        code: 'DIRECTORY_EXISTS',
+        message: `${targetDir} already exists.`,
+      },
+      path: targetDir,
+    };
+  }
+
+  const repo = repoFor(templateKey);
+
+  onProgress({step: 'clone', status: 'start', message: 'Cloning template...'});
+  try {
+    await simpleGit().clone(repo, targetDir,
+        ['--branch=main', '--single-branch', '--depth=1']);
+    onProgress({step: 'clone', status: 'success', message: 'Template cloned.'});
+  } catch (err) {
+    onProgress({step: 'clone', status: 'fail', message: 'Clone failed.'});
+    return {
+      ok: false,
+      error: {
+        code: 'CLONE_FAILED',
+        message: `Could not clone ${repo}: ${err.message}`,
+      },
+    };
+  }
+
+  // No .git leakage from the template repo.
+  fs.rmSync(path.join(targetDir, '.git'), {recursive: true, force: true});
+
+  applyProjectIdentity(targetDir, appName);
+
+  let gitInitialized = false;
+  if (initGit) {
+    onProgress({step: 'git', status: 'start', message: 'Initialising git...'});
+    gitInitialized = await run('git', ['init', '--quiet'], targetDir) === 0;
+    onProgress({
+      step: 'git',
+      status: gitInitialized ? 'success' : 'skip',
+      message: gitInitialized ? 'Git repository initialised.' : 'Skipped git init.',
+    });
+  }
+
+  let dependenciesInstalled = false;
+  if (install) {
+    onProgress({
+      step: 'install',
+      status: 'start',
+      message: 'Installing dependencies...',
+    });
+    dependenciesInstalled =
+        await run('npm', ['install', '--silent'], targetDir) === 0;
+    onProgress({
+      step: 'install',
+      status: dependenciesInstalled ? 'success' : 'fail',
+      message: dependenciesInstalled
+          ? 'Dependencies installed.'
+          : 'Dependency install failed — run npm install manually.',
+    });
+  }
+
+  return {
+    ok: true,
+    appName,
+    path: targetDir,
+    template: templateKey,
+    templateRepo: repo,
+    gitInitialized,
+    dependenciesInstalled,
+    nextSteps: [
+      `cd ${appName}`,
+      ...(dependenciesInstalled ? [] : ['npm install']),
+      'npm start',
+    ],
+  };
+}

package/src/core/generate-module.js

@@ -0,0 +1,146 @@
+// Core module generation. No terminal output — returns structured results.
+// The CLI layer is responsible for rendering these.
+
+import path from 'path';
+import GenerateFileString from '../templates/generate-file-string.js';
+import {detectSpyneProject} from './create-app.js';
+import {getLocalFileDirectory, onSaveSpyneFileToDir} from '../utils/file-utils.js';
+import {insertChannelStrings} from '../utils/insert-channel-strings-to-index-file.js';
+import {Data} from '../spyne-template-prompts.js';
+
+const {fileTypesArr} = Data;
+
+const toPascalCase = (str) => String(str).
+    replace(/\.js$/, '').
+    split(/[-_\s]+/).
+    filter(Boolean).
+    map((s) => s.charAt(0).toUpperCase() + s.slice(1)).
+    join('');
+
+const toConstantCase = (str) => {
+  const name = String(str).toLowerCase().startsWith('channel')
+      ? str
+      : `Channel${str}`;
+  return name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').
+      replace(/[-\s]+/g, '_').
+      toUpperCase();
+};
+
+const toMethodPrefix = (className) => {
+  const words = String(className).
+      replace(/([a-z0-9])([A-Z])/g, '$1 $2').
+      split(/[\s-_]+/).
+      filter(Boolean).
+      slice(0, 2);
+  const joined = words.map(
+      (w, i) => i === 0
+          ? w.toLowerCase()
+          : w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('');
+  return `${joined}$`;
+};
+
+const withTrailingSlash = (dir) => dir.endsWith('/') ? dir : `${dir}/`;
+
+/**
+ * Fill in the same defaults the interactive prompts would have offered, so a
+ * flags-only invocation produces identical output to the picker.
+ */
+export const resolveModuleArgs = (args = {}) => {
+  const {fileType} = args;
+  const fileName = String(args.fileName).endsWith('.js')
+      ? args.fileName
+      : `${args.fileName}.js`;
+  const className = args.className || toPascalCase(fileName);
+  const fileDirectory = withTrailingSlash(
+      args.fileDirectory || getLocalFileDirectory(fileType));
+
+  const resolved = {fileType, fileName, className, fileDirectory};
+
+  if (fileType === 'Channel') {
+    resolved.channelName = args.channelName || toConstantCase(className);
+    resolved.replayLastPayload = args.replayLastPayload === true ||
+        args.replayLastPayload === 'true';
+  }
+
+  if (fileType === 'SpyneTrait') {
+    resolved.methodPrefix = args.methodPrefix || toMethodPrefix(className);
+  }
+
+  return resolved;
+};
+
+/**
+ * Generate a single Spyne module file.
+ *
+ * @param {Object} args
+ * @returns {Promise<Object>} structured result — never throws for expected
+ *   failures (missing name, existing file); those surface on the result.
+ */
+export async function generateModule(args = {}) {
+  if (!fileTypesArr.includes(args.fileType)) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_FILE_TYPE',
+        message: `Unknown file type "${args.fileType}". Expected one of: ${fileTypesArr.join(
+            ', ')}.`,
+      },
+    };
+  }
+
+  if (!args.fileName) {
+    return {
+      ok: false,
+      error: {code: 'MISSING_FILE_NAME', message: 'A file name is required.'},
+    };
+  }
+
+  // Modules generate into an existing project; an app does not exist yet.
+  if (args.requireProject !== false && !detectSpyneProject().isSpyneProject) {
+    return {
+      ok: false,
+      error: {
+        code: 'NOT_IN_SPYNE_PROJECT',
+        message: 'Run this inside a SpyneJS project. To start a new one: spyne-cli create-app <app-name>',
+      },
+    };
+  }
+
+  const resolved = resolveModuleArgs(args);
+  const {fileType, fileName, className, fileDirectory} = resolved;
+  const {fileString} = new GenerateFileString(fileType, resolved);
+  const saved = onSaveSpyneFileToDir(fileString, fileName, fileDirectory);
+
+  // The CLI prints the generated source for copy-paste when a write fails, so
+  // failure results carry the same payload a success would.
+  if (!saved.fileHasSaved) {
+    return {
+      ok: false,
+      error: {
+        code: saved.fileExists ? 'FILE_ALREADY_EXISTS' : 'WRITE_FAILED',
+        message: saved.fileExists
+            ? `${saved.fileDirPath} already exists.`
+            : `Could not write ${saved.fileDirPath}.`,
+      },
+      ...resolved,
+      filePath: saved.fileDirPath,
+      errorType: saved.errorType,
+      channelRegistered: false,
+      fileString,
+    };
+  }
+
+  let channelRegistered = false;
+  if (fileType === 'Channel') {
+    channelRegistered = insertChannelStrings(className, fileName).fileHasSaved;
+  }
+
+  return {
+    ok: true,
+    ...resolved,
+    filePath: saved.fileDirPath,
+    relativePath: path.relative(process.cwd(), saved.fileDirPath),
+    channelRegistered,
+    fileString,
+  };
+}