@aifabrix/builder 2.20.0 → 2.21.1

package/README.md

@@ -76,8 +76,8 @@ flowchart TD
     Build --> Run[Run Locally]
     Run --> Deploy[Deploy to Azure]
     
-    style Install fill:#e1f5ff
-    style Deploy fill:#c8e6c9
+    style Install fill:#0062FF,color:#FFFFFF
+    style Deploy fill:#10B981,color:#FFFFFF
 ```
 
 ## Requirements

package/lib/api/auth.api.js

@@ -95,29 +95,28 @@ async function getAuthLogin(controllerUrl, redirect, state, authConfig) {
 async function initiateDeviceCodeFlow(controllerUrl, environment, scope) {
   const client = new ApiClient(controllerUrl);
   const body = {};
+  const params = {};
 
+  // Environment goes in query params (per OpenAPI spec)
   if (environment) {
-    body.environment = environment;
+    params.environment = environment;
   }
+
+  // Scope goes in request body
   if (scope) {
     body.scope = scope;
   }
 
-  // Use query params if environment provided (per OpenAPI spec)
-  if (environment) {
-    const params = { environment };
-    if (scope) {
-      params.scope = scope;
-    }
-    return await client.post('/api/v1/auth/login', {
-      params
-    });
+  // Build request options
+  const requestOptions = {};
+  if (Object.keys(params).length > 0) {
+    requestOptions.params = params;
+  }
+  if (Object.keys(body).length > 0) {
+    requestOptions.body = body;
   }
 
-  // Otherwise use body
-  return await client.post('/api/v1/auth/login', {
-    body: Object.keys(body).length > 0 ? body : undefined
-  });
+  return await client.post('/api/v1/auth/login', requestOptions);
 }
 
 /**

package/lib/api/index.js

@@ -110,12 +110,27 @@ class ApiClient {
    * @param {Object} [options] - Request options
    * @param {Object} [options.body] - Request body (will be JSON stringified)
    * @param {Object} [options.headers] - Additional headers
+   * @param {Object} [options.params] - Query parameters (will be converted to query string)
    * @returns {Promise<Object>} API response
    */
   async post(endpoint, options = {}) {
-    const url = this._buildUrl(endpoint);
+    let url = this._buildUrl(endpoint);
     const headers = this._buildHeaders(options.headers);
 
+    // Add query parameters if provided
+    if (options.params) {
+      const params = new URLSearchParams();
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          params.append(key, String(value));
+        }
+      });
+      const queryString = params.toString();
+      if (queryString) {
+        url += `?${queryString}`;
+      }
+    }
+
     const requestOptions = {
       method: 'POST',
       headers

package/lib/cli.js

@@ -366,6 +366,36 @@ function setupCommands(program) {
       }
     });
 
+  program.command('split-json <app>')
+    .description('Split deployment JSON into component files (env.template, variables.yaml, rbac.yml, README.md)')
+    .option('-o, --output <dir>', 'Output directory for component files (defaults to same directory as JSON)')
+    .action(async(appName, options) => {
+      try {
+        const fs = require('fs');
+        const { detectAppType, getDeployJsonPath } = require('./utils/paths');
+        const { appPath, appType } = await detectAppType(appName);
+        const deployJsonPath = getDeployJsonPath(appName, appType, true);
+
+        if (!fs.existsSync(deployJsonPath)) {
+          throw new Error(`Deployment JSON file not found: ${deployJsonPath}`);
+        }
+
+        const outputDir = options.output || appPath;
+        const result = await generator.splitDeployJson(deployJsonPath, outputDir);
+
+        logger.log(chalk.green('\n✓ Successfully split deployment JSON into component files:'));
+        logger.log(`  • env.template: ${result.envTemplate}`);
+        logger.log(`  • variables.yaml: ${result.variables}`);
+        if (result.rbac) {
+          logger.log(`  • rbac.yml: ${result.rbac}`);
+        }
+        logger.log(`  • README.md: ${result.readme}`);
+      } catch (error) {
+        handleCommandError(error, 'split-json');
+        process.exit(1);
+      }
+    });
+
   program.command('genkey <app>')
     .description('Generate deployment key')
     .action(async(appName) => {

package/lib/commands/login.js

@@ -342,7 +342,29 @@ async function handleDeviceCodeLogin(controllerUrl, environment, offline, scope)
     // Use centralized API client for device code flow initiation
     const deviceCodeApiResponse = await initiateDeviceCodeFlow(controllerUrl, envKey, requestScope);
 
+    // Validate response structure
+    if (!deviceCodeApiResponse) {
+      throw new Error('Device code flow initiation returned no response');
+    }
+
+    // Check if API call was successful
+    if (!deviceCodeApiResponse.success) {
+      const errorMessage = deviceCodeApiResponse.formattedError ||
+                          deviceCodeApiResponse.error ||
+                          'Device code flow initiation failed';
+      const error = new Error(errorMessage);
+      // Preserve formattedError for better error display
+      if (deviceCodeApiResponse.formattedError) {
+        error.formattedError = deviceCodeApiResponse.formattedError;
+      }
+      throw error;
+    }
+
     // Handle API response format: { success: boolean, data: DeviceCodeResponse }
+    if (!deviceCodeApiResponse.data) {
+      throw new Error('Device code flow initiation returned no data');
+    }
+
     const apiResponse = deviceCodeApiResponse.data;
     const deviceCodeData = apiResponse.data || apiResponse;
 

package/lib/generator-split.js

@@ -0,0 +1,342 @@
+/**
+ * AI Fabrix Builder Deployment JSON Split Functions
+ *
+ * Helper functions for splitting deployment JSON files into component files
+ *
+ * @fileoverview Split functions for deployment JSON reverse conversion
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Converts configuration array back to env.template format
+ * @function extractEnvTemplate
+ * @param {Array} configuration - Configuration array from deployment JSON
+ * @returns {string} env.template content
+ */
+function extractEnvTemplate(configuration) {
+  if (!Array.isArray(configuration) || configuration.length === 0) {
+    return '';
+  }
+
+  const lines = [];
+
+  // Generate env.template lines
+  for (const config of configuration) {
+    if (!config.name || !config.value) {
+      continue;
+    }
+
+    let value = config.value;
+    // Add kv:// prefix if location is keyvault
+    if (config.location === 'keyvault') {
+      value = `kv://${value}`;
+    }
+
+    lines.push(`${config.name}=${value}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Parses image reference string into components
+ * @function parseImageReference
+ * @param {string} imageString - Full image string (e.g., "registry/name:tag")
+ * @returns {Object} Object with registry, name, and tag
+ */
+function parseImageReference(imageString) {
+  if (!imageString || typeof imageString !== 'string') {
+    return { registry: null, name: null, tag: 'latest' };
+  }
+
+  // Handle format: registry/name:tag or name:tag or registry/name
+  const parts = imageString.split('/');
+  let registry = null;
+  let nameAndTag = imageString;
+
+  if (parts.length > 1) {
+    // Check if first part looks like a registry (contains .)
+    if (parts[0].includes('.')) {
+      registry = parts[0];
+      nameAndTag = parts.slice(1).join('/');
+    } else {
+      // No registry, just name:tag
+      nameAndTag = imageString;
+    }
+  }
+
+  // Split name and tag
+  const tagIndex = nameAndTag.lastIndexOf(':');
+  let name = nameAndTag;
+  let tag = 'latest';
+
+  if (tagIndex !== -1) {
+    name = nameAndTag.substring(0, tagIndex);
+    tag = nameAndTag.substring(tagIndex + 1);
+  }
+
+  return { registry, name, tag };
+}
+
+/**
+ * Extracts deployment JSON into variables.yaml structure
+ * @function extractVariablesYaml
+ * @param {Object} deployment - Deployment JSON object
+ * @returns {Object} Variables YAML structure
+ */
+function extractVariablesYaml(deployment) {
+  if (!deployment || typeof deployment !== 'object') {
+    throw new Error('Deployment object is required');
+  }
+
+  const variables = {};
+
+  // Extract app information
+  if (deployment.key || deployment.displayName || deployment.description || deployment.type) {
+    variables.app = {};
+    if (deployment.key) variables.app.key = deployment.key;
+    if (deployment.displayName) variables.app.displayName = deployment.displayName;
+    if (deployment.description) variables.app.description = deployment.description;
+    if (deployment.type) variables.app.type = deployment.type;
+  }
+
+  // Extract image information
+  if (deployment.image) {
+    const imageParts = parseImageReference(deployment.image);
+    variables.image = {};
+    if (imageParts.name) variables.image.name = imageParts.name;
+    if (imageParts.registry) variables.image.registry = imageParts.registry;
+    if (imageParts.tag) variables.image.tag = imageParts.tag;
+    if (deployment.registryMode) variables.image.registryMode = deployment.registryMode;
+  }
+
+  // Extract port
+  if (deployment.port !== undefined) {
+    variables.port = deployment.port;
+  }
+
+  // Extract requirements
+  if (deployment.requiresDatabase || deployment.requiresRedis || deployment.requiresStorage || deployment.databases) {
+    variables.requires = {};
+    if (deployment.requiresDatabase !== undefined) variables.requires.database = deployment.requiresDatabase;
+    if (deployment.requiresRedis !== undefined) variables.requires.redis = deployment.requiresRedis;
+    if (deployment.requiresStorage !== undefined) variables.requires.storage = deployment.requiresStorage;
+    if (deployment.databases) variables.requires.databases = deployment.databases;
+  }
+
+  // Extract healthCheck
+  if (deployment.healthCheck) {
+    variables.healthCheck = deployment.healthCheck;
+  }
+
+  // Extract authentication
+  if (deployment.authentication) {
+    variables.authentication = { ...deployment.authentication };
+  }
+
+  // Extract build
+  if (deployment.build) {
+    variables.build = deployment.build;
+  }
+
+  // Extract repository
+  if (deployment.repository) {
+    variables.repository = deployment.repository;
+  }
+
+  // Extract deployment config
+  if (deployment.deployment) {
+    variables.deployment = deployment.deployment;
+  }
+
+  // Extract other optional fields
+  if (deployment.startupCommand) {
+    variables.startupCommand = deployment.startupCommand;
+  }
+  if (deployment.runtimeVersion) {
+    variables.runtimeVersion = deployment.runtimeVersion;
+  }
+  if (deployment.scaling) {
+    variables.scaling = deployment.scaling;
+  }
+  if (deployment.frontDoorRouting) {
+    variables.frontDoorRouting = deployment.frontDoorRouting;
+  }
+
+  // Extract roles and permissions (if present)
+  if (deployment.roles) {
+    variables.roles = deployment.roles;
+  }
+  if (deployment.permissions) {
+    variables.permissions = deployment.permissions;
+  }
+
+  return variables;
+}
+
+/**
+ * Extracts roles and permissions from deployment JSON
+ * @function extractRbacYaml
+ * @param {Object} deployment - Deployment JSON object
+ * @returns {Object|null} RBAC YAML structure or null if no roles/permissions
+ */
+function extractRbacYaml(deployment) {
+  if (!deployment || typeof deployment !== 'object') {
+    return null;
+  }
+
+  const hasRoles = deployment.roles && Array.isArray(deployment.roles) && deployment.roles.length > 0;
+  const hasPermissions = deployment.permissions && Array.isArray(deployment.permissions) && deployment.permissions.length > 0;
+
+  if (!hasRoles && !hasPermissions) {
+    return null;
+  }
+
+  const rbac = {};
+  if (hasRoles) {
+    rbac.roles = deployment.roles;
+  }
+  if (hasPermissions) {
+    rbac.permissions = deployment.permissions;
+  }
+
+  return rbac;
+}
+
+/**
+ * Generates README.md content from deployment JSON
+ * @function generateReadmeFromDeployJson
+ * @param {Object} deployment - Deployment JSON object
+ * @returns {string} README.md content
+ */
+function generateReadmeFromDeployJson(deployment) {
+  if (!deployment || typeof deployment !== 'object') {
+    throw new Error('Deployment object is required');
+  }
+
+  const appName = deployment.key || 'application';
+  const displayName = deployment.displayName || appName;
+  const description = deployment.description || 'Application deployment configuration';
+  const port = deployment.port || 3000;
+  const image = deployment.image || 'unknown';
+
+  const lines = [
+    `# ${displayName}`,
+    '',
+    description,
+    '',
+    '## Quick Start',
+    '',
+    'This application is configured via deployment JSON and component files.',
+    '',
+    '## Configuration',
+    '',
+    `- **Application Key**: \`${appName}\``,
+    `- **Port**: \`${port}\``,
+    `- **Image**: \`${image}\``,
+    '',
+    '## Files',
+    '',
+    '- `variables.yaml` - Application configuration',
+    '- `env.template` - Environment variables template',
+    '- `rbac.yml` - Roles and permissions (if applicable)',
+    '- `README.md` - This file',
+    '',
+    '## Documentation',
+    '',
+    'For more information, see the [AI Fabrix Builder documentation](../../docs/README.md).'
+  ];
+
+  return lines.join('\n');
+}
+
+/**
+ * Splits a deployment JSON file into component files
+ * @async
+ * @function splitDeployJson
+ * @param {string} deployJsonPath - Path to deployment JSON file
+ * @param {string} [outputDir] - Directory to write component files (defaults to same directory as JSON)
+ * @returns {Promise<Object>} Object with paths to generated files
+ * @throws {Error} If JSON file not found or invalid
+ */
+async function splitDeployJson(deployJsonPath, outputDir = null) {
+  if (!deployJsonPath || typeof deployJsonPath !== 'string') {
+    throw new Error('Deployment JSON path is required and must be a string');
+  }
+
+  // Validate file exists
+  const fsSync = require('fs');
+  if (!fsSync.existsSync(deployJsonPath)) {
+    throw new Error(`Deployment JSON file not found: ${deployJsonPath}`);
+  }
+
+  // Determine output directory
+  const finalOutputDir = outputDir || path.dirname(deployJsonPath);
+
+  // Ensure output directory exists
+  if (!fsSync.existsSync(finalOutputDir)) {
+    await fs.mkdir(finalOutputDir, { recursive: true });
+  }
+
+  // Load and parse deployment JSON
+  let deployment;
+  try {
+    const jsonContent = await fs.readFile(deployJsonPath, 'utf8');
+    deployment = JSON.parse(jsonContent);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`Deployment JSON file not found: ${deployJsonPath}`);
+    }
+    throw new Error(`Invalid JSON syntax in deployment file: ${error.message}`);
+  }
+
+  // Extract components
+  const envTemplate = extractEnvTemplate(deployment.configuration || []);
+  const variables = extractVariablesYaml(deployment);
+  const rbac = extractRbacYaml(deployment);
+  const readme = generateReadmeFromDeployJson(deployment);
+
+  // Write component files
+  const results = {};
+
+  // Write env.template
+  const envTemplatePath = path.join(finalOutputDir, 'env.template');
+  await fs.writeFile(envTemplatePath, envTemplate, { mode: 0o644, encoding: 'utf8' });
+  results.envTemplate = envTemplatePath;
+
+  // Write variables.yaml
+  const variablesPath = path.join(finalOutputDir, 'variables.yaml');
+  const variablesYaml = yaml.dump(variables, { indent: 2, lineWidth: -1 });
+  await fs.writeFile(variablesPath, variablesYaml, { mode: 0o644, encoding: 'utf8' });
+  results.variables = variablesPath;
+
+  // Write rbac.yml (only if roles/permissions exist)
+  if (rbac) {
+    const rbacPath = path.join(finalOutputDir, 'rbac.yml');
+    const rbacYaml = yaml.dump(rbac, { indent: 2, lineWidth: -1 });
+    await fs.writeFile(rbacPath, rbacYaml, { mode: 0o644, encoding: 'utf8' });
+    results.rbac = rbacPath;
+  }
+
+  // Write README.md
+  const readmePath = path.join(finalOutputDir, 'README.md');
+  await fs.writeFile(readmePath, readme, { mode: 0o644, encoding: 'utf8' });
+  results.readme = readmePath;
+
+  return results;
+}
+
+module.exports = {
+  splitDeployJson,
+  extractEnvTemplate,
+  extractVariablesYaml,
+  extractRbacYaml,
+  parseImageReference,
+  generateReadmeFromDeployJson
+};
+

package/lib/generator.js

@@ -18,6 +18,7 @@ const _keyGenerator = require('./key-generator');
 const _validator = require('./validator');
 const builders = require('./generator-builders');
 const { detectAppType, getDeployJsonPath } = require('./utils/paths');
+const splitFunctions = require('./generator-split');
 
 /**
  * Loads variables.yaml file
@@ -161,8 +162,8 @@ async function generateDeployJson(appName) {
   const envTemplate = loadEnvTemplate(templatePath);
   const rbac = loadRbac(rbacPath);
 
-  // Parse environment variables from template
-  const configuration = parseEnvironmentVariables(envTemplate);
+  // Parse environment variables from template and merge portalInput from variables.yaml
+  const configuration = parseEnvironmentVariables(envTemplate, variables);
 
   // Build deployment manifest WITHOUT deploymentKey initially
   const deployment = builders.buildManifestStructure(appName, variables, null, configuration, rbac);
@@ -187,10 +188,85 @@ async function generateDeployJson(appName) {
   return jsonPath;
 }
 
-function parseEnvironmentVariables(envTemplate) {
+/**
+ * Validates portalInput structure against schema requirements
+ * @param {Object} portalInput - Portal input configuration to validate
+ * @param {string} variableName - Variable name for error messages
+ * @throws {Error} If portalInput structure is invalid
+ */
+function validatePortalInput(portalInput, variableName) {
+  if (!portalInput || typeof portalInput !== 'object') {
+    throw new Error(`Invalid portalInput for variable '${variableName}': must be an object`);
+  }
+
+  // Check required fields
+  if (!portalInput.field || typeof portalInput.field !== 'string') {
+    throw new Error(`Invalid portalInput for variable '${variableName}': field is required and must be a string`);
+  }
+
+  if (!portalInput.label || typeof portalInput.label !== 'string') {
+    throw new Error(`Invalid portalInput for variable '${variableName}': label is required and must be a string`);
+  }
+
+  // Validate field type
+  const validFieldTypes = ['password', 'text', 'textarea', 'select'];
+  if (!validFieldTypes.includes(portalInput.field)) {
+    throw new Error(`Invalid portalInput for variable '${variableName}': field must be one of: ${validFieldTypes.join(', ')}`);
+  }
+
+  // Validate select field requires options
+  if (portalInput.field === 'select') {
+    if (!portalInput.options || !Array.isArray(portalInput.options) || portalInput.options.length === 0) {
+      throw new Error(`Invalid portalInput for variable '${variableName}': select field requires a non-empty options array`);
+    }
+  }
+
+  // Validate optional fields
+  if (portalInput.placeholder !== undefined && typeof portalInput.placeholder !== 'string') {
+    throw new Error(`Invalid portalInput for variable '${variableName}': placeholder must be a string`);
+  }
+
+  if (portalInput.masked !== undefined && typeof portalInput.masked !== 'boolean') {
+    throw new Error(`Invalid portalInput for variable '${variableName}': masked must be a boolean`);
+  }
+
+  if (portalInput.validation !== undefined) {
+    if (typeof portalInput.validation !== 'object' || Array.isArray(portalInput.validation)) {
+      throw new Error(`Invalid portalInput for variable '${variableName}': validation must be an object`);
+    }
+  }
+
+  if (portalInput.options !== undefined && portalInput.field !== 'select') {
+    // Options should only be present for select fields
+    if (Array.isArray(portalInput.options) && portalInput.options.length > 0) {
+      throw new Error(`Invalid portalInput for variable '${variableName}': options can only be used with select field type`);
+    }
+  }
+}
+
+/**
+ * Parses environment variables from env.template and merges portalInput from variables.yaml
+ * @param {string} envTemplate - Content of env.template file
+ * @param {Object|null} [variablesConfig=null] - Optional configuration from variables.yaml
+ * @returns {Array<Object>} Configuration array with merged portalInput
+ * @throws {Error} If portalInput structure is invalid
+ */
+function parseEnvironmentVariables(envTemplate, variablesConfig = null) {
   const configuration = [];
   const lines = envTemplate.split('\n');
 
+  // Create a map of portalInput configurations by variable name
+  const portalInputMap = new Map();
+  if (variablesConfig && variablesConfig.configuration && Array.isArray(variablesConfig.configuration)) {
+    for (const configItem of variablesConfig.configuration) {
+      if (configItem.name && configItem.portalInput) {
+        // Validate portalInput before adding to map
+        validatePortalInput(configItem.portalInput, configItem.name);
+        portalInputMap.set(configItem.name, configItem.portalInput);
+      }
+    }
+  }
+
   for (const line of lines) {
     const trimmed = line.trim();
 
@@ -227,12 +303,19 @@ function parseEnvironmentVariables(envTemplate) {
       required = true;
     }
 
-    configuration.push({
+    const configItem = {
       name: key,
       value: value.replace('kv://', ''), // Remove kv:// prefix for KeyVault
       location,
       required
-    });
+    };
+
+    // Merge portalInput if it exists in variables.yaml
+    if (portalInputMap.has(key)) {
+      configItem.portalInput = portalInputMap.get(key);
+    }
+
+    configuration.push(configItem);
   }
 
   return configuration;
@@ -399,6 +482,12 @@ module.exports = {
   generateDeployJsonWithValidation,
   generateExternalSystemApplicationSchema,
   parseEnvironmentVariables,
+  splitDeployJson: splitFunctions.splitDeployJson,
+  extractEnvTemplate: splitFunctions.extractEnvTemplate,
+  extractVariablesYaml: splitFunctions.extractVariablesYaml,
+  extractRbacYaml: splitFunctions.extractRbacYaml,
+  parseImageReference: splitFunctions.parseImageReference,
+  generateReadmeFromDeployJson: splitFunctions.generateReadmeFromDeployJson,
   buildImageReference: builders.buildImageReference,
   buildHealthCheck: builders.buildHealthCheck,
   buildRequirements: builders.buildRequirements,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {

package/tatus

@@ -1,181 +0,0 @@
-
-                   SSUUMMMMAARRYY OOFF LLEESSSS CCOOMMMMAANNDDSS
-
-      Commands marked with * may be preceded by a number, _N.
-      Notes in parentheses indicate the behavior if _N is given.
-      A key preceded by a caret indicates the Ctrl key; thus ^K is ctrl-K.
-
-  h  H                 Display this help.
-  q  :q  Q  :Q  ZZ     Exit.
- ---------------------------------------------------------------------------
-
-                           MMOOVVIINNGG
-
-  e  ^E  j  ^N  CR  *  Forward  one line   (or _N lines).
-  y  ^Y  k  ^K  ^P  *  Backward one line   (or _N lines).
-  f  ^F  ^V  SPACE  *  Forward  one window (or _N lines).
-  b  ^B  ESC-v      *  Backward one window (or _N lines).
-  z                 *  Forward  one window (and set window to _N).
-  w                 *  Backward one window (and set window to _N).
-  ESC-SPACE         *  Forward  one window, but don't stop at end-of-file.
-  d  ^D             *  Forward  one half-window (and set half-window to _N).
-  u  ^U             *  Backward one half-window (and set half-window to _N).
-  ESC-)  RightArrow *  Right one half screen width (or _N positions).
-  ESC-(  LeftArrow  *  Left  one half screen width (or _N positions).
-  ESC-}  ^RightArrow   Right to last column displayed.
-  ESC-{  ^LeftArrow    Left  to first column.
-  F                    Forward forever; like "tail -f".
-  ESC-F                Like F but stop when search pattern is found.
-  r  ^R  ^L            Repaint screen.
-  R                    Repaint screen, discarding buffered input.
-        ---------------------------------------------------
-        Default "window" is the screen height.
-        Default "half-window" is half of the screen height.
- ---------------------------------------------------------------------------
-
-                          SSEEAARRCCHHIINNGG
-
-  /_p_a_t_t_e_r_n          *  Search forward for (_N-th) matching line.
-  ?_p_a_t_t_e_r_n          *  Search backward for (_N-th) matching line.
-  n                 *  Repeat previous search (for _N-th occurrence).
-  N                 *  Repeat previous search in reverse direction.
-  ESC-n             *  Repeat previous search, spanning files.
-  ESC-N             *  Repeat previous search, reverse dir. & spanning files.
-  ^O^N  ^On         *  Search forward for (_N-th) OSC8 hyperlink.
-  ^O^P  ^Op         *  Search backward for (_N-th) OSC8 hyperlink.
-  ^O^L  ^Ol            Jump to the currently selected OSC8 hyperlink.
-  ESC-u                Undo (toggle) search highlighting.
-  ESC-U                Clear search highlighting.
-  &_p_a_t_t_e_r_n          *  Display only matching lines.
-        ---------------------------------------------------
-        A search pattern may begin with one or more of:
-        ^N or !  Search for NON-matching lines.
-        ^E or *  Search multiple files (pass thru END OF FILE).
-        ^F or @  Start search at FIRST file (for /) or last file (for ?).
-        ^K       Highlight matches, but don't move (KEEP position).
-        ^R       Don't use REGULAR EXPRESSIONS.
-        ^S _n     Search for match in _n-th parenthesized subpattern.
-        ^W       WRAP search if no match found.
-        ^L       Enter next character literally into pattern.
- ---------------------------------------------------------------------------
-
-                           JJUUMMPPIINNGG
-
-  g  <  ESC-<       *  Go to first line in file (or line _N).
-  G  >  ESC->       *  Go to last line in file (or line _N).
-  p  %              *  Go to beginning of file (or _N percent into file).
-  t                 *  Go to the (_N-th) next tag.
-  T                 *  Go to the (_N-th) previous tag.
-  {  (  [           *  Find close bracket } ) ].
-  }  )  ]           *  Find open bracket { ( [.
-  ESC-^F _<_c_1_> _<_c_2_>  *  Find close bracket _<_c_2_>.
-  ESC-^B _<_c_1_> _<_c_2_>  *  Find open bracket _<_c_1_>.
-        ---------------------------------------------------
-        Each "find close bracket" command goes forward to the close bracket 
-          matching the (_N-th) open bracket in the top line.
-        Each "find open bracket" command goes backward to the open bracket 
-          matching the (_N-th) close bracket in the bottom line.
-
-  m_<_l_e_t_t_e_r_>            Mark the current top line with <letter>.
-  M_<_l_e_t_t_e_r_>            Mark the current bottom line with <letter>.
-  '_<_l_e_t_t_e_r_>            Go to a previously marked position.
-  ''                   Go to the previous position.
-  ^X^X                 Same as '.
-  ESC-m_<_l_e_t_t_e_r_>        Clear a mark.
-        ---------------------------------------------------
-        A mark is any upper-case or lower-case letter.
-        Certain marks are predefined:
-             ^  means  beginning of the file
-             $  means  end of the file
- ---------------------------------------------------------------------------
-
-                        CCHHAANNGGIINNGG FFIILLEESS
-
-  :e [_f_i_l_e]            Examine a new file.
-  ^X^V                 Same as :e.
-  :n                *  Examine the (_N-th) next file from the command line.
-  :p                *  Examine the (_N-th) previous file from the command line.
-  :x                *  Examine the first (or _N-th) file from the command line.
-  ^O^O                 Open the currently selected OSC8 hyperlink.
-  :d                   Delete the current file from the command line list.
-  =  ^G  :f            Print current file name.
- ---------------------------------------------------------------------------
-
-                    MMIISSCCEELLLLAANNEEOOUUSS CCOOMMMMAANNDDSS
-
-  -_<_f_l_a_g_>              Toggle a command line option [see OPTIONS below].
-  --_<_n_a_m_e_>             Toggle a command line option, by name.
-  __<_f_l_a_g_>              Display the setting of a command line option.
-  ___<_n_a_m_e_>             Display the setting of an option, by name.
-  +_c_m_d                 Execute the less cmd each time a new file is examined.
-
-  !_c_o_m_m_a_n_d             Execute the shell command with $SHELL.
-  #_c_o_m_m_a_n_d             Execute the shell command, expanded like a prompt.
-  |XX_c_o_m_m_a_n_d            Pipe file between current pos & mark XX to shell command.
-  s _f_i_l_e               Save input to a file.
-  v                    Edit the current file with $VISUAL or $EDITOR.
-  V                    Print version number of "less".
- ---------------------------------------------------------------------------
-
-                           OOPPTTIIOONNSS
-
-        Most options may be changed either on the command line,
-        or from within less by using the - or -- command.
-        Options may be given in one of two forms: either a single
-        character preceded by a -, or a name preceded by --.
-
-  -?  ........  --help
-                  Display help (from command line).
-  -a  ........  --search-skip-screen
-                  Search skips current screen.
-  -A  ........  --SEARCH-SKIP-SCREEN
-                  Search starts just after target line.
-  -b [_N]  ....  --buffers=[_N]
-                  Number of buffers.
-  -B  ........  --auto-buffers
-                  Don't automatically allocate buffers for pipes.
-  -c  ........  --clear-screen
-                  Repaint by clearing rather than scrolling.
-  -d  ........  --dumb
-                  Dumb terminal.
-  -D xx_c_o_l_o_r  .  --color=xx_c_o_l_o_r
-                  Set screen colors.
-  -e  -E  ....  --quit-at-eof  --QUIT-AT-EOF
-                  Quit at end of file.
-  -f  ........  --force
-                  Force open non-regular files.
-  -F  ........  --quit-if-one-screen
-                  Quit if entire file fits on first screen.
-  -g  ........  --hilite-search
-                  Highlight only last match for searches.
-  -G  ........  --HILITE-SEARCH
-                  Don't highlight any matches for searches.
-  -h [_N]  ....  --max-back-scroll=[_N]
-                  Backward scroll limit.
-  -i  ........  --ignore-case
-                  Ignore case in searches that do not contain uppercase.
-  -I  ........  --IGNORE-CASE
-                  Ignore case in all searches.
-  -j [_N]  ....  --jump-target=[_N]
-                  Screen position of target lines.
-  -J  ........  --status-column
-                  Display a status column at left edge of screen.
-  -k _f_i_l_e  ...  --lesskey-file=_f_i_l_e
-                  Use a compiled lesskey file.
-  -K  ........  --quit-on-intr
-                  Exit less in response to ctrl-C.
-  -L  ........  --no-lessopen
-                  Ignore the LESSOPEN environment variable.
-  -m  -M  ....  --long-prompt  --LONG-PROMPT
-                  Set prompt style.
-  -n .........  --line-numbers
-                  Suppress line numbers in prompts and messages.
-  -N .........  --LINE-NUMBERS
-                  Display line number at start of each line.
-  -o [_f_i_l_e] ..  --log-file=[_f_i_l_e]
-                  Copy to log file (standard input only).
-  -O [_f_i_l_e] ..  --LOG-FILE=[_f_i_l_e]
-                  Copy to log file (unconditionally overwrite).
-  -p _p_a_t_t_e_r_n .  --pattern=[_p_a_t_t_e_r_n]
-                  Start at pattern (from command line).
-  -P [_p_r_o_m_p_t]   --prompt=[_p_r_o_m_p_t]