@eliware/vyops 2.0.0 → 2.1.0

package/README.md

@@ -28,7 +28,7 @@ npm install
 The package provides:
 
 ```text
-vyops   Deploy or dry-run a configuration.
+vyops   Preflight or release a configuration bundle.
 ```
 
 ## Configuration
@@ -41,22 +41,29 @@ vyops   Deploy or dry-run a configuration.
 | `SSH_HOST_CA` | No | unset | Trusted SSH host-CA public key for certificate verification. |
 | `LOG_LEVEL` | No | `info` | Winston log level (`error`, `warn`, `info`, `http`, `verbose`, `debug`, or `silly`). |
 
-The target must be supplied as `user@host`. The config must use native VyOS curly-brace syntax.
+The config must use native VyOS curly-brace syntax. The bundle's `system host-name`
+and single `system login user` entry provide the release target automatically.
 
 For a router that has not received its SSH key yet, provide the SSH password through stdin:
 
 ```sh
-printf '%s\n' "$VYOS_PASSWORD" | vyops --password-stdin vyos@new-router config.boot
+printf '%s\n' "$VYOS_PASSWORD" | vyops release --password-stdin /path/to/config.boot
 ```
 
 Password mode still requires the target host key to be present in `known_hosts`; it does not disable host verification. Passwords are not accepted as command-line arguments or written to logs.
 
 ## Usage
 
-Deploy:
+Preflight a bundle without connecting:
 
 ```sh
-vyops vyos@core1 /path/to/config.boot
+vyops preflight /path/to/config.boot
+```
+
+Release a bundle:
+
+```sh
+vyops release /path/to/config.boot
 ```
 
 Console switches:
@@ -64,16 +71,19 @@ Console switches:
 ```sh
 vyops --help
 vyops --version
-vyops --dry-run vyos@core1 /path/to/config.boot
-vyops --force --debug vyos@core1 /path/to/config.boot
-vyops --backup vyos@core1 /path/to/backup
+vyops --debug preflight /path/to/config.boot
+vyops release --force --debug /path/to/config.boot
+vyops backup vyos@core1 /path/to/backup
 ```
 
-`--backup` downloads the active `/config/config.boot` and the complete
+`backup` downloads the active `/config/config.boot` and the complete
 `/config/scripts` tree into the destination directory. It does not enter
 configuration mode or modify the router.
 
-`--dry-run` validates the config and skips SSH, commit, save, download, and Git pushback.
+`preflight` validates the config and recursively checks the `scripts/` tree before
+any SSH connection. Executable scripts must use LF line endings, a supported
+shell shebang, and valid executable intent. `release` runs the same checks before
+uploading or changing the router.
 
 The deployment workflow:
 

package/RELEASE_NOTES.md

@@ -1,5 +1,19 @@
 # Release Notes
 
+## 2.1.0
+
+- **Breaking:** Replace the legacy positional deployment and `--dry-run`
+  workflows with the first-class `preflight`, `release`, and `backup`
+  commands.
+- Add bundle preflight validation for recursively synchronized scripts,
+  including CRLF detection, shell shebang validation, and executable intent.
+- Derive the release SSH target from the configuration's `system host-name`
+  and single `system login user` entry.
+- Normalize executable script deployment permissions to `0755` and clean up
+  script staging after post-commit synchronization failures.
+- Allow command switches such as `--debug` and `--password-stdin` before or
+  after the command name.
+
 ## 2.0.0
 
 - **Breaking:** Replace the direct `ssh2` integration with the shared

package/package.json

@@ -1,12 +1,12 @@
 {
     "name": "@eliware/vyops",
-    "version": "2.0.0",
-    "description": "Deploy native VyOS configuration files over SSH.",
+    "version": "2.1.0",
+    "description": "Preflight, release, and back up native VyOS configuration bundles over SSH.",
     "main": "vyops.mjs",
     "scripts": {
         "lint": "eliware-test --lint",
         "test": "eliware-test",
-        "deploy": "./vyops.mjs",
+        "deploy": "node vyops.mjs",
         "pack": "npm pack --dry-run",
         "validate:package": "npm pack --dry-run --json | node scripts/validate-package.mjs",
         "audit": "node scripts/audit.mjs"

package/src/args.mjs

@@ -1,16 +1,18 @@
 export const usage = `Usage:
-  vyops [--dry-run] [--force] [--debug] [--password-stdin] <user@hostname-or-ip> <config.boot>
-  vyops --backup [--debug] [--password-stdin] <user@hostname-or-ip> <destination-directory>
+  vyops preflight <config.boot>
+  vyops release [--force] [--debug] [--password-stdin] <config.boot>
+  vyops backup [--debug] [--password-stdin] <user@hostname-or-ip> <destination-directory>
   vyops --help
   vyops --version`;
 
 export function parseArgs(argv) {
   if (argv.length === 1 && argv[0] === '--help') return { help: true };
   if (argv.length === 1 && argv[0] === '--version') return { version: true };
-
+  const command = argv.find(value => !value.startsWith('--'));
+  if (!['preflight', 'release', 'backup'].includes(command)) throw new Error(usage);
   const options = new Set(argv.filter(value => value.startsWith('--')));
-  if ([...options].some(option => !['--dry-run', '--force', '--debug', '--backup', '--password-stdin'].includes(option))) throw new Error(usage);
-  const values = argv.filter(value => !value.startsWith('--'));
-  if (values.length !== 2) throw new Error(usage);
-  return { target: values[0], config: values[1], ...(options.has('--backup') ? { backup: true } : {}), ...(options.has('--dry-run') ? { dryRun: true } : {}), ...(options.has('--force') ? { force: true } : {}), ...(options.has('--debug') ? { debug: true } : {}), ...(options.has('--password-stdin') ? { passwordStdin: true } : {}) };
+  const values = argv.filter(value => !value.startsWith('--')).slice(1);
+  const allowed = command === 'release' ? ['--force', '--debug', '--password-stdin'] : ['--debug', '--password-stdin'];
+  if ([...options].some(option => !allowed.includes(option)) || values.length !== (command === 'backup' ? 2 : 1)) throw new Error(usage);
+  return { command, ...(command === 'backup' ? { target: values[0], config: values[1] } : { config: values[0] }), ...(options.has('--force') ? { force: true } : {}), ...(options.has('--debug') ? { debug: true } : {}), ...(options.has('--password-stdin') ? { passwordStdin: true } : {}) };
 }

package/src/bundle.mjs

@@ -0,0 +1,43 @@
+import { promises as fs } from 'node:fs';
+import { join, relative } from 'node:path';
+
+async function filesIn(directory, root = directory) {
+  const result = [];
+  let entries;
+  try { entries = await fs.readdir(directory, { withFileTypes: true }); }
+  catch (error) { if (error.code === 'ENOENT') return result; throw error; }
+  for (const entry of entries) {
+    const file = join(directory, entry.name);
+    if (entry.isDirectory()) result.push(...await filesIn(file, root));
+    else if (entry.isFile()) result.push({ file, name: relative(root, file).replaceAll('\\', '/') });
+  }
+  return result;
+}
+
+export function targetFromConfig(text) {
+  const host = text.match(/(?:^|\n)\s*host-name\s+(?:"([^"]+)"|'([^']+)'|(\S+))/)?.slice(1).find(Boolean);
+  const users = [...text.matchAll(/(?:^|\n)\s*user\s+([A-Za-z0-9._-]+)\s*\{/g)].map(match => match[1]);
+  if (!host) throw new Error('preflight failed: config does not define system host-name');
+  if (users.length !== 1) throw new Error(`preflight failed: expected exactly one system login user; found ${users.length}`);
+  return `${users[0]}@${host}`;
+}
+
+function scriptError(name, message) { throw new Error(`preflight failed: scripts/${name} ${message}`); }
+
+export async function validateBundle(config, text, { extractTarget = true } = {}) {
+  const scripts = await filesIn(join(config, '..', 'scripts'));
+  for (const { file, name } of scripts) {
+    const data = await fs.readFile(file);
+    const firstLine = data.toString('utf8').split(/\n/, 1)[0].replace(/\r$/, '');
+    const executable = firstLine.startsWith('#!') || /(?:\.sh|\.script)$/.test(name)
+      || /^(?:commit\/post-hooks\.d\/|vyos-(?:pre|post)config-bootup\.script$)/.test(name);
+    if (!executable) continue;
+    if (data.includes(13)) scriptError(name, 'uses CRLF line endings; convert to LF');
+    if (!firstLine.startsWith('#!')) scriptError(name, 'is executable but has no shebang');
+    const interpreter = firstLine.slice(2).trim().split(/\s+/, 1)[0];
+    if (!['/bin/sh', '/bin/bash', '/bin/vbash', '/usr/bin/env'].includes(interpreter)) {
+      scriptError(name, `uses unsupported interpreter ${interpreter}`);
+    }
+  }
+  return { ...(extractTarget ? { target: targetFromConfig(text) } : {}), scripts };
+}

package/src/deploy.mjs

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
+import { readFile as readLocalFile } from 'node:fs/promises';
 import { fs, path as eliwarePath, log } from '@eliware/common';
 import { close, connect, download, exec, interactive, upload } from './ssh.mjs';
 
@@ -51,7 +52,14 @@ async function installScripts(client, config, log, runId) {
       const installed = `${installDir}/${name}`;
       const backup = `${backupDir}/${name}`;
       const parent = eliwarePath(name, '..').replaceAll(String.fromCharCode(92), '/');
-      const mode = /\.(?:sh|script)$/.test(name)
+      let content = Buffer.alloc(0);
+      try { content = await readLocalFile(local); }
+      /* istanbul ignore next -- missing files are only possible with a mocked directory listing. */
+      catch (error) {
+        /* istanbul ignore next -- missing files are only possible with a mocked directory listing. */
+        if (error.code !== 'ENOENT') throw error;
+      }
+      const mode = content.toString('utf8').startsWith('#!') || /\.(?:sh|script)$/.test(name)
         || /^(?:commit[/\\]post-hooks\.d[/\\])/.test(name)
         ? 0o755
         : (await fs.promises.stat(local)).mode & 0o777;
@@ -127,7 +135,10 @@ export async function deploy({ target, config, password }) {
     }
     return 0;
   } catch (error) {
-    if (finalizeHooks && !hooksFinalized && !deploymentCommitted) await finalizeHooks(false, client);
+    if (finalizeHooks && !hooksFinalized) {
+      await finalizeHooks(deploymentCommitted, client);
+      hooksFinalized = true;
+    }
     throw error;
   } finally {
     debugLog('cleaning up remote file');

package/src/main.mjs

@@ -3,6 +3,7 @@ import packageJson from '../package.json' with { type: 'json' };
 import { deploy } from './deploy.mjs';
 import { backup } from './backup.mjs';
 import { readAndValidateConfig } from './validate.mjs';
+import { validateBundle, targetFromConfig } from './bundle.mjs';
 import { pushBack, shouldSkip } from './git.mjs';
 import { closeAll } from './ssh.mjs';
 import { log, registerHandlers, registerSignals } from '@eliware/common';
@@ -31,18 +32,26 @@ try {
     args.password = await readPasswordStdin();
     if (!args.password) throw new Error('password-stdin received an empty password');
   }
-  if (args.backup) {
+  if (args.command === 'backup') {
     await backup(args);
     log.info(`Backup successful: ${args.config}`);
     process.exit(0);
   }
-  log.debug(`[vyops] validating config: ${args.config}`);
-  await readAndValidateConfig(args.config);
-  log.debug('[vyops] config validation complete');
-  if (args.dryRun) {
-    log.info(`Configuration valid; dry run for ${args.target}`);
+  if (args.command === 'preflight') {
+    const text = await readAndValidateConfig(args.config);
+    const { target, scripts } = await validateBundle(args.config, text);
+    log.info(`Preflight successful: ${target} (${scripts.length} script files)`);
     process.exit(0);
   }
+  if (args.command === 'release') {
+    const text = await readAndValidateConfig(args.config);
+    await validateBundle(args.config, text);
+    args.target = targetFromConfig(text);
+  }
+  log.debug(`[vyops] validating config: ${args.config}`);
+  const configText = await readAndValidateConfig(args.config);
+  if (args.command === 'release') await validateBundle(args.config, configText, { extractTarget: true });
+  log.debug('[vyops] config validation complete');
   if (!args.force && await shouldSkip(args.config)) {
     log.info('Latest commit is Pushback and config is unchanged; skipping deployment');
     process.exit(0);