@eliware/vyops 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eli Sterling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# VyOps
+
+> Deploy native VyOS configuration files over SSH and synchronize confirmed router state back to Git.
+
+## Features
+
+- SSH-key authentication via `ssh2`.
+- Native VyOS curly-brace configuration validation.
+- Candidate load, `compare`, `commit-confirm`, confirmation, and save.
+- Post-commit hook installation from `scripts/commit/post-hooks.d/`.
+- Pushback of confirmed `/config/config.boot` changes to the current Git repository.
+
+## Requirements
+
+- Node.js 26 or newer.
+- npm.
+- SSH access to the target VyOS router using an existing key.
+- A Git working tree when pushback behavior is enabled by the deployment workflow.
+
+## Installation
+
+```sh
+npm install
+```
+
+The package provides:
+
+```text
+vyops   Deploy or dry-run a configuration.
+```
+
+## Configuration
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `VYOPS_SSH_KEY` | No | `$HOME/.ssh/id_rsa` | Private SSH key path. |
+| `SSH_AUTH_SOCK` | No | unset | SSH agent socket passed to `ssh2`. |
+| `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.
+
+## Usage
+
+Deploy:
+
+```sh
+./vyops.mjs vyos@core1 /path/to/config.boot
+```
+
+Console switches:
+
+```sh
+./vyops.mjs --help
+./vyops.mjs --version
+./vyops.mjs --dry-run vyos@core1 /path/to/config.boot
+./vyops.mjs --force --debug vyos@core1 /path/to/config.boot
+```
+
+`--dry-run` validates the config and skips SSH, commit, save, download, and Git pushback.
+
+The deployment workflow:
+
+1. Connects using SSH keys.
+2. Uploads the config to `/home/vyos`.
+3. Loads it into the candidate configuration.
+4. Prints `compare` output.
+5. Runs `commit-confirm`.
+6. Confirms and saves only after confirmation.
+7. Installs local post-commit hooks, when present.
+8. Downloads `/config/config.boot` back to the supplied config path.
+9. Removes temporary remote files and closes SSH sessions.
+
+Exit code `0` means success. Non-zero means validation or deployment failure.
+
+## Git pushback behavior
+
+After a successful deployment, VyOps commits and pushes changes to the current Git repository with a `Pushback <timestamp>` commit. A later run skips deployment when the config is unchanged and the latest commit is a pushback commit.
+
+Review repository status and remotes before deployment. Do not run deployments concurrently against `core1` and `core2`.
+
+## Security
+
+- Config files may contain secrets; do not print, publish, or commit deployment logs containing config contents.
+- Use least-privilege SSH accounts and keys dedicated to the target routers.
+- Keep private keys outside the repository and restrict their filesystem permissions.
+- `compare` output is logged during deployment; review logs and diffs through the normal change-control process.
+- Use `LOG_LEVEL=debug` only when troubleshooting; debug output includes connection, path, and command progress.
+
+## Development and validation
+
+```sh
+npm install
+npm test
+npm run lint
+npm run audit
+npm run validate:package
+```
+
+Coverage is generated by the test command. Focused tests should be added with behavior changes. Never deploy to a router during tests unless explicitly requested.
+
+## Operational notes
+
+Deployments require existing SSH keys and a reachable VyOS target. The workflow uses confirmed commits and saves only after confirmation. Temporary remote files are cleaned up in the deployment cleanup path. SIGINT, SIGTERM, and SIGHUP trigger SSH cleanup through the shared signal handlers.
+
+## Support
+
+Repository: `git@github.com:eliware/vyops-js.git`
+
+Open an issue or provide a focused patch with tests and validation results.
+
+## License
+
+MIT License; see `LICENSE`.

package/RELEASE_NOTES.md

@@ -0,0 +1,29 @@
+# Release Notes
+
+## 1.0.2
+
+- Hardened SSH host verification with the user's `known_hosts` file.
+- Added validated targets, SSH/SFTP timeouts, randomized remote temporary paths, and awaited cleanup.
+- Added transactional post-commit hook backup and rollback.
+- Added Git pushback isolation, locking, stale-lock recovery, and `--force`.
+- Added `--debug` logging and improved interactive deployment validation.
+- Added npm packaging whitelist and package validation.
+- Added CI timeout, dependency audit, and package validation.
+
+Verification:
+
+- `npm test` (100% coverage)
+- `npm run lint`
+- `npm run audit`
+- `npm run validate:package`
+
+## 1.0.3 - 2026-08-10
+
+- Expanded README documentation for installation, configuration, usage, security, operations, development, and support.
+- Documented Git pushback behavior and dry-run validation.
+- Added `@eliware/common` logging, filesystem, path, error-handler, and signal-handler integration.
+
+Verification:
+
+- `npm test`
+- `npm run lint`

package/bin/vyops

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+await import('../vyops.mjs');

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "@eliware/vyops",
+    "version": "1.0.3",
+    "description": "Deploy native VyOS configuration files over SSH.",
+    "main": "vyops.mjs",
+    "scripts": {
+        "lint": "npx oxlint .",
+        "test": "npx --node-options=\"--experimental-vm-modules --no-warnings\" jest --detectOpenHandles --silent --coverage",
+        "deploy": "./vyops.mjs",
+        "test:gaps": "npm test 2>&1 | grep '|' | grep -vF '|     100 |      100 |     100 |     100 |'",
+        "pack": "npm pack --dry-run",
+        "validate:package": "npm pack --dry-run --json | node scripts/validate-package.mjs",
+        "audit": "npm audit --omit=dev --audit-level=moderate"
+    },
+    "keywords": [
+        "vyos",
+        "networking",
+        "gitops",
+        "ssh",
+        "cli"
+    ],
+    "type": "module",
+    "dependencies": {
+        "@eliware/common": "^1.1.7",
+        "ssh2": "^1.17.0"
+    },
+    "devDependencies": {
+        "jest": "^30.4.2",
+        "oxlint": "^1.77.0"
+    },
+    "bin": {
+        "vyops": "./bin/vyops"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/eliware/vyops.git"
+    },
+    "homepage": "https://github.com/eliware/vyops#readme",
+    "bugs": {
+        "url": "https://github.com/eliware/vyops/issues"
+    },
+    "files": [
+        "vyops.mjs",
+        "bin/",
+        "src/",
+        "README.md",
+        "LICENSE",
+        "RELEASE_NOTES.md"
+    ]
+}

package/src/args.mjs

@@ -0,0 +1,15 @@
+export const usage = `Usage:
+  vyops [--dry-run] [--force] [--debug] <user@hostname-or-ip> <config.boot>
+  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 options = new Set(argv.filter(value => value.startsWith('--')));
+  if ([...options].some(option => !['--dry-run', '--force', '--debug'].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('--dry-run') ? { dryRun: true } : {}), ...(options.has('--force') ? { force: true } : {}), ...(options.has('--debug') ? { debug: true } : {}) };
+}

package/src/deploy.mjs

@@ -0,0 +1,102 @@
+import { randomUUID } from 'node:crypto';
+import { fs, path as eliwarePath, log } from '@eliware/common';
+import { close, connect, download, exec, interactive, upload } from './ssh.mjs';
+
+export function extractCompare(output) {
+  const ansi = new RegExp(`${String.fromCharCode(27)}\\[[0-9;?]*[ -/]*[@-~]`, 'g');
+  const title = new RegExp(`${String.fromCharCode(27)}\\][^${String.fromCharCode(7)}]*(?:${String.fromCharCode(7)}|${String.fromCharCode(27)}\\\\)`, 'g');
+  const clean = output.replace(ansi, '').replace(title, '').replace(new RegExp(`${String.fromCharCode(27)}[=><]`, 'g'), '').replace(/\r/g, '');
+  const match = clean.match(/# compare\n([\s\S]*?)(?=\n[^\n]*# printf)/)
+    ?? clean.match(/(No changes between working and active configurations\.)[\s\S]*?(?=\n[^\n]*# printf)/);
+  return match?.[1].replace(/^\[edit\]\s*$/gm, '').trim() ?? '';
+}
+
+async function installPostCommitHooks(client, config, log, runId) {
+  const hooksDir = eliwarePath(config, '..', 'scripts', 'commit', 'post-hooks.d');
+  let names;
+  try {
+    names = (await fs.promises.readdir(hooksDir, { withFileTypes: true }))
+      .filter(entry => entry.isFile())
+      .map(entry => entry.name)
+      .sort();
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  if (!names.length) return null;
+  if (names.some(name => !name || name === '.' || name === '..' || /[\\/]/.test(name))) {
+    throw new Error('post-commit hook name is invalid');
+  }
+  const remoteDir = `/home/vyos/.post-hooks.${runId}`;
+  const backupDir = `/home/vyos/.post-hooks-backup.${runId}`;
+  const installDir = '/config/scripts/commit/post-hooks.d';
+  const made = await exec(client, `mkdir -p ${JSON.stringify(remoteDir)} && sudo mkdir -p ${JSON.stringify(installDir)} ${JSON.stringify(backupDir)}`);
+  if (made.code !== 0) throw new Error(`post-commit hook directory setup failed: ${made.stderr || made.stdout}`.trim());
+  try {
+    for (const name of names) {
+      const local = eliwarePath(hooksDir, name);
+      const remote = `${remoteDir}/${name}`;
+      const installed = `${installDir}/${name}`;
+      const backup = `${backupDir}/${name}`;
+      const backedUp = await exec(client, `if sudo test -e ${JSON.stringify(installed)}; then sudo cp -p -- ${JSON.stringify(installed)} ${JSON.stringify(backup)}; fi`);
+      if (backedUp.code !== 0) throw new Error(`post-commit hook backup failed (${name}): ${backedUp.stderr || backedUp.stdout}`.trim());
+      await upload(client, local, remote);
+      const installedResult = await exec(client, `sudo install -m 755 ${JSON.stringify(remote)} ${JSON.stringify(installed)}`);
+      if (installedResult.code !== 0) throw new Error(`post-commit hook install failed (${name}): ${installedResult.stderr || installedResult.stdout}`.trim());
+      log(`installed post-commit hook: ${name}`);
+    }
+  } catch (error) {
+    await exec(client, `sudo rm -f -- ${names.map(name => JSON.stringify(`${installDir}/${name}`)).join(' ')}; for f in ${JSON.stringify(backupDir)}/*; do [ -e "$f" ] && sudo mv -- "$f" ${JSON.stringify(installDir)}/; done; rm -rf -- ${JSON.stringify(remoteDir)} ${JSON.stringify(backupDir)}`).catch(cleanupError => log(`hook rollback failed: ${cleanupError.message}`));
+    throw error;
+  }
+  return async committed => {
+    if (committed) {
+      await exec(client, `sudo rm -rf -- ${JSON.stringify(backupDir)}; rm -rf -- ${JSON.stringify(remoteDir)}`).catch(error => log(`hook cleanup failed: ${error.message}`));
+      return;
+    }
+    await exec(client, `sudo rm -f -- ${names.map(name => JSON.stringify(`${installDir}/${name}`)).join(' ')}; for f in ${JSON.stringify(backupDir)}/*; do [ -e "$f" ] && sudo mv -- "$f" ${JSON.stringify(installDir)}/; done; rm -rf -- ${JSON.stringify(remoteDir)} ${JSON.stringify(backupDir)}`).catch(error => log(`hook rollback failed: ${error.message}`));
+  };
+}
+
+export async function deploy({ target, config }) {
+  const debugLog = message => log.debug(`[vyops] ${message}`);
+  debugLog(`connecting: ${target}`);
+  const client = await connect(target);
+  debugLog('SSH connected');
+  let finalizeHooks;
+  const runId = randomUUID();
+  const remote = `/home/vyos/.config.deploy.${runId}`;
+  try {
+    debugLog(`uploading config: ${config}`);
+    await upload(client, config, remote);
+    debugLog(`upload complete: ${remote}`);
+    finalizeHooks = await installPostCommitHooks(client, config, debugLog, runId);
+    debugLog('starting interactive deployment sequence');
+    const output = await interactive(client, [
+      'configure',
+      { command: `load ${remote}`, reject: /(?:load failed|error|invalid)/i },
+      "printf '%s\\n' '--- compare ---'",
+      'compare',
+      "printf '%s\\n' '--- end compare ---'",
+      { command: 'commit-confirm 5', reject: /(?:commit failed|error|invalid)/i },
+      { command: 'confirm', reject: /(?:confirm failed|error|invalid)/i },
+      { command: 'save', reject: /(?:save failed|error|invalid)/i },
+      'exit',
+      'exit',
+    ], debugLog);
+    debugLog(`interactive sequence returned (${output.length} bytes)`);
+    const compare = extractCompare(output);
+    if (compare) log.info(compare);
+    if (finalizeHooks) await finalizeHooks(true);
+    debugLog(`syncing live config: /config/config.boot -> ${config}`);
+    await download(client, '/config/config.boot', config);
+    return 0;
+  } catch (error) {
+    if (finalizeHooks) await finalizeHooks(false);
+    throw error;
+  } finally {
+    debugLog('cleaning up remote file');
+    await exec(client, `rm -f -- ${JSON.stringify(remote)}`).catch(error => debugLog(`cleanup failed: ${error.message}`));
+    await close(client);
+  }
+}

package/src/git.mjs

@@ -0,0 +1,86 @@
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import { promisify } from 'node:util';
+import { path } from '@eliware/common';
+
+const run = promisify(execFile);
+const LOCK_MAX_AGE = 60 * 60 * 1000;
+
+async function git(args, cwd) {
+  return run('git', args, { cwd, encoding: 'utf8' });
+}
+
+async function staleLock(lock) {
+  let owner;
+  let stats;
+  try {
+    [owner, stats] = await Promise.all([
+      fs.readFile(path(lock, 'owner'), 'utf8'),
+      fs.stat(lock),
+    ]);
+  } catch {
+    return false;
+  }
+  const pid = Number.parseInt(owner.trim(), 10);
+  if (Number.isInteger(pid) && pid > 0) {
+    try {
+      process.kill(pid, 0);
+      return false;
+    } catch (error) {
+      if (error.code === 'EPERM') return false;
+      if (error.code === 'ESRCH') return true;
+      return false;
+    }
+  }
+  return Date.now() - stats.mtimeMs > LOCK_MAX_AGE;
+}
+
+async function withRepositoryLock(repo, action, force) {
+  const lock = path(repo, '.git', 'vyops-pushback.lock');
+  try {
+    await fs.mkdir(lock);
+  } catch (error) {
+    if (error.code !== 'EEXIST' || (!force && !(await staleLock(lock)))) {
+      if (error.code === 'EEXIST') throw new Error('another pushback is already running');
+      throw error;
+    }
+    await fs.rm(lock, { recursive: true, force: true });
+    await fs.mkdir(lock);
+  }
+  try {
+    await fs.writeFile(path(lock, 'owner'), `${process.pid}\n`, 'utf8');
+    return await action();
+  } finally {
+    await fs.rm(lock, { recursive: true, force: true });
+  }
+}
+
+function configDirectory(config) {
+  return path(config, '..');
+}
+
+export async function shouldSkip(config) {
+  const cwd = configDirectory(config);
+  const { stdout: root } = await git(['rev-parse', '--show-toplevel'], cwd);
+  const repo = root.trim();
+  const relative = config.startsWith(`${repo}/`) ? config.slice(repo.length + 1) : config;
+  const { stdout: status } = await git(['status', '--porcelain', '--', relative], repo);
+  if (status.trim()) return false;
+  const { stdout: subject } = await git(['log', '-1', '--format=%s'], repo);
+  return subject.trim().startsWith('Pushback ');
+}
+
+export async function pushBack(config, { force = false } = {}) {
+  const { stdout: root } = await git(['rev-parse', '--show-toplevel'], configDirectory(config));
+  const repo = root.trim();
+  return withRepositoryLock(repo, async () => {
+    const relative = config.startsWith(`${repo}/`) ? config.slice(repo.length + 1) : config;
+    const { stdout: diff } = await git(['diff', '--', relative], repo);
+    if (!diff) return false;
+    await git(['add', '--', relative], repo);
+    const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    await git(['commit', '--only', '-m', `Pushback ${timestamp}`, '--', relative], repo);
+    await git(['push'], repo);
+    return true;
+  }, force);
+}

package/src/main.mjs

@@ -0,0 +1,45 @@
+import { parseArgs, usage } from './args.mjs';
+import packageJson from '../package.json' with { type: 'json' };
+import { deploy } from './deploy.mjs';
+import { readAndValidateConfig } from './validate.mjs';
+import { pushBack, shouldSkip } from './git.mjs';
+import { closeAll } from './ssh.mjs';
+import { log, registerHandlers, registerSignals } from '@eliware/common';
+
+const errors = registerHandlers({ log });
+const signals = registerSignals({ log, shutdownHook: async () => closeAll() });
+
+try {
+  const args = parseArgs(process.argv.slice(2));
+  log.debug(`[vyops] arguments parsed: target=${args.target || '-'} config=${args.config || '-'}`);
+  if (args.help) {
+    log.info(usage);
+    process.exit(0);
+  }
+  if (args.version) {
+    log.info(packageJson.version);
+    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}`);
+    process.exit(0);
+  }
+  if (!args.force && await shouldSkip(args.config)) {
+    log.info('Latest commit is Pushback and config is unchanged; skipping deployment');
+    process.exit(0);
+  }
+  log.debug('[vyops] deployment starting');
+  await deploy(args);
+  log.debug('[vyops] deployment complete; starting Git pushback');
+  if (await pushBack(args.config, { force: args.force })) log.info('Pushback committed and pushed');
+  log.info('Deployment successful');
+} catch (error) {
+  log.error(error.message);
+  process.exitCode = 1;
+} finally {
+  signals.removeHandlers();
+  errors.removeHandlers();
+}

package/src/ssh.mjs

@@ -0,0 +1,273 @@
+import { createHmac } from 'node:crypto';
+import { fs, log } from '@eliware/common';
+import ssh2 from 'ssh2';
+
+const { Client, utils } = ssh2;
+
+const CONNECT_TIMEOUT = 30000;
+const OPERATION_TIMEOUT = 60000;
+
+export function parseTarget(target) {
+  if (typeof target !== 'string' || !target || /\s/.test(target)) {
+    throw new Error('invalid target; expected user@host');
+  }
+  const at = target.indexOf('@');
+  if (at <= 0 || at !== target.lastIndexOf('@') || at === target.length - 1) {
+    throw new Error('invalid target; expected user@host');
+  }
+  const username = target.slice(0, at);
+  const host = target.slice(at + 1);
+  if (!/^[A-Za-z0-9._-]+$/.test(username) || !/^(?:\[[0-9A-Fa-f]*:[0-9A-Fa-f:]+\]|(?!\[)[A-Za-z0-9._:-]+)$/.test(host)) {
+    throw new Error('invalid target; expected user@host');
+  }
+  return { username, host };
+}
+
+function wildcardMatch(pattern, value) {
+  const expression = `^${pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`;
+  return new RegExp(expression).test(value);
+}
+
+function hostMatches(pattern, hosts) {
+  if (pattern.startsWith('|1|')) {
+    const [, , salt, digest] = pattern.split('|');
+    if (!salt || !digest) return false;
+    return hosts.some(host => createHmac('sha1', Buffer.from(salt, 'base64')).update(host).digest('base64') === digest);
+  }
+  return hosts.some(host => wildcardMatch(pattern, host));
+}
+
+function keyMatches(expected, actual) {
+  try {
+    const parsed = utils.parseKey(`${expected.type} ${expected.data}`);
+    return parsed.getPublicSSH().equals(actual);
+  } catch {
+    return false;
+  }
+}
+
+function verifyKnownHost(host, key, knownHosts) {
+  const hosts = [host, `[${host}]:22`];
+  let matched = false;
+  for (const line of knownHosts.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const fields = trimmed.split(/\s+/);
+    if (fields[0].startsWith('@')) {
+      if (fields[0] === '@revoked' && fields[1]?.split(',').some(pattern => hostMatches(pattern, hosts))) return false;
+      continue;
+    }
+    if (fields.length < 3) continue;
+    const [hostList, type, data] = fields;
+    const patterns = hostList.split(',');
+    if (patterns.some(pattern => pattern.startsWith('!') && hostMatches(pattern.slice(1), hosts))) return false;
+    if (patterns.some(pattern => !pattern.startsWith('!') && hostMatches(pattern, hosts))
+      && keyMatches({ type, data }, key)) matched = true;
+  }
+  return matched;
+}
+
+export async function connect(target) {
+  const { username, host } = parseTarget(target);
+  log.debug(`[vyops] SSH connecting: ${username}@${host}`);
+  const privateKey = await fs.promises.readFile(process.env.VYOPS_SSH_KEY || `${process.env.HOME}/.ssh/id_rsa`);
+  const knownHostsPath = `${process.env.HOME}/.ssh/known_hosts`;
+  const knownHosts = await fs.promises.readFile(knownHostsPath, 'utf8');
+  return new Promise((resolve, reject) => {
+    const client = new Client();
+    client.once('ready', () => { log.debug(`[vyops] SSH connected: ${username}@${host}`); resolve(client); });
+    client.once('error', reject);
+    client.once('close', () => activeClients.delete(client));
+    activeClients.add(client);
+    client.connect({
+      host,
+      username,
+      agent: process.env.SSH_AUTH_SOCK,
+      privateKey,
+      hostVerifier: (key, callback) => callback(verifyKnownHost(host, key, knownHosts)),
+      readyTimeout: CONNECT_TIMEOUT,
+      authTimeout: CONNECT_TIMEOUT,
+    });
+  });
+}
+
+export function exec(client, command) {
+  log.debug(`[vyops] SSH exec: ${command}`);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`SSH command timed out: ${command}`)), OPERATION_TIMEOUT);
+    client.exec(command, (error, stream) => {
+      if (error) { clearTimeout(timer); return reject(error); }
+      let stdout = '', stderr = '';
+      const finish = (callback, value) => {
+        clearTimeout(timer);
+        callback(value);
+      };
+      stream.on('data', data => { stdout += data; });
+      stream.stderr.on('data', data => { stderr += data; });
+      stream.on('error', error2 => finish(reject, error2));
+      stream.on('close', code => finish(resolve, { code: code ?? 1, stdout, stderr }));
+    });
+  });
+}
+
+export async function upload(client, local, remote, mode = 0o600) {
+  log.debug(`[vyops] SFTP upload: ${local} -> ${remote}`);
+  const data = await fs.promises.readFile(local);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`SFTP upload timed out: ${remote}`)), OPERATION_TIMEOUT);
+    client.sftp((error, sftp) => {
+      if (error) { clearTimeout(timer); return reject(error); }
+      sftp.writeFile(remote, data, { mode }, error2 => {
+        clearTimeout(timer);
+        return error2 ? reject(error2) : resolve();
+      });
+    });
+  });
+}
+
+export function download(client, remote, local) {
+  log.debug(`[vyops] SFTP download: ${remote} -> ${local}`);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`SFTP download timed out: ${remote}`)), OPERATION_TIMEOUT);
+    client.sftp((error, sftp) => {
+      if (error) { clearTimeout(timer); return reject(error); }
+      sftp.fastGet(remote, local, error2 => {
+        clearTimeout(timer);
+        return error2 ? reject(error2) : resolve();
+      });
+    });
+  });
+}
+
+export function interactive(client, commands, log = () => {}) {
+  return new Promise((resolve, reject) => {
+    client.shell({ term: 'xterm', cols: 160, rows: 48 }, (error, stream) => {
+      if (error) return reject(error);
+      log('VyOS interactive shell opened');
+      let output = '';
+      let response = '';
+      let index = 0;
+      let waiting = false;
+      let answering = false;
+      let settled = false;
+      let timedOut = false;
+      let currentItem;
+      log(`interactive sequence start (${commands.length} commands)`);
+      const timer = setTimeout(() => {
+        log(`timeout; next command: ${index + 1}/${commands.length}; waiting=${waiting}; answering=${answering}`);
+        log(`partial response:\n${response}`);
+        timedOut = true;
+        settled = true;
+        stream.close();
+        reject(new Error('interactive SSH timeout'));
+      }, 60000);
+      const ansi = new RegExp(`${String.fromCharCode(27)}\\[[0-9;?]*[ -/]*[@-~]`, 'g');
+      const title = new RegExp(`${String.fromCharCode(27)}\\][^${String.fromCharCode(7)}]*(?:${String.fromCharCode(7)}|${String.fromCharCode(27)}\\\\)`, 'g');
+      const clean = value => value.replace(ansi, '').replace(title, '').replace(/\r/g, '');
+      const prompt = value => /(?:^|\n)[A-Za-z0-9._-]+@[A-Za-z0-9._:-]+(?::~\$|#)\s*$/.test(value);
+      const sendNext = () => {
+        if (waiting || index >= commands.length) return;
+        currentItem = commands[index++];
+        const item = currentItem;
+        const command = typeof item === 'string' ? item : item.command;
+        response = '';
+        waiting = true;
+        log(`send [${index}/${commands.length}]: ${command}`);
+        log(`state before send: index=${index}, waiting=${waiting}, answering=${answering}`);
+        stream.write(`${command}\n`);
+        log(`write complete [${index}/${commands.length}]`);
+      };
+      stream.on('data', data => {
+        const text = data.toString();
+        output += text;
+        response += text;
+        log(`recv (${text.length} bytes): ${JSON.stringify(text)}`);
+        const cleaned = clean(response);
+        const pager = /(?:^|\n):\s*$/.test(cleaned) || /--More--\s*$/i.test(cleaned);
+        log(`state after data: index=${index}, waiting=${waiting}, answering=${answering}, prompt=${prompt(cleaned)}, pager=${pager}, bytes=${text.length}`);
+        if (pager) {
+          log('pager prompt detected; sending space');
+          stream.write(' ');
+          log('write complete: space');
+          return;
+        }
+        if (/Proceed\s*\?\s*\[Y\/n\]/i.test(cleaned) && !answering) {
+          answering = true;
+          log('commit-confirm prompt detected; sending: y');
+          response = '';
+          stream.write('y\n');
+          log('write complete: y');
+          return;
+        }
+        const commandComplete = waiting
+          && prompt(cleaned)
+          && !/Proceed\s*\?\s*\[Y\/n\]/i.test(cleaned);
+        log(`command completion check: complete=${commandComplete}`);
+        if (commandComplete) {
+          answering = false;
+          waiting = false;
+          log(`response [${index}]:\n${cleaned}`);
+          if (typeof currentItem !== 'string' && currentItem.reject?.test(cleaned)) {
+            settled = true;
+            clearTimeout(timer);
+            stream.close();
+            reject(new Error(`interactive command failed: ${currentItem.command}`));
+            return;
+          }
+          if (index >= commands.length) {
+            settled = true;
+            clearTimeout(timer);
+            stream.end();
+            resolve(output);
+          } else sendNext();
+        }
+      });
+      stream.on('error', error => {
+        log(`interactive stream error: ${error.message}`);
+        clearTimeout(timer);
+        reject(error);
+      });
+      stream.stderr.on('data', data => {
+        const text = data.toString();
+        output += text;
+        response += text;
+        log(`recv stderr (${text.length} bytes): ${JSON.stringify(text)}`);
+      });
+      stream.on('close', () => {
+        log(`VyOS interactive shell closed; settled=${settled}; index=${index}/${commands.length}`);
+        clearTimeout(timer);
+        if (!settled && !timedOut) {
+          const finalCommand = commands.at(-1);
+          const expectedClose = typeof finalCommand === 'string'
+            ? finalCommand === 'exit'
+            : finalCommand?.command === 'exit';
+          if (commands.length === 0 || (index >= commands.length && expectedClose)) resolve(output);
+          else reject(new Error('interactive SSH closed before command sequence completed'));
+        }
+      });
+      sendNext();
+    });
+  });
+}
+
+const activeClients = new Set();
+
+export function close(client) {
+  if (!client) return Promise.resolve();
+  return new Promise(resolve => {
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      activeClients.delete(client);
+      resolve();
+    };
+    client.once('close', done);
+    client.once('error', done);
+    client.end();
+  });
+}
+
+export async function closeAll() {
+  await Promise.all([...activeClients].map(client => close(client)));
+}

package/src/validate.mjs

@@ -0,0 +1,137 @@
+import { fs } from '@eliware/common';
+
+function naturalCompare(a, b) {
+  if (a.startsWith(b) && a !== b) return 1;
+  if (b.startsWith(a) && a !== b) return -1;
+  const aa = a.split(/(\d+)/), bb = b.split(/(\d+)/);
+  for (let i = 0; i < Math.min(aa.length, bb.length); i += 1) {
+    const an = /^\d+$/.test(aa[i]), bn = /^\d+$/.test(bb[i]);
+    if (an && bn && Number(aa[i]) !== Number(bb[i])) return Number(aa[i]) - Number(bb[i]);
+    if (aa[i] !== bb[i]) return aa[i] < bb[i] ? -1 : 1;
+  }
+  return aa.length - bb.length || 0;
+}
+
+function fail(line, message) {
+  throw new Error(`config validation failed at line ${line}: ${message}`);
+}
+
+export function validateConfig(text) {
+  if (!text.trim()) throw new Error('config validation failed: file is empty');
+
+  let depth = 0;
+  let hasStatement = false;
+  let line = 1;
+  let lineText = '';
+
+  const finishLine = () => {
+    let code = '';
+    let q = null;
+    let e = false;
+    for (const char of lineText) {
+      if (e) { code += char; e = false; continue; }
+      if (q && char === '\\') { code += char; e = true; continue; }
+      if (char === '"' || char === "'") {
+        q = q === char ? null : q || char;
+        code += char;
+        continue;
+      }
+      if (!q && char === '#') break;
+      code += char;
+    }
+    if (q) fail(line, 'unterminated quote');
+
+    const trimmed = code.trim();
+    if (!trimmed) return;
+    hasStatement = true;
+
+    const expectedDepth = trimmed === '}' ? depth - 1 : depth;
+    if (expectedDepth < 0) fail(line, 'unexpected closing brace');
+    const expectedIndent = '    '.repeat(expectedDepth);
+    if (!lineText.startsWith(expectedIndent) || lineText.slice(expectedIndent.length).startsWith(' ')) {
+      fail(line, `incorrect indentation; expected ${expectedDepth * 4} spaces`);
+    }
+
+    let open = -1;
+    let close = -1;
+    q = null; e = false;
+    for (let i = 0; i < code.length; i += 1) {
+      const char = code[i];
+      if (e) { e = false; continue; }
+      if (q && char === '\\') { e = true; continue; }
+      if (char === '"' || char === "'") { q = q === char ? null : q || char; continue; }
+      if (q) continue;
+      if (char === '{') { if (open >= 0) fail(line, 'multiple opening braces on one line'); open = i; }
+      if (char === '}') { if (close >= 0) fail(line, 'multiple closing braces on one line'); close = i; }
+    }
+
+    if (open >= 0 && close >= 0) fail(line, 'opening and closing brace must be on separate lines');
+    if (open >= 0) {
+      if (!code.slice(0, open).trim() || code.slice(open + 1).trim()) fail(line, 'opening brace must end the line');
+      depth += 1;
+      return;
+    }
+    if (close >= 0) {
+      if (code.slice(0, close).trim() || code.slice(close + 1).trim()) fail(line, 'closing brace must be alone');
+      depth -= 1;
+    }
+  };
+
+  for (const char of text) {
+    if (char === '\n') { finishLine(); lineText = ''; line += 1; }
+    else lineText += char;
+  }
+  finishLine();
+  if (depth !== 0) fail(line, 'unbalanced braces');
+  if (!hasStatement) throw new Error('config validation failed: no configuration statements');
+  return text;
+}
+
+export async function readAndValidateConfig(path) {
+  const text = await fs.promises.readFile(path, 'utf8');
+  return validateConfig(text);
+}
+
+
+export function fixConfig(text) {
+  const lines = text.replace(/\r\n?/g, '\n').split('\n').map(line => line.trim());
+  let index = 0;
+
+  const parseLevel = depth => {
+    const units = [];
+    while (index < lines.length) {
+      const trimmed = lines[index++];
+      if (!trimmed) { units.push({ key: '', lines: [''] }); continue; }
+      if (trimmed.startsWith('#')) units.push({ key: '', lines: [`${'    '.repeat(depth)}${trimmed}`] });
+      else if (trimmed === '}') {
+        if (depth === 0) throw new Error(`config validation failed: unexpected closing brace at line ${index}`);
+        return { units, closed: true };
+      } else if (trimmed.endsWith('{')) {
+        const header = trimmed;
+        const children = parseLevel(depth + 1);
+        if (!children.closed) throw new Error(`config validation failed: unbalanced braces at line ${index}`);
+        units.push({ key: header, lines: [`${'    '.repeat(depth)}${header}`, ...children.units.flatMap(unit => unit.lines), `${'    '.repeat(depth)}}`] });
+      } else units.push({ key: trimmed, lines: [`${'    '.repeat(depth)}${trimmed}`] });
+    }
+
+    for (let i = 0; i < units.length;) {
+      if (!units[i].key.endsWith('{')) { i += 1; continue; }
+      let end = i;
+      while (end < units.length && units[end].key.endsWith('{')) end += 1;
+      units.splice(i, end - i, ...units.slice(i, end).sort((a, b) => naturalCompare(
+        a.key.replace(/\s*\{$/, ''), b.key.replace(/\s*\{$/, ''),
+      )));
+      i = end;
+    }
+    return { units, closed: false };
+  };
+
+  const parsed = parseLevel(0);
+  let output = parsed.units.flatMap(unit => unit.lines);
+  const header = [];
+  while (output[0]?.startsWith('//')) header.push(output.shift());
+  while (output[0] === '') output.shift();
+  while (output.at(-1) === '') output.pop();
+  if (header.length) output.push('', '', ...header);
+  return `${output.join('\n')}\n`;
+}

package/vyops.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+if (process.argv.includes('--debug')) process.env.LOG_LEVEL = 'debug';
+await import('./src/main.mjs');