@takodotid/circuit 0.27.0 → 0.28.0

package/dist/types/adapters/devices/fortios/index.d.ts

@@ -1,5 +1,6 @@
 import type { Client } from "ssh2";
 import type { Device, Family } from "../../../schema";
+import { type ConsoleDialect } from "../../../transport/console";
 import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions } from "../types";
 /** What a session reads and writes: an SSH shell, or anything else that streams the CLI. */
 export type Channel = {
@@ -26,10 +27,8 @@ export declare class Cli {
     private collect;
 }
 export declare function login(device: Device): Promise<Client>;
-/**
- * Log in on a serial console, whatever state the last session left it in: a pager is quit, a `config` level left, a session someone left open logged out, so every session starts from a fresh login. The CLI ends a line at a carriage return.
- */
-export declare function consoleLogin(channel: Channel, user: string, password: string): Promise<Cli>;
+/** How the FortiOS console asks for a login, and what moves it on from where the last session left it. */
+export declare const FORTIOS_CONSOLE: ConsoleDialect;
 /** Refuse a device on a release this adapter was not proved on, before anything is read or sent. */
 export declare function checkVersion(cli: Cli, device: Device): Promise<void>;
 /** Secrets the device prints: a password or an SNMPv3 key as a cipher, a certificate's key encrypted, and the SNMP community in clear. None leave the read. */

package/dist/types/adapters/devices/junos/index.d.ts

@@ -1,6 +1,7 @@
 import type { Client, ClientChannel } from "ssh2";
 import type { Device, Family } from "../../../schema";
-import type { ApplyOptions, DeviceAdapter, Plan } from "../types";
+import { type ConsoleDialect } from "../../../transport/console";
+import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions } from "../types";
 /** A statement's words; a quoted value is one word with its quotes. */
 export declare function wordsOf(statement: string): string[];
 /** The device prints a password as a hash, an SNMP key as a reversible cipher, and a community as itself. None leave the read. */
@@ -16,7 +17,9 @@ export declare function clean(output: string): string;
  */
 export declare function plan(desired: string, current: string, options: Pick<ApplyOptions, "secrets">): Plan;
 export declare function login(device: Device): Promise<Client>;
-export declare function read(device: Device): Promise<string>;
+export declare function read(device: Device, _network?: readonly Device[], options?: ReadOptions): Promise<string>;
+/** How the console asks for a login. Root lands in a shell, `%`, every other user in the CLI, `>`; a session left in configuration mode, `#`, leaves it first. Not yet proved on a device. */
+export declare const JUNOS_CONSOLE: ConsoleDialect;
 /** An interactive CLI with paging off. Root lands in a shell and starts the CLI from there. */
 export declare function openCli(channel: ClientChannel): Promise<void>;
 /** How a commit that could cut access is guarded: it rolls back after `minutes` unless `prove` shows access survived. */

package/dist/types/adapters/devices/raisecom-ros/index.d.ts

@@ -1,23 +1,28 @@
 import type { ClientChannel } from "ssh2";
 import type { Device } from "../../../schema";
+import { type ConsoleDialect } from "../../../transport/console";
 import { type Dialect } from "../lines";
-import type { DeviceAdapter, Plan } from "../types";
+import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions } from "../types";
 export declare const dialect: Dialect;
 /** The access-list that guards every management service. */
 export declare const MANAGEMENT_ACL = 1000;
 /** `99,200-201,999`, the platform's compression of a VLAN list. */
 export declare function vlanList(ids: number[]): string;
 export declare function render(device: Device): string;
+/** A session, and how to prove access in a fresh login: a new SSH session, or logging out and in again on the console. */
 export type Session = {
     channel: ClientChannel;
     close: () => void;
+    fresh: () => Promise<Session>;
 };
-/** An interactive shell, paging off. A session that does not answer as ROS is refused, so nothing meant for it can reach another shell. */
-export declare function open(device: Device): Promise<Session>;
+/** How the console asks for a login. Not yet proved on a device: the RAX721's console was never cabled to a jump host. */
+export declare const RAISECOM_CONSOLE: ConsoleDialect;
+/** An interactive shell, paging off, over SSH or on the console. A session that does not answer as ROS is refused, so nothing meant for it can reach another shell. */
+export declare function open(device: Device, options?: ReadOptions): Promise<Session>;
 /** What the device runs, credentials scrubbed. */
-export declare function read(device: Device): Promise<string>;
+export declare function read(device: Device, _network?: readonly Device[], options?: ReadOptions): Promise<string>;
 export declare function unsupported(device: Device): string[];
-export declare function apply(device: Device, _network: readonly Device[], plan: Plan): Promise<void>;
+export declare function apply(device: Device, _network: readonly Device[], plan: Plan, options: ApplyOptions): Promise<void>;
 /** The VLAN IDs of a `create vlan 10,20-30 active` line. */
 export declare function createdIds(line: string): number[];
 export declare const raisecom: DeviceAdapter;

package/dist/types/adapters/devices/routeros/index.d.ts

@@ -1,17 +1,30 @@
 import type { Client } from "ssh2";
 import type { Device, Family } from "../../../schema";
-import type { ApplyOptions, DeviceAdapter, Plan } from "../types";
+import { type ConsoleDialect } from "../../../transport/console";
+import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions } from "../types";
 /** The major version this adapter renders for. Version 6 has a different BGP and filter language altogether. */
 export declare const SUPPORTED_MAJOR = 7;
 export declare function login(device: Device): Promise<Client>;
+/** How the RouterOS console asks for a login. The flags after the user turn off colours and terminal detection, without which the console redraws every line. */
+export declare const ROUTEROS_CONSOLE: ConsoleDialect;
+/** Where commands run, one at a time, each returning what it printed: an SSH session, or the console. */
+type Session = {
+    run(command: string, timeout?: number): Promise<string>;
+    /** Write a file to the device. Only SSH can. */
+    upload?(path: string, content: string): Promise<void>;
+    /** A fresh login, which proves access survived: this session ends and a new SSH session opens, or the console logs out and in again. */
+    fresh(): Promise<Session>;
+    end(): void;
+};
 /** Refuse a device on a version this adapter does not render for, before anything is read or sent. */
-export declare function checkVersion(client: Client, device: Device): Promise<void>;
+export declare function checkVersion(session: Session, device: Device): Promise<void>;
 /**
  * What the device runs: its export, its users, and its certificates. Secrets are not part of an export.
  */
-export declare function read(device: Device): Promise<string>;
+export declare function read(device: Device, _network?: readonly Device[], options?: ReadOptions): Promise<string>;
 export declare function unsupported(device: Device): string[];
 export declare function apply(device: Device, _network: readonly Device[], changes: Plan, options: ApplyOptions): Promise<void>;
 /** Replace a list's entries in batches, so each command stays a sane length. */
 export declare function fill(device: Device, _network: readonly Device[], set: string, family: Family, prefixes: string[]): Promise<void>;
 export declare const routeros: DeviceAdapter;
+export {};

package/dist/types/adapters/devices/vrp/index.d.ts

@@ -1,7 +1,8 @@
 import type { Client, ClientChannel } from "ssh2";
 import type { Device } from "../../../schema";
+import { type ConsoleDialect } from "../../../transport/console";
 import { type Dialect } from "../lines";
-import type { DeviceAdapter, Plan } from "../types";
+import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions } from "../types";
 export declare const dialect: Dialect;
 /** The ACL that guards every management service. */
 export declare const MANAGEMENT_ACL = 2000;
@@ -17,8 +18,10 @@ export declare function login(device: Device): Promise<Client>;
  * Every login asks whether to change the password. Answering yes replaces it at once and every stored credential with it, so the answer is always no. Anything sent before the question is answered is taken as the answer.
  */
 export declare function openShell(client: Client): Promise<ClientChannel>;
+/** How the console asks for a login: the same question to change the password, always answered no, and a system view left with `return`. Not yet proved on a device. */
+export declare const VRP_CONSOLE: ConsoleDialect;
 /** What the device runs, credentials scrubbed. */
-export declare function read(device: Device): Promise<string>;
+export declare function read(device: Device, _network?: readonly Device[], options?: ReadOptions): Promise<string>;
 export declare function unsupported(device: Device): string[];
-export declare function apply(device: Device, _network: readonly Device[], plan: Plan): Promise<void>;
+export declare function apply(device: Device, _network: readonly Device[], plan: Plan, options: ApplyOptions): Promise<void>;
 export declare const vrp: DeviceAdapter;

package/dist/types/schema/device.d.ts

@@ -28,11 +28,11 @@ export type Jump = {
     /** The jump host is reached through a Cloudflare Tunnel, so Circuit connects with `cloudflared access ssh`, which must be installed. */
     cloudflared?: true;
 };
-/** A serial console, reached through a jump host. */
+/** A serial console, on a jump host or on the computer Circuit runs on. */
 export type Console = {
-    /** The jump host the console cable is plugged into. */
-    jump: Jump;
-    /** The serial port on the jump host. A path under `/dev/serial/by-path/` stays the same when two adapters swap names. */
+    /** The jump host the console cable is plugged into. When absent, the cable is plugged into the computer Circuit runs on. */
+    jump?: Jump;
+    /** The serial port: on Linux or macOS a path under `/dev`, where a path under `/dev/serial/by-path/` stays the same when two adapters swap names; on Windows a COM port, such as `COM3`. */
     port: string;
     /** Line speed in bits per second, such as 9600 or 115200. */
     baud: number;

package/dist/types/transport/console.d.ts

@@ -1,9 +1,57 @@
 import { type ClientChannel } from "ssh2";
-import type { Console } from "../schema";
+import type { Console, Device } from "../schema";
 /** An open console: the stream to the device's CLI, and how to let it go. */
 export type ConsoleSession = {
     channel: ClientChannel;
     close: () => void;
 };
-/** Open a device's serial console through its jump host. Fails when another session holds the port. */
+/** Open a device's serial console, through its jump host or on this computer. Fails when another session holds the port. */
 export declare function openConsole(console: Console): Promise<ConsoleSession>;
+/** A device's console and its login, for `--console`. */
+export declare function consoleOf(device: Device): {
+    console: Console;
+    user: string;
+    password: string;
+};
+/** How a platform's console asks for a login and shows its prompt, and what moves it on from anywhere else. */
+export type ConsoleDialect = {
+    /** The login prompt. */
+    login: RegExp;
+    /** The password prompt. */
+    password: RegExp;
+    /** The CLI's prompt once logged in. */
+    prompt: RegExp;
+    /** What logs out from the prompt. */
+    logout: string;
+    /** Other places a console can be left, each with what moves it toward a login prompt: a pager, a config level, a question. Checked before the prompt. */
+    others?: readonly (readonly [RegExp, string])[];
+    /** The name typed at the login prompt, when the platform adds to it. */
+    user?: (user: string) => string;
+};
+/** The channel a console speaks on: an SSH stream from the relay, or anything shaped like one. */
+type Channel = Pick<ClientChannel, "write"> & {
+    on(event: "data", listener: (chunk: Buffer) => void): unknown;
+    removeListener(event: "data", listener: (chunk: Buffer) => void): unknown;
+};
+/** Write, then wait until what the console printed since ends with one of the patterns. Returns which, and what was printed. */
+export declare function expect(channel: Channel, write: string, patterns: readonly RegExp[], timeout?: number): Promise<{
+    index: number;
+    text: string;
+}>;
+/**
+ * Log in on a console, whatever state the last session left it in: what `others` names is moved on, a session left open is logged out, so every session starts from a fresh login. Returns once the CLI's prompt shows.
+ */
+export declare function consoleLogin(channel: Channel, dialect: ConsoleDialect, user: string, password: string): Promise<void>;
+/** The text after a command's echo. A terminal wraps a long echo where it likes, so the echo is matched character by character, line breaks it added skipped. */
+export declare function afterEcho(text: string, command: string): string;
+/** A CLI on a console that runs one command at a time and returns what it printed, as an SSH exec would: no echo, no prompt. */
+export declare class ConsoleShell {
+    private readonly channel;
+    private readonly dialect;
+    constructor(channel: Channel, dialect: ConsoleDialect);
+    /** Run a command and wait for the prompt. A pager in `others` is answered as it shows. */
+    run(command: string, timeout?: number): Promise<string>;
+    /** Log out, so no session is left open on the console. */
+    logout(): void;
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.27.0",
+    "version": "0.28.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",

package/src/adapters/devices/fortios/index.ts

@@ -6,7 +6,7 @@ import type { Client } from "ssh2";
 import { familyOf, host, split } from "../../../core/addr";
 import { MARKER, resolve, valueOfReference } from "../../../core/secrets";
 import type { AclRule, Device, Family, FilterRule } from "../../../schema";
-import { openConsole } from "../../../transport/console";
+import { type ConsoleDialect, consoleLogin, consoleOf, openConsole } from "../../../transport/console";
 import { connect, shell } from "../../../transport/ssh";
 import { portsOf, spell } from "../catalog";
 import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions } from "../types";
@@ -148,74 +148,18 @@ export async function login(device: Device): Promise<Client> {
     });
 }
 
-/** What a console shows when it waits for something, in the order they are checked. */
-const CONSOLE_STATES = [
-    ["login", /login: $/],
-    ["password", /Password: $/],
-    ["banner", BANNER],
-    ["pager", /--More-- $/],
-    ["context", /\([^)\n]*\) [#$] $/],
-    ["prompt", /[#$] $/],
-] as const;
-
-type ConsoleState = (typeof CONSOLE_STATES)[number][0];
-
-/** Write to a console, then wait until it shows one of its states. */
-function prompted(channel: Channel, write: string, timeout = 30_000): Promise<ConsoleState> {
-    return new Promise((done, fail) => {
-        let text = "";
-
-        const stop = () => {
-            clearTimeout(limit);
-            channel.removeListener("data", onData);
-        };
-
-        const onData = (chunk: Buffer) => {
-            text += chunk.toString("utf8").replace(/\r/g, "");
-
-            const state = CONSOLE_STATES.find(([, pattern]) => pattern.test(text));
-            if (!state) return;
-
-            stop();
-            done(state[0]);
-        };
-
-        const limit = setTimeout(() => {
-            stop();
-            fail(new Error(`the console did not answer: ${text.slice(-200)}`));
-        }, timeout);
-
-        channel.on("data", onData);
-        channel.write(write);
-    });
-}
-
-/**
- * Log in on a serial console, whatever state the last session left it in: a pager is quit, a `config` level left, a session someone left open logged out, so every session starts from a fresh login. The CLI ends a line at a carriage return.
- */
-export async function consoleLogin(channel: Channel, user: string, password: string): Promise<Cli> {
-    // What to send in each state to get closer to a login prompt.
-    const toward: Record<Exclude<ConsoleState, "login">, string> = {
-        password: "\r",
-        banner: "a",
-        pager: "q",
-        context: "end\r",
-        prompt: "exit\r",
-    };
-
-    let state = await prompted(channel, "\r");
-    for (let step = 0; state !== "login"; step++) {
-        if (step >= 10) throw new Error(`the console never reached a login prompt; it is at ${state}`);
-        state = await prompted(channel, toward[state]);
-    }
-
-    if ((await prompted(channel, `${user}\r`)) !== "password") throw new Error("the console did not ask for a password");
-
-    const answer = await prompted(channel, `${password}\r`, 60_000);
-    if (answer !== "prompt") throw new Error(`the console refused the login of ${user}`);
-
-    return new Cli(channel, "\r");
-}
+/** How the FortiOS console asks for a login, and what moves it on from where the last session left it. */
+export const FORTIOS_CONSOLE: ConsoleDialect = {
+    login: /login: $/,
+    password: /Password: $/,
+    prompt: /[#$] $/,
+    logout: "exit",
+    others: [
+        [BANNER, "a"],
+        [/--More-- $/, "q"],
+        [/\([^)\n]*\) [#$] $/, "end\n"],
+    ],
+};
 
 /** Log out of a console, so no session is left open on it. */
 async function consoleLogout(cli: Cli): Promise<void> {
@@ -223,27 +167,15 @@ async function consoleLogout(cli: Cli): Promise<void> {
     await cli.run("exit", 10_000).catch(() => undefined);
 }
 
-/** The device's console and its login. */
-function consoleOf(device: Device) {
-    const console = device.connection.console;
-    if (!console) throw new Error(`${device.name}: no connection.console`);
-
-    const user = device.users?.[device.connection.user];
-    if (!user) throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
-
-    return { console, user: device.connection.user as string, password: resolve(user.password) };
-}
-
 /** Log in on the console, open the CLI, and run `work` in it. `work` is also given a way to log in afresh on the same console. */
 async function consoleSession<T>(device: Device, work: (cli: Cli, relogin: () => Promise<void>) => Promise<T>): Promise<T> {
     const { console, user, password } = consoleOf(device);
     const opened = await openConsole(console);
 
     try {
-        const cli = await consoleLogin(opened.channel, user, password);
-        const relogin = async () => {
-            await consoleLogin(opened.channel, user, password);
-        };
+        await consoleLogin(opened.channel, FORTIOS_CONSOLE, user, password);
+        const cli = new Cli(opened.channel);
+        const relogin = () => consoleLogin(opened.channel, FORTIOS_CONSOLE, user, password);
 
         const result = await work(cli, relogin);
         await consoleLogout(cli);

package/src/adapters/devices/junos/index.ts

@@ -6,9 +6,10 @@ import type { Client, ClientChannel } from "ssh2";
 import { familyOf, host, isAddress, split } from "../../../core/addr";
 import { resolve, substitute } from "../../../core/secrets";
 import type { Device, Family } from "../../../schema";
+import { type ConsoleDialect, consoleLogin, consoleOf, openConsole } from "../../../transport/console";
 import { connect, exec, readUntil, shell } from "../../../transport/ssh";
 import { lagIds } from "../derive";
-import type { ApplyOptions, DeviceAdapter, Plan, Step } from "../types";
+import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions, Step } from "../types";
 import { GENERATED, settingsOf } from "./bgp";
 import { KEY_STATEMENT, Names, render, stormProfile, vrrpAddress } from "./render";
 
@@ -303,8 +304,8 @@ export async function login(device: Device): Promise<Client> {
 }
 
 /** Refuse a device on a release this adapter was not proved on, before anything is read or sent. */
-async function checkVersion(client: Client, device: Device): Promise<void> {
-    const version = await exec(client, "show version | match Junos:");
+async function checkVersion(ask: (command: string) => Promise<string>, device: Device): Promise<void> {
+    const version = await ask("show version | match Junos:");
     const release = /Junos: (\d+)\.(\S+)/.exec(version);
 
     if (!release) throw new Error(`${device.name} did not say which Junos it runs: ${version.slice(0, 200)}`);
@@ -313,11 +314,21 @@ async function checkVersion(client: Client, device: Device): Promise<void> {
     }
 }
 
-export async function read(device: Device): Promise<string> {
+export async function read(device: Device, _network: readonly Device[] = [], options: ReadOptions = {}): Promise<string> {
+    if (options.console) {
+        return onConsole(device, async (channel) => {
+            await checkVersion((command) => run(channel, command), device);
+            const output = await run(channel, "show configuration | display set | no-more", 180_000);
+            if (!/^set /m.test(output)) throw new Error(`${device.name} returned no configuration`);
+
+            return clean(output);
+        });
+    }
+
     const client = await login(device);
 
     try {
-        await checkVersion(client, device);
+        await checkVersion((command) => exec(client, command), device);
         const output = await exec(client, "show configuration | display set | no-more", 180_000);
         if (!/^set /m.test(output)) throw new Error(`${device.name} returned no configuration`);
 
@@ -347,6 +358,38 @@ async function edit(channel: ClientChannel, line: string, timeout = 60_000): Pro
     return output.replace(/\r/g, "");
 }
 
+/** How the console asks for a login. Root lands in a shell, `%`, every other user in the CLI, `>`; a session left in configuration mode, `#`, leaves it first. Not yet proved on a device. */
+export const JUNOS_CONSOLE: ConsoleDialect = {
+    login: /login: $/,
+    password: /Password:\s*$/,
+    prompt: /[>%] $/,
+    logout: "exit",
+    others: [[/# $/, "exit configuration-mode\n"]],
+};
+
+/** Log in on the console, open the CLI, and run `work` in it with a way to log in afresh. Logs out after. */
+async function onConsole<T>(device: Device, work: (channel: ClientChannel, relogin: () => Promise<void>) => Promise<T>): Promise<T> {
+    const { console, user, password } = consoleOf(device);
+    const opened = await openConsole(console);
+
+    // The CLI is opened on a prompt asked for after the login, since the login's own prompt is already read.
+    const login = async () => {
+        await consoleLogin(opened.channel, JUNOS_CONSOLE, user, password);
+        const ready = openCli(opened.channel);
+        opened.channel.write("\n");
+        await ready;
+    };
+
+    try {
+        await login();
+        const result = await work(opened.channel, login);
+        opened.channel.write(`${JUNOS_CONSOLE.logout}\n`);
+        return result;
+    } finally {
+        opened.close();
+    }
+}
+
 /** An interactive CLI with paging off. Root lands in a shell and starts the CLI from there. */
 export async function openCli(channel: ClientChannel): Promise<void> {
     const banner = await readUntil(channel, (text) => PROMPT.test(text.replace(/\r/g, "")), 20_000, 500);
@@ -470,10 +513,27 @@ export async function configure(channel: ClientChannel, plan: Plan, guard?: Guar
 }
 
 export async function apply(device: Device, _network: readonly Device[], plan: Plan, options: ApplyOptions): Promise<void> {
+    if (options.console) {
+        await onConsole(device, async (channel, relogin) => {
+            await checkVersion((command) => run(channel, command), device);
+
+            // A fresh login on the console ends the session that holds the candidate, so the proof logs in again and takes the candidate back to confirm the commit.
+            await configure(channel, plan, {
+                minutes: options.rollback,
+                prove: async () => {
+                    await run(channel, "exit configuration-mode");
+                    await relogin();
+                    await run(channel, "configure exclusive");
+                },
+            });
+        });
+        return;
+    }
+
     const client = await login(device);
 
     try {
-        await checkVersion(client, device);
+        await checkVersion((command) => exec(client, command), device);
 
         const channel = await shell(client);
         await openCli(channel);
@@ -760,7 +820,7 @@ export async function fill(device: Device, _network: readonly Device[], set: str
     const client = await login(device);
 
     try {
-        await checkVersion(client, device);
+        await checkVersion((command) => exec(client, command), device);
 
         const channel = await shell(client);
         await openCli(channel);
@@ -775,6 +835,7 @@ export async function fill(device: Device, _network: readonly Device[], set: str
 
 export const junos: DeviceAdapter = {
     extension: ".conf",
+    console: true,
     unsupported,
     render,
     read,

package/src/adapters/devices/raisecom-ros/index.ts

@@ -7,11 +7,12 @@ import { familyOf, host, netmask, split, wildcard } from "../../../core/addr";
 import { marker, resolve, substitute } from "../../../core/secrets";
 import { offset } from "../../../core/time";
 import type { Device, Port, SnmpUser, Switched, Vrrp } from "../../../schema";
+import { type ConsoleDialect, consoleLogin, consoleOf, openConsole } from "../../../transport/console";
 import { connect, readUntil, send, shell } from "../../../transport/ssh";
 import { portsOf, spell } from "../catalog";
 import { ipv4Networks, lagIds, switchUnsupported } from "../derive";
 import { compare, type Dialect, entries, type Group, scrub, steps, vlanListChange } from "../lines";
-import type { DeviceAdapter, Plan, Step } from "../types";
+import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions, Step } from "../types";
 
 /** Lines the device prints whatever is configured, or that are part of moving around the CLI. */
 const DEVICE_FACTS = [
@@ -306,10 +307,33 @@ function physicalPort(settings: AnyPort | undefined, vlanId: (name: string) => n
 /** The firmware offers only an `ssh-rsa` host key, so that one is allowed for this platform alone. Key exchange, cipher and MAC still negotiate modern ones. */
 const HOST_KEYS = ["ssh-rsa"];
 
-export type Session = { channel: ClientChannel; close: () => void };
+/** A session, and how to prove access in a fresh login: a new SSH session, or logging out and in again on the console. */
+export type Session = { channel: ClientChannel; close: () => void; fresh: () => Promise<Session> };
 
-/** An interactive shell, paging off. A session that does not answer as ROS is refused, so nothing meant for it can reach another shell. */
-export async function open(device: Device): Promise<Session> {
+/** How the console asks for a login. Not yet proved on a device: the RAX721's console was never cabled to a jump host. */
+export const RAISECOM_CONSOLE: ConsoleDialect = {
+    login: /login:\s*$/i,
+    password: /password:\s*$/i,
+    prompt: /[#>]\s*$/,
+    logout: "exit",
+    others: [[/\(config[^)\n]*\)#\s*$/, "end\n"]],
+};
+
+/** An interactive shell, paging off, over SSH or on the console. A session that does not answer as ROS is refused, so nothing meant for it can reach another shell. */
+export async function open(device: Device, options: ReadOptions = {}): Promise<Session> {
+    const session = options.console ? await consoleShell(device) : await sshShell(device);
+
+    const version = await send(session.channel, "show version", 15_000, 1500);
+    if (!version.includes("ROS")) {
+        session.close();
+        throw new Error(`${device.name} did not answer as ROS`);
+    }
+
+    await send(session.channel, "terminal page-break disable", 15_000, 1000);
+    return session;
+}
+
+async function sshShell(device: Device): Promise<Session> {
     const user = device.users?.[device.connection.user];
     if (!user) throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
 
@@ -327,19 +351,51 @@ export async function open(device: Device): Promise<Session> {
     };
 
     const banner = await readUntil(channel, (text) => /[#>]\s*$/.test(text.trimEnd()), 30_000);
-    const version = await send(channel, "show version", 15_000, 1500);
-    if (!/[#>]\s*$/.test(banner.trimEnd()) || !version.includes("ROS")) {
+    if (!/[#>]\s*$/.test(banner.trimEnd())) {
         close();
         throw new Error(`${device.name} did not answer as ROS`);
     }
 
-    await send(channel, "terminal page-break disable", 15_000, 1000);
-    return { channel, close };
+    return {
+        channel,
+        close,
+        fresh: async () => {
+            close();
+            return open(device);
+        },
+    };
+}
+
+async function consoleShell(device: Device): Promise<Session> {
+    const { console, user, password } = consoleOf(device);
+    const opened = await openConsole(console);
+
+    try {
+        await consoleLogin(opened.channel, RAISECOM_CONSOLE, user, password);
+    } catch (error) {
+        opened.close();
+        throw error;
+    }
+
+    const session: Session = {
+        channel: opened.channel,
+        close: () => {
+            opened.channel.write(`${RAISECOM_CONSOLE.logout}\n`);
+            opened.close();
+        },
+        fresh: async () => {
+            await consoleLogin(opened.channel, RAISECOM_CONSOLE, user, password);
+            await send(opened.channel, "terminal page-break disable", 15_000, 1000);
+            return session;
+        },
+    };
+
+    return session;
 }
 
 /** What the device runs, credentials scrubbed. */
-export async function read(device: Device): Promise<string> {
-    const { channel, close } = await open(device);
+export async function read(device: Device, _network: readonly Device[] = [], options: ReadOptions = {}): Promise<string> {
+    const { channel, close } = await open(device, options);
 
     try {
         // Without paging off and a long wait for silence, the dump stops halfway with no error.
@@ -493,8 +549,9 @@ const CONFIRM = /^(portswitch|switchport trunk allowed vlan|switchport mode)/;
 /** A service letting go of an access-list, so the list can change. */
 const RELEASE = /^no (\S+ access-list \d+)$/;
 
-export async function apply(device: Device, _network: readonly Device[], plan: Plan): Promise<void> {
-    const { channel, close } = await open(device);
+export async function apply(device: Device, _network: readonly Device[], plan: Plan, options: ApplyOptions): Promise<void> {
+    const session = await open(device, options);
+    const { channel } = session;
     // Bindings released for an access-list edit. A failure binds them again before anything else, so the list keeps guarding management.
     const released: string[] = [];
 
@@ -521,12 +578,11 @@ export async function apply(device: Device, _network: readonly Device[], plan: P
         await send(channel, "config", 10_000).catch(() => undefined);
         for (const binding of released) await send(channel, binding, 10_000).catch(() => undefined);
         if (released.length) console.log(`  bound again: ${released.join(", ")}`);
+        session.close();
         throw error;
-    } finally {
-        close();
     }
 
-    const proof = await open(device).catch(() => undefined);
+    const proof = await session.fresh().catch(() => undefined);
     if (!proof)
         throw new Error(
             "applied, but a fresh login failed. Not written: a reboot restores the previous configuration. Recover from the console."
@@ -627,4 +683,4 @@ function plan(desired: string, current: string): ReturnType<DeviceAdapter["plan"
     return { steps: planned, problems: [] };
 }
 
-export const raisecom: DeviceAdapter = { extension: ".txt", unsupported, render, read, plan, apply };
+export const raisecom: DeviceAdapter = { extension: ".txt", console: true, unsupported, render, read, plan, apply };

package/src/adapters/devices/routeros/TRAPS.md

@@ -41,3 +41,4 @@ Behaviour that looks like something else. Each one has been hit on a real device
 - `bgp-path-len` counts every AS in the path, prepends included, and takes the same strict comparisons as `dst-len`.
 - `:parse` checks the command, not the text inside `rule=`. A routing filter rule is only checked when it is added.
 - `/routing/filter/filter-wizard` adds the rule it builds; it is not a dry run. `set blackhole yes` was proved this way on 7.23, in an unused chain removed right after.
+- On the serial console, the prompt can come twice after a login. The console echoes a long command wrapped at 80 columns, and a `print` that fills the screen stops at `-- [Q quit|D dump|down]`, where `D` prints the rest.